presentum library

A declarative cross-platform Flutter engine with focus on state to display presentations, such as campaigns, banners, notifications, etc., anywhere, anytime.

Classes

AllOfEligibility

ALL nested conditions must be satisfied (AND combinator).

AllOfExtractor<S extends HasMetadata>

Extracts AllOfEligibility from metadata (nested extractors).

AllOfRule

Evaluates AllOfEligibility conditions (AND combinator).

AnyOfEligibility

At least ONE nested condition must be satisfied (OR combinator).

AnyOfExtractor<S extends HasMetadata>

Extracts AnyOfEligibility from metadata (nested extractors).

AnyOfRule

Evaluates AnyOfEligibility conditions (OR combinator).

AnySegmentEligibility

A value from context must be a member of at least one segment in the required set.

AnySegmentExtractor<S extends HasMetadata>

Extracts AnySegmentEligibility from metadata.

AnySegmentRule

Evaluates AnySegmentEligibility conditions.

BatchingListUpdateCallback

A batching implementation of ListUpdateCallback that can batch consecutive operations of the same type.

BooleanFlagEligibility

A boolean flag in context must match the required value.

BooleanFlagExtractor<S extends HasMetadata>

Extracts BooleanFlagEligibility from metadata.

BooleanFlagRule

Evaluates BooleanFlagEligibility conditions.

ChangeOperation

Represents a change operation.

CollectingListUpdateCallback

A ListUpdateCallback that collects all operations into lists for later processing.

ConstantEligibility

A direct boolean value (useful for hard-coded eligibility).

ConstantExtractor<S extends HasMetadata>

Extracts ConstantEligibility from metadata.

ConstantRule

Evaluates ConstantEligibility conditions.

DefaultEligibilityResolver<S>

Default implementation of EligibilityResolver.

DiffCallback

Abstract callback class used by DiffUtil while calculating the diff between two lists.

DiffResult

This class holds the information about the result of a DiffUtil.calculateDiff call.

DiffUtil

Main DiffUtil class containing the core algorithm implementation.

DiffUtils

Utility class with convenience methods for common DiffUtil operations.

Eligibility

Base class for all eligibility conditions.

EligibilityExtractor<S>

Extracts structured Eligibility conditions from a subject.

EligibilityResolver<S>

Resolves whether a subject is eligible based on extracted conditions.

EligibilityRule<T extends Eligibility>

Evaluates a specific type of Eligibility against a runtime context.

HasMetadata

Interface for subjects that have metadata.

InheritedPresentum<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Inherited presentum widget.

InheritedPresentumItem<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Inherited widget that provides the PresentumItem instance to the widget tree.

InMemoryPresentumStorage<S extends PresentumSurface, V extends PresentumVisualVariant>

In-memory implementation of the presentum storage.

InsertOperation

Represents an insert operation.

IPresentumEventHandler<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Event handler for presentation item events.

IPresentumGuard<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Guard for the presentum.

IPresentumTransitionObserver<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Observer for Presentum state transitions.

ItemActivatedChange<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

An item became the active item in a slot.

ItemCallback<T>

Callback for calculating the diff between two non-null items in a list.

ItemDeactivatedChange<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

An item was removed from the active slot.

ItemDequeuedChange<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

An item was removed from a slot's queue.

ItemQueuedChange<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

An item was added to a slot's queue.

ListDiffCallback<T>

A simple implementation of DiffCallback for comparing two lists directly.

ListUpdateCallback

Interface for receiving update operations from DiffResult.

MetadataExtractor<S extends HasMetadata>

Base class for metadata-based extractors.

MoveOperation

Represents a move operation.

NoOpPresentumStorage<S extends PresentumSurface, V extends PresentumVisualVariant>

No-op implementation of the presentum storage. Used when storage is not provided.

NotEligibility

Inverts the result of a nested condition (NOT combinator).

NotRule

Evaluates NotEligibility conditions (NOT combinator).

NumericComparisonEligibility

A numeric value from context must satisfy a comparison with a threshold.

NumericComparisonExtractor<S extends HasMetadata>

Extracts NumericComparisonEligibility from metadata.

NumericComparisonRule

Evaluates NumericComparisonEligibility conditions.

Presentum<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

The main class of the package.

PresentumConvertedEvent<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Event when a presentation item is converted.

PresentumDismissedEvent<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Event when a presentation item is dismissed.

PresentumEngine<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Presentum engine.

PresentumEvent<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Event that can occur during presentation lifecycle.

PresentumGuard<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Guard for the router.

PresentumHistoryEntry<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Presentum history entry.

PresentumItem<TPayload extends PresentumPayload<S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

A concrete decision: "show payload with option on surface now".

PresentumOption<S extends PresentumSurface, V extends PresentumVisualVariant>

One renderable option of an item for a given surface and visual variant style.

PresentumOutlet<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Outlet that can render items from a surface of the same type.

PresentumOutlet$Composition<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Outlet that can render items from a surface of the same type.

PresentumOutlet$Composition2<TItem1 extends PresentumItem<PresentumPayload<S1, V1>, S1, V1>, TItem2 extends PresentumItem<PresentumPayload<S2, V2>, S2, V2>, S1 extends PresentumSurface, V1 extends PresentumVisualVariant, S2 extends PresentumSurface, V2 extends PresentumVisualVariant>

Cross-presentum composition outlet for two different presentums.

PresentumOutlet$Composition3<TItem1 extends PresentumItem<PresentumPayload<S1, V1>, S1, V1>, TItem2 extends PresentumItem<PresentumPayload<S2, V2>, S2, V2>, TItem3 extends PresentumItem<PresentumPayload<S3, V3>, S3, V3>, S1 extends PresentumSurface, S2 extends PresentumSurface, S3 extends PresentumSurface, V1 extends PresentumVisualVariant, V2 extends PresentumVisualVariant, V3 extends PresentumVisualVariant>

