@sincpro/web-ui 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,42 @@
+import { type FormMode } from "./mode.js";
+/**
+ * Drop a file, or pick one. Progress is a real bar; failure is a sentence.
+ *
+ * This is the control. Where it lives —a `Dialog`, a wizard step— is the
+ * consumer's. Putting a dashed box on top of a list was the product drawing
+ * the control in the wrong place, not the absence of a control.
+ *
+ * Context: the zone is React Aria's `DropZone` and the button its `FileTrigger`.
+ * Dragging is a mouse gesture, so the zone is never the only way in: the
+ * «choose file» button opens the system's file dialog from the keyboard, and the
+ * zone itself takes a paste (Ctrl/⌘+V of a copied file) and announces a drop to
+ * a screen reader. While a file uploads the zone refuses another one — a second
+ * drop in the middle of an upload replaces nothing and confuses everything.
+ *
+ * `accept` filters the file dialog. A drop is NOT filtered: the browser does not
+ * say a dragged file's extension until it lands, and a drop that silently does
+ * nothing reads as a broken zone. The file reaches `onFile`, and the consumer
+ * answers with `error` when it cannot read it.
+ */
+export type DropZoneProps = {
+    /** The browser's `accept` list: extensions and MIME types, comma-separated
+     *  (`".pdf,application/pdf"`). */
+    accept?: string;
+    label?: string;
+    busy?: boolean;
+    /** 0 to 100, same scale as `ProgressBar`. */
+    progress?: number;
+    fileName?: string;
+    fileDetail?: string;
+    error?: string | null;
+    onFile: (file: File) => void;
+    onCancel?: () => void;
+    onRetry?: () => void;
+    id?: string;
+    describedBy?: string;
+    invalid?: boolean;
+    /** Forces the mode. By default it inherits the form's: in read mode it draws the
+     *  file's name. */
+    mode?: FormMode;
+};
+export declare function DropZone({ accept, label, busy, progress, fileName, fileDetail, error, onFile, onCancel, onRetry, id: ownId, describedBy: ownDescribedBy, invalid: ownInvalid, mode, }: DropZoneProps): import("react").JSX.Element;

package/dist/primitives/field/DropZone.js

@@ -0,0 +1,52 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { cn } from "../../foundations/variants.js";
+import { Button, buttonClasses } from "../button/Button.js";
+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/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();
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    const readMode = useFormMode(mode) === "read";
+    if (readMode)
+        return _jsx(ReadValue, { value: fileName ?? null });
+    const sentence = label ?? copy.field.drop;
+    const types = accept
+        ?.split(",")
+        .map((t) => t.trim())
+        .filter((t) => t !== "");
+    async function onDrop(items) {
+        if (busy)
+            return;
+        for (const item of items) {
+            if (item.kind === "file") {
+                onFile(await item.getFile());
+                return;
+            }
+        }
+    }
+    return (_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsxs(AriaDropZone, { ...(labelledBy === undefined
+                    ? { "aria-label": sentence }
+                    : { "aria-labelledby": labelledBy }), "aria-describedby": describedBy, isDisabled: busy, getDropOperation: () => (busy ? "cancel" : "copy"), onDrop: (event) => void onDrop(event.items), className: ({ isDropTarget, isFocusVisible }) => cn("flex flex-col items-center gap-3 rounded-box border px-4 py-6 text-center transition-colors duration-(--duration-instant) outline-primary outline-offset-2", isDropTarget
+                    ? "border-primary bg-primary/8 forced-colors:border-[Highlight]"
+                    : invalid
+                        ? "border-danger bg-surface"
+                        : "border-line-strong bg-surface", isFocusVisible ? "outline-2" : "outline-0"), children: [_jsx("p", { className: "text-body text-muted", children: sentence }), busy ? (_jsxs("div", { className: "flex w-full max-w-sm flex-col items-center gap-2", children: [fileName === undefined ? null : (_jsx("p", { className: "max-w-full truncate text-body text-ink", children: fileName })), _jsx("div", { className: "w-full", children: _jsx(ProgressBar, { value: progress ?? 0, label: copy.field.uploadProgress, width: "w-full" }) }), fileDetail === undefined ? null : (_jsx("p", { className: "text-meta text-muted", children: fileDetail }))] })) : (_jsxs("div", { className: "flex flex-wrap items-center justify-center gap-3", children: [_jsx(FileTrigger, { ...(types === undefined ? {} : { acceptedFileTypes: types }), onSelect: (files) => {
+                                    const file = files?.[0];
+                                    if (file !== undefined)
+                                        onFile(file);
+                                }, children: _jsx(AriaButton, { id: id, "data-emphasis": "secondary", className: buttonClasses("secondary", "md"), children: copy.field.chooseFile }) }), onCancel === undefined ? null : (_jsx(Button, { role: "ghost", onClick: onCancel, children: copy.field.cancel }))] }))] }), error === undefined || error === null ? null : (_jsx(Failed, { heading: copy.field.fileUnreadable, sentence: error, ...(onRetry === undefined
+                    ? {}
+                    : {
+                        action: (_jsx(Button, { role: "ghost", onClick: onRetry, children: copy.field.tryAnother })),
+                    }) }))] }));
+}

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

