@instruments/materia-ui 0.1.0

package/dist/compositions/tag-selector/tag-selector-trigger.d.ts

@@ -0,0 +1,19 @@
+interface TagSelectorTriggerProps {
+    className?: string;
+    /** Placeholder text when no tags selected */
+    placeholder?: string;
+}
+/**
+ * TagSelectorTrigger - The clickable area that opens the tag selector popover.
+ * Shows selected tags with a ghost placeholder at the end. When `wrapTags` is
+ * true (default) the tags wrap onto multiple rows; when false they stay on a
+ * single row that scrolls horizontally. Each pill keeps its natural width
+ * (`shrink-0`) so labels never squeeze or truncate mid-word - unless
+ * `truncateChips` is set, which caps each label's width and ellipsises it.
+ * When `maxVisibleTags` is set and the selection exceeds it, only the first N
+ * chips render, followed by a neutral outline `+N` overflow pill (a count, not
+ * a button - the whole trigger opens the popover).
+ * In single-select mode, the placeholder is hidden when a value is selected.
+ */
+export declare const TagSelectorTrigger: ({ placeholder, className, }: TagSelectorTriggerProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/tag-selector/tag-selector-trigger.js

@@ -0,0 +1,42 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Flex } from "../../components/flex.js";
+import { PopoverTrigger } from "../../components/popover.js";
+import { ScrollArea } from "../../components/scroll-area.js";
+import { ScrollFade } from "../../components/scroll-fade.js";
+import { Tag } from "../../components/tag.js";
+import { getTagOptionDomId, tagColorToDotTone, tagColorToTone, TRUNCATE_CHIP_MAX_WIDTH, useTagSelectorContext, } from "../tag-selector/tag-selector-context.js";
+import { getVisibleTagSlice } from "../tag-selector/use-tag-selector.js";
+/**
+ * TagSelectorTrigger - The clickable area that opens the tag selector popover.
+ * Shows selected tags with a ghost placeholder at the end. When `wrapTags` is
+ * true (default) the tags wrap onto multiple rows; when false they stay on a
+ * single row that scrolls horizontally. Each pill keeps its natural width
+ * (`shrink-0`) so labels never squeeze or truncate mid-word - unless
+ * `truncateChips` is set, which caps each label's width and ellipsises it.
+ * When `maxVisibleTags` is set and the selection exceeds it, only the first N
+ * chips render, followed by a neutral outline `+N` overflow pill (a count, not
+ * a button - the whole trigger opens the popover).
+ * In single-select mode, the placeholder is hidden when a value is selected.
+ */
+export const TagSelectorTrigger = ({ placeholder = "Add tags\u2026", className, }) => {
+    const { activeId, value, size, open, listboxId, singleSelect, wrapTags, maxVisibleTags, truncateChips, } = useTagSelectorContext();
+    const { visibleTags, overflowCount } = getVisibleTagSlice(value, maxVisibleTags);
+    // Overflowing selections collapse to chips + a `+N` pill only - the ghost
+    // placeholder would defeat the compact framing maxVisibleTags exists for.
+    const hidePlaceholder = (singleSelect && value.length > 0) || overflowCount > 0;
+    const activeDescendantId = open && activeId !== null
+        ? getTagOptionDomId(listboxId, activeId)
+        : undefined;
+    const chipClassName = cn("shrink-0", truncateChips && TRUNCATE_CHIP_MAX_WIDTH);
+    const tagPills = (_jsxs(_Fragment, { children: [visibleTags.map((tag) => tag.color ? (_jsx(Tag, { className: chipClassName, dot: tagColorToDotTone(tag.color), emphasis: "soft", size: size, tone: tagColorToTone(tag.color), children: tag.label }, tag.id)) : (_jsx(Tag, { asInput: true, className: chipClassName, size: size, children: tag.label }, tag.id))), overflowCount > 0 && (_jsxs(Tag, { className: "shrink-0", emphasis: "outline", size: size, tone: "neutral", children: ["+", overflowCount] })), !hidePlaceholder && (_jsx(Tag, { asInput: true, className: "text-muted-foreground shrink-0", size: size, children: placeholder }))] }));
+    return (_jsx(PopoverTrigger
+    // A combobox <div>, not a <button>: it hosts the tag pills.
+    , { 
+        // A combobox <div>, not a <button>: it hosts the tag pills.
+        nativeButton: false, render: (triggerProps) => (_jsx(Flex, { ...triggerProps, align: "center", "aria-activedescendant": activeDescendantId, "aria-controls": listboxId, "aria-expanded": open, "aria-haspopup": "listbox", className: cn("relative w-full cursor-pointer rounded-lg", focusRing(), className), "data-component": "tag-selector-trigger", "data-slot": "tag-selector-trigger", 
+            // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role, react-doctor/prefer-tag-over-role -- combobox container wraps interactive Tag pills + scroll area; an <input>/<select> cannot host these children
+            role: "combobox", tabIndex: 0 })), children: wrapTags ? (_jsx(Flex, { align: "center", className: "flex-1 gap-1.5", wrap: "wrap", children: tagPills })) : (_jsxs(_Fragment, { children: [_jsxs(ScrollArea, { className: "flex-1", hideScrollbar: true, orientation: "horizontal", viewportClassName: "[&>div]:!flex [&>div]:items-center [&>div]:gap-1.5", children: [tagPills, _jsx("span", { "aria-hidden": true, className: "w-4 shrink-0" })] }), _jsx(ScrollFade, { className: "to-white", orientation: "horizontal", position: "end", size: "sm" })] })) }));
+};

