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.

The adapter binds to the control instance passed at call time and never re-binds. Replacing that instance later (FormGroup.setControl(), rebuilding the form) goes unnoticed - the subscriptions stay on the old control and the accessor freezes on its last mirrored state. Call adaptFormControl again with the new instance and swap the [field] binding instead.

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).

Read the resolved timeline config. Runs in an injection context.

Root-level provider. Apply once in bootstrapApplication / appConfig.providers.

Component-scoped override. Returns Provider[] rather than EnvironmentProviders because viewProviders rejects opaque environment providers.

Features merge onto the parent config - an enclosing scope, or the root provider, or the library defaults when neither is present - so a region can re-phrase one label without resetting every other one the app set.

Merge label overrides into the cascade. Keys left out keep their English library default, so a consumer translates what they need and nothing more.

provideTimelineConfig(
  withTimelineLabels({
    retry: 'Erneut versuchen',
    emptyFallback: 'Noch keine Ereignisse.',
    groupLabel: (group) => group.start.toLocaleDateString('de-AT'),
  }),
)

Merge app-wide slot template defaults into the cascade. Keys left out keep whatever an earlier feature set, and a per-instance slot directive still wins over anything set here.

One bag rather than a with*Template builder per slot, matching how the select family carries its own slot defaults - the timeline has eight slots and near-identical builders would only add surface.

readonly emptyTpl = viewChild.required<TemplateRef<CngxTimelineEmptyContext>>('emptyTpl', {
  read: TemplateRef,
});

providers: [provideTimelineConfig(withTimelineTemplates({ empty: this.emptyTpl() }))]

Reduce a feature list onto a base config, merging text and axes in isolation.

Convenience accessor for the resolved panel configuration. Runs in an injection context; resolves through the cascade. Equivalent to inject(CNGX_A11Y_PANEL_CONFIG).

Application-root configuration cascade for the accessibility panel. Pass any combination of with* features in bootstrapApplication's providers; supplied features merge with the library defaults, so consumers only declare what they override.

Component-scoped 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 one panel can re-scope its axis subset or labels without disturbing the rest of the app. This is the component-scope tier of the resolution cascade: provideA11yPanelConfigAt (nearest) wins over provideA11yPanelConfig (root), which wins over the library defaults.

Replace the rendered axis list - reorder groups, drop an axis, or restrict the options a group offers. Supplying a subset renders only those groups.

provideA11yPanelConfig(
  withA11yPanelAxes([
    { axis: 'textScale', reset: 'md', options: [
      { value: 'md', label: 'Default' },
      { value: 'lg', label: 'Large' },
    ] },
  ]),
);

Override any subset of the panel text - axis group labels, the Reset label, the default heading, or the Reset announcement. The axes record merges key-by-key, so a single axis can be relabelled in isolation.

provideA11yPanelConfig(
  withA11yPanelLabels({
    heading: 'Barrierefreiheit',
    axes: { motion: 'Bewegung' },
    resetMessage: 'Einstellungen zurueckgesetzt',
  }),
);

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 }),
);

Apply the visually-hidden (screen-reader-only) recipe to a dynamically created dialog node.

Inline styles instead of relying on the cngx-sr-only class alone so the live region and the drag instruction stay hidden even when no cngx stylesheet is loaded. The node remains perceivable to AT - describedby targets and live regions must never be display: none.

Internal helper - intentionally not exported from public-api.ts.

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. A NaN bound behaves like an open bound (every comparison against NaN is false, so that side never clamps) - pass-through, not an error. 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).

A context that a resume() can lift - suspended, or Safari's interrupted.

Map a raw AudioContext.state onto AudioStatus. Safari reports a non-standard 'interrupted' (phone call, Siri, audio-route change) that the spec union does not carry; it resumes on the next gesture exactly like a suspended context, so it folds to 'suspended' rather than being cast into the union. Any unknown value degrades to 'suspended', the safe resting state a subsequent resume() can lift.

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.

