@sincpro/web-ui 0.0.0-stage → 0.2.0

package/dist/primitives/notice/Toast.js

@@ -0,0 +1,142 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { cn, focusRing } from "../../foundations/variants.js";
+import { CheckCircle2, Info, TriangleAlert, X, XCircle } from "lucide-react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { Button as AriaButton, Link as AriaLink, Text, UNSTABLE_Toast as AriaToast, UNSTABLE_ToastContent as ToastContent, UNSTABLE_ToastQueue as ToastQueue, UNSTABLE_ToastRegion as ToastRegion, } from "react-aria-components";
+const Ctx = createContext(null);
+export function useToast() {
+    const api = useContext(Ctx);
+    if (api === null) {
+        throw new Error("useToast needs a <ToastProvider> above it in the tree.");
+    }
+    return api;
+}
+/** The same API, or `null` when no `ToastProvider` is above. For a component that OFFERS
+ *  undo when the screen has a notice stack and still renders alone — in a story, in a test,
+ *  in an app that has not mounted the provider yet. */
+export function useToastIfAny() {
+    return useContext(Ctx);
+}
+const ICON = {
+    neutral: Info,
+    info: Info,
+    good: CheckCircle2,
+    warn: TriangleAlert,
+    bad: XCircle,
+    accent: Info,
+};
+const TONE = {
+    neutral: "text-muted",
+    info: "text-info",
+    good: "text-good",
+    warn: "text-warn",
+    bad: "text-bad",
+    accent: "text-ink",
+};
+const LIFE = 8000;
+/** The default: the bad ones do NOT leave on their own. See the note above. */
+function lifeOf(toast) {
+    return toast.duration ?? (toast.tone === "bad" ? 0 : LIFE);
+}
+const LINK = "self-start rounded-control text-micro font-medium text-primary transition-colors duration-(--duration-instant) hover:underline hover:underline-offset-4 cursor-pointer outline-offset-1";
+export function ToastProvider({ children }) {
+    const [toasts, setToasts] = useState([]);
+    const next = useRef(1);
+    const dismiss = useCallback((id) => {
+        setToasts((prev) => prev.filter((t) => t.id !== id));
+    }, []);
+    const show = useCallback((spec) => {
+        const id = next.current;
+        next.current += 1;
+        setToasts((prev) => {
+            if (spec.key === undefined)
+                return [...prev, { ...spec, id }];
+            const i = prev.findIndex((t) => t.key === spec.key);
+            /* Replaces IN ITS PLACE and not at the end: if the notice jumps to the
+               bottom of the stack every time it updates, whoever was reading it loses
+               it. */
+            if (i < 0)
+                return [...prev, { ...spec, id }];
+            const n = [...prev];
+            n[i] = { ...spec, id };
+            return n;
+        });
+        return id;
+    }, []);
+    const api = useMemo(() => ({ show, dismiss }), [show, dismiss]);
+    return (_jsxs(Ctx.Provider, { value: api, children: [children, _jsx(ToastLayer, { toasts: toasts, onDismiss: dismiss })] }));
+}
+/** The region of a given list of notices. `ToastProvider` draws it from its own state; it is
+ *  exported so it can be drawn without the context — a story that wants to see the tones
+ *  together and still.
+ *
+ *  Context: React Aria's queue is the behaviour (timers, pause, landmark, focus) and this
+ *  list is the content. Each notice in the list is mirrored into the queue once; when the
+ *  queue closes one — its timer ran out, its × or its action was pressed — `onDismiss`
+ *  hears it, and when the list drops one the queue closes it. */
+export function ToastLayer({ toasts, onDismiss, }) {
+    const copy = useUiCopy();
+    const [queue] = useState(() => new ToastQueue());
+    const [, setVersion] = useState(0);
+    const latest = useRef(onDismiss);
+    /* The ids the layer is closing because the LIST dropped them: those must not be reported
+       back as if the person had closed them. */
+    const dropping = useRef(new Set());
+    useEffect(() => {
+        latest.current = onDismiss;
+    }, [onDismiss]);
+    useEffect(() => {
+        const wanted = new Set(toasts.map((t) => t.id));
+        const queued = new Set(queue.visibleToasts.map((t) => t.content.id));
+        for (const queuedToast of queue.visibleToasts) {
+            if (!wanted.has(queuedToast.content.id)) {
+                dropping.current.add(queuedToast.content.id);
+                queue.close(queuedToast.key);
+            }
+        }
+        for (const toast of toasts) {
+            if (queued.has(toast.id))
+                continue;
+            const life = lifeOf(toast);
+            queue.add(toast, {
+                ...(life > 0 ? { timeout: life } : {}),
+                onClose: () => {
+                    if (dropping.current.delete(toast.id))
+                        return;
+                    latest.current(toast.id);
+                },
+            });
+        }
+        setVersion((v) => v + 1);
+    }, [toasts, queue]);
+    const byId = new Map(queue.visibleToasts.map((t) => [t.content.id, t]));
+    /* Drawn in the LIST's order, oldest at the bottom: the newest notice appears on top of
+       the stack and a replaced one stays where it was. */
+    const ordered = [...toasts].reverse().flatMap((t) => {
+        const queued = byId.get(t.id);
+        return queued === undefined ? [] : [{ toast: t, queued }];
+    });
+    /* Mounted only while there is something to show. React Aria registers the region as an F6
+       landmark when it mounts, and it skips the registration if the region's element does not
+       exist yet — which is the case for a region mounted empty (it draws nothing until the
+       first notice). Mounting it together with its first notice is what makes F6 reach it. */
+    if (ordered.length === 0)
+        return null;
+    return (_jsx(ToastRegion, { queue: queue, "aria-label": copy.shell.notices, 
+        /* `inset-x-4` with a fixed width and `ml-auto`: that way the notice rests against the
+           right but never runs off the left edge on a phone. */
+        className: ({ isFocusVisible }) => cn("fixed inset-x-4 bottom-4 z-50 ml-auto flex w-(--container-toast) max-w-full flex-col gap-2 rounded-panel outline-offset-4", focusRing({ isFocusVisible })), children: ordered.map(({ toast, queued }) => (_jsx(ToastCard, { toast: toast, queued: queued, queue: queue }, queued.key))) }));
+}
+function ToastCard({ toast, queued, queue, }) {
+    const copy = useUiCopy();
+    const tone = toast.tone ?? "neutral";
+    const Icon = ICON[tone];
+    const close = () => queue.close(queued.key);
+    const action = toast.action;
+    return (_jsxs(AriaToast, { toast: queued, className: ({ isFocusVisible }) => cn("flex min-w-0 items-start gap-2.5 rounded-panel border border-line bg-surface px-3.5 py-3 shadow-float outline-offset-2", focusRing({ isFocusVisible })), children: [_jsx(Icon, { className: `mt-px size-(--size-icon-md) shrink-0 ${TONE[tone]}`, strokeWidth: 2, "aria-hidden": true }), _jsxs(ToastContent, { className: "flex min-w-0 flex-1 flex-col gap-1", children: [_jsx(Text, { slot: "title", className: "text-meta text-ink", children: toast.message }), toast.detail === undefined ? null : (_jsx(Text, { slot: "description", className: "text-micro text-muted", children: toast.detail }))] }), action === undefined ? null : action.href !== undefined ? (_jsx(AriaLink, { href: action.href, onPress: close, className: ({ isFocusVisible }) => cn(LINK, "mt-px", focusRing({ isFocusVisible })), children: action.label })) : (_jsx(AriaButton, { onPress: () => {
+                    action.onSelect?.();
+                    close();
+                }, className: ({ isFocusVisible }) => cn(LINK, "mt-px", focusRing({ isFocusVisible })), children: action.label })), _jsx(AriaButton, { slot: "close", "aria-label": copy.shell.closeNotice, className: ({ isFocusVisible }) => cn("-mt-0.5 -mr-1 inline-flex size-6 shrink-0 cursor-default items-center justify-center rounded-pill text-muted transition-colors duration-(--duration-instant) hover:bg-ink/6 hover:text-ink pressed:bg-ink/10", focusRing({ isFocusVisible })), children: _jsx(X, { className: "size-(--size-icon-sm)", strokeWidth: 2, "aria-hidden": true }) })] }));
+}

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

