@dereekb/dbx-core 13.9.0 → 13.10.0

package/fesm2022/dereekb-dbx-core.mjs

@@ -555,6 +555,11 @@ class DbxActionContextStoreSourceInstance {
  *
  * Can be disabled by setting `dbxActionAutoModify` to `false`.
  *
+ * @dbxAction
+ * @dbxActionSlug auto-modify
+ * @dbxActionStateInteraction IDLE
+ * @dbxActionConsumesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -616,6 +621,11 @@ const DBX_ACTION_AUTO_TRIGGER_INSTANT_TRIGGER_DEBOUNCE = 10;
  * Useful for auto-save scenarios where data changes should automatically submit without
  * requiring an explicit user action. Use with care to avoid triggering loops.
  *
+ * @dbxAction
+ * @dbxActionSlug auto-trigger
+ * @dbxActionStateInteraction IDLE, TRIGGERED
+ * @dbxActionConsumesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -788,39 +798,62 @@ function dbxActionWorkProgress(workOrWorkProgress, progressPercent) {
 }
 /**
  * Used by ActionContextState to denote what state the action is in.
+ *
+ * @dbxActionStateEnum
  */
 var DbxActionState;
 (function (DbxActionState) {
     /**
      * No action in progress. Waiting for the trigger.
+     *
+     * @dbxActionStateTransitionsFrom RESOLVED, REJECTED, DISABLED
+     * @dbxActionStateTransitionsTo TRIGGERED, DISABLED
      */
     DbxActionState["IDLE"] = "idle";
     /**
      * Idle state that can be set to show that the source is not yet ready.
+     *
+     * @dbxActionStateTransitionsFrom IDLE, RESOLVED, REJECTED
+     * @dbxActionStateTransitionsTo IDLE
      */
     DbxActionState["DISABLED"] = "disabled";
     /**
      * The action was triggered. We wait (and allow) the value to be updated.
+     *
+     * @dbxActionStateTransitionsFrom IDLE
+     * @dbxActionStateTransitionsTo VALUE_READY
      */
     DbxActionState["TRIGGERED"] = "triggered";
     /**
      * The trigger was accepted and the value is updated. It should begin working immediately.
      *
      * ValueReady cannot be set until triggered is set.
+     *
+     * @dbxActionStateTransitionsFrom TRIGGERED
+     * @dbxActionStateTransitionsTo WORKING
      */
     DbxActionState["VALUE_READY"] = "valueReady";
     /**
      * The action is in progress.
+     *
+     * @dbxActionStateTransitionsFrom VALUE_READY
+     * @dbxActionStateTransitionsTo RESOLVED, REJECTED
      */
     DbxActionState["WORKING"] = "working";
     /**
      * The trigger, action, or value was rejected due to an error or other issue.
      *
      * An error may be specified optionally.
+     *
+     * @dbxActionStateTransitionsFrom WORKING
+     * @dbxActionStateTransitionsTo IDLE, DISABLED
      */
     DbxActionState["REJECTED"] = "rejected";
     /**
      * The action resolved without issue.
+     *
+     * @dbxActionStateTransitionsFrom WORKING
+     * @dbxActionStateTransitionsTo IDLE, DISABLED
      */
     DbxActionState["RESOLVED"] = "resolved";
 })(DbxActionState || (DbxActionState = {}));
@@ -1010,7 +1043,7 @@ function loadingStateForActionContextState(state) {
         case DbxActionState.TRIGGERED:
         case DbxActionState.VALUE_READY:
         case DbxActionState.WORKING:
-            loadingState = beginLoading(state.workProgress != null ? { loadingProgress: state.workProgress } : undefined);
+            loadingState = beginLoading(state.workProgress == null ? undefined : { loadingProgress: state.workProgress });
             break;
     }
     return loadingState;
@@ -1051,6 +1084,13 @@ const ACTION_CONTEXT_STORE_LOCKSET_DESTROY_DELAY_TIME = 2000;
  * IDLE/DISABLED -> TRIGGERED -> VALUE_READY -> WORKING -> RESOLVED | REJECTED
  * ```
  *
+ * @dbxAction
+ * @dbxActionSlug action-context-store
+ * @dbxActionRole store
+ * @dbxActionDisabledKey dbx_action_disabled
+ * @dbxActionDisabledKey dbx_action_enforce_modified
+ * @dbxActionSkillRefs dbx__ref__dbx-component-patterns
+ *
  * @typeParam T - The input value type provided after triggering.
  * @typeParam O - The output result type produced on resolution.
  *
@@ -1504,6 +1544,11 @@ function provideSecondaryActionStoreSource(sourceType) {
  * On destruction, the directive coordinates cleanup through a {@link LockSet} to ensure
  * in-flight operations complete before the store is torn down.
  *
+ * @dbxAction
+ * @dbxActionSlug action
+ * @dbxActionStateInteraction IDLE
+ * @dbxActionProducesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -1558,6 +1603,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * This is useful when an action context is created programmatically (e.g., via
  * {@link DbxActionContextMachine}) and needs to be shared with template-based directives.
  *
+ * @dbxAction
+ * @dbxActionSlug source
+ *
  * @example
  * ```html
  * <!-- Forward a programmatic action source to template directives -->
@@ -1592,6 +1640,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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.
  *
+ * @dbxAction
+ * @dbxActionSlug logger
+ * @dbxActionStateInteraction IDLE, TRIGGERED, VALUE_READY, WORKING, RESOLVED, REJECTED, DISABLED
+ * @dbxActionConsumesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -1697,6 +1750,9 @@ function actionContextStoreSourceMap() {
  *
  * The map is exported as `actionMap` for template reference access.
  *
+ * @dbxAction
+ * @dbxActionSlug context-map
+ *
  * @example
  * ```html
  * <div dbxActionContextMap>
@@ -1939,6 +1995,11 @@ const APP_ACTION_DISABLED_DIRECTIVE_KEY = 'dbx_action_disabled';
  *
  * The disable key is automatically cleaned up on directive destruction.
  *
+ * @dbxAction
+ * @dbxActionSlug disabled
+ * @dbxActionStateInteraction DISABLED
+ * @dbxActionConsumesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -1989,6 +2050,11 @@ const APP_ACTION_DISABLED_ON_SUCCESS_DIRECTIVE_KEY = 'dbx_action_disabled_on_suc
  *
  * The disable key is automatically cleaned up on directive destruction.
  *
+ * @dbxAction
+ * @dbxActionSlug disabled-on-success
+ * @dbxActionStateInteraction RESOLVED, DISABLED
+ * @dbxActionConsumesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -2134,6 +2200,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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.
  *
+ * @dbxAction
+ * @dbxActionSlug handler
+ * @dbxActionStateInteraction VALUE_READY, WORKING, RESOLVED, REJECTED
+ * @dbxActionConsumesContext
+ * @dbxActionSkillRefs dbx__ref__dbx-component-patterns, dbx__guide__action-analytics
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -2169,6 +2241,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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.
  *
+ * @dbxAction
+ * @dbxActionSlug handler-value
+ * @dbxActionStateInteraction VALUE_READY, WORKING, RESOLVED
+ * @dbxActionConsumesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -2438,6 +2515,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * This is useful for performing side effects like logging, showing error toasts, or
  * handling specific error conditions programmatically.
  *
+ * @dbxAction
+ * @dbxActionSlug error-handler
+ * @dbxActionStateInteraction REJECTED
+ * @dbxActionConsumesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -2486,6 +2568,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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.
  *
+ * @dbxAction
+ * @dbxActionSlug value
+ * @dbxActionStateInteraction TRIGGERED, VALUE_READY
+ * @dbxActionConsumesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -2601,6 +2688,11 @@ const APP_ACTION_ENFORCE_MODIFIED_DIRECTIVE_KEY = 'dbx_action_enforce_modified';
  *
  * The disable key is automatically cleaned up on directive destruction.
  *
+ * @dbxAction
+ * @dbxActionSlug enforce-modified
+ * @dbxActionStateInteraction IDLE, DISABLED
+ * @dbxActionConsumesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -2789,6 +2881,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * Supports optional `isModified` and `isEqual` functions to control whether the retrieved
  * value should proceed to `readyValue` or be rejected.
  *
+ * @dbxAction
+ * @dbxActionSlug value-getter
+ * @dbxActionStateInteraction TRIGGERED, VALUE_READY
+ * @dbxActionConsumesContext
+ *
  * @example
  * ```html
  * <div dbxAction>
@@ -6444,6 +6541,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * Useful for normalizing values that may be plain values, getter functions, or Observables
  * into a consistent Observable stream for use with the `async` pipe.
  *
+ * @dbxPipe
+ * @dbxPipeSlug as-observable
+ * @dbxPipeCategory async
  * @example
  * ```html
  * <span>{{ valueOrGetter | asObservable | async }}</span>
@@ -6469,6 +6569,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * Displays only the date portion (no times). Returns a fallback string when the input is `null` or `undefined`.
  *
+ * @dbxPipe
+ * @dbxPipeSlug date-day-range
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-time-range, date-day-time-range
  * @example
  * ```html
  * <span>{{ dateRange | dateDayRange }}</span>
@@ -6500,6 +6604,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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.
  *
+ * @dbxPipe
+ * @dbxPipeSlug to-js-date
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-distance, date-format-distance
  * @example
  * ```html
  * <span>{{ '2024-01-05T12:00:00Z' | toJsDate | date:'short' }}</span>
@@ -6539,6 +6647,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * Accepts an optional comparison date (defaults to now) and a fallback string for `null`/`undefined` input.
  *
+ * @dbxPipe
+ * @dbxPipeSlug date-distance
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-range-distance, date-format-distance, time-distance
  * @example
  * ```html
  * <span>{{ someDate | dateDistance }}</span>
@@ -6581,6 +6693,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * Returns `undefined` if the input is falsy or not a valid date.
  *
+ * @dbxPipe
+ * @dbxPipeSlug date-format-distance
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-distance, date-format-from-to
  * @example
  * ```html
  * <span>{{ someDate | dateFormatDistance:'MMM d, y' }}</span>
@@ -6624,6 +6740,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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.
  *
+ * @dbxPipe
+ * @dbxPipeSlug date-format-from-to
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-time-range, date-format-distance
  * @example
  * ```html
  * <span>{{ eventStart | dateFormatFromTo:'MMM d, h:mm a':90 }}</span>
@@ -6662,6 +6782,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * Includes both the date and time portions. Returns a fallback string when the input is `null` or `undefined`.
  *
+ * @dbxPipe
+ * @dbxPipeSlug date-day-time-range
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-time-range, date-day-range
  * @example
  * ```html
  * <span>{{ dateRange | dateDayTimeRange }}</span>
@@ -6692,6 +6816,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * Displays the date and time of both the start and end. Returns a fallback string when the input is `null` or `undefined`.
  *
+ * @dbxPipe
+ * @dbxPipeSlug date-time-range
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-time-range-only, date-day-range, date-day-time-range
  * @example
  * ```html
  * <span>{{ dateRange | dateTimeRange }}</span>
@@ -6723,6 +6851,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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`.
  *
+ * @dbxPipe
+ * @dbxPipeSlug date-range-distance
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-distance
  * @example
  * ```html
  * <span>{{ someDate | dateRangeDistance }}</span>
@@ -6753,6 +6885,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * Displays only the time portion (no date). Returns a fallback string when the input is `null` or `undefined`.
  *
+ * @dbxPipe
+ * @dbxPipeSlug date-time-range-only
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-time-range
  * @example
  * ```html
  * <span>{{ dateRange | dateTimeRangeOnly }}</span>
@@ -6785,6 +6921,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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.
  *
+ * @dbxPipe
+ * @dbxPipeSlug target-date-to-system-date
+ * @dbxPipeCategory date
+ * @dbxPipeRelated system-date-to-target-date, timezone-abbreviation
  * @example
  * ```html
  * <span>{{ targetDate | targetDateToSystemDate:'America/New_York' | date:'short' }}</span>
@@ -6813,6 +6953,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * Accepts an optional {@link FormatDateRangeDistanceFunctionConfig} to customize the output format.
  * Returns a fallback string when the input is `null` or `undefined`.
  *
+ * @dbxPipe
+ * @dbxPipeSlug date-time-range-only-distance
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-time-range, date-range-distance
  * @example
  * ```html
  * <span>{{ dateRange | dateTimeRangeOnlyDistance }}</span>
@@ -6848,6 +6992,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * Defaults to the current date if no reference date is provided.
  * Returns `undefined` if the timezone is falsy.
  *
+ * @dbxPipe
+ * @dbxPipeSlug timezone-abbreviation
+ * @dbxPipeCategory date
+ * @dbxPipeRelated system-date-to-target-date, target-date-to-system-date
  * @example
  * ```html
  * <span>{{ 'America/New_York' | timezoneAbbreviation }}</span>
@@ -6879,6 +7027,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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.
  *
+ * @dbxPipe
+ * @dbxPipeSlug system-date-to-target-date
+ * @dbxPipeCategory date
+ * @dbxPipeRelated target-date-to-system-date, timezone-abbreviation
  * @example
  * ```html
  * <span>{{ systemDate | systemDateToTargetDate:'America/New_York' | date:'short' }}</span>
@@ -6910,6 +7062,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * A `~` prefix is added when the value is rounded up. Returns `undefined` for `null` or non-numeric input.
  *
+ * @dbxPipe
+ * @dbxPipeSlug minutes-string
+ * @dbxPipeCategory date
+ * @dbxPipeRelated to-minutes
  * @example
  * ```html
  * <span>{{ 90 | minutesString }}</span>
@@ -6962,6 +7118,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * Otherwise, returns a human-readable distance string with suffix (e.g., "in 3 hours").
  * Returns the `unavailable` string when the input is falsy.
  *
+ * @dbxPipe
+ * @dbxPipeSlug time-countdown-distance
+ * @dbxPipeCategory date
+ * @dbxPipeRelated time-distance
  * @example
  * ```html
  * <span>{{ futureDate | timeCountdownDistance }}</span>
@@ -7008,6 +7168,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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.
  *
+ * @dbxPipe
+ * @dbxPipeSlug time-distance
+ * @dbxPipeCategory date
+ * @dbxPipeRelated date-distance, time-countdown-distance
  * @example
  * ```html
  * <span>{{ someDate | timeDistance }}</span>
@@ -7051,6 +7215,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * Returns the original value (0 or falsy) if the input is falsy.
  *
+ * @dbxPipe
+ * @dbxPipeSlug to-minutes
+ * @dbxPipeCategory date
+ * @dbxPipeRelated minutes-string
  * @example
  * ```html
  * <span>{{ 180000 | toMinutes }}</span>
@@ -7085,6 +7253,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * Returns `undefined` for falsy input. If serialization fails, returns `'ERROR'` and logs the error to the console.
  *
+ * @dbxPipe
+ * @dbxPipeSlug prettyjson
+ * @dbxPipeCategory misc
  * @example
  * ```html
  * <pre>{{ myObject | prettyjson }}</pre>
@@ -7093,6 +7264,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * <pre>{{ myObject | prettyjson:4 }}</pre>
  * <!-- Output: formatted JSON with 4-space indentation -->
  * ```
+ * @param spacing Indent spaces; defaults to `2`.
  */
 class PrettyJsonPipe {
     static toPrettyJson(input, spacing = 2) {
@@ -7127,6 +7299,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * Returns the original value if the input is `null` or `undefined`.
  *
+ * @dbxPipe
+ * @dbxPipeSlug cut-text
+ * @dbxPipeCategory value
+ * @dbxPipeSkillRefs dbx-value-pipes
  * @example
  * ```html
  * <span>{{ 'Hello World' | cutText:5 }}</span>
@@ -7135,6 +7311,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * <span>{{ longText | cutText:20:'--' }}</span>
  * <!-- Output: "Some long text here--" -->
  * ```
+ * @param maxLength Maximum allowed length before truncation.
+ * @param endText Suffix appended when truncation occurs.
  */
 class CutTextPipe {
     transform(input, maxLength, endText) {
@@ -7159,11 +7337,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * for getter functions whose return value may change over time.
  * Use {@link GetValueOncePipe} (`getValueOnce`) for a pure alternative when the value is static.
  *
+ * @dbxPipe
+ * @dbxPipeSlug get-value
+ * @dbxPipeCategory value
+ * @dbxPipeRelated get-value-once
+ * @dbxPipeSkillRefs dbx-value-pipes
  * @example
  * ```html
  * <span>{{ myGetterOrValue | getValue }}</span>
  * <span>{{ myGetterFn | getValue:someArg }}</span>
  * ```
+ * @param args Optional argument forwarded to the getter function.
  */
 class GetValuePipe {
     transform(input, args) {
@@ -7186,10 +7370,16 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * 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.
  *
+ * @dbxPipe
+ * @dbxPipeSlug get-value-once
+ * @dbxPipeCategory value
+ * @dbxPipeRelated get-value
+ * @dbxPipeSkillRefs dbx-value-pipes
  * @example
  * ```html
  * <span>{{ myGetterOrValue | getValueOnce }}</span>
  * ```
+ * @param args Optional argument forwarded to the getter function.
  */
 class GetValueOncePipe {
     transform(input, args) {
@@ -7212,6 +7402,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  *
  * Optionally accepts a default string to display when the input is `null` or `undefined`.
  *
+ * @dbxPipe
+ * @dbxPipeSlug dollar-amount
+ * @dbxPipeCategory value
+ * @dbxPipeSkillRefs dbx-value-pipes
  * @example
  * ```html
  * <span>{{ 19.5 | dollarAmount }}</span>
@@ -7220,6 +7414,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
  * <span>{{ nullValue | dollarAmount:'N/A' }}</span>
  * <!-- Output: "N/A" -->
  * ```
+ * @param defaultIfNull String to display when the input is `null` or `undefined`. Defaults to formatting `null` through `dollarAmountString`.
  */
 class DollarAmountPipe {
     transform(input, defaultIfNull) {
@@ -7393,10 +7588,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
         }] });
 
 /**
- * Connects the host element's {@link FilterSource} to an ancestor {@link FilterSourceConnector} on initialization.
+ * Connects the host element's {@link FilterSource} to an ancestor {@link FilterSourceConnector} on init. Place on an element whose own directive contributes a `FilterSource` (via `host: true`) so it auto-wires to the parent connector.
  *
- * Place on an element that has a `FilterSource` (via `host: true`) to automatically
- * wire it up to a parent `FilterSourceConnector`.
+ * @dbxFilter
+ * @dbxFilterSlug connect-source
+ * @dbxFilterRelated source, source-connector
+ * @dbxFilterSkillRefs dbx__ref__dbx-component-patterns
  *
  * @example
  * ```html
@@ -7423,14 +7620,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
         }] });
 
 /**
- * Concrete directive that acts as both a {@link FilterSource} and {@link FilterSourceConnector}.
+ * Acts as both {@link FilterSource} and {@link FilterSourceConnector} — bridges a filter from one part of the template to another. Pair with `[dbxFilterConnectSource]` on the inner element that owns the source.
  *
- * Place on an element to bridge a filter source from one part of the template to another.
+ * @dbxFilter
+ * @dbxFilterSlug source-connector
+ * @dbxFilterRelated source, connect-source
+ * @dbxFilterSkillRefs dbx__ref__dbx-component-patterns
  *
  * @example
  * ```html
  * <div dbxFilterSourceConnector>
- *   <my-list-component></my-list-component>
+ *   <my-filter-form dbxFilterSource dbxFilterConnectSource></my-filter-form>
+ *   <my-list></my-list>
  * </div>
  * ```
  */
