@sincpro/web-ui 0.0.0-stage → 0.1.0

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,3 @@
+export { Popover, type PopoverProps } from "./Popover.js";
+export { PopoverTrigger, type PopoverTriggerProps, } from "./PopoverTrigger.js";
+export { Tooltip, type TooltipProps, TooltipTrigger, } from "./Tooltip.js";

package/dist/primitives/overlay/index.js

@@ -0,0 +1,5 @@
+/* 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. */
+export { Popover } from "./Popover.js";
+export { PopoverTrigger, } from "./PopoverTrigger.js";
+export { Tooltip, TooltipTrigger, } from "./Tooltip.js";

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

@@ -0,0 +1,48 @@
+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;
+}
+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;
+    describedBy?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    /** 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;

package/dist/primitives/picker/Picker.js

@@ -0,0 +1,150 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { AriaLocale } from "../../foundations/aria.js";
+import { fillCopy, useUiCopy } from "../../foundations/copy.js";
+import { cn, tv } from "../../foundations/variants.js";
+import { IconButton } from "../button/Button.js";
+import { FieldButton, FieldGroup } from "../field/aria.js";
+import { useFieldIds } from "../field/context.js";
+import { ReadValue } from "../field/Field.js";
+import { useFormMode } from "../field/mode.js";
+import { Popover } from "../overlay/Popover.js";
+import { Check, ChevronDown, SquareArrowOutUpRight } from "lucide-react";
+import { useContext, useMemo, useRef, useState } from "react";
+import { ComboBox as AriaComboBox, ComboBoxStateContext, Input, ListBox, ListBoxItem, Text, useFilter, } from "react-aria-components";
+/** The id of the «see all…» row. Not a record id: it cannot collide with one. */
+const BROWSE_ALL = "\u0000browse-all";
+const CAP = 8;
+/* No focus ring on an option: the focus stays in the input (the list is driven from it),
+   and the marked row is said by its tint — a ring inside the list as well as around the
+   field is two marks for one place. */
+const option = tv({
+    base: "flex w-full min-w-0 cursor-default gap-2 rounded-control px-2 text-left outline-0 select-none forced-color-adjust-none",
+    variants: {
+        hints: {
+            true: "items-start py-1.5",
+            false: "items-center py-1",
+        },
+        isFocused: {
+            true: "bg-primary/8 forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]",
+        },
+        isHovered: {
+            true: "bg-ink/4",
+        },
+        isPressed: {
+            true: "bg-primary/12",
+        },
+        isDisabled: {
+            true: "opacity-45 forced-colors:text-[GrayText]",
+        },
+    },
+    compoundVariants: [{ isFocused: true, isHovered: true, class: "bg-primary/8" }],
+});
+export function Picker({ mode, ...props }) {
+    if (useFormMode(mode) === "read") {
+        return _jsx(ReadValue, { value: props.items.find((i) => i.id === props.value)?.name ?? null });
+    }
+    /* 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(EditablePicker, { ...props }) }));
+}
+function EditablePicker({ id: ownId, items, value, onChange, placeholder, onBrowseAll, onOpen, emptyText, searchPlaceholder, loading = false, loadingText, describedBy: ownDescribedBy, invalid: ownInvalid, disabled = false, }) {
+    const { id, labelledBy, describedBy, invalid } = useFieldIds({
+        id: ownId,
+        describedBy: ownDescribedBy,
+        invalid: ownInvalid,
+    });
+    const copy = useUiCopy();
+    const { contains } = useFilter({ sensitivity: "base" });
+    const shownPlaceholder = placeholder ?? copy.picker.placeholder;
+    const shownEmpty = emptyText ?? copy.picker.empty;
+    const shownSearch = searchPlaceholder ?? copy.picker.search;
+    const shownLoading = loadingText ?? copy.picker.loading;
+    const chosen = items.find((i) => i.id === value);
+    const chosenName = chosen?.name ?? "";
+    /* Both the text and the choice are controlled, so React Aria never rewrites the field
+       from its own collection — which is capped and filtered, and may not hold the chosen
+       record at all. `query` is what filters: empty when the list opens (the whole list,
+       not just the one already chosen), the typed text after that. */
+    const [open, setOpen] = useState(false);
+    const [text, setText] = useState(chosenName);
+    const [query, setQuery] = useState("");
+    const [shownFor, setShownFor] = useState(chosenName);
+    if (!open && shownFor !== chosenName) {
+        setShownFor(chosenName);
+        setText(chosenName);
+    }
+    const filtered = useMemo(() => {
+        const q = query.trim();
+        if (q === "")
+            return items;
+        return items.filter((i) => contains(`${i.name} ${i.meta ?? ""} ${i.haystack ?? ""}`, q));
+    }, [items, query, contains]);
+    const visible = loading ? [] : filtered.slice(0, CAP);
+    const remaining = loading ? 0 : filtered.length - visible.length;
+    const hasMarks = items.some((i) => i.icon !== undefined);
+    const hasHints = visible.some((i) => i.meta !== undefined);
+    /* «See all…» is an OPTION at the end of the list and not a button in a footer: the
+       arrows reach it like any other row. As a footer button it was out of the keyboard's
+       path — Tab leaves the field and closes the list before getting there. */
+    const browsable = remaining > 0 && onBrowseAll !== undefined;
+    const listed = browsable
+        ? [...visible, { id: BROWSE_ALL, name: copy.picker.browseAll }]
+        : visible;
+    const closeList = useRef(null);
+    const take = (key) => {
+        if (key === null)
+            return;
+        const next = String(key);
+        if (next === BROWSE_ALL) {
+            /* The full list opens somewhere else (a dialog, a panel): this one closes and the
+               field keeps the chosen name. */
+            closeList.current?.();
+            setText(chosenName);
+            setQuery("");
+            onBrowseAll?.();
+            return;
+        }
+        setText(items.find((i) => i.id === next)?.name ?? "");
+        setQuery("");
+        if (next !== value)
+            onChange?.(next);
+    };
+    return (_jsxs(AriaComboBox, { id: id, "aria-labelledby": labelledBy, "aria-describedby": describedBy, items: listed, value: value ?? null, onChange: take, inputValue: text, onInputChange: (next) => {
+            setText(next);
+            setQuery(next);
+        }, onOpenChange: (isOpen, trigger) => {
+            setOpen(isOpen);
+            if (isOpen && trigger !== "input")
+                setQuery("");
+            if (!isOpen) {
+                setText(chosenName);
+                setQuery("");
+            }
+        }, 
+        /* Opening on focus is what a many2one does: you arrive at the field to choose, and
+           the options are the answer before the first letter. */
+        menuTrigger: "focus", 
+        /* An empty list stays open to SAY it is empty (or loading) instead of vanishing. */
+        allowsEmptyCollection: true, isInvalid: invalid, isDisabled: disabled, className: "w-full min-w-0", children: [_jsx(CloseBridge, { into: closeList }), _jsxs(FieldGroup, { children: [_jsx(Input, { placeholder: loading ? shownLoading : open ? shownSearch : shownPlaceholder, title: shownSearch, 
+                        /* Arriving selects the name, so the first letter typed replaces it. Only when
+                           ARRIVING: React Aria hands the focus back to the input while the list is open,
+                           and selecting again then would swallow every second letter. */
+                        onFocus: (event) => {
+                            if (!open)
+                                event.currentTarget.select();
+                        }, 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" }), value !== undefined && value !== "" && onOpen !== undefined ? (_jsx(IconButton, { icon: SquareArrowOutUpRight, label: copy.picker.open, size: "sm", disabled: disabled, onClick: () => onOpen(value) })) : null, _jsx(FieldButton, { className: "mr-1", children: _jsx(ChevronDown, { "aria-hidden": true, className: "size-(--size-icon-md)", strokeWidth: 2 }) })] }), _jsxs(Popover, { placement: "bottom start", className: "flex w-(--trigger-width) flex-col overflow-hidden", children: [_jsx(ListBox, { items: listed, renderEmptyState: () => (_jsx("p", { className: "px-3 py-3 text-center text-meta text-muted", children: loading ? shownLoading : shownEmpty })), className: "min-h-0 flex-1 overflow-y-auto p-1 outline-0", children: (item) => item.id === BROWSE_ALL ? (_jsx(ListBoxItem, { id: BROWSE_ALL, textValue: item.name, className: (state) => `${option({ ...state, hints: false })} mt-1 border-t border-line text-primary`, children: _jsxs("span", { className: "flex w-full items-center justify-between gap-2", children: [_jsx("span", { className: "font-medium", children: item.name }), _jsx("span", { className: "text-micro tabular-nums text-muted", children: fillCopy(copy.picker.more, {
+                                            count: remaining.toLocaleString(copy.locale),
+                                        }) })] }) })) : (_jsx(ListBoxItem, { id: item.id, textValue: item.name, isDisabled: item.disabled, className: (state) => option({ ...state, hints: hasHints }), children: ({ isSelected }) => (_jsx(Row, { item: item, selected: isSelected, marks: hasMarks, hints: hasHints })) })) }), remaining > 0 && !browsable ? (_jsxs("div", { className: "flex shrink-0 items-center gap-2 border-t border-line bg-ground px-2.5 py-1.5", children: [_jsx("span", { className: "text-micro tabular-nums text-muted", children: fillCopy(copy.picker.more, { count: remaining.toLocaleString(copy.locale) }) }), _jsx("span", { className: "text-micro text-muted", children: copy.picker.refine })] })) : null] })] }));
+}
+function Row({ item, selected, marks, hints, }) {
+    const Icon = item.icon;
+    return (_jsxs(_Fragment, { children: [marks ? (_jsx("span", { className: cn(hints ? "mt-0.5" : "", "flex size-(--size-icon-sm) shrink-0 items-center justify-center"), children: selected ? (_jsx(Check, { "aria-hidden": true, className: "size-(--size-icon-sm) text-primary forced-colors:text-[HighlightText]", strokeWidth: 2.5 })) : Icon !== undefined ? (_jsx(Icon, { "aria-hidden": true, className: "size-(--size-icon-sm) text-muted", strokeWidth: 1.75 })) : null })) : null, _jsxs("span", { className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [_jsxs("span", { className: "flex min-w-0 items-center gap-1.5", children: [_jsx(Text, { slot: "label", className: cn("min-w-0 truncate text-meta text-ink", selected ? "font-medium" : ""), children: item.name }), item.tags] }), item.meta === undefined ? null : (_jsx(Text, { slot: "description", className: "truncate text-micro tabular-nums text-muted", children: item.meta }))] }), !marks && selected ? (_jsx(Check, { "aria-hidden": true, className: "size-(--size-icon-sm) shrink-0 text-primary forced-colors:text-[HighlightText]", strokeWidth: 2.5 })) : null] }));
+}
+/** Hands the combobox's `close` to the code outside it: React Aria owns the open state and
+ *  offers no controlled `isOpen`, and the «see all…» row has to close the list it lives in. */
+function CloseBridge({ into }) {
+    const state = useContext(ComboBoxStateContext);
+    into.current = state === null ? null : () => state.close();
+    return null;
+}

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

