@octanejs/cmdk 0.1.0

package/src/components/dialog.tsrx

@@ -0,0 +1,40 @@
+// Command.Dialog. Renders the command menu inside an @octanejs/radix Dialog.
+// Built with createElement rather than JSX children: radix's Dialog.Portal
+// iterates its children via Children.map, which needs real element descriptors —
+// octane's compiled .tsrx children would be opaque (the documented radix
+// asChild/Slot divergence). The overlay + content are passed as descriptor
+// children.
+import { createElement } from 'octane';
+import { Dialog as RadixDialog } from '@octanejs/radix';
+import { CommandRoot } from './command.tsrx';
+import type { DialogProps } from '../types';
+
+export function Dialog(props: DialogProps) {
+	const {
+		open,
+		defaultOpen,
+		onOpenChange,
+		modal,
+		overlayClassName,
+		contentClassName,
+		container,
+		label,
+		ref: _ref,
+		...etc
+	} = props;
+
+	return createElement(
+		RadixDialog.Root,
+		{ open, defaultOpen, onOpenChange, modal },
+		createElement(
+			RadixDialog.Portal,
+			{ container },
+			createElement(RadixDialog.Overlay, { 'cmdk-overlay': '', className: overlayClassName }),
+			createElement(
+				RadixDialog.Content,
+				{ 'aria-label': label, 'cmdk-dialog': '', className: contentClassName },
+				createElement(CommandRoot, { ref: props.ref, label, ...etc }),
+			),
+		),
+	);
+}

package/src/components/empty.tsrx

@@ -0,0 +1,28 @@
+// Command.Empty. Renders only when the filter matched nothing.
+import { useSyncExternalStore } from 'octane';
+import { useStore } from '../context.tsrx';
+import type { EmptyProps } from '../types';
+
+export function Empty(props: EmptyProps) @{
+	const store = useStore()!;
+
+	// Force-mounted items never enter `filtered.count`, so consult both: "no
+	// results" must not render while any item is visible.
+	const snapshot = () => {
+		const state = store.snapshot();
+		return state.filtered.count === 0 && state.forceMountedCount === 0;
+	};
+
+	// The server snapshot is `false`. Items register in layout effects, which do
+	// not run on the server, so the count is unavoidably 0 there — rendering on
+	// that would ship "No results found." above a fully-populated list on every
+	// SSR page and leave it there for readers without JavaScript. This subscribes
+	// directly rather than through `useCmdk` because a server snapshot passed to
+	// a base hook from inside a custom .tsrx hook does not reach the SSR runtime.
+	const render = useSyncExternalStore(store.subscribe, snapshot, () => false);
+
+	if (!render) return null;
+
+	const { ref: _ref, children, ...etc } = props;
+	<div ref={props.ref} {...etc} cmdk-empty="" role="presentation">{children}</div>
+}

package/src/components/group.tsrx

@@ -0,0 +1,52 @@
+// Command.Group. Registers itself, renders an optional heading, and hides when
+// no member item matches the search.
+import { useLayoutEffect, useMemo, useRef } from 'octane';
+import { GroupContext, useCommand } from '../context.tsrx';
+import { useCmdk, useId, useValue } from '../hooks.tsrx';
+import type { GroupProps } from '../types';
+
+export function Group(props: GroupProps) @{
+	const { heading, children, forceMount, ref: _ref, ...etc } = props;
+	const id = useId();
+	const ref = useRef<HTMLDivElement | null>(null);
+	const headingRef = useRef<HTMLDivElement | null>(null);
+	const headingId = useId();
+	const context = useCommand()!;
+	const render = useCmdk(
+		(s) => forceMount
+			? true
+			: context.filter() === false
+				? true
+				: !s.search
+					? true
+					: s.filtered.groups.has(id),
+	);
+
+	useLayoutEffect(() => {
+		return context.group(id);
+	}, []);
+
+	// Value derives from the `value` prop or the heading's textContent.
+	// `aliases` is passed explicitly (groups have no keywords): octane compiles a
+	// custom-hook call as `withSlot(sym, hook, ...args, sym)`, so an OMITTED
+	// optional trailing parameter receives the slot symbol instead of its default
+	// (`= []` only fires on `undefined`). See useValue in ../hooks.tsrx.
+	useValue(id, ref, [props.value, headingRef], []);
+
+	const contextValue = useMemo(() => ({ id, forceMount }), [forceMount]);
+
+	<div
+		ref={[ref, props.ref]}
+		{...etc}
+		cmdk-group=""
+		role="presentation"
+		hidden={render ? undefined : true}
+	>
+		@if (heading) {
+			<div ref={headingRef} cmdk-group-heading="" aria-hidden={true} id={headingId}>{heading}</div>
+		}
+		<div cmdk-group-items="" role="group" aria-labelledby={heading ? headingId : undefined}>
+			<GroupContext.Provider value={contextValue}>{children}</GroupContext.Provider>
+		</div>
+	</div>
+}