Strings parse leniently via Number.parseFloat: a leading numeric prefix wins even when a unit trails it ('12px' coerces to 12, '1.5rem' to 1.5). A string with no leading number ('px12', 'true') returns fallback. Booleans and objects are never numeric and return fallback.

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.

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.

The treetable keeps its own numeric-aware localeCompare collation - this comparator (< / > on the extractor output) is not a drop-in replacement for it.

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

Returning the literal false from the visitor stops the walk immediately - no further node is visited at any depth. Any other return value continues the traversal, so existing visitors (void or value-returning arrows alike) keep their behavior. The return type is unknown rather than boolean | void on purpose: a concise arrow like (n) => seen.push(n) must stay assignable.

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 index half of the clamp path is suppressed while the brain is busy or total is 0, so a transient total drop during a refetch never persists a page-0 clamp into a controlled consumer; a clamp that survives the settle emits then.

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.

Route submenu hover intent through the focus stack. Watches the CngxMenuSubmenuLike.hoverIntent signal of every submenu companion registered anywhere in the menu tree and routes its edges through the same primitives keyboard and click use: a settled hover opens via CngxMenuFocusStack.openSubmenuFor (stack-tracked, first item highlighted, keyboard-visible), a settled un-hover closes via CngxMenuFocusStack.closeSubmenuFor (stack popped innermost-first). The submenu companion itself owns NO open/close mechanics for hover - it only derives intent.

The walk covers the WHOLE registered tree, not just the open chain: a submenu whose menu drops out of the chain (popped by a chain-correcting open, cleared by reset()) still decays its intent afterwards, and that false edge must be observed or the bookkeeping would go stale and fire a spurious close when the menu re-enters the chain. Items in a hidden menu cannot produce real pointer events, so the extra tracking never opens anything on its own.

Edge-driven, not state-reconciling: a keyboard-opened submenu whose intent never settled true is left alone, so pointer-less operation is unchanged.

Must run in an injection context (constructor / field initializer) - it installs an effect. Every focus-stack owner wires it once: CngxMenuTrigger, CngxContextMenuTrigger, and CngxContextMenuFor.

Default focus-stack implementation. Behaviour matches the W3C APG Menu Button pattern that CngxMenuTrigger shipped inline before extraction.

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.

Aggregate N independent CngxAsyncStates into one derived CngxAsyncState.

Pure, keyless, and injection-context-free - it reuses buildAsyncStateView so every derived flag (isLoading, isSettled, hasData, ...) stays single-source-consistent with every other producer. The result is a CngxAsyncState, so it flows through cngx-async-container, the transition bridges, and every other consumer unchanged.

Combined status follows a fixed priority rule (first match wins):

1. any source error -> error
2. else any source loading/pending -> loading
3. else any source refreshing -> refreshing
4. else all sources success -> success
5. else -> idle (empty list, or any remaining idle)

data is the per-source data() values in input order; each element is T | undefined because a source carries no data until it reaches success. error is the first error in input order (raw, for the single-error bridge path). Emptiness is the aggregate rule - empty only when it has at least one source and every source is itself empty - which the data shape cannot infer (an N-element array is never length 0), so it is supplied explicitly.

Two view fields are constant by construction: rule 2 collapses pending into loading, so the combined status is never 'pending' and isPending is always false; and progress is always undefined because per-source progress values have no comparable scale to aggregate over (a determinate upload percentage and an indeterminate fetch cannot be averaged honestly).

Declarative live-region phrase with transition arming and expiry - the shared shape behind "voice the change, not the standing state". A real transition (arm) sets the phrase; an expiry transition (spend) clears an already-voiced phrase so a later content change cannot re-announce it; everything else keeps the previous phrase.

Fully derived (linkedSignal over source snapshots) - no effect, no imperative previous-value tracking.

