@sincpro/web-ui 0.1.0 → 1.0.0

package/dist/primitives/picker/Picker.js

@@ -1,20 +1,69 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { AriaLocale } from "../../foundations/aria.js";
 import { fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { matchedWord, matches } from "../../foundations/match.js";
 import { cn, tv } from "../../foundations/variants.js";
 import { IconButton } from "../button/Button.js";
 import { FieldButton, FieldGroup } from "../field/aria.js";
 import { useFieldIds } from "../field/context.js";
 import { ReadValue } from "../field/Field.js";
 import { useFormMode } from "../field/mode.js";
+import { Menu } from "../menu/Menu.js";
 import { Popover } from "../overlay/Popover.js";
-import { Check, ChevronDown, SquareArrowOutUpRight } from "lucide-react";
+import { MatchedText } from "./MatchedText.js";
+import { Avatar } from "../value/Person.js";
+import { AppWindow, Check, ChevronDown, Ellipsis, Eye, PanelRight, PictureInPicture2, 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";
-/** The id of the «see all…» row. Not a record id: it cannot collide with one. */
+import { Collection, ComboBox as AriaComboBox, ComboBoxStateContext, Header, Input, ListBox, ListBoxItem, ListBoxLoadMoreItem, ListBoxSection, Text, useFilter, } from "react-aria-components";
+/** The icon of each place a record opens — the same in every field and list. */
+const OPEN_ICON = {
+    modal: PictureInPicture2,
+    peek: Eye,
+    page: SquareArrowOutUpRight,
+    side: PanelRight,
+    window: AppWindow,
+};
+/** The id of the «Buscar más…» row. Not a record id: it cannot collide with one. */
 const BROWSE_ALL = "\u0000browse-all";
+/** The rows that create from what was typed — quick, or with the full form. */
+const CREATE = "\u0000create";
+const CREATE_EDIT = "\u0000create-edit";
+/** The rows that act instead of choosing: after the records, in this order. */
+const ACTIONS = new Set([CREATE, CREATE_EDIT, BROWSE_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 «Buscar más…» 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 +97,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, onCreate, onCreateAndEdit, onOpen, openTargets = ["modal", "peek", "side", "page"], 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,29 +129,55 @@ 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
        arrows reach it like any other row. As a footer button it was out of the keyboard's
        path — Tab leaves the field and closes the list before getting there. */
-    const browsable = remaining > 0 && onBrowseAll !== undefined;
-    const listed = browsable
-        ? [...visible, { id: BROWSE_ALL, name: copy.picker.browseAll }]
-        : visible;
+    const browsable = onBrowseAll !== undefined;
+    const typed = query.trim();
+    /* Exactly the name of an option already: creating it again would make a twin. */
+    const named = typed !== "" &&
+        items.some((i) => i.name.localeCompare(typed, copy.locale, { sensitivity: "base" }) === 0);
+    const actions = loading
+        ? []
+        : [
+            ...(onCreate !== undefined && typed !== "" && !named
+                ? [{ id: CREATE, name: fillCopy(copy.picker.create, { name: typed }) }]
+                : []),
+            ...(onCreateAndEdit === undefined
+                ? []
+                : [{ id: CREATE_EDIT, name: copy.picker.createAndEdit }]),
+            ...(browsable ? [{ id: BROWSE_ALL, name: copy.picker.browseAll }] : []),
+        ];
+    const listed = [...visible, ...actions];
     const closeList = useRef(null);
     const take = (key) => {
         if (key === null)
             return;
         const next = String(key);
-        if (next === BROWSE_ALL) {
-            /* The full list opens somewhere else (a dialog, a panel): this one closes and the
-               field keeps the chosen name. */
+        if (ACTIONS.has(next)) {
+            /* The full list, or the new record's form, opens somewhere else (a dialog, a panel):
+               this one closes and the field keeps the chosen name. A quick create chooses the new
+               record once it exists. */
+            const asked = query;
             closeList.current?.();
             setText(chosenName);
             setQuery("");
-            onBrowseAll?.();
+            if (next === BROWSE_ALL)
+                onBrowseAll?.(asked);
+            if (next === CREATE_EDIT)
+                onCreateAndEdit?.(asked.trim());
+            if (next === CREATE && onCreate !== undefined) {
+                /* The field keeps the new name from now on, not the old one until the record exists:
+                   a controlled text that changes while the input has focus reopens the list. */
+                setText(asked.trim());
+                void Promise.resolve(onCreate(asked.trim())).then((created) => onChange?.(created));
+            }
             return;
         }
         setText(items.find((i) => i.id === next)?.name ?? "");
@@ -110,7 +185,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) => {
@@ -126,23 +201,67 @@ function EditablePicker({ id: ownId, items, value, onChange, placeholder, onBrow
            the options are the answer before the first letter. */
         menuTrigger: "focus", 
         /* An empty list stays open to SAY it is empty (or loading) instead of vanishing. */
-        allowsEmptyCollection: true, isInvalid: invalid, isDisabled: disabled, className: "w-full min-w-0", children: [_jsx(CloseBridge, { into: closeList }), _jsxs(FieldGroup, { children: [_jsx(Input, { placeholder: loading ? shownLoading : open ? shownSearch : shownPlaceholder, title: shownSearch, 
+        allowsEmptyCollection: true, isInvalid: invalid, isDisabled: disabled, className: "w-full min-w-0", children: [_jsx(CloseBridge, { into: closeList }), _jsxs(FieldGroup, { children: [chosen?.avatar === undefined || open ? null : (_jsx("span", { className: "flex shrink-0 items-center pl-2", children: _jsx(Avatar, { name: chosen.name, size: "sm", ...(typeof chosen.avatar === "string" ? { src: chosen.avatar } : {}) }) })), _jsx(Input, { placeholder: loading ? shownLoading : open ? shownSearch : shownPlaceholder, title: shownSearch, 
                         /* Arriving selects the name, so the first letter typed replaces it. Only when
                            ARRIVING: React Aria hands the focus back to the input while the list is open,
                            and selecting again then would swallow every second letter. */
                         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 &&
+                        openTargets[0] !== undefined ? (_jsxs(_Fragment, { children: [_jsx(IconButton, { icon: OPEN_ICON[openTargets[0]], label: copy.picker.openIn[openTargets[0]], size: "sm", disabled: disabled, onClick: () => onOpen(value, openTargets[0]) }), openTargets.length < 2 || disabled ? null : (_jsx(Menu, { label: copy.picker.openMore, icon: Ellipsis, iconOnly: true, chevron: false, variant: "text", align: "end", groups: [
+                                    {
+                                        options: openTargets.slice(1).map((to) => ({
+                                            id: to,
+                                            label: copy.picker.openIn[to],
+                                            icon: OPEN_ICON[to],
+                                        })),
+                                    },
+                                ], onSelect: (to) => onOpen(value, to) }))] })) : 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, query: query, 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] })] }));
 }
-function Row({ item, selected, marks, hints, }) {
+/**
+ * The list of a `Picker`: its rows, the section headers, the «Buscar más…» 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, query = "", emptyText, onLoadMore, loadingMore = false, "aria-label": ariaLabel, }) {
+    const copy = useUiCopy();
+    const entries = useMemo(() => sectioned(items), [items]);
+    /* The actions are one block under the records: one hairline above the first of them. */
+    const firstAction = items.find((i) => ACTIONS.has(i.id))?.id;
+    const renderItem = (item) => ACTIONS.has(item.id) ? (_jsx(ListBoxItem, { id: item.id, textValue: item.name, className: (state) => cn(option({ ...state, hints: false }), "text-primary", item.id === firstAction && items[0]?.id !== item.id
+            ? "mt-1 border-t border-line"
+            : ""), children: _jsxs("span", { className: "flex w-full items-center justify-between gap-2", children: [_jsx("span", { className: "min-w-0 truncate font-medium", children: item.name }), item.id !== BROWSE_ALL || remaining === 0 ? null : (_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, query: query, locale: copy.locale })) }));
+    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, dependencies: [query], 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, dependencies: [query], 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, query, locale, }) {
     const Icon = item.icon;
-    return (_jsxs(_Fragment, { children: [marks ? (_jsx("span", { className: cn(hints ? "mt-0.5" : "", "flex size-(--size-icon-sm) shrink-0 items-center justify-center"), children: selected ? (_jsx(Check, { "aria-hidden": true, className: "size-(--size-icon-sm) text-primary forced-colors:text-[HighlightText]", strokeWidth: 2.5 })) : Icon !== undefined ? (_jsx(Icon, { "aria-hidden": true, className: "size-(--size-icon-sm) text-muted", strokeWidth: 1.75 })) : null })) : null, _jsxs("span", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [_jsxs("span", { className: "flex min-w-0 items-center gap-1.5", children: [_jsx(Text, { slot: "label", className: cn("min-w-0 truncate text-meta text-ink", selected ? "font-medium" : ""), children: item.name }), item.tags] }), item.meta === undefined ? null : (_jsx(Text, { slot: "description", className: "truncate text-micro tabular-nums text-muted", children: item.meta }))] }), !marks && selected ? (_jsx(Check, { "aria-hidden": true, className: "size-(--size-icon-sm) shrink-0 text-primary forced-colors:text-[HighlightText]", strokeWidth: 2.5 })) : null] }));
+    const copy = useUiCopy();
+    /* Listed for a code that is not drawn — the barcode, the NIT —: say which, or the row reads
+       as a wrong match. */
+    const hidden = query.trim() === "" ||
+        matches(item.name, query, locale) ||
+        (item.meta !== undefined && matches(item.meta, query, locale)) ||
+        item.haystack === undefined
+        ? null
+        : matchedWord(item.haystack, query, locale);
+    return (_jsxs(_Fragment, { children: [marks ? (_jsx("span", { className: cn(hints ? "mt-0.5" : "", "flex size-(--size-icon-sm) shrink-0 items-center justify-center"), children: selected ? (_jsx(Check, { "aria-hidden": true, className: "size-(--size-icon-sm) text-primary forced-colors:text-[HighlightText]", strokeWidth: 2.5 })) : Icon !== undefined ? (_jsx(Icon, { "aria-hidden": true, className: "size-(--size-icon-sm) text-muted", strokeWidth: 1.75 })) : null })) : null, item.avatar === undefined ? null : (_jsx(Avatar, { name: item.name, size: "sm", ...(typeof item.avatar === "string" ? { src: item.avatar } : {}) })), _jsxs("span", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [_jsxs("span", { className: "flex min-w-0 items-center gap-1.5", children: [_jsx(Text, { slot: "label", className: cn("min-w-0 truncate text-meta text-ink", selected ? "font-medium" : ""), children: _jsx(MatchedText, { text: item.name, query: query, locale: locale }) }), item.tags] }), item.meta === undefined ? null : (_jsx(Text, { slot: "description", className: "truncate text-micro tabular-nums text-muted", children: _jsx(MatchedText, { text: item.meta, query: query, locale: locale }) })), hidden === null ? null : (_jsxs("span", { className: "truncate text-micro text-muted", children: [copy.picker.matched, " ", _jsx("span", { className: "font-mono", children: _jsx(MatchedText, { text: hidden, query: query, locale: locale }) })] }))] }), item.aside === undefined ? null : (_jsx("span", { className: "flex shrink-0 items-center gap-1.5 self-center text-meta text-ink tabular-nums", children: item.aside })), !marks && selected ? (_jsx(Check, { "aria-hidden": true, className: "size-(--size-icon-sm) shrink-0 text-primary forced-colors:text-[HighlightText]", strokeWidth: 2.5 })) : null] }));
 }
 /** Hands the combobox's `close` to the code outside it: React Aria owns the open state and
- *  offers no controlled `isOpen`, and the «see all…» row has to close the list it lives in. */
+ *  offers no controlled `isOpen`, and the «Buscar más…» row has to close the list it lives in. */
 function CloseBridge({ into }) {
     const state = useContext(ComboBoxStateContext);
     into.current = state === null ? null : () => state.close();

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";