ark-cmdk 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# ark-cmdk
+
+## Purpose
+
+`ark-cmdk` is a small, data-driven command menu for React 19 built on Ark UI.
+
+It ships one first-class API for:
+
+- inline command menus with `Command.Root`
+- modal command palettes with `Command.Dialog`
+- explicit item identity, search ranking, and active-item state
+
+## Installation
+
+```bash
+pnpm add ark-cmdk react react-dom
+```
+
+`ark-cmdk` targets React 19, browser-side CSR, and ESM only.
+
+## Quick Example
+
+```tsx
+import { Command } from 'ark-cmdk'
+
+const items = [
+  { id: 'open', label: 'Open File' },
+  { id: 'save', label: 'Save File' },
+]
+
+export function Example() {
+  return (
+    <Command.Root
+      itemToString={(item) => item.label}
+      itemToValue={(item) => item.id}
+      items={items}
+      label="Command Menu"
+    >
+      <Command.Input placeholder="Search commands..." />
+      <Command.List empty={<div>No results.</div>}>
+        {(item) => <div>{item.label}</div>}
+      </Command.List>
+    </Command.Root>
+  )
+}
+```
+
+## Documentation Map
+
+- Concepts and recommended patterns: [docs/context.md](docs/context.md)
+- Inline usage example: [examples/inline.tsx](examples/inline.tsx)
+- Dialog usage example: [examples/dialog.tsx](examples/dialog.tsx)
+- Controlled state example: [examples/controlled-state.tsx](examples/controlled-state.tsx)
+- Exact exported signatures: [dist/index.d.mts](dist/index.d.mts)
+- API contract: [docs/v0.1-api.md](docs/v0.1-api.md)

package/dist/index.d.mts

