@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,130 @@
+import type { Announcements } from "@dnd-kit/core";
+import type { DotProps } from "../../components/dot/dot-root.js";
+import type { PillTone } from "../../components/pill/pill-variants.js";
+import type { TagSize } from "../../components/tag/tag-root.js";
+type DotTone = NonNullable<DotProps["tone"]>;
+/**
+ * Semantic colour for tags - aligned with the Dot variant system.
+ */
+export type TagColor = "default" | "secondary" | "affirmative" | "warning" | "info" | "destructive" | "brand";
+export declare const tagColorToTone: (color: TagColor) => PillTone;
+/**
+ * Map a stored {@link TagColor} (Dot vocabulary) onto a {@link DotTone}. Dot's
+ * tone union matches PillTone, so this reuses the same collapse (`default` and
+ * `secondary` → `neutral`). Kept separate so the persisted `TagColor` union is
+ * never renamed (DB values would desync).
+ */
+export declare const tagColorToDotTone: (color: TagColor) => DotTone;
+/**
+ * Tag data structure.
+ */
+export interface TagData {
+    /** Optional semantic colour for coloured tags (e.g., status tags). */
+    color?: TagColor | undefined;
+    id: string;
+    label: string;
+}
+/**
+ * Derive the stable DOM `id` for an option row from the listbox id and tag id.
+ * Shared by the option rows (which set it) and the trigger (which references it
+ * via `aria-activedescendant`), so both sides always agree on the same value.
+ */
+export declare const getTagOptionDomId: (listboxId: string, tagId: string) => string;
+/**
+ * Max-width applied to a chip label when `truncateChips` is on, so long labels
+ * ellipsise. Shared by the trigger row and the popover search row - the two
+ * must ellipsise at the same width or truncation reads inconsistent.
+ */
+export declare const TRUNCATE_CHIP_MAX_WIDTH = "max-w-32";
+/**
+ * TagSelector context value.
+ */
+interface TagSelectorContextValue {
+    /**
+     * Id of the option row the keyboard highlight currently points at (null when
+     * the user hasn't arrow-navigated). Referenced by the trigger's
+     * `aria-activedescendant`.
+     */
+    activeId: string | null;
+    /** Whether new tags can be created */
+    allowCreate: boolean;
+    /** Whether tags can be edited/deleted */
+    allowManage: boolean;
+    /** Whether tags can be reordered */
+    allowReorder: boolean;
+    /** Cancel edit */
+    cancelEdit: () => void;
+    /** Available colours for the colour picker */
+    colorPalette: TagColor[];
+    /** Tags matching the current search query, in listbox display order */
+    filteredTags: TagData[];
+    /** Confirm edit */
+    confirmEdit: () => void;
+    /** Whether the popover covers the trigger */
+    coverTrigger: boolean;
+    /** Create a new tag */
+    createTag: (label: string) => void;
+    /** Delete a tag */
+    deleteTag: (id: string) => void;
+    /** ID of tag being edited (null if none) */
+    editingId: string | null;
+    /** Temporary edit value */
+    editValue: string;
+    /** Generated ID for the listbox element (ARIA) */
+    listboxId: string;
+    /**
+     * Cap how many selected chips the trigger renders before collapsing the rest
+     * into a `+N` overflow pill. Undefined renders every chip.
+     */
+    maxVisibleTags: number | undefined;
+    /** Move the active-descendant highlight to the next/previous option row */
+    moveActiveDescendant: (direction: "down" | "up") => void;
+    /** Whether the popover is open */
+    open: boolean;
+    /** Pending colour for the create flow */
+    pendingColor: TagColor | undefined;
+    /** Remove a tag from selection */
+    removeTag: (id: string) => void;
+    /** Consumer override for the drag-and-drop screen-reader announcements. */
+    reorderAnnouncements: Announcements | undefined;
+    /** Reorder tags */
+    reorderTags: (tags: TagData[]) => void;
+    /** Search query */
+    searchQuery: string;
+    /** Set the active-descendant option id (null clears the highlight) */
+    setActiveId: (id: string | null) => void;
+    /** Update edit value */
+    setEditValue: (value: string) => void;
+    /** Set open state */
+    setOpen: (open: boolean) => void;
+    /** Set pending colour */
+    setPendingColor: (color: TagColor | undefined) => void;
+    /** Set search query */
+    setSearchQuery: (query: string) => void;
+    /** Show colour picker swatches in create/edit flows */
+    showColorPicker: boolean;
+    /** Single-select mode: only one tag can be selected at a time */
+    singleSelect: boolean;
+    /** Component size */
+    size: TagSize;
+    /** Start editing a tag */
+    startEditing: (id: string) => void;
+    /** All available tags */
+    tags: TagData[];
+    /** Select/deselect a tag */
+    toggleTag: (tag: TagData) => void;
+    /** Opt-in per-chip CSS truncation for long labels. */
+    truncateChips: boolean;
+    /** Currently selected tags */
+    value: TagData[];
+    /** Whether tags wrap (true) or scroll horizontally (false) */
+    wrapTags: boolean;
+}
+declare const TagSelectorContext: import("react").Context<TagSelectorContextValue | null>;
+/**
+ * Hook to access TagSelector context.
+ * Throws if used outside of TagSelector.
+ */
+export declare const useTagSelectorContext: () => TagSelectorContextValue;
+export type { TagSelectorContextValue };
+export { TagSelectorContext };

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