package/dist/compositions/tag-selector/tag-selector-types.d.ts

@@ -0,0 +1,86 @@
+import type { Announcements } from "@dnd-kit/core";
+import type * as React from "react";
+import type { TagSize } from "../../components/tag/tag-root.js";
+import type { TagColor, TagData } from "../tag-selector/tag-selector-context.js";
+/** Props passed to custom trigger render function */
+export interface TagSelectorTriggerRenderProps {
+    /** Whether the popover is open */
+    open: boolean;
+    /** Placeholder text */
+    placeholder: string;
+    /** Currently selected tags */
+    value: TagData[];
+}
+export interface TagSelectorProps {
+    /** Allow creating new tags */
+    allowCreate?: boolean;
+    /** Allow editing/deleting tags */
+    allowManage?: boolean;
+    /** Allow reordering tags */
+    allowReorder?: boolean;
+    className?: string;
+    /** Available colours for the colour picker */
+    colorPalette?: TagColor[];
+    /** Whether the popover overlaps the trigger instead of appearing below it */
+    coverTrigger?: boolean;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Empty state message */
+    emptyMessage?: string;
+    /**
+     * Cap how many selected chips the trigger renders. When set and the selection
+     * exceeds it, only the first N chips show, followed by a `+N` overflow count
+     * pill. Undefined (default) renders every chip (wrapping or scrolling per
+     * `wrapTags`). Handy for fixed-width table cells.
+     */
+    maxVisibleTags?: number;
+    /** Called when selection changes */
+    onChange: (tags: TagData[]) => void;
+    /** Called when a new tag is created */
+    onCreateTag?: (label: string, color?: TagColor) => Promise<TagData>;
+    /** Called when a tag is deleted */
+    onDeleteTag?: (id: string) => Promise<void>;
+    /** Called when a tag is edited */
+    onEditTag?: (id: string, newLabel: string, color?: TagColor) => Promise<void>;
+    /** Called when open state changes */
+    onOpenChange?: (open: boolean) => void;
+    /** Called when tags are reordered */
+    onReorder?: (tags: TagData[]) => void;
+    /** Called when tags list should be refetched (e.g., on search) */
+    onSearch?: (query: string) => Promise<TagData[]>;
+    /** Controlled open state */
+    open?: boolean;
+    /**
+     * Override the drag-and-drop screen-reader announcements used while
+     * reordering tags. Follows @dnd-kit's {@link Announcements} contract. When
+     * omitted, sensible English defaults are used. Only relevant with
+     * `allowReorder`. Memoise the object you pass (useMemo or module scope) -
+     * a fresh literal per render defeats the context value's memoization.
+     */
+    reorderAnnouncements?: Announcements;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Search input placeholder */
+    searchPlaceholder?: string;
+    /** Show colour picker swatches when creating/editing tags */
+    showColorPicker?: boolean;
+    /** Single-select mode: only one tag can be selected at a time */
+    singleSelect?: boolean;
+    /** Component size */
+    size?: TagSize;
+    /** All available tags */
+    tags?: TagData[];
+    /** Custom trigger render function. When provided, replaces the default trigger. */
+    trigger?: (props: TagSelectorTriggerRenderProps) => React.ReactElement;
+    /**
+     * Opt-in per-chip truncation. Long labels ellipsise (CSS `truncate` + a
+     * max-width) instead of pushing the trigger/search row wider, keeping the
+     * `+N` overflow pill and search input visible. Default false = chips keep
+     * their natural width.
+     */
+    truncateChips?: boolean;
+    /** Currently selected tags */
+    value: TagData[];
+    /** Whether tags wrap (true) or scroll horizontally (false) */
+    wrapTags?: boolean;
+}

