@sincpro/web-ui 1.6.0 → 1.7.0

package/dist/primitives/field/PatternInput.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFieldIds, useFormMode } from "../../foundations/form.js";
+import { controlClasses, nameOf, ReadValue, } from "./Field.js";
+import { maskedChange, useMaskCaret } from "./mask.js";
+import { formatPattern, patternLength, patternValue, } from "./pattern.js";
+import { Input, TextField as AriaTextField } from "react-aria-components";
+const isSlotChar = (char) => /[a-z\d]/i.test(char);
+/**
+ * An identifier with a fixed shape — a NIT, a CI, a bank account, an IBAN — typed on its
+ * `pattern` (`#` digit, `A` letter, `*` either; see `pattern.ts`).
+ *
+ * Context: written into a `TextInput`, «1020304-5», «10203045» and «1020304 5» were three
+ * values for the same company, and the search found one of them. Here the value is only the
+ * characters (`"10203045"`), the separators are drawn as they are typed, a character the
+ * slot does not take is not let in, and the caret stays where it was while the separators
+ * appear (`mask.ts`). Pasting «BO12 3456…» with any spacing lands in the slots.
+ *
+ * Read mode draws it on the pattern, in mono — a value written by a machine and compared
+ * with the one next to it. Whether it is COMPLETE is the form's to say: `isPatternComplete`.
+ */
+export function PatternInput({ id: ownId, value, onChange, pattern, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, mode, "aria-label": ariaLabel, }) {
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    const clean = patternValue(value, pattern);
+    const drawn = formatPattern(clean, pattern);
+    const { input, keep } = useMaskCaret(drawn, isSlotChar);
+    if (useFormMode(mode) === "read") {
+        return _jsx(ReadValue, { mono: true, value: clean === "" ? null : drawn });
+    }
+    const change = (raw) => {
+        const { next, caret } = maskedChange({
+            raw,
+            at: input.current?.selectionStart ?? raw.length,
+            current: clean,
+            drawn,
+            clean: (text) => patternValue(text, pattern),
+            max: patternLength(pattern),
+        });
+        keep(caret);
+        onChange?.(next);
+    };
+    const shown = placeholder ?? pattern.replace(/#/g, "0").replace(/\*/g, "X");
+    return (_jsx(AriaTextField, { id: id, "aria-labelledby": labelledBy, "aria-label": nameOf(labelledBy, ariaLabel, shown), value: drawn, onChange: change, inputMode: /[A*]/.test(pattern) ? "text" : "numeric", isInvalid: invalid, isDisabled: disabled, className: "w-full min-w-0", children: _jsx(Input, { ref: input, "aria-describedby": describedBy, placeholder: shown, spellCheck: false, autoCapitalize: "characters", className: `${controlClasses(invalid)} font-mono tabular-nums` }) }));
+}

package/dist/primitives/field/RichTextEditor.d.ts

@@ -0,0 +1,18 @@
+export type MentionItem = {
+    id: string;
+    label: string;
+};
+export type RichTextEditorProps = {
+    id: string | undefined;
+    labelledBy: string | undefined;
+    describedBy: string | undefined;
+    invalid: boolean;
+    ariaLabel: string | undefined;
+    value: string;
+    onChange: ((html: string) => void) | undefined;
+    placeholder: string | undefined;
+    disabled: boolean;
+    toolbar: "full" | "basic" | "none";
+    mentions: ((query: string) => readonly MentionItem[] | Promise<readonly MentionItem[]>) | undefined;
+};
+export declare function RichTextEditor({ id, labelledBy, describedBy, invalid, ariaLabel, value, onChange, placeholder, disabled, toolbar, mentions, }: RichTextEditorProps): import("react").JSX.Element;

package/dist/primitives/field/RichTextEditor.js

@@ -0,0 +1,224 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { Button, IconButton } from "../button/Button.js";
+import { emailHref, telHref, urlHref } from "./contact.js";
+import { PopoverTrigger } from "../overlay/PopoverTrigger.js";
+import { Toolbar, ToolbarSeparator } from "../toolbar/Toolbar.js";
+import Mention from "@tiptap/extension-mention";
+import { TableKit } from "@tiptap/extension-table";
+import { Placeholder } from "@tiptap/extensions";
+import { EditorContent, useEditor, useEditorState } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { Bold, Heading2, Heading3, Italic, Link as LinkIcon, List, ListOrdered, Redo2, RemoveFormatting, Strikethrough, Table, TextQuote, Underline, Undo2, } from "lucide-react";
+import { useEffect, useId, useRef, useState } from "react";
+/** A link address as people write it: a website, an email, a phone — or nothing valid. */
+function linkHref(text) {
+    const clean = text.trim();
+    if (clean === "")
+        return null;
+    if (clean.includes("@") && !clean.includes("/"))
+        return emailHref(clean.replace(/^mailto:/i, ""));
+    if (/^(?:tel:)?\+?[\d\s().-]{6,}$/i.test(clean))
+        return telHref(clean);
+    return urlHref(clean);
+}
+function LinkForm({ editor, close }) {
+    const copy = useUiCopy().richText;
+    const current = editor.getAttributes("link")["href"] ?? "";
+    const [text, setText] = useState(current);
+    const [tried, setTried] = useState(false);
+    const inputId = useId();
+    const href = linkHref(text);
+    const apply = () => {
+        setTried(true);
+        if (href === null)
+            return;
+        editor.chain().focus().extendMarkRange("link").setLink({ href }).run();
+        close();
+    };
+    return (_jsxs("form", { className: "flex w-72 max-w-full flex-col gap-2", onSubmit: (event) => {
+            event.preventDefault();
+            apply();
+        }, children: [_jsx("label", { htmlFor: inputId, className: "text-micro font-medium text-muted", children: copy.linkUrl }), _jsx("input", { id: inputId, value: text, autoFocus: true, inputMode: "url", spellCheck: false, "aria-invalid": tried && href === null, ...(tried && href === null ? { "aria-describedby": `${inputId}-error` } : {}), onChange: (event) => setText(event.target.value), className: "h-(--size-control-md) w-full min-w-0 rounded-control border border-line-strong bg-surface px-2.5 text-meta text-ink outline-0 focus-visible:border-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary" }), tried && href === null ? (_jsx("p", { id: `${inputId}-error`, role: "alert", className: "text-micro text-danger", children: copy.badLink })) : null, _jsxs("div", { className: "flex items-center justify-end gap-2", children: [current === "" ? null : (_jsx(Button, { role: "ghost", size: "sm", onClick: () => {
+                            editor.chain().focus().extendMarkRange("link").unsetLink().run();
+                            close();
+                        }, children: copy.removeLink })), _jsx(Button, { role: "secondary", size: "sm", type: "submit", children: copy.applyLink })] })] }));
+}
+function Bar({ editor, full }) {
+    const copy = useUiCopy().richText;
+    const on = useEditorState({
+        editor,
+        selector: ({ editor: e }) => ({
+            bold: e.isActive("bold"),
+            italic: e.isActive("italic"),
+            underline: e.isActive("underline"),
+            strike: e.isActive("strike"),
+            h2: e.isActive("heading", { level: 2 }),
+            h3: e.isActive("heading", { level: 3 }),
+            bullet: e.isActive("bulletList"),
+            ordered: e.isActive("orderedList"),
+            quote: e.isActive("blockquote"),
+            link: e.isActive("link"),
+            undo: e.can().undo(),
+            redo: e.can().redo(),
+        }),
+    });
+    const chain = () => editor.chain().focus();
+    const toggle = (label, icon, pressed, run) => (_jsx(IconButton, { icon: icon, label: label, "aria-pressed": pressed, disabled: !editor.isEditable, 
+        /* Keeps the selection: a press that blurred the editor would format nothing. */
+        onMouseDown: (event) => event.preventDefault(), onClick: run }, label));
+    return (_jsx("div", { className: "border-b border-line px-1 py-1", children: _jsxs(Toolbar, { label: copy.toolbar, children: [toggle(copy.bold, Bold, on.bold, () => chain().toggleBold().run()), toggle(copy.italic, Italic, on.italic, () => chain().toggleItalic().run()), full
+                    ? toggle(copy.underline, Underline, on.underline, () => chain().toggleUnderline().run())
+                    : null, full
+                    ? toggle(copy.strike, Strikethrough, on.strike, () => chain().toggleStrike().run())
+                    : null, _jsx(ToolbarSeparator, {}), full
+                    ? toggle(copy.heading, Heading2, on.h2, () => chain().toggleHeading({ level: 2 }).run())
+                    : null, full
+                    ? toggle(copy.subheading, Heading3, on.h3, () => chain().toggleHeading({ level: 3 }).run())
+                    : null, toggle(copy.bulletList, List, on.bullet, () => chain().toggleBulletList().run()), toggle(copy.orderedList, ListOrdered, on.ordered, () => chain().toggleOrderedList().run()), full
+                    ? toggle(copy.quote, TextQuote, on.quote, () => chain().toggleBlockquote().run())
+                    : null, _jsx(ToolbarSeparator, {}), _jsx(PopoverTrigger, { title: copy.link, trigger: _jsx(IconButton, { icon: LinkIcon, label: copy.link, "aria-pressed": on.link, disabled: !editor.isEditable }), children: (close) => _jsx(LinkForm, { editor: editor, close: close }) }), full ? (_jsx(IconButton, { icon: Table, label: copy.table, disabled: !editor.isEditable, onMouseDown: (event) => event.preventDefault(), onClick: () => chain().insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run() })) : null, full ? (_jsxs(_Fragment, { children: [_jsx(ToolbarSeparator, {}), _jsx(IconButton, { icon: Undo2, label: copy.undo, disabled: !on.undo, onMouseDown: (event) => event.preventDefault(), onClick: () => chain().undo().run() }), _jsx(IconButton, { icon: Redo2, label: copy.redo, disabled: !on.redo, onMouseDown: (event) => event.preventDefault(), onClick: () => chain().redo().run() }), _jsx(IconButton, { icon: RemoveFormatting, label: copy.clear, disabled: !editor.isEditable, onMouseDown: (event) => event.preventDefault(), onClick: () => chain().unsetAllMarks().clearNodes().run() })] })) : null] }) }));
+}
+/** The list that opens on «@»: fixed under the caret, moved through from the editor. */
+function MentionList({ asking, active, listId, }) {
+    const copy = useUiCopy().richText;
+    const rect = asking.rect;
+    if (rect === null)
+        return null;
+    return (_jsx("ul", { id: listId, role: "listbox", "aria-label": copy.mentions, className: "fixed z-50 flex w-64 flex-col rounded-panel border border-line-strong bg-surface p-1 shadow-float", style: { left: rect.left, top: rect.bottom + 4 }, children: asking.items.length === 0 ? (_jsx("li", { role: "option", "aria-selected": false, "aria-disabled": true, className: "px-2 py-1 text-meta text-muted", children: copy.noMatches })) : (asking.items.map((item, index) => (_jsx("li", { id: `${listId}-${index}`, role: "option", "aria-selected": index === active, onMouseDown: (event) => {
+                event.preventDefault();
+                asking.pick(item);
+            }, className: `cursor-default rounded-control px-2 py-1 text-meta text-ink ${index === active ? "bg-primary/8" : ""}`, children: item.label }, item.id)))) }));
+}
+export function RichTextEditor({ id, labelledBy, describedBy, invalid, ariaLabel, value, onChange, placeholder, disabled, toolbar, mentions, }) {
+    const changed = useRef(onChange);
+    changed.current = onChange;
+    const searching = useRef(mentions);
+    searching.current = mentions;
+    const [asking, setAsking] = useState(null);
+    const [active, setActive] = useState(0);
+    const activeRef = useRef(0);
+    activeRef.current = active;
+    const askingRef = useRef(null);
+    askingRef.current = asking;
+    const listId = useId();
+    const editor = useEditor({
+        immediatelyRender: false,
+        editable: !disabled,
+        content: value,
+        extensions: [
+            StarterKit.configure({
+                heading: { levels: [2, 3] },
+                link: {
+                    openOnClick: false,
+                    autolink: true,
+                    HTMLAttributes: { rel: "noopener noreferrer", target: "_blank" },
+                },
+            }),
+            TableKit.configure({ table: { resizable: false } }),
+            ...(placeholder === undefined ? [] : [Placeholder.configure({ placeholder })]),
+            ...(mentions === undefined
+                ? []
+                : [
+                    Mention.configure({
+                        HTMLAttributes: { "data-type": "mention" },
+                        renderText: ({ node }) => `@${String(node.attrs["label"] ?? node.attrs["id"])}`,
+                        suggestion: {
+                            char: "@",
+                            items: async ({ query }) => [...((await searching.current?.(query)) ?? [])],
+                            render: () => {
+                                const show = (props) => {
+                                    setActive(0);
+                                    setAsking({
+                                        items: props.items,
+                                        rect: props.clientRect?.() ?? null,
+                                        pick: (item) => props.command({ id: item.id, label: item.label }),
+                                    });
+                                };
+                                return {
+                                    onStart: show,
+                                    onUpdate: show,
+                                    onExit: () => setAsking(null),
+                                    onKeyDown: ({ event }) => {
+                                        const now = askingRef.current;
+                                        if (now === null)
+                                            return false;
+                                        const count = now.items.length;
+                                        if (event.key === "Escape") {
+                                            setAsking(null);
+                                            return true;
+                                        }
+                                        if (count === 0)
+                                            return false;
+                                        if (event.key === "ArrowDown") {
+                                            setActive((activeRef.current + 1) % count);
+                                            return true;
+                                        }
+                                        if (event.key === "ArrowUp") {
+                                            setActive((activeRef.current - 1 + count) % count);
+                                            return true;
+                                        }
+                                        if (event.key === "Enter" || event.key === "Tab") {
+                                            const item = now.items[activeRef.current];
+                                            if (item !== undefined)
+                                                now.pick(item);
+                                            return true;
+                                        }
+                                        return false;
+                                    },
+                                };
+                            },
+                        },
+                    }),
+                ]),
+        ],
+        editorProps: {
+            attributes: {
+                class: "rich-text min-h-24 max-h-96 overflow-y-auto px-2.5 py-2 outline-0",
+                role: "textbox",
+                "aria-multiline": "true",
+            },
+        },
+        onUpdate: ({ editor: e }) => changed.current?.(e.isEmpty ? "" : e.getHTML()),
+    });
+    /* The field's wiring on the editable element itself — React Aria-style ids from `Field`,
+       kept in step when they change (an error appears, the label is renamed). */
+    useEffect(() => {
+        const dom = editor?.view.dom;
+        if (dom === undefined)
+            return;
+        const set = (name, next) => next === undefined ? dom.removeAttribute(name) : dom.setAttribute(name, next);
+        set("id", id);
+        set("aria-labelledby", labelledBy);
+        set("aria-label", labelledBy === undefined ? (ariaLabel ?? placeholder) : undefined);
+        set("aria-describedby", describedBy);
+        set("aria-invalid", invalid ? "true" : undefined);
+        set("aria-controls", asking === null ? undefined : listId);
+        set("aria-activedescendant", asking === null || asking.items.length === 0 ? undefined : `${listId}-${active}`);
+    }, [
+        editor,
+        id,
+        labelledBy,
+        describedBy,
+        invalid,
+        ariaLabel,
+        placeholder,
+        asking,
+        active,
+        listId,
+    ]);
+    useEffect(() => editor?.setEditable(!disabled), [editor, disabled]);
+    /* A value written from outside (a reset, a suggestion applied) replaces the content — but
+       never while the person is typing, which would move their caret. */
+    useEffect(() => {
+        if (editor === null || editor.isFocused)
+            return;
+        const current = editor.isEmpty ? "" : editor.getHTML();
+        if (current !== value)
+            editor.commands.setContent(value === "" ? "" : value, { emitUpdate: false });
+    }, [editor, value]);
+    return (_jsxs("div", { className: `w-full min-w-0 overflow-clip rounded-control border bg-surface transition-colors duration-(--duration-instant) focus-within:outline-2 focus-within:outline-offset-2 ${invalid
+            ? "border-danger focus-within:outline-danger"
+            : "border-line-strong focus-within:border-primary focus-within:outline-primary"} ${disabled ? "bg-ground text-muted" : ""}`, children: [editor === null || toolbar === "none" ? null : (_jsx(Bar, { editor: editor, full: toolbar === "full" })), _jsx(EditorContent, { editor: editor }), asking === null ? null : (_jsx(MentionList, { asking: asking, active: active, listId: listId }))] }));
+}

package/dist/primitives/field/RichTextInput.d.ts

@@ -0,0 +1,30 @@
+import type { ControlProps } from "./Field.js";
+import type { MentionItem } from "./RichTextEditor.js";
+/**
+ * Formatted text — a description, the notes of an order, the body of an email: an Odoo `html`
+ * field. The value is HTML in and HTML out.
+ *
+ * Context: Tiptap (ProseMirror) underneath because it is headless — the toolbar is the
+ * system's own `Toolbar` of `IconButton`s, so the editor looks like every other control —
+ * and because it reads and writes HTML, which is what the engine stores. The editor is a
+ * separate chunk loaded only on editing; until it arrives, a box of the editor's size holds
+ * the place so the form does not jump.
+ *
+ * Read mode never mounts an editor: it draws `RichTextValue`, the same HTML CLEANED of
+ * anything that runs (DOMPurify), in the same `rich-text` style the editor uses — so what is
+ * written is what is read, line for line.
+ *
+ * `toolbar` picks how much to offer: `full` (headings, quote, table, undo), `basic` (bold,
+ * italic, lists, link — a comment), `none` (only the keyboard shortcuts). `mentions` turns on
+ * «@»: the application answers who matches what was typed.
+ */
+export declare function RichTextInput({ id: ownId, value, onChange, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled, mode, toolbar, mentions, "aria-label": ariaLabel, }: ControlProps & {
+    /** HTML. `""` is empty. */
+    value: string;
+    onChange?: (html: string) => void;
+    placeholder?: string;
+    toolbar?: "full" | "basic" | "none";
+    /** Who can be mentioned with «@», for what was typed after it. */
+    mentions?: (query: string) => readonly MentionItem[] | Promise<readonly MentionItem[]>;
+}): import("react").JSX.Element;
+export type { MentionItem };

package/dist/primitives/field/RichTextInput.js

@@ -0,0 +1,38 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFieldIds, useFormMode } from "../../foundations/form.js";
+import { RichTextValue } from "../value/RichText.js";
+import { lazy, Suspense } from "react";
+/* The editor (Tiptap + ProseMirror) is its own chunk: fetched the first time a rich-text
+   field is EDITED, never by a record that is only read. */
+const RichTextEditor = lazy(() => import("./RichTextEditor.js").then((module) => ({
+    default: module.RichTextEditor,
+})));
+/**
+ * Formatted text — a description, the notes of an order, the body of an email: an Odoo `html`
+ * field. The value is HTML in and HTML out.
+ *
+ * Context: Tiptap (ProseMirror) underneath because it is headless — the toolbar is the
+ * system's own `Toolbar` of `IconButton`s, so the editor looks like every other control —
+ * and because it reads and writes HTML, which is what the engine stores. The editor is a
+ * separate chunk loaded only on editing; until it arrives, a box of the editor's size holds
+ * the place so the form does not jump.
+ *
+ * Read mode never mounts an editor: it draws `RichTextValue`, the same HTML CLEANED of
+ * anything that runs (DOMPurify), in the same `rich-text` style the editor uses — so what is
+ * written is what is read, line for line.
+ *
+ * `toolbar` picks how much to offer: `full` (headings, quote, table, undo), `basic` (bold,
+ * italic, lists, link — a comment), `none` (only the keyboard shortcuts). `mentions` turns on
+ * «@»: the application answers who matches what was typed.
+ */
+export function RichTextInput({ id: ownId, value, onChange, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, mode, toolbar = "full", mentions, "aria-label": ariaLabel, }) {
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    if (useFormMode(mode) === "read")
+        return _jsx(RichTextValue, { value: value });
+    return (_jsx(Suspense, { fallback: _jsx("div", { "aria-busy": "true", className: "h-32 w-full min-w-0 animate-reveal-late rounded-control border border-line-strong bg-ground" }), children: _jsx(RichTextEditor, { id: id, labelledBy: labelledBy, describedBy: describedBy, invalid: invalid, ariaLabel: ariaLabel, value: value, onChange: onChange, placeholder: placeholder, disabled: disabled, toolbar: toolbar, mentions: mentions }) }));
+}

