@sincpro/web-ui 1.6.0 → 1.7.1

package/dist/primitives/table/EditableTable.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useUiCopy } from "../../foundations/copy.js";
 import { byDensity, useDensity } from "../../foundations/density.js";
-import { ControlStateContext } from "../../foundations/form.js";
+import { ControlStateContext, FieldBoundary } from "../../foundations/form.js";
 import { pathKey, pileIsOpen, pileItems, pilesOf, } from "../../foundations/grouping.js";
 import { HANDHELD_WIDTH } from "../../foundations/layout.js";
 import { stickyTop, useScrollBox } from "../../foundations/sticky.js";
@@ -816,106 +816,109 @@ groupTotal, height, layout = "auto", onOpen, onDiscard, bands, adds, flag, onReo
                         return null;
                     return (_jsxs("div", { className: "flex items-baseline justify-between gap-3 text-meta", children: [_jsx("dt", { className: "text-muted", children: c.header }), _jsx("dd", { className: "font-semibold text-ink tabular-nums", children: total })] }, c.id));
                 }) }))] }));
-    return (_jsxs("div", { ref: frame, className: "min-w-0", children: [_jsx("div", { ref: box.ref, tabIndex: box.tabIndex, className: `min-w-0 focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary ${box.className}`, style: box.style, children: stacked ? (list) : (_jsxs("table", { className: "w-full border-separate border-spacing-0 px-1 text-left", ...(view.on
-                        ? { "aria-rowcount": 1 + drawn.length + (totals === undefined ? 0 : 1) }
-                        : {}), children: [_jsx("thead", { className: "sticky z-10 bg-ground", style: stickyTop, children: _jsxs("tr", { ...(view.on ? { "aria-rowindex": 1 } : {}), children: [reorderable ? _jsx("td", { className: "w-0 border-b border-line-strong" }) : null, columns.map((c) => c.header === "" ? (_jsx("td", { className: "w-0 border-b border-line-strong" }, c.id)) : (_jsx("th", { scope: "col", style: c.width === undefined ? undefined : { width: c.width }, 
-                                        /* A column of figures takes its figures' width (`w-0` in an auto
-                                           table is «as narrow as its content») and the text takes the rest:
-                                           the product name was cut while «Cantidad» had room for ten digits. */
-                                        className: `border-b border-line-strong ${HEADER_TEXT} ${cell} ${c.numeric === true ? "text-right" : "text-left"} ${c.numeric === true && c.width === undefined ? "w-0" : ""}`, children: c.header }, c.id))), onRemove === undefined ? null : (_jsx("td", { className: "w-0 border-b border-line-strong" }))] }) }), _jsxs("tbody", { ref: view.body.ref, ...(reorderable
-                                ? {
-                                    onDragOver: overRow,
-                                    onDrop: (event) => {
-                                        event.preventDefault();
-                                        if (dragged.current !== null && landing !== undefined)
-                                            land(dragged.current, landing);
-                                        dragged.current = null;
-                                        setLanding(undefined);
-                                    },
-                                }
-                                : {}), children: [rows.length === 0 ? (_jsx("tr", { children: _jsx("td", { colSpan: columns.length +
-                                            (onRemove === undefined ? 0 : 1) +
-                                            (reorderable ? 1 : 0), className: `text-meta text-muted italic ${cell}`, children: emptyText }) })) : (view.rows.flatMap((slot, at) => {
-                                    const entry = drawn[slot.index];
-                                    if (entry === undefined)
-                                        return [];
-                                    const windowed = view.windowed(slot.index);
-                                    /* What is not drawn is a spacer of its height: the rows above the window
-                                       before the first, and the gap before a row kept only because it holds
-                                       the focus. */
-                                    const gap = view.pad(at === 0 ? 0 : view.rows[at - 1].end, slot.start, width, `gap:${slot.index}`);
-                                    if (entry.pile !== undefined) {
-                                        const pile = entry.pile;
-                                        const inside = pile.piles.length === 0 ? pile.items : pileItems(pile.piles);
-                                        return [
-                                            gap,
-                                            /* La banda respeta la cuadrícula: el rótulo en la primera
-                                             columna y cada total bajo la suya. Un total en un rincón
-                                             obliga a buscar de qué columna es; alineado no hay nada que
-                                             buscar. */
-                                            _jsxs("tr", { ...windowed, children: [reorderable ? _jsx("td", { className: "w-0 bg-ground" }) : null, columns.map((c, ci) => (_jsx("td", { className: `bg-ground text-meta ${cell} ${c.numeric === true ? "text-right tabular-nums" : ""}`, style: ci === 0 && pile.depth > 0
-                                                            ? {
-                                                                paddingLeft: `calc(var(--spacing-indent) * ${pile.depth} + 0.625rem)`,
-                                                            }
-                                                            : undefined, children: ci === 0
-                                                            ? pileTag(pile, copy.locale)
-                                                            : (groupTotal?.(c, inside) ?? null) }, c.id))), onRemove === undefined ? null : _jsx("td", { className: "w-0 bg-ground" })] }, `pile:${pathKey(pile.path)}`),
-                                        ];
+    return (
+    /* A collection is many controls, each named by its column: no enclosing `Field`
+       reaches inside (see `FieldBoundary`). */
+    _jsx(FieldBoundary, { children: _jsxs("div", { ref: frame, className: "min-w-0", children: [_jsx("div", { ref: box.ref, tabIndex: box.tabIndex, className: `min-w-0 focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary ${box.className}`, style: box.style, children: stacked ? (list) : (_jsxs("table", { className: "w-full border-separate border-spacing-0 px-1 text-left", ...(view.on
+                            ? { "aria-rowcount": 1 + drawn.length + (totals === undefined ? 0 : 1) }
+                            : {}), children: [_jsx("thead", { className: "sticky z-10 bg-ground", style: stickyTop, children: _jsxs("tr", { ...(view.on ? { "aria-rowindex": 1 } : {}), children: [reorderable ? _jsx("td", { className: "w-0 border-b border-line-strong" }) : null, columns.map((c) => c.header === "" ? (_jsx("td", { className: "w-0 border-b border-line-strong" }, c.id)) : (_jsx("th", { scope: "col", style: c.width === undefined ? undefined : { width: c.width }, 
+                                            /* A column of figures takes its figures' width (`w-0` in an auto
+                                             table is «as narrow as its content») and the text takes the rest:
+                                             the product name was cut while «Cantidad» had room for ten digits. */
+                                            className: `border-b border-line-strong ${HEADER_TEXT} ${cell} ${c.numeric === true ? "text-right" : "text-left"} ${c.numeric === true && c.width === undefined ? "w-0" : ""}`, children: c.header }, c.id))), onRemove === undefined ? null : (_jsx("td", { className: "w-0 border-b border-line-strong" }))] }) }), _jsxs("tbody", { ref: view.body.ref, ...(reorderable
+                                    ? {
+                                        onDragOver: overRow,
+                                        onDrop: (event) => {
+                                            event.preventDefault();
+                                            if (dragged.current !== null && landing !== undefined)
+                                                land(dragged.current, landing);
+                                            dragged.current = null;
+                                            setLanding(undefined);
+                                        },
                                     }
-                                    const row = entry.row;
-                                    const id = getRowId(row);
-                                    const isEditing = editing === id;
-                                    const band = bandOf(row);
-                                    if (band !== null) {
-                                        const { span, figures } = bandFigures(row);
-                                        const bandWash = isEditing
-                                            ? "bg-primary/5"
-                                            : band === "section"
-                                                ? "bg-ground group-hover/row:bg-ink/6"
-                                                : "group-hover/row:bg-ink/4";
-                                        const bandMark = `border-b border-line first:rounded-l-control last:rounded-r-control ${bandWash}`;
-                                        const control = isEditing && editable && bands?.edit !== undefined;
+                                    : {}), children: [rows.length === 0 ? (_jsx("tr", { children: _jsx("td", { colSpan: columns.length +
+                                                (onRemove === undefined ? 0 : 1) +
+                                                (reorderable ? 1 : 0), className: `text-meta text-muted italic ${cell}`, children: emptyText }) })) : (view.rows.flatMap((slot, at) => {
+                                        const entry = drawn[slot.index];
+                                        if (entry === undefined)
+                                            return [];
+                                        const windowed = view.windowed(slot.index);
+                                        /* What is not drawn is a spacer of its height: the rows above the window
+                                         before the first, and the gap before a row kept only because it holds
+                                         the focus. */
+                                        const gap = view.pad(at === 0 ? 0 : view.rows[at - 1].end, slot.start, width, `gap:${slot.index}`);
+                                        if (entry.pile !== undefined) {
+                                            const pile = entry.pile;
+                                            const inside = pile.piles.length === 0 ? pile.items : pileItems(pile.piles);
+                                            return [
+                                                gap,
+                                                /* La banda respeta la cuadrícula: el rótulo en la primera
+                                               columna y cada total bajo la suya. Un total en un rincón
+                                               obliga a buscar de qué columna es; alineado no hay nada que
+                                               buscar. */
+                                                _jsxs("tr", { ...windowed, children: [reorderable ? _jsx("td", { className: "w-0 bg-ground" }) : null, columns.map((c, ci) => (_jsx("td", { className: `bg-ground text-meta ${cell} ${c.numeric === true ? "text-right tabular-nums" : ""}`, style: ci === 0 && pile.depth > 0
+                                                                ? {
+                                                                    paddingLeft: `calc(var(--spacing-indent) * ${pile.depth} + 0.625rem)`,
+                                                                }
+                                                                : undefined, children: ci === 0
+                                                                ? pileTag(pile, copy.locale)
+                                                                : (groupTotal?.(c, inside) ?? null) }, c.id))), onRemove === undefined ? null : _jsx("td", { className: "w-0 bg-ground" })] }, `pile:${pathKey(pile.path)}`),
+                                            ];
+                                        }
+                                        const row = entry.row;
+                                        const id = getRowId(row);
+                                        const isEditing = editing === id;
+                                        const band = bandOf(row);
+                                        if (band !== null) {
+                                            const { span, figures } = bandFigures(row);
+                                            const bandWash = isEditing
+                                                ? "bg-primary/5"
+                                                : band === "section"
+                                                    ? "bg-ground group-hover/row:bg-ink/6"
+                                                    : "group-hover/row:bg-ink/4";
+                                            const bandMark = `border-b border-line first:rounded-l-control last:rounded-r-control ${bandWash}`;
+                                            const control = isEditing && editable && bands?.edit !== undefined;
+                                            return [
+                                                gap,
+                                                _jsxs(EditRow, { as: "tr", ...rowWiring(id, row), windowed: windowed, className: `group/row ${editable ? RING : ""} ${editable && !isEditing ? "cursor-text" : ""}`, children: [reorderable ? grip(id, bandMark) : null, _jsx("td", { colSpan: span, ...(control ? { "data-edit": "" } : {}), className: `text-meta ${bandMark} ${lineOver(id)} ${cell} ${band === "section"
+                                                                ? "font-semibold text-ink"
+                                                                : "text-muted italic"}`, children: control ? bands?.edit?.(row, setter(id)) : bands?.render(row) }), columns.slice(span).map((c, i) => (_jsx("td", { className: `text-meta text-ink ${bandMark} ${cell} ${c.numeric === true
+                                                                ? "text-right font-semibold tabular-nums"
+                                                                : ""}`, children: figures[span + i] ?? null }, c.id))), onRemove === undefined ? null : (_jsx("td", { className: `w-0 py-1 pr-2 pl-1 align-middle ${bandMark}`, children: _jsx("span", { className: "flex opacity-0 transition-opacity duration-(--duration-instant) group-hover/row:opacity-100 group-focus-visible/row:opacity-100 focus-within:opacity-100", onClick: (e) => e.stopPropagation(), children: _jsx(IconButton, { icon: Trash2, label: copy.editable.remove, size: "sm", tone: "danger", ...(editable && stop !== id ? { tabIndex: -1 } : {}), onClick: () => onRemove(id) }) }) }))] }, id),
+                                            ];
+                                        }
+                                        /* The wash lives on the cells. A background on the row paints
+                                       edge to edge, and `border-collapse` would ignore a radius. */
+                                        const wash = isEditing ? "bg-primary/5" : "group-hover/row:bg-ink/4";
+                                        const mark = `border-b border-line first:rounded-l-control last:rounded-r-control ${wash}`;
+                                        const set = setter(id);
                                         return [
                                             gap,
-                                            _jsxs(EditRow, { as: "tr", ...rowWiring(id, row), windowed: windowed, className: `group/row ${editable ? RING : ""} ${editable && !isEditing ? "cursor-text" : ""}`, children: [reorderable ? grip(id, bandMark) : null, _jsx("td", { colSpan: span, ...(control ? { "data-edit": "" } : {}), className: `text-meta ${bandMark} ${lineOver(id)} ${cell} ${band === "section"
-                                                            ? "font-semibold text-ink"
-                                                            : "text-muted italic"}`, children: control ? bands?.edit?.(row, setter(id)) : bands?.render(row) }), columns.slice(span).map((c, i) => (_jsx("td", { className: `text-meta text-ink ${bandMark} ${cell} ${c.numeric === true
-                                                            ? "text-right font-semibold tabular-nums"
-                                                            : ""}`, children: figures[span + i] ?? null }, c.id))), onRemove === undefined ? null : (_jsx("td", { className: `w-0 py-1 pr-2 pl-1 align-middle ${bandMark}`, children: _jsx("span", { className: "flex opacity-0 transition-opacity duration-(--duration-instant) group-hover/row:opacity-100 group-focus-visible/row:opacity-100 focus-within:opacity-100", onClick: (e) => e.stopPropagation(), children: _jsx(IconButton, { icon: Trash2, label: copy.editable.remove, size: "sm", tone: "danger", ...(editable && stop !== id ? { tabIndex: -1 } : {}), onClick: () => onRemove(id) }) }) }))] }, id),
+                                            _jsxs(EditRow, { as: "tr", ...rowWiring(id, row), windowed: windowed, 
+                                                /* The focus ring is drawn on the row, inset, so it is not cut by
+                                               the box and does not move the cells. */
+                                                className: `group/row ${editable ? RING : ""} ${editable && !isEditing && !locked(row) ? "cursor-text" : ""}`, children: [reorderable ? grip(id, mark) : null, columns.map((c, ci) => {
+                                                        const state = stateOf(row, c);
+                                                        const control = isEditing && writes(row, c, state);
+                                                        /* Not `mark`: that name is the row's border and wash, above. Shadowed,
+                                                         the cells were drawn with the class «null» — no hairline, no hover. */
+                                                        const flagged = ci === 0 ? flagOf(row, true) : null;
+                                                        const cellFlag = cellFlagOf(row, c, state, true);
+                                                        const value = state?.hidden === true
+                                                            ? null
+                                                            : control
+                                                                ? controlOf(row, c, state, set)
+                                                                : c.render(row);
+                                                        return (_jsxs("td", { ...(control ? { "data-edit": "" } : {}), className: `text-meta text-ink ${mark} ${lineOver(id)} ${cell} ${c.numeric === true ? "text-right tabular-nums" : ""}`, children: [flagged === null && cellFlag === null ? (value) : (_jsxs("span", { className: "flex min-w-0 items-start gap-1.5", children: [flagged, cellFlag, _jsx("span", { className: "min-w-0 flex-1", children: value })] })), errorOf(row, c, state)] }, c.id));
+                                                    }), onRemove === undefined ? null : (_jsx("td", { className: `w-0 py-1 pr-2 pl-1 align-middle ${mark}`, children: _jsx("span", { className: "flex opacity-0 transition-opacity duration-(--duration-instant) group-hover/row:opacity-100 group-focus-visible/row:opacity-100 focus-within:opacity-100", onClick: (e) => e.stopPropagation(), children: _jsx(IconButton, { icon: Trash2, label: copy.editable.remove, size: "sm", tone: "danger", ...(editable && stop !== id ? { tabIndex: -1 } : {}), onClick: () => onRemove(id) }) }) }))] }, id),
                                         ];
-                                    }
-                                    /* The wash lives on the cells. A background on the row paints
-                                     edge to edge, and `border-collapse` would ignore a radius. */
-                                    const wash = isEditing ? "bg-primary/5" : "group-hover/row:bg-ink/4";
-                                    const mark = `border-b border-line first:rounded-l-control last:rounded-r-control ${wash}`;
-                                    const set = setter(id);
-                                    return [
-                                        gap,
-                                        _jsxs(EditRow, { as: "tr", ...rowWiring(id, row), windowed: windowed, 
-                                            /* The focus ring is drawn on the row, inset, so it is not cut by
-                                             the box and does not move the cells. */
-                                            className: `group/row ${editable ? RING : ""} ${editable && !isEditing && !locked(row) ? "cursor-text" : ""}`, children: [reorderable ? grip(id, mark) : null, columns.map((c, ci) => {
-                                                    const state = stateOf(row, c);
-                                                    const control = isEditing && writes(row, c, state);
-                                                    /* Not `mark`: that name is the row's border and wash, above. Shadowed,
-                                                       the cells were drawn with the class «null» — no hairline, no hover. */
-                                                    const flagged = ci === 0 ? flagOf(row, true) : null;
-                                                    const cellFlag = cellFlagOf(row, c, state, true);
-                                                    const value = state?.hidden === true
-                                                        ? null
-                                                        : control
-                                                            ? controlOf(row, c, state, set)
-                                                            : c.render(row);
-                                                    return (_jsxs("td", { ...(control ? { "data-edit": "" } : {}), className: `text-meta text-ink ${mark} ${lineOver(id)} ${cell} ${c.numeric === true ? "text-right tabular-nums" : ""}`, children: [flagged === null && cellFlag === null ? (value) : (_jsxs("span", { className: "flex min-w-0 items-start gap-1.5", children: [flagged, cellFlag, _jsx("span", { className: "min-w-0 flex-1", children: value })] })), errorOf(row, c, state)] }, c.id));
-                                                }), onRemove === undefined ? null : (_jsx("td", { className: `w-0 py-1 pr-2 pl-1 align-middle ${mark}`, children: _jsx("span", { className: "flex opacity-0 transition-opacity duration-(--duration-instant) group-hover/row:opacity-100 group-focus-visible/row:opacity-100 focus-within:opacity-100", onClick: (e) => e.stopPropagation(), children: _jsx(IconButton, { icon: Trash2, label: copy.editable.remove, size: "sm", tone: "danger", ...(editable && stop !== id ? { tabIndex: -1 } : {}), onClick: () => onRemove(id) }) }) }))] }, id),
-                                    ];
-                                })), rows.length === 0 ? null : view.tail(width)] }), totals === undefined ? null : (_jsx("tfoot", { children: _jsxs("tr", { children: [reorderable ? _jsx("td", { className: "border-t border-line-strong" }) : null, columns.map((c, i) => (_jsx("td", { className: `border-t border-line-strong text-meta font-semibold text-ink ${cell} ${c.numeric === true ? "text-right tabular-nums" : ""}`, children: totals[i] ?? null }, c.id))), onRemove === undefined ? null : (_jsx("td", { className: "border-t border-line-strong" }))] }) }))] })) }), onAdd === undefined && (adds === undefined || adds.length === 0) ? null : (
-            /* The «add» goes under the grid, as text, not as a button away from it:
-               what is about to happen is that one more row shows up right here.
-               The hover is the same inset mark as a row: the shell lines the label
-               up with the cells, and the button itself is the rounded wash. It sits
-               outside the scroll box, so a table with its own height keeps it in view.
-               A section and a note sit beside it, quieter: the line is what is added
-               most, so it keeps the lead and the whole free width. */
-            _jsxs("div", { className: "flex flex-wrap items-center gap-x-1 px-1 py-0.5", children: [onAdd === undefined ? null : (_jsxs("button", { ref: addButton, type: "button", onClick: () => add(), className: `flex items-center gap-1.5 rounded-control text-left text-meta text-primary transition-colors duration-(--duration-instant) hover:bg-primary/5 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-primary ${adds === undefined || adds.length === 0 ? "w-full" : ""} ${byDensity(d, "px-3 py-1", "px-2 py-0.5")}`, children: [_jsx(Plus, { className: "size-(--size-icon-sm)", strokeWidth: 2.5, "aria-hidden": true }), addText] })), (adds ?? []).map((extra) => (_jsx("button", { type: "button", onClick: () => add(extra.onAdd), className: `rounded-control text-left text-meta text-muted transition-colors duration-(--duration-instant) hover:bg-primary/5 hover:text-primary focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-primary ${byDensity(d, "px-3 py-1", "px-2 py-0.5")}`, children: extra.label }, extra.label)))] }))] }));
+                                    })), rows.length === 0 ? null : view.tail(width)] }), totals === undefined ? null : (_jsx("tfoot", { children: _jsxs("tr", { children: [reorderable ? _jsx("td", { className: "border-t border-line-strong" }) : null, columns.map((c, i) => (_jsx("td", { className: `border-t border-line-strong text-meta font-semibold text-ink ${cell} ${c.numeric === true ? "text-right tabular-nums" : ""}`, children: totals[i] ?? null }, c.id))), onRemove === undefined ? null : (_jsx("td", { className: "border-t border-line-strong" }))] }) }))] })) }), onAdd === undefined && (adds === undefined || adds.length === 0) ? null : (
+                /* The «add» goes under the grid, as text, not as a button away from it:
+                 what is about to happen is that one more row shows up right here.
+                 The hover is the same inset mark as a row: the shell lines the label
+                 up with the cells, and the button itself is the rounded wash. It sits
+                 outside the scroll box, so a table with its own height keeps it in view.
+                 A section and a note sit beside it, quieter: the line is what is added
+                 most, so it keeps the lead and the whole free width. */
+                _jsxs("div", { className: "flex flex-wrap items-center gap-x-1 px-1 py-0.5", children: [onAdd === undefined ? null : (_jsxs("button", { ref: addButton, type: "button", onClick: () => add(), className: `flex items-center gap-1.5 rounded-control text-left text-meta text-primary transition-colors duration-(--duration-instant) hover:bg-primary/5 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-primary ${adds === undefined || adds.length === 0 ? "w-full" : ""} ${byDensity(d, "px-3 py-1", "px-2 py-0.5")}`, children: [_jsx(Plus, { className: "size-(--size-icon-sm)", strokeWidth: 2.5, "aria-hidden": true }), addText] })), (adds ?? []).map((extra) => (_jsx("button", { type: "button", onClick: () => add(extra.onAdd), className: `rounded-control text-left text-meta text-muted transition-colors duration-(--duration-instant) hover:bg-primary/5 hover:text-primary focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-primary ${byDensity(d, "px-3 py-1", "px-2 py-0.5")}`, children: extra.label }, extra.label)))] }))] }) }));
 }

