@sincpro/web-ui 0.1.0 → 1.0.0

package/dist/primitives/dialog/Dialog.js

@@ -1,10 +1,11 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useUiCopy } from "../../foundations/copy.js";
+import { HANDHELD_WIDTH } from "../../foundations/layout.js";
 import { cn, tv } from "../../foundations/variants.js";
 import { Button, IconButton } from "../button/Button.js";
 import { Maximize2, X } from "lucide-react";
-import { useId } from "react";
+import { useEffect, useId, useState } from "react";
 import { Dialog as AriaDialog, Heading, Modal, ModalOverlay } from "react-aria-components";
 /** The scrim. The page stays visible under it — the dialog is ABOUT something on it.
  *  On a phone it drops the padding and pushes the window to the bottom edge. */
@@ -39,11 +40,11 @@ export const dialogStyles = { overlay, modal };
  *
  *  Internal — exported only so a test can read its markup, which the modal (a portal)
  *  does not produce on the server. */
-export function DialogSurface({ title, subtitle, context, onClose, onExpand, expandLabel, footer, children, }) {
+export function DialogSurface({ title, subtitle, context, onClose, onExpand, expandLabel, footer, children, onDragStart, }) {
     const copy = useUiCopy();
     const subtitleId = useId();
     const expand = expandLabel ?? copy.dialog.expand;
-    return (_jsxs(AriaDialog, { "aria-describedby": subtitle === undefined ? undefined : subtitleId, className: "flex max-h-[inherit] min-h-0 flex-1 flex-col outline-0", children: [_jsxs("header", { className: "flex shrink-0 items-start gap-3 border-b border-line px-4 py-3", children: [_jsxs("div", { className: "min-w-0 flex-1", children: [context === undefined ? null : (
+    return (_jsxs(AriaDialog, { "aria-describedby": subtitle === undefined ? undefined : subtitleId, className: "flex max-h-[inherit] min-h-0 flex-1 flex-col outline-0", children: [_jsxs("header", { onPointerDown: onDragStart, className: cn("flex shrink-0 items-start gap-3 border-b border-line px-4 py-3", onDragStart !== undefined && "cursor-grab select-none active:cursor-grabbing"), children: [_jsxs("div", { className: "min-w-0 flex-1", children: [context === undefined ? null : (
                             /* The context, on top and small. It is what keeps the first field
                                from being «about what?». Same voice as a field label, not a
                                console kicker: mono uppercase next to a form title was a
@@ -59,11 +60,46 @@ export function DialogSurface({ title, subtitle, context, onClose, onExpand, exp
  * stays mounted for the exit transition after `open` turns `false`, so the window fades
  * out instead of vanishing.
  */
-export function Dialog({ open, width = "md", onClose, ...surface }) {
+export function Dialog({ open, width = "md", onClose, movable = false, ...surface }) {
+    const [offset, setOffset] = useState({ x: 0, y: 0 });
+    /* Every opening starts centred: where it was dragged last time is not where it belongs. */
+    useEffect(() => {
+        if (open)
+            setOffset({ x: 0, y: 0 });
+    }, [open]);
+    /* `transform` and not `translate`: the window enters and leaves on `translate`, which is
+       transitioned — a drag on it would trail the pointer by the panel's duration. */
+    const drag = (event) => {
+        if (event.button !== 0 || event.pointerType === "touch")
+            return;
+        if (event.target.closest("button, a, input") !== null)
+            return;
+        /* Below it the window is a bottom sheet, and a sheet is not dragged around. */
+        if (window.innerWidth < HANDHELD_WIDTH)
+            return;
+        const from = { x: event.clientX - offset.x, y: event.clientY - offset.y };
+        /* Never further than half the screen from the centre: the header — the only handle — has
+           to stay where a pointer can reach it. */
+        const halfW = window.innerWidth / 2;
+        const halfH = window.innerHeight / 2;
+        const clamp = (value, half) => Math.max(-half, Math.min(half, value));
+        const move = (next) => setOffset({
+            x: clamp(next.clientX - from.x, halfW),
+            y: clamp(next.clientY - from.y, halfH),
+        });
+        const stop = () => {
+            window.removeEventListener("pointermove", move);
+            window.removeEventListener("pointerup", stop);
+        };
+        window.addEventListener("pointermove", move);
+        window.addEventListener("pointerup", stop);
+    };
     return (_jsx(ModalOverlay, { isOpen: open, onOpenChange: (next) => {
             if (!next)
                 onClose();
-        }, isDismissable: true, className: overlay, children: _jsx(Modal, { className: (state) => modal({ ...state, width }), children: _jsx(DialogSurface, { onClose: onClose, ...surface }) }) }));
+        }, isDismissable: true, className: overlay, children: _jsx(Modal, { className: (state) => modal({ ...state, width }), ...(movable
+                ? { style: { transform: `translate(${offset.x}px, ${offset.y}px)` } }
+                : {}), children: _jsx(DialogSurface, { onClose: onClose, ...surface, ...(movable ? { onDragStart: drag } : {}) }) }) }));
 }
 /** A dialog with steps, for what CANNOT be answered in one go.
  *

package/dist/primitives/field/DropZone.js

@@ -7,7 +7,7 @@ import { useFieldIds } from "./context.js";
 import { ReadValue } from "./Field.js";
 import { useFormMode } from "./mode.js";
 import { Failed } from "../notice/Notice.js";
-import { ProgressBar } from "../value/Value.js";
+import { ProgressBar } from "../value/ProgressBar.js";
 import { Button as AriaButton, DropZone as AriaDropZone, FileTrigger, } from "react-aria-components";
 export function DropZone({ accept, label, busy = false, progress, fileName, fileDetail, error, onFile, onCancel, onRetry, id: ownId, describedBy: ownDescribedBy, invalid: ownInvalid, mode, }) {
     const copy = useUiCopy();

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

@@ -1,7 +1,8 @@
 import { type FieldIds } from "./context.js";
 import { type FormMode } from "./mode.js";
+import { type FieldNote } from "./note.js";
 import { type ReactNode } from "react";
-export declare function Field({ label, hint, error, required, children, htmlFor, layout, action, mode, }: {
+export declare function Field({ label, hint, error, required, children, htmlFor, layout, action, mode, note, copy: copyAs, }: {
     label: string;
     /** What is expected. A `?` on the label that opens it on press. */
     hint?: string;
@@ -27,6 +28,13 @@ export declare function Field({ label, hint, error, required, children, htmlFor,
     action?: ReactNode;
     /** Forces the mode of this field. By default it inherits it from the view. */
     mode?: FormMode;
+    /** A note that belongs to THIS field — «vence en 3 días», «tiene una NC sin aplicar ·
+     *  Aplicar». A card in the record's margin when there is one, a `Flag` by the label when
+     *  there is not; its sentence describes the control (`aria-describedby`). See `note.tsx`. */
+    note?: FieldNote;
+    /** The copy button by the label (see `copy.tsx`): on by default, copying what the control
+     *  shows. A string copies that instead; `false` removes the button from this field. */
+    copy?: string | false;
 }): import("react").JSX.Element;
 /**
  * A label with its VALUE, without a control below. What was missing to show a
@@ -40,7 +48,7 @@ export declare function Field({ label, hint, error, required, children, htmlFor,
  * It uses the same geometry as `Field`, so a field that goes from being looked
  * at to being edited does not move anything around it.
  */
-export declare function DataField({ label, value, hint, layout, mono, action, }: {
+export declare function DataField({ label, value, hint, layout, mono, action, note, copy: copyAs, }: {
     label: string;
     /** `undefined` and `null` are drawn with the missing mark: saying there is no
      *  data is information, and a blank line does not give it. */
@@ -50,6 +58,10 @@ export declare function DataField({ label, value, hint, layout, mono, action, }:
     /** The value was written by the machine: an id, a code, an account number. */
     mono?: boolean;
     action?: ReactNode;
+    /** A note that belongs to this value — the same as `Field`'s. */
+    note?: FieldNote;
+    /** The copy button by the label, as `Field`'s: on by default for a value that is there. */
+    copy?: string | false;
 }): import("react").JSX.Element;
 /** What a control draws when the form is LOOKED AT instead of written into.
  *

package/dist/primitives/field/Field.js

@@ -6,12 +6,14 @@ import { byDensity, useDensity } from "../../foundations/density.js";
 import { focusRing, tv } from "../../foundations/variants.js";
 import { FieldGroup, listOptionStyles } from "./aria.js";
 import { FieldIdsContext, useFieldIds, } from "./context.js";
+import { FieldCopy, useFieldCopy } from "./copy.js";
 import { useSheetLayout } from "./layout.js";
 import { FormModeProvider, useFormMode, } from "./mode.js";
+import { describedByOf, NoteCard, NoteFlag, } from "./note.js";
 import { Hint } from "../hint/Hint.js";
 import { Popover } from "../overlay/Popover.js";
 import { AlertCircle, Check, ChevronDown, ChevronUp } from "lucide-react";
-import { useId } from "react";
+import { useId, useRef } from "react";
 import { Button as AriaButton, Input, ListBox, ListBoxItem, NumberField as AriaNumberField, Select as AriaSelect, SelectValue, TextArea as AriaTextArea, TextField as AriaTextField, } from "react-aria-components";
 /* ==================================================================== *
  *  THE CONTROLS — the label is not optional and the error is not a color.
@@ -38,19 +40,24 @@ import { Button as AriaButton, Input, ListBox, ListBoxItem, NumberField as AriaN
  *  control ate a line on every field. The error still goes below, close to
  *  the cursor, and it says what to put.
  * ==================================================================== */
-export function Field({ label, hint, error, required = false, children, htmlFor, layout, action, mode, }) {
+export function Field({ label, hint, error, required = false, children, htmlFor, layout, action, mode, note, copy: copyAs, }) {
     const d = useDensity();
     const copy = useUiCopy();
+    const copies = useFieldCopy() && copyAs !== false;
+    const shown = useRef(null);
     const auto = useId();
     const id = htmlFor ?? auto;
     const sheetLayout = useSheetLayout();
     const inline = layout === "inline" || (layout === undefined && sheetLayout === "horizontal");
     const hintId = `${id}-hint`;
     const errorId = `${id}-error`;
-    const describedBy = [hint === undefined ? null : hintId, error === undefined ? null : errorId]
-        .filter((x) => x !== null)
-        .join(" ") || undefined;
-    const labelNode = (_jsxs("span", { className: `flex min-w-0 items-center gap-1 text-micro font-medium text-muted ${inline ? "pt-2" : ""}`, children: [_jsxs("label", { id: `${id}-label`, htmlFor: id, className: inline ? "min-w-0 truncate" : "", children: [label, required ? (_jsxs(_Fragment, { children: [_jsxs("span", { className: "text-ink", "aria-hidden": true, children: [" ", "*"] }), _jsxs("span", { className: "sr-only", children: [", ", copy.field.required] })] })) : null] }), hint === undefined ? null : _jsx(Hint, { id: hintId, children: hint })] }));
+    const noteId = `${id}-note`;
+    /* The error first: what has to be corrected is heard before what is worth knowing. */
+    const describedBy = describedByOf(hint === undefined ? null : hintId, error === undefined ? null : errorId, note === undefined ? null : noteId);
+    const labelNode = (_jsxs("span", { className: `flex min-w-0 items-center gap-1 text-micro font-medium text-muted ${inline ? "pt-2" : ""}`, children: [_jsxs("label", { id: `${id}-label`, htmlFor: id, className: inline ? "min-w-0 truncate" : "", children: [label, required ? (_jsxs(_Fragment, { children: [_jsxs("span", { className: "text-ink", "aria-hidden": true, children: [" ", "*"] }), _jsxs("span", { className: "sr-only", children: [", ", copy.field.required] })] })) : null] }), hint === undefined ? null : _jsx(Hint, { id: hintId, children: hint }), note === undefined ? null : _jsx(NoteFlag, { note: note }), copies ? (_jsx(FieldCopy, { label: label, scope: shown, ...(typeof copyAs === "string" ? { value: copyAs } : {}) })) : null] }));
+    /* Last in the field so it is read last; absolutely placed, it still sits at the field's
+       top — the static position of an absolute child of a flex or grid box is its start. */
+    const noteCard = note === undefined ? null : _jsx(NoteCard, { note: note, id: noteId, owner: label });
     /* The field's `mode` propagates INWARDS and is not used here: what knows how
        to draw itself as data is the control, not the label. That way a computed
        field stays in read mode inside a form that is being edited, without the
@@ -63,12 +70,12 @@ export function Field({ label, hint, error, required = false, children, htmlFor,
     };
     /* The render prop gets the same context as a control written directly: a system control
        inside it then also finds the label that names it, not only the id it is handed. */
-    const content = (_jsx(FieldIdsContext.Provider, { value: ids, children: typeof children === "function" ? children(ids) : children }));
+    const content = (_jsx(FieldIdsContext.Provider, { value: ids, children: _jsx("div", { ref: shown, className: "contents", children: typeof children === "function" ? children(ids) : children }) }));
     const body = (_jsxs(_Fragment, { children: [mode === undefined ? (content) : (_jsx(FormModeProvider, { value: mode, children: content })), error === undefined ? null : (_jsxs("p", { id: errorId, role: "alert", className: "flex items-start gap-1.5 text-micro text-danger", children: [_jsx(AlertCircle, { className: "mt-px size-(--size-icon-sm) shrink-0", strokeWidth: 2, "aria-hidden": true }), _jsx("span", { className: "max-w-prose", children: error })] }))] }));
     if (inline) {
-        return (_jsxs("div", { className: "grid-label grid min-w-0 items-start gap-x-4 gap-y-1", children: [labelNode, _jsx("div", { className: "flex min-w-0 flex-col gap-1", children: body }), action === undefined ? null : (_jsx("div", { "data-under-control": true, className: "flex items-center gap-2", children: action }))] }));
+        return (_jsxs("div", { className: "grid-label grid min-w-0 items-start gap-x-4 gap-y-1 group/field", children: [labelNode, _jsx("div", { className: "flex min-w-0 flex-col gap-1", children: body }), action === undefined ? null : (_jsx("div", { "data-under-control": true, className: "flex items-center gap-2", children: action })), noteCard] }));
     }
-    return (_jsxs("div", { className: `flex min-w-0 flex-col ${byDensity(d, "gap-1", "gap-0.5")}`, children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [labelNode, action === undefined ? null : _jsx("span", { className: "ml-auto shrink-0", children: action })] }), body] }));
+    return (_jsxs("div", { className: `group/field flex min-w-0 flex-col ${byDensity(d, "gap-1", "gap-0.5")}`, children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [labelNode, action === undefined ? null : _jsx("span", { className: "ml-auto shrink-0", children: action })] }), body, noteCard] }));
 }
 /**
  * A label with its VALUE, without a control below. What was missing to show a
@@ -82,18 +89,22 @@ export function Field({ label, hint, error, required = false, children, htmlFor,
  * It uses the same geometry as `Field`, so a field that goes from being looked
  * at to being edited does not move anything around it.
  */
-export function DataField({ label, value, hint, layout, mono = false, action, }) {
+export function DataField({ label, value, hint, layout, mono = false, action, note, copy: copyAs, }) {
     const d = useDensity();
+    const shown = useRef(null);
+    const allowed = useFieldCopy() && copyAs !== false;
+    const noteId = `${useId()}-note`;
     const sheetLayout = useSheetLayout();
     const inline = layout === "inline" || (layout === undefined && sheetLayout === "horizontal");
     const empty = value === undefined || value === null || value === "";
     const unset = useUiCopy().field.unset;
-    const labelNode = (_jsxs("span", { className: `flex min-w-0 items-center gap-1 text-micro font-medium text-muted ${inline ? "pt-0.5" : ""}`, children: [_jsx("span", { className: inline ? "min-w-0 truncate" : "", children: label }), hint === undefined ? null : _jsx(Hint, { children: hint })] }));
-    const valueNode = (_jsx("span", { className: `min-w-0 text-meta ${empty ? "text-muted italic" : "text-ink"} ${mono ? "font-mono tabular-nums" : ""}`, children: empty ? unset : value }));
+    const labelNode = (_jsxs("span", { className: `flex min-w-0 items-center gap-1 text-micro font-medium text-muted ${inline ? "pt-0.5" : ""}`, children: [_jsx("span", { className: inline ? "min-w-0 truncate" : "", children: label }), hint === undefined ? null : _jsx(Hint, { children: hint }), note === undefined ? null : _jsx(NoteFlag, { note: note }), allowed && !empty ? (_jsx(FieldCopy, { label: label, scope: shown, ...(typeof copyAs === "string" ? { value: copyAs } : {}) })) : null] }));
+    const noteCard = note === undefined ? null : _jsx(NoteCard, { note: note, id: noteId, owner: label });
+    const valueNode = (_jsx("span", { ref: shown, ...(note === undefined ? {} : { "aria-describedby": noteId }), className: `min-w-0 text-meta ${empty ? "text-muted italic" : "text-ink"} ${mono ? "font-mono tabular-nums" : ""}`, children: empty ? unset : value }));
     if (inline) {
-        return (_jsxs("div", { className: "grid-label grid min-w-0 items-baseline gap-x-4 gap-y-0.5", children: [labelNode, _jsxs("span", { className: "flex min-w-0 items-baseline gap-2", children: [valueNode, action] })] }));
+        return (_jsxs("div", { className: "grid-label grid min-w-0 items-baseline gap-x-4 gap-y-0.5 group/field", children: [labelNode, _jsxs("span", { className: "flex min-w-0 items-baseline gap-2", children: [valueNode, action] }), noteCard] }));
     }
-    return (_jsxs("div", { className: `flex min-w-0 flex-col ${byDensity(d, "gap-1", "gap-0.5")}`, children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [labelNode, action === undefined ? null : _jsx("span", { className: "ml-auto shrink-0", children: action })] }), valueNode] }));
+    return (_jsxs("div", { className: `group/field flex min-w-0 flex-col ${byDensity(d, "gap-1", "gap-0.5")}`, children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [labelNode, action === undefined ? null : _jsx("span", { className: "ml-auto shrink-0", children: action })] }), valueNode, noteCard] }));
 }
 /** What a control draws when the form is LOOKED AT instead of written into.
  *

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

@@ -0,0 +1,16 @@
+import { type ReactNode, type RefObject } from "react";
+/** Turns the fields' copy buttons on or off for everything inside. On by default. */
+export declare function FieldCopyProvider({ value, children, }: {
+    value: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useFieldCopy(): boolean;
+/** The text a value area shows, inputs included, placeholders and named buttons left out. */
+export declare function shownText(root: HTMLElement): string;
+/** The button by a field's label. `scope` is the field's value area. */
+export declare function FieldCopy({ label, scope, value, }: {
+    label: string;
+    scope: RefObject<HTMLElement | null>;
+    /** What to copy instead of what is seen. */
+    value?: string;
+}): import("react").JSX.Element;

package/dist/primitives/field/copy.js

@@ -0,0 +1,69 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { CopyButton } from "../value/Copyable.js";
+import { createContext, useContext } from "react";
+/* ==================================================================== *
+ *  THE COPY BUTTON OF A FIELD — what is on screen, to the clipboard.
+ *
+ *  Context: half of what a record shows is there to be pasted somewhere else —
+ *  the customer's name into an email, a NIT into the tax portal, a reference
+ *  into the bank's site. Selecting it by hand fails on exactly those: a
+ *  many2one is a link that OPENS when pressed, a date is three segments, a
+ *  number field holds its value in an input. So every `Field` and `DataField`
+ *  carries a small copy button next to its label, in read mode and in edit
+ *  mode alike, revealed by the pointer or the focus (always shown on a touch
+ *  screen, where there is no hover).
+ *
+ *  ── It copies what is SEEN ──────────────────────────────────────────
+ *
+ *  The field does not know its control's value — the control does — so the
+ *  button reads the value area at the moment of the press: the text drawn,
+ *  plus what the inputs hold (the name a picker shows, a formatted amount),
+ *  skipping placeholders (an empty date's «dd/mm/aaaa»), what is hidden, and
+ *  the named icon buttons inside (a chip's «remove», a summary's «i»). What
+ *  the person sees is what they paste.
+ *
+ *  ── On by default, never imposed ────────────────────────────────────
+ *
+ *  This system gives possibilities; it does not enclose. `copy="…"` copies
+ *  something else (the NIT alone, an id the screen does not draw), `copy={false}`
+ *  removes the button from one field, and `FieldCopyProvider value={false}`
+ *  from a whole form — a login, a wizard where copying means nothing.
+ * ==================================================================== */
+const FieldCopyContext = createContext(true);
+/** Turns the fields' copy buttons on or off for everything inside. On by default. */
+export function FieldCopyProvider({ value, children, }) {
+    return _jsx(FieldCopyContext.Provider, { value: value, children: children });
+}
+export function useFieldCopy() {
+    return useContext(FieldCopyContext);
+}
+/** What skipping means: not seen, or not the value. */
+const SKIP = '[hidden], [aria-hidden="true"], [data-placeholder], .sr-only, button[aria-label], [data-copy-skip], select';
+/** The text a value area shows, inputs included, placeholders and named buttons left out. */
+export function shownText(root) {
+    const parts = [];
+    const walk = (node) => {
+        if (node.nodeType === Node.TEXT_NODE) {
+            parts.push(node.textContent ?? "");
+            return;
+        }
+        if (!(node instanceof HTMLElement) || node.matches(SKIP))
+            return;
+        if (node instanceof HTMLInputElement || node instanceof HTMLTextAreaElement) {
+            if (node.type !== "hidden")
+                parts.push(` ${node.value} `);
+            return;
+        }
+        for (const child of node.childNodes)
+            walk(child);
+    };
+    walk(root);
+    return parts.join("").replace(/\s+/g, " ").trim();
+}
+/** The button by a field's label. `scope` is the field's value area. */
+export function FieldCopy({ label, scope, value, }) {
+    const ui = useUiCopy();
+    return (_jsx("span", { "data-copy-skip": "", className: "inline-flex shrink-0 opacity-0 transition-opacity duration-(--duration-instant) group-hover/field:opacity-100 focus-within:opacity-100 pointer-coarse:opacity-100", children: _jsx(CopyButton, { label: fillCopy(ui.copyable.field, { label }), value: () => value ?? (scope.current === null ? "" : shownText(scope.current)) }) }));
+}

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

@@ -1,7 +1,9 @@
 export { Checkbox, type CheckItem, CheckList } from "./Checks.js";
 export { type FieldIds, useFieldIds } from "./context.js";
+export { FieldCopyProvider, shownText, useFieldCopy, } from "./copy.js";
 export { DropZone, type DropZoneProps } from "./DropZone.js";
 export { controlClasses, DataField, Field, NumberInput, ReadValue, Select, type SelectOption, TextArea, TextInput, } from "./Field.js";
 export { type FieldLayout, FieldLayoutProvider, useSheetLayout, } from "./layout.js";
 export { type FormMode, FormModeProvider, useFormMode, } from "./mode.js";
 export { Suggest, type SuggestProps } from "./Suggest.js";
+export { type FieldNote } from "./note.js";

package/dist/primitives/field/index.js

@@ -4,8 +4,12 @@
    a dialog. */
 export { Checkbox, CheckList } from "./Checks.js";
 export { useFieldIds } from "./context.js";
+/* The copy button every field carries by its label — on by default, off by field or by form. */
+export { FieldCopyProvider, shownText, useFieldCopy, } from "./copy.js";
 export { DropZone } from "./DropZone.js";
 export { controlClasses, DataField, Field, NumberInput, ReadValue, Select, TextArea, TextInput, } from "./Field.js";
 export { FieldLayoutProvider, useSheetLayout, } from "./layout.js";
 export { FormModeProvider, useFormMode, } from "./mode.js";
 export { Suggest } from "./Suggest.js";
+/* A note that belongs to one field: a card in the record's margin, or a flag by its label. */
+export {} from "./note.js";

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

@@ -0,0 +1,55 @@
+import { type FlagTone } from "../notice/Flag.js";
+import { type ReactNode } from "react";
+/** A note anchored to one field: a sentence, what explains it, and what resolves it. */
+export type FieldNote = {
+    /** Without it, `info`. The tone has a shape as well as a colour (`Flag`). */
+    tone?: FlagTone;
+    /** The sentence: «Vence en 3 días». It names the mark and heads the card. */
+    label: string;
+    /** What explains it: «NC/2026/0012 por Bs. 1.200,00, sin aplicar». */
+    detail?: ReactNode;
+    /** What resolves it, if there is something to press: a `Button` with `role="ghost"`
+     *  and `size="sm"` — the record's primary action is not here. */
+    action?: ReactNode;
+};
+/** A note as the record lists it: the note, what it belongs to, and where it is. */
+export type NoteEntry = {
+    id: string;
+    note: FieldNote;
+    /** What it belongs to: «Cliente», «Impresora térmica de tickets 80 mm». */
+    owner: string;
+    /** The field or row it is anchored to — what «take me there» scrolls to. */
+    anchor: () => HTMLElement | null;
+};
+/** The notes mounted in a record. It notifies only when a note appears or goes: a note
+ *  whose words changed is updated in place, so re-rendering a form (new `note` objects on
+ *  every render) does not make the record render again, and again. */
+export type NoteRegistry = {
+    /** Adds the note, or replaces its words without telling anyone. */
+    put: (entry: NoteEntry) => void;
+    /** The note went away. */
+    drop: (id: string) => void;
+    subscribe: (listener: () => void) => () => void;
+    snapshot: () => readonly NoteEntry[];
+};
+export declare function createNoteRegistry(): NoteRegistry;
+/** The registry of the record around — `Record` provides it. */
+export declare const NoteRegistryContext: import("react").Context<NoteRegistry | null>;
+/** The notes mounted in the record around, in the order they were mounted. */
+export declare function useNoteEntries(): readonly NoteEntry[];
+/** What a note leaves in its field: its sentence, hidden, for the field's
+ *  `aria-describedby`, and its entry in the record's activity — where it is listed with
+ *  what it belongs to and taken back to on press. Nothing is drawn: the mark by the label
+ *  (`NoteFlag`) says WHERE, the activity says WHAT. */
+export declare function NoteCard({ note, id, owner, }: {
+    note: FieldNote;
+    id: string;
+    /** What it belongs to — the field's label. A row's card reads it from its row. */
+    owner?: string;
+}): import("react").JSX.Element;
+/** The mark next to the label: WHERE the note is. It opens the note on press. */
+export declare function NoteFlag({ note }: {
+    note: FieldNote;
+}): import("react").JSX.Element;
+/** Joins ids for `aria-describedby`, dropping the absent ones. */
+export declare function describedByOf(...ids: readonly (string | undefined | null)[]): string | undefined;

package/dist/primitives/field/note.js

@@ -0,0 +1,117 @@
+"use client";
+import { Fragment as _Fragment, jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Flag } from "../notice/Flag.js";
+import { createContext, useContext, useLayoutEffect, useRef, useSyncExternalStore, } from "react";
+export function createNoteRegistry() {
+    const entries = new Map();
+    const listeners = new Set();
+    let list = [];
+    const changed = () => {
+        list = [...entries.values()];
+        for (const listener of listeners)
+            listener();
+    };
+    return {
+        put: (entry) => {
+            const known = entries.get(entry.id);
+            if (known === undefined) {
+                entries.set(entry.id, entry);
+                changed();
+                return;
+            }
+            /* In place: the snapshot keeps its identity, so `useSyncExternalStore` sees no change
+               — a new array here re-rendered the record, which re-rendered the field, which put
+               again, for ever. */
+            Object.assign(known, entry);
+        },
+        drop: (id) => {
+            if (entries.delete(id))
+                changed();
+        },
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot: () => list,
+    };
+}
+/** The registry of the record around — `Record` provides it. */
+export const NoteRegistryContext = createContext(null);
+const NONE = [];
+const noop = () => () => { };
+/** The notes mounted in the record around, in the order they were mounted. */
+export function useNoteEntries() {
+    const registry = useContext(NoteRegistryContext);
+    const snapshot = registry?.snapshot ?? (() => NONE);
+    /* The same snapshot on the server: nothing registers there (no effects run), so it is
+       empty unless someone filled the registry by hand. */
+    return useSyncExternalStore(registry?.subscribe ?? noop, snapshot, snapshot);
+}
+/** What a card belongs to when nobody said: the row it sits in, by the first words of its
+ *  first cell — «Impresora térmica de tickets 80 mm» —, or nothing. The card's own words
+ *  (it sits in that cell) are skipped. */
+function ownerFromRow(card) {
+    const cell = card.closest("tr")?.querySelector("td");
+    if (cell === null || cell === undefined)
+        return "";
+    const walk = document.createTreeWalker(cell, NodeFilter.SHOW_TEXT);
+    for (let node = walk.nextNode(); node !== null; node = walk.nextNode()) {
+        if (node.parentElement?.closest("[data-field-note]") !== null)
+            continue;
+        const text = node.textContent?.trim() ?? "";
+        if (text !== "")
+            return text.slice(0, 60);
+    }
+    return "";
+}
+/** The field or row a card is anchored to: the row, the fact (a `<dd>`'s group), or the
+ *  field box the card is the last child of. */
+function anchorOf(card) {
+    if (card === null)
+        return null;
+    const row = card.closest("tr");
+    if (row !== null)
+        return row;
+    const parent = card.parentElement;
+    return parent?.tagName === "DD" ? parent.parentElement : parent;
+}
+/* ---------------------------------------------------------------- *
+ *  The two faces
+ * ---------------------------------------------------------------- */
+/** What a note leaves in its field: its sentence, hidden, for the field's
+ *  `aria-describedby`, and its entry in the record's activity — where it is listed with
+ *  what it belongs to and taken back to on press. Nothing is drawn: the mark by the label
+ *  (`NoteFlag`) says WHERE, the activity says WHAT. */
+export function NoteCard({ note, id, owner, }) {
+    const registry = useContext(NoteRegistryContext);
+    const ref = useRef(null);
+    /* Before paint, so the record's activity knows on its first frame whether there is
+       anything to align — its default view depends on it. On EVERY render: the words are
+       kept current, silently (a new `note` object each render must not re-render the
+       record); only appearing and going away are news. */
+    useLayoutEffect(() => {
+        if (registry === null)
+            return;
+        const card = ref.current;
+        registry.put({
+            id,
+            note,
+            owner: owner ?? (card === null ? "" : ownerFromRow(card)),
+            anchor: () => anchorOf(ref.current),
+        });
+    });
+    useLayoutEffect(() => {
+        if (registry === null)
+            return;
+        return () => registry.drop(id);
+    }, [registry, id]);
+    return (_jsx("div", { ref: ref, "data-field-note": "", hidden: true, children: _jsxs("span", { id: id, children: [note.label, note.detail === undefined ? null : _jsxs(_Fragment, { children: [" \u2014 ", note.detail] })] }) }));
+}
+/** The mark next to the label: WHERE the note is. It opens the note on press. */
+export function NoteFlag({ note }) {
+    return (_jsx("span", { className: "inline-flex shrink-0", children: _jsx(Flag, { tone: note.tone ?? "info", label: note.label, children: note.detail === undefined && note.action === undefined ? undefined : (_jsxs("span", { className: "flex flex-col gap-2", children: [note.detail === undefined ? null : _jsx("span", { children: note.detail }), note.action === undefined ? null : _jsx("span", { className: "flex", children: note.action })] })) }) }));
+}
+/** Joins ids for `aria-describedby`, dropping the absent ones. */
+export function describedByOf(...ids) {
+    return ids.filter((x) => x !== undefined && x !== null).join(" ") || undefined;
+}

package/dist/primitives/index.d.ts

@@ -16,4 +16,5 @@ export * from "./table/index.js";
 export * from "./tabs/index.js";
 export * from "./tag/index.js";
 export * from "./toolbar/index.js";
+export * from "./tree/index.js";
 export * from "./value/index.js";

package/dist/primitives/index.js

@@ -17,4 +17,5 @@ export * from "./table/index.js";
 export * from "./tabs/index.js";
 export * from "./tag/index.js";
 export * from "./toolbar/index.js";
+export * from "./tree/index.js";
 export * from "./value/index.js";

package/dist/primitives/menu/Menu.d.ts

@@ -1,6 +1,7 @@
 import { type ButtonRole, type ButtonSize } from "../button/Button.js";
 import type { LucideIcon } from "lucide-react";
 import type { ReactNode } from "react";
+import { type Key } from "react-aria-components";
 export interface MenuOption {
     id: string;
     label: string;
@@ -27,6 +28,16 @@ export interface MenuOption {
      *  menu built from a registry —twenty-five operations, each one with its own
      *  action— has no reasonable `switch` on the other side. */
     onSelect?: () => void;
+    /** The keys that run this option without opening the menu, as the user reads them
+     *  —«Ctrl+P», «⌘D»—. Drawn at the end of the row and linked to it for a screen reader.
+     *  It is a HINT: binding the keys is the application's job, because the menu does not
+     *  exist until it is opened. In an ERP the frequent verbs have a shortcut, and the menu
+     *  is where people learn it. */
+    shortcut?: string;
+    /** The option opens a SUBMENU with these options instead of running. Its own `onSelect`
+     *  and `checked` are ignored — a row that opens something does not also do something.
+     *  Children may carry `items` too, but a third level is usually a dialog in disguise. */
+    items?: readonly MenuOption[];
 }
 export interface MenuGroup {
     /** The group's label, in the brand voice. Without a label, the group is just
@@ -51,6 +62,9 @@ declare const WIDTH: {
     readonly md: "min-w-56 max-w-80";
     readonly lg: "min-w-80 max-w-(--container-short)";
 };
+/** Every option of the tree by id, children included: a submenu is a separate React Aria
+ *  menu with its own `onAction`, and both have to reach the same handlers. */
+export declare function indexOptions(options: readonly MenuOption[], into?: Map<string, MenuOption>): Map<string, MenuOption>;
 export declare function Menu({ label, groups, onSelect, surface, align, icon: Trigger, 
 /** The menu as a control of a list ("filters ▾") carries the chevron; the
  *  actions `⋯` does not, because the icon already says there is more. */
@@ -97,4 +111,18 @@ chevron, active, iconOnly, variant, searchPlaceholder, emptyText, width, role, s
      *  each click turns three hides into three open-close round trips. */
     closeOnSelect?: boolean;
 }): import("react").JSX.Element;
+/**
+ * The panel of a `Menu`: its groups and rows, and the submenus hanging from them. Internal —
+ * it is not exported from the family — and separate from the trigger for two reasons: a
+ * submenu is this same panel one level down, and a panel can be rendered on the server
+ * without the trigger's popover, which is how the tests see the rows.
+ */
+export declare function MenuList({ label, groups, onAction, closeOnSelect, emptyText, width, }: {
+    label: string;
+    groups: readonly MenuGroup[];
+    onAction: (key: Key) => void;
+    closeOnSelect: boolean;
+    emptyText: string;
+    width?: keyof typeof WIDTH;
+}): import("react").JSX.Element;
 export {};