@stridge/noctis 1.0.0-beta.5 → 1.0.0-beta.6

package/dist/components/command/command.js

@@ -0,0 +1,471 @@
+"use client";
+import { useNoctisStringFormatter } from "../../core/use-injected-labels.js";
+import { VisuallyHidden } from "../../core/visually-hidden/visually-hidden.js";
+import { useRender } from "../../core/render.js";
+import { Surface } from "../surface/surface.js";
+import { Dialog } from "../dialog/dialog.js";
+import { CommandGroupProvider, CommandListboxProvider, useCommandGroup, useCommandListbox, useCommandListboxState, useCommandOption, useRegisterGroupLabel } from "./command-listbox.js";
+import { CommandProvider, useCommandContext } from "./command.context.js";
+import { COMMAND_SLOTS } from "./command.slots.js";
+import { breadcrumbProps, emptyProps, footerProps, groupLabelProps, groupProps, headerProps, inputActionProps, inputProps, itemIconProps, itemLabelProps, itemProps, listProps, loadingProps, panelProps, separatorProps } from "./command.props.js";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/command/command.tsx
+/** Derive the controlled-or-uncontrolled query and the drill-in handlers shared by Root and Dialog. */
+function usePaletteState({ value, defaultValue, onValueChange, pages = [], onPagesChange, loading }) {
+	const [uncontrolled, setUncontrolled] = useState(defaultValue ?? "");
+	const query = value ?? uncontrolled;
+	const setQuery = useCallback((next) => {
+		if (value === void 0) setUncontrolled(next);
+		onValueChange?.(next);
+	}, [value, onValueChange]);
+	const depth = pages.length;
+	const queryStack = useRef([]);
+	const prevDepth = useRef(depth);
+	useEffect(() => {
+		if (depth > prevDepth.current) setQuery("");
+		else if (depth < prevDepth.current) setQuery(queryStack.current[depth] ?? "");
+		prevDepth.current = depth;
+	}, [depth, setQuery]);
+	useEffect(() => {
+		queryStack.current[depth] = query;
+	}, [depth, query]);
+	const navigateTo = useCallback((index) => {
+		onPagesChange?.(index < 0 ? [] : pages.slice(0, index + 1));
+	}, [pages, onPagesChange]);
+	return {
+		query,
+		setQuery,
+		context: useMemo(() => ({
+			pages,
+			loading,
+			navigateTo
+		}), [
+			pages,
+			loading,
+			navigateTo
+		])
+	};
+}
+/** The drill-in view key — changes on push/pop (not on typing), so the highlight resets to the top of a
+* new view but persists across keystrokes within one. */
+function viewKeyFor(pages) {
+	return pages.length === 0 ? "root" : `${pages.length}:${pages[pages.length - 1].id}`;
+}
+/**
+* The interaction chassis both modes wrap. Noctis owns the combobox/listbox keyboard model directly (see
+* `command-listbox`) — auto-highlighting the top result, the smart key-repeat loop, Enter activation —
+* so the cmdk details behave exactly as a command bar should, with the input keeping focus and
+* `aria-activedescendant` tracking the highlighted row.
+*/
+function PaletteBody({ query, setQuery, context, loop = false, children }) {
+	return /* @__PURE__ */ jsx(CommandProvider, {
+		value: context,
+		children: /* @__PURE__ */ jsx(CommandListboxProvider, {
+			value: useCommandListboxState({
+				query,
+				setQuery,
+				loop,
+				viewKey: viewKeyFor(context.pages)
+			}),
+			children
+		})
+	});
+}
+/**
+* The inline palette: the command interface embedded in normal flow (a page, a sidebar, a settings
+* panel) rather than a modal. Renders the panel through `Surface` (the `menu` elevation scope, border,
+* and card shadow) and shares the query + drill-in state with every part. For the modal launcher use
+* `Command.Dialog`; both share identical inner parts.
+*
+* @see {@link CommandRootProps}
+*/
+function CommandRoot({ value, defaultValue, onValueChange, pages, onPagesChange, loading, loop, children, ...props }) {
+	return /* @__PURE__ */ jsx(PaletteBody, {
+		...usePaletteState({
+			value,
+			defaultValue,
+			onValueChange,
+			pages,
+			onPagesChange,
+			loading
+		}),
+		loop,
+		children: /* @__PURE__ */ jsx(Surface, {
+			elevation: "menu",
+			bordered: true,
+			shadow: "card",
+			"data-slot": COMMAND_SLOTS.panel,
+			...props,
+			children
+		})
+	});
+}
+/**
+* The modal palette: the centred, focus-trapped command launcher built on the Noctis `Dialog` chassis
+* (portal, blurred backdrop, scroll-lock, Esc/outside-click dismissal) with a top-anchored, fixed-height
+* panel that scale-fades in. Wire `open`/`onOpenChange` to a `Command.Trigger` (or any control). Shares
+* identical inner parts with the inline `Command.Root`.
+*
+* @see {@link CommandDialogProps}
+*/
+function CommandDialog({ open, onOpenChange, label, value, defaultValue, onValueChange, pages, onPagesChange, loading, loop, children }) {
+	const state = usePaletteState({
+		value,
+		defaultValue,
+		onValueChange,
+		pages,
+		onPagesChange,
+		loading
+	});
+	const formatter = useNoctisStringFormatter();
+	const dialogLabel = label ?? formatter.format("command.label");
+	return /* @__PURE__ */ jsx(Dialog.Root, {
+		open,
+		onOpenChange,
+		children: /* @__PURE__ */ jsxs(Dialog.Portal, { children: [/* @__PURE__ */ jsx(Dialog.Backdrop, { "data-slot": COMMAND_SLOTS.backdrop }), /* @__PURE__ */ jsxs(Dialog.Popup, {
+			elevation: "menu",
+			"data-slot": COMMAND_SLOTS.panel,
+			"data-modal": "",
+			children: [/* @__PURE__ */ jsx(Dialog.Title, {
+				"data-slot": "noctis-visually-hidden",
+				render: /* @__PURE__ */ jsx(VisuallyHidden, {}),
+				children: dialogLabel
+			}), /* @__PURE__ */ jsx(PaletteBody, {
+				...state,
+				loop,
+				children
+			})]
+		})] })
+	});
+}
+/**
+* A headless launcher for the modal palette. It wires only behaviour and accessibility — `onClick` to
+* open, `aria-haspopup="dialog"`, and `aria-expanded` — onto whatever element you render, so you bring
+* your own `Button`/`Kbd` visuals. Wire the same `open`/`onOpenChange` state you pass to `Command.Dialog`.
+*
+* @see {@link CommandTriggerProps}
+*/
+function CommandTrigger({ open, onOpenChange, render, ref, onClick, ...props }) {
+	return useRender({
+		defaultTagName: "button",
+		render,
+		ref,
+		props: {
+			type: "button",
+			"aria-haspopup": "dialog",
+			"aria-expanded": open ?? void 0,
+			onClick: (event) => {
+				onClick?.(event);
+				if (!event.defaultPrevented) onOpenChange?.(true);
+			},
+			...props
+		}
+	});
+}
+/** The input row: holds an optional `Command.Breadcrumb`, a leading glyph, the `Command.Input`, and an
+* optional `Command.InputAction`, over a hairline divider. */
+function CommandHeader({ children, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		...headerProps(),
+		...props,
+		children
+	});
+}
+/**
+* The drill-in trail. Renders one button per page in the stack and nothing at the top level; clicking a
+* segment truncates the stack back to its depth. Reads the stack from context — just drop it in the
+* header.
+*/
+function CommandBreadcrumb(props) {
+	const { pages, navigateTo } = useCommandContext("Breadcrumb");
+	if (pages.length === 0) return null;
+	return /* @__PURE__ */ jsx("div", {
+		...breadcrumbProps(),
+		...props,
+		children: pages.map((page, index) => /* @__PURE__ */ jsx("button", {
+			type: "button",
+			onClick: () => navigateTo(index),
+			children: page.label
+		}, page.id))
+	});
+}
+/**
+* The query field — a `role="combobox"` that keeps focus while a virtual cursor (`aria-activedescendant`)
+* moves the active row. Typing filters (you rank externally); arrows / Home / End / PageUp-Down move the
+* highlight, Enter activates it, and Backspace on an empty query pops the drill-in stack. The keyboard
+* model is the palette's own (see `command-listbox`), not a delegated primitive's.
+*
+* @see {@link CommandInput.Props}
+*/
+function CommandInput({ onKeyDown, ...props }) {
+	const { pages, navigateTo } = useCommandContext("Input");
+	const { query, setQuery, listId, activeId, onInputKeyDown } = useCommandListbox("Input");
+	return /* @__PURE__ */ jsx("input", {
+		"data-slot": COMMAND_SLOTS.input,
+		type: "text",
+		role: "combobox",
+		value: query,
+		"aria-expanded": true,
+		"aria-controls": listId,
+		"aria-activedescendant": activeId,
+		"aria-autocomplete": "list",
+		autoComplete: "off",
+		autoCorrect: "off",
+		spellCheck: false,
+		...props,
+		onChange: (event) => setQuery(event.target.value),
+		onKeyDown: (event) => {
+			onKeyDown?.(event);
+			if (event.defaultPrevented || event.nativeEvent.isComposing) return;
+			if (event.key === "Backspace" && event.currentTarget.value === "" && pages.length > 0) {
+				event.preventDefault();
+				navigateTo(pages.length - 2);
+				return;
+			}
+			onInputKeyDown(event);
+		}
+	});
+}
+/** A trailing affordance slot in the input row (a mode pill, an "ask" hand-off, a hint). */
+function CommandInputAction({ children, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		...inputActionProps(),
+		...props,
+		children
+	});
+}
+/** The CSS var the list animates its `block-size` off; the hook writes the measured content height here. */
+const LIST_HEIGHT_VAR = "--_command-list-height";
+/**
+* Drive the palette's height animation. The rows live in a measured inner sizer; a `ResizeObserver`
+* watches it and writes its current height to the list's `--_command-list-height` var, so the list (and
+* the auto-height panel riding on it) animates smoothly between sizes as the rows change instead of
+* snapping. The list's own `transition` does the tweening; this only feeds it concrete heights.
+*/
+function useListAutoHeight(sizerRef) {
+	useEffect(() => {
+		const sizer = sizerRef.current;
+		/* v8 ignore next -- the sizer ref is always attached by the time the effect runs */
+		if (!sizer) return void 0;
+		const list = sizer.parentElement;
+		/* v8 ignore next -- the sizer always renders inside the list element */
+		if (!list) return void 0;
+		const observer = new ResizeObserver(() => {
+			list.style.setProperty(LIST_HEIGHT_VAR, `${sizer.offsetHeight}px`);
+		});
+		observer.observe(sizer);
+		return () => observer.disconnect();
+	}, [sizerRef]);
+}
+/**
+* The scrolling `role="listbox"` of command rows and sections. The rows render inside a measured sizer so
+* the palette can animate its height as the result set changes (see {@link useListAutoHeight}). Within it,
+* a per-page view wrapper is keyed by the drill-in depth: pushing or popping a page remounts it, so its
+* CSS enter animation replays — the old view gives way and the new one opens — while a query change (same
+* page) leaves it in place so typing doesn't re-animate.
+*/
+function CommandList({ children, ...props }) {
+	const sizerRef = useRef(null);
+	const { pages } = useCommandContext("List");
+	const { listId, listRef } = useCommandListbox("List");
+	useListAutoHeight(sizerRef);
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": COMMAND_SLOTS.list,
+		role: "listbox",
+		id: listId,
+		ref: listRef,
+		...props,
+		children: /* @__PURE__ */ jsx("div", {
+			ref: sizerRef,
+			"data-slot": COMMAND_SLOTS.listSizer,
+			children: /* @__PURE__ */ jsx("div", {
+				"data-slot": COMMAND_SLOTS.listView,
+				children
+			}, viewKeyFor(pages))
+		})
+	});
+}
+/** A labelled section: a `role="group"` wrapping a `Command.GroupLabel` and its rows, `aria-labelledby`
+* the label while one is rendered. */
+function CommandGroup({ children, ...props }) {
+	const { labelId, setLabelId } = useCommandGroup();
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": COMMAND_SLOTS.group,
+		role: "group",
+		"aria-labelledby": labelId,
+		...props,
+		children: /* @__PURE__ */ jsx(CommandGroupProvider, {
+			value: setLabelId,
+			children
+		})
+	});
+}
+/** A section heading (not an option). Lends its id to the enclosing `Command.Group`'s `aria-labelledby`. */
+function CommandGroupLabel({ children, ...props }) {
+	const id = useId();
+	useRegisterGroupLabel(id);
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": COMMAND_SLOTS.groupLabel,
+		id,
+		...props,
+		children
+	});
+}
+/**
+* One command row (`role="option"`). Activated by click or by pressing Enter while highlighted
+* (`onSelect`). Compose a `Command.ItemIcon` and a `Command.ItemLabel` inside; any further content (a
+* `Kbd` shortcut, a badge, a count) is pushed to the row's end by the label's `flex` — the row stays
+* yours to fill past the icon. Hovering highlights it; the keyboard highlight (`data-highlighted`, the
+* input's `aria-activedescendant`) is the palette's own; activation runs the action, never fills the query.
+*
+* @see {@link CommandItem.Props}
+*/
+function CommandItem({ value, disabled, onSelect, onClick, onPointerMove, children, ...props }) {
+	const { id, active, setActive } = useCommandOption();
+	return /* @__PURE__ */ jsx("div", {
+		...itemProps({
+			highlighted: active,
+			disabled
+		}),
+		id,
+		role: "option",
+		tabIndex: -1,
+		"aria-selected": active,
+		"aria-disabled": disabled || void 0,
+		"data-value": value,
+		...props,
+		onPointerMove: (event) => {
+			onPointerMove?.(event);
+			if (!disabled) setActive();
+		},
+		onClick: (event) => {
+			if (disabled) return;
+			onClick?.(event);
+			if (!event.defaultPrevented) onSelect?.(value);
+		},
+		children
+	});
+}
+/** The leading glyph column of a row (wrap an `Icon` so it keeps its token sizing). */
+function CommandItemIcon({ children, ...props }) {
+	return /* @__PURE__ */ jsx("span", {
+		...itemIconProps(),
+		...props,
+		children
+	});
+}
+/** The row's text column (truncates rather than wrapping). */
+function CommandItemLabel({ children, ...props }) {
+	return /* @__PURE__ */ jsx("span", {
+		...itemLabelProps(),
+		...props,
+		children
+	});
+}
+/** A thin divider between sections. */
+function CommandSeparator(props) {
+	return /* @__PURE__ */ jsx("div", {
+		role: "separator",
+		...separatorProps(),
+		...props
+	});
+}
+/**
+* The centred no-results message. A polite live region so screen readers announce it; render it
+* conditionally when your ranked list is empty (you own the data, so you know when there's nothing to
+* show — Noctis doesn't filter internally).
+*/
+function CommandEmpty({ children, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		role: "status",
+		"aria-live": "polite",
+		...emptyProps(),
+		...props,
+		children
+	});
+}
+/** The centred async progress shell, shown before results settle (compose a spinner glyph + copy). */
+function CommandLoading({ children, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		...loadingProps(),
+		...props,
+		children
+	});
+}
+/**
+* The footer region — a bare, end-aligned strip below the list. Unopinionated about its contents: drop
+* in whatever status or hints you want (e.g. `Kbd` caps beside a label). The component ships no
+* "hint" part, so you own the markup.
+*/
+function CommandFooter({ children, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		...footerProps(),
+		...props,
+		children
+	});
+}
+/**
+* An accessible command palette — a query field over a ranked, sectioned list of commands with full
+* combobox/`aria-activedescendant` keyboard navigation and breadcrumb drill-in. Ships as a modal
+* (`Command.Dialog` + a headless `Command.Trigger`) or inline (`Command.Root`); both share identical
+* inner parts. Ranking is owned by Noctis — rank your commands with the exported `rankItems` /
+* `useCommandRanking` and render the survivors as `Command.Item`s.
+*
+* @example
+* ```tsx
+* const ranked = rankItems(commands, query);
+* <Command.Dialog open={open} onOpenChange={setOpen} value={query} onValueChange={setQuery}>
+*   <Command.Header>
+*     <SearchIcon />
+*     <Command.Input placeholder="Type a command…" />
+*   </Command.Header>
+*   <Command.List>
+*     <Command.Empty>No commands found.</Command.Empty>
+*     {ranked.map((c) => (
+*       <Command.Item key={c.value} value={c.value} onSelect={c.run}>
+*         <Command.ItemLabel>{c.label}</Command.ItemLabel>
+*       </Command.Item>
+*     ))}
+*   </Command.List>
+* </Command.Dialog>
+* ```
+*/
+const Command = {
+	/** The inline palette (embedded in normal flow). `Command.Root.props()` → its spreadable panel prop bag. */
+	Root: Object.assign(CommandRoot, { props: panelProps }),
+	/** The modal palette (centred, focus-trapped). */
+	Dialog: CommandDialog,
+	/** A headless launcher that wires open + ARIA onto your own button. */
+	Trigger: CommandTrigger,
+	/** The input row. `Command.Header.props()` → its spreadable prop bag. */
+	Header: Object.assign(CommandHeader, { props: headerProps }),
+	/** The drill-in trail. `Command.Breadcrumb.props()` → its spreadable prop bag. */
+	Breadcrumb: Object.assign(CommandBreadcrumb, { props: breadcrumbProps }),
+	/** The query field. `Command.Input.props()` → its spreadable prop bag. */
+	Input: Object.assign(CommandInput, { props: inputProps }),
+	/** The trailing input affordance. `Command.InputAction.props()` → its spreadable prop bag. */
+	InputAction: Object.assign(CommandInputAction, { props: inputActionProps }),
+	/** The scrolling listbox. `Command.List.props()` → its spreadable prop bag. */
+	List: Object.assign(CommandList, { props: listProps }),
+	/** A labelled section. `Command.Group.props()` → its spreadable prop bag. */
+	Group: Object.assign(CommandGroup, { props: groupProps }),
+	/** A section heading. `Command.GroupLabel.props()` → its spreadable prop bag. */
+	GroupLabel: Object.assign(CommandGroupLabel, { props: groupLabelProps }),
+	/** One command row. `Command.Item.props({ highlighted, disabled })` → its spreadable prop bag for a foreign element. */
+	Item: Object.assign(CommandItem, { props: itemProps }),
+	/** The leading row glyph. `Command.ItemIcon.props()` → its spreadable prop bag. */
+	ItemIcon: Object.assign(CommandItemIcon, { props: itemIconProps }),
+	/** The row's text column. `Command.ItemLabel.props()` → its spreadable prop bag. */
+	ItemLabel: Object.assign(CommandItemLabel, { props: itemLabelProps }),
+	/** A section divider. `Command.Separator.props()` → its spreadable prop bag. */
+	Separator: Object.assign(CommandSeparator, { props: separatorProps }),
+	/** The no-results message. `Command.Empty.props()` → its spreadable prop bag. */
+	Empty: Object.assign(CommandEmpty, { props: emptyProps }),
+	/** The async progress shell. `Command.Loading.props()` → its spreadable prop bag. */
+	Loading: Object.assign(CommandLoading, { props: loadingProps }),
+	/** The footer region (compose your own status/hints). `Command.Footer.props()` → its spreadable prop bag. */
+	Footer: Object.assign(CommandFooter, { props: footerProps })
+};
+//#endregion
+export { Command };

