@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/components/ui/stateful-table.d.ts

@@ -0,0 +1,345 @@
+import { type ReactNode } from 'react';
+import { type TableSortDirection } from './table-sort.js';
+/**
+ * Which way a column is ordered, and how to leave that order.
+ *
+ * `TableSort`'s own union, taken rather than restated, because two Components that
+ * each declared a direction would be two lists to keep in step and the sort
+ * header's whole reason for existing is that it agrees with whatever reorders the
+ * rows.
+ */
+export type StatefulTableDirection = TableSortDirection;
+/**
+ * One column of a StatefulTable that cannot be ordered.
+ *
+ * A separate arm rather than an optional `accessor` beside an optional `sortable`,
+ * and the split is the argument. A sortable column needs a value to sort *by*, and
+ * the value is not always the cell's text: a status column orders `critical,
+ * degraded, healthy` rather than alphabetically, and a column of charts orders on
+ * the number the chart reports. So the accessor is required in the sortable arm and
+ * the `sortable` boolean is absent from this one, and two optionals would be a
+ * combination that type-checks and then cannot sort anything.
+ */
+export type StatefulTableColumn<TRow> = {
+    /** The column's stable key, and what a sort names. */
+    id: string;
+    /** The column's visible name. */
+    header: ReactNode;
+    /** The cell's content for one row. */
+    cell: (row: TRow) => ReactNode;
+    /** Whether this column can be ordered. */
+    sortable?: false;
+};
+/** One column of a StatefulTable that can be ordered, and by what. */
+export type StatefulTableSortableColumn<TRow> = {
+    /** The column's stable key, and what a sort names. */
+    id: string;
+    /** The column's visible name. */
+    header: ReactNode;
+    /** The cell's content for one row. */
+    cell: (row: TRow) => ReactNode;
+    /** This column can be ordered, and the value it orders on. */
+    sortable: true;
+    /**
+     * The value this column orders on, for one row.
+     *
+     * Required, and it is the whole of this Component's authority over the caller's
+     * data: the value sorted on is the caller's and never the cell's text, because a
+     * Component that inferred an accessor from a rendered cell would be deciding the
+     * order of records it cannot read.
+     */
+    accessor: (row: TRow) => string | number;
+};
+/** One column, sortable or not. */
+export type StatefulTableColumnUnion<TRow> = StatefulTableColumn<TRow> | StatefulTableSortableColumn<TRow>;
+/**
+ * Which column is ordered, and which way.
+ *
+ * A single value rather than a per-column record, and the reason is the one
+ * `table-sort` gives for putting `aria-sort` on exactly one header: two columns
+ * both reporting an order is a table claiming to be sorted two ways at once, and a
+ * reader comparing the two hears a contradiction. One column, one direction.
+ */
+export type StatefulTableSort = {
+    /** The id of the column that is ordered. */
+    column: string;
+    /** The way it is ordered. */
+    direction: StatefulTableDirection;
+};
+/**
+ * The state a StatefulTable owns and the caller reads.
+ *
+ * One value rather than four props, and the reason is that these four are not
+ * independent. Which page is showing is a function of the order and the set in every
+ * implementation anyone writes, and four props let a caller hold a page number that
+ * contradicts the sort they have just set, which is a table showing rows that are
+ * not in the order its own header claims. One value is also one place to put, so a
+ * caller can hold it in a reducer, in a store, or in an address query and this
+ * Component does not care which.
+ */
+export type StatefulTableState = {
+    /**
+     * Which column is ordered and which way, or `null` for the caller's own order.
+     *
+     * `null` is the order of the array as it was handed over, and it is reachable from
+     * the control rather than only at mount, because a reader who sorted a column to
+     * find the extreme and no longer cares has to be able to get the original back
+     * from the header they already know. That is `table-sort`'s three-state cycle and
+     * this is where the third state is spent.
+     */
+    sort: StatefulTableSort | null;
+    /** The keys of the rows the reader has selected. */
+    selection: readonly string[];
+    /**
+     * The ids of the columns the reader has hidden.
+     *
+     * Kept beside `selection` rather than folded into the column list for the reason
+     * the sort is a value and not a column field: a column marked hidden in the list
+     * would be undone by every fetch that rebuilds the list, and a caller's columns
+     * say which columns exist rather than which are on screen right now.
+     */
+    hiddenColumns: readonly string[];
+    /**
+     * The page being shown, counting from zero.
+     *
+     * Clamped on the way out rather than refused on the way in, for the reason `Steps`
+     * clamps `current`: an out-of-range page after the caller narrows the set is an
+     * ordinary event, and the reader should land on the last page that has rows on it
+     * rather than on an empty table with an error beside it.
+     */
+    page: number;
+};
+/**
+ * One state change, and which of the four facts it moved.
+ *
+ * `changed` is there so a caller can persist one thing rather than four: a table in
+ * an address wants the sort and the page and not the selection, and a change report
+ * with no field for that makes every caller diff the object themselves. It is called
+ * `visibility` rather than `hiddenColumns` because it names the fact that changed
+ * rather than the field that holds it, and a caller reading a persisted event log is
+ * better served by the former.
+ */
+export type StatefulTableChange = {
+    /** The state to move to. */
+    state: StatefulTableState;
+    /** Which of the four facts changed. */
+    changed: 'sort' | 'selection' | 'visibility' | 'page';
+};
+/**
+ * The props a StatefulTable accepts.
+ *
+ * A declared interface rather than one extended from `Table`'s, and the reason is
+ * this Component: `Table` is presentational and forwards every native table prop, so
+ * extending it would hand this Component a `children` that is a body, a `className`
+ * that is a table's, and no place at all for the four state props that are the
+ * reason it exists.
+ */
+export interface StatefulTableProps<TRow> {
+    /**
+     * The rows, in the order the caller wants them before this Component has reordered
+     * anything.
+     *
+     * Required, and the caller's order is what `sort: null` means. A caller with a
+     * server-side order hands over rows already in that order and a reader who sorts
+     * and then unsorts gets the caller's order back rather than an arbitrary one.
+     */
+    rows: readonly TRow[];
+    /**
+     * The caller's key for a row.
+     *
+     * Required, because selection is a set of keys and reordering maps positions to
+     * rows, and a Component that read identity off a position would select the wrong
+     * row the instant the order changed.
+     */
+    getRowId: (row: TRow) => string;
+    /** The columns, in the order they are shown. */
+    columns: readonly StatefulTableColumnUnion<TRow>[];
+    /**
+     * The state, controlled.
+     *
+     * Required and never defaulted, because a table that kept its own sort and
+     * selection could not be read back by the caller, and a caller who cannot read the
+     * sort cannot put it in an address, cannot restore it, and cannot tell a server
+     * which page to send. Controlled is the decision; an uncontrolled sibling would be
+     * a second way to say the same four facts and the two would disagree within a
+     * release.
+     */
+    state: StatefulTableState;
+    /** Called when any of the four facts changes. */
+    onChange: (change: StatefulTableChange) => void;
+    /**
+     * The table's caption, drawn by `TableCaption` where a caption belongs.
+     *
+     * Optional rather than required because `label` already names the table, and a
+     * caption that repeats the accessible name is a sentence read twice. Pass one
+     * where it says something the name does not: what the set is a slice of, or what
+     * a row means.
+     */
+    caption?: ReactNode;
+    /**
+     * The table's accessible name.
+     *
+     * Required, and a `string` because it goes into `aria-label` and an accessible
+     * name is a string. A table with no name is announced as "table" and a page with
+     * two of them is a page where a reader cannot tell which is which.
+     */
+    label: string;
+    /**
+     * The words read for what pressing a sortable header will do.
+     *
+     * Required, and a function of the *next* direction for the reason `table-sort`
+     * gives at length: a header that announces "sorted ascending" when it is already
+     * ascending tells a reader nothing about the press they are about to make.
+     */
+    announceSort: (column: string, direction: StatefulTableDirection) => string;
+    /**
+     * The label of the control that selects every row on the page.
+     *
+     * Required, and a `string` because it is written into `aria-label` and an
+     * accessible name is a string. It is expected to carry the count, because a
+     * control labelled "Select all" beside twenty rows a reader has not seen is a
+     * claim about the whole set when it means the page.
+     */
+    selectAllLabel: string;
+    /** The accessible name of one row's selection control, given the row's key. */
+    selectRowLabel: (rowKey: string) => string;
+    /**
+     * The label of the control that shows and hides columns.
+     *
+     * Required, and it opens a disclosure rather than sitting as a row of checkboxes
+     * because which columns exist is a fact about the caller's data and the screen it
+     * is on, and a control that is a row of boxes beside the header on a phone has
+     * taken the table's whole width to describe itself.
+     */
+    columnsLabel: ReactNode;
+    /**
+     * The words shown when the set has no rows.
+     *
+     * Required, and required because an empty `<tbody>` is a table with a shape and
+     * nothing in it, which reads as a rendering failure. A sentence is the caller's,
+     * because a set that is empty because it is loading and a set that is empty
+     * because there is nothing are two different sentences and only the caller knows
+     * which one applies.
+     */
+    emptyLabel: ReactNode;
+    /**
+     * The words on the control that goes to the previous page.
+     *
+     * Required, and required as a pair with `nextPageLabel` because the two are the
+     * same control in two positions: a caller who localises one and not the other has
+     * a control that looks localised and is half of it, which is the state
+     * `PaginationPrevious` exists to prevent.
+     */
+    previousPageLabel: string;
+    /** The words on the control that goes to the next page. */
+    nextPageLabel: string;
+    /**
+     * The words for where the reader is in the set, given the page and how many there
+     * are.
+     *
+     * Required, and a function because "Page 2 of 9" is false in a language that puts
+     * the total first, and a pager that assembled the sentence would have assembled it
+     * in one of them. It is also the accessible name of the pager, so a reader who
+     * arrives at that row is told where they are before they touch either control.
+     */
+    pageLabel: (page: number, pages: number) => string;
+    /**
+     * How many rows a page holds.
+     *
+     * A number and not a class, because the bound is data: the same table is forty rows
+     * in a sidebar and eight on a full page, and a caller who could only say
+     * `max-h-80` would be picking one of those for the other. It has no effect on a
+     * set smaller than it.
+     *
+     * @defaultValue 10
+     */
+    pageSize?: number;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * A row set that owns its sort, its selection, its column visibility and its page,
+ * and hands all four to the caller as one value.
+ *
+ * **Prism's `table` is presentational and `table-sort` is a header cell, and this
+ * is the thing neither of them is.** `Table` forwards every native table prop and
+ * holds nothing; `TableSort` reports a direction and leaves the reordering to the
+ * caller. Between them is the half every consumer writes again: the row order, which
+ * rows are selected, which columns are on screen and which page is showing, and the
+ * four have to agree with each other after every change. That agreement is the
+ * Component. A caller holding them as four independent props gets a page number that
+ * does not match the sort they have just set, which is a table whose rows are not in
+ * the order its own header claims.
+ *
+ * **One state value rather than four props, for the same reason.** The four are not
+ * independent: which page is showing is a function of the order and the set in every
+ * implementation anyone writes, and four props let a caller hold a contradiction. One
+ * value is also one place to hold it, so a caller can put it in a reducer, in their
+ * store, or in an address query and this Component does not care which. The cost is
+ * that a caller changing one fact spreads the rest, which is one line and is the
+ * price of the four being unable to disagree.
+ *
+ * **It owns the order, and the accessor is how.** This is the one place a Component
+ * in this package decides something about the caller's data, and the refusal to do
+ * it any other way is the design. A column is sortable only when it carries an
+ * `accessor`, so the value sorted on is the caller's and never the cell's text: a
+ * status column that orders `critical, degraded, healthy` and a column of charts that
+ * orders on the number the chart reports are both expressible here, and neither is
+ * guessable from a cell. That is why the column type is a union of a sortable arm and
+ * a plain one rather than two optionals: an optional accessor beside a `sortable`
+ * boolean is a combination that type-checks and then cannot sort anything.
+ *
+ * **Numbers compare as numbers and everything else goes through the platform's own
+ * collator.** The `Intl.Collator` half is not a nicety: a name column ordered with
+ * `<` puts every uppercase name before every lowercase one in half the languages a
+ * product is sold in, and the comparator that fixes that belongs to the platform
+ * rather than to this package. The locale is the runtime's own, which is right on a
+ * server and wrong on a multilingual page, so it is stated here rather than guessed.
+ * `numeric` is on so a column of identifiers orders 2 before 10, which is the one
+ * case a reader always notices.
+ *
+ * **A server-ordered set is the original order, and that is what `sort: null` means.**
+ * A caller with a server-side order hands over rows already in it, and a reader who
+ * sorts and then unsorts gets the caller's order back. The three-state cycle on the
+ * header is `table-sort`'s and it is spent here, in the third state: one route back
+ * to the original, and it is the header they already know.
+ *
+ * **Selection is a set of the caller's keys, and the header's control covers the
+ * page rather than the set.** The two differ whenever the caller pages, and
+ * conflating them is the defect this Component exists to prevent: a "select all"
+ * that selected every row on the server when twenty are on screen acted on four
+ * hundred rows a reader never saw. So the header's checkbox covers the rows on the
+ * current page, it is `indeterminate` when some of them are selected, and the words
+ * are the caller's.
+ *
+ * **Column visibility is the reader's preference and lives beside the columns rather
+ * than inside them.** A column marked hidden in the caller's array would be undone by
+ * every fetch that rebuilds the array, and a caller's columns say which columns exist
+ * rather than which are on screen right now. Nothing is hidden on width alone: a
+ * table with eleven columns on a phone is a hard problem, and pruning columns by
+ * guessing at a width takes away a column the reader needed without telling them,
+ * which is a worse failure than a scroll.
+ *
+ * **The header is a real `<tr>` of `<th scope="col">` cells and the sortable ones are
+ * `TableSort`, composed.** Neither is this Component's decision: a header row of
+ * `div`s is a grid with no column names in it, and a screen reader moving across a
+ * table announces a column rather than a button. `TableSort` carries the direction,
+ * the mark and the announcement, and the caller's `announceSort` is passed straight
+ * through to it, so the sentence a reader hears about a press is the caller's.
+ *
+ * **The pager is drawn only when there is more than one page**, because a pager on a
+ * set of four rows is a row of controls describing a choice the reader does not have.
+ * Its controls are `aria-disabled` rather than natively disabled on the end pages,
+ * for the reason `FormWizard` gives on its back control: a control that leaves the
+ * tab order answers a press with silence.
+ *
+ * **It is a client Component**, because every one of the four changes happens after
+ * the reader acts, and because `state`, `onChange` and the row and column accessors
+ * are functions the caller hands it, which is a client-to-client boundary wherever it
+ * is written. What that costs is the price of every client control: a server
+ * Component may render one page of rows once with the state already in place, and
+ * what it may not do is let the reader change any of the four facts.
+ */
+declare function StatefulTable({ rows, getRowId, columns, state, onChange, caption, label, announceSort, selectAllLabel, selectRowLabel, columnsLabel, emptyLabel, previousPageLabel, nextPageLabel, pageLabel, pageSize, className, }: StatefulTableProps<any>): import("react").JSX.Element;
+export { StatefulTable };
+//# sourceMappingURL=stateful-table.d.ts.map

package/dist/components/ui/stateful-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateful-table.d.ts","sourceRoot":"","sources":["../../../src/components/ui/stateful-table.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAavD,OAAO,EAAa,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAGjE;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,kBAAkB,CAAA;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,CAAC,IAAI,IAAI;IACtC,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAA;IACV,iCAAiC;IACjC,MAAM,EAAE,SAAS,CAAA;IACjB,sCAAsC;IACtC,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS,CAAA;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAA;CACjB,CAAA;AAED,sEAAsE;AACtE,MAAM,MAAM,2BAA2B,CAAC,IAAI,IAAI;IAC9C,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAA;IACV,iCAAiC;IACjC,MAAM,EAAE,SAAS,CAAA;IACjB,sCAAsC;IACtC,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS,CAAA;IAC9B,8DAA8D;IAC9D,QAAQ,EAAE,IAAI,CAAA;IACd;;;;;;;OAOG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,GAAG,MAAM,CAAA;CACzC,CAAA;AAED,mCAAmC;AACnC,MAAM,MAAM,wBAAwB,CAAC,IAAI,IACrC,mBAAmB,CAAC,IAAI,CAAC,GACzB,2BAA2B,CAAC,IAAI,CAAC,CAAA;AAErC;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAA;IACd,6BAA6B;IAC7B,SAAS,EAAE,sBAAsB,CAAA;CAClC,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;;;;OAQG;IACH,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC9B,oDAAoD;IACpD,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B;;;;;;;OAOG;IACH,aAAa,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,4BAA4B;IAC5B,KAAK,EAAE,kBAAkB,CAAA;IACzB,uCAAuC;IACvC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,YAAY,GAAG,MAAM,CAAA;CACtD,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB,CAAC,IAAI;IACtC;;;;;;;OAOG;IACH,IAAI,EAAE,SAAS,IAAI,EAAE,CAAA;IACrB;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,CAAA;IAC/B,gDAAgD;IAChD,OAAO,EAAE,SAAS,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAA;IAClD;;;;;;;;;OASG;IACH,KAAK,EAAE,kBAAkB,CAAA;IACzB,iDAAiD;IACjD,QAAQ,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAA;IAC/C;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,sBAAsB,KAAK,MAAM,CAAA;IAC3E;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,CAAA;IACtB,+EAA+E;IAC/E,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAA;IAC1C;;;;;;;OAOG;IACH,YAAY,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,UAAU,EAAE,SAAS,CAAA;IACrB;;;;;;;OAOG;IACH,iBAAiB,EAAE,MAAM,CAAA;IACzB,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;;;OAQG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClD;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AACH,iBAAS,aAAa,CAAC,EACrB,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,KAAK,EACL,QAAQ,EACR,OAAO,EACP,KAAK,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,SAAS,EACT,QAAa,EACb,SAAS,GACV,EAAE,kBAAkB,CAAC,GAAG,CAAC,+BAoPzB;AA8BD,OAAO,EAAE,aAAa,EAAE,CAAA"}

package/dist/components/ui/stateful-table.js

@@ -0,0 +1,169 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useState } from 'react';
+import { Button } from './button.js';
+import { Checkbox } from './checkbox.js';
+import { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow, } from './table.js';
+import { TableSort } from './table-sort.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A row set that owns its sort, its selection, its column visibility and its page,
+ * and hands all four to the caller as one value.
+ *
+ * **Prism's `table` is presentational and `table-sort` is a header cell, and this
+ * is the thing neither of them is.** `Table` forwards every native table prop and
+ * holds nothing; `TableSort` reports a direction and leaves the reordering to the
+ * caller. Between them is the half every consumer writes again: the row order, which
+ * rows are selected, which columns are on screen and which page is showing, and the
+ * four have to agree with each other after every change. That agreement is the
+ * Component. A caller holding them as four independent props gets a page number that
+ * does not match the sort they have just set, which is a table whose rows are not in
+ * the order its own header claims.
+ *
+ * **One state value rather than four props, for the same reason.** The four are not
+ * independent: which page is showing is a function of the order and the set in every
+ * implementation anyone writes, and four props let a caller hold a contradiction. One
+ * value is also one place to hold it, so a caller can put it in a reducer, in their
+ * store, or in an address query and this Component does not care which. The cost is
+ * that a caller changing one fact spreads the rest, which is one line and is the
+ * price of the four being unable to disagree.
+ *
+ * **It owns the order, and the accessor is how.** This is the one place a Component
+ * in this package decides something about the caller's data, and the refusal to do
+ * it any other way is the design. A column is sortable only when it carries an
+ * `accessor`, so the value sorted on is the caller's and never the cell's text: a
+ * status column that orders `critical, degraded, healthy` and a column of charts that
+ * orders on the number the chart reports are both expressible here, and neither is
+ * guessable from a cell. That is why the column type is a union of a sortable arm and
+ * a plain one rather than two optionals: an optional accessor beside a `sortable`
+ * boolean is a combination that type-checks and then cannot sort anything.
+ *
+ * **Numbers compare as numbers and everything else goes through the platform's own
+ * collator.** The `Intl.Collator` half is not a nicety: a name column ordered with
+ * `<` puts every uppercase name before every lowercase one in half the languages a
+ * product is sold in, and the comparator that fixes that belongs to the platform
+ * rather than to this package. The locale is the runtime's own, which is right on a
+ * server and wrong on a multilingual page, so it is stated here rather than guessed.
+ * `numeric` is on so a column of identifiers orders 2 before 10, which is the one
+ * case a reader always notices.
+ *
+ * **A server-ordered set is the original order, and that is what `sort: null` means.**
+ * A caller with a server-side order hands over rows already in it, and a reader who
+ * sorts and then unsorts gets the caller's order back. The three-state cycle on the
+ * header is `table-sort`'s and it is spent here, in the third state: one route back
+ * to the original, and it is the header they already know.
+ *
+ * **Selection is a set of the caller's keys, and the header's control covers the
+ * page rather than the set.** The two differ whenever the caller pages, and
+ * conflating them is the defect this Component exists to prevent: a "select all"
+ * that selected every row on the server when twenty are on screen acted on four
+ * hundred rows a reader never saw. So the header's checkbox covers the rows on the
+ * current page, it is `indeterminate` when some of them are selected, and the words
+ * are the caller's.
+ *
+ * **Column visibility is the reader's preference and lives beside the columns rather
+ * than inside them.** A column marked hidden in the caller's array would be undone by
+ * every fetch that rebuilds the array, and a caller's columns say which columns exist
+ * rather than which are on screen right now. Nothing is hidden on width alone: a
+ * table with eleven columns on a phone is a hard problem, and pruning columns by
+ * guessing at a width takes away a column the reader needed without telling them,
+ * which is a worse failure than a scroll.
+ *
+ * **The header is a real `<tr>` of `<th scope="col">` cells and the sortable ones are
+ * `TableSort`, composed.** Neither is this Component's decision: a header row of
+ * `div`s is a grid with no column names in it, and a screen reader moving across a
+ * table announces a column rather than a button. `TableSort` carries the direction,
+ * the mark and the announcement, and the caller's `announceSort` is passed straight
+ * through to it, so the sentence a reader hears about a press is the caller's.
+ *
+ * **The pager is drawn only when there is more than one page**, because a pager on a
+ * set of four rows is a row of controls describing a choice the reader does not have.
+ * Its controls are `aria-disabled` rather than natively disabled on the end pages,
+ * for the reason `FormWizard` gives on its back control: a control that leaves the
+ * tab order answers a press with silence.
+ *
+ * **It is a client Component**, because every one of the four changes happens after
+ * the reader acts, and because `state`, `onChange` and the row and column accessors
+ * are functions the caller hands it, which is a client-to-client boundary wherever it
+ * is written. What that costs is the price of every client control: a server
+ * Component may render one page of rows once with the state already in place, and
+ * what it may not do is let the reader change any of the four facts.
+ */
+function StatefulTable({ rows, getRowId, columns, state, onChange, caption, label, announceSort, selectAllLabel, selectRowLabel, columnsLabel, emptyLabel, previousPageLabel, nextPageLabel, pageLabel, pageSize = 10, className, }) {
+    const generated = useId();
+    const [columnsOpen, setColumnsOpen] = useState(false);
+    const columnsId = `${generated}-columns`;
+    const shown = columns.filter((column) => !state.hiddenColumns.includes(column.id));
+    const ordered = state.sort === null ? [...rows] : [...rows].sort(comparator(state.sort, columns));
+    const pages = Math.max(1, Math.ceil(ordered.length / Math.max(1, pageSize)));
+    const page = Math.min(Math.max(Math.trunc(state.page), 0), pages - 1);
+    const visible = ordered.slice(page * pageSize, page * pageSize + pageSize);
+    const selected = new Set(state.selection);
+    const pageKeys = visible.map(getRowId);
+    const everyOnPage = pageKeys.length > 0 && pageKeys.every((key) => selected.has(key));
+    const someOnPage = pageKeys.some((key) => selected.has(key));
+    const move = (next, changed) => onChange({ state: { ...state, ...next }, changed });
+    return (_jsxs("div", { "data-slot": "stateful-table", className: cn('flex w-full flex-col gap-3', className), children: [_jsxs("div", { "data-slot": "stateful-table-toolbar", className: "flex items-center justify-end", children: [_jsx(Button, { "data-slot": "stateful-table-columns-toggle", type: "button", variant: "outline", size: "sm", "aria-expanded": columnsOpen, "aria-controls": columnsId, onClick: () => setColumnsOpen((open) => !open), children: columnsLabel }), _jsx("div", { id: columnsId, "data-slot": "stateful-table-columns", hidden: !columnsOpen, className: "border-border bg-popover text-popover-foreground absolute end-4 mt-9 flex flex-col gap-2 rounded-md border p-3 shadow-md", children: columns.map((column) => (_jsxs("label", { "data-slot": "stateful-table-column-toggle", className: "flex items-center gap-2 text-sm", children: [_jsx(Checkbox, { checked: !state.hiddenColumns.includes(column.id), onCheckedChange: (next) => move({
+                                        hiddenColumns: next
+                                            ? state.hiddenColumns.filter((id) => id !== column.id)
+                                            : [...state.hiddenColumns, column.id],
+                                    }, 'visibility') }), column.header] }, column.id))) })] }), _jsxs(Table, { "data-slot": "stateful-table-frame", "aria-label": label, className: "w-full", children: [caption === undefined ? null : _jsx(TableCaption, { children: caption }), _jsx(TableHeader, { children: _jsxs(TableRow, { children: [_jsx(TableHead, { className: "w-10", children: _jsx(Checkbox, { "data-slot": "stateful-table-select-all", checked: everyOnPage, indeterminate: someOnPage && !everyOnPage, "aria-label": selectAllLabel, onCheckedChange: (next) => move({
+                                            // The page's rows and not the set's. A control that selected
+                                            // every row on the server when twenty are on screen acted on
+                                            // four hundred rows the reader never saw, and that is the defect
+                                            // this Component exists to prevent rather than to ship.
+                                            selection: next
+                                                ? [...new Set([...state.selection, ...pageKeys])]
+                                                : state.selection.filter((key) => !pageKeys.includes(key)),
+                                        }, 'selection') }) }), shown.map((column) => (_jsx(TableHead, { children: column.sortable === true ? (_jsx(TableSort, { column: column.id, direction: state.sort !== null && state.sort.column === column.id
+                                            ? state.sort.direction
+                                            : 'none', onDirectionChange: (direction) => move({
+                                            sort: direction === 'none' ? null : { column: column.id, direction },
+                                            // Back to the first page, because a page number chosen for
+                                            // one order means nothing in another and the reader who
+                                            // changed the order is on a page that may have nothing on
+                                            // it.
+                                            page: 0,
+                                        }, 'sort'), announce: (direction) => announceSort(column.id, direction), children: column.header })) : (column.header) }, column.id)))] }) }), _jsx(TableBody, { children: visible.length === 0 ? (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: shown.length + 1, "data-slot": "stateful-table-empty", children: emptyLabel }) })) : (visible.map((row) => {
+                            const key = getRowId(row);
+                            const isSelected = selected.has(key);
+                            return (_jsxs(TableRow, { "data-slot": "stateful-table-row", "data-selected": isSelected ? 'true' : undefined, "data-state": isSelected ? 'selected' : undefined, className: isSelected ? 'bg-muted' : undefined, children: [_jsx(TableCell, { className: "w-10", children: _jsx(Checkbox, { "data-slot": "stateful-table-select-row", checked: isSelected, "aria-label": selectRowLabel(key), onCheckedChange: (next) => move({
+                                                selection: next
+                                                    ? [...state.selection, key]
+                                                    : state.selection.filter((held) => held !== key),
+                                            }, 'selection') }) }), shown.map((column) => (_jsx(TableCell, { "data-slot": "stateful-table-cell", children: column.cell(row) }, column.id)))] }, key));
+                        })) })] }), pages <= 1 ? null : (_jsxs("nav", { "data-slot": "stateful-table-pager", "aria-label": pageLabel(page, pages), className: "flex items-center justify-end gap-2", children: [_jsx(Button, { "data-slot": "stateful-table-previous", type: "button", variant: "outline", size: "sm", "aria-disabled": page === 0 || undefined, onClick: () => {
+                            if (page === 0)
+                                return;
+                            move({ page: page - 1 }, 'page');
+                        }, children: previousPageLabel }), _jsx("span", { "data-slot": "stateful-table-page", "aria-hidden": "true", className: "text-muted-foreground text-sm tabular-nums", children: pageLabel(page, pages) }), _jsx(Button, { "data-slot": "stateful-table-next", type: "button", variant: "outline", size: "sm", "aria-disabled": page === pages - 1 || undefined, onClick: () => {
+                            if (page === pages - 1)
+                                return;
+                            move({ page: page + 1 }, 'page');
+                        }, children: nextPageLabel })] }))] }));
+}
+/**
+ * The comparator a sort uses, read off the caller's own accessor.
+ *
+ * A column with no accessor returns a comparator that preserves the order, and it is
+ * unreachable rather than defensive: `TableSort` is rendered only in the arm of the
+ * column union that carries one, so the type has already said the accessor is there.
+ * The guard is here because a caller can cast their columns into the union, and a
+ * silently unsorted column is the one failure this Component cannot afford.
+ */
+function comparator({ column, direction }, columns) {
+    const found = columns.find((candidate) => candidate.id === column);
+    const accessor = found?.accessor;
+    if (accessor === undefined)
+        return () => 0;
+    const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+    const sign = direction === 'descending' ? -1 : 1;
+    return (a, b) => {
+        const left = accessor(a);
+        const right = accessor(b);
+        if (typeof left === 'number' && typeof right === 'number')
+            return (left - right) * sign;
+        return collator.compare(String(left), String(right)) * sign;
+    };
+}
+export { StatefulTable };