package/src/components/input.tsrx

@@ -0,0 +1,44 @@
+// Command.Input. Drives the search from the native `onInput` event (the public
+// `onValueChange` API is unchanged); supports controlled `value`.
+import { useEffect } from 'octane';
+import { useCommand, useStore } from '../context.tsrx';
+import { useCmdk } from '../hooks.tsrx';
+import type { InputProps } from '../types';
+
+export function Input(props: InputProps) @{
+	const { onValueChange, ref: _ref, ...etc } = props;
+	const isControlled = props.value != null;
+	const store = useStore()!;
+	const search = useCmdk((s) => s.search);
+	const selectedItemId = useCmdk((s) => s.selectedItemId);
+	const context = useCommand()!;
+
+	useEffect(() => {
+		if (props.value != null) {
+			store.setState('search', props.value);
+		}
+	}, [props.value]);
+
+	<input
+		ref={props.ref}
+		{...etc}
+		cmdk-input=""
+		autoComplete="off"
+		autoCorrect="off"
+		spellCheck={false}
+		aria-autocomplete="list"
+		role="combobox"
+		aria-expanded={true}
+		aria-controls={context.listId}
+		aria-labelledby={context.labelId}
+		aria-activedescendant={selectedItemId}
+		id={context.inputId}
+		type="text"
+		value={isControlled ? props.value : search}
+		onInput={(event) => {
+			const next = event.currentTarget.value;
+			if (!isControlled) store.setState('search', next);
+			onValueChange?.(next);
+		}}
+	/>
+}

package/src/components/item.tsrx

@@ -0,0 +1,95 @@
+// Command.Item. Registers itself, tracks selection, and fires onSelect via the
+// native cmdk select event (dispatched by the root's Enter handler or a click).
+import { useContext, useEffect, useLayoutEffect, useRef } from 'octane';
+import { GroupContext, useCommand, useStore } from '../context.tsrx';
+import { useAsRef, useCmdk, useId, useValue } from '../hooks.tsrx';
+import { SELECT_EVENT } from '../lib/constants';
+import type { ItemProps } from '../types';
+
+export function Item(props: ItemProps) @{
+	const id = useId();
+	const ref = useRef<HTMLDivElement | null>(null);
+	const groupContext = useContext(GroupContext);
+	const context = useCommand()!;
+	const propsRef = useAsRef(props);
+	const forceMount = propsRef.current?.forceMount ?? groupContext?.forceMount;
+
+	useLayoutEffect(() => {
+		// A force-mounted item is exempt from filtering, so it is registered on the
+		// force-mount path instead — it still has to be counted somewhere, or Empty
+		// renders "no results" while this item is on screen.
+		return forceMount ? context.forceItem(id) : context.item(id, groupContext?.id);
+	}, [forceMount]);
+
+	// deps: the provided `value` prop, else the rendered element's textContent
+	// (via `ref`). cmdk's string-child inspection is dropped — octane's compiled
+	// children are opaque, and the textContent fallback covers the same case.
+	const value = useValue(id, ref, [props.value, ref], props.keywords);
+
+	const store = useStore()!;
+	const selected = useCmdk((s) => Boolean(s.value && s.value === value.current));
+	const render = useCmdk(
+		(s) => forceMount
+			? true
+			: context.filter() === false
+				? true
+				: !s.search
+					? true
+					: // An item with no entry in `filtered.items` has never been
+					// scored — that is not the same as having scored zero, and
+					// treating it as zero deadlocks: the item renders null, so
+					// `ref.current` stays null, so `useValue` has no textContent to
+					// infer from, so it registers an empty value, which scores zero
+					// forever. Upstream cannot reach this because it reads the value
+					// out of `props.children` synchronously; octane's compiled
+					// children are opaque, so the first render IS the registration.
+					// Rendering unscored items lets that first pass happen; the very
+					// next filter pass hides it if it genuinely does not match.
+					s.filtered.items.has(id)
+						? (s.filtered.items.get(id) ?? 0) > 0
+						: true,
+	);
+
+	useEffect(() => {
+		const element = ref.current;
+		if (!element || props.disabled) return;
+		element.addEventListener(SELECT_EVENT, onSelect);
+		return () => element.removeEventListener(SELECT_EVENT, onSelect);
+	}, [render, props.onSelect, props.disabled]);
+
+	function onSelect() {
+		select();
+		propsRef.current.onSelect?.(value.current ?? '');
+	}
+
+	function select() {
+		store.setState('value', value.current ?? '', true);
+	}
+
+	if (!render) return null;
+
+	const {
+		disabled,
+		value: _value,
+		onSelect: _onSelect,
+		forceMount: _forceMount,
+		keywords: _keywords,
+		children,
+		ref: _ref,
+		...etc
+	} = props;
+
+	<div
+		ref={[ref, props.ref]}
+		{...etc}
+		id={id}
+		cmdk-item=""
+		role="option"
+		aria-disabled={Boolean(disabled)}
+		aria-selected={Boolean(selected)}
+		data-disabled={Boolean(disabled)}
+		data-selected={Boolean(selected)}
+		onPointerMove={disabled || context.getDisablePointerSelection() ? undefined : select}
+		onClick={disabled ? undefined : onSelect}
+	>{children}</div>
+}

