@sincpro/web-ui 1.6.0 → 1.7.1

package/dist/components/attachments/Attachments.d.ts

@@ -0,0 +1,56 @@
+import { type FormMode } from "../../foundations/form.js";
+export type AttachmentStatus = "ready" | "uploading" | "failed";
+export type AttachmentFile = {
+    /** The attachment's identity: the server's id, or a local key while it uploads. */
+    id: string;
+    /** The file name as it was saved: «Factura proveedor 0418.pdf». */
+    name: string;
+    /** In bytes. Written in the copy's locale: «1,2 MB». */
+    size?: number;
+    /** The MIME type, when the server knows it. With the name, it picks the icon. */
+    type?: string;
+    /** Where it downloads from. Absent = no download (still uploading, or not allowed). */
+    url?: string;
+    /** A small image for the thumbnail. Defaults to `url` for an image — pass a smaller one
+     *  when the server has it, so a list of 4 MB photos does not load 4 MB photos. */
+    thumbnail?: string;
+    /** Who added it. */
+    by?: string;
+    /** Their face, for the chip. */
+    byAvatar?: string;
+    /** When it was added. */
+    at?: Date | string | number;
+    /** `ready` by default. The application owns it: it is what the upload is really doing. */
+    status?: AttachmentStatus;
+    /** 0 to 100 while `uploading`. Absent = under way without a figure yet. */
+    progress?: number;
+    /** Why it `failed`, in the server's words. */
+    error?: string;
+};
+export type AttachmentsProps = {
+    files: readonly AttachmentFile[];
+    /** Files to add: dropped, pasted or chosen. Present = the drop zone is drawn (in edit
+     *  mode). The application uploads them and puts them in `files` as `uploading`. */
+    onAdd?: (files: File[]) => void;
+    /** A file was removed. It is gone at once; the notice offers to undo it. */
+    onRemove?: (file: AttachmentFile) => void;
+    /** Put a removed file back where it was. Without it the notice has no «Deshacer». */
+    onRestore?: (file: AttachmentFile, index: number) => void;
+    /** Open the file. Present = its name is a button; WHERE it opens is the application's. */
+    onOpen?: (file: AttachmentFile) => void;
+    /** Try a failed upload again. Present = a failed file offers «Reintentar». */
+    onRetry?: (file: AttachmentFile) => void;
+    /** The browser's `accept` list for the file dialog (`".pdf,image/*"`). */
+    accept?: string;
+    /** `read` for a record that can no longer change. By default, the form's mode. */
+    mode?: FormMode;
+    /** The accessible name of the list. «Adjuntos» by default. */
+    label?: string;
+    /** What an empty list says, when the screen can say something closer to its domain:
+     *  «Esta compra todavía no tiene la factura del proveedor». */
+    empty?: string;
+    /** The «now» the dates are relative to — so a story or a test does not change its
+     *  text every minute. */
+    now?: Date;
+};
+export declare function Attachments({ files, onAdd, onRemove, onRestore, onOpen, onRetry, accept, mode, label, empty, now, }: AttachmentsProps): import("react").JSX.Element;

package/dist/components/attachments/Attachments.js