@@ -0,0 +1,4 @@
+export { Callout, type CalloutProps } from "./Callout.js";
+export { Flag, type FlagProps, type FlagTone } from "./Flag.js";
+export { Empty, Failed, ICONO_ROTO, Missing, Skeleton, } from "./Notice.js";
+export { ToastLayer, ToastProvider, type ToastSpec, useToast, useToastIfAny, } from "./Toast.js";

package/dist/primitives/notice/index.js

@@ -0,0 +1,6 @@
+/* How a view says that there is nothing, that it failed, or that nobody knows
+   how to draw it. */
+export { Callout } from "./Callout.js";
+export { Flag } from "./Flag.js";
+export { Empty, Failed, ICONO_ROTO, Missing, Skeleton, } from "./Notice.js";
+export { ToastLayer, ToastProvider, useToast, useToastIfAny, } from "./Toast.js";

package/dist/primitives/overlay/Popover.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from "react";
+import { type PopoverProps as AriaPopoverProps } from "react-aria-components";
+export type PopoverProps = Omit<AriaPopoverProps, "children"> & {
+    children: ReactNode;
+};
+export declare function Popover({ children, className, offset, ...props }: PopoverProps): import("react").JSX.Element;

package/dist/primitives/overlay/Popover.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { tv } from "../../foundations/variants.js";
+import { composeRenderProps, Popover as AriaPopover, } from "react-aria-components";
+/**
+ * What floats over the page anchored to something: the calendar of a date picker, the list
+ * of a combobox, a small form opened from a button.
+ *
+ * Context: it is the same surface the system's `Menu` floats on — raised white, strong
+ * hairline, the `float` shadow — so everything that opens on top of the page reads as one
+ * kind of thing. React Aria places it, flips it when it does not fit, traps and returns the
+ * focus and closes it on Escape; this only dresses it.
+ */
+const popover = tv({
+    base: "rounded-panel border border-line-strong bg-surface text-ink shadow-float outline-0 transition-[opacity,translate] duration-(--duration-quick) ease-(--ease-out) forced-colors:bg-[Canvas]",
+    variants: {
+        isEntering: {
+            true: "opacity-0 placement-bottom:-translate-y-1 placement-top:translate-y-1",
+        },
+        isExiting: {
+            true: "opacity-0",
+        },
+    },
+});
+export function Popover({ children, className, offset = 6, ...props }) {
+    return (_jsx(AriaPopover, { offset: offset, ...props, className: composeRenderProps(className, (own, state) => popover({ ...state, className: own })), children: children }));
+}