@@ -0,0 +1 @@
+export { Picker, type PickerItem, type PickerProps, } from "./Picker.js";

package/dist/primitives/picker/index.js

@@ -0,0 +1,2 @@
+/* The replacement for `<select>` when you have to SEE in order to choose. */
+export { Picker, } from "./Picker.js";

package/dist/primitives/surface/Peek.d.ts

@@ -0,0 +1,60 @@
+import type { ReactNode } from "react";
+export interface PeekProps {
+    open: boolean;
+    title: ReactNode;
+    subtitle?: ReactNode;
+    /** The × button and Escape (while the focus is inside the drawer). */
+    onClose: () => void;
+    /** Promoting preserves the context: it is the same view changing surface. */
+    onPromote?: () => void;
+    /** The actions of the record being previewed, next to «open as panel». */
+    actions?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * The drawer that previews a record next to the list it came from.
+ *
+ * Context: the drawer comes in from the right and does NOT dim what is behind
+ * it — that is the property that defines it. The list it came from stays
+ * clickable, which is the whole point of a preview; a scrim would turn it into
+ * a dialog, and a dialog is for what has to be answered before moving on.
+ * Pressing another row replaces what the drawer shows; it never opens a second one.
+ *
+ * It is anchored to the work area and not to the window: it covers the content
+ * without covering the menu or the activity bar, which are still navigation.
+ * The left corners are the panel radius. The sheet still spans the work area;
+ * only the cut against the list is rounded, so the drawer reads as a panel.
+ *
+ * ── On a phone it is a bottom sheet ───────────────────────────────────
+ *
+ * Below `sm` (40rem, `--container-handheld`) there is no «beside the list»: 30rem from
+ * the right of a 390 px screen is the whole screen. So the same drawer anchors to the
+ * BOTTOM edge of the window — full width, top corners rounded, at most `--size-sheet`
+ * (90dvh) tall, its body scrolling inside — and comes in from below. The strip left on
+ * top still shows the list, and it is still not dimmed: what defines the drawer survives
+ * the change of edge. It is `fixed` there and not `absolute` because on a phone the work
+ * area is as tall as its content, and its bottom edge can be three screens down; the
+ * screen's bottom edge is where the thumb is. (Like any `fixed`, it is anchored to the
+ * window only if no ancestor has a `transform` or containment — mount it next to the
+ * list, not inside a `@container`.) CSS only: the focus, Escape and restore below do not
+ * change.
+ *
+ * ── Why it is not React Aria's `ModalOverlay` ─────────────────────────
+ *
+ * Every overlay React Aria has —`ModalOverlay`, `Sheet`— is modal: it makes the rest of the
+ * page `inert`, traps the focus and portals to the window. Each of those breaks a promise
+ * above: the list would stop answering, and the drawer would cover the menu. So the drawer
+ * is an `<aside>` in the work area (the «preview» landmark) holding a NON-modal React Aria
+ * `Dialog`:
+ *
+ * - `Dialog` — `role="dialog"` without `aria-modal`, named by its title (`Heading
+ *   slot="title"`), and on open it takes the focus itself — else a keyboard user would have
+ *   to tab through the whole list to reach it. Focusing the panel and not its first button
+ *   keeps the close tooltip from popping up on every open.
+ * - `FocusScope restoreFocus` — on close the focus goes back to the row that opened it.
+ *   There is no `contain`: Tab may walk out to the list, which is still live.
+ * - `useKeyboard` — Escape closes it while the focus is INSIDE the drawer. A listener on
+ *   the window closed it from anywhere, competing with every other Escape on the page (a
+ *   search field clearing, a list dropping its selection).
+ */
+export declare function Peek({ open, title, subtitle, onClose, onPromote, actions, children, }: PeekProps): import("react").JSX.Element | null;

