@sincpro/web-ui 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,61 @@
+import { composeClasses } from "../../foundations/variants.js";
+import type { Ref } from "react";
+import { type ButtonProps as AriaButtonProps, type GroupProps } from "react-aria-components";
+/**
+ * The pieces every React Aria control of the system is built from — the box a date field,
+ * a combobox or a number field draws, and the small button inside it.
+ *
+ * Context: they look exactly like `controlClasses()` — same height, border, radius and
+ * focus — because a form mixes both kinds of control in one column, and a date field one
+ * pixel taller than the text input above it is the first thing an eye catches.
+ */
+export declare const fieldGroupStyles: import("tailwind-variants/config").TVReturnType<{
+    isFocusWithin: {
+        false: string;
+        true: string;
+    };
+    isInvalid: {
+        true: string;
+    };
+    isDisabled: {
+        true: string;
+    };
+}, undefined, "group flex h-(--size-control-md) w-full min-w-0 items-center overflow-hidden rounded-control border bg-surface text-meta text-ink transition-colors duration-(--duration-instant) forced-colors:bg-[Field]", {
+    isFocusVisible: {
+        false: string;
+        true: string;
+    };
+}, undefined, import("tailwind-variants/config").TVReturnType<{
+    isFocusVisible: {
+        false: string;
+        true: string;
+    };
+}, undefined, "outline-primary outline-offset-2 forced-colors:outline-[Highlight]", undefined, undefined, undefined>>;
+/** The box of a composite control: a field and its buttons, framed as one input. The `ref`
+ *  reaches the box (React 19: a plain prop) — a control that floats a list as wide as the
+ *  box, like `TagsField`, measures it. */
+export declare function FieldGroup({ ref, ...props }: GroupProps & {
+    ref?: Ref<HTMLDivElement>;
+}): import("react").JSX.Element;
+/** The button inside a field: the calendar of a date picker, the arrow of a combobox. */
+export declare function FieldButton(props: AriaButtonProps): import("react").JSX.Element;
+/**
+ * One row of a floating list — the options of a `Select`, the suggestions of a `Suggest`.
+ *
+ * Context: the same row `ComboBox` draws (control height, the `primary` tint on the row the
+ * keyboard is on), so every list that drops from a field reads as one kind of thing whatever
+ * control opened it.
+ */
+export declare const listOptionStyles: import("tailwind-variants/config").TVReturnType<{
+    isFocused: {
+        true: string;
+    };
+    isPressed: {
+        true: string;
+    };
+    isDisabled: {
+        true: string;
+    };
+}, undefined, "group flex min-h-(--size-control-md) cursor-default items-center gap-2 rounded-control px-2 py-1 text-meta text-ink outline-0 select-none forced-color-adjust-none", undefined, undefined, undefined>;
+/** For a control that only adds to the system's classes. */
+export { composeClasses };

package/dist/primitives/field/aria.js