@@ -0,0 +1,48 @@
+"use client";
+import { createContext, use } from "react";
+/**
+ * Map a stored {@link TagColor} (Dot vocabulary) onto a Tag {@link PillTone}.
+ * `default`/`secondary` both collapse onto the neutral tone.
+ */
+const TAG_COLOR_TO_TONE = {
+    affirmative: "success",
+    brand: "brand",
+    default: "neutral",
+    destructive: "danger",
+    info: "info",
+    secondary: "neutral",
+    warning: "warning",
+};
+export const tagColorToTone = (color) => TAG_COLOR_TO_TONE[color];
+/**
+ * Map a stored {@link TagColor} (Dot vocabulary) onto a {@link DotTone}. Dot's
+ * tone union matches PillTone, so this reuses the same collapse (`default` and
+ * `secondary` → `neutral`). Kept separate so the persisted `TagColor` union is
+ * never renamed (DB values would desync).
+ */
+export const tagColorToDotTone = (color) => TAG_COLOR_TO_TONE[color];
+/**
+ * Derive the stable DOM `id` for an option row from the listbox id and tag id.
+ * Shared by the option rows (which set it) and the trigger (which references it
+ * via `aria-activedescendant`), so both sides always agree on the same value.
+ */
+export const getTagOptionDomId = (listboxId, tagId) => `${listboxId}-option-${tagId}`;
+/**
+ * Max-width applied to a chip label when `truncateChips` is on, so long labels
+ * ellipsise. Shared by the trigger row and the popover search row - the two
+ * must ellipsise at the same width or truncation reads inconsistent.
+ */
+export const TRUNCATE_CHIP_MAX_WIDTH = "max-w-32";
+const TagSelectorContext = createContext(null);
+/**
+ * Hook to access TagSelector context.
+ * Throws if used outside of TagSelector.
+ */
+export const useTagSelectorContext = () => {
+    const context = use(TagSelectorContext);
+    if (!context) {
+        throw new Error("useTagSelectorContext must be used within a TagSelectorProvider");
+    }
+    return context;
+};
+export { TagSelectorContext };

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

@@ -0,0 +1,14 @@
+import type * as React from "react";
+import type { TagData } from "../tag-selector/tag-selector-context.js";
+interface TagSelectorItemProps {
+    /** Whether this tag is selected */
+    selected: boolean;
+    /** The tag data */
+    tag: TagData;
+}
+/**
+ * TagSelectorItem - A draggable tag item with grip handle and action menu.
+ * Supports inline editing, selection, and drag-to-reorder.
+ */
+export declare const TagSelectorItem: ({ tag, selected }: TagSelectorItemProps) => React.JSX.Element;
+export {};

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

