@intentface/ui 0.0.0-stage → 0.7.0

package/dist/composer/attachments-machine.d.ts

@@ -0,0 +1,34 @@
+import { type AttachmentErrorCode, type AttachmentItem } from "../attachments/index.js";
+export type AttachmentStoreState = {
+    items: AttachmentItem[];
+    error: AttachmentErrorCode | null;
+};
+export type AttachmentStoreAction = {
+    type: "add";
+    files: File[] | FileList;
+} | {
+    type: "remove";
+    id: string;
+} | {
+    type: "reset";
+};
+export type AttachmentStoreConfig = {
+    accept: string;
+    maxFiles: number;
+    maxFileSize: number;
+    convert: (file: File) => AttachmentItem;
+    destroy: (item: AttachmentItem) => void;
+};
+export declare const INITIAL_ATTACHMENT_STATE: AttachmentStoreState;
+export declare const attachmentReducer: (state: AttachmentStoreState, action: AttachmentStoreAction, config: AttachmentStoreConfig) => AttachmentStoreState;
+export type DragHandlerCallbacks = {
+    isInScope: (event: DragEvent) => boolean;
+    onFiles: (files: FileList) => void;
+    setDragging: (active: boolean) => void;
+};
+export declare const createDragHandlers: (callbacks: DragHandlerCallbacks) => {
+    onDragOver: (event: Event) => void;
+    onDragEnter: (event: Event) => void;
+    onDragLeave: (event: Event) => void;
+    onDrop: (event: Event) => void;
+};

package/dist/composer/attachments-machine.js

@@ -0,0 +1,91 @@
+// Attachments — pure store reducer that validates and accumulates files, plus
+// the drag-and-drop handler factory. The store owns the state cell; this owns
+// the rules.
+import { matchesAccept } from "../attachments/index.js";
+export const INITIAL_ATTACHMENT_STATE = {
+    items: [],
+    error: null,
+};
+export const attachmentReducer = (state, action, config) => {
+    switch (action.type) {
+        case "add": {
+            const incoming = [...action.files];
+            if (!incoming.length)
+                return state;
+            const accepted = incoming.filter((file) => matchesAccept(file, config.accept));
+            if (!accepted.length) {
+                return { ...state, error: "accept" };
+            }
+            const sized = accepted.filter((file) => file.size <= config.maxFileSize);
+            if (!sized.length) {
+                return { ...state, error: "max_file_size" };
+            }
+            const capacity = Math.max(0, config.maxFiles - state.items.length);
+            const capped = sized.slice(0, capacity);
+            const overCapacityError = sized.length > capacity ? "max_files" : null;
+            if (!capped.length) {
+                return { ...state, error: overCapacityError ?? state.error };
+            }
+            return {
+                items: [...state.items, ...capped.map(config.convert)],
+                error: overCapacityError,
+            };
+        }
+        case "remove": {
+            const found = state.items.find((item) => item.id === action.id);
+            if (found)
+                config.destroy(found);
+            return {
+                items: state.items.filter((item) => item.id !== action.id),
+                error: null,
+            };
+        }
+        case "reset": {
+            for (const item of state.items)
+                config.destroy(item);
+            return INITIAL_ATTACHMENT_STATE;
+        }
+    }
+};
+export const createDragHandlers = (callbacks) => {
+    const counter = { current: 0 };
+    const carriesFiles = (event) => event.dataTransfer?.types?.includes("Files") ?? false;
+    return {
+        onDragOver: (event) => {
+            const dragEvent = event;
+            if (!callbacks.isInScope(dragEvent))
+                return;
+            if (carriesFiles(dragEvent))
+                dragEvent.preventDefault();
+        },
+        onDragEnter: (event) => {
+            const dragEvent = event;
+            if (!callbacks.isInScope(dragEvent))
+                return;
+            if (carriesFiles(dragEvent)) {
+                counter.current++;
+                callbacks.setDragging(true);
+            }
+        },
+        onDragLeave: (event) => {
+            const dragEvent = event;
+            if (!callbacks.isInScope(dragEvent))
+                return;
+            counter.current--;
+            if (counter.current === 0)
+                callbacks.setDragging(false);
+        },
+        onDrop: (event) => {
+            const dragEvent = event;
+            if (!callbacks.isInScope(dragEvent))
+                return;
+            if (carriesFiles(dragEvent))
+                dragEvent.preventDefault();
+            counter.current = 0;
+            callbacks.setDragging(false);
+            const files = dragEvent.dataTransfer?.files;
+            if (files && files.length > 0)
+                callbacks.onFiles(files);
+        },
+    };
+};