@@ -0,0 +1,93 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { attachmentKind, fileExtension, formatFileSize, } from "./files.js";
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { useFormMode } from "../../foundations/form.js";
+import { Button, IconButton, IconLink } from "../../primitives/button/Button.js";
+import { DropZone } from "../../primitives/field/DropZone.js";
+import { Empty } from "../../primitives/notice/Notice.js";
+import { useToastIfAny } from "../../primitives/notice/Toast.js";
+import { DateValue } from "../../primitives/value/DateValue.js";
+import { UserChip } from "../../primitives/value/Person.js";
+import { ProgressBar } from "../../primitives/value/ProgressBar.js";
+import { Download, File, FileImage, FileSpreadsheet, FileText, FileType, RotateCcw, Trash2, TriangleAlert, X, } from "lucide-react";
+import { useEffect, useId, useRef } from "react";
+const KIND_ICON = {
+    image: FileImage,
+    pdf: FileText,
+    sheet: FileSpreadsheet,
+    doc: FileType,
+    other: File,
+};
+/** The type, at the size of a row: the image itself when there is one, otherwise the icon
+ *  of its kind over its extension. The extension is written because three of the five
+ *  icons are a page with lines on it — «PDF» and «DOCX» are what tell them apart, and a
+ *  word is never a colour that only some people see. */
+function Thumb({ file, kind }) {
+    const picture = kind === "image" && file.status !== "failed" ? (file.thumbnail ?? file.url) : undefined;
+    const Icon = KIND_ICON[kind];
+    const extension = fileExtension(file.name).slice(0, 4);
+    return (
+    /* Decorative: the name next to it says which file it is, and the image's `alt` would
+       say it twice. */
+    _jsx("span", { "aria-hidden": true, className: "flex size-(--size-control-lg) shrink-0 flex-col items-center justify-center gap-0.5 overflow-clip rounded-control border border-line bg-ink/4 text-muted", children: picture === undefined ? (_jsxs(_Fragment, { children: [_jsx(Icon, { className: "size-(--size-icon-md)", strokeWidth: 1.75 }), extension === "" ? null : (_jsx("span", { className: "text-micro leading-none font-medium uppercase", children: extension }))] })) : (_jsx("img", { src: picture, alt: "", loading: "lazy", className: "size-full object-cover" })) }));
+}
+export function Attachments({ files, onAdd, onRemove, onRestore, onOpen, onRetry, accept, mode, label, empty, now, }) {
+    const copy = useUiCopy();
+    const toast = useToastIfAny();
+    const editable = useFormMode(mode) !== "read";
+    const base = useId();
+    const dropId = `${base}-drop`;
+    const listRef = useRef(null);
+    /* Where the focus goes once the removed file has left `files`: a file's id, or `null`
+       for the drop zone. Set on remove, spent when the list the application answers with
+       is drawn — not before, or it would land on the row that is about to disappear. */
+    const focusNext = useRef(undefined);
+    useEffect(() => {
+        const target = focusNext.current;
+        if (target === undefined)
+            return;
+        focusNext.current = undefined;
+        if (target === null) {
+            document.getElementById(dropId)?.focus();
+            return;
+        }
+        const row = [
+            ...(listRef.current?.querySelectorAll("[data-attachment-id]") ?? []),
+        ].find((one) => one.dataset["attachmentId"] === target);
+        (row?.querySelector("[data-attachment-remove]") ??
+            row?.querySelector("[data-attachment-name]"))?.focus();
+    }, [files, dropId]);
+    const remove = (file, index) => {
+        const neighbour = files[index + 1] ?? files[index - 1];
+        focusNext.current =
+            neighbour === undefined ? (onAdd === undefined ? undefined : null) : neighbour.id;
+        onRemove?.(file);
+        /* Only what was stored can be undone: a cancelled upload was never there. */
+        if ((file.status ?? "ready") !== "ready")
+            return;
+        toast?.show({
+            message: fillCopy(copy.attachments.removed, { name: file.name }),
+            ...(onRestore === undefined
+                ? {}
+                : {
+                    action: {
+                        label: copy.attachments.undo,
+                        onSelect: () => onRestore(file, index),
+                    },
+                }),
+        });
+    };
+    const adding = editable && onAdd !== undefined;
+    return (_jsxs("div", { className: "flex min-w-0 flex-col gap-3", children: [files.length === 0 ? (adding ? null : (_jsx(Empty, { sentence: empty ?? copy.attachments.empty, align: "start" }))) : (_jsx("ul", { ref: listRef, "aria-label": label ?? copy.attachments.label, className: "flex min-w-0 flex-col divide-y divide-line", children: files.map((file, index) => {
+                    const status = file.status ?? "ready";
+                    const nameId = `${base}-${index}-name`;
+                    const detailId = `${base}-${index}-detail`;
+                    const kind = attachmentKind(file.name, file.type);
+                    return (_jsxs("li", { "data-attachment-id": file.id, "data-status": status, className: "flex min-w-0 items-center gap-3 py-2", children: [_jsx(Thumb, { file: file, kind: kind }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1", children: [onOpen === undefined || status !== "ready" ? (_jsx("span", { id: nameId, title: file.name, className: "max-w-full truncate text-body font-medium text-ink", children: file.name })) : (_jsx("button", { type: "button", id: nameId, title: file.name, "data-attachment-name": true, "aria-describedby": detailId, onClick: () => onOpen(file), className: "max-w-full cursor-pointer truncate rounded-control text-left text-body font-medium text-ink outline-primary outline-offset-2 hover:underline hover:underline-offset-4 focus-visible:outline-2 forced-colors:outline-[Highlight]", children: file.name })), status === "uploading" ? (_jsx("div", { className: "w-full", children: _jsx(ProgressBar, { label: fillCopy(copy.attachments.uploading, { name: file.name }), width: "w-full", ...(file.progress === undefined ? {} : { value: file.progress }) }) })) : status === "failed" ? (
+                                    /* The icon AND the words: red alone is a colour some people do not see. */
+                                    _jsxs("p", { id: detailId, role: "alert", className: "flex min-w-0 items-start gap-1.5 text-meta text-bad", children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "mt-px size-(--size-icon-sm) shrink-0", strokeWidth: 2 }), _jsx("span", { className: "min-w-0", children: file.error ?? copy.attachments.failed })] })) : (_jsxs("p", { id: detailId, className: "flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 text-meta text-muted", children: [file.size === undefined ? null : (_jsx("span", { className: "tabular-nums whitespace-nowrap", children: formatFileSize(file.size, copy.locale) })), file.by === undefined ? null : (_jsx(UserChip, { name: file.by, size: "sm", ...(file.byAvatar === undefined ? {} : { src: file.byAvatar }) })), file.at === undefined ? null : (_jsx(DateValue, { when: file.at, ...(now === undefined ? {} : { now }) }))] }))] }), _jsxs("div", { className: "flex shrink-0 items-center gap-1", children: [status === "failed" && onRetry !== undefined ? (_jsx(Button, { role: "ghost", size: "sm", icon: RotateCcw, "aria-describedby": nameId, onClick: () => onRetry(file), children: copy.attachments.retry })) : null, status === "ready" && file.url !== undefined ? (_jsx(IconLink, { icon: Download, label: copy.attachments.download, href: file.url, download: file.name, tone: "normal", "aria-describedby": nameId })) : null, editable && onRemove !== undefined ? (_jsx(IconButton, { icon: status === "ready" ? Trash2 : X, label: status === "uploading"
+                                            ? copy.attachments.cancelUpload
+                                            : copy.attachments.remove, tone: status === "ready" ? "danger" : "normal", "data-attachment-remove": true, "aria-describedby": nameId, onClick: () => remove(file, index) })) : null] })] }, file.id));
+                }) })), adding ? (_jsx(DropZone, { id: dropId, mode: "edit", label: files.length === 0 ? (empty ?? copy.attachments.emptyAdd) : copy.attachments.add, ...(accept === undefined ? {} : { accept }), onFile: (file) => onAdd([file]) })) : null] }));
+}