package/dist/components/command/command.props.d.ts

@@ -0,0 +1,91 @@
+//#region src/components/command/command.props.d.ts
+/** A spreadable data-attribute prop bag — the shape every `Command.*.props()` returns. */
+type CommandPartProps = {
+  /** The slot value the matching `command.css` rules anchor on. */"data-slot": string; /** Forwarded verbatim — styling is attribute-driven, so this is an optional consumer passthrough. */
+  className?: string; /** A data-attribute present (empty string) or absent (`undefined`); never `false`. */
+  [attr: `data-${string}`]: string | undefined;
+};
+/** Common shape: every part's `.props()` accepts an optional `className` passthrough. */
+interface BasePropsArgs {
+  /** Forwarded verbatim onto the returned prop bag. */
+  className?: string;
+}
+/** Argument to `Command.Panel.props(...)` — whether the panel is in its modal (centred popup) form. */
+interface CommandPanelPropsArgs extends BasePropsArgs {
+  /** Whether the panel is the modal popup (drives the fixed-position scale-fade via `data-modal`). */
+  modal?: boolean;
+}
+/** Argument to `Command.Item.props(...)` — the per-row state the CSS keys its highlight off. */
+interface CommandItemPropsArgs extends BasePropsArgs {
+  /** Whether the pointer/keyboard is over this row (drives the highlight via `data-highlighted`). */
+  highlighted?: boolean;
+  /** Whether this row is disabled (drives the not-allowed affordance via `data-disabled`). */
+  disabled?: boolean;
+}
+/** Argument to a stateless part's `.props(...)` — no variants/state of its own. */
+type CommandStatelessPropsArgs = BasePropsArgs;
+/** Panel prop bag: the slot anchor plus the modal flag (the surface paint is owned by the composed Surface). */
+declare function panelProps({
+  modal,
+  className
+}?: CommandPanelPropsArgs): CommandPartProps;
+/** Header prop bag: just the slot anchor (the input row). */
+declare function headerProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Breadcrumb prop bag: just the slot anchor (the drill-in trail). */
+declare function breadcrumbProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Input prop bag: just the slot anchor (the query field). */
+declare function inputProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Input-action prop bag: just the slot anchor (the trailing affordance). */
+declare function inputActionProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** List prop bag: just the slot anchor (the scrolling listbox). */
+declare function listProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Group prop bag: just the slot anchor (a labelled section). */
+declare function groupProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Group-label prop bag: just the slot anchor (a section heading). */
+declare function groupLabelProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Item prop bag: slot anchor plus the `data-highlighted`/`data-disabled` state. */
+declare function itemProps({
+  highlighted,
+  disabled,
+  className
+}?: CommandItemPropsArgs): CommandPartProps;
+/** Item-icon prop bag: just the slot anchor (the leading row glyph). */
+declare function itemIconProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Item-label prop bag: just the slot anchor (the row's text column). */
+declare function itemLabelProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Separator prop bag: just the slot anchor (a section divider). */
+declare function separatorProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Empty prop bag: just the slot anchor (the no-results message). */
+declare function emptyProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Loading prop bag: just the slot anchor (the async progress shell). */
+declare function loadingProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+/** Footer prop bag: just the slot anchor (the footer region). */
+declare function footerProps({
+  className
+}?: CommandStatelessPropsArgs): CommandPartProps;
+//#endregion
+export { CommandPartProps, breadcrumbProps, emptyProps, footerProps, groupLabelProps, groupProps, headerProps, inputActionProps, inputProps, itemIconProps, itemLabelProps, itemProps, listProps, loadingProps, panelProps, separatorProps };

package/dist/components/command/command.props.js

@@ -0,0 +1,94 @@
+import { COMMAND_SLOTS } from "./command.slots.js";
+//#region src/components/command/command.props.ts
+/**
+* The D12 unified variant contract for Command — a per-part set of `props(...)` builders that each
+* return a **spreadable props object** of the form `{ "data-slot": "noctis-command-<part>",
+* ...dataAttrs }`, derived from the part's variant/state inputs.
+*
+* Under the single-`data-slot` anchor model the `data-slot` is the only styling hook needed —
+* `command.css` keys every rule off it — so spreading a part's `props()` onto a *foreign* element
+* styles it as that part:
+*
+*     <li {...Command.Item.props({ highlighted: true })}>Transfer assets…</li>
+*     // → <li data-slot="noctis-command-item" data-highlighted="">
+*
+* The escape hatch carries no className (styling is attribute-driven); an optional `className`
+* passthrough is accepted and forwarded verbatim. The same variant→data-attribute→values mapping is
+* emitted as data from the token graph (`generated/declarations.json` → `variantSchema`) so non-React /
+* agent consumers can hand-write the markup from the docs.
+*/
+/** Stamp a boolean state as a bare data-attribute: present (`""`) when on, absent (`undefined`) when off. */
+const flag = (on) => on ? "" : void 0;
+const withClassName = (bag, className) => className === void 0 ? bag : {
+	...bag,
+	className
+};
+/** Panel prop bag: the slot anchor plus the modal flag (the surface paint is owned by the composed Surface). */
+function panelProps({ modal, className } = {}) {
+	return withClassName({
+		"data-slot": COMMAND_SLOTS.panel,
+		"data-modal": flag(modal)
+	}, className);
+}
+/** Header prop bag: just the slot anchor (the input row). */
+function headerProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.header }, className);
+}
+/** Breadcrumb prop bag: just the slot anchor (the drill-in trail). */
+function breadcrumbProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.breadcrumb }, className);
+}
+/** Input prop bag: just the slot anchor (the query field). */
+function inputProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.input }, className);
+}
+/** Input-action prop bag: just the slot anchor (the trailing affordance). */
+function inputActionProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.inputAction }, className);
+}
+/** List prop bag: just the slot anchor (the scrolling listbox). */
+function listProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.list }, className);
+}
+/** Group prop bag: just the slot anchor (a labelled section). */
+function groupProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.group }, className);
+}
+/** Group-label prop bag: just the slot anchor (a section heading). */
+function groupLabelProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.groupLabel }, className);
+}
+/** Item prop bag: slot anchor plus the `data-highlighted`/`data-disabled` state. */
+function itemProps({ highlighted, disabled, className } = {}) {
+	return withClassName({
+		"data-slot": COMMAND_SLOTS.item,
+		"data-highlighted": flag(highlighted),
+		"data-disabled": flag(disabled)
+	}, className);
+}
+/** Item-icon prop bag: just the slot anchor (the leading row glyph). */
+function itemIconProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.itemIcon }, className);
+}
+/** Item-label prop bag: just the slot anchor (the row's text column). */
+function itemLabelProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.itemLabel }, className);
+}
+/** Separator prop bag: just the slot anchor (a section divider). */
+function separatorProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.separator }, className);
+}
+/** Empty prop bag: just the slot anchor (the no-results message). */
+function emptyProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.empty }, className);
+}
+/** Loading prop bag: just the slot anchor (the async progress shell). */
+function loadingProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.loading }, className);
+}
+/** Footer prop bag: just the slot anchor (the footer region). */
+function footerProps({ className } = {}) {
+	return withClassName({ "data-slot": COMMAND_SLOTS.footer }, className);
+}
+//#endregion
+export { breadcrumbProps, emptyProps, footerProps, groupLabelProps, groupProps, headerProps, inputActionProps, inputProps, itemIconProps, itemLabelProps, itemProps, listProps, loadingProps, panelProps, separatorProps };

package/dist/components/command/command.slots.d.ts

@@ -0,0 +1,23 @@
+//#region src/components/command/command.slots.d.ts
+/**
+ * The `data-*` hooks `Command` stamps on its parts, for host-side styling and tests. Slot values mark
+ * each rendered element; the state attributes are emitted by the palette's own combobox/listbox engine
+ * (which drives the keyboard model — see `command-listbox`) and by the composed Dialog — pair a slot with
+ * a state to target, say, the highlighted row or the modal panel while it transitions in.
+ */
+declare enum CommandDataAttributes {
+  /** Marks each rendered part. */
+  slot = "data-slot",
+  /** Present on the panel in its modal form (the centred, fixed-height, scale-fading popup). */
+  modal = "data-modal",
+  /** Present on the command row the pointer or keyboard is currently over (the active descendant). */
+  highlighted = "data-highlighted",
+  /** Present on a disabled command row. */
+  disabled = "data-disabled",
+  /** Present on the modal panel/scrim for the first frame after mount — the transition's start state. */
+  startingStyle = "data-starting-style",
+  /** Present on the modal panel/scrim while it transitions out before unmounting. */
+  endingStyle = "data-ending-style"
+}
+//#endregion
+export { CommandDataAttributes };