BlocxCollectionBloc<T extends BlocxBaseEntity, P> class abstract

Base class for all list/collection blocs in the blocx ecosystem.

Manages an immutable, paginated list of BlocxBaseEntity items. Mixin capabilities are auto-initialised in the constructor based on which mixins are applied to the concrete subclass — no manual init calls needed.

Minimal setup

Override paginationTask with a BlocxPaginatedUseCaseTask and dispatch BlocxCollectionEventLoadInitialPage to trigger the first load:

class OrdersBloc extends BlocxCollectionBloc<Order, void> {
  OrdersBloc() : super();

  @override
  BlocxPaginatedUseCaseTask get paginationTask => BlocxPaginatedUseCaseTask(
    useCase: _getOrdersUseCase,
    inputBuilder: ({required limit, required offset}) =>
        BlocxPaginationInput(limit: limit, offset: offset),
  );
}

Optional features (applied via mixins)

Mixin	Behaviour unlocked
BlocxCollectionRefreshableMixin	Pull-to-refresh
BlocxCollectionInfiniteMixin	Infinite scroll / next-page loading
BlocxCollectionSearchableMixin	Debounced search with separate result list
BlocxCollectionSelectableMixin	Multi-item selection
BlocxCollectionDeletableMixin	Animated item removal
BlocxCollectionHighlightableMixin	Temporary item highlighting
BlocxCollectionExpandableMixin	Expandable / collapsible items
BlocxCollectionScrollableMixin	Programmatic scroll-to-item
BlocxCollectionSyncStreamMixin	Live updates via a stream

Type parameters

T: The entity type. Must extend BlocxBaseEntity.
P: The payload type passed with BlocxCollectionEventLoadInitialPage. Use void when no payload is needed.

Inheritance

Object
BaseBloc<BlocxCollectionEvent<T>, BlocxCollectionState<T>>
BlocxCollectionBloc

Implementers

Constructors

BlocxCollectionBloc(): Creates the bloc.

Properties

additionalInfo → dynamic: Optional additional metadata attached to loaded states.
no setterinherited
beingRemovedItemIds → Set<String>: Identifiers of items currently being removed.
no setter
beingSelectedItemIds → Set<String>: Identifiers of items currently being selected.
no setter
defaultError → ReadableError: The fallback ReadableError used when no BlocxErrorTranslator is registered or when the translator does not recognise the error.
no setterinherited
errorDisplayPolicy → ErrorDisplayPolicy: Controls how errors are surfaced to the user.
no setterinherited
expandedItemIds → Set<String>: Identifiers of expanded items.
no setter
hashCode → int: The hash code for this object.
no setterinherited
hasReachedEnd ↔ bool: Whether the collection has reached the final page.
getter/setter pairinherited
highlightedItemIds → Set<String>: Identifiers of highlighted items.
no setter
infiniteListBloc → BlocxInfiniteListBloc: Infinite list controller used for pagination coordination.
no setter
infiniteListRefreshThreshold → double: The drag distance (in pixels) required to trigger a pull-to-refresh.
no setter
isClosed → bool: Whether the bloc is closed.
no setterinherited
isDeletable → bool: Whether BlocxCollectionDeletableMixin is applied.
no setter
isExpandable → bool: Whether BlocxCollectionExpandableMixin is applied.
no setter
isHighlightable → bool: Whether item highlighting is enabled.
no setter
isInfinite → bool: Whether BlocxCollectionInfiniteMixin is applied.
no setter
isLoadingNextPage ↔ bool: Whether a next-page request is currently running.
getter/setter pairinherited
isRefreshable → bool: Whether BlocxCollectionRefreshableMixin is applied.
no setter
isRefreshing ↔ bool: Whether a refresh operation is currently active.
getter/setter pairinherited
isScrollable → bool: Whether BlocxCollectionScrollableMixin is applied.
no setter
isSearchable → bool: Whether BlocxCollectionSearchableMixin is applied.
no setter
isSearching ↔ bool: Whether a search operation is currently active.
getter/setter pairinherited
isSelectable → bool: Whether BlocxCollectionSelectableMixin is applied.
no setter
isStreamable → bool: Whether BlocxCollectionSyncStreamMixin is applied.
no setter
limit → int: Default number of items to load per page.
no setterinherited
list → UnmodifiableListView<T>: Immutable view of the internal list.
no setterinherited
loadInitialPageTask → BlocxPaginatedUseCaseTask<BlocxPaginatedInput, T>?: Task responsible for loading the initial page.
no setterinherited
offset → int: Current offset based on loaded items.
no setterinherited
paginationTask → BlocxPaginatedUseCaseTask<BlocxPaginatedInput, T>?: Shared paginated task used by initial load, next-page load, and refresh.
no setterinherited
payload ↔ P?: Optional external payload used for initial loading.
getter/setter pairinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
screenManagerCubit → ScreenManagerCubit: Direct access to the internal ScreenManagerCubit.
no setterinherited
selectedItemIds → Set<String>: Identifiers of selected items.
no setter
state → BlocxCollectionState<T>: The current state.
no setterinherited
stream → Stream<BlocxCollectionState<T>>: The current stream of states.
no setterinherited