package/dist/primitives/overlay/PopoverTrigger.d.ts

@@ -0,0 +1,55 @@
+import { type PopoverProps } from "./Popover.js";
+import { type ReactElement, type ReactNode } from "react";
+/** What the trigger has to accept: the system's `Button` and `IconButton` both do — they
+ *  forward `ref`, spread native props and say what they open. */
+type TriggerElement = ReactElement<{
+    expanded?: boolean;
+    haspopup?: "menu" | "dialog" | "listbox";
+}>;
+type Naming = 
+/** Drawn at the top of the popover, and its accessible name. */
+{
+    title: string;
+    label?: undefined;
+}
+/** The accessible name when the popover has no visible title — a detail card whose
+ *  first line already says what it is. */
+ | {
+    title?: undefined;
+    label: string;
+};
+export type PopoverTriggerProps = Naming & {
+    /** The button that opens it — a system `Button` or `IconButton`, written as an element. */
+    trigger: TriggerElement;
+    /** The content. As a function it receives `close`, for the «Aplicar» of a small form. */
+    children: ReactNode | ((close: () => void) => ReactNode);
+    placement?: PopoverProps["placement"];
+};
+/**
+ * A small form or a detail opened from a button, floating next to it: «filtrar por monto»,
+ * «ver detalle del cliente».
+ *
+ * Context: it is the step below `Dialog`. A dialog takes the screen and asks something
+ * before moving on; this asks two numbers WITHOUT hiding the table they filter — the
+ * person keeps seeing what the answer is about. It floats on the system's `Popover`, so it
+ * looks like the calendar of a date picker and the list of a combobox.
+ *
+ * ── Why `trigger={<Button …/>}` and not a compound `<PopoverTrigger.Button>` ──
+ *
+ * The opener is an ordinary system button, written the way every other button of the
+ * screen is written. A compound form would need a second button component — a React Aria
+ * `Button` dressed like ours — and two buttons that look the same and are different
+ * components drift apart by the third release. One prop, one element, one button.
+ *
+ * ── It is React Aria's `DialogTrigger`, through `Pressable` ──
+ *
+ * `DialogTrigger` hands its trigger the press handlers and a `ref` through context; React
+ * Aria's `Pressable` is the adapter that clones them onto any element that forwards `ref`
+ * and spreads native props — which the system's buttons do. So the popover is anchored to
+ * the button itself, focus goes into the dialog and comes back to the button, and Escape
+ * and a click outside close it. The open state is kept here only to tell the button
+ * `expanded` and `haspopup="dialog"`, so it says what it opens the same way a menu
+ * trigger says it.
+ */
+export declare function PopoverTrigger({ trigger, title, label, children, placement, }: PopoverTriggerProps): import("react").JSX.Element;
+export {};

