@sincpro/web-ui 1.5.0 → 1.7.0

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.d.ts

@@ -2,7 +2,7 @@ import { type FormMode } from "../../foundations/form.js";
 import { type DialogContext } from "../../primitives/dialog/Dialog.js";
 import type { FlagTone } from "../../primitives/notice/Flag.js";
 import type { DataColumn } from "../../primitives/table/DataTable.js";
-import { type EditColumn, type EditLayout } from "../../primitives/table/EditableTable.js";
+import { type EditCellState, type EditColumn, type EditLayout, type EditRowState } from "../../primitives/table/EditableTable.js";
 import { type TotalsProps, type TotalsRow } from "../../primitives/value/Totals.js";
 import { type ReactNode } from "react";
 /**
@@ -41,6 +41,8 @@ export type LineEditorState = {
 export type LineItemsProps<T> = {
     lines: readonly T[];
     columns: readonly LineItemColumn<T>[];
+    /** The line's key on this screen — LOCAL, not its id on the server: a new line gets one
+     *  when it is made and keeps it after saving. See «A line's key is local» above. */
     getLineId: (line: T) => string;
     /** How a line is named — in the removal notice, the editor's header and for the
      *  screen reader next to each row's buttons. Defaults to the first column's text. */
@@ -52,7 +54,8 @@ export type LineItemsProps<T> = {
     onChange?: (id: string, next: T) => void;
     /** A new line, already filled in the editor (or blank, without an editor). */
     onAdd?: (line: T) => void;
-    /** The blank line «Agregar una línea» starts from. Required for adding. */
+    /** The blank line «Agregar una línea» starts from. Required for adding. It carries its
+     *  local key from here — `{ key: crypto.randomUUID(), … }` — since it has no server id. */
     newLine?: () => T;
     /** A line was removed. It is gone at once; the notice offers to undo it. */
     onRemove?: (id: string) => void;
@@ -93,6 +96,14 @@ export type LineItemsProps<T> = {
         detail?: ReactNode;
         owner?: string;
     } | null;
+    /** What each cell is on each line — readonly, required, hidden, its error, its warning
+     *  («precio bajo el costo» on the price) — as the backend says it per line and field.
+     *  `EditableTable`'s `cellState`, passed through. The error reaches the cell's control as
+     *  `aria-invalid` and `aria-describedby`. */
+    cellState?: (line: T, columnId: string) => EditCellState | null;
+    /** What a whole line is: `readonly` is read in place and offers no pencil (a delivered
+     *  line). A line that should not be seen is not passed in `lines`. */
+    rowState?: (line: T) => EditRowState | null;
     /** Sections and notes among the lines. See the file's header. */
     structure?: LineStructure<T>;
     /** The lines' order is the document's (Odoo's `sequence`): a grip at the start of each line
@@ -111,4 +122,4 @@ export type LineItemsProps<T> = {
  * removing asked first, what an empty document said. One component, built on
  * `EditableTable` and `Dialog`, makes the one2many the same block everywhere.
  */
-export declare function LineItems<T>({ lines, columns, getLineId, lineLabel, mode, onChange, onAdd, newLine, onRemove, onRestore, editor, isValid, context, searchText, searchFrom, totals, layout, adding, onOpenLine, flag, structure, onReorder, visibleColumnIds, onVisibleColumnIdsChange, }: LineItemsProps<T>): import("react").JSX.Element;
+export declare function LineItems<T>({ lines, columns, getLineId, lineLabel, mode, onChange, onAdd, newLine, onRemove, onRestore, editor, isValid, context, searchText, searchFrom, totals, layout, adding, onOpenLine, flag, cellState, rowState, structure, onReorder, visibleColumnIds, onVisibleColumnIdsChange, }: LineItemsProps<T>): import("react").JSX.Element;

package/dist/components/lines/LineItems.js

@@ -38,7 +38,7 @@ function plain(v) {
  * removing asked first, what an empty document said. One component, built on
  * `EditableTable` and `Dialog`, makes the one2many the same block everywhere.
  */
-export function LineItems({ lines, columns, getLineId, lineLabel, mode, onChange, onAdd, newLine, onRemove, onRestore, editor, isValid, context, searchText, searchFrom = 8, totals, layout = "auto", adding, onOpenLine, flag, structure, onReorder, visibleColumnIds, onVisibleColumnIdsChange, }) {
+export function LineItems({ lines, columns, getLineId, lineLabel, mode, onChange, onAdd, newLine, onRemove, onRestore, editor, isValid, context, searchText, searchFrom = 8, totals, layout = "auto", adding, onOpenLine, flag, cellState, rowState, structure, onReorder, visibleColumnIds, onVisibleColumnIdsChange, }) {
     const copy = useUiCopy();
     const toast = useOptionalToast();
     const read = useFormMode(mode) === "read";
@@ -259,7 +259,7 @@ export function LineItems({ lines, columns, getLineId, lineLabel, mode, onChange
                    and a trash can lit on each of twenty lines are forty invitations. They
                    fade instead of unmounting, so Tab still reaches them. Pressing them does
                    not put the row into in-place editing. */
-                _jsxs("span", { "data-line": id, className: "flex items-center justify-end gap-0.5 whitespace-nowrap opacity-0 transition-opacity duration-(--duration-instant) group-hover/row:opacity-100 focus-within:opacity-100 in-data-stacked:opacity-100", onClick: (e) => e.stopPropagation(), children: [_jsx("span", { id: nameId, className: "sr-only", children: labelOf(line) }), canEdit && kindOf(line) === "line" ? (_jsx(IconButton, { icon: Pencil, label: copy.lines.edit, "aria-describedby": nameId, haspopup: "dialog", onClick: () => openLine(id, line) })) : null, canRemove ? (_jsx(IconButton, { icon: Trash2, label: copy.lines.remove, tone: "danger", "aria-describedby": nameId, onClick: () => remove(line) })) : null] }));
+                _jsxs("span", { "data-line": id, className: "flex items-center justify-end gap-0.5 whitespace-nowrap opacity-0 transition-opacity duration-(--duration-instant) group-hover/row:opacity-100 focus-within:opacity-100 in-data-stacked:opacity-100", onClick: (e) => e.stopPropagation(), children: [_jsx("span", { id: nameId, className: "sr-only", children: labelOf(line) }), canEdit && kindOf(line) === "line" && rowState?.(line)?.readonly !== true ? (_jsx(IconButton, { icon: Pencil, label: copy.lines.edit, "aria-describedby": nameId, haspopup: "dialog", onClick: () => openLine(id, line) })) : null, canRemove ? (_jsx(IconButton, { icon: Trash2, label: copy.lines.remove, tone: "danger", "aria-describedby": nameId, onClick: () => remove(line) })) : null] }));
             },
         });
     }