Methods

add(BlocxCollectionEvent<T> event) → void: Notifies the Bloc of a new event which triggers all corresponding EventHandler instances.
inherited
addError(Object error, [StackTrace? stackTrace]) → void: Reports an error which triggers onError with an optional StackTrace.
inherited
addItem(BlocxCollectionEventAddItem<T> event, Emitter<BlocxCollectionState<T>> emit) → Future<void>: Adds event.item to the collection.
inherited
clearList() → void: Clears all collection items.
inherited
close() → Future<void>: Closes the internal ScreenManagerCubit before closing the bloc itself.
override
displayErrorSnackbar(String message, {String? title}) → void: Displays an error snackbar with message and optional title.
inherited
displayErrorWidget(ReadableError error) → void: Displays a full-page error widget for error.
inherited
displayErrorWidgetByErrorCode(BlocXErrorCode errorCode, {Object? error, StackTrace? stackTrace}) → void: Displays a full-page error widget derived from a BlocXErrorCode.
inherited
displayInfoSnackbar(String message, {String? title}) → void: Displays an info snackbar with message and optional title.
inherited
displayWarningSnackbar(String message, {String? title}) → void: Displays a warning snackbar with message and optional title.
inherited
doAfterInsert() → void: Hook executed after insert operations.
inherited
emit(BlocxCollectionState<T> state) → void: emit is only for internal use and should never be called directly outside of tests. The Emitter instance provided to each EventHandler should be used instead.
inherited
emitState(Emitter<BlocxCollectionState<T>> emit) → void: Emits the current loaded collection state.
inherited
handleError(Object error, Emitter<BaseState> emit, {StackTrace? stacktrace}) → FutureOr<void>: Logs error, translates it to a ReadableError, then surfaces it according to errorDisplayPolicy.
inherited
handleReplaceList(BlocxCollectionEventReplaceList<T> event, Emitter<BlocxCollectionState<T>> emit) → FutureOr<void>: Handles full list replacement.
inherited
initCoreMixin() → void: Registers core collection event handlers.
inherited
insertToList(List<T> data, bool hasReachedEnd, DataInsertSource insertSource) → Future<void>: Inserts data into the collection using insertSource.
inherited
insertToListSingle(T item, {int index = 0}) → void: Inserts a single item at index.
inherited
loadInitialPage(BlocxCollectionEventLoadInitialPage<T, P> event, Emitter<BlocxCollectionState<T>> emit) → Future<void>: Loads the first page of collection data.
inherited
modifyListBeforeInsert(List<T> data) → Future<List<T>>: Allows modification of incoming data before insertion.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
on<E extends Event>(EventHandler<E, BlocxCollectionState<T>> handler, {EventTransformer<E>? transformer}) → void: Register event handler for an event of type E. There should only ever be one event handler per event type E.
inherited
onChange(Change<BlocxCollectionState<T>> change) → void: Called whenever a change occurs with the given change. A change occurs when a new state is emitted. onChange is called before the state of the cubit is updated. onChange is a great spot to add logging/analytics for a specific cubit.
inherited
onDone(BlocxCollectionEvent<T> event, [Object? error, StackTrace? stackTrace]) → void: Called whenever an event handler for a specific Bloc has completed. This may include an error and stackTrace if an uncaught exception occurred within the event handler.
inherited
onError(Object error, StackTrace stackTrace) → void: Called whenever an error occurs and notifies BlocObserver.onError.
inherited
onEvent(BlocxCollectionEvent<T> event) → void: Called whenever an event is added to the Bloc. A great spot to add logging/analytics at the individual Bloc level.
inherited
onTransition(Transition<BlocxCollectionEvent<T>, BlocxCollectionState<T>> transition) → void: Called whenever a transition occurs with the given transition. A transition occurs when a new event is added and a new state is emitted from a corresponding EventHandler.
inherited
pop() → void: Triggers a pop/back-navigation signal.
inherited
removeItemFromList(T item) → void: Removes one item from the collection.
inherited
replaceItemInList(T item) → void: Replaces one existing item.
inherited
replaceList(List<T> newList) → void: Replaces the entire collection with newList.
inherited
sortList(Comparator<T> comparator) → void: Sorts the collection using comparator.
inherited
toString() → String: A string representation of this object.
inherited
updateItem(BlocxCollectionEventUpdateItem<T> event, Emitter<BlocxCollectionState<T>> emit) → FutureOr<void>: Updates event.item inside the collection.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited