CngxActiveDescendant
projects/common/a11y/active-descendant/active-descendant.directive.ts
Import#
import { CngxActiveDescendant } from '@cngx/common/a11y'
Description#
WAI-ARIA active-descendant pattern. Focus stays on the host; the active
option is reported via aria-activedescendant.
When to use this vs. CngxRovingTabindex
- Active-descendant when focus stays on one container (listbox, menu, combobox input) and items must not be tab-stops. Screen readers announce the referenced option while the focus ring stays on the host.
- Roving tabindex when items themselves are tab-stops (toolbar, tab
list, grid cells). See
CngxRovingTabindex.
Item registration
Items register either by providing CNGX_AD_ITEM via hostDirectives /
providers, or by passing a Signal<ActiveDescendantItem[]> through the
items input. The items input wins when both are present; use it when
items come from a dynamic data source.
Virtualization
When virtualCount is set, navigation can address indices not currently
in the DOM. pendingHighlight tells the consumer to scroll the missing
item into view; the consumer calls clearPendingHighlight() afterwards.
Material/CDK equivalent
Same model as cdk-listbox and mat-select, without the visual shell and
driven by signals instead of ListKeyManager.
Metadata#
Host#
Relationships
Index#
Properties
Methods
Outputs
HostBindings
HostListeners
Inputs#
Whether the first non-disabled item is highlighted automatically.
falseOptional explicit item list. When provided, takes precedence over items
registered via CNGX_AD_ITEM. Useful for combobox-style consumers that
drive the menu from a dynamic data source - pass the unwrapped array
(typically the result of a computed()), Angular's signal inputs make it
reactive automatically.
"vertical" | "horizontal"Arrow-key navigation axis. Defaults to 'vertical' (listbox/menu style).
'vertical'Whether disabled items are skipped during navigation and value lookup.
truenumber | undefinedWhen set, navigation treats the range [0, virtualCount) as the item
space even if only a subset is rendered. Targets outside the rendered
range surface as pendingHighlight for scroll-and-retry protocols.
Outputs#
Instance Properties#
Methods#
highlightByIndex(index: number)Highlight by zero-based index. Out-of-range indices are ignored.
Disabled items are rejected when skipDisabled() is true.
highlightByValue(value: unknown)Highlight the first item whose value matches (via Object.is). No-op if
no match. Disabled items are rejected when skipDisabled() is true.
unknowntypeaheadChar(ch: string)Push a printable character into the typeahead buffer and jump to the next matching option. Exposed for external keyboard hosts (e.g. a select trigger) that keep focus on themselves while using active-descendant semantics on a separate listbox.
Consumers should only forward single-character printable keys (length === 1,
non-whitespace). Navigation keys and non-printables must not be forwarded.
HostBindings#
| Binding | Expression |
|---|---|
[attr.aria-activedescendant] | activeId() |
HostListeners#
| Event | Handler |
|---|---|
(keydown) | keydown() |