@@ -7490,18 +7691,26 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
             type: Directive
         }] });
 /**
- * Concrete directive that provides a {@link FilterSource} from a keyed entry in a parent {@link FilterMap}.
+ * Provides a {@link FilterSource} for a keyed entry in an ancestor {@link FilterMap}. Children can inject the source as if it were the only filter on the page; the map dispatches by key.
+ *
+ * @dbxFilter
+ * @dbxFilterSlug map-source
+ * @dbxFilterRelated map, map-source-connector
+ * @dbxFilterSkillRefs dbx__ref__dbx-component-patterns
  *
  * @example
  * ```html
  * <div dbxFilterMap>
- *   <div [dbxFilterMapSource]="'listFilter'">
+ *   <div [dbxFilterMapSource]="'profileList'">
  *     <my-filtered-list></my-filtered-list>
  *   </div>
  * </div>
  * ```
  */
 class DbxFilterMapSourceDirective extends AbstractDbxFilterMapSourceDirective {
+    /**
+     * The map key this source binds to.
+     */
     dbxFilterMapSource = input(...(ngDevMode ? [undefined, { debugName: "dbxFilterMapSource" }] : /* istanbul ignore next */ []));
     _dbxFilterMapSourceEffect = effect(() => this.setFilterMapKey(this.dbxFilterMapSource()), ...(ngDevMode ? [{ debugName: "_dbxFilterMapSourceEffect" }] : /* istanbul ignore next */ []));
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: DbxFilterMapSourceDirective, deps: null, target: i0.ɵɵFactoryTarget.Directive });
@@ -7518,20 +7727,26 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
         }], propDecorators: { dbxFilterMapSource: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxFilterMapSource", required: false }] }] } });
 
 /**
- * Directive that acts as both a {@link FilterSourceConnector} and {@link FilterSource} for a keyed entry in a parent {@link FilterMap}.
+ * Both {@link FilterSource} and {@link FilterSourceConnector} for a keyed entry in an ancestor {@link FilterMap}. Connects an external filter source to one map slot and re-emits that slot's filter.
  *
- * Connects an external filter source to a specific filter map entry and re-emits that entry's filter.
+ * @dbxFilter
+ * @dbxFilterSlug map-source-connector
+ * @dbxFilterRelated map, map-source
+ * @dbxFilterSkillRefs dbx__ref__dbx-component-patterns
  *
  * @example
  * ```html
  * <div dbxFilterMap>
- *   <div [dbxFilterMapSourceConnector]="'myList'">
- *     <my-list-component></my-list-component>
+ *   <div [dbxFilterMapSourceConnector]="'profileList'">
+ *     <my-list></my-list>
  *   </div>
  * </div>
  * ```
  */
 class DbxFilterMapSourceConnectorDirective extends AbstractDbxFilterMapSourceDirective {
+    /**
+     * The map key this connector binds to.
+     */
     dbxFilterMapSourceConnector = input(...(ngDevMode ? [undefined, { debugName: "dbxFilterMapSourceConnector" }] : /* istanbul ignore next */ []));
     _dbxFilterMapSourceConnectorEffect = effect(() => this.setFilterMapKey(this.dbxFilterMapSourceConnector()), ...(ngDevMode ? [{ debugName: "_dbxFilterMapSourceConnectorEffect" }] : /* istanbul ignore next */ []));
     // MARK: FilterSourceConnector
@@ -7557,10 +7772,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImpor
         }], propDecorators: { dbxFilterMapSourceConnector: [{ type: i0.Input, args: [{ isSignal: true, alias: "dbxFilterMapSourceConnector", required: false }] }] } });
 
 /**
- * Directive that provides a {@link FilterMap} instance for managing multiple named filter sources.
+ * Provides a {@link FilterMap} instance in DI so multiple child sources can register / look up filters by string key. Use when one screen needs several independent filter contexts.
  *
- * Child directives like `dbxFilterMapSource` and `dbxFilterMapSourceConnector` look up this
- * map via DI to register and retrieve filter instances by key.
+ * @dbxFilter
+ * @dbxFilterSlug map
+ * @dbxFilterRelated map-source, map-source-connector
+ * @dbxFilterSkillRefs dbx__ref__dbx-component-patterns
  *
  * @example
  * ```html
@@ -7605,12 +7822,17 @@ function isClickablePartialFilterPreset(preset) {
 }
 
 /**
- * Provides a {@link FilterSource} in the DI tree, allowing child components to inject and consume filter state.
+ * Provides a {@link FilterSource} in DI so child components can inject and consume the current filter value. Use this on a wrapper element when the child is the canonical owner of the filter (a filter form, a chip group).
+ *
+ * @dbxFilter
+ * @dbxFilterSlug source
+ * @dbxFilterRelated connect-source, source-connector, map-source
+ * @dbxFilterSkillRefs dbx__ref__dbx-component-patterns
  *
  * @example
  * ```html
  * <div dbxFilterSource>
- *   <my-list-component></my-list-component>
+ *   <my-filter-form></my-filter-form>
  * </div>
  * ```
  */