@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/lib/public.js

@@ -0,0 +1,33 @@
+// Public helpers re-exported from the package root. Owned by the foundations group.
+// Component authors: import from these modules directly (`../lib/labels`, `../lib/variants`…).
+export { cn } from "./cn.js";
+// Locale, built-in strings, formatting
+export { LocaleProvider, useLocale, useMessages, useFormat, useText, mergeMessages, directionOf, } from "./locale.js";
+export { useLabels, createLabels, resolveLabels } from "./labels.js";
+export { formatMessage } from "./message-format.js";
+export { en } from "../locales/en.js";
+// Text (search, sort, case, initials, slugs)
+export { foldText, matchText, highlightText, highlightParts, cmdkFilter, compareText, getCollator, upperText, lowerText, initials, slugify, registerTextRules, baseLanguage, } from "./text.js";
+// Hooks
+export { useControllableState, useLatest, useEventCallback, useIsomorphicLayoutEffect } from "./use-controllable-state.js";
+export { composeRefs, useComposedRefs, mergeIds, setRef } from "./compose-refs.js";
+export { useMediaQuery, useBreakpoint, breakpoints } from "./use-media-query.js";
+export { useReducedMotion, useReducedTransparency } from "./use-reduced-motion.js";
+export { useHotkeys, useIsMac, isApplePlatform, parseShortcut, matchesShortcut, shortcutKeys, formatKey, formatShortcut, } from "./use-hotkeys.js";
+export { useHoverIntent } from "./use-hover-intent.js";
+export { useContainerWidth } from "./use-container-width.js";
+// Shared variants & menu model
+export { controlVariants, itemVariants, itemSlots, } from "./variants.js";
+// Theming, portals, layers
+export { ThemeScope, PortalContainer, usePortalContainer, themeAttributes } from "./theme-scope.js";
+export { Layer, LayerProvider, useLayerDepth, layerAttributes } from "./layer.js";
+// App bridge
+export { VamosProvider, useVamos, useLink, useImage, useCan, useNavigation, useMediaAdapter, SmartLink, DefaultLink, DefaultImage, isExternalHref, } from "./provider.js";
+// Async lists (Combobox, Record picker and custom pickers build on it)
+export { useAsyncList } from "./use-async-list.js";
+// Colour parsing, formatting and contrast (Color picker)
+export { parseColor, toHex, formatColor, contrastRatio, contrastLevel, readableOn } from "./color.js";
+// Forms
+export { FieldContext, useFieldContext, useFieldControl, FieldContextReset, focusFirstInvalid } from "./field-context.js";
+// Client islands for server-compatible components
+export { ChipRemoveButton, LocalizedText, LocaleCount } from "./islands.js";

package/dist/lib/sr-name.d.ts

@@ -0,0 +1,18 @@
+import * as React from "react";
+/**
+ * A fuller accessible name for a control whose visible text is a short summary (a calendar event
+ * showing "9:00 Standup" that screen readers should hear as "Standup, Monday, 9:00 to 9:15").
+ *
+ * Use it instead of an `aria-label` that differs from the visible text, which fails WCAG 2.5.3
+ * label-in-name (axe `label-content-name-mismatch`). The name is read from a visually hidden span;
+ * the visible content is hidden from assistive tech so it isn't read twice. Never wrap focusable
+ * content in it (that content would be `aria-hidden`).
+ *
+ * ```tsx
+ * <button><SrName name={describe(event)}>{time} {title}</SrName></button>
+ * ```
+ */
+export declare function SrName({ name, children }: {
+    name: string;
+    children?: React.ReactNode;
+}): React.JSX.Element;

