@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/components/tabs.js

@@ -0,0 +1,173 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Tabs as RadixTabs } from "radix-ui";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.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 { useLink, useNavigation } from "../lib/provider.js";
+import { Badge } from "./badge.js";
+/* ------------------------------------------------------------------ */
+/* Variants (shared by Radix tabs and link tabs)                       */
+/* ------------------------------------------------------------------ */
+export const tabsListVariants = cva("relative flex min-w-max", {
+    variants: {
+        variant: {
+            /** Pages and records: hairline rule with an accent underline on the selected tab. */
+            underline: "gap-5 border-b border-line data-[orientation=vertical]:min-w-0 data-[orientation=vertical]:flex-col data-[orientation=vertical]:gap-0.5 data-[orientation=vertical]:border-b-0 data-[orientation=vertical]:border-s",
+            /** Status filters: quiet pills. */
+            pill: "gap-1 data-[orientation=vertical]:min-w-0 data-[orientation=vertical]:flex-col",
+            /** 2–4 option view switch (List / Grid). */
+            segmented: "inline-flex w-max gap-0.5 rounded-ui border border-line bg-surface-2 p-0.5 data-[orientation=vertical]:flex-col",
+        },
+        fill: { true: "w-full min-w-0 [&>*]:flex-1" },
+    },
+    defaultVariants: { variant: "underline" },
+});
+export const tabsTriggerVariants = cva([
+    "group/tab relative inline-flex shrink-0 select-none items-center gap-2 whitespace-nowrap font-medium text-fg-muted outline-none",
+    "transition-[color,background-color,box-shadow] duration-150 focus-ring",
+    "hover:text-fg data-selected:text-fg",
+    "disabled:pointer-events-none disabled:opacity-45 aria-disabled:pointer-events-none aria-disabled:opacity-45",
+    "[&_svg]:shrink-0",
+], {
+    variants: {
+        variant: {
+            underline: [
+                "justify-center rounded-ui-sm px-0.5 focus-visible:outline-offset-0",
+                // indicator: a 2px accent rule that grows in from the centre
+                "after:pointer-events-none after:absolute after:inset-x-0 after:-bottom-px after:h-0.5 after:rounded-full after:bg-accent-ink",
+                "after:origin-center after:scale-x-0 after:transition-transform after:duration-200 motion-reduce:after:transition-none data-selected:after:scale-x-100",
+                // vertical: indicator on the start edge
+                "data-[orientation=vertical]:justify-start data-[orientation=vertical]:px-3 data-[orientation=vertical]:hover:bg-hover",
+                "data-[orientation=vertical]:after:inset-x-auto data-[orientation=vertical]:after:inset-y-1.5 data-[orientation=vertical]:after:-start-px data-[orientation=vertical]:after:bottom-auto",
+                "data-[orientation=vertical]:after:h-auto data-[orientation=vertical]:after:w-0.5 data-[orientation=vertical]:after:scale-x-100 data-[orientation=vertical]:after:scale-y-0 data-[orientation=vertical]:data-selected:after:scale-y-100",
+            ],
+            pill: "justify-center rounded-full px-3 hover:bg-hover data-selected:bg-selected data-[orientation=vertical]:justify-start data-[orientation=vertical]:rounded-ui-sm",
+            segmented: "justify-center rounded-[calc(var(--radius)-3px)] px-3 data-selected:bg-surface data-selected:shadow-[0_1px_2px_rgb(0_0_0/0.1),0_0_0_1px_var(--line)] glass:data-selected:bg-field",
+        },
+        size: { sm: "text-[13px] [&_svg]:size-3.5", md: "text-sm [&_svg]:size-4" },
+    },
+    compoundVariants: [
+        { variant: "underline", size: "sm", className: "h-9" },
+        { variant: "underline", size: "md", className: "h-11" },
+        { variant: "pill", size: "sm", className: "h-7" },
+        { variant: "pill", size: "md", className: "h-8" },
+        { variant: "segmented", size: "sm", className: "h-[calc(var(--control-h)-0.75rem)]" },
+        { variant: "segmented", size: "md", className: "h-[calc(var(--control-h)-0.375rem)]" },
+    ],
+    defaultVariants: { variant: "underline", size: "md" },
+});
+const TabsContext = React.createContext({ value: "", orientation: "horizontal" });
+const TabsListContext = React.createContext({ variant: "underline", size: "md" });
+/**
+ * Switches between views of the same context (WAI-ARIA Tabs: arrows, Home/End).
+ * Inactive panels unmount by default; pass `forceMount` on a `TabsContent` to keep it.
+ *
+ * ```tsx
+ * <Tabs defaultValue="overview">
+ *   <TabsList>
+ *     <TabsTrigger value="overview">Overview</TabsTrigger>
+ *     <TabsTrigger value="deals" count={4}>Deals</TabsTrigger>
+ *   </TabsList>
+ *   <TabsContent value="overview">…</TabsContent>
+ * </Tabs>
+ * ```
+ *
+ * `activationMode="manual"` for heavy panels (focus moves with arrows, Enter/Space selects).
+ * For route-based tabs use `TabsLinkList` — that is navigation, not the Tabs pattern.
+ */
+export const Tabs = React.forwardRef(function Tabs({ value: valueProp, defaultValue, onValueChange, orientation = "horizontal", className, ...props }, ref) {
+    const [value, setValue] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? "", onChange: onValueChange, name: "Tabs" });
+    const ctx = React.useMemo(() => ({ value, orientation }), [value, orientation]);
+    return (_jsx(TabsContext.Provider, { value: ctx, children: _jsx(RadixTabs.Root, { ref: ref, "data-slot": "tabs", value: value, onValueChange: setValue, orientation: orientation, className: cn("flex flex-col gap-4 data-[orientation=vertical]:flex-row data-[orientation=vertical]:gap-6", className), ...props }) }));
+});
+/** The row (or column) of tab triggers. */
+export const TabsList = React.forwardRef(function TabsList({ variant = "underline", size = "md", fill, overflow = "scroll", className, children, ...props }, ref) {
+    const { value, orientation } = React.useContext(TabsContext);
+    const scrollRef = React.useRef(null);
+    const scrolls = overflow === "scroll" && orientation === "horizontal" && !fill;
+    useEdgeFade(scrollRef, "x", scrolls);
+    // Keep the selected tab visible when it changes (or on mount).
+    React.useEffect(() => {
+        const scroller = scrollRef.current;
+        if (!scrolls || !scroller)
+            return;
+        const active = scroller.querySelector("[data-selected]");
+        if (!active)
+            return;
+        const s = scroller.getBoundingClientRect();
+        const a = active.getBoundingClientRect();
+        if (a.left < s.left || a.right > s.right) {
+            scroller.scrollTo?.({ left: scroller.scrollLeft + (a.left - s.left) - s.width / 2 + a.width / 2, behavior: "smooth" });
+        }
+    }, [value, scrolls]);
+    const ctx = React.useMemo(() => ({ variant, size }), [variant, size]);
+    const list = (_jsx(RadixTabs.List, { ref: ref, "data-slot": "tabs-list", "data-variant": variant, className: cn(tabsListVariants({ variant, fill }), className), ...props, children: children }));
+    return (_jsx(TabsListContext.Provider, { value: ctx, children: scrolls ? (_jsx("div", { ref: scrollRef, "data-slot": "tabs-scroller", "data-edge-fade": "x", className: "min-w-0 scrollbar-none overflow-x-auto overscroll-x-contain", children: list })) : (list) }));
+});
+/** One tab. `value` must match a `TabsContent`. */
+export const TabsTrigger = React.forwardRef(function TabsTrigger({ value, icon, count, badgeTone, className, children, ...props }, ref) {
+    const { variant, size } = React.useContext(TabsListContext);
+    const selected = React.useContext(TabsContext).value === value;
+    // Tabs used as a filter (no TabsContent) would point aria-controls at a panel that never
+    // exists — an invalid ARIA reference. Drop it when the selected tab has no panel in the DOM.
+    const innerRef = React.useRef(null);
+    const composedRef = useComposedRefs(ref, innerRef);
+    const controlsId = React.useRef(null);
+    const [noPanel, setNoPanel] = React.useState(false);
+    React.useEffect(() => {
+        const el = innerRef.current;
+        if (!el)
+            return;
+        controlsId.current ??= el.getAttribute("aria-controls");
+        if (!selected)
+            return;
+        const id = controlsId.current;
+        setNoPanel(!!id && !el.ownerDocument.getElementById(id));
+    }, [selected]);
+    return (_jsx(RadixTabs.Trigger, { ref: composedRef, value: value, "data-slot": "tabs-trigger", "data-selected": selected ? "" : undefined, className: cn(tabsTriggerVariants({ variant, size }), className), ...props, ...(noPanel && props["aria-controls"] === undefined ? { "aria-controls": undefined } : {}), children: _jsx(TabContent, { icon: icon, count: count, badgeTone: badgeTone ?? (selected && variant !== "underline" ? "accent" : undefined), children: children }) }));
+});
+function TabContent({ icon, count, badgeTone, children }) {
+    return (_jsxs(_Fragment, { children: [icon ? (_jsx("span", { "aria-hidden": true, className: "inline-flex text-fg-subtle transition-colors group-hover/tab:text-fg-muted group-data-selected/tab:text-current", children: icon })) : null, _jsx("span", { className: "truncate", children: children }), count !== undefined ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "sr-only", children: ", " }), _jsx(Badge, { count: count, tone: badgeTone ?? "neutral", className: "-me-0.5" })] })) : null] }));
+}
+/** The panel for one tab. Unmounted while inactive unless `forceMount`. */
+export const TabsContent = React.forwardRef(function TabsContent({ className, ...props }, ref) {
+    return _jsx(RadixTabs.Content, { ref: ref, "data-slot": "tabs-content", className: cn("min-w-0 flex-1 rounded-ui outline-none focus-ring", className), ...props });
+});
+/**
+ * Route-based tabs: a `<nav>` of links with `aria-current="page"` on the active one. Links use the
+ * app's router `Link` from `VamosProvider`, and the active tab is derived from `currentPath`
+ * unless a `TabsLink` sets `active`.
+ *
+ * ```tsx
+ * <TabsLinkList aria-label="Contact sections">
+ *   <TabsLink href="/contacts/42" exact>Overview</TabsLink>
+ *   <TabsLink href="/contacts/42/deals" count={4}>Deals</TabsLink>
+ * </TabsLinkList>
+ * ```
+ */
+export const TabsLinkList = React.forwardRef(function TabsLinkList({ variant = "underline", size = "md", fill, orientation = "horizontal", overflow = "scroll", className, children, ...props }, ref) {
+    const scrollRef = React.useRef(null);
+    const composed = useComposedRefs(ref, scrollRef);
+    const scrolls = overflow === "scroll" && orientation === "horizontal" && !fill;
+    useEdgeFade(scrollRef, "x", scrolls);
+    React.useEffect(() => {
+        const el = scrollRef.current;
+        if (!scrolls || !el)
+            return;
+        el.querySelector("[aria-current=page]")?.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+    }, [scrolls]);
+    const ctx = React.useMemo(() => ({ variant, size }), [variant, size]);
+    return (_jsx(TabsListContext.Provider, { value: ctx, children: _jsx("nav", { ref: composed, "data-slot": "tabs-link-list", "data-edge-fade": scrolls ? "x" : undefined, className: cn(scrolls && "min-w-0 scrollbar-none overflow-x-auto overscroll-x-contain", className), ...props, children: _jsx("div", { "data-orientation": orientation, "data-variant": variant, className: tabsListVariants({ variant, fill }), children: React.Children.map(children, (child) => React.isValidElement(child) ? React.cloneElement(child, { "data-orientation": orientation }) : child) }) }) }));
+});
+/** One route tab. Renders the app's `Link`. */
+export const TabsLink = React.forwardRef(function TabsLink({ href, active, exact, icon, count, badgeTone, disabled, className, children, ...props }, ref) {
+    const Link = useLink();
+    const { isActive } = useNavigation();
+    const { variant, size } = React.useContext(TabsListContext);
+    const current = active ?? isActive(href, { exact });
+    return (_jsx(Link, { ref: ref, href: href, "data-slot": "tabs-link", "data-selected": current ? "" : undefined, "aria-current": current ? "page" : undefined, "aria-disabled": disabled || undefined, tabIndex: disabled ? -1 : undefined, className: cn(tabsTriggerVariants({ variant, size }), className), ...props, children: _jsx(TabContent, { icon: icon, count: count, badgeTone: badgeTone ?? (current && variant !== "underline" ? "accent" : undefined), children: children }) }));
+});