package/dist/components/attachments/files.d.ts

@@ -0,0 +1,28 @@
+/** The five kinds a list of attachments tells apart. Five and not twenty: the icon is there
+ *  to say «this one is the spreadsheet» at a glance, and twenty icons are read, not seen. */
+export type AttachmentKind = "image" | "pdf" | "sheet" | "doc" | "other";
+/** The extension of a file name, lower-case, without the dot — `""` when it has none. A
+ *  leading dot (`.env`) is a hidden file, not an extension. */
+export declare function fileExtension(name: string): string;
+/**
+ * The kind of a file, from its MIME type and, failing that, its name.
+ *
+ * Context: the MIME type wins because it is what the server READ; the extension is what
+ * somebody typed. But a server that does not sniff answers `application/octet-stream` for
+ * everything, and then the name is all there is — so an unknown or generic type falls
+ * through to the extension instead of to «other».
+ */
+export declare function attachmentKind(name: string, type?: string): AttachmentKind;
+/**
+ * A size in bytes as a person reads it: «512 B», «34 KB», «1,2 MB» — in the copy's locale.
+ *
+ * Context: one decimal below ten and none above. «1,2 MB» and «1,9 MB» are different
+ * files; «123,4 MB» and «123,9 MB» are the same one, and the decimal is noise. Steps of 1024,
+ * the way the operating system that saved the file counts it — a file that says «1 MB» here
+ * and «1,05 MB» in the folder it came from reads as a different file.
+ *
+ * The number is `Intl`'s and the unit is written here: `Intl`'s own byte units change with
+ * the engine («byte», «kB», «B») and a column of sizes that writes its unit three ways is
+ * worse than any of the three.
+ */
+export declare function formatFileSize(bytes: number, locale: string): string;

package/dist/components/attachments/files.js

