Functions

Adapts an Angular Reactive Forms AbstractControl (FormControl, FormGroup, FormArray) to the CngxFieldAccessor interface expected by cngx-form-field.

This enables using cngx-form-field without Signal Forms - for teams that haven't migrated yet or for forms that use Reactive Forms by design.

A CngxFieldAccessor compatible with [field] input on cngx-form-field.

readonly emailControl = new FormControl('', [Validators.required, Validators.email]);
readonly emailField = adaptFormControl(this.emailControl, 'email', inject(DestroyRef));

Append child to the group at path. Throws when path does not resolve to a group.

Structural equality between two filter trees. Intended as the equal option on computed / linkedSignal exposing a FilterGroup, per the cngx signal-architecture equality rule (object/array computeds MUST pass an explicit equal fn). Identity short-circuits.

Pure tree utilities for the filter-builder data model. Every mutator returns a new tree; the originals are never modified. Identity is preserved when no descendant changed - feeds the filterTreeEqual short-circuit on computed / linkedSignal consumers (Pillar 1).

Paths are arrays of child indices. The empty path [] addresses the root group; [2, 0] addresses the first child of the root's third child.

Remove the node at path. Throws on empty path - the root cannot be removed.

Replace the node at path via updater. Returns the original root when no descendant changed (identity-preserving).

Reduce a feature list onto a base config, merging each sub-tree in isolation.

Convenience accessor for the incremental-list configuration. Runs in injection context; resolves through the cascade. Equivalent to inject(CNGX_INCREMENTAL_LIST_CONFIG).

Application-root configuration cascade for the incremental list. Pass any combination of with* features in bootstrapApplication's providers. Supplied features merge with the library defaults, so consumers only declare the keys they override.

Component-scoped incremental-list configuration override. Pass into a component's or directive's viewProviders; features merge on top of the parent config (an enclosing scope or the application root), so a region can re-phrase its labels without disturbing the rest of the app.

Override any subset of the incremental-list labels. The override applies to both the visible built-in views and the live-region announcements.

provideIncrementalListConfig(
  withIncrementalListAriaLabels({
    empty: 'Noch nichts hier',
    endReached: (total) => `Alle ${total} geladen`,
  }),
);

Supply application-wide template-slot defaults. A per-instance projected slot still wins over this tier; it only applies where no instance slot is present.

provideIncrementalListConfig(
  withIncrementalListTemplates({ empty: myBrandedEmptyTemplate }),
);

Reduce a feature list onto a base config, merging each sub-tree in isolation.

Convenience accessor for the paginator configuration. Runs in injection context; resolves through the cascade. Equivalent to inject(CNGX_PAGINATOR_CONFIG).

Application-root configuration cascade for the paginator. Pass any combination of with* features in bootstrapApplication's providers. Supplied features deep-merge with the library defaults, so consumers only declare the keys they want to override.

Component-scoped paginator configuration override. Pass into a component's or directive's viewProviders; features merge on top of the parent config (an enclosing scope or the application root), so a region can re-phrase its announcements or labels without disturbing the rest of the app.

Override any subset of the paginator live-region announcement phrasing.

provideCngxPaginatorConfig(
  withPaginatorAnnouncements({
    pageChange: (page, total) => `Seite ${page} von ${total}`,
    loading: 'Wird geladen',
    updated: 'Aktualisiert',
  }),
);

Override any subset of the paginator accessible-name strings. Per-instance aria-label bindings still win over the cascade for the landmark name.

provideCngxPaginatorConfig(
  withPaginatorAriaLabels({ next: 'Nächste Seite', previous: 'Vorige Seite' }),
);

Supply the default items-per-page choices for the cngx-pgn-page-size dropdown app-wide. The segment renders these when no per-instance [options] is bound; a non-empty [options] input still wins. The list replaces the library default wholesale - it is one atomic value, not a merged sub-tree.

provideCngxPaginatorConfig(
  withPaginatorPageSizeOptions([12, 24, 48]),
);

Override the page-status format. The cngx-pgn-status segment renders the returned string verbatim, so this localises the "Page n of m" readout that the responsive collapse reveals.

provideCngxPaginatorConfig(
  withPaginatorPageStatusFormat((page, totalPages) => `Seite ${page} von ${totalPages}`),
);

Override the range-readout format. The cngx-pgn-range segment renders the returned string verbatim, so this also localises the of connector.

provideCngxPaginatorConfig(
  withPaginatorRangeFormat((start, end, total) => `${start}-${end} von ${total}`),
);

Supply application-wide template-slot defaults for the paginator. The per-instance *cngxPaginatorLoading slot still wins over this tier; it only applies where no instance slot is projected.

provideCngxPaginatorConfig(
  withPaginatorTemplates({ loading: myBrandedSpinnerTemplate }),
);

Shallow positional equality for two readonly arrays. Returns true when both arrays reference the same object, or when they have the same length and every index holds a Object.is-equal value.

Intended as an equal arg for computed() / linkedSignal returning readonly T[], so consumers downstream do not re-render when the computed re-runs but produces a positionally-identical array. Two arrays with the same values in a different order compare unequal.

Shallow structural equality for two readonly Sets. Returns true when both sets reference the same object, or when they have the same size and every element of a is present in b. Element comparison uses Set.has (SameValueZero semantics).

Intended as an equal arg for computed() / linkedSignal returning ReadonlySet<T>, so consumers downstream do not re-render when the computed re-runs but produces the same element set.

App-wide entry point for the Select-family configuration surfaces. Routes mixed features from provideSelectConfig, provideActionSelectConfig, and provideReorderableSelectConfig to the correct underlying provider. The three individual providers stay exported.