package/src/components/list.tsrx

@@ -0,0 +1,50 @@
+// Command.List. The listbox container; wires the inner sizer to the command
+// context so the root can query items within it, and keeps the
+// `--cmdk-list-height` custom property in sync with the sizer's height.
+import { useEffect, useRef } from 'octane';
+import { useCommand } from '../context.tsrx';
+import { useCmdk } from '../hooks.tsrx';
+import type { ListProps } from '../types';
+
+export function List(props: ListProps) @{
+	const { children, label = 'Suggestions', ref: _ref, ...etc } = props;
+	const ref = useRef<HTMLDivElement | null>(null);
+	const height = useRef<HTMLDivElement | null>(null);
+	const selectedItemId = useCmdk((s) => s.selectedItemId);
+	const context = useCommand()!;
+
+	// Mirror the sizer's height onto `--cmdk-list-height` so consumers can
+	// animate the list as results change. Guarded on ResizeObserver: it does not
+	// exist during SSR or in jsdom, where the property is simply never set.
+	useEffect(() => {
+		const el = height.current;
+		const wrapper = ref.current;
+		if (!el || !wrapper || typeof ResizeObserver === 'undefined') return;
+
+		let animationFrame = 0;
+		const observer = new ResizeObserver(() => {
+			animationFrame = requestAnimationFrame(() => {
+				wrapper.style.setProperty('--cmdk-list-height', el.offsetHeight.toFixed(1) + 'px');
+			});
+		});
+		observer.observe(el);
+
+		return () => {
+			cancelAnimationFrame(animationFrame);
+			observer.unobserve(el);
+		};
+	}, []);
+
+	<div
+		ref={[ref, props.ref]}
+		{...etc}
+		cmdk-list=""
+		role="listbox"
+		tabIndex={-1}
+		aria-activedescendant={selectedItemId}
+		aria-label={label}
+		id={context.listId}
+	>
+		<div ref={[height, context.listInnerRef]} cmdk-list-sizer="">{children}</div>
+	</div>
+}

package/src/components/loading.tsrx

@@ -0,0 +1,19 @@
+// Command.Loading. A progressbar to render while async options load.
+import type { LoadingProps } from '../types';
+
+export function Loading(props: LoadingProps) @{
+	const { progress, children, label = 'Loading...', ref: _ref, ...etc } = props;
+
+	<div
+		ref={props.ref}
+		{...etc}
+		cmdk-loading=""
+		role="progressbar"
+		aria-valuenow={progress}
+		aria-valuemin={0}
+		aria-valuemax={100}
+		aria-label={label}
+	>
+		<div aria-hidden={true}>{children}</div>
+	</div>
+}

package/src/components/separator.tsrx