@@ -0,0 +1,100 @@
+/* ==================================================================== *
+ *  FILES — what a file IS, read from what the server says about it: its kind (for the icon
+ *  and the thumbnail) and its size (for a person, not for a disk).
+ *
+ *  Pure on purpose: the list draws with it, and a test checks it without a browser.
+ * ==================================================================== */
+const BY_EXTENSION = {
+    png: "image",
+    jpg: "image",
+    jpeg: "image",
+    gif: "image",
+    webp: "image",
+    svg: "image",
+    bmp: "image",
+    avif: "image",
+    heic: "image",
+    pdf: "pdf",
+    xlsx: "sheet",
+    xls: "sheet",
+    xlsm: "sheet",
+    ods: "sheet",
+    csv: "sheet",
+    docx: "doc",
+    doc: "doc",
+    odt: "doc",
+    rtf: "doc",
+    txt: "doc",
+    md: "doc",
+};
+/** The extension of a file name, lower-case, without the dot — `""` when it has none. A
+ *  leading dot (`.env`) is a hidden file, not an extension. */
+export function fileExtension(name) {
+    const dot = name.lastIndexOf(".");
+    if (dot <= 0 || dot === name.length - 1)
+        return "";
+    return name.slice(dot + 1).toLowerCase();
+}
+/**
+ * The kind of a file, from its MIME type and, failing that, its name.
+ *
+ * Context: the MIME type wins because it is what the server READ; the extension is what
+ * somebody typed. But a server that does not sniff answers `application/octet-stream` for
+ * everything, and then the name is all there is — so an unknown or generic type falls
+ * through to the extension instead of to «other».
+ */
+export function attachmentKind(name, type) {
+    const mime = (type ?? "").toLowerCase();
+    if (mime.startsWith("image/"))
+        return "image";
+    if (mime === "application/pdf")
+        return "pdf";
+    if (mime.includes("spreadsheet") || mime.includes("ms-excel") || mime === "text/csv") {
+        return "sheet";
+    }
+    if (mime.includes("wordprocessing") ||
+        mime.includes("msword") ||
+        mime.includes("opendocument.text") ||
+        mime === "text/plain" ||
+        mime === "text/markdown") {
+        return "doc";
+    }
+    return BY_EXTENSION[fileExtension(name)] ?? "other";
+}
+const UNITS = ["B", "KB", "MB", "GB", "TB"];
+/* A no-break space: «1,2» on one line and «MB» on the next reads as two values. */
+const NO_BREAK = String.fromCharCode(0xa0);
+const STEP = 1024;
+/**
+ * A size in bytes as a person reads it: «512 B», «34 KB», «1,2 MB» — in the copy's locale.
+ *
+ * Context: one decimal below ten and none above. «1,2 MB» and «1,9 MB» are different
+ * files; «123,4 MB» and «123,9 MB» are the same one, and the decimal is noise. Steps of 1024,
+ * the way the operating system that saved the file counts it — a file that says «1 MB» here
+ * and «1,05 MB» in the folder it came from reads as a different file.
+ *
+ * The number is `Intl`'s and the unit is written here: `Intl`'s own byte units change with
+ * the engine («byte», «kB», «B») and a column of sizes that writes its unit three ways is
+ * worse than any of the three.
+ */
+export function formatFileSize(bytes, locale) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return "";
+    let value = bytes;
+    let unit = 0;
+    while (value >= STEP && unit < UNITS.length - 1) {
+        value /= STEP;
+        unit += 1;
+    }
+    const digits = unit === 0 || value >= 10 ? 0 : 1;
+    /* 1023,96 KB rounds to «1.024 KB»: that is the next unit, written in the wrong one. */
+    const rounded = Number(value.toFixed(digits));
+    if (rounded >= STEP && unit < UNITS.length - 1) {
+        return formatFileSize(STEP ** (unit + 1), locale);
+    }
+    const number = new Intl.NumberFormat(locale, {
+        maximumFractionDigits: digits,
+        minimumFractionDigits: 0,
+    }).format(rounded);
+    return `${number}${NO_BREAK}${UNITS[unit]}`;
+}

package/dist/components/attachments/index.d.ts

@@ -0,0 +1,2 @@
+export { type AttachmentFile, Attachments, type AttachmentsProps, type AttachmentStatus, } from "./Attachments.js";
+export { type AttachmentKind, attachmentKind, fileExtension, formatFileSize, } from "./files.js";

package/dist/components/attachments/index.js

@@ -0,0 +1,3 @@
+/* ATTACHMENTS — the files of a record: what they are, who brought them, and what to do with them. */
+export { Attachments, } from "./Attachments.js";
+export { attachmentKind, fileExtension, formatFileSize, } from "./files.js";

package/dist/components/flow/StepFlow.d.ts

