@dereekb/dbx-core 13.2.1 → 13.2.2

package/fesm2022/dereekb-dbx-core.mjs

@@ -214,29 +214,92 @@ function cleanDestroy(input) {
 }
 
 /**
- * Source that provides a ActionContextStore observable.
+ * Abstract source that provides an observable of an {@link ActionContextStore}.
+ *
+ * This is the primary injection token used by action directives to access the action state.
+ * Implementations are typically provided via Angular's DI, either by {@link DbxActionDirective}
+ * or through secondary source providers.
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionDirective} for the directive that provides this source.
+ * @see {@link SecondaryActionContextStoreSource} for nested action source forwarding.
  */
 class ActionContextStoreSource {
 }
 /**
- * Secondary source. Used by DbxActionContextComponent to find secondary sources.
+ * Secondary action context store source used for nested or forwarded action contexts.
+ *
+ * When a {@link DbxActionDirective} is created, it checks for the presence of this secondary
+ * source via host injection. If found, the directive reuses the existing store rather than
+ * creating its own, enabling action context sharing across component boundaries.
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionSourceDirective} for the directive that provides this.
  */
 class SecondaryActionContextStoreSource extends ActionContextStoreSource {
 }
+/**
+ * Filters null/undefined values from an observable of {@link ActionContextStore} instances.
+ *
+ * @typeParam T - The input value type.
+ * @typeParam O - The output result type.
+ * @param obs - The observable that may emit null/undefined store values.
+ * @returns An observable that only emits non-null store instances.
+ */
 function actionContextStoreSourcePipe(obs) {
     return obs.pipe(filterMaybe());
 }
+/**
+ * Pipes a function through the action store from the given source.
+ *
+ * Subscribes to the source's store observable and applies the provided function
+ * via switchMap, automatically switching to the latest store.
+ *
+ * @typeParam R - The return type of the derived observable.
+ * @typeParam T - The input value type.
+ * @typeParam O - The output result type.
+ * @param source - The action context store source to read from.
+ * @param pipeFn - The function to apply to each emitted store.
+ * @returns An observable of the derived value.
+ */
 function pipeActionStore(source, pipeFn) {
     return source.store$.pipe(switchMap(pipeFn));
 }
 /**
- * Convenience function for subscribing to the input source once and using the provided store.
+ * Subscribes to the source once and invokes the provided function with the store.
+ *
+ * This is a convenience for performing one-shot imperative operations on the store,
+ * such as triggering an action or setting a value, without maintaining a long-lived subscription.
+ *
+ * @typeParam T - The input value type.
+ * @typeParam O - The output result type.
+ * @param source - The action context store source to read from.
+ * @param useFn - The function to invoke with the store.
+ * @returns The subscription (completes after first emission).
  */
 function useActionStore(source, useFn) {
     return source.store$.pipe(first()).subscribe(useFn);
 }
 /**
- * Service that wraps a ActionContextStoreSource.
+ * Convenience wrapper around an {@link ActionContextStoreSource} that provides direct
+ * access to all the store's reactive selectors and imperative state-change methods.
+ *
+ * This class is the primary interface injected by action directives to interact with
+ * the action lifecycle. It delegates all operations through the underlying source's
+ * store observable, while also maintaining a {@link LockSet} for cleanup coordination.
+ *
+ * All reactive properties (e.g., `isWorking$`, `success$`, `error$`) are piped through
+ * the source's `store$` via switchMap, so they automatically follow store changes.
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link ActionContextStore} for the underlying store.
+ * @see {@link ActionContextStoreSource} for the source abstraction.
  */
 class DbxActionContextStoreSourceInstance {
     lockSet = new LockSet();
@@ -373,6 +436,28 @@ class DbxActionContextStoreSourceInstance {
     }
 }
 