Eager-read caveat. linkedSignal only observes source snapshots it is actually read under. A consumer that renders this phrase behind a short-circuiting arm (busy() ? busyPhrase : phrase()) MUST read the phrase eagerly before branching, otherwise the phrase never observes the busy-start snapshot and the spend transition is skipped.

private readonly selectionPhrase = createAnnouncementPhrase({
  source: () => ({ selected: this.selected(), loading: this.loading() }),
  arm: (curr, prev) =>
    curr.selected !== prev.selected ? (curr.selected ? 'Selected' : 'Deselected') : null,
  spend: (curr, prev) => curr.loading && !prev.loading,
});

Array-shape commit flow shared by CngxMultiSelect and CngxCombobox. Owns commit-controller lifecycle, reconciliation via sameArrayContents, togglingOption.set(null) on success and at beginClear entry, optimistic rollback on error, live-region "removed" announce on a successful clear and the announceError hook on failure. 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.

Canvas rendering backend. Mounts a <canvas> absolutely positioned over the chart's SVG frame and paints each LayerGeometry onto its 2D context: Path2D stroke/fill for line/area, per-mark loops for bar/scatter, moveTo/lineTo for threshold, fillRect for band.

Colors resolve through a closure-local cache: the first paint() reads each CSS custom property once via getComputedStyle(host); subsequent paints hit the cache, so the paint hot path performs zero synchronous DOM reads. CngxChartRenderer.invalidateColorCache clears it - the renderer controller calls it on a dimensions() change (a proxy for layout / theming reflow). It never writes the chart context's renderSvg gate; the shell owns that.

The plot inset needs no handling here. Every geometry this backend paints was derived from ctx.xScale() / ctx.yScale(), whose ranges are already the inset plot area, so canvas marks land exactly where SVG marks would without the renderer knowing an inset exists. Axis decoration never reaches this file at all: there is no axis branch in KIND_VARS and no text call anywhere in the backend, because CngxAxis renders its own SVG ungated by renderSvg in both modes. The two paths therefore cannot disagree on where the plot area is, and only one of them ever draws an axis.

They do differ on what happens past the box edge: a canvas clips natively at the element bounds, and since the SVG root no longer sets overflow: visible it now clips there too. Out-of-domain data is cut off on both paths.

Owns the renderer mount / destroy / paint reactive lifecycle so the chart shell holds no rendering brain. Installs two effects:

• mount - tracks mode(); on change, destroys the previous backend, builds the new one via factory, mounts it, and seeds the first paint.
• paint - tracks geometries() and the (structurally-deduped) dimensions; repaints on every geometry emission and invalidates the backend's color cache when the dimensions actually change.

Both effects wrap their imperative renderer calls in untracked() so the renderer's own signal reads never feed back into the effect graph. The dimensions are tracked through a linkedSignal guarded by dimensionsEqual, so a resize observer re-emitting the same width/height literal does not trigger a redundant cache invalidation.

Must run in an injection context (the chart shell calls it from a field initialiser / constructor). Ships as a plain create* factory the shell calls directly - no DI token, since the only second consumer today is a test double, which injects a fake factory through the deps.

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.

Creates a CngxContainerSize over element.

Observes the border box, so the reported size matches what an inline-size container query measures. The property() reads are plain computed()s over the same resize signal - the browser has already re-evaluated every container query by the time a ResizeObserver callback runs, so the read returns the current value without a second scheduling hop.

Reads the nearest query container declared by a [cngxContainer] ancestor, or observes target (default: the host element) when there is none.

Use it where a component must branch structurally on the width it was given

• a different template, a focus move, an aria-modal flip. Purely visual adaptation needs no TypeScript at all: write a @container rule.

private readonly container = inject(CNGX_CONTAINER_SIZE, { optional: true });
private readonly wide = this.container?.property('--cngx-thing-wide', this.host) ?? signal('').asReadonly();
readonly mode = computed(() => (this.wide() === '1' ? 'side' : 'over'));