@@ -0,0 +1,178 @@
+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, note, copy: copyAs, }: {
+    label: string;
+    /** What is expected. A `?` on the label that opens it on press. */
+    hint?: string;
+    /** What has to be corrected. It goes BELOW, close to the cursor, and it says
+     *  what to put. */
+    error?: string;
+    required?: boolean;
+    /** The control. Written directly — `<Field label="Nombre"><TextInput … /></Field>` — it
+     *  reads its id, description and error state from the field. The render prop
+     *  `{(aria) => …}` is still there for a control that is not one of the system's. */
+    children: ReactNode | ((ids: FieldIds) => ReactNode);
+    htmlFor?: string;
+    /** `inline` puts the label on the LEFT, in a fixed-width column. It is what
+     *  turns twenty stacked fields into a record that reads at a glance: every
+     *  value starts on the same vertical, so the eye goes down a column instead of
+     *  bouncing. It needs width — in a narrow drawer, the label eats the field.
+     *  Omit it to inherit the sheet: `horizontal` there is this, `stacked` is the
+     *  label above. */
+    layout?: "stacked" | "inline";
+    /** A button attached to the label: "generate", "clear", "pick from the
+     *  catalog". It goes above and not below the control because it belongs to the
+     *  FIELD, not to the form — what goes below is what closes the whole form. */
+    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
+ * record without pretending it is being edited.
+ *
+ * Context: until now, showing a value with its name in a form forced you to put
+ * a disabled `TextInput`. That draws the box, the border and the height of
+ * something you write into, and a whole record like that is twelve boxes empty
+ * of meaning.
+ *
+ * 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, 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. */
+    value: ReactNode;
+    hint?: string;
+    layout?: "stacked" | "inline";
+    /** 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.
+ *
+ *  It is a single piece and not an `if` repeated in every control: if each one
+ *  solves its read mode its own way, the record ends up with six different ways
+ *  of saying the same thing. */
+export declare function ReadValue({ value, mono }: {
+    value: ReactNode;
+    mono?: boolean;
+}): import("react").JSX.Element;
+/** The shared look of everything that is written into or chosen from.
+ *
+ *  It exists as a function and not as a loose class so that a new control cannot
+ *  be born with another height, another radius or another focus. That was the
+ *  original defect: every file wrote its own `<input className="…">`. */
+export declare function controlClasses(invalid?: boolean): string;
+/** What every text control shares: the field's wiring, overridable prop by prop. */
+type ControlProps = {
+    id?: string;
+    describedBy?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    /** Forces the mode. By default it inherits the form's: in read mode it draws the value. */
+    mode?: FormMode;
+    /** The name of the control when it is NOT inside a `Field` — a cell of an editable table,
+     *  the box of a message. Inside a field, the field's label names it. */
+    "aria-label"?: string;
+};
+/**
+ * One line of text: a business name, a reference, a NIT.
+ *
+ * Context: it is React Aria's `TextField` — the field's label, hint and error reach the real
+ * `<input>` through `useFieldIds`, and React Aria adds the rest of what a text input owes a
+ * screen reader. What it draws is `controlClasses()`, the one box every control shares.
+ */
+export declare function TextInput({ id: ownId, value, onChange, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled, mode, mono, spellCheck, "aria-label": ariaLabel, }: ControlProps & {
+    value: string;
+    onChange?: (next: string) => void;
+    placeholder?: string;
+    /** The value was written by the machine and gets compared with the one next to it: an
+     *  id, a key, an account code. See the family rule in Typography. */
+    mono?: boolean;
+    /** `false` for a value that is a token and not prose — a product code, a reference, an
+     *  account code — so the browser stops underlining identifiers as misspellings. */
+    spellCheck?: boolean;
+}): import("react").JSX.Element;
+/**
+ * A number typed the way the person writes it: «1.234,56» in Bolivia, «1,234.56» in the
+ * United States.
+ *
+ * Context: it was an `<input type="number">`, and that input only understands the
+ * browser's idea of a number — on a Spanish form, «1.234,56» was either refused or read as
+ * one point two. It is React Aria's `NumberField` now, inside `AriaLocale`: it parses and
+ * formats in the locale of the copy table, not the browser's, so an amount reads the same
+ * here as in the listing next to it. `format` takes `Intl.NumberFormatOptions` — a
+ * currency, a percentage, two fixed decimals — and the field types and shows it that way.
+ *
+ * The arrow keys (and the two small buttons) step by `step`; on leaving the field the value
+ * is clamped to `min`/`max` and snapped to `step`, so what the form submits is always a
+ * number the field would have accepted. The value stays a plain `number`, and `""` is the
+ * empty field — never `NaN`, which is how React Aria says it inside.
+ */
+export declare function NumberInput({ id: ownId, value, onChange, min, max, step, unit, format, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled, mode, "aria-label": ariaLabel, }: ControlProps & {
+    value: number | "";
+    onChange?: (next: number | "") => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** The unit, attached to the field: "días", "u.", "kg". A number without a unit in a
+     *  form is half a question. For money, prefer `format` with a currency. */
+    unit?: string;
+    /** How the number is written: `{ style: "currency", currency: "BOB" }`,
+     *  `{ style: "percent" }`, `{ minimumFractionDigits: 2 }`. In the copy's locale. */
+    format?: Intl.NumberFormatOptions;
+    placeholder?: string;
+}): import("react").JSX.Element;
+/**
+ * Several lines of prose: the notes of an order, the reason of a credit note.
+ *
+ * Context: React Aria's `TextField` with a `TextArea` inside — the same wiring as
+ * `TextInput`, the same box, taller and resizable only downwards, because a note grows in
+ * lines, not in width.
+ */
+export declare function TextArea({ id: ownId, value, onChange, placeholder, rows, describedBy: ownDescribedBy, invalid: ownInvalid, disabled, mode, "aria-label": ariaLabel, }: ControlProps & {
+    value: string;
+    onChange?: (next: string) => void;
+    placeholder?: string;
+    rows?: number;
+}): import("react").JSX.Element;
+export interface SelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+/** The system's select, for SHORT and closed lists: the payment terms, the currency, the
+ *  warehouse.
+ *
+ *  Context: it was a native `<select>`, and its open list was the operating system's — its
+ *  font, its colors, its radius, in the middle of a form drawn with the system's. It is
+ *  React Aria's `Select` now: the trigger is the system's control box and the list floats
+ *  on the system's `Popover`, row for row the same as `ComboBox`'s. The keyboard is still a
+ *  select's: arrows open it and move, typing a letter jumps to the option, Enter picks.
+ *
+ *  As soon as the list has to show two pieces of data per option —a name and its tax id—
+ *  or grows past a screen, it is a `ComboBox` (type to find) or a `Picker` (records with
+ *  their metadata). An option here is ONE LINE OF TEXT. */
+export declare function Select({ id: ownId, value, options, onChange, describedBy: ownDescribedBy, invalid: ownInvalid, disabled, placeholder, mode, "aria-label": ariaLabel, }: ControlProps & {
+    /** The chosen option's `value`; `""` is nothing chosen, and draws the placeholder. */
+    value: string;
+    options: readonly SelectOption[];
+    onChange?: (next: string) => void;
+    placeholder?: string;
+}): import("react").JSX.Element;
+export {};

package/dist/primitives/field/Field.js

@@ -0,0 +1,251 @@
+"use client";
+import { jsxs as _jsxs, Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { AriaLocale } from "../../foundations/aria.js";
+import { useUiCopy } from "../../foundations/copy.js";
+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, 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.
+ *
+ *  The state we came from is on record: twenty raw controls across six files,
+ *  **none of them with an associated label or `aria-describedby`**, and all of
+ *  them 24 px tall. That is not a matter of abstract accessibility: a `label`
+ *  without `htmlFor` is a label that does not enlarge the click area, and a hint
+ *  that is not linked is a hint a screen reader never reads.
+ *
+ *  ── The error says WHAT to do, not that something is wrong ──────────
+ *
+ *  "Invalid value" is no use. An error message has to say what was expected
+ *  —"it has to be a number between 0 and 1"— because whoever made the mistake
+ *  already knows they made it: what they don't know is what to put.
+ *
+ *  And it is never ONLY color: it carries an icon and text. A red border is
+ *  invisible to someone who doesn't tell red apart, and also to someone who is
+ *  looking at another part of the screen.
+ *
+ *  ── The hint sits on the label, the error BELOW the control ─────────
+ *
+ *  Help is a `?` next to the name, opened with a press. A paragraph above the
+ *  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, 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 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
+       consumer having to pass it to the control as well. */
+    const ids = {
+        id,
+        labelId: `${id}-label`,
+        describedBy,
+        invalid: error !== undefined,
+    };
+    /* 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: _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 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: `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
+ * record without pretending it is being edited.
+ *
+ * Context: until now, showing a value with its name in a form forced you to put
+ * a disabled `TextInput`. That draws the box, the border and the height of
+ * something you write into, and a whole record like that is twelve boxes empty
+ * of meaning.
+ *
+ * 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, 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 }), 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 group/field", children: [labelNode, _jsxs("span", { className: "flex min-w-0 items-baseline gap-2", children: [valueNode, action] }), noteCard] }));
+    }
+    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.
+ *
+ *  It is a single piece and not an `if` repeated in every control: if each one
+ *  solves its read mode its own way, the record ends up with six different ways
+ *  of saying the same thing. */
+export function ReadValue({ value, mono = false }) {
+    const unset = useUiCopy().field.unset;
+    const empty = value === undefined || value === null || value === "";
+    return (_jsx("span", { className: `flex min-h-(--size-control-md) min-w-0 items-center text-meta ${empty ? "text-muted italic" : "text-ink"} ${mono ? "font-mono tabular-nums" : ""}`, children: empty ? unset : value }));
+}
+/** The shared look of everything that is written into or chosen from.
+ *
+ *  It exists as a function and not as a loose class so that a new control cannot
+ *  be born with another height, another radius or another focus. That was the
+ *  original defect: every file wrote its own `<input className="…">`. */
+export function controlClasses(invalid = false) {
+    return `h-(--size-control-md) w-full min-w-0 rounded-control border bg-surface px-2.5 text-meta text-ink transition-colors duration-(--duration-instant) placeholder:text-muted focus-visible:outline-2 focus-visible:outline-offset-2 disabled:cursor-not-allowed disabled:bg-ground disabled:text-muted ${invalid
+        ? "border-danger focus-visible:border-danger focus-visible:outline-danger"
+        : "border-line-strong focus-visible:border-primary focus-visible:outline-primary"}`;
+}
+/* `aria-describedby` goes on the INPUT and not on React Aria's field: the field adds the ids
+   of its own description and error slots, which this system never renders (`Field` draws
+   them), and the input's own prop replaces that list with the field's real one. */
+/** The accessible name of a control. Inside a `Field` the field's label names it; outside,
+ *  the consumer's `aria-label`, and as a last resort the placeholder — which is what a
+ *  browser reads for a bare `<input placeholder>` anyway, so a control outside a form is
+ *  never nameless. */
+function nameOf(labelledBy, ariaLabel, placeholder) {
+    return labelledBy === undefined ? (ariaLabel ?? placeholder) : ariaLabel;
+}
+/**
+ * One line of text: a business name, a reference, a NIT.
+ *
+ * Context: it is React Aria's `TextField` — the field's label, hint and error reach the real
+ * `<input>` through `useFieldIds`, and React Aria adds the rest of what a text input owes a
+ * screen reader. What it draws is `controlClasses()`, the one box every control shares.
+ */
+export function TextInput({ id: ownId, value, onChange, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, mode, mono = false, spellCheck, "aria-label": ariaLabel, }) {
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    if (useFormMode(mode) === "read")
+        return _jsx(ReadValue, { value: value, mono: mono });
+    return (_jsx(AriaTextField, { id: id, "aria-labelledby": labelledBy, "aria-label": nameOf(labelledBy, ariaLabel, placeholder), value: value, onChange: (next) => onChange?.(next), isInvalid: invalid, isDisabled: disabled, className: "w-full min-w-0", children: _jsx(Input, { "aria-describedby": describedBy, placeholder: placeholder, spellCheck: spellCheck, className: `${controlClasses(invalid)} ${mono ? "font-mono tabular-nums" : ""}` }) }));
+}
+/** The amount, the quantity, the percentage — read in the copy's locale, every time. */
+function useReadNumber(format) {
+    const { locale } = useUiCopy();
+    const formatter = new Intl.NumberFormat(locale, format);
+    return (value) => formatter.format(value);
+}
+const stepper = "flex min-h-0 flex-1 cursor-default items-center justify-center px-1 text-muted transition-colors duration-(--duration-instant) outline-0 hover:bg-ink/6 hover:text-ink pressed:bg-ink/10 disabled:cursor-not-allowed disabled:text-line-strong disabled:hover:bg-transparent forced-colors:disabled:text-[GrayText]";
+/**
+ * A number typed the way the person writes it: «1.234,56» in Bolivia, «1,234.56» in the
+ * United States.
+ *
+ * Context: it was an `<input type="number">`, and that input only understands the
+ * browser's idea of a number — on a Spanish form, «1.234,56» was either refused or read as
+ * one point two. It is React Aria's `NumberField` now, inside `AriaLocale`: it parses and
+ * formats in the locale of the copy table, not the browser's, so an amount reads the same
+ * here as in the listing next to it. `format` takes `Intl.NumberFormatOptions` — a
+ * currency, a percentage, two fixed decimals — and the field types and shows it that way.
+ *
+ * The arrow keys (and the two small buttons) step by `step`; on leaving the field the value
+ * is clamped to `min`/`max` and snapped to `step`, so what the form submits is always a
+ * number the field would have accepted. The value stays a plain `number`, and `""` is the
+ * empty field — never `NaN`, which is how React Aria says it inside.
+ */
+export function NumberInput({ id: ownId, value, onChange, min, max, step, unit, format, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, mode, "aria-label": ariaLabel, }) {
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    const read = useReadNumber(format);
+    if (useFormMode(mode) === "read") {
+        return (_jsx(ReadValue, { value: value === "" ? null : (_jsxs("span", { className: "tabular-nums", children: [read(value), unit === undefined ? "" : ` ${unit}`] })) }));
+    }
+    return (_jsx(AriaLocale, { children: _jsxs(AriaNumberField, { id: id, "aria-labelledby": labelledBy, "aria-label": nameOf(labelledBy, ariaLabel, placeholder), value: value === "" ? Number.NaN : value, onChange: (next) => onChange?.(Number.isNaN(next) ? "" : next), minValue: min, maxValue: max, step: step, formatOptions: format, isInvalid: invalid, isDisabled: disabled, className: "flex w-full min-w-0 items-center gap-2", children: [_jsxs(FieldGroup, { children: [_jsx(Input, { "aria-describedby": describedBy, placeholder: placeholder, className: "h-full min-w-0 flex-1 bg-transparent px-2.5 text-meta text-ink tabular-nums outline-0 placeholder:text-muted disabled:cursor-not-allowed" }), _jsxs("span", { className: "flex h-full shrink-0 flex-col border-l border-line", children: [_jsx(AriaButton, { slot: "increment", className: stepper, children: _jsx(ChevronUp, { "aria-hidden": true, className: "size-(--size-icon-sm)", strokeWidth: 2 }) }), _jsx(AriaButton, { slot: "decrement", className: `${stepper} border-t border-line`, children: _jsx(ChevronDown, { "aria-hidden": true, className: "size-(--size-icon-sm)", strokeWidth: 2 }) })] })] }), unit === undefined ? null : (_jsx("span", { className: "shrink-0 text-meta whitespace-nowrap text-muted", children: unit }))] }) }));
+}
+/**
+ * Several lines of prose: the notes of an order, the reason of a credit note.
+ *
+ * Context: React Aria's `TextField` with a `TextArea` inside — the same wiring as
+ * `TextInput`, the same box, taller and resizable only downwards, because a note grows in
+ * lines, not in width.
+ */
+export function TextArea({ id: ownId, value, onChange, placeholder, rows = 3, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, mode, "aria-label": ariaLabel, }) {
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    /* The paragraph in read mode keeps its line breaks: a long text without them
+       is a block, and whoever wrote it put them there for a reason. */
+    if (useFormMode(mode) === "read") {
+        return value === "" ? (_jsx(ReadValue, { value: null })) : (_jsx("span", { className: "text-meta whitespace-pre-line text-ink", children: value }));
+    }
+    return (_jsx(AriaTextField, { id: id, "aria-labelledby": labelledBy, "aria-label": nameOf(labelledBy, ariaLabel, placeholder), value: value, onChange: (next) => onChange?.(next), isInvalid: invalid, isDisabled: disabled, className: "w-full min-w-0", children: _jsx(AriaTextArea, { "aria-describedby": describedBy, rows: rows, placeholder: placeholder, className: `${controlClasses(invalid)} h-auto resize-y py-1.5 leading-relaxed` }) }));
+}
+const selectTrigger = tv({
+    extend: focusRing,
+    base: "flex h-(--size-control-md) w-full min-w-0 cursor-default items-center gap-2 rounded-control border bg-surface pr-2 pl-2.5 text-start text-meta text-ink transition-colors duration-(--duration-instant) forced-colors:bg-[Field]",
+    variants: {
+        isFocusVisible: {
+            true: "border-primary",
+        },
+        isInvalid: {
+            false: "border-line-strong forced-colors:border-[ButtonBorder]",
+            true: "border-danger outline-danger forced-colors:border-[Mark]",
+        },
+        isDisabled: {
+            true: "cursor-not-allowed bg-ground text-muted forced-colors:text-[GrayText]",
+        },
+    },
+});
+/** The system's select, for SHORT and closed lists: the payment terms, the currency, the
+ *  warehouse.
+ *
+ *  Context: it was a native `<select>`, and its open list was the operating system's — its
+ *  font, its colors, its radius, in the middle of a form drawn with the system's. It is
+ *  React Aria's `Select` now: the trigger is the system's control box and the list floats
+ *  on the system's `Popover`, row for row the same as `ComboBox`'s. The keyboard is still a
+ *  select's: arrows open it and move, typing a letter jumps to the option, Enter picks.
+ *
+ *  As soon as the list has to show two pieces of data per option —a name and its tax id—
+ *  or grows past a screen, it is a `ComboBox` (type to find) or a `Picker` (records with
+ *  their metadata). An option here is ONE LINE OF TEXT. */
+export function Select({ id: ownId, value, options, onChange, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, placeholder, mode, "aria-label": ariaLabel, }) {
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    /* In read mode the option's LABEL is drawn, not its value: `CONTADO` is the backend's
+       key, and what the form promised to show was «Al contado». */
+    if (useFormMode(mode) === "read") {
+        return _jsx(ReadValue, { value: options.find((o) => o.value === value)?.label ?? null });
+    }
+    return (_jsx(AriaLocale, { children: _jsxs(AriaSelect, { id: id, "aria-labelledby": labelledBy, "aria-label": nameOf(labelledBy, ariaLabel, placeholder), "aria-describedby": describedBy, value: value === "" ? null : value, onChange: (next) => onChange?.(next === null ? "" : String(next)), placeholder: placeholder, isInvalid: invalid, isDisabled: disabled, className: "w-full min-w-0", children: [_jsxs(AriaButton, { className: (state) => selectTrigger({ ...state, isInvalid: invalid }), children: [_jsx(SelectValue, { className: "min-w-0 flex-1 truncate data-placeholder:text-muted", children: ({ isPlaceholder, selectedText, defaultChildren }) => isPlaceholder ? defaultChildren : selectedText }), _jsx(ChevronDown, { "aria-hidden": true, className: "size-(--size-icon-md) shrink-0 text-muted", strokeWidth: 2 })] }), _jsx(Popover, { placement: "bottom start", className: "min-w-(--trigger-width)", children: _jsx(ListBox, { items: options, className: "max-h-[inherit] overflow-auto p-1 outline-0", children: (option) => (_jsx(ListBoxItem, { id: option.value, textValue: option.label, isDisabled: option.disabled, className: listOptionStyles, children: ({ isSelected }) => (_jsxs(_Fragment, { children: [_jsx("span", { className: `min-w-0 flex-1 truncate ${isSelected ? "font-medium" : ""}`, children: option.label }), _jsx("span", { className: "flex size-(--size-icon-md) shrink-0 items-center justify-center", children: isSelected ? (_jsx(Check, { "aria-hidden": true, className: "size-(--size-icon-md) text-primary forced-colors:text-[HighlightText]", strokeWidth: 2 })) : null })] })) })) }) })] }) }));
+}

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

@@ -0,0 +1,48 @@
+import { type FormMode } from "./mode.js";
+/**
+ * A text with suggestions: the open field that proposes.
+ *
+ * Context: there were two text controls and neither served the most common case of an ERP
+ * form. `Select` is a CLOSED list —what is not there cannot be written— and `TextInput` is
+ * free but does not help. The unit of a product, the bank of a payment, the city of a
+ * customer: fields where values already exist and they have to be offered **without
+ * forbidding a new one**.
+ *
+ * What not having it costs shows in the data: without suggestions «Bs.», «BOB» and
+ * «bolivianos» end up in the same column, and then somebody writes a `CASE` to unify them.
+ *
+ * ── Why it is not a `<datalist>` ────────────────────────────────────
+ *
+ * Because every browser draws it its own way and none follows the tokens: in the middle of a
+ * form with the system's type, radius and colors, an operating-system dropdown appears. It is
+ * React Aria's `ComboBox` with `allowsCustomValue` instead: the list floats on the system's
+ * `Popover`, the keyboard is a combobox's (arrows move, Enter picks, Escape closes), and
+ * whatever is typed stays typed. The filter is React Aria's `contains` in the copy's locale,
+ * so «potosi» finds «Potosí».
+ *
+ * ── What it is NOT ──────────────────────────────────────────────────
+ *
+ * It is not `ComboBox`, whose value must be one of its options, nor `Picker`, which chooses
+ * ONE record among thousands with its own search, metadata rows and dialog. This is a text
+ * field that also proposes: the list is short, it is of values and not of records, and what
+ * is stored is what was written.
+ */
+export type SuggestProps = {
+    id?: string;
+    value: string;
+    onChange?: (next: string) => void;
+    /** What already exists. Short: if they are hundreds, what is needed is a `Picker`. */
+    suggestions: readonly string[];
+    placeholder?: string;
+    describedBy?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    mono?: boolean;
+    mode?: FormMode;
+    /** How many are shown at once. More than this is a list to be read, and reading a list
+     *  is what this control exists to avoid. */
+    max?: number;
+    /** The name of the field when it is not inside a `Field`. */
+    "aria-label"?: string;
+};
+export declare function Suggest({ mode, ...props }: SuggestProps): import("react").JSX.Element;

package/dist/primitives/field/Suggest.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AriaLocale } from "../../foundations/aria.js";
+import { FieldGroup, listOptionStyles } from "./aria.js";
+import { useFieldIds } from "./context.js";
+import { ReadValue } from "./Field.js";
+import { useFormMode } from "./mode.js";
+import { Popover } from "../overlay/Popover.js";
+import { ComboBox as AriaComboBox, Input, ListBox, ListBoxItem, useFilter, } from "react-aria-components";
+const MAX = 8;
+export function Suggest({ mode, ...props }) {
+    if (useFormMode(mode) === "read")
+        return _jsx(ReadValue, { value: props.value, mono: props.mono });
+    /* The filter reads the locale from React Aria's context, so the box that provides it has
+       to be ABOVE the component that asks for it. */
+    return (_jsx(AriaLocale, { children: _jsx(EditableSuggest, { ...props }) }));
+}
+function EditableSuggest({ id: ownId, value, onChange, suggestions, placeholder, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, mono = false, max = MAX, "aria-label": ariaLabel, }) {
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    const { contains } = useFilter({ sensitivity: "base" });
+    /* Filtered by what is typed, hiding the one that ALREADY is exactly the value: offering
+       what someone just finished typing is a suggestion that suggests nothing. The list is
+       filtered here and not by React Aria because of that rule and of `max`. */
+    const needle = value.trim();
+    /* «Exactly» ignores case but NOT accents: «potosi» still offers «Potosí», which is the
+       spelling the person was reaching for. */
+    const exact = needle.toLocaleLowerCase();
+    const shown = suggestions
+        .filter((one) => one.toLocaleLowerCase() !== exact)
+        .filter((one) => needle === "" || contains(one, needle))
+        .slice(0, max)
+        .map((one) => ({ id: one }));
+    return (_jsxs(AriaComboBox, { id: id, "aria-labelledby": labelledBy, "aria-label": labelledBy === undefined ? (ariaLabel ?? placeholder) : ariaLabel, 
+        /* An open field: what is typed is the value, a suggestion only fills it faster. */
+        allowsCustomValue: true, inputValue: value, onInputChange: (next) => onChange?.(next), items: shown, 
+        /* It proposes as soon as the field is entered, like the hand-written one did: the
+           suggestions are most useful BEFORE anything is typed. */
+        menuTrigger: "focus", isInvalid: invalid, isDisabled: disabled, className: "w-full min-w-0", children: [_jsx(FieldGroup, { children: _jsx(Input, { "aria-describedby": describedBy, placeholder: placeholder, 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 ${mono ? "font-mono" : ""}` }) }), _jsx(Popover, { placement: "bottom start", className: "w-(--trigger-width)", children: _jsx(ListBox, { className: "max-h-[inherit] overflow-auto p-1 outline-0", children: (item) => (_jsx(ListBoxItem, { id: item.id, textValue: item.id, className: listOptionStyles, children: _jsx("span", { className: `min-w-0 truncate ${mono ? "font-mono" : ""}`, children: item.id }) })) }) })] }));
+}