@cosmicdrift/kumiko-renderer 0.373.0 → 0.377.0

package/dist/web/primitives/embedded-list-input.js

@@ -0,0 +1,382 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// EmbeddedListInput — row/totals table for a createEmbeddedListField
+// (invoice-positions-style) field. Controlled: rows, derived values, and
+// issue groups are computed by the caller; this component only renders
+// and reports interaction (cell edits, row add/remove/duplicate/move,
+// paste).
+//
+// Only one of the two layouts (table for md+, cards below md) is mounted
+// at a time, picked via useIsNarrowViewport — mounting both and toggling
+// with `hidden`/`md:hidden` left two live inputs per cell sharing one DOM
+// id (#1854). The `hidden md:block` / `md:hidden` classes stay on the
+// wrapper divs as a defensive fallback (e.g. SSR/no-JS, where
+// getServerSnapshot forces the desktop layout) even though
+// useIsNarrowViewport — unlike the vendored useIsMobile it replaced —
+// already reports the correct value on the very first client render.
+//
+// ponytail: crossing the mobile/desktop breakpoint unmounts the active
+// layout and mounts the other, so an in-progress cell draft (uncommitted
+// MoneyInput text, IME composition) and focus are lost — accepted trade-off
+// for the single-mount-per-side fix above. Upgrade: lift per-cell draft
+// state into a `draftsByCellId` map here that survives the layout swap.
+import { ArrowDown, ArrowUp, Copy, Plus, Trash2 } from "lucide-react";
+import { Fragment, useEffect, useRef, useState, } from "react";
+import { applyFormatSpec } from "../../headless/index.js";
+import { useLocale, useTranslation } from "../../index.js";
+import { cn } from "../lib/cn.js";
+import { Button as UiButton } from "../ui/button.js";
+import { Checkbox } from "../ui/checkbox.js";
+import { Input as UiInput } from "../ui/input.js";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../ui/table.js";
+import { ComboboxInput } from "./combobox.js";
+import { DateInput } from "./date-input.js";
+import { formatMoney, MoneyInput } from "./money-input.js";
+import { SegmentedControl } from "./segmented-select.js";
+import { TimestampInput } from "./timestamp-input.js";
+import { useIsNarrowViewport } from "./use-narrow-viewport.js";
+// `input[type=hidden]` excluded — ComboboxInput renders one as a plain
+// name-carrier before its focusable trigger button.
+const FOCUSABLE_SELECTOR = "input:not([type=hidden]), button, [tabindex]";
+// Widths in rem include the cell's padding. Short-value columns are fixed so
+// the table's free width goes to the text/reference columns, which only
+// declare a floor (about 16 characters plus padding or a chevron).
+const FLEXIBLE_COLUMN_MIN_REM = 12;
+// Four size-7 icon buttons (duplicate, up, down, remove) plus the cell's px-1 and border.
+const ACTIONS_COLUMN_REM = 8.5;
+function fixedColumnRem(type) {
+    switch (type) {
+        case "number":
+        case "decimal":
+            return 7.5;
+        case "money":
+            return 10;
+        case "date":
+            return 10;
+        case "timestamp":
+            return 16;
+        case "boolean":
+            return 4;
+        case "select":
+            return 12;
+        case "text":
+        case "reference":
+            return undefined;
+        default: {
+            const exhaustiveCheck = type;
+            return exhaustiveCheck;
+        }
+    }
+}
+// Widths sit on <col>: in a table-fixed table they are the column widths, and the
+// columns without one (text/reference) are the ones that absorb the free width.
+function columnWidthStyle(type) {
+    const rem = fixedColumnRem(type);
+    return rem === undefined ? undefined : { width: `${rem}rem` };
+}
+// A table-fixed table distributes only the width beyond this sum; below it the
+// scroll container scrolls instead of squeezing columns.
+function tableMinWidthRem(columns, hasActions) {
+    const columnsRem = columns.reduce((sum, column) => sum + (fixedColumnRem(column.type) ?? FLEXIBLE_COLUMN_MIN_REM), 0);
+    return columnsRem + (hasActions ? ACTIONS_COLUMN_REM : 0);
+}
+function columnAlignClass(type) {
+    switch (type) {
+        case "money":
+        case "number":
+        case "decimal":
+            return "text-right";
+        case "boolean":
+            return "text-center";
+        case "date":
+        case "timestamp":
+        case "text":
+        case "select":
+        case "reference":
+            return "text-left";
+        default: {
+            const exhaustiveCheck = type;
+            return exhaustiveCheck;
+        }
+    }
+}
+// Exported (unlike columnWidthClass/columnAlignClass above) because
+// happy-dom performs no layout — scrollWidth/clientWidth/getBoundingClientRect
+// always read 0 in tests, so the only way to cover this decision at all is
+// as a pure function of the three scroll metrics, tested directly.
+// The 1px slack absorbs sub-pixel rounding from browser zoom/fractional
+// scaling, which would otherwise report a spurious sliver of "still
+// scrollable" at a fully-scrolled edge.
+export function computeScrollAffordance(scrollLeft, scrollWidth, clientWidth) {
+    return {
+        canScrollLeft: scrollLeft > 1,
+        canScrollRight: scrollLeft + clientWidth < scrollWidth - 1,
+    };
+}
+function formatTotalValue(total, columns, currency, locale) {
+    const column = columns.find((c) => c.field === total.field);
+    if (column?.type === "money")
+        return formatMoney(total.value, currency, locale);
+    return total.value.toLocaleString(locale);
+}
+// Tab/newline-delimited clipboard text → 2D string grid. Not a regex
+// parse — split on the literal delimiters, trim a trailing `\r` per line
+// (Windows clipboard line endings).
+function parsePasteGrid(text) {
+    return text.split("\n").map((line) => {
+        const withoutCr = line.endsWith("\r") ? line.slice(0, -1) : line;
+        return withoutCr.split("\t");
+    });
+}
+function IssueMessages({ issues, testId, constrainWidth, }) {
+    const t = useTranslation();
+    if (issues === undefined || issues.length === 0)
+        return null;
+    return (_jsx("div", { role: "alert", "data-testid": testId, className: cn("text-xs text-destructive", constrainWidth === true && "max-w-[16rem] whitespace-normal break-words"), children: issues.map((issue) => (_jsx("div", { children: t(issue.i18nKey, issue.params) }, `${issue.path}:${issue.code}`))) }));
+}
+function readOnlyCellText(column, value, currency, locale) {
+    if (value === null || value === undefined || value === "")
+        return "";
+    switch (column.type) {
+        case "boolean":
+            return value === true ? "✓" : "";
+        case "date":
+        case "timestamp":
+            return applyFormatSpec({ format: column.type, locale }, value);
+        case "number":
+        case "decimal":
+            return typeof value === "number"
+                ? applyFormatSpec({ format: column.type, locale }, value)
+                : String(value);
+        case "money":
+            return typeof value === "number" ? formatMoney(value, currency, locale) : String(value);
+        case "select":
+            return typeof value === "string" ? (column.optionLabels?.[value] ?? value) : String(value);
+        case "reference":
+            return typeof value === "string"
+                ? (column.referenceOptions?.find((o) => o.value === value)?.label ?? value)
+                : String(value);
+        case "text":
+            return String(value);
+        default: {
+            const exhaustiveCheck = column.type;
+            return exhaustiveCheck;
+        }
+    }
+}
+function renderCellControl({ cellId, column, label, value, disabled, onChange, currency, locale, }) {
+    if (column.readOnly === true && !column.derived) {
+        return (_jsx("div", { "data-cell-id": cellId, "data-readonly-cell": "", className: cn("min-w-0 whitespace-normal break-words py-1.5 text-sm", columnAlignClass(column.type)), children: readOnlyCellText(column, value, currency, locale) }));
+    }
+    const isDisabled = disabled || column.derived;
+    switch (column.type) {
+        case "text":
+            return (_jsx(UiInput, { "data-cell-id": cellId, type: "text", "aria-label": label, className: "min-w-0", disabled: isDisabled, value: typeof value === "string" ? value : "", onChange: (e) => onChange(e.target.value) }));
+        case "number":
+        case "decimal":
+            return (_jsx(UiInput, { "data-cell-id": cellId, type: "number", "aria-label": label, disabled: isDisabled, className: "min-w-0 text-right tabular-nums", value: typeof value === "number" ? value : "", onChange: (e) => {
+                    const raw = e.target.value;
+                    onChange(raw === "" ? undefined : Number(raw));
+                } }));
+        case "boolean":
+            return (_jsx("div", { className: "flex justify-center", children: _jsx(Checkbox, { "data-cell-id": cellId, "aria-label": label, disabled: isDisabled, checked: value === true, onCheckedChange: (checked) => onChange(checked === true) }) }));
+        case "date":
+            return (_jsx("div", { "data-cell-id": cellId, className: "w-full min-w-0", children: _jsx(DateInput, { id: cellId, name: cellId, ariaLabel: label, value: typeof value === "string" ? value : "", onChange: (v) => onChange(v), disabled: isDisabled }) }));
+        case "timestamp":
+            return (_jsx("div", { "data-cell-id": cellId, className: "w-full min-w-0", children: _jsx(TimestampInput, { id: cellId, name: cellId, ariaLabel: label, value: typeof value === "string" ? value : "", onChange: (v) => onChange(v), disabled: isDisabled }) }));
+        case "money":
+            return (_jsx("div", { "data-cell-id": cellId, className: "w-full min-w-0", children: _jsx(MoneyInput, { id: cellId, name: cellId, ariaLabel: label, value: typeof value === "number" ? value : "", onChange: (v) => onChange(v), currency: currency, disabled: isDisabled }) }));
+        case "select": {
+            const options = (column.options ?? []).map((opt) => ({
+                value: opt,
+                label: column.optionLabels?.[opt] ?? opt,
+            }));
+            if (column.display === "radio" && options.length > 0) {
+                return (_jsx("div", { "data-cell-id": cellId, className: "w-full min-w-0", children: _jsx(SegmentedControl, { id: cellId, name: cellId, labelProps: { "aria-label": label }, value: typeof value === "string" ? value : "", onChange: (v) => onChange(v), options: options, disabled: isDisabled }) }));
+            }
+            return (_jsx("div", { "data-cell-id": cellId, className: "w-full min-w-0", children: _jsx(ComboboxInput, { id: cellId, name: cellId, ariaLabel: label, value: typeof value === "string" ? value : "", onChange: (v) => onChange(v), options: options, disabled: isDisabled }) }));
+        }
+        case "reference":
+            return (_jsx("div", { "data-cell-id": cellId, className: "w-full min-w-0", children: _jsx(ComboboxInput, { id: cellId, name: cellId, ariaLabel: label, value: typeof value === "string" ? value : "", onChange: (v) => onChange(v), options: column.referenceOptions ?? [], disabled: isDisabled, loading: column.referenceLoading }) }));
+        default: {
+            const exhaustiveCheck = column.type;
+            return exhaustiveCheck;
+        }
+    }
+}
+function RowActions({ rowIndex, rowsLength, minItems, maxItems, onDuplicateRow, onMoveRow, onRemoveRow, duplicateLabel, moveUpLabel, moveDownLabel, removeLabel, testIdPrefix, buttonSizeClass = "size-7", }) {
+    const duplicateDisabled = maxItems !== undefined && rowsLength >= maxItems;
+    const removeDisabled = rowsLength <= (minItems ?? 0);
+    return (_jsxs("div", { className: "inline-flex items-center", children: [_jsx(UiButton, { type: "button", variant: "ghost", size: "icon", className: buttonSizeClass, "aria-label": duplicateLabel, disabled: duplicateDisabled, onClick: () => onDuplicateRow(rowIndex), "data-testid": testIdPrefix !== undefined ? `${testIdPrefix}-duplicate` : undefined, children: _jsx(Copy, { className: "size-4", "aria-hidden": "true" }) }), _jsx(UiButton, { type: "button", variant: "ghost", size: "icon", className: buttonSizeClass, "aria-label": moveUpLabel, disabled: rowIndex === 0, onClick: () => onMoveRow(rowIndex, rowIndex - 1), "data-testid": testIdPrefix !== undefined ? `${testIdPrefix}-move-up` : undefined, children: _jsx(ArrowUp, { className: "size-4", "aria-hidden": "true" }) }), _jsx(UiButton, { type: "button", variant: "ghost", size: "icon", className: buttonSizeClass, "aria-label": moveDownLabel, disabled: rowIndex === rowsLength - 1, onClick: () => onMoveRow(rowIndex, rowIndex + 1), "data-testid": testIdPrefix !== undefined ? `${testIdPrefix}-move-down` : undefined, children: _jsx(ArrowDown, { className: "size-4", "aria-hidden": "true" }) }), _jsx(UiButton, { type: "button", variant: "ghost", size: "icon", className: buttonSizeClass, "aria-label": removeLabel, disabled: removeDisabled, onClick: () => onRemoveRow(rowIndex), "data-testid": testIdPrefix !== undefined ? `${testIdPrefix}-remove` : undefined, children: _jsx(Trash2, { className: "size-4", "aria-hidden": "true" }) })] }));
+}
+export function EmbeddedListInput({ id, columns, rows, totals, currency, disabled, fixedRows, minItems, maxItems, listIssues, rowIssues, cellIssues, onCellChange, onAddRow, onRemoveRow, onDuplicateRow, onMoveRow, onPasteCells, addLabel, actionsLabel, removeLabel, duplicateLabel, moveUpLabel, moveDownLabel, emptyLabel, emptyCtaLabel, testId, }) {
+    // Callers that don't wire up the field-currency plumbing (or direct
+    // callers/tests that predate #1839) keep getting the same "EUR" this
+    // component always hardcoded.
+    const effectiveCurrency = currency ?? "EUR";
+    const t = useTranslation();
+    const cellLabel = (column, rowIndex) => t("kumiko.field.embedded-list.cell-label", { column: column.label, row: rowIndex + 1 });
+    const resolvedLocale = useLocale().locale();
+    const isMobile = useIsNarrowViewport();
+    const containerRef = useRef(null);
+    const [pendingFocusCellId, setPendingFocusCellId] = useState(undefined);
+    const [scrollAffordance, setScrollAffordance] = useState({
+        canScrollLeft: false,
+        canScrollRight: false,
+    });
+    // A callback ref (not useRef) so the setup effect below re-runs exactly
+    // when the scroll container itself is attached/detached — isMobile flips
+    // the whole subtree between mobile cards and this table (see the
+    // ponytail note at the top of the file), so a plain useRef wouldn't
+    // notice the desktop table remounting with a fresh DOM node.
+    const [scrollContainerEl, setScrollContainerEl] = useState(null);
+    // Resetting scrollLeft here is what guarantees the table always opens
+    // scrolled fully left (fw#2159): browsers still auto-scroll a focused
+    // descendant into view even inside an overflow-x-auto container, but
+    // that's now a real, user-drivable scroll instead of an invisible one.
+    useEffect(() => {
+        if (scrollContainerEl === null)
+            return;
+        const el = scrollContainerEl;
+        el.scrollLeft = 0;
+        const updateAffordance = () => {
+            setScrollAffordance(computeScrollAffordance(el.scrollLeft, el.scrollWidth, el.clientWidth));
+        };
+        updateAffordance();
+        el.addEventListener("scroll", updateAffordance);
+        const resizeObserver = new ResizeObserver(updateAffordance);
+        resizeObserver.observe(el);
+        return () => {
+            el.removeEventListener("scroll", updateAffordance);
+            resizeObserver.disconnect();
+        };
+    }, [scrollContainerEl]);
+    // React 19 batches the setPendingFocusCellId + onAddRow calls from the
+    // same keydown handler into one commit, so the new row already exists
+    // by the time this effect runs — no need to depend on rows.length too.
+    useEffect(() => {
+        if (pendingFocusCellId === undefined)
+            return;
+        // ponytail: capability-scoped DOM query, not a global — degrades to
+        // "no auto-focus" on a hypothetical native impl instead of crashing.
+        // `data-cell-id` sits on the focusable control itself for text/boolean
+        // cells, but on a non-focusable wrapper `<div>` for date/money/select/
+        // reference/timestamp cells (see renderCellControl) — walk into the
+        // wrapper for its focusable descendant instead of calling .focus() on
+        // a div. `input[type=hidden]` excluded: ComboboxInput (select/reference)
+        // renders a hidden name-carrier input before its trigger button — it
+        // would otherwise win the "first match in document order" query
+        // without ever actually receiving focus.
+        const matched = containerRef.current?.querySelector(`[data-cell-id="${pendingFocusCellId}"]`);
+        const target = matched?.matches(FOCUSABLE_SELECTOR)
+            ? matched
+            : (matched?.querySelector(FOCUSABLE_SELECTOR) ?? matched);
+        target?.focus();
+        setPendingFocusCellId(undefined);
+    }, [pendingFocusCellId]);
+    const cellId = (rowIndex, field) => `${id}-${rowIndex}-${field}`;
+    // handleLastCellKeyDown must attach to the last EDITABLE column, not
+    // columns.length - 1 — a derived column there is rendered disabled
+    // (renderCellControl) and never receives focus/keydown, which would
+    // silently kill Tab/Enter-appends-a-row whenever the table ends in a
+    // derived column (e.g. a trailing "amount" total).
+    const lastEditableIndex = columns.findLastIndex((column) => !column.derived && column.readOnly !== true);
+    // Fixed rows drop every row-mutation affordance but leave cells editable.
+    const showControls = disabled !== true && fixedRows !== true;
+    // The pinned actions column marks its edge with an inset shadow: in a
+    // border-collapse table a border-l is painted at the cell's unscrolled
+    // position and vanishes while content scrolls underneath.
+    const isHorizontallyScrollable = scrollAffordance.canScrollLeft || scrollAffordance.canScrollRight;
+    const addDisabled = maxItems !== undefined && rows.length >= maxItems;
+    const handlePaste = (rowIndex, columnIndex) => {
+        return (event) => {
+            if (onPasteCells === undefined)
+                return;
+            if (disabled === true)
+                return;
+            const text = event.clipboardData?.getData("text") ?? "";
+            const grid = parsePasteGrid(text);
+            const isMultiCell = grid.length > 1 || (grid[0]?.length ?? 0) > 1;
+            if (!isMultiCell)
+                return;
+            event.preventDefault();
+            onPasteCells(rowIndex, columnIndex, grid);
+        };
+    };
+    const handleLastCellKeyDown = (event) => {
+        if (disabled === true || fixedRows === true)
+            return;
+        const isTabForward = event.key === "Tab" && !event.shiftKey;
+        const isEnter = event.key === "Enter";
+        if (!isTabForward && !isEnter)
+            return;
+        // A select/reference last column renders its picker trigger as a
+        // <button> (or an open cmdk popover's own input) in the cell — Enter
+        // there is the browser's native button-activation, not "append a row".
+        // Returning before preventDefault() lets that activation proceed;
+        // Tab still falls through to the append-row behavior below.
+        if (isEnter &&
+            event.target instanceof HTMLElement &&
+            event.target.closest('button, [role="combobox"], [cmdk-input]') !== null) {
+            return;
+        }
+        if (maxItems !== undefined && rows.length >= maxItems)
+            return;
+        // Enter bubbles up from the cell control through this TableCell — an
+        // ancestor of any <form> the caller wraps the whole field in.
+        // preventDefault() during the bubble phase still stops that form's
+        // default submit, same as it stops Tab's default focus-move below.
+        event.preventDefault();
+        // readOnly cells render a non-focusable div, so focusing columns[0] would drop focus.
+        const firstColumn = columns.find((c) => c.derived !== true && c.readOnly !== true);
+        if (firstColumn !== undefined) {
+            setPendingFocusCellId(cellId(rows.length, firstColumn.field));
+        }
+        onAddRow();
+    };
+    const testIdFor = (suffix) => testId !== undefined ? `${testId}-${suffix}` : undefined;
+    if (rows.length === 0) {
+        return (_jsxs("div", { ref: containerRef, "data-testid": testId !== undefined ? `${testId}-empty` : "embedded-list-empty", className: "flex flex-col items-center justify-center gap-3 rounded-lg border border-dashed p-10 text-center text-sm text-muted-foreground", children: [_jsx("span", { children: emptyLabel }), showControls && (_jsxs(UiButton, { type: "button", variant: "outline", size: "sm", onClick: onAddRow, "data-testid": testId !== undefined ? `${testId}-empty-add` : "embedded-list-empty-add", children: [_jsx(Plus, { className: "size-4", "aria-hidden": "true" }), emptyCtaLabel] }))] }));
+    }
+    const hasTotals = totals !== undefined && totals.length > 0;
+    return (_jsxs("div", { ref: containerRef, "data-testid": testId, className: "min-w-0", children: [!isMobile && (_jsxs("div", { "data-testid": testIdFor("desktop"), className: "hidden min-w-0 md:block", children: [_jsxs("div", { className: "min-w-0 overflow-hidden rounded-lg border bg-card", children: [_jsxs("div", { className: "relative min-w-0", children: [_jsx("div", { ref: setScrollContainerEl, "data-testid": testIdFor("desktop-scroll"), className: "overflow-x-auto [&_[data-slot=table-container]]:overflow-x-visible", children: _jsxs(Table, { className: "w-full table-fixed", style: { minWidth: `${tableMinWidthRem(columns, showControls)}rem` }, children: [_jsxs("colgroup", { children: [columns.map((column) => (_jsx("col", { style: columnWidthStyle(column.type) }, column.field))), showControls && _jsx("col", { style: { width: `${ACTIONS_COLUMN_REM}rem` } })] }), _jsx(TableHeader, { className: "bg-muted", children: _jsxs(TableRow, { className: "hover:bg-transparent", children: [columns.map((column) => (_jsx(TableHead, { title: column.label, className: cn("truncate", columnAlignClass(column.type)), children: column.label }, column.field))), showControls && (_jsx(TableHead, { className: cn("sticky right-0 z-10 whitespace-nowrap bg-muted px-1 text-right", isHorizontallyScrollable &&
+                                                                    "shadow-[inset_1px_0_0_var(--color-border)]"), "aria-label": actionsLabel }))] }) }), _jsx(TableBody, { children: rows.map((row, rowIndex) => {
+                                                        const isLastRow = rowIndex === rows.length - 1;
+                                                        const rowIssuesForRow = rowIssues?.[rowIndex];
+                                                        return (_jsxs(Fragment
+                                                        // biome-ignore lint/suspicious/noArrayIndexKey: rows have no caller-guaranteed stable id; every cell is fully controlled (value+onChange), so reordering doesn't rely on DOM node identity surviving between renders.
+                                                        , { children: [_jsxs(TableRow, { className: "group", "data-testid": testIdFor(`row-${rowIndex}`), children: [columns.map((column, columnIndex) => {
+                                                                            const isLastCell = isLastRow && columnIndex === lastEditableIndex;
+                                                                            const issues = cellIssues?.[`${rowIndex}.${column.field}`];
+                                                                            return (_jsxs(TableCell, { "data-testid": testIdFor(`cell-${rowIndex}-${column.field}`), onPaste: onPasteCells !== undefined
+                                                                                    ? handlePaste(rowIndex, columnIndex)
+                                                                                    : undefined, onKeyDown: isLastCell ? handleLastCellKeyDown : undefined, children: [renderCellControl({
+                                                                                        cellId: cellId(rowIndex, column.field),
+                                                                                        label: cellLabel(column, rowIndex),
+                                                                                        column,
+                                                                                        value: row[column.field],
+                                                                                        disabled: disabled === true,
+                                                                                        onChange: (value) => onCellChange(rowIndex, column.field, value),
+                                                                                        currency: effectiveCurrency,
+                                                                                        locale: resolvedLocale,
+                                                                                    }), _jsx(IssueMessages, { issues: issues, testId: testIdFor(`cell-${rowIndex}-${column.field}-errors`), constrainWidth: true })] }, column.field));
+                                                                        }), showControls && (_jsx(TableCell, { className: cn("sticky right-0 z-10 whitespace-nowrap bg-card px-1 text-right group-hover:bg-muted", isHorizontallyScrollable &&
+                                                                                "shadow-[inset_1px_0_0_var(--color-border)]"), children: _jsx(RowActions, { rowIndex: rowIndex, rowsLength: rows.length, minItems: minItems, maxItems: maxItems, onDuplicateRow: onDuplicateRow, onMoveRow: onMoveRow, onRemoveRow: onRemoveRow, duplicateLabel: duplicateLabel, moveUpLabel: moveUpLabel, moveDownLabel: moveDownLabel, removeLabel: removeLabel, testIdPrefix: testIdFor(`row-${rowIndex}`) }) }))] }), rowIssuesForRow !== undefined && rowIssuesForRow.length > 0 && (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: columns.length + (showControls ? 1 : 0), children: _jsx(IssueMessages, { issues: rowIssuesForRow, testId: testIdFor(`row-${rowIndex}-issues`) }) }) }))] }, rowIndex));
+                                                    }) })] }) }), scrollAffordance.canScrollLeft && (_jsx("div", { "aria-hidden": "true", className: "pointer-events-none absolute inset-y-0 left-0 w-6 bg-gradient-to-r from-card to-transparent" })), scrollAffordance.canScrollRight && !showControls && (_jsx("div", { "aria-hidden": "true", className: "pointer-events-none absolute inset-y-0 right-0 w-6 bg-gradient-to-l from-card to-transparent" }))] }), showControls && (_jsx("div", { className: "border-t p-2", children: _jsxs(UiButton, { type: "button", variant: "ghost", size: "sm", onClick: onAddRow, disabled: addDisabled, "data-testid": testIdFor("add"), children: [_jsx(Plus, { className: "size-4", "aria-hidden": "true" }), addLabel] }) })), hasTotals && (_jsx("div", { "data-testid": testIdFor("totals"), className: "flex flex-wrap items-center justify-end gap-6 border-t bg-muted/30 px-4 py-3 text-sm", children: totals.map((total) => (_jsxs("div", { className: "flex items-baseline gap-2", children: [_jsx("span", { className: "text-muted-foreground", children: total.label }), _jsx("span", { className: "font-medium tabular-nums", children: formatTotalValue(total, columns, effectiveCurrency, resolvedLocale) })] }, total.field))) }))] }), _jsx(IssueMessages, { issues: listIssues, testId: testIdFor("list-issues") })] })), isMobile && (_jsxs("div", { "data-testid": testIdFor("mobile"), className: "md:hidden flex flex-col gap-3", children: [rows.map((row, rowIndex) => {
+                        const isLastRow = rowIndex === rows.length - 1;
+                        const rowIssuesForRow = rowIssues?.[rowIndex];
+                        return (_jsxs("div", { "data-testid": testIdFor(`row-${rowIndex}`), className: "flex flex-col gap-3 rounded-lg border bg-card p-4", children: [columns.map((column, columnIndex) => {
+                                    const isLastCell = isLastRow && columnIndex === lastEditableIndex;
+                                    const issues = cellIssues?.[`${rowIndex}.${column.field}`];
+                                    return (_jsxs("div", { className: "flex flex-col gap-1", onPaste: onPasteCells !== undefined ? handlePaste(rowIndex, columnIndex) : undefined, onKeyDown: isLastCell ? handleLastCellKeyDown : undefined, children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground", children: column.label }), renderCellControl({
+                                                cellId: cellId(rowIndex, column.field),
+                                                label: cellLabel(column, rowIndex),
+                                                column,
+                                                value: row[column.field],
+                                                disabled: disabled === true,
+                                                onChange: (value) => onCellChange(rowIndex, column.field, value),
+                                                currency: effectiveCurrency,
+                                                locale: resolvedLocale,
+                                            }), _jsx(IssueMessages, { issues: issues, testId: testIdFor(`cell-${rowIndex}-${column.field}-errors`) })] }, column.field));
+                                }), rowIssuesForRow !== undefined && rowIssuesForRow.length > 0 && (_jsx(IssueMessages, { issues: rowIssuesForRow, testId: testIdFor(`row-${rowIndex}-issues`) })), showControls && (_jsx("div", { className: "flex items-center justify-end gap-1 border-t pt-3", children: _jsx(RowActions, { rowIndex: rowIndex, rowsLength: rows.length, minItems: minItems, maxItems: maxItems, onDuplicateRow: onDuplicateRow, onMoveRow: onMoveRow, onRemoveRow: onRemoveRow, duplicateLabel: duplicateLabel, moveUpLabel: moveUpLabel, moveDownLabel: moveDownLabel, removeLabel: removeLabel, testIdPrefix: testIdFor(`row-${rowIndex}`), buttonSizeClass: "size-10" }) }))] }, rowIndex));
+                    }), showControls && (_jsxs(UiButton, { type: "button", variant: "outline", onClick: onAddRow, disabled: addDisabled, "data-testid": testIdFor("add"), children: [_jsx(Plus, { className: "size-4", "aria-hidden": "true" }), addLabel] })), hasTotals && (_jsx("div", { "data-testid": testIdFor("totals"), className: "flex flex-col gap-2 rounded-lg border bg-muted/30 p-4 text-sm", children: totals.map((total) => (_jsxs("div", { className: "flex items-center justify-between", children: [_jsx("span", { className: "text-muted-foreground", children: total.label }), _jsx("span", { className: "font-medium tabular-nums", children: formatTotalValue(total, columns, effectiveCurrency, resolvedLocale) })] }, total.field))) })), _jsx(IssueMessages, { issues: listIssues, testId: testIdFor("list-issues") })] }))] }));
+}