package/dist/compositions/tag-selector/tag-selector-types.js

@@ -0,0 +1 @@
+export {};

package/dist/compositions/tag-selector/use-tag-selector-context-value.d.ts

@@ -0,0 +1,15 @@
+import type { TagSelectorContextValue } from "./tag-selector-context.js";
+/** Assembles the memoized context value from state + handlers. */
+/**
+ * Input to {@link useTagSelectorContextValue}. The CRUD/confirm handlers may be
+ * async (consumer-supplied `onCreateTag` etc. often return promises); the
+ * context exposes them as fire-and-forget `() => void`. Widening the param here
+ * lets the async useCallbacks be passed without a no-misused-promises flag.
+ */
+type TagSelectorContextValueParts = Omit<TagSelectorContextValue, "confirmEdit" | "createTag" | "deleteTag"> & {
+    confirmEdit: () => void | Promise<void>;
+    createTag: (label: string) => void | Promise<void>;
+    deleteTag: (id: string) => void | Promise<void>;
+};
+export declare const useTagSelectorContextValue: (parts: TagSelectorContextValueParts) => TagSelectorContextValue;
+export {};

package/dist/compositions/tag-selector/use-tag-selector-context-value.js

@@ -0,0 +1,79 @@
+import { useMemo } from "react";
+export const useTagSelectorContextValue = (parts) => {
+    const { activeId, allowCreate, allowManage, allowReorder, cancelEdit, colorPalette, confirmEdit, coverTrigger, createTag, deleteTag, editValue, editingId, filteredTags, listboxId, maxVisibleTags, moveActiveDescendant, open, pendingColor, removeTag, reorderAnnouncements, reorderTags, searchQuery, setActiveId, setEditValue, setOpen, setPendingColor, setSearchQuery, showColorPicker, singleSelect, size, startEditing, tags, toggleTag, truncateChips, value, wrapTags, } = parts;
+    return useMemo(() => ({
+        activeId,
+        allowCreate,
+        allowManage,
+        allowReorder,
+        cancelEdit,
+        colorPalette,
+        confirmEdit,
+        coverTrigger,
+        createTag,
+        deleteTag,
+        editValue,
+        editingId,
+        filteredTags,
+        listboxId,
+        maxVisibleTags,
+        moveActiveDescendant,
+        open,
+        pendingColor,
+        removeTag,
+        reorderAnnouncements,
+        reorderTags,
+        searchQuery,
+        setActiveId,
+        setEditValue,
+        setOpen,
+        setPendingColor,
+        setSearchQuery,
+        showColorPicker,
+        singleSelect,
+        size,
+        startEditing,
+        tags,
+        toggleTag,
+        truncateChips,
+        value,
+        wrapTags,
+    }), [
+        activeId,
+        size,
+        value,
+        tags,
+        filteredTags,
+        searchQuery,
+        open,
+        listboxId,
+        editingId,
+        editValue,
+        allowCreate,
+        allowReorder,
+        allowManage,
+        wrapTags,
+        coverTrigger,
+        singleSelect,
+        showColorPicker,
+        colorPalette,
+        pendingColor,
+        maxVisibleTags,
+        truncateChips,
+        reorderAnnouncements,
+        toggleTag,
+        removeTag,
+        setOpen,
+        startEditing,
+        confirmEdit,
+        cancelEdit,
+        createTag,
+        deleteTag,
+        reorderTags,
+        moveActiveDescendant,
+        setActiveId,
+        setEditValue,
+        setPendingColor,
+        setSearchQuery,
+    ]);
+};

package/dist/compositions/tag-selector/use-tag-selector.d.ts