@@ -0,0 +1,37 @@
+import { type ReactNode } from "react";
+export type StepFlowStepProps = {
+    /** Who the step is: what `current` and `onCurrentChange` speak. */
+    id: string;
+    /** The step's name: on the strip and as the heading of its contents. */
+    title: string;
+    /** One sentence under the title: what this step asks for. */
+    description?: string;
+    /** Why it cannot move on yet. Present = «Siguiente» (or the finish) is off and this is
+     *  written next to it. Absent = the step is answered. */
+    blocked?: string;
+    /** What the forward button says from this step. On the last step it names what is going
+     *  to happen — «Importar 40 contactos» — instead of the copy's «Terminar». */
+    nextLabel?: string;
+    children?: ReactNode;
+};
+export type StepFlowProps = {
+    /** The current step's id, controlled. With `onCurrentChange`, the screen owns the step:
+     *  it can keep it in the URL, or jump back to the step that has the problem. */
+    current?: string;
+    /** Where an uncontrolled flow starts. The first step when absent. */
+    defaultCurrent?: string;
+    onCurrentChange?: (id: string) => void;
+    /** The forward button on the last step: the operation itself. */
+    onFinish: () => void;
+    /** Leave without doing anything. Without it there is no «Cancelar» — the surface that
+     *  opened the flow may already have its own way out (the composer modal's ×). */
+    onCancel?: () => void;
+    /** The operation is running: the primary is busy, the way back is off. */
+    busy?: boolean;
+    /** `StepFlow.Step`, in order. */
+    children?: ReactNode;
+};
+export declare function StepFlow({ current: controlled, defaultCurrent, onCurrentChange, onFinish, onCancel, busy, children, }: StepFlowProps): import("react").JSX.Element | null;
+export declare namespace StepFlow {
+    var Step: ((props: StepFlowStepProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"step">;
+}

package/dist/components/flow/StepFlow.js

@@ -0,0 +1,74 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { flatten, propsOf, slot, slotOf } from "../../foundations/slots.js";
+import { Button } from "../../primitives/button/Button.js";
+import { Check, ChevronRight, CircleAlert } from "lucide-react";
+import { useEffect, useId, useRef, useState } from "react";
+const Step = slot("step", (_props) => null);
+/** The steps as written, in order. */
+function readSteps(children) {
+    return flatten(children)
+        .filter((node) => slotOf(node) === "step")
+        .map((node) => propsOf(node));
+}
+const DISC = {
+    done: "bg-good/12 text-good",
+    current: "bg-ink text-surface",
+    pending: "bg-ink/8 text-muted",
+};
+export function StepFlow({ current: controlled, defaultCurrent, onCurrentChange, onFinish, onCancel, busy = false, children, }) {
+    const words = useUiCopy().stepFlow;
+    const steps = readSteps(children);
+    const [own, setOwn] = useState(defaultCurrent);
+    const wanted = controlled ?? own;
+    /* An id that is not (or no longer) a step falls back to the first: a flow that draws
+       nothing because a step was renamed is a blank modal with no way out. */
+    const found = steps.findIndex((s) => s.id === wanted);
+    const at = found === -1 ? 0 : found;
+    const step = steps[at];
+    const currentId = step?.id;
+    const headingRef = useRef(null);
+    const shown = useRef(currentId);
+    const headingId = useId();
+    const blockedId = useId();
+    /* The focus follows the step — but not on the first render, and not on StrictMode's
+       second run of the same one: `shown` only differs after a real move. */
+    useEffect(() => {
+        if (shown.current === currentId)
+            return;
+        shown.current = currentId;
+        headingRef.current?.focus();
+    }, [currentId]);
+    if (step === undefined)
+        return null;
+    const last = at === steps.length - 1;
+    const total = steps.length;
+    const go = (id) => {
+        if (controlled === undefined)
+            setOwn(id);
+        onCurrentChange?.(id);
+    };
+    const forward = () => {
+        if (busy || step.blocked !== undefined)
+            return;
+        if (last)
+            onFinish();
+        else
+            go(steps[at + 1].id);
+    };
+    const position = fillCopy(words.position, { index: at + 1, total });
+    return (
+    /* `h-full`: the composer modal's body is a block with a height, not a flex column —
+       filling it is what keeps the footer in sight while the step scrolls. */
+    _jsxs("div", { className: "flex h-full min-h-0 min-w-0 flex-1 flex-col bg-surface text-ink", children: [_jsx("ol", { "aria-label": words.steps, className: "flex min-w-0 shrink-0 flex-wrap items-center gap-x-1 gap-y-1 border-b border-line px-4 py-2.5", children: steps.map((s, i) => {
+                    const state = i < at ? "done" : i === at ? "current" : "pending";
+                    const content = (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, className: `inline-flex size-5 shrink-0 items-center justify-center rounded-pill text-micro font-medium tabular-nums ${DISC[state]}`, children: state === "done" ? (_jsx(Check, { className: "size-(--size-icon-sm)", strokeWidth: 2.5 })) : (i + 1) }), _jsx("span", { className: "min-w-0 truncate", children: s.title }), state === "current" ? null : (_jsx("span", { className: "sr-only", children: ` (${state === "done" ? words.done : words.pending})` }))] }));
+                    return (_jsxs("li", { className: "flex min-w-0 items-center gap-1", children: [i === 0 ? null : (_jsx(ChevronRight, { "aria-hidden": true, className: "size-(--size-icon-sm) shrink-0 text-muted" })), state === "done" && !busy ? (_jsx("button", { type: "button", onClick: () => go(s.id), className: "inline-flex min-w-0 items-center gap-1.5 rounded-control px-1.5 py-1 text-micro text-ink transition-colors duration-(--duration-instant) hover:bg-ink/6 focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary", children: content })) : (_jsx("span", { "aria-current": state === "current" ? "step" : undefined, className: `inline-flex min-w-0 items-center gap-1.5 px-1.5 py-1 text-micro ${state === "current"
+                                    ? "font-medium text-ink"
+                                    : state === "done"
+                                        ? "text-ink"
+                                        : "text-muted"}`, children: content }))] }, s.id));
+                }) }), _jsx("p", { role: "status", className: "sr-only", children: busy ? words.working : fillCopy(words.announce, { position, title: step.title }) }), _jsxs("section", { "aria-labelledby": headingId, className: "min-h-0 min-w-0 flex-1 overflow-y-auto px-4 py-4", children: [_jsx("p", { className: "text-micro text-muted tabular-nums", children: position }), _jsx("h2", { id: headingId, ref: headingRef, tabIndex: -1, className: "text-title font-semibold text-ink outline-0", children: step.title }), step.description === undefined ? null : (_jsx("p", { className: "mt-1 max-w-prose text-meta text-muted", children: step.description })), _jsx("div", { className: "mt-4 flex min-w-0 flex-col gap-3", children: step.children })] }), _jsxs("footer", { className: "flex min-w-0 shrink-0 flex-wrap items-center justify-end gap-2 border-t border-line bg-ground px-4 py-3 max-sm:safe-bottom", children: [step.blocked === undefined ? null : (_jsxs("p", { id: blockedId, className: "mr-auto flex min-w-0 items-center gap-1.5 text-micro text-warn", children: [_jsx(CircleAlert, { "aria-hidden": true, className: "size-(--size-icon-sm) shrink-0" }), _jsx("span", { className: "min-w-0", children: step.blocked })] })), onCancel === undefined ? null : (_jsx(Button, { role: "ghost", onClick: onCancel, disabled: busy, children: words.cancel })), at === 0 ? null : (_jsx(Button, { role: "secondary", onClick: () => go(steps[at - 1].id), disabled: busy, children: words.back })), _jsx(Button, { role: "primary", onClick: forward, busy: busy, disabled: step.blocked !== undefined, ...(step.blocked === undefined ? {} : { "aria-describedby": blockedId }), children: step.nextLabel ?? (last ? words.finish : words.next) })] })] }));
+}
+StepFlow.Step = Step;