package/dist/primitives/overlay/PopoverTrigger.js

@@ -0,0 +1,38 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Popover } from "./Popover.js";
+import { cloneElement, useState, } from "react";
+import { Dialog, DialogTrigger, Heading, Pressable } from "react-aria-components";
+/**
+ * A small form or a detail opened from a button, floating next to it: «filtrar por monto»,
+ * «ver detalle del cliente».
+ *
+ * Context: it is the step below `Dialog`. A dialog takes the screen and asks something
+ * before moving on; this asks two numbers WITHOUT hiding the table they filter — the
+ * person keeps seeing what the answer is about. It floats on the system's `Popover`, so it
+ * looks like the calendar of a date picker and the list of a combobox.
+ *
+ * ── Why `trigger={<Button …/>}` and not a compound `<PopoverTrigger.Button>` ──
+ *
+ * The opener is an ordinary system button, written the way every other button of the
+ * screen is written. A compound form would need a second button component — a React Aria
+ * `Button` dressed like ours — and two buttons that look the same and are different
+ * components drift apart by the third release. One prop, one element, one button.
+ *
+ * ── It is React Aria's `DialogTrigger`, through `Pressable` ──
+ *
+ * `DialogTrigger` hands its trigger the press handlers and a `ref` through context; React
+ * Aria's `Pressable` is the adapter that clones them onto any element that forwards `ref`
+ * and spreads native props — which the system's buttons do. So the popover is anchored to
+ * the button itself, focus goes into the dialog and comes back to the button, and Escape
+ * and a click outside close it. The open state is kept here only to tell the button
+ * `expanded` and `haspopup="dialog"`, so it says what it opens the same way a menu
+ * trigger says it.
+ */
+export function PopoverTrigger({ trigger, title, label, children, placement = "bottom start", }) {
+    const [open, setOpen] = useState(false);
+    return (_jsxs(DialogTrigger, { isOpen: open, onOpenChange: setOpen, children: [_jsx(Pressable, { children: 
+                /* React Aria types the child as an intrinsic element; a component that forwards
+                   `ref` and spreads native props is the same thing to it at runtime. */
+                cloneElement(trigger, { expanded: open, haspopup: "dialog" }) }), _jsx(Popover, { placement: placement, children: _jsx(Dialog, { "aria-label": label, className: "max-h-[inherit] max-w-sm min-w-56 overflow-auto p-3 outline-0", children: ({ close }) => (_jsxs(_Fragment, { children: [title === undefined ? null : (_jsx(Heading, { slot: "title", className: "mb-2 text-meta font-semibold text-ink", children: title })), typeof children === "function" ? children(close) : children] })) }) })] }));
+}

package/dist/primitives/overlay/Preview.d.ts