@@ -0,0 +1,28 @@
+import type * as React from "react";
+import type { TagData } from "../tag-selector/tag-selector-context.js";
+import type { TagSelectorProps } from "./tag-selector-types.js";
+/**
+ * Split a selected-tag list into the chips the trigger should render and the
+ * count that overflows past `maxVisibleTags`. When `maxVisibleTags` is undefined
+ * (or the selection fits within it) every tag stays visible and the overflow is
+ * zero. Pure so the trigger's `+N` behaviour is unit-testable without a render.
+ */
+export declare const getVisibleTagSlice: (value: TagData[], maxVisibleTags: number | undefined) => {
+    overflowCount: number;
+    visibleTags: TagData[];
+};
+/**
+ * All TagSelector state, handlers, and the assembled context value. Extracted
+ * from the component so the render stays small.
+ */
+export declare const useTagSelectorState: (props: TagSelectorProps) => {
+    className: string | undefined;
+    contextValue: import("../tag-selector.js").TagSelectorContextValue;
+    emptyMessage: string;
+    open: boolean;
+    placeholder: string;
+    searchPlaceholder: string;
+    setOpen: (newOpen: boolean) => void;
+    trigger: ((props: import("./tag-selector-types.js").TagSelectorTriggerRenderProps) => React.ReactElement) | undefined;
+    value: TagData[];
+};

package/dist/compositions/tag-selector/use-tag-selector.js