package/dist/primitives/field/SignatureInput.d.ts

@@ -0,0 +1,34 @@
+import { type ControlProps } from "./Field.js";
+/**
+ * A signature: drawn with the mouse, a pen or a finger — or typed, for whoever cannot draw.
+ *
+ * Context: the pad is a canvas that follows the pointer (`touch-none`, so a finger draws
+ * instead of scrolling the page) and smooths each stroke through the midpoints of its
+ * samples (`strokeSteps`) — no pressure, no library, and no corners. When a stroke ends the
+ * pad is exported as a PNG data URL and handed to `onChange`; «Limpiar» empties it and
+ * hands `null`.
+ *
+ * **A canvas alone shuts people out.** Whoever works with a keyboard or a screen reader, or
+ * whose hand does not hold a pointer steady, cannot draw. «Escribir mi nombre» turns the pad
+ * into a text box: the name typed (starting from `name`, when the form knows who signs) is
+ * written into the same PNG in the system's font, in italic, on the same line — the value
+ * has the same shape whichever way it was made, and the form does not have to know.
+ *
+ * **The pad is paper.** It is a forced-light subtree (`data-theme="light"`): the pen reads
+ * `--color-ink` there, so a signature made in the dark theme is still dark ink on a
+ * transparent PNG — the thing a printed contract or a PDF expects — and read mode lays it on
+ * the same paper, so it is legible on either theme.
+ *
+ * A value that did not come from this pad (a signature already saved) is shown as it is,
+ * not drawn over: «Limpiar» starts a new one. In read mode it draws the image.
+ */
+export declare function SignatureInput({ id: ownId, value, onChange, name, alt, describedBy: ownDescribedBy, invalid: ownInvalid, disabled, mode, "aria-label": ariaLabel, }: ControlProps & {
+    /** The signature as an image: a PNG data URL from this pad, or the URL of a saved one.
+     *  `null` or `""` is unsigned. */
+    value: string | null;
+    onChange?: (next: string | null) => void;
+    /** Who signs, to start the typed signature with. */
+    name?: string;
+    /** What the image is called to a screen reader. «Firma» by default. */
+    alt?: string;
+}): import("react").JSX.Element;