@@ -0,0 +1,19 @@
+import { type PopoverProps } from "./Popover.js";
+import { type ReactElement, type ReactNode } from "react";
+export type PreviewProps = {
+    /** What the preview is of — a link to the record, written as an element: a React Aria
+     *  `Link`, or anything that forwards `ref` and spreads native props. It must be
+     *  focusable: the keyboard reaches the preview through it. */
+    trigger: ReactElement;
+    /** The accessible name of the floating card: «Resumen de Distribuidora Andina». */
+    label: string;
+    /** What floats: a `RelationCard`, a few facts. It may hold actions — «Abrir». */
+    children: ReactNode;
+    placement?: PopoverProps["placement"];
+    /** Milliseconds resting on the trigger before it opens. 600 by default — see above. */
+    delay?: number;
+    closeDelay?: number;
+    /** The trigger stays, the preview does not open. */
+    disabled?: boolean;
+};
+export declare function Preview({ trigger, label, children, placement, delay, closeDelay, disabled, }: PreviewProps): import("react").JSX.Element;

package/dist/primitives/overlay/Preview.js

@@ -0,0 +1,60 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Popover } from "./Popover.js";
+import { isValidElement } from "react";
+import { Focusable, Link, PreviewTrigger } from "react-aria-components";
+/**
+ * A glance at a record without leaving the screen: the customer of an invoice, the product
+ * of a line — who or what it is, shown when the pointer rests on its name, the keyboard
+ * stops on it or a finger presses it long.
+ *
+ * Context: it sits between the two other things that float from a mark.
+ *
+ * - `Tooltip` is a LABEL: a few words about a control, never interactive — React Aria makes
+ *   it a `role="tooltip"` the keyboard cannot enter. A customer's debt, phone and «Abrir»
+ *   are not a label.
+ * - `PopoverTrigger` is ASKED FOR: a press on a button opens a dialog that takes the focus
+ *   until it is closed. Right for a small form; too much ceremony to see whose NIT it is.
+ *
+ * `Preview` is React Aria's `PreviewTrigger`: a NON-modal popover (`role="dialog"`, named by
+ * `label`) that opens on hover, on keyboard focus and on long press, and that MAY hold
+ * interactive content. It does not take the focus when it opens — the person who tabs past
+ * a column of customers keeps walking the table — but Tab from the trigger goes into it,
+ * Escape closes it and returns to the trigger, and the pointer can travel diagonally from the
+ * name to the card without it closing (React Aria's safe area). A long press moves the focus
+ * into it, so a touch screen reader lands on the card. All of that is React Aria's; this
+ * only floats it on the system's `Popover` — the surface, hairline, radius and `float`
+ * shadow everything that opens over the page has.
+ *
+ * ── The delays: 600 ms to open, 200 ms to close ──────────────────────
+ *
+ * They are React Aria's defaults, written here so a change in the library does not change
+ * the system silently. 600 ms is the line between crossing and resting: in a table the
+ * pointer crosses customer names all day on its way to something else, and a card of 18rem
+ * that covered four rows on every pass would be noise. Below ~400 ms it opens on the way;
+ * above a second it feels broken to the person who did stop to look. Keyboard focus waits the
+ * same, so tabbing quickly does not open a card per row. Once one is open the next opens at
+ * once (React Aria's warm-up): comparing the customers of six invoices is a run down the
+ * column, not six waits. It is shorter than a tooltip's on purpose — a preview is asked for
+ * by resting on a NAME you want to know about; a tooltip names an icon you mostly know.
+ * 200 ms to close is only for the jittery exit; the trip to the card is covered by the
+ * safe area, not by the delay.
+ *
+ * ── The trigger ──────────────────────────────────────────────────────
+ *
+ * React Aria hands the trigger its hover, focus, long-press and `aria-*` props through
+ * context. A React Aria `Link` — the name of a `RelationValue` — reads that context itself,
+ * so it is passed as is. Anything else — a system `Button`, a `ButtonLink`, a plain `<a>` —
+ * goes through `Focusable`, the adapter that clones those props and a `ref` onto an element
+ * that forwards `ref` and spreads native props (the same one `TooltipTrigger` uses). Wrapping
+ * the `Link` too would hand it the props twice.
+ */
+const PREVIEW_DELAY = 600;
+const PREVIEW_CLOSE_DELAY = 200;
+export function Preview({ trigger, label, children, placement = "bottom start", delay = PREVIEW_DELAY, closeDelay = PREVIEW_CLOSE_DELAY, disabled = false, }) {
+    const readsContext = isValidElement(trigger) && trigger.type === Link;
+    return (_jsxs(PreviewTrigger, { delay: delay, closeDelay: closeDelay, isDisabled: disabled, children: [readsContext ? (trigger) : (
+            /* React Aria types the child as an intrinsic element; a component that forwards
+               `ref` and spreads native props is the same thing to it at runtime. */
+            _jsx(Focusable, { children: trigger })), _jsx(Popover, { placement: placement, "aria-label": label, children: _jsx("div", { className: "max-h-[inherit] max-w-sm overflow-auto p-3", children: children }) })] }));
+}

