@sincpro/web-ui 0.1.0 → 0.2.0

package/dist/primitives/dialog/Drill.d.ts

@@ -0,0 +1,90 @@
+import { type DialogContext, type DialogWidth } from "./Dialog.js";
+import { type ReactNode, type RefObject } from "react";
+/** Where the drill was opened from: the page's record. The first crumb of the trail. */
+export type DrillOrigin = DialogContext;
+/** Which contexts are open, in order, and the ways to move between them. */
+export interface DrillState {
+    /** The ids of the open contexts, from the first opened to the one in front. */
+    readonly path: readonly string[];
+    /** One level deeper. An id already on the path goes back to it instead: a product
+     *  that leads to its supplier that leads to the same product is a loop, not depth. */
+    open: (id: string) => void;
+    /** Up one level. On the first one, it closes. */
+    back: () => void;
+    /** Back to the context with this id, closing the ones in front of it. */
+    to: (id: string) => void;
+    /** Close every level: back to the page. */
+    close: () => void;
+    /** Internal: the control that opened each level, where focus returns when the level
+     *  above it closes. Written by `open`, read by `Drill`. */
+    readonly focusMarks: RefObject<(HTMLElement | null)[]>;
+}
+/** One level deeper: push the id — or, when it is already open, go back to it. Internal,
+ *  exported for the test. */
+export declare function openPath(path: readonly string[], id: string): readonly string[];
+/** Back to the context with this id; an id not on the path changes nothing. */
+export declare function toPath(path: readonly string[], id: string): readonly string[];
+/** The written contexts that are open, in the order of the path. A context on the path
+ *  that is not written is skipped: there is nothing to draw for it. */
+export declare function framesOf(children: ReactNode, path: readonly string[]): DrillContextProps[];
+/** The state of a `Drill`: the path of open contexts. Pass it to `<Drill state={…}>` and
+ *  call `open(id)` from wherever the context is opened — a relation's «Abrir», a
+ *  `Picker`'s open button, a rail action, a line's cell. */
+export declare function useDrill(initial?: readonly string[]): DrillState;
+export interface DrillContextProps {
+    /** What `open(id)` names. Unique inside the drill. */
+    id: string;
+    /** The context's name: the title while it is in front, its crumb when it is behind.
+     *  Short — «Línea 3», «Impresora térmica 80 mm», «Registrar pago». */
+    title: string;
+    /** One sentence under the title; also the dialog's description while in front. */
+    subtitle?: string;
+    /** This context's actions — Cancel and ONE primary. Drawn only while it is in front. */
+    footer?: ReactNode;
+    /** No padding of its own: for a child that is already a surface with its own margins
+     *  (a `Record`). A form or a wizard keeps the padding. */
+    flush?: boolean;
+    children: ReactNode;
+}
+export interface DrillProps {
+    state: DrillState;
+    /** The page's record, as the first crumb: «pedido · S00142». Pressing it closes. */
+    origin?: DrillOrigin;
+    /** One width for every level: a window that changes width at each step jumps under the
+     *  pointer. `lg` by default — a record with pages and lines needs it. */
+    width?: DialogWidth;
+    /** The `Drill.Context`s. Which ones are open is the state's path. */
+    children: ReactNode;
+}
+/**
+ * The inside of the window: the trail, the context in front (and the ones behind it,
+ * hidden), and the footer of the one in front.
+ *
+ * Internal — exported only so a test can read its markup, which the modal (a portal)
+ * does not produce on the server.
+ */
+export declare function DrillSurface({ frames, origin, onBack, onTo, onClose, focusMarks, }: {
+    frames: readonly DrillContextProps[];
+    origin?: DrillOrigin;
+    onBack: () => void;
+    onTo: (id: string) => void;
+    onClose: () => void;
+    focusMarks?: RefObject<(HTMLElement | null)[]>;
+}): import("react").JSX.Element | null;
+/**
+ * ONE dialog that holds a stack of contexts opened from a record — and from each other —
+ * with a trail back to the page. See the header of this file.
+ *
+ *     const drill = useDrill();
+ *     …<RelationValue name={product} onOpen={() => drill.open("product")} />…
+ *     <Drill state={drill} origin={{ kind: "pedido", label: "S00142" }}>
+ *       <Drill.Context id="product" title={product} flush>
+ *         <Record identity={…}>…</Record>
+ *       </Drill.Context>
+ *       <Drill.Context id="supplier" title={supplier} footer={…}>…</Drill.Context>
+ *     </Drill>
+ */
+export declare function Drill({ state, origin, width, children }: DrillProps): import("react").JSX.Element;
+export declare namespace Drill {
+    var Context: ((props: DrillContextProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"context">;
+}

package/dist/primitives/dialog/Drill.js

@@ -0,0 +1,172 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { flatten, propsOf, slot, slotOf } from "../../foundations/slots.js";
+import { cn, focusRing, tv } from "../../foundations/variants.js";
+import { IconButton } from "../button/Button.js";
+import { dialogStyles, } from "./Dialog.js";
+import { ArrowLeft, ChevronRight, X } from "lucide-react";
+import { useEffect, useId, useRef, useState } from "react";
+import { useKeyboard } from "react-aria";
+import { Dialog as AriaDialog, Heading, Link, Modal, ModalOverlay, } from "react-aria-components";
+function focused() {
+    if (typeof document === "undefined")
+        return null;
+    return document.activeElement instanceof HTMLElement ? document.activeElement : null;
+}
+/** One level deeper: push the id — or, when it is already open, go back to it. Internal,
+ *  exported for the test. */
+export function openPath(path, id) {
+    const at = path.indexOf(id);
+    return at === -1 ? [...path, id] : path.slice(0, at + 1);
+}
+/** Back to the context with this id; an id not on the path changes nothing. */
+export function toPath(path, id) {
+    const at = path.indexOf(id);
+    return at === -1 ? path : path.slice(0, at + 1);
+}
+/** The written contexts that are open, in the order of the path. A context on the path
+ *  that is not written is skipped: there is nothing to draw for it. */
+export function framesOf(children, path) {
+    const written = flatten(children)
+        .filter((node) => slotOf(node) === "context")
+        .map((node) => propsOf(node))
+        .filter((props) => props !== undefined);
+    return path
+        .map((id) => written.find((context) => context.id === id))
+        .filter((frame) => frame !== undefined);
+}
+/** The state of a `Drill`: the path of open contexts. Pass it to `<Drill state={…}>` and
+ *  call `open(id)` from wherever the context is opened — a relation's «Abrir», a
+ *  `Picker`'s open button, a rail action, a line's cell. */
+export function useDrill(initial = []) {
+    const [path, setPath] = useState(initial);
+    const focusMarks = useRef([]);
+    return {
+        path,
+        open: (id) => {
+            if (!path.includes(id))
+                focusMarks.current[path.length] = focused();
+            setPath(openPath(path, id));
+        },
+        back: () => setPath(path.slice(0, -1)),
+        to: (id) => setPath(toPath(path, id)),
+        close: () => setPath([]),
+        focusMarks,
+    };
+}
+const crumb = tv({
+    extend: focusRing,
+    base: "block max-w-(--container-crumb) min-w-0 cursor-pointer truncate rounded-mark text-muted transition-colors duration-(--duration-instant) hover:text-ink hover:underline hover:underline-offset-4",
+});
+/**
+ * The inside of the window: the trail, the context in front (and the ones behind it,
+ * hidden), and the footer of the one in front.
+ *
+ * Internal — exported only so a test can read its markup, which the modal (a portal)
+ * does not produce on the server.
+ */
+export function DrillSurface({ frames, origin, onBack, onTo, onClose, focusMarks, }) {
+    const copy = useUiCopy();
+    const depth = frames.length;
+    const top = frames[depth - 1];
+    const parent = depth > 1 ? frames[depth - 2] : undefined;
+    const bodies = useRef(new Map());
+    const was = useRef(depth);
+    const subtitleId = useId();
+    const { keyboardProps } = useKeyboard({
+        onKeyDown: (e) => {
+            if (e.key !== "Escape") {
+                e.continuePropagation();
+                return;
+            }
+            if (depth > 1)
+                onBack();
+            else
+                onClose();
+        },
+    });
+    /* Focus follows the level. Down: into the new context, so the keyboard does not stay on
+       a control that is now hidden. Up: back to what opened the level that closed. */
+    const topId = top?.id;
+    useEffect(() => {
+        const before = was.current;
+        was.current = depth;
+        if (before === depth || depth === 0 || topId === undefined)
+            return;
+        const box = bodies.current.get(topId);
+        if (depth > before) {
+            box?.focus();
+            return;
+        }
+        const mark = focusMarks?.current[depth];
+        (mark?.isConnected === true ? mark : box)?.focus();
+    }, [depth, topId, focusMarks]);
+    if (top === undefined)
+        return null;
+    const trail = [
+        ...(origin === undefined
+            ? []
+            : [
+                {
+                    key: "\u0000origin",
+                    label: (_jsxs(_Fragment, { children: [origin.kind === undefined ? null : (_jsxs("span", { className: "font-medium", children: [origin.kind, " "] })), _jsx("span", { className: "text-ink", children: origin.label })] })),
+                    onPress: onClose,
+                },
+            ]),
+        ...frames.slice(0, -1).map((frame) => ({
+            key: frame.id,
+            label: frame.title,
+            onPress: () => onTo(frame.id),
+        })),
+    ];
+    return (_jsx(AriaDialog, { ...(top.subtitle === undefined ? {} : { "aria-describedby": subtitleId }), className: "flex max-h-[inherit] min-h-0 flex-1 flex-col outline-0", children: _jsxs("div", { ...keyboardProps, className: "flex max-h-[inherit] min-h-0 flex-1 flex-col", children: [_jsxs("header", { className: "flex shrink-0 items-start gap-2 border-b border-line px-4 py-3", children: [parent === undefined ? null : (_jsx("span", { className: "-ml-1.5 shrink-0", children: _jsx(IconButton, { icon: ArrowLeft, label: fillCopy(copy.drill.back, { name: parent.title }), onClick: onBack }) })), _jsxs("div", { className: "min-w-0 flex-1", children: [trail.length === 0 ? null : (
+                                /* Where this was opened from, small and on top — the same place `Dialog`
+                                   says what it is about. Every crumb is a way back; the one in front is
+                                   not a crumb, it is the title. */
+                                _jsx("nav", { "aria-label": copy.drill.trail, className: "mb-0.5 flex min-w-0", children: _jsx("ol", { className: "flex min-w-0 flex-wrap items-center gap-x-1 gap-y-0.5 text-micro", children: trail.map((one, i) => (_jsxs("li", { className: "flex min-w-0 items-center gap-1", children: [i === 0 ? null : (_jsx(ChevronRight, { className: "size-(--size-icon-sm) shrink-0 text-line-strong", strokeWidth: 2, "aria-hidden": true })), _jsx(Link, { onPress: one.onPress, className: ({ isFocusVisible }) => crumb({ isFocusVisible }), children: one.label })] }, one.key))) }) })), _jsx(Heading, { slot: "title", className: "truncate text-title font-semibold text-ink", children: top.title }), top.subtitle === undefined ? null : (_jsx("p", { id: subtitleId, className: "mt-1 max-w-prose text-meta text-muted", children: top.subtitle }))] }), _jsx(IconButton, { icon: X, label: copy.shell.close, onClick: onClose })] }), frames.map((frame) => {
+                    const front = frame.id === top.id;
+                    return (
+                    /* Each level scrolls on its own and the ones behind are `hidden`, not gone:
+                       their state — a half-typed payment, the open tab of a product — is still
+                       there when the level above closes. */
+                    _jsx("div", { ref: (node) => {
+                            if (node === null)
+                                bodies.current.delete(frame.id);
+                            else
+                                bodies.current.set(frame.id, node);
+                        }, hidden: !front, tabIndex: -1, "data-drill-context": frame.id, className: cn("min-h-0 flex-1 overflow-y-auto outline-0", frame.flush !== true && "px-4 py-4", front && frame.footer === undefined && "max-sm:safe-bottom"), children: frame.children }, frame.id));
+                }), top.footer === undefined ? null : (_jsx("footer", { className: "flex shrink-0 flex-wrap items-center justify-end gap-2 border-t border-line bg-ground px-4 py-3 max-sm:safe-bottom", children: top.footer }))] }) }));
+}
+/** One context of a drill: a title, what goes inside, and its own footer. It does not
+ *  draw where it is written — the `Drill` draws it when its id is on the path. */
+const DrillContextSlot = slot("context", (_props) => null);
+/**
+ * ONE dialog that holds a stack of contexts opened from a record — and from each other —
+ * with a trail back to the page. See the header of this file.
+ *
+ *     const drill = useDrill();
+ *     …<RelationValue name={product} onOpen={() => drill.open("product")} />…
+ *     <Drill state={drill} origin={{ kind: "pedido", label: "S00142" }}>
+ *       <Drill.Context id="product" title={product} flush>
+ *         <Record identity={…}>…</Record>
+ *       </Drill.Context>
+ *       <Drill.Context id="supplier" title={supplier} footer={…}>…</Drill.Context>
+ *     </Drill>
+ */
+export function Drill({ state, origin, width = "lg", children }) {
+    /* While the window fades out the path is already empty: it keeps drawing the last levels
+       it had, so the content does not vanish before the window does. */
+    const [lastPath, setLastPath] = useState(state.path);
+    if (state.path.length > 0 && state.path !== lastPath)
+        setLastPath(state.path);
+    const path = state.path.length > 0 ? state.path : lastPath;
+    const frames = framesOf(children, path);
+    return (_jsx(ModalOverlay, { isOpen: state.path.length > 0, onOpenChange: (next) => {
+            if (!next)
+                state.close();
+        }, isDismissable: true, 
+        /* Escape is ours: up one level, not out of everything. See the header. */
+        isKeyboardDismissDisabled: true, className: dialogStyles.overlay, children: _jsx(Modal, { className: (s) => dialogStyles.modal({ ...s, width }), children: _jsx(DrillSurface, { frames: frames, ...(origin === undefined ? {} : { origin }), onBack: state.back, onTo: state.to, onClose: state.close, focusMarks: state.focusMarks }) }) }));
+}
+Drill.Context = DrillContextSlot;

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

@@ -1 +1,2 @@
 export { Dialog, type DialogContext, type DialogProps, type DialogWidth, Wizard, type WizardProps, type WizardStep, } from "./Dialog.js";
+export { Drill, type DrillContextProps, type DrillOrigin, type DrillProps, type DrillState, useDrill, } from "./Drill.js";

package/dist/primitives/dialog/index.js

@@ -1,2 +1,4 @@
 /* What has to be answered before moving on. */
 export { Dialog, Wizard, } from "./Dialog.js";
+/* One dialog that holds a stack of contexts opened from a record, and from each other. */
+export { Drill, useDrill, } from "./Drill.js";

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;