@@ -0,0 +1,99 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSortable } from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Check, Ellipsis, GripVertical, Pencil, Trash2 } from "lucide-react";
+import { useEffect, useRef } from "react";
+import { Button } from "../../components/button.js";
+import { Dot } from "../../components/dot.js";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, } from "../../components/dropdown-menu.js";
+import { Flex } from "../../components/flex.js";
+import { Icon } from "../../components/icon.js";
+import { TagSelectorColorSwatches } from "../tag-selector/tag-selector-color-swatches.js";
+import { getTagOptionDomId, tagColorToDotTone, useTagSelectorContext, } from "../tag-selector/tag-selector-context.js";
+/**
+ * Square 24px ghost button for the row's icon controls. A text size keeps the
+ * 16px glyph (icon sizes would shrink it to 12px), and `pressed={false}` stops
+ * the press scale from nudging the row.
+ */
+const ROW_ICON_BUTTON = "text-muted-foreground hover:text-foreground aspect-square px-0";
+/** Label button, or the inline edit input with optional colour picker. */
+const TagItemBody = ({ colorPalette, editValue, inputRef, isEditing, onItemClick, onKeyDown, pendingColor, setEditValue, setPendingColor, showColorPicker, tag, }) => {
+    if (isEditing) {
+        return (_jsxs(Flex, { className: "min-w-0 flex-1 gap-1.5", direction: "column", children: [_jsx("input", { "aria-label": "Edit tag", 
+                    // text-paragraph md:text-paragraph-sm is the input family's iOS idiom (see Textarea):
+                    // ≥16px below md so iOS Safari doesn't zoom on focus, 14px on desktop.
+                    className: cn(focusRing(), "text-paragraph md:text-paragraph-sm min-w-0 bg-transparent", "focus-visible:ring-inset"), onChange: (e) => {
+                        setEditValue(e.target.value);
+                    }, onKeyDown: onKeyDown, ref: inputRef, type: "text", value: editValue }), showColorPicker && colorPalette.length > 0 && (_jsx(TagSelectorColorSwatches, { onSelect: setPendingColor, palette: colorPalette, selected: pendingColor }))] }));
+    }
+    return (_jsx(Button, { align: "start", className: "h-auto min-w-0 flex-1 shrink border-0 px-0 font-normal hover:bg-transparent", emphasis: "ghost", onClick: onItemClick, pressed: false, size: "sm", tone: "neutral", type: "button", children: _jsx("span", { className: "min-w-0 truncate", children: tag.label }) }));
+};
+/** Trailing controls: confirm, selection indicator, actions menu, placeholder. */
+const TagItemControls = ({ allowManage, isEditing, onConfirmEdit, onDeleteTag, onStartEditing, selected, tagId, tagLabel, }) => {
+    // Choosing Edit unmounts this menu. On unmount the menu returns focus to
+    // whatever held it before it opened (often the search field), pulling focus
+    // out of the edit input, so after Edit it returns focus nowhere.
+    const editChosen = useRef(false);
+    return (_jsxs(_Fragment, { children: [isEditing && (_jsx(Button, { "aria-label": "Save tag", className: cn(ROW_ICON_BUTTON, "-mr-1"), emphasis: "ghost", onClick: onConfirmEdit, pressed: false, size: "2xs", tone: "neutral", type: "button", children: _jsx(Icon, { icon: Check, size: "xs" }) })), !isEditing && selected && (_jsx(Icon, { className: "text-foreground shrink-0", icon: Check, size: "xs" })), !isEditing && allowManage && (_jsxs(DropdownMenu, { onOpenChange: (open) => {
+                    if (open) {
+                        editChosen.current = false;
+                    }
+                }, children: [_jsx(DropdownMenuTrigger, { render: (triggerProps) => (_jsx(Button, { ...triggerProps, "aria-label": `Actions for ${tagLabel}`, className: cn(ROW_ICON_BUTTON, "-mr-1"), emphasis: "ghost", onClick: (e) => {
+                                triggerProps.onClick?.(e);
+                                e.stopPropagation();
+                            }, pressed: false, size: "2xs", tone: "neutral", type: "button" })), children: _jsx(Icon, { icon: Ellipsis, size: "xs" }) }), _jsxs(DropdownMenuContent, { align: "end", finalFocus: () => !editChosen.current, sideOffset: 4, children: [_jsx(DropdownMenuItem, { icon: Pencil, onClick: () => {
+                                    editChosen.current = true;
+                                    onStartEditing(tagId);
+                                }, children: "Edit" }), _jsx(DropdownMenuItem, { icon: Trash2, onClick: () => {
+                                    onDeleteTag(tagId);
+                                }, tone: "danger", children: "Delete" })] })] })), !(isEditing || allowManage || selected) && (_jsx("span", { className: "w-4 shrink-0" }))] }));
+};
+const TagItemDragHandle = ({ attributes, isDragging, listeners, tagLabel, }) => (_jsx(Button, { "aria-label": `Reorder ${tagLabel}`, className: cn(ROW_ICON_BUTTON, "-ml-1 cursor-grab touch-none", isDragging && "cursor-grabbing"), emphasis: "ghost", pressed: false, size: "2xs", tone: "neutral", type: "button", ...attributes, ...listeners, children: _jsx(Icon, { icon: GripVertical, size: "xs" }) }));
+/**
+ * TagSelectorItem - A draggable tag item with grip handle and action menu.
+ * Supports inline editing, selection, and drag-to-reorder.
+ */
+export const TagSelectorItem = ({ tag, selected }) => {
+    const inputRef = useRef(null);
+    const { activeId, editingId, editValue, allowReorder, allowManage, listboxId, showColorPicker, colorPalette, pendingColor, setActiveId, setPendingColor, toggleTag, startEditing, setEditValue, confirmEdit, cancelEdit, deleteTag, } = useTagSelectorContext();
+    const isEditing = editingId === tag.id;
+    const isActive = activeId === tag.id;
+    const optionDomId = getTagOptionDomId(listboxId, tag.id);
+    // dnd-kit sortable hook
+    const { attributes, listeners, setNodeRef, transform, transition, isDragging, } = useSortable({
+        disabled: !allowReorder || isEditing,
+        id: tag.id,
+    });
+    // Focus input when entering edit mode
+    useEffect(() => {
+        if (isEditing && inputRef.current) {
+            inputRef.current.focus();
+            inputRef.current.select();
+        }
+    }, [isEditing]);
+    const handleKeyDown = (e) => {
+        if (e.key === "Enter") {
+            e.preventDefault();
+            confirmEdit();
+        }
+        else if (e.key === "Escape") {
+            e.preventDefault();
+            cancelEdit();
+        }
+    };
+    const handleItemClick = () => {
+        if (!isEditing) {
+            toggleTag(tag);
+        }
+    };
+    return (_jsxs(Flex, { align: "center", "aria-selected": selected, className: cn("min-h-10 rounded-full px-4 py-2 transition-colors", "hover:bg-muted/50", isActive && "bg-muted/50", isDragging && "opacity-50"), "data-active": isActive || undefined, "data-component": "tag-selector-item", "data-slot": "tag-selector-item", gap: "xs", id: optionDomId, onPointerMove: () => {
+            if (!(isEditing || isActive)) {
+                setActiveId(tag.id);
+            }
+        }, ref: setNodeRef, 
+        // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role, react-doctor/prefer-tag-over-role -- listbox option row hosting interactive sub-controls (drag handle, label button, actions menu); a native <option> cannot render this content
+        role: "option", style: { transform: CSS.Transform.toString(transform), transition }, children: [allowReorder && (_jsx(TagItemDragHandle, { attributes: attributes, isDragging: isDragging, listeners: listeners, tagLabel: tag.label })), !isEditing && tag.color && (_jsx(Dot, { size: "xs", tone: tagColorToDotTone(tag.color) })), _jsx(TagItemBody, { colorPalette: colorPalette, editValue: editValue, inputRef: inputRef, isEditing: isEditing, onItemClick: handleItemClick, onKeyDown: handleKeyDown, pendingColor: pendingColor, setEditValue: setEditValue, setPendingColor: setPendingColor, showColorPicker: showColorPicker, tag: tag }), _jsx(TagItemControls, { allowManage: allowManage, isEditing: isEditing, onConfirmEdit: confirmEdit, onDeleteTag: deleteTag, onStartEditing: startEditing, selected: selected, tagId: tag.id, tagLabel: tag.label })] }));
+};

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