package/dist/components/flow/index.d.ts

@@ -0,0 +1 @@
+export { StepFlow, type StepFlowProps, type StepFlowStepProps, } from "./StepFlow.js";

package/dist/components/flow/index.js

@@ -0,0 +1,2 @@
+/* One operation in several steps, done in one sitting — import: upload › map › review. */
+export { StepFlow, } from "./StepFlow.js";

package/dist/components/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./activity/index.js";
 export * from "./assist/index.js";
+export * from "./attachments/index.js";
 export * from "./calendar/index.js";
+export * from "./flow/index.js";
 export * from "./form/index.js";
 export * from "./frame/index.js";
 export * from "./gantt/index.js";

package/dist/components/index.js

@@ -1,7 +1,9 @@
 /* COMPONENTS — primitives composed to answer ONE question of the product, by family. */
 export * from "./activity/index.js";
 export * from "./assist/index.js";
+export * from "./attachments/index.js";
 export * from "./calendar/index.js";
+export * from "./flow/index.js";
 export * from "./form/index.js";
 export * from "./frame/index.js";
 export * from "./gantt/index.js";

package/dist/components/lines/LineItems.js

@@ -4,7 +4,7 @@ import { commitDraft, filterLines, planRemoval, } from "./lines.js";
 import { useColumnControl, } from "../listing/columns.js";
 import { ColumnsMenu } from "../listing/ColumnsMenu.js";
 import { fillCopy, useUiCopy } from "../../foundations/copy.js";
-import { FieldIdsContext } from "../../foundations/form.js";
+import { FieldBoundary, FieldIdsContext } from "../../foundations/form.js";
 import { useFormMode } from "../../foundations/form.js";
 import { Button, IconButton } from "../../primitives/button/Button.js";
 import { SearchField } from "../../primitives/choice/SearchField.js";