package/dist/lib/sr-name.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A fuller accessible name for a control whose visible text is a short summary (a calendar event
+ * showing "9:00 Standup" that screen readers should hear as "Standup, Monday, 9:00 to 9:15").
+ *
+ * Use it instead of an `aria-label` that differs from the visible text, which fails WCAG 2.5.3
+ * label-in-name (axe `label-content-name-mismatch`). The name is read from a visually hidden span;
+ * the visible content is hidden from assistive tech so it isn't read twice. Never wrap focusable
+ * content in it (that content would be `aria-hidden`).
+ *
+ * ```tsx
+ * <button><SrName name={describe(event)}>{time} {title}</SrName></button>
+ * ```
+ */
+export function SrName({ name, children }) {
+    return (_jsxs(_Fragment, { children: [_jsx("span", { className: "sr-only", children: name }), _jsx("span", { "aria-hidden": true, className: "contents", children: children })] }));
+}

package/dist/lib/text.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Locale-aware text helpers — the single source for search, typeahead, sorting, initials and
+ * slugs in the kit. React-free (works in server components).
+ *
+ * Why: `"İ".toLowerCase()` is `"i̇"` (two code units), `"ı".toUpperCase()` is `"I"`, and people
+ * type "cagri" when they mean "Çağrı". Every function takes a BCP 47 `locale` (default `"en"`);
+ * pass `useLocale().locale` from components, or use the bound `useText()` hook.
+ */
+export interface TextRules {
+    /** Extra per-character folds applied after locale lowercasing (must map 1 char → 1 char). */
+    fold?: Record<string, string>;
+    /** Per-character slug transliteration applied before the generic one (may expand: "ä" → "ae"). */
+    slug?: Record<string, string>;
+    /** Word used for "&" in slugs ("and", "ve", "und"). */
+    and?: string;
+}
+/** Register (or extend) the rules for a language, e.g. `registerTextRules("fr", { and: "et" })`. */
+export declare function registerTextRules(lang: string, r: TextRules): void;
+/** Base language of a BCP 47 tag: `"tr-TR"` → `"tr"`. */
+export declare function baseLanguage(locale?: string): string;
+/**
+ * Folds text for search: locale lowercase + diacritic stripping + locale rules.
+ * The result has **exactly the same length** as the input (1:1 per UTF-16 unit), so indexes
+ * found in the folded string are valid on the original (see `highlightText`).
+ *
+ * ```ts
+ * foldText("İSTANBUL", "tr"); // "istanbul"
+ * foldText("Çağrı Işık", "tr"); // "cagri isik"
+ * ```
+ */
+export declare function foldText(s: string, locale?: string): string;
+/**
+ * `true` when every word of `query` occurs in `text` (order-independent, folded).
+ * An empty query matches everything.
+ *
+ * ```ts
+ * matchText("Çağrı Yılmaz", "yilmaz cag", "tr"); // true
+ * ```
+ */
+export declare function matchText(text: string, query: string, locale?: string): boolean;
+/**
+ * Match ranges `[start, end)` of every query word in `text`, sorted and merged. Indexes are
+ * valid on the original string because folding preserves length.
+ */
+export declare function highlightText(text: string, query: string, locale?: string): Array<[start: number, end: number]>;
+/**
+ * `text` split into matched / unmatched parts, ready to render:
+ *
+ * ```tsx
+ * {highlightParts(label, query, locale).map((p, i) => (p.match ? <mark key={i}>{p.text}</mark> : p.text))}
+ * ```
+ */
+export declare function highlightParts(text: string, query: string, locale?: string): Array<{
+    text: string;
+    match: boolean;
+}>;
+/**
+ * A score function for cmdk's `filter` prop (0 = hidden, 1 = best):
+ * exact > prefix > word start > contains > keyword match. Every query word must match.
+ *
+ * ```tsx
+ * <Command filter={cmdkFilter(locale)}>
+ * ```
+ */
+export declare function cmdkFilter(locale?: string): (value: string, search: string, keywords?: string[]) => number;
+/** Cached `Intl.Collator(locale, { sensitivity: "base", numeric: true })`. */
+export declare function getCollator(locale?: string, options?: Intl.CollatorOptions): Intl.Collator;
+/**
+ * A locale-aware comparator for `Array.prototype.sort`: "Çiçek" sorts after "Cem" in Turkish,
+ * "item 10" after "item 9".
+ */
+export declare function compareText(locale?: string, options?: Intl.CollatorOptions): (a: string, b: string) => number;
+/** `toLocaleUpperCase` with the right language (tr: "i" → "İ"). Use instead of CSS `text-transform`. */
+export declare const upperText: (s: string, locale?: string) => string;
+/** `toLocaleLowerCase` with the right language (tr: "I" → "ı"). */
+export declare const lowerText: (s: string, locale?: string) => string;
+/**
+ * Initials for avatars: first letter of the first and last word, uppercased with the locale.
+ *
+ * ```ts
+ * initials("ilker şahin", "tr"); // "İŞ"
+ * initials("Ada Lovelace"); // "AL"
+ * ```
+ */
+export declare function initials(name: string, locale?: string, max?: 1 | 2): string;
+export interface SlugifyOptions {
+    locale?: string;
+    /** Default 80. Cut at a separator when possible. */
+    maxLength?: number;
+    separator?: "-" | "_";
+}
+/**
+ * URL slug with locale transliteration.
+ *
+ * ```ts
+ * slugify("Çağrı Merkezi & Destek", { locale: "tr" }); // "cagri-merkezi-ve-destek"
+ * slugify("Größe über alles", { locale: "de" }); // "groesse-ueber-alles"
+ * ```
+ */
+export declare function slugify(s: string, opts?: SlugifyOptions): string;