@@ -283,7 +283,7 @@ export function LineItems({ lines, columns, getLineId, lineLabel, mode, onChange
                                             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 }), ...(onReorder === undefined || read ? {} : { onReorder }), ...(inPlace && onRemove !== undefined
+                            : 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 }
@@ -291,8 +291,10 @@ export function LineItems({ lines, columns, getLineId, lineLabel, mode, onChange
                             ? {
                                 onOpen: (id) => {
                                     const line = lines.find((l) => getLineId(l) === id);
-                                    if (line !== undefined)
+                                    /* 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)

package/dist/components/listing/SortMenu.d.ts

@@ -1,25 +1,30 @@
 import type { Surface } from "../../foundations/types.js";
-import type { SortState } from "../../primitives/table/Table.js";
+import { type SortState } from "../../primitives/table/sorting.js";
 /**
- * ORDENAR, cuando no hay encabezados donde hacer clic.
+ * ORDENAR — por uno o por varios campos, desde la barra.
  *
  * Context: ordenar era una capacidad de `DataTable` y de nadie más. Se hacía
  * clic en el encabezado de la columna, que es la forma correcta **cuando hay
  * encabezados**. En filas, en tablero y en la planilla no los hay, así que
  * cambiar de presentación no perdía sólo el orden puesto: perdía la posibilidad
- * de ordenar. Es exactamente el mismo drift que tenía la agrupación.
+ * de ordenar.
  *
  * El orden es del CONJUNTO y no de la presentación, igual que los niveles y que
  * lo plegado. Por eso el control vive en la barra y no adentro de la tabla, y
  * por eso la tabla sigue teniendo además sus encabezados: son dos puertas a lo
  * mismo, y la de los encabezados es más rápida cuando existe.
  *
- * ── Por qué es un `Menu` y el agrupador no ──────────────────────────
+ * ── Varios criterios, y por eso un panel y no un menú ───────────────
  *
- * Porque ordenar SÍ es elegir una opción: un campo y una dirección. No hay orden
- * ni jerarquía que expresar —ordenar por dos campos a la vez es un desempate,
- * que es otra pregunta y la hace el motor— así que una lista de tildes alcanza y
- * no hace falta un editor.
+ * Se decía que ordenar por dos campos era «un desempate que hace el motor» y
+ * que alcanzaba con elegir uno. La gente pidió lo contrario en la pantalla: por
+ * fecha, y en la misma fecha por cliente, y después por producto. El motor ya
+ * lo aceptaba (`order: [...]`); faltaba poder decirlo. Un orden de N campos
+ * tiene ORDEN entre ellos —el segundo sólo decide entre las filas que el
+ * primero dejó iguales—, y eso un menú de tildes no lo expresa: hace falta una
+ * lista que se reordena. Es la de React Aria (`GridList` + `useDragAndDrop`):
+ * se arrastra con el mouse, y con el teclado desde el asa (Enter, flechas,
+ * Enter), anunciado.
  */
 export type SortField<T = unknown> = {
     field: string;
@@ -33,7 +38,7 @@ export type SortField<T = unknown> = {
      * falso— así que ahí el orden viaja en la lectura y esto sólo lo refleja.
      */
     value?: (item: T) => string | number | null | undefined;
-    /** Qué quiere decir «ascendente» para este campo. Sin esto, «A → Z».
+    /** Qué quiere decir «ascendente» para este campo. Sin esto, «ascendente».
      *  Una fecha asciende de vieja a nueva y un importe de chico a grande, y
      *  decirlo evita el clic de prueba. */
     ascLabel?: string;
@@ -42,21 +47,20 @@ export type SortField<T = unknown> = {
 export type SortMenuProps = {
     /** Por qué campos se puede ordenar. Sin ninguno, el control no se dibuja. */
     fields: readonly SortField<never>[];
-    sort: SortState | null;
-    onSortChange: (next: SortState | null) => void;
+    /** El orden, de afuera hacia adentro. Vacío es «como llegaron». */
+    sort: readonly SortState[];
+    onSortChange: (next: SortState[]) => void;
     surface?: Surface;
 };
 /**
- * Las filas, ordenadas acá.
+ * Las filas, ordenadas acá, por cada criterio en su orden.
  *
- * Sólo cuando el campo activo declara `value`; si no, se devuelven tal cual —
- * ordenar una página de un conjunto que se pagina afuera produce un orden que es
- * mentira, porque ordena las doce que llegaron y no las ciento ochenta y siete.
+ * Sólo por los campos que declaran `value`; los demás se saltean —ordenar una
+ * página de un conjunto que se pagina afuera produce un orden que es mentira,
+ * porque ordena las doce que llegaron y no las ciento ochenta y siete. Sin
+ * ningún criterio legible, se devuelven tal cual.
  *
- * Los faltantes van SIEMPRE al final, suba o baje el orden. Es lo que hace
- * cualquier planilla, y la razón es que un vacío no es «el más chico»: es la
- * ausencia de respuesta, y ponerlo primero al invertir el orden llena la primera
- * pantalla con las filas que menos dicen.
+ * Los faltantes van SIEMPRE al final, suba o baje el orden (ver `compareBy`).
  */
-export declare function sortItems<T>(items: readonly T[], fields: readonly SortField<T>[], sort: SortState | null | undefined): readonly T[];
+export declare function sortItems<T>(items: readonly T[], fields: readonly SortField<T>[], sort: readonly SortState[] | undefined): readonly T[];
 export declare function SortMenu({ fields, sort, onSortChange, surface }: SortMenuProps): import("react").JSX.Element | null;