@@ -0,0 +1,128 @@
+import * as React from "react";
+import { ReactElement, RefAttributes } from "react";
+
+//#region src/command/types.d.ts
+/**
+ * Scores an item against the current search string.
+ *
+ * Return a value less than or equal to `0` to hide the item. Higher scores rank
+ * earlier in the visible list.
+ *
+ * @param itemText The trimmed searchable text derived from `itemToString`.
+ * @param search The trimmed current search string.
+ * @param keywords The trimmed keyword aliases derived from `itemToKeywords`.
+ */
+type CommandFilter = (itemText: string, search: string, keywords: readonly string[]) => number;
+/**
+ * Props for the inline command surface.
+ *
+ * `Command.Root` owns item normalization, filtering, active-item state, and
+ * selection for a data-driven item array. It never inspects arbitrary child
+ * trees to discover items.
+ */
+interface CommandRootProps<TItem = any> extends Omit<React.ComponentPropsWithoutRef<'div'>, 'children' | 'defaultValue' | 'onSelect'> {
+  activeValue?: string | null;
+  children: React.ReactNode;
+  class?: string;
+  defaultActiveValue?: string | null;
+  defaultSearch?: string;
+  filter?: CommandFilter;
+  itemToDisabled?: (item: TItem) => boolean | undefined;
+  itemToKeywords?: (item: TItem) => readonly string[] | undefined;
+  itemToString: (item: TItem) => string;
+  itemToValue: (item: TItem) => string;
+  items: readonly TItem[];
+  label: string;
+  onActiveValueChange?: (value: string | null) => void;
+  onSearchChange?: (search: string) => void;
+  onSelect?: (item: TItem) => void;
+  search?: string;
+}
+/**
+ * Props for the search input part.
+ *
+ * The rendered input value is bound to the parent command's `search` state.
+ */
+interface CommandInputProps extends Omit<React.ComponentPropsWithoutRef<'input'>, 'children' | 'defaultValue' | 'onChange' | 'type' | 'value'> {
+  class?: string;
+}
+/**
+ * Derived state passed to `Command.List` item render functions.
+ */
+interface CommandListItemState {
+  active: boolean;
+  disabled: boolean;
+  value: string;
+}
+/**
+ * Props for the visible item list.
+ *
+ * `children` is a render function over the current visible items, not an item
+ * registration API.
+ */
+interface CommandListProps<TItem = any> extends Omit<React.ComponentPropsWithoutRef<'div'>, 'children'> {
+  children: (item: TItem, state: CommandListItemState) => React.ReactNode;
+  class?: string;
+  empty?: React.ReactNode;
+}
+/**
+ * Props for the modal command wrapper.
+ *
+ * `Command.Dialog` reuses the same item, search, active-item, and selection
+ * semantics as `Command.Root`, while delegating overlay behavior to Ark
+ * `Dialog`.
+ */
+interface CommandDialogProps<TItem = any> extends CommandRootProps<TItem> {
+  contentClass?: string;
+  contentClassName?: string;
+  onOpenChange: (open: boolean) => void;
+  open: boolean;
+  overlayClass?: string;
+  overlayClassName?: string;
+}
+//#endregion
+//#region src/command/dialog.d.ts
+interface CommandDialogComponent {
+  <TItem = any>(props: CommandDialogProps<TItem> & RefAttributes<HTMLDivElement>): ReactElement;
+}
+//#endregion
+//#region src/command/list.d.ts
+interface CommandListComponent {
+  <TItem = any>(props: CommandListProps<TItem> & RefAttributes<HTMLDivElement>): ReactElement;
+}
+//#endregion
+//#region src/command/root.d.ts
+interface CommandRootComponent {
+  <TItem = any>(props: CommandRootProps<TItem> & RefAttributes<HTMLDivElement>): ReactElement;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Public namespace for `ark-cmdk`.
+ *
+ * Use `Command.Root` for inline command menus and `Command.Dialog` for modal
+ * command palettes. Pair either root with `Command.Input` and `Command.List`.
+ *
+ * @example
+ * ```tsx
+ * import { Command } from 'ark-cmdk'
+ *
+ * <Command.Root
+ *   itemToString={(item) => item.label}
+ *   itemToValue={(item) => item.id}
+ *   items={items}
+ *   label="Command Menu"
+ * >
+ *   <Command.Input />
+ *   <Command.List>{(item) => <div>{item.label}</div>}</Command.List>
+ * </Command.Root>
+ * ```
+ */
+declare const Command: {
+  readonly Dialog: CommandDialogComponent;
+  readonly Input: React.ForwardRefExoticComponent<CommandInputProps & React.RefAttributes<HTMLInputElement>>;
+  readonly List: CommandListComponent;
+  readonly Root: CommandRootComponent;
+};
+//#endregion
+export { Command, type CommandDialogProps, type CommandFilter, type CommandInputProps, type CommandListItemState, type CommandListProps, type CommandRootProps };

package/dist/index.mjs

@@ -0,0 +1,422 @@
+import { Dialog } from "@ark-ui/react/dialog";
+import { Portal } from "@ark-ui/react/portal";
+import { createContext, forwardRef, useCallback, useContext, useEffect, useEffectEvent, useMemo, useRef, useState } from "react";
+import { Combobox, createListCollection } from "@ark-ui/react/combobox";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/command/state.ts
+function composeRefs(...refs) {
+	return (value) => {
+		for (const ref of refs) {
+			if (!ref) continue;
+			if (typeof ref === "function") {
+				ref(value);
+				continue;
+			}
+			ref.current = value;
+		}
+	};
+}
+function mergeClassName(className, classProp) {
+	const merged = [classProp, className].filter(Boolean).join(" ").trim();
+	return merged === "" ? void 0 : merged;
+}
+function useCommandActiveState({ activeValue, defaultActiveValue = null, onActiveValueChange, search, visibleItems }) {
+	const changeActiveValue = useEffectEvent((value) => {
+		onActiveValueChange?.(value);
+	});
+	const [internalActiveValue, setInternalActiveValue] = useState(() => resolveInitialActiveValue(visibleItems, defaultActiveValue));
+	const isControlled = activeValue !== void 0;
+	const currentActiveValue = isControlled ? activeValue : internalActiveValue;
+	const previousSearchRef = useRef(search);
+	const previousValueOrderRef = useRef(visibleItems.map((item) => item.value));
+	const isFirstRenderRef = useRef(true);
+	const setActiveValue = useCallback((value) => {
+		if (Object.is(currentActiveValue, value)) return;
+		if (!isControlled) setInternalActiveValue(value);
+		changeActiveValue(value);
+	}, [
+		changeActiveValue,
+		currentActiveValue,
+		isControlled
+	]);
+	useEffect(() => {
+		if (isFirstRenderRef.current) {
+			isFirstRenderRef.current = false;
+			previousSearchRef.current = search;
+			previousValueOrderRef.current = visibleItems.map((item) => item.value);
+			return;
+		}
+		const nextActiveValue = reconcileActiveValue({
+			currentActiveValue,
+			previousValueOrder: previousValueOrderRef.current,
+			searchChanged: search !== previousSearchRef.current,
+			visibleItems
+		});
+		previousSearchRef.current = search;
+		previousValueOrderRef.current = visibleItems.map((item) => item.value);
+		if (Object.is(nextActiveValue, currentActiveValue)) return;
+		if (!isControlled) setInternalActiveValue(nextActiveValue);
+		changeActiveValue(nextActiveValue);
+	}, [
+		changeActiveValue,
+		currentActiveValue,
+		isControlled,
+		search,
+		visibleItems
+	]);
+	return {
+		activeValue: isVisibleEnabledValue(visibleItems, currentActiveValue) ? currentActiveValue : null,
+		setActiveValue
+	};
+}
+function useControllableState({ defaultValue, onChange, value }) {
+	const changeValue = useEffectEvent((nextValue) => {
+		onChange?.(nextValue);
+	});
+	const [internalValue, setInternalValue] = useState(defaultValue);
+	const isControlled = value !== void 0;
+	const currentValue = isControlled ? value : internalValue;
+	return {
+		isControlled,
+		setValue: useCallback((nextValue) => {
+			if (Object.is(currentValue, nextValue)) return;
+			if (!isControlled) setInternalValue(nextValue);
+			changeValue(nextValue);
+		}, [
+			changeValue,
+			currentValue,
+			isControlled
+		]),
+		value: currentValue
+	};
+}
+function getFirstVisibleEnabledValue(items) {
+	for (const item of items) if (!item.disabled) return item.value;
+	return null;
+}
+function reconcileActiveValue({ currentActiveValue, previousValueOrder, searchChanged, visibleItems }) {
+	if (visibleItems.length === 0) return null;
+	if (searchChanged) return getFirstVisibleEnabledValue(visibleItems);
+	if (currentActiveValue == null) return getFirstVisibleEnabledValue(visibleItems);
+	if (isVisibleEnabledValue(visibleItems, currentActiveValue)) return currentActiveValue;
+	return getNextFallbackValue(previousValueOrder, visibleItems, currentActiveValue);
+}
+function resolveInitialActiveValue(items, defaultActiveValue) {
+	if (defaultActiveValue && isVisibleEnabledValue(items, defaultActiveValue)) return defaultActiveValue;
+	return getFirstVisibleEnabledValue(items);
+}
+function getNextFallbackValue(previousValueOrder, visibleItems, removedValue) {
+	const enabledValues = new Set(visibleItems.filter((item) => !item.disabled).map((item) => item.value));
+	if (enabledValues.size === 0) return null;
+	const removedIndex = previousValueOrder.indexOf(removedValue);
+	if (removedIndex === -1) return getFirstVisibleEnabledValue(visibleItems);
+	for (let index = removedIndex + 1; index < previousValueOrder.length; index += 1) {
+		const candidate = previousValueOrder[index];
+		if (enabledValues.has(candidate)) return candidate;
+	}
+	for (let index = removedIndex - 1; index >= 0; index -= 1) {
+		const candidate = previousValueOrder[index];
+		if (enabledValues.has(candidate)) return candidate;
+	}
+	return getFirstVisibleEnabledValue(visibleItems);
+}
+function isVisibleEnabledValue(items, value) {
+	if (!value) return false;
+	return items.some((item) => item.value === value && !item.disabled);
+}
+//#endregion
+//#region src/command/context.tsx
+const CommandContext = createContext(null);
+function CommandContextProvider({ children, value }) {
+	return /* @__PURE__ */ jsx(CommandContext.Provider, {
+		value,
+		children
+	});
+}
+function useCommandContext() {
+	const value = useContext(CommandContext);
+	if (!value) throw new Error("Command parts must be rendered inside Command.Root or Command.Dialog.");
+	return value;
+}
+//#endregion
+//#region src/command/filter.ts
+const defaultFilter = (itemText, search, keywords) => {
+	const normalizedItemText = normalizeText(itemText);
+	const normalizedSearch = normalizeText(search);
+	if (normalizedSearch === "") return 1;
+	return commandScore(normalizedItemText, normalizedSearch, [...keywords]);
+};
+function getVisibleItems(items, search, filter) {
+	const normalizedSearch = normalizeText(search);
+	if (normalizedSearch === "") return items.map((item) => ({
+		...item,
+		score: 1
+	}));
+	return items.map((item) => ({
+		...item,
+		score: filter(item.text, normalizedSearch, item.keywords)
+	})).filter((item) => item.score > 0).sort((left, right) => {
+		if (left.score !== right.score) return right.score - left.score;
+		return left.index - right.index;
+	});
+}
+function normalizeKeywords(keywords) {
+	if (!keywords) return [];
+	return keywords.map((keyword) => normalizeText(keyword)).filter((keyword) => keyword.length > 0);
+}
+function normalizeText(value) {
+	return value.trim();
+}
+const SCORE_CONTINUE_MATCH = 1;
+const SCORE_SPACE_WORD_JUMP = .9;
+const SCORE_NON_SPACE_WORD_JUMP = .8;
+const SCORE_CHARACTER_JUMP = .17;
+const SCORE_TRANSPOSITION = .1;
+const PENALTY_SKIPPED = .999;
+const PENALTY_CASE_MISMATCH = .9999;
+const PENALTY_NOT_COMPLETE = .99;
+const isGap = /[\\/_+.#"@\x5b({&]/;
+const gapMatches = /[\\/_+.#"@\x5b({&]/g;
+const isSpace = /[\s-]/;
+const spaceMatches = /[\s-]/g;
+function commandScore(string, abbreviation, aliases) {
+	const haystack = aliases.length > 0 ? `${string} ${aliases.join(" ")}` : string;
+	return commandScoreInner(haystack, abbreviation, formatInput(haystack), formatInput(abbreviation), 0, 0, {});
+}
+function commandScoreInner(string, abbreviation, lowerString, lowerAbbreviation, stringIndex, abbreviationIndex, memoizedResults) {
+	if (abbreviationIndex === abbreviation.length) {
+		if (stringIndex === string.length) return SCORE_CONTINUE_MATCH;
+		return PENALTY_NOT_COMPLETE;
+	}
+	const memoizeKey = `${stringIndex},${abbreviationIndex}`;
+	const memoizedValue = memoizedResults[memoizeKey];
+	if (memoizedValue !== void 0) return memoizedValue;
+	const abbreviationChar = lowerAbbreviation.charAt(abbreviationIndex);
+	let index = lowerString.indexOf(abbreviationChar, stringIndex);
+	let highScore = 0;
+	while (index >= 0) {
+		let score = commandScoreInner(string, abbreviation, lowerString, lowerAbbreviation, index + 1, abbreviationIndex + 1, memoizedResults);
+		if (score > highScore) {
+			if (index === stringIndex) score *= SCORE_CONTINUE_MATCH;
+			else if (isGap.test(string.charAt(index - 1))) {
+				score *= SCORE_NON_SPACE_WORD_JUMP;
+				const wordBreaks = string.slice(stringIndex, index - 1).match(gapMatches);
+				if (wordBreaks && stringIndex > 0) score *= Math.pow(PENALTY_SKIPPED, wordBreaks.length);
+			} else if (isSpace.test(string.charAt(index - 1))) {
+				score *= SCORE_SPACE_WORD_JUMP;
+				const spaceBreaks = string.slice(stringIndex, index - 1).match(spaceMatches);
+				if (spaceBreaks && stringIndex > 0) score *= Math.pow(PENALTY_SKIPPED, spaceBreaks.length);
+			} else {
+				score *= SCORE_CHARACTER_JUMP;
+				if (stringIndex > 0) score *= Math.pow(PENALTY_SKIPPED, index - stringIndex);
+			}
+			if (string.charAt(index) !== abbreviation.charAt(abbreviationIndex)) score *= PENALTY_CASE_MISMATCH;
+		}
+		const transposed = lowerString.charAt(index - 1) === lowerAbbreviation.charAt(abbreviationIndex + 1) || lowerAbbreviation.charAt(abbreviationIndex + 1) === lowerAbbreviation.charAt(abbreviationIndex) && lowerString.charAt(index - 1) !== lowerAbbreviation.charAt(abbreviationIndex);
+		if (score < SCORE_TRANSPOSITION && transposed) {
+			const transposedScore = commandScoreInner(string, abbreviation, lowerString, lowerAbbreviation, index + 1, abbreviationIndex + 2, memoizedResults);
+			if (transposedScore * SCORE_TRANSPOSITION > score) score = transposedScore * SCORE_TRANSPOSITION;
+		}
+		if (score > highScore) highScore = score;
+		index = lowerString.indexOf(abbreviationChar, index + 1);
+	}
+	memoizedResults[memoizeKey] = highScore;
+	return highScore;
+}
+function formatInput(value) {
+	return value.toLowerCase().replace(spaceMatches, " ");
+}
+//#endregion
+//#region src/command/root.tsx
+const EMPTY_SELECTION = [];
+const CommandRootInternal = forwardRef(function CommandRootImpl(props, ref) {
+	const { activeValue, children, class: classProp, className, defaultActiveValue, defaultSearch = "", filter = defaultFilter, itemToDisabled, itemToKeywords, itemToString, itemToValue, items, label, onActiveValueChange, onSearchChange, onSelect, search, inputRef: inputRefProp, ...rootProps } = props;
+	const fallbackInputRef = useRef(null);
+	const inputRef = inputRefProp ?? fallbackInputRef;
+	const emitSelect = useEffectEvent((value) => {
+		const selectedItem = normalizedItems.find((item) => item.value === value)?.item;
+		if (selectedItem) onSelect?.(selectedItem);
+	});
+	const searchState = useControllableState({
+		defaultValue: defaultSearch,
+		onChange: onSearchChange,
+		value: search
+	});
+	const normalizedItems = useMemo(() => {
+		const seenValues = /* @__PURE__ */ new Set();
+		return items.map((item, index) => {
+			const value = itemToValue(item);
+			if (value.trim() === "") throw new Error("Command items require a non-empty string value.");
+			if (seenValues.has(value)) throw new Error(`Command item values must be unique. Received "${value}".`);
+			seenValues.add(value);
+			return {
+				disabled: itemToDisabled?.(item) ?? false,
+				index,
+				item,
+				keywords: normalizeKeywords(itemToKeywords?.(item)),
+				text: normalizeText(itemToString(item)),
+				value
+			};
+		});
+	}, [
+		itemToDisabled,
+		itemToKeywords,
+		itemToString,
+		itemToValue,
+		items
+	]);
+	const visibleItems = useMemo(() => getVisibleItems(normalizedItems, searchState.value, filter), [
+		filter,
+		normalizedItems,
+		searchState.value
+	]);
+	const activeState = useCommandActiveState({
+		activeValue,
+		defaultActiveValue,
+		onActiveValueChange,
+		search: searchState.value,
+		visibleItems
+	});
+	const collection = useMemo(() => createListCollection({
+		isItemDisabled: (item) => item.disabled,
+		itemToString: (item) => item.text,
+		itemToValue: (item) => item.value,
+		items: visibleItems
+	}), [visibleItems]);
+	return /* @__PURE__ */ jsx(CommandContextProvider, {
+		value: {
+			inputRef,
+			label,
+			visibleActiveValue: activeState.activeValue,
+			visibleItems
+		},
+		children: /* @__PURE__ */ jsx(Combobox.Root, {
+			...rootProps,
+			ref,
+			className: mergeClassName(className, classProp),
+			closeOnSelect: false,
+			collection,
+			disableLayer: true,
+			highlightedValue: activeState.activeValue,
+			inputBehavior: "none",
+			inputValue: searchState.value,
+			loopFocus: false,
+			onHighlightChange: ({ highlightedValue }) => {
+				activeState.setActiveValue(highlightedValue);
+			},
+			onInputValueChange: ({ inputValue }) => {
+				searchState.setValue(inputValue);
+			},
+			onOpenChange: () => {},
+			onSelect: ({ itemValue }) => {
+				emitSelect(itemValue);
+			},
+			open: true,
+			openOnChange: false,
+			openOnClick: false,
+			openOnKeyPress: false,
+			selectionBehavior: "preserve",
+			value: EMPTY_SELECTION,
+			children
+		})
+	});
+});
+const CommandRoot = CommandRootInternal;
+//#endregion
+//#region src/command/dialog.tsx
+const CommandDialog = forwardRef(function CommandDialog(props, ref) {
+	const { contentClass, contentClassName, onOpenChange, open, overlayClass, overlayClassName, ...rootProps } = props;
+	const inputRef = useRef(null);
+	useEffect(() => {
+		if (open) inputRef.current?.focus();
+	}, [open]);
+	return /* @__PURE__ */ jsx(Dialog.Root, {
+		"aria-label": rootProps.label,
+		initialFocusEl: () => inputRef.current,
+		onOpenChange: ({ open }) => {
+			onOpenChange(open);
+		},
+		open,
+		unmountOnExit: true,
+		children: /* @__PURE__ */ jsxs(Portal, { children: [/* @__PURE__ */ jsx(Dialog.Backdrop, { className: mergeClassName(overlayClassName, overlayClass) }), /* @__PURE__ */ jsx(Dialog.Positioner, { children: /* @__PURE__ */ jsx(Dialog.Content, {
+			className: mergeClassName(contentClassName, contentClass),
+			ref,
+			children: /* @__PURE__ */ jsx(CommandRootInternal, {
+				...rootProps,
+				inputRef
+			})
+		}) })] })
+	});
+});
+//#endregion
+//#region src/command/input.tsx
+const CommandInput = forwardRef(function CommandInput(props, ref) {
+	const { "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, class: classProp, className, ...inputProps } = props;
+	const { inputRef, label } = useCommandContext();
+	return /* @__PURE__ */ jsx(Combobox.Input, {
+		...inputProps,
+		"aria-label": ariaLabelledby ? void 0 : ariaLabel ?? label,
+		"aria-labelledby": ariaLabelledby,
+		className: mergeClassName(className, classProp),
+		ref: composeRefs(ref, inputRef)
+	});
+});
+//#endregion
+//#region src/command/list.tsx
+const CommandList = forwardRef(function CommandList(props, ref) {
+	const { children, class: classProp, className, empty, onPointerMoveCapture, ...listProps } = props;
+	const { visibleActiveValue, visibleItems } = useCommandContext();
+	return /* @__PURE__ */ jsx(Combobox.Content, { children: /* @__PURE__ */ jsxs(Combobox.List, {
+		...listProps,
+		className: mergeClassName(className, classProp),
+		onPointerMoveCapture: callAll(onPointerMoveCapture, stopPointerHighlightCapture),
+		ref,
+		children: [visibleItems.length === 0 ? empty : null, visibleItems.map((item) => /* @__PURE__ */ jsx(Combobox.Item, {
+			item,
+			children: children(item.item, {
+				active: item.value === visibleActiveValue,
+				disabled: item.disabled,
+				value: item.value
+			})
+		}, item.value))]
+	}) });
+});
+function callAll(...handlers) {
+	return (event) => {
+		for (const handler of handlers) handler?.(event);
+	};
+}
+function stopPointerHighlightCapture(event) {
+	if (event.target !== event.currentTarget) event.stopPropagation();
+}
+//#endregion
+//#region src/index.ts
+/**
+* Public namespace for `ark-cmdk`.
+*
+* Use `Command.Root` for inline command menus and `Command.Dialog` for modal
+* command palettes. Pair either root with `Command.Input` and `Command.List`.
+*
+* @example
+* ```tsx
+* import { Command } from 'ark-cmdk'
+*
+* <Command.Root
+*   itemToString={(item) => item.label}
+*   itemToValue={(item) => item.id}
+*   items={items}
+*   label="Command Menu"
+* >
+*   <Command.Input />
+*   <Command.List>{(item) => <div>{item.label}</div>}</Command.List>
+* </Command.Root>
+* ```
+*/
+const Command = {
+	Dialog: CommandDialog,
+	Input: CommandInput,
+	List: CommandList,
+	Root: CommandRoot
+};
+//#endregion
+export { Command };

package/docs/context.md

@@ -0,0 +1,121 @@
+# Overview
+
+`ark-cmdk` is a small, data-driven command menu for React 19 built on Ark UI.
+
+The library keeps one first-class model:
+
+- the consumer owns an explicit item array
+- `ark-cmdk` derives visibility, ranking, active-item state, and selection from that data
+- Ark UI owns combobox and dialog accessibility behavior
+
+# When to Use
+
+Use `ark-cmdk` when you want:
+
+- an inline command menu or modal command palette in a React 19 client app
+- explicit item identity instead of DOM-driven item discovery
+- built-in search ranking over a data array
+- controlled or uncontrolled search state
+- controlled or uncontrolled active-item state
+- unstyled parts with consumer-owned item rendering
+
+# When Not to Use
+
+`ark-cmdk` is the wrong fit when you need:
+
+- `cmdk` drop-in compatibility
+- manual filtering or manual ordering control
+- groups or loading helpers
+- DOM-driven child inspection
+- pointer-hover activation, loop navigation, Vim bindings, or Alt-based group jumps
+- React Server Component usage or React versions older than 19
+
+# Core Abstractions
+
+- `Command.Root`: the inline state owner for item normalization, filtering, active-item state, and selection
+- `Command.Input`: the search input bound to the root's `search` state
+- `Command.List`: the visible item list rendered through a function child
+- `Command.Dialog`: a thin modal wrapper over the same command semantics
+- `search`: the current text query
+- `active item`: the highlighted visible enabled item used for keyboard navigation and `aria-activedescendant`
+- `committed selection`: the item passed to `onSelect`
+
+# Data Flow / Lifecycle
+
+1. The consumer passes `items` plus `itemToValue` and `itemToString`.
+2. `ark-cmdk` normalizes item text, keywords, and disabled state from that data.
+3. The current `search` string is scored against normalized items.
+4. Visible items are derived from scores and sorted by rank.
+5. The active item is reconciled against the visible enabled set.
+6. Keyboard navigation updates the active item.
+7. `Enter` or click commits the current item through `onSelect`.
+
+The DOM is a projection of derived state. It is not the source of truth for item identity, ordering, or filtering.
+
+# Common Tasks -> Recommended APIs
+
+- Inline command menu: `Command.Root` + `Command.Input` + `Command.List`
+- Modal command palette: `Command.Dialog`
+- Controlled search: `search` + `onSearchChange`
+- Controlled active item: `activeValue` + `onActiveValueChange`
+- Search aliases: `itemToKeywords`
+- Disabled-item handling: `itemToDisabled`
+- Empty states: `Command.List` `empty`
+- Custom row rendering: `Command.List` render function
+- Styling: `className` on `Command.Root`, `Command.Input`, and `Command.List`, plus `overlayClassName` and `contentClassName` on `Command.Dialog`
+
+# Recommended Patterns
+
+- Keep `itemToValue` stable, unique, and non-empty across renders.
+- Treat `search` and `activeValue` as separate concerns.
+- Keep side effects in `onSelect`, not in active-item change handlers.
+- Use `itemToKeywords` for aliases instead of concatenating extra text into rendered labels.
+- Render item UI entirely inside the `Command.List` render function.
+- Use examples in [examples/inline.tsx](../examples/inline.tsx), [examples/dialog.tsx](../examples/dialog.tsx), and [examples/controlled-state.tsx](../examples/controlled-state.tsx) as the canonical usage patterns.
+
+# Patterns to Avoid
+
+- Deriving item identity from rendered text or DOM structure
+- Rebuilding item values with random or unstable IDs
+- Treating active-item movement as a committed selection
+- Assuming hidden or disabled items remain keyboard targets
+- Depending on undocumented selector compatibility with `cmdk`
+- Reintroducing manual filtering as an implicit second mode
+
+# Invariants and Constraints
+
+- React 19 only
+- browser-side CSR only
+- ESM only
+- one first-class data-driven API
+- item identity is explicit through `itemToValue`
+- `Command.List` renders only the current visible item set
+- disabled items are skipped by active-item selection and committed selection
+- dialog behavior remains Ark-owned
+
+# Error Model
+
+- An empty `itemToValue` result throws during render.
+- Duplicate `itemToValue` results throw during render.
+- Returning an active value that does not resolve to a visible enabled item leaves the command with no rendered active item.
+- A filter score less than or equal to `0` hides the item from the visible list.
+
+# Terminology
+
+- `search`: the current query string
+- `visible item`: an item whose filter score is greater than `0`, or any item when search is empty
+- `active item`: the highlighted visible enabled item
+- `committed selection`: the item passed to `onSelect`
+- `keywords`: alias terms used during scoring
+
+# Non-Goals
+
+- `cmdk` parity
+- manual filtering mode
+- groups
+- loading helpers
+- pointer-hover activation
+- loop navigation
+- Vim bindings
+- Alt-based group jumps
+- selector compatibility shims

package/examples/controlled-state.tsx

@@ -0,0 +1,36 @@
+import { useState } from 'react'
+
+import { Command } from 'ark-cmdk'
+
+const items = [
+  { id: 'alpha', label: 'Alpha' },
+  { id: 'bravo', label: 'Bravo' },
+]
+
+export function ControlledStateExample() {
+  const [search, setSearch] = useState('')
+  const [activeValue, setActiveValue] = useState<string | null>('alpha')
+
+  return (
+    <Command.Root
+      activeValue={activeValue}
+      itemToString={(item) => item.label}
+      itemToValue={(item) => item.id}
+      items={items}
+      label="Command Menu"
+      onActiveValueChange={setActiveValue}
+      onSearchChange={setSearch}
+      search={search}
+    >
+      <Command.Input />
+      <Command.List empty={<div>No results.</div>}>
+        {(item, state) => (
+          <div>
+            {state.active ? 'Active: ' : null}
+            {item.label}
+          </div>
+        )}
+      </Command.List>
+    </Command.Root>
+  )
+}

package/examples/dialog.tsx

@@ -0,0 +1,32 @@
+import { useState } from 'react'
+
+import { Command } from 'ark-cmdk'
+
+const items = [
+  { id: 'open', label: 'Open File' },
+  { id: 'save', label: 'Save File' },
+]
+
+export function DialogExample() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <Command.Dialog
+      contentClassName="command-dialog"
+      itemToString={(item) => item.label}
+      itemToValue={(item) => item.id}
+      items={items}
+      label="Command Menu"
+      onOpenChange={setOpen}
+      open={open}
+      overlayClassName="command-overlay"
+    >
+      <Command.Input placeholder="Type a command..." />
+      <Command.List empty={<div>No results.</div>}>
+        {(item, state) => (
+          <div className={state.active ? 'is-active' : undefined}>{item.label}</div>
+        )}
+      </Command.List>
+    </Command.Dialog>
+  )
+}

package/examples/inline.tsx

@@ -0,0 +1,30 @@
+import { Command } from 'ark-cmdk'
+
+const items = [
+  { id: 'open', label: 'Open File', keywords: ['file'] },
+  { id: 'save', label: 'Save File', keywords: ['write'] },
+  { id: 'close', disabled: true, label: 'Close Window' },
+]
+
+export function InlineExample() {
+  return (
+    <Command.Root
+      itemToDisabled={(item) => item.disabled}
+      itemToKeywords={(item) => item.keywords}
+      itemToString={(item) => item.label}
+      itemToValue={(item) => item.id}
+      items={items}
+      label="Command Menu"
+      onSelect={(item) => {
+        console.log(item.id)
+      }}
+    >
+      <Command.Input placeholder="Search commands..." />
+      <Command.List empty={<div>No results.</div>}>
+        {(item, state) => (
+          <div className={state.active ? 'is-active' : undefined}>{item.label}</div>
+        )}
+      </Command.List>
+    </Command.Root>
+  )
+}

package/package.json

@@ -1,13 +1,53 @@
 {
   "name": "ark-cmdk",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
+  "description": "A small, data-driven command menu for React 19 built on Ark UI",
+  "version": "0.1.0",
   "license": "MIT",
-  "type": "commonjs"
-}
+  "author": "Alec Larson",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aleclarson/ark-cmdk.git"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^29.0.2",
+    "oxfmt": "^0.44.0",
+    "oxlint": "^1.59.0",
+    "radashi": "^12.7.2",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "tsdown": "^0.21.7",
+    "tsnapi": "^0.1.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "peerDependencies": {
+    "@ark-ui/react": ">=5",
+    "react": ">=19"
+  },
+  "scripts": {
+    "dev": "tsdown --sourcemap --watch",
+    "build": "tsdown",
+    "format": "oxfmt .",
+    "lint": "oxlint src",
+    "typecheck": "tsc --noEmit && tsc -p test --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/readme.md

@@ -1 +0,0 @@
-Coming soon...