@octanejs/cmdk 0.1.17 → 0.1.19

package/README.md

@@ -15,7 +15,9 @@ wiring to Octane (native events, ref-as-prop, `useId`), and building on
 > 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
+> `cmdk@1.1.1` on React and asserts byte-equal HTML for its declared cases. The
+> canonical upstream Playwright suite is vendored but not yet adapted
+> exhaustively, so parity remains recorded-unverified. See [`UPSTREAM.md`](./UPSTREAM.md),
 > [`docs/cmdk-port-plan.md`](../../docs/cmdk-port-plan.md) and the authoritative
 > [`docs/bindings-status.md`](../../docs/bindings-status.md).
 
@@ -47,9 +49,10 @@ Standard Octane binding adaptations (see
   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.
+- Score ranking uses CSS `order` while filtering instead of physically moving
+  renderer-owned nodes. Clearing the search removes those declarations and
+  restores source order; DOM-order selectors can differ from visual order while
+  a filter is active.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/cmdk",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -30,21 +30,23 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@octanejs/radix": "0.1.33"
+    "@octanejs/radix": "0.1.35"
   },
   "peerDependencies": {
-    "octane": "0.1.34"
+    "octane": "0.1.36"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@tsrx/react": "^0.2.56",
     "cmdk": "1.1.1",
     "esbuild": "^0.28.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
     "vitest": "^4.1.10",
-    "@octanejs/testing-library": "0.1.31",
-    "octane": "0.1.34"
+    "@octanejs/testing-library": "0.1.33",
+    "octane": "0.1.36"
   },
   "scripts": {
     "test": "vitest run"

package/src/cmdk.tsrx

@@ -19,7 +19,8 @@
 // - `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
+// - OCTANE DIVERGENCE[as-child-unsupported][differential:cmdk-as-child]:
+//   `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

package/src/components/command.tsrx

@@ -130,6 +130,7 @@ export function CommandRoot(props: CommandProps) @{
 					}
 					ids.current.set(id, { value: itemValue ?? '', keywords });
 					state.current.filtered.items.set(id, score(itemValue ?? '', keywords));
+					// OCTANE DIVERGENCE[value-change-filter-refresh][differential:cmdk-value-change-filter]:
 					// Re-derive the aggregate before sorting. Scoring this one item
 					// updates `filtered.items` but leaves `filtered.count` and
 					// `filtered.groups` describing the previous values, and those two
@@ -167,7 +168,8 @@ export function CommandRoot(props: CommandProps) @{
 					// An item leaving its group has to be dropped from that group's member
 					// set too, or the set accumulates dead ids for the Command's lifetime
 					// (unbounded growth in a menu whose results churn) and filterItems()
-					// walks them on every keystroke.
+					// walks them on every keystroke. Documented in status.json; no paired
+					// DOM oracle distinguishes the bookkeeping from upstream.
 					if (groupId) allGroups.current.get(groupId)?.delete(id);
 					const selectedItem = getSelectedItem();
 
@@ -194,9 +196,13 @@ export function CommandRoot(props: CommandProps) @{
 				schedule(8, () => store.emit());
 
 				return () => {
+					// OCTANE DIVERGENCE[force-mount-empty-count][differential:cmdk-force-mount-empty]:
+					// Releasing the force-mount count on unmount is required so Empty can
+					// reappear once no force-mounted item remains visible.
 					releaseValue(id);
 					allForceMounted.current.delete(id);
 					state.current.forceMountedCount = allForceMounted.current.size;
+					// OCTANE DIVERGENCE[selected-force-mount-teardown][differential:cmdk-selected-force-mount]:
 					// A force-mounted item is selectable like any other, so losing the
 					// selected one has to move the selection on — exactly as the plain
 					// item teardown does. Without this the value stays pointing at a node
@@ -250,6 +256,8 @@ export function CommandRoot(props: CommandProps) @{
 		const owners = (valueOwners.current.get(next) ?? 0) + 1;
 		valueOwners.current.set(next, owners);
 		if (owners > 1) {
+			// OCTANE DIVERGENCE[duplicate-value-warning][differential:cmdk-duplicate-value]:
+			// Development builds report duplicate values; upstream accepts them silently.
 			console.warn(
 				`[@octanejs/cmdk] ${owners} items share the value ${JSON.stringify(next)}. ` +
 					`Selection is keyed by value, so they will all appear selected at once and ` +
@@ -399,7 +407,7 @@ export function CommandRoot(props: CommandProps) @{
 	/**
  * Order items by score, and groups by their best item score, using CSS `order`.
  *
- * OCTANE DIVERGENCE: cmdk's sort is DOM-authoritative — it puts matches in
+ * OCTANE DIVERGENCE[runtime-adaptation-divergences][differential:cmdk-filter-selection-empty]: cmdk's sort is DOM-authoritative — it puts matches in
  * score order by physically relocating item nodes into the list sizer. Octane
  * fences every component's DOM with a pair of comment markers and tracks the
  * range between them, and a template construct like `@for` or `@if` wraps each
@@ -418,7 +426,8 @@ export function CommandRoot(props: CommandProps) @{
  * The cost is that the sizer and each group's item container become flex
  * columns while a filter is active, so a consumer who relies on physical DOM
  * order (`:nth-child` styling, drag handles) or on a custom container
- * `display` sees a divergence from upstream. Recorded in status.json.
+ * `display` sees a divergence from upstream. This marker authenticates ranking
+ * and aria wiring only; event/ref adaptations are out of scope for this case.
  */
 	function sort() {
 		if (!state.current.search || propsRef.current.shouldFilter === false) {
@@ -453,6 +462,7 @@ export function CommandRoot(props: CommandProps) @{
 		// ranks below continue past them instead of tying.
 		let topLevel = 0;
 
+		// OCTANE DIVERGENCE[force-mount-rank-order][differential:cmdk-force-mount-rank]:
 		// EVERY valid item gets a rank, not just the matches. A non-match usually
 		// unmounts and never needs one, but a force-mounted item never scores and
 		// never unmounts — and an unranked child keeps the initial `order` of 0,
@@ -488,7 +498,7 @@ export function CommandRoot(props: CommandProps) @{
 			setStyle(node, 'order', String(group ? rank + 1 : topLevel += 1));
 		});
 
-		// OCTANE DIVERGENCE: upstream looks each group element up by
+		// OCTANE DIVERGENCE[corrected-group-ordering][differential:cmdk-groups]: upstream looks each group element up by
 		// `[cmdk-group=""][data-value="<groupId>"]`, but `data-value` holds the
 		// group's VALUE (its heading text), never its id — so upstream's selector
 		// can never match and its group reordering is effectively dead code.

package/src/components/dialog.tsrx

@@ -23,6 +23,10 @@ export function Dialog(props: DialogProps) {
 		...etc
 	} = props;
 
+	// OCTANE DIVERGENCE[dialog-default-open][differential:cmdk-dialog-default-open]:
+	// Upstream forwards only open/onOpenChange; the port also wires defaultOpen
+	// through to the Radix root. `modal` is forwarded too, but that prop is outside
+	// this record's observing case.
 	return createElement(
 		RadixDialog.Root,
 		{ open, defaultOpen, onOpenChange, modal },

package/src/components/empty.tsrx

@@ -6,6 +6,7 @@ import type { EmptyProps } from '../types';
 export function Empty(props: EmptyProps) @{
 	const store = useStore()!;
 
+	// OCTANE DIVERGENCE[force-mount-empty-count][differential:cmdk-force-mount-empty]:
 	// Force-mounted items never enter `filtered.count`, so consult both: "no
 	// results" must not render while any item is visible.
 	const snapshot = () => {
@@ -13,6 +14,7 @@ export function Empty(props: EmptyProps) @{
 		return state.filtered.count === 0 && state.forceMountedCount === 0;
 	};
 
+	// OCTANE DIVERGENCE[ssr-empty-suppressed][differential:cmdk-ssr-empty]:
 	// 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

package/src/components/item.tsrx

@@ -40,11 +40,10 @@ export function Item(props: ItemProps) @{
 					// 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.
+					// forever. Upstream reads string children synchronously; octane's
+					// compiled children are opaque, so the first render IS the
+					// registration. Rendering unscored items lets that first pass
+					// happen; the next filter pass hides it if it does not match.
 					s.filtered.items.has(id)
 						? (s.filtered.items.get(id) ?? 0) > 0
 						: true,

package/src/hooks.tsrx

@@ -109,10 +109,11 @@ export function useScheduleLayoutEffect() {
 			try {
 				f();
 			} catch (error) {
+				// OCTANE DIVERGENCE[batcher-isolation][differential:cmdk-batcher-isolation]:
 				// 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.
+				// exception raised inside an effect. Upstream rethrows out of the flush.
 				console.error(error);
 			}
 		}