@@ -0,0 +1,11 @@
+interface TagSelectorListProps {
+    className?: string;
+    /** Custom empty state message */
+    emptyMessage?: string;
+}
+/**
+ * TagSelectorList - Scrollable list of tag items with drag-to-reorder support.
+ * Shows filtered tags based on search query, with "Create" option when no match.
+ */
+export declare const TagSelectorList: ({ emptyMessage, className, }: TagSelectorListProps) => import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,100 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { closestCenter, DndContext, KeyboardSensor, PointerSensor, useSensor, useSensors, } from "@dnd-kit/core";
+import { SortableContext, sortableKeyboardCoordinates, verticalListSortingStrategy, } from "@dnd-kit/sortable";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Plus } from "lucide-react";
+import { useMemo } from "react";
+import { Button } from "../../components/button.js";
+import { Flex } from "../../components/flex.js";
+import { TagSelectorColorSwatches } from "../tag-selector/tag-selector-color-swatches.js";
+import { useTagSelectorContext } from "../tag-selector/tag-selector-context.js";
+import { TagSelectorItem } from "../tag-selector/tag-selector-item.js";
+/**
+ * Keyboard drag instructions announced when a drag handle gains focus. The
+ * package ships no i18n runtime, so these are hardcoded English; override the
+ * per-drag messages via TagSelector's `reorderAnnouncements` prop.
+ */
+const REORDER_SCREEN_READER_INSTRUCTIONS = {
+    draggable: "To reorder a tag, press Space or Enter to pick it up, use the arrow keys to move it, then press Space or Enter again to drop it, or press Escape to cancel.",
+};
+/** Resolve a tag's label from its dnd id (falls back to the raw id). */
+const tagLabelById = (tags, id) => tags.find((t) => t.id === String(id))?.label ?? String(id);
+/** 1-based position of a tag in the list, by its dnd id. */
+const tagPositionById = (tags, id) => tags.findIndex((t) => t.id === String(id)) + 1;
+/**
+ * Default English drag-and-drop announcements, closed over the current tag list
+ * so messages carry labels and 1-based positions. Overridden wholesale by the
+ * `reorderAnnouncements` prop.
+ */
+const buildTagReorderAnnouncements = (tags) => ({
+    onDragCancel: ({ active }) => `Reordering cancelled. Tag ${tagLabelById(tags, active.id)} was returned to its starting position.`,
+    onDragEnd: ({ active, over }) => over
+        ? `Tag ${tagLabelById(tags, active.id)} was dropped at position ${tagPositionById(tags, over.id)} of ${tags.length}.`
+        : `Tag ${tagLabelById(tags, active.id)} was dropped.`,
+    onDragOver: ({ active, over }) => over
+        ? `Tag ${tagLabelById(tags, active.id)} was moved over position ${tagPositionById(tags, over.id)} of ${tags.length}.`
+        : `Tag ${tagLabelById(tags, active.id)} is no longer over a droppable position.`,
+    onDragStart: ({ active }) => `Picked up tag ${tagLabelById(tags, active.id)}.`,
+});
+/** "Create <query>" affordance with optional colour palette, shown when no tag matches. */
+const TagSelectorCreateOption = () => {
+    const { searchQuery, showColorPicker, colorPalette, pendingColor, setPendingColor, createTag, } = useTagSelectorContext();
+    const handleCreateTag = () => {
+        if (searchQuery.trim()) {
+            createTag(searchQuery.trim());
+        }
+    };
+    return (_jsxs(Flex, { className: "bg-muted/50 gap-1.5 rounded-xl px-4 py-2.5", direction: "column", children: [_jsx(Button, { align: "start", className: "h-auto w-full gap-2 border-0 px-0 font-normal hover:bg-transparent hover:opacity-80", emphasis: "ghost", onClick: handleCreateTag, pressed: false, size: "sm", suffixIcon: Plus, suffixIconClassName: "text-muted-foreground", tone: "neutral", type: "button", children: _jsxs("span", { className: "min-w-0 flex-1 truncate text-left", children: ["Create \u201C", searchQuery, "\u201D"] }) }), showColorPicker && colorPalette.length > 0 && (_jsx(TagSelectorColorSwatches, { onSelect: setPendingColor, palette: colorPalette, selected: pendingColor }))] }));
+};
+/** The list of tag rows, with drag-to-reorder support when enabled. */
+const TagSelectorItems = ({ filteredTags, selectedIds, }) => {
+    const { allowReorder, tags, reorderTags, reorderAnnouncements } = useTagSelectorContext();
+    // Stable identity matters: dnd-kit resubscribes its drag monitor whenever
+    // the announcements object changes, so rebuild only when tags actually do.
+    const announcements = useMemo(() => reorderAnnouncements ?? buildTagReorderAnnouncements(tags), [reorderAnnouncements, tags]);
+    // dnd-kit sensors
+    const sensors = useSensors(useSensor(PointerSensor, {
+        activationConstraint: {
+            distance: 8,
+        },
+    }), useSensor(KeyboardSensor, {
+        coordinateGetter: sortableKeyboardCoordinates,
+    }));
+    const handleDragEnd = (event) => {
+        const { active, over } = event;
+        if (over && active.id !== over.id) {
+            const oldIndex = tags.findIndex((tag) => tag.id === active.id);
+            const newIndex = tags.findIndex((tag) => tag.id === over.id);
+            if (oldIndex !== -1 && newIndex !== -1) {
+                const newTags = [...tags];
+                const [removed] = newTags.splice(oldIndex, 1);
+                if (removed) {
+                    newTags.splice(newIndex, 0, removed);
+                    reorderTags(newTags);
+                }
+            }
+        }
+    };
+    if (allowReorder) {
+        return (_jsx(DndContext, { accessibility: {
+                announcements,
+                screenReaderInstructions: REORDER_SCREEN_READER_INSTRUCTIONS,
+            }, collisionDetection: closestCenter, onDragEnd: handleDragEnd, sensors: sensors, children: _jsx(SortableContext, { items: filteredTags.map((t) => t.id), strategy: verticalListSortingStrategy, children: filteredTags.map((tag) => (_jsx(TagSelectorItem, { selected: selectedIds.has(tag.id), tag: tag }, tag.id))) }) }));
+    }
+    return filteredTags.map((tag) => (_jsx(TagSelectorItem, { selected: selectedIds.has(tag.id), tag: tag }, tag.id)));
+};
+/**
+ * TagSelectorList - Scrollable list of tag items with drag-to-reorder support.
+ * Shows filtered tags based on search query, with "Create" option when no match.
+ */
+export const TagSelectorList = ({ emptyMessage = "No tags found.", className, }) => {
+    const { tags, value, searchQuery, allowCreate, filteredTags, listboxId } = useTagSelectorContext();
+    // Check if search query matches any existing tag
+    const exactMatch = tags.some((tag) => tag.label.toLowerCase() === searchQuery.toLowerCase());
+    const showCreateOption = allowCreate && searchQuery !== "" && !exactMatch;
+    const selectedIds = new Set(value.map((t) => t.id));
+    return (_jsx(Flex, { className: cn("max-h-75 overflow-y-auto p-1", className), "data-component": "tag-selector-list", "data-slot": "tag-selector-list", direction: "column", id: listboxId, 
+        // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role, react-doctor/prefer-tag-over-role -- this is a custom listbox widget whose children are interactive TagSelectorItem rows, a drag-to-reorder DndContext, and a "Create" affordance with a colour palette; <datalist>/<select> can only hold plain <option>s, so they cannot represent this content.
+        role: "listbox", children: filteredTags.length === 0 && !showCreateOption ? (_jsx("div", { className: "text-muted-foreground text-paragraph-sm py-6 text-center", children: emptyMessage })) : (_jsxs(_Fragment, { children: [showCreateOption && _jsx(TagSelectorCreateOption, {}), _jsx(TagSelectorItems, { filteredTags: filteredTags, selectedIds: selectedIds })] })) }));
+};

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

