@sincpro/web-ui 0.1.0 → 0.2.0

package/dist/primitives/picker/Picker.js

@@ -11,10 +11,42 @@ import { useFormMode } from "../field/mode.js";
 import { Popover } from "../overlay/Popover.js";
 import { Check, ChevronDown, SquareArrowOutUpRight } from "lucide-react";
 import { useContext, useMemo, useRef, useState } from "react";
-import { ComboBox as AriaComboBox, ComboBoxStateContext, Input, ListBox, ListBoxItem, Text, useFilter, } from "react-aria-components";
+import { Collection, ComboBox as AriaComboBox, ComboBoxStateContext, Header, Input, ListBox, ListBoxItem, ListBoxLoadMoreItem, ListBoxSection, Text, useFilter, } from "react-aria-components";
 /** The id of the «see all…» row. Not a record id: it cannot collide with one. */
 const BROWSE_ALL = "\u0000browse-all";
 const CAP = 8;
+/**
+ * What the list shows and how many are left out of it. Capped at 8 with the footer count,
+ * unless the list loads incrementally — then everything that arrived is listed and the
+ * scroll asks for more.
+ */
+export function shownRows(filtered, { loading, incremental }) {
+    if (loading)
+        return { visible: [], remaining: 0 };
+    if (incremental)
+        return { visible: filtered, remaining: 0 };
+    const visible = filtered.slice(0, CAP);
+    return { visible, remaining: filtered.length - visible.length };
+}
+/** Folds consecutive items of the same `section` into one run under a header. The ids of
+ *  the runs cannot collide with a record id, like the «see all…» one. */
+function sectioned(items) {
+    const out = [];
+    for (const item of items) {
+        if (item.section === undefined) {
+            out.push(item);
+            continue;
+        }
+        const last = out.at(-1);
+        if (last !== undefined && "items" in last && last.section === item.section) {
+            last.items.push(item);
+        }
+        else {
+            out.push({ id: `\u0000section-${out.length}`, section: item.section, items: [item] });
+        }
+    }
+    return out;
+}
 /* No focus ring on an option: the focus stays in the input (the list is driven from it),
    and the marked row is said by its tint — a ring inside the list as well as around the
    field is two marks for one place. */
@@ -48,7 +80,7 @@ export function Picker({ mode, ...props }) {
        to be ABOVE the component that asks for it. */
     return (_jsx(AriaLocale, { children: _jsx(EditablePicker, { ...props }) }));
 }