bootstrapApplication(App, {
  providers: [
    provideCngxSelect(
      // CngxSelectConfig features
      withPanelWidth('trigger'),
      withVirtualization({ estimateSize: 36 }),
      withAriaLabels({ clearButton: 'Clear', chipRemove: 'Remove' }),

      // CngxActionSelectConfig features
      withFocusTrapBehavior('strict'),
      withCloseOnCreate(true),

      // CngxReorderableSelectConfig features
      withReorderKeyboardModifier('alt'),
      withReorderStripFreeze(true),
    ),
  ],
});

Component-scoped twin of provideCngxSelect. Returns Provider[] because viewProviders rejects EnvironmentProviders.

Build a read-only CngxAsyncState<T> view from source signals.

All derived fields (isLoading, isPending, isEmpty, etc.) are computed() from the provided sources — the result is a consistent, single-source-of-truth state object that cannot become inconsistent.

This is the shared kernel used by all async state factories and state producers. No injection context required — uses only computed().

Walks the activated route tree from the root down the firstChild chain, accumulating the URL and emitting one crumb per route whose data[dataKey] is a non-empty string. A non-empty data[iconKey] string rides onto the crumb's opaque icon (the leading icon slot renders it; deepest wins on the componentless-collapse branch, like the label).

Positional shape equality for two crumb trails. The router source maps a fresh crumb literal per navigation, so reference equality (Object.is) would treat every NavigationEnd as a change; comparing label/href/icon lets a same-shape navigation keep the previous signal reference and stops it cascading the bar (reference_signal_architecture Equality Rule).

The router source populates label, href, and (from data[iconKey]) icon, so those three fully describe a crumb's identity here - icon must be compared or an icon-only route-data change never propagates. When SPA-link emission lands, its equality is defined alongside it.

Build the SVG d attribute for a sequence of points.

The full path data starting with M. Returns '' when the input is empty; M x y when the input has one point.

Build the full dot sequence plus the viewport anchor. Every page gets a dot; for large counts the dots that fall outside the centred VISIBLE window are shrunk to small (they sit off-screen behind the viewport clip and shrink as they glide out), and the two dots at each truncated visible edge step down medium -> small (iOS page-control edge-shrink). The consumer translates the track by firstVisible so navigation slides the strip instead of reshuffling the DOM - the active dot stays centred and the row glides under it.

Enumerates the sibling routes at depth in the activated route chain: the children of that level's parent (or the root config at depth 0) whose data[dataKey] is a non-empty string, marking the active child current. Sibling configs come from the static route configuration, not the activated snapshot (which only holds the one active child), so the whole set of alternatives is visible. Duplicate hrefs are collapsed like buildCrumbs.

Positional shape equality for two sibling sets. The router source maps a fresh sibling literal per navigation, so reference equality (Object.is) would treat every NavigationEnd as a change; comparing label/href/current lets a same-shape navigation keep the previous signal reference and stops it cascading the dropdown (reference_signal_architecture Equality Rule). Mirrors crumbsEqual.

current is compared because the same set of siblings with a different active member is a genuine change - the aria-current marker moves.

Creates a functional route guard that blocks navigation when the form is dirty.

Works with Angular's CanDeactivateFn. The isDirty callback is evaluated on each navigation attempt. When dirty, shows a confirm dialog.

Uses DOCUMENT injection for SSR safety — returns true (allow) when no window is available.

Pair with CngxBeforeUnload for full coverage (browser close + route change):

// Route config
{
  path: 'edit',
  component: EditComponent,
  canDeactivate: [canDeactivateWhenClean(() => inject(EditComponent).isDirty())]
}

A functional guard compatible with Angular's canDeactivate.

Clamp a number into the inclusive range [min, max]. null or undefined bounds read as -Infinity / +Infinity respectively, so either side can be left open. NaN value propagates and is returned unchanged. When the bounds invert (min > max after coercion), min wins and the returned value is min.

Pure factory for a slider's value derivation - the brain shared by CngxSlider and each CngxSliderThumb of a range slider. It owns no DI and no DOM: hand it the source signals, get back the clamped value, the track fraction, the aria-valuetext string, and the four mutation helpers the keyboard / pointer handlers call. Snapping and bound-clamping live in CngxSliderCore.setValue, so every write path stays valid without an effect syncing state (Pillar 1).

Coerce a bound value to a number (via coerceNumberProperty, falling back to fallback) and clamp it into the ARIA heading-level range 2-6.

Coerce a bound value to a number (via coerceNumberProperty, falling back to fallback) and clamp it into the ARIA heading-level range 2-6.

Map a cell's col track intent to one CSS grid-template-columns track. Unset (undefined) falls back to the derived default: the primary column grows (minmax(0, 1fr)), every other column fits its content (auto). The named sizes resolve against the registered --cngx-dga-col-sm|-md|-lg tokens, each with a rem fallback so the track stays valid even before the token surface loads (an invalid var() would collapse the whole grid-template-columns to one column).

Apply a per-call [0, 1] scale to a tone's peak gain. Centralised here so every play path (play / tone / sequence) scales identically and an engine override sees per-element volume uniformly, rather than each caller pre-baking its own gain.

Coerce a single value or an array to an array. Returns the input unchanged when already an array; wraps a scalar value in a single-element array otherwise.

Coerces a value to a boolean.

Strings are truthy unless they equal 'false'. All other falsy values return false.

Coerces a value to a number.

Returns fallback when the value is null, undefined, NaN, or non-numeric.

Collect all descendant values of a node (exclusive of the node itself), in DFS order. For cascade-select: toggling a parent flips all entries in this list atomically.

Return a new tree containing only nodes whose value matches predicate or have at least one matching descendant. Ancestors of any match are preserved so the path is never broken; branches with zero matches are dropped entirely.

Fresh implementation — not ported from @cngx/data-display/treetable.

Flatten a tree in DFS order. Each emitted FlatTreeNode carries aria-level (depth + 1), aria-posinset, and aria-setsize data so the rendering layer can bind them directly.

A flat node is visible iff every ancestor in its parentIds chain is present in expandedIds. Root nodes (empty chain) are always visible.