A component that declares the container in its own stylesheet and reads it itself passes its host explicitly and reads the property off ::after - there is no descendant to carry the value:

private readonly host = inject(ElementRef).nativeElement as Element;
private readonly container = injectContainerSize(this.host);
private readonly narrow = this.container.property('--cngx-thing-narrow', this.host, '::after');

Build the popover-facade adapter the submenu brain (CngxMenuItemSubmenu) drives instead of a [cngxMenuItemSubmenu] popover input. Every member delegates to the target panel's own CngxPopover, reading target() lazily so the facade stays valid across [submenu] changes and inert (no visible, empty id) while the target is unbound. show() delegates to the supplied open routing rather than popover.show(), so opening goes through the trigger's focus stack (Pillar 1) instead of bypassing it.

Internal decompose glue, not a consumer contract - NOT exported from public-api.ts. Extracting it keeps CngxContextMenuItem's class body a thin shell (reference_atomic_decompose rule 1).

Build a CngxContextMenuTriggerCore from its dependencies. Pure factory - no Angular DI; the caller resolves collaborators and passes them in.

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()).

null falls through too: the ?? treats a deliberate null on the priority source exactly like absence and reads the next source. A priority source that needs to express "deliberately empty" must yield a real value ([], '') instead of null - there is no way to make null win here.

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.

Builds the default matcher: a pure label/keyword ranker. An empty query returns every (scoped) command at score 0 in registration order; a non-empty query keeps only commands that match label or keyword, ranked label-exact > label-prefix > label-substring > keyword. The optional scope filters to commands whose group equals it.

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, over the shared resize kernel (createResizeSignal) rather than a hand-rolled ResizeObserver. Not the CngxResizeObserver directive - that can only attach through hostDirectives, and this factory is called from a field initialiser. 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 - both derive a rung from the space the stepper was given and return a single Signal; this one measures, the other reads what CSS resolved.

'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.

The contract, in resolution order:

1. Unknown field (fieldDef is undefined) - false. The expression references a field the consumer never declared.
2. Unfilled value - true. The user picked a field and an operator but supplied no value (null / undefined / ''), so the row is a no-op that must not exclude every item. Operators whose definition is valueless (builtin isEmpty / isNotEmpty) are exempt and evaluate normally; the registry passed via options.operators extends this exemption to consumer-registered valueless operators.
3. Unknown operator - one console.warn per key in dev mode, then false for every item. An operator that reaches evaluation without a registered definition is a wiring bug, and a loud conservative false beats a silent one.
4. Otherwise the resolved CngxFilterOperatorDef.evaluate runs with the item value, the expression value, and the evaluation context.

Semantics of the builtin definitions:

• eq / neq compare with Object.is identity - no coercion, no case folding.
• contains / startsWith / endsWith require both sides to be strings (anything else is false) and are case-SENSITIVE unless options.caseInsensitive is true, which lowercases both sides.
• gt / gte / lt / lte order numbers, Date instances, and strings (lexicographic). Nullish operands and mixed/unsupported type pairs compare as NaN, so every ordering test on them is false.

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).

Evaluation contract per expression - see evaluateExpression: unknown field keys evaluate false, unfilled values short-circuit true, unknown operators warn once in dev mode and evaluate false. Pass options to evaluate against a consumer-extended operator registry or with case-insensitive substring matching.

Field-control ARIA scaffolding shared by every control that provides CNGX_FORM_FIELD_CONTROL against a surrounding cngx-form-field: id/disabled/errorState/focused plus the ARIA projection (describedby/labelledby/invalid/required/busy/errormessage/readonly/ disabled) and the focus handlers. Sibling of createFieldSync; unlike the sync it needs no injection context - the caller passes its (optional) presenter.

The host still owns its bindings: each directive binds only the signals its host template declares, and control-specific surfaces (empty, aria-label fallbacks) stay in the control.

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.