@star-ng/ui 0.0.0-stage → 0.2.0

package/types/star-ng-ui-tree.d.ts

@@ -0,0 +1,343 @@
+import { ConnectedPosition } from "@angular/cdk/overlay";
+import { FormValueControl } from "@angular/forms/signals";
+import * as i0 from "@angular/core";
+/** The part of a tree node that the helpers read. `StarTreeNode` fits it. */
+interface BranchLike<N> {
+  readonly key: string;
+  readonly children?: readonly N[];
+}
+/** One visible row of the flattened tree. */
+interface TreeRow<N> {
+  readonly node: N;
+  /** Depth of the node, starting at 1 (`aria-level`). */
+  readonly level: number;
+  /** Number of siblings, the node included (`aria-setsize`). */
+  readonly setSize: number;
+  /** Position among the siblings, starting at 1 (`aria-posinset`). */
+  readonly position: number;
+  readonly parentKey: string | null;
+}
+/**
+ * Flattens the nodes whose parents are open into rows. The sibling numbers come from the data,
+ * so they stay right for rows that are not in the DOM. `openAll` shows every branch open (filter).
+ */
+export declare function flattenVisible<N extends BranchLike<N>>(nodes: readonly N[], open: ReadonlySet<string>, openAll?: boolean): TreeRow<N>[];
+/** Row index of each key. */
+export declare function rowIndexOf<N extends BranchLike<N>>(rows: readonly TreeRow<N>[]): Map<string, number>;
+/** Parent key of every node (null at the top). */
+export declare function parentsOf<N extends BranchLike<N>>(nodes: readonly N[]): Map<string, string | null>;
+/**
+ * The key that keeps the focus after the rows changed: the previous key if it is still a row,
+ * else its nearest ancestor that is a row, else the first row.
+ */
+export declare function stillFocusable(previous: string | null | undefined, rowIndex: ReadonlyMap<string, number>, parents: ReadonlyMap<string, string | null>, firstKey: string | null): string | null;
+/**
+ * The row that a navigation key moves to, or null when the key does not move (or there is no
+ * target). Arrow right on a closed branch and arrow left on an open branch toggle it: they have
+ * no target.
+ */
+export declare function navigationTarget<N extends BranchLike<N>>(rows: readonly TreeRow<N>[], index: number, key: string, state: {
+  hasChildren: boolean;
+  expanded: boolean;
+}): string | null;
+/**
+ * Scroll offset that brings a fixed-size row fully into view with the least movement, or null
+ * when the row is already fully visible.
+ */
+export declare function scrollOffsetToReveal(index: number, itemSize: number, scrollOffset: number, viewportSize: number): number | null;
+/** Tree data (PrimeNG `TreeNode`). `key` must be unique in the tree. */
+export interface StarTreeNode<T = unknown> {
+  readonly key: string;
+  readonly label: string;
+  readonly icon?: string;
+  readonly data?: T;
+  readonly children?: readonly StarTreeNode<T>[];
+  readonly selectable?: boolean;
+  readonly disabled?: boolean;
+}
+type VisibleNode = TreeRow<StarTreeNode>;
+/**
+ * Tree (PrimeNG `p-tree`): expand / collapse, single, multiple or checkbox selection (checkbox
+ * mode selects whole branches and shows mixed parents), filter, and the WAI-ARIA tree keyboard
+ * model (Up / Down, Right opens or enters, Left closes or goes to the parent, Home / End,
+ * Enter / Space select, `*` expands siblings).
+ *
+ * Large trees: `virtualScroll` with `scrollHeight` and `virtualItemSize` renders only the rows in
+ * and near the viewport (CDK virtual scrolling). Every row has a fixed height then. Keys, selection
+ * and `aria-setsize` / `aria-posinset` work over all open rows, also the ones that are not in the DOM.
+ *
+ * Value: the selected node keys.
+ * `<star-tree [nodes]="departments" selectionMode="checkbox" [(value)]="keys" filter ariaLabel="Departments" />`
+ */
+export declare class StarTree implements FormValueControl<readonly string[]> {
+  protected readonly text: import("@star-ng/ui/core").StarUiText;
+  private readonly host;
+  private readonly doc;
+  readonly value: import("@angular/core").ModelSignal<readonly string[]>;
+  readonly nodes: import("@angular/core").InputSignal<readonly StarTreeNode<unknown>[]>;
+  readonly selectionMode: import("@angular/core").InputSignal<"single" | "multiple" | "checkbox" | null>;
+  /** Expanded node keys. */
+  readonly expanded: import("@angular/core").ModelSignal<readonly string[]>;
+  readonly filter: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /** Maximum height of the tree (a CSS length, for example `16rem`). The tree scrolls inside it. */
+  readonly scrollHeight: import("@angular/core").InputSignal<string | null>;
+  /**
+   * Windowed rendering for large trees (CDK virtual scrolling): only the rows in and near the
+   * viewport are in the DOM. Needs `scrollHeight`, and every row gets the fixed height
+   * `virtualItemSize`. Without `scrollHeight` the tree renders all rows as usual.
+   */
+  readonly virtualScroll: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /** Row height in pixels in windowed rendering. Keep it equal to the real height of a row. */
+  readonly virtualItemSize: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  readonly ariaLabel: import("@angular/core").InputSignal<string | null>;
+  readonly disabled: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  readonly touch: import("@angular/core").OutputEmitterRef<void>;
+  readonly nodeSelect: import("@angular/core").OutputEmitterRef<StarTreeNode<unknown>>;
+  protected readonly query: import("@angular/core").WritableSignal<string>;
+  private readonly viewport;
+  private readonly filtered;
+  private readonly index;
+  private readonly parents;
+  private readonly openKeys;
+  private readonly selectedKeys;
+  /** Flattened visible rows; a filter shows every matching branch open. */
+  protected readonly visible: import("@angular/core").Signal<VisibleNode[]>;
+  private readonly rowIndex;
+  /** Check state of each node of the (filtered) tree; empty outside checkbox mode. */
+  private readonly checkMap;
+  /**
+   * The active row (the one with `tabindex` 0). It stays a row after the rows change, and it
+   * is kept in state, not read from the DOM: in windowed rendering its element may not exist.
+   */
+  protected readonly focusKey: import("@angular/core").WritableSignal<string | null>;
+  protected readonly windowed: import("@angular/core").Signal<boolean>;
+  /** The windowed viewport shows when there are rows; the empty message needs the plain list. */
+  protected readonly showViewport: import("@angular/core").Signal<boolean>;
+  /** Height of the viewport: as high as the rows, at most `scrollHeight`. */
+  protected readonly viewportHeight: import("@angular/core").Signal<string>;
+  /** Rows that are in the DOM now: indexes `start` up to (not including) `end`. */
+  private readonly range;
+  /** The active row is in the DOM. If it is not, the viewport takes the Tab stop. */
+  protected readonly activeRendered: import("@angular/core").Signal<boolean>;
+  protected readonly multiselectable: import("@angular/core").Signal<true | null>;
+  /** Row to focus as soon as its element exists (it may need scrolling in first). */
+  private pendingFocus;
+  /** The focus waits on the viewport because the focused row left the DOM. */
+  protected parked: boolean;
+  protected readonly trackRow: (_: number, row: VisibleNode) => string;
+  constructor();
+  isExpanded(node: StarTreeNode): boolean;
+  toggle(node: StarTreeNode, open?: boolean): void;
+  protected isSelected(node: StarTreeNode): boolean;
+  /** Checkbox mode: true, false or 'mixed' from the leaves below. */
+  protected checkState(node: StarTreeNode): boolean | 'mixed';
+  select(node: StarTreeNode): void;
+  protected onClick(node: StarTreeNode, event: MouseEvent): void;
+  protected onRowFocus(key: string): void;
+  /**
+   * Moves the focus to a row. The row becomes the active row at once. In windowed rendering the
+   * row is scrolled into the window first, and the focus is applied after its element renders.
+   */
+  private focusRow;
+  /** Scrolls a row into the window with the least movement (`scrollToIndex` puts it on top). */
+  private revealRow;
+  private rowElement;
+  private applyPendingFocus;
+  /**
+   * The browser drops the focus to the page body when the focused element leaves the DOM. Before
+   * the focused row scrolls out of the window, the focus moves to the viewport; the keys still
+   * work there, and the focus returns to the row when it renders again.
+   */
+  private parkFocus;
+  private restoreParkedFocus;
+  /** Tab into the viewport (no row has the Tab stop): the focus goes to the active row. */
+  protected onViewportFocus(): void;
+  /** Keys on the viewport itself (the focus is parked there): they act on the active row. */
+  protected onViewportKeydown(event: KeyboardEvent): void;
+  protected onKeydown(event: KeyboardEvent, row: VisibleNode): void;
+  /** Label of a node key (used by `star-tree-select`). */
+  labelFor(key: string): string;
+  /** Keys of leaves only, for checkbox summaries. */
+  isLeaf(key: string): boolean;
+  focus(): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarTree, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StarTree, "star-tree", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "nodes": {
+      "alias": "nodes";
+      "required": false;
+      "isSignal": true;
+    };
+    "selectionMode": {
+      "alias": "selectionMode";
+      "required": false;
+      "isSignal": true;
+    };
+    "expanded": {
+      "alias": "expanded";
+      "required": false;
+      "isSignal": true;
+    };
+    "filter": {
+      "alias": "filter";
+      "required": false;
+      "isSignal": true;
+    };
+    "scrollHeight": {
+      "alias": "scrollHeight";
+      "required": false;
+      "isSignal": true;
+    };
+    "virtualScroll": {
+      "alias": "virtualScroll";
+      "required": false;
+      "isSignal": true;
+    };
+    "virtualItemSize": {
+      "alias": "virtualItemSize";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "disabled": {
+      "alias": "disabled";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "value": "valueChange";
+    "expanded": "expandedChange";
+    "touch": "touch";
+    "nodeSelect": "nodeSelect";
+  }, never, never, true, never>;
+}
+/**
+ * Tree select (PrimeNG `p-treeselect`): a select field whose panel is an `star-tree`.
+ * Value: selected node keys (one key in `single` mode).
+ *
+ * `<star-tree-select [nodes]="departments" selectionMode="checkbox" [(value)]="keys" placeholder="Department" />`
+ */
+export declare class StarTreeSelect implements FormValueControl<readonly string[]> {
+  /** Keeps the CDK direction (overlays and menus) in step with `<html dir>`. */
+  private readonly directionSync;
+  protected readonly text: import("@star-ng/ui/core").StarUiText;
+  protected readonly inputId: string;
+  protected readonly positions: ConnectedPosition[];
+  readonly value: import("@angular/core").ModelSignal<readonly string[]>;
+  readonly nodes: import("@angular/core").InputSignal<readonly StarTreeNode<unknown>[]>;
+  readonly selectionMode: import("@angular/core").InputSignal<"single" | "multiple" | "checkbox">;
+  readonly expanded: import("@angular/core").ModelSignal<readonly string[]>;
+  readonly filter: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /** Windowed rendering of the panel tree (see `star-tree`). The panel is 18rem high. */
+  readonly virtualScroll: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /** Row height in pixels in windowed rendering. */
+  readonly virtualItemSize: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  readonly showClear: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  readonly placeholder: import("@angular/core").InputSignal<string | null>;
+  readonly ariaLabel: import("@angular/core").InputSignal<string | null>;
+  readonly maxSelectedLabels: import("@angular/core").InputSignal<number>;
+  readonly disabled: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  readonly invalid: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  readonly touched: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  readonly touch: import("@angular/core").OutputEmitterRef<void>;
+  protected readonly open: import("@angular/core").WritableSignal<boolean>;
+  protected readonly panelTree: import("@angular/core").Signal<StarTree | undefined>;
+  private readonly trigger;
+  private readonly labels;
+  protected readonly summary: import("@angular/core").Signal<string>;
+  /**
+   * Accessible name of the trigger button: the label and the text on the button, so the visible
+   * text is part of the name (WCAG 2.5.3). `null` without `ariaLabel`: a `star-field` label then
+   * names the button.
+   */
+  protected readonly triggerName: import("@angular/core").Signal<string | null>;
+  protected close(focus?: boolean): void;
+  protected onOutside(event: MouseEvent): void;
+  focus(): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarTreeSelect, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StarTreeSelect, "star-tree-select", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "nodes": {
+      "alias": "nodes";
+      "required": false;
+      "isSignal": true;
+    };
+    "selectionMode": {
+      "alias": "selectionMode";
+      "required": false;
+      "isSignal": true;
+    };
+    "expanded": {
+      "alias": "expanded";
+      "required": false;
+      "isSignal": true;
+    };
+    "filter": {
+      "alias": "filter";
+      "required": false;
+      "isSignal": true;
+    };
+    "virtualScroll": {
+      "alias": "virtualScroll";
+      "required": false;
+      "isSignal": true;
+    };
+    "virtualItemSize": {
+      "alias": "virtualItemSize";
+      "required": false;
+      "isSignal": true;
+    };
+    "showClear": {
+      "alias": "showClear";
+      "required": false;
+      "isSignal": true;
+    };
+    "placeholder": {
+      "alias": "placeholder";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "maxSelectedLabels": {
+      "alias": "maxSelectedLabels";
+      "required": false;
+      "isSignal": true;
+    };
+    "disabled": {
+      "alias": "disabled";
+      "required": false;
+      "isSignal": true;
+    };
+    "invalid": {
+      "alias": "invalid";
+      "required": false;
+      "isSignal": true;
+    };
+    "touched": {
+      "alias": "touched";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "value": "valueChange";
+    "expanded": "expandedChange";
+    "touch": "touch";
+  }, never, never, true, never>;
+}
+export type { BranchLike, TreeRow };