Return a new tree where each level's siblings are sorted independently by the by extractor. Child ordering is stable within its own level only — the relative position of nodes across different parents is irrelevant.

Fresh implementation — not ported from @cngx/data-display/treetable.

DFS visitor. visit is called once per node with the current depth.

Builds a CngxPhoneMetadata adapter from a region keyed prefix map, so a consumer declares the prefixes that matter instead of hand-writing the region branch and the matching closure.

The adapter resolves the line type by longest matching prefix: the matcher with the most matched leading digits wins, so a specific '0820' fixed-line rule beats a broader '08' mobile rule. Ties resolve to mobile (it is the decisive case auto mask alternation cares about). An unknown region or no matching prefix returns 'unknown', keeping the length-based fallback.

It still ships no numbering data - the caller supplies every prefix - so it is sugar over an inline adapter, not a replacement for a real metadata library like libphonenumber-js.

providePhoneMetadata(
  createPrefixPhoneMetadata({
    DE: { mobile: [/^1[567]/] },
    AT: { mobile: ['650', '660', '664', '676', '699'] },
  }),
);

Registers a CngxPhoneMetadata adapter for CngxPhoneInput's auto line-type detection.

Returns a plain Provider, so it works app-wide in ApplicationConfig.providers or scoped to a subtree via a component's viewProviders - mirroring provideInputConfig. The nearest provider wins for a subtree by token resolution.

// app.config.ts
providers: [providePhoneMetadata(libphonenumberAdapter)]

Wires the CngxPaginate brain's page / page-size changes onto a host's two-way outputs with exactly-once emit semantics. Two paths feed each handler, sharing a last-emitted guard:

• a subscription forwards the brain's nav-only pageChange / pageSizeChange
  • the only signal that captures a controlled-mode setPage, because the brain's pageIndex() stays pinned to the input until the consumer feeds it back;
• an effect() reads the effective pageIndex() / pageSize() and covers a total-shrink clamp the nav-only output misses.

The shared guard makes a value one path already emitted a no-op on the other, so each change emits exactly once. Seeded with the current effective values, so wiring emits no initial change.

Shared verbatim by the CngxPaginator shell and the CngxIncrementalList organism, so the two-way emit behaviour is byte-identical. Call inside an injection context (constructor or field initialiser) - it reads DestroyRef and creates effects.

Wires the reset-on-change behaviour onto a CngxPaginate brain: when key() changes (after the initial run) the paginator jumps to the first page. The first run captures the mounting value without resetting, and an already-first paginator emits nothing.

Shared by [cngxPaginateResetOn], the CngxPaginator shell's resetOn input, and the CngxMatPaginator bridge's resetOn input, so the behaviour is byte-identical across all three. Call inside an injection context (constructor or field initialiser).

Wires a CngxRecycler to a CngxActiveDescendant in virtual mode.

When the AD directive navigates to an item whose index is not in the recycler's rendered range, it sets pendingHighlight (via the virtualCount path). This helper watches that signal and scrolls the recycler to the target index; AD's own effect observes the resulting DOM update and clears the pending state automatically (see the pendingHighlightState.set(null) branch in CngxActiveDescendant after a re-render brings the target into the rendered range).

Unlike * connectRecyclerToRoving}, we don't re-focus a DOM element after the scroll — AD doesn't move real focus, it only rebinds aria-activedescendant. Once the target index enters the rendered range, the [attr.aria-activedescendant] binding on the combobox trigger resolves to the now-present option element for free.

Must be called in an injection context (typically a component constructor) on the same component that owns both the recycler and the AD directive.

Wires a CngxRecycler to a CngxRovingTabindex in virtual mode.

When the roving tabindex navigates to an item that is not in the DOM (out of rendered range), this function scrolls the recycler to that item and focuses it after rendering.

Must be called in an injection context (constructor or field initializer) on the component that hosts both the recycler's scroll container and the CngxRovingTabindex directive. The injected ElementRef is used to query [data-cngx-recycle-index] — calling from a child component would query the wrong subtree.

Level-2 factory implementing the WAI-ARIA APG accordion keyboard model over a registration model rather than contentChildren roving. Registration is immune to component-view boundaries, so any accordion skin - the @cngx/ui/accordion organism, or a future one that renders each header in its own view - gets working Arrow/Home/End nav.

Pillar 1 (Ableitung statt Verwaltung): the tab stop is derived from the coordinator's rovingActiveId, not managed as a second index. Focus movement is a DOM concern the factory owns - the coordinator only records which header should be the stop; it never touches the DOM.

Action-host bridge for a select-family variant: dirty signal + stable callbacks bundle + focus-trap policy + dismiss-block signal. dirty is the only writable slot; everything else is computed. Installs a capture-phase Escape listener on the host element via DestroyRef. Injection context required.

Wires listbox.ad.activated into the variant's commit / non-commit callbacks. Single effect(onCleanup) - subscribes on ref resolve, unsubscribes on teardown. Payload runs inside untracked; activations for unknown values are dropped. Value-shape agnostic - rollback ownership stays in the consumer.

Array-shape commit flow shared by CngxMultiSelect and CngxCombobox. Owns commit-controller lifecycle, reconciliation via sameArrayContents, togglingOption.set(null) on success, optimistic rollback on error, live-region "removed" announce. Consumer owns change-event payloads via the finalize callbacks.

No scalar twin: this handler is array-only by design.

Create a mutation async state — for explicit user-triggered actions.

Must be called in an injection context (field initializer or constructor) because it uses inject(DestroyRef) for cleanup.

readonly saveResident = createAsyncState<Resident>();

async handleSave(): Promise<void> {
  await this.saveResident.execute(
    () => this.api.save(this.form().value())
  );
}

Create the autoplay gate: a one-shot latch that flips armed to true on the first pointerdown / keydown / touchstart and then removes its own listeners. The engine consults armed() before resuming the shared AudioContext, honouring the browser autoplay policy without a permission prompt.