Cross-presentum composition outlet for three different presentums.

PresentumPayload<S extends PresentumSurface, V extends PresentumVisualVariant>

Generic payload that contain options that can be presented across multiple surfaces.

PresentumShownEvent<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Event when a presentation item is shown.

PresentumSlot<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

A presentation slot is the per‑surface queue:

PresentumState<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Sealed root type for presentation state.

PresentumState$Immutable<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

PresentumState$Mutable<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Mutable state.

PresentumStateBase<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Base class for presentation state implementations.

PresentumStateDiff<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Computed difference between two Presentum states.

PresentumStateObserver<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Presentum state observer.

PresentumStateTransition<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Represents a state transition in the Presentum engine.

PresentumStorage<S extends PresentumSurface, V extends PresentumVisualVariant>

Storage contract used by guards (domain provides implementation).

PresentumStorageEventHandler<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Event handler for the presentum storage.

RecurringTimePatternEligibility

Time must match a recurring weekly pattern (cron-like).

RecurringTimePatternExtractor<S extends HasMetadata>

Extracts RecurringTimePatternEligibility from metadata.

RecurringTimePatternRule

Evaluates RecurringTimePatternEligibility conditions.

RemoveOperation

Represents a remove operation.

SetMembershipEligibility

A value must be present in a specified set.

SetMembershipExtractor<S extends HasMetadata>

Extracts SetMembershipEligibility from metadata.

SetMembershipRule

Evaluates SetMembershipEligibility conditions.

SimpleItemCallback<T>

A simple ItemCallback implementation that uses object equality and a custom ID function.

SlotChange<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Base class for all slot changes.

SlotDiff<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant>

Computed difference for a single slot/surface.

StringMatchEligibility

A string value from context must match a pattern.

StringMatchExtractor<S extends HasMetadata>

Extracts StringMatchEligibility from metadata.

StringMatchRule

Evaluates StringMatchEligibility conditions.

TimeOfDay

Time of day representation (hours and minutes).

TimeRangeEligibility

Time must fall within a specified range (inclusive of start, exclusive of end).

TimeRangeExtractor<S extends HasMetadata>

Extracts TimeRangeEligibility from metadata.

TimeRangeRule

Evaluates TimeRangeEligibility conditions.

Enums

DayOfWeek

Days of the week for recurring patterns.

NumericComparison

Comparison operators for numeric eligibility.

OutletGroupMode

How a PresentumOutlet should select items from a surface slot.

PopupConflictStrategy

Strategy for handling popup conflicts when a new popup activates while another is already showing.

PopupPresentResult

Result of presenting a popup.

PresentumStateIntention

PresentumState$Mutable intention to change and update state at application.

Mixins

PresentumActiveSurfaceItemObserverMixin<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant, T extends StatefulWidget>

Observes a surface's slot for active item changes and executes custom logic.

PresentumOutlet$CompositionMixin

Mixin that contains the logic for collecting items from a surface slot.

PresentumPopupSurfaceStateMixin<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant, T extends StatefulWidget>

Manages popup presentation (dialogs/fullscreen widgets) for a surface.

PresentumSurface

Marker for all presentum surfaces.

PresentumVisualVariant

Marker for all presentum visual styles.

Extension Types

MetadataKeys

Standard metadata field names used across the eligibility system.

Extensions

MetadataExtraction on Map<String, dynamic>

Type-safe utilities for extracting structured data from metadata.

PresentumBuildContextExtension on BuildContext

Extension methods for BuildContext.

Functions

createStandardRules() → List<EligibilityRule<Eligibility>>

Convenience function to create a standard rule set with all built-in rules.

Typedefs

CompositionItemsResolver<TItem> = List<TItem> Function(List<TItem> items)

Resolver function that decides how to select items from a surface slot.

CompositionItemsResolver2<TItem1, TItem2> = List<PresentumItem<PresentumPayload<PresentumSurface, PresentumVisualVariant>, PresentumSurface, PresentumVisualVariant>> Function(List<TItem1> items1, List<TItem2> items2)

Resolver function that decides how to combine items from two different presentums.

CompositionItemsResolver3<TItem1, TItem2, TItem3> = List<PresentumItem<PresentumPayload<PresentumSurface, PresentumVisualVariant>, PresentumSurface, PresentumVisualVariant>> Function(List<TItem1> items1, List<TItem2> items2, List<TItem3> items3)

Resolver function that decides how to combine items from three different presentums.

ConditionalSlotVisitor<TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant> = bool Function(S surface, PresentumSlot<TItem, S, V> slot)

Signature for the callback to PresentumState.visitSlots.

PresentumOutletBuilder<T> = Widget Function(BuildContext context, T item)

Builder function that receives the BuildContext and the TItem item.

PresentumOutletPlaceholderBuilder = Widget Function(BuildContext context)

Builder function that receives the BuildContext and returns a placeholder widget.

SlotChangeMatch<R, T extends SlotChange<TItem, S, V>, TItem extends PresentumItem<PresentumPayload<S, V>, S, V>, S extends PresentumSurface, V extends PresentumVisualVariant> = R Function(T value)

Signature for slot change pattern matching callbacks.

Exceptions / Errors

EligibilityException

Base class for all eligibility exceptions.

EvaluationException

Thrown when an eligibility rule evaluation fails unexpectedly.

MalformedMetadataException

Thrown when metadata cannot be parsed into an eligibility condition.