@@ -0,0 +1,14 @@
+// Command.Separator. Shown when the search is empty (or always, with
+// `alwaysRender`); removed while searching.
+import { useRef } from 'octane';
+import { useCmdk } from '../hooks.tsrx';
+import type { SeparatorProps } from '../types';
+
+export function Separator(props: SeparatorProps) @{
+	const { alwaysRender, ref: _ref, ...etc } = props;
+	const ref = useRef<HTMLDivElement | null>(null);
+	const render = useCmdk((s) => !s.search);
+
+	if (!alwaysRender && !render) return null;
+	<div ref={[ref, props.ref]} {...etc} cmdk-separator="" role="separator" />
+}

package/src/context.tsrx

@@ -0,0 +1,12 @@
+// The three cmdk contexts and their accessors. `useContext` is context-identity
+// keyed (not compiler-slot keyed), so these thin wrappers are safe to share.
+import { createContext, useContext } from 'octane';
+import type { Context, Group, Store } from './types';
+
+export const CommandContext = createContext<Context | null>(null);
+export const useCommand = () => useContext(CommandContext);
+
+export const StoreContext = createContext<Store | null>(null);
+export const useStore = () => useContext(StoreContext);
+
+export const GroupContext = createContext<Group | null>(null);

package/src/filter.ts

@@ -0,0 +1,14 @@
+// Framework-free default filter. Kept out of the .tsrx component module so the
+// scorer/filter can be imported without pulling in the octane renderer (the
+// unit tests run in a plain node environment).
+import { commandScore } from './command-score';
+
+/**
+ * The default scoring filter used by `Command` when no custom `filter` is
+ * provided. Mirrors cmdk's `defaultFilter`: a positive score means the value
+ * matches the search; `0` means no match. `keywords` (aliases) are folded into
+ * the scored string.
+ */
+export function defaultFilter(value: string, search: string, keywords?: string[]): number {
+	return commandScore(value, search, keywords ?? []);
+}

package/src/hooks.tsrx