package/dist/composer/attachments.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from "react";
+import { type AttachmentItem } from "../attachments/index.js";
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+export type ComposerAttachmentsProps = {
+    convert?: (file: File) => AttachmentItem;
+    destroy?: (item: AttachmentItem) => void;
+    accept?: string;
+    maxFiles?: number;
+    maxFileSize?: number;
+    multiple?: boolean;
+    globalDrop?: boolean;
+    children?: ReactNode;
+};
+export declare const ComposerAttachments: ({ convert, destroy, accept, maxFiles, maxFileSize, multiple, globalDrop, children, }: ComposerAttachmentsProps) => import("react").JSX.Element;
+export type ComposerAttachmentTriggerProps = PrimitiveProps<"button">;
+export declare const ComposerAttachmentTrigger: ({ className, render, style, ...elementProps }: ComposerAttachmentTriggerProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/composer/attachments.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { revokeAttachmentUrl, toAttachmentItem } from "../attachments/index.js";
+import { useRenderElement } from "../internal/render/useRenderElement.js";
+import { useComposer, useComposerContextStore } from "./store.js";
+export const ComposerAttachments = ({ convert = toAttachmentItem, destroy = revokeAttachmentUrl, accept = "", maxFiles = Number.POSITIVE_INFINITY, maxFileSize = Number.POSITIVE_INFINITY, multiple = true, globalDrop = false, children, }) => {
+    const store = useComposerContextStore();
+    const attachments = useComposer((composer) => composer.attachments);
+    store.attachmentConfigRef.current = { accept, maxFiles, maxFileSize, convert, destroy };
+    attachments.globalDropRef.current = globalDrop;
+    const handleFileChange = (event) => {
+        if (event.currentTarget.files) {
+            attachments.add(event.currentTarget.files);
+        }
+        event.currentTarget.value = "";
+    };
+    return (_jsxs(_Fragment, { children: [_jsx("input", { accept: accept, style: { display: "none" }, multiple: multiple, onChange: handleFileChange, ref: attachments.fileInputRef, type: "file" }), children] }));
+};
+export const ComposerAttachmentTrigger = ({ className, render, style, ...elementProps }) => {
+    const attachments = useComposer((composer) => composer.attachments);
+    return useRenderElement("button", { className, render, style }, {
+        props: [
+            {
+                // Default overridable name — the trigger is typically icon-only.
+                "aria-label": "Add attachment",
+                "data-composer-attachment-trigger": "",
+                onClick: () => attachments.openFileDialog(),
+            },
+            elementProps,
+        ],
+    });
+};

package/dist/composer/command-list.d.ts

@@ -0,0 +1,49 @@
+import { type ComponentProps, type ReactNode } from "react";
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+import { Commands } from "./commands.js";
+import type { CommandItemData } from "./types.js";
+export type CommandListState = "loading" | "empty" | "ready";
+export declare const optionDomId: (listboxId: string, value: string) => string;
+export type ComposerCommandState = {
+    /** Present as data-loading while an async items callback is in flight. */
+    loading: boolean;
+    /** Present as data-empty when nothing matches the query. */
+    empty: boolean;
+};
+export type ComposerCommandProps = PrimitiveProps<"div", ComposerCommandState> & {
+    prefix: string;
+};
+export declare const ComposerCommand: ({ prefix, className, render, style, children, ...elementProps }: ComposerCommandProps) => import("react").JSX.Element | null;
+export declare const useCommandListItems: <Item extends CommandItemData = CommandItemData>() => {
+    items: Item[];
+    state: CommandListState;
+};
+export type ComposerCommandListProps<Item extends CommandItemData> = Omit<PrimitiveProps<"div">, "children"> & {
+    children: (item: Item) => ReactNode;
+};
+export declare const ComposerCommandList: <Item extends CommandItemData>({ className, render, style, children: renderItem, ...elementProps }: ComposerCommandListProps<Item>) => ReactNode;
+export type ComposerCommandLoadingProps = PrimitiveProps<"div">;
+export declare const ComposerCommandLoading: ({ children, className, render, style, ...elementProps }: ComposerCommandLoadingProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ComposerCommandEmptyProps = PrimitiveProps<"div">;
+export declare const ComposerCommandEmpty: ({ children, className, render, style, ...elementProps }: ComposerCommandEmptyProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ComposerCommandDismissProps = PrimitiveProps<"button">;
+export declare const ComposerCommandDismiss: ({ children, className, render, style, ...elementProps }: ComposerCommandDismissProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ComposerCommandItemProps = Omit<ComponentProps<typeof Commands.Item>, "highlighted" | "disabled"> & {
+    value: string;
+};
+export declare const ComposerCommandItem: ({ value, ...props }: ComposerCommandItemProps) => import("react").JSX.Element;
+export type ComposerCommandItemIconProps = PrimitiveProps<"span">;
+export declare const ComposerCommandItemIcon: ({ className, render, style, ...elementProps }: ComposerCommandItemIconProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ComposerCommandItemLabelProps = PrimitiveProps<"span">;
+export declare const ComposerCommandItemLabel: ({ className, render, style, ...elementProps }: ComposerCommandItemLabelProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ComposerCommandItemDescriptionProps = PrimitiveProps<"span">;
+export declare const ComposerCommandItemDescription: ({ className, render, style, ...elementProps }: ComposerCommandItemDescriptionProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type ComposerCommandGroupProps<Item extends CommandItemData = CommandItemData> = {
+    /** Bucket the resolved items by this key (defines the app's grouping taxonomy). */
+    groupBy: (item: Item) => string;
+    /** Render one group: its key + that group's already-filtered items. */
+    children: (group: string, items: Item[]) => ReactNode;
+};
+export declare const ComposerCommandGroup: <Item extends CommandItemData = CommandItemData>({ groupBy, children: renderGroup, }: ComposerCommandGroupProps<Item>) => ReactNode;
+export type ComposerCommandGroupLabelProps = PrimitiveProps<"div">;
+export declare const ComposerCommandGroupLabel: ({ className, render, style, ...elementProps }: ComposerCommandGroupLabelProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/composer/command-list.js

@@ -0,0 +1,360 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+// Composer.Command family — resolution (sync/async items, fuzzy filter),
+// keyboard/mouse selection, chip insertion, dismissal, and the nav/items
+// context split (highlight changes don't re-render the items map, and items
+// mutations don't re-render every row). All unstyled; state panels as
+// data-state / data-highlighted.
+import { createContext, Fragment, use, useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { useRenderElement } from "../internal/render/useRenderElement.js";
+import { Commands } from "./commands.js";
+import { filterArrayItems, suggestionRemainder } from "./fuzzy.js";
+import { useAsRef, useComposerInternals, useIsomorphicLayoutEffect } from "./internals.js";
+import { useComposer, useComposerContextStore } from "./store.js";
+const CommandListNavContext = createContext(null);
+const CommandListItemsContext = createContext(null);
+// ---------------------------------------------------------------------------
+// Item resolution — turn the prefix's items config (array or async callback)
+// into the current filtered list + loading/empty/ready state.
+// ---------------------------------------------------------------------------
+const useResolvedItems = (itemsProp, query, isActive) => {
+    const isCallback = typeof itemsProp === "function";
+    const [asyncState, setAsyncState] = useState(() => ({ items: [], loading: isCallback }));
+    useEffect(() => {
+        if (typeof itemsProp !== "function")
+            return;
+        if (!isActive)
+            return;
+        const controller = new AbortController();
+        let cancelled = false;
+        let result;
+        try {
+            result = itemsProp(query, { signal: controller.signal });
+        }
+        catch (error) {
+            console.warn("Composer.commands items callback threw:", error);
+            setAsyncState({ items: [], loading: false });
+            return () => {
+                cancelled = true;
+                controller.abort();
+            };
+        }
+        if (result instanceof Promise) {
+            setAsyncState((previous) => ({ ...previous, loading: true }));
+            result.then((resolved) => {
+                if (cancelled)
+                    return;
+                setAsyncState({ items: resolved, loading: false });
+            }, (error) => {
+                if (cancelled)
+                    return;
+                if (error?.name === "AbortError")
+                    return;
+                console.warn("Composer.commands items callback rejected:", error);
+                setAsyncState((previous) => ({ ...previous, loading: false }));
+            });
+        }
+        else {
+            setAsyncState({ items: result, loading: false });
+        }
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [itemsProp, query, isActive]);
+    if (Array.isArray(itemsProp)) {
+        const items = filterArrayItems(itemsProp, query);
+        return { items, state: items.length === 0 ? "empty" : "ready" };
+    }
+    if (asyncState.loading) {
+        // Locally filter the most-recent resolved set so typing feels instant
+        // while the new fetch is in flight. The server result replaces this once
+        // it lands.
+        return {
+            items: filterArrayItems(asyncState.items, query),
+            state: "loading",
+        };
+    }
+    return {
+        items: asyncState.items,
+        state: asyncState.items.length === 0 ? "empty" : "ready",
+    };
+};
+// ---------------------------------------------------------------------------
+// Composer.Command — the orchestrator: resolves items for the active
+// prefix, owns the highlight/selection/dismiss logic, and provides the two
+// contexts. Renders null unless this prefix is the active one.
+// ---------------------------------------------------------------------------
+const EMPTY_ITEMS = [];
+// Deterministic option-row id shared by the row itself and the editor's
+// aria-activedescendant. Values sanitize to valid id tokens.
+export const optionDomId = (listboxId, value) => `${listboxId}-option-${value.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+// The badge's hint chrome: non-editable so the caret can't enter it, no chip
+// id so the reader/mappers treat it as zero-width presentation, aria-hidden
+// so screen readers skip the ghost. Styled via its part attribute like any other part.
+const createHintElement = (badge) => {
+    const hint = badge.ownerDocument.createElement("span");
+    hint.setAttribute("data-command-hint", "");
+    hint.setAttribute("contenteditable", "false");
+    hint.setAttribute("aria-hidden", "true");
+    badge.appendChild(hint);
+    return hint;
+};
+export const ComposerCommand = ({ prefix, className, render, style, children, ...elementProps }) => {
+    const store = useComposerContextStore();
+    const internals = useComposerInternals();
+    // Renders while this prefix is the active one AND through its close animation. `active`
+    // flips false the instant the trigger closes, but the store keeps `present` sticky until
+    // the Panel's exit animation finishes (finalizePanelClose). `wasActive` marks that this
+    // prefix — not a sibling — is the one closing, so only it keeps rendering during the window.
+    const isActive = useComposer((composer) => composer.commands.active && composer.commands.trigger === prefix);
+    const present = useComposer((composer) => composer.commands.present);
+    const query = useComposer((composer) => composer.commands.query);
+    // State adjusted during render (not a ref React might keep from a discarded
+    // render); it only flips at open and at the end of the close, so it costs a
+    // re-render at those two moments and nowhere else.
+    const [wasActive, setWasActive] = useState(false);
+    if (isActive && !wasActive)
+        setWasActive(true);
+    else if (!isActive && !present && wasActive)
+        setWasActive(false);
+    const isPresent = isActive || (present && wasActive);
+    const config = internals.commands[prefix];
+    const itemsProp = config?.items ?? EMPTY_ITEMS;
+    const kind = config?.kind ?? "execute";
+    // Freeze the last resolved items while closing so the exiting panel shows what it had,
+    // not a re-filter/re-fetch against the now-empty query.
+    const resolved = useResolvedItems(itemsProp, query, isActive);
+    const lastResolvedRef = useRef(resolved);
+    if (isActive)
+        lastResolvedRef.current = resolved;
+    const { items, state } = isActive ? resolved : lastResolvedRef.current;
+    // The highlight index lives in the store (so the editor's keydown handler can
+    // move it). It's raw/unbounded; wrap it by the current item count here. The
+    // wrap runs over the enabled subset only, so disabled rows render but never
+    // take the highlight — arrow keys hop over them for free. An empty list has
+    // no highlighted row — the "No results" row stands in as the sole selectable.
+    const enabledItems = useMemo(() => items.filter((item) => !item.disabled), [items]);
+    const highlightIndex = useComposer((composer) => composer.commands.highlightIndex);
+    const activeIndex = enabledItems.length > 0
+        ? ((highlightIndex % enabledItems.length) + enabledItems.length) % enabledItems.length
+        : -1;
+    const highlightedItem = enabledItems[activeIndex] ?? null;
+    const effectiveHighlight = highlightedItem?.value ?? null;
+    // Badge hint — one real element (span[data-command-hint], appended
+    // inside the badge) carrying either the ghost-text completion of the
+    // highlighted item or the per-prefix empty-query placeholder. One slot, one
+    // value: the suggestion wins by a plain ?? chain, so exclusivity is code,
+    // not CSS specificity. The reader and position mappers treat non-editable,
+    // non-chip elements as zero-width presentation, so the hint never reaches
+    // the model. The badge is engine-owned DOM out of JSX reach — same access
+    // pattern as the popover's anchor query — so this is a true DOM-integration
+    // effect. No deps: badge identity changes on token rewraps, which always
+    // coincide with a re-render here (query/highlight subscribed).
+    const suggestion = isActive && highlightedItem && (config?.suggestion ?? true)
+        ? suggestionRemainder(query, highlightedItem.label)
+        : null;
+    const hintText = suggestion ?? (isActive && query === "" ? (config?.placeholder ?? "Type to filter") : null);
+    useIsomorphicLayoutEffect(() => {
+        const badge = store.editorRef.current?.getRootElement()?.querySelector("[data-command-badge]");
+        const existingHint = badge?.querySelector("[data-command-hint]") ?? null;
+        if (!badge || !hintText) {
+            existingHint?.remove();
+            return;
+        }
+        const hint = existingHint ?? createHintElement(badge);
+        if (hint.textContent !== hintText)
+            hint.textContent = hintText;
+    });
+    // Mirror the highlighted row's DOM id into the store — the editor renders
+    // it as aria-activedescendant. This is where the raw highlight index
+    // resolves against the actual item list, so the id can only be derived here.
+    // Only the ACTIVE command writes: with several Commands mounted, an inactive
+    // sibling writing null would ping-pong against the active one's id forever
+    // (max-update-depth). Clearing on close is setCommands' job.
+    useIsomorphicLayoutEffect(() => {
+        if (!isActive)
+            return;
+        store.setActiveOptionId(highlightedItem ? optionDomId(store.listboxId, highlightedItem.value) : null);
+    });
+    const selectByValue = useCallback((value) => {
+        const editor = store.editorRef.current;
+        if (!editor)
+            return;
+        const item = items.find((candidate) => candidate.value === value);
+        if (!item || item.disabled)
+            return;
+        if (kind === "insert") {
+            editor.insertChipAtTrigger({
+                prefix,
+                value: item.value,
+                label: item.label ?? item.value,
+                icon: item.icon,
+            });
+        }
+        else {
+            editor.deleteTrigger();
+            // Read the attachment actions lazily at selection time — their
+            // identities are store-stable, so subscribing would only re-render the
+            // list on unrelated attachment changes.
+            const { add, remove, openFileDialog } = store.getSnapshot().attachments;
+            const onSelectContext = {
+                editor: store.controller,
+                attachments: { add, remove, openFileDialog },
+            };
+            item.onSelect?.(onSelectContext);
+        }
+        editor.closeCommands();
+    }, [store, items, kind, prefix]);
+    const dismiss = useCallback(() => {
+        store.editorRef.current?.dismissCommands();
+    }, [store]);
+    // The editor's keydown handler invokes the current selection through
+    // commandSelectRef. Keep the latest values in a ref so the callback stays
+    // stable, and register it via the root's callback ref (commit-time) — not an
+    // effect, not a render-phase assignment.
+    const selectState = useAsRef({ effectiveHighlight, selectByValue, dismiss, state });
+    const runSelect = useCallback(() => {
+        const { effectiveHighlight, selectByValue, dismiss, state } = selectState.current;
+        // With a match, select it. When empty, the "No results" row is the sole
+        // option and selecting it dismisses — so Tab/Enter aren't dead (Linear-style).
+        if (effectiveHighlight)
+            selectByValue(effectiveHighlight);
+        else if (state === "empty")
+            dismiss();
+    }, []);
+    const registerSelect = useCallback((node) => {
+        store.commandSelectRef.current = node ? runSelect : null;
+    }, [store, runSelect]);
+    // Scroll the highlighted row into view as it becomes the highlight. Stable, so
+    // React calls it only on highlight change — no per-render scroll, no effect.
+    //
+    // container:"nearest" hard-scopes the scroll to the list on Chromium.
+    // Safari/Firefox silently ignore the member (unknown dictionary keys) and
+    // run an UNSCOPED block:"nearest" — scrollIntoView then scrolls every
+    // ancestor scrolling box, the window included, whenever the row isn't
+    // viewport-visible.
+    //
+    // KNOWN BUG (accepted 2026-07-10): on Safari, arrowing through the list
+    // while the popup opens can scroll the page behind it (reproduced; the
+    // positioner's viewport containment is not sufficient there). Accepted in
+    // exchange for native scroll-padding support and −24 lines; goes away when
+    // WebKit ships `container`. If it starts to hurt sooner, the scoped manual
+    // implementation lives in this function's git history (PR #39, first
+    // commit).
+    const scrollHighlightedIntoView = useCallback((node) => {
+        // Cast: lib.dom doesn't know the `container` member yet (Chromium-only).
+        node?.scrollIntoView({ block: "nearest", container: "nearest" });
+    }, []);
+    const navContext = useMemo(() => ({
+        highlightedValue: effectiveHighlight,
+        setHighlightedValue: (value) => {
+            const index = value === null ? -1 : enabledItems.findIndex((item) => item.value === value);
+            if (index >= 0)
+                store.setHighlight(index);
+        },
+        selectByValue,
+        dismiss,
+        scrollHighlightedIntoView,
+    }), [effectiveHighlight, enabledItems, selectByValue, dismiss, scrollHighlightedIntoView, store]);
+    const itemsContext = useMemo(() => ({ items, state }), [items, state]);
+    const element = useRenderElement("div", { className, render, style }, {
+        enabled: isPresent,
+        state: { loading: state === "loading", empty: state === "empty" },
+        ref: registerSelect,
+        props: [{ "data-composer-command-list": "", children }, elementProps],
+    });
+    if (!isPresent)
+        return null;
+    return (_jsx(CommandListItemsContext, { value: itemsContext, children: _jsx(CommandListNavContext, { value: navContext, children: element }) }));
+};
+// ---------------------------------------------------------------------------
+// List hooks — the consumer-facing items hook and the internal nav accessor
+// the slot primitives read.
+// ---------------------------------------------------------------------------
+export const useCommandListItems = () => {
+    const context = use(CommandListItemsContext);
+    if (!context) {
+        throw new Error("<Composer.CommandList> must be rendered inside <Composer.Command>.");
+    }
+    return context;
+};
+const useCommandListNav = (componentName) => {
+    const context = use(CommandListNavContext);
+    if (!context) {
+        throw new Error(`<Composer.${componentName}> must be rendered inside <Composer.Command>.`);
+    }
+    return context;
+};
+export const ComposerCommandList = ({ className, render, style, children: renderItem, ...elementProps }) => {
+    const { items, state } = useCommandListItems();
+    const store = useComposerContextStore();
+    return useRenderElement("div", { className, render, style }, {
+        props: [
+            {
+                // The combobox popup: the editor references this element via
+                // aria-controls and points aria-activedescendant at its rows.
+                role: "listbox",
+                id: store.listboxId,
+                "aria-label": "Suggestions",
+                "aria-busy": state === "loading" || undefined,
+                "data-composer-command-items": "",
+                children: items.map((item, index) => (_jsx(Fragment, { children: renderItem(item) }, item.value ?? `__cmd_${index}`))),
+            },
+            elementProps,
+        ],
+    });
+};
+export const ComposerCommandLoading = ({ children, className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, {
+    props: [{ "data-composer-command-loading": "", children }, elementProps],
+});
+export const ComposerCommandEmpty = ({ children, className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, {
+    props: [{ role: "status", "data-composer-command-empty": "", children }, elementProps],
+});
+export const ComposerCommandDismiss = ({ children, className, render, style, ...elementProps }) => {
+    const navContext = useCommandListNav("CommandDismiss");
+    return useRenderElement("button", { className, render, style }, {
+        props: [
+            {
+                tabIndex: -1,
+                "data-composer-command-dismiss": "",
+                onMouseDown: (event) => {
+                    event.preventDefault();
+                    navContext.dismiss();
+                },
+                children,
+            },
+            elementProps,
+        ],
+    });
+};
+export const ComposerCommandItem = ({ value, ...props }) => {
+    const navContext = useCommandListNav("CommandItem");
+    const itemsContext = use(CommandListItemsContext);
+    const store = useComposerContextStore();
+    const isHighlighted = navContext.highlightedValue === value;
+    // Disabled comes from the item data (CommandItemData.disabled) — the same
+    // source the nav wrap skips — so the row can never disagree with the
+    // keyboard behavior. Not a prop: two writers would let them drift.
+    const isDisabled = itemsContext?.items.some((item) => item.value === value && item.disabled) ?? false;
+    return (_jsx(Commands.Item, { ref: isHighlighted ? navContext.scrollHighlightedIntoView : undefined, id: optionDomId(store.listboxId, value), "aria-selected": isHighlighted, "data-composer-command-item": "", highlighted: isHighlighted, disabled: isDisabled, onMouseDown: (event) => {
+            // preventDefault even when disabled — the click must never steal
+            // focus from the editor.
+            event.preventDefault();
+            if (!isDisabled)
+                navContext.selectByValue(value);
+        }, onMouseEnter: isDisabled ? undefined : () => navContext.setHighlightedValue(value), ...props }));
+};
+export const ComposerCommandItemIcon = ({ className, render, style, ...elementProps }) => useRenderElement("span", { className, render, style }, { props: [{ "data-composer-command-item-icon": "" }, elementProps] });
+export const ComposerCommandItemLabel = ({ className, render, style, ...elementProps }) => useRenderElement("span", { className, render, style }, { props: [{ "data-composer-command-item-label": "" }, elementProps] });
+export const ComposerCommandItemDescription = ({ className, render, style, ...elementProps }) => useRenderElement("span", { className, render, style }, { props: [{ "data-composer-command-item-description": "" }, elementProps] });
+// Grouping is a render concern: this reads the resolved items, buckets them by `groupBy`
+// with `Map.groupBy` (which preserves first-appearance order — Object.groupBy would reorder
+// integer-like keys), and renders the child once per group inside a `command-group`
+// container. Nav order stays store-driven, so a group whose items all filter out just
+// doesn't render. Annotate `groupBy`'s param to type the items (no inline JSX generic).
+export const ComposerCommandGroup = ({ groupBy, children: renderGroup, }) => {
+    const { items } = useCommandListItems();
+    return (_jsx(_Fragment, { children: [...Map.groupBy(items, groupBy)].map(([group, groupItems]) => (_jsx(Commands.Group, { children: renderGroup(group, groupItems) }, group))) }));
+};
+export const ComposerCommandGroupLabel = ({ className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, { props: [{ "data-composer-command-group-label": "" }, elementProps] });

package/dist/composer/commands.d.ts

@@ -0,0 +1,28 @@
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+type CommandsRootProps = PrimitiveProps<"div">;
+type CommandsGroupProps = PrimitiveProps<"div">;
+type CommandsGroupLabelProps = PrimitiveProps<"div">;
+export type CommandsItemState = {
+    /** Present as data-highlighted while keyboard/hover highlighted. */
+    highlighted: boolean;
+    /** Present as data-disabled while the row is inert. */
+    disabled: boolean;
+};
+export type CommandsItemProps = PrimitiveProps<"button", CommandsItemState> & {
+    highlighted?: boolean;
+    disabled?: boolean;
+};
+type CommandsItemLabelProps = PrimitiveProps<"span">;
+type CommandsItemDescriptionProps = PrimitiveProps<"span">;
+type CommandsEmptyProps = PrimitiveProps<"div">;
+type CommandsFooterProps = PrimitiveProps<"div">;
+export declare const Commands: (({ className, render, style, ...elementProps }: CommandsRootProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>) & {
+    Group: ({ className, render, style, ...elementProps }: CommandsGroupProps) => import("react").JSX.Element;
+    GroupLabel: ({ className, render, style, ...elementProps }: CommandsGroupLabelProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    Item: ({ highlighted, disabled, className, render, style, ...elementProps }: CommandsItemProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    ItemLabel: ({ className, render, style, ...elementProps }: CommandsItemLabelProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    ItemDescription: ({ className, render, style, ...elementProps }: CommandsItemDescriptionProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    Empty: ({ children, className, render, style, ...elementProps }: CommandsEmptyProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+    Footer: ({ className, render, style, ...elementProps }: CommandsFooterProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+};
+export {};