package/dist/primitives/field/SignatureInput.js

@@ -0,0 +1,215 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { useFieldIds, useFormMode } from "../../foundations/form.js";
+import { cn } from "../../foundations/variants.js";
+import { Button } from "../button/Button.js";
+import { controlClasses, nameOf, ReadValue, } from "./Field.js";
+import { capturePointer, fitFontSize, strokeSteps, } from "./media.js";
+import { Eraser, PenLine, Type } from "lucide-react";
+import { useEffect, useId, useRef, useState } from "react";
+/** The pen, in CSS pixels: the weight of a ballpoint at the size the pad is drawn. */
+const PEN = 2.25;
+/** Where the line sits, from the top of the pad — the same fraction the drawn line uses
+ *  (`bottom-1/4`), so a typed name rests on the line the person sees. */
+const BASELINE = 0.75;
+/** The gap between the pad's edge and the start of a typed name — `inset-x-4`. */
+const INSET = 16;
+/** The pen's colour: the INK token of the paper the canvas is on, read when it paints. The
+ *  pad is a light subtree (see below), so this is the dark ink in either theme. */
+function inkOf(el) {
+    const style = getComputedStyle(el);
+    return style.getPropertyValue("--color-ink").trim() || style.color;
+}
+function paint(canvas, strokes) {
+    const ctx = canvas.getContext("2d");
+    if (ctx === null)
+        return;
+    const dpr = canvas.clientWidth === 0 ? 1 : canvas.width / canvas.clientWidth;
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    const ink = inkOf(canvas);
+    ctx.strokeStyle = ink;
+    ctx.fillStyle = ink;
+    ctx.lineWidth = PEN;
+    ctx.lineCap = "round";
+    ctx.lineJoin = "round";
+    for (const stroke of strokes) {
+        ctx.beginPath();
+        for (const step of strokeSteps(stroke)) {
+            if (step.kind === "dot") {
+                ctx.arc(step.at.x, step.at.y, PEN / 2, 0, Math.PI * 2);
+                ctx.fill();
+            }
+            else if (step.kind === "move")
+                ctx.moveTo(step.to.x, step.to.y);
+            else if (step.kind === "quad") {
+                ctx.quadraticCurveTo(step.control.x, step.control.y, step.to.x, step.to.y);
+            }
+            else
+                ctx.lineTo(step.to.x, step.to.y);
+        }
+        ctx.stroke();
+    }
+}
+/** A typed name, written as a signature: the system's font in italic, on the line, as big as
+ *  the pad allows and smaller when the name is long. */
+function typedSignature(text, pad) {
+    const dpr = window.devicePixelRatio || 1;
+    const width = pad.clientWidth || 480;
+    const height = pad.clientHeight || 128;
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.round(width * dpr);
+    canvas.height = Math.round(height * dpr);
+    const ctx = canvas.getContext("2d");
+    if (ctx === null)
+        return "";
+    ctx.scale(dpr, dpr);
+    const family = getComputedStyle(pad).fontFamily;
+    const font = (size) => `italic 400 ${size}px ${family}`;
+    const base = Math.round(height * 0.42);
+    ctx.font = font(base);
+    const size = fitFontSize(ctx.measureText(text).width, base, width - INSET * 2);
+    ctx.font = font(size);
+    ctx.fillStyle = inkOf(pad);
+    ctx.textBaseline = "alphabetic";
+    ctx.fillText(text, INSET, height * BASELINE - 2);
+    return canvas.toDataURL("image/png");
+}
+/**
+ * A signature: drawn with the mouse, a pen or a finger — or typed, for whoever cannot draw.
+ *
+ * Context: the pad is a canvas that follows the pointer (`touch-none`, so a finger draws
+ * instead of scrolling the page) and smooths each stroke through the midpoints of its
+ * samples (`strokeSteps`) — no pressure, no library, and no corners. When a stroke ends the
+ * pad is exported as a PNG data URL and handed to `onChange`; «Limpiar» empties it and
+ * hands `null`.
+ *
+ * **A canvas alone shuts people out.** Whoever works with a keyboard or a screen reader, or
+ * whose hand does not hold a pointer steady, cannot draw. «Escribir mi nombre» turns the pad
+ * into a text box: the name typed (starting from `name`, when the form knows who signs) is
+ * written into the same PNG in the system's font, in italic, on the same line — the value
+ * has the same shape whichever way it was made, and the form does not have to know.
+ *
+ * **The pad is paper.** It is a forced-light subtree (`data-theme="light"`): the pen reads
+ * `--color-ink` there, so a signature made in the dark theme is still dark ink on a
+ * transparent PNG — the thing a printed contract or a PDF expects — and read mode lays it on
+ * the same paper, so it is legible on either theme.
+ *
+ * A value that did not come from this pad (a signature already saved) is shown as it is,
+ * not drawn over: «Limpiar» starts a new one. In read mode it draws the image.
+ */
+export function SignatureInput({ id: ownId, value, onChange, name = "", alt, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, mode, "aria-label": ariaLabel, }) {
+    const copy = useUiCopy();
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    const readMode = useFormMode(mode) === "read";
+    const [typing, setTyping] = useState(false);
+    const [typed, setTyped] = useState(name);
+    const pad = useRef(null);
+    const canvas = useRef(null);
+    const strokes = useRef([]);
+    const drawing = useRef(false);
+    /* The last value this pad handed out: a `value` equal to it is the pad's own work, and the
+       canvas keeps drawing it; anything else came from outside and is shown as an image. */
+    const emitted = useRef(null);
+    const own = useId();
+    const helpId = `${own}-help`;
+    const has = value !== null && value !== "";
+    const stored = has && value !== emitted.current;
+    const label = alt ?? copy.media.signature;
+    /* The canvas is as many device pixels as it is drawn at, or the line blurs on a dense
+       screen; a resize repaints the strokes, which are kept in CSS pixels. */
+    useEffect(() => {
+        const el = canvas.current;
+        if (el === null)
+            return;
+        const fit = () => {
+            const dpr = window.devicePixelRatio || 1;
+            el.width = Math.max(1, Math.round(el.clientWidth * dpr));
+            el.height = Math.max(1, Math.round(el.clientHeight * dpr));
+            paint(el, strokes.current);
+        };
+        fit();
+        const observer = new ResizeObserver(fit);
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [typing, stored, readMode]);
+    if (readMode) {
+        return has ? (_jsx("span", { "data-theme": "light", className: "inline-flex rounded-control border border-line bg-surface p-1", children: _jsx("img", { src: value, alt: label, className: "h-16 w-auto" }) })) : (_jsx(ReadValue, { value: null }));
+    }
+    const emit = (next) => {
+        emitted.current = next;
+        onChange?.(next);
+    };
+    const pointOf = (event) => {
+        const box = event.currentTarget.getBoundingClientRect();
+        return { x: event.clientX - box.left, y: event.clientY - box.top };
+    };
+    function onPointerDown(event) {
+        if (disabled || (event.pointerType === "mouse" && event.button !== 0))
+            return;
+        capturePointer(event);
+        drawing.current = true;
+        strokes.current.push([pointOf(event)]);
+        paint(event.currentTarget, strokes.current);
+    }
+    function onPointerMove(event) {
+        if (!drawing.current)
+            return;
+        const stroke = strokes.current[strokes.current.length - 1];
+        if (stroke === undefined)
+            return;
+        /* The samples the browser merged into this event: a fast stroke between two frames is
+           several points, and drawing only the last one cuts its curves into chords. */
+        const native = event.nativeEvent;
+        const samples = typeof native.getCoalescedEvents === "function" ? native.getCoalescedEvents() : [];
+        const box = event.currentTarget.getBoundingClientRect();
+        if (samples.length > 0) {
+            for (const one of samples)
+                stroke.push({ x: one.clientX - box.left, y: one.clientY - box.top });
+        }
+        else
+            stroke.push(pointOf(event));
+        paint(event.currentTarget, strokes.current);
+    }
+    function onPointerUp(event) {
+        if (!drawing.current)
+            return;
+        drawing.current = false;
+        emit(event.currentTarget.toDataURL("image/png"));
+    }
+    function clear() {
+        strokes.current = [];
+        if (canvas.current !== null)
+            paint(canvas.current, []);
+        if (typing)
+            setTyped("");
+        emit(null);
+    }
+    function writeTyped(text) {
+        setTyped(text);
+        emit(text.trim() === "" || pad.current === null ? null : typedSignature(text, pad.current));
+    }
+    /* One signature, either way: switching starts the other one from scratch, and a typed name
+       that is already there is written at once. */
+    function switchMode() {
+        strokes.current = [];
+        if (typing) {
+            setTyping(false);
+            emit(null);
+        }
+        else {
+            setTyping(true);
+            writeTyped(typed);
+        }
+    }
+    const paper = cn("relative h-32 w-full overflow-clip rounded-control border bg-surface font-sans text-ink", invalid ? "border-danger" : "border-line-strong", disabled ? "bg-ground" : "");
+    return (_jsxs("div", { id: id, role: "group", "aria-labelledby": labelledBy, "aria-label": nameOf(labelledBy, ariaLabel), "aria-describedby": describedBy, className: "flex w-full min-w-0 flex-col gap-2", children: [_jsxs("div", { ref: pad, "data-theme": "light", className: paper, children: [stored || (typing && has) ? (_jsx("img", { src: value ?? "", alt: label, className: "size-full object-contain object-left" })) : typing ? null : (_jsx("canvas", { ref: canvas, role: "img", "aria-label": copy.media.signaturePad, "aria-describedby": helpId, onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: onPointerUp, onPointerCancel: onPointerUp, className: cn("absolute inset-0 size-full touch-none", disabled ? "cursor-not-allowed" : "cursor-crosshair") })), _jsx("span", { "aria-hidden": true, className: "pointer-events-none absolute inset-x-4 bottom-1/4 border-t border-line-strong" })] }), typing ? (_jsxs("label", { className: "flex flex-col gap-1 text-micro font-medium text-muted", children: [copy.media.typedName, _jsx("input", { 
+                        /* The person asked for this box by pressing the button: the focus goes there. */
+                        autoFocus: true, value: typed, disabled: disabled, autoComplete: "name", onChange: (event) => writeTyped(event.target.value), className: `${controlClasses(invalid)} font-normal` })] })) : (_jsx("p", { id: helpId, className: "text-micro text-muted", children: copy.media.signatureHelp })), _jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsx(Button, { size: "sm", icon: typing ? PenLine : Type, disabled: disabled, onClick: switchMode, children: typing ? copy.media.drawInstead : copy.media.typeName }), _jsx(Button, { role: "ghost", size: "sm", icon: Eraser, disabled: disabled, onClick: clear, children: copy.media.clear })] })] }));
+}