@@ -0,0 +1,57 @@
+import type { TagSelectorProps } from "./tag-selector-types.js";
+export type { TagColor, TagData } from "../tag-selector/tag-selector-context.js";
+export type { TagSelectorProps, TagSelectorTriggerRenderProps, } from "./tag-selector-types.js";
+/**
+ * TagSelector - A multi-select tag component with search, create, edit, delete, and reorder capabilities.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with static tags
+ * <TagSelector
+ *   value={selectedTags}
+ *   onChange={setSelectedTags}
+ *   tags={allTags}
+ * />
+ *
+ * // Horizontal scroll mode (no wrapping)
+ * <TagSelector
+ *   value={selectedTags}
+ *   onChange={setSelectedTags}
+ *   tags={allTags}
+ *   wrapTags={false}
+ * />
+ *
+ * // Custom trigger
+ * <TagSelector
+ *   value={selectedTags}
+ *   onChange={setSelectedTags}
+ *   tags={allTags}
+ *   trigger={({ value, open }) => (
+ *     <Button emphasis="outline">
+ *       {value.length > 0 ? `${value.length} selected` : "Select tags"}
+ *     </Button>
+ *   )}
+ * />
+ *
+ * // Full-featured with CRUD
+ * <TagSelector
+ *   value={selectedTags}
+ *   onChange={setSelectedTags}
+ *   tags={allTags}
+ *   onCreateTag={async (label) => api.createTag({ label })}
+ *   onEditTag={async (id, label) => api.updateTag(id, { label })}
+ *   onDeleteTag={async (id) => api.deleteTag(id)}
+ *   onReorder={async (tags) => api.reorderTags(tags.map(t => t.id))}
+ *   allowCreate
+ *   allowReorder
+ *   allowManage
+ * />
+ * ```
+ *
+ * @bestPractice The CRUD affordances are gated - `onCreateTag`/`onEditTag`/`onDeleteTag`/`onReorder` do nothing unless you also set the matching `allowCreate`/`allowManage`/`allowReorder` flag.
+ * @bestPractice `value`/`onChange` carry the selected `TagData[]` and are required - `TagSelector` is controlled; supply the full option set via `tags`.
+ * @bestPractice A custom `trigger` render-prop is passed to `PopoverTrigger` as `render`, so return a single element that forwards its ref/props (e.g. a `Button`).
+ * @bestPractice Use `singleSelect` when only one tag may be chosen; for a fixed, non-editable list prefer `Combobox`/multi-`Select` and reserve `TagSelector` for managing the tag set itself.
+ * @category inputs
+ */
+export declare const TagSelector: (props: TagSelectorProps) => import("react").JSX.Element;

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