package/dist/primitives/overlay/Tooltip.d.ts

@@ -0,0 +1,38 @@
+import { type ReactNode } from "react";
+import { type TooltipProps as AriaTooltipProps } from "react-aria-components";
+export type TooltipProps = Omit<AriaTooltipProps, "children" | "offset"> & {
+    /** A few words. A sentence of help is a `Hint`, not a tooltip. */
+    children: ReactNode;
+    /** The small point toward the control. On by default: in a row of five icons it says
+     *  WHICH one is being named. */
+    arrow?: boolean;
+};
+export declare function Tooltip({ children, arrow, className, ...props }: TooltipProps): import("react").JSX.Element;
+export declare function useInTooltipTrigger(): boolean;
+/**
+ * Ties a control to its `Tooltip`: the control first, the tooltip second.
+ *
+ * Context: the timing is React Aria's on purpose — its default delay before the first one,
+ * and the warm-up that opens the next one at once while the pointer runs along a row of
+ * icons. A tooltip that opens on every pass of the mouse is noise; one that makes you wait
+ * on each icon of a row is a toll. `delay` is here for the rare control that needs it, not
+ * to tune each screen.
+ *
+ * ── Why the control is wrapped in `Focusable` here ──
+ *
+ * React Aria's trigger hands its pointer, focus and `aria-describedby` props to the control
+ * through context, and only a React Aria component reads that context. `Focusable` is the
+ * adapter for everything else: it clones the control with those props and a `ref`. Doing it
+ * here means a consumer writes `<TooltipTrigger><Button …/><Tooltip …/></TooltipTrigger>`
+ * with the system's own buttons — they forward `ref` and spread native props — or with a
+ * plain `<button>`, and never has to know the adapter exists.
+ */
+export declare function TooltipTrigger({ children, delay, closeDelay, disabled, }: {
+    /** The control — one element that forwards `ref` and spreads native props, like every
+     *  system button — then the `Tooltip`. */
+    children: ReactNode;
+    /** Milliseconds before the first tooltip opens. React Aria's default when absent. */
+    delay?: number;
+    closeDelay?: number;
+    disabled?: boolean;
+}): import("react").JSX.Element;

package/dist/primitives/overlay/Tooltip.js

