@rivinia/table 0.0.0-stage → 1.0.0

package/types/rivinia-table.d.ts

@@ -0,0 +1,490 @@
+import { Signal, WritableSignal } from "@angular/core";
+/**
+ * The public vocabulary of `@rivinia/table`.
+ *
+ * Everything here is data: no behaviour, no Angular imports. The controller
+ * and the UI both read these shapes, which is what keeps the headless core
+ * testable without a DOM and the UI replaceable without touching the logic.
+ */
+/** Rows are identified by a stable id, never by an array position. */
+type TableRowId = string | number;
+type SortDirection = 'asc' | 'desc';
+/** One active sort level. Multi-sort is an ordered list of these. */
+interface SortState {
+  readonly column: string;
+  readonly direction: SortDirection;
+}
+/** One active column filter. The value shape belongs to the app's filter. */
+interface FilterState {
+  readonly column: string;
+  readonly value: unknown;
+}
+/** A row after the pipeline has given it an id and a position. */
+interface TableRow<T> {
+  /** Stable across sorting and paging: what selection and actions refer to. */
+  readonly id: TableRowId;
+  /** False when this row's configured identity is invalid or ambiguous. */
+  readonly identityValid?: boolean;
+  readonly data: T;
+  /** Position in `rows`, i.e. after filtering and sorting. */
+  readonly index: number;
+}
+/** A rectangle of a grid, expressed in cell coordinates. */
+interface CellSpan {
+  readonly rowSpan?: number;
+  readonly colSpan?: number;
+}
+/** What a `span()` / `colSpan()` callback is given. */
+interface SpanContext<T> {
+  readonly row: TableRow<T>;
+  readonly column: TableColumn<T>;
+  readonly value: unknown;
+  readonly rowIndex: number;
+  readonly columnIndex: number;
+}
+/** A span anchored at one cell; the cells it covers are not rendered. */
+interface SpanCell {
+  readonly row: number;
+  readonly column: number;
+  readonly rowSpan: number;
+  readonly colSpan: number;
+}
+/**
+ * The resolved span grid for the current rows and columns.
+ *
+ * Every query is O(1): the model is a dense matrix of anchors built once per
+ * (rows, columns) pair, so rendering 10,000 rows does not re-walk the options.
+ */
+interface SpanModel {
+  /** Anchors only, in reading order. Covered cells appear nowhere. */
+  readonly cells: readonly SpanCell[];
+  /** True when a span STARTS at this position. */
+  at(row: number, column: number): SpanCell | null;
+  /** The span COVERING this position, including the anchor itself. */
+  owner(row: number, column: number): SpanCell | null;
+  /** One step of keyboard navigation that respects spans. */
+  move(row: number, column: number, dRow: number, dColumn: number): {
+    readonly row: number;
+    readonly column: number;
+  };
+}
+/** A value accessor: a key of the row, or a function for computed cells. */
+/**
+ * `V` defaults to `any`, not `unknown`, on purpose.
+ *
+ * A column array holds columns of DIFFERENT value types, so it is written
+ * `TableColumn<Invoice>[]`. With `V = unknown` that annotation means
+ * `TableColumn<Invoice, unknown>`, and every `accessor('amount', …)` — which
+ * infers `V = number` — is rejected, because `format(value: number)` cannot
+ * accept an `unknown` parameter. `any` keeps the inferred type at the call site
+ * (`accessor('amount').format` still gets `number`) while letting the array
+ * annotation erase it.
+ */
+type TableColumnAccessor<T, V = any> = (keyof T & string) | ((row: T) => V);
+/** How a cell's text behaves when it does not fit. See the text section. */
+type TextOverflow = 'nowrap' | 'wrap' | 'clamp';
+interface TableColumn<T, V = any> {
+  readonly id: string;
+  readonly header?: string;
+  readonly accessor?: TableColumnAccessor<T, V>;
+  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: V, row: T, locale: string) => string;
+  readonly comparator?: (a: V, b: V) => number;
+  readonly hidden?: boolean;
+  /** Per column, because a note column and an id column need different rules. */
+  readonly textOverflow?: TextOverflow;
+  /** Only meaningful with `textOverflow: 'clamp'`. Defaults to 2. */
+  readonly lines?: number;
+  /** Row-span sugar: merge consecutive rows whose key is equal. */
+  readonly merge?: 'equal' | ((row: T, anchor: T) => boolean);
+  /** Column-span sugar: how many columns this cell covers. */
+  readonly colSpan?: number | ((context: SpanContext<T>) => number);
+  /** Escape hatch, both axes. Cannot be combined with `merge` / `colSpan`. */
+  readonly span?: (context: SpanContext<T>) => CellSpan | null | undefined;
+}
+/** A column definition without the two fields `tableColumn()` supplies. */
+type ColumnDef<T, V = unknown> = Omit<TableColumn<T, V>, 'id' | 'accessor'>;
+/** Server mode: the app fetches, the table only describes what it needs. */
+interface TableRequest {
+  readonly page: number;
+  readonly pageSize: number;
+  readonly sort: readonly SortState[];
+  readonly filters: readonly FilterState[];
+  readonly search: string;
+}
+/** The serialisable slice of the table: what a URL or a saved view holds. */
+interface TableState {
+  readonly sort: readonly SortState[];
+  readonly filters: readonly FilterState[];
+  readonly search: string;
+  readonly page: number;
+  readonly pageSize: number;
+  /** Column ids in display order. */
+  readonly order: readonly string[];
+  /** Column ids the user hid. */
+  readonly hidden: readonly string[];
+  /** Pinned column ids on the start edge. */
+  readonly pinnedStart: readonly string[];
+  /** Pinned column ids on the end edge. */
+  readonly pinnedEnd: readonly string[];
+  /** Row ids, and the ids explicitly excluded from the set. */
+  readonly selected: readonly TableRowId[];
+  readonly excluded: readonly TableRowId[];
+}
+/**
+ * Where span diagnostics go. A `warn` sink is injected rather than hard-coded
+ * so a consumer can route the messages through its own logger, and a test can
+ * assert them without touching the console.
+ */
+interface SpanWarnOptions {
+  readonly warn?: (message: string) => void;
+}
+/**
+ * `buildSpanModel` options.
+ *
+ * `strict` exists because the same builder serves two callers with opposite
+ * needs: `createTable()` validates its column list ONCE and may throw (a
+ * conflicting declaration is a bug in code, not in data), while a render-time
+ * rebuild must never throw — an app that swaps its columns at runtime would
+ * otherwise blank the grid. Strict mode is the documented default; the
+ * controller passes `strict: false` and lets `span` win, as the design says.
+ */
+interface SpanBuildOptions extends SpanWarnOptions {
+  /**
+   * Throw when a column declares `span` together with `merge`/`colSpan`.
+   * @default true
+   */
+  readonly strict?: boolean;
+}
+/**
+ * Validates a column list without touching any data. `createTable()` calls
+ * this at construction so a conflicting declaration fails immediately — with
+ * an actionable message — instead of at the first paint, and in production
+ * too, because it is a defect in the column list rather than in the data.
+ */
+export declare function assertSpanColumns<T>(columns: readonly TableColumn<T>[], options?: SpanWarnOptions): void;
+/**
+ * Resolves `span` / `merge` / `colSpan` into the concrete span grid of the
+ * given rows and columns.
+ *
+ * Semantics (ported from the validated prototype, 35/35 contract checks):
+ * - only anchors exist; a covered position has no cell and, in the UI, no DOM;
+ * - first claim wins: an overlapping later span is shrunk (width, then height)
+ *   and reported, so a configuration hazard is never silent;
+ * - row spans stop at the page (a page is a DOM boundary) and column spans at
+ *   the visible range and at the pinned-region boundary;
+ * - `Infinity` means "the rest of my region", resolved before integer checks;
+ * - `0`, negatives, `NaN` and fractions are clamped to 1 with a warning, so a
+ *   bad return value can never delete a cell;
+ * - rows must already be the rendered order: a merge follows adjacency, so
+ *   sorting legitimately starts a new run.
+ *
+ * The model is a dense matrix of owner indices, so `at()` / `owner()` are O(1)
+ * and `move()` walks only the cells it skips.
+ */
+export declare function buildSpanModel<T>(rows: readonly TableRow<T>[], columns: readonly TableColumn<T>[], options?: SpanBuildOptions): SpanModel;
+/**
+ * The value of one cell, resolved through the column's accessor.
+ *
+ * The accessor is either a key or a function (the shared contract allows
+ * both), so every consumer — the pipeline, the span engine, a custom renderer
+ * — reads a cell the same way. A display/action column has no accessor and
+ * therefore no value; `undefined` is the honest answer, not an error.
+ */
+export declare function readCellValue<T, V = unknown>(column: TableColumn<T, V>, row: TableRow<T>): V | undefined;
+/** The result of `paginate`, with the display range the footer needs. */
+interface TablePage<T> {
+  readonly pageRows: readonly TableRow<T>[];
+  /** Rows before pagination. */
+  readonly total: number;
+  /** `ceil(total / pageSize)`; `0` when there is no row. */
+  readonly pageCount: number;
+  /** 1-based index of the first row on this page; `0` when the page is empty. */
+  readonly start: number;
+  /** 1-based index of the last row on this page; `0` when the page is empty. */
+  readonly end: number;
+}
+/**
+ * Keeps the rows that satisfy EVERY active filter.
+ *
+ * A filter on a column that is hidden, unknown, or has no accessor is ignored
+ * rather than treated as "match nothing": a saved view that references a
+ * removed column should lose that constraint, not empty the table.
+ */
+export declare function applyFilters<T>(rows: readonly TableRow<T>[], columns: readonly TableColumn<T>[], filters: readonly FilterState[]): readonly TableRow<T>[];
+/**
+ * Global search across every column that has a value.
+ *
+ * Display columns are skipped (they hold no data), and the needle is
+ * normalized with the same Arabic rules as the filters, so search finds a name
+ * written with or without diacritics. An empty search returns the input array
+ * unchanged — identity matters, because the controller's `computed` chain
+ * uses it to avoid downstream work.
+ */
+export declare function applySearch<T>(rows: readonly TableRow<T>[], columns: readonly TableColumn<T>[], search: string): readonly TableRow<T>[];
+/**
+ * Multi-level, stable sort with nulls LAST in both directions.
+ *
+ * Two decisions worth stating: a missing value always sorts to the end (a
+ * blank salary at the top of an ascending list is noise, and flipping it with
+ * the direction would put it at the top of a descending one too), and the
+ * pre-sort index is the final tie-break, so equal keys keep their order even
+ * on an engine whose sort is not stable.
+ *
+ * Sort levels that reference a hidden, unknown or accessor-less column are
+ * skipped rather than applied as a no-op, so `sorting` never lies about what
+ * is active.
+ */
+export declare function applySort<T>(rows: readonly TableRow<T>[], columns: readonly TableColumn<T>[], sorting: readonly SortState[], locale?: string): readonly TableRow<T>[];
+/**
+ * Slices one page and reports the footer's numbers.
+ *
+ * `start` / `end` are 1-based and inclusive ("1-25 of 12,345"), and both are 0
+ * when the page holds nothing — a page past the end is legal and returns an
+ * empty page, it is not silently clamped to the last one (clamping would hide
+ * a controller bug and lie about the requested state).
+ *
+ * A non-positive / non-finite `pageSize` means "no pagination": every row on
+ * one page. That is a deliberate degradation rather than a crash.
+ */
+export declare function paginate<T>(rows: readonly TableRow<T>[], page: number, pageSize: number): TablePage<T>;
+/**
+ * The two ways a column is declared. `accessor` is a data column (it has a
+ * value to sort, filter and span by); `display` is a rendering-only column
+ * such as an action or a status chip.
+ */
+interface TableColumnFactory<T> {
+  /**
+   * A data column bound to a key of the row.
+   *
+   * The id defaults to the key and the header to the id, so a column is a
+   * one-liner until it needs to say something else — and the id stays the key
+   * unless the definition overrides it... it cannot: `ColumnDef` omits `id`,
+   * which keeps `state`, saved views and template slots referring to the same
+   * string the data is bound to.
+   */
+  accessor<K extends keyof T & string>(key: K, definition?: ColumnDef<T, T[K]>): TableColumn<T, T[K]>;
+  /**
+   * A column with no accessor: a template, an action, a computed badge.
+   *
+   * It still has an id (that is what `rvTableCell="status"` and the state
+   * round-trip refer to), but no value, so sorting and filtering skip it.
+   */
+  display(id: string, definition?: ColumnDef<T, unknown>): TableColumn<T>;
+}
+/**
+ * Typed column factory: `tableColumn<Employee>()`.
+ *
+ * The factory exists instead of an object literal so `accessor('salary')` is
+ * checked against the row type (`keyof T`) and the value type (`T[K]`) at the
+ * call site — a misspelled key is a compile error, not an empty column. The
+ * returned columns are frozen: a column list is configuration, and a mutation
+ * after `createTable()` would silently disagree with the cached signals.
+ */
+export declare function tableColumn<T>(): TableColumnFactory<T>;
+/** How many rows a table can select. */
+type TableSelectionKind = 'none' | 'single' | 'multi';
+/**
+ * The shape of the selection set (not how many rows may be selected).
+ *
+ * `include` lists the selected ids; `exclude` means "everything the current
+ * rows contain, minus these". The second form is what makes "select all 12,345
+ * matching rows" representable without materializing 12,345 ids, and it is why
+ * a server can be sent `{ all: true, except: [...] }` instead.
+ */
+type TableSelectionMode = 'include' | 'exclude';
+/** Which rows "select all" covers. */
+type TableSelectionScope = 'page' | 'filtered' | 'all';
+/** Selection configuration. Absent means selection is off. */
+interface TableSelectionOptions {
+  /**
+   * `'none'` renders no selection affordance and makes every method a no-op.
+   * @default 'none'
+   */
+  readonly mode?: TableSelectionKind;
+  /**
+   * Scope used by `selectAll()` when the caller does not pass one.
+   * @default 'filtered'
+   */
+  readonly selectAllScope?: TableSelectionScope;
+}
+/**
+ * Server-mode loader shape. Declared so the public contract is stable, but
+ * NOT wired in 0.1.0: the client-only build never fetches.
+ */
+interface TableServerOptions<T> {
+  readonly load: (request: TableRequest, context: {
+    readonly abortSignal: AbortSignal;
+  }) => Promise<{
+    readonly items: readonly T[];
+    readonly total: number;
+  }>;
+}
+/**
+ * Everything `createTable()` needs.
+ *
+ * It is a FUNCTION, not an object, because every read must happen inside the
+ * controller's `computed`s: passing `data: () => this.api.rows()` (a signal
+ * read) is what makes the row model react to new data without a subscription
+ * or a `reload()` call.
+ */
+interface TableOptions<T> {
+  /** The declared columns, in display order. */
+  readonly columns: () => readonly TableColumn<T>[];
+  /** Client mode: the whole data set. */
+  readonly data?: () => readonly T[];
+  /** Server mode: declared only, not wired in 0.1.0 (the table warns). */
+  readonly server?: TableServerOptions<T>;
+  /**
+   * Row identity. IDs must be unique, stable, non-empty strings or finite
+   * numbers within the full data set. In development invalid or duplicate
+   * values throw with their source row positions. In production ambiguous
+   * rows remain visible but identity-dependent actions (such as selection) are
+   * disabled for them. Defaults to `row.id`, then a per-object generated id
+   * kept in a `WeakMap`; never use the array index.
+   */
+  readonly getRowId?: (row: T) => TableRowId;
+  /** Locale for collation and formatting; read lazily so it can be a signal. */
+  readonly locale?: () => string;
+  /** Selection configuration; absent = selection off. */
+  readonly selection?: TableSelectionOptions;
+  /**
+   * Rows per page. `initialState.pageSize` — a restored view — wins over it, so
+   * a saved state is never silently replaced by the default.
+   * @default 25
+   */
+  readonly pageSize?: number;
+  /** The saved view the table starts from. */
+  readonly initialState?: Partial<TableState>;
+  /** Skip the client filter/search stage (the caller filtered the data). */
+  readonly manualFiltering?: boolean;
+  /** Skip the client sort stage (the caller sorted the data). */
+  readonly manualSorting?: boolean;
+  /** Skip the client page stage (the caller paged the data). */
+  readonly manualPagination?: boolean;
+  /** Total row count when the data comes from outside. */
+  readonly rowCount?: () => number;
+  /** Diagnostic sink for span/clamp messages. Defaults to dev-mode console. */
+  readonly warn?: (message: string) => void;
+}
+/**
+ * Row selection as the UI sees it.
+ *
+ * Reads are signals so a header checkbox and every row cell update together;
+ * writes are methods because they must normalize the include/exclude mode and
+ * respect `mode: 'none' | 'single'`.
+ */
+interface RiviniaTableSelection {
+  /** True when selection is enabled at all (the UI renders no box otherwise). */
+  readonly enabled: boolean;
+  /** True for multi-select; false for single-select (checkbox vs radio). */
+  readonly multiple: boolean;
+  /** Include or exclude set. */
+  readonly mode: Signal<TableSelectionMode>;
+  /** Selected ids, in row order, limited to the rows the table currently holds. */
+  readonly ids: Signal<readonly TableRowId[]>;
+  /** `ids().length`. */
+  readonly count: Signal<number>;
+  select(id: TableRowId): void;
+  deselect(id: TableRowId): void;
+  toggle(id: TableRowId): void;
+  /** Clears the selection (including "select all", in every mode). */
+  clear(): void;
+  isSelected(id: TableRowId): boolean;
+  /** Adds every row of the current page; in exclude mode it re-includes them. */
+  selectAllOnPage(): void;
+  /**
+   * `'page'` selects the page; `'filtered'`/`'all'` switch to exclude mode
+   * with nothing excluded, i.e. every matching row (and any future one).
+   */
+  selectAll(scope?: TableSelectionScope): void;
+}
+/**
+ * The table, as a chain of `computed`s — one per pipeline stage.
+ *
+ * `data -> rows (filter, search, sort) -> pageRows -> spans` means Angular's
+ * own caching gives incremental recomputation for free: a page change does not
+ * re-sort, a sort does not re-filter, and selection/scroll never rebuild the
+ * span matrix because nothing in that chain reads them.
+ *
+ * The controller owns no fetching and no DOM. It is constructed outside the
+ * injector graph (`createTable` needs no provider), which is what lets a
+ * consumer build one inside a component field initializer or inside a test.
+ */
+export declare class RiviniaTable<T> {
+  /** The declared columns, hidden ones included, in display order. */
+  readonly columns: Signal<readonly TableColumn<T>[]>;
+  /** The columns that render: `columns` without `hidden: true`. */
+  readonly visibleColumns: Signal<readonly TableColumn<T>[]>;
+  /** Filtered and sorted rows, numbered from 0. */
+  readonly rows: Signal<readonly TableRow<T>[]>;
+  /** The current page of `rows`. */
+  readonly pageRows: Signal<readonly TableRow<T>[]>;
+  /** The resolved span grid over `pageRows` x `visibleColumns`. */
+  readonly spans: Signal<SpanModel>;
+  /** Client row count, or `rowCount()` when the data comes from outside. */
+  readonly total: Signal<number>;
+  /** `ceil(total / pageSize)`; `0` for an empty table. */
+  readonly pageCount: Signal<number>;
+  /** Ordered multi-sort; index 0 is the primary level. */
+  readonly sorting: WritableSignal<readonly SortState[]>;
+  /** Active column filters, ANDed together. */
+  readonly filters: WritableSignal<readonly FilterState[]>;
+  /** Global search across every data column. */
+  readonly globalSearch: WritableSignal<string>;
+  /**
+   * 0-based page. A linked signal: it returns to 0 when the filter, sort or
+   * search changes (the result set changed under the user), while an explicit
+   * `set()` still wins until the next such change.
+   */
+  readonly page: WritableSignal<number>;
+  readonly pageSize: WritableSignal<number>;
+  readonly selection: RiviniaTableSelection;
+  /** What a server-mode fetch would need; `data`-driven tables ignore it. */
+  readonly request: Signal<TableRequest>;
+  /** The serializable slice: a saved view, a URL, a test assertion. */
+  readonly state: Signal<TableState>;
+  private readonly options;
+  private readonly initialState;
+  /** What `resetState()` returns to: the restored size, else the option. */
+  private readonly defaultPageSize;
+  private readonly warn;
+  private readonly warned;
+  private readonly generatedIds;
+  private readonly selectionImpl;
+  private generatedIdSeq;
+  constructor(options: () => TableOptions<T>);
+  /**
+   * Applies a saved view. Unknown fields are ignored on purpose: column order,
+   * visibility and pinning are owned by the column list in 0.1.0, so a state
+   * that carries them round-trips unchanged without pretending the controller
+   * can reorder the consumer's columns.
+   */
+  setState(patch: Partial<TableState>): void;
+  /** Returns to `initialState`, including the initial page and selection. */
+  resetState(): void;
+  /**
+   * `getRowId` -> `row.id` -> a per-object generated id. Custom IDs must be
+   * unique, stable, non-empty strings or finite numbers; ambiguous rows are
+   * rejected in development and excluded from identity-dependent operations
+   * in production. Primitive rows require a unique `getRowId`.
+   *
+   * A primitive row has no identity of its own, so equal primitives collapse
+   * into one id; that is documented, and `getRowId` is the answer.
+   */
+  private readonly defaultRowId;
+}
+/**
+ * Creates a table from a reactive options function.
+ *
+ * No DI, no injection context, no HTTP: the caller passes `data` as a signal
+ * read and gets derived signals back, so the table is usable in a component
+ * field initializer, in a test, or in a headless script.
+ */
+export declare function createTable<T>(options: () => TableOptions<T>): RiviniaTable<T>;
+export type { CellSpan, ColumnDef, FilterState, RiviniaTableSelection, SortDirection, SortState, SpanBuildOptions, SpanCell, SpanContext, SpanModel, SpanWarnOptions, TableColumn, TableColumnAccessor, TableColumnFactory, TableOptions, TablePage, TableRequest, TableRow, TableRowId, TableSelectionKind, TableSelectionMode, TableSelectionOptions, TableSelectionScope, TableServerOptions, TableState, TextOverflow };