package/dist/components/ui/status.d.ts

@@ -0,0 +1,99 @@
+import type { ComponentProps, ReactNode } from 'react';
+/**
+ * The five tones a Status's dot can take.
+ *
+ * A tone is a judgement the caller makes, and this Component has the same reason
+ * `MeterTone` gives for holding the same judgement at arm's length: it can see
+ * the state, and it cannot see whether the state is urgent. A Status is asked
+ * for far more often than a Meter is, and for smaller things, which is exactly
+ * the case where a Component that coloured itself would be making a claim about
+ * the caller's product with the least evidence. A deploy is `info` on a status
+ * page and `success` in a release note; a disk is `warning` at 80 percent and
+ * `destructive` at 95, and the number does not know which of the two the
+ * consumer is looking at.
+ *
+ * **The set is the semantic contract's, and the JSDoc has to say what that
+ * costs.** The contract publishes three state roles, `success`, `warning` and
+ * `destructive`, and it publishes no informational one, so `info` here borrows
+ * `brand-ink`, which is the only cool role in the contract that means "not an
+ * alarm". The cost is named rather than hidden: in a pack whose brand hue is also
+ * its emphasis hue, an `info` dot and an emphasised mark are the same colour. The
+ * alternative was a fourth state role in the token contract, which is a
+ * decision about the tokens rather than about a Component, and a Component that
+ * invented the role would have had a second source of truth for colour. The
+ * other alternative, dropping `info` from the set, would have made the ordinary
+ * states of a product, in progress, scheduled, degraded, unreachable, expressible
+ * only as `neutral` and `warning`, which are both wrong.
+ *
+ * `neutral` is the tone for a state with nothing to alarm about, and it is drawn
+ * in the muted foreground rather than the full ink. A dot in the foreground
+ * colour reads as an emphasis mark rather than as a state, and a row of neutral
+ * states is a row of things the reader should look at.
+ */
+export type StatusTone = 'neutral' | 'info' | 'success' | 'warning' | 'destructive';
+/**
+ * A dot in one of five tones, and the caller's words beside it.
+ *
+ * **The dot is the tone and the label is the caller's.** The split is the whole
+ * design. A Component that knew what the words were would be a Component making
+ * a claim about a product it knows nothing about, so it takes the tone and the
+ * caller takes the sentence, and neither one can be derived from the other
+ * without a lie.
+ *
+ * **The label is required, and the reason is the colour.** A status with no words
+ * is a coloured dot, and a coloured dot is invisible to a reader who cannot
+ * separate the tones and unreadable to a screen reader whatever the tones are.
+ * There is a Component for the other half of that idea, an indicator that is
+ * decorative beside a state the surrounding sentence already names, and it is a
+ * different Item because a name it did not receive is a name the consumer has to
+ * supply. This one refuses to render unlabelled rather than rendering something
+ * every consumer inherits.
+ *
+ * **The tone is required rather than defaulted.** There is no `neutral` default
+ * for the same reason `MeterTone` states, and this Component inherits that
+ * argument in full: a tone is a judgement about urgency that only the caller can
+ * make, and a Component that picked one would be picking it for four products at
+ * once. A default here is the quietest way to ship a claim, because it looks
+ * like a convenience and behaves like an opinion.
+ *
+ * **The tone is never the only signal.** Every dot here is `aria-hidden` and the
+ * label carries the meaning, so a reader who cannot separate `warning` from
+ * `destructive` still reads which is which. That is also why the tone list can
+ * stay as small as it is: a wider list would be a wider set of colours a reader
+ * has to learn and a maintainer has to keep true, and the words are what make
+ * each one legible. The cost is stated rather than hidden: `warning` is amber and
+ * measures about 2.1:1 against the default pack's light background, so on a light
+ * surface that one dot is a tint rather than a mark. The label beside it is what
+ * carries the state, which is the trade this design makes everywhere.
+ *
+ * It is a server Component: no hook, no state, and a status that changes is
+ * something the surrounding surface re-renders, not something this Component
+ * animates.
+ */
+declare function Status({ className, tone, label, size, ...props }: {
+    /**
+     * Which of the five tones the dot takes. Required rather than defaulted, for
+     * the reason `StatusTone` states in full.
+     */
+    tone: StatusTone;
+    /**
+     * The words naming the state, in the product's own vocabulary.
+     *
+     * Required, and deliberately not derived from `tone`: a product that says
+     * "Degraded" and a product that says "Partially unavailable" are both
+     * describing the same tone, and neither word is Prism's to choose.
+     */
+    label: ReactNode;
+    /**
+     * The size of the dot and of the label together. @defaultValue 'md'
+     *
+     * Two steps and not one, because a status appears at two scales in practice: in
+     * a dense table row, where a `md` dot competes with the numbers beside it, and
+     * beside a heading, where `sm` is hard to find. Sizing the pair together is
+     * deliberate, because a small dot beside a large label is a status the reader
+     * is meant to read rather than one they are meant to spot.
+     */
+    size?: 'sm' | 'md';
+} & Omit<ComponentProps<'span'>, 'children'>): import("react").JSX.Element;
+export { Status };
+//# sourceMappingURL=status.d.ts.map

package/dist/components/ui/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/components/ui/status.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;AAuBnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,IAAI,EACJ,KAAK,EACL,IAAW,EACX,GAAG,KAAK,EACT,EAAE;IACD;;;OAGG;IACH,IAAI,EAAE,UAAU,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;CACnB,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,+BAiB3C;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}