@@ -0,0 +1,74 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { tv } from "../../foundations/variants.js";
+import { Children, createContext, isValidElement, useContext, } from "react";
+import { composeRenderProps, Focusable, OverlayArrow, Tooltip as AriaTooltip, TooltipTrigger as AriaTooltipTrigger, } from "react-aria-components";
+/**
+ * The name of a control that has no visible name — an icon button of a table row, of a
+ * toolbar — shown when the pointer rests on it or the keyboard reaches it.
+ *
+ * Context: it is not the other two ways of putting words next to a mark.
+ *
+ * - `Hint` is CONTENT: a sentence of help that does not fit on the page, behind a `?`. It
+ *   opens on press and stays, because it is meant to be read, on a tablet too.
+ * - The native `title` is the browser's tooltip: it shows late, unstyled, never on keyboard
+ *   focus and never on touch — the person who navigates with Tab never learns what the
+ *   trash can is. That is why icon targets no longer use it.
+ *
+ * `Tooltip` is the LABEL, shown: a few words, on hover AND on focus, never interactive, never
+ * pinned. It is drawn on the chrome (the dark surface of the shell) because it is not part
+ * of the page — it is a whisper about one control, and the dark box reads as that against
+ * a page of white surfaces. React Aria decides when: its default delay on the first hover,
+ * then the next tooltip of the row opens at once (warm-up), and Escape closes it.
+ *
+ * Every `IconButton` and `IconLink` already draws one with its `label`; write a
+ * `TooltipTrigger` by hand only for a control that is not an icon target, or to say more
+ * than the label.
+ */
+const tooltip = tv({
+    base: "group max-w-64 rounded-control bg-chrome px-2 py-1 text-micro text-chrome-ink shadow-float transition-[opacity,translate] duration-(--duration-quick) ease-(--ease-out) forced-colors:border forced-colors:border-[ButtonBorder] forced-colors:bg-[Canvas] forced-colors:text-[CanvasText]",
+    variants: {
+        isEntering: {
+            true: "opacity-0 placement-top:translate-y-1 placement-bottom:-translate-y-1 placement-left:translate-x-1 placement-right:-translate-x-1",
+        },
+        isExiting: {
+            true: "opacity-0",
+        },
+    },
+});
+export function Tooltip({ children, arrow = true, className, ...props }) {
+    return (_jsxs(AriaTooltip, { offset: arrow ? 8 : 4, ...props, className: composeRenderProps(className, (own, state) => tooltip({ ...state, className: own })), children: [arrow ? (_jsx(OverlayArrow, { children: _jsx("svg", { viewBox: "0 0 8 8", "aria-hidden": true, className: "block size-2 fill-chrome group-placement-bottom:rotate-180 group-placement-left:-rotate-90 group-placement-right:rotate-90 forced-colors:fill-[Canvas]", children: _jsx("path", { d: "M0 0 L4 4 L8 0" }) }) })) : null, children] }));
+}
+/** True inside the control slot of a `TooltipTrigger`: an `IconButton` written there leaves
+ *  its own tooltip out, so the consumer's is the only one. */
+const InTooltipTrigger = createContext(false);
+export function useInTooltipTrigger() {
+    return useContext(InTooltipTrigger);
+}
+function isDisabledControl(control) {
+    if (!isValidElement(control))
+        return false;
+    return control.props.disabled === true || control.props.isDisabled === true;
+}
+/**
+ * Ties a control to its `Tooltip`: the control first, the tooltip second.
+ *
+ * Context: the timing is React Aria's on purpose — its default delay before the first one,
+ * and the warm-up that opens the next one at once while the pointer runs along a row of
+ * icons. A tooltip that opens on every pass of the mouse is noise; one that makes you wait
+ * on each icon of a row is a toll. `delay` is here for the rare control that needs it, not
+ * to tune each screen.
+ *
+ * ── Why the control is wrapped in `Focusable` here ──
+ *
+ * React Aria's trigger hands its pointer, focus and `aria-describedby` props to the control
+ * through context, and only a React Aria component reads that context. `Focusable` is the
+ * adapter for everything else: it clones the control with those props and a `ref`. Doing it
+ * here means a consumer writes `<TooltipTrigger><Button …/><Tooltip …/></TooltipTrigger>`
+ * with the system's own buttons — they forward `ref` and spread native props — or with a
+ * plain `<button>`, and never has to know the adapter exists.
+ */
+export function TooltipTrigger({ children, delay, closeDelay, disabled = false, }) {
+    const [control, ...tooltip] = Children.toArray(children);
+    return (_jsxs(AriaTooltipTrigger, { delay: delay, closeDelay: closeDelay, isDisabled: disabled, children: [_jsx(InTooltipTrigger.Provider, { value: true, children: _jsx(Focusable, { isDisabled: isDisabledControl(control), children: control }) }), tooltip] }));
+}

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

@@ -0,0 +1,4 @@
+export { Popover, type PopoverProps } from "./Popover.js";
+export { PopoverTrigger, type PopoverTriggerProps, } from "./PopoverTrigger.js";
+export { Preview, type PreviewProps } from "./Preview.js";
+export { Tooltip, type TooltipProps, TooltipTrigger, } from "./Tooltip.js";

package/dist/primitives/overlay/index.js

@@ -0,0 +1,7 @@
+/* LO QUE FLOTA anclado a algo: el calendario de un selector de fecha, la lista de un
+   combobox, un formulario chico abierto desde un botón, el nombre de un ícono, el vistazo
+   a un registro al pasar por su nombre. */
+export { Popover } from "./Popover.js";
+export { PopoverTrigger, } from "./PopoverTrigger.js";
+export { Preview } from "./Preview.js";
+export { Tooltip, TooltipTrigger, } from "./Tooltip.js";