package/dist/components/tag-input.d.ts

@@ -0,0 +1,77 @@
+import * as React from "react";
+import { type BadgeProps } from "./badge.js";
+declare const tagInputLabels: {
+    placeholder: string;
+    list: string;
+    suggestions: string;
+    added: string;
+    removed: string;
+    duplicate: string;
+    max: string;
+    notAllowed: string;
+    tooLong: string;
+    invalid: string;
+    remove: string;
+    loading: string;
+};
+export type TagInputLabels = typeof tagInputLabels;
+export type TagDelimiter = "Enter" | "Tab" | "," | ";" | " " | (string & {});
+export interface TagInputProps {
+    /** Current tags (controlled). */
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (tags: string[]) => void;
+    /**
+     * Suggestions under the input: a static list (filtered with locale folding), or a loader
+     * `(query, signal) => Promise<string[]>` — debounced and aborted for you.
+     */
+    suggestions?: string[] | ((query: string, signal: AbortSignal) => Promise<string[]>);
+    /** `false`: only suggestions can be added. Default `true`. */
+    allowCustom?: boolean;
+    /** Keys that commit the typed text. Default `["Enter", "Tab", ","]`. Paste always splits on comma, semicolon and newline. */
+    delimiters?: TagDelimiter[];
+    /** Maximum number of tags. */
+    max?: number;
+    /** Maximum characters per tag. */
+    maxLength?: number;
+    /** Return an error message for an invalid tag; it is kept, shown in the danger tone and makes the field invalid. */
+    validate?: (tag: string) => string | true;
+    /** Normalise before adding. Default: trim and collapse inner whitespace. */
+    transform?: (tag: string) => string;
+    /** Duplicate check: `"fold"` (default) treats "İstanbul" and "istanbul" as the same tag. */
+    dedupe?: "fold" | "exact";
+    /** Badge tone per tag (segment colours, status). */
+    tagTone?: (tag: string) => BadgeProps["tone"];
+    /** Commit the typed text when the input loses focus. Default `false`. */
+    addOnBlur?: boolean;
+    /** Each tag submits one entry under this name (`formData.getAll(name)`). */
+    name?: string;
+    placeholder?: string;
+    size?: "sm" | "md";
+    /** `"ghost"`: borderless until hover/focus. */
+    variant?: "default" | "ghost";
+    disabled?: boolean;
+    invalid?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    className?: string;
+    /** Built-in string overrides (`tagInput` namespace). */
+    labels?: Partial<TagInputLabels>;
+}
+/**
+ * Free-form multi-value entry: post tags, contact segments, skills, recipients, keywords.
+ * Chips live inside the box with a trailing text input. Enter, Tab or comma add; paste splits a
+ * comma- or newline-separated list; Backspace on the empty input moves to the last chip, and a
+ * second Backspace removes it; ←/→ move between chips. Adds and removals are announced.
+ *
+ * ```tsx
+ * <Field label="Tags"><TagInput name="tags" suggestions={existingTags} max={10} /></Field>
+ * <TagInput validate={(v) => /^\S+@\S+\.\S+$/.test(v) || "Not an email address"} />
+ * ```
+ */
+export declare const TagInput: React.ForwardRefExoticComponent<TagInputProps & React.RefAttributes<HTMLInputElement>>;
+export {};

