@star-ng/ui 0.0.0-stage → 0.2.0

package/types/star-ng-ui-data-display.d.ts

@@ -0,0 +1,438 @@
+import * as i0 from "@angular/core";
+import { TemplateRef } from "@angular/core";
+import { StarOptionKey } from "@star-ng/ui/core";
+import { StarTreeNode, TreeRow } from "@star-ng/ui/tree";
+/** The rows in the DOM and the height of the two spacer rows that stand for the others. */
+interface RowWindow {
+  /** Index of the first rendered row. */
+  readonly start: number;
+  /** Index after the last rendered row. */
+  readonly end: number;
+  /** Height in pixels of the rows before `start`. */
+  readonly before: number;
+  /** Height in pixels of the rows from `end` on. */
+  readonly after: number;
+}
+/** `aria-rowcount`: the visible rows and the header row. */
+declare function ariaRowCount(rowCount: number): number;
+export interface StarTreeTableColumn {
+  readonly field: string;
+  readonly header: string;
+  readonly width?: string;
+  readonly align?: 'start' | 'center' | 'end';
+}
+type TreeTableNode = StarTreeNode<Record<string, unknown>>;
+type TreeTableRow = TreeRow<TreeTableNode>;
+/** One rendered row: the row and its `aria-rowindex` (null in the default rendering). */
+interface TreeTableEntry {
+  readonly row: TreeTableRow;
+  readonly aria: number | null;
+}
+/**
+ * Tree table (PrimeNG `p-treetable`): hierarchical rows with expand / collapse in a table,
+ * `role="treegrid"`, Right / Left on a row expand / collapse, Up / Down, Home and End move between
+ * rows. Node `data` holds the column values; the first column shows the tree toggle.
+ *
+ * Large tables: `virtualScroll` with `scrollHeight` and `virtualItemSize` renders only the rows in
+ * and near the viewport. It is still one `<table>`: a spacer row above and one below the rendered
+ * rows stand for the others, the header is sticky, and every row has the fixed height
+ * `virtualItemSize`. Keys, `aria-rowcount`, `aria-rowindex`, `aria-level`, `aria-setsize` and
+ * `aria-posinset` work over all open rows, also the ones that are not in the DOM.
+ *
+ * `<star-tree-table [nodes]="budget" [columns]="cols" [(expanded)]="open" ariaLabel="Budget" />`
+ */
+export declare class StarTreeTable {
+  protected readonly text: import("@star-ng/ui/core").StarUiText;
+  private readonly doc;
+  readonly nodes: import("@angular/core").InputSignal<readonly TreeTableNode[]>;
+  readonly columns: import("@angular/core").InputSignal<readonly StarTreeTableColumn[]>;
+  readonly expanded: import("@angular/core").ModelSignal<readonly string[]>;
+  readonly ariaLabel: import("@angular/core").InputSignal<string | null>;
+  /**
+   * Maximum height of the table (a CSS length, for example `20rem`). The table scrolls inside it
+   * and the header stays at the top.
+   */
+  readonly scrollHeight: import("@angular/core").InputSignal<string | null>;
+  /**
+   * Windowed rendering for large tables: only the rows in and near the viewport are in the DOM.
+   * Needs `scrollHeight`, and every row gets the fixed height `virtualItemSize` with its text on
+   * one line. Without `scrollHeight` the table renders all rows as usual.
+   */
+  readonly virtualScroll: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  /**
+   * Row height in pixels in windowed rendering. The default is the natural height of a row of
+   * this table.
+   */
+  readonly virtualItemSize: import("@angular/core").InputSignalWithTransform<number, unknown>;
+  private readonly scroller;
+  private readonly header;
+  private readonly openKeys;
+  private readonly parents;
+  /** The rows whose parents are open, in order. The sibling numbers come from the data. */
+  protected readonly rows: import("@angular/core").Signal<TreeTableRow[]>;
+  private readonly rowIndex;
+  /**
+   * 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>;
+  private readonly scrollTop;
+  private readonly viewportHeight;
+  /** The rows that are in the DOM. Without windowed rendering: all of them. */
+  protected readonly window: import("@angular/core").Signal<RowWindow>;
+  protected readonly entries: import("@angular/core").Signal<TreeTableEntry[]>;
+  /** The active row is in the DOM. If it is not, the scroll area takes the Tab stop. */
+  protected readonly activeRendered: import("@angular/core").Signal<boolean>;
+  protected readonly ariaRowCount: typeof ariaRowCount;
+  /** Row to focus as soon as its element exists (it may need scrolling in first). */
+  private pendingFocus;
+  /** The focus waits on the scroll area because the focused row left the DOM. */
+  protected parked: boolean;
+  constructor();
+  protected isOpen(key: string): boolean;
+  toggle(key: string, open?: boolean): void;
+  /** Reads the scroll position and the height of the scroll area (windowed rendering). */
+  protected syncScroll(): void;
+  protected onRowFocus(event: FocusEvent, 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 fully into view, below the sticky header, with the least movement. */
+  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 leaves the window, the focus moves to the scroll area; the keys still work
+   * there, and the focus returns to the row when it renders again.
+   */
+  private parkFocus;
+  private restoreParkedFocus;
+  /** Tab into the scroll area (no row has the Tab stop): the focus goes to the active row. */
+  protected onScrollerFocus(): void;
+  /** Keys on the scroll area itself (the focus is parked there): they act on the active row. */
+  protected onScrollerKeydown(event: KeyboardEvent): void;
+  protected onKeydown(event: KeyboardEvent, row: TreeTableRow): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarTreeTable, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StarTreeTable, "star-tree-table", never, {
+    "nodes": {
+      "alias": "nodes";
+      "required": false;
+      "isSignal": true;
+    };
+    "columns": {
+      "alias": "columns";
+      "required": true;
+      "isSignal": true;
+    };
+    "expanded": {
+      "alias": "expanded";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "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;
+    };
+  }, {
+    "expanded": "expandedChange";
+  }, never, never, true, never>;
+}
+/** Item template: `<ng-template starDataViewItem let-item let-layout="layout">`. */
+export declare class StarDataViewItem<T = unknown> {
+  readonly starDataViewItemOf: import("@angular/core").InputSignal<readonly T[] | null>;
+  readonly template: TemplateRef<{
+    $implicit: T;
+    layout: "list" | "grid";
+    index: number;
+  }>;
+  static ngTemplateContextGuard<T>(_dir: StarDataViewItem<T>, _ctx: unknown): _ctx is {
+    $implicit: T;
+    layout: 'list' | 'grid';
+    index: number;
+  };
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarDataViewItem<any>, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<StarDataViewItem<any>, "ng-template[starDataViewItem]", never, {
+    "starDataViewItemOf": {
+      "alias": "starDataViewItemOf";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * Data view (PrimeNG `p-dataview`): items in a list or a responsive grid, layout switch,
+ * client pagination and an empty state. It does not sort: sort the items before you pass them in.
+ * You design each item with a template.
+ *
+ * ```html
+ * <star-data-view [items]="products" [(layout)]="layout" paginator [rows]="6">
+ *   <ng-template starDataViewItem let-p let-layout="layout">…</ng-template>
+ * </star-data-view>
+ * ```
+ */
+export declare class StarDataView<T = unknown> {
+  protected readonly text: import("@star-ng/ui/core").StarUiText;
+  protected readonly layouts: ({
+    id: "list";
+    label: string;
+    icon: string;
+  } | {
+    id: "grid";
+    label: string;
+    icon: string;
+  })[];
+  readonly items: import("@angular/core").InputSignal<readonly T[]>;
+  readonly layout: import("@angular/core").ModelSignal<"list" | "grid">;
+  readonly paginator: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+  readonly rows: import("@angular/core").ModelSignal<number>;
+  readonly first: import("@angular/core").ModelSignal<number>;
+  readonly emptyMessage: import("@angular/core").InputSignal<string | null>;
+  protected readonly itemTemplate: import("@angular/core").Signal<StarDataViewItem<any> | undefined>;
+  protected readonly pageItems: import("@angular/core").Signal<readonly T[]>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarDataView<any>, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StarDataView<any>, "star-data-view", never, {
+    "items": {
+      "alias": "items";
+      "required": false;
+      "isSignal": true;
+    };
+    "layout": {
+      "alias": "layout";
+      "required": false;
+      "isSignal": true;
+    };
+    "paginator": {
+      "alias": "paginator";
+      "required": false;
+      "isSignal": true;
+    };
+    "rows": {
+      "alias": "rows";
+      "required": false;
+      "isSignal": true;
+    };
+    "first": {
+      "alias": "first";
+      "required": false;
+      "isSignal": true;
+    };
+    "emptyMessage": {
+      "alias": "emptyMessage";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "layout": "layoutChange";
+    "rows": "rowsChange";
+    "first": "firstChange";
+  }, ["itemTemplate"], ["[starDataViewHeader]"], true, never>;
+}
+/**
+ * Order list (PrimeNG `p-orderlist`): reorder items with buttons or Alt + Arrow keys; the moved
+ * item keeps focus and a live region announces its new position.
+ * `<star-order-list [(value)]="priorities" optionLabel="name" ariaLabel="Queue order" />`
+ */
+export declare class StarOrderList<T = unknown> {
+  protected readonly text: import("@star-ng/ui/core").StarUiText;
+  protected readonly hintId: string;
+  readonly value: import("@angular/core").ModelSignal<readonly T[]>;
+  readonly optionLabel: import("@angular/core").InputSignal<StarOptionKey<T> | null>;
+  readonly ariaLabel: import("@angular/core").InputSignal<string | null>;
+  protected readonly selected: import("@angular/core").WritableSignal<number>;
+  protected readonly announcement: import("@angular/core").WritableSignal<string>;
+  protected readonly actions: ({
+    id: "top";
+    label: string;
+    icon: string;
+  } | {
+    id: "up";
+    label: string;
+    icon: string;
+  } | {
+    id: "down";
+    label: string;
+    icon: string;
+  } | {
+    id: "bottom";
+    label: string;
+    icon: string;
+  })[];
+  protected labelOf(item: T): string;
+  protected canMove(direction: 'top' | 'up' | 'down' | 'bottom'): boolean;
+  move(direction: 'top' | 'up' | 'down' | 'bottom'): void;
+  protected onKeydown(event: KeyboardEvent, index: number): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarOrderList<any>, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StarOrderList<any>, "star-order-list", never, {
+    "value": {
+      "alias": "value";
+      "required": false;
+      "isSignal": true;
+    };
+    "optionLabel": {
+      "alias": "optionLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "value": "valueChange";
+  }, never, never, true, never>;
+}
+/**
+ * Pick list (PrimeNG `p-picklist`): move items between a source and a target list.
+ * Double-click or Enter moves one item; buttons move the selection or everything.
+ * `<star-pick-list [(source)]="available" [(target)]="assigned" optionLabel="name" sourceHeader="Available" targetHeader="Assigned" />`
+ */
+export declare class StarPickList<T = unknown> {
+  protected readonly text: import("@star-ng/ui/core").StarUiText;
+  private readonly idGen;
+  protected readonly ids: {
+    source: string;
+    target: string;
+  };
+  protected readonly sides: readonly ["source", "target"];
+  readonly source: import("@angular/core").ModelSignal<readonly T[]>;
+  readonly target: import("@angular/core").ModelSignal<readonly T[]>;
+  readonly optionLabel: import("@angular/core").InputSignal<StarOptionKey<T> | null>;
+  readonly sourceHeader: import("@angular/core").InputSignal<string | null>;
+  readonly targetHeader: import("@angular/core").InputSignal<string | null>;
+  private readonly selection;
+  protected labelOf(item: T): string;
+  protected picked(side: 'source' | 'target'): readonly T[];
+  protected isPicked(side: 'source' | 'target', item: T): boolean;
+  protected pick(side: 'source' | 'target', item: T): void;
+  transfer(from: 'source' | 'target', items: readonly T[]): void;
+  /** Reads a value with an optional key (exposed for custom templates). */
+  read(item: T, key: StarOptionKey<T>): unknown;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarPickList<any>, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StarPickList<any>, "star-pick-list", never, {
+    "source": {
+      "alias": "source";
+      "required": false;
+      "isSignal": true;
+    };
+    "target": {
+      "alias": "target";
+      "required": false;
+      "isSignal": true;
+    };
+    "optionLabel": {
+      "alias": "optionLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "sourceHeader": {
+      "alias": "sourceHeader";
+      "required": false;
+      "isSignal": true;
+    };
+    "targetHeader": {
+      "alias": "targetHeader";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "source": "sourceChange";
+    "target": "targetChange";
+  }, never, never, true, never>;
+}
+export interface StarOrgNode<T = unknown> {
+  /** Unique id of the node in the chart. */
+  readonly key: string;
+  readonly label: string;
+  /** Second line, for example a role. */
+  readonly subtitle?: string;
+  readonly data?: T;
+  readonly children?: readonly StarOrgNode<T>[];
+}
+export interface StarOrgNodeContext<T> {
+  readonly $implicit: StarOrgNode<T>;
+  readonly level: number;
+}
+/** Custom node content: `<ng-template starOrgNode let-node>…</ng-template>`. */
+export declare class StarOrgNodeTemplate<T = unknown> {
+  readonly template: TemplateRef<StarOrgNodeContext<T>>;
+  static ngTemplateContextGuard<T>(_dir: StarOrgNodeTemplate<T>, _ctx: unknown): _ctx is StarOrgNodeContext<T>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarOrgNodeTemplate<any>, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<StarOrgNodeTemplate<any>, "ng-template[starOrgNode]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Organization chart (PrimeNG `p-organizationchart`): a hierarchy drawn top-down with
+ * connector lines. The markup is a nested list, so assistive technology reads the levels.
+ * A node with children has a button that hides or shows its branch.
+ *
+ * `<star-org-chart ariaLabel="Safety team" [value]="team" [(collapsedKeys)]="closed" selectable />`
+ */
+export declare class StarOrgChart<T = unknown> {
+  protected readonly text: import("@star-ng/ui/core").StarUiText;
+  /** Root node of the chart. */
+  readonly value: import("@angular/core").InputSignal<StarOrgNode<T>>;
+  readonly ariaLabel: import("@angular/core").InputSignal<string | null>;
+  /** Keys of the nodes whose branch is hidden. Two-way. */
+  readonly collapsedKeys: import("@angular/core").ModelSignal<readonly string[]>;
+  /** Nodes are buttons; one node can be selected. */
+  readonly selectable: import("@angular/core").InputSignalWithTransform<boolean, boolean | "">;
+  readonly selectedKey: import("@angular/core").ModelSignal<string | null>;
+  readonly nodeSelect: import("@angular/core").OutputEmitterRef<StarOrgNode<T>>;
+  protected readonly nodeTemplate: import("@angular/core").Signal<StarOrgNodeTemplate<any> | undefined>;
+  protected isCollapsed(node: StarOrgNode<T>): boolean;
+  protected toggle(node: StarOrgNode<T>): void;
+  protected select(node: StarOrgNode<T>): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StarOrgChart<any>, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StarOrgChart<any>, "star-org-chart", never, {
+    "value": {
+      "alias": "value";
+      "required": true;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "collapsedKeys": {
+      "alias": "collapsedKeys";
+      "required": false;
+      "isSignal": true;
+    };
+    "selectable": {
+      "alias": "selectable";
+      "required": false;
+      "isSignal": true;
+    };
+    "selectedKey": {
+      "alias": "selectedKey";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "collapsedKeys": "collapsedKeysChange";
+    "selectedKey": "selectedKeyChange";
+    "nodeSelect": "nodeSelect";
+  }, ["nodeTemplate"], never, true, never>;
+}
+export {};