package/dist/primitives/picker/Picker.d.ts

@@ -0,0 +1,89 @@
+import { type FormMode } from "../field/mode.js";
+import type { LucideIcon } from "lucide-react";
+import { type ReactNode } from "react";
+export interface PickerItem {
+    id: string;
+    name: string;
+    /** The data that allows choosing well, already formatted: stock on hand, a
+     *  price, a tax id. In tabular figures, so they line up between options, which
+     *  is what makes them comparable at a glance. */
+    meta?: string;
+    tags?: ReactNode;
+    icon?: LucideIcon;
+    disabled?: boolean;
+    /** Extra text WHERE TO SEARCH that is not drawn: the internal code and the
+     *  barcode of a product, the NIT of a customer.
+     *
+     *  Context: it is the difference between being able to type the code printed
+     *  on the box and finding the product, and having to remember what it was
+     *  called. Drawing every code of every option is not an alternative. */
+    haystack?: string;
+    /** The header this item is listed under. Consecutive items with the same section share
+     *  one header; an item without it is listed loose, outside any section. */
+    section?: string;
+}
+/**
+ * What the list shows and how many are left out of it. Capped at 8 with the footer count,
+ * unless the list loads incrementally — then everything that arrived is listed and the
+ * scroll asks for more.
+ */
+export declare function shownRows(filtered: readonly PickerItem[], { loading, incremental }: {
+    loading: boolean;
+    incremental: boolean;
+}): {
+    visible: readonly PickerItem[];
+    remaining: number;
+};
+export type PickerProps = {
+    id?: string;
+    items: readonly PickerItem[];
+    value?: string;
+    onChange?: (id: string) => void;
+    placeholder?: string;
+    /** What to do with the ones that don't fit. Without this, the footer only
+     *  informs. */
+    onBrowseAll?: () => void;
+    /** Open the chosen record. Drawn as a trailing affordance, the way a many2one
+     *  offers "open" next to "pick". Absent when there is nothing chosen. */
+    onOpen?: (id: string) => void;
+    emptyText?: string;
+    /** Placeholder of the field while it is being typed into. It is NOT a second
+     *  box — the field itself is the search. */
+    searchPlaceholder?: string;
+    /** The options are still coming. It gets said, not hidden: an empty picker
+     *  while loading reads as "there is nothing", which is a different answer. */
+    loading?: boolean;
+    loadingText?: string;
+    /** The list grows from the backend: called when its end scrolls into view. The consumer
+     *  appends the next page to `items`; with nothing more to fetch it does nothing. Turns off
+     *  the cap of 8, the «see all…» row and the footer count. */
+    onLoadMore?: () => void;
+    /** A page asked for by `onLoadMore` is on its way: a quiet row at the end says so. Unlike
+     *  `loading`, the rows already there stay. */
+    loadingMore?: boolean;
+    describedBy?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    /** The name of the control when it is NOT inside a `Field` — a cell of an editable table.
+     *  Inside a field, the field's label names it. */
+    "aria-label"?: string;
+    /** Forces the mode. By default it inherits the form's: in read mode it draws the name. */
+    mode?: FormMode;
+};
+export declare function Picker({ mode, ...props }: PickerProps): import("react").JSX.Element;
+/**
+ * The list of a `Picker`: its rows, the section headers, the «see all…» row and the loading
+ * row at the end. Internal — not exported from the family — and apart from the combobox so it
+ * can be rendered on the server without a popover, which is how the tests see the rows.
+ */
+export declare function PickerOptions({ items, marks, hints, remaining, emptyText, onLoadMore, loadingMore, "aria-label": ariaLabel, }: {
+    items: readonly PickerItem[];
+    marks: boolean;
+    hints: boolean;
+    remaining: number;
+    emptyText: string;
+    onLoadMore?: () => void;
+    loadingMore?: boolean;
+    /** Only when rendered outside the combobox, which otherwise names the list. */
+    "aria-label"?: string;
+}): import("react").JSX.Element;