@@ -0,0 +1,350 @@
+"use client";
+import { useCallback, useEffect, useId, useMemo, useRef, useState, } from "react";
+import { useTagSelectorContextValue } from "./use-tag-selector-context-value.js";
+const EMPTY_TAGS = [];
+const EMPTY_COLOR_PALETTE = [];
+/**
+ * Split a selected-tag list into the chips the trigger should render and the
+ * count that overflows past `maxVisibleTags`. When `maxVisibleTags` is undefined
+ * (or the selection fits within it) every tag stays visible and the overflow is
+ * zero. Pure so the trigger's `+N` behaviour is unit-testable without a render.
+ */
+export const getVisibleTagSlice = (value, maxVisibleTags) => {
+    if (maxVisibleTags === undefined || value.length <= maxVisibleTags) {
+        return { overflowCount: 0, visibleTags: value };
+    }
+    const cap = Math.max(0, maxVisibleTags);
+    return {
+        overflowCount: value.length - cap,
+        visibleTags: value.slice(0, cap),
+    };
+};
+/** Controlled/uncontrolled open state plus the search/edit fields it resets on close. */
+const useTagSelectorOpenState = ({ onOpenChange, openProp, }) => {
+    const [internalOpen, setInternalOpen] = useState(false);
+    const [searchQuery, setSearchQuery] = useState("");
+    const [editingId, setEditingId] = useState(null);
+    const [editValue, setEditValue] = useState("");
+    const [activeId, setActiveId] = useState(null);
+    const open = openProp ?? internalOpen;
+    const setOpen = useCallback((newOpen) => {
+        setInternalOpen(newOpen);
+        onOpenChange?.(newOpen);
+        if (!newOpen) {
+            setSearchQuery("");
+            setEditingId(null);
+            setEditValue("");
+            setActiveId(null);
+        }
+    }, [onOpenChange]);
+    // Typing resets the keyboard highlight so navigation restarts from the top.
+    const changeSearchQuery = useCallback((query) => {
+        setSearchQuery(query);
+        setActiveId(null);
+    }, []);
+    return {
+        activeId,
+        editValue,
+        editingId,
+        open,
+        searchQuery,
+        setActiveId,
+        setEditValue,
+        setEditingId,
+        setOpen,
+        setSearchQuery: changeSearchQuery,
+    };
+};
+/** Search-filtered tags plus keyboard active-descendant movement over them. */
+const useTagSelectorActiveDescendant = ({ searchQuery, setActiveId, tags, }) => {
+    const filteredTags = useMemo(() => searchQuery
+        ? tags.filter((tag) => tag.label.toLowerCase().includes(searchQuery.toLowerCase()))
+        : tags, [searchQuery, tags]);
+    const moveActiveDescendant = useCallback((direction) => {
+        setActiveId((current) => {
+            if (filteredTags.length === 0) {
+                return null;
+            }
+            const currentIndex = filteredTags.findIndex((t) => t.id === current);
+            if (direction === "down") {
+                const nextIndex = currentIndex === -1 ? 0 : (currentIndex + 1) % filteredTags.length;
+                return filteredTags[nextIndex]?.id ?? null;
+            }
+            const previousIndex = currentIndex <= 0 ? filteredTags.length - 1 : currentIndex - 1;
+            return filteredTags[previousIndex]?.id ?? null;
+        });
+    }, [filteredTags, setActiveId]);
+    return { filteredTags, moveActiveDescendant };
+};
+/** Selection toggle/remove handlers. */
+const useTagSelectionHandlers = ({ onChange, setOpen, singleSelect, value, }) => {
+    // Toggle tag selection
+    const toggleTag = useCallback((tag) => {
+        const isSelected = value.some((t) => t.id === tag.id);
+        if (singleSelect) {
+            if (isSelected) {
+                onChange([]);
+            }
+            else {
+                onChange([tag]);
+            }
+            // Close popover after selection in single-select mode
+            setOpen(false);
+        }
+        else if (isSelected) {
+            onChange(value.filter((t) => t.id !== tag.id));
+        }
+        else {
+            onChange([...value, tag]);
+        }
+    }, [value, onChange, singleSelect, setOpen]);
+    // Remove tag from selection
+    const removeTag = useCallback((id) => {
+        onChange(value.filter((t) => t.id !== id));
+    }, [value, onChange]);
+    return { removeTag, toggleTag };
+};
+/** Inline edit (start/confirm/cancel) handlers. */
+const useTagEditHandlers = ({ editValue, editingId, onChange, onEditTag, pendingColor, setEditValue, setEditingId, setPendingColor, setTags, tags, value, }) => {
+    // Start editing a tag
+    const startEditing = useCallback((id) => {
+        const tag = tags.find((t) => t.id === id);
+        if (tag) {
+            setEditingId(id);
+            setEditValue(tag.label);
+            setPendingColor(tag.color);
+        }
+    }, [tags, setEditValue, setEditingId, setPendingColor]);
+    // Confirm edit
+    const confirmEdit = useCallback(async () => {
+        if (editingId === null || editValue.trim() === "") {
+            setEditingId(null);
+            setEditValue("");
+            return;
+        }
+        const newLabel = editValue.trim();
+        const tag = tags.find((t) => t.id === editingId);
+        if (tag && (tag.label !== newLabel || tag.color !== pendingColor)) {
+            // Call external handler if provided
+            if (onEditTag) {
+                await onEditTag(editingId, newLabel, pendingColor);
+            }
+            // Update local state
+            setTags((prev) => prev.map((t) => t.id === editingId
+                ? { ...t, color: pendingColor, label: newLabel }
+                : t));
+            // Update selection if this tag was selected
+            if (value.some((t) => t.id === editingId)) {
+                onChange(value.map((t) => t.id === editingId
+                    ? { ...t, color: pendingColor, label: newLabel }
+                    : t));
+            }
+        }
+        setEditingId(null);
+        setEditValue("");
+    }, [
+        editingId,
+        editValue,
+        pendingColor,
+        tags,
+        value,
+        onChange,
+        onEditTag,
+        setEditValue,
+        setEditingId,
+        setTags,
+    ]);
+    // Cancel edit
+    const cancelEdit = useCallback(() => {
+        setEditingId(null);
+        setEditValue("");
+        setPendingColor(undefined);
+    }, [setEditValue, setEditingId, setPendingColor]);
+    return { cancelEdit, confirmEdit, startEditing };
+};
+/** Tag mutation (create/delete/reorder) handlers. */
+const useTagCrudHandlers = ({ onChange, onCreateTag, onDeleteTag, onReorder, pendingColor, setOpen, setPendingColor, setSearchQuery, setTags, singleSelect, value, }) => {
+    // Ref to access current value in async callbacks (avoids stale closures)
+    const valueRef = useRef(value);
+    useEffect(() => {
+        valueRef.current = value;
+    }, [value]);
+    // Create a new tag (instant optimistic UI, async server call in background)
+    const createTag = useCallback((label) => {
+        if (!label.trim()) {
+            return;
+        }
+        const trimmed = label.trim();
+        const color = pendingColor;
+        // Instant: show a pending tag in the UI immediately
+        const pendingId = `_pending-${Date.now()}`;
+        const pendingTag = { color, id: pendingId, label: trimmed };
+        setTags((prev) => [...prev, pendingTag]);
+        if (singleSelect) {
+            onChange([pendingTag]);
+            setOpen(false);
+        }
+        else {
+            onChange([...value, pendingTag]);
+        }
+        setSearchQuery("");
+        setPendingColor(undefined);
+        if (onCreateTag) {
+            // Fire server create in the background, then swap pending → real.
+            const reconcilePendingTag = async () => {
+                try {
+                    const realTag = await onCreateTag(trimmed, color);
+                    setTags((prev) => prev.map((t) => (t.id === pendingId ? realTag : t)));
+                    const { current } = valueRef;
+                    onChange(current.map((t) => (t.id === pendingId ? realTag : t)));
+                }
+                catch {
+                    // On failure: remove the pending tag
+                    setTags((prev) => prev.filter((t) => t.id !== pendingId));
+                    const { current } = valueRef;
+                    onChange(current.filter((t) => t.id !== pendingId));
+                }
+            };
+            void reconcilePendingTag();
+        }
+    }, [
+        onCreateTag,
+        value,
+        onChange,
+        pendingColor,
+        singleSelect,
+        setOpen,
+        setPendingColor,
+        setSearchQuery,
+        setTags,
+    ]);
+    // Delete a tag
+    const deleteTag = useCallback(async (id) => {
+        // Call external handler if provided
+        if (onDeleteTag) {
+            await onDeleteTag(id);
+        }
+        // Remove from tags list
+        setTags((prev) => prev.filter((t) => t.id !== id));
+        // Remove from selection if selected
+        if (value.some((t) => t.id === id)) {
+            onChange(value.filter((t) => t.id !== id));
+        }
+    }, [onDeleteTag, value, onChange, setTags]);
+    // Reorder tags
+    const reorderTags = useCallback((newTags) => {
+        setTags(newTags);
+        onReorder?.(newTags);
+    }, [onReorder, setTags]);
+    return { createTag, deleteTag, reorderTags };
+};
+/** Resolve the display options and defaults that feed the context and the root. */
+const resolveTagSelectorOptions = ({ allowCreate = false, allowManage = false, allowReorder = false, className, colorPalette = EMPTY_COLOR_PALETTE, coverTrigger = false, emptyMessage = "No tags found.", maxVisibleTags, placeholder = "Add tags…", reorderAnnouncements, searchPlaceholder = "Search tags…", showColorPicker = false, singleSelect = false, size = "lg", trigger, truncateChips = false, wrapTags = true, }) => ({
+    allowCreate,
+    allowManage,
+    allowReorder,
+    className,
+    colorPalette,
+    coverTrigger,
+    emptyMessage,
+    maxVisibleTags,
+    placeholder,
+    reorderAnnouncements,
+    searchPlaceholder,
+    showColorPicker,
+    singleSelect,
+    size,
+    trigger,
+    truncateChips,
+    wrapTags,
+});
+/**
+ * All TagSelector state, handlers, and the assembled context value. Extracted
+ * from the component so the render stays small.
+ */
+export const useTagSelectorState = (props) => {
+    const { value, onChange, tags: tagsProp = EMPTY_TAGS, onCreateTag, onEditTag, onDeleteTag, onReorder, open: openProp, onOpenChange, } = props;
+    const options = resolveTagSelectorOptions(props);
+    const { singleSelect } = options;
+    const listboxId = useId();
+    const [tags, setTags] = useState(tagsProp);
+    const [syncedTagsProp, setSyncedTagsProp] = useState(tagsProp);
+    const [pendingColor, setPendingColor] = useState();
+    // Sync tags from prop: a new `tags` prop replaces the local (edited) list.
+    if (syncedTagsProp !== tagsProp) {
+        setSyncedTagsProp(tagsProp);
+        setTags(tagsProp);
+    }
+    const { activeId, editValue, editingId, open, searchQuery, setActiveId, setEditValue, setEditingId, setOpen, setSearchQuery, } = useTagSelectorOpenState({ onOpenChange, openProp });
+    const { filteredTags, moveActiveDescendant } = useTagSelectorActiveDescendant({ searchQuery, setActiveId, tags });
+    const { removeTag, toggleTag } = useTagSelectionHandlers({
+        onChange,
+        setOpen,
+        singleSelect,
+        value,
+    });
+    const { cancelEdit, confirmEdit, startEditing } = useTagEditHandlers({
+        editValue,
+        editingId,
+        onChange,
+        onEditTag,
+        pendingColor,
+        setEditValue,
+        setEditingId,
+        setPendingColor,
+        setTags,
+        tags,
+        value,
+    });
+    const { createTag, deleteTag, reorderTags } = useTagCrudHandlers({
+        onChange,
+        onCreateTag,
+        onDeleteTag,
+        onReorder,
+        pendingColor,
+        setOpen,
+        setPendingColor,
+        setSearchQuery,
+        setTags,
+        singleSelect,
+        value,
+    });
+    const contextValue = useTagSelectorContextValue({
+        ...options,
+        activeId,
+        cancelEdit,
+        confirmEdit,
+        createTag,
+        deleteTag,
+        editValue,
+        editingId,
+        filteredTags,
+        listboxId,
+        moveActiveDescendant,
+        open,
+        pendingColor,
+        removeTag,
+        reorderTags,
+        searchQuery,
+        setActiveId,
+        setEditValue,
+        setOpen,
+        setPendingColor,
+        setSearchQuery,
+        startEditing,
+        tags,
+        toggleTag,
+        value,
+    });
+    return {
+        className: options.className,
+        contextValue,
+        emptyMessage: options.emptyMessage,
+        open,
+        placeholder: options.placeholder,
+        searchPlaceholder: options.searchPlaceholder,
+        setOpen,
+        trigger: options.trigger,
+        value,
+    };
+};