package/dist/web/primitives/file-thumbnail.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from "react";
+import type { ListColumnFileDisplay } from "../../headless/index.ts";
+export declare function fileOriginalUrl(fileId: string): string;
+export declare function fileVariantUrl(fileId: string, variant: string): string;
+export declare function FileThumbnail({ fileId, variant, className, testId, }: {
+    readonly fileId: string;
+    readonly variant?: string;
+    readonly className?: string;
+    readonly testId?: string;
+}): ReactNode;
+export declare function FileNameLink({ fileId, fallbackLabel, className, }: {
+    readonly fileId: string;
+    readonly fallbackLabel: string;
+    readonly className?: string;
+}): ReactNode;
+export declare function CardLeadingImage({ value, display, }: {
+    readonly value: unknown;
+    readonly display: ListColumnFileDisplay;
+}): ReactNode;
+export declare function FileDisplayCell({ value, display, fallbackLabel, compact, }: {
+    readonly value: unknown;
+    readonly display: ListColumnFileDisplay;
+    readonly fallbackLabel: string;
+    readonly compact?: boolean;
+}): ReactNode;

package/dist/web/primitives/file-thumbnail.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
+import { ImageIcon } from "lucide-react";
+import { useEffect, useState } from "react";
+import { cn } from "../lib/cn.js";
+// Stored values are untrusted: only UUIDs reach a request, and path segments are
+// encoded so an id like "../x" or "a?b" cannot redirect the request.
+export function fileOriginalUrl(fileId) {
+    return `/api/files/${encodeURIComponent(fileId)}`;
+}
+export function fileVariantUrl(fileId, variant) {
+    return `${fileOriginalUrl(fileId)}/variant/${encodeURIComponent(variant)}`;
+}
+function thumbnailSources(fileId, variant) {
+    if (!isUuid(fileId))
+        return [];
+    return variant === undefined
+        ? [fileOriginalUrl(fileId)]
+        : [fileVariantUrl(fileId, variant), fileOriginalUrl(fileId)];
+}
+// A declared variant can 404 when the upload carried no entityType/fieldName
+// (the variant is resolved per field), while the original always serves. So the
+// chain is variant -> original -> placeholder instead of a broken-image icon.
+function ThumbnailChain({ fileId, variant, className, testId, }) {
+    const sources = thumbnailSources(fileId, variant);
+    const [failedCount, setFailedCount] = useState(0);
+    const src = sources[failedCount];
+    if (src === undefined) {
+        return (_jsx("div", { "data-testid": testId, className: cn("bg-muted text-muted-foreground flex items-center justify-center rounded-md border", className), children: _jsx(ImageIcon, { className: "size-1/3" }) }));
+    }
+    return (_jsx("img", { src: src, alt: "", "data-testid": testId, onError: () => setFailedCount((n) => n + 1), className: cn("bg-muted rounded-md border object-contain", className) }));
+}
+export function FileThumbnail({ fileId, variant, className = "h-24 w-32", testId, }) {
+    return (_jsx(ThumbnailChain, { fileId: fileId, variant: variant, className: className, testId: testId }, `${fileId}:${variant ?? ""}`));
+}
+function isFileMeta(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "fileName" in value &&
+        typeof value.fileName === "string");
+}
+export function FileNameLink({ fileId, fallbackLabel, className, }) {
+    const [fileName, setFileName] = useState(null);
+    const validId = isUuid(fileId);
+    useEffect(() => {
+        let cancelled = false;
+        setFileName(null);
+        if (!validId)
+            return;
+        fetch(`${fileOriginalUrl(fileId)}/meta`)
+            .then((res) => (res.ok ? res.json() : null))
+            .then((meta) => {
+            if (!cancelled && isFileMeta(meta))
+                setFileName(meta.fileName);
+        })
+            .catch(() => { });
+        return () => {
+            cancelled = true;
+        };
+    }, [fileId, validId]);
+    if (!validId)
+        return _jsx("span", { className: cn("text-sm", className), children: fallbackLabel });
+    return (_jsx("a", { href: fileOriginalUrl(fileId), target: "_blank", rel: "noreferrer", className: cn("text-sm underline underline-offset-2", className), children: fileName ?? fallbackLabel }));
+}
+function fileIdsOf(value) {
+    if (typeof value === "string")
+        return value === "" ? [] : [value];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "string" && entry !== "");
+}
+// Height-bound, width follows the aspect ratio within a clamp, so a portrait and
+// a landscape photo both read as a preview without stretching the column.
+const TABLE_THUMBNAIL_CLASS = "h-16 min-w-16 max-w-24 object-cover";
+// A card's meta line is one text line (h-5) tall.
+const CARD_THUMBNAIL_CLASS = "size-5 rounded-sm object-cover";
+const CARD_LEADING_CLASS = "size-14 shrink-0 rounded-md object-cover";
+// Leading preview of a narrow list card: the card's own image, not a meta chip.
+export function CardLeadingImage({ value, display, }) {
+    const [first] = fileIdsOf(value);
+    if (first === undefined || display.kind !== "image")
+        return null;
+    return (_jsx(FileThumbnail, { fileId: first, className: CARD_LEADING_CLASS, ...(display.variant !== undefined && { variant: display.variant }) }));
+}
+export function FileDisplayCell({ value, display, fallbackLabel, compact = false, }) {
+    const [first, ...rest] = fileIdsOf(value);
+    if (first === undefined)
+        return null;
+    return (_jsxs("span", { className: "inline-flex items-center gap-2", children: [display.kind === "image" ? (_jsx(FileThumbnail, { fileId: first, className: compact ? CARD_THUMBNAIL_CLASS : TABLE_THUMBNAIL_CLASS, ...(display.variant !== undefined && { variant: display.variant }) })) : (_jsx(FileNameLink, { fileId: first, fallbackLabel: fallbackLabel })), rest.length > 0 && _jsxs("span", { className: "text-muted-foreground text-xs", children: ["+", rest.length] })] }));
+}