package/dist/primitives/field/card.d.ts

@@ -0,0 +1,33 @@
+export type CardBrand = "visa" | "mastercard" | "amex" | "discover" | "diners" | "jcb" | "unionpay" | "maestro";
+/** The longest a card number gets, of any brand. */
+export declare const CARD_MAX_DIGITS = 19;
+/** Only the digits of what was typed or pasted: «4242 4242-4242» → «424242424242». */
+export declare function cardDigits(text: string): string;
+/** The brand the first digits say, or `null` while they do not say one yet. */
+export declare function cardBrand(digits: string): CardBrand | null;
+/** How the brand is written: «American Express». */
+export declare function cardBrandName(brand: CardBrand): string;
+/** The most digits a number of this brand takes — where typing stops. */
+export declare function cardMaxDigits(digits: string, brand?: CardBrand | null): number;
+/** The digits in the brand's groups: «378282246310005» → «3782 822463 10005». */
+export declare function formatCardNumber(digits: string, brand?: CardBrand | null): string;
+/** The Luhn check digit holds: a mistyped digit or two swapped neighbours fail it. */
+export declare function luhnValid(digits: string): boolean;
+/** A whole number: a known brand, one of its lengths, and the check digit holds. */
+export declare function isValidCardNumber(digits: string): boolean;
+/** Only the last four, the way a card is shown once it is stored: «•••• 4242». */
+export declare function maskCardNumber(digits: string): string;
+/** The digits of an expiry, a leading zero put in for a month that can only be one digit:
+ *  «4» is April, so «04»; «1» may still be October. At most four: MMAA. */
+export declare function expiryDigits(text: string): string;
+/** How the expiry reads: «1228» → «12/28». */
+export declare function formatExpiry(digits: string): string;
+/** The month and the full year of a whole expiry, or `null` while it is not one. */
+export declare function expiryParts(digits: string): {
+    month: number;
+    year: number;
+} | null;
+/** A real month that has not ended yet: a card is good through the last day of its month. */
+export declare function isExpiryValid(digits: string, now?: Date): boolean;
+/** How many digits the security code has: four on the front of an Amex, three elsewhere. */
+export declare function cardCodeLength(brand: CardBrand | null | undefined): 3 | 4;