+/**
+ * Directive that automatically marks the parent action as modified whenever it becomes unmodified.
+ *
+ * This ensures the action is always considered "modified" and therefore always eligible for triggering.
+ * Useful in combination with {@link DbxActionAutoTriggerDirective} and {@link DbxActionEnforceModifiedDirective}
+ * when the action should be continuously available for submission.
+ *
+ * Can be disabled by setting `dbxActionAutoModify` to `false`.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container dbxActionAutoModify></ng-container>
+ *   <ng-container dbxActionAutoTrigger></ng-container>
+ * </div>
+ * ```
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionAutoTriggerDirective} for automatically triggering modified actions.
+ */
 class DbxActionAutoModifyDirective {
     source = inject((DbxActionContextStoreSourceInstance), { host: true });
     autoModifyEnabled = input(true, { ...(ngDevMode ? { debugName: "autoModifyEnabled" } : {}), alias: 'dbxActionAutoModify', transform: isNotFalse });
@@ -412,9 +497,35 @@ const MAX_ERRORS_TO_THROTTLE_ON = 6;
 const DBX_ACTION_AUTO_TRIGGER_FAST_TRIGGER_DEBOUNCE = 200;
 const DBX_ACTION_AUTO_TRIGGER_INSTANT_TRIGGER_DEBOUNCE = 10;
 /**
- * Directive that automatically triggers the action periodically when it is in a modified state.
+ * Directive that automatically triggers the parent action when the action becomes modified and can be triggered.
+ *
+ * Uses configurable debounce and throttle timers to prevent excessive triggering. Also
+ * supports error-aware throttling: as consecutive errors accumulate, the throttle interval
+ * increases to give transient issues time to resolve.
+ *
+ * Useful for auto-save scenarios where data changes should automatically submit without
+ * requiring an explicit user action. Use with care to avoid triggering loops.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container dbxActionAutoTrigger></ng-container>
+ *   <!-- form or value source here -->
+ * </div>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Fast trigger preset with limit -->
+ * <div dbxAction>
+ *   <ng-container dbxActionAutoTrigger useFastTriggerPreset [triggerLimit]="5"></ng-container>
+ * </div>
+ * ```
  *
- * When using auto triggers be sure to make sure that the action is not triggering too often due to misconfiguration.
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionAutoModifyDirective} for automatically marking the action as modified.
  */
 class DbxActionAutoTriggerDirective {
     source = inject((DbxActionContextStoreSourceInstance), { host: true });
@@ -510,7 +621,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [], propDecorators: { triggerDebounce: [{ type: i0.Input, args: [{ isSignal: true, alias: "triggerDebounce", required: false }] }], triggerThrottle: [{ type: i0.Input, args: [{ isSignal: true, alias: "triggerThrottle", required: false }] }], triggerErrorThrottle: [{ type: i0.Input, args: [{ isSignal: true, alias: "triggerErrorThrottle", required: false }] }], maxErrorsForThrottle: [{ type: i0.Input, args: [{ isSignal: true, alias: "maxErrorsForThrottle", required: false }] }], triggerLimit: [{ type: i0.Input, args: [{ isSignal: true, alias: "triggerLimit", required: false }] }], triggerEnabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionAutoTrigger", required: false }] }], useFastTriggerPreset: [{ type: i0.Input, args: [{ isSignal: true, alias: "useFastTriggerPreset", required: false }] }], useInstantTriggerPreset: [{ type: i0.Input, args: [{ isSignal: true, alias: "useInstantTriggerPreset", required: false }] }] } });
 
 /**
- * WorkInstanceDelegate implementation using an DbxActionContextStoreSourceInstance.
+ * {@link WorkInstanceDelegate} implementation that bridges the `@dereekb/rxjs` work execution
+ * system with the action context store.
+ *
+ * This delegate translates work lifecycle events (startWorking, success, reject) into
+ * corresponding state transitions on the {@link DbxActionContextStoreSourceInstance},
+ * allowing {@link workFactory} to drive the action state machine.
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionHandlerInstance} which uses this delegate to handle value-ready events.
  */
 class DbxActionWorkInstanceDelegate {
     _source;
@@ -593,7 +714,19 @@ var DbxActionState;
      */
     DbxActionState["RESOLVED"] = "resolved";
 })(DbxActionState || (DbxActionState = {}));
+/**
+ * The default disabled key used when no specific key is provided to {@link ActionContextStore.disable}.
+ */
 const DEFAULT_ACTION_DISABLED_KEY = 'dbx_action_disabled';
+/**
+ * Determines whether the given action state represents an idle-like state.
+ *
+ * Idle-like states include IDLE, DISABLED, REJECTED, and RESOLVED -- any state
+ * where the action is not currently in-progress (triggered, value-ready, or working).
+ *
+ * @param actionState - The action state to check.
+ * @returns `true` if the state is idle-like, `false` if the action is in-progress.
+ */
 function isIdleActionState(actionState) {
     switch (actionState) {
         case DbxActionState.IDLE:
@@ -605,6 +738,15 @@ function isIdleActionState(actionState) {
             return false;
     }
 }
+/**
+ * Maps a {@link DbxActionState} to the corresponding {@link LoadingStateType}.
+ *
+ * This bridges the action state machine with the loading state system from `@dereekb/rxjs`,
+ * allowing action states to be represented as loading states for UI display.
+ *
+ * @param actionState - The action state to convert.
+ * @returns The corresponding loading state type (IDLE, LOADING, SUCCESS, or ERROR).
+ */
 function loadingStateTypeForActionState(actionState) {
     let loadingStateType;
     switch (actionState) {
@@ -625,34 +767,119 @@ function loadingStateTypeForActionState(actionState) {
     return loadingStateType;
 }
 
+/**
+ * Checks whether the action context is enabled (not disabled by any key).
+ *
+ * @param state - The current action context state to check.
+ * @returns `true` if no disabled keys are active.
+ */
 function isActionContextEnabled(state) {
     return BooleanStringKeyArrayUtility.isFalse(state.disabled);
 }
+/**
+ * Checks whether the action context is disabled by at least one disabled key.
+ *
+ * @param state - The current action context state to check.
+ * @returns `true` if any disabled keys are active.
+ */
 function isActionContextDisabled(state) {
     return BooleanStringKeyArrayUtility.isTrue(state.disabled);
 }
+/**
+ * Checks whether the action context state represents an effectively disabled state.
+ *
+ * An action is considered disabled when it is both idle (not in-progress) and has
+ * at least one active disabled key.
+ *
+ * @param state - The current action context state to check.
+ * @returns `true` if the action is idle and disabled.
+ */
 function isDisabledActionContextState(state) {
     return isIdleActionState(state.actionState) && isActionContextDisabled(state);
 }
+/**
+ * Checks whether the given action state represents an in-progress (non-idle) state.
+ *
+ * This is the inverse of {@link isIdleActionState}. Returns `true` for TRIGGERED, VALUE_READY, and WORKING states.
+ *
+ * @param actionState - The action state to check.
+ * @returns `true` if the action is in any non-idle state.
+ */
 function isWorkingActionState(actionState) {
     return !isIdleActionState(actionState);
 }
+/**
+ * Determines whether the action state allows triggering.
+ *
+ * An action can be triggered when it is idle (but not DISABLED specifically) and
+ * not already in-progress.
+ *
+ * @param actionState - The action state to check.
+ * @returns `true` if the action can be triggered from this state.
+ */
 function canTriggerActionState(actionState) {
     return actionState !== DbxActionState.DISABLED && isIdleActionState(actionState);
 }
+/**
+ * Determines whether the action can be triggered based on the full context state.
+ *
+ * Requires the action to be both enabled (no disabled keys) and in an idle action state.
+ *
+ * @param state - The current action context state to check.
+ * @returns `true` if the action can be triggered.
+ */
 function canTriggerAction(state) {
     return isActionContextEnabled(state) && isIdleActionState(state.actionState);
 }
+/**
+ * Determines whether a value can be readied for the action.
+ *
+ * A value can only be readied when the action is in the TRIGGERED state,
+ * which means the trigger has been activated and the system is waiting for a value.
+ *
+ * @param state - The current action context state to check.
+ * @returns `true` if the action is in the TRIGGERED state.
+ */
 function canReadyValue(state) {
     return state.actionState === DbxActionState.TRIGGERED;
 }
+/**
+ * Checks whether the action context is both modified and ready to be triggered.
+ *
+ * This is commonly used by auto-trigger directives to determine when to fire automatically.
+ *
+ * @param state - The current action context state to check.
+ * @returns `true` if the action is modified and can be triggered.
+ */
 function actionContextIsModifiedAndCanTrigger(state) {
     // console.log('check: ', state, state.isModified, canTriggerAction(state));
     return state.isModified && canTriggerAction(state);
 }
+/**
+ * Checks whether the action context has no error, is modified, and can be triggered.
+ *
+ * A stricter variant of {@link actionContextIsModifiedAndCanTrigger} that also requires
+ * no error to be present in the current state.
+ *
+ * @param state - The current action context state to check.
+ * @returns `true` if no error exists and the action is modified and triggerable.
+ */
 function actionContextHasNoErrorAndIsModifiedAndCanTrigger(state) {
     return !state.error && actionContextIsModifiedAndCanTrigger(state);
 }
+/**
+ * Converts an {@link ActionContextState} to a {@link LoadingState} for UI consumption.
+ *
+ * Maps the action lifecycle states to loading state equivalents:
+ * - RESOLVED -> success result with the output value
+ * - REJECTED -> error result with the error
+ * - IDLE/DISABLED -> idle loading state
+ * - All other states -> loading (with optional work progress)
+ *
+ * @typeParam O - The output result type.
+ * @param state - The action context state to convert.
+ * @returns A loading state representation of the action context state.
+ */
 function loadingStateForActionContextState(state) {
     let loadingState;
     switch (state.actionState) {
@@ -672,6 +899,14 @@ function loadingStateForActionContextState(state) {
     }
     return loadingState;
 }
+/**
+ * Extracts the {@link LoadingStateType} from the current action context state.
+ *
+ * A convenience wrapper around {@link loadingStateTypeForActionState} that accepts the full context state.
+ *
+ * @param state - The action context state to convert.
+ * @returns The corresponding loading state type.
+ */
 function loadingStateTypeForActionContextState(state) {
     return loadingStateTypeForActionState(state.actionState);
 }
@@ -679,7 +914,33 @@ const INITIAL_STATE = {
     isModified: false,
     actionState: DbxActionState.IDLE
 };
+/**
+ * Delay in milliseconds before the lock set destroys the store after all locks are released.
+ * Provides a grace period for actions to finalize before the store is torn down.
+ */
 const ACTION_CONTEXT_STORE_LOCKSET_DESTROY_DELAY_TIME = 2000;
+/**
+ * NgRx ComponentStore that manages the reactive state machine for a single action lifecycle.
+ *
+ * This is the central state container for the action system. It tracks the full lifecycle
+ * of an action from idle through trigger, value preparation, work execution, and resolution
+ * or rejection. Multiple selectors expose derived reactive streams for each phase.
+ *
+ * The store uses a {@link LockSet} for cleanup coordination: it delays its own destruction
+ * until all in-flight work completes (e.g., a working action finishes), preventing
+ * premature teardown of subscriptions.
+ *
+ * State transitions follow this flow:
+ * ```
+ * IDLE/DISABLED -> TRIGGERED -> VALUE_READY -> WORKING -> RESOLVED | REJECTED
+ * ```
+ *
+ * @typeParam T - The input value type provided after triggering.
+ * @typeParam O - The output result type produced on resolution.
+ *
+ * @see {@link ActionContextStoreSource} for providing store access to directives.
+ * @see {@link DbxActionContextStoreSourceInstance} for the convenience wrapper.
+ */
 class ActionContextStore extends ComponentStore {
     lockSet = cleanLockSet({
         onLockSetDestroy: () => super.ngOnDestroy(),
@@ -909,7 +1170,20 @@ function updateIsModifiedOnActionContextState(state, isModified) {
 }
 
 /**
- * Abstract class that can either use SecondaryActionContextStoreSource or create it's own.
+ * Base class for action context sources that can either reuse an existing
+ * {@link SecondaryActionContextStoreSource} or create their own internal {@link ActionContextStore}.
+ *
+ * If a secondary source is provided (typically via Angular DI), it is used directly,
+ * enabling store sharing across component boundaries. Otherwise, a new standalone store is created.
+ *
+ * This class also creates a {@link DbxActionContextStoreSourceInstance} for convenient access
+ * to the store's reactive streams and imperative methods.
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionDirective} which extends this class.
+ * @see {@link DbxActionContextMachine} which extends this class for programmatic use.
  */
 class DbxActionContextBaseSource {
     _inputSource;
@@ -1078,7 +1352,40 @@ function provideSecondaryActionStoreSource(sourceType) {
 }
 
 /**
- * Provides an DbxAction/DbxActionContext.
+ * Core directive that creates and provides an action context for its host element and descendants.
+ *
+ * This is the root of the action system in templates. It creates an {@link ActionContextStore}
+ * and provides it (along with the related source tokens) via Angular's dependency injection,
+ * making the action lifecycle available to all child action directives.
+ *
+ * If a {@link SecondaryActionContextStoreSource} is available on the host, the directive will
+ * reuse that store instead of creating its own, enabling action context forwarding.
+ *
+ * On destruction, the directive coordinates cleanup through a {@link LockSet} to ensure
+ * in-flight operations complete before the store is torn down.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <button (click)="action.trigger()">Submit</button>
+ *   <div *dbxActionHasSuccess>Success!</div>
+ *   <div *dbxActionWorking>Loading...</div>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- As an element -->
+ * <dbx-action>
+ *   <ng-container [dbxActionHandler]="handleAction">...</ng-container>
+ * </dbx-action>
+ * ```
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionSourceDirective} for forwarding an external action source.
+ * @see {@link ActionContextStore} for the underlying state store.
  */
 class DbxActionDirective extends DbxActionContextBaseSource {
     constructor() {
@@ -1104,7 +1411,25 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * Directive that provides a DbxActionSourceDirective that is passed in.
+ * Directive that forwards an externally-provided {@link ActionContextStoreSource} as a
+ * {@link SecondaryActionContextStoreSource}, enabling child `dbxAction` directives to
+ * reuse an existing action context rather than creating their own.
+ *
+ * This is useful when an action context is created programmatically (e.g., via
+ * {@link DbxActionContextMachine}) and needs to be shared with template-based directives.
+ *
+ * @example
+ * ```html
+ * <!-- Forward a programmatic action source to template directives -->
+ * <div [dbxActionSource]="myActionSource">
+ *   <div dbxAction>
+ *     <button (click)="action.trigger()">Submit</button>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @see {@link DbxActionDirective} for the directive that consumes this source.
+ * @see {@link SecondaryActionContextStoreSource}
  */
 class DbxActionSourceDirective {
     dbxActionSource = input(...(ngDevMode ? [undefined, { debugName: "dbxActionSource" }] : []));
@@ -1122,7 +1447,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { dbxActionSource: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionSource", required: false }] }] } });
 
 /**
- * Prints out the current state to the console. Useful for debugging.
+ * Debug directive that logs every action context state change to the console.
+ *
+ * Subscribes to the parent action's full state stream and prints each state snapshot
+ * via `console.log`. Useful during development to inspect the action lifecycle transitions.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container dbxActionLogger></ng-container>
+ *   <!-- other action directives -->
+ * </div>
+ * ```
  */
 class DbxActionContextLoggerDirective {
     source = inject(DbxActionContextStoreSourceInstance, { host: true });
@@ -1146,7 +1482,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * Map that returns sources for ActionKey values.
+ * Abstract map that associates {@link ActionKey} values with {@link ActionContextStoreSource} instances.
+ *
+ * This allows multiple independent actions to be registered and retrieved by key,
+ * enabling coordination between related actions (e.g., disabling one while another is working).
+ *
+ * @typeParam T - The input value type for the actions.
+ * @typeParam O - The output result type for the actions.
+ *
+ * @see {@link actionContextStoreSourceMap} for the factory function.
+ * @see {@link DbxActionContextMapDirective} for the directive that provides this in templates.
  */
 class ActionContextStoreSourceMap {
 }
@@ -1204,9 +1549,28 @@ function actionContextStoreSourceMap() {
 }
 
 /**
- * Context used for providing actions based on the action key.
+ * Directive that creates and provides an {@link ActionContextStoreSourceMap} for its descendants.
+ *
+ * This enables a group of related action contexts to be registered by key and looked up
+ * by child directives. Useful when multiple actions need to coordinate (e.g., disable
+ * all other actions while one is working).
  *
- * This is useful for passing action contexts around via the providers instead of explicit injection.
+ * The map is exported as `actionMap` for template reference access.
+ *
+ * @example
+ * ```html
+ * <div dbxActionContextMap>
+ *   <div dbxAction [dbxActionMapSource]="'save'">...</div>
+ *   <div dbxAction [dbxActionMapSource]="'delete'">...</div>
+ *   <div [dbxActionFromMap]="'save'">
+ *     <!-- consumes the 'save' action context -->
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @see {@link DbxActionFromMapDirective} for consuming actions by key.
+ * @see {@link DbxActionMapSourceDirective} for registering actions by key.
+ * @see {@link DbxActionMapWorkingDisableDirective} for cross-action disable coordination.
  */
 class DbxActionContextMapDirective {
     actionContextStoreSourceMap = clean(inject(ActionContextStoreSourceMap));
@@ -1234,7 +1598,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Directive that provides a ActionContextStoreSource using the input key and DbxActionContextMapDirective.
+ * Directive that retrieves an {@link ActionContextStoreSource} from an ancestor
+ * {@link DbxActionContextMapDirective} using the provided key, and provides it as
+ * a {@link SecondaryActionContextStoreSource} for descendant `dbxAction` directives.
+ *
+ * This allows a child action context to bind to an action that was registered elsewhere
+ * in the template via {@link DbxActionMapSourceDirective}.
+ *
+ * @example
+ * ```html
+ * <div dbxActionContextMap>
+ *   <div dbxAction [dbxActionMapSource]="'myAction'">...</div>
+ *   <!-- Consume the registered action elsewhere in the tree -->
+ *   <div [dbxActionFromMap]="'myAction'">
+ *     <div dbxAction>
+ *       <div *dbxActionHasSuccess>Done!</div>
+ *     </div>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @see {@link DbxActionContextMapDirective} for the parent map provider.
+ * @see {@link DbxActionMapSourceDirective} for registering an action into the map.
  */
 class DbxActionFromMapDirective {
     _actionContextStoreSourceMap = inject(ActionContextStoreSourceMap);
@@ -1254,7 +1639,23 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { key: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionFromMap", required: false }] }] } });
 
 /**
- * Used to communicate with an dbxActionMap and set the ActionContextStore to the store based on the key.
+ * Directive that registers the host element's {@link ActionContextStoreSource} into an ancestor
+ * {@link ActionContextStoreSourceMap} under the provided key.
+ *
+ * When the key changes, the previous registration is removed and the new one is added.
+ * On destroy, the registration is cleaned up automatically.
+ *
+ * @example
+ * ```html
+ * <div dbxActionContextMap>
+ *   <div dbxAction [dbxActionMapSource]="'save'">
+ *     <button (click)="action.trigger()">Save</button>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @see {@link DbxActionContextMapDirective} for the parent map provider.
+ * @see {@link DbxActionFromMapDirective} for consuming registered actions by key.
  */
 class DbxActionMapSourceDirective {
     _actionContextStoreSourceMap = inject(ActionContextStoreSourceMap);
@@ -1294,9 +1695,15 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { key: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionMapSource", required: false }] }] } });
 
 /**
- * Creates a new ActionContextStoreSourceMapReader from the input.
- 
- * @param actionKeySourceMap$
+ * Creates a new {@link ActionContextStoreSourceMapReader} from the given action key source map.
+ *
+ * The reader provides reactive utility functions to aggregate data across all stores
+ * in the map (e.g., checking if any store is working, or reducing values from all stores).
+ *
+ * @typeParam T - The input value type for the actions.
+ * @typeParam O - The output result type for the actions.
+ * @param actionKeySourceMap$ - Observable (or static value) of the action key to source map.
+ * @returns A reader with aggregate query functions over the map's stores.
  */
 function actionContextStoreSourceMapReader(actionKeySourceMap$) {
     const sourceMap$ = asObservable(actionKeySourceMap$);
@@ -1327,9 +1734,33 @@ function fromAllActionContextStoreSourceMapSources(actionKeySourceMap$, mapFn) {
     return asObservable(actionKeySourceMap$).pipe(switchMap((x) => x.actionKeySourceMap$), switchMap(combineLatestFromMapValuesObsFn((x) => x.store$.pipe(switchMap(mapFn)))));
 }
 
+/**
+ * Default disabled key used by {@link DbxActionMapWorkingDisableDirective} to track
+ * the "another action is working" disabled reason.
+ */
 const DEFAULT_ACTION_MAP_WORKING_DISABLED_KEY = 'action_map_working_disable';
 /**
- * Used to communicate with an dbxActionMap and set the ActionContextStore to be disabled if any other element in the map is working.
+ * Directive that disables the host action when any other action in the ancestor
+ * {@link ActionContextStoreSourceMap} is currently working.
+ *
+ * This prevents concurrent action execution within a group of related actions.
+ * When all other actions finish working, the host action is automatically re-enabled.
+ *
+ * A custom disabled key can be provided via the `dbxActionMapWorkingDisable` input.
+ *
+ * @example
+ * ```html
+ * <div dbxActionContextMap>
+ *   <div dbxAction [dbxActionMapSource]="'save'" dbxActionMapWorkingDisable>
+ *     <button (click)="action.trigger()">Save</button>
+ *   </div>
+ *   <div dbxAction [dbxActionMapSource]="'delete'" dbxActionMapWorkingDisable>
+ *     <button (click)="action.trigger()">Delete</button>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @see {@link DbxActionContextMapDirective} for the parent map provider.
  */
 class DbxActionMapWorkingDisableDirective {
     _actionContextStoreSourceMap = inject(ActionContextStoreSourceMap);
@@ -1355,9 +1786,32 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }], ctorParameters: () => [], propDecorators: { disabledKey: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionMapWorkingDisable", required: false }] }] } });
 
+/**
+ * Disabled key used by {@link DbxActionDisabledDirective} to track its disabled state.
+ */
 const APP_ACTION_DISABLED_DIRECTIVE_KEY = 'dbx_action_disabled';
 /**
- * Directive that allows disabling an action using the inputs.
+ * Directive that disables or enables the parent action based on a boolean input.
+ *
+ * When `dbxActionDisabled` is `true` (or an empty string, which coerces to `true`),
+ * the action is disabled with the {@link APP_ACTION_DISABLED_DIRECTIVE_KEY}. When `false`,
+ * the disable key is removed, re-enabling the action (assuming no other sources have disabled it).
+ *
+ * The disable key is automatically cleaned up on directive destruction.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container [dbxActionDisabled]="isFormInvalid"></ng-container>
+ *   <button (click)="action.trigger()">Submit</button>
+ * </div>
+ * ```
+ *
+ * @typeParam T - The input value type.
+ * @typeParam O - The output result type.
+ *
+ * @see {@link DbxActionEnforceModifiedDirective} for disabling when not modified.
+ * @see {@link DbxActionDisabledOnSuccessDirective} for disabling after success.
  */
 class DbxActionDisabledDirective {
     source = inject((DbxActionContextStoreSourceInstance), { host: true });
@@ -1380,9 +1834,34 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }], ctorParameters: () => [], propDecorators: { disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionDisabled", required: false }] }] } });
 
+/**
+ * Disabled key used by {@link DbxActionDisabledOnSuccessDirective} to track the
+ * "disabled after success" reason.
+ */
 const APP_ACTION_DISABLED_ON_SUCCESS_DIRECTIVE_KEY = 'dbx_action_disabled_on_success';
 /**
- * Directive that will disable the action after the action completes successfully.
+ * Directive that disables the parent action after it resolves successfully.
+ *
+ * This is useful for one-shot actions where the user should not be able to re-trigger
+ * the action after it succeeds (e.g., a confirmation dialog or a single-use form submission).
+ *
+ * Can be disabled by setting `dbxActionDisabledOnSuccess` to `false`.
+ *
+ * The disable key is automatically cleaned up on directive destruction.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container dbxActionDisabledOnSuccess></ng-container>
+ *   <button (click)="action.trigger()">Confirm</button>
+ * </div>
+ * ```
+ *
+ * @typeParam T - The input value type.
+ * @typeParam O - The output result type.
+ *
+ * @see {@link DbxActionDisabledDirective} for general-purpose disabling.
+ * @see {@link DbxActionEnforceModifiedDirective} for disabling when not modified.
  */
 class DbxActionDisabledOnSuccessDirective {
     source = inject((DbxActionContextStoreSourceInstance), { host: true });
@@ -1405,9 +1884,31 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }], ctorParameters: () => [], propDecorators: { disabledOnSuccess: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionDisabledOnSuccess", required: false }] }] } });
 
+/**
+ * Lock key used by {@link DbxActionHandlerInstance} to prevent the source from being destroyed
+ * while a handler's work is still in progress.
+ */
 const DBX_ACTION_HANDLER_LOCK_KEY = 'dbxActionHandler';
 /**
- * Context used for defining a function that performs an action using the input function to handle valueReady$ events from an action context.
+ * Manages the execution of a {@link Work} function in response to `valueReady$` events
+ * from an action context.
+ *
+ * When initialized, it subscribes to the source's `valueReady$` stream and executes
+ * the configured handler function (or handler value) using {@link workFactory}. The handler
+ * function drives the action through the working/success/reject lifecycle via a
+ * {@link DbxActionWorkInstanceDelegate}.
+ *
+ * Supports two modes:
+ * - **Handler function**: A full {@link Work} function that receives the value and a work context.
+ * - **Handler value**: A simple getter or factory that returns the result directly.
+ *
+ * A lock is added to the source's lock set during work execution to prevent premature cleanup.
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionHandlerDirective} for the template directive that wraps this instance.
+ * @see {@link DbxActionWorkInstanceDelegate} for the delegate that bridges work events to the store.
  */
 class DbxActionHandlerInstance {
     _delegate;
@@ -1463,7 +1964,16 @@ class DbxActionHandlerInstance {
 }
 
 /**
- * Abstract directive that wraps and handles a DbxActionHandlerInstance lifecycle.
+ * Abstract base directive that creates and manages a {@link DbxActionHandlerInstance} lifecycle.
+ *
+ * Subclasses configure how the handler function or value is provided to the instance.
+ * The instance is initialized on construction and cleaned up automatically via the action's lock set.
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionHandlerDirective} for the work-function variant.
+ * @see {@link DbxActionHandlerValueDirective} for the value/getter variant.
  */
 class AbstractDbxActionHandlerDirective {
     source = inject((DbxActionContextStoreSourceInstance), { host: true });
@@ -1478,7 +1988,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
             type: Directive
         }], ctorParameters: () => [] });
 /**
- * Directive that passes a Work function to handle a valueReady$ event from an action context.
+ * Directive that provides a {@link Work} function to handle the action's `valueReady$` event.
+ *
+ * When the action is triggered and a value becomes ready, the provided work function is
+ * called with the value and a work context. The work function is responsible for performing
+ * the async operation and signaling success or failure through the context.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container [dbxActionHandler]="handleSave"></ng-container>
+ *   <button (click)="action.trigger()">Save</button>
+ * </div>
+ * ```
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionHandlerValueDirective} for the simpler value/getter variant.
  */
 class DbxActionHandlerDirective extends AbstractDbxActionHandlerDirective {
     handlerFunction = input.required({ ...(ngDevMode ? { debugName: "handlerFunction" } : {}), alias: 'dbxActionHandler' });
@@ -1496,7 +2023,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }], propDecorators: { handlerFunction: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionHandler", required: true }] }] } });
 /**
- * Directive that passes a value to handle a valueReady$ event from an action context.
+ * Directive that provides a static value, getter, or factory to resolve the action's `valueReady$` event.
+ *
+ * Unlike {@link DbxActionHandlerDirective}, this does not require a full {@link Work} function.
+ * The provided value (or the result of calling the getter/factory) is used directly as the
+ * action's result, with the working/success lifecycle handled automatically.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container [dbxActionHandlerValue]="computeResult"></ng-container>
+ *   <button (click)="action.trigger()">Compute</button>
+ * </div>
+ * ```
+ *
+ * @typeParam T - The input value type for the action.
+ * @typeParam O - The output result type for the action.
+ *
+ * @see {@link DbxActionHandlerDirective} for the full work-function variant.
  */
 class DbxActionHandlerValueDirective extends AbstractDbxActionHandlerDirective {
     handlerValue = input.required({ ...(ngDevMode ? { debugName: "handlerValue" } : {}), alias: 'dbxActionHandlerValue' });
@@ -1515,7 +2059,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { handlerValue: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionHandlerValue", required: true }] }] } });
 
 /**
- * Abstract directive class that watches a show$ observable and behaves like *ngIf.
+ * Abstract structural directive that conditionally renders its template based on a reactive boolean observable,
+ * similar to `*ngIf` but driven by an `Observable<boolean>`.
+ *
+ * Subclasses provide the `show$` observable to control visibility. The template is created
+ * when `show$` emits `true` and cleared when it emits `false`.
+ *
+ * @example
+ * ```typescript
+ * @Directive({ selector: '[appShowIfAdmin]' })
+ * export class ShowIfAdminDirective extends AbstractIfDirective {
+ *   readonly show$ = inject(AuthService).isAdmin$;
+ * }
+ * ```
+ *
+ * @example
+ * ```html
+ * <div *appShowIfAdmin>Only visible to admins</div>
+ * ```
  */
 class AbstractIfDirective {
     _templateRef = inject(TemplateRef);
@@ -1539,16 +2100,46 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Transforms an empty string to undefined.
+ * Angular input transform that converts an empty string to `undefined`.
  *
- * Used for Angular inputs that are optional and share the same alias as the directive.
+ * Useful for Angular directive inputs where the attribute can be applied without a value
+ * (e.g., `<div myDirective>` passes `''`), and you want to treat that as "not provided".
+ *
+ * @example
+ * ```typescript
+ * @Directive({ selector: '[appHighlight]' })
+ * export class HighlightDirective {
+ *   @Input({ alias: 'appHighlight', transform: transformEmptyStringInputToUndefined })
+ *   color?: string;
+ * }
+ * ```
  */
 const transformEmptyStringInputToUndefined = (value) => (value === '' ? undefined : value);
 
 /**
- * Structural directive that displays the content before the store has success.
+ * Structural directive that conditionally renders its content when the action is idle.
  *
- * Can be configured to hide for a temporary period.
+ * Optionally accepts a number (in milliseconds) to auto-hide the content after the specified
+ * duration, even if the action is still idle. Useful for showing initial instructions that
+ * should disappear after a timeout.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <div *dbxActionIdle>Ready to submit.</div>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Hide idle content after 5 seconds -->
+ * <div dbxAction>
+ *   <div *dbxActionIdle="5000">Ready to submit.</div>
+ * </div>
+ * ```
+ *
+ * @see {@link DbxActionIsWorkingDirective} for showing content when working.
+ * @see {@link DbxActionHasSuccessDirective} for showing content on success.
  */
 class DbxActionIdleDirective extends AbstractIfDirective {
     _store = inject(DbxActionContextStoreSourceInstance);
@@ -1573,9 +2164,30 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { hideAfter: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionIdle", required: false }] }] } });
 
 /**
- * Structural directive that displays the content before the store has success.
+ * Structural directive that renders its content while the action has not yet succeeded.
+ *
+ * The content is visible during all states before success (IDLE, TRIGGERED, WORKING, etc.)
+ * and is hidden once the action resolves successfully. Optionally accepts a number (in milliseconds)
+ * specifying how long to keep the content hidden after success before showing it again.
  *
- * Can be configured to hide for a temporary period.
+ * This is the inverse of {@link DbxActionHasSuccessDirective}.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <div *dbxActionPreSuccess>Not yet saved.</div>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Re-show content 2 seconds after success -->
+ * <div dbxAction>
+ *   <div *dbxActionPreSuccess="2000">Not yet saved.</div>
+ * </div>
+ * ```
+ *
+ * @see {@link DbxActionHasSuccessDirective} for showing content on success.
  */
 class DbxActionPreSuccessDirective extends AbstractIfDirective {
     _store = inject(DbxActionContextStoreSourceInstance);
@@ -1600,9 +2212,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { hideFor: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionPreSuccess", required: false }] }] } });
 
 /**
- * Structural directive that displays the content when the store has a success value.
+ * Structural directive that conditionally renders its content when the action has resolved successfully.
+ *
+ * Optionally accepts a number (in milliseconds) to auto-hide the content after the specified
+ * duration, useful for showing temporary success messages that fade away.
  *
- * Can be configured to show for a temporary period.
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <div *dbxActionHasSuccess>Saved successfully!</div>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Show success message for 3 seconds -->
+ * <div dbxAction>
+ *   <div *dbxActionHasSuccess="3000">Saved!</div>
+ * </div>
+ * ```
+ *
+ * @see {@link DbxActionPreSuccessDirective} for showing content before success.
+ * @see {@link DbxActionSuccessHandlerDirective} for executing a function on success.
  */
 class DbxActionHasSuccessDirective extends AbstractIfDirective {
     _store = inject(DbxActionContextStoreSourceInstance);
@@ -1627,7 +2258,25 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { hideAfter: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionHasSuccess", required: false }] }] } });
 
 /**
- * Directive that executes a function on ActionContextStore Success.
+ * Directive that executes a callback function each time the action resolves successfully.
+ *
+ * The provided function receives the action's result value. This is useful for
+ * performing side effects like navigation, showing notifications, or refreshing data
+ * after a successful action.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container [dbxActionSuccessHandler]="onSaveSuccess"></ng-container>
+ *   <button (click)="action.trigger()">Save</button>
+ * </div>
+ * ```
+ *
+ * @typeParam T - The input value type.
+ * @typeParam O - The output result type.
+ *
+ * @see {@link DbxActionHasSuccessDirective} for rendering content on success.
+ * @see {@link DbxActionErrorHandlerDirective} for handling errors.
  */
 class DbxActionSuccessHandlerDirective {
     source = inject((DbxActionContextStoreSourceInstance), { host: true });
@@ -1655,7 +2304,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [], propDecorators: { dbxActionSuccessHandler: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionSuccessHandler", required: false }] }] } });
 
 /**
- * Directive that executes a function on ActionContextStore error.
+ * Directive that executes a callback function each time the action's error state changes.
+ *
+ * The provided function receives the {@link ReadableError} from the action context.
+ * This is useful for performing side effects like logging, showing error toasts, or
+ * handling specific error conditions programmatically.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container [dbxActionErrorHandler]="onError"></ng-container>
+ *   <button (click)="action.trigger()">Submit</button>
+ * </div>
+ * ```
+ *
+ * @typeParam T - The input value type.
+ * @typeParam O - The output result type.
+ *
+ * @see {@link DbxActionSuccessHandlerDirective} for handling success.
  */
 class DbxActionErrorHandlerDirective {
     source = inject((DbxActionContextStoreSourceInstance), { host: true });
@@ -1683,13 +2349,37 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [], propDecorators: { dbxActionErrorHandler: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionErrorHandler", required: false }] }] } });
 
 /**
- * Directive that provides a default value when triggered.
+ * Directive that provides a value (or value-producing function) to the action when triggered.
+ *
+ * The value is always available and ready to be used. When the action is triggered,
+ * the current value is resolved (via `getValueFromGetter` if a function) and passed
+ * to `readyValue()` on the action source.
+ *
+ * The input filters out null/undefined values, waiting until a non-null value is provided.
+ * If you need to pass null/undefined as valid action values, use {@link DbxActionValueTriggerDirective} instead.
  *
- * No value is required, allowing the directive to automatically call readyValue.
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container [dbxActionValue]="myValue"></ng-container>
+ *   <button (click)="action.trigger()">Submit</button>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- With a getter function -->
+ * <div dbxAction>
+ *   <ng-container [dbxActionValue]="getLatestValue"></ng-container>
+ *   <button (click)="action.trigger()">Submit</button>
+ * </div>
+ * ```
  *
- * The valueOrFunction will filter on null/undefined input and wait until the input value is non-null.
+ * @typeParam T - The input value type.
+ * @typeParam O - The output result type.
  *
- * Use a getter if null/undefined values should be passed to the action.
+ * @see {@link DbxActionValueTriggerDirective} for lazy value retrieval on trigger.
+ * @see {@link DbxActionValueStreamDirective} for reactive stream-based values.
  */
 class DbxActionValueDirective {
     valueOrFunction = input('', { ...(ngDevMode ? { debugName: "valueOrFunction" } : {}), alias: 'dbxActionValue' });
@@ -1720,9 +2410,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [], propDecorators: { valueOrFunction: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionValue", required: false }] }] } });
 
 /**
- * Structural directive that displays the content when the store is working.
+ * Structural directive that conditionally renders its content while the action is in a working state.
+ *
+ * Optionally accepts a number (in milliseconds) to auto-hide the content after a specified duration,
+ * even if the action is still working. This is useful for showing brief "loading" indicators
+ * that should disappear after a timeout.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <div *dbxActionWorking>Loading...</div>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Hide after 3 seconds even if still working -->
+ * <div dbxAction>
+ *   <div *dbxActionIsWorking="3000">Loading...</div>
+ * </div>
+ * ```
  *
- * Can specify a period in milliseconds that shows how long to show up after working for a particular number of seconds.
+ * @see {@link DbxActionIdleDirective} for showing content when idle.
  */
 class DbxActionIsWorkingDirective extends AbstractIfDirective {
     _store = inject(DbxActionContextStoreSourceInstance);
@@ -1753,17 +2462,40 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }], propDecorators: { hideAfter: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionWorking", required: false }] }], hideAfterIsWorking: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionIsWorking", required: false }] }] } });
 
-const APP_ACTION_ENFORCE_MODIFIED_DIRECTIVE_KEY = 'dbx_action_enforce_modified';
 /**
- * Directive that toggles disabling an action if the action is not marked modified.
+ * Disabled key used by {@link DbxActionEnforceModifiedDirective} to track the
+ * "not modified" disabled reason.
  */
-class DbxActionEnforceModifiedDirective {
-    source = inject(DbxActionContextStoreSourceInstance, { host: true });
-    enabled = input(true, { ...(ngDevMode ? { debugName: "enabled" } : {}), alias: 'dbxActionEnforceModified', transform: (value) => value !== false });
-    enabled$ = toObservable(this.enabled);
-    constructor() {
-        cleanSubscription(combineLatest([this.source.isModified$, this.enabled$])
-            .pipe(delay(0))
+const APP_ACTION_ENFORCE_MODIFIED_DIRECTIVE_KEY = 'dbx_action_enforce_modified';
+/**
+ * Directive that disables the parent action when the action is not marked as modified.
+ *
+ * When enabled (default), this enforces that the user must make changes before the action
+ * can be triggered. Once the action is marked as modified, the disabled key is removed.
+ * This prevents no-op submissions where nothing has actually changed.
+ *
+ * Can be disabled by setting `dbxActionEnforceModified` to `false`.
+ *
+ * The disable key is automatically cleaned up on directive destruction.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container dbxActionEnforceModified></ng-container>
+ *   <button (click)="action.trigger()">Save</button>
+ * </div>
+ * ```
+ *
+ * @see {@link DbxActionDisabledDirective} for general-purpose disabling.
+ * @see {@link DbxActionAutoModifyDirective} for always keeping the action modified.
+ */
+class DbxActionEnforceModifiedDirective {
+    source = inject(DbxActionContextStoreSourceInstance, { host: true });
+    enabled = input(true, { ...(ngDevMode ? { debugName: "enabled" } : {}), alias: 'dbxActionEnforceModified', transform: (value) => value !== false });
+    enabled$ = toObservable(this.enabled);
+    constructor() {
+        cleanSubscription(combineLatest([this.source.isModified$, this.enabled$])
+            .pipe(delay(0))
             .subscribe(([modified, enableDirective]) => {
             const disable = enableDirective && !modified;
             this.source.disable(APP_ACTION_ENFORCE_MODIFIED_DIRECTIVE_KEY, disable);
@@ -1782,7 +2514,19 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [], propDecorators: { enabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionEnforceModified", required: false }] }] } });
 
 /**
- * Utility class that handles trigger events to retrieve a value.
+ * Utility class that handles the trigger-to-value-ready phase of the action lifecycle.
+ *
+ * When initialized, it subscribes to the source's `triggered$` stream. On each trigger,
+ * it calls the configured {@link DbxActionValueGetterValueGetterFunction} to retrieve the value,
+ * runs an optional {@link IsModifiedFunction} check, and either calls `readyValue()` with
+ * the retrieved value or `reject()` if the value is null/undefined or an error occurred.
+ *
+ * This separates value retrieval from the trigger event, allowing lazy or async value computation.
+ *
+ * @typeParam T - The value type for the action.
+ *
+ * @see {@link DbxActionValueTriggerDirective} for the directive wrapper.
+ * @see {@link DbxActionValueDirective} for the simpler always-piped-value approach.
  */
 class DbxActionValueGetterInstance {
     _valueGetterFunction = new BehaviorSubject(undefined);
@@ -1838,7 +2582,14 @@ class DbxActionValueGetterInstance {
 }
 
 /**
- * Abstract class for directives that may perform an action when trigger is called, and returns a value.
+ * Abstract base class for directives that retrieve a value when the action is triggered.
+ *
+ * Creates and manages a {@link DbxActionValueGetterInstance} internally, providing
+ * methods for subclasses to configure the value getter, isModified, and isEqual functions.
+ *
+ * @typeParam T - The value type for the action.
+ *
+ * @see {@link DbxActionValueTriggerDirective} for the concrete implementation.
  */
 class AbstractDbxActionValueGetterDirective {
     _injector = inject(Injector);
@@ -1878,10 +2629,27 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
             type: Directive
         }], ctorParameters: () => [] });
 /**
- * Action directive that uses a getter function instead and waits for the trigger to be called before calling the function.
+ * Directive that uses a getter function to retrieve the action value only when triggered.
  *
- * Similar to DbxActionValueDirective, but the getter is called when a trigger is activated.
- * The DbxActionValueDirective always pipes the latests value while waiting for a trigger, and does not allow using a getter.
+ * Unlike {@link DbxActionValueDirective} which continuously pipes the latest value,
+ * this directive calls the getter function lazily -- only when the action is triggered.
+ * This is useful when the value computation is expensive or depends on state that should
+ * only be captured at trigger time.
+ *
+ * Supports optional `isModified` and `isEqual` functions to control whether the retrieved
+ * value should proceed to `readyValue` or be rejected.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container [dbxActionValueGetter]="getFormValue"></ng-container>
+ *   <button (click)="action.trigger()">Submit</button>
+ * </div>
+ * ```
+ *
+ * @typeParam T - The value type for the action.
+ *
+ * @see {@link DbxActionValueDirective} for the always-available value approach.
  */
 class DbxActionValueTriggerDirective extends AbstractDbxActionValueGetterDirective {
     dbxActionValueGetter = input(...(ngDevMode ? [undefined, { debugName: "dbxActionValueGetter" }] : []));
@@ -1908,7 +2676,29 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [], propDecorators: { dbxActionValueGetter: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionValueGetter", required: false }] }], dbxActionValueGetterIsModified: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionValueGetterIsModified", required: false }] }], dbxActionValueGetterIsEqual: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionValueGetterIsEqual", required: false }] }] } });
 
 /**
- * Directive that watches a value observable for changes and sets the new value and modified states as necessary.
+ * Directive that watches a value observable stream and automatically updates the action's
+ * modified state and provides the latest value when triggered.
+ *
+ * Each emission from the stream is checked against an optional `isModified` or `isEqual`
+ * function to determine if the action should be marked as modified. When the action is
+ * triggered, the latest value from the stream is passed to `readyValue()` only if modified.
+ *
+ * This is ideal for form-based workflows where the form value changes over time and
+ * should automatically track modification state.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <ng-container [dbxActionValueStream]="formValue$"></ng-container>
+ *   <button (click)="action.trigger()">Save</button>
+ * </div>
+ * ```
+ *
+ * @typeParam T - The input value type.
+ * @typeParam O - The output result type.
+ *
+ * @see {@link DbxActionValueDirective} for static/getter-based values.
+ * @see {@link DbxActionValueTriggerDirective} for lazy getter values on trigger.
  */
 class DbxActionValueStreamDirective {
     source = inject((DbxActionContextStoreSourceInstance), { host: true });
@@ -1960,9 +2750,19 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [], propDecorators: { dbxActionValueStream: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionValueStream", required: false }] }], dbxActionValueStreamIsEqualValue: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionValueStreamIsEqualValue", required: false }] }], dbxActionValueStreamIsModifiedValue: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxActionValueStreamIsModifiedValue", required: false }] }] } });
 
 /**
- * Structural directive that displays the content when the store has been triggered.
+ * Structural directive that conditionally renders its content when the action has been triggered.
+ *
+ * Shows content during the TRIGGERED state (after trigger, before value-ready/working).
+ * Optionally accepts a number (in milliseconds) to auto-hide the content after the specified duration.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <div *dbxActionTriggered>Preparing...</div>
+ * </div>
+ * ```
  *
- * Can be configured to hide for a temporary period.
+ * @see {@link DbxActionIsWorkingDirective} for content shown during the working state.
  */
 class DbxActionTriggeredDirective extends AbstractIfDirective {
     _store = inject(DbxActionContextStoreSourceInstance);
@@ -2068,6 +2868,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Creates a simple {@link DbxActionContextSourceReference} wrapper around a source instance.
+ *
+ * The returned reference has a no-op `destroy()` method, making it suitable for cases
+ * where the caller does not own the lifecycle of the source instance.
+ *
+ * @typeParam T - The input value type.
+ * @typeParam O - The output result type.
+ * @param sourceInstance - The source instance to wrap.
+ * @returns A destroyable reference to the source instance.
+ */
 function makeDbxActionContextSourceReference(sourceInstance) {
     return {
         sourceInstance,
@@ -2075,6 +2886,15 @@ function makeDbxActionContextSourceReference(sourceInstance) {
     };
 }
 
+/**
+ * Type guard that checks whether the given input is a {@link SegueRef} object (as opposed to a raw router link string).
+ *
+ * @typeParam O - The type of the transition options.
+ * @param input - The value to test.
+ * @returns `true` if the input is a {@link SegueRef} with a non-empty `ref` property.
+ *
+ * @see {@link asSegueRef} for converting an input to a SegueRef
+ */
 function isSegueRef(input) {
     return typeof input === 'object' && hasValueOrNotEmpty(input.ref);
 }
@@ -2101,21 +2921,77 @@ function asSegueRefString(input) {
         throw new Error(`asSegueRefString() failed to convert the input to a string: ${input}`);
     }
 }
+/**
+ * Creates a {@link SegueRef} from a string ref path and optional segue options.
+ *
+ * @typeParam O - The type of the transition options.
+ * @param ref - The string ref path to wrap.
+ * @param options - Optional parameters and transition options to include.
+ * @returns A new {@link SegueRef} containing the given ref and options.
+ */
 function refStringToSegueRef(ref, options) {
     return { ...options, ref };
 }
+/**
+ * Maps an observable of string ref paths to an observable of {@link SegueRef} objects.
+ *
+ * @typeParam O - The type of the transition options.
+ * @param obs - The source observable emitting string ref paths.
+ * @param options - Optional parameters and transition options to include in each emitted SegueRef.
+ * @returns An observable that emits {@link SegueRef} objects.
+ *
+ * @see {@link refStringToSegueRef}
+ */
 function mapRefStringObsToSegueRefObs(obs, options) {
     return obs.pipe(map((x) => refStringToSegueRef(x, options)));
 }
 
 /**
- * Client auth service used to retrieve info about the current state of client authentication and client roles they may have.
+ * Abstract service that provides reactive access to the current authentication state, user roles, and lifecycle events.
+ *
+ * This is the primary abstraction for authentication in dbx-core. Concrete implementations
+ * (e.g., Firebase-based auth) must provide all observable streams and the logout behavior.
+ *
+ * Components and services should inject this abstract class rather than a concrete implementation,
+ * enabling the auth provider to be swapped without changing consumer code.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class MyComponent {
+ *   private readonly authService = inject(DbxAuthService);
+ *
+ *   readonly isLoggedIn$ = this.authService.isLoggedIn$;
+ *   readonly roles$ = this.authService.authRoles$;
+ *
+ *   logout() {
+ *     this.authService.logOut();
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link AuthUserState} for the possible user states.
+ * @see {@link DbxAppAuthEffects} for how this service is bridged into the NgRx store.
  */
 class DbxAuthService {
 }
 
 /**
- * This generates a TransitionHookFn that can be used with redirecting routes.
+ * Creates a UIRouter `TransitionHookFn` that performs auth-based route guarding.
+ *
+ * The generated hook evaluates the `makeDecisionsObs` observable for each transition:
+ * - If it emits `true`, the transition proceeds normally.
+ * - If it emits `false`, the user is redirected to the default target or a custom redirect
+ *   specified in the state's `data.redirectTo` property.
+ * - If it emits a route reference, the user is redirected to that specific route.
+ * - If the observable does not emit within the configured timeout, the transition is rejected.
+ *
+ * @param config - The hook configuration including redirect targets and the decision observable factory.
+ * @returns A `TransitionHookFn` suitable for registration with UIRouter's `TransitionService`.
+ *
+ * @see {@link enableIsLoggedInHook} for a login-based usage.
+ * @see {@link enableHasAuthRoleHook} for a role-based usage.
+ * @see {@link enableHasAuthStateHook} for a state-based usage.
  */
 function makeAuthTransitionHook(config) {
     const { defaultRedirectTarget, errorRedirectTarget = defaultRedirectTarget, timeoutTime = 1000 } = config;
@@ -2181,10 +3057,31 @@ function makeAuthTransitionHook(config) {
 }
 
 /**
- * Creates a AuthTransitionRedirectTargetGetter that can redirect values based on the current authUserState.
+ * Creates an {@link AuthTransitionRedirectTargetGetter} that dynamically determines the redirect
+ * destination based on the current {@link AuthUserState}.
  *
- * @param stateMap
- * @returns
+ * This is useful when different auth states should redirect to different routes. For example,
+ * a `'new'` user might be redirected to an onboarding page while an `'anon'` user is sent to login.
+ *
+ * Each value in the `stateMap` can be either a static route reference or a dynamic getter
+ * for more complex redirect logic.
+ *
+ * @param stateMap - An object map where keys are {@link AuthUserState} values and values are
+ *   redirect targets (static or dynamic) for that state.
+ * @returns An {@link AuthTransitionRedirectTargetGetter} that resolves the redirect based on the current auth state.
+ *
+ * @example
+ * ```ts
+ * const redirectGetter = redirectBasedOnAuthUserState({
+ *   'none': '/auth/login',
+ *   'anon': '/auth/login',
+ *   'new': '/onboard',
+ *   'user': '/app'
+ * });
+ * ```
+ *
+ * @see {@link AuthTransitionRedirectTargetOrGetter}
+ * @see {@link AuthUserState}
  */
 function redirectBasedOnAuthUserState(stateMap) {
     return (input) => {
@@ -2208,7 +3105,18 @@ function redirectBasedOnAuthUserState(stateMap) {
 }
 
 /**
- * This hook redirects to the configured default state when a user is not logged in for configured states.
+ * Registers a UIRouter transition hook that redirects unauthenticated users away from
+ * states that require login.
+ *
+ * The hook fires on `onBefore` (priority 100) for any state whose `data` property has
+ * `requiredLogIn: true`. If the user is not logged in (as determined by {@link DbxAuthService.isLoggedIn$}),
+ * they are redirected to the configured `defaultRedirectTarget`.
+ *
+ * @param transitionService - The UIRouter `TransitionService` to register the hook with.
+ * @param config - Configuration including redirect targets and timeout settings.
+ *
+ * @see {@link IsLoggedInStateData} for marking states as requiring login.
+ * @see {@link makeAuthTransitionHook} for the underlying hook factory.
  */
 function enableIsLoggedInHook(transitionService, config) {
     // Matches if the destination state's data property has a truthy 'isSecure' property
@@ -2230,10 +3138,19 @@ function enableIsLoggedInHook(transitionService, config) {
 }
 
 /**
- * This hook redirects to the configured default state when a user:
+ * Registers a UIRouter transition hook that redirects users who lack the required auth roles
+ * away from protected states.
+ *
+ * The hook fires on `onBefore` (priority 100) for any state whose `data` property has an
+ * `authRoles` value. If the user's current roles do not satisfy the requirement
+ * (based on the configured `authRolesMode`), they are redirected.
  *
- * - does not have an allowed state
- * - has a disallowed state
+ * @param transitionService - The UIRouter `TransitionService` to register the hook with.
+ * @param config - Configuration including redirect targets and timeout settings.
+ *
+ * @see {@link HasAuthRoleStateData} for marking states with required roles.
+ * @see {@link hasAuthRoleDecisionPipe} for the role evaluation logic.
+ * @see {@link makeAuthTransitionHook} for the underlying hook factory.
  */
 function enableHasAuthRoleHook(transitionService, config) {
     // Matches if the destination state's data property has a truthy 'isSecure' property
@@ -2256,6 +3173,18 @@ function enableHasAuthRoleHook(transitionService, config) {
     // Register the "requires auth" hook with the TransitionsService
     transitionService.onBefore(isSecureCriteria, assertHasAuthRole, { priority: 100 });
 }
+/**
+ * Creates an RxJS operator that evaluates whether the user's {@link AuthRoleSet} satisfies
+ * the role requirements defined in the given {@link HasAuthRoleStateData}.
+ *
+ * The operator processes role configurations and applies the specified `authRolesMode`
+ * (`'all'` or `'any'`) to determine if the user has sufficient roles.
+ *
+ * @param stateData - The role configuration from the UIRouter state's `data` property.
+ * @returns An `OperatorFunction` that transforms an `AuthRoleSet` stream into a `boolean` stream.
+ *
+ * @see {@link enableHasAuthRoleHook} for where this is used in transition hooks.
+ */
 function hasAuthRoleDecisionPipe(stateData) {
     const authRolesMode = stateData.authRolesMode || 'all';
     const authRoleConfigs = asArray(stateData.authRoles).map((x) => {
@@ -2285,10 +3214,18 @@ function hasAuthRoleDecisionPipe(stateData) {
 }
 
 /**
- * This hook redirects to the configured default state when a user:
+ * Registers a UIRouter transition hook that redirects users whose {@link AuthUserState} does not
+ * satisfy the state's requirements.
  *
- * - does not have an allowed state
- * - has a disallowed state
+ * The hook fires on `onBefore` (priority 100) for any state whose `data` property has an
+ * `authStates` value. It supports both allow-lists and deny-lists of auth user states.
+ *
+ * @param transitionService - The UIRouter `TransitionService` to register the hook with.
+ * @param config - Configuration including redirect targets and timeout settings.
+ *
+ * @see {@link HasAuthStateData} for marking states with required auth states.
+ * @see {@link HasAuthStateObjectConfig} for detailed allowed/disallowed configuration.
+ * @see {@link makeAuthTransitionHook} for the underlying hook factory.
  */
 function enableHasAuthStateHook(transitionService, config) {
     // Matches if the destination state's data property has a truthy 'isSecure' property
@@ -2450,27 +3387,61 @@ class AbstractOnDbxAppContextStateEffects {
     }
 }
 
+/**
+ * Sentinel value representing an unauthenticated or unidentifiable user.
+ *
+ * Used as a fallback when no valid {@link AuthUserIdentifier} is available.
+ */
 const NO_AUTH_USER_IDENTIFIER = '0';
 /**
- * Creates an AuthUserIdentifier from the input. If the input is undefined, returns the NoAuthUserIdentifier.
+ * Normalizes an optional user identifier into a guaranteed {@link AuthUserIdentifier}.
  *
- * @param inputId
- * @returns
+ * If the input is `undefined` or falsy, returns {@link NO_AUTH_USER_IDENTIFIER} as a safe default.
+ * This ensures downstream consumers always receive a non-null identifier value.
+ *
+ * @param inputId - The user identifier to normalize, or `undefined`/`null`.
+ * @returns The input identifier if truthy, otherwise {@link NO_AUTH_USER_IDENTIFIER}.
+ *
+ * @example
+ * ```ts
+ * authUserIdentifier('abc123'); // 'abc123'
+ * authUserIdentifier(undefined); // '0'
+ * ```
  */
 function authUserIdentifier(inputId) {
     return inputId ? inputId : NO_AUTH_USER_IDENTIFIER;
 }
 
 /**
- * Action for when the user has logged in.
+ * NgRx action dispatched when the user has successfully logged in.
+ *
+ * This is an event action (past tense) triggered by {@link DbxAppAuthEffects} in response
+ * to the {@link DbxAuthService.onLogIn$} observable. It signals that authentication has been
+ * established and downstream effects (e.g., navigation to the app) can proceed.
+ *
+ * @see {@link loggedOut} for the corresponding logout event.
+ * @see {@link DbxAppAuthEffects.emitLoggedIn}
  */
 const loggedIn = createAction('[App/Auth] Auth Logged In');
 /**
- * Action for when the user has logged out.
+ * NgRx action dispatched when the user has logged out.
+ *
+ * This is an event action (past tense) triggered by {@link DbxAppAuthEffects} in response
+ * to the {@link DbxAuthService.onLogOut$} observable. When dispatched, the user reducer
+ * resets the auth state to its initial values (no user, no roles, not onboarded).
+ *
+ * @see {@link loggedIn} for the corresponding login event.
+ * @see {@link logout} for the imperative command action to initiate logout.
  */
 const loggedOut = createAction('[App/Auth] Auth Logged Out');
 /**
- * Action to log the user out.
+ * NgRx action that commands the application to perform a logout.
+ *
+ * This is a command action (imperative) that, when dispatched, triggers {@link DbxAppAuthEffects.forwardLogoutToAuthService}
+ * to call {@link DbxAuthService.logOut}. Use this action to initiate logout from anywhere in the application
+ * via the NgRx store rather than calling the auth service directly.
+ *
+ * @see {@link loggedOut} for the event action dispatched after logout completes.
  */
 const logout = createAction('[App/Auth] Auth Logout');
 
@@ -2482,19 +3453,42 @@ var auth_action = /*#__PURE__*/Object.freeze({
 });
 
 /**
- * Sets the user's identifier in the auth.
+ * NgRx action that updates the authenticated user's identifier in the store.
+ *
+ * Dispatched by {@link DbxAppAuthEffects.setUserIdentifier} whenever the
+ * {@link DbxAuthService.userIdentifier$} emits a new value.
+ *
+ * @see {@link DbxAppAuthStateUser.userId}
  */
 const setUserIdentifier = createAction('[App/Auth] Set User Identifier', props());
 /**
- * Sets the user's state in the auth.
+ * NgRx action that updates the authenticated user's {@link AuthUserState} in the store.
+ *
+ * Dispatched by {@link DbxAppAuthEffects.setUserState} whenever the
+ * {@link DbxAuthService.authUserState$} emits a new value. The state determines
+ * the user's lifecycle stage (none, anon, new, user, or error).
+ *
+ * @see {@link AuthUserState}
+ * @see {@link DbxAppAuthStateUser.userState}
  */
 const setUserState = createAction('[App/Auth] Set User State', props());
 /**
- * Sets the user's roles in the auth.
+ * NgRx action that updates the authenticated user's auth roles in the store.
+ *
+ * Dispatched by {@link DbxAppAuthEffects.setUserRoles} whenever the
+ * {@link DbxAuthService.authRoles$} emits a new role set. Roles are stored
+ * as an array in the NgRx state.
+ *
+ * @see {@link DbxAppAuthStateUser.userRoles}
  */
 const setUserRoles = createAction('[App/Auth] Set User Roles', props());
 /**
- * Sets the user's onboarding state.
+ * NgRx action that updates the authenticated user's onboarding status in the store.
+ *
+ * Dispatched by {@link DbxAppAuthEffects.setUserIsOnboarded} whenever the
+ * {@link DbxAuthService.isOnboarded$} emits a new value.
+ *
+ * @see {@link DbxAppAuthStateUser.isOnboarded}
  */
 const setUserIsOnboarded = createAction('[App/Auth] Set User Is Onboarded', props());
 
@@ -2512,7 +3506,16 @@ var index$1 = /*#__PURE__*/Object.freeze({
     DbxAppAuthUserActions: user_action
 });
 
+/**
+ * NgRx feature key for the auth user sub-state within the auth feature.
+ */
 const dbxAppAuthUserFeatureKey = 'user';
+/**
+ * Initial state for the auth user reducer.
+ *
+ * Represents a fully unauthenticated state: no user identifier, not onboarded,
+ * in the `'none'` auth state, with no roles assigned.
+ */
 const initialState = {
     userId: NO_AUTH_USER_IDENTIFIER,
     isOnboarded: false,
@@ -2522,11 +3525,20 @@ const initialState = {
 const reducer = createReducer(initialState, on(loggedOut, () => ({ ...initialState })), on(setUserIdentifier, (state, { id: userId }) => ({ ...state, userId })), on(setUserIsOnboarded, (state, { isOnboarded }) => ({ ...state, isOnboarded })), on(setUserState, (state, { state: userState }) => ({ ...state, userState })), on(setUserRoles, (state, { roles: userRoles }) => ({ ...state, userRoles: Array.from(userRoles) })));
 
 /**
- * Global feature key
+ * NgRx feature key used to register the auth feature state in the global store.
+ *
+ * The auth state is registered under `'app.auth'` in the root NgRx state tree.
  */
 const featureKey = 'app.auth';
 /**
- * Reducers mapping for the DbxAppAuthFeatureState
+ * Combined reducer function for the auth feature state.
+ *
+ * Merges all auth sub-reducers (currently just the user reducer) using NgRx's `combineReducers`.
+ * This function is registered with `provideState` via {@link provideDbxAppAuthState}.
+ *
+ * @param state - The current auth feature state, or `undefined` for initialization.
+ * @param action - The dispatched NgRx action.
+ * @returns The updated {@link DbxAppAuthFeatureState}.
  */
 function reducers(state, action) {
     return combineReducers({
@@ -2534,11 +3546,15 @@ function reducers(state, action) {
     })(state, action);
 }
 /**
- * Selects the DbxAppAuthFeatureState feature context.
+ * NgRx feature selector that retrieves the entire {@link DbxAppAuthFeatureState} from the global store.
  */
 const selectAppAuthFeature = createFeatureSelector(featureKey);
 /**
- * Selector to retrieve the state value from our DbxAppContextStateData in our DbxAppContextFeatureState.
+ * NgRx selector that retrieves the {@link DbxAppAuthStateUser} from the auth feature state.
+ *
+ * Provides access to the user's identifier, auth state, roles, and onboarding status.
+ *
+ * @see {@link DbxAppAuthStateService.authStateUser$} for the observable wrapper.
  */
 const selectDbxAppAuthUser = createSelector(selectAppAuthFeature, (featureState) => featureState[dbxAppAuthUserFeatureKey]);
 
@@ -2551,10 +3567,21 @@ var index = /*#__PURE__*/Object.freeze({
 });
 
 /**
- * Creates a GoWithRouter function.
+ * Creates a navigation function bound to the given {@link DbxRouterService}.
  *
- * @param dbxRouterService
- * @returns
+ * The returned function accepts either a {@link SegueRef}, a router link string, or an observable of either,
+ * resolves it to a single value, and calls `go()` on the router service.
+ *
+ * @param dbxRouterService - The router service to use for navigation.
+ * @returns A function that navigates to the given route and returns a promise resolving to the navigation result.
+ *
+ * @example
+ * ```ts
+ * const navigate = goWithRouter(routerService);
+ * await navigate({ ref: 'app.dashboard' });
+ * ```
+ *
+ * @see {@link GoWithRouter}
  */
 function goWithRouter(dbxRouterService) {
     return (route) => {
@@ -2563,30 +3590,109 @@ function goWithRouter(dbxRouterService) {
 }
 
 /**
- * Router service definition that provides high level information about router transitions.
+ * Abstract service that provides an observable stream of router transition events.
+ *
+ * This is the base class for {@link DbxRouterService}, exposing only the transition
+ * observation capability without navigation methods. Useful when a consumer only needs
+ * to react to route changes without performing navigation.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * class MyComponent {
+ *   private readonly transitions = inject(DbxRouterTransitionService);
+ *
+ *   readonly onSuccess$ = this.transitions.transitions$.pipe(
+ *     filter(e => e.type === DbxRouterTransitionEventType.SUCCESS)
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link DbxRouterService} for the full router service with navigation
+ * @see {@link DbxRouterTransitionEvent} for the event type
  */
 class DbxRouterTransitionService {
 }
 
 /**
- * Router service definition that can route the app and provide routing details.
+ * Abstract router service that provides navigation capabilities and routing state information.
+ *
+ * Extends {@link DbxRouterTransitionService} with navigation methods (`go`, `updateParams`) and
+ * route inspection methods (`isActive`, `isActiveExactly`, `comparePrecision`).
+ *
+ * Concrete implementations include {@link DbxAngularRouterService} (Angular Router) and
+ * {@link DbxUIRouterService} (UIRouter).
+ *
+ * @example
+ * ```ts
+ * // Inject and use in a component or service
+ * @Component({ ... })
+ * class MyComponent {
+ *   private readonly router = inject(DbxRouterService);
+ *
+ *   navigateToDashboard(): void {
+ *     this.router.go({ ref: 'app.dashboard', refParams: { tab: 'overview' } });
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link DbxRouterTransitionService} for transition event observables
+ * @see {@link DbxAngularRouterService} for the Angular Router implementation
+ * @see {@link DbxUIRouterService} for the UIRouter implementation
  */
 class DbxRouterService extends DbxRouterTransitionService {
 }
 
 /**
- * Auth routes configurations for an app.
+ * Abstract configuration class that defines the key authentication-related routes for an application.
+ *
+ * Provide a concrete instance of this class via {@link provideDbxAppAuthRouter} to configure
+ * where the auth router service navigates during authentication lifecycle events (login, logout, onboarding).
+ *
+ * @example
+ * ```ts
+ * const authRoutes: DbxAppAuthRoutes = {
+ *   loginRef: '/auth/login',
+ *   loggedOutRef: '/auth/logged-out',
+ *   onboardRef: '/onboard',
+ *   appRef: '/app'
+ * };
+ * ```
+ *
+ * @see {@link DbxAppAuthRouterService} for the service that uses these routes for navigation.
+ * @see {@link provideDbxAppAuthRouter} for registering this configuration.
  */
 class DbxAppAuthRoutes {
 }
 
 /**
- * Helper service for navigating to important auth-related routes.
+ * Angular service that provides programmatic navigation to key authentication-related routes.
+ *
+ * This service wraps {@link DbxRouterService} and {@link DbxAppAuthRoutes} to offer
+ * convenient methods for navigating to login, logout, onboarding, and main app routes.
+ * It also manages an `isAuthRouterEffectsEnabled` flag that controls whether
+ * {@link DbxAppAuthRouterEffects} should perform automatic navigation on auth events.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class LogoutButtonComponent {
+ *   private readonly authRouterService = inject(DbxAppAuthRouterService);
+ *
+ *   async onLogout() {
+ *     await this.authRouterService.goToLoggedOut();
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link DbxAppAuthRoutes} for the route configuration.
+ * @see {@link DbxAppAuthRouterEffects} for automatic navigation on auth state changes.
  */
 class DbxAppAuthRouterService {
     dbxRouterService = inject(DbxRouterService);
     dbxAppAuthRoutes = inject(DbxAppAuthRoutes);
     _isAuthRouterEffectsEnabled = new BehaviorSubject(true);
+    /** Observable of whether auth router effects are currently enabled. */
     isAuthRouterEffectsEnabled$ = this._isAuthRouterEffectsEnabled.asObservable();
     ngOnDestroy() {
         this._isAuthRouterEffectsEnabled.complete();
@@ -2648,13 +3754,31 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Used by DbxAppAuthRouterEffects to configure the states that should be activve by default.
+ * Angular injection token used to configure which {@link DbxAppContextState} values
+ * the {@link DbxAppAuthRouterEffects} should be active for.
+ *
+ * When provided, the effects will only trigger navigation (e.g., redirect on logout)
+ * when the application is in one of the specified context states.
+ * Defaults to {@link DBX_KNOWN_APP_CONTEXT_STATES} if not explicitly provided.
+ *
+ * @see {@link provideDbxAppAuthRouterState} for how this token is provisioned.
  */
 const DBX_APP_AUTH_ROUTER_EFFECTS_TOKEN = new InjectionToken('DbxAppAuthRouterEffectsActiveStates');
 /**
- * Set of ngrx effects that handle navigation in the app when the auth changes in certain ways.
+ * NgRx effects class that performs automatic navigation when authentication state changes.
  *
- * Is configurable via the DBX_APP_AUTH_ROUTER_EFFECTS_TOKEN to choose which states this effect is active or not. By default is equal to DBX_KNOWN_APP_CONTEXT_STATES.
+ * This effects class handles two key navigation scenarios:
+ * - **On logout**: Redirects the user to the login route via {@link DbxAppAuthRouterService.goToLogin}.
+ * - **On login**: Redirects the user to the main app route via {@link DbxAppAuthRouterService.goToApp}.
+ *
+ * Navigation only occurs when:
+ * 1. The app is in one of the configured active context states (see {@link DBX_APP_AUTH_ROUTER_EFFECTS_TOKEN}).
+ * 2. The {@link DbxAppAuthRouterService.isAuthRouterEffectsEnabled} flag is `true`.
+ *
+ * Extends {@link AbstractOnDbxAppContextStateEffects} to scope effect activation to specific app states.
+ *
+ * @see {@link DbxAppAuthRouterService} for the navigation methods used.
+ * @see {@link provideDbxAppAuthRouterState} for registration and configuration.
  */
 class DbxAppAuthRouterEffects extends AbstractOnDbxAppContextStateEffects {
     dbxAppAuthRouterService = inject(DbxAppAuthRouterService);
@@ -2677,10 +3801,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * Creates EnvironmentProviders for providing DbxAppAuthRouterState configuration and effects.
+ * Creates Angular `EnvironmentProviders` that register the auth router state effects
+ * and their configuration.
  *
- * @param config Configuration
- * @returns EnvironmentProviders
+ * This provisions the {@link DBX_APP_AUTH_ROUTER_EFFECTS_TOKEN} with the active states
+ * and registers the {@link DbxAppAuthRouterEffects} NgRx effects class.
+ *
+ * @param config - Configuration specifying which app context states activate the auth router effects.
+ * @returns Angular `EnvironmentProviders` for the auth router state effects.
+ *
+ * @example
+ * ```ts
+ * provideDbxAppAuthRouterState({
+ *   activeRoutesToApplyEffects: ['root']
+ * });
+ * ```
+ *
+ * @see {@link provideDbxAppAuth} for the all-in-one provider that includes this.
+ * @see {@link DbxAppAuthRouterEffects} for the effects that handle auth-based navigation.
  */
 function provideDbxAppAuthRouterState(config) {
     const { activeRoutesToApplyEffects } = config;
@@ -2697,10 +3835,25 @@ function provideDbxAppAuthRouterState(config) {
 }
 
 /**
- * Creates EnvironmentProviders for providing DbxAppAuthRoutes configuration.
+ * Creates Angular `EnvironmentProviders` that register the {@link DbxAppAuthRoutes} configuration.
  *
- * @param config Configuration
- * @returns EnvironmentProviders
+ * This makes the auth routes available for injection throughout the application,
+ * primarily consumed by {@link DbxAppAuthRouterService} for programmatic navigation.
+ *
+ * @param config - Configuration containing the auth routes to register.
+ * @returns Angular `EnvironmentProviders` for the auth router.
+ *
+ * @example
+ * ```ts
+ * provideDbxAppAuthRouter({
+ *   dbxAppAuthRoutes: {
+ *     loginRef: '/auth/login',
+ *     appRef: '/app'
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link provideDbxAppAuth} for the all-in-one provider that includes this.
  */
 function provideDbxAppAuthRouter(config) {
     const { dbxAppAuthRoutes } = config;
@@ -2714,51 +3867,115 @@ function provideDbxAppAuthRouter(config) {
 }
 
 /**
- * Convenience operator that emits events when the input observable goes from false to true.
+ * Creates an observable that emits a `void` event each time the user transitions from
+ * logged-out to logged-in (i.e., the input observable transitions from `false` to `true`).
  *
- * @param isLoggedInObs
- * @returns
+ * Useful for triggering side effects (e.g., loading user data) on login events.
+ *
+ * @param isLoggedInObs - An observable that emits `true` when the user is logged in and `false` otherwise.
+ * @returns An observable that emits `void` on each false-to-true transition.
+ *
+ * @see {@link loggedOutObsFromIsLoggedIn} for the inverse (logout detection).
  */
 function loggedInObsFromIsLoggedIn(isLoggedInObs) {
     return isLoggedInObs.pipe(onFalseToTrue(), map(() => undefined));
 }
 /**
- * Convenience operator that emits events when the input observable goes from true to false.
+ * Creates an observable that emits a `void` event each time the user transitions from
+ * logged-in to logged-out (i.e., the input observable transitions from `true` to `false`).
  *
- * @param isLoggedInObs
- * @returns
+ * Useful for triggering side effects (e.g., clearing cached data) on logout events.
+ *
+ * @param isLoggedInObs - An observable that emits `true` when the user is logged in and `false` otherwise.
+ * @returns An observable that emits `void` on each true-to-false transition.
+ *
+ * @see {@link loggedInObsFromIsLoggedIn} for the inverse (login detection).
  */
 function loggedOutObsFromIsLoggedIn(isLoggedInObs) {
     return isLoggedInObs.pipe(onTrueToFalse(), map(() => undefined));
 }
+/**
+ * RxJS operator that checks whether an {@link AuthRoleSet} contains **all** roles from the given observable set.
+ *
+ * Emits `true` when every role in the target set is present in the source role set, `false` otherwise.
+ *
+ * @param roles - Observable of the required roles to check against.
+ * @returns An `OperatorFunction` that transforms an `AuthRoleSet` stream into a `boolean` stream.
+ *
+ * @see {@link authRolesSetContainsAnyRoleFrom} for matching any role.
+ * @see {@link authRolesSetContainsNoRolesFrom} for matching no roles.
+ */
 function authRolesSetContainsAllRolesFrom(roles) {
     return setContainsAllValuesFrom(roles);
 }
+/**
+ * RxJS operator that checks whether an {@link AuthRoleSet} contains **any** role from the given observable set.
+ *
+ * Emits `true` when at least one role in the target set is present in the source role set, `false` otherwise.
+ *
+ * @param roles - Observable of the target roles to check against.
+ * @returns An `OperatorFunction` that transforms an `AuthRoleSet` stream into a `boolean` stream.
+ *
+ * @see {@link authRolesSetContainsAllRolesFrom} for matching all roles.
+ * @see {@link authRolesSetContainsNoRolesFrom} for matching no roles.
+ */
 function authRolesSetContainsAnyRoleFrom(roles) {
     return setContainsAllValuesFrom(roles);
 }
+/**
+ * RxJS operator that checks whether an {@link AuthRoleSet} contains **none** of the roles from the given observable set.
+ *
+ * Emits `true` when no role in the target set is present in the source role set, `false` otherwise.
+ * Useful for hiding content from users with specific roles.
+ *
+ * @param roles - Observable of the roles to check for absence.
+ * @returns An `OperatorFunction` that transforms an `AuthRoleSet` stream into a `boolean` stream.
+ *
+ * @see {@link authRolesSetContainsAllRolesFrom} for matching all roles.
+ * @see {@link authRolesSetContainsAnyRoleFrom} for matching any role.
+ */
 function authRolesSetContainsNoRolesFrom(roles) {
     return setContainsNoValueFrom(roles);
 }
 
 /**
- * Set of ngrx effects that repeat events from DbxAuthService.
+ * NgRx effects class that bridges the {@link DbxAuthService} observables into the NgRx store.
+ *
+ * This effects class serves two purposes:
+ * 1. **Event forwarding**: Listens to the auth service's reactive streams (login/logout events,
+ *    user state, roles, onboarding status, user identifier) and dispatches corresponding NgRx actions
+ *    to keep the store in sync with the auth provider.
+ * 2. **Command handling**: Listens for the `logout` command action and forwards it to
+ *    {@link DbxAuthService.logOut} to perform the actual logout.
+ *
+ * This is registered via {@link provideDbxAppAuthState} and should not be provided manually.
+ *
+ * @see {@link DbxAuthService} for the source observables.
+ * @see {@link DbxAppAuthActions} for the auth lifecycle actions.
+ * @see {@link DbxAppAuthUserActions} for the user state actions.
  */
 class DbxAppAuthEffects {
     dbxAuthService = inject(DbxAuthService);
     actions$ = inject(Actions);
     store = inject((Store));
     // MARK: Auth
+    /** Dispatches {@link DbxAppAuthActions.loggedIn} when the auth service emits a login event. */
     emitLoggedIn = createEffect(() => this.dbxAuthService.onLogIn$.pipe(map(() => loggedIn())));
+    /** Dispatches {@link DbxAppAuthActions.loggedOut} when the auth service emits a logout event. */
     emitLoggedOut = createEffect(() => this.dbxAuthService.onLogOut$.pipe(map(() => loggedOut())));
+    /** Forwards the {@link DbxAppAuthActions.logout} command to {@link DbxAuthService.logOut}. */
     forwardLogoutToAuthService = createEffect(() => this.actions$.pipe(ofType(logout), tap(() => {
         // Perform the logout
         this.dbxAuthService.logOut();
     })), { dispatch: false });
-    // MARK: Auth
+    // MARK: User
+    /** Syncs the user identifier from the auth service into the NgRx store. */
     setUserIdentifier = createEffect(() => this.dbxAuthService.userIdentifier$.pipe(map((id) => setUserIdentifier({ id }))));
+    /** Syncs the user's {@link AuthUserState} from the auth service into the NgRx store. */
     setUserState = createEffect(() => this.dbxAuthService.authUserState$.pipe(map((state) => setUserState({ state }))));
+    /** Syncs the user's auth roles from the auth service into the NgRx store. */
     setUserRoles = createEffect(() => this.dbxAuthService.authRoles$.pipe(map((roles) => setUserRoles({ roles: Array.from(roles ?? []) }))));
+    /** Syncs the user's onboarding status from the auth service into the NgRx store. */
     setUserIsOnboarded = createEffect(() => this.dbxAuthService.isOnboarded$.pipe(map((isOnboarded) => setUserIsOnboarded({ isOnboarded }))));
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: DbxAppAuthEffects, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: DbxAppAuthEffects });
@@ -2768,19 +3985,49 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Creates EnvironmentProviders for providing the DbxAppAuth state and effects.
+ * Creates Angular `EnvironmentProviders` that register the NgRx auth feature state and effects.
  *
- * @returns EnvironmentProviders
+ * This provisions the `fromDbxAppAuth` feature reducer and the {@link DbxAppAuthEffects} effects class,
+ * which together manage the auth user state (identifier, roles, onboarding status) in the NgRx store.
+ *
+ * Typically called internally by {@link provideDbxAppAuth}, but can be used independently
+ * if only the state management (without router integration) is needed.
+ *
+ * @returns Angular `EnvironmentProviders` for the auth state feature.
+ *
+ * @see {@link DbxAppAuthEffects}
+ * @see {@link fromDbxAppAuth}
  */
 function provideDbxAppAuthState() {
     return makeEnvironmentProviders([provideState(featureKey, reducers), provideEffects(DbxAppAuthEffects)]);
 }
 
 /**
- * The "all-in-one" provider for an app's dbx-core auth providers.
+ * All-in-one provider function that registers the complete set of dbx-core auth providers.
  *
- * @param config Configuration
- * @returns EnvironmentProviders
+ * This is the recommended way to set up authentication in a dbx-core application. It provisions:
+ * - The NgRx auth state and effects via {@link provideDbxAppAuthState}
+ * - The auth router configuration via {@link provideDbxAppAuthRouter}
+ * - The auth router state effects via {@link provideDbxAppAuthRouterState}
+ *
+ * @param config - Combined auth configuration including routes and active states for effects.
+ * @returns Angular `EnvironmentProviders` to be included in the application's provider list.
+ *
+ * @example
+ * ```ts
+ * // In your app config or module:
+ * provideDbxAppAuth({
+ *   dbxAppAuthRoutes: {
+ *     loginRef: '/login',
+ *     appRef: '/app'
+ *   },
+ *   activeRoutesToApplyEffects: ['root']
+ * });
+ * ```
+ *
+ * @see {@link provideDbxAppAuthState}
+ * @see {@link provideDbxAppAuthRouter}
+ * @see {@link provideDbxAppAuthRouterState}
  */
 function provideDbxAppAuth(config) {
     const { dbxAppAuthRoutes, activeRoutesToApplyEffects } = config;
@@ -2789,7 +4036,24 @@ function provideDbxAppAuth(config) {
 }
 
 /**
- * Structural decorator directive similar to ngIf that embeds content if the current auth user has any of the target role(s).
+ * Structural directive that conditionally renders its host element based on whether
+ * the currently authenticated user possesses **at least one** of the specified auth roles.
+ *
+ * Similar to `*ngIf`, this directive shows or hides content reactively as the user's
+ * roles change. It uses {@link DbxAuthService.authRoles$} to observe the current role set
+ * and checks that at least one role in the target list is present.
+ *
+ * @example
+ * ```html
+ * <!-- Show if user has either 'admin' or 'moderator' role -->
+ * <div *dbxAuthHasAnyRole="['admin', 'moderator']">Privileged content</div>
+ *
+ * <!-- Show if user has the 'viewer' role -->
+ * <div *dbxAuthHasAnyRole="'viewer'">Viewer content</div>
+ * ```
+ *
+ * @see {@link DbxAuthHasRolesDirective} for requiring **all** specified roles.
+ * @see {@link DbxAuthNotAnyRoleDirective} for excluding users with specified roles.
  */
 class DbxAuthHasAnyRoleDirective extends AbstractIfDirective {
     _authService = inject(DbxAuthService);
@@ -2808,7 +4072,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { targetRoles: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxAuthHasAnyRole", required: false }] }] } });
 
 /**
- * Structural decorator directive similar to ngIf that embeds content if the current auth user has all of the target role(s).
+ * Structural directive that conditionally renders its host element based on whether
+ * the currently authenticated user possesses **all** of the specified auth roles.
+ *
+ * Similar to `*ngIf`, this directive shows or hides content reactively as the user's
+ * roles change. It uses {@link DbxAuthService.authRoles$} to observe the current role set
+ * and checks that every role in the target list is present.
+ *
+ * @example
+ * ```html
+ * <!-- Show only if user has the 'admin' role -->
+ * <div *dbxAuthHasRoles="'admin'">Admin-only content</div>
+ *
+ * <!-- Show only if user has BOTH 'editor' and 'reviewer' roles -->
+ * <div *dbxAuthHasRoles="['editor', 'reviewer']">Editor and reviewer content</div>
+ * ```
+ *
+ * @see {@link DbxAuthHasAnyRoleDirective} for matching **any** of the specified roles.
+ * @see {@link DbxAuthNotAnyRoleDirective} for excluding users with specified roles.
  */
 class DbxAuthHasRolesDirective extends AbstractIfDirective {
     _authService = inject(DbxAuthService);
@@ -2827,7 +4108,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { targetRoles: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxAuthHasRoles", required: false }] }] } });
 
 /**
- * Structural decorator directive similar to ngIf that embeds content if the current auth user has none of the target role(s).
+ * Structural directive that conditionally renders its host element based on whether
+ * the currently authenticated user possesses **none** of the specified auth roles.
+ *
+ * This is the inverse of {@link DbxAuthHasAnyRoleDirective}. Content is shown only when
+ * the user does not have any of the listed roles. Useful for hiding content from
+ * privileged users or showing fallback UI for unprivileged users.
+ *
+ * @example
+ * ```html
+ * <!-- Show only if user does NOT have the 'admin' role -->
+ * <div *dbxAuthNotAnyRole="'admin'">Non-admin content</div>
+ *
+ * <!-- Show only if user has NEITHER 'banned' nor 'suspended' role -->
+ * <div *dbxAuthNotAnyRole="['banned', 'suspended']">Active user content</div>
+ * ```
+ *
+ * @see {@link DbxAuthHasRolesDirective} for requiring **all** specified roles.
+ * @see {@link DbxAuthHasAnyRoleDirective} for requiring **any** of the specified roles.
  */
 class DbxAuthNotAnyRoleDirective extends AbstractIfDirective {
     _authService = inject(DbxAuthService);
@@ -2846,10 +4144,29 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { targetRoles: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxAuthNotAnyRole", required: false }] }] } });
 
 /**
- * State for accessing the app's DbxAppAuthState defined within the DbxAppAuthFullState for the ngrx store.
+ * Angular service that provides access to the current auth user state from the NgRx store.
+ *
+ * This service acts as a convenience wrapper around the NgRx store, exposing a selector
+ * for the {@link DbxAppAuthStateUser} slice of the auth feature state. It is provided
+ * at the root level and can be injected anywhere authentication state is needed.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class MyComponent {
+ *   private readonly authStateService = inject(DbxAppAuthStateService);
+ *
+ *   readonly user$ = this.authStateService.authStateUser$;
+ * }
+ * ```
+ *
+ * @see {@link DbxAppAuthFullState}
+ * @see {@link fromDbxAppAuth.selectDbxAppAuthUser}
  */
 class DbxAppAuthStateService {
+    /** NgRx store instance typed to the full auth state. */
     store = inject((Store));
+    /** Observable of the current {@link DbxAppAuthStateUser} from the NgRx store. */
     authStateUser$ = this.store.select(selectDbxAppAuthUser);
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: DbxAppAuthStateService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: DbxAppAuthStateService, providedIn: 'root' });
@@ -2861,8 +4178,31 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Abstract base class defining the reactive interface for a button component.
+ *
+ * Provides observable streams for disabled state, working state, click events,
+ * and display content. Implementations are provided via DI using {@link provideDbxButton}.
+ *
+ * @see {@link AbstractDbxButtonDirective} for the default implementation.
+ * @see {@link DbxButtonDirective} for the concrete directive.
+ */
 class DbxButton {
 }
+/**
+ * Creates Angular providers that register a {@link DbxButton} implementation for DI.
+ *
+ * @param sourceType - The concrete button directive or component class to provide.
+ *
+ * @example
+ * ```typescript
+ * @Directive({
+ *   selector: '[myCustomButton]',
+ *   providers: provideDbxButton(MyCustomButtonDirective),
+ * })
+ * export class MyCustomButtonDirective extends AbstractDbxButtonDirective {}
+ * ```
+ */
 function provideDbxButton(sourceType) {
     return [
         {
@@ -2872,17 +4212,31 @@ function provideDbxButton(sourceType) {
     ];
 }
 /**
- * Returns the DbxButtonDisplayType given the input content.
+ * Determines whether a button display is an icon-only button or a text button.
  *
- * @param content
- * @returns
+ * @param content - The button display configuration to evaluate.
+ * @returns `'icon_button'` if only an icon is set, otherwise `'text_button'`.
+ *
+ * @example
+ * ```typescript
+ * dbxButtonDisplayType({ icon: 'edit' }); // 'icon_button'
+ * dbxButtonDisplayType({ icon: 'save', text: 'Save' }); // 'text_button'
+ * ```
  */
 function dbxButtonDisplayType(content) {
     return !content.text && content.icon ? 'icon_button' : 'text_button';
 }
 
 /**
- * Context used for linking a button to an ActionContext and only look for triggers.
+ * Links a {@link DbxButton} click to an action context trigger, without synchronizing
+ * disabled or working states. Use {@link DbxActionButtonDirective} for full state binding.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <button dbxButton dbxActionButtonTrigger>Trigger Only</button>
+ * </div>
+ * ```
  */
 class DbxActionButtonTriggerDirective {
     dbxButton = inject(DbxButton, { host: true });
@@ -2907,7 +4261,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * Context used for linking a button to an ActionContext.
+ * Links a {@link DbxButton} to an action context, synchronizing the button's
+ * disabled and working states with the action's lifecycle and forwarding
+ * button clicks as action triggers.
+ *
+ * Extends {@link DbxActionButtonTriggerDirective} by also binding working/disabled state.
+ *
+ * @example
+ * ```html
+ * <div dbxAction>
+ *   <button dbxButton dbxActionButton [text]="'Submit'">Submit</button>
+ * </div>
+ * ```
  */
 class DbxActionButtonDirective extends DbxActionButtonTriggerDirective {
     constructor() {
@@ -2931,6 +4296,23 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 // MARK: Button Directives
+/**
+ * Navigates to a route when the host {@link DbxButton} is clicked, using the provided {@link SegueRef}.
+ *
+ * @example
+ * ```html
+ * <button dbxButton [dbxButtonSegue]="{ ref: '/dashboard' }">Go to Dashboard</button>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * readonly segue: SegueRef = { ref: '/settings', refType: 'url' };
+ * ```
+ *
+ * ```html
+ * <button dbxButton [dbxButtonSegue]="segue">Settings</button>
+ * ```
+ */
 class DbxButtonSegueDirective {
     dbxButton = inject(DbxButton);
     dbxRouterService = inject(DbxRouterService);
@@ -2955,7 +4337,19 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [], propDecorators: { segueRef: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxButtonSegue", required: false }] }] } });
 
 /**
- * Abstract button component.
+ * Abstract base directive implementing the {@link DbxButton} interface with signal-based state management.
+ *
+ * Manages disabled state, working/progress state, display content (icon/text),
+ * and button click interception. Subclass this to create custom button directives.
+ *
+ * @example
+ * ```typescript
+ * @Directive({
+ *   selector: '[myButton]',
+ *   providers: provideDbxButton(MyButtonDirective),
+ * })
+ * export class MyButtonDirective extends AbstractDbxButtonDirective {}
+ * ```
  */
 class AbstractDbxButtonDirective {
     /**
@@ -3046,7 +4440,23 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [], propDecorators: { buttonClick: [{ type: i0.Output, args: ["buttonClick"] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], working: [{ type: i0.Input, args: [{ isSignal: true, alias: "working", required: false }] }], buttonDisplay: [{ type: i0.Input, args: [{ isSignal: true, alias: "buttonDisplay", required: false }] }], icon: [{ type: i0.Input, args: [{ isSignal: true, alias: "icon", required: false }] }], text: [{ type: i0.Input, args: [{ isSignal: true, alias: "text", required: false }] }] } });
 // MARK: Implementation
 /**
- * Provides an DbxButton directive.
+ * Concrete button directive that provides a {@link DbxButton} instance via DI.
+ *
+ * Apply to any element to make it a managed button with reactive disabled,
+ * working, and display state.
+ *
+ * @example
+ * ```html
+ * <button dbxButton [icon]="'save'" [text]="'Save'" [disabled]="isSaving">
+ *   Save
+ * </button>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Access the button instance via template reference: -->
+ * <button dbxButton #btn="dbxButton" (click)="btn.clickButton()">Submit</button>
+ * ```
  */
 class DbxButtonDirective extends AbstractDbxButtonDirective {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: DbxButtonDirective, deps: null, target: i0.ɵɵFactoryTarget.Directive });
@@ -3063,9 +4473,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Context used for linking a button to a LoadingContext.
+ * Links a {@link DbxButton} to a {@link LoadingContext}, automatically setting the button
+ * to a working state whenever the loading context is actively loading.
  *
- * It will be set working when the context is set loading.
+ * @example
+ * ```html
+ * <button dbxButton [dbxLoadingButton]="loadingContext">
+ *   Loading...
+ * </button>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * readonly loadingContext = cleanLoadingContext<MyData>(this.data$);
+ * ```
  */
 class DbxLoadingButtonDirective {
     dbxButton = inject(DbxButton, { host: true });
@@ -3115,7 +4536,22 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * State for accessing the app's DbxAppContextState defined within the DbxAppContextFullState for the ngrx store.
+ * Service for dispatching and selecting the application's {@link DbxAppContextState} from the NgRx store.
+ *
+ * Provided at the root level. Use to transition between app-level context states
+ * (e.g., public, auth, onboard, app).
+ *
+ * @example
+ * ```typescript
+ * @Component({ ... })
+ * export class AppComponent {
+ *   private readonly contextService = inject(DbxAppContextService);
+ *
+ *   onLogin(): void {
+ *     this.contextService.setState('app');
+ *   }
+ * }
+ * ```
  */
 class DbxAppContextService {
     store = inject((Store));
@@ -3137,7 +4573,22 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Used to set the DbxAppContextState for an app to the input state using the DbxAppContextService.
+ * Sets the application's {@link DbxAppContextState} when the input value changes.
+ *
+ * Dispatches to the NgRx store via {@link DbxAppContextService}. Commonly placed
+ * on route-level components to declare which context the route belongs to.
+ *
+ * @example
+ * ```html
+ * <div [dbxAppContextState]="'app'">
+ *   <!-- App-level content rendered when context is 'app' -->
+ * </div>
+ * ```
+ *
+ * @example
+ * ```html
+ * <router-outlet dbxAppContextState="public"></router-outlet>
+ * ```
  */
 class DbxAppContextStateDirective {
     dbxAppContextStateService = inject(DbxAppContextService);
@@ -3169,13 +4620,42 @@ function provideDbxAppContextState() {
 }
 
 /**
- * App environment details
+ * Abstract token class representing the application's runtime environment configuration.
+ *
+ * Provided via DI using {@link provideDbxAppEnviroment} and accessed through {@link DbxAppEnviromentService}.
+ * Subclass or provide a concrete instance to define environment-specific flags.
+ *
+ * @example
+ * ```typescript
+ * const env: DbxAppEnviroment = {
+ *   production: false,
+ *   testing: true,
+ * };
+ *
+ * // In app config:
+ * provideDbxAppEnviroment(env);
+ * ```
  */
 class DbxAppEnviroment {
 }
 
 /**
- * Service for accessing the app's environment details.
+ * Injectable service providing convenience accessors for the application's {@link DbxAppEnviroment}.
+ *
+ * Exposes computed properties for common environment checks (production, staging, testing)
+ * and a typed getter for accessing custom environment properties.
+ *
+ * @example
+ * ```typescript
+ * @Component({ ... })
+ * export class MyComponent {
+ *   private readonly envService = inject(DbxAppEnviromentService);
+ *
+ *   get showDebugPanel(): boolean {
+ *     return !this.envService.isProduction;
+ *   }
+ * }
+ * ```
  */
 class DbxAppEnviromentService {
     environment = inject(DbxAppEnviroment);
@@ -3202,9 +4682,19 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Provides the DbxAppEnviromentService and DbxAppEnviroment.
+ * Registers {@link DbxAppEnviroment} and {@link DbxAppEnviromentService} as environment-level providers.
+ *
+ * @param environment - The concrete environment configuration to provide.
  *
- * @param environment
+ * @example
+ * ```typescript
+ * // In app.config.ts:
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideDbxAppEnviroment({ production: true, staging: false }),
+ *   ],
+ * };
+ * ```
  */
 function provideDbxAppEnviroment(environment) {
     const providers = [
@@ -3217,10 +4707,21 @@ function provideDbxAppEnviroment(environment) {
     return makeEnvironmentProviders(providers);
 }
 
+/**
+ * Function that expands a single {@link ClickableAnchorLinkTree} node into a tree of {@link ExpandedClickableAnchorLinkTree} nodes.
+ *
+ * @see {@link expandClickableAnchorLinkTree} for the full expand-and-flatten operation
+ */
 const expandClickableAnchorLinkTreeNode = expandTreeFunction({
     getChildren: (x) => x.children
 });
+/**
+ * Flattens an expanded tree of {@link ExpandedClickableAnchorLinkTree} nodes into a flat array, preserving the tree node wrappers.
+ */
 const flattenExpandedClickableAnchorLinkTree = flattenTreeToArrayFunction();
+/**
+ * Flattens an expanded tree of {@link ExpandedClickableAnchorLinkTree} nodes into a flat array of the underlying {@link ClickableAnchorLinkTree} values.
+ */
 const flattenExpandedClickableAnchorLinkTreeToLinks = flattenTreeToArrayFunction((x) => x.value);
 /**
  * Fully expands the given parent link and flattens the tree to a single parent link.
@@ -3235,6 +4736,15 @@ function expandClickableAnchorLinkTree(link) {
  * Expands an array of links into an array of ExpandedClickableAnchorLinkTree tree values.
  */
 const expandClickableAnchorLinkTrees = expandFlattenTreeFunction(expandClickableAnchorLinkTreeNode, flattenExpandedClickableAnchorLinkTree);
+/**
+ * Determines the {@link ClickableAnchorType} for a given anchor based on its properties.
+ *
+ * Priority order: disabled > sref (router link) > clickable (onClick handler) > href (external URL) > plain.
+ *
+ * @param anchor - The anchor to evaluate.
+ * @param disabled - An optional external disabled override; if `true`, the anchor type will be `'disabled'` regardless of the anchor's own state.
+ * @returns The determined {@link ClickableAnchorType}.
+ */
 function anchorTypeForAnchor(anchor, disabled) {
     let type = 'disabled';
     if (!disabled && anchor) {
@@ -3256,8 +4766,45 @@ function anchorTypeForAnchor(anchor, disabled) {
     }
     return type;
 }
+/**
+ * Abstract base class representing a reactive anchor element that exposes its state as observables.
+ *
+ * Subclasses provide concrete implementations that manage the anchor's disabled, selected, and type states.
+ *
+ * @typeParam T - The specific anchor type, defaulting to {@link ClickableAnchor}.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * class MyAnchorComponent extends DbxAnchor {
+ *   readonly disabled$ = of(false);
+ *   readonly selected$ = of(true);
+ *   readonly anchor$ = of({ ref: 'app.home' });
+ *   readonly type$ = of('sref' as ClickableAnchorType);
+ * }
+ * ```
+ *
+ * @see {@link provideDbxAnchor} for configuring DI providers
+ * @see {@link AbstractDbxAnchorDirective} for the directive-based implementation
+ */
 class DbxAnchor {
 }
+/**
+ * Creates Angular DI providers that register the given source type as a {@link DbxAnchor} provider using `forwardRef`.
+ *
+ * @typeParam S - The concrete {@link DbxAnchor} subclass to provide.
+ * @param sourceType - The class type to register as the anchor provider.
+ * @returns An array of Angular providers.
+ *
+ * @example
+ * ```ts
+ * @Directive({
+ *   selector: '[myAnchor]',
+ *   providers: provideDbxAnchor(MyAnchorDirective)
+ * })
+ * class MyAnchorDirective extends DbxAnchor { ... }
+ * ```
+ */
 function provideDbxAnchor(sourceType) {
     return [
         {
@@ -3268,13 +4815,41 @@ function provideDbxAnchor(sourceType) {
 }
 
 /**
- * Abstract anchor directive.
+ * Abstract base directive for managing anchor state using Angular signals and model inputs.
+ *
+ * Provides reactive computed properties for the resolved anchor, its disabled/selected state, and its type.
+ * Subclasses can extend this to implement framework-specific anchor rendering (e.g., UIRouter or Angular Router).
+ *
+ * @typeParam T - The specific anchor type, defaulting to {@link ClickableAnchor}.
+ *
+ * @example
+ * ```html
+ * <!-- Usage in a template via a concrete subclass -->
+ * <my-anchor [ref]="'/app/dashboard'" [disabled]="isDisabled">
+ *   Dashboard
+ * </my-anchor>
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Programmatic usage
+ * directive.setRef('app.dashboard');
+ * directive.setDisabled(true);
+ * ```
+ *
+ * @see {@link DbxAnchor} for the abstract base class this implements
+ * @see {@link anchorTypeForAnchor} for anchor type resolution logic
  */
 class AbstractDbxAnchorDirective {
+    /** Model input for the segue ref or router link to navigate to. */
     ref = model(...(ngDevMode ? [undefined, { debugName: "ref" }] : []));
+    /** Model input for the full anchor configuration object. */
     anchor = model(...(ngDevMode ? [undefined, { debugName: "anchor" }] : []));
+    /** Model input for externally controlling the disabled state. */
     disabled = model(...(ngDevMode ? [undefined, { debugName: "disabled" }] : []));
+    /** Model input for externally controlling the selected state. */
     selected = model(...(ngDevMode ? [undefined, { debugName: "selected" }] : []));
+    /** Computed anchor that merges the `ref` input with the `anchor` input, preferring `ref` when set. */
     anchorSignal = computed(() => {
         const ref = this.ref();
         const anchor = this.anchor();
@@ -3284,37 +4859,46 @@ class AbstractDbxAnchorDirective {
         }
         return result;
     }, ...(ngDevMode ? [{ debugName: "anchorSignal" }] : []));
+    /** Computed selected state that combines the `selected` input with the anchor's own `selected` property. */
     selectedSignal = computed(() => {
         const selected = this.selected();
         const anchor = this.anchorSignal();
         return selected || anchor?.selected;
     }, ...(ngDevMode ? [{ debugName: "selectedSignal" }] : []));
+    /** Computed {@link ClickableAnchorType} derived from the current anchor and disabled state. */
     typeSignal = computed(() => {
         const anchor = this.anchorSignal();
         const disabled = this.disabled();
         return anchorTypeForAnchor(anchor, disabled);
     }, ...(ngDevMode ? [{ debugName: "typeSignal" }] : []));
+    /** Computed disabled state that combines the `disabled` input with the anchor's own `disabled` property. */
     disabledSignal = computed(() => {
         const disabled = this.disabled();
         const anchor = this.anchorSignal();
         return disabled || anchor?.disabled;
     }, ...(ngDevMode ? [{ debugName: "disabledSignal" }] : []));
+    /** Computed URL extracted from the current anchor's `url` property. */
     urlSignal = computed(() => this.anchorSignal()?.url, ...(ngDevMode ? [{ debugName: "urlSignal" }] : []));
+    /** Computed target (e.g., `_blank`) extracted from the current anchor's `target` property. */
     targetSignal = computed(() => this.anchorSignal()?.target, ...(ngDevMode ? [{ debugName: "targetSignal" }] : []));
     anchor$ = toObservable(this.anchorSignal);
     disabled$ = toObservable(this.disabledSignal);
     selected$ = toObservable(this.selectedSignal);
     type$ = toObservable(this.typeSignal);
     // MARK: Accessors
+    /** Sets the segue ref or router link for this anchor. */
     setRef(ref) {
         this.ref.set(ref);
     }
+    /** Sets the full anchor configuration object. */
     setAnchor(anchor) {
         this.anchor.set(anchor);
     }
+    /** Sets the external disabled state override. */
     setDisabled(disabled) {
         this.disabled.set(disabled);
     }
+    /** Sets the external selected state override. */
     setSelected(selected) {
         this.selected.set(selected);
     }
@@ -3325,27 +4909,65 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
             type: Directive
         }], propDecorators: { ref: [{ type: i0.Input, args: [{ isSignal: true, alias: "ref", required: false }] }, { type: i0.Output, args: ["refChange"] }], anchor: [{ type: i0.Input, args: [{ isSignal: true, alias: "anchor", required: false }] }, { type: i0.Output, args: ["anchorChange"] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }, { type: i0.Output, args: ["disabledChange"] }], selected: [{ type: i0.Input, args: [{ isSignal: true, alias: "selected", required: false }] }, { type: i0.Output, args: ["selectedChange"] }] } });
 
+/**
+ * Creates a {@link ClickableUrl} configured to open the given URL in a new browser tab (`target="_blank"`).
+ *
+ * @param url - The URL to open.
+ * @returns A {@link ClickableUrl} with the `target` set to `'_blank'`.
+ */
 function clickableUrlInNewTab(url) {
     return {
         url,
         target: '_blank'
     };
 }
+/**
+ * Creates a {@link ClickableUrl} with a `mailto:` URL from the given email configuration.
+ *
+ * @param mailTo - The mail-to configuration (email address, subject, body, etc.).
+ * @returns A {@link ClickableUrl} with the URL set to a `mailto:` link.
+ *
+ * @see {@link mailToUrlString}
+ */
 function clickableUrlMailTo(mailTo) {
     return {
         url: mailToUrlString(mailTo)
     };
 }
+/**
+ * Creates a {@link ClickableUrl} with a `tel:` URL from the given phone number.
+ *
+ * @param tel - The phone number to create a tel link for.
+ * @returns A {@link ClickableUrl} with the URL set to a `tel:` link.
+ *
+ * @see {@link telUrlString}
+ */
 function clickableUrlTel(tel) {
     return {
         url: telUrlString(tel)
     };
 }
 
+/**
+ * Default param value that indicates no specific identifier has been set, triggering a redirect to the default allowed identifier.
+ */
 const DEFAULT_REDIRECT_FOR_IDENTIFIER_PARAM_VALUE = '0';
+/**
+ * Default route parameter key used to read the model identifier from the URL.
+ */
 const DEFAULT_REDIRECT_FOR_IDENTIFIER_PARAM_KEY = 'id';
 /**
- * This hook asserts the user is allowed to view a route with an identifier as a state parameter.
+ * Registers a UIRouter transition hook that asserts the user is allowed to view a route with an identifier as a state parameter.
+ *
+ * When a transition occurs to the target route:
+ * 1. If the identifier param is missing or equals the default placeholder value, it redirects to the default allowed identifier.
+ * 2. If the identifier differs from the default, it calls `canViewModelWithId` to verify access.
+ * 3. If access is denied, it redirects to the default allowed identifier.
+ *
+ * @param input - Configuration specifying the route criteria, param key, and access control logic.
+ *
+ * @see {@link RedirectForIdentifierParamHookInput}
+ * @see {@link redirectForUserIdentifierParamHook} for a user-specific convenience wrapper
  */
 function redirectForIdentifierParamHook(input) {
     const { defaultAllowedValue, idParam = DEFAULT_REDIRECT_FOR_IDENTIFIER_PARAM_KEY, defaultParamValue = DEFAULT_REDIRECT_FOR_IDENTIFIER_PARAM_VALUE, priority = 100, transitionService, canViewModelWithId: canViewUser } = input;
@@ -3394,10 +5016,25 @@ function redirectForIdentifierParamHook(input) {
     transitionService.onBefore(criteria, assertAllowedId, { priority });
 }
 
+/**
+ * Default param value that indicates no specific user identifier has been set, triggering a redirect to the authenticated user's identifier.
+ */
 const DEFAULT_REDIRECT_FOR_USER_IDENTIFIER_PARAM_VALUE = '0';
+/**
+ * Default route parameter key used to read the user identifier from the URL.
+ */
 const DEFAULT_REDIRECT_FOR_USER_IDENTIFIER_PARAM_KEY = 'uid';
 /**
- * This hook asserts the user is allowed to view a route with a user identifier as a parameter.
+ * Registers a UIRouter transition hook that asserts the current user is allowed to view a route parameterized by a user identifier.
+ *
+ * This is a convenience wrapper around {@link redirectForIdentifierParamHook} that automatically uses the
+ * authenticated user's identifier from {@link DbxAuthService} as the default value when the `uid` param is
+ * missing or matches the placeholder value.
+ *
+ * @param input - Configuration specifying the route criteria, access control logic, and optional parameter overrides.
+ *
+ * @see {@link RedirectForUserIdentifierParamHookInput}
+ * @see {@link redirectForIdentifierParamHook}
  */
 function redirectForUserIdentifierParamHook(input) {
     const { uidParam = DEFAULT_REDIRECT_FOR_USER_IDENTIFIER_PARAM_KEY, defaultParamValue = DEFAULT_REDIRECT_FOR_USER_IDENTIFIER_PARAM_VALUE, criteria, priority = 100, transitionService, canViewUser } = input;
@@ -3412,6 +5049,14 @@ function redirectForUserIdentifierParamHook(input) {
     });
 }
 
+/**
+ * Enum describing the type of a router transition event.
+ *
+ * Used by {@link DbxRouterTransitionEvent} to categorize transition lifecycle events.
+ *
+ * @see {@link DbxRouterTransitionEvent}
+ * @see {@link DbxRouterTransitionService}
+ */
 var DbxRouterTransitionEventType;
 (function (DbxRouterTransitionEventType) {
     /**
@@ -3425,7 +5070,24 @@ var DbxRouterTransitionEventType;
 })(DbxRouterTransitionEventType || (DbxRouterTransitionEventType = {}));
 
 /**
- * AngularRouter implementation of DbxRouterService and DbxRouterTransitionService.
+ * Angular Router implementation of {@link DbxRouterService} and {@link DbxRouterTransitionService}.
+ *
+ * Maps Angular Router's `NavigationStart` and `NavigationEnd` events to {@link DbxRouterTransitionEvent} values
+ * and provides navigation via Angular's `Router.navigate()` and `Router.navigateByUrl()` methods.
+ *
+ * @example
+ * ```ts
+ * // Register via the module
+ * DbxCoreAngularRouterSegueModule.forRoot()
+ *
+ * // Or inject directly
+ * const router = inject(DbxRouterService);
+ * await router.go({ ref: '/dashboard' });
+ * ```
+ *
+ * @see {@link DbxRouterService}
+ * @see {@link DbxCoreAngularRouterSegueModule} for module-based registration
+ * @see {@link DbxUIRouterService} for the UIRouter alternative
  */
 class DbxAngularRouterService {
     router = inject(Router);
@@ -3493,6 +5155,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
             type: Injectable
         }] });
 
+/**
+ * NgModule that provides the Angular Router-based implementation of {@link DbxRouterService} and {@link DbxRouterTransitionService}.
+ *
+ * Use `forRoot()` to register the providers at the application root level.
+ *
+ * @example
+ * ```ts
+ * @NgModule({
+ *   imports: [
+ *     DbxCoreAngularRouterSegueModule.forRoot()
+ *   ]
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @see {@link DbxAngularRouterService} for the underlying service implementation
+ * @see {@link provideDbxUIRouterService} for the UIRouter alternative
+ */
 class DbxCoreAngularRouterSegueModule {
     static forRoot() {
         return {
@@ -3520,7 +5200,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * UIRouter implementation of DbxRouterService and DbxRouterTransitionService.
+ * UIRouter implementation of {@link DbxRouterService} and {@link DbxRouterTransitionService}.
+ *
+ * Bridges UIRouter's `TransitionService` events to {@link DbxRouterTransitionEvent} values and provides
+ * navigation via UIRouter's `StateService.go()`. Supports state activity checks and route precision comparison.
+ *
+ * @example
+ * ```ts
+ * // Register via the provider function
+ * provideDbxUIRouterService()
+ *
+ * // Or inject and use
+ * const router = inject(DbxRouterService);
+ * await router.go({ ref: 'app.dashboard', refParams: { id: '123' } });
+ * ```
+ *
+ * @see {@link DbxRouterService}
+ * @see {@link provideDbxUIRouterService} for provider registration
+ * @see {@link DbxAngularRouterService} for the Angular Router alternative
  */
 class DbxUIRouterService {
     state = inject(StateService);
@@ -3607,9 +5304,25 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * Provides a DbxUIRouterService and configures it to provide for DbxRouterService and DbxRouterTransitionService.
+ * Creates Angular environment providers that register {@link DbxUIRouterService} as the implementation
+ * for both {@link DbxRouterService} and {@link DbxRouterTransitionService}.
  *
- * @returns EnvironmentProviders
+ * Use this function in the application's `bootstrapApplication` or `provideRouter` configuration
+ * when using UIRouter as the routing framework.
+ *
+ * @returns Angular `EnvironmentProviders` for the UIRouter-based router service.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideDbxUIRouterService()
+ *   ]
+ * });
+ * ```
+ *
+ * @see {@link DbxUIRouterService}
+ * @see {@link DbxCoreAngularRouterSegueModule} for the Angular Router alternative
  */
 function provideDbxUIRouterService() {
     const providers = [
@@ -3627,26 +5340,49 @@ function provideDbxUIRouterService() {
 }
 
 /**
- * Convenience function for filtering success from the input observable.
+ * Filters the given transition event observable to only emit successful transitions.
  *
- * @param obs
- * @returns
+ * Convenience function equivalent to applying {@link filterTransitionSuccess} as a pipe operator.
+ *
+ * @param obs - The source observable of router transition events.
+ * @returns An observable that emits only successful transition events.
+ *
+ * @see {@link filterTransitionSuccess}
  */
 function successTransition(obs) {
     return obs.pipe(filterTransitionSuccess());
 }
+/**
+ * RxJS operator that filters transition events to only pass through successful transitions.
+ *
+ * @returns A `MonoTypeOperatorFunction` that filters for {@link DbxRouterTransitionEventType.SUCCESS} events.
+ *
+ * @see {@link filterTransitionEvent}
+ */
 function filterTransitionSuccess() {
     return filterTransitionEvent(DbxRouterTransitionEventType.SUCCESS);
 }
+/**
+ * RxJS operator that filters transition events to only pass through events of the specified type.
+ *
+ * @param type - The transition event type to filter for.
+ * @returns A `MonoTypeOperatorFunction` that only passes matching events.
+ */
 function filterTransitionEvent(type) {
     return filter((x) => x.type === type);
 }
 /**
- * Creates a new observable that uses the input DbxRouterTransitionService and DbxRouterService to determine whether or not any of the configured routes are active.
+ * Creates an observable that emits the list of currently active routes after each successful transition.
  *
- * @param obs
- * @param config
- * @returns
+ * On each successful router transition, checks all configured routes against the router service
+ * and emits an array of those that are active. The result is deduplicated by index and shared.
+ *
+ * @typeParam T - The route configuration type, extending {@link LatestSuccessfulRoutesConfigRoute}.
+ * @param config - Configuration specifying the router services and routes to monitor.
+ * @returns An observable emitting an array of the currently active route configurations.
+ *
+ * @see {@link LatestSuccessfulRoutesConfig}
+ * @see {@link isLatestSuccessfulRoute} for a boolean variant
  */
 function latestSuccessfulRoutes(config) {
     const { dbxRouterTransitionService, dbxRouterService, routes: inputRoutes } = config;
@@ -3661,11 +5397,16 @@ function latestSuccessfulRoutes(config) {
     }), distinctUntilKeysChange((x) => x.i), map((x) => x.map((y) => y.r)), shareReplay(1));
 }
 /**
- * Creates a new observable that uses the input DbxRouterTransitionService and DbxRouterService to determine whether or not any of the configured routes are active.
+ * Creates an observable that emits `true` when any of the configured routes are active after a successful transition,
+ * and `false` otherwise.
  *
- * @param obs
- * @param config
- * @returns
+ * This is a simplified boolean variant of {@link latestSuccessfulRoutes}.
+ *
+ * @param config - Configuration specifying the router services, routes, and match mode.
+ * @returns An observable emitting `true` when at least one configured route is active, `false` otherwise.
+ *
+ * @see {@link IsLatestSuccessfulRouteConfig}
+ * @see {@link latestSuccessfulRoutes} for the full route list variant
  */
 function isLatestSuccessfulRoute(config) {
     const { dbxRouterTransitionService, dbxRouterService, activeExactly } = config;
@@ -3678,11 +5419,29 @@ function isLatestSuccessfulRoute(config) {
 }
 
 /**
- * Abstract directive that listens to onSuccess transition events and runs a function.
+ * Abstract directive that provides observables for reacting to successful router transitions.
+ *
+ * Subclasses can subscribe to `transitionSuccess$` to react to each successful navigation,
+ * or use `initAndUpdateOnTransitionSuccess$` which also emits once immediately on initialization.
+ *
+ * @example
+ * ```ts
+ * @Directive({ selector: '[myTransitionHandler]' })
+ * class MyTransitionHandlerDirective extends AbstractTransitionDirective {
+ *   readonly data$ = this.initAndUpdateOnTransitionSuccess$.pipe(
+ *     switchMap(() => this.loadData())
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link AbstractTransitionWatcherDirective} for a variant that automatically calls a callback
+ * @see {@link DbxRouterTransitionService}
  */
 class AbstractTransitionDirective {
     dbxRouterTransitionService = inject(DbxRouterTransitionService);
+    /** Observable that emits on each successful router transition. */
     transitionSuccess$ = successTransition(this.dbxRouterTransitionService.transitions$);
+    /** Observable that emits immediately on initialization and on each subsequent successful transition. */
     initAndUpdateOnTransitionSuccess$ = this.transitionSuccess$.pipe(startWith(undefined));
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: AbstractTransitionDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
     static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.0", type: AbstractTransitionDirective, isStandalone: true, ngImport: i0 });
@@ -3692,7 +5451,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Abstract directive that listens to onSuccess transition events and runs a function.
+ * Abstract directive that automatically calls {@link updateForSuccessfulTransition} on each successful router transition.
+ *
+ * Extends {@link AbstractTransitionDirective} by subscribing to successful transitions during construction
+ * and invoking the abstract `updateForSuccessfulTransition()` method for each one.
+ *
+ * Also provides a `zoneUpdateForSuccessfulTransition()` method that wraps the update call in `NgZone.run()`.
+ *
+ * @example
+ * ```ts
+ * @Directive({ selector: '[myRouteWatcher]' })
+ * class MyRouteWatcherDirective extends AbstractTransitionWatcherDirective {
+ *   protected updateForSuccessfulTransition(): void {
+ *     console.log('Route changed successfully');
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link AbstractTransitionDirective}
  */
 class AbstractTransitionWatcherDirective extends AbstractTransitionDirective {
     ngZone = inject(NgZone);
@@ -3716,10 +5492,15 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * Creates an IsSegueRefActiveFunction
+ * Creates an {@link IsSegueRefActiveFunction} from the given configuration.
  *
- * @param config
- * @returns
+ * The returned function checks whether the configured segue ref is active in the router each time it is called.
+ * When `activeExactly` is `true`, uses `isActiveExactly`; otherwise uses `isActive`.
+ *
+ * @param config - The configuration containing the router service, segue ref, and match mode.
+ * @returns A callable function that returns `true` when the route is active.
+ *
+ * @see {@link IsSegueRefActiveFunctionConfig}
  */
 function isSegueRefActiveFunction(config) {
     const { dbxRouterService, segueRef, activeExactly = false } = config;
@@ -3730,9 +5511,24 @@ function isSegueRefActiveFunction(config) {
 }
 
 // MARK: Transition Events
+/**
+ * Filters the given transition event observable to only emit events of the specified type.
+ *
+ * @param events$ - The source observable of router transition events.
+ * @param type - The transition event type to filter for.
+ * @returns An observable that emits only events matching the given type.
+ */
 function onRouterTransitionEventType(events$, type) {
     return events$.pipe(filter((x) => x.type === type));
 }
+/**
+ * Filters the given transition event observable to only emit successful transition events.
+ *
+ * @param events$ - The source observable of router transition events.
+ * @returns An observable that emits only {@link DbxRouterTransitionEventType.SUCCESS} events.
+ *
+ * @see {@link onRouterTransitionEventType}
+ */
 function onRouterTransitionSuccessEvent(events$) {
     return onRouterTransitionEventType(events$, DbxRouterTransitionEventType.SUCCESS);
 }
@@ -3812,7 +5608,24 @@ function dbxRouteParamReaderInstance(dbxRouterService, defaultParamKey, defaultV
 
 const DEFAULT_REDIRECT_INSTANCE_FORWARD_FACTORY = defaultForwardFunctionFactory((value) => of(value == null));
 /**
- * Utility class used in conjuction with a DbxRouteParamReaderInstance to redirect when the default param is not valid.
+ * Utility class that works with a {@link DbxRouteParamReaderInstance} to automatically redirect the router
+ * when the current parameter value is determined to require a default substitution.
+ *
+ * When enabled and initialized, it monitors the parameter value and, if the configured filter function
+ * indicates the value should be replaced, updates the route to use the default value instead.
+ *
+ * @typeParam T - The type of the parameter value.
+ *
+ * @example
+ * ```ts
+ * const paramReader = dbxRouteParamReaderInstance<string>(routerService, 'id');
+ * const redirect = new DbxRouteParamDefaultRedirectInstance(paramReader);
+ * redirect.setUseDefaultFilter(value => of(value === '0'));
+ * redirect.init();
+ * ```
+ *
+ * @see {@link DbxRouteParamReaderInstance}
+ * @see {@link dbxRouteModelIdParamRedirect} for the model-specific usage pattern
  */
 class DbxRouteParamDefaultRedirectInstance {
     instance;
@@ -3882,9 +5695,34 @@ const DBX_ROUTE_MODEL_ID_PARAM_DEFAULT_KEY_PARAM_KEY = 'key';
  * Default value used by dbxRouteModelIdParamRedirect() for when a value is not available or provided.
  */
 const DBX_ROUTE_MODEL_ID_PARAM_DEFAULT_USE_PARAM_VALUE = '0';
+/**
+ * Creates a {@link DbxRouteModelIdParamRedirectInstance} configured to read a "key" parameter from the current route.
+ *
+ * This is a convenience wrapper around {@link dbxRouteModelIdParamRedirect} that defaults the parameter key to `'key'`.
+ *
+ * @param dbxRouterService - The router service to read parameters from.
+ * @param defaultParamKey - The route parameter key to read. Defaults to `'key'`.
+ * @returns A new redirect instance.
+ *
+ * @see {@link dbxRouteModelIdParamRedirect}
+ */
 function dbxRouteModelKeyParamRedirect(dbxRouterService, defaultParamKey = DBX_ROUTE_MODEL_ID_PARAM_DEFAULT_KEY_PARAM_KEY) {
     return dbxRouteModelIdParamRedirect(dbxRouterService, defaultParamKey);
 }
+/**
+ * Creates a {@link DbxRouteModelIdParamRedirectInstance} that reads a model identifier from the current route
+ * and optionally redirects when the value matches a placeholder (defaulting to `'0'`).
+ *
+ * The instance must be initialized via `init()` to activate the redirect behavior, and destroyed via `destroy()`
+ * when no longer needed.
+ *
+ * @param dbxRouterService - The router service to read parameters from and perform redirects with.
+ * @param defaultParamKey - The route parameter key to read. Defaults to `'id'`.
+ * @returns A new redirect instance.
+ *
+ * @see {@link DbxRouteModelIdParamRedirectInstance}
+ * @see {@link dbxRouteModelKeyParamRedirect} for the key-based variant
+ */
 function dbxRouteModelIdParamRedirect(dbxRouterService, defaultParamKey = DBX_ROUTE_MODEL_ID_PARAM_DEFAULT_ID_PARAM_KEY) {
     const _paramReader = dbxRouteParamReaderInstance(dbxRouterService, defaultParamKey);
     const _paramRedirect = new DbxRouteParamDefaultRedirectInstance(_paramReader);
@@ -3943,12 +5781,37 @@ function dbxRouteModelIdParamRedirect(dbxRouterService, defaultParamKey = DBX_RO
 
 // MARK: Id
 /**
- * DbxRouteModelIdDirective delegate that can recieve an observable of the model id from the route.
+ * Abstract delegate that receives model identifier observables from a {@link DbxRouteModelIdDirective}.
+ *
+ * Implement this class and register it as a provider to receive the id parameter read from the current route.
+ * The directive will call {@link useRouteModelIdParamsObservable} during initialization.
+ *
+ * @example
+ * ```ts
+ * @Directive({
+ *   selector: '[myModelLoader]',
+ *   providers: provideDbxRouteModelIdDirectiveDelegate(MyModelLoaderDirective)
+ * })
+ * class MyModelLoaderDirective extends DbxRouteModelIdDirectiveDelegate {
+ *   useRouteModelIdParamsObservable(idFromParams$: Observable<Maybe<ModelKey>>, computedId$: Observable<Maybe<ModelKey>>): Subscription {
+ *     return computedId$.subscribe(id => this.loadModel(id));
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link DbxRouteModelIdDirective} for the directive that provides the id observables
+ * @see {@link provideDbxRouteModelIdDirectiveDelegate} for registering the delegate provider
  */
 class DbxRouteModelIdDirectiveDelegate {
 }
 /**
- * Configures providers for a DbxRouteModelIdDirectiveDelegate.
+ * Creates Angular DI providers that register the given source type as a {@link DbxRouteModelIdDirectiveDelegate}.
+ *
+ * @typeParam S - The concrete delegate class type to register.
+ * @param sourceType - The class to provide as the delegate.
+ * @returns An array of Angular providers.
+ *
+ * @see {@link DbxRouteModelIdDirectiveDelegate}
  */
 function provideDbxRouteModelIdDirectiveDelegate(sourceType) {
     const providers = [
@@ -3961,12 +5824,37 @@ function provideDbxRouteModelIdDirectiveDelegate(sourceType) {
 }
 // MARK: Key
 /**
- * DbxRouteModelKeyDirective delegate that can recieve an observable of the model id from the route.
+ * Abstract delegate that receives model key observables from a {@link DbxRouteModelKeyDirective}.
+ *
+ * Implement this class and register it as a provider to receive the key parameter read from the current route.
+ * The directive will call {@link useRouteModelKeyParamsObservable} during initialization.
+ *
+ * @example
+ * ```ts
+ * @Directive({
+ *   selector: '[myModelKeyLoader]',
+ *   providers: provideDbxRouteModelKeyDirectiveDelegate(MyModelKeyLoaderDirective)
+ * })
+ * class MyModelKeyLoaderDirective extends DbxRouteModelKeyDirectiveDelegate {
+ *   useRouteModelKeyParamsObservable(keyFromParams$: Observable<Maybe<ModelKey>>, computedKey$: Observable<Maybe<ModelKey>>): Subscription {
+ *     return computedKey$.subscribe(key => this.loadModel(key));
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link DbxRouteModelKeyDirective} for the directive that provides the key observables
+ * @see {@link provideDbxRouteModelKeyDirectiveDelegate} for registering the delegate provider
  */
 class DbxRouteModelKeyDirectiveDelegate {
 }
 /**
- * Configures providers for a DbxRouteModelKeyDirectiveDelegate.
+ * Creates Angular DI providers that register the given source type as a {@link DbxRouteModelKeyDirectiveDelegate}.
+ *
+ * @typeParam S - The concrete delegate class type to register.
+ * @param sourceType - The class to provide as the delegate.
+ * @returns An array of Angular providers.
+ *
+ * @see {@link DbxRouteModelKeyDirectiveDelegate}
  */
 function provideDbxRouteModelKeyDirectiveDelegate(sourceType) {
     const providers = [
@@ -3979,7 +5867,19 @@ function provideDbxRouteModelKeyDirectiveDelegate(sourceType) {
 }
 
 /**
- * Used for retrieving the user's current id DbxAuthService and passes it as an identifier for a DbxRouteModelIdDirectiveDelegate.
+ * Directive that retrieves the currently authenticated user's identifier from {@link DbxAuthService}
+ * and passes it directly to a {@link DbxRouteModelIdDirectiveDelegate}.
+ *
+ * This is useful for routes that should always use the current user's ID, bypassing route parameter reading entirely.
+ *
+ * @example
+ * ```html
+ * <!-- Automatically provides the authenticated user's ID to the delegate -->
+ * <div dbxRouteModelIdFromAuthUserId></div>
+ * ```
+ *
+ * @see {@link DbxRouteModelIdDirectiveDelegate} for the delegate that receives the id observables
+ * @see {@link DbxAuthService} for the authentication service providing the user identifier
  */
 class DbxRouteModelIdFromAuthUserIdDirective {
     dbxAuthService = inject(DbxAuthService);
@@ -3999,7 +5899,25 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * Used for retrieving the model's id from the current route using the configured parameter and passes it to its delegate.
+ * Directive that reads a model identifier from the current route's parameters and passes it to a {@link DbxRouteModelIdDirectiveDelegate}.
+ *
+ * Supports configurable parameter key, default value, redirect behavior, and custom decision logic for determining
+ * when to use the default value vs. the route parameter.
+ *
+ * @example
+ * ```html
+ * <!-- Basic usage: reads "id" param from route and passes to delegate -->
+ * <div dbxRouteModelId></div>
+ *
+ * <!-- Custom param key -->
+ * <div [dbxRouteModelId]="'modelId'"></div>
+ *
+ * <!-- With default value and redirect disabled -->
+ * <div dbxRouteModelId [dbxRouteModelIdDefault]="defaultId$" [dbxRouteModelIdDefaultRedirect]="false"></div>
+ * ```
+ *
+ * @see {@link DbxRouteModelIdDirectiveDelegate} for the delegate that receives the id observables
+ * @see {@link dbxRouteModelIdParamRedirect} for the underlying redirect logic
  */
 class DbxRouteModelIdDirective {
     dbxRouterService = inject(DbxRouterService);
@@ -4051,9 +5969,26 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
             }] } });
 
 /**
- * Used for retrieving the model's key from the current route using the configured parameter and passes it to its delegate.
+ * Directive that reads a model key from the current route's parameters and passes it to a {@link DbxRouteModelKeyDirectiveDelegate}.
+ *
+ * Functions identically to {@link DbxRouteModelIdDirective} but uses a "key" parameter (defaulting to `'key'`)
+ * instead of "id". Supports configurable parameter key, default value, redirect behavior, and custom decision logic.
+ *
+ * @example
+ * ```html
+ * <!-- Basic usage: reads "key" param from route and passes to delegate -->
+ * <div dbxRouteModelKey></div>
  *
- * If the key does not exist in the params, then the p
+ * <!-- Custom param key -->
+ * <div [dbxRouteModelKey]="'slug'"></div>
+ *
+ * <!-- With default value and redirect disabled -->
+ * <div dbxRouteModelKey [dbxRouteModelKeyDefault]="defaultKey$" [dbxRouteModelKeyDefaultRedirect]="false"></div>
+ * ```
+ *
+ * @see {@link DbxRouteModelKeyDirectiveDelegate} for the delegate that receives the key observables
+ * @see {@link dbxRouteModelKeyParamRedirect} for the underlying redirect logic
+ * @see {@link DbxRouteModelIdDirective} for the id-based equivalent
  */
 class DbxRouteModelKeyDirective {
     dbxRouterService = inject(DbxRouterService);
@@ -4105,7 +6040,15 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
             }] } });
 
 /**
- * Pipes an ObservableOrValueGetter to an Observable value.
+ * Converts an {@link ObservableOrValueGetter} into an {@link Observable}.
+ *
+ * Useful for normalizing values that may be plain values, getter functions, or Observables
+ * into a consistent Observable stream for use with the `async` pipe.
+ *
+ * @example
+ * ```html
+ * <span>{{ valueOrGetter | asObservable | async }}</span>
+ * ```
  */
 class AsObservablePipe {
     transform(input) {
@@ -4122,6 +6065,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Formats a {@link DateRange} as a human-readable day range string using {@link formatToDayRangeString}.
+ *
+ * Displays only the date portion (no times). Returns a fallback string when the input is `null` or `undefined`.
+ *
+ * @example
+ * ```html
+ * <span>{{ dateRange | dateDayRange }}</span>
+ * <!-- Output: "Jan 5 - Jan 8" -->
+ *
+ * <span>{{ nullRange | dateDayRange:'No dates' }}</span>
+ * <!-- Output: "No dates" -->
+ * ```
+ */
 class DateDayRangePipe {
     transform(input, unavailable = 'Not Available') {
         if (input) {
@@ -4143,6 +6100,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Converts a {@link DateOrDateString} value to a JavaScript {@link Date} object using {@link toJsDate}.
+ *
+ * Returns `undefined` if the input is `null`, `undefined`, or results in an invalid date.
+ * Also provides a static `toJsDate()` method used by other pipes in this package.
+ *
+ * @example
+ * ```html
+ * <span>{{ '2024-01-05T12:00:00Z' | toJsDate | date:'short' }}</span>
+ * <!-- Output: "1/5/24, 12:00 PM" -->
+ *
+ * <span>{{ dateOrString | toJsDate | date:'fullDate' }}</span>
+ * ```
+ */
 class ToJsDatePipe {
     static toJsDate(input) {
         let date;
@@ -4169,6 +6140,23 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Formats a date as a human-readable distance string relative to another date (or now) using {@link formatDateDistance}.
+ *
+ * Accepts an optional comparison date (defaults to now) and a fallback string for `null`/`undefined` input.
+ *
+ * @example
+ * ```html
+ * <span>{{ someDate | dateDistance }}</span>
+ * <!-- Output: "3 hours ago" -->
+ *
+ * <span>{{ someDate | dateDistance:referenceDate }}</span>
+ * <!-- Output: "2 days ago" -->
+ *
+ * <span>{{ nullDate | dateDistance:null:'Unknown' }}</span>
+ * <!-- Output: "Unknown" -->
+ * ```
+ */
 class DateDistancePipe {
     transform(input, inputTo, unavailable = 'Not Available') {
         if (input != null) {
@@ -4193,7 +6181,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Pipe that takes in a date and appends the distance to it in parenthesis.
+ * Formats a date using a locale-aware format string and appends the relative distance to now in parentheses.
+ *
+ * Returns `undefined` if the input is falsy or not a valid date.
+ *
+ * @example
+ * ```html
+ * <span>{{ someDate | dateFormatDistance:'MMM d, y' }}</span>
+ * <!-- Output: "Jan 5, 2024 (3 days ago)" -->
+ *
+ * <span>{{ someDate | dateFormatDistance:'short':true }}</span>
+ * <!-- Output: "1/5/24, 2:30 PM (about 3 days ago)" with includeSeconds enabled -->
+ * ```
  */
 class DateFormatDistancePipe {
     locale = inject(LOCALE_ID);
@@ -4224,7 +6223,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Pipe that takes in a date and number of minutes and outputs a formatted date.
+ * Formats a date as a "from - to" time range string given a start date, format string, and duration in minutes.
+ *
+ * The start date is formatted using the Angular locale-aware {@link formatDate}, and the end time
+ * is computed by adding the given minutes and formatted as a time-only string.
+ *
+ * @example
+ * ```html
+ * <span>{{ eventStart | dateFormatFromTo:'MMM d, h:mm a':90 }}</span>
+ * <!-- Output: "Jan 5, 2:00 PM - 3:30 PM" -->
+ * ```
  */
 class DateFormatFromToPipe {
     locale = inject(LOCALE_ID);
@@ -4252,6 +6260,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Formats a {@link DateRange} as a human-readable day and time range string using {@link formatToDayTimeRangeString}.
+ *
+ * Includes both the date and time portions. Returns a fallback string when the input is `null` or `undefined`.
+ *
+ * @example
+ * ```html
+ * <span>{{ dateRange | dateDayTimeRange }}</span>
+ * <!-- Output: "Jan 5, 2:00 PM - Jan 8, 4:00 PM" -->
+ *
+ * <span>{{ nullRange | dateDayTimeRange:'No dates' }}</span>
+ * <!-- Output: "No dates" -->
+ * ```
+ */
 class DateDayTimeRangePipe {
     transform(input, unavailable = 'Not Available') {
         if (input) {
@@ -4273,6 +6295,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Formats a {@link DateRange} as a time range string using {@link formatToTimeRangeString}.
+ *
+ * Displays the date and time of both the start and end. Returns a fallback string when the input is `null` or `undefined`.
+ *
+ * @example
+ * ```html
+ * <span>{{ dateRange | dateTimeRange }}</span>
+ * <!-- Output: "Jan 5, 2:00 PM - 4:00 PM" -->
+ *
+ * <span>{{ nullRange | dateTimeRange:'TBD' }}</span>
+ * <!-- Output: "TBD" -->
+ * ```
+ */
 class DateTimeRangePipe {
     transform(input, unavailable = 'Not Available') {
         if (input) {
@@ -4294,6 +6330,21 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Formats a {@link Date} or {@link DateRange} as a human-readable distance string relative to now using {@link formatDateDistance}.
+ *
+ * This is an impure pipe that recalculates on every change detection cycle to keep the distance up to date.
+ * Returns a fallback string when the input is `null` or `undefined`.
+ *
+ * @example
+ * ```html
+ * <span>{{ someDate | dateRangeDistance }}</span>
+ * <!-- Output: "3 hours ago" -->
+ *
+ * <span>{{ nullDate | dateRangeDistance:'Unknown' }}</span>
+ * <!-- Output: "Unknown" -->
+ * ```
+ */
 class DateRangeDistancePipe {
     transform(input, unavailable = 'Not Available') {
         if (input != null) {
@@ -4315,6 +6366,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Formats a {@link DateRange} as a time-only range string using {@link formatToTimeRangeString} with the time-only flag enabled.
+ *
+ * Displays only the time portion (no date). Returns a fallback string when the input is `null` or `undefined`.
+ *
+ * @example
+ * ```html
+ * <span>{{ dateRange | dateTimeRangeOnly }}</span>
+ * <!-- Output: "2:00 PM - 4:00 PM" -->
+ *
+ * <span>{{ nullRange | dateTimeRangeOnly:'TBD' }}</span>
+ * <!-- Output: "TBD" -->
+ * ```
+ */
 class DateTimeRangeOnlyPipe {
     transform(input, unavailable = 'Not Available') {
         if (input) {
@@ -4337,7 +6402,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Converts the input date and timezone to a system date that represents that date/time.
+ * Converts a target timezone date back to the equivalent system (UTC-based) date using {@link dateTimezoneUtcNormal}.
+ *
+ * This is the inverse of {@link SystemDateToTargetDatePipe}. Useful when you have a date representing
+ * local time in a target timezone and need to convert it back to the system timezone.
+ * Returns `undefined` if either the input date or timezone is falsy.
+ *
+ * @example
+ * ```html
+ * <span>{{ targetDate | targetDateToSystemDate:'America/New_York' | date:'short' }}</span>
+ * <!-- Output: the date/time converted back to the system timezone -->
+ * ```
  */
 class TargetDateToSystemDatePipe {
     transform(input, timezone) {
@@ -4360,6 +6435,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Formats a {@link DateRange} as a human-readable distance string using {@link formatDateRangeDistance}.
+ *
+ * Accepts an optional {@link FormatDateRangeDistanceFunctionConfig} to customize the output format.
+ * Returns a fallback string when the input is `null` or `undefined`.
+ *
+ * @example
+ * ```html
+ * <span>{{ dateRange | dateTimeRangeOnlyDistance }}</span>
+ * <!-- Output: "3 hours" -->
+ *
+ * <span>{{ dateRange | dateTimeRangeOnlyDistance:config }}</span>
+ * <!-- Output varies based on config -->
+ *
+ * <span>{{ nullRange | dateTimeRangeOnlyDistance:null:'TBD' }}</span>
+ * <!-- Output: "TBD" -->
+ * ```
+ */
 class DateTimeRangeOnlyDistancePipe {
     transform(input, config, unavailable = 'Not Available') {
         if (input) {
@@ -4382,7 +6475,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Converts the input date and timezone to the proper abbreviation. Uses the input date for the context, or uses now.
+ * Returns the abbreviated name for a timezone string (e.g., "EST", "PDT") using {@link getTimezoneAbbreviation}.
+ *
+ * Optionally accepts a reference date to determine the correct abbreviation (e.g., for daylight saving time).
+ * Defaults to the current date if no reference date is provided.
+ * Returns `undefined` if the timezone is falsy.
+ *
+ * @example
+ * ```html
+ * <span>{{ 'America/New_York' | timezoneAbbreviation }}</span>
+ * <!-- Output: "EST" or "EDT" depending on the current date -->
+ *
+ * <span>{{ timezone | timezoneAbbreviation:referenceDate }}</span>
+ * <!-- Output: abbreviation for the timezone at the given reference date -->
+ * ```
  */
 class TimezoneAbbreviationPipe {
     transform(timezone, input) {
@@ -4406,7 +6512,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Converts the input date and timezone to a target date that represents that date/time for the timezone.
+ * Converts a system (UTC-based) date to the equivalent local date in the given timezone using {@link dateTimezoneUtcNormal}.
+ *
+ * This is useful when you have a date in the system's timezone and need to display it as if it were in the target timezone.
+ * Returns `undefined` if either the input date or timezone is falsy.
+ *
+ * @example
+ * ```html
+ * <span>{{ systemDate | systemDateToTargetDate:'America/New_York' | date:'short' }}</span>
+ * <!-- Output: the date/time as it appears in the New York timezone -->
+ * ```
  */
 class SystemDateToTargetDatePipe {
     transform(input, timezone) {
@@ -4429,6 +6544,27 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Converts a numeric minute value into a human-readable duration string with automatic unit scaling.
+ *
+ * - Values over 3600 minutes are displayed as days (e.g., "~2 days")
+ * - Values over 180 minutes are displayed as hours (e.g., "~4 hours")
+ * - Values at or below 180 minutes are displayed as minutes (e.g., "90 minutes")
+ *
+ * A `~` prefix is added when the value is rounded up. Returns `undefined` for `null` or non-numeric input.
+ *
+ * @example
+ * ```html
+ * <span>{{ 90 | minutesString }}</span>
+ * <!-- Output: "90 minutes" -->
+ *
+ * <span>{{ 250 | minutesString }}</span>
+ * <!-- Output: "~5 hours" -->
+ *
+ * <span>{{ 5000 | minutesString }}</span>
+ * <!-- Output: "~2 days" -->
+ * ```
+ */
 class MinutesStringPipe {
     transform(input) {
         const minutes = Number(input);
@@ -4463,6 +6599,22 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Formats the distance from now to a future date as a countdown string.
+ *
+ * If the target date is in the past, returns the `soonString` (defaults to `"Soon"`).
+ * Otherwise, returns a human-readable distance string with suffix (e.g., "in 3 hours").
+ * Returns the `unavailable` string when the input is falsy.
+ *
+ * @example
+ * ```html
+ * <span>{{ futureDate | timeCountdownDistance }}</span>
+ * <!-- Output: "in 3 hours" or "Soon" if past -->
+ *
+ * <span>{{ futureDate | timeCountdownDistance:'Imminent':'N/A' }}</span>
+ * <!-- Output: "Imminent" if past, "N/A" if null -->
+ * ```
+ */
 class TimeDistanceCountdownPipe {
     transform(input, soonString = 'Soon', unavailable = 'Not Available') {
         if (input) {
@@ -4492,6 +6644,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                     pure: false
                 }]
         }] });
+/**
+ * Formats the distance between a date and a reference date (defaults to now) as a human-readable string with suffix.
+ *
+ * Uses date-fns {@link formatDistance} to produce output like "3 hours ago" or "in 2 days".
+ * Returns the `unavailable` string when the input is falsy.
+ *
+ * @example
+ * ```html
+ * <span>{{ someDate | timeDistance }}</span>
+ * <!-- Output: "3 hours ago" -->
+ *
+ * <span>{{ someDate | timeDistance:referenceDate }}</span>
+ * <!-- Output: "2 days ago" (relative to referenceDate) -->
+ *
+ * <span>{{ nullDate | timeDistance:null:'Unknown' }}</span>
+ * <!-- Output: "Unknown" -->
+ * ```
+ */
 class TimeDistancePipe {
     transform(input, to, unavailable = 'Not Available') {
         if (input) {
@@ -4516,6 +6686,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Converts a duration in milliseconds to whole minutes by dividing by 60,000 and flooring the result.
+ *
+ * Returns the original value (0 or falsy) if the input is falsy.
+ *
+ * @example
+ * ```html
+ * <span>{{ 180000 | toMinutes }}</span>
+ * <!-- Output: 3 -->
+ *
+ * <span>{{ durationMs | toMinutes }} min</span>
+ * <!-- Output: "5 min" -->
+ * ```
+ */
 class ToMinutesPipe {
     transform(milliseconds) {
         if (milliseconds) {
@@ -4535,6 +6719,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Formats a value as a pretty-printed JSON string using {@link JSON.stringify} with configurable indentation.
+ *
+ * Returns `undefined` for falsy input. If serialization fails, returns `'ERROR'` and logs the error to the console.
+ *
+ * @example
+ * ```html
+ * <pre>{{ myObject | prettyjson }}</pre>
+ * <!-- Output: formatted JSON with 2-space indentation -->
+ *
+ * <pre>{{ myObject | prettyjson:4 }}</pre>
+ * <!-- Output: formatted JSON with 4-space indentation -->
+ * ```
+ */
 class PrettyJsonPipe {
     static toPrettyJson(input, spacing = 2) {
         let json;
@@ -4564,7 +6762,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Pipe that cuts the input text to the requested length and adds elipsis.
+ * Truncates the input string to a maximum length and appends an ellipsis (or custom suffix) using {@link cutString}.
+ *
+ * Returns the original value if the input is `null` or `undefined`.
+ *
+ * @example
+ * ```html
+ * <span>{{ 'Hello World' | cutText:5 }}</span>
+ * <!-- Output: "Hello..." -->
+ *
+ * <span>{{ longText | cutText:20:'--' }}</span>
+ * <!-- Output: "Some long text here--" -->
+ * ```
  */
 class CutTextPipe {
     transform(input, maxLength, endText) {
@@ -4583,7 +6792,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Retrieves the value from the getter. This is a non-pure pipe. Use the getValueOncePipe instead for a pure pipe.
+ * Resolves a {@link GetterOrValue} to its underlying value using {@link getValueFromGetter}.
+ *
+ * This is an impure pipe that re-evaluates on every change detection cycle, making it suitable
+ * for getter functions whose return value may change over time.
+ * Use {@link GetValueOncePipe} (`getValueOnce`) for a pure alternative when the value is static.
+ *
+ * @example
+ * ```html
+ * <span>{{ myGetterOrValue | getValue }}</span>
+ * <span>{{ myGetterFn | getValue:someArg }}</span>
+ * ```
  */
 class GetValuePipe {
     transform(input, args) {
@@ -4601,7 +6820,15 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 /**
- * Pipes a GetValuePipe to an Observable value.
+ * Resolves a {@link GetterOrValue} to its underlying value using {@link getValueFromGetter}.
+ *
+ * This is a pure pipe that only re-evaluates when the input reference changes.
+ * Use {@link GetValuePipe} (`getValue`) if the getter function's return value may change between cycles.
+ *
+ * @example
+ * ```html
+ * <span>{{ myGetterOrValue | getValueOnce }}</span>
+ * ```
  */
 class GetValueOncePipe {
     transform(input, args) {
@@ -4620,9 +6847,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Pipe that takes in a number and returns the number formatted as a dollar using dollarAmountString().
+ * Formats a numeric value as a US dollar currency string using {@link dollarAmountString}.
+ *
+ * Optionally accepts a default string to display when the input is `null` or `undefined`.
+ *
+ * @example
+ * ```html
+ * <span>{{ 19.5 | dollarAmount }}</span>
+ * <!-- Output: "$19.50" -->
  *
- * Can provide a default string value to use when the input is null or undefined.
+ * <span>{{ nullValue | dollarAmount:'N/A' }}</span>
+ * <!-- Output: "N/A" -->
+ * ```
  */
 class DollarAmountPipe {
     transform(input, defaultIfNull) {
@@ -4641,7 +6877,19 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Abstract FilterSourceConnector directive.
+ * Abstract directive implementing both {@link FilterSourceConnector} and {@link FilterSource}.
+ *
+ * Receives a filter source via {@link connectWithSource} and re-emits its filter values.
+ * Subclass to create concrete connector directives.
+ *
+ * @typeParam F - The filter type.
+ *
+ * @example
+ * ```html
+ * <div dbxFilterSourceConnector>
+ *   <!-- Child components can inject FilterSource to read the connected filter -->
+ * </div>
+ * ```
  */
 class AbstractFilterSourceConnectorDirective {
     _source = completeOnDestroy(new BehaviorSubject(undefined));
@@ -4657,7 +6905,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Angular provider convenience function for a FilterSource.
+ * Creates Angular providers that register a {@link FilterSource} implementation for DI.
+ *
+ * @param sourceType - The concrete filter source class to provide.
+ *
+ * @example
+ * ```typescript
+ * @Directive({
+ *   selector: '[myFilterSource]',
+ *   providers: provideFilterSource(MyFilterSourceDirective),
+ * })
+ * export class MyFilterSourceDirective { ... }
+ * ```
  */
 function provideFilterSource(sourceType) {
     return [
@@ -4668,7 +6927,9 @@ function provideFilterSource(sourceType) {
     ];
 }
 /**
- * Angular provider convenience function for a FilterSourceConnector.
+ * Creates Angular providers that register both a {@link FilterSourceConnector} and {@link FilterSource} for DI.
+ *
+ * @param sourceType - The concrete connector class to provide.
  */
 function provideFilterSourceConnector(sourceType) {
     return [
@@ -4683,11 +6944,32 @@ function provideFilterSourceConnector(sourceType) {
     ];
 }
 
+/**
+ * DI token for providing a default filter value to {@link AbstractFilterSourceDirective}.
+ */
 const FILTER_SOURCE_DIRECTIVE_DEFAULT_FILTER_TOKEN = new InjectionToken('FILTER_SOURCE_DIRECTIVE_DEFAULT_FILTER_SOURCE_TOKEN');
+/**
+ * Abstract class defining the contract for a filter source directive that can be set, reset, and initialized with filters.
+ *
+ * @typeParam F - The filter type.
+ */
 class FilterSourceDirective {
 }
 /**
- * Angular provider convenience function for a FilterSourceDirective.
+ * Creates Angular providers for a {@link FilterSourceDirective} implementation,
+ * with an optional factory for providing a default filter value.
+ *
+ * @param sourceType - The concrete directive class.
+ * @param defaultFilterFactory - Optional factory to provide an initial filter value via DI.
+ *
+ * @example
+ * ```typescript
+ * @Directive({
+ *   selector: '[myFilterSource]',
+ *   providers: provideFilterSourceDirective(MyFilterSourceDirective),
+ * })
+ * export class MyFilterSourceDirective extends AbstractFilterSourceDirective<MyFilter> {}
+ * ```
  */
 function provideFilterSourceDirective(sourceType, defaultFilterFactory) {
     const providers = [
@@ -4707,7 +6989,12 @@ function provideFilterSourceDirective(sourceType, defaultFilterFactory) {
     return providers;
 }
 /**
- * Abstract FilterSource implementation and directive.
+ * Abstract directive providing a complete {@link FilterSource} implementation backed by a {@link FilterSourceInstance}.
+ *
+ * Supports setting/resetting filters, initializing from an external observable, and providing
+ * a default filter via the {@link FILTER_SOURCE_DIRECTIVE_DEFAULT_FILTER_TOKEN} DI token.
+ *
+ * @typeParam F - The filter type.
  */
 class AbstractFilterSourceDirective {
     _defaultFilter = inject(FILTER_SOURCE_DIRECTIVE_DEFAULT_FILTER_TOKEN, { optional: true });
@@ -4742,7 +7029,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Connects the host FilterSource to a FilterSourceConnector.
+ * Connects the host element's {@link FilterSource} to an ancestor {@link FilterSourceConnector} on initialization.
+ *
+ * Place on an element that has a `FilterSource` (via `host: true`) to automatically
+ * wire it up to a parent `FilterSourceConnector`.
+ *
+ * @example
+ * ```html
+ * <div dbxFilterSourceConnector>
+ *   <my-filter-form dbxFilterSource dbxFilterConnectSource></my-filter-form>
+ * </div>
+ * ```
  */
 class DbxFilterConnectSourceDirective {
     filterSource = inject((FilterSource), { host: true });
@@ -4762,7 +7059,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Used as a FilterSource and FilterSourceConnector.
+ * Concrete directive that acts as both a {@link FilterSource} and {@link FilterSourceConnector}.
+ *
+ * Place on an element to bridge a filter source from one part of the template to another.
+ *
+ * @example
+ * ```html
+ * <div dbxFilterSourceConnector>
+ *   <my-list-component></my-list-component>
+ * </div>
+ * ```
  */
 class DbxFilterSourceConnectorDirective extends AbstractFilterSourceConnectorDirective {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: DbxFilterSourceConnectorDirective, deps: null, target: i0.ɵɵFactoryTarget.Directive });
@@ -4778,7 +7084,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Provides a FilterSource from a parent FilterMap.
+ * Abstract directive that resolves a specific filter instance from a parent {@link FilterMap} by key.
+ *
+ * Subclasses set the key via {@link setFilterMapKey} and access the resolved instance via `instance$`.
+ *
+ * @typeParam F - The filter type.
  */
 class AbstractDbxFilterMapInstanceDirective {
     dbxFilterMap = inject((FilterMap));
@@ -4799,7 +7109,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Abstract directive that extends AbstractDbxFilterMapInstanceDirective and implements FilterSource.
+ * Abstract directive that extends {@link AbstractDbxFilterMapInstanceDirective} to also implement {@link FilterSource},
+ * emitting the filter values from the resolved filter map instance.
+ *
+ * @typeParam F - The filter type.
  */
 class AbstractDbxFilterMapSourceDirective extends AbstractDbxFilterMapInstanceDirective {
     filter$ = this.instance$.pipe(switchMap((x) => x.filter$));
@@ -4813,7 +7126,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
             type: Directive
         }] });
 /**
- * Provides a FilterSource from a parent FilterMap.
+ * Concrete directive that provides a {@link FilterSource} from a keyed entry in a parent {@link FilterMap}.
+ *
+ * @example
+ * ```html
+ * <div dbxFilterMap>
+ *   <div [dbxFilterMapSource]="'listFilter'">
+ *     <my-filtered-list></my-filtered-list>
+ *   </div>
+ * </div>
+ * ```
  */
 class DbxFilterMapSourceDirective extends AbstractDbxFilterMapSourceDirective {
     dbxFilterMapSource = input(...(ngDevMode ? [undefined, { debugName: "dbxFilterMapSource" }] : []));
@@ -4832,7 +7154,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { dbxFilterMapSource: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxFilterMapSource", required: false }] }] } });
 
 /**
- * Acts as an "input" FilterSourceConnector for an FilterMap, as well as a source for the FilterSourceConnector.
+ * Directive that acts as both a {@link FilterSourceConnector} and {@link FilterSource} for a keyed entry in a parent {@link FilterMap}.
+ *
+ * Connects an external filter source to a specific filter map entry and re-emits that entry's filter.
+ *
+ * @example
+ * ```html
+ * <div dbxFilterMap>
+ *   <div [dbxFilterMapSourceConnector]="'myList'">
+ *     <my-list-component></my-list-component>
+ *   </div>
+ * </div>
+ * ```
  */
 class DbxFilterMapSourceConnectorDirective extends AbstractDbxFilterMapSourceDirective {
     dbxFilterMapSourceConnector = input(...(ngDevMode ? [undefined, { debugName: "dbxFilterMapSourceConnector" }] : []));
@@ -4860,7 +7193,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { dbxFilterMapSourceConnector: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxFilterMapSourceConnector", required: false }] }] } });
 
 /**
- * Direction that provides a FilterMap.
+ * Directive that provides a {@link FilterMap} instance for managing multiple named filter sources.
+ *
+ * Child directives like `dbxFilterMapSource` and `dbxFilterMapSourceConnector` look up this
+ * map via DI to register and retrieve filter instances by key.
+ *
+ * @example
+ * ```html
+ * <div dbxFilterMap>
+ *   <div [dbxFilterMapSource]="'listA'">...</div>
+ *   <div [dbxFilterMapSource]="'listB'">...</div>
+ * </div>
+ * ```
  */
 class DbxFilterMapDirective {
     filterMap = clean(inject((FilterMap)));
@@ -4877,15 +7221,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Type guard that checks if an object is a {@link ClickableFilterPreset}.
+ */
 function isClickableFilterPreset(preset) {
     return objectHasKey(preset, 'presetValue');
 }
+/**
+ * Type guard that checks if an object is a {@link ClickablePartialFilterPreset}.
+ */
 function isClickablePartialFilterPreset(preset) {
     return objectHasKeys(preset, ['partialPresetValue', 'isActive']);
 }
 
 /**
- * Basic filter source directive.
+ * Provides a {@link FilterSource} in the DI tree, allowing child components to inject and consume filter state.
+ *
+ * @example
+ * ```html
+ * <div dbxFilterSource>
+ *   <my-list-component></my-list-component>
+ * </div>
+ * ```
  */
 class DbxFilterSourceDirective extends AbstractFilterSourceDirective {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: DbxFilterSourceDirective, deps: null, target: i0.ɵɵFactoryTarget.Directive });
@@ -4914,12 +7271,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                 }]
         }] });
 
+/**
+ * Injection token used to provide arbitrary data to dynamically created components.
+ *
+ * Components created via {@link DbxInjectionComponentConfig} can inject this token
+ * to access the `data` property from their configuration.
+ *
+ * @example
+ * ```typescript
+ * // In a dynamically injected component:
+ * readonly data = inject(DBX_INJECTION_COMPONENT_DATA);
+ * ```
+ */
 const DBX_INJECTION_COMPONENT_DATA = new InjectionToken('DbxInjectionComponentConfigData');
 /**
- * Merges multiple configurations into a single configuration.
+ * Merges multiple partial {@link DbxInjectionComponentConfig} objects into a single configuration.
  *
- * @param configs
- * @returns
+ * Provider arrays are concatenated (not overwritten) so that all providers from all configs
+ * are preserved. All other properties are merged with later values taking precedence.
+ *
+ * @typeParam T - The component type for the configuration.
+ * @param configs - An array of partial configs (may contain `undefined`/`null` entries which are filtered out).
+ * @returns A single merged partial configuration.
  */
 function mergeDbxInjectionComponentConfigs(configs) {
     const providers = mergeArrays(filterMaybeArrayValues(configs).map((x) => x.providers));
@@ -4929,17 +7302,46 @@ function mergeDbxInjectionComponentConfigs(configs) {
 }
 
 /**
- * Merges the input providers into a single array.
+ * Flattens and merges multiple provider sources into a single `StaticProvider[]` array.
  *
- * @param providers
- * @returns
+ * Each argument can be a single `StaticProvider`, an array of providers, or `undefined`/`null`.
+ * All values are flattened into a single array with nullish entries removed.
+ *
+ * @param providers - Any number of provider values or arrays to merge.
+ * @returns A flat array of all non-nullish static providers.
+ *
+ * @example
+ * ```typescript
+ * const providers = mergeStaticProviders(
+ *   { provide: TOKEN_A, useValue: 'a' },
+ *   undefined,
+ *   [{ provide: TOKEN_B, useValue: 'b' }]
+ * );
+ * // Result: [{ provide: TOKEN_A, useValue: 'a' }, { provide: TOKEN_B, useValue: 'b' }]
+ * ```
  */
 function mergeStaticProviders(...providers) {
     return flattenArrayOrValueArray(providers);
 }
 
 /**
- * Instance used by components to inject content based on the configuration into the view.
+ * Core runtime engine for the dbx-injection system. Manages the lifecycle of dynamically injected
+ * components and templates within an Angular `ViewContainerRef`.
+ *
+ * This class reactively listens to configuration and template observables. When a new
+ * {@link DbxInjectionComponentConfig} or {@link DbxInjectionTemplateConfig} is emitted, it tears
+ * down the previous content and creates the new component or template in the target view container.
+ *
+ * Component configs take precedence over template configs when both are provided.
+ *
+ * Typically used internally by {@link AbstractDbxInjectionDirective} and {@link DbxInjectionComponent}
+ * rather than consumed directly.
+ *
+ * @typeParam T - The type of the dynamically created component.
+ *
+ * @see {@link DbxInjectionComponentConfig}
+ * @see {@link DbxInjectionTemplateConfig}
+ * @see {@link AbstractDbxInjectionDirective}
  */
 class DbxInjectionInstance {
     _subscriptionObject = new SubscriptionObject();
@@ -5055,7 +7457,16 @@ class DbxInjectionInstance {
 }
 
 /**
- * Abstract directive that injects content based on the configuration into the view.
+ * Abstract base directive for dynamically injecting components or templates into a view.
+ *
+ * Manages a {@link DbxInjectionInstance} lifecycle, initializing it on `ngOnInit` and
+ * destroying it on `ngOnDestroy`. Subclasses are responsible for wiring their inputs
+ * (config, template, content) to the corresponding setter methods.
+ *
+ * @typeParam T - The type of the dynamically created component.
+ *
+ * @see {@link DbxInjectionComponent} - The concrete standalone component implementation.
+ * @see {@link DbxInjectionInstance}
  */
 class AbstractDbxInjectionDirective {
     _instance = new DbxInjectionInstance(inject(Injector));
@@ -5065,12 +7476,27 @@ class AbstractDbxInjectionDirective {
     ngOnDestroy() {
         this._instance.destroy();
     }
+    /**
+     * Sets the component injection configuration on the underlying {@link DbxInjectionInstance}.
+     *
+     * @param config - The component config, observable, or getter to use.
+     */
     setConfig(config) {
         this._instance.config = config;
     }
+    /**
+     * Sets the template injection configuration on the underlying {@link DbxInjectionInstance}.
+     *
+     * @param template - The template config, observable, or getter to use.
+     */
     setTemplate(template) {
         this._instance.template = template;
     }
+    /**
+     * Sets the target `ViewContainerRef` where dynamic content will be inserted.
+     *
+     * @param content - The view container reference for content projection.
+     */
     setContent(content) {
         this._instance.content = content;
     }
@@ -5082,11 +7508,46 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Component that injects content based on the configuration into the view.
+ * Standalone component for dynamically injecting a component or template into the DOM.
+ *
+ * Accepts a {@link DbxInjectionComponentConfig} (to create a component) or a
+ * {@link DbxInjectionTemplateConfig} (to embed a template/view). When the config changes,
+ * the previous content is destroyed and the new content is created in its place.
+ *
+ * Can be used as an element (`<dbx-injection>`) or as an attribute directive
+ * (`[dbxInjection]` / `[dbx-injection]`).
+ *
+ * @typeParam T - The type of the dynamically created component.
+ *
+ * @example
+ * ```html
+ * <!-- Element usage with a component config -->
+ * <dbx-injection [config]="myComponentConfig"></dbx-injection>
+ *
+ * <!-- Element usage with a template config -->
+ * <dbx-injection [template]="myTemplateConfig"></dbx-injection>
+ *
+ * <!-- Attribute usage -->
+ * <div dbxInjection [config]="myComponentConfig"></div>
+ * ```
+ *
+ * @see {@link DbxInjectionComponentConfig}
+ * @see {@link DbxInjectionTemplateConfig}
+ * @see {@link AbstractDbxInjectionDirective}
  */
 class DbxInjectionComponent extends AbstractDbxInjectionDirective {
+    /**
+     * Reference to the internal view container where dynamic content is projected.
+     */
     content = viewChild('content', { ...(ngDevMode ? { debugName: "content" } : {}), read: ViewContainerRef });
+    /**
+     * The component injection configuration. Accepts an observable, getter, or static value.
+     */
     config = input(...(ngDevMode ? [undefined, { debugName: "config" }] : []));
+    /**
+     * The template injection configuration. Accepts an observable, getter, or static value.
+     * Only used when `config` is not provided.
+     */
     template = input(...(ngDevMode ? [undefined, { debugName: "template" }] : []));
     // allow signal writes for each as during their initialization they may write to a signal in some cases when initializing
     _contentEffect = effect(() => this.setContent(this.content()), ...(ngDevMode ? [{ debugName: "_contentEffect" }] : []));
@@ -5110,9 +7571,32 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { content: [{ type: i0.ViewChild, args: ['content', { ...{ read: ViewContainerRef }, isSignal: true }] }], config: [{ type: i0.Input, args: [{ isSignal: true, alias: "config", required: false }] }], template: [{ type: i0.Input, args: [{ isSignal: true, alias: "template", required: false }] }] } });
 
 /**
- * Component that injects content based on the configuration into the view.
+ * Renders a list of dynamically injected components from an array of {@link DbxInjectionArrayEntry} items.
+ *
+ * Each entry is tracked by its `key` property for efficient change detection, and rendered
+ * using a nested {@link DbxInjectionComponent}.
+ *
+ * @example
+ * ```html
+ * <dbx-injection-array [entries]="myEntries" />
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In the host component:
+ * myEntries: DbxInjectionArrayEntry[] = [
+ *   { key: 'chart', injectionConfig: { componentClass: ChartComponent } },
+ *   { key: 'table', injectionConfig: { componentClass: TableComponent } }
+ * ];
+ * ```
+ *
+ * @see {@link DbxInjectionArrayEntry}
+ * @see {@link DbxInjectionComponent}
  */
 class DbxInjectionArrayComponent {
+    /**
+     * The array of keyed injection entries to render. Each entry produces a `<dbx-injection>` component.
+     */
     entries = input(undefined, ...(ngDevMode ? [{ debugName: "entries" }] : []));
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: DbxInjectionArrayComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.0", type: DbxInjectionArrayComponent, isStandalone: true, selector: "dbx-injection-array", inputs: { entries: { classPropertyName: "entries", publicName: "entries", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `
@@ -5137,15 +7621,31 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { entries: [{ type: i0.Input, args: [{ isSignal: true, alias: "entries", required: false }] }] } });
 
 /**
- * View that can switch to show another arbitrary view, then switch back when the promise ends.
+ * Abstract service for temporarily replacing a view's content with a dynamically injected component,
+ * then restoring the original content when done.
+ *
+ * Unlike `*ngIf` or `*ngSwitch`, the original child content is **hidden** rather than destroyed,
+ * preserving component state. Once the injected context's promise resolves (or is reset), the
+ * original content is re-displayed.
  *
- * It is similar to *ngIf/*ngSwitch, but the original child content is retained instead of discarded,
- * and returns once the special context is done being used.
+ * This is useful for overlay-like workflows such as inline editors, confirmation dialogs,
+ * or multi-step flows where destroying and recreating the underlying view would lose state.
+ *
+ * @see {@link DbxInjectionContextConfig}
+ * @see {@link DbxInjectionContextDirective} - The concrete structural directive implementation.
  */
 class DbxInjectionContext {
 }
 /**
- * Allows a directive to provide a formly context and form.
+ * Creates Angular providers that register a concrete {@link DbxInjectionContext} implementation
+ * under the abstract `DbxInjectionContext` token via `useExisting`.
+ *
+ * This enables dependency injection consumers to request `DbxInjectionContext` and receive
+ * the specific directive or service implementation.
+ *
+ * @typeParam T - The concrete type that extends {@link DbxInjectionContext}.
+ * @param type - The concrete class to register as the existing provider.
+ * @returns An array of Angular providers.
  */
 function provideDbxInjectionContext(type) {
     return [
@@ -5157,7 +7657,37 @@ function provideDbxInjectionContext(type) {
 }
 
 /**
- * DbxInjectedViewContext implementation. Acts similar to *ngIf, but instead switches to a different view without destroying the original child view.
+ * Structural directive that implements {@link DbxInjectionContext}, allowing its host content
+ * to be temporarily replaced with a dynamically injected component and then restored.
+ *
+ * Unlike `*ngIf` or `*ngSwitch`, the original child content is **detached** (hidden) rather than
+ * destroyed, so component state is preserved while the injected context is active. When the
+ * context's promise resolves or {@link resetContext} is called, the original view is re-attached.
+ *
+ * The directive also accepts an optional `[dbxInjectionContext]` input to set a static component
+ * config directly, which replaces the default content until cleared.
+ *
+ * @typeParam O - The output type produced by {@link showContext}.
+ *
+ * @example
+ * ```html
+ * <!-- Wrap content that should be temporarily replaceable -->
+ * <div *dbxInjectionContext>
+ *   <p>Original content preserved while context is active</p>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Programmatically show a temporary editor overlay:
+ * const result = await injectionContext.showContext({
+ *   config: { componentClass: InlineEditorComponent },
+ *   use: (editor) => editor.waitForSave()
+ * });
+ * ```
+ *
+ * @see {@link DbxInjectionContext}
+ * @see {@link DbxInjectionContextConfig}
  */
 class DbxInjectionContextDirective {
     _injector = inject(Injector);
@@ -5167,6 +7697,10 @@ class DbxInjectionContextDirective {
     _currentPromise;
     _embeddedView;
     _isDetached = false;
+    /**
+     * Optional static component config input. When set, the directive replaces its content
+     * with the specified component. When cleared (`undefined`), the original content is restored.
+     */
     config = input(...(ngDevMode ? [undefined, { debugName: "config" }] : []));
     _configEffect = effect(() => {
         this.setConfig(this.config());
@@ -5189,6 +7723,9 @@ class DbxInjectionContextDirective {
         this._instance.destroy();
         this._embeddedView?.destroy(); // destroy our embedded view too if it is set.
     }
+    /**
+     * {@inheritDoc DbxInjectionContext.showContext}
+     */
     async showContext(config) {
         // clear the current context before showing something new.
         this.resetContext();
@@ -5237,6 +7774,9 @@ class DbxInjectionContextDirective {
             return result;
         }
     }
+    /**
+     * {@inheritDoc DbxInjectionContext.resetContext}
+     */
     resetContext() {
         let clearedValue = false;
         if (this._currentPromise) {
@@ -5251,6 +7791,14 @@ class DbxInjectionContextDirective {
         }
         return clearedValue;
     }
+    /**
+     * Sets or clears the active component configuration.
+     *
+     * When a config is provided, the original embedded view is detached and the component is injected.
+     * When `undefined` is provided, the injected component is removed and the original view is re-attached.
+     *
+     * @param config - The component config to display, or `undefined` to restore the original content.
+     */
     setConfig(config) {
         let reattach = false;
         if (config) {
@@ -5282,17 +7830,37 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }], propDecorators: { config: [{ type: i0.Input, args: [{ isSignal: true, alias: "config", required: false }] }] } });
 
 /**
- * Abstract DbxInjectionContext implementation that forwards commands to a host DbxInjectionContext.
+ * Abstract directive that delegates {@link DbxInjectionContext} operations to a host-level
+ * `DbxInjectionContext` obtained via Angular's dependency injection (`{ host: true }`).
+ *
+ * This is useful for creating specialized injection context subtypes that can be injected
+ * by their own token while still forwarding the actual show/reset behavior to a parent
+ * {@link DbxInjectionContextDirective}.
  *
- * This abstract type is used by related types for dependency injection purposes, so that those types
- * can be injected instead of just any DbxInjectionContext.
+ * @example
+ * ```typescript
+ * @Directive({ providers: [{ provide: MySpecialContext, useExisting: MyForwardDirective }] })
+ * class MyForwardDirective extends AbstractForwardDbxInjectionContextDirective {}
+ * ```
+ *
+ * @see {@link DbxInjectionContext}
+ * @see {@link DbxInjectionContextDirective}
  */
 class AbstractForwardDbxInjectionContextDirective {
+    /**
+     * The host-level {@link DbxInjectionContext} that all operations are forwarded to.
+     */
     dbxInjectionContext = inject(DbxInjectionContext, { host: true });
     // MARK: DbxInjectionContext
+    /**
+     * {@inheritDoc DbxInjectionContext.showContext}
+     */
     showContext(config) {
         return this.dbxInjectionContext.showContext(config);
     }
+    /**
+     * {@inheritDoc DbxInjectionContext.resetContext}
+     */
     resetContext() {
         return this.dbxInjectionContext.resetContext();
     }
@@ -5304,10 +7872,30 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Provides a switchMap that passes configuration from the observable, unless the value is null/undefined/true in which case it passes the default configuration.
+ * Creates an RxJS operator that switches between injection component configs, falling back to a
+ * default config when the source emits `null`, `undefined`, or `true`.
  *
- * @param defaultConfig
- * @returns
+ * If the `defaultConfig` resolves to a class (function), it is automatically wrapped into a
+ * `{ componentClass }` config object.
+ *
+ * This is useful for reactive streams where an upstream value may indicate "use the default component"
+ * rather than providing an explicit configuration.
+ *
+ * @typeParam T - The specific {@link DbxInjectionComponentConfig} subtype.
+ * @typeParam X - The component type.
+ * @param defaultConfig - A static value, getter, or component class to use as the fallback config.
+ * @returns An RxJS operator compatible with `pipe()`.
+ *
+ * @see {@link DbxInjectionComponentConfig}
+ *
+ * @example
+ * ```typescript
+ * config$.pipe(
+ *   switchMapDbxInjectionComponentConfig(MyDefaultComponent)
+ * ).subscribe(config => {
+ *   // config is always a DbxInjectionComponentConfig or undefined
+ * });
+ * ```
  */
 function switchMapDbxInjectionComponentConfig(defaultConfig) {
     const defaultAsGetter = asGetter(defaultConfig);
@@ -5326,11 +7914,21 @@ function switchMapDbxInjectionComponentConfig(defaultConfig) {
 }
 
 /**
- * Creates a new instance of the injectable type with the input injector.
+ * Creates a child injector with the given `type` as its sole provider and immediately
+ * resolves an instance of that type.
  *
- * @param type
- * @param parent
- * @returns
+ * This is a convenience for one-off instantiation of an injectable class using a specific
+ * parent injector, without needing to manually configure `Injector.create()`.
+ *
+ * @typeParam T - The type to instantiate.
+ * @param type - The injectable class to provide and resolve.
+ * @param parent - The parent injector that supplies the type's dependencies.
+ * @returns A new instance of `T`.
+ *
+ * @example
+ * ```typescript
+ * const service = newWithInjector(MyService, parentInjector);
+ * ```
  */
 function newWithInjector(type, parent) {
     const injector = Injector.create({ providers: [type], parent });
@@ -5338,7 +7936,26 @@ function newWithInjector(type, parent) {
 }
 
 /**
- * Abstract ComponentStore extension that provides a LockSet and OnDestroy delaying/cleanup.
+ * Abstract NgRx `ComponentStore` extension that integrates a {@link LockSet} for coordinating
+ * async operations and delays destruction until all locks are released.
+ *
+ * Subclasses call {@link setupLockSet} to register parent lock sets and named locks.
+ * On destroy, the store waits for all locks to unlock before completing cleanup,
+ * preventing premature teardown of in-flight operations.
+ *
+ * @typeParam S - The shape of the component store's state object.
+ *
+ * @example
+ * ```typescript
+ * interface MyState { items: string[]; }
+ *
+ * @Injectable()
+ * export class MyStore extends LockSetComponentStore<MyState> {
+ *   constructor() {
+ *     super({ items: [] });
+ *   }
+ * }
+ * ```
  */
 class LockSetComponentStore extends ComponentStore {
     initialState;
@@ -5383,7 +8000,8 @@ class LockSetComponentStore extends ComponentStore {
         }, this.lockSetDestroyDelayMs);
     }
     /**
-     * Completes the cleanup of the object.
+     * Immediately completes cleanup by destroying the lock set.
+     * Called after all locks are released during the deferred destruction process.
      */
     _destroyNow() {
         this.lockSet.destroy();
@@ -5400,6 +8018,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
                     type: Optional
                 }] }] });
 
+/**
+ * Default {@link SimpleStorageAccessorConverter} that uses `JSON.stringify`/`JSON.parse` for conversion.
+ *
+ * @typeParam T - The type of value being converted.
+ */
 class StringifySimpleStorageAccessorConverter {
     stringifyValue(value) {
         return JSON.stringify(value);
@@ -5408,6 +8031,12 @@ class StringifySimpleStorageAccessorConverter {
         return JSON.parse(data);
     }
 }
+/**
+ * Composes a {@link StorageAccessor} and a {@link SimpleStorageAccessorConverter} into a single
+ * {@link SimpleStorageAccessorDelegate} implementation.
+ *
+ * @typeParam T - The type of value being stored.
+ */
 class WrapperSimpleStorageAccessorDelegate {
     _delegate;
     _converter;
@@ -5440,6 +8069,11 @@ class WrapperSimpleStorageAccessorDelegate {
         return this._converter.parseValue(data);
     }
 }
+/**
+ * Validates that a storage key prefix is non-empty and does not contain the prefix splitter character.
+ *
+ * @throws {Error} If the prefix is invalid or the splitter is empty.
+ */
 function assertValidStorageKeyPrefix(prefix, prefixSplitter) {
     if (!prefixSplitter) {
         throw new Error('Invalid storage key prefix splitter. Must be defined and not empty.'); // TODO(FUTURE): Consider changing to a concrete error type
@@ -5448,11 +8082,34 @@ function assertValidStorageKeyPrefix(prefix, prefixSplitter) {
         throw new Error('Invalid storage key prefix.');
     }
 }
+/**
+ * Checks whether a storage key prefix is valid (non-empty and does not contain the splitter).
+ */
 function isValidStorageKeyPrefix(prefix, prefixSpltter) {
     return Boolean(prefix && prefix.indexOf(prefixSpltter) === -1);
 }
 /**
- * LimitedStorageAccessor implementation that uses a Delegate
+ * Full-featured {@link StorageAccessor} that adds key namespacing, JSON serialization,
+ * and optional time-based expiration on top of a raw string storage backend.
+ *
+ * Values are stored as JSON with metadata (timestamp) and automatically checked
+ * for expiration on read.
+ *
+ * @typeParam T - The type of values stored.
+ *
+ * @throws {DataDoesNotExistError} When reading a key that does not exist.
+ * @throws {DataIsExpiredError} When reading a key whose stored data has expired.
+ *
+ * @example
+ * ```typescript
+ * const accessor = factory.createStorageAccessor<UserSettings>({
+ *   prefix: 'user_prefs',
+ *   expiresIn: 3600000,
+ * });
+ *
+ * accessor.set('theme', { dark: true }).subscribe();
+ * accessor.get('theme').subscribe(settings => console.log(settings));
+ * ```
  */
 class SimpleStorageAccessor {
     static PREFIX_SPLITTER = '::';
@@ -5571,7 +8228,16 @@ class SimpleStorageAccessor {
 }
 
 /**
- * Simple StorageAccessor implementation that wraps a FullStorageObject.
+ * {@link StorageAccessor} implementation that wraps a {@link FullStorageObject} and stores raw strings.
+ *
+ * Each operation completes synchronously within an observable wrapper.
+ *
+ * @example
+ * ```typescript
+ * const accessor = new StringStorageAccessor(localStorage);
+ * accessor.set('key', 'value').subscribe();
+ * accessor.get('key').subscribe(value => console.log(value)); // 'value'
+ * ```
  */
 class StringStorageAccessor {
     _storage;
@@ -5618,11 +8284,34 @@ class StringStorageAccessor {
     }
 }
 
+/**
+ * DI token for the application's default {@link FullStorageObject} instance.
+ *
+ * Provided by {@link provideDbxStorage}.
+ */
 const DEFAULT_STORAGE_OBJECT_TOKEN = new InjectionToken('DBX_CORE_DEFAULT_STORAGE_OBJECT');
+/**
+ * DI token for the application's default {@link SimpleStorageAccessorFactory} instance.
+ *
+ * Provided by {@link provideDbxStorage}.
+ */
 const DEFAULT_STORAGE_ACCESSOR_FACTORY_TOKEN = new InjectionToken('DBX_CORE_DEFAULT_STORAGE_ACCESSOR_FACTORY');
 
 /**
- * Used for building SimpleStorageAccessor instances from SimpleStorageAccessorConfig.
+ * Injectable factory for creating namespaced {@link SimpleStorageAccessor} instances
+ * backed by the application's default storage object.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class UserPrefsService {
+ *   private readonly storage = inject(SimpleStorageAccessorFactory)
+ *     .createStorageAccessor<UserPrefs>({ prefix: 'user_prefs' });
+ *
+ *   save(prefs: UserPrefs) { return this.storage.set('current', prefs); }
+ *   load() { return this.storage.get('current'); }
+ * }
+ * ```
  */
 class SimpleStorageAccessorFactory {
     storageObject = inject(DEFAULT_STORAGE_OBJECT_TOKEN);
@@ -5643,23 +8332,45 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImpor
         }] });
 
 /**
- * Stored object accessor that can get/set/remove via a key, or be cleared entirely.
+ * Abstract storage accessor providing key-value get/set/remove operations and a clear-all method.
+ *
+ * All operations return observables for consistency across sync and async storage backends.
+ *
+ * @typeParam T - The type of values stored.
+ *
+ * @see {@link StorageAccessor} for extended functionality including key/value enumeration.
  */
 class LimitedStorageAccessor {
 }
 /**
- * LimitedStorageAccessor extension that has knowledge of all stored keys.
+ * Extended storage accessor that adds the ability to enumerate all stored keys and values,
+ * optionally filtered by a key prefix.
+ *
+ * @typeParam T - The type of values stored.
  */
 class StorageAccessor extends LimitedStorageAccessor {
 }
 /**
- * StorageAccessor-like object that has immediate/synchronous functionality for get/set.
+ * Synchronous storage accessor for scenarios where blocking get/set/remove is acceptable.
+ *
+ * @typeParam T - The type of values stored.
  */
 class InstantStorageAccessor {
 }
 
 /**
- * StorageObject using LocalStorage.
+ * {@link FullStorageObject} implementation backed by the browser's `localStorage`.
+ *
+ * Wraps a `StorageObject` (the Web Storage API interface) and adds availability checking
+ * and a `removeAll` operation.
+ *
+ * @example
+ * ```typescript
+ * const storage = new FullLocalStorageObject(window.localStorage);
+ * if (storage.isAvailable) {
+ *   storage.setItem('key', 'value');
+ * }
+ * ```
  */
 class FullLocalStorageObject {
     _localStorage;
@@ -5705,7 +8416,16 @@ class FullLocalStorageObject {
 }
 
 /**
- * FullStorageObject implementation that uses a localstorage that entirely resides in memory.
+ * In-memory {@link FullStorageObject} implementation that does not persist across page loads.
+ *
+ * Used as a fallback when `localStorage` is unavailable (e.g., private browsing, SSR)
+ * or for testing scenarios.
+ *
+ * @example
+ * ```typescript
+ * const storage = new MemoryStorageObject();
+ * storage.setItem('temp', 'data'); // stored only in memory
+ * ```
  */
 class MemoryStorageObject extends FullLocalStorageObject {
     get isLastingStorage() {
@@ -5720,8 +8440,14 @@ class MemoryStorageObject extends FullLocalStorageObject {
 }
 
 /**
- * Default storage object factory function that creates a FullLocalStorageObject,
- * falling back to MemoryStorageObject if localStorage is not available.
+ * Creates the default {@link FullStorageObject}, preferring `localStorage` and
+ * falling back to an in-memory store if `localStorage` is unavailable.
+ *
+ * @example
+ * ```typescript
+ * const storage = defaultStorageObjectFactory();
+ * storage.setItem('key', 'value');
+ * ```
  */
 function defaultStorageObjectFactory() {
     let storageObject = new FullLocalStorageObject(localStorage);
@@ -5731,9 +8457,16 @@ function defaultStorageObjectFactory() {
     return storageObject;
 }
 /**
- * Creates EnvironmentProviders for providing a default storage object and SimpleStorageAccessorFactory.
+ * Registers the default storage object and {@link SimpleStorageAccessorFactory} as environment-level providers.
  *
- * @returns EnvironmentProviders
+ * Call in your application config to enable storage-based services throughout the app.
+ *
+ * @example
+ * ```typescript
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [provideDbxStorage()],
+ * };
+ * ```
  */
 function provideDbxStorage() {
     const providers = [
@@ -5756,55 +8489,69 @@ function provideDbxStorage() {
 }
 
 /**
- * Convenience function used within observables for views that need to detect changes after a value changes.
+ * RxJS operator that triggers `detectChanges()` on a `ChangeDetectorRef` after each emission.
  *
- * @deprecated reminder to move to Angular signals
+ * Wraps the detection call in a `setTimeout` to avoid triggering it during change detection cycles.
  *
- * @param cdRef
- * @param timeout
- * @returns
+ * @deprecated Use Angular signals instead.
+ *
+ * @param cdRef - The change detector to trigger. If `null`/`undefined`, the operator is a no-op.
+ * @param timeout - Delay in milliseconds before calling `detectChanges`.
+ *
+ * @example
+ * ```typescript
+ * this.data$.pipe(tapDetectChanges(this.cdRef)).subscribe();
+ * ```
  */
 function tapDetectChanges(cdRef, timeout = 0) {
     return cdRef ? tap(() => setTimeout(() => safeDetectChanges(cdRef), timeout)) : tap();
 }
 /**
- * Triggers a check for detecting any changes on the model safely to ve registered via detectChanges().
+ * Safely calls `detectChanges()` on a `ChangeDetectorRef`, skipping the call if the view is already destroyed.
  *
- * @deprecated reminder to move to Angular signals
+ * @deprecated Use Angular signals instead.
  *
- * @param cdRef
+ * @param cdRef - The change detector to trigger.
  */
 function safeDetectChanges(cdRef) {
     safeUseCdRef(cdRef, () => cdRef.detectChanges());
 }
 /**
- * Convenience function used within observables for views that use the OnPush ChangeDetectionStrategy and needs to call markForCheck when a new observable value is pushed.
+ * RxJS operator that calls `markForCheck()` on a `ChangeDetectorRef` after each emission.
  *
- * NOTE: If the observable is being consumed via the "async" pipe, this may not be necessary.
+ * Intended for components using `OnPush` change detection that subscribe to observables
+ * outside of the `async` pipe. Not needed when using the `async` pipe.
  *
- * @deprecated reminder to move to Angular signals
- * @param cdRef
- * @param timeout
- * @returns
+ * @deprecated Use Angular signals instead.
+ *
+ * @param cdRef - The change detector to mark. If `null`/`undefined`, the operator is a no-op.
+ * @param timeout - Delay in milliseconds before calling `markForCheck`.
+ *
+ * @example
+ * ```typescript
+ * this.data$.pipe(tapSafeMarkForCheck(this.cdRef)).subscribe();
+ * ```
  */
 function tapSafeMarkForCheck(cdRef, timeout = 0) {
     return cdRef ? tap(() => setTimeout(() => safeMarkForCheck(cdRef), timeout)) : tap();
 }
 /**
- * Marks the ChangeDetectorRef for changes as long as the view has not been destroyed.
+ * Safely calls `markForCheck()` on a `ChangeDetectorRef`, skipping the call if the view is already destroyed.
  *
- * @deprecated reminder to move to Angular signals
+ * @deprecated Use Angular signals instead.
  *
- * @param cdRef
+ * @param cdRef - The change detector to mark.
  */
 function safeMarkForCheck(cdRef) {
     safeUseCdRef(cdRef, () => cdRef.markForCheck());
 }
 /**
- * Triggers a detection change on the input view as long as the view has not been destroyed.
+ * Executes a callback with the given `ChangeDetectorRef` only if its view has not been destroyed.
  *
- * @deprecated reminder to move to Angular signals
- * @param cdRef
+ * @deprecated Use Angular signals instead.
+ *
+ * @param cdRef - The change detector to guard.
+ * @param use - Callback to invoke with the change detector.
  */
 function safeUseCdRef(cdRef, use) {
     if (!cdRef.destroyed) {
@@ -5812,17 +8559,31 @@ function safeUseCdRef(cdRef, use) {
     }
 }
 /**
- * Used to check an injected ElementRef that wraps an ng-content injection point whether or not any content was injected,
- * or more specifically if the parent component passed any target content to the child. This will still return true if
- * passed content is empty.
+ * Checks whether an `ng-content` wrapper element received any projected content from its parent.
+ *
+ * Returns `true` if the element has any child nodes, even if the projected content is empty.
+ * Useful for conditionally showing fallback content when no projection is provided.
  *
- * TS:
- * @ViewChild('customLoading', { static: false }) customCustom: ElementRef;
+ * @param ref - Reference to the wrapper element around `ng-content`.
  *
- * HTML:
- * <div #customContent>
- *  <ng-content select="[content]"></ng-content>
+ * @example
+ * ```typescript
+ * // In the component class:
+ * @ViewChild('contentWrapper', { static: false }) contentRef: ElementRef;
+ *
+ * get hasContent(): boolean {
+ *   return checkNgContentWrapperHasContent(this.contentRef);
+ * }
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- In the component template: -->
+ * <div #contentWrapper>
+ *   <ng-content select="[content]"></ng-content>
  * </div>
+ * <div *ngIf="!hasContent">No content provided</div>
+ * ```
  */
 function checkNgContentWrapperHasContent(ref) {
     // https://github.com/angular/angular/issues/26083