@@ -0,0 +1,67 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Popover, PopoverTrigger } from "../../components/popover.js";
+import { TagSelectorContent } from "../tag-selector/tag-selector-content.js";
+import { TagSelectorContext } from "../tag-selector/tag-selector-context.js";
+import { TagSelectorList } from "../tag-selector/tag-selector-list.js";
+import { TagSelectorSearch } from "../tag-selector/tag-selector-search.js";
+import { TagSelectorTrigger } from "../tag-selector/tag-selector-trigger.js";
+import { useTagSelectorState } from "./use-tag-selector.js";
+/**
+ * TagSelector - A multi-select tag component with search, create, edit, delete, and reorder capabilities.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with static tags
+ * <TagSelector
+ *   value={selectedTags}
+ *   onChange={setSelectedTags}
+ *   tags={allTags}
+ * />
+ *
+ * // Horizontal scroll mode (no wrapping)
+ * <TagSelector
+ *   value={selectedTags}
+ *   onChange={setSelectedTags}
+ *   tags={allTags}
+ *   wrapTags={false}
+ * />
+ *
+ * // Custom trigger
+ * <TagSelector
+ *   value={selectedTags}
+ *   onChange={setSelectedTags}
+ *   tags={allTags}
+ *   trigger={({ value, open }) => (
+ *     <Button emphasis="outline">
+ *       {value.length > 0 ? `${value.length} selected` : "Select tags"}
+ *     </Button>
+ *   )}
+ * />
+ *
+ * // Full-featured with CRUD
+ * <TagSelector
+ *   value={selectedTags}
+ *   onChange={setSelectedTags}
+ *   tags={allTags}
+ *   onCreateTag={async (label) => api.createTag({ label })}
+ *   onEditTag={async (id, label) => api.updateTag(id, { label })}
+ *   onDeleteTag={async (id) => api.deleteTag(id)}
+ *   onReorder={async (tags) => api.reorderTags(tags.map(t => t.id))}
+ *   allowCreate
+ *   allowReorder
+ *   allowManage
+ * />
+ * ```
+ *
+ * @bestPractice The CRUD affordances are gated - `onCreateTag`/`onEditTag`/`onDeleteTag`/`onReorder` do nothing unless you also set the matching `allowCreate`/`allowManage`/`allowReorder` flag.
+ * @bestPractice `value`/`onChange` carry the selected `TagData[]` and are required - `TagSelector` is controlled; supply the full option set via `tags`.
+ * @bestPractice A custom `trigger` render-prop is passed to `PopoverTrigger` as `render`, so return a single element that forwards its ref/props (e.g. a `Button`).
+ * @bestPractice Use `singleSelect` when only one tag may be chosen; for a fixed, non-editable list prefer `Combobox`/multi-`Select` and reserve `TagSelector` for managing the tag set itself.
+ * @category inputs
+ */
+export const TagSelector = (props) => {
+    const { className, contextValue, emptyMessage, open, placeholder, searchPlaceholder, setOpen, trigger, value, } = useTagSelectorState(props);
+    return (_jsx(TagSelectorContext.Provider, { value: contextValue, children: _jsx(Popover, { onOpenChange: setOpen, open: open, children: _jsxs("div", { className: cn("relative", className), "data-component": "tag-selector", "data-slot": "tag-selector", children: [trigger ? (_jsx(PopoverTrigger, { render: trigger({ open, placeholder, value }) })) : (_jsx(TagSelectorTrigger, { placeholder: placeholder })), _jsxs(TagSelectorContent, { children: [_jsx(TagSelectorSearch, { placeholder: searchPlaceholder }), _jsx(TagSelectorList, { emptyMessage: emptyMessage })] })] }) }) }));
+};

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

