@rivinia/table 0.0.0-stage → 0.1.0

package/types/rivinia-table-ui.d.ts

@@ -0,0 +1,514 @@
+import { CellSpan, SortDirection, SortState, SpanModel, TableRow, TableRowId, TextOverflow } from "@rivinia/table";
+import * as i0 from "@angular/core";
+import { TemplateRef } from "@angular/core";
+/**
+ * The column shape the grid READS — a renderer-facing contract, not a copy of
+ * the core type.
+ *
+ * Why not `TableColumn<any>`: that looks like the obvious "some column" type,
+ * but it is not a supertype of a real one. Its accessor is
+ * `(keyof any & string) | ((row: any) => V)` = `string | …`, and a concrete
+ * `keyof Person & string` is narrower, so `TableColumn<Person>` would NOT be
+ * assignable to `TableColumn<any>` — a consumer could not pass their own
+ * typed columns at all. The same inversion repeats through `SpanContext`.
+ *
+ * So the callbacks here take `any` as their PARAMETER type (always assignable
+ * in both directions) instead of `any` as the type argument. The result is a
+ * genuine supertype: every `TableColumn<T>` is assignable to it.
+ *
+ * The renderer reads `id`, `header`, `accessor`, `format`, `sortable`,
+ * `width`, `flex`, `align`, `hidden`, `textOverflow` and `lines`. The rest is
+ * declared so a column literal typed as `TableUiColumn[]` can carry the full
+ * core vocabulary without an excess-property error: spans are rendered from
+ * `[spans]` (not from the column), `comparator` belongs to the core's sorting,
+ * and pinning is not implemented by this entry point.
+ */
+interface TableUiColumn {
+  readonly id: string;
+  readonly header?: string;
+  readonly accessor?: string | ((row: any) => unknown);
+  readonly sortable?: boolean;
+  readonly width?: string;
+  /** 0 = fixed; > 0 absorbs free space. */
+  readonly flex?: number;
+  readonly pinned?: 'start' | 'end';
+  readonly align?: 'start' | 'center' | 'end';
+  readonly format?: (value: any, row: any, locale: string) => string;
+  readonly comparator?: (a: any, b: any) => number;
+  readonly hidden?: boolean;
+  readonly textOverflow?: TextOverflow;
+  readonly lines?: number;
+  readonly merge?: 'equal' | ((row: any, anchor: any) => boolean);
+  readonly colSpan?: number | ((context: any) => number);
+  readonly span?: (context: any) => CellSpan | null | undefined;
+}
+/** A row as the grid reads it. `TableRow<T>` has no variance, so this is safe. */
+type TableUiRow = TableRow<any>;
+/** Row height + padding preset. Token values per preset are in the CSS. */
+type TableUiDensity = 'compact' | 'default' | 'comfortable';
+/**
+ * The text a grid shows on its own. Everything here is also a `[labels]`
+ * override, so an Arabic page gets Arabic text without a second code path.
+ */
+interface TableUiLabels {
+  /** The grid's accessible name when `[ariaLabel]` is unset. */
+  readonly grid: string;
+  /** Announced while `[loading]` is true (the skeletons are decorative). */
+  readonly loading: string;
+  /** Fallback when `[error]` holds something that is not an `Error`/string. */
+  readonly error: string;
+  /** Used when `[emptyMessage]` is unset. */
+  readonly empty: string;
+  /** The grid's `aria-describedby`: what the keyboard does. */
+  readonly keyboardHelp: string;
+}
+export declare const TABLE_UI_LABELS_EN: TableUiLabels;
+export declare const TABLE_UI_LABELS_AR: TableUiLabels;
+/**
+ * The label set for a locale, defaulting to English.
+ *
+ * It is a plain function (not a DI token) because it is pure and the UI entry
+ * must stay usable without a provider — the same rule the core follows.
+ */
+declare function tableUiLabels(locale: string | undefined): TableUiLabels;
+/**
+ * What a projected `[rvTableCell]` template receives.
+ *
+ * `$implicit` is the {@link TableRow} wrapper — the same shape the `rows`
+ * input holds — so `let-row` is what the grid itself sees. `data` is the
+ * consumer's own object, `value` is the accessor's resolved value BEFORE
+ * `format`, and `column` is the column definition. The value is untrusted
+ * (`unknown`) because the grid does not know the column's value type.
+ *
+ * ```html
+ * <ng-template rvTableCell="actions" let-row let-data="data">
+ *   <button (click)="open(row.id)">Open {{ data.number }}</button>
+ * </ng-template>
+ * ```
+ */
+interface TableUiCellContext<T = unknown> {
+  readonly $implicit: TableRow<T>;
+  /** The same row under a named key, for templates that already destructure. */
+  readonly row: TableRow<T>;
+  /** The consumer's own object (`row.data`). */
+  readonly data: T;
+  /** The accessor's value before `column.format`. */
+  readonly value: unknown;
+  /** The renderer-facing column definition the grid rendered. */
+  readonly column: TableUiColumn;
+  /** Position inside the rendered page, not the index in the full data set. */
+  readonly rowIndex: number;
+}
+/** Payload of `(selectionChange)`: the new set AND which row moved it. */
+interface TableUiSelectionChange<T = unknown> {
+  readonly selected: ReadonlySet<TableRowId>;
+  /** `null` when no single row caused the change (programmatic or clear-all). */
+  readonly row: TableRow<T> | null;
+}
+/** One cell as the template sees it — everything resolved, nothing computed there. */
+interface RenderCell {
+  readonly column: TableUiColumn;
+  readonly columnIndex: number;
+  readonly rowSpan: number;
+  readonly colSpan: number;
+  readonly spanned: boolean;
+  readonly overflow: TextOverflow;
+  /** `null` unless the column is a clamp column; drives `--rv-table-clamp-lines`. */
+  readonly lines: number | null;
+  readonly text: string;
+  /** Id of the visually-hidden full-text node, when the cell can be cut off. */
+  readonly describedBy: string | null;
+  readonly template: TemplateRef<TableUiCellContext> | null;
+  readonly context: TableUiCellContext;
+  /** Explicit placement, so covered positions leave no auto-flow hole. */
+  readonly gridRow: string;
+  readonly gridColumn: string;
+}
+interface RenderRow {
+  /** The effective row id (`[rowKey]` applied): what selection and tracking use. */
+  readonly id: TableRowId;
+  readonly row: TableUiRow;
+  /** Position inside the rendered page. */
+  readonly rowIndex: number;
+  /** 1-based position in the FULL data set; the header is row 1. */
+  readonly ariaRowIndex: number;
+  readonly selected: boolean;
+  readonly cells: readonly RenderCell[];
+}
+interface TableUiState {
+  readonly kind: 'error' | 'empty';
+  readonly message: string;
+}
+/**
+ * `<rv-table>` — a `role="grid"` data grid, built from divs on purpose.
+ *
+ * ## Why not `<table>`
+ * An interactive grid is `role="grid"`, not `role="table"`, so the roles have
+ * to be written either way. Once they are, a native table adds layout
+ * negotiation (`table-layout`), inconsistent sticky headers and no way to span
+ * a cell across ROWS without owning the row structure. Divs + CSS grid keep
+ * the geometry explicit and the ARIA exact.
+ *
+ * ## The consumer decides what a cell contains
+ * The column list carries geometry and a header; the CELL is either the
+ * column's `accessor` (+ optional `format`) or — for an actions column, a
+ * badge, an avatar — a projected template keyed by column id:
+ *
+ * ```html
+ * <rv-table [columns]="columns()" [rows]="rows()" [spans]="spans()" selectable>
+ *   <ng-template rvTableCell="actions" let-row let-data="data">
+ *     <button type="button" (click)="edit(row.id)">Edit {{ data.number }}</button>
+ *   </ng-template>
+ * </rv-table>
+ * ```
+ *
+ * The table never knows that "actions" means actions: a column with an id and
+ * no `accessor` renders only the projected template. A template also WINS over
+ * an accessor when both exist — markup is an override, not a second source of
+ * truth for the column list (`[columns]` stays the only one).
+ *
+ * ## Spans
+ * `[spans]` is the core's resolved `SpanModel`: only anchors are rendered,
+ * covered positions have no element at all (nothing is hidden with a flag), and
+ * each anchor is placed on the shared CSS grid with an explicit
+ * `grid-row: <start> / span <n>` and `grid-column: <start> / span <n>`. Because
+ * the spans are real grid spans, a merged cell survives wrapping rows and
+ * needs no height arithmetic. `aria-rowspan` / `aria-colspan` are written only
+ * when greater than 1, and every cell carries `aria-colindex` (WAI-ARIA
+ * requires it once the grid is not a simple matrix).
+ *
+ * ## Keyboard
+ * One tab stop (roving `tabindex`), moved with the arrows through
+ * `spans.move()` — so moving INTO a merged cell lands on its anchor and moving
+ * inside one leaves it. Home/End pick the first/last anchor of the row,
+ * PageUp/PageDown move a screen, Enter activates the row, Space toggles
+ * selection. Horizontal arrows mirror in RTL; vertical ones never do.
+ *
+ * ## Theming
+ * Every colour and shape is read AT THE USE SITE as
+ * `var(--rv-table-<part>, var(--rv-<semantic>, <default>))`, so one
+ * `:root { --rv-bg: … }` reaches the grid. Nothing is declared on the host, so
+ * a token set anywhere on an ancestor wins (the D42/D46 rule).
+ * `[density]` only changes the FALLBACK of the size tokens, so an explicit
+ * token still wins over the preset.
+ *
+ * The override surface is documented and stable:
+ * classes `.rv-table-scroller`, `.rv-table-grid`, `.rv-table-head`,
+ * `.rv-table-head-cell`, `.rv-table-head-button`, `.rv-table-head-label`,
+ * `.rv-table-body`, `.rv-table-row`, `.rv-table-cell`, `.rv-table-text`,
+ * `.rv-table-sort`, `.rv-table-sort-rank`, `.rv-table-state`,
+ * `.rv-table-skeleton`, `.rv-table-sr-only`;
+ * hooks `[data-density]`, `[data-loading]`, `[data-sticky]`, `[data-selectable]`
+ * on the host, `[data-sortable]`, `[data-sorted]`, `[data-sort-rank]`,
+ * `[data-sort-direction]` on a header cell, and `[data-selected]`,
+ * `[data-span]`, `[data-align]`, `[data-overflow]`, `[data-row]`, `[data-col]`
+ * on a body cell. Component styles are injected at runtime and carry the
+ * component's scope attribute, so a plain `.rv-table-cell { … }` in an app
+ * stylesheet can lose at equal specificity: scope it as
+ * `rv-table .rv-table-cell { … }`, or use the tokens.
+ */
+export declare class RiviniaTableComponent {
+  private readonly host;
+  private readonly scroller;
+  private readonly projectedCells;
+  /** The columns, in render order. Hidden ones are filtered out, not counted. */
+  readonly columns: import("@angular/core").InputSignal<readonly TableUiColumn[]>;
+  /** The page's rows (already filtered/sorted/paged by the consumer or core). */
+  readonly rows: import("@angular/core").InputSignal<readonly TableUiRow[]>;
+  /** The core's resolved span matrix for `rows` + visible columns. */
+  readonly spans: import("@angular/core").InputSignal<SpanModel | null>;
+  /** While true the grid is `aria-busy`, renders skeletons and no data rows. */
+  readonly loading: import("@angular/core").InputSignal<boolean>;
+  /**
+   * How many skeleton rows to draw. `'auto'` (default) mirrors the rows that
+   * are currently rendered, at least one — so the layout does not jump.
+   */
+  readonly skeletonRows: import("@angular/core").InputSignal<number | "auto">;
+  /** A failed load. `null`/`undefined` means "no error". */
+  readonly error: import("@angular/core").InputSignal<unknown>;
+  /** Text of the empty state. Unset falls back to the locale's label. */
+  readonly emptyMessage: import("@angular/core").InputSignal<string | undefined>;
+  /**
+   * Derives the id used by selection, tracking and `(rowActivate)` from the
+   * row's data. Unset uses `TableRow.id`, which is already stable.
+   */
+  readonly rowKey: import("@angular/core").InputSignal<((row: any) => TableRowId) | undefined>;
+  /** Renders row selection: `aria-selected`, Space, and click-to-select. */
+  readonly selectable: import("@angular/core").InputSignal<boolean>;
+  /**
+   * The selected row ids. Two-way: `[(selected)]`. A `Set` (not an array)
+   * because every row asks "am I selected?" on every render.
+   */
+  readonly selected: import("@angular/core").ModelSignal<ReadonlySet<TableRowId>>;
+  /**
+   * The active sort, highest priority first. Two-way: `[(sort)]`, and the
+   * model's own `(sortChange)` fires whenever this component changes it.
+   */
+  readonly sort: import("@angular/core").ModelSignal<readonly SortState[]>;
+  readonly density: import("@angular/core").InputSignal<TableUiDensity>;
+  /** Sticks the header to the top of the scroller. */
+  readonly stickyHeader: import("@angular/core").InputSignal<boolean>;
+  /**
+   * The number of rows in the FULL result set, for `aria-rowcount` when the
+   * consumer pages on the server. Unset derives it from the rows' `index`,
+   * which is exact when the grid renders the whole set.
+   */
+  readonly totalRows: import("@angular/core").InputSignal<number | undefined>;
+  /** Accessible name of the grid (`aria-label`). */
+  readonly ariaLabel: import("@angular/core").InputSignal<string | undefined>;
+  /** Overrides for the built-in English/Arabic text. */
+  readonly labels: import("@angular/core").InputSignal<Partial<TableUiLabels> | undefined>;
+  /** Enter on a focused cell, or a double-click on a row. */
+  readonly rowActivate: import("@angular/core").OutputEmitterRef<TableUiRow>;
+  /**
+   * A row was selected/deselected by the user. The model already carries the
+   * new set (`selectedChange`); this output also names the row that moved.
+   */
+  readonly selectionChange: import("@angular/core").OutputEmitterRef<TableUiSelectionChange<unknown>>;
+  protected readonly instructionsId: string;
+  private readonly uid;
+  protected readonly visibleColumns: import("@angular/core").Signal<TableUiColumn[]>;
+  protected readonly columnCount: import("@angular/core").Signal<number>;
+  /**
+   * The ONE column geometry both the header and the body read.
+   *
+   * A flex column keeps its declared width as the track's FLOOR
+   * (`minmax(<width>, Nfr)`, design §5.2): with `minmax(0, Nfr)` a narrow
+   * container would collapse the column to zero and its content would vanish
+   * instead of scrolling. Fixed columns are their width, untouched.
+   */
+  protected readonly columnTemplate: import("@angular/core").Signal<string>;
+  /**
+   * The grid's intrinsic width, so the scroller actually scrolls instead of
+   * squeezing every column. It is the sum of the declared widths — which is
+   * why a column width should be a length (`px`, `rem`, `ch`), not `max-content`.
+   */
+  protected readonly minWidth: import("@angular/core").Signal<string>;
+  /**
+   * `aria-label` written on the HOST — `<rv-table aria-label="Invoices">` — is
+   * the attribute a consumer reaches for first, but the `role="grid"` element
+   * lives INSIDE the component, so the attribute would otherwise stop at the
+   * host and the grid would keep its fallback name ("Data grid"). Read on every
+   * change detection: it is a `getAttribute` call, and a dynamic label belongs
+   * on the `[ariaLabel]` input, which is reactive.
+   */
+  protected get hostLabel(): string | undefined;
+  protected readonly effectiveLabels: import("@angular/core").Signal<TableUiLabels>;
+  protected readonly locale: import("@angular/core").Signal<string>;
+  /** Column id → the consumer's template. Rebuilt only when content changes. */
+  private readonly cellTemplates;
+  /**
+   * Sort lookup by column id: direction plus 1-based priority. One map instead
+   * of a linear search per rendered header cell.
+   */
+  private readonly sortIndex;
+  /** The fully resolved view model. Nothing in the template computes. */
+  protected readonly renderedRows: import("@angular/core").Signal<readonly RenderRow[]>;
+  protected readonly skeletonList: import("@angular/core").Signal<unknown[]>;
+  protected readonly state: import("@angular/core").Signal<TableUiState | null>;
+  /**
+   * The rows that actually have DOM cells. While loading the skeletons replace
+   * them, and an error/empty state replaces them too, so the keyboard must not
+   * "move" into a row that has no element to focus.
+   */
+  protected readonly bodyRows: import("@angular/core").Signal<readonly RenderRow[]>;
+  /**
+   * The header row is row 1 (WAI-ARIA counts the header), so the grid's row
+   * count is the data count + 1. `-1` is legal ("unknown"), but a wrong count
+   * is worse than an honest one, so `[totalRows]` is the precise answer when
+   * the consumer pages on the server.
+   */
+  protected readonly rowCount: import("@angular/core").Signal<number>;
+  /** Row index in the rendered page; `-1` is the header row. */
+  private readonly active;
+  private pendingFocus;
+  /**
+   * The active cell, clamped to what is actually rendered. A stale row index
+   * (the data shrank) would otherwise leave the grid with no tab stop at all.
+   * While loading there are no data cells, so the header is the tab stop.
+   */
+  protected readonly effectiveActive: import("@angular/core").Signal<{
+    row: number;
+    column: number;
+  }>;
+  constructor();
+  protected isActive(row: number, column: number): boolean;
+  protected isSortable(column: TableUiColumn): boolean;
+  protected sortRank(column: TableUiColumn): number;
+  protected sortDirection(column: TableUiColumn): SortDirection | null;
+  /**
+   * `aria-sort` lives on exactly ONE header (the highest-priority sort), as
+   * WAI-ARIA requires; secondary sorted columns are shown with a rank badge
+   * and announce `none`, because the attribute has no "secondary" value.
+   */
+  protected ariaSort(column: TableUiColumn): 'ascending' | 'descending' | 'none' | null;
+  protected onHeaderClick(column: TableUiColumn, columnIndex: number, event: MouseEvent): void;
+  protected rowId(row: TableUiRow): TableRowId;
+  protected onRowActivate(item: RenderRow): void;
+  /**
+   * A double-click is a row activation. It is ignored when it lands on an
+   * interactive element inside a projected template: the action the user asked
+   * for (Edit, Open, a link) must not also fire the row's own activation.
+   */
+  protected onRowDoubleClick(item: RenderRow, event: MouseEvent): void;
+  protected onCellClick(item: RenderRow, cell: RenderCell, event: MouseEvent): void;
+  protected onCellFocus(row: number, column: number): void;
+  protected onKeydown(event: KeyboardEvent): void;
+  private onHeaderKey;
+  private cycleSort;
+  /**
+   * A page step stays inside the BODY. The header is reachable with ArrowUp,
+   * but PageUp from the first data row must not surprise the user by landing on
+   * the sort controls; page keys are a data-reading affordance.
+   */
+  private page;
+  private moveBy;
+  /** Clamp to the page, then snap onto the anchor of whatever cell is there. */
+  private moveTo;
+  private firstColumn;
+  private lastColumn;
+  /** One screen minus one row; 10 when there is no layout to measure (SSR, jsdom). */
+  private pageRows;
+  private focusCell;
+  /**
+   * Direction is read from the nearest `[dir]` FIRST, then from computed
+   * style: jsdom does not inherit computed direction, and `dir="auto"` needs
+   * the computed answer anyway.
+   */
+  private isRtl;
+  private buildCells;
+  private readValue;
+  private toggleRow;
+  private errorText;
+  static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaTableComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<RiviniaTableComponent, "rv-table", never, {
+    "columns": {
+      "alias": "columns";
+      "required": true;
+      "isSignal": true;
+    };
+    "rows": {
+      "alias": "rows";
+      "required": false;
+      "isSignal": true;
+    };
+    "spans": {
+      "alias": "spans";
+      "required": false;
+      "isSignal": true;
+    };
+    "loading": {
+      "alias": "loading";
+      "required": false;
+      "isSignal": true;
+    };
+    "skeletonRows": {
+      "alias": "skeletonRows";
+      "required": false;
+      "isSignal": true;
+    };
+    "error": {
+      "alias": "error";
+      "required": false;
+      "isSignal": true;
+    };
+    "emptyMessage": {
+      "alias": "emptyMessage";
+      "required": false;
+      "isSignal": true;
+    };
+    "rowKey": {
+      "alias": "rowKey";
+      "required": false;
+      "isSignal": true;
+    };
+    "selectable": {
+      "alias": "selectable";
+      "required": false;
+      "isSignal": true;
+    };
+    "selected": {
+      "alias": "selected";
+      "required": false;
+      "isSignal": true;
+    };
+    "sort": {
+      "alias": "sort";
+      "required": false;
+      "isSignal": true;
+    };
+    "density": {
+      "alias": "density";
+      "required": false;
+      "isSignal": true;
+    };
+    "stickyHeader": {
+      "alias": "stickyHeader";
+      "required": false;
+      "isSignal": true;
+    };
+    "totalRows": {
+      "alias": "totalRows";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "labels": {
+      "alias": "labels";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "selected": "selectedChange";
+    "sort": "sortChange";
+    "rowActivate": "rowActivate";
+    "selectionChange": "selectionChange";
+  }, ["projectedCells"], ["[rvTableCell]"], true, never>;
+}
+/**
+ * `[rvTableCell]="columnId"` — the consumer's renderer for one column.
+ *
+ * Put it on an `<ng-template>`; the grid never renders the template directly,
+ * it asks for it BY COLUMN ID and instantiates it once per row. That is what
+ * makes an actions column possible without the table knowing anything about
+ * actions: the column list only declares geometry and a header, and the
+ * markup decides what a cell contains.
+ *
+ * ```html
+ * <rv-table [columns]="columns()" [rows]="rows()">
+ *   <ng-template rvTableCell="actions" let-row let-data="data">
+ *     <button type="button" (click)="edit(data)">Edit</button>
+ *   </ng-template>
+ * </rv-table>
+ * ```
+ *
+ * A column whose id has no template and no `accessor` renders an empty cell,
+ * so declare the column for its width/header and supply the template here.
+ * The template wins over `accessor` when both exist: markup is an override.
+ *
+ * The context is {@link TableUiCellContext} — `$implicit` (and `row`) is the
+ * `TableRow`, `data` is your object, `value` is the accessor's value.
+ */
+export declare class RvTableCell {
+  /**
+   * The id of the column this template renders. It must match a
+   * `TableColumn.id`; an id that matches nothing is simply never used (the
+   * grid cannot throw at render time for a template it was given).
+   */
+  readonly columnId: import("@angular/core").InputSignal<string>;
+  /** The template to instantiate. Injected from the `<ng-template>` host. */
+  readonly template: TemplateRef<TableUiCellContext>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<RvTableCell, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<RvTableCell, "[rvTableCell]", never, {
+    "columnId": {
+      "alias": "rvTableCell";
+      "required": true;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+export type { TableUiCellContext, TableUiColumn, TableUiDensity, TableUiLabels, TableUiRow, TableUiSelectionChange };