@@ -0,0 +1,70 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { composeClasses, focusRing, tv } from "../../foundations/variants.js";
+import { Button as AriaButton, composeRenderProps, Group, } from "react-aria-components";
+/**
+ * The pieces every React Aria control of the system is built from — the box a date field,
+ * a combobox or a number field draws, and the small button inside it.
+ *
+ * Context: they look exactly like `controlClasses()` — same height, border, radius and
+ * focus — because a form mixes both kinds of control in one column, and a date field one
+ * pixel taller than the text input above it is the first thing an eye catches.
+ */
+export const fieldGroupStyles = tv({
+    extend: focusRing,
+    base: "group flex h-(--size-control-md) w-full min-w-0 items-center overflow-hidden rounded-control border bg-surface text-meta text-ink transition-colors duration-(--duration-instant) forced-colors:bg-[Field]",
+    variants: {
+        isFocusWithin: {
+            false: "border-line-strong forced-colors:border-[ButtonBorder]",
+            true: "border-primary forced-colors:border-[Highlight]",
+        },
+        isInvalid: {
+            true: "border-danger forced-colors:border-[Mark]",
+        },
+        isDisabled: {
+            true: "cursor-not-allowed bg-ground text-muted forced-colors:border-[GrayText]",
+        },
+    },
+});
+/** The box of a composite control: a field and its buttons, framed as one input. The `ref`
+ *  reaches the box (React 19: a plain prop) — a control that floats a list as wide as the
+ *  box, like `TagsField`, measures it. */
+export function FieldGroup({ ref, ...props }) {
+    return (_jsx(Group, { ref: ref, ...props, className: composeRenderProps(props.className, (className, state) => fieldGroupStyles({ ...state, className })) }));
+}
+const fieldButton = tv({
+    extend: focusRing,
+    base: "inline-flex shrink-0 items-center justify-center rounded-mark p-1 text-muted transition-colors duration-(--duration-instant) hover:bg-ink/6 hover:text-ink pressed:bg-ink/10",
+    variants: {
+        isDisabled: {
+            true: "text-line-strong hover:bg-transparent forced-colors:text-[GrayText]",
+        },
+    },
+});
+/** The button inside a field: the calendar of a date picker, the arrow of a combobox. */
+export function FieldButton(props) {
+    return (_jsx(AriaButton, { ...props, className: composeRenderProps(props.className, (className, state) => fieldButton({ ...state, className })) }));
+}
+/**
+ * One row of a floating list — the options of a `Select`, the suggestions of a `Suggest`.
+ *
+ * Context: the same row `ComboBox` draws (control height, the `primary` tint on the row the
+ * keyboard is on), so every list that drops from a field reads as one kind of thing whatever
+ * control opened it.
+ */
+export const listOptionStyles = tv({
+    base: "group flex min-h-(--size-control-md) cursor-default items-center gap-2 rounded-control px-2 py-1 text-meta text-ink outline-0 select-none forced-color-adjust-none",
+    variants: {
+        isFocused: {
+            true: "bg-primary/8 forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]",
+        },
+        isPressed: {
+            true: "bg-primary/12",
+        },
+        isDisabled: {
+            true: "text-muted opacity-45 forced-colors:text-[GrayText]",
+        },
+    },
+});
+/** For a control that only adds to the system's classes. */
+export { composeClasses };

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

@@ -0,0 +1,30 @@
+/**
+ * What a `Field` hands to the control inside it: the id its label points at, the ids that
+ * describe it (hint, error), and whether it is in error.
+ *
+ * Context: `Field` used to hand these through a render prop — `{(aria) => <TextInput
+ * id={aria.id} … />}` — on every field of every form. Correct, and three lines of wiring
+ * per field that anyone could get wrong (forget `describedBy` and the error is never read
+ * aloud). Now a control written directly inside a `Field` reads them from here; the render
+ * prop still works, and an explicit prop on the control always wins.
+ */
+export type FieldIds = {
+    id: string;
+    /** The id of the field's label. A native input is named by `<label for>`; a React Aria
+     *  control — a date picker, a combobox — is a group of elements, and is named by this. */
+    labelId: string;
+    describedBy: string | undefined;
+    invalid: boolean;
+};
+export declare const FieldIdsContext: import("react").Context<FieldIds | null>;
+/** The ids of the enclosing `Field`, resolved against the control's own props. */
+export declare function useFieldIds(own: {
+    id?: string;
+    describedBy?: string;
+    invalid?: boolean;
+}): {
+    id: string | undefined;
+    labelledBy: string | undefined;
+    describedBy: string | undefined;
+    invalid: boolean;
+};

package/dist/primitives/field/context.js

@@ -0,0 +1,13 @@
+"use client";
+import { createContext, useContext } from "react";
+export const FieldIdsContext = createContext(null);
+/** The ids of the enclosing `Field`, resolved against the control's own props. */
+export function useFieldIds(own) {
+    const field = useContext(FieldIdsContext);
+    return {
+        id: own.id ?? field?.id,
+        labelledBy: field?.labelId,
+        describedBy: own.describedBy ?? field?.describedBy,
+        invalid: own.invalid ?? field?.invalid ?? false,
+    };
+}

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

@@ -0,0 +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

