@neuravision/ng-construct 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuravision/ng-construct",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Angular components for the Construct Design System",
   "keywords": [
     "angular",
@@ -12,7 +12,7 @@
     "@angular/common": "^21.1.0",
     "@angular/core": "^21.1.0",
     "@angular/router": "^21.1.0",
-    "@neuravision/construct": "^1.1.4",
+    "@neuravision/construct": "^1.2.0",
     "@lucide/angular": "^1.0.0-rc.0"
   },
   "dependencies": {

package/types/neuravision-ng-construct.d.ts

@@ -3216,6 +3216,288 @@ declare class AfTableCellComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<AfTableCellComponent, "af-table-cell", never, { "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
+/**
+ * Node descriptor consumed by `af-tree`.
+ *
+ * Generic over the application data type `T` so consumers can attach typed
+ * payloads without losing type safety in slot templates.
+ */
+interface TreeNode<T = unknown> {
+    /** Stable id; used as the default `trackBy` key. */
+    id: string;
+    /** Human-readable label; rendered as a11y fallback when no `nodeContent` slot is provided. */
+    label: string;
+    /** Arbitrary application data — typed via the generic parameter. */
+    data?: T;
+    /** Child nodes; `undefined` triggers async-load on first expand, `[]` is a known-empty leaf. */
+    children?: TreeNode<T>[];
+    /** Disabled nodes cannot receive focus, expand, select, or activate. */
+    disabled?: boolean;
+    /** Force leaf rendering even when `children` is undefined (skips async-load hint). */
+    isLeaf?: boolean;
+    /** Renders a busy indicator on the row — set while children are loading. */
+    loading?: boolean;
+    /** Free-form metadata; e.g. `{ orphan: true }` enables the warning state. */
+    meta?: Record<string, unknown>;
+}
+/** Selection mode for the tree. */
+type TreeSelectionMode = 'none' | 'single' | 'multiple';
+/** Payload of the `nodeToggle` output. */
+interface TreeToggleEvent<T = unknown> {
+    node: TreeNode<T>;
+    expanded: boolean;
+}
+/**
+ * Context object passed to slot templates so consumers can render bespoke
+ * content while still receiving the active filter for custom highlighting.
+ */
+interface TreeNodeTemplateContext<T = unknown> {
+    $implicit: TreeNode<T>;
+    node: TreeNode<T>;
+    level: number;
+    filter: string;
+    expanded: boolean;
+    selected: boolean;
+    focused: boolean;
+}
+
+/**
+ * Accessible Tree component implementing the WAI-ARIA Tree View pattern.
+ *
+ * Wraps the Construct `ct-tree` CSS component into a signal-based, OnPush
+ * Angular component with full keyboard navigation, type-ahead, single /
+ * multi-selection, async-load support, and client-side filtering.
+ *
+ * @example Static org tree
+ * <af-tree
+ *   [nodes]="organizations()"
+ *   ariaLabel="Organizations"
+ *   [showIndentGuides]="true"
+ *   selection="single"
+ *   [(selectedIds)]="selected"
+ *   (nodeActivate)="open($event)">
+ *   <ng-template #nodeContent let-node>
+ *     <af-icon name="folder" />
+ *     <span>{{ node.label }}</span>
+ *     <af-badge>{{ node.data.customerType }}</af-badge>
+ *   </ng-template>
+ * </af-tree>
+ *
+ * @example Async lazy-load
+ * <af-tree
+ *   [nodes]="nodes()"
+ *   ariaLabel="File system"
+ *   (loadChildren)="onLoad($event)" />
+ *
+ * @accessibility
+ * - Container exposes `role="tree"` and the required `aria-label`.
+ * - Each node is a `<li role="treeitem">` carrying `aria-level`,
+ *   `aria-setsize`, `aria-posinset`, and (when expandable) `aria-expanded`.
+ * - Roving tabindex on the `<li>` so screen readers announce treeitem role,
+ *   level and selection state when focus lands.
+ * - Keyboard: `↑`/`↓` move focus, `→` expands or steps into children,
+ *   `←` collapses or steps to the parent, `Home`/`End` jump, `Enter`
+ *   activates, `Space` toggles selection (multi) or activates (single),
+ *   `*` expands all sibling branches, A–Z performs incremental type-ahead.
+ * - Selection state is mirrored via `aria-selected` only when
+ *   `selection !== 'none'` — leaves implicit selection off in static trees.
+ * - `aria-busy="true"` is rendered on rows whose `node.loading` is `true`.
+ * - Custom slot templates receive the active filter so they can highlight
+ *   matches consistently with the default renderer.
+ */
+declare class AfTreeComponent<T = unknown> {
+    /** Internal id used to scope live-region announcements (debug aid). */
+    protected readonly uid: number;
+    /** I18n bundle resolved via {@link AF_TREE_I18N}. Public so the recursive child component can render labels. */
+    readonly i18n: _neuravision_ng_construct.AfTreeI18n;
+    private readonly announcer;
+    private readonly host;
+    private readonly injector;
+    /** Hierarchical node list. */
+    nodes: _angular_core.InputSignal<TreeNode<T>[]>;
+    /** Container `aria-label` — required by the WAI-ARIA Tree pattern. */
+    ariaLabel: _angular_core.InputSignal<string>;
+    /** Selection mode. Defaults to `'none'`. */
+    selection: _angular_core.InputSignal<TreeSelectionMode>;
+    /** Two-way bound set of expanded node ids. */
+    expandedIds: _angular_core.ModelSignal<Set<string>>;
+    /** Two-way bound set of selected node ids. */
+    selectedIds: _angular_core.ModelSignal<Set<string>>;
+    /** Case-insensitive substring filter; auto-expands ancestors of matches. */
+    filter: _angular_core.InputSignal<string>;
+    /** Render `.ct-tree--guides` (vertical indent lines). */
+    showIndentGuides: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Render `.ct-tree--dense` modifier. */
+    dense: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Render `.ct-tree--bordered` (surface variant). */
+    bordered: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** TrackBy override — defaults to `node.id`. */
+    trackBy: _angular_core.InputSignal<(node: TreeNode<T>) => unknown>;
+    /** Emits when a node is activated (Enter or row click). */
+    nodeActivate: _angular_core.OutputEmitterRef<TreeNode<T>>;
+    /** Emits when a node is expanded or collapsed. */
+    nodeToggle: _angular_core.OutputEmitterRef<TreeToggleEvent<T>>;
+    /** Emits when focus moves to a node. */
+    nodeFocus: _angular_core.OutputEmitterRef<TreeNode<T>>;
+    /** Emits the first time a node with `children === undefined` is expanded (lazy-load hook). */
+    loadChildren: _angular_core.OutputEmitterRef<TreeNode<T>>;
+    /** Template for custom node content; falls back to `node.label` with highlight. */
+    nodeContent: _angular_core.Signal<TemplateRef<TreeNodeTemplateContext<T>> | undefined>;
+    /** Template for action buttons rendered visible-on-hover/focus. */
+    nodeActions: _angular_core.Signal<TemplateRef<TreeNodeTemplateContext<T>> | undefined>;
+    /** Template for warning slot (e.g. orphan indicators). */
+    nodeWarning: _angular_core.Signal<TemplateRef<TreeNodeTemplateContext<T>> | undefined>;
+    /** Template shown when the (filtered) tree is empty. */
+    emptySlot: _angular_core.Signal<TemplateRef<unknown> | undefined>;
+    /** Currently focused node id (drives the roving tabindex). */
+    readonly focusedId: _angular_core.WritableSignal<string | null>;
+    /** Tracks nodes whose `loadChildren` has already fired so we don't refire on re-expand. */
+    private readonly loadedIds;
+    /** Type-ahead buffer + reset timer. */
+    private typeBuffer;
+    private typeTimer;
+    /** Flat list of visible (expanded-path) nodes. Used for keyboard nav. */
+    protected readonly visibleNodeOrder: _angular_core.Signal<TreeNode<T>[]>;
+    /** Top-level filtered nodes — used by the template. */
+    protected readonly visibleNodes: _angular_core.Signal<TreeNode<T>[]>;
+    protected readonly treeClasses: _angular_core.Signal<string>;
+    /**
+     * Set of node ids matching the current filter. Empty set means no filter active.
+     * Filtering is case-insensitive substring on `node.label`.
+     */
+    private readonly filterMatches;
+    /** Auto-expanded ids derived from active filter (ancestors of matches). */
+    private readonly autoExpandedIds;
+    constructor();
+    /** A node is expandable when it has unloaded children, real children, or is loading. */
+    isExpandable(node: TreeNode<T>): boolean;
+    isExpanded(node: TreeNode<T>): boolean;
+    isSelected(node: TreeNode<T>): boolean;
+    /** Returns the children list filtered by the active filter (or all if none). */
+    filterChildren(children: TreeNode<T>[]): TreeNode<T>[];
+    /** Wraps the first case-insensitive match of the active filter in `<mark>` tags. */
+    highlight(label: string): string;
+    /** Toggle the expanded state of `node`; fires `loadChildren` on first lazy-expand. */
+    toggle(node: TreeNode<T>): void;
+    /**
+     * Activate `node` — always emits `nodeActivate` and updates selection per
+     * mode. In `multiple` mode `Enter` activates without toggling selection so
+     * keyboard users can drive a primary action without disturbing checkboxes.
+     */
+    activate(node: TreeNode<T>, source: 'click' | 'enter' | 'space'): void;
+    private applySingleSelection;
+    private toggleMultiSelection;
+    protected handleKeydown(event: KeyboardEvent): void;
+    protected handleClick(event: MouseEvent): void;
+    private expandClosedSiblings;
+    private typeahead;
+    /** Move focus to `node` — updates the roving tabindex and pulls DOM focus into the tree. */
+    private moveFocus;
+    /** Programmatically focus the tree row matching `id`. */
+    focusNode(id: string): void;
+    /** Walk the tree until a node with the given id is found. */
+    findNode(id: string, list?: TreeNode<T>[]): TreeNode<T> | null;
+    /** Locate the parent of `id` — returns null when the node is at root level. */
+    findParent(id: string, list?: TreeNode<T>[]): TreeNode<T> | null;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AfTreeComponent<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AfTreeComponent<any>, "af-tree", never, { "nodes": { "alias": "nodes"; "required": true; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": true; "isSignal": true; }; "selection": { "alias": "selection"; "required": false; "isSignal": true; }; "expandedIds": { "alias": "expandedIds"; "required": false; "isSignal": true; }; "selectedIds": { "alias": "selectedIds"; "required": false; "isSignal": true; }; "filter": { "alias": "filter"; "required": false; "isSignal": true; }; "showIndentGuides": { "alias": "showIndentGuides"; "required": false; "isSignal": true; }; "dense": { "alias": "dense"; "required": false; "isSignal": true; }; "bordered": { "alias": "bordered"; "required": false; "isSignal": true; }; "trackBy": { "alias": "trackBy"; "required": false; "isSignal": true; }; }, { "expandedIds": "expandedIdsChange"; "selectedIds": "selectedIdsChange"; "nodeActivate": "nodeActivate"; "nodeToggle": "nodeToggle"; "nodeFocus": "nodeFocus"; "loadChildren": "loadChildren"; }, ["nodeContent", "nodeActions", "nodeWarning", "emptySlot"], never, true, never>;
+}
+
+/** Translatable strings used by the tree component. */
+interface AfTreeI18n {
+    /** Screen-reader announcement when a node is expanded. Use `{label}` placeholder. */
+    expanded: string;
+    /** Screen-reader announcement when a node is collapsed. Use `{label}` placeholder. */
+    collapsed: string;
+    /** Screen-reader announcement when a node is selected. Use `{label}` placeholder. */
+    selected: string;
+    /** `aria-label` for the chevron toggle button (button is `aria-hidden`, used as fallback). */
+    toggleLabel: string;
+    /** Visually-hidden text inside the `aria-busy` row announcing async loading. */
+    loadingLabel: string;
+    /** Default `<af-empty-state>` message when the tree has zero nodes (and no `empty` slot). */
+    emptyMessage: string;
+    /** Tooltip / aria-label on the orphan warning marker. */
+    orphanLabel: string;
+}
+/**
+ * Injection token to override tree screen-reader announcements
+ * and visible labels for i18n.
+ *
+ * @example
+ * providers: [{
+ *   provide: AF_TREE_I18N,
+ *   useValue: {
+ *     expanded: '{label} ausgeklappt',
+ *     collapsed: '{label} eingeklappt',
+ *     selected: '{label} ausgewählt',
+ *     toggleLabel: 'Aufklappen / Zuklappen',
+ *     loadingLabel: 'Lädt …',
+ *     emptyMessage: 'Keine Einträge',
+ *     orphanLabel: 'Übergeordneter Eintrag fehlt',
+ *   },
+ * }]
+ */
+declare const AF_TREE_I18N: InjectionToken<AfTreeI18n>;
+
+/**
+ * Test harness for {@link AfTreeComponent}.
+ *
+ * Wraps the rendered DOM behind a semantic API so specs and host apps can
+ * navigate the tree without coupling to internal CSS class names.
+ *
+ * @example
+ * const harness = new AfTreeHarness(fixture.nativeElement);
+ * harness.getNode('root').focus();
+ * harness.pressKey('ArrowDown');
+ * expect(harness.focusedId()).toBe('child-1');
+ */
+declare class AfTreeHarness {
+    private readonly hostEl;
+    constructor(container: HTMLElement);
+    /** Container `<ul role="tree">` element. */
+    getRootElement(): HTMLElement | null;
+    /** Returns harnesses for every visible (rendered) treeitem in document order. */
+    getVisibleNodes(): AfTreeNodeHarness[];
+    /** Returns the harness for the node with the given id, or null when not rendered. */
+    getNode(id: string): AfTreeNodeHarness | null;
+    /** Id of the currently focused node (the one whose `<li>` carries `tabindex=0`). */
+    focusedId(): string | null;
+    /** Dispatches a keydown on the focused row (or first row if none focused). */
+    pressKey(key: string): void;
+    /** Returns whether `aria-multiselectable` is set on the root list. */
+    isMultiselectable(): boolean;
+    /** Returns the `aria-label` of the root list. */
+    getAriaLabel(): string | null;
+    /** True when the empty-state is rendered (no rows visible). */
+    isEmpty(): boolean;
+}
+/** Test harness for a single `<li role="treeitem">` rendered by `af-tree`. */
+declare class AfTreeNodeHarness {
+    private readonly liEl;
+    constructor(liEl: HTMLElement);
+    /** Stable id of the node (mirrors `TreeNode.id`). */
+    getId(): string;
+    /** Trimmed label text of the node. */
+    getLabel(): string;
+    /** 1-based depth of the node. */
+    getLevel(): number;
+    isExpanded(): boolean;
+    isExpandable(): boolean;
+    isSelected(): boolean;
+    isDisabled(): boolean;
+    isBusy(): boolean;
+    isFocused(): boolean;
+    /** Programmatically focus the row's `<li>` element. */
+    focus(): void;
+    /** Click the row (centre area, not the toggle / actions). */
+    clickRow(): void;
+    /** Click the chevron toggle button. */
+    clickToggle(): void;
+    /** Return the underlying `<li>` element for advanced assertions. */
+    getElement(): HTMLElement;
+}
+
 /**
  * Transforms snake_case or SCREAMING_SNAKE_CASE strings to Title Case labels.
  *
@@ -3230,5 +3512,5 @@ declare class AfFormatLabelPipe implements PipeTransform {
     static ɵpipe: _angular_core.ɵɵPipeDeclaration<AfFormatLabelPipe, "afFormatLabel", true>;
 }
 
-export { AF_ACCORDION_I18N, AF_ALERT_I18N, AF_INPUT_I18N, AF_SELECT_I18N, AF_SELECT_MENU_I18N, AVATAR_SEED_PALETTE_SIZE, AfAccordionComponent, AfAccordionHarness, AfAccordionItemComponent, AfAccordionItemHarness, AfAlertComponent, AfAlertHarness, AfAppShellComponent, AfAppShellPageHeaderComponent, AfAppShellV2Component, AfAppShellV2ToolbarComponent, AfAvatarComponent, AfBadgeComponent, AfBadgeHarness, AfBannerComponent, AfBreadcrumbsComponent, AfButtonComponent, AfButtonHarness, AfCardComponent, AfCellDefDirective, AfCheckboxComponent, AfChipComponent, AfChipInputComponent, AfComboboxComponent, AfDataTableComponent, AfDatepickerComponent, AfDividerComponent, AfDrawerComponent, AfDropdownComponent, AfEmptyStateComponent, AfFieldComponent, AfFileUploadComponent, AfFormatLabelPipe, AfIconComponent, AfInputComponent, AfInputHarness, AfModalComponent, AfNavItemComponent, AfNavTabsComponent, AfNavbarComponent, AfPaginationComponent, AfPopoverComponent, AfPopoverTriggerDirective, AfProgressBarComponent, AfRadioComponent, AfRadioGroupComponent, AfSelectComponent, AfSelectHarness, AfSelectMenuComponent, AfSelectMenuHarness, AfSidebarComponent, AfSkeletonComponent, AfSkipLinkComponent, AfSliderComponent, AfSpinnerComponent, AfSwitchComponent, AfTabPanelComponent, AfTableBodyComponent, AfTableCellComponent, AfTableComponent, AfTableHeaderCellComponent, AfTableHeaderComponent, AfTableRowComponent, AfTabsComponent, AfTextareaComponent, AfToastContainerComponent, AfToastService, AfToggleGroupComponent, AfToolbarComponent, AfTooltipDirective };
-export type { AfAccordionI18n, AfAlertI18n, AfAlertVariant, AfAvatarSize, AfAvatarStatus, AfBadgeVariant, AfBannerAppearance, AfBannerPosition, AfBannerVariant, AfBreadcrumb, AfButtonSize, AfButtonType, AfButtonVariant, AfCardElevation, AfCardPadding, AfChipAppearance, AfChipSize, AfChipVariant, AfColumn, AfComboboxOption, AfDataRow, AfDataTableConfig, AfDateRange, AfDatepickerMode, AfDatepickerValueFormat, AfDatepickerView, AfDividerColor, AfDividerOrientation, AfDividerSpacing, AfDrawerPosition, AfDrawerSize, AfDropdownItem, AfEmptyStateSize, AfEmptyStateVariant, AfFileEntry, AfFileValidationError, AfIconSize, AfInputI18n, AfInputType, AfNavTab, AfNavTabsSize, AfNavTabsVariant, AfNavbarSize, AfNavbarVariant, AfPopoverAlign, AfPopoverPosition, AfPopoverSize, AfProgressBarSize, AfProgressBarVariant, AfSelectI18n, AfSelectMenuI18n, AfSelectMenuOption, AfSelectOption, AfShellPanelState, AfShellSidebarState, AfSidebarMode, AfSkeletonVariant, AfSliderSize, AfSortDirection, AfSortState, AfSpinnerSize, AfTab, AfTableCellType, AfTableVariant, AfToast, AfToastVariant, AfToggleGroupSize, AfToggleItem, AfTooltipPosition };
+export { AF_ACCORDION_I18N, AF_ALERT_I18N, AF_INPUT_I18N, AF_SELECT_I18N, AF_SELECT_MENU_I18N, AF_TREE_I18N, AVATAR_SEED_PALETTE_SIZE, AfAccordionComponent, AfAccordionHarness, AfAccordionItemComponent, AfAccordionItemHarness, AfAlertComponent, AfAlertHarness, AfAppShellComponent, AfAppShellPageHeaderComponent, AfAppShellV2Component, AfAppShellV2ToolbarComponent, AfAvatarComponent, AfBadgeComponent, AfBadgeHarness, AfBannerComponent, AfBreadcrumbsComponent, AfButtonComponent, AfButtonHarness, AfCardComponent, AfCellDefDirective, AfCheckboxComponent, AfChipComponent, AfChipInputComponent, AfComboboxComponent, AfDataTableComponent, AfDatepickerComponent, AfDividerComponent, AfDrawerComponent, AfDropdownComponent, AfEmptyStateComponent, AfFieldComponent, AfFileUploadComponent, AfFormatLabelPipe, AfIconComponent, AfInputComponent, AfInputHarness, AfModalComponent, AfNavItemComponent, AfNavTabsComponent, AfNavbarComponent, AfPaginationComponent, AfPopoverComponent, AfPopoverTriggerDirective, AfProgressBarComponent, AfRadioComponent, AfRadioGroupComponent, AfSelectComponent, AfSelectHarness, AfSelectMenuComponent, AfSelectMenuHarness, AfSidebarComponent, AfSkeletonComponent, AfSkipLinkComponent, AfSliderComponent, AfSpinnerComponent, AfSwitchComponent, AfTabPanelComponent, AfTableBodyComponent, AfTableCellComponent, AfTableComponent, AfTableHeaderCellComponent, AfTableHeaderComponent, AfTableRowComponent, AfTabsComponent, AfTextareaComponent, AfToastContainerComponent, AfToastService, AfToggleGroupComponent, AfToolbarComponent, AfTooltipDirective, AfTreeComponent, AfTreeHarness, AfTreeNodeHarness };
+export type { AfAccordionI18n, AfAlertI18n, AfAlertVariant, AfAvatarSize, AfAvatarStatus, AfBadgeVariant, AfBannerAppearance, AfBannerPosition, AfBannerVariant, AfBreadcrumb, AfButtonSize, AfButtonType, AfButtonVariant, AfCardElevation, AfCardPadding, AfChipAppearance, AfChipSize, AfChipVariant, AfColumn, AfComboboxOption, AfDataRow, AfDataTableConfig, AfDateRange, AfDatepickerMode, AfDatepickerValueFormat, AfDatepickerView, AfDividerColor, AfDividerOrientation, AfDividerSpacing, AfDrawerPosition, AfDrawerSize, AfDropdownItem, AfEmptyStateSize, AfEmptyStateVariant, AfFileEntry, AfFileValidationError, AfIconSize, AfInputI18n, AfInputType, AfNavTab, AfNavTabsSize, AfNavTabsVariant, AfNavbarSize, AfNavbarVariant, AfPopoverAlign, AfPopoverPosition, AfPopoverSize, AfProgressBarSize, AfProgressBarVariant, AfSelectI18n, AfSelectMenuI18n, AfSelectMenuOption, AfSelectOption, AfShellPanelState, AfShellSidebarState, AfSidebarMode, AfSkeletonVariant, AfSliderSize, AfSortDirection, AfSortState, AfSpinnerSize, AfTab, AfTableCellType, AfTableVariant, AfToast, AfToastVariant, AfToggleGroupSize, AfToggleItem, AfTooltipPosition, AfTreeI18n, TreeNode, TreeNodeTemplateContext, TreeSelectionMode, TreeToggleEvent };