package/dist/primitives/surface/Peek.js

@@ -0,0 +1,71 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { DensityProvider } from "../../foundations/density.js";
+import { cn } from "../../foundations/variants.js";
+import { Button, IconButton } from "../button/Button.js";
+import { Tag } from "../tag/Tag.js";
+import { SquareArrowOutUpRight, X } from "lucide-react";
+import { FocusScope, useKeyboard } from "react-aria";
+import { Dialog, Heading } from "react-aria-components";
+/**
+ * The drawer that previews a record next to the list it came from.
+ *
+ * Context: the drawer comes in from the right and does NOT dim what is behind
+ * it — that is the property that defines it. The list it came from stays
+ * clickable, which is the whole point of a preview; a scrim would turn it into
+ * a dialog, and a dialog is for what has to be answered before moving on.
+ * Pressing another row replaces what the drawer shows; it never opens a second one.
+ *
+ * It is anchored to the work area and not to the window: it covers the content
+ * without covering the menu or the activity bar, which are still navigation.
+ * The left corners are the panel radius. The sheet still spans the work area;
+ * only the cut against the list is rounded, so the drawer reads as a panel.
+ *
+ * ── On a phone it is a bottom sheet ───────────────────────────────────
+ *
+ * Below `sm` (40rem, `--container-handheld`) there is no «beside the list»: 30rem from
+ * the right of a 390 px screen is the whole screen. So the same drawer anchors to the
+ * BOTTOM edge of the window — full width, top corners rounded, at most `--size-sheet`
+ * (90dvh) tall, its body scrolling inside — and comes in from below. The strip left on
+ * top still shows the list, and it is still not dimmed: what defines the drawer survives
+ * the change of edge. It is `fixed` there and not `absolute` because on a phone the work
+ * area is as tall as its content, and its bottom edge can be three screens down; the
+ * screen's bottom edge is where the thumb is. (Like any `fixed`, it is anchored to the
+ * window only if no ancestor has a `transform` or containment — mount it next to the
+ * list, not inside a `@container`.) CSS only: the focus, Escape and restore below do not
+ * change.
+ *
+ * ── Why it is not React Aria's `ModalOverlay` ─────────────────────────
+ *
+ * Every overlay React Aria has —`ModalOverlay`, `Sheet`— is modal: it makes the rest of the
+ * page `inert`, traps the focus and portals to the window. Each of those breaks a promise
+ * above: the list would stop answering, and the drawer would cover the menu. So the drawer
+ * is an `<aside>` in the work area (the «preview» landmark) holding a NON-modal React Aria
+ * `Dialog`:
+ *
+ * - `Dialog` — `role="dialog"` without `aria-modal`, named by its title (`Heading
+ *   slot="title"`), and on open it takes the focus itself — else a keyboard user would have
+ *   to tab through the whole list to reach it. Focusing the panel and not its first button
+ *   keeps the close tooltip from popping up on every open.
+ * - `FocusScope restoreFocus` — on close the focus goes back to the row that opened it.
+ *   There is no `contain`: Tab may walk out to the list, which is still live.
+ * - `useKeyboard` — Escape closes it while the focus is INSIDE the drawer. A listener on
+ *   the window closed it from anywhere, competing with every other Escape on the page (a
+ *   search field clearing, a list dropping its selection).
+ */
+export function Peek({ open, title, subtitle, onClose, onPromote, actions, children, }) {
+    const copy = useUiCopy();
+    const { keyboardProps } = useKeyboard({
+        onKeyDown: (e) => {
+            if (e.key === "Escape")
+                onClose();
+            else
+                e.continuePropagation();
+        },
+    });
+    if (!open)
+        return null;
+    const hasActions = onPromote !== undefined || actions !== undefined;
+    return (_jsx(FocusScope, { restoreFocus: true, children: _jsx("aside", { ...keyboardProps, "aria-label": copy.shell.preview, className: "peek-width absolute top-0 right-0 bottom-0 z-30 overflow-hidden rounded-l-panel border-l border-line-strong bg-surface shadow-window transition-[opacity,translate] duration-(--duration-panel) ease-(--ease-out) starting:translate-x-4 starting:opacity-0 max-sm:fixed max-sm:top-auto max-sm:left-0 max-sm:max-h-(--size-sheet) max-sm:w-full max-sm:rounded-tr-panel max-sm:rounded-bl-none max-sm:border-t max-sm:border-l-0 max-sm:starting:translate-x-0 max-sm:starting:translate-y-4", children: _jsxs(Dialog, { className: "flex h-full max-h-[inherit] flex-col outline-0", children: [_jsxs("header", { className: "shrink-0 border-b border-line", children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2 px-3 py-2", children: [_jsx(Tag, { tone: "info", children: copy.shell.previewTag }), _jsx(Heading, { slot: "title", level: 2, className: "min-w-0 flex-1 truncate text-meta font-medium text-ink", children: title }), _jsx(IconButton, { icon: X, label: copy.shell.closePreview, onClick: onClose })] }), subtitle === undefined ? null : (_jsx("p", { className: "truncate px-3 pb-2 text-micro tabular-nums text-muted", children: subtitle }))] }), hasActions ? (_jsxs("div", { className: "flex min-w-0 shrink-0 flex-wrap items-center gap-1.5 border-b border-line px-3 py-1.5 max-sm:order-last max-sm:border-t max-sm:border-b-0 max-sm:pt-2 max-sm:safe-bottom", children: [onPromote === undefined ? null : (_jsx(Button, { role: "secondary", size: "sm", icon: SquareArrowOutUpRight, onClick: onPromote, children: copy.shell.openAsPanel })), actions] })) : null, _jsx("div", { className: cn("min-h-0 flex-1 overflow-y-auto px-3 py-3", !hasActions && "max-sm:safe-bottom"), children: _jsx(DensityProvider, { value: "compact", children: children }) })] }) }) }));
+}

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

@@ -0,0 +1 @@
+export { Peek, type PeekProps } from "./Peek.js";

package/dist/primitives/surface/index.js

@@ -0,0 +1,2 @@
+/* Where a view is mounted without losing track of where it came from. */
+export { Peek } from "./Peek.js";

package/dist/primitives/table/CellEditor.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+/**
+ * One cell of a `DataTable` that edits in place: its drawing becomes a button that opens
+ * `editor` in a popover anchored to the cell.
+ *
+ * Internal to the table family: a column asks for it with `DataColumn.edit`.
+ */
+export declare function CellEditor({ label, numeric, editor, children, }: {
+    /** The verb and the column: «Editar vencimiento». Names the button and the popover. */
+    label: string;
+    numeric: boolean;
+    editor: (done: () => void) => ReactNode;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/primitives/table/CellEditor.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn, focusRing } from "../../foundations/variants.js";
+import { Popover } from "../overlay/Popover.js";
+import { Pencil } from "lucide-react";
+import { useEffect, useId, useRef } from "react";
+import { Button as AriaButton, Dialog, DialogTrigger } from "react-aria-components";
+/* ==================================================================== *
+ *  CELL EDITOR — change one value of a list without leaving the list.
+ *
+ *  Context: the salesperson of an invoice, its due date, its stage. Opening the record to
+ *  change one field and coming back is three screens for one value, and the person loses
+ *  the row they were on. Odoo answers it with the editable list; this is the step before it:
+ *  the list stays a list, and ONE cell opens a small popover with the right control —
+ *  a `Picker`, a `Calendar`, a `Select` — anchored to the cell, the way a date picker opens
+ *  its calendar under its field.
+ *
+ *  ── The cell IS the button ──────────────────────────────────────────
+ *
+ *  The whole drawing of the cell is the trigger, not a pencil on its side: the target is
+ *  the value the eye is already on (Fitts), and a column of twelve pencils is noise. The
+ *  pencil only appears where the pointer or the keyboard is — on hover and on visible
+ *  focus — the same rule `RowActions` follows: an affordance without a subject yet is not
+ *  shown. That is also why an editable column must not draw links: they would be a button
+ *  inside a button.
+ *
+ *  ── React Aria's dialog trigger ─────────────────────────────────────
+ *
+ *  `DialogTrigger` + `Popover` + `Dialog`: Escape and a click outside close it, and the
+ *  focus goes back to the cell it came from, so the keyboard continues down the column.
+ *  What commits is the editor's own gesture (choosing a person, pressing a day), and then
+ *  it calls `done`. Closing without that gesture changes nothing — Escape is «cancel».
+ *
+ *  The button's name is the verb plus the value («Editar vencimiento 15/11/2026»): the
+ *  value alone does not say it can be changed, the verb alone does not say what it is.
+ * ==================================================================== */
+/** The first control of the editor gets the focus, unless the editor already placed it
+ *  (a `Calendar` with `autoFocus`). Arriving in a popover with the focus on its frame is one
+ *  extra Tab before the first key does anything. */
+function useFocusFirst(scope) {
+    useEffect(() => {
+        const frame = requestAnimationFrame(() => {
+            const root = scope.current;
+            if (root === null)
+                return;
+            const active = document.activeElement;
+            if (active !== null && active !== root && root.contains(active))
+                return;
+            for (const selector of [
+                "input:not([disabled])",
+                /* A calendar: the day the keyboard is on, not the «previous month» arrow. */
+                '[role="grid"] [tabindex="0"]',
+                "button:not([disabled])",
+                '[tabindex="0"]',
+            ]) {
+                const target = root.querySelector(selector);
+                if (target !== null) {
+                    target.focus();
+                    return;
+                }
+            }
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [scope]);
+}
+function EditorDialog({ label, editor, }) {
+    const ref = useRef(null);
+    useFocusFirst(ref);
+    return (_jsx(Dialog, { ref: ref, "aria-label": label, className: "max-h-[inherit] max-w-sm min-w-56 overflow-auto p-2 outline-0", children: ({ close }) => editor(close) }));
+}
+/**
+ * One cell of a `DataTable` that edits in place: its drawing becomes a button that opens
+ * `editor` in a popover anchored to the cell.
+ *
+ * Internal to the table family: a column asks for it with `DataColumn.edit`.
+ */
+export function CellEditor({ label, numeric, editor, children, }) {
+    const verb = useId();
+    const shown = useId();
+    return (
+    /* The row may open its record on click; changing one cell must not also open it. */
+    _jsx("div", { onClick: (event) => event.stopPropagation(), className: "-mx-1 min-w-0", children: _jsxs(DialogTrigger, { children: [_jsxs(AriaButton, { "aria-labelledby": `${verb} ${shown}`, className: ({ isFocusVisible }) => cn("group/edit flex w-full min-w-0 cursor-pointer items-center gap-1.5 rounded-mark px-1 text-inherit outline-0 transition-colors duration-(--duration-instant) hover:bg-ink/6 pressed:bg-ink/10 aria-expanded:bg-primary/8", numeric ? "flex-row-reverse text-right" : "text-left", focusRing({ isFocusVisible })), children: [_jsx("span", { id: verb, hidden: true, children: label }), _jsx("span", { id: shown, className: "min-w-0 flex-1 truncate", children: children }), _jsx(Pencil, { "aria-hidden": true, strokeWidth: 2, className: "size-(--size-icon-sm) shrink-0 text-muted opacity-0 transition-opacity duration-(--duration-instant) group-hover/edit:opacity-100 group-focus-visible/edit:opacity-100 group-aria-expanded/edit:opacity-100" })] }), _jsx(Popover, { placement: numeric ? "bottom end" : "bottom start", children: _jsx(EditorDialog, { label: label, editor: editor }) })] }) }));
+}