package/dist/web/primitives/file-upload.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from "react";
+export type FileUploadInputProps = {
+    readonly kind: "file" | "image";
+    readonly id: string;
+    readonly value: string | null;
+    readonly onChange: (fileId: string | null) => void;
+    readonly accept?: readonly string[];
+    readonly disabled?: boolean;
+    readonly entityType?: string;
+    readonly entityId?: string;
+    readonly fieldName?: string;
+    readonly imageVariant?: string;
+    readonly capture?: "environment" | "user";
+    /** Folder picker (web-only, `webkitdirectory`): hands the picked files with
+     *  `webkitRelativePath` to `onFilesPicked` and uploads nothing. */
+    readonly directory?: boolean;
+    readonly onFilesPicked?: (files: readonly File[]) => void;
+    readonly pickLabel?: string;
+    readonly testId?: string;
+};
+export declare function FileUploadInput({ kind, id, value, onChange, accept, disabled, entityType, entityId, fieldName, imageVariant, capture, directory, onFilesPicked, pickLabel, testId, }: FileUploadInputProps): ReactNode;

package/dist/web/primitives/file-upload.js

@@ -0,0 +1,56 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// File/image upload widget for the auto-edit form. Uploads via multipart POST
+// to /api/files (mounted by the stack when a storageProvider is set), gets the
+// FileRef UUID back and lifts it up as the field value. Image → uncropped
+// rectangular preview (GET /api/files/:id, or the declared variant), file →
+// file name link. A disabled input shows the value only, without controls.
+import { ImageIcon, Loader2, Upload } from "lucide-react";
+import { useRef, useState } from "react";
+import { useTranslation } from "../../index.js";
+import { toAcceptAttr } from "../lib/accept-attr.js";
+import { resizeImageBeforeUpload } from "../lib/resize-image.js";
+import { FileUploadFailedError, uploadFileRef } from "../lib/upload-file-ref.js";
+import { Button as UiButton } from "../ui/button.js";
+import { FileNameLink, FileThumbnail } from "./file-thumbnail.js";
+// React's input typings have no `webkitdirectory`; spreading keeps it typed-cast-free.
+const DIRECTORY_INPUT_ATTRS = { webkitdirectory: "", multiple: true };
+export function FileUploadInput({ kind, id, value, onChange, accept, disabled, entityType, entityId, fieldName, imageVariant, capture, directory, onFilesPicked, pickLabel, testId, }) {
+    const t = useTranslation();
+    const inputRef = useRef(null);
+    const [uploading, setUploading] = useState(false);
+    const [error, setError] = useState(null);
+    async function onPick(e) {
+        if (directory === true) {
+            onFilesPicked?.(Array.from(e.target.files ?? []));
+            if (inputRef.current)
+                inputRef.current.value = "";
+            return;
+        }
+        const file = e.target.files?.[0];
+        if (file === undefined)
+            return;
+        setUploading(true);
+        setError(null);
+        try {
+            const uploadFile = await resizeImageBeforeUpload(file);
+            onChange(await uploadFileRef(uploadFile, { entityType, entityId, fieldName }));
+        }
+        catch (error) {
+            setError(error instanceof FileUploadFailedError && error.fromServer
+                ? error.message
+                : t("kumiko.field.file-upload.failed"));
+        }
+        finally {
+            setUploading(false);
+            // Clear the input so re-picking the SAME file still fires change — the
+            // browser suppresses the event otherwise (no-op in jsdom, real-browser).
+            if (inputRef.current)
+                inputRef.current.value = "";
+        }
+    }
+    const acceptAttr = toAcceptAttr(accept);
+    return (_jsxs("div", { className: "flex items-center gap-4", children: [kind === "image" && value !== null && (_jsx(FileThumbnail, { fileId: value, ...(imageVariant !== undefined && { variant: imageVariant }) })), kind === "image" && value === null && (_jsx("div", { className: "bg-muted text-muted-foreground flex h-24 w-32 items-center justify-center rounded-md border", children: _jsx(ImageIcon, { className: "size-6" }) })), kind === "file" && value !== null && (_jsx(FileNameLink, { fileId: value, fallbackLabel: t("kumiko.field.file-upload.attached") })), _jsx("input", { ref: inputRef, id: id, ...(testId !== undefined && { "data-testid": `${testId}-input` }), type: "file", className: "hidden", ...(acceptAttr !== undefined && { accept: acceptAttr }), ...(capture !== undefined && { capture }), ...(directory === true && DIRECTORY_INPUT_ATTRS), onChange: (e) => void onPick(e), disabled: disabled }), disabled !== true && (_jsxs(_Fragment, { children: [_jsxs(UiButton, { type: "button", variant: "outline", size: "sm", disabled: uploading, onClick: () => inputRef.current?.click(), ...(testId !== undefined && { "data-testid": `${testId}-pick` }), children: [uploading ? (_jsx(Loader2, { className: "size-4 animate-spin" })) : (_jsx(Upload, { className: "size-4" })), pickLabel ??
+                                (value !== null
+                                    ? t("kumiko.field.file-upload.change")
+                                    : t("kumiko.field.file-upload.upload"))] }), value !== null && (_jsx(UiButton, { type: "button", variant: "ghost", size: "sm", onClick: () => onChange(null), children: t("kumiko.field.file-upload.remove") }))] })), error !== null && _jsx("span", { className: "text-destructive text-xs", children: error })] }));
+}

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

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+import { applyFormatSpec } from "../../headless/index.ts";
+import { type CardProps, type CorePrimitives, type FormWidth } from "../../index.ts";
+import "../react-css-custom-properties.ts";
+export declare const END_LABEL_MIN_ROWS = 50;
+export declare function isComponentRendererRef(renderer: unknown): {
+    readonly name: string;
+} | undefined;
+export { applyFormatSpec };
+export declare function defaultCellRender(value: unknown, type: string, optionLabels?: Readonly<Record<string, string>>, locale?: string, columnKey?: string, grouping?: boolean): string;
+export declare function EmbeddedFormProvider({ children }: {
+    children: ReactNode;
+}): ReactNode;
+export declare function BareFormProvider({ children }: {
+    children: ReactNode;
+}): ReactNode;
+export declare function ScreenWidthProvider({ width, children, }: {
+    readonly width: FormWidth | undefined;
+    readonly children: ReactNode;
+}): ReactNode;
+export type FormScreenShellWidth = FormWidth;
+export declare function FormScreenShell({ children, className, testId, maxWidth, fillHeight, }: {
+    readonly children: ReactNode;
+    readonly className?: string;
+    readonly testId?: string;
+    readonly maxWidth?: FormScreenShellWidth;
+    /** Stacks children in a `h-full` flex column instead of normal document
+     *  flow, so a `flex-1 min-h-0` child can claim the remaining height below
+     *  the others (fw#2722 — DefaultForm's tabs+relatedList case). Default
+     *  false: unchanged, content-sized height. */
+    readonly fillHeight?: boolean;
+}): ReactNode;
+export declare function DefaultCard({ slots, options, className, testId, dataAttributes, children, }: CardProps): ReactNode;
+export declare const defaultPrimitives: CorePrimitives;