@@ -0,0 +1,125 @@
+// Custom hooks shared across the cmdk components. Kept in a `.tsrx` module so
+// octane's compiler owns their hook slots (the same pattern sonner uses for its
+// hooks.tsrx); consumers import and call them like any hook.
+import {
+	useId as octaneUseId,
+	useLayoutEffect,
+	useRef,
+	useState,
+	useSyncExternalStore,
+} from 'octane';
+import { useCommand, useStore } from './context.tsrx';
+import { VALUE_ATTR } from './lib/constants';
+import type { State } from './types';
+
+/**
+ * cmdk takes its ids from `@radix-ui/react-id`, which prefixes the framework's
+ * `useId` with `radix-` so they read as Radix-owned and never collide with app
+ * ids. Match that here (rather than octane's bare `useId`) so the rendered
+ * `id`/`aria-*`/`for` wiring is shape-compatible with upstream — the
+ * differential suite compares it.
+ */
+export function useId(): string {
+	return `radix-${octaneUseId()}`;
+}
+
+/** A ref that always holds the latest value (updated in a layout effect). */
+export function useAsRef<T>(data: T) {
+	const ref = useRef<T>(data);
+	useLayoutEffect(() => {
+		ref.current = data;
+	});
+	return ref;
+}
+
+/** A ref whose value is computed lazily on first render. */
+export function useLazyRef<T>(fn: () => T) {
+	const ref = useRef<T | undefined>(undefined);
+	if (ref.current === undefined) {
+		ref.current = fn();
+	}
+	return ref as { current: T };
+}
+
+/** Run a selector against the store state. */
+export function useCmdk<T>(selector: (state: State) => T): T {
+	const store = useStore()!;
+	const cb = () => selector(store.snapshot());
+	return useSyncExternalStore(store.subscribe, cb, cb);
+}
+
+/**
+ * Registers an item/group's value: from the provided `value` prop or the
+ * rendered element's `textContent` (cmdk's string-child inspection is dropped
+ * because octane's compiled children are opaque). Returns the value ref.
+ *
+ * NOTE on `aliases`: octane compiles a custom-hook call as
+ * `withSlot(sym, hook, ...args, sym)`, so the trailing slot symbol becomes an
+ * extra argument. A caller that OMITS this optional trailing parameter receives
+ * that symbol instead of the `= []` default (which only fires on `undefined`).
+ * Callers must therefore pass `aliases` explicitly, and the read below is
+ * defensive so a missed call site degrades to "no keywords" rather than
+ * throwing mid-effect (which silently aborts value registration).
+ */
+export function useValue(
+	id: string,
+	ref: { current: HTMLElement | null },
+	deps: (string | undefined | { current: HTMLElement | null })[],
+	aliases: string[] = [],
+) {
+	const valueRef = useRef<string | undefined>(undefined);
+	const context = useCommand()!;
+
+	useLayoutEffect(() => {
+		const value = (() => {
+			for (const part of deps) {
+				if (typeof part === 'string') return part.trim();
+				if (part && typeof part === 'object' && 'current' in part) {
+					if (part.current) return part.current.textContent?.trim();
+					return valueRef.current;
+				}
+			}
+			return undefined;
+		})();
+
+		const keywords =
+			Array.isArray(aliases) ? aliases.map((alias) => alias.trim()) : [];
+		context.value(id, value, keywords);
+		ref.current?.setAttribute(VALUE_ATTR, value ?? '');
+		valueRef.current = value;
+	});
+
+	return valueRef;
+}
+
+/** Imperatively run a function on the next layout-effect cycle. */
+export function useScheduleLayoutEffect() {
+	const [s, ss] = useState<object | undefined>(undefined);
+	const fns = useLazyRef(() => new Map<string | number, () => void>());
+
+	useLayoutEffect(() => {
+		// Snapshot and clear BEFORE running: a scheduled callback may schedule more
+		// work (e.g. selectFirstItem → setState('value') → schedule(...)), and those
+		// nested entries must survive into the next flush rather than be wiped by a
+		// reset that runs after the callbacks. Each callback is isolated so one
+		// throwing (e.g. scrollIntoView) can't drop the callbacks queued after it.
+		const pending = [...fns.current.values()];
+		fns.current = new Map();
+		for (const f of pending) {
+			try {
+				f();
+			} catch (error) {
+				// Isolate, but never swallow. A scheduled callback can run user code
+				// (selectFirstItem -> setState('value') -> onValueChange), so a failure
+				// here must stay visible; report it the same way octane reports an
+				// exception raised inside an effect, and keep the siblings running.
+				console.error(error);
+			}
+		}
+	}, [s]);
+
+	return (id: string | number, cb: () => void) => {
+		fns.current.set(id, cb);
+		ss({});
+	};
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// @octanejs/cmdk — a port of cmdk@1.1.1 (dip/cmdk) onto the octane renderer.
+// See docs/cmdk-port-plan.md for the phased plan and supported surface.
+//
+// The renderer is authored in `.tsrx` so octane's compiler owns the component
+// templates and hook slots; the scorer/filter stay framework-free.
+export {
+	Command,
+	CommandRoot,
+	CommandItem,
+	CommandInput,
+	CommandList,
+	CommandGroup,
+	CommandSeparator,
+	CommandDialog,
+	CommandEmpty,
+	CommandLoading,
+	useCommandState,
+} from './cmdk.tsrx';
+export { defaultFilter } from './filter';
+export type {
+	CommandProps,
+	ItemProps,
+	InputProps,
+	ListProps,
+	GroupProps,
+	SeparatorProps,
+	DialogProps,
+	EmptyProps,
+	LoadingProps,
+	CommandFilter,
+} from './types';

package/src/lib/constants.ts

@@ -0,0 +1,23 @@
+// The cmdk DOM contract: attribute selectors consumers style against and the
+// port queries, the native selection event name, the value attribute, and the
+// screen-reader-only style for the hidden accessibility label.
+
+export const GROUP_SELECTOR = `[cmdk-group=""]`;
+export const GROUP_ITEMS_SELECTOR = `[cmdk-group-items=""]`;
+export const GROUP_HEADING_SELECTOR = `[cmdk-group-heading=""]`;
+export const ITEM_SELECTOR = `[cmdk-item=""]`;
+export const VALID_ITEM_SELECTOR = `${ITEM_SELECTOR}:not([aria-disabled="true"])`;
+export const SELECT_EVENT = `cmdk-item-select`;
+export const VALUE_ATTR = `data-value`;
+
+export const srOnlyStyles = {
+	position: 'absolute',
+	width: '1px',
+	height: '1px',
+	padding: '0',
+	margin: '-1px',
+	overflow: 'hidden',
+	clip: 'rect(0, 0, 0, 0)',
+	whiteSpace: 'nowrap',
+	borderWidth: '0',
+} as const;