package/dist/compositions/tag-selector.d.ts

@@ -0,0 +1,9 @@
+export { TagSelectorContent } from "./tag-selector/tag-selector-content.js";
+export type { TagColor, TagData, TagSelectorContextValue, } from "./tag-selector/tag-selector-context.js";
+export { useTagSelectorContext } from "./tag-selector/tag-selector-context.js";
+export { TagSelectorItem } from "./tag-selector/tag-selector-item.js";
+export { TagSelectorList } from "./tag-selector/tag-selector-list.js";
+export type { TagSelectorProps, TagSelectorTriggerRenderProps, } from "./tag-selector/tag-selector-root.js";
+export { TagSelector } from "./tag-selector/tag-selector-root.js";
+export { TagSelectorSearch } from "./tag-selector/tag-selector-search.js";
+export { TagSelectorTrigger } from "./tag-selector/tag-selector-trigger.js";

package/dist/compositions/tag-selector.js

@@ -0,0 +1,7 @@
+export { TagSelectorContent } from "./tag-selector/tag-selector-content.js";
+export { useTagSelectorContext } from "./tag-selector/tag-selector-context.js";
+export { TagSelectorItem } from "./tag-selector/tag-selector-item.js";
+export { TagSelectorList } from "./tag-selector/tag-selector-list.js";
+export { TagSelector } from "./tag-selector/tag-selector-root.js";
+export { TagSelectorSearch } from "./tag-selector/tag-selector-search.js";
+export { TagSelectorTrigger } from "./tag-selector/tag-selector-trigger.js";

