@sincpro/web-ui 1.5.0 → 1.7.0

package/dist/primitives/field/PasswordInput.js

@@ -0,0 +1,44 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { useFieldIds, useFormMode } from "../../foundations/form.js";
+import { FieldButton, FieldGroup } from "./aria.js";
+import { nameOf, ReadValue } from "./Field.js";
+import { Eye, EyeOff, TriangleAlert } from "lucide-react";
+import { useId, useState } from "react";
+import { Input, TextField as AriaTextField } from "react-aria-components";
+/**
+ * A password: hidden while it is typed, shown on purpose with the eye.
+ *
+ * Context: it is `TextInput`'s wiring — React Aria's `TextField`, named and described by
+ * its `Field` through `useFieldIds` — with three things a password owes and a text does not:
+ *
+ * - **The eye.** Typing blind is where a long password goes wrong; the button shows it as
+ *   text and hides it again, and says which of the two it will do. `revealable={false}`
+ *   removes it, for a screen where it must not be shown.
+ * - **Caps Lock.** The most common reason a right password is refused. While it is on, a
+ *   line under the control says so — in the warn tone, with an icon and the words.
+ * - **Read mode never shows it.** It draws a fixed row of dots, the same for every length
+ *   (a length is a hint), and says «password set» to a screen reader. The field's copy
+ *   button copies what is SEEN: the dots are not a value, and a hidden input is skipped
+ *   (`clipboard.tsx`); revealed, it copies like any text.
+ *
+ * `autoComplete` tells a password manager what this is: `current-password` fills a login,
+ * `new-password` offers to generate one.
+ */
+export function PasswordInput({ id: ownId, value, onChange, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, mode, autoComplete = "current-password", revealable = true, "aria-label": ariaLabel, }) {
+    const copy = useUiCopy();
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    const [shown, setShown] = useState(false);
+    const [capsLock, setCapsLock] = useState(false);
+    const capsId = `${useId()}-caps`;
+    if (useFormMode(mode) === "read") {
+        return (_jsx(ReadValue, { value: value === "" ? null : (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, "data-copy-skip": "", className: "tracking-widest", children: "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022" }), _jsx("span", { className: "sr-only", children: copy.field.secretSet })] })) }));
+    }
+    const readCaps = (event) => setCapsLock(event.getModifierState("CapsLock"));
+    return (_jsxs("div", { className: "flex w-full min-w-0 flex-col gap-1", children: [_jsx(AriaTextField, { id: id, "aria-labelledby": labelledBy, "aria-label": nameOf(labelledBy, ariaLabel, placeholder), value: value, onChange: (next) => onChange?.(next), type: shown ? "text" : "password", autoComplete: autoComplete, isInvalid: invalid, isDisabled: disabled, className: "w-full min-w-0", children: _jsxs(FieldGroup, { isInvalid: invalid, isDisabled: disabled, children: [_jsx(Input, { "aria-describedby": [describedBy, capsLock ? capsId : null].filter(Boolean).join(" ") || undefined, placeholder: placeholder, spellCheck: false, onKeyDown: readCaps, onKeyUp: readCaps, onBlur: () => setCapsLock(false), className: "h-full min-w-0 flex-1 bg-transparent px-2.5 text-meta text-ink outline-0 placeholder:text-muted disabled:cursor-not-allowed" }), revealable ? (_jsx(FieldButton, { "aria-label": shown ? copy.field.hideSecret : copy.field.showSecret, isDisabled: disabled, onPress: () => setShown((now) => !now), className: "mr-1", children: shown ? (_jsx(EyeOff, { "aria-hidden": true, className: "size-(--size-icon-sm)", strokeWidth: 2 })) : (_jsx(Eye, { "aria-hidden": true, className: "size-(--size-icon-sm)", strokeWidth: 2 })) })) : null] }) }), capsLock ? (_jsxs("p", { id: capsId, className: "flex items-center gap-1.5 text-micro text-warn", children: [_jsx(TriangleAlert, { "aria-hidden": true, className: "size-(--size-icon-sm) shrink-0", strokeWidth: 2 }), copy.field.capsLock] })) : null] }));
+}

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

@@ -0,0 +1,23 @@
+import { type ControlProps } from "./Field.js";
+/**
+ * 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 declare function PatternInput({ id: ownId, value, onChange, pattern, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled, mode, "aria-label": ariaLabel, }: ControlProps & {
+    /** The characters only, without separators. */
+    value: string;
+    onChange?: (value: string) => void;
+    /** «###-#######», «AA## #### #### ####». */
+    pattern: string;
+    /** Without one, the pattern itself with `0` for a digit: «000-0000000». */
+    placeholder?: string;
+}): import("react").JSX.Element;

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;