package/dist/components/tag-input.js

@@ -0,0 +1,305 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { mergeIds } from "../lib/compose-refs.js";
+import { useFieldControl } from "../lib/field-context.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { foldText, highlightParts, matchText } from "../lib/text.js";
+import { useAsyncList } from "../lib/use-async-list.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { controlVariants, itemVariants } from "../lib/variants.js";
+import { Badge } from "./badge.js";
+import { Popover, PopoverAnchor, PopoverContent } from "./popover.js";
+import { Spinner } from "./spinner.js";
+const tagInputLabels = {
+    placeholder: "Add a tag…",
+    list: "Tags",
+    suggestions: "Suggestions",
+    added: "“{tag}” added",
+    removed: "“{tag}” removed",
+    duplicate: "“{tag}” is already added",
+    max: "{max, plural, one {Up to # tag} other {Up to # tags}}",
+    notAllowed: "“{tag}” isn't one of the options",
+    tooLong: "{max, plural, one {Tags can be at most # character} other {Tags can be at most # characters}}",
+    invalid: "{tag}: {message}",
+    remove: "Remove {label}",
+    loading: "Loading suggestions…",
+};
+const defaultTransform = (s) => s.replace(/\s+/g, " ").trim();
+const PASTE_SPLIT = /[,;\n\r\t]+/;
+/**
+ * Free-form multi-value entry: post tags, contact segments, skills, recipients, keywords.
+ * Chips live inside the box with a trailing text input. Enter, Tab or comma add; paste splits a
+ * comma- or newline-separated list; Backspace on the empty input moves to the last chip, and a
+ * second Backspace removes it; ←/→ move between chips. Adds and removals are announced.
+ *
+ * ```tsx
+ * <Field label="Tags"><TagInput name="tags" suggestions={existingTags} max={10} /></Field>
+ * <TagInput validate={(v) => /^\S+@\S+\.\S+$/.test(v) || "Not an email address"} />
+ * ```
+ */
+export const TagInput = React.forwardRef(function TagInput(props, forwardedRef) {
+    const { value: valueProp, defaultValue, onValueChange, suggestions, allowCustom = true, delimiters = ["Enter", "Tab", ","], max, maxLength, validate, transform = defaultTransform, dedupe = "fold", tagTone, addOnBlur = false, name: nameProp, placeholder, size = "md", variant = "default", invalid, className, labels, } = props;
+    const t = useLabels("tagInput", tagInputLabels, labels);
+    const { locale } = useLocale();
+    const control = useFieldControl({
+        id: props.id,
+        name: nameProp,
+        disabled: props.disabled,
+        readOnly: props.readOnly,
+        required: props.required,
+        "aria-invalid": invalid ? true : undefined,
+        "aria-label": props["aria-label"],
+        "aria-labelledby": props["aria-labelledby"],
+        "aria-describedby": props["aria-describedby"],
+    });
+    const disabled = Boolean(control.disabled);
+    const readOnly = Boolean(control.readOnly);
+    const inert = disabled || readOnly;
+    const [tags, setTags] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? [], onChange: onValueChange, name: "TagInput" });
+    const [text, setText] = React.useState("");
+    const [announcement, setAnnouncement] = React.useState("");
+    const [flash, setFlash] = React.useState(null);
+    const [focused, setFocused] = React.useState(false);
+    const [listOpen, setListOpen] = React.useState(false);
+    const [active, setActive] = React.useState(-1);
+    const inputRef = React.useRef(null);
+    const boxRef = React.useRef(null);
+    const chipsRef = React.useRef(null);
+    const baseId = React.useId();
+    const listId = `${baseId}-list`;
+    const maxId = `${baseId}-max`;
+    const key = React.useCallback((s) => (dedupe === "fold" ? foldText(s, locale) : s), [dedupe, locale]);
+    const full = max !== undefined && tags.length >= max;
+    /* ---------------------------------------------------------------- suggestions */
+    const loader = typeof suggestions === "function" ? suggestions : undefined;
+    const async = useAsyncList({ load: loader, query: text.trim(), enabled: Boolean(loader) && focused && listOpen });
+    const taken = React.useMemo(() => new Set(tags.map(key)), [tags, key]);
+    const options = React.useMemo(() => {
+        const source = Array.isArray(suggestions) ? suggestions.filter((s) => !text.trim() || matchText(s, text.trim(), locale)) : async.items;
+        return source.filter((s) => !taken.has(key(s))).slice(0, 50);
+    }, [suggestions, async.items, text, locale, taken, key]);
+    const hasSuggestions = suggestions !== undefined;
+    const showList = hasSuggestions && focused && listOpen && !inert && !full && (options.length > 0 || async.loading);
+    React.useEffect(() => {
+        setActive(-1);
+    }, [text]);
+    /* ---------------------------------------------------------------- mutations */
+    const say = (msg) => setAnnouncement((prev) => (prev === msg ? `${msg} ` : msg));
+    const add = (raw, current) => {
+        const tag = transform(raw);
+        if (!tag)
+            return null;
+        if (max !== undefined && current.length >= max) {
+            say(t("max", { max }));
+            return null;
+        }
+        if (maxLength !== undefined && tag.length > maxLength) {
+            say(t("tooLong", { max: maxLength }));
+            return null;
+        }
+        const k = key(tag);
+        const dup = current.findIndex((x) => key(x) === k);
+        if (dup >= 0) {
+            setFlash(dup);
+            say(t("duplicate", { tag: current[dup] }));
+            return null;
+        }
+        if (!allowCustom) {
+            const pool = Array.isArray(suggestions) ? suggestions : async.items;
+            const match = pool.find((s) => key(s) === k);
+            if (!match) {
+                say(t("notAllowed", { tag }));
+                return null;
+            }
+            return [...current, match];
+        }
+        return [...current, tag];
+    };
+    const commit = (raws) => {
+        let next = tags;
+        const added = [];
+        for (const raw of raws) {
+            const r = add(raw, next);
+            if (r) {
+                added.push(r[r.length - 1]);
+                next = r;
+            }
+        }
+        if (added.length === 0)
+            return false;
+        setTags(next);
+        const message = validate ? validate(added[added.length - 1]) : true;
+        say(message === true ? t("added", { tag: added.join(", ") }) : t("invalid", { tag: added[added.length - 1], message }));
+        return true;
+    };
+    const removeAt = (index, refocus) => {
+        if (inert)
+            return;
+        const tag = tags[index];
+        if (tag === undefined)
+            return;
+        setTags(tags.filter((_, i) => i !== index));
+        say(t("removed", { tag }));
+        if (!refocus)
+            return;
+        requestAnimationFrame(() => {
+            const buttons = chipsRef.current?.querySelectorAll('[data-slot="chip-remove"]');
+            if (buttons && buttons.length > 0 && index > 0)
+                buttons[index - 1].focus();
+            else
+                inputRef.current?.focus();
+        });
+    };
+    React.useEffect(() => {
+        if (flash === null)
+            return;
+        const id = setTimeout(() => setFlash(null), 600);
+        return () => clearTimeout(id);
+    }, [flash]);
+    /* ---------------------------------------------------------------- input events */
+    const charDelimiters = delimiters.filter((d) => d.length === 1);
+    const onKeyDown = (e) => {
+        if (e.nativeEvent.isComposing)
+            return;
+        if (showList && (e.key === "ArrowDown" || e.key === "ArrowUp")) {
+            e.preventDefault();
+            const n = options.length;
+            if (n === 0)
+                return;
+            setActive((i) => (e.key === "ArrowDown" ? (i + 1) % n : i <= 0 ? n - 1 : i - 1));
+            return;
+        }
+        if (e.key === "ArrowDown" && hasSuggestions) {
+            e.preventDefault();
+            setListOpen(true);
+            return;
+        }
+        if (e.key === "Escape" && showList) {
+            e.preventDefault();
+            setListOpen(false);
+            return;
+        }
+        if (e.key === "Enter" && showList && active >= 0 && options[active]) {
+            e.preventDefault();
+            if (commit([options[active]]))
+                setText("");
+            return;
+        }
+        if (delimiters.includes(e.key)) {
+            if (!text.trim()) {
+                // An empty Enter must not submit the form by accident; Tab moves on as usual.
+                if (e.key === "Enter")
+                    e.preventDefault();
+                return;
+            }
+            e.preventDefault();
+            if (commit([text]))
+                setText("");
+            return;
+        }
+        if (e.key === "Backspace" && text === "" && tags.length > 0) {
+            e.preventDefault();
+            const buttons = chipsRef.current?.querySelectorAll('[data-slot="chip-remove"]');
+            buttons?.[buttons.length - 1]?.focus();
+            return;
+        }
+        if ((e.key === "ArrowLeft" && !isRtl()) || (e.key === "ArrowRight" && isRtl())) {
+            if (e.currentTarget.selectionStart === 0 && e.currentTarget.selectionEnd === 0 && tags.length > 0) {
+                e.preventDefault();
+                const buttons = chipsRef.current?.querySelectorAll('[data-slot="chip-remove"]');
+                buttons?.[buttons.length - 1]?.focus();
+            }
+        }
+    };
+    const isRtl = () => (boxRef.current ? getComputedStyle(boxRef.current).direction === "rtl" : false);
+    const onChange = (e) => {
+        const v = e.target.value;
+        // Typed (or IME-inserted) delimiter characters split the text.
+        if (charDelimiters.some((d) => v.includes(d))) {
+            const parts = v.split(new RegExp(`[${charDelimiters.map((d) => d.replace(/[\\\]^-]/g, "\\$&")).join("")}]`));
+            const rest = parts.pop() ?? "";
+            commit(parts);
+            setText(rest);
+        }
+        else {
+            setText(v);
+        }
+        setListOpen(true);
+    };
+    const onPaste = (e) => {
+        const pasted = e.clipboardData.getData("text");
+        if (!PASTE_SPLIT.test(pasted))
+            return;
+        e.preventDefault();
+        const parts = (text + pasted).split(PASTE_SPLIT).filter((p) => p.trim());
+        commit(parts);
+        setText("");
+    };
+    const onChipKeyDown = (e) => {
+        const buttons = [...(chipsRef.current?.querySelectorAll('[data-slot="chip-remove"]') ?? [])];
+        const i = buttons.indexOf(document.activeElement);
+        if (i < 0)
+            return;
+        const rtl = isRtl();
+        if (e.key === (rtl ? "ArrowRight" : "ArrowLeft")) {
+            e.preventDefault();
+            buttons[Math.max(0, i - 1)].focus();
+        }
+        else if (e.key === (rtl ? "ArrowLeft" : "ArrowRight")) {
+            e.preventDefault();
+            (buttons[i + 1] ?? inputRef.current)?.focus();
+        }
+        else if (e.key === "Escape" || (e.key.length === 1 && !e.metaKey && !e.ctrlKey)) {
+            // Typing on a chip goes back to the input.
+            inputRef.current?.focus();
+        }
+    };
+    /* ---------------------------------------------------------------- render */
+    const invalidTags = validate ? tags.map((tag) => validate(tag)) : null;
+    const anyInvalid = invalidTags?.some((r) => r !== true) ?? false;
+    const isInvalid = Boolean(control["aria-invalid"]) || anyInvalid;
+    const activeId = active >= 0 ? `${listId}-${active}` : undefined;
+    const name = control.name;
+    const box = (_jsxs("div", { ref: boxRef, "data-slot": "tag-input", "data-size": size, "data-readonly": readOnly ? "" : undefined, "data-full": full ? "" : undefined, "aria-invalid": isInvalid || undefined, "aria-disabled": disabled || undefined, onPointerDown: (e) => {
+            if (e.target === e.currentTarget || e.target === chipsRef.current) {
+                e.preventDefault();
+                inputRef.current?.focus();
+            }
+        }, className: cn(controlVariants({ size, variant, multiline: true }), "cursor-text flex-wrap gap-1 py-1 ps-1.5 pe-2", size === "sm" ? "min-h-[calc(var(--control-h)-0.5rem)] py-0.5" : "min-h-(--control-h)", disabled && "cursor-not-allowed", className), children: [tags.length > 0 ? (_jsx("ul", { ref: chipsRef, "aria-label": t("list"), className: "contents", onKeyDown: onChipKeyDown, children: tags.map((tag, i) => {
+                    const result = invalidTags?.[i];
+                    const bad = result !== undefined && result !== true;
+                    return (_jsx("li", { className: "flex min-w-0", children: _jsxs(Badge, { size: size === "sm" ? "sm" : "md", shape: "square", tone: bad ? "danger" : (tagTone?.(tag) ?? "neutral"), "data-flash": flash === i ? "" : undefined, "data-invalid": bad ? "" : undefined, title: bad ? result : undefined, className: "ui-tag max-w-64 min-w-0", onRemove: inert ? undefined : () => removeAt(i, true), removeLabel: t("remove", { label: tag }), children: [_jsx("span", { className: "truncate", children: tag }), bad ? _jsxs("span", { className: "sr-only", children: [", ", result] }) : null] }) }, `${tag}-${i}`));
+                }) })) : null, _jsx("input", { ref: (node) => {
+                    inputRef.current = node;
+                    if (typeof forwardedRef === "function")
+                        forwardedRef(node);
+                    else if (forwardedRef)
+                        forwardedRef.current = node;
+                }, id: control.id, type: "text", value: text, disabled: disabled, readOnly: readOnly || full, "aria-label": control["aria-label"], "aria-labelledby": control["aria-labelledby"], "aria-describedby": mergeIds(control["aria-describedby"], max !== undefined ? maxId : undefined), "aria-invalid": isInvalid || undefined, "aria-required": control.required || undefined, enterKeyHint: "enter", autoComplete: "off", placeholder: full || readOnly ? undefined : tags.length === 0 ? (placeholder ?? t("placeholder")) : undefined, ...(hasSuggestions
+                    ? {
+                        role: "combobox",
+                        "aria-autocomplete": "list",
+                        "aria-expanded": showList,
+                        "aria-controls": showList ? listId : undefined,
+                        "aria-activedescendant": showList ? activeId : undefined,
+                    }
+                    : {}), onChange: onChange, onKeyDown: onKeyDown, onPaste: onPaste, onFocus: () => setFocused(true), onBlur: () => {
+                    setFocused(false);
+                    setListOpen(false);
+                    if (addOnBlur && text.trim() && commit([text]))
+                        setText("");
+                }, className: cn("h-[calc(var(--control-h)-0.5rem)] min-w-0 flex-1 bg-transparent px-1.5 text-[length:inherit] text-fg outline-none placeholder:text-fg-subtle disabled:cursor-not-allowed", size === "sm" && "h-[calc(var(--control-h)-0.875rem)]", full ? "w-2 min-w-2 max-w-2 flex-none caret-transparent" : "min-w-20") }), max !== undefined ? (_jsxs("span", { "aria-hidden": true, className: cn("ms-auto shrink-0 self-center ps-1 text-[11px] tabular text-fg-subtle", full && "text-fg-muted"), children: [tags.length, "/", max] })) : null, _jsx("span", { id: maxId, className: "sr-only", children: max !== undefined ? t("max", { max }) : "" }), _jsx("span", { "aria-live": "polite", className: "sr-only", children: announcement }), name ? tags.map((tag, i) => _jsx("input", { type: "hidden", name: name, value: tag }, `${tag}-${i}`)) : null] }));
+    if (!hasSuggestions)
+        return box;
+    return (_jsxs(Popover, { open: showList, onOpenChange: (o) => !o && setListOpen(false), children: [_jsx(PopoverAnchor, { asChild: true, children: box }), _jsx(PopoverContent, { size: "trigger", padded: false, align: "start", "aria-label": t("suggestions"), className: "min-w-48", onOpenAutoFocus: (e) => e.preventDefault(), onCloseAutoFocus: (e) => e.preventDefault(), onInteractOutside: (e) => {
+                    if (boxRef.current?.contains(e.target))
+                        e.preventDefault();
+                }, children: _jsxs("ul", { id: listId, role: "listbox", "aria-label": t("suggestions"), className: "max-h-64 overflow-y-auto p-1", children: [async.loading && options.length === 0 ? (_jsxs("li", { role: "presentation", className: "flex items-center gap-2 px-2 py-1.5 text-[13px] text-fg-muted", children: [_jsx(Spinner, { size: "xs", tone: "muted" }), t("loading")] })) : null, options.map((option, i) => (_jsx("li", { id: `${listId}-${i}`, role: "option", "aria-selected": i === active, "data-selected": i === active ? "true" : undefined, onMouseDown: (e) => e.preventDefault(), onMouseMove: () => setActive(i), onClick: () => {
+                                if (commit([option]))
+                                    setText("");
+                                inputRef.current?.focus();
+                            }, className: itemVariants({ size: size === "sm" ? "sm" : "md" }), children: _jsx("span", { className: "truncate", children: highlightParts(option, text.trim(), locale).map((p, j) => p.match ? (_jsx("span", { className: "font-semibold text-fg", children: p.text }, j)) : (_jsx(React.Fragment, { children: p.text }, j))) }) }, option)))] }) })] }));
+});