package/dist/compositions/thinking-trace/thinking-trace-root.d.ts

@@ -0,0 +1,23 @@
+import type { ThinkingTraceProps } from "./types.js";
+export type { ThinkingTraceProps, ThinkingTraceRow, ThinkingTraceVariant, } from "./types.js";
+/**
+ * Expandable agent thinking / tool / search trace, driven by real agent state.
+ *
+ * While `streaming` is `true` the trace is open, shows every row it is given and
+ * shimmers `activeLabel`. When it turns `false` the trace collapses to
+ * `doneLabel`; rows stay mounted and the header re-expands them. A manual
+ * toggle of the header pins expansion until the component unmounts.
+ *
+ * @example
+ * ```tsx
+ * <ThinkingTrace
+ *   doneLabel={`Thought for ${elapsedSeconds} seconds`}
+ *   rows={steps.map((step) => ({ primary: step.label }))}
+ *   streaming={status === "streaming"}
+ * />
+ * ```
+ *
+ * @bestPractice Pair above streaming answers in chat. Use ThinkingLoader when you only need a one-line narrated header without an expandable timeline.
+ * @category assistant
+ */
+export declare const ThinkingTrace: ({ className, activeLabel, doneLabel, query, rows, streaming, variant, }: ThinkingTraceProps) => import("react").JSX.Element;