-function EditablePicker({ id: ownId, items, value, onChange, placeholder, onBrowseAll, onOpen, emptyText, searchPlaceholder, loading = false, loadingText, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, }) {
+function EditablePicker({ id: ownId, items, value, onChange, placeholder, onBrowseAll, onOpen, emptyText, searchPlaceholder, loading = false, loadingText, onLoadMore, loadingMore = false, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, "aria-label": ariaLabel, }) {
     const { id, labelledBy, describedBy, invalid } = useFieldIds({
         id: ownId,
         describedBy: ownDescribedBy,
@@ -80,8 +112,10 @@ function EditablePicker({ id: ownId, items, value, onChange, placeholder, onBrow
             return items;
         return items.filter((i) => contains(`${i.name} ${i.meta ?? ""} ${i.haystack ?? ""}`, q));
     }, [items, query, contains]);
-    const visible = loading ? [] : filtered.slice(0, CAP);
-    const remaining = loading ? 0 : filtered.length - visible.length;
+    const { visible, remaining } = shownRows(filtered, {
+        loading,
+        incremental: onLoadMore !== undefined,
+    });
     const hasMarks = items.some((i) => i.icon !== undefined);
     const hasHints = visible.some((i) => i.meta !== undefined);
     /* «See all…» is an OPTION at the end of the list and not a button in a footer: the
@@ -110,7 +144,7 @@ function EditablePicker({ id: ownId, items, value, onChange, placeholder, onBrow
         if (next !== value)
             onChange?.(next);
     };
-    return (_jsxs(AriaComboBox, { id: id, "aria-labelledby": labelledBy, "aria-describedby": describedBy, items: listed, value: value ?? null, onChange: take, inputValue: text, onInputChange: (next) => {
+    return (_jsxs(AriaComboBox, { id: id, "aria-labelledby": labelledBy, "aria-label": ariaLabel, "aria-describedby": describedBy, items: listed, value: value ?? null, onChange: take, inputValue: text, onInputChange: (next) => {
             setText(next);
             setQuery(next);
         }, onOpenChange: (isOpen, trigger) => {
@@ -133,9 +167,29 @@ function EditablePicker({ id: ownId, items, value, onChange, placeholder, onBrow
                         onFocus: (event) => {
                             if (!open)
                                 event.currentTarget.select();
-                        }, className: "h-full min-w-0 flex-1 bg-transparent px-2.5 text-meta text-ink outline-0 placeholder:text-muted disabled:cursor-not-allowed" }), value !== undefined && value !== "" && onOpen !== undefined ? (_jsx(IconButton, { icon: SquareArrowOutUpRight, label: copy.picker.open, size: "sm", disabled: disabled, onClick: () => onOpen(value) })) : null, _jsx(FieldButton, { className: "mr-1", children: _jsx(ChevronDown, { "aria-hidden": true, className: "size-(--size-icon-md)", strokeWidth: 2 }) })] }), _jsxs(Popover, { placement: "bottom start", className: "flex w-(--trigger-width) flex-col overflow-hidden", children: [_jsx(ListBox, { items: listed, renderEmptyState: () => (_jsx("p", { className: "px-3 py-3 text-center text-meta text-muted", children: loading ? shownLoading : shownEmpty })), className: "min-h-0 flex-1 overflow-y-auto p-1 outline-0", children: (item) => item.id === BROWSE_ALL ? (_jsx(ListBoxItem, { id: BROWSE_ALL, textValue: item.name, className: (state) => `${option({ ...state, hints: false })} mt-1 border-t border-line text-primary`, children: _jsxs("span", { className: "flex w-full items-center justify-between gap-2", children: [_jsx("span", { className: "font-medium", children: item.name }), _jsx("span", { className: "text-micro tabular-nums text-muted", children: fillCopy(copy.picker.more, {
-                                            count: remaining.toLocaleString(copy.locale),
-                                        }) })] }) })) : (_jsx(ListBoxItem, { id: item.id, textValue: item.name, isDisabled: item.disabled, className: (state) => option({ ...state, hints: hasHints }), children: ({ isSelected }) => (_jsx(Row, { item: item, selected: isSelected, marks: hasMarks, hints: hasHints })) })) }), remaining > 0 && !browsable ? (_jsxs("div", { className: "flex shrink-0 items-center gap-2 border-t border-line bg-ground px-2.5 py-1.5", children: [_jsx("span", { className: "text-micro tabular-nums text-muted", children: fillCopy(copy.picker.more, { count: remaining.toLocaleString(copy.locale) }) }), _jsx("span", { className: "text-micro text-muted", children: copy.picker.refine })] })) : null] })] }));
+                        }, className: "h-full min-w-0 flex-1 bg-transparent px-2.5 text-meta text-ink outline-0 placeholder:text-muted disabled:cursor-not-allowed" }), value !== undefined && value !== "" && onOpen !== undefined ? (_jsx(IconButton, { icon: SquareArrowOutUpRight, label: copy.picker.open, size: "sm", disabled: disabled, onClick: () => onOpen(value) })) : null, _jsx(FieldButton, { className: "mr-1", children: _jsx(ChevronDown, { "aria-hidden": true, className: "size-(--size-icon-md)", strokeWidth: 2 }) })] }), _jsxs(Popover, { placement: "bottom start", className: "flex w-(--trigger-width) flex-col overflow-hidden", children: [_jsx(PickerOptions, { items: listed, marks: hasMarks, hints: hasHints, remaining: remaining, emptyText: loading ? shownLoading : shownEmpty, 
+                        /* Not while the first page loads: the sentinel of an empty list is in view and
+                           would ask for page two before page one arrived. */
+                        onLoadMore: loading ? undefined : onLoadMore, loadingMore: loadingMore }), remaining > 0 && !browsable ? (_jsxs("div", { className: "flex shrink-0 items-center gap-2 border-t border-line bg-ground px-2.5 py-1.5", children: [_jsx("span", { className: "text-micro tabular-nums text-muted", children: fillCopy(copy.picker.more, { count: remaining.toLocaleString(copy.locale) }) }), _jsx("span", { className: "text-micro text-muted", children: copy.picker.refine })] })) : null] })] }));
+}
+/**
+ * The list of a `Picker`: its rows, the section headers, the «see all…» row and the loading
+ * row at the end. Internal — not exported from the family — and apart from the combobox so it
+ * can be rendered on the server without a popover, which is how the tests see the rows.
+ */
+export function PickerOptions({ items, marks, hints, remaining, emptyText, onLoadMore, loadingMore = false, "aria-label": ariaLabel, }) {
+    const copy = useUiCopy();
+    const entries = useMemo(() => sectioned(items), [items]);
+    const renderItem = (item) => item.id === BROWSE_ALL ? (_jsx(ListBoxItem, { id: BROWSE_ALL, textValue: item.name, className: (state) => `${option({ ...state, hints: false })} mt-1 border-t border-line text-primary`, children: _jsxs("span", { className: "flex w-full items-center justify-between gap-2", children: [_jsx("span", { className: "font-medium", children: item.name }), _jsx("span", { className: "text-micro tabular-nums text-muted", children: fillCopy(copy.picker.more, {
+                        count: remaining.toLocaleString(copy.locale),
+                    }) })] }) })) : (_jsx(ListBoxItem, { id: item.id, textValue: item.name, isDisabled: item.disabled, className: (state) => option({ ...state, hints }), children: ({ isSelected }) => (_jsx(Row, { item: item, selected: isSelected, marks: marks, hints: hints })) }));
+    return (_jsxs(ListBox, { "aria-label": ariaLabel, 
+        /* Nothing matched YET while the next page is coming: «nothing matches» above «loading
+           more…» says two contradicting things, so the empty list says only the second. */
+        renderEmptyState: () => (_jsx("p", { className: "px-3 py-3 text-center text-meta text-muted", children: loadingMore ? copy.picker.loadingMore : emptyText })), 
+        /* Incremental, the list is not capped: it scrolls inside its own height and the
+           sentinel at its end is what asks for more. */
+        className: cn("min-h-0 flex-1 overflow-y-auto p-1 outline-0", onLoadMore === undefined ? "" : "max-h-(--size-dropdown)"), children: [_jsx(Collection, { items: entries, children: (entry) => "items" in entry ? (_jsxs(ListBoxSection, { id: entry.id, className: "not-first:mt-1 not-first:border-t not-first:border-line not-first:pt-1", children: [_jsxs(Header, { className: "flex items-center gap-2 px-2 pt-1 pb-0.5 text-micro font-medium text-muted", children: [marks ? (_jsx("span", { className: "size-(--size-icon-sm) shrink-0", "aria-hidden": true })) : null, entry.section] }), _jsx(Collection, { items: entry.items, children: renderItem })] })) : (renderItem(entry)) }), onLoadMore === undefined ? null : (_jsx(ListBoxLoadMoreItem, { onLoadMore: onLoadMore, isLoading: loadingMore && items.length > 0, className: "px-3 py-1.5 text-center text-micro text-muted", children: copy.picker.loadingMore }))] }));
 }
 function Row({ item, selected, marks, hints, }) {
     const Icon = item.icon;

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

@@ -0,0 +1,20 @@
+import { type ReactNode } from "react";
+/**
+ * A cell's value with its copy button — the table's version of a field's (see
+ * `primitives/field/copy.tsx`): the number of an invoice, a customer's name, an amount, copied
+ * without opening the row or selecting by hand.
+ *
+ * Context: the button appears where the pointer or the focus is (on a touch screen it is
+ * always there) and always takes its room, so nothing in the row moves when it shows. In a
+ * numeric cell it goes BEFORE the figure, so the figures stay aligned on the right edge —
+ * which is what makes a column of amounts comparable. It copies what the cell shows
+ * («Bs. 4.132,50», not `4132.5`) unless the column says what to copy.
+ */
+export declare function CellCopy({ children, header, numeric, value, }: {
+    children: ReactNode;
+    /** The column's name, for the button's: «Copiar «Cliente»». */
+    header: string;
+    numeric?: boolean;
+    /** What to copy instead of what is seen. */
+    value?: string;
+}): import("react").JSX.Element;

package/dist/primitives/table/CellCopy.js

@@ -0,0 +1,23 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { shownText } from "../field/copy.js";
+import { CopyButton } from "../value/Copyable.js";
+import { useRef } from "react";
+/**
+ * A cell's value with its copy button — the table's version of a field's (see
+ * `primitives/field/copy.tsx`): the number of an invoice, a customer's name, an amount, copied
+ * without opening the row or selecting by hand.
+ *
+ * Context: the button appears where the pointer or the focus is (on a touch screen it is
+ * always there) and always takes its room, so nothing in the row moves when it shows. In a
+ * numeric cell it goes BEFORE the figure, so the figures stay aligned on the right edge —
+ * which is what makes a column of amounts comparable. It copies what the cell shows
+ * («Bs. 4.132,50», not `4132.5`) unless the column says what to copy.
+ */
+export function CellCopy({ children, header, numeric = false, value, }) {
+    const ui = useUiCopy();
+    const shown = useRef(null);
+    const button = (_jsx("span", { "data-copy-skip": "", className: "inline-flex shrink-0 opacity-0 transition-opacity duration-(--duration-instant) group-hover/cell:opacity-100 focus-within:opacity-100 pointer-coarse:opacity-100", children: _jsx(CopyButton, { label: fillCopy(ui.copyable.field, { label: header }), value: () => value ?? (shown.current === null ? "" : shownText(shown.current)) }) }));
+    return (_jsxs("span", { className: `group/cell flex w-full min-w-0 items-center gap-1 ${numeric ? "justify-end" : ""}`, children: [numeric ? button : null, _jsx("span", { ref: shown, className: "min-w-0", children: children }), numeric ? null : button] }));
+}

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

@@ -8,6 +8,17 @@ import { type ReactNode } from "react";
  *  identifiers or averaging file sizes produces numbers that look like data and
  *  mean nothing. An aggregate has to be chosen on purpose. */
 export type Aggregate = "count" | "sum" | "mean" | "min" | "max" | "unique";
+/**
+ * How the aggregate of a column is written: its `format` when the aggregate is in the
+ * column's units, `undefined` (the bare number) otherwise.
+ *
+ * Exported for the other places that draw `aggregateOf` — the bands of the sheet, the report
+ * built from the piles — so the footer and the band never write the same total two ways.
+ * Not public.
+ */
+export declare function aggregateFormat<T>(column: DataColumn<T>): ((value: number) => string) | undefined;
+/** An aggregate of a column, written — or the bare number when nothing says how. */
+export declare function aggregateText<T>(column: DataColumn<T>, value: number): string | number;
 export interface DataColumn<T> {
     id: string;
     header: string;
@@ -44,6 +55,19 @@ export interface DataColumn<T> {
     numeric?: boolean;
     width?: number;
     aggregate?: Aggregate;
+    /**
+     * How a number of this column is WRITTEN where the code draws it instead of a row: the
+     * footer's aggregate, the total of a band of the sheet, the lines of a report built
+     * from the piles. `(n) => money(n)` makes the footer read «Bs. 78.752,90» like the cells
+     * above it, and not «78.752,9».
+     *
+     * Context: the cells already had their way (`cell`), and that way takes a ROW — the
+     * footer has no row, only a number. A string and not a node because two of the three
+     * places are grids of text: the sheet and the report. Applies to the aggregates in the
+     * column's units (`sum`, `mean`, `min`, `max`); a `count` stays a count. Without it,
+     * the number in the copy table's locale, as before.
+     */
+    format?: (value: number) => string;
     sortable?: boolean;
     /** Odoo: fields without `optional` cannot leave the view. When true, the
      *  column appears in the columns submenu and can be hidden. */
@@ -66,7 +90,32 @@ export interface DataColumn<T> {
         /** Which rows can be changed — a paid invoice cannot. All of them by default. */
         when?: (row: T) => boolean;
     };
+    /** The control of this column in the row of a NEW record (`DataTable`'s `create`).
+     *  The same contract as `EditableTable`'s `edit`: `set` replaces the draft. Give it an
+     *  `aria-label` — a cell has no `Field` to name it. Without it the column stays
+     *  empty in that row: a computed amount, a sequence the backend assigns. */
+    input?: (draft: T, set: (next: T) => void) => ReactNode;
+    /** The copy button of the cells (`CellCopy`): on by default, copying what the cell shows.
+     *  A function copies what it returns for the row instead; `false` removes it from this
+     *  column — a column of tags or of buttons has nothing worth pasting. */
+    copy?: false | ((row: T) => string);
 }
+/** Writing a new record in the list. See the file's header. */
+export type DataTableCreate<T> = {
+    /** The record being written, or `null` when there is none. */
+    draft: T | null;
+    /** «Add» was asked for: the consumer sets a blank `draft`. */
+    onStart: () => void;
+    onChange: (next: T) => void;
+    /** `Enter`, leaving the row after writing in it, or `Tab` past its last control. The
+     *  consumer validates and saves, and sets `draft` back to `null` — or keeps it, to
+     *  say what is missing. */
+    onCommit: (draft: T) => void;
+    /** `Escape`, or leaving the row without having written anything. */
+    onCancel: () => void;
+    /** The «add» under the table. Defaults to the copy table's. */
+    label?: string;
+};
 /**
  * El agregado de una columna sobre un conjunto de filas.
  *
@@ -99,7 +148,7 @@ export type GroupColumn<T> = {
     /** Cómo se lee esa clave. */
     labelOf: (key: string) => string;
 };
-export declare function DataTable<T extends object>({ data, columns, getRowId, sort, onSortChange, levels, selected, onSelectedChange, height, onRowClick, rowActions, totals, collapsed, onGroupToggle, }: {
+export declare function DataTable<T extends object>({ data, columns, getRowId, sort, onSortChange, levels, selected, onSelectedChange, height, onRowClick, rowActions, totals, collapsed, onGroupToggle, create, copyable, }: {
     data: readonly T[];
     columns: readonly DataColumn<T>[];
     getRowId: (row: T) => string;
@@ -132,4 +181,9 @@ export declare function DataTable<T extends object>({ data, columns, getRowId, s
      *  table does not reopen what rows just folded. */
     collapsed?: readonly string[];
     onGroupToggle?: (key: string) => void;
+    /** Write a new record as a row of the list. See the file's header. */
+    create?: DataTableCreate<T>;
+    /** The cells' copy buttons, on by default. `false` takes them off the whole table; a
+     *  column turns its own off with `copy: false`. */
+    copyable?: boolean;
 }): import("react").JSX.Element;

package/dist/primitives/table/DataTable.js

@@ -2,27 +2,54 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { fillCopy, useUiCopy } from "../../foundations/copy.js";
 import { pathKey } from "../../foundations/grouping.js";
+import { CellCopy } from "./CellCopy.js";
 import { CellEditor } from "./CellEditor.js";
+import { EditRow, firstControl } from "./EditableTable.js";
 import { RowActions } from "./RowActions.js";
 import { SelectBox, Table, Td, Th, THead, Tr, } from "./Table.js";
 import { aggregationFns, columnGroupingFeature, createColumnHelper, createExpandedRowModel, createGroupedRowModel, createSortedRowModel, rowAggregationFeature, rowExpandingFeature, rowSortingFeature, sortFns, tableFeatures, useTable, } from "@tanstack/react-table";
-import { ChevronRight } from "lucide-react";
-import { useMemo } from "react";
-function aggregateLabel(copy, kind, v) {
+import { ChevronRight, Plus } from "lucide-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+/** The aggregates that are an amount OF the column — a sum of bolivianos is bolivianos — and
+ *  so are written the way the column writes its numbers. `count` and `unique` count rows
+ *  and values: «Bs. 12,00 rows» would be nonsense. */
+const IN_COLUMN_UNITS = new Set(["sum", "mean", "min", "max"]);
+/**
+ * How the aggregate of a column is written: its `format` when the aggregate is in the
+ * column's units, `undefined` (the bare number) otherwise.
+ *
+ * Exported for the other places that draw `aggregateOf` — the bands of the sheet, the report
+ * built from the piles — so the footer and the band never write the same total two ways.
+ * Not public.
+ */
+export function aggregateFormat(column) {
+    return column.aggregate !== undefined && IN_COLUMN_UNITS.has(column.aggregate)
+        ? column.format
+        : undefined;
+}
+/** An aggregate of a column, written — or the bare number when nothing says how. */
+export function aggregateText(column, value) {
+    const format = aggregateFormat(column);
+    return format === undefined ? value : format(value);
+}
+function aggregateLabel(copy, column, v) {
     const n = v.toLocaleString(copy.locale);
-    switch (kind) {
+    /* Raw, a sum of amounts read «78.752,9»: one decimal lost and no currency, under a
+       column whose every cell says «Bs. 12.300,00». */
+    const amount = (fallback) => column.format === undefined ? fallback : column.format(v);
+    switch (column.aggregate ?? "count") {
         case "sum":
-            return n;
+            return amount(n);
         case "count":
             return `${n} ${v === 1 ? copy.table.row : copy.table.rows}`;
         case "mean":
             return fillCopy(copy.table.mean, {
-                value: v.toLocaleString(copy.locale, { maximumFractionDigits: 2 }),
+                value: amount(v.toLocaleString(copy.locale, { maximumFractionDigits: 2 })),
             });
         case "min":
-            return fillCopy(copy.table.min, { value: n });
+            return fillCopy(copy.table.min, { value: amount(n) });
         case "max":
-            return fillCopy(copy.table.max, { value: n });
+            return fillCopy(copy.table.max, { value: amount(n) });
         case "unique":
             return fillCopy(copy.table.distinct, { value: n });
     }
@@ -90,8 +117,46 @@ export function aggregateOf(column, rows) {
             return numbers.length;
     }
 }
-export function DataTable({ data, columns, getRowId, sort, onSortChange, levels, selected, onSelectedChange, height, onRowClick, rowActions, totals = false, collapsed, onGroupToggle, }) {
+export function DataTable({ data, columns, getRowId, sort, onSortChange, levels, selected, onSelectedChange, height, onRowClick, rowActions, totals = false, collapsed, onGroupToggle, create, copyable = true, }) {
     const copy = useUiCopy();
+    const draft = create?.draft ?? null;
+    const draftRow = useRef(null);
+    const addButton = useRef(null);
+    /* Whether anything was written in the draft: leaving a blank one drops it. */
+    const touched = useRef(false);
+    const writing = draft !== null;
+    /* Each «add» is a session. With `Tab` the next draft replaces the saved one without
+       ever being `null`, so `writing` alone would not say a new record began. */
+    const [session, setSession] = useState(0);
+    /* «add» is hidden while writing: the focus goes back to it once it is there again. */
+    const backToAdd = useRef(false);
+    const start = () => {
+        setSession((n) => n + 1);
+        create?.onStart();
+    };
+    /* A draft that appears takes the focus on its first control — «add» is a request to
+       write, not to look for where to. */
+    useEffect(() => {
+        if (!writing) {
+            if (backToAdd.current)
+                addButton.current?.focus();
+            backToAdd.current = false;
+            return;
+        }
+        touched.current = false;
+        const node = draftRow.current;
+        if (node !== null)
+            (firstControl(node) ?? node).focus();
+    }, [writing, session]);
+    const saveDraft = (refocus) => {
+        if (create === undefined || draft === null)
+            return;
+        backToAdd.current = refocus;
+        if (touched.current)
+            create.onCommit(draft);
+        else
+            create.onCancel();
+    };
     // In v9 the helper is bound to the features AND to the data type: that is what
     // makes the compiler know about `enableGrouping` only if we ask for the
     // feature.
@@ -208,37 +273,58 @@ export function DataTable({ data, columns, getRowId, sort, onSortChange, levels,
             n.delete(id);
         onSelectedChange?.(n);
     }
-    return (_jsxs(Table, { height: height, children: [_jsxs(THead, { children: [selecting ? (_jsx(Th, { width: 36, children: _jsx(SelectBox, { label: copy.selection.all, checked: all, indeterminate: some, onChange: (v) => onSelectedChange?.(v ? new Set(leaves.map((r) => r.id)) : new Set()) }) })) : null, columns.map((c) => (_jsx(Th, { sortKey: c.sortable === false ? undefined : c.id, sort: sort, onSort: onSortChange, numeric: c.numeric, width: c.width, children: c.header }, c.id))), rowActions === undefined ? null : _jsx(Th, { width: 1, children: "" })] }), _jsx("tbody", { children: drawn.map((row) => {
-                    const isGroup = row.subRows.length > 0;
-                    if (isGroup) {
-                        const path = pathOf(row);
-                        const key = pathKey(path);
-                        const depth = path.length - 1;
-                        const id = row.groupingColumnId ?? undefined;
-                        const level = levels?.find((one) => one.id === id);
-                        /* La CLAVE del montón —la del motor— y el rótulo, que lo pone el
-                           nivel: son dos textos y sólo el segundo cambia con el idioma. */
-                        const value = path[depth] ?? key;
-                        const open = collapsed === undefined
-                            ? row.getIsExpanded()
-                            : collapsed.includes(key) !== true;
-                        return (
-                        /* The group row: it spans the whole width, says which value it
-                           groups by and how many are inside. The counter is what makes it
-                           useful without opening it. */
-                        _jsx("tr", { className: "border-b border-line bg-ground", children: _jsx("td", { colSpan: columns.length + (selecting ? 1 : 0) + (rowActions === undefined ? 0 : 1), className: "px-3 py-1.5", style: depth === 0
-                                    ? undefined
-                                    : { paddingLeft: `calc(var(--spacing-indent) * ${depth} + 0.75rem)` }, children: _jsxs("button", { type: "button", onClick: () => onGroupToggle === undefined ? row.toggleExpanded() : onGroupToggle(key), "aria-expanded": open, className: "inline-flex items-center gap-1.5 rounded-control text-meta font-medium text-ink transition-colors duration-(--duration-instant) hover:text-primary focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary", children: [_jsx(ChevronRight, { className: `size-(--size-icon-sm) text-muted transition-transform duration-(--duration-instant) ${open ? "rotate-90" : ""}`, strokeWidth: 2, "aria-hidden": true }), level === undefined ? null : (_jsx("span", { className: "text-micro font-normal text-muted/70", children: level.label })), _jsx("span", { children: level === undefined ? value : level.labelOf(value) }), _jsx("span", { className: "inline-flex shrink-0 items-center rounded-pill border border-line-strong bg-ink/5 px-2 py-0.5 text-micro tabular-nums text-muted", children: row.getLeafRows().length.toLocaleString(copy.locale) })] }) }) }, row.id));
-                    }
-                    const original = row.original;
-                    return (_jsxs(Tr, { selected: selected?.has(row.id) === true, onClick: onRowClick === undefined ? undefined : () => onRowClick(original), children: [selecting ? (_jsx(Td, { children: _jsx(SelectBox, { label: copy.selection.row, checked: selected?.has(row.id) === true, onChange: (v) => toggle(row.id, v) }) })) : null, columns.map((c) => {
-                                const t = c.tone?.(original);
-                                const n = c.note?.(original);
-                                const edit = c.edit?.when?.(original) === false ? undefined : c.edit;
-                                return (_jsx(Td, { numeric: c.numeric, mono: c.mono === true, ...(t === undefined ? {} : { tone: t }), ...(n === undefined ? {} : { title: n }), children: edit !== undefined ? (_jsx(CellEditor, { label: fillCopy(copy.inlineEdit.editCell, { column: c.header }), numeric: c.numeric === true, editor: (done) => edit.render(original, done), children: drawCell(copy, c, original) })) : (drawCell(copy, c, original)) }, c.id));
-                            }), rowActions === undefined ? null : (_jsx(RowActions, { actions: rowActions(original) }))] }, row.id));
-                }) }), footer === null ? null : (_jsx("tfoot", { className: "sticky bottom-0 z-10 bg-ground", children: _jsxs("tr", { className: "border-t border-line-strong", children: [selecting ? _jsx("td", {}) : null, columns.map((c, i) => {
+    const grid = (_jsxs(Table, { height: height, children: [_jsxs(THead, { children: [selecting ? (_jsx(Th, { width: 36, children: _jsx(SelectBox, { label: copy.selection.all, checked: all, indeterminate: some, onChange: (v) => onSelectedChange?.(v ? new Set(leaves.map((r) => r.id)) : new Set()) }) })) : null, columns.map((c) => (_jsx(Th, { sortKey: c.sortable === false ? undefined : c.id, sort: sort, onSort: onSortChange, numeric: c.numeric, width: c.width, children: c.header }, c.id))), rowActions === undefined ? null : _jsx(Th, { width: 1, children: "" })] }), _jsxs("tbody", { children: [drawn.map((row) => {
+                        const isGroup = row.subRows.length > 0;
+                        if (isGroup) {
+                            const path = pathOf(row);
+                            const key = pathKey(path);
+                            const depth = path.length - 1;
+                            const id = row.groupingColumnId ?? undefined;
+                            const level = levels?.find((one) => one.id === id);
+                            /* La CLAVE del montón —la del motor— y el rótulo, que lo pone el
+                               nivel: son dos textos y sólo el segundo cambia con el idioma. */
+                            const value = path[depth] ?? key;
+                            const open = collapsed === undefined
+                                ? row.getIsExpanded()
+                                : collapsed.includes(key) !== true;
+                            return (
+                            /* The group row: it spans the whole width, says which value it
+                               groups by and how many are inside. The counter is what makes it
+                               useful without opening it. */
+                            _jsx("tr", { className: "border-b border-line bg-ground", children: _jsx("td", { colSpan: columns.length + (selecting ? 1 : 0) + (rowActions === undefined ? 0 : 1), className: "px-3 py-1.5", style: depth === 0
+                                        ? undefined
+                                        : { paddingLeft: `calc(var(--spacing-indent) * ${depth} + 0.75rem)` }, children: _jsxs("button", { type: "button", onClick: () => onGroupToggle === undefined ? row.toggleExpanded() : onGroupToggle(key), "aria-expanded": open, className: "inline-flex items-center gap-1.5 rounded-control text-meta font-medium text-ink transition-colors duration-(--duration-instant) hover:text-primary focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary", children: [_jsx(ChevronRight, { className: `size-(--size-icon-sm) text-muted transition-transform duration-(--duration-instant) ${open ? "rotate-90" : ""}`, strokeWidth: 2, "aria-hidden": true }), level === undefined ? null : (_jsx("span", { className: "text-micro font-normal text-muted/70", children: level.label })), _jsx("span", { children: level === undefined ? value : level.labelOf(value) }), _jsx("span", { className: "inline-flex shrink-0 items-center rounded-pill border border-line-strong bg-ink/5 px-2 py-0.5 text-micro tabular-nums text-muted", children: row.getLeafRows().length.toLocaleString(copy.locale) })] }) }) }, row.id));
+                        }
+                        const original = row.original;
+                        return (_jsxs(Tr, { selected: selected?.has(row.id) === true, onClick: onRowClick === undefined ? undefined : () => onRowClick(original), children: [selecting ? (_jsx(Td, { children: _jsx(SelectBox, { label: copy.selection.row, checked: selected?.has(row.id) === true, onChange: (v) => toggle(row.id, v) }) })) : null, columns.map((c) => {
+                                    const t = c.tone?.(original);
+                                    const n = c.note?.(original);
+                                    const edit = c.edit?.when?.(original) === false ? undefined : c.edit;
+                                    return (_jsx(Td, { numeric: c.numeric, mono: c.mono === true, ...(t === undefined ? {} : { tone: t }), ...(n === undefined ? {} : { title: n }), children: edit !== undefined ? (_jsx(CellEditor, { label: fillCopy(copy.inlineEdit.editCell, { column: c.header }), numeric: c.numeric === true, editor: (done) => edit.render(original, done), children: drawCell(copy, c, original) })) : copyable && c.copy !== false ? (_jsx(CellCopy, { header: c.header, numeric: c.numeric === true, ...(c.copy === undefined ? {} : { value: c.copy(original) }), children: drawCell(copy, c, original) })) : (drawCell(copy, c, original)) }, c.id));
+                                }), rowActions === undefined ? null : (_jsx(RowActions, { actions: rowActions(original) }))] }, row.id));
+                    }), create === undefined || draft === null ? null : (_jsxs(EditRow, { as: "tr", rowId: "\\u0000draft", rowRef: (node) => {
+                            draftRow.current = node;
+                        }, editable: true, editing: true, tabbable: false, className: "group/row", onStart: () => { }, onCommit: saveDraft, onCancel: () => {
+                            backToAdd.current = true;
+                            create.onCancel();
+                        }, onMove: () => { }, onFocusRow: () => { }, onTabOut: (direction) => {
+                            /* Past the last control: saved, and the next one started — unless nothing
+                               was written, which is «I am done». Backwards, the browser's way. */
+                            if (direction === "prev" || !touched.current)
+                                return false;
+                            create.onCommit(draft);
+                            start();
+                            return true;
+                        }, children: [selecting ? _jsx("td", { className: DRAFT_CELL }) : null, columns.map((c) => (_jsx("td", { ...(c.input === undefined ? {} : { "data-edit": "" }), className: `${DRAFT_CELL} ${c.numeric === true ? "text-right tabular-nums" : ""}`, children: c.input?.(draft, (next) => {
+                                    touched.current = true;
+                                    create.onChange(next);
+                                }) ?? null }, c.id))), rowActions === undefined ? null : _jsx("td", { className: DRAFT_CELL })] }))] }), footer === null ? null : (_jsx("tfoot", { className: "sticky bottom-0 z-10 bg-ground", children: _jsxs("tr", { className: "border-t border-line-strong", children: [selecting ? _jsx("td", {}) : null, columns.map((c, i) => {
                             const value = footer[i] ?? null;
-                            return (_jsx("td", { className: `px-3 py-1.5 text-meta font-semibold text-ink ${c.numeric === true ? "text-right tabular-nums" : ""}`, children: i === 0 && value === null ? (_jsxs("span", { className: "text-muted", children: [data.length.toLocaleString(copy.locale), " ", data.length === 1 ? copy.table.row : copy.table.rows] })) : value === null ? null : (aggregateLabel(copy, c.aggregate ?? "count", value)) }, c.id));
+                            return (_jsx("td", { className: `px-3 py-1.5 text-meta font-semibold text-ink ${c.numeric === true ? "text-right tabular-nums" : ""}`, children: i === 0 && value === null ? (_jsxs("span", { className: "text-muted", children: [data.length.toLocaleString(copy.locale), " ", data.length === 1 ? copy.table.row : copy.table.rows] })) : value === null ? null : (aggregateLabel(copy, c, value)) }, c.id));
                         }), rowActions === undefined ? null : _jsx("td", {})] }) }))] }));
+    if (create === undefined)
+        return grid;
+    return (_jsxs("div", { className: "flex min-w-0 flex-col", children: [grid, writing ? null : (_jsx("div", { className: "px-1 py-0.5", children: _jsxs("button", { ref: addButton, type: "button", onClick: start, className: "flex w-full items-center gap-1.5 rounded-control px-3 py-1 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", children: [_jsx(Plus, { className: "size-(--size-icon-sm)", strokeWidth: 2.5, "aria-hidden": true }), create.label ?? copy.table.add] }) }))] }));
 }
+/* A cell of the row being written: the table's cell, washed like an edited row. */
+const DRAFT_CELL = "border-b border-line bg-primary/5 px-3 py-1 align-middle text-meta text-ink first:rounded-l-control last:rounded-r-control";

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

@@ -1,4 +1,5 @@
 import { type Grouping } from "../../foundations/grouping.js";
+import { type FlagProps } from "../notice/Flag.js";
 import { type ReactNode } from "react";
 /** Where a column goes when the row is drawn as a stacked card (a narrow box).
  *  `trail` sits at the top right, beside the title — a state, the row's buttons. */
@@ -28,7 +29,32 @@ export interface EditColumn<T> {
      *  discount. `null` or `""` leaves it out of that row's line — a zero discount is
      *  not news. Without it the line reads «<header> <cell>». */
     brief?: (row: T) => ReactNode;
+    /** Drawn on section and note rows too, instead of being covered by their text — the
+     *  row's buttons. `render` receives the band's row. */
+    onBands?: boolean;
 }
+/** What a row that is not a line is. See «sections and notes» in the file's header. */
+export type EditBands<T> = {
+    /** `section` heads the lines under it; `note` is a sentence between lines; `null` is a
+     *  line. */
+    kind: (row: T) => "section" | "note" | null;
+    /** The band's text as it reads. */
+    render: (row: T) => ReactNode;
+    /** Its control while the row is edited — a text field, named. */
+    edit?: (row: T, set: (next: T) => void) => ReactNode;
+    /** What a section's lines add up to in `column`, already formatted; `null` where the
+     *  column does not add up. The lines are the ones under it until the next section. */
+    total?: (column: EditColumn<T>, lines: readonly T[]) => ReactNode | null;
+};
+/** One more way to add, beside «add a line»: a section, a note. */
+export type EditAdd = {
+    label: string;
+    /** As `onAdd`: return the new row's id and it opens. */
+    onAdd: () => string | void | Promise<string | void>;
+};
+/** The lines each section heads: the rows after it up to the next section. Notes do not
+ *  cut a section, and are not lines. */
+export declare function sectionLines<T>(rows: readonly T[], getRowId: (row: T) => string, kind: (row: T) => "section" | "note" | null): Map<string, T[]>;
 /**
  * Where each column goes in the stacked card, defaults resolved: a declared `stack`
  * wins; otherwise the first undeclared column is the title (unless one was declared),
@@ -39,6 +65,56 @@ export declare function stackPlaces(columns: readonly {
     stack?: StackPlace;
     numeric?: boolean;
 }[]): StackPlace[];
+/** The first control of a row being edited: the first one in an editable cell, else
+ *  anything focusable in the row (a column without `edit` may still hold a button). */
+export declare function firstControl(row: HTMLElement): HTMLElement | null;
+/** Where `Tab` goes from the edge of an edited row: the next or previous row opened, a new
+ *  row added, or out of the table the browser's way. */
+export type TabTarget = {
+    kind: "row";
+    id: string;
+} | {
+    kind: "add";
+} | {
+    kind: "leave";
+};
+/**
+ * Where `Tab` past the last control (`next`) or `Shift+Tab` before the first (`prev`) of
+ * the edited row `from` goes, over the rows in the order they are drawn.
+ *
+ * Past the last row it adds one when the table can — unless `from` is itself a row just
+ * added and still blank: one more `Tab` there means «I am done», not «another blank line».
+ */
+export declare function tabTarget(order: readonly string[], from: string, direction: "next" | "prev", { canAdd, blank }: {
+    canAdd: boolean;
+    blank: boolean;
+}): TabTarget;
+export type RowKey = "ArrowDown" | "ArrowUp" | "Home" | "End";
+/**
+ * One body row. Its own component so that it can hold React Aria's `useKeyboard`
+ * (a hook per row) and the timer that decides whether the focus really left it.
+ * The same row is a `<tr>` in the table and an `<li>` in the stacked list — and the row
+ * of a new record in `DataTable`: one keyboard model, three shapes. Exported for that
+ * family sibling only; it is not in the barrel.
+ */
+export declare function EditRow({ as, rowId, rowRef, editable, editing, tabbable, className, onStart, onCommit, onCancel, onMove, onFocusRow, onTabOut, children, }: {
+    as: "tr" | "li";
+    rowId: string;
+    rowRef: (node: HTMLElement | null) => void;
+    editable: boolean;
+    editing: boolean;
+    tabbable: boolean;
+    className: string;
+    onStart: (viaKeyboard: boolean) => void;
+    onCommit: (refocus: boolean) => void;
+    onCancel: () => void;
+    onMove: (key: RowKey) => void;
+    onFocusRow: () => void;
+    /** `Tab` left the row by one of its edges. `true` = the table took it (opened another
+     *  row, added one); `false` = the browser moves the focus as usual. */
+    onTabOut: (direction: "next" | "prev") => boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
 /**
  * A table whose rows are edited in place, one row at a time.
  *
@@ -59,13 +135,16 @@ totals, empty, grouping,
 /** El total de una columna DENTRO de un montón, ya formateado. Lo calcula quien
  *  compone, por el mismo motivo que `totals`: sumar significa cosas distintas
  *  según el dominio, y un porcentaje se promedia, no se suma. */
-groupTotal, height, layout, onOpen, }: {
+groupTotal, height, layout, onOpen, onDiscard, bands, adds, flag, }: {
     rows: readonly T[];
     columns: readonly EditColumn<T>[];
     getRowId: (row: T) => string;
     onChange?: (id: string, next: T) => void;
     onRemove?: (id: string) => void;
-    onAdd?: () => void;
+    /** «Add a line». Return the new row's id —or a promise of it, when the backend makes
+     *  the record— and the table opens that row with the focus on its first control.
+     *  Return nothing and the row just appears, closed. */
+    onAdd?: () => string | void | Promise<string | void>;
     addLabel?: string;
     totals?: readonly (ReactNode | null)[];
     empty?: string;
@@ -93,4 +172,20 @@ groupTotal, height, layout, onOpen, }: {
      *  form of its own, a dialog that is a bottom sheet on a phone. The table ignores it:
      *  there the row is edited where it is read. */
     onOpen?: (id: string) => void;
+    /** Take back a row `onAdd` opened when it is abandoned: `Escape` on it, or leaving it
+     *  without a single change. Not `onRemove`: nobody removed a line, so there is nothing
+     *  to undo or to announce. Without it the blank row stays. */
+    onDiscard?: (id: string) => void;
+    /** Rows that are not lines: sections and notes. See the file's header. */
+    bands?: EditBands<T>;
+    /** More ways to add, drawn beside «add» under the grid: «add a section», «add a note». */
+    adds?: readonly EditAdd[];
+    /** A warning about one row — stock, a price under cost — drawn as a `Flag` at its start.
+     *  `null` for the rows with nothing to say, which should be most of them. `owner` is what
+     *  the record's activity says it belongs to («Línea 3 · Impresora…»); without it, the
+     *  row's first value. */
+    flag?: (row: T) => (Omit<FlagProps, "children"> & {
+        detail?: ReactNode;
+        owner?: string;
+    }) | null;
 }): import("react").JSX.Element;