@star-ng/ui 0.1.0 → 0.2.0

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

@@ -1,37 +1,121 @@
 import * as i0 from "@angular/core";
 import { TemplateRef } from "@angular/core";
 import { StarOptionKey } from "@star-ng/ui/core";
-import { StarTreeNode } from "@star-ng/ui/tree";
+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';
 }
-interface TreeRow {
-  readonly node: StarTreeNode<Record<string, unknown>>;
-  readonly level: number;
-  readonly setSize: number;
-  readonly position: number;
+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 move between rows.
- * Node `data` holds the column values; the first column shows the tree toggle.
+ * `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;
-  readonly nodes: import("@angular/core").InputSignal<readonly StarTreeNode<Record<string, unknown>>[]>;
+  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>;
-  protected readonly rows: import("@angular/core").Signal<TreeRow[]>;
+  /**
+   * 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;
-  protected onKeydown(event: KeyboardEvent, row: TreeRow): 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": {
@@ -54,6 +138,21 @@ export declare class StarTreeTable {
       "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>;

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

@@ -1,33 +1,7 @@
 import { FormValueControl } from "@angular/forms/signals";
-import { StarOptionKey } from "@star-ng/ui/core";
+import { StarOptionKey, StarWindowRow } from "@star-ng/ui/core";
 import { StarOptionTemplate } from "@star-ng/ui/select";
 import * as i0 from "@angular/core";
-/**
- * Pure helpers of the virtual list in `star-listbox`: row model, index math, keyboard target and
- * ARIA values. They have no DOM access, so unit tests can check them without layout.
- */
-/** One row of the virtual list. Group headings and options have the same height. */
-type ListboxRow<T> = {
-  readonly kind: 'group';
-  readonly key: string;
-  readonly label: string;
-  readonly id: string;
-} | {
-  readonly kind: 'option';
-  readonly key: string;
-  readonly option: T;
-  /** Index in the visible options (keyboard order). */
-  readonly index: number;
-  /** Id of the heading row of the group, or null without groups. */
-  readonly groupId: string | null;
-  /** Index of the heading row of the group, or -1 without groups. */
-  readonly groupRow: number;
-};
-/** The rows, and for each visible option the index of its row. */
-interface ListboxLayout<T> {
-  readonly rows: readonly ListboxRow<T>[];
-  readonly rowOfOption: readonly number[];
-}
 /**
  * Inline list choice (PrimeNG `p-listbox`): single or `multiple` (checkboxes), filter,
  * option template, WAI-ARIA listbox keyboard (Arrow, Home / End, Space / Enter, typeahead).
@@ -81,17 +55,17 @@ export declare class StarListbox<TOption = unknown, TValue = TOption> implements
   protected groupId(index: number): string | null;
   protected readonly itemSize: import("@angular/core").Signal<number>;
   /** Group headings and options in one list of rows of equal height. */
-  protected readonly layout: import("@angular/core").Signal<ListboxLayout<TOption>>;
+  protected readonly layout: import("@angular/core").Signal<import("@star-ng/ui/core").StarWindowLayout<TOption>>;
   protected readonly viewportHeight: import("@angular/core").Signal<string>;
   /** Rows that are in the DOM now: `[start, end)`, reported by the CDK viewport. */
   private readonly renderedRange;
-  protected readonly trackRow: (_index: number, row: ListboxRow<TOption>) => string;
+  protected readonly trackRow: (_index: number, row: StarWindowRow<TOption>) => string;
   protected positionOf(index: number): {
     setsize: number;
     posinset: number;
   };
   /** The heading of the group, only while its row is in the DOM (the id must exist). */
-  protected describedBy(row: Extract<ListboxRow<TOption>, {
+  protected describedBy(row: Extract<StarWindowRow<TOption>, {
     kind: 'option';
   }>): string | null;
   /** `aria-activedescendant` only names an option that is in the DOM. */
@@ -193,5 +167,4 @@ export declare class StarListbox<TOption = unknown, TValue = TOption> implements
     "value": "valueChange";
     "touch": "touch";
   }, ["optionTemplate"], never, true, never>;
-}
-export {};
+}

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

@@ -1,5 +1,5 @@
 import { FormValueControl } from "@angular/forms/signals";
-import { StarOptionKey } from "@star-ng/ui/core";
+import { StarOptionKey, StarWindowRow } from "@star-ng/ui/core";
 import { StarMenuItem } from "@star-ng/ui/menu";
 import * as i0 from "@angular/core";
 import { ElementRef, TemplateRef } from "@angular/core";
@@ -185,19 +185,7 @@ export declare class StarOptionTemplate<T = unknown> {
   }, {}, never, never, true, never>;
 }
 /** One rendered line of the option list: a group heading or an option. */
-export type StarListRow<T> = {
-  readonly kind: 'group';
-  readonly key: string;
-  readonly label: string;
-  readonly id: string;
-} | {
-  readonly kind: 'option';
-  readonly key: string;
-  readonly option: T;
-  /** Index in the visible options (keyboard order). */
-  readonly index: number;
-  readonly groupId: string | null;
-};
+export type StarListRow<T> = StarWindowRow<T>;
 /**
  * Shared state and keyboard model of the dropdown list controls (WAI-ARIA combobox +
  * listbox with `aria-activedescendant`). Subclasses add the selection model.
@@ -207,6 +195,8 @@ export declare abstract class StarOptionListBase<TOption, TValue> {
   private readonly directionSync;
   protected readonly text: import("@star-ng/ui/core").StarUiText;
   private readonly ids;
+  private readonly document;
+  private readonly injector;
   readonly options: import("@angular/core").InputSignal<readonly TOption[]>;
   readonly optionLabel: import("@angular/core").InputSignal<StarOptionKey<TOption> | null>;
   /** Value stored in the form. Omit to store the whole option. */
@@ -221,7 +211,10 @@ export declare abstract class StarOptionListBase<TOption, TValue> {
   readonly optionGroup: import("@angular/core").InputSignal<StarOptionKey<TOption> | null>;
   /**
    * Renders only the lines in view, for long option lists. Every line has the height
-   * `virtualItemSize` and option text stays on one line.
+   * `virtualItemSize` and option text stays on one line. Keys and type-ahead work over all
+   * options, also those that are not in the DOM. Page up and Page down move by the lines in view.
+   * Each option has `aria-setsize` and `aria-posinset` for the whole list, and
+   * `aria-activedescendant` only names an option that is in the DOM.
    */
   readonly virtualScroll: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
   /** Line height in pixels with `virtualScroll`. */
@@ -260,6 +253,8 @@ export declare abstract class StarOptionListBase<TOption, TValue> {
   protected readonly visibleOptions: import("@angular/core").Signal<readonly TOption[]>;
   /** With `optionGroup`: keeps each group together, in the order the groups first appear. */
   protected groupedOrder(options: readonly TOption[]): readonly TOption[];
+  /** Group headings and options in display order, and the row of each option. */
+  protected readonly layout: import("@angular/core").Signal<import("@star-ng/ui/core").StarWindowLayout<TOption>>;
   /** Group headings and options, in display order. */
   protected readonly rows: import("@angular/core").Signal<readonly StarListRow<TOption>[]>;
   private readonly listScrollTop;
@@ -273,7 +268,12 @@ export declare abstract class StarOptionListBase<TOption, TValue> {
   }>;
   protected readonly renderedRows: import("@angular/core").Signal<readonly StarListRow<TOption>[]>;
   protected onListScroll(event: Event): void;
+  /** `aria-activedescendant` only names an option that is in the DOM. */
   protected readonly activeId: import("@angular/core").Signal<string | null>;
+  /** The heading of the group, only while its row is in the DOM (the id must exist). */
+  protected describedBy(row: Extract<StarListRow<TOption>, {
+    kind: 'option';
+  }>): string | null;
   protected readonly emptyText: import("@angular/core").Signal<string>;
   private typeahead;
   private typeaheadTimer;
@@ -303,14 +303,32 @@ export declare abstract class StarOptionListBase<TOption, TValue> {
   protected onPanelMousedown(event: MouseEvent): void;
   protected onTriggerBlur(): void;
   protected onFilterInput(value: string): void;
+  /**
+   * Shows the list from its top. The window and the scroll position of the element change
+   * together: a new list that is still long would else keep the old position of the element
+   * while the window draws its first lines.
+   */
+  protected resetScroll(): void;
   protected onOptionClick(option: TOption, index: number): void;
   /** Keyboard model for both the trigger and the filter input. */
   protected onKeydown(event: KeyboardEvent): void;
   private chooseActive;
   private moveActive;
+  /** Page up / Page down: moves the active option by the lines in view, over all options. */
+  private movePage;
   protected firstEnabledFrom(start: number, step: 1 | -1): number;
   /** Type a letter to jump to the next option whose label starts with the typed text. */
   private runTypeahead;
+  /** The list element in the panel (the panel is outside the host, in the overlay). */
+  private listElement;
+  /**
+   * Moves the list element to the offset of the window. A list that has just opened may not be
+   * able to take it yet: it may be too short until its window is drawn, or not laid out until
+   * the popover shows. The browser then keeps the old offset and sends no scroll event, so the
+   * window would draw lines that the element does not show. Try again for some frames, until the
+   * element is there or the user scrolls.
+   */
+  private applyScroll;
   private scrollActiveIntoView;
   static ɵfac: i0.ɵɵFactoryDeclaration<StarOptionListBase<any, any>, never>;
   static ɵdir: i0.ɵɵDirectiveDeclaration<StarOptionListBase<any, any>, never, never, {
@@ -469,6 +487,11 @@ export declare class StarMultiSelect<TOption = unknown, TValue = TOption> extend
   private readonly selectableVisible;
   /** `true`, `false` or `'mixed'` for the "select all" box (over visible, enabled options). */
   protected readonly allState: import("@angular/core").Signal<boolean | "mixed">;
+  /**
+   * The chosen values in a `Set`, for the default `compareWith`. A lookup then costs one step and
+   * not one scan of the value: with 10,000 chosen options a scan per option took seconds.
+   */
+  private readonly chosenSet;
   protected isSelected(option: TOption): boolean;
   protected choose(option: TOption): void;
   protected initialActiveIndex(): number;

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

@@ -812,18 +812,74 @@ export interface StarPrintFitMeasure {
   /** Minimum width of each column at the last step that keeps words whole. */
   readonly columns: readonly number[];
 }
+/** A style sheet of the print document that can be changed and removed again. */
+export interface StarPrintStyle {
+  /** Replaces the rules of the sheet. */
+  set(css: string): void;
+  /** Takes the sheet out of the document. */
+  remove(): void;
+}
+/**
+ * Adds a style sheet to `doc`. The sheet is a constructed style sheet (`new CSSStyleSheet()`,
+ * created in the realm of the document, then `adoptedStyleSheets`). A policy whose `style-src`
+ * has no `'unsafe-inline'` blocks an inline `style` element, but it does not block a constructed
+ * sheet. An environment without constructed style sheets (or one where they fail) gets a
+ * `style` element instead: that is the only fallback, and a strict policy blocks it.
+ */
+export declare function addPrintStyle(doc: Document, css?: string): StarPrintStyle;
+/**
+ * Adds the base style of the print document (see `buildPrintDocument`) to `doc`. The document
+ * has no `style` element and no `style` attribute, so a Content-Security-Policy without
+ * `'unsafe-inline'` in `style-src` does not unstyle it. Call it when the frame has loaded,
+ * before `fitPrintDocument` measures the table.
+ */
+export declare function stylePrintDocument(doc: Document): void;
 /**
  * Measures the minimum width of the print table at each fit step, in the layout of `doc`, and
- * adds the style sheet of `printFitStyle` to it. Call it when the frame has loaded, before the
- * print dialog opens. The widths are read in the real fonts of the document, so the text of any
- * font, wide or narrow, gets the steps it needs.
+ * adds the style sheet of `printFitStyle` to it (a constructed style sheet, see
+ * `addPrintStyle`). Call it when the frame has loaded and has its base style
+ * (`stylePrintDocument`), before the print dialog opens. The widths are read in the real fonts
+ * of the document, so the text of any font, wide or narrow, gets the steps it needs.
  */
 export declare function fitPrintDocument(doc: Document): StarPrintFitMeasure;
+/** Alignment of a print column. `start` and `end` follow the direction of the document. */
+export type StarPrintAlign = 'start' | 'center' | 'end';
+/**
+ * Alignment of a print column. The column definition decides: an explicit `align` wins. Without
+ * it a column in which every value is a number (and there is at least one) is `end`, and any
+ * other column is `start`. The type of the printed text does not matter: a number that a
+ * `format` function turned into a string still sits in a number column. `values` are the cell
+ * values before formatting.
+ */
+export declare function printColumnAlign(align: StarPrintAlign | undefined, values: readonly unknown[]): StarPrintAlign;
+/** Language and direction of the print document. */
+export interface StarPrintContext {
+  readonly lang?: string;
+  readonly dir?: 'ltr' | 'rtl';
+}
+/**
+ * `lang` and `dir` for the print document: the nearest ancestor of `host` (the element itself
+ * first) that has the attribute with a usable value, else the `<html>` element of `doc`. An
+ * empty `lang` and a `dir` other than `ltr` or `rtl` (such as `auto`) are skipped.
+ */
+export declare function printContext(host: Element | null, doc: Document): StarPrintContext;
+/** Options of `buildPrintDocument`. */
+export interface StarPrintOptions extends StarPrintContext {
+  /** Alignment of each column, in column order (see `printColumnAlign`). */
+  readonly align?: readonly StarPrintAlign[];
+}
+/** Base style of the print document. It is added with `stylePrintDocument`, not inline. */
+export declare const PRINT_STYLE = "body{font:12px/1.4 system-ui,sans-serif;color:#000;margin:16px}\nh1{font-size:16px;margin:0 0 12px;overflow-wrap:anywhere}\n.fit{container-type:inline-size}\ntable{width:100%;border-collapse:collapse}\nth,td{padding:4px 8px;border:1px solid #999;text-align:start;vertical-align:top;overflow-wrap:break-word}\nth{background:#eee}\nth.c,td.c{text-align:center}\nth.e,td.e{text-align:end}\ntd.s{white-space:nowrap}\nthead{display:table-header-group}\ntr{break-inside:avoid}";
 /**
- * HTML document with one table, for the browser print dialog ("Save as PDF"). The table is
- * built to print at the normal size. When the paper is too narrow for it, call
- * `fitPrintDocument` on the loaded document: the table then wraps, shrinks or breaks words
- * (see `PRINT_FIT_STEPS`) so that no column is cut off.
+ * HTML document with one table, for the browser print dialog ("Save as PDF"). The markup has
+ * no `style` element and no `style` attribute: the style is added to the loaded document by
+ * `stylePrintDocument`, as a constructed style sheet, so that it works under a policy without
+ * `'unsafe-inline'` in `style-src`. The table is built to print at the normal size. When the
+ * paper is too narrow for it, call `fitPrintDocument` on the loaded document: the table then
+ * wraps, shrinks or breaks words (see `PRINT_FIT_STEPS`) so that no column is cut off.
+ *
+ * `options.align` sets the alignment of each column (cells and header). `options.lang` and
+ * `options.dir` go on the `html` element.
  */
-export declare function buildPrintDocument(title: string, headers: readonly string[], rows: readonly (readonly StarExportCell[])[]): string;
+export declare function buildPrintDocument(title: string, headers: readonly string[], rows: readonly (readonly StarExportCell[])[], options?: StarPrintOptions): string;
 export {};

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

@@ -1,6 +1,11 @@
 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;
@@ -12,6 +17,34 @@ interface TreeRow<N> {
   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;
@@ -307,4 +340,4 @@ export declare class StarTreeSelect implements FormValueControl<readonly string[
     "touch": "touch";
   }, never, never, true, never>;
 }
-export {};
+export type { BranchLike, TreeRow };