package/dist/primitives/table/Table.d.ts

@@ -1,11 +1,7 @@
 import type { Tone } from "../../foundations/types.js";
 import type { WindowedRow } from "./rowWindow.js";
+import { type SortState } from "./sorting.js";
 import { type ReactNode } from "react";
-export type SortDirection = "asc" | "desc";
-export interface SortState {
-    key: string;
-    direction: SortDirection;
-}
 export declare function Table({ children, 
 /** With a height, the table scrolls on its own and the header sticks.
  *  Without a height, the page scrolls and the header goes away. */
@@ -29,14 +25,15 @@ export declare function THead({ children, rowIndex, }: {
 }): import("react").JSX.Element;
 /** A column. If it gets a `sortKey`, it can be sorted.
  *
- *  The icon is ALWAYS there, dimmed when the column is not the sorted one: an
+ *  The icon is ALWAYS there, dimmed when the column is not sorted: an
  *  indicator that only shows up once you sort does not say which columns are
  *  sortable, and then you have to try them one by one. */
 export declare function Th({ children, sortKey, sort, onSort, numeric, align, width, }: {
     children: ReactNode;
     sortKey?: string;
-    sort?: SortState | null;
-    onSort?: (next: SortState | null) => void;
+    /** The order of the set, outermost first. Empty is «as they came». */
+    sort?: readonly SortState[];
+    onSort?: (next: SortState[]) => void;
     /** Numbers align to the right: that is what lets you compare orders of
      *  magnitude without reading the figures. */
     numeric?: boolean;

package/dist/primitives/table/Table.js

@@ -1,8 +1,46 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
 import { stickyTop, useScrollBox } from "../../foundations/sticky.js";
+import { pressSort, sortPosition, } from "./sorting.js";
 import { ArrowDown, ArrowUp, ChevronRight, ChevronsUpDown } from "lucide-react";
 import { createContext, useContext, useId } from "react";
+/* ==================================================================== *
+ *  TABLE — the way this product shows N records.
+ *
+ *  Dense, but readable, and a single split is what makes that possible:
+ *
+ *      the header in PROPORTIONAL        is a word
+ *      a number in TABULAR FIGURES       is a value that lines up with the one below
+ *
+ *  That is what makes a table readable at a glance: the eye tells the frame
+ *  apart from the content without reading either of them. Everything in mono
+ *  —which is where this product came from— turned the header into just another
+ *  row of data, and the whole report into a terminal. Mono is now for codes
+ *  only, and only when a cell asks for it.
+ *
+ *  ── Three sort states, not two ──────────────────────────────────────
+ *
+ *  Ascending, descending and **unsorted**. The third one is not a luxury: the
+ *  natural order of a delivery queue is the order they arrived in, and a table that
+ *  only toggles asc/desc has no way back to it. Losing the original order and
+ *  not being able to get it back is the number one complaint about any
+ *  sortable table.
+ *
+ *  ── And more than one column ────────────────────────────────────────
+ *
+ *  Shift+click adds the column as a TIE-BREAKER instead of replacing the order:
+ *  «by date, then by customer». Each sorted header then carries its place (1,
+ *  2, 3) next to the arrow, because two arrows alone do not say which one
+ *  decides. The model is in `sorting.ts`.
+ *
+ *  ── The header stays pinned ─────────────────────────────────────────
+ *
+ *  It is the difference between a long table you can read and one where, by
+ *  row forty, nobody knows which column they are looking at any more. It needs
+ *  the box to have a height: without `height` there is no scroll of its own
+ *  and nothing to stick to.
+ * ==================================================================== */
 export function Table({ children, 
 /** With a height, the table scrolls on its own and the header sticks.
  *  Without a height, the page scrolls and the header goes away. */
@@ -28,25 +66,35 @@ export function THead({ children, rowIndex, }) {
 }
 /** A column. If it gets a `sortKey`, it can be sorted.
  *
- *  The icon is ALWAYS there, dimmed when the column is not the sorted one: an
+ *  The icon is ALWAYS there, dimmed when the column is not sorted: an
  *  indicator that only shows up once you sort does not say which columns are
  *  sortable, and then you have to try them one by one. */
 export function Th({ children, sortKey, sort, onSort, numeric = false, align, width, }) {
-    const active = sortKey !== undefined && sort?.key === sortKey;
-    const dir = active ? sort.direction : undefined;
-    function nextSort() {
-        if (sortKey === undefined || onSort === undefined)
-            return;
-        // asc → desc → unsorted. The third click puts the table back the way it was.
-        if (!active)
-            onSort({ key: sortKey, direction: "asc" });
-        else if (dir === "asc")
-            onSort({ key: sortKey, direction: "desc" });
-        else
-            onSort(null);
-    }
+    const copy = useUiCopy();
+    const at = sortKey === undefined ? null : sortPosition(sort, sortKey);
+    const dir = at?.direction;
+    /* The place is drawn only when there is more than one criterion: «1» alone says nothing
+       the arrow did not. */
+    const ranked = at !== null && (sort?.length ?? 0) > 1;
+    const right = (align ?? (numeric ? "right" : "left")) === "right";
     const Icon = dir === "asc" ? ArrowUp : dir === "desc" ? ArrowDown : ChevronsUpDown;
-    return (_jsx("th", { scope: "col", style: width === undefined ? undefined : { width }, "aria-sort": active ? (dir === "asc" ? "ascending" : "descending") : "none", className: `border-b border-line-strong px-3 py-2 ${HEADER_TEXT} ${(align ?? (numeric ? "right" : "left")) === "right" ? "text-right" : "text-left"}`, children: sortKey === undefined ? (children) : (_jsxs("button", { type: "button", onClick: nextSort, className: `inline-flex items-center gap-1 rounded-control transition-colors duration-(--duration-instant) hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary ${(align ?? (numeric ? "right" : "left")) === "right" ? "flex-row-reverse" : ""} ${active ? "text-ink" : ""}`, children: [children, _jsx(Icon, { className: `size-(--size-icon-sm) shrink-0 ${active ? "text-primary" : "text-line-strong"}`, strokeWidth: 2, "aria-hidden": true })] })) }));
+    return (_jsx("th", { scope: "col", style: width === undefined ? undefined : { width }, "aria-sort": sortKey === undefined
+            ? undefined
+            : at === null
+                ? "none"
+                : at.index > 0
+                    ? undefined
+                    : dir === "asc"
+                        ? "ascending"
+                        : "descending", className: `border-b border-line-strong px-3 py-2 ${HEADER_TEXT} ${right ? "text-right" : "text-left"}`, children: sortKey === undefined ? (children) : (_jsxs("button", { type: "button", title: copy.sorting.addHint, 
+            /* Shift+click selects the header's text in some browsers before the click lands. */
+            onMouseDown: (event) => {
+                if (event.shiftKey)
+                    event.preventDefault();
+            }, onClick: (event) => onSort?.(pressSort(sort ?? [], sortKey, event.shiftKey)), className: `inline-flex items-center gap-1 rounded-control transition-colors duration-(--duration-instant) select-none hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary ${right ? "flex-row-reverse" : ""} ${at === null ? "" : "text-ink"}`, children: [children, _jsxs("span", { className: "inline-flex shrink-0 items-center gap-px", children: [_jsx(Icon, { className: `size-(--size-icon-sm) shrink-0 ${at === null ? "text-line-strong" : "text-primary"}`, strokeWidth: 2, "aria-hidden": true }), ranked ? (_jsx("span", { "aria-hidden": true, className: "text-micro text-primary tabular-nums", children: at.index + 1 })) : null] }), ranked ? (_jsx("span", { className: "sr-only", children: fillCopy(copy.sorting.place, {
+                        place: String(at.index + 1),
+                        direction: dir === "asc" ? copy.sorting.asc : copy.sorting.desc,
+                    }) })) : null] })) }));
 }
 /** The wash of a row lives on the cells, not on the `<tr>`. A background on the
  *  row paints edge to edge; on the cells the ends can round and the table's

package/dist/primitives/table/index.d.ts

@@ -5,4 +5,5 @@ export { PivotTable, type PivotTableProps, } from "./PivotTable.js";
 export { type ReportColumn, type ReportRow, type ReportRowKind, ReportTable, } from "./ReportTable.js";
 export { type RowAction, RowActions } from "./RowActions.js";
 export { type SheetColumn, SheetTable } from "./SheetTable.js";
-export { CELL_TONE, type SortDirection, type SortState, Table, Td, Th, THead, Tr, } from "./Table.js";
+export { compareBy, flipSort, moveSort, pressSort, type SortDirection, sortPosition, type SortState, } from "./sorting.js";
+export { CELL_TONE, Table, Td, Th, THead, Tr } from "./Table.js";

package/dist/primitives/table/index.js

@@ -7,4 +7,5 @@ export { PivotTable, } from "./PivotTable.js";
 export { ReportTable, } from "./ReportTable.js";
 export { RowActions } from "./RowActions.js";
 export { SheetTable } from "./SheetTable.js";
-export { CELL_TONE, Table, Td, Th, THead, Tr, } from "./Table.js";
+export { compareBy, flipSort, moveSort, pressSort, sortPosition, } from "./sorting.js";
+export { CELL_TONE, Table, Td, Th, THead, Tr } from "./Table.js";

package/dist/primitives/table/sorting.d.ts

@@ -0,0 +1,42 @@
+export type SortDirection = "asc" | "desc";
+/** One criterion: a field and its direction. */
+export interface SortState {
+    key: string;
+    direction: SortDirection;
+}
+/** Where a column stands in the order: its place (0 = the primary) and direction. */
+export declare function sortPosition(sort: readonly SortState[] | undefined, key: string): {
+    index: number;
+    direction: SortDirection;
+} | null;
+/**
+ * What a press on a column header does to the order.
+ *
+ * Plain press — the column ALONE:
+ *   - the only criterion: asc → desc → nothing. The third press gives the
+ *     natural order back (see `Table.tsx`).
+ *   - with others around it: the column alone, flipped if it was there, and
+ *     never «nothing» — a press that also wipes the tie-breakers someone built
+ *     in the panel would be a surprise, not a shortcut.
+ *
+ * `additive` (Shift) — one more tie-breaker, the others untouched:
+ *   - absent: appended, ascending.
+ *   - ascending: flipped in its place.
+ *   - descending: taken out.
+ */
+export declare function pressSort(sort: readonly SortState[], key: string, additive: boolean): SortState[];
+/** The criterion at `index` with its direction flipped. */
+export declare function flipSort(sort: readonly SortState[], index: number): SortState[];
+/** The criteria with the ones in `keys` moved to sit before `target` (or after it). The
+ *  shape React Aria's drag-and-drop hands over: a set of dragged keys and a drop target. */
+export declare function moveSort(sort: readonly SortState[], keys: ReadonlySet<string>, target: string, position: "before" | "after"): SortState[];
+/**
+ * Compares two rows by every criterion, in order: the second one speaks only when the first
+ * one ties. `read` gives each row's value for a field; `undefined` there means «this field
+ * cannot be sorted here» and the criterion is skipped.
+ *
+ * Missing values go LAST whatever the direction. A blank is not «the smallest»: it is the
+ * absence of an answer, and putting it first when the order is flipped fills the first
+ * screen with the rows that say the least.
+ */
+export declare function compareBy<T>(sort: readonly SortState[], read: (key: string) => ((row: T) => string | number | null | undefined) | undefined): (a: T, b: T) => number;

package/dist/primitives/table/sorting.js

@@ -0,0 +1,110 @@
+/* ==================================================================== *
+ *  SORTING — an ordered list of criteria, not one column.
+ *
+ *  Context: the order of a set was ONE field and a direction. That answers
+ *  «the newest first», and not the question people actually asked the list:
+ *  «by date, and within the same date by customer, and then by product». The
+ *  second and third fields are tie-breakers — they only decide between rows the
+ *  first one left equal — and the engine's criteria already takes them
+ *  (`order: [{ field, descending }, …]`). What could not say it was the screen.
+ *
+ *  So the order is a LIST, outermost first. Empty is «as they came»: the
+ *  third state of a header, which gives the natural order back.
+ *
+ *  The two doors to it write the same list:
+ *
+ *      header click        this column alone — the quick question
+ *      header Shift+click  this column as one more tie-breaker
+ *      the bar's panel     the whole list: add, flip, reorder, remove
+ *
+ *  Pure, and in the table family because the header (`Th`) is its first user;
+ *  the list's bar reads it from here.
+ * ==================================================================== */
+/** Where a column stands in the order: its place (0 = the primary) and direction. */
+export function sortPosition(sort, key) {
+    const index = sort?.findIndex((one) => one.key === key) ?? -1;
+    if (index === -1 || sort === undefined)
+        return null;
+    return { index, direction: sort[index]?.direction ?? "asc" };
+}
+/**
+ * What a press on a column header does to the order.
+ *
+ * Plain press — the column ALONE:
+ *   - the only criterion: asc → desc → nothing. The third press gives the
+ *     natural order back (see `Table.tsx`).
+ *   - with others around it: the column alone, flipped if it was there, and
+ *     never «nothing» — a press that also wipes the tie-breakers someone built
+ *     in the panel would be a surprise, not a shortcut.
+ *
+ * `additive` (Shift) — one more tie-breaker, the others untouched:
+ *   - absent: appended, ascending.
+ *   - ascending: flipped in its place.
+ *   - descending: taken out.
+ */
+export function pressSort(sort, key, additive) {
+    const at = sortPosition(sort, key);
+    if (additive) {
+        if (at === null)
+            return [...sort, { key, direction: "asc" }];
+        if (at.direction === "asc") {
+            return sort.map((one, i) => (i === at.index ? { key, direction: "desc" } : one));
+        }
+        return sort.filter((_, i) => i !== at.index);
+    }
+    if (at === null)
+        return [{ key, direction: "asc" }];
+    if (sort.length === 1)
+        return at.direction === "asc" ? [{ key, direction: "desc" }] : [];
+    return [{ key, direction: at.direction === "asc" ? "desc" : "asc" }];
+}
+/** The criterion at `index` with its direction flipped. */
+export function flipSort(sort, index) {
+    return sort.map((one, i) => i === index ? { ...one, direction: one.direction === "asc" ? "desc" : "asc" } : one);
+}
+/** The criteria with the ones in `keys` moved to sit before `target` (or after it). The
+ *  shape React Aria's drag-and-drop hands over: a set of dragged keys and a drop target. */
+export function moveSort(sort, keys, target, position) {
+    const moving = sort.filter((one) => keys.has(one.key));
+    const rest = sort.filter((one) => !keys.has(one.key));
+    const at = rest.findIndex((one) => one.key === target);
+    if (at === -1 || moving.length === 0)
+        return [...sort];
+    const cut = position === "before" ? at : at + 1;
+    return [...rest.slice(0, cut), ...moving, ...rest.slice(cut)];
+}
+/**
+ * Compares two rows by every criterion, in order: the second one speaks only when the first
+ * one ties. `read` gives each row's value for a field; `undefined` there means «this field
+ * cannot be sorted here» and the criterion is skipped.
+ *
+ * Missing values go LAST whatever the direction. A blank is not «the smallest»: it is the
+ * absence of an answer, and putting it first when the order is flipped fills the first
+ * screen with the rows that say the least.
+ */
+export function compareBy(sort, read) {
+    const criteria = sort.flatMap((one) => {
+        const value = read(one.key);
+        return value === undefined ? [] : [{ value, sign: one.direction === "asc" ? 1 : -1 }];
+    });
+    return (a, b) => {
+        for (const { value, sign } of criteria) {
+            const left = value(a);
+            const right = value(b);
+            const leftMissing = left === null || left === undefined || left === "";
+            const rightMissing = right === null || right === undefined || right === "";
+            if (leftMissing && rightMissing)
+                continue;
+            if (leftMissing)
+                return 1;
+            if (rightMissing)
+                return -1;
+            const order = typeof left === "number" && typeof right === "number"
+                ? left - right
+                : String(left).localeCompare(String(right));
+            if (order !== 0)
+                return order * sign;
+        }
+        return 0;
+    };
+}

package/dist/primitives/value/RichText.d.ts

@@ -0,0 +1,10 @@
+/** The HTML with everything that runs taken out, or `null` where there is no DOM to do it. */
+export declare function sanitizeRichText(html: string): string | null;
+/** The words of an HTML, without its tags: what is shown where it cannot be cleaned. */
+export declare function richTextPlain(html: string): string;
+/** Nothing written: no text and no image — «<p></p>» from an emptied editor counts as nothing. */
+export declare function isRichTextEmpty(html: string | null | undefined): boolean;
+/** The HTML of a note, read: cleaned, in the system's text style (`rich-text` in tokens.css). */
+export declare function RichTextValue({ value }: {
+    value: string | null | undefined;
+}): import("react").JSX.Element;