Pure factory — takes its target and destroyRef as arguments rather than calling inject(), so it composes inside the engine's injection context yet stays testable with a fake target. No DI token: the gate has no independent swap consumer (severity ladder concern: over-abstraction), so it ships token-less and the engine owns it.

Construct a BandScale from a categorical domain and a numeric range. See the type-level documentation above for parameter semantics.

The default collapse rule: keep the first crumb and the last maxVisible - 1, folding the middle into the overflow menu. Returns an empty set when maxVisible is unset/invalid (< 1) or the trail already fits (total <= maxVisible), so a short trail never collapses.

Builds a CngxChipRemovalHandler. Owns disabled-guard, snapshot, filter, branch dispatch, WeakMap closure stability. Consumer owns the commit dispatch (beginCommit), rollback snapshotting (onBeforeCommit), and change-event emission (onSyncFinalize).

Plain factory for the chip-strip roving-tabindex controller shared by CngxReorderableMultiSelect today and by any future reorder-aware chip trigger (e.g. a tag-input with user-defined ordering). Extracted from the component so the same focus-state machine doesn't reappear inline in every variant.

Why not CngxRovingTabindex. That directive uses a host (keydown) listener that doesn't check modifier keys. Co-located with CngxReorder on the same chip-strip element it double-fires on Ctrl+Arrow (the reorder emits, then roving also moves focus - racy). This controller deliberately skips modifier-pressed events so the paired reorder directive owns that gesture.

Injection context. Must be called in an injection context (component constructor / field init) because it installs an * effect() for the active-index clamp on count shrink.

Material variant of CngxTabOverflowDomAdapter.

resolveStripRoot walks from host up to <mat-tab-header> and locates .mat-mdc-tab-label-container via any rendered .mat-mdc-tab descendant — Material's IO-friendly scroll container.

resolveTabButton indexes positionally; Material owns the DOM and cngx handle ids never reach the button elements. Index correlates against presenter.tabs() registration order.

Wire it via the directive's CNGX_TAB_OVERFLOW_DOM_ADAPTER_FACTORY provider:

providers: [
  { provide: CNGX_TAB_OVERFLOW_DOM_ADAPTER_FACTORY,
    useValue: createCngxMatTabOverflowDomAdapter }
]

Default adapter for the cngx-native <cngx-tab-group> strip:
walks host.closest('.cngx-tabs__strip-wrapper') for the IO root, then [id="${handle.id}-header"] for each button.

Factory for the commit controller.

Plain function, not a class — matches the rest of the repo (createManualState, createAsyncState, createTransitionTracker). See reference_api_prefix_convention.md.

Direct (non-DI) factory for a select-side commit controller. Wraps a fresh generic controller with the action-shape adapter; bypasses CNGX_COMMIT_CONTROLLER_FACTORY. Use CNGX_SELECT_COMMIT_CONTROLLER_FACTORY for DI-aware resolution.

Default factory for the scalar commit-error announcer. Dispatches via policy.kind: 'verbose' announces the formatted error message at the configured severity; 'soft' calls the soft-announce hook (CngxTypeahead removal pattern).

Override the CNGX_COMMIT_ERROR_ANNOUNCER_FACTORY token to swap in telemetry or locale-aware variants.

Derives a controlled/uncontrolled source signal: a higher-precedence priority source wins over a lower-precedence fallback source. Precedence is the only contract - either argument may be an injected token signal, a component input(), or a projected contentChild query, and which role a given source plays flips per seam (the bar lets an injected source win over its [items] input; the overflow lets a forwarded input() win over its projected slot query). Collapses the repeated priority?.() ?? fallback() seam - the "controlled source wins via computed" pattern - into one factory beside its create* siblings.

Pure pass-through: it returns whichever underlying signal's own value, never a fresh literal, so an equal fn is unnecessary and no downstream cascade fires. priority absent (no source injected) or yielding undefined (an unbound input, an unmatched query) both fall through to fallback - one expression covers the accessor-absent seam (source?.crumbs) and the value-undefined seam (itemTemplateInput()).

A computed reading priority?.() ?? fallback().

// an injected source wins over the [items] input, else the input shows
protected readonly items = createControlledSource(
this.itemsSource?.crumbs, // injected source signal, may be absent
this.itemsInput,          // [items] input - the fallback
);

Plain factory for the quick-create commit flow. Shared by CngxActionSelect and CngxActionMultiSelect. Two separate factories vs createReorderCommitHandler because create and reorder have different value-shape contracts (materialise new T vs reorder existing T[]).

Per-name time-window debouncer: suppresses repeated fires of the same earcon within windowMs. A separate composed factory rather than logic buried in the engine (Pillar 3). Plain factory, no DI token — withDebounceMs covers configuration and there is no independent swap consumer.

windowMs accepts a getter so a caller whose window is a reactive input can hold ONE debouncer instance for its lifetime and still track changes: the window is resolved per shouldFire call, not captured at construction. That keeps the (stateful) debouncer out of the signal graph — minting one inside a computed would return a fresh object per evaluation and break the equality rule. CngxAudioPitch is the getter consumer; the engine passes a number.

The clock is injectable (now) purely so specs are deterministic; production defaults to Date.now.

Canonical W3C listbox flat-nav: PageUp/Down step 10 with disabled back-probe; typeahead delegates to the variant's TypeaheadController.

Build a Signal<Map<string, T>> from a Signal<readonly T[]> of directives keyed by id(). Structural equal prevents cascade when contentChildren re-emits an unchanged child set. Shared by <cngx-tab-group>, <cngx-stepper>, and <cngx-mat-stepper>.

Click-outside handler. Pure closure over opts - no Angular DI. Override via CNGX_DISMISS_HANDLER_FACTORY for telemetry or conditional-dismiss prompts.

Bidirectional binding between a scalar value signal and the visible text of a co-located <input> running CngxListboxSearch. Two effect()s - value→input (gated on focused) and search-term→callback (gated on writingFlag + skipInitial).