package/dist/lib/text.js

@@ -0,0 +1,233 @@
+/**
+ * Locale-aware text helpers — the single source for search, typeahead, sorting, initials and
+ * slugs in the kit. React-free (works in server components).
+ *
+ * Why: `"İ".toLowerCase()` is `"i̇"` (two code units), `"ı".toUpperCase()` is `"I"`, and people
+ * type "cagri" when they mean "Çağrı". Every function takes a BCP 47 `locale` (default `"en"`);
+ * pass `useLocale().locale` from components, or use the bound `useText()` hook.
+ */
+/** Folds that apply in every locale (characters without a Unicode decomposition). */
+const GENERIC_FOLD = { ı: "i", ø: "o", ł: "l", đ: "d", ħ: "h", ŧ: "t", ŀ: "l" };
+const GENERIC_SLUG = { ß: "ss", æ: "ae", œ: "oe", ø: "o", ł: "l", đ: "d", ð: "d", þ: "th", ı: "i", ħ: "h" };
+const rules = new Map([
+    ["en", { and: "and" }],
+    // Turkish: dotted/dotless i are handled by toLocaleLowerCase("tr"); the rest decompose (ç ğ ş ö ü).
+    ["tr", { and: "ve" }],
+    ["de", { and: "und", slug: { ä: "ae", ö: "oe", ü: "ue", ß: "ss" } }],
+    ["az", { and: "və", slug: { ə: "e" }, fold: { ə: "e" } }],
+]);
+const foldCache = new Map();
+/** Register (or extend) the rules for a language, e.g. `registerTextRules("fr", { and: "et" })`. */
+export function registerTextRules(lang, r) {
+    const key = lang.toLowerCase();
+    const prev = rules.get(key) ?? {};
+    rules.set(key, { ...prev, ...r, fold: { ...prev.fold, ...r.fold }, slug: { ...prev.slug, ...r.slug } });
+    foldCache.delete(key);
+}
+/** Base language of a BCP 47 tag: `"tr-TR"` → `"tr"`. */
+export function baseLanguage(locale) {
+    return (locale || "en").split(/[-_]/)[0].toLowerCase();
+}
+const MARKS = /[\u0300-\u036f]/g;
+function foldChar(c, lang, r) {
+    let lower = c.toLocaleLowerCase(lang);
+    if (lower.length !== 1) {
+        // e.g. "İ" → "i̇" outside Turkish: drop the combining mark, keep 1:1 length.
+        const stripped = lower.normalize("NFD").replace(MARKS, "");
+        lower = stripped.length === 1 ? stripped : c;
+    }
+    const custom = r?.fold?.[lower] ?? GENERIC_FOLD[lower];
+    if (custom)
+        return custom;
+    const base = lower.normalize("NFD").replace(MARKS, "");
+    return base.length === 1 ? base : lower;
+}
+/**
+ * Folds text for search: locale lowercase + diacritic stripping + locale rules.
+ * The result has **exactly the same length** as the input (1:1 per UTF-16 unit), so indexes
+ * found in the folded string are valid on the original (see `highlightText`).
+ *
+ * ```ts
+ * foldText("İSTANBUL", "tr"); // "istanbul"
+ * foldText("Çağrı Işık", "tr"); // "cagri isik"
+ * ```
+ */
+export function foldText(s, locale) {
+    const lang = baseLanguage(locale);
+    const r = rules.get(lang);
+    let cache = foldCache.get(lang);
+    if (!cache)
+        foldCache.set(lang, (cache = new Map()));
+    let out = "";
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        const code = c.charCodeAt(0);
+        // Surrogate halves (emoji etc.) and plain ASCII lowercase/digits pass through.
+        if ((code >= 0xd800 && code <= 0xdfff) || (code >= 0x61 && code <= 0x7a) || (code >= 0x30 && code <= 0x39) || code === 0x20) {
+            out += c;
+            continue;
+        }
+        let f = cache.get(c);
+        if (f === undefined)
+            cache.set(c, (f = foldChar(c, lang, r)));
+        out += f;
+    }
+    return out;
+}
+const words = (q) => q.split(/\s+/).filter(Boolean);
+/**
+ * `true` when every word of `query` occurs in `text` (order-independent, folded).
+ * An empty query matches everything.
+ *
+ * ```ts
+ * matchText("Çağrı Yılmaz", "yilmaz cag", "tr"); // true
+ * ```
+ */
+export function matchText(text, query, locale) {
+    const t = foldText(text, locale);
+    return words(foldText(query, locale)).every((w) => t.includes(w));
+}
+/**
+ * Match ranges `[start, end)` of every query word in `text`, sorted and merged. Indexes are
+ * valid on the original string because folding preserves length.
+ */
+export function highlightText(text, query, locale) {
+    const t = foldText(text, locale);
+    const ranges = [];
+    for (const w of words(foldText(query, locale))) {
+        let from = 0;
+        for (let i = t.indexOf(w, from); i !== -1; i = t.indexOf(w, from)) {
+            ranges.push([i, i + w.length]);
+            from = i + w.length;
+        }
+    }
+    ranges.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    const merged = [];
+    for (const r of ranges) {
+        const last = merged[merged.length - 1];
+        if (last && r[0] <= last[1])
+            last[1] = Math.max(last[1], r[1]);
+        else
+            merged.push([r[0], r[1]]);
+    }
+    return merged;
+}
+/**
+ * `text` split into matched / unmatched parts, ready to render:
+ *
+ * ```tsx
+ * {highlightParts(label, query, locale).map((p, i) => (p.match ? <mark key={i}>{p.text}</mark> : p.text))}
+ * ```
+ */
+export function highlightParts(text, query, locale) {
+    const out = [];
+    let pos = 0;
+    for (const [s, e] of highlightText(text, query, locale)) {
+        if (s > pos)
+            out.push({ text: text.slice(pos, s), match: false });
+        out.push({ text: text.slice(s, e), match: true });
+        pos = e;
+    }
+    if (pos < text.length || out.length === 0)
+        out.push({ text: text.slice(pos), match: false });
+    return out;
+}
+/**
+ * A score function for cmdk's `filter` prop (0 = hidden, 1 = best):
+ * exact > prefix > word start > contains > keyword match. Every query word must match.
+ *
+ * ```tsx
+ * <Command filter={cmdkFilter(locale)}>
+ * ```
+ */
+export function cmdkFilter(locale) {
+    return (value, search, keywords) => {
+        const q = foldText(search.trim(), locale);
+        if (!q)
+            return 1;
+        const v = foldText(value, locale);
+        if (v === q)
+            return 1;
+        if (v.startsWith(q))
+            return 0.9;
+        const qs = words(q);
+        const vWords = words(v.replace(/[^\p{L}\p{N}\s]+/gu, " "));
+        if (qs.every((w) => vWords.some((vw) => vw.startsWith(w))))
+            return 0.75;
+        if (qs.every((w) => v.includes(w)))
+            return 0.5;
+        const k = foldText((keywords ?? []).join(" "), locale);
+        if (k && qs.every((w) => v.includes(w) || k.includes(w)))
+            return 0.3;
+        return 0;
+    };
+}
+const collators = new Map();
+/** Cached `Intl.Collator(locale, { sensitivity: "base", numeric: true })`. */
+export function getCollator(locale = "en", options) {
+    const key = locale + (options ? JSON.stringify(options) : "");
+    let c = collators.get(key);
+    if (!c)
+        collators.set(key, (c = new Intl.Collator(locale, { sensitivity: "base", numeric: true, ...options })));
+    return c;
+}
+/**
+ * A locale-aware comparator for `Array.prototype.sort`: "Çiçek" sorts after "Cem" in Turkish,
+ * "item 10" after "item 9".
+ */
+export function compareText(locale, options) {
+    return getCollator(locale, options).compare;
+}
+/** `toLocaleUpperCase` with the right language (tr: "i" → "İ"). Use instead of CSS `text-transform`. */
+export const upperText = (s, locale) => s.toLocaleUpperCase(baseLanguage(locale));
+/** `toLocaleLowerCase` with the right language (tr: "I" → "ı"). */
+export const lowerText = (s, locale) => s.toLocaleLowerCase(baseLanguage(locale));
+/**
+ * Initials for avatars: first letter of the first and last word, uppercased with the locale.
+ *
+ * ```ts
+ * initials("ilker şahin", "tr"); // "İŞ"
+ * initials("Ada Lovelace"); // "AL"
+ * ```
+ */
+export function initials(name, locale, max = 2) {
+    const parts = name
+        .replace(/@.*$/, "")
+        .split(/[\s._-]+/)
+        .map((w) => Array.from(w).find((ch) => /\p{L}|\p{N}/u.test(ch)))
+        .filter((ch) => Boolean(ch));
+    if (parts.length === 0)
+        return "";
+    const picked = max === 1 || parts.length === 1 ? [parts[0]] : [parts[0], parts[parts.length - 1]];
+    return upperText(picked.join(""), locale);
+}
+/**
+ * URL slug with locale transliteration.
+ *
+ * ```ts
+ * slugify("Çağrı Merkezi & Destek", { locale: "tr" }); // "cagri-merkezi-ve-destek"
+ * slugify("Größe über alles", { locale: "de" }); // "groesse-ueber-alles"
+ * ```
+ */
+export function slugify(s, opts = {}) {
+    const { locale, maxLength = 80, separator = "-" } = opts;
+    const lang = baseLanguage(locale);
+    const r = rules.get(lang);
+    const lower = s.toLocaleLowerCase(lang);
+    let out = "";
+    for (const ch of lower)
+        out += r?.slug?.[ch] ?? GENERIC_SLUG[ch] ?? ch;
+    out = out
+        .normalize("NFD")
+        .replace(MARKS, "")
+        .replace(/&/g, ` ${r?.and ?? "and"} `)
+        .replace(/['’`]/g, "")
+        .replace(/[^a-z0-9]+/g, separator)
+        .replace(new RegExp(`^\\${separator}+|\\${separator}+$`, "g"), "");
+    if (out.length > maxLength) {
+        const cut = out.slice(0, maxLength);
+        const at = cut.lastIndexOf(separator);
+        out = (at > maxLength * 0.5 ? cut.slice(0, at) : cut).replace(new RegExp(`\\${separator}+$`), "");
+    }
+    return out;
+}

package/dist/lib/theme-scope.d.ts

@@ -0,0 +1,58 @@
+import * as React from "react";
+/** The five theme axes (plus direction) that can be set on any subtree. */
+export interface ThemeAxes {
+    /** `"light"` | `"dark"` → class. */
+    theme?: "light" | "dark";
+    /** → `data-material`. */
+    material?: "glass" | "solid";
+    /** → `data-accent` (lime, ocean, ember, rose, graphite or your own). */
+    accent?: string;
+    /** → `data-density`. */
+    density?: "comfortable" | "compact" | "spacious";
+    /** → `data-font` (editorial, grotesk, corporate, system or your own preset). */
+    font?: string;
+    /** → `dir` + Radix DirectionProvider. */
+    dir?: "ltr" | "rtl";
+    /** → `data-glass-quality="low"` disables blur for low-power devices. */
+    glassQuality?: "high" | "low";
+}
+/**
+ * The class/attributes that apply theme axes to an element — usable in server components:
+ *
+ * ```tsx
+ * <section {...themeAttributes({ theme: "dark", accent: "ember" })}>…</section>
+ * ```
+ */
+export declare function themeAttributes(axes: ThemeAxes): {
+    className?: string;
+} & Record<`data-${string}` | "dir", string | undefined>;
+/**
+ * The element overlays should portal into, or `undefined` for `document.body`.
+ * Pass it to every Radix `Portal`: `<Popover.Portal container={usePortalContainer()}>`.
+ */
+export declare function usePortalContainer(): HTMLElement | undefined;
+/** Makes `container` the portal target for every kit overlay below it. */
+export declare function PortalContainer({ container, children }: {
+    container: HTMLElement | null;
+    children: React.ReactNode;
+}): React.JSX.Element;
+export interface ThemeScopeProps extends ThemeAxes, Omit<React.HTMLAttributes<HTMLDivElement>, "dir"> {
+    /** Merge onto the single child instead of rendering a `<div>`. */
+    asChild?: boolean;
+    /** Overlays opened inside portal into this scope so they keep its theme. Default `true`. */
+    portal?: boolean;
+}
+/**
+ * Applies theme axes to a subtree and keeps overlays inside it. Without it, Radix portals to
+ * `body` and a popover inside a dark preview opens in the light page theme.
+ *
+ * ```tsx
+ * <ThemeScope theme="dark" material="glass" accent="ocean" className="rounded-ui-lg p-6">
+ *   <Select … />   // its listbox portals into the scope → dark + glass + ocean
+ * </ThemeScope>
+ * ```
+ *
+ * The scope element must not use `transform`, `filter`, `backdrop-filter` or `contain`, because
+ * those turn it into the containing block for the fixed-position overlays inside it.
+ */
+export declare const ThemeScope: React.ForwardRefExoticComponent<ThemeScopeProps & React.RefAttributes<HTMLDivElement>>;

package/dist/lib/theme-scope.js

@@ -0,0 +1,59 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Direction, Slot } from "radix-ui";
+import { cn } from "./cn.js";
+import { useComposedRefs } from "./compose-refs.js";
+/**
+ * The class/attributes that apply theme axes to an element — usable in server components:
+ *
+ * ```tsx
+ * <section {...themeAttributes({ theme: "dark", accent: "ember" })}>…</section>
+ * ```
+ */
+export function themeAttributes(axes) {
+    return {
+        className: axes.theme,
+        "data-material": axes.material,
+        "data-accent": axes.accent,
+        "data-density": axes.density,
+        "data-font": axes.font,
+        "data-glass-quality": axes.glassQuality === "low" ? "low" : undefined,
+        dir: axes.dir,
+    };
+}
+const PortalContainerContext = React.createContext(null);
+/**
+ * The element overlays should portal into, or `undefined` for `document.body`.
+ * Pass it to every Radix `Portal`: `<Popover.Portal container={usePortalContainer()}>`.
+ */
+export function usePortalContainer() {
+    return React.useContext(PortalContainerContext) ?? undefined;
+}
+/** Makes `container` the portal target for every kit overlay below it. */
+export function PortalContainer({ container, children }) {
+    return _jsx(PortalContainerContext.Provider, { value: container, children: children });
+}
+/**
+ * Applies theme axes to a subtree and keeps overlays inside it. Without it, Radix portals to
+ * `body` and a popover inside a dark preview opens in the light page theme.
+ *
+ * ```tsx
+ * <ThemeScope theme="dark" material="glass" accent="ocean" className="rounded-ui-lg p-6">
+ *   <Select … />   // its listbox portals into the scope → dark + glass + ocean
+ * </ThemeScope>
+ * ```
+ *
+ * The scope element must not use `transform`, `filter`, `backdrop-filter` or `contain`, because
+ * those turn it into the containing block for the fixed-position overlays inside it.
+ */
+export const ThemeScope = React.forwardRef(function ThemeScope({ theme, material, accent, density, font, dir, glassQuality, asChild, portal = true, className, children, ...props }, ref) {
+    const [node, setNode] = React.useState(null);
+    const composed = useComposedRefs(ref, setNode);
+    const { className: themeClass, ...attrs } = themeAttributes({ theme, material, accent, density, font, dir, glassQuality });
+    const Comp = asChild ? Slot.Root : "div";
+    let content = (_jsx(Comp, { ref: composed, "data-slot": "theme-scope", className: cn(themeClass, className), ...attrs, ...props, children: children }));
+    if (dir)
+        content = _jsx(Direction.Provider, { dir: dir, children: content });
+    return portal ? _jsx(PortalContainer, { container: node, children: content }) : content;
+});

package/dist/lib/use-async-list.d.ts

@@ -0,0 +1,60 @@
+/** One page of results with an optional cursor for the next page (`null`/absent = last page). */
+export interface AsyncPage<T> {
+    items: T[];
+    cursor?: string | null;
+}
+/**
+ * Loads items for a query. Return an array (single page) or `{ items, cursor }` for paging.
+ * Always pass `signal` to `fetch` so superseded requests are cancelled.
+ */
+export type AsyncLoader<T> = (query: string, signal: AbortSignal, cursor?: string) => Promise<T[] | AsyncPage<T>>;
+export interface UseAsyncListOptions<T> {
+    /** The loader. When absent the hook is idle and returns no items. */
+    load?: AsyncLoader<T>;
+    /** Current query; every change (debounced) starts a new first-page request. */
+    query: string;
+    /** ms to wait after the last query change. Default 200. The first request is not delayed. */
+    debounce?: number;
+    /** Set `false` to pause (e.g. while a popover is closed). Default `true`. */
+    enabled?: boolean;
+    /** Cache results per query for the lifetime of the component. Default `true`. */
+    cache?: boolean;
+    /** Don't load below this many characters (returns an empty, idle list). Default 0. */
+    minQueryLength?: number;
+}
+export interface AsyncListState<T> {
+    items: T[];
+    /** First page in flight (including the debounce wait). */
+    loading: boolean;
+    /** A next page is in flight. */
+    loadingMore: boolean;
+    /** The last error (cleared on the next successful request). */
+    error: unknown;
+    /** A cursor for another page exists. */
+    hasMore: boolean;
+    /** The query the current `items` belong to. */
+    loadedQuery: string | null;
+    /** Fetch the next page (no-op without a cursor or while loading). */
+    loadMore: () => void;
+    /** Drop the cache for the current query and load it again. */
+    reload: () => void;
+}
+/**
+ * Debounced, abortable, paged loading for search lists: Combobox, Tag input suggestions,
+ * record and user pickers.
+ *
+ * ```tsx
+ * const list = useAsyncList({
+ *   query,
+ *   load: async (q, signal, cursor) => {
+ *     const res = await fetch(`/api/contacts?q=${encodeURIComponent(q)}&after=${cursor ?? ""}`, { signal });
+ *     return res.json(); // { items, cursor }
+ *   },
+ * });
+ * list.items; list.loading; list.loadMore();
+ * ```
+ *
+ * - Typing fast only sends the last query; a new query aborts the request in flight.
+ * - Results are cached per query, so deleting a character shows the earlier list instantly.
+ */
+export declare function useAsyncList<T>({ load, query, debounce, enabled, cache, minQueryLength }: UseAsyncListOptions<T>): AsyncListState<T>;