@@ -0,0 +1,15 @@
+/* THE CONTROLS a form is written with.
+   What ARRANGES them —the sheet, the section, the footer— lives in `components/form`: a
+   control does not know a form exists, and is used the same way inside a cell, a filter or
+   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/layout.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from "react";
+/**
+ * HOW A FIELD PLACES ITS LABEL. Declared once, inherited by every field.
+ *
+ *     stacked      the label above. The grouped look of iOS. The default.
+ *     horizontal   label | value, and every value starts on the same vertical — the Odoo
+ *                  form, where twenty fields read as a column and not as a bounce.
+ *
+ * Context: it lives in `primitives/field` and not next to `Sheet`, which declares it,
+ * because the one that READS it is `Field` — and a primitive cannot import from a
+ * component. The container sets it, the field obeys, and the type that joins them is in the
+ * level both can see.
+ *
+ * Being a context and not a prop is what keeps a sheet from ending up half aligned: nobody
+ * has to remember to pass it to each field.
+ */
+export type FieldLayout = "stacked" | "horizontal";
+/** The name the sheet knows it by. */
+export type SheetLayout = FieldLayout;
+export declare function useSheetLayout(): FieldLayout;
+export declare function FieldLayoutProvider({ value, children, }: {
+    value: FieldLayout;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/primitives/field/layout.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const LayoutCtx = createContext("stacked");
+export function useSheetLayout() {
+    return useContext(LayoutCtx);
+}
+export function FieldLayoutProvider({ value, children, }) {
+    return _jsx(LayoutCtx.Provider, { value: value, children: children });
+}

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

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+export type FormMode = "edit" | "read";
+export declare function FormModeProvider({ value, children, }: {
+    value: FormMode;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The mode of this field. The prop beats the context — a computed field stays
+ *  in read mode inside a form that is being edited. */
+export declare function useFormMode(explicit?: FormMode): FormMode;

package/dist/primitives/field/mode.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const Ctx = createContext("edit");
+export function FormModeProvider({ value, children, }) {
+    return _jsx(Ctx.Provider, { value: value, children: children });
+}
+/** The mode of this field. The prop beats the context — a computed field stays
+ *  in read mode inside a form that is being edited. */
+export function useFormMode(explicit) {
+    const inherited = useContext(Ctx);
+    return explicit ?? inherited;
+}

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/hint/Hint.d.ts

@@ -0,0 +1,31 @@
+import { type ReactNode } from "react";
+/**
+ * A sentence that does not fit on the page, attached to a mark.
+ *
+ * Context: `title` on a field is a native tooltip and nobody finds it. Odoo
+ * puts a `?` next to the label; pressing it is how you read the help without
+ * it eating a line. The mark is the affordance; the sentence is the content.
+ *
+ * ── Why a click and a popover, and not a `Tooltip` ──
+ *
+ * A `Tooltip` is a LABEL: a few words that show on hover and vanish when the
+ * pointer leaves — useless on a tablet, and gone before a sentence is read.
+ * This is content, so it opens on press (mouse, touch, Enter or Space) and
+ * stays until it is put away: a second press, Escape, or a click outside. It
+ * is React Aria's `DialogTrigger` on the system's `Popover` — the same white
+ * surface as a calendar or a small filter form — so placement, flipping when
+ * there is no room below, focus moving in and back to the `?`, and Escape are
+ * React Aria's, not a hand-written listener.
+ *
+ * The sentence also lives, hidden, next to the mark under `id`: a field points
+ * its `aria-describedby` there, and a closed popover is not in the page for a
+ * screen reader to read.
+ */
+export declare function Hint({ children, label, id, }: {
+    children: ReactNode;
+    /** Visible mark. The `?` is the default because it is the one that gets
+     *  recognized as «there is more to read». */
+    label?: ReactNode;
+    /** For `aria-describedby` on the field the help belongs to. */
+    id?: string;
+}): import("react").JSX.Element;

package/dist/primitives/hint/Hint.js

@@ -0,0 +1,42 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { tv } from "../../foundations/variants.js";
+import { Popover } from "../overlay/Popover.js";
+import { CircleHelp } from "lucide-react";
+import { useId } from "react";
+import { Button, Dialog, DialogTrigger } from "react-aria-components";
+const mark = tv({
+    base: "inline-flex size-4 shrink-0 cursor-help items-center justify-center rounded-pill text-muted outline-0 transition-colors duration-(--duration-instant) hover:bg-ink/8 hover:text-ink aria-expanded:bg-ink/8 aria-expanded:text-ink forced-colors:text-[ButtonText]",
+    variants: {
+        isFocusVisible: {
+            true: "outline-2 outline-offset-1 outline-primary forced-colors:outline-[Highlight]",
+        },
+    },
+});
+/**
+ * A sentence that does not fit on the page, attached to a mark.
+ *
+ * Context: `title` on a field is a native tooltip and nobody finds it. Odoo
+ * puts a `?` next to the label; pressing it is how you read the help without
+ * it eating a line. The mark is the affordance; the sentence is the content.
+ *
+ * ── Why a click and a popover, and not a `Tooltip` ──
+ *
+ * A `Tooltip` is a LABEL: a few words that show on hover and vanish when the
+ * pointer leaves — useless on a tablet, and gone before a sentence is read.
+ * This is content, so it opens on press (mouse, touch, Enter or Space) and
+ * stays until it is put away: a second press, Escape, or a click outside. It
+ * is React Aria's `DialogTrigger` on the system's `Popover` — the same white
+ * surface as a calendar or a small filter form — so placement, flipping when
+ * there is no room below, focus moving in and back to the `?`, and Escape are
+ * React Aria's, not a hand-written listener.
+ *
+ * The sentence also lives, hidden, next to the mark under `id`: a field points
+ * its `aria-describedby` there, and a closed popover is not in the page for a
+ * screen reader to read.
+ */
+export function Hint({ children, label = "?", id, }) {
+    const auto = useId();
+    const textId = id ?? auto;
+    return (_jsxs("span", { className: "inline-flex shrink-0", children: [_jsxs(DialogTrigger, { children: [_jsx(Button, { "aria-label": typeof children === "string" ? children : undefined, className: (state) => mark(state), children: label === "?" ? (_jsx(CircleHelp, { className: "size-3.5", strokeWidth: 2, "aria-hidden": true })) : (label) }), _jsx(Popover, { placement: "bottom", className: "max-w-64 rounded-box", children: _jsx(Dialog, { "aria-labelledby": textId, className: "px-3 py-2.5 text-micro leading-relaxed text-ink outline-0", children: children }) })] }), _jsx("span", { id: textId, hidden: true, children: children })] }));
+}

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

@@ -0,0 +1 @@
+export { Hint } from "./Hint.js";

package/dist/primitives/hint/index.js

@@ -0,0 +1 @@
+export { Hint } from "./Hint.js";

package/dist/primitives/index.d.ts

@@ -0,0 +1,20 @@
+export * from "./block/index.js";
+export * from "./button/index.js";
+export * from "./cell/index.js";
+export * from "./choice/index.js";
+export * from "./date/index.js";
+export * from "./dialog/index.js";
+export * from "./disclosure/index.js";
+export * from "./field/index.js";
+export * from "./hint/index.js";
+export * from "./menu/index.js";
+export * from "./notice/index.js";
+export * from "./overlay/index.js";
+export * from "./picker/index.js";
+export * from "./surface/index.js";
+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

@@ -0,0 +1,21 @@
+/* PRIMITIVES — a piece that does not know which screen it is on. */
+export * from "./block/index.js";
+export * from "./button/index.js";
+export * from "./cell/index.js";
+export * from "./choice/index.js";
+export * from "./date/index.js";
+export * from "./dialog/index.js";
+export * from "./disclosure/index.js";
+export * from "./field/index.js";
+export * from "./hint/index.js";
+export * from "./menu/index.js";
+export * from "./notice/index.js";
+export * from "./overlay/index.js";
+export * from "./picker/index.js";
+export * from "./surface/index.js";
+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";