Bounded retry loop for DOM-anchoring patterns - shared attempt-counter and give-up and cancellation contract.
Used by <cngx-tab-overflow>'s rAF strip-attach loop and [cngxMatTabs]'s afterNextRender header-anchor loop.

Consumer-supplied scheduler lets different timing primitives flow through one counter.

const retry = createDomAnchorRetry({
  attempt: () => {
    const root = host.closest('.strip-wrapper');
    if (!root) return null;
    observer.observe(root);
    return true;
  },
  maxAttempts: 60,
  schedule: (cb) => {
    const h = requestAnimationFrame(cb);
    return () => cancelAnimationFrame(h);
  },
  onGiveUp: () => console.warn('strip wrapper not found'),
});
afterNextRender(() => retry.start());
destroyRef.onDestroy(() => retry.cancel());

Tracks an element's content-box width as a reactive signal via the ResizeObserver API. Mirrors createMobileViewportSignal's matchMedia wrapper: the API is wrapped directly (not via the CngxResizeObserver directive, which can only attach through hostDirectives). In SSR / non-DOM environments the signal stays 0 and no observer is wired.

Resolves the classic strip's density rung from its own container width against the step count and two per-step px thresholds. Pure create* factory, sibling to createStepperDisplayMode - it owns a ResizeObserver the way the display-mode factory owns a matchMedia listener, and returns a single derived Signal.

'comfortable' density short-circuits to 'full' (no measurement dependency). Before the first measurement (width === 0) and for an empty strip the rung is 'full', so the strip never flashes 'minimal' on mount.

Frozen empty root used as the presenter's model<FilterGroup> default and by CngxFilterBuilderState.clear(). Always returns the same frozen reference so consumers comparing tree identity short-circuit correctly.

Build a fresh FilterExpression with a generated id.

Build a fresh FilterGroup with a generated id. Defaults to and logic, no children, not negated.

Normalises a tree by assigning a stable id to every node missing one. Identity-preserving short-circuit - when every node already carries an id, the same tree reference is returned. Consumers who hand-construct trees (deserialised JSON, presets, persisted snapshots) run this once at the boundary; the presenter already invokes it on initial read and on every external write through value.

Evaluate a single FilterExpression against item. Unfilled expressions short-circuit to true (except isEmpty/isNotEmpty).

Build an item-level predicate from a FilterGroup. Returns null when the tree itself is null - the consumer typically interprets null as "no filtering, accept every item". For an empty root group, the returned predicate evaluates true for every item (vacuous truth on and).

Bidirectional Field <-> control value sync via CngxFormFieldPresenter.

Two effect()s, each reading the opposite branch inside untracked() with valueEquals as the cycle break - the canonical bridge every model()-based cngx control reuses instead of re-implementing field write-back. Both the field and the control's model() are writable sources of truth, so this is coordination, not a single computed(). Requires an injection context; no-op without a surrounding cngx-form-field.

Keeps the create* prefix despite calling inject() in its body: it is a blessed exception (see architecture-summary, mirrors adaptFormControl), not an oversight. The name is also the public @cngx/forms/select export; renaming would break that contract.

createFieldSync<number>({
  componentValue: this.value,
  valueEquals: Object.is,
  coerceFromField: (v) => (typeof v === 'number' ? v : 0),
});

Gate-aware wrapper over the canonical createFieldSync from @cngx/forms/field. Returns early when CNGX_SELECT_DISABLE_FIELD_SYNC is provided truthy in the injection context; otherwise delegates to the one bridge implementation. Array-shape callers keep working unchanged: the field createFieldSync<V> is generic in V and the composites already pass their own valueEquals / coerceFromField / toFieldValue.

Kept as the select-local export so the 9 select composites and cngx-filter-builder import the gate and the sync from one module.

Default announcer - derives the live-region string from lastMutation through the i18n formatter bundle.

Inject-context helper that resolves CNGX_FILTER_BUILDER_ANNOUNCER_FACTORY.

Default factory behind CNGX_FILTER_BUILDER_STATE_FACTORY. Wraps one writable FilterGroup signal as the canonical tree and returns the CngxFilterBuilderState the presenter drives:

• read-only tree / fieldMap / isEmpty signals
• path-keyed mutators (addExpression, setLogic, removeNode, clear, ...)
• the lastMutation event the announcer formats into live-region text

Two-way binding: pass the presenter's model<FilterGroup>() as source, so every mutator write emits through the consumer's [(value)]. Uncontrolled callers omit source and the factory creates its own signal from initial ?? EMPTY_ROOT.

Plain TS, no inject() - testable without TestBed. Override the token to wrap this (logging, undo) rather than reimplementing the mutators.

