@octanejs/cmdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+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,57 @@
+# @octanejs/cmdk
+
+[cmdk](https://github.com/dip/cmdk) — the fast, composable command menu — ported
+to the [Octane](https://github.com/octanejs/octane) renderer.
+
+This is an Octane port of `cmdk@1.1.1`. It preserves cmdk's public API (the
+`Command` namespace, `useCommandState`, `defaultFilter`) and its
+DOM-authoritative filter/selection model, adapting only the React-renderer
+wiring to Octane (native events, ref-as-prop, `useId`), and building on
+[`@octanejs/radix`](../radix) for the Radix primitives cmdk depends on.
+
+> **Alpha.** The whole component set is implemented — `Command`, `Command.Input`,
+> `Command.List`, `Command.Item`, `Command.Group`, `Command.Separator`,
+> `Command.Dialog`, `Command.Empty`, `Command.Loading`, plus `useCommandState`
+> and `defaultFilter` — with filtering, score sorting, keyboard navigation,
+> controlled modes, and SSR + hydration. `asChild` is the one unsupported prop.
+> A differential suite runs the same fixture through this port and the published
+> `cmdk@1.1.1` on React and asserts byte-equal HTML. See
+> [`docs/cmdk-port-plan.md`](../../docs/cmdk-port-plan.md) and the authoritative
+> [`docs/bindings-status.md`](../../docs/bindings-status.md).
+
+## Divergences from React cmdk
+
+Standard Octane binding adaptations (see
+[`docs/react-parity-migration-plan.md`](../../docs/react-parity-migration-plan.md)):
+
+- `Command.Input` drives search from the native `onInput` event; the public
+  `onValueChange(search)` API is unchanged.
+- Components take `ref` as a normal prop (Octane has no `forwardRef`).
+- Callbacks (`onSelect`, pointer, keyboard) observe native DOM events.
+- Item/group values come from the `value` prop or the rendered `textContent`;
+  cmdk's string-child inspection is dropped (Octane's compiled children are
+  opaque).
+- `asChild` is **not** supported: cmdk clones the child element and re-parents
+  the component's own content into it, which has no faithful equivalent over
+  opaque compiled children.
+- Group reordering resolves the group element by its registered value; upstream
+  looks it up by `[data-value="<groupId>"]`, which can never match.
+- `Command.Dialog` is built on `@octanejs/radix`'s Dialog; ids come from
+  `octane`'s `useId` (prefixed to match upstream's `@radix-ui/react-id`). Radix
+  `Primitive`/`Slot` are not used — without `asChild` there is nothing to slot,
+  so every component renders its own host element.
+- `Command.Empty` and a visible item are mutually exclusive, including for
+  `forceMount` items and during SSR. Upstream can render both at once.
+- `forceMount` items are full citizens of registration: they release the value
+  they registered on unmount, and removing the selected one moves the selection
+  on. Upstream never registers them, so it does neither.
+- `Command.Dialog` also accepts `defaultOpen` and `modal`; upstream forwards
+  only `open`/`onOpenChange`.
+- After a search is cleared, items stay in the order `sort()` left them rather
+  than returning to source order — octane's reconciler does not reposition nodes
+  it did not move. Same items, same selection; only the residual order differs.
+
+## License
+
+MIT. The vendored `command-score` implementation retains its upstream MIT
+license.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@octanejs/cmdk",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "cmdk for the octane renderer — the cmdk 1.1.1 command-menu source ported onto octane's hooks and native events: the Command namespace, useCommandState, and the DOM-authoritative filter/selection model, built on @octanejs/radix primitives.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/cmdk"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@octanejs/radix": "0.1.16"
+  },
+  "peerDependencies": {
+    "octane": "0.1.17"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@tsrx/react": "^0.2.50",
+    "cmdk": "1.1.1",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "vitest": "^4.1.10",
+    "octane": "0.1.17",
+    "@octanejs/testing-library": "0.1.14"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/cmdk.tsrx

@@ -0,0 +1,52 @@
+// @octanejs/cmdk — the Command menu, ported from cmdk@1.1.1 (dip/cmdk,
+// cmdk/src/index.tsx) onto the octane renderer.
+//
+// This module is the barrel: it assembles the `Command` namespace from the
+// per-component modules under ./components and re-exports the public surface.
+// The store/registration hooks live in ./hooks.tsrx, the contexts in
+// ./context.tsrx, and the DOM constants/helpers in ./lib.
+//
+// octane adaptations (see docs/react-parity-migration-plan.md):
+// - No forwardRef: every component takes `ref` as a normal prop; composeRefs
+//   becomes octane's multi-ref `ref={[a, b]}`.
+// - Input drives search from native `onInput`; the public `onValueChange` API
+//   is unchanged (there is no synthetic `onChange`).
+// - Radix `useId` becomes octane's `useId`; the store subscribes through
+//   octane's `useSyncExternalStore`.
+// - `useValue` derives an item's value from its provided `value` prop or the
+//   rendered `textContent`; cmdk's string-child inspection is dropped because
+//   octane's compiled children are opaque render bodies.
+// - `sort()` reorders only the surviving (score > 0) items — moving a
+//   to-be-unmounted node orphans it in an octane hydrated tree (see
+//   ./components/command.tsrx).
+// - `asChild` is NOT supported: cmdk's SlottableWithNestedChildren clones a child
+//   element via React.cloneElement/isValidElement and re-parents the component's
+//   own content into it. Octane's compiled children are opaque render bodies, so
+//   that introspect-and-clone has no faithful equivalent — components always
+//   render their own host element. `Command.Dialog` composes @octanejs/radix via
+//   createElement descriptors instead.
+import { CommandRoot } from './components/command.tsrx';
+import { Item } from './components/item.tsrx';
+import { Input } from './components/input.tsrx';
+import { List } from './components/list.tsrx';
+import { Group } from './components/group.tsrx';
+import { Separator } from './components/separator.tsrx';
+import { Empty } from './components/empty.tsrx';
+import { Loading } from './components/loading.tsrx';
+import { Dialog } from './components/dialog.tsrx';
+import { useCmdk } from './hooks.tsrx';
+
+const Command = Object.assign(CommandRoot, {
+	List,
+	Item,
+	Input,
+	Group,
+	Separator,
+	Dialog,
+	Empty,
+	Loading,
+});
+
+export { Command, CommandRoot, Item, Input, List, Group, Separator, Dialog, Empty, Loading };
+export { useCmdk as useCommandState };
+export { Item as CommandItem, Input as CommandInput, List as CommandList, Group as CommandGroup, Separator as CommandSeparator, Dialog as CommandDialog, Empty as CommandEmpty, Loading as CommandLoading };

package/src/cmdk.tsrx.d.ts

@@ -0,0 +1,49 @@
+// Ambient declaration for cmdk.tsrx so `.ts` consumers and tsgo see real types
+// without parsing the .tsrx source (kept in sync with cmdk.tsrx's exports).
+import type { OctaneNode } from 'octane';
+import type {
+	CommandProps,
+	DialogProps,
+	EmptyProps,
+	GroupProps,
+	InputProps,
+	ItemProps,
+	ListProps,
+	LoadingProps,
+	SeparatorProps,
+	State,
+} from './types';
+
+export declare function CommandRoot(props: CommandProps): OctaneNode;
+export declare function Item(props: ItemProps): OctaneNode;
+export declare function Input(props: InputProps): OctaneNode;
+export declare function List(props: ListProps): OctaneNode;
+export declare function Group(props: GroupProps): OctaneNode;
+export declare function Separator(props: SeparatorProps): OctaneNode;
+export declare function Dialog(props: DialogProps): OctaneNode;
+export declare function Empty(props: EmptyProps): OctaneNode;
+export declare function Loading(props: LoadingProps): OctaneNode;
+
+export declare const Command: typeof CommandRoot & {
+	List: typeof List;
+	Item: typeof Item;
+	Input: typeof Input;
+	Group: typeof Group;
+	Separator: typeof Separator;
+	Dialog: typeof Dialog;
+	Empty: typeof Empty;
+	Loading: typeof Loading;
+};
+
+export declare function useCommandState<T>(selector: (state: State) => T): T;
+
+export {
+	Item as CommandItem,
+	Input as CommandInput,
+	List as CommandList,
+	Group as CommandGroup,
+	Separator as CommandSeparator,
+	Dialog as CommandDialog,
+	Empty as CommandEmpty,
+	Loading as CommandLoading,
+};

package/src/command-score.ts

@@ -0,0 +1,177 @@
+// Vendored from cmdk@1.1.1 (source: cmdk/src/command-score.ts, upstream repo
+// dip/cmdk). The algorithm and every score constant are unchanged. The only
+// edits are toolchain adaptations: the inner helpers gained explicit parameter
+// type annotations for this package's `strict` typecheck (upstream ships them
+// untyped), and the file is formatted to repo style. No logic was touched.
+
+// The scores are arranged so that a continuous match of characters will
+// result in a total score of 1.
+//
+// The best case, this character is a match, and either this is the start
+// of the string, or the previous character was also a match.
+var SCORE_CONTINUE_MATCH = 1,
+	// A new match at the start of a word scores better than a new match
+	// elsewhere as it's more likely that the user will type the starts
+	// of fragments.
+	// NOTE: We score word jumps between spaces slightly higher than slashes, brackets
+	// hyphens, etc.
+	SCORE_SPACE_WORD_JUMP = 0.9,
+	SCORE_NON_SPACE_WORD_JUMP = 0.8,
+	// Any other match isn't ideal, but we include it for completeness.
+	SCORE_CHARACTER_JUMP = 0.17,
+	// If the user transposed two letters, it should be significantly penalized.
+	//
+	// i.e. "ouch" is more likely than "curtain" when "uc" is typed.
+	SCORE_TRANSPOSITION = 0.1,
+	// The goodness of a match should decay slightly with each missing
+	// character.
+	//
+	// i.e. "bad" is more likely than "bard" when "bd" is typed.
+	//
+	// This will not change the order of suggestions based on SCORE_* until
+	// 100 characters are inserted between matches.
+	PENALTY_SKIPPED = 0.999,
+	// The goodness of an exact-case match should be higher than a
+	// case-insensitive match by a small amount.
+	//
+	// i.e. "HTML" is more likely than "haml" when "HM" is typed.
+	//
+	// This will not change the order of suggestions based on SCORE_* until
+	// 1000 characters are inserted between matches.
+	PENALTY_CASE_MISMATCH = 0.9999,
+	// Match higher for letters closer to the beginning of the word
+	PENALTY_DISTANCE_FROM_START = 0.9,
+	// If the word has more characters than the user typed, it should
+	// be penalised slightly.
+	//
+	// i.e. "html" is more likely than "html5" if I type "html".
+	//
+	// However, it may well be the case that there's a sensible secondary
+	// ordering (like alphabetical) that it makes sense to rely on when
+	// there are many prefix matches, so we don't make the penalty increase
+	// with the number of tokens.
+	PENALTY_NOT_COMPLETE = 0.99;
+
+var IS_GAP_REGEXP = /[\\\/_+.#"@\[\(\{&]/,
+	COUNT_GAPS_REGEXP = /[\\\/_+.#"@\[\(\{&]/g,
+	IS_SPACE_REGEXP = /[\s-]/,
+	COUNT_SPACE_REGEXP = /[\s-]/g;
+
+function commandScoreInner(
+	string: string,
+	abbreviation: string,
+	lowerString: string,
+	lowerAbbreviation: string,
+	stringIndex: number,
+	abbreviationIndex: number,
+	memoizedResults: Record<string, number>,
+): number {
+	if (abbreviationIndex === abbreviation.length) {
+		if (stringIndex === string.length) {
+			return SCORE_CONTINUE_MATCH;
+		}
+		return PENALTY_NOT_COMPLETE;
+	}
+
+	var memoizeKey = `${stringIndex},${abbreviationIndex}`;
+	if (memoizedResults[memoizeKey] !== undefined) {
+		return memoizedResults[memoizeKey];
+	}
+
+	var abbreviationChar = lowerAbbreviation.charAt(abbreviationIndex);
+	var index = lowerString.indexOf(abbreviationChar, stringIndex);
+	var highScore = 0;
+
+	var score, transposedScore, wordBreaks, spaceBreaks;
+
+	while (index >= 0) {
+		score = commandScoreInner(
+			string,
+			abbreviation,
+			lowerString,
+			lowerAbbreviation,
+			index + 1,
+			abbreviationIndex + 1,
+			memoizedResults,
+		);
+		if (score > highScore) {
+			if (index === stringIndex) {
+				score *= SCORE_CONTINUE_MATCH;
+			} else if (IS_GAP_REGEXP.test(string.charAt(index - 1))) {
+				score *= SCORE_NON_SPACE_WORD_JUMP;
+				wordBreaks = string.slice(stringIndex, index - 1).match(COUNT_GAPS_REGEXP);
+				if (wordBreaks && stringIndex > 0) {
+					score *= Math.pow(PENALTY_SKIPPED, wordBreaks.length);
+				}
+			} else if (IS_SPACE_REGEXP.test(string.charAt(index - 1))) {
+				score *= SCORE_SPACE_WORD_JUMP;
+				spaceBreaks = string.slice(stringIndex, index - 1).match(COUNT_SPACE_REGEXP);
+				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;
+			}
+		}
+
+		if (
+			(score < SCORE_TRANSPOSITION &&
+				lowerString.charAt(index - 1) === lowerAbbreviation.charAt(abbreviationIndex + 1)) ||
+			(lowerAbbreviation.charAt(abbreviationIndex + 1) ===
+				lowerAbbreviation.charAt(abbreviationIndex) && // allow duplicate letters. Ref #7428
+				lowerString.charAt(index - 1) !== lowerAbbreviation.charAt(abbreviationIndex))
+		) {
+			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(string: string): string {
+	// convert all valid space characters to space so they match each other
+	return string.toLowerCase().replace(COUNT_SPACE_REGEXP, ' ');
+}
+
+export function commandScore(string: string, abbreviation: string, aliases: string[]): number {
+	/* NOTE:
+	 * in the original, we used to do the lower-casing on each recursive call, but this meant that toLowerCase()
+	 * was the dominating cost in the algorithm, passing both is a little ugly, but considerably faster.
+	 */
+	string = aliases && aliases.length > 0 ? `${string + ' ' + aliases.join(' ')}` : string;
+	return commandScoreInner(
+		string,
+		abbreviation,
+		formatInput(string),
+		formatInput(abbreviation),
+		0,
+		0,
+		{},
+	);
+}