@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/components/record-detail-layout.js

@@ -0,0 +1,233 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Collapsible } from "radix-ui";
+import { ArrowLeft, ChevronDown, ChevronLeft, ChevronRight, LockKeyhole, SearchX } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useFormat } from "../lib/locale.js";
+import { SmartLink, useNavigation } from "../lib/provider.js";
+import { useHotkeys } from "../lib/use-hotkeys.js";
+import { useContainerWidth } from "../lib/use-container-width.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { useComposedRefs } from "../lib/compose-refs.js";
+import { useEdgeFade } from "../lib/use-edge-fade.js";
+import { Button } from "./button.js";
+import { EmptyStateDescription, EmptyStateIcon, emptyStateVariants } from "./empty-state.js";
+import { Skeleton, SkeletonAvatar, SkeletonText } from "./skeleton.js";
+import { Spinner } from "./spinner.js";
+/* ------------------------------------------------------------------ */
+/* Labels & context                                                    */
+/* ------------------------------------------------------------------ */
+const recordLabels = {
+    pager: "{index} of {total}",
+    pagerLabel: "Record navigation",
+    previous: "Previous record",
+    next: "Next record",
+    details: "Details",
+    facts: "Key facts",
+    saving: "Saving…",
+    notFound: "Record not found",
+    notFoundDescription: "It may have been deleted, merged into another record, or the link is out of date.",
+    forbidden: "You don't have access to this record",
+    forbiddenDescription: "Ask an admin of this workspace to share it with you.",
+    loading: "Loading record",
+    resizeAside: "Resize side column",
+};
+/** Below this container width (42rem) the side column moves under the header as collapsed sections. Matches navigation.css. */
+const NARROW = 672;
+const RecordLayoutContext = React.createContext({
+    narrow: false,
+    readOnly: false,
+    asidePosition: "end",
+    resizable: false,
+    asideWidth: 320,
+    minAsideWidth: 260,
+    maxAsideWidth: 520,
+    defaultAsideWidth: 320,
+    setAsideWidth: () => { },
+});
+/**
+ * The drag edge of a side column (WAI-ARIA window splitter: focusable `separator` with
+ * `aria-valuenow`; arrows resize, Shift+arrows in bigger steps, Home/End jump to min/max,
+ * double-click resets). Logical: works in RTL.
+ */
+export const SidePaneHandle = React.forwardRef(function SidePaneHandle({ value, min = 240, max = 560, defaultValue, onValueChange, edge = "start", step = 16, className, onKeyDown, onDoubleClick, ...props }, ref) {
+    const innerRef = React.useRef(null);
+    const composed = useComposedRefs(ref, innerRef);
+    const [dragging, setDragging] = React.useState(false);
+    const clamp = (w) => Math.round(Math.min(max, Math.max(min, w)));
+    const dir = () => (innerRef.current && getComputedStyle(innerRef.current).direction === "rtl" ? -1 : 1);
+    // dx is a visual (screen) movement of the handle; turn it into a width change.
+    const grow = (dx) => (edge === "start" ? -dx : dx) * dir();
+    return (_jsx("div", { ref: composed, role: "separator", "aria-orientation": "vertical", "aria-valuenow": value, "aria-valuemin": min, "aria-valuemax": max, tabIndex: 0, "data-slot": "side-pane-handle", "data-dragging": dragging ? "" : undefined, className: cn("vui-pane-handle group/pane absolute inset-y-0 z-[1] w-2 cursor-col-resize touch-none outline-none", edge === "start" ? "-start-[calc(var(--gap)/2+4px)]" : "-end-[calc(var(--gap)/2+4px)]", className), onPointerDown: (e) => {
+            if (e.button !== 0)
+                return;
+            e.preventDefault();
+            const el = e.currentTarget;
+            el.setPointerCapture?.(e.pointerId);
+            const startX = e.clientX;
+            const startW = value;
+            setDragging(true);
+            const move = (ev) => onValueChange(clamp(startW + grow(ev.clientX - startX)));
+            const up = () => {
+                setDragging(false);
+                el.removeEventListener("pointermove", move);
+                el.removeEventListener("pointerup", up);
+                el.removeEventListener("pointercancel", up);
+            };
+            el.addEventListener("pointermove", move);
+            el.addEventListener("pointerup", up);
+            el.addEventListener("pointercancel", up);
+        }, onKeyDown: (e) => {
+            onKeyDown?.(e);
+            if (e.defaultPrevented)
+                return;
+            const s = e.shiftKey ? step * 4 : step;
+            let next = null;
+            if (e.key === "ArrowLeft")
+                next = value + grow(-s);
+            else if (e.key === "ArrowRight")
+                next = value + grow(s);
+            else if (e.key === "Home")
+                next = min;
+            else if (e.key === "End")
+                next = max;
+            else if (e.key === "Enter" && defaultValue !== undefined)
+                next = defaultValue;
+            if (next === null)
+                return;
+            e.preventDefault();
+            onValueChange(clamp(next));
+        }, onDoubleClick: (e) => {
+            onDoubleClick?.(e);
+            if (defaultValue !== undefined)
+                onValueChange(clamp(defaultValue));
+        }, ...props, children: _jsx("span", { "aria-hidden": true, className: cn("pointer-events-none absolute inset-y-2 start-1/2 w-px -translate-x-1/2 rounded-full bg-transparent transition-[background-color,width] duration-150 rtl:translate-x-1/2", "group-hover/pane:bg-field-border-hover group-focus-visible/pane:w-0.5 group-focus-visible/pane:bg-ring group-data-dragging/pane:w-0.5 group-data-dragging/pane:bg-accent-ink") }) }));
+});
+/**
+ * The "show one record" page: record header (media, title, status, key facts, actions, pager),
+ * a main column (tabs, overview, activity, related lists) and a side column of details.
+ * Below 42rem (672px) of its own width the side column moves under the header and its
+ * sections fold, and the key facts become a horizontal strip. It measures itself, not the
+ * viewport, so it works the same beside an App shell sidebar or in a split view.
+ *
+ * ```tsx
+ * <RecordLayout>
+ *   <RecordHeader media={<Avatar name="Jane Doe" size="xl" />} title="Jane Doe" subtitle="Head of Ops · Acme"
+ *     status={<Badge tone="success">Customer</Badge>} facts={[{ label: "Owner", value: "Meltem Aydın" }]}
+ *     pager={<RecordPager index={3} total={128} prevHref="/contacts/41" nextHref="/contacts/43" />} />
+ *   <RecordMain>{tabs}</RecordMain>
+ *   <RecordAside><RecordAsideSection title="Details"><DescriptionList … /></RecordAsideSection></RecordAside>
+ * </RecordLayout>
+ * ```
+ */
+export const RecordLayout = React.forwardRef(function RecordLayout({ asidePosition = "end", asideWidth: asideWidthProp, defaultAsideWidth = 320, onAsideWidthChange, resizable = false, minAsideWidth = 260, maxAsideWidth = 520, state = "ready", notFound, forbidden, readOnly = false, labels, className, style, children, ...props }, ref) {
+    const t = useLabels("record", recordLabels, labels);
+    const { ref: measureRef, width } = useContainerWidth();
+    const composed = useComposedRefs(ref, measureRef);
+    const [asideWidth, setAsideWidth] = useControllableState({ value: asideWidthProp, defaultValue: defaultAsideWidth, onChange: onAsideWidthChange, name: "RecordLayout" });
+    const narrow = width !== undefined && width < NARROW;
+    const ctx = React.useMemo(() => ({ narrow, readOnly, asidePosition, resizable, asideWidth, minAsideWidth, maxAsideWidth, defaultAsideWidth, setAsideWidth, labels }), [narrow, readOnly, asidePosition, resizable, asideWidth, minAsideWidth, maxAsideWidth, defaultAsideWidth, setAsideWidth, labels]);
+    let content = children;
+    if (state === "loading")
+        content = _jsx(RecordLayoutSkeleton, { label: t("loading") });
+    else if (state === "not-found")
+        content = notFound ?? _jsx(RecordStatePage, { kind: "not-found", title: t("notFound"), description: t("notFoundDescription") });
+    else if (state === "forbidden")
+        content = forbidden ?? _jsx(RecordStatePage, { kind: "forbidden", title: t("forbidden"), description: t("forbiddenDescription") });
+    return (_jsx(RecordLayoutContext.Provider, { value: ctx, children: _jsx("div", { ref: composed, "data-slot": "record-layout", "data-state": state, "data-narrow": narrow ? "" : undefined, className: cn("@container/record w-full min-w-0", className), style: { "--record-aside-w": `${asideWidth}px`, ...style }, ...props, children: _jsx("div", { className: "vui-record-grid", "data-aside": asidePosition, children: content }) }) }));
+});
+/** Full-page state with the page's one h1 (EmptyState titles stop at h2). */
+function RecordStatePage({ kind, title, description }) {
+    const Icon = kind === "forbidden" ? LockKeyhole : SearchX;
+    return (_jsxs("div", { "data-slot": "record-state", "data-kind": kind, className: cn(emptyStateVariants({ size: "lg" }), "[grid-column:1/-1]"), children: [_jsx(EmptyStateIcon, { className: "surface-2 mb-2 text-fg-muted", children: _jsx(Icon, { "aria-hidden": true }) }), _jsx("h1", { className: "font-display max-w-[36ch] text-balance text-[1.75rem] leading-tight text-fg", children: title }), _jsx(EmptyStateDescription, { size: "lg", children: description })] }));
+}
+function RecordLayoutSkeleton({ label }) {
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { role: "status", "aria-label": label, "aria-busy": "true", className: "flex items-center gap-4 [grid-area:header]", children: [_jsx(SkeletonAvatar, { size: "xl" }), _jsxs("div", { className: "grid flex-1 gap-2", children: [_jsx(Skeleton, { className: "h-6 w-56 rounded-ui-sm" }), _jsx(Skeleton, { className: "h-4 w-40 rounded-ui-sm" })] })] }), _jsxs("div", { className: "grid gap-(--gap) [grid-area:main]", children: [_jsx("div", { className: "surface rounded-ui-lg p-(--gap)", children: _jsx(SkeletonText, { lines: 4 }) }), _jsx("div", { className: "surface rounded-ui-lg p-(--gap)", children: _jsx(SkeletonText, { lines: 3 }) })] }), _jsx("div", { className: "grid gap-3 [grid-area:aside]", children: _jsx("div", { className: "surface-2 rounded-ui-lg p-4", children: _jsx(SkeletonText, { lines: 5 }) }) })] }));
+}
+/** The record's header: back link + pager, media, h1, status, subtitle, actions and key facts. */
+export const RecordHeader = React.forwardRef(function RecordHeader({ media, title, subtitle, status, facts, actions, back, pager, saving, size = "md", loading, labels, className, children, ...props }, ref) {
+    const ctx = React.useContext(RecordLayoutContext);
+    const t = useLabels("record", recordLabels, labels ?? ctx.labels);
+    const showActions = actions && !ctx.readOnly;
+    const factsRef = React.useRef(null);
+    useEdgeFade(factsRef, "x", Boolean(facts?.length));
+    return (_jsxs("header", { ref: ref, "data-slot": "record-header", "data-size": size, className: cn("flex min-w-0 flex-col gap-4 [grid-area:header]", className), ...props, children: [back || pager ? (_jsxs("div", { className: "flex min-h-8 items-center justify-between gap-3", children: [back ? (_jsxs(SmartLink, { href: back.href, className: "-ms-0.5 inline-flex w-fit items-center gap-1.5 rounded-ui-sm text-[13px] text-fg-muted transition-colors hover:text-fg focus-ring", children: [_jsx(ArrowLeft, { "aria-hidden": true, className: "size-3.5 rtl:-scale-x-100" }), back.label] })) : (_jsx("span", {})), pager] })) : null, _jsxs("div", { className: "flex flex-wrap items-start gap-x-5 gap-y-4", children: [media ? _jsx("div", { "data-slot": "record-header-media", className: "shrink-0", children: media }) : null, _jsxs("div", { className: "min-w-0 flex-[1_1_16rem] self-center", children: [_jsxs("div", { className: "flex flex-wrap items-center gap-x-3 gap-y-1.5", children: [_jsx("h1", { "aria-busy": loading || undefined, className: cn("font-display min-w-0 text-fg [text-wrap:balance]", size === "md" ? "text-[length:calc(28px*var(--display-scale))] leading-[1.1]" : "text-[length:calc(20px*var(--display-scale))] leading-[1.15]"), children: loading ? _jsx(Skeleton, { className: "inline-block h-[0.8em] w-[min(16rem,55vw)] rounded-ui-sm align-middle" }) : title }), status && !loading ? _jsx("span", { className: "inline-flex items-center gap-2", children: status }) : null, saving ? (_jsxs("span", { role: "status", className: "inline-flex items-center gap-1.5 text-[13px] text-fg-subtle", children: [_jsx(Spinner, { size: "xs" }), " ", t("saving")] })) : null] }), loading ? (_jsx(Skeleton, { className: "mt-2 h-4 w-48 rounded-ui-sm" })) : subtitle ? (_jsx("p", { className: "mt-1 text-[14px] text-fg-muted", children: subtitle })) : null] }), showActions ? _jsx("div", { "data-slot": "record-header-actions", className: "flex flex-wrap items-center gap-2 self-center", children: actions }) : null] }), facts?.length ? (_jsx("div", { ref: factsRef, role: "group", "aria-label": t("facts"), tabIndex: 0, "data-slot": "record-facts", "data-edge-fade": "x", className: "-mx-1 overflow-x-auto scrollbar-none rounded-ui-sm px-1 focus-ring @2xl/record:overflow-visible", children: _jsx("dl", { className: "flex w-max min-w-full items-stretch @2xl/record:w-auto @2xl/record:flex-wrap @2xl/record:gap-y-3", children: facts.map((f, i) => (_jsxs("div", { className: "flex min-w-0 shrink-0 flex-col gap-1 border-s border-line px-5 first:border-s-0 first:ps-0", children: [_jsx("dt", { className: "text-[12px] text-fg-subtle", children: f.label }), _jsx("dd", { className: "tabular text-[14px] font-medium text-fg", children: f.value })] }, i))) }) })) : null, children] }));
+});
+/** "3 of 128" with previous/next buttons and `j` / `k` shortcuts. */
+export const RecordPager = React.forwardRef(function RecordPager({ index, total, prevHref, nextHref, onPrevious, onNext, shortcuts = true, labels, className, ...props }, ref) {
+    const ctx = React.useContext(RecordLayoutContext);
+    const t = useLabels("record", recordLabels, labels ?? ctx.labels);
+    const f = useFormat();
+    const { navigate } = useNavigation();
+    const hasPrev = index > 1 && Boolean(prevHref || onPrevious);
+    const hasNext = index < total && Boolean(nextHref || onNext);
+    const go = (which) => {
+        const href = which === "prev" ? prevHref : nextHref;
+        const cb = which === "prev" ? onPrevious : onNext;
+        if (cb)
+            cb();
+        if (href)
+            navigate(href);
+    };
+    useHotkeys("k", () => go("prev"), { enabled: shortcuts && hasPrev });
+    useHotkeys("j", () => go("next"), { enabled: shortcuts && hasNext });
+    const step = (which) => {
+        const enabled = which === "prev" ? hasPrev : hasNext;
+        const href = which === "prev" ? prevHref : nextHref;
+        const cb = which === "prev" ? onPrevious : onNext;
+        const label = which === "prev" ? t("previous") : t("next");
+        const Icon = which === "prev" ? ChevronLeft : ChevronRight;
+        const common = {
+            "aria-label": label,
+            title: shortcuts ? `${label} (${which === "prev" ? "K" : "J"})` : label,
+            "aria-keyshortcuts": shortcuts ? (which === "prev" ? "k" : "j") : undefined,
+            variant: "ghost",
+            size: "icon-sm",
+        };
+        if (href && enabled && !cb) {
+            return (_jsx(Button, { asChild: true, ...common, children: _jsx(SmartLink, { href: href, children: _jsx(Icon, { "aria-hidden": true, className: "rtl:-scale-x-100" }) }) }));
+        }
+        return (_jsx(Button, { ...common, disabled: !enabled, onClick: () => go(which), children: _jsx(Icon, { "aria-hidden": true, className: "rtl:-scale-x-100" }) }));
+    };
+    return (_jsxs("nav", { ref: ref, "aria-label": t("pagerLabel"), "data-slot": "record-pager", className: cn("inline-flex items-center gap-1", className), ...props, children: [_jsx("span", { className: "tabular me-1 text-[13px] text-fg-muted", children: t("pager", { index: f.number(index), total: f.number(total) }) }), _jsxs("span", { className: "inline-flex items-center rounded-ui-sm border border-line", children: [step("prev"), _jsx("span", { "aria-hidden": true, className: "h-4 w-px bg-line" }), step("next")] })] }));
+});
+/** The main column: tabs, overview, activity, related lists. */
+export const RecordMain = React.forwardRef(function RecordMain({ tabs, className, children, ...props }, ref) {
+    return (_jsxs("div", { ref: ref, "data-slot": "record-main", className: cn("flex min-w-0 flex-col gap-(--gap) [grid-area:main]", className), ...props, children: [tabs ? _jsx("div", { "data-slot": "record-main-tabs", className: "-mb-1", children: tabs }) : null, children] }));
+});
+/** A titled card in the main column: overview, activity, related deals. `<section aria-labelledby>`. */
+export const RecordSection = React.forwardRef(function RecordSection({ title, description, action, padding = "md", className, children, id, ...props }, ref) {
+    const autoId = React.useId();
+    const titleId = `${id ?? `record-section${autoId.replace(/:/g, "")}`}-title`;
+    return (_jsxs("section", { ref: ref, id: id, "aria-labelledby": titleId, "data-slot": "record-section", className: cn("surface overflow-hidden rounded-ui-lg", className), ...props, children: [_jsxs("div", { className: "flex items-start justify-between gap-3 px-(--gap) pt-[calc(var(--gap)*0.8)]", children: [_jsxs("div", { className: "min-w-0", children: [_jsx("h2", { id: titleId, className: "text-[15px] font-semibold text-fg", children: title }), description ? _jsx("p", { className: "mt-0.5 text-[13px] text-fg-muted", children: description }) : null] }), action ? _jsx("div", { className: "-me-1 -mt-1 flex shrink-0 items-center gap-1.5", children: action }) : null] }), _jsx("div", { className: cn(padding === "md" ? "p-(--gap) pt-3" : "pt-3"), children: children })] }));
+});
+/** The side column (`<aside>`): description lists, owners, tags, related records. */
+export const RecordAside = React.forwardRef(function RecordAside({ className, children, labels, ...props }, ref) {
+    const ctx = React.useContext(RecordLayoutContext);
+    const t = useLabels("record", recordLabels, labels ?? ctx.labels);
+    return (_jsxs("aside", { ref: ref, "aria-label": props["aria-label"] ?? t("details"), "data-slot": "record-aside", className: cn("relative flex min-w-0 flex-col gap-3 [grid-area:aside]", className), ...props, children: [ctx.resizable && !ctx.narrow ? (_jsx(SidePaneHandle, { "aria-label": t("resizeAside"), edge: ctx.asidePosition === "end" ? "start" : "end", value: ctx.asideWidth, min: ctx.minAsideWidth, max: ctx.maxAsideWidth, defaultValue: ctx.defaultAsideWidth, onValueChange: ctx.setAsideWidth })) : null, children] }));
+});
+/** A titled block in the side column; folds like an accordion item when space is short. */
+export const RecordAsideSection = React.forwardRef(function RecordAsideSection({ title, action, collapsible = false, defaultOpen = true, open: openProp, onOpenChange, headingLevel = 2, className, children, ...props }, ref) {
+    const { narrow } = React.useContext(RecordLayoutContext);
+    const foldable = collapsible || narrow;
+    const touched = React.useRef(false);
+    const [open, setOpen] = useControllableState({ value: openProp, defaultValue: defaultOpen, onChange: onOpenChange, name: "RecordAsideSection" });
+    // Fold when the layout turns narrow, unfold when it widens again — until the user decides.
+    React.useEffect(() => {
+        if (touched.current || openProp !== undefined)
+            return;
+        setOpen(narrow ? false : defaultOpen);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [narrow]);
+    const autoId = React.useId();
+    const titleId = `record-aside${autoId.replace(/:/g, "")}`;
+    const H = `h${headingLevel}`;
+    const isOpen = foldable ? open : true;
+    return (_jsx(Collapsible.Root, { open: isOpen, onOpenChange: (v) => {
+            touched.current = true;
+            setOpen(v);
+        }, asChild: true, children: _jsxs("section", { ref: ref, "aria-labelledby": titleId, "data-slot": "record-aside-section", "data-state": isOpen ? "open" : "closed", className: cn("surface-2 rounded-ui-lg", className), ...props, children: [_jsxs("div", { className: "flex min-h-11 items-center gap-2 ps-4 pe-2", children: [_jsx(H, { id: titleId, className: "min-w-0 flex-1 text-[13px] font-semibold text-fg", children: foldable ? (_jsxs(Collapsible.Trigger, { className: "group/aside -ms-1.5 flex w-[calc(100%+0.375rem)] items-center gap-1.5 rounded-ui-sm px-1.5 py-1 text-start outline-none focus-ring", children: [_jsx(ChevronDown, { "aria-hidden": true, className: "size-3.5 shrink-0 text-fg-subtle transition-transform duration-200 group-data-[state=closed]/aside:-rotate-90 motion-reduce:transition-none rtl:group-data-[state=closed]/aside:rotate-90" }), _jsx("span", { className: "truncate", children: title })] })) : (_jsx("span", { className: "block truncate py-1", children: title })) }), action ? _jsx("div", { className: "flex shrink-0 items-center gap-1", children: action }) : null] }), _jsx(Collapsible.Content, { className: "ui-collapse", children: _jsx("div", { className: "px-4 pb-4", children: children }) })] }) }));
+});

package/dist/components/record-picker.d.ts

@@ -0,0 +1,199 @@
+import * as React from "react";
+/**
+ * How a picker reads a collection. The kit knows nothing about your API: wrap your fetch
+ * (REST, tRPC, a server action, `queryClient.fetchQuery`) in `search` and `getByIds`.
+ */
+export interface RecordSource<R> {
+    /** Cache key for the collection ("contacts", "companies"). Records are cached per key for the session. */
+    key: string;
+    /** Server search. Fold case and accents server-side too (Postgres `unaccent(lower(...))`). */
+    search: (query: string, ctx: {
+        signal: AbortSignal;
+        cursor?: string;
+        locale: string;
+    }) => Promise<{
+        items: R[];
+        nextCursor?: string;
+    }>;
+    /** Resolve labels for ids you already have (initial values, a record loaded without its relations). */
+    getByIds?: (ids: string[], signal: AbortSignal) => Promise<R[]>;
+    getId: (r: R) => string;
+    getLabel: (r: R) => string;
+    getDescription?: (r: R) => string | undefined;
+    getAvatar?: (r: R) => {
+        src?: string | null;
+        name: string;
+        shape?: "circle" | "square";
+    } | undefined;
+    /** Link to the record: chips and cards become links. */
+    href?: (r: R) => string | undefined;
+}
+export interface ArrayRecordSourceOptions<R> extends Omit<RecordSource<R>, "key" | "search" | "getByIds"> {
+    /** Extra searchable text (email, SKU, city). */
+    getKeywords?: (r: R) => string[];
+    /** Page size. Default 50. */
+    pageSize?: number;
+    /** Fake latency in ms (docs, prototypes). Default 0. */
+    delay?: number;
+}
+/**
+ * A `RecordSource` over an in-memory array, searched with locale folding (İ/ı, accents).
+ * Good for small sets, tests and prototypes; switch to a server `search` later without
+ * touching the picker.
+ */
+export declare function arrayRecordSource<R>(key: string, items: R[], options: ArrayRecordSourceOptions<R>): RecordSource<R>;
+/** Clears the picker's session caches (after a logout, or in tests). Pass a key to clear one collection. */
+export declare function clearRecordPickerCache(key?: string): void;
+declare const recordPickerLabels: {
+    placeholder: string;
+    placeholderMultiple: string;
+    search: string;
+    searching: string;
+    empty: string;
+    noResultsFor: string;
+    create: string;
+    creating: string;
+    browse: string;
+    recent: string;
+    results: string;
+    loadMore: string;
+    unknown: string;
+    max: string;
+    error: string;
+    retry: string;
+    clear: string;
+    add: string;
+    change: string;
+    open: string;
+    remove: string;
+    browseTitle: string;
+    selectCount: string;
+    cancel: string;
+    resolving: string;
+    selectedCount: string;
+};
+export type RecordPickerLabels = typeof recordPickerLabels;
+/** A pinned row at the top of the list ("Assign to me", "Create from template…"). */
+export interface RecordPickerAction<R> {
+    id: string;
+    label: React.ReactNode;
+    /** Plain text for the accessible name when `label` isn't a string. */
+    textValue?: string;
+    icon?: React.ReactNode;
+    /** Hide while searching. Default `true`. */
+    hideWhileSearching?: boolean;
+    onSelect: (api: {
+        select: (r: R) => void;
+        close: () => void;
+        query: string;
+    }) => void;
+}
+/** What `renderTrigger` receives. */
+export interface RecordPickerTriggerContext<R> {
+    selected: R[];
+    /** Selected ids whose records couldn't be found. */
+    unknownIds: string[];
+    open: boolean;
+    disabled: boolean;
+    placeholder: string;
+    getLabel: (r: R) => string;
+}
+export interface RecordPickerRenderState {
+    selected: boolean;
+    disabled: boolean;
+    query: string;
+}
+interface RecordPickerBaseProps<R> {
+    source: RecordSource<R>;
+    /** Custom option row. Default: avatar, label (matches in bold) and description. */
+    renderItem?: (r: R, state: RecordPickerRenderState) => React.ReactNode;
+    /** Records that can't be picked (archived, no permission). Already-selected ones still show. */
+    getDisabled?: (r: R) => boolean;
+    /** Group results under headings ("Customers", "Suppliers"). */
+    getGroup?: (r: R) => string | undefined;
+    /** Inline create: return the new record (it is selected). Shown as "Create “query”". */
+    onCreate?: (query: string) => R | Promise<R>;
+    /** `true` → the built-in browse dialog (search + list + load more). A function renders your own (a Data Table with filters). */
+    browse?: boolean | ((props: {
+        onPick: (records: R[]) => void;
+        selectedIds: string[];
+        multiple: boolean;
+        close: () => void;
+    }) => React.ReactNode);
+    /** Shown above results when the query is empty. Default: the last 5 records picked from this source in the session. `false` hides. */
+    recent?: R[] | false;
+    /** Pinned rows on top of the list. */
+    actions?: RecordPickerAction<R>[];
+    /** Replace what a pick adds (a team → its members). */
+    resolveSelection?: (r: R) => R | R[] | Promise<R | R[]>;
+    /** Records for the initial value, so labels show without a round trip. */
+    selectedRecords?: R[];
+    /** Selected records as chips (default) or cards (record detail pages). */
+    display?: "chip" | "card";
+    /** `"inline"` renders the search list without a trigger (side panels). */
+    mode?: "popover" | "inline";
+    size?: "sm" | "md" | "lg";
+    placeholder?: string;
+    searchPlaceholder?: string;
+    /** Hidden input name(s) for native form posts (multi → repeated inputs). */
+    name?: string;
+    disabled?: boolean;
+    /** Chips become plain links; nothing can change. */
+    readOnly?: boolean;
+    invalid?: boolean;
+    required?: boolean;
+    /** Single: show the × clear button. Default `true` (unless `required`). */
+    clearable?: boolean;
+    /** Full control over the trigger (avatar stacks, a button in a table cell). Must forward ref and props. */
+    renderTrigger?: (ctx: RecordPickerTriggerContext<R>) => React.ReactElement;
+    /** Extra content above the search box (tabs, filters). */
+    header?: React.ReactNode;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    labels?: Partial<RecordPickerLabels>;
+    id?: string;
+    className?: string;
+    /** Class of the popover panel. */
+    contentClassName?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-invalid"?: boolean | "true" | "false";
+}
+export interface RecordPickerSingleProps<R> extends RecordPickerBaseProps<R> {
+    multiple?: false;
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (id: string | null, record: R | null) => void;
+    max?: never;
+}
+export interface RecordPickerMultipleProps<R> extends RecordPickerBaseProps<R> {
+    multiple: true;
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (ids: string[], records: R[]) => void;
+    /** Most records that can be picked. */
+    max?: number;
+}
+export type RecordPickerProps<R> = RecordPickerSingleProps<R> | RecordPickerMultipleProps<R>;
+/**
+ * Link one or many related records from any collection: a contact to a company, a post to its
+ * author, an order to a customer, a task to a project. Async search with debounce, abort and
+ * paging; recent picks; inline create; a browse dialog for big sets; chips or cards; ids → labels
+ * resolution with a skeleton and an "Unknown record" state for deleted records.
+ *
+ * ```tsx
+ * const companies: RecordSource<Company> = {
+ *   key: "companies",
+ *   search: (q, { signal, cursor }) => api.companies.search({ q, cursor }, { signal }),
+ *   getByIds: (ids, signal) => api.companies.byIds(ids, { signal }),
+ *   getId: (c) => c.id, getLabel: (c) => c.name, getDescription: (c) => c.domain,
+ * };
+ * <Field label="Company"><RecordPicker source={companies} value={companyId} onValueChange={setCompanyId} /></Field>
+ * ```
+ */
+export declare const RecordPicker: <R>(props: RecordPickerProps<R> & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.ReactElement;
+export {};