Wires every slot query through the documented three-stage cascade. Must be called inside an Angular injection context (the helper resolves CNGX_FILTER_BUILDER_CONFIG lazily and the contentChild signals were already created in the caller's context).

The default factory is registered behind CNGX_FILTER_BUILDER_TEMPLATE_REGISTRY_FACTORY so consumers can wrap the resolution path (telemetry, dynamic theme swapping, etc.) without forking the component.

Inject-context helper that resolves the registry factory through the DI token and invokes it with the caller's contentChild queries. The <cngx-filter-builder> component is the canonical caller.

Pass-through renderer: every option enters the DOM. Comfortable to ~500 options; beyond that, wire a virtualising renderer via CNGX_PANEL_RENDERER_FACTORY.

Pure-TS linear scale. Maps a numeric domain [d0, d1] to a numeric range [r0, r1] via standard linear interpolation. Domain may be inverted (d0 > d1) for SVG Y-axes where the top of the chart is the highest data value but the lowest pixel coordinate.

Values outside the domain extrapolate. Charts that need overflow clamping clamp at the data layer, not the scale.

(v: number) => number mapping domain values to range values.

Builds a LocalItemsBuffer. Reads compareWith lazily so mid-flight comparator swaps are honoured.

Create a fully manual async state — no HTTP, no automatic loading.

Use for local operations: heavy computations, Web Workers, complex local processes. Does not require an injection context — uses only signal() and computed().

readonly processState = createManualState<ProcessResult>();

async handleProcess(): Promise<void> {
  this.processState.set('loading');
  this.processState.setProgress(0);
  const result = await heavyComputation((p) => this.processState.setProgress(p));
  this.processState.setSuccess(result);
}

Single shared bidirectional-sync factory for cngx organisms / directives that bridge a cngx presenter against a Material parent (<mat-tab-group>, <mat-stepper>, etc.).

Lives at Level 2 in @cngx/common/data parallel to createCommitController. Material types never enter the signature — the caller maps Material-specific events and property accessors to a host-agnostic shape at the directive boundary.

Installs:

1. A presenter→Material effect() that tracks presenterIndex and writes through writeSelectedIndex, equality-guarded against readSelectedIndex() to suppress redundant writes. The Material read+write pair runs inside untracked() per reference_signal_architecture rule 2.
2. A Material→presenter subscription that forwards each selectionChange$ emission to onMaterialSelection (equality-guarded against presenterIndex() so a Material event whose value already matches the presenter is dropped — closes the re-entrancy loop).

Both sides clean up via destroyRef.

Material-eager-advance reconciliation. Material's MDC click handler advances selectedIndex before the Material→presenter subscription forwards the click. When the presenter HOLDS its index (pessimistic mode + bound commitAction), the subscriber does NOT write Material back: on a SUCCESSFUL commit the presenter later advances to the clicked target and Material is already there, so the mirror effect is a no-op (no flash); on a REJECTED commit the presenter never moves, leaving Material eager-advanced on the refused tab. The host detects the rejection through its own commit lifecycle and calls CngxMaterialBidirectionalSyncHandle.reconcile to snap Material back. Writing from inside the subscriber instead is unsafe: Material's selectedIndex read-back lags a programmatic write, so the mirror effect's equality guard reads a stale value and skips the corrective write, sticking the visual on the wrong tab.

Self-echo suppression (loop-safety). Every programmatic selectedIndex write makes Material re-emit selectionChange. The factory records each value it writes and drops the matching echo (indexOf + splice, which also prunes earlier writes whose echo Material coalesced away) before any other processing. This is load-bearing for an ASYNC commit-action: Material emits the echo a microtask later, by which point the commit may have advanced presenterIndex, so an equality-only guard (presenterIndex() === idx) would FAIL to drop the echo — it would re-enter the subscriber and ping-pong against the in-flight navigation (the demo freezes). Matching the echo by the value we wrote drops it regardless of where the presenter has moved.

Set-based bidirectional sync between a <mat-accordion>'s projected <mat-expansion-panel> tree and the headless CngxAccordion open-set. The accordion open-set is a multi-membership Set<string>, so the index-based createMaterialBidirectionalSync (@cngx/common/data) does not fit — this helper syncs per-panel expanded against set membership instead.

Installs two effects and one listener-set:

1. brain→Material — an effect() tracking panels() and, per panel, accordion.isOpen(id). When the open-set (or the panel list) changes it writes panel.expanded to match, guarded by a re-entrancy flag so the resulting synchronous expandedChange echo does not loop back. The Material writes run inside untracked() per reference_signal_architecture rule 2.
2. subscription reconcile — an effect() tracking only panels(); inside untracked() it subscribes freshly-added panels' expandedChange and drops removed ones (diff-only churn, a Map<P, subscription>).
3. Material→brain — each expandedChange listener flips the brain via accordion.toggle(id), but only when the incoming expanded differs from the brain's current (clamped) membership, so a programmatic echo (or a redundant Material emit) is a no-op. Routing through toggle (not a raw set-write) means single-mode arbitration and the exposed openIds model stay identical to the native CngxAccordionPanel DOM path.

The idempotent membership check plus the re-entrancy flag together close the loop: the flag drops the synchronous echo CdkAccordionItem emits from its expanded setter during our own write, and the membership check drops any Material emit that already agrees with the brain.

Translates a Material MatStep into a cngx CngxStepRegistration.

• id - always a fresh idSeed() value. Mirrors the tabs instrumentation handle: a label-keyed id would collide when two steps share a label.
• kind - fixed at 'step'. The instrumentation path does not project nested <mat-step> groups (Material's stepper has no group-of-steps concept; group-aware semantics belong to the <cngx-stepper> thin-wrapper organism).
• label - snapshot signal resolved through a four-tier fallback at registration time so cngx-side phrases (announcements, aria-label composition, telemetry) never read empty when Material consumers project a <ng-template matStepLabel>:
  1. MatStep.label when it is a plain string - the canonical shape and the only one that emits a runtime change Material itself observes.
  2. MatStep.ariaLabel when the consumer set the input - designed exactly as the substitute for template labels.
  3. Static-text read from MatStep.stepLabel.template via a throwaway detached EmbeddedViewRef (readMatStepLabelTemplateText). Captures literal matStepLabel markup; dynamic interpolation bails through to (4).
  4. Step <id> - deterministic, derived from the cngx handle id. Always non-empty. Documented limitation: runtime label changes do not propagate. CDK's CdkStep does not expose a _stateChanges Subject analogous to MatTab._stateChanges, so cngx cannot re-trigger the snapshot when Material flips the input later. Surface the same Material-internal coupling family typed in MaterialPrivateSurfaces.CompletedOverrideSource.
• disabled - fixed false. Material owns step gating via linear + editable + completed; surfacing a cngx-side disabled would duplicate Material's own click-time enforcement and is ignored by <mat-stepper> itself.
• state - computed() over MatStep.hasError / MatStep.completed. CdkStep.completed's getter reads _completedOverride() - a WritableSignal<boolean | null> typed in MaterialPrivateSurfaces.CompletedOverrideSource. The cngx computed transitively tracks that signal through the getter and re-fires whenever Material flips completion. hasError is a plain property setter on CdkStep, NOT a Signal - a hasError write that is not paired with a completed change does not re-trigger this computed. In practice Material wizards write the two together (step.hasError = true; step.completed = false in error-handler patterns and inside Material's own error-state matchers) so the limitation is benign for the documented usage pattern.
• errorAggregator - points at the shared NO_ERROR_AGGREGATOR constant.

Translates a Material MatTab into a cngx CngxTabHandle plus a writable errorAggregator slot the [cngxMatTabError] directive binds.

• id - fresh idSeed() value; a label-keyed id would collide when two tabs share a label.
• label / disabled - computed signals retriggered by toSignal(matTab._stateChanges). Bridge lifetime is tied to the supplied injector (typically a per-tab child EnvironmentInjector). _stateChanges is a Material-internal surface.
• errorAggregator - writable seeded at undefined; [cngxMatTabError] writes its bound aggregator in and resets on teardown. The handle exposes .asReadonly() to preserve the CngxTabHandle contract.
• directError - writable seeded at false; [cngxMatTabErrorFlag] writes its string | boolean value in and resets on teardown. Folds into hasError / errorMessage.

Default factory that hands out the root-scoped CngxMenuAnnouncer singleton. Consumers wire a custom announcer by replacing CNGX_MENU_ANNOUNCER_FACTORY.

Must run inside an injection context.

Resolve the CngxMenuAnnouncerLike from the current injection scope via the factory token. Must run inside an injection context.

Default factory. Pure closure over opts - no Angular DI. Mirrors the shape of @cngx/forms/select's createDismissHandler so future cross-family consolidation has a clean target.

Override via CNGX_MENU_DISMISS_HANDLER_FACTORY for telemetry-wrapped or test-doubled dismissal.

Build the dismiss lifecycle for a menu-bearing trigger directive. Lazily instantiates the handler on first attach() so the trigger's popover input is bound before the factory reads it. The returned lastSource signal is owned by this binding - the factory writes it via its onDismiss callback, which runs from DOM event handlers (never inside an Angular effect()).

Returns a reactive Signal<boolean> that reflects whether the host window matches a CSS media query (e.g. (max-width: 480px)). Used by <cngx-stepper> to drive its mobile auto-collapse template branch.

In SSR / non-DOM environments the signal stays false and the listener is never wired.

Resolves the active stepper display mode by combining a viewport media-query with the configured mobileCollapse policy. 'classic' keeps the full strip; 'text' / 'dots' swap to the matching compact variant.

Creates a mock CngxFieldAccessor that returns a fully writable MockFieldRef. Tests can mutate any signal to simulate field state changes.

const { accessor, ref } = createMockField({ name: 'email', required: true });
// Pass `accessor` to [field] input
// Mutate ref.touched.set(true) to simulate interaction

Creates a mock ValidationError.WithFieldTree for testing.

Pure-TS ordinal scale. Maps a discrete categorical domain to a cycling palette of values (typically colours). When the domain is longer than the palette, mappings wrap modulo palette length.

Callable (v: T) => string returning the palette entry for v. Lookup of an unknown value returns the palette's first entry.

Scroll-into-view effect for any strip-based organism (tabs, stepper headers, future scrolling lists).
Tracks activeId and scrolls the matching [id="<itemId>-header"] into view.

The DOM call sits in untracked() (only activeId is tracked).
scrollIntoView is missing in jsdom - guarded with optional chain.

UX / a11y#

• The active tab is never stranded off-screen: when activation moves to a tab clipped by overflow (keyboard arrow, deep link, programmatic select), its header scrolls into view, so the focused and selected tab is always visible (WCAG 2.4.7 Focus Visible).
• Pairs with the overflow surface: picking a hidden tab from the "More" popover scrolls it back into the strip, and the overflow recompute then self-trims - keyboard navigation and the overflow list stay in sync.
• Motion is overridable for reduced motion: the default is smooth-center along the inline axis; pass scrollOptions (e.g. behavior: 'auto') to honour prefers-reduced-motion or to scroll vertically.

// Install once from the organism's field-init (needs an injection context).
createOrganismScrollSync({
  activeId: this.presenter.activeId, // Signal<string | null>
  hostElement: this.hostElement,     // holds the [id="<tabId>-header"] buttons
  injector: this.injector,
  // scrollOptions omitted -> smooth-center; override for reduced motion:
  // scrollOptions: { behavior: 'auto' },
});

Resets the AD highlight on popover close.
Keyboard-open paths (ArrowDown / End / typeahead on the closed trigger) set activeIndex via AD's own keydown listener before opening - unaffected. Mouse-open leaves activeIndex === -1 so the popover renders unhighlighted.
Without this reset, the next open would inherit a stale index from the prior keyboard session.

Must run in injection context.

UX / a11y#

• Closing the popover resets the highlight, so a keyboard session never leaves a stale aria-activedescendant for the next open.
• Each row has a stable descendant id (tabOverflowOptionId), so the SR focus reference never dangles across re-renders.
• Highlight is virtual focus, not DOM focus: keyboard nav moves aria-activedescendant while real focus stays on the trigger (APG menu-button); the rows are never tab stops.

Wires the 3-stage template cascade for the overflow molecule's two visible regions:
per-instance directive > CNGX_TABS_CONFIG.templates.overflow* > built-in markup (template-outlet returns null). \

Pure - no DI, no side effects, no destroy hooks. Safe to call from a component's field-init block. Mirrors the select-family createTemplateRegistry pattern.

DOM id for a hidden-tab option row in the overflow listbox.
Stable across CD passes so aria-activedescendant resolves to the same <li>. -overflow-option suffix avoids collision with the strip-button (-header) and per-tab descriptor (-desc).

Builds the paginator live-region message as a single derived signal - no class logic baked into the shell, so the skin still ejects cleanly. The message is a linkedSignal over [pageIndex, totalPages, isBusy] from CNGX_PAGINATOR_HOST: it speaks "Page N of M" on every effective-page change (navigation OR a total-shrink clamp, so the clamp is never silent), "Loading" while busy, and "Updated" on the first settle after busy. Phrasing comes from injectPaginatorConfig.

The previous source value (held by linkedSignal) is what distinguishes a settle from a steady state, so there is no signal write in an effect and no imperative previous tracking. Identical consecutive messages dedupe through the signal's value equality, so the live region never re-announces a no-op.

Must run in an injection context (call as a field initialiser on the shell).

Shared nav-button glue. Composition, not an abstract base class: each of the four segments calls this factory as a field initialiser and binds the same template, differing only in selector, glyph, and the three options here.

One effect() that emits openedChange/opened/closed on panelOpen flips and restores focus to the trigger after close. Output emits + focus call wrapped in untracked. Injection context required.

Builds the dependency-less default password-strength estimator.

The heuristic scores length tiers (>= 8 / 12 / 16) plus character-class diversity (lower, upper, digit, symbol) and subtracts a point for a run of three or more identical characters, then clamps to 0..4. It ships no dictionary - enterprises swap in zxcvbn or similar via CNGX_PASSWORD_STRENGTH_FACTORY.

Pure-TS path builder with single-slot LRU memo on (data, xScale, yScale) reference identity. Pure TS, no Angular dep. Compute guard only - does not know about signals or equal functions; the d computed in <cngx-line> carries the cascade guard separately.

The cache returns the previous result when all three inputs are reference-equal to the previous call. Any reference mismatch triggers a rebuild and updates the slot.

Each call to createPathBuilder returns a fresh builder with its own lastData / lastX / lastY slots - there is no cross-call / cross-consumer state. The cascade guard for layer atoms is the equal: (a, b) => a === b on the builder computed; combined with Angular signals' default behaviour of skipping re-emissions when the inputs to the computed are unchanged, two consecutive cascade ticks with the same (y, x, curve) produce the same builder instance.

Hierarchy-preserving option model derived from projected DOM. Leaves stay leaves, groups stay groups; createSelectCore reflattens for AD lookup. Labels are plain-text via {{ }} interpolation.

Builds a CngxPanelRendererFactory backed by a consumer-owned CngxRecycler. Slices flatOptions to the recycler window and forwards spacer heights + setsize. Consumer wires connectRecyclerToActiveDescendant separately; this factory doesn't touch AD state.

Plain factory for the reorder-commit flow used by CngxReorderableMultiSelect. Operates on ordered arrays with same-membership semantics.

Why a separate factory (not a flag on createArrayCommitHandler): the array handler's reconcileValues uses sameArrayContents to short-circuit writes when the target matches current state - a pure reorder would silently skip. A bypassReconcile flag would complicate every other call-site; a dedicated factory keeps the array handler's hot path small.

CngxTreeSelect.dispatchValueChange follows the same pattern inline; a future refactor could lift it here.

Scalar-shape commit flow shared by scalar select variants. Owns commit-controller lifecycle, reconciliation, togglingOption.set(null) on success, optimistic rollback on error. Consumer owns change-event emission, announcer severity (onCommitError), input-text mirroring (onValueWrite), and popover-close timing - handler never closes the panel.

One or two effect()s for input-trigger variants: skipInitial-gated searchTermChange forward (when emit is set) and auto-open-on-typing. External calls wrapped in untracked. Injection context required.

Create a signal-based selection engine that reads and writes an external WritableSignal<T[]>.

const values = signal<User[]>([]);
const selection = createSelectionController(values, { keyFn: (u) => u.id });

selection.select(alice);
selection.isSelected(alice)();      // true
selection.isSelected(alice) === selection.isSelected(alice); // stable

Pure factory for a slider's keyboard + pointer-drag behaviour - the shared interaction brain for both CngxSlider (single) and each CngxSliderThumb (range). Arrow / Page / Home / End map onto the core's step helpers; pointer-down captures the pointer and drags via the supplied fractionFromPointer. Keeping this in one factory means the track and the thumb cannot drift apart.

Maps a pointer position to a 0..1 track fraction against el's geometry. Vertical sliders measure bottom-up (fraction 0 at the lower edge) to match the skin's bottom-anchored fill. Shared by the single slider and the range host so the geometry math lives in exactly one place.

Derives a slider's tick marks + labels from its bounds, shared by CngxSlider and CngxRangeSlider so the math lives once. marks gates the repeating-gradient interval; labels gates the numeric stops; both are independent. The values signal is arrayEqual-guarded.

Derives the shared sort-header state for one column from a CngxSort getter.

Both CngxSortHeader (table context, aria-sort) and CngxDgaSortHeader (disclosure context, role="button" + aria-describedby) compose this factory and keep only their own a11y presentation. The factory is a11y-agnostic - it returns the plain derived signals each header maps to its own DOM/ARIA surface.

The derived { entry, isActive, isAsc, isDesc, priority, toggle } bundle.

Build a stepper commit handler over an existing CngxCommitController. Resolves Observable<boolean> / Promise<boolean> / boolean returns into a unified accept: boolean outcome.

Builds the collapsed-group pointer-navigation view. Level-2 helper so the organism stays a thin renderer.

Indices resolve against flatSteps (DFS order, live flatIndex) rather than group.children - the flattener spreads group nodes but leaves their children as the tree projection where every step still carries the seeded -1. Each candidate is gated by canNavigateTo + busy (mirroring the step-header reachability), so a linear-blocked leading step is skipped to the first reachable one.

Builds the collapsed-group summary view. Level-2 helper so the organism stays a thin renderer. status mode defers its SR phrasing to the group's existing status-phrase span, so srText returns null there. English defaults (locale via the i18n cascade is a follow-up).

Terminal-step totals for a group's subtree; reads each step state().