@orkestrel/table 0.0.8 → 0.0.9

package/dist/src/browser/index.d.ts

@@ -0,0 +1,902 @@
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { JSONRecord } from '@orkestrel/contract';
+
+/**
+ * Keeps the rows whose cell falls between `minimum` and `maximum`, both included, compared the
+ * way the column compares.
+ *
+ * @remarks
+ * A `text` column holding ISO strings therefore takes a pair of ISO strings and reads as a date
+ * range.
+ */
+declare interface BetweenFilter {
+    readonly column: string;
+    readonly operator: 'between';
+    readonly minimum: string | number;
+    readonly maximum: string | number;
+}
+
+/**
+ * Represents a column drawn from a declared list, compared by the order that list declares. It
+ * requires `choices`.
+ *
+ * @remarks
+ * A cell holding a value the list does not offer is refused at admission.
+ */
+declare interface ChoiceColumn extends ColumnBase {
+    readonly cell: 'choice';
+    readonly choices: readonly ColumnChoice[];
+}
+
+/**
+ * Describes what every column carries, whatever its cells hold — the name a row's cell uses, the
+ * text a reader sees, whether a host draws the column, and the metadata a host attaches to it.
+ *
+ * @remarks
+ * `key` names the column, and it is the name a row uses for that column's cell. `label` is the
+ * heading a reader sees and `help` explains the column.
+ *
+ * `hidden` declares the column out of the presentation. It is still sorted, still filtered, and
+ * still serialized, because hiding is what a host draws rather than what the table holds.
+ *
+ * There is no `sortable` and no `filterable`. Every declared column sorts and filters; whether a
+ * heading offers either is the host's decision.
+ *
+ * `meta` is a bounded JSON carrier for whatever the schema declines to model. The table never
+ * reads it, no comparison sees it, and it round-trips verbatim. This package defines no key in
+ * it, so every key belongs to the host: an alignment, a format, a pixel width.
+ */
+declare interface ColumnBase {
+    readonly key: string;
+    readonly label?: string;
+    readonly help?: string;
+    readonly hidden?: boolean;
+    readonly meta?: JSONRecord;
+}
+
+/**
+ * Represents one value a `choice` column offers — `value` is stored, `label` is read, and `help`
+ * explains.
+ *
+ * @remarks
+ * The order a column declares its choices in is the order that column sorts by, which is what
+ * lets a status column sort draft before live before archived rather than alphabetically.
+ */
+declare interface ColumnChoice {
+    readonly value: string;
+    readonly label: string;
+    readonly help?: string;
+}
+
+/** Keeps the rows whose cell holds this `text` somewhere inside it. */
+declare interface ContainsFilter {
+    readonly column: string;
+    readonly operator: 'contains';
+    readonly text: string;
+}
+
+/** Creates a native table binding with one retained row owner.
+ * @param element - The native table to bind.
+ * @param document - The borrowed core document.
+ * @param options - Renderers, scoped controls, and listeners.
+ * @returns The native binding.
+ */
+export declare function createTableBinding(element: HTMLTableElement, document: TableInterface, options?: TableBindingOptions): TableBindingInterface;
+
+/** Keeps the rows whose cell holds exactly this `value`. */
+declare interface EqualsFilter {
+    readonly column: string;
+    readonly operator: 'equals';
+    readonly value: TableCell;
+}
+
+/**
+ * Manages the rows somebody has opened up.
+ *
+ * @remarks
+ * Expansion holds keys exactly as selection does, and what an opened row shows beside it is the
+ * host's to draw.
+ *
+ * @example
+ * ```ts
+ * table.expansion.toggle('7')
+ * table.expansion.keys.has('7') // true
+ * ```
+ */
+declare interface ExpansionManagerInterface {
+    /** Holds the keys of the rows opened right now. */
+    readonly keys: ReadonlySet<TableKey>;
+    /** Opens every row the table holds, one row, or several. */
+    expand(): void;
+    /**
+     * Opens one row.
+     *
+     * @param key - The row's key.
+     * @returns True if the key named a row the table holds; false otherwise.
+     */
+    expand(key: TableKey): boolean;
+    /**
+     * Opens several rows.
+     *
+     * @param keys - The rows' keys.
+     * @returns True if every key named a row the table holds; false otherwise. Every key is
+     *   checked before any row opens.
+     */
+    expand(keys: readonly TableKey[]): boolean;
+    /**
+     * Closes every row, one row, or several. A known key that was not open still answers `true`.
+     */
+    clear(): void;
+    /**
+     * Closes one row.
+     *
+     * @param key - The row's key.
+     * @returns True if the key named a row the table holds, whether or not it was
+     *   open; false otherwise.
+     */
+    clear(key: TableKey): boolean;
+    /**
+     * Closes several rows.
+     *
+     * @param keys - The rows' keys.
+     * @returns True if every key named a row the table holds; false otherwise. Every key is
+     *   checked before any row closes.
+     */
+    clear(keys: readonly TableKey[]): boolean;
+    /**
+     * Opens one row, or closes it when it is already open; over a list, turns each row around on
+     * its own.
+     *
+     * @param key - The row's key.
+     * @returns True if the key named a row the table holds; false otherwise.
+     */
+    toggle(key: TableKey): boolean;
+    /**
+     * Turns several rows around, each on its own.
+     *
+     * @param keys - The rows' keys.
+     * @returns True if every key named a row the table holds; false otherwise. Every key is
+     *   checked before any row turns.
+     */
+    toggle(keys: readonly TableKey[]): boolean;
+}
+
+/**
+ * Manages which rows a table keeps.
+ *
+ * @remarks
+ * The table holds at most one filter per column and keeps the rows every filter accepts.
+ *
+ * @example
+ * ```ts
+ * table.filter.set({ column: 'name', operator: 'contains', text: 'ad' })
+ * table.count // how many rows are left
+ * ```
+ */
+declare interface FilterManagerInterface {
+    /**
+     * Finds one column's filter; `undefined` when nothing filters that column.
+     *
+     * @param column - The column's key.
+     * @returns The filter, or `undefined` when nothing filters that column.
+     */
+    filter(column: string): TableFilter | undefined;
+    /**
+     * Reads every filter the table keeps rows by, in the order they were set.
+     *
+     * @returns The filters the table keeps rows by.
+     */
+    filters(): readonly TableFilter[];
+    /**
+     * Filters one column or several. A filter for a column already filtered replaces it; every
+     * other one joins the end. An undeclared column raises `COLUMN`, and a filter the column does
+     * not admit raises `CELL`.
+     *
+     * @param filters - The filters to set. A filter for a column already filtered replaces that
+     *   column's filter; every other one joins the end of the list.
+     * @throws A {@link TableError} coded `COLUMN` when a filter names a column the schema does not
+     *   declare, and `CELL` when an operand is one the column cannot hold. Every filter is checked
+     *   before any is set.
+     */
+    set(filters: readonly TableFilter[]): void;
+    /**
+     * Filters one column.
+     *
+     * @param filter - The filter to set.
+     * @throws A {@link TableError} coded `COLUMN` when the filter names a column the schema does
+     *   not declare, and `CELL` when an operand is one the column cannot hold.
+     */
+    set(filter: TableFilter): void;
+    /**
+     * Stops filtering everything, one column, or several. An undeclared column returns `false` and
+     * stops nothing.
+     */
+    remove(): void;
+    /**
+     * Stops filtering one column.
+     *
+     * @param column - The column's key.
+     * @returns True if the schema declares that column; false otherwise.
+     */
+    remove(column: string): boolean;
+    /**
+     * Stops filtering several columns.
+     *
+     * @param columns - The columns' keys.
+     * @returns True if the schema declares every one of them; false otherwise. Every key is
+     *   checked before any filter goes.
+     */
+    remove(columns: readonly string[]): boolean;
+}
+
+/** Represents a column of yes-or-no answers, compared false before true. */
+declare interface FlagColumn extends ColumnBase {
+    readonly cell: 'flag';
+}
+
+/** Checks whether a caught value is a native table binding error.
+ * @param value - The caught value.
+ * @returns Whether the value is a binding error.
+ */
+export declare function isTableBindingError(value: unknown): value is TableBindingError;
+
+/** Represents a column of numbers, compared by magnitude. */
+declare interface NumberColumn extends ColumnBase {
+    readonly cell: 'number';
+}
+
+/**
+ * Manages which stretch of the filtered rows the view shows.
+ *
+ * @remarks
+ * `page` is the state, counted from one. `offset` and `count` are worked out from it and from the
+ * rows the filter admits, so nothing here can drift out of step with what the table holds. A page
+ * beyond the last one clamps to the last one.
+ *
+ * `offset` counts the rows skipped, from zero, which is what a database query asks for.
+ *
+ * @example
+ * ```ts
+ * table.pagination.resize(10)
+ * table.pagination.move(3)
+ * table.pagination.offset // 20
+ * ```
+ */
+declare interface PaginationManagerInterface {
+    /** Holds the page the view shows, counted from one, and `1` when the table is not paged. */
+    readonly page: number;
+    /** Holds the number of rows one page shows, or `undefined` when the table is not paged. */
+    readonly limit: number | undefined;
+    /** Holds the number of rows the view skips before the page it shows, counted from zero. */
+    readonly offset: number;
+    /** Counts the pages the rows admitted by the filter fill, and `1` when the table is not paged. */
+    readonly count: number;
+    /**
+     * Shows another page, counted from one and clamped to the pages that exist.
+     *
+     * @param page - The page to show, counted from one and clamped to the pages that exist. `NaN`
+     *   shows the first page.
+     */
+    move(page: number): void;
+    /**
+     * Sets how many rows a page holds, keeping the first row the view was showing. Leave the
+     * argument out to stop paging.
+     *
+     * @remarks
+     * The page moves to wherever that first row now falls.
+     *
+     * @param limit - How many rows a page holds. Leave it out to stop paging, and the view shows
+     *   every row the filter admits.
+     */
+    resize(limit?: number): void;
+}
+
+/** Reads declared header metadata and explicit row keys into a validated core projection.
+ * @param element - A native table with data-table-key naming its identity column.
+ * @returns The schema and rows, validated together before any mutation.
+ * @throws A binding error when metadata, identities, or cells are malformed.
+ * @example
+ * ```ts
+ * import { createTable } from '@orkestrel/table'
+ * import { readTable } from '@orkestrel/table/browser'
+ * const element = document.createElement('table')
+ * element.setAttribute('data-table-key', 'id')
+ * element.innerHTML = '<thead><tr><th data-table-column="id" data-table-cell="text">Reference</th></tr></thead><tbody></tbody>'
+ * const projection = readTable(element)
+ * const table = createTable(projection.schema, { rows: projection.rows })
+ * ```
+ */
+export declare function readTable(element: HTMLTableElement): TableProjection;
+
+/** Reads explicit keys and declared direct cells against a core schema.
+ * @param schema - The declared columns and identity column.
+ * @param elements - Data rows belonging to one table, including retained detached rows.
+ * @returns Validated rows in the supplied order.
+ * @throws A binding error for duplicate keys, undeclared cells, or malformed values.
+ */
+export declare function readTableRows(schema: TableSchema, elements: readonly HTMLTableRowElement[]): readonly TableRow[];
+
+/** Reads and validates explicit native header metadata.
+ * @param element - The table declaring its identity column and cell kinds.
+ * @returns The core schema described by the native headers.
+ */
+export declare function readTableSchema(element: HTMLTableElement): TableSchema;
+
+/**
+ * Manages the rows a table holds, in the order it holds them.
+ *
+ * @remarks
+ * This order is the table's own, and it is what the view shows when no sort term separates two
+ * rows. Sorting reads it and never rewrites it.
+ *
+ * @example
+ * ```ts
+ * table.rows.add({ id: '7', name: 'Ada', age: 36 })
+ * table.rows.update({ id: '7', age: 37 })
+ * ```
+ */
+declare interface RowManagerInterface {
+    /**
+     * Finds one row by key; `undefined` when the table holds no such key.
+     *
+     * @param key - The row's key.
+     * @returns The row, or `undefined` when the table holds no such key.
+     */
+    row(key: TableKey): TableRow | undefined;
+    /**
+     * Reads every row the table holds, in its own order — unfiltered, unsorted, and unpaged.
+     *
+     * @returns The rows, in the order the table holds them.
+     */
+    rows(): readonly TableRow[];
+    /**
+     * Takes in one row or several, appending them in the order given. Every row is checked before
+     * any is admitted.
+     *
+     * @param rows - The rows to admit.
+     * @throws A {@link TableError} coded `KEY` when a row's key is missing, unusable, already
+     *   taken, or repeated inside the batch, and `CELL` when a cell is one its column cannot hold.
+     *   Every row is checked before any is admitted, so one refusal admits none of them.
+     */
+    add(rows: readonly TableRow[]): void;
+    /**
+     * Takes in one row, appending it.
+     *
+     * @param row - The row to admit.
+     * @throws A {@link TableError} coded `KEY` when the row's key is missing, unusable, or already
+     *   taken, and `CELL` when a cell is one its column cannot hold.
+     */
+    add(row: TableRow): void;
+    /**
+     * Writes over one row or several, each found by the key it carries. The cells given replace;
+     * the cells left out stay.
+     *
+     * @param rows - The rows to write, each carrying the key of the row it writes over.
+     * @returns True if every key named a row the table holds; false otherwise.
+     * @throws A {@link TableError} coded `CELL` when a cell is one its column cannot hold. Every
+     *   row is checked before any is written, so one refusal writes none of them.
+     */
+    update(rows: readonly TableRow[]): boolean;
+    /**
+     * Writes over one row, found by the key it carries.
+     *
+     * @remarks
+     * The cells given replace the cells held; the cells left out stay as they are. A row's key
+     * therefore cannot move, because a different key names a different row.
+     *
+     * @param row - The cells to write, carrying the key of the row they belong to.
+     * @returns True if the key named a row the table holds; false otherwise.
+     * @throws A {@link TableError} coded `CELL` when a cell is one its column cannot hold.
+     */
+    update(row: TableRow): boolean;
+    /**
+     * Replaces complete rows under existing keys, removing omitted cells without moving identities.
+     * @param rows - Whole rows to replace; every key must already exist.
+     * @returns Whether every key exists. A missing key leaves the batch unchanged.
+     * @throws A table error when any row is invalid, before any row is written.
+     */
+    replace(rows: readonly TableRow[]): boolean;
+    /**
+     * Replaces one complete row while retaining its position, selection, and expansion.
+     * @param row - The whole replacement, including its existing identity.
+     * @returns Whether the key exists.
+     */
+    replace(row: TableRow): boolean;
+    /**
+     * Moves one row to another place in the table's own order, counted from zero and clamped to the
+     * rows that exist.
+     *
+     * @param key - The row's key.
+     * @param index - Where to put it, counted from zero and clamped to the rows that exist. `NaN`
+     *   puts the row first.
+     * @returns True if the key named a row the table holds; false otherwise.
+     */
+    move(key: TableKey, index: number): boolean;
+    /**
+     * Takes out every row, one row, or several. Selection and expansion drop the keys of the rows
+     * that went.
+     */
+    remove(): void;
+    /**
+     * Takes out one row.
+     *
+     * @param key - The row's key.
+     * @returns True if the key named a row the table holds; false otherwise.
+     */
+    remove(key: TableKey): boolean;
+    /**
+     * Takes out several rows.
+     *
+     * @param keys - The rows' keys.
+     * @returns True if every key named a row the table holds; false otherwise. Every key is
+     *   checked before any row goes, so one unknown key leaves the whole call undone.
+     */
+    remove(keys: readonly TableKey[]): boolean;
+}
+
+/**
+ * Manages the rows somebody has picked.
+ *
+ * @remarks
+ * Selection holds keys, never rows or positions, so a pick survives a sort, a filter, and a page
+ * turn. A row that leaves the table takes its key out of the selection with it.
+ *
+ * @example
+ * ```ts
+ * table.selection.toggle('7')
+ * table.selection.keys.has('7') // true
+ * ```
+ */
+declare interface SelectionManagerInterface {
+    /** Holds the keys of the rows picked right now. */
+    readonly keys: ReadonlySet<TableKey>;
+    /**
+     * Picks every row the table holds, one row, or several. Every row, not every visible one.
+     *
+     * @remarks
+     * A host picking one page hands that page's keys over instead.
+     */
+    select(): void;
+    /**
+     * Picks one row.
+     *
+     * @param key - The row's key.
+     * @returns True if the key named a row the table holds; false otherwise.
+     */
+    select(key: TableKey): boolean;
+    /**
+     * Picks several rows.
+     *
+     * @param keys - The rows' keys.
+     * @returns True if every key named a row the table holds; false otherwise. Every key is
+     *   checked before any row is picked.
+     */
+    select(keys: readonly TableKey[]): boolean;
+    /**
+     * Drops every pick, one pick, or several. A known key that was not picked still answers `true`.
+     */
+    clear(): void;
+    /**
+     * Drops one pick.
+     *
+     * @param key - The row's key.
+     * @returns True if the key named a row the table holds, whether or not it was
+     *   picked; false otherwise.
+     */
+    clear(key: TableKey): boolean;
+    /**
+     * Drops several picks.
+     *
+     * @param keys - The rows' keys.
+     * @returns True if every key named a row the table holds; false otherwise. Every key is
+     *   checked before any pick is dropped.
+     */
+    clear(keys: readonly TableKey[]): boolean;
+    /**
+     * Picks one row, or drops it when it is already picked; over a list, turns each row around on
+     * its own.
+     *
+     * @param key - The row's key.
+     * @returns True if the key named a row the table holds; false otherwise.
+     */
+    toggle(key: TableKey): boolean;
+    /**
+     * Turns several rows around, each on its own.
+     *
+     * @param keys - The rows' keys.
+     * @returns True if every key named a row the table holds; false otherwise. Every key is
+     *   checked before any row turns.
+     */
+    toggle(keys: readonly TableKey[]): boolean;
+}
+
+/**
+ * Manages the order a table reads its rows in.
+ *
+ * @remarks
+ * The table holds one term per column and applies them in the order they were set. Which
+ * direction a heading offers next is the host's decision, so there is no cycling verb here: read
+ * the column's term, decide, then set or remove it.
+ *
+ * @example
+ * ```ts
+ * table.sort.set({ column: 'age', direction: 'descending' })
+ * table.sort.orders() // [{ column: 'age', direction: 'descending' }]
+ * ```
+ */
+declare interface SortManagerInterface {
+    /**
+     * Finds one column's term; `undefined` when nothing sorts that column.
+     *
+     * @param column - The column's key.
+     * @returns The term, or `undefined` when nothing sorts that column.
+     */
+    order(column: string): TableOrder | undefined;
+    /**
+     * Reads every term the table sorts by, first to last, in the order they decide.
+     *
+     * @returns The terms the table sorts by.
+     */
+    orders(): readonly TableOrder[];
+    /**
+     * Sorts by one column or several. A term for a column already sorted replaces its direction in
+     * place; every other term joins the end. An undeclared column raises `COLUMN`.
+     *
+     * @param orders - The terms to set. A term for a column already sorted replaces that column's
+     *   direction in place; every other term joins the end of the list.
+     * @throws A {@link TableError} coded `COLUMN` when a term names a column the schema does not
+     *   declare. Every term is checked before any is set.
+     */
+    set(orders: readonly TableOrder[]): void;
+    /**
+     * Sorts by one column.
+     *
+     * @param order - The term to set.
+     * @throws A {@link TableError} coded `COLUMN` when the term names a column the schema does not
+     *   declare.
+     */
+    set(order: TableOrder): void;
+    /**
+     * Stops sorting by everything, by one column, or by several. An undeclared column returns
+     * `false` and stops nothing.
+     */
+    remove(): void;
+    /**
+     * Stops sorting by one column.
+     *
+     * @param column - The column's key.
+     * @returns True if the schema declares that column; false otherwise.
+     */
+    remove(column: string): boolean;
+    /**
+     * Stops sorting by several columns.
+     *
+     * @param columns - The columns' keys.
+     * @returns True if the schema declares every one of them; false otherwise. Every key is
+     *   checked before any term goes.
+     */
+    remove(columns: readonly string[]): boolean;
+}
+
+/** Retains keyed native rows while projecting every core table manager. */
+export declare class TableBinding implements TableBindingInterface {
+    #private;
+    /** Creates a native binding over a borrowed document.
+     * @param element - The table whose body the binding owns.
+     * @param document - The core document retained by the caller.
+     * @param options - Row ownership, detail renderer, controls, and listeners.
+     */
+    constructor(element: HTMLTableElement, document: TableInterface, options?: TableBindingOptions);
+    get element(): HTMLTableElement;
+    get document(): TableInterface;
+    get destroyed(): boolean;
+    get emitter(): EmitterInterface<TableBindingEventMap>;
+    /** Reconciles native input and retries rendering against the current document. */
+    refresh(): void;
+    /** Releases native resources and restores authored state while retaining the core document. */
+    destroy(): void;
+}
+
+/** Represents a native table binding failure with a machine-readable code. */
+export declare class TableBindingError extends Error {
+    readonly code: TableBindingErrorCode;
+    /** Creates a binding failure.
+     * @param code - The failed boundary.
+     * @param message - The explanation.
+     */
+    constructor(code: TableBindingErrorCode, message: string);
+}
+
+/** Names a native binding failure at its structure, rendering, or lifecycle boundary. */
+export declare type TableBindingErrorCode = 'STRUCTURE';
+
+/** Announces cancelable sorting, completed rendering, and failed DOM operations. */
+export declare type TableBindingEventMap = {
+    readonly sort: readonly [event: CustomEvent<readonly TableOrder[]>];
+    readonly render: readonly [];
+    readonly error: readonly [error: unknown];
+};
+
+/** Binds native table elements to a borrowed core document. */
+export declare interface TableBindingInterface {
+    readonly element: HTMLTableElement;
+    readonly document: TableInterface;
+    readonly destroyed: boolean;
+    readonly emitter: EmitterInterface<TableBindingEventMap>;
+    /** Reconciles and renders the document, retrying a failed renderer. */
+    refresh(): void;
+    /** Releases listeners and restores owned attributes without destroying the document. */
+    destroy(): void;
+}
+
+/** Configures row ownership, detail presentation, scoped controls, and event listeners.
+ * @remarks
+ * Supply row for model-owned values and an empty body. Omit it to enhance authored rows
+ * matching the supplied document. Each callback patches only the supplied row contents.
+ * Detail receives a generated row containing a spanning cell. Scope contains the table and
+ * its external page checkbox. The error option handles listener throws; on.error observes
+ * failed native reads and renders. Neither callback owns row placement or core teardown.
+ */
+export declare interface TableBindingOptions {
+    readonly row?: TableRenderHandler;
+    readonly detail?: TableRenderHandler;
+    readonly scope?: HTMLElement;
+    readonly on?: EmitterHooks<TableBindingEventMap>;
+    readonly error?: EmitterErrorHandler;
+}
+
+/**
+ * Represents every value a cell can hold — a `string`, a `number`, or a `boolean`.
+ *
+ * @remarks
+ * The variant follows the column: `text` and `choice` hold a `string`, `number` holds a `number`,
+ * and `flag` holds a `boolean`. A cell nobody has filled has no key in its row, so absence is
+ * `undefined` and never `null` or an empty string.
+ */
+declare type TableCell = string | number | boolean;
+
+/**
+ * Represents any column a schema can declare — the union discriminated on `cell`.
+ *
+ * @remarks
+ * Narrowing on `cell` reaches each variant's own members.
+ *
+ * @example
+ * ```ts
+ * function choices(column: TableColumn): readonly ColumnChoice[] {
+ * 	return column.cell === 'choice' ? column.choices : []
+ * }
+ * ```
+ */
+declare type TableColumn = TextColumn | NumberColumn | FlagColumn | ChoiceColumn;
+
+/**
+ * Names which way a column sorts. A column nobody has sorted carries no term at all.
+ *
+ * @remarks
+ * No member of this union stands for unsorted; that state is the missing {@link TableOrder}.
+ */
+declare type TableDirection = 'ascending' | 'descending';
+
+/**
+ * Lists everything a table announces, mapping each event to the payload its listeners receive.
+ *
+ * @remarks
+ * Every event fires after the state it reports is committed, and only when something actually
+ * moved: a write that changes nothing announces nothing.
+ *
+ * `write` and `remove` carry one key and fire once per row, in the order the table wrote or
+ * removed them. A listener that wants the row reads it back.
+ *
+ * `sort` and `filter` carry the whole axis as it now stands, and `select` and `expand` carry the
+ * whole key set. Each payload is owned by the listener, so nothing it holds moves underneath it.
+ *
+ * `paginate` carries the page the table now shows, and fires whenever the paged window moves,
+ * including a clamp and a change of page size.
+ *
+ * `clear` is a signal, and it is the whole announcement of that reset: a clear emits no `remove`,
+ * no `select`, and no `paginate` beside it.
+ */
+declare type TableEventMap = {
+    readonly write: readonly [key: TableKey];
+    readonly remove: readonly [key: TableKey];
+    readonly sort: readonly [orders: readonly TableOrder[]];
+    readonly filter: readonly [filters: readonly TableFilter[]];
+    readonly select: readonly [keys: ReadonlySet<TableKey>];
+    readonly expand: readonly [keys: ReadonlySet<TableKey>];
+    readonly paginate: readonly [page: number];
+    readonly clear: readonly [];
+};
+
+/**
+ * Represents any filter a table can hold — the union discriminated on `operator`.
+ *
+ * @remarks
+ * Each operator carries only the operands it uses, so a `between` missing a bound cannot be
+ * written down.
+ *
+ * A table holds at most one filter per column and keeps every row all of them accept. There is no
+ * either-or composition in this version.
+ *
+ * @example
+ * ```ts
+ * const filter: TableFilter = { column: 'age', operator: 'between', minimum: 30, maximum: 40 }
+ * ```
+ */
+declare type TableFilter = ContainsFilter | BetweenFilter | EqualsFilter;
+
+/**
+ * Represents a table: what it declares, the rows it holds, and the lens it reads them through.
+ *
+ * @remarks
+ * The table owns values, not pixels. It renders nothing, reads no document, and names no host
+ * type, so one table serves a browser, a terminal, a report, and an export equally.
+ *
+ * One manager holds each axis that moves: `rows`, `sort`, `filter`, `selection`, `expansion`, and
+ * `pagination`. Nothing else is stored. `view` and `count` are worked out when they are read, so no
+ * second copy of the answer can go stale.
+ *
+ * A write validates all of itself before any of it lands, and announces itself once it has.
+ *
+ * @example
+ * ```ts
+ * table.filter.set({ column: 'name', operator: 'contains', text: 'ad' })
+ * table.sort.set({ column: 'age', direction: 'descending' })
+ * table.view // the rows to draw now: filtered, sorted, paged
+ * ```
+ */
+declare interface TableInterface {
+    /** Holds the table's event emitter. */
+    readonly emitter: EmitterInterface<TableEventMap>;
+    /** Holds what this table declares. */
+    readonly schema: TableSchema;
+    /** Manages the rows the table holds. */
+    readonly rows: RowManagerInterface;
+    /** Manages the order the table reads them in. */
+    readonly sort: SortManagerInterface;
+    /** Manages which of them the table keeps. */
+    readonly filter: FilterManagerInterface;
+    /** Manages the ones somebody has picked. */
+    readonly selection: SelectionManagerInterface;
+    /** Manages the ones somebody has opened up. */
+    readonly expansion: ExpansionManagerInterface;
+    /** Manages which stretch of them the view shows. */
+    readonly pagination: PaginationManagerInterface;
+    /**
+     * Returns the rows to draw right now: filtered, then sorted, then paged.
+     *
+     * @remarks
+     * It is worked out on every read and never stored, so it is right the instant anything moves.
+     */
+    readonly view: readonly TableRow[];
+    /** Counts the rows the filter admits, before the page narrows them. */
+    readonly count: number;
+    /** Reports whether the table has been torn down. */
+    readonly destroyed: boolean;
+    /**
+     * Puts the table back the way it opened, holding nothing. Rows, sort, filter, selection,
+     * expansion, and the page all reset.
+     *
+     * @remarks
+     * The table emits `clear` and nothing else, so a reset of ten thousand rows is one
+     * announcement.
+     */
+    clear(): void;
+    /**
+     * Tears the table down. Idempotent; afterwards every write raises `DESTROYED` and every getter
+     * still answers.
+     *
+     * @remarks
+     * The write throws a {@link TableError} carrying that code, and what a getter answers is what
+     * the table last held, so a host can read its way out of teardown without catching anything.
+     */
+    destroy(): void;
+}
+
+/**
+ * Represents a row's identity — a `string`, carried in the cell the schema's `key` names.
+ *
+ * @remarks
+ * The identity must be non-empty. A column's own identifier is a plain `string`; this names a row.
+ * Selection and expansion hold these keys and nothing else, so a row keeps its selection through a
+ * re-sort.
+ *
+ * @example
+ * ```ts
+ * const key: TableKey = '7'
+ * ```
+ */
+declare type TableKey = string;
+
+/**
+ * Represents one column's place in the sort — the `column` and its `direction`. The list is read
+ * left to right.
+ *
+ * @remarks
+ * The first term decides, and each later term breaks the tie the terms before it left. Rows no
+ * term separates keep the order the table holds them in.
+ *
+ * @example
+ * ```ts
+ * const order: TableOrder = { column: 'age', direction: 'descending' }
+ * ```
+ */
+declare interface TableOrder {
+    readonly column: string;
+    readonly direction: TableDirection;
+}
+
+/** Holds a validated native table projection for constructing a core document. */
+export declare interface TableProjection {
+    readonly schema: TableSchema;
+    readonly rows: readonly TableRow[];
+}
+
+/** Patches the contents of a retained row without moving or replacing that row.
+ * @param element - The binding-owned row; a detail row already contains its spanning cell.
+ * @param row - The core value to present.
+ */
+export declare type TableRenderHandler = (element: HTMLTableRowElement, row: TableRow) => void;
+
+/**
+ * Represents one row, keyed by column. A column nobody has filled has no key here.
+ *
+ * @remarks
+ * A row carries no key the schema does not declare, and the table clones and freezes it at
+ * admission, so nothing a caller holds afterwards can move a stored row.
+ *
+ * @example
+ * ```ts
+ * const row: TableRow = { id: '7', name: 'Ada', age: 36, active: true }
+ * ```
+ */
+declare type TableRow = Readonly<Record<string, TableCell>>;
+
+/**
+ * Holds everything a table declares about itself — how the table is described, which column
+ * carries row identity, and the columns it declares, in the order it declares them.
+ *
+ * @remarks
+ * The schema is data. It carries no function, so all of it crosses a wire and nothing is dropped
+ * on the way.
+ *
+ * `columns` is the schema's column list, and the order it declares is the order a host presents.
+ * `key` names the column whose cells carry row identity; it is required, it must name a declared
+ * column, and the table refuses a row whose cell there is missing, empty, or not a string. There
+ * is no default column, no positional fallback, and no key generation: an index is a position,
+ * and a position is not an identity.
+ *
+ * `name`, `label`, and `help` describe the table itself.
+ *
+ * @example
+ * ```ts
+ * const schema: TableSchema = {
+ * 	label: 'People',
+ * 	key: 'id',
+ * 	columns: [
+ * 		{ cell: 'text', key: 'id', label: 'Reference' },
+ * 		{ cell: 'text', key: 'name', label: 'Name' },
+ * 		{ cell: 'number', key: 'age', label: 'Age' },
+ * 	],
+ * }
+ * ```
+ */
+declare interface TableSchema {
+    readonly name?: string;
+    readonly label?: string;
+    readonly help?: string;
+    readonly key: string;
+    readonly columns: readonly TableColumn[];
+}
+
+/**
+ * Represents a column of text, compared lexically. Carries a date, a time, and a timestamp as ISO
+ * strings.
+ */
+declare interface TextColumn extends ColumnBase {
+    readonly cell: 'text';
+}
+
+export { }