@@ -228,7 +228,14 @@ export function LineItems({ lines, columns, getLineId, lineLabel, mode, onChange
         ...(c.stack === undefined ? {} : { stack: c.stack }),
         ...(c.brief === undefined ? {} : { brief: c.brief }),
         render: (line) => {
-            const drawn = c.cell === undefined ? plain(c.value(line)) : c.cell(line);
+            /* `cell` draws it; without one, `text` is how it READS — the raw `value` is what the
+               search and the sort compare («3» is a unit id; «caja ×12» is what it says). The
+               same order `DataTable` follows. */
+            const drawn = c.cell !== undefined
+                ? c.cell(line)
+                : c.text !== undefined
+                    ? c.text(line)
+                    : plain(c.value(line));
             /* An amount never breaks in two: «Bs.» over «12.500,00» reads as two values. */
             return c.numeric === true ? _jsx("span", { className: "whitespace-nowrap", children: drawn }) : drawn;
         },
@@ -273,47 +280,50 @@ export function LineItems({ lines, columns, getLineId, lineLabel, mode, onChange
             shown: shown.length.toLocaleString(copy.locale),
             count: lineCount.toLocaleString(copy.locale),
         });
-    return (_jsxs("section", { ref: root, "aria-label": copy.lineItems.table, className: "flex min-w-0 flex-col gap-4", children: [lines.length === 0 && !canAdd ? (
-            /* Said, with its way out: an empty document is a question («what is sold
-               here?»), not a blank box. In read mode there is no way out to offer. */
-            _jsx(Empty, { align: "start", sentence: copy.lines.empty, action: addButton ?? undefined })) : (_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsxs("div", { className: "flex flex-wrap items-center gap-x-3 gap-y-2 px-1", children: [searchable ? (_jsxs("div", { className: "w-full max-w-(--container-search) min-w-0 flex-1", children: [_jsx("span", { id: searchLabelId, className: "sr-only", children: copy.lines.search }), _jsx(FieldIdsContext.Provider, { value: {
-                                            id: `${searchLabelId}-input`,
-                                            labelId: searchLabelId,
-                                            describedBy: undefined,
-                                            invalid: false,
-                                        }, children: _jsx(SearchField, { value: query, onChange: setQuery, placeholder: copy.lines.search }) })] })) : null, _jsx("span", { className: "text-meta text-muted tabular-nums", "aria-live": "polite", children: count }), columnControl.hasOptional || addButton !== null ? (_jsxs("span", { className: "ml-auto flex items-center gap-2", children: [_jsx(ColumnsMenu, { control: columnControl }), addButton] })) : null] }), _jsx(EditableTable, { rows: shown, columns: tableColumns, getRowId: getLineId, empty: lines.length === 0
-                            ? copy.lines.empty
-                            : fillCopy(copy.lineItems.noMatch, { query: query.trim() }), layout: layout, ...(inline ? { onAdd: () => addInline(), addLabel: copy.lines.add } : {}), ...(bandAdds.length === 0 ? {} : { adds: bandAdds }), ...(bands === undefined ? {} : { bands }), ...(flag === undefined ? {} : { flag }), ...(cellState === undefined ? {} : { cellState }), ...(rowState === undefined ? {} : { rowState }), ...(onReorder === undefined || read ? {} : { onReorder }), ...(inPlace && onRemove !== undefined
-                            ? /* A blank row nobody wrote in is taken back without a notice: nobody
-                                 removed anything, so there is nothing to undo. */
-                                { onDiscard: onRemove }
-                            : {}), ...(canEdit
-                            ? {
-                                onOpen: (id) => {
-                                    const line = lines.find((l) => getLineId(l) === id);
-                                    /* A read-only line opens no form to change it. */
-                                    if (line !== undefined && rowState?.(line)?.readonly !== true) {
-                                        openLine(id, line);
-                                    }
-                                },
-                            }
-                            : {}), ...(canChange && columns.some((c) => c.edit !== undefined)
-                            ? { onChange: (id, next) => onChange?.(id, next) }
-                            : {}) })] })), totals === undefined || ("length" in totals && totals.length === 0) ? null : (
-            /* Inset like the table's cells, so the last figure lines up with the amounts. */
-            _jsx("div", { className: "px-4", children: "length" in totals ? _jsx(Totals, { rows: totals }) : _jsx(Totals, { ...totals }) })), editor === undefined || session === null ? null : (_jsx(Dialog, { open: open, width: "sm", title: session.id === null ? copy.lineItems.newLine : copy.lines.edit, ...(context === undefined ? {} : { context }), ...(session.id === null ? {} : { subtitle: labelOf(session.draft) }), onClose: () => setOpen(false), footer: _jsxs(_Fragment, { children: [session.id === null || !canRemove ? null : (
-                        /* Apart, at the other end from «Listo»: removing is not the way the
-                           form is meant to close. */
-                        _jsx("span", { className: "mr-auto", children: _jsx(IconButton, { icon: Trash2, label: copy.lines.remove, tone: "danger", onClick: () => {
-                                    const line = lines.find((l) => getLineId(l) === session.id);
-                                    setOpen(false);
-                                    if (line !== undefined)
-                                        remove(line);
-                                } }) })), _jsx(Button, { role: "ghost", size: "sm", onClick: () => setOpen(false), children: copy.dialog.cancel }), _jsx(Button, { role: "primary", size: "sm", type: "submit", form: formId, children: copy.lines.done })] }), children: _jsx("form", { id: formId, noValidate: true, onSubmit: (e) => {
-                        e.preventDefault();
-                        save();
-                    }, className: "flex flex-col gap-3", children: editor(session.draft, setDraft, {
-                        tried: session.tried,
-                        isNew: session.id === null,
-                    }) }) }))] }));
+    return (
+    /* A collection is many controls, each named by its column: no enclosing `Field`
+       reaches inside (see `FieldBoundary`). */
+    _jsx(FieldBoundary, { children: _jsxs("section", { ref: root, "aria-label": copy.lineItems.table, className: "flex min-w-0 flex-col gap-4", children: [lines.length === 0 && !canAdd ? (
+                /* Said, with its way out: an empty document is a question («what is sold
+                 here?»), not a blank box. In read mode there is no way out to offer. */
+                _jsx(Empty, { align: "start", sentence: copy.lines.empty, action: addButton ?? undefined })) : (_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsxs("div", { className: "flex flex-wrap items-center gap-x-3 gap-y-2 px-1", children: [searchable ? (_jsxs("div", { className: "w-full max-w-(--container-search) min-w-0 flex-1", children: [_jsx("span", { id: searchLabelId, className: "sr-only", children: copy.lines.search }), _jsx(FieldIdsContext.Provider, { value: {
+                                                id: `${searchLabelId}-input`,
+                                                labelId: searchLabelId,
+                                                describedBy: undefined,
+                                                invalid: false,
+                                            }, children: _jsx(SearchField, { value: query, onChange: setQuery, placeholder: copy.lines.search }) })] })) : null, _jsx("span", { className: "text-meta text-muted tabular-nums", "aria-live": "polite", children: count }), columnControl.hasOptional || addButton !== null ? (_jsxs("span", { className: "ml-auto flex items-center gap-2", children: [_jsx(ColumnsMenu, { control: columnControl }), addButton] })) : null] }), _jsx(EditableTable, { rows: shown, columns: tableColumns, getRowId: getLineId, empty: lines.length === 0
+                                ? copy.lines.empty
+                                : fillCopy(copy.lineItems.noMatch, { query: query.trim() }), layout: layout, ...(inline ? { onAdd: () => addInline(), addLabel: copy.lines.add } : {}), ...(bandAdds.length === 0 ? {} : { adds: bandAdds }), ...(bands === undefined ? {} : { bands }), ...(flag === undefined ? {} : { flag }), ...(cellState === undefined ? {} : { cellState }), ...(rowState === undefined ? {} : { rowState }), ...(onReorder === undefined || read ? {} : { onReorder }), ...(inPlace && onRemove !== undefined
+                                ? /* A blank row nobody wrote in is taken back without a notice: nobody
+                                   removed anything, so there is nothing to undo. */
+                                    { onDiscard: onRemove }
+                                : {}), ...(canEdit
+                                ? {
+                                    onOpen: (id) => {
+                                        const line = lines.find((l) => getLineId(l) === id);
+                                        /* A read-only line opens no form to change it. */
+                                        if (line !== undefined && rowState?.(line)?.readonly !== true) {
+                                            openLine(id, line);
+                                        }
+                                    },
+                                }
+                                : {}), ...(canChange && columns.some((c) => c.edit !== undefined)
+                                ? { onChange: (id, next) => onChange?.(id, next) }
+                                : {}) })] })), totals === undefined || ("length" in totals && totals.length === 0) ? null : (
+                /* Inset like the table's cells, so the last figure lines up with the amounts. */
+                _jsx("div", { className: "px-4", children: "length" in totals ? _jsx(Totals, { rows: totals }) : _jsx(Totals, { ...totals }) })), editor === undefined || session === null ? null : (_jsx(Dialog, { open: open, width: "sm", title: session.id === null ? copy.lineItems.newLine : copy.lines.edit, ...(context === undefined ? {} : { context }), ...(session.id === null ? {} : { subtitle: labelOf(session.draft) }), onClose: () => setOpen(false), footer: _jsxs(_Fragment, { children: [session.id === null || !canRemove ? null : (
+                            /* Apart, at the other end from «Listo»: removing is not the way the
+                             form is meant to close. */
+                            _jsx("span", { className: "mr-auto", children: _jsx(IconButton, { icon: Trash2, label: copy.lines.remove, tone: "danger", onClick: () => {
+                                        const line = lines.find((l) => getLineId(l) === session.id);
+                                        setOpen(false);
+                                        if (line !== undefined)
+                                            remove(line);
+                                    } }) })), _jsx(Button, { role: "ghost", size: "sm", onClick: () => setOpen(false), children: copy.dialog.cancel }), _jsx(Button, { role: "primary", size: "sm", type: "submit", form: formId, children: copy.lines.done })] }), children: _jsx("form", { id: formId, noValidate: true, onSubmit: (e) => {
+                            e.preventDefault();
+                            save();
+                        }, className: "flex flex-col gap-3", children: editor(session.draft, setDraft, {
+                            tried: session.tried,
+                            isNew: session.id === null,
+                        }) }) }))] }) }));
 }