@@ -0,0 +1,17 @@
+import type * as React from "react";
+interface TagSelectorSearchProps {
+    className?: string;
+    /** Placeholder text for search input */
+    placeholder?: string;
+}
+/**
+ * TagSelectorSearch - Search input area with selected tags display.
+ * Shows selected tags inline with the search input.
+ *
+ * The field is the `Input` primitive with its shell stripped - see the
+ * className comment at the usage below. `role="combobox"` semantics live on
+ * the trigger; here the input only carries
+ * `aria-activedescendant`/`aria-controls` pointing at the listbox.
+ */
+export declare const TagSelectorSearch: ({ placeholder, className, }: TagSelectorSearchProps) => React.JSX.Element;
+export {};

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

@@ -0,0 +1,91 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useEffect, useRef } from "react";
+import { Flex } from "../../components/flex.js";
+import { Input } from "../../components/input.js";
+import { Tag } from "../../components/tag.js";
+import { getTagOptionDomId, tagColorToDotTone, tagColorToTone, TRUNCATE_CHIP_MAX_WIDTH, useTagSelectorContext, } from "../tag-selector/tag-selector-context.js";
+/** The selected tags shown inline ahead of the search field. */
+const SelectedTagChips = ({ removeTag, truncateChips, value, }) => {
+    const chipClassName = truncateChips ? TRUNCATE_CHIP_MAX_WIDTH : undefined;
+    return (_jsx(_Fragment, { children: value.map((tag) => tag.color ? (_jsx(Tag, { className: chipClassName, dot: tagColorToDotTone(tag.color), emphasis: "soft", onDismiss: () => {
+                removeTag(tag.id);
+            }, size: "sm", tone: tagColorToTone(tag.color), children: tag.label }, tag.id)) : (_jsx(Tag, { asInput: true, className: chipClassName, onDismiss: () => {
+                removeTag(tag.id);
+            }, size: "sm", children: tag.label }, tag.id))) }));
+};
+/**
+ * TagSelectorSearch - Search input area with selected tags display.
+ * Shows selected tags inline with the search input.
+ *
+ * The field is the `Input` primitive with its shell stripped - see the
+ * className comment at the usage below. `role="combobox"` semantics live on
+ * the trigger; here the input only carries
+ * `aria-activedescendant`/`aria-controls` pointing at the listbox.
+ */
+export const TagSelectorSearch = ({ placeholder = "Search tags…", className, }) => {
+    const inputRef = useRef(null);
+    const { activeId, value, searchQuery, setSearchQuery, removeTag, tags, allowCreate, createTag, filteredTags, listboxId, moveActiveDescendant, toggleTag, open, truncateChips, } = useTagSelectorContext();
+    const activeDescendantId = open && activeId !== null
+        ? getTagOptionDomId(listboxId, activeId)
+        : undefined;
+    // Auto-focus input when popover opens
+    useEffect(() => {
+        if (open && inputRef.current) {
+            inputRef.current.focus();
+        }
+    }, [open]);
+    const handleKeyDown = (e) => {
+        if (e.key === "ArrowDown") {
+            e.preventDefault();
+            moveActiveDescendant("down");
+            return;
+        }
+        if (e.key === "ArrowUp") {
+            e.preventDefault();
+            moveActiveDescendant("up");
+            return;
+        }
+        if (e.key === "Backspace" && searchQuery === "" && value.length > 0) {
+            // Remove last tag on Backspace when input is empty
+            const lastTag = value.at(-1);
+            if (lastTag) {
+                removeTag(lastTag.id);
+            }
+        }
+        else if (e.key === "Enter") {
+            // A highlighted option (reached via arrow keys) takes priority: toggle it.
+            const activeTag = activeId === null
+                ? undefined
+                : filteredTags.find((tag) => tag.id === activeId);
+            if (activeTag) {
+                e.preventDefault();
+                toggleTag(activeTag);
+                setSearchQuery("");
+                return;
+            }
+            if (searchQuery.trim()) {
+                e.preventDefault();
+                const trimmed = searchQuery.trim();
+                const exactMatch = tags.find((tag) => tag.label.toLowerCase() === trimmed.toLowerCase());
+                if (exactMatch) {
+                    toggleTag(exactMatch);
+                    setSearchQuery("");
+                }
+                else if (allowCreate) {
+                    createTag(trimmed);
+                }
+            }
+        }
+    };
+    return (_jsxs(Flex, { align: "center", className: cn("border-border border-b px-4 py-3.5", className), "data-component": "tag-selector-search", "data-slot": "tag-selector-search", gap: "xs", wrap: "wrap", children: [_jsx(SelectedTagChips, { removeTag: removeTag, truncateChips: truncateChips, value: value }), _jsx(Input, { "aria-activedescendant": activeDescendantId, "aria-controls": listboxId, "aria-label": "Search tags", 
+                // Strip the Input shell (border, fill, shadow, fixed height, radius) so
+                // it reads as a bare field in the chip row, while still routing through
+                // the primitive + its focusInput() token. rounded-none keeps the inset
+                // focus ring square - pixel-identical to the pre-recompose raw input.
+                // text-paragraph md:text-paragraph-sm - see Textarea's iOS-zoom idiom.
+                className: cn("text-paragraph md:text-paragraph-sm h-auto min-w-20 flex-1 rounded-none border-0 bg-transparent px-0 py-0 shadow-none", "focus-visible:ring-inset"), onChange: (e) => {
+                    setSearchQuery(e.target.value);
+                }, onKeyDown: handleKeyDown, placeholder: value.length === 0 ? placeholder : "", ref: inputRef, type: "text", value: searchQuery })] }));
+};