package/dist/components/task-list.d.ts

@@ -0,0 +1,89 @@
+import * as React from "react";
+export type TaskPriority = "low" | "medium" | "high" | "urgent";
+export interface TaskData {
+    id: string;
+    title: string;
+    done: boolean;
+    /** Second line (checklist hint, task notes). */
+    description?: string;
+    assignee?: {
+        id: string;
+        name: string;
+        avatar?: string;
+    };
+    /** Due date `YYYY-MM-DD`. */
+    due?: string;
+    priority?: TaskPriority;
+    /** Subtasks (nest as deep as you need; one level reads best). */
+    children?: TaskData[];
+    /** Can't be toggled or edited (system-checked step). */
+    disabled?: boolean;
+}
+export declare const taskListLabels: {
+    list: string;
+    progress: string;
+    hideCompleted: string;
+    showCompleted: string;
+    add: string;
+    addSubtask: string;
+    addSubtaskTo: string;
+    edit: string;
+    remove: string;
+    moveUp: string;
+    moveDown: string;
+    due: string;
+    overdue: string;
+    priority: string;
+    low: string;
+    medium: string;
+    high: string;
+    urgent: string;
+    assignee: string;
+    subtasks: string;
+    expand: string;
+    empty: string;
+    allDone: string;
+    toggleError: string;
+    saveError: string;
+    newTask: string;
+};
+export type TaskListLabels = Partial<typeof taskListLabels>;
+export interface TaskListProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title" | "onToggle"> {
+    items: TaskData[];
+    /** Check / uncheck. Updates optimistically; a rejection reverts and shows a toast. */
+    onToggle?: (id: string, done: boolean) => void | Promise<void>;
+    /** Shows the add input (and "Add subtask" with `parentId`). Enter creates and keeps focus. */
+    onAdd?: (title: string, parentId?: string) => void | Promise<void>;
+    /** Title edits (click the pencil, Enter saves, Esc cancels). */
+    onEdit?: (id: string, patch: Partial<TaskData>) => void | Promise<void>;
+    onRemove?: (id: string) => void | Promise<void>;
+    /** Keyboard reorder: Alt+↑ / Alt+↓ on a task. Receives the new sibling order. */
+    onReorder?: (ids: string[], parentId?: string) => void | Promise<void>;
+    /** Heading above the list ("Onboarding — week 1"). */
+    title?: React.ReactNode;
+    /** Header "Hide completed" toggle (controlled / uncontrolled). */
+    hideCompleted?: boolean;
+    defaultHideCompleted?: boolean;
+    onHideCompletedChange?: (hide: boolean) => void;
+    /** Progress bar + "3 of 7 done". Default `true`. */
+    showProgress?: boolean;
+    /** Done tasks move below open ones. Default `false`. */
+    sortCompleted?: boolean;
+    /** `list` (assignee, due, priority) or `checklist` (titles only). Default `"list"`. */
+    variant?: "list" | "checklist";
+    /** Today for due states, `YYYY-MM-DD` or a Date (docs, tests). Default: the live clock in the provider time zone. */
+    today?: string | Date;
+    readOnly?: boolean;
+    labels?: TaskListLabels;
+}
+/**
+ * Checkable tasks with assignee, due date, priority and subtasks: deal follow-ups, onboarding,
+ * an editorial checklist. Optimistic toggles, inline add and edit, overdue / due-today tones,
+ * and a progress header announced politely ("4 of 7 done").
+ *
+ * ```tsx
+ * <TaskList title="Onboarding" items={tasks} onToggle={api.toggle} onAdd={api.add} />
+ * <TaskList variant="checklist" items={prePublish} onToggle={toggle} />
+ * ```
+ */
+export declare const TaskList: React.ForwardRefExoticComponent<TaskListProps & React.RefAttributes<HTMLDivElement>>;