@ailuracode/alpine-command 1.0.0 → 2.0.0

package/README.md

@@ -1,26 +1,135 @@
 # @ailuracode/alpine-command
 
-Headless command palette store for Alpine.js — searchable actions, keyboard navigation, groups, and shortcuts. Compose optionally with dialog and toast plugins.
-
-**[Full documentation →](../../docs/plugins/command.md)**
+Headless command palette (Spotlight-style) store — searchable actions, groups, keyboard navigation, nested pages, async execution, aliases, and ARIA helpers.
 
 ## Install
 
 ```bash
-pnpm add @ailuracode/alpine-command alpinejs
+pnpm add @ailuracode/alpine-command @ailuracode/alpine-core alpinejs
+```
+
+Active item navigation uses inline helpers — no extra dependency.
+
+## Quick start
+
+```js
+import Alpine from "alpinejs";
+import { commandPlugin } from "@ailuracode/alpine-command";
+
+Alpine.plugin(
+  commandPlugin({
+    searchStrategy: "substring",
+    onRun(item) {
+      console.log("Ran", item.id);
+    },
+    persistence: {
+      maxRecent: 8,
+      getRecent: () => JSON.parse(localStorage.getItem("recent-commands") ?? "[]"),
+      setRecent: (ids) => localStorage.setItem("recent-commands", JSON.stringify(ids)),
+    },
+  })
+);
+Alpine.start();
 ```
 
 ## Store API
 
+| Member | Description |
+|--------|-------------|
+| `open()` / `close()` / `toggle()` | Palette visibility |
+| `isOpen` | Whether the palette is open |
+| `search` | Reactive filter string |
+| `activeIndex` | Keyboard-highlighted row |
+| `filteredItems` / `visibleItems` | Visible commands for the current page |
+| `groupedItems` | Filtered items grouped by `group` |
+| `register(item)` | Register an action; returns `unregister()` |
+| `run(id)` / `cancelRun()` | Execute or cancel in-flight async work |
+| `pushPage(page)` / `goBack()` | Nested command pages |
+| `executionState` / `runningId` | Async execution state |
+| `inputProps()` / `listboxProps()` / `optionProps(id)` | Headless ARIA props |
+| `handleKeydown(event)` | Typing, Backspace, Arrow/Home/End/Enter/Escape |
+
+### Command item
+
 ```ts
-$store.command.open();
-$store.command.search = "theme";
-$store.command.register({
+{
   id: "toggle-theme",
   label: "Toggle theme",
-  group: "Appearance",
-  shortcut: "⌘K",
+  group?: "Appearance",
+  shortcut?: "⌘K",
+  keywords?: ["dark", "light"],
+  aliases?: ["spotlight"],
+  disabled?: false | (() => boolean),
+  hidden?: false | (() => boolean),
+  enabled?: true | (() => boolean),
+  pinned?: false,
+  page?: "root",
+  load?: async () => {},
   action: () => {},
-});
-$store.command.run("toggle-theme");
+}
 ```
+
+### Search
+
+- Default strategy: substring ranking on label, aliases, keywords, group, and shortcut
+- `searchStrategy: "fuzzy"` enables lightweight fuzzy matching
+- `rank(item, search)` replaces the deprecated `filter(item, search)` boolean API
+
+Disabled commands remain visible unless `hidden` is true. Keyboard navigation and `run()` skip disabled or loading commands.
+
+## Plugin options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `id` | auto-generated | Controller identifier |
+| `rank` / `searchStrategy` | substring | Ranker for the filter pipeline |
+| `persistence` | — | Recent/pinned hooks (maxRecent, getRecent, setRecent, getPinned, setPinned) |
+| `storeKey` | `'command'` | `$store` key the Alpine plugin registers under |
+| `magicKey` | `'command'` (or `storeKey` when renamed) | `$command` magic key the Alpine plugin registers under |
+
+### Avoiding name collisions
+
+If your application already owns a `$store.command` or another toolkit plugin registers on that name, rename the integration surface without touching the controller:
+
+```ts
+Alpine.plugin(commandPlugin({
+  storeKey: "palette",         // → $store.palette
+  // magicKey follows storeKey by default → $palette
+  magicKey: "cmd",             // explicit override → $cmd
+}));
+```
+
+`storeKey` is the only argument most hosts need. `magicKey` moves independently only when both names must be freed. The exposed constants `DEFAULT_COMMAND_STORE_KEY` and `DEFAULT_COMMAND_MAGIC_KEY` keep the rename discoverable from TypeScript.
+
+## Integration
+
+- **Overlay** — optional `overlayId` documents a palette layer id for `$store.overlay.zIndexOf(overlayId, layer)`
+- **Scroll** — pass `scroll: $store.scroll` to lock page scroll while open (enabled by default when provided)
+- **Keyboard** — global open shortcuts remain consumer-owned; compose with `@ailuracode/alpine-keyboard` when needed
+- **Dialog / Toast** — render the palette in a dialog panel or call `$toast()` from `action` / `onRun`
+
+Neither overlay, scroll, keyboard, dialog, nor toast is required.
+
+## SSR
+
+Register commands on the client. The controller does not touch browser globals during import or construction.
+
+## Standalone usage
+
+```ts
+import { createCommandController } from "@ailuracode/alpine-command";
+
+const command = createCommandController();
+command.register({ id: "save", label: "Save", action: () => {} });
+command.open();
+```
+
+## Migration notes
+
+- `register()` now returns an unregister callback; `unregister(id)` remains available
+- `filter` is deprecated in favor of `rank` or `searchStrategy`
+- `filteredItems` now includes disabled commands; use `itemState(id)?.disabled` or `visibleItems` for runtime state
+
+## License
+
+MIT

package/dist/global.d.ts

@@ -1,30 +1,66 @@
 /// <reference types="@types/alpinejs" />
 
-import type { CommandItem } from "./types";
+import type {
+  CommandExecutionState,
+  CommandItem,
+  CommandItemState,
+  CommandPage,
+  CommandStoreConfig,
+} from "./types";
 
-export type { CommandAction, CommandItem, CommandStoreConfig } from "./types";
+export type {
+  CommandAction,
+  CommandExecutionState,
+  CommandFilterFn,
+  CommandItem,
+  CommandItemState,
+  CommandLoader,
+  CommandPage,
+  CommandPersistence,
+  CommandPredicate,
+  CommandRankFn,
+  CommandSearchStrategy,
+  CommandStoreConfig,
+} from "./types";
 
 export interface CommandStore {
   search: string;
   activeIndex: number;
   visible: boolean;
   items: Record<string, CommandItem>;
-  readonly isOpen: boolean;
+  isOpen: boolean;
+  executionState: CommandExecutionState;
+  runningId: string | null;
+  currentPageId: string;
+  pageStack: string[];
+  pages: Record<string, CommandPage>;
+  loadingIds: string[];
+  pinnedIds: string[];
+  recentIds: string[];
   open(): void;
   close(): void;
   toggle(): void;
-  register(item: CommandItem): void;
+  register(item: CommandItem): () => void;
   unregister(id: string): void;
   run(id: string): Promise<void>;
+  cancelRun(): void;
   handleKeydown(event: KeyboardEvent): void;
-  readonly filteredItems: CommandItem[];
-  readonly groupedItems: Record<string, CommandItem[]>;
+  pushPage(page: CommandPage): Promise<void>;
+  popPage(): void;
+  goBack(): void;
+  itemState(id: string): CommandItemState | null;
+  inputProps(): Record<string, string | boolean | undefined>;
+  listboxProps(): Record<string, string | boolean | undefined>;
+  optionProps(id: string): Record<string, string | number | boolean | undefined>;
+  filteredItems: CommandItem[];
+  visibleItems: CommandItemState[];
+  groupedItems: Record<string, CommandItem[]>;
   destroy(): void;
 }
 
 export function createCommandController(
-  config?: import("./types").CommandStoreConfig
-): import("./types").CommandController;
+  config?: CommandStoreConfig
+): import("./controller").CommandController;
 
 export default function commandPlugin(
   options?: import("./types").CommandPluginOptions

package/dist/index.d.ts

@@ -1,55 +1,161 @@
 import { Alpine, PluginCallback, BaseController } from '@ailuracode/alpine-core';
 export { Unsubscribe } from '@ailuracode/alpine-core';
+import { ScrollStore } from '@ailuracode/alpine-scroll';
 import { Alpine as Alpine$1 } from 'alpinejs';
 
 /**
  * Public type contracts for `@ailuracode/alpine-command`.
- *
- * Every public type lives in a `types.ts` module so consumers can import
- * them without pulling the implementation. The shape IS the contract.
  */
 
 /** Action callback invoked when a command is executed. */
 type CommandAction = () => void | Promise<void>;
+/** Static or reactive predicate for command state. */
+type CommandPredicate = boolean | (() => boolean);
+/** Async loader for lazy command registration. */
+type CommandLoader = () => void | Promise<void>;
+/** Search ranking strategy. */
+type CommandSearchStrategy = "substring" | "fuzzy";
+/** Rank function — higher scores surface earlier; `null` excludes the item. */
+type CommandRankFn = (item: CommandItem, search: string) => number | null;
+/**
+ * @deprecated Use {@link CommandRankFn} via `rank` or `searchStrategy` instead.
+ * Legacy boolean filter kept for backward compatibility.
+ */
+type CommandFilterFn = (item: CommandItem, search: string) => boolean;
+/** Optional recent/pinned persistence hooks. */
+type CommandPersistence = {
+    readonly maxRecent?: number;
+    readonly getRecent?: () => readonly string[] | Promise<readonly string[]>;
+    readonly setRecent?: (ids: readonly string[]) => void | Promise<void>;
+    readonly getPinned?: () => readonly string[] | Promise<readonly string[]>;
+    readonly setPinned?: (ids: readonly string[]) => void | Promise<void>;
+};
+/** Nested command page metadata. */
+type CommandPage = {
+    readonly id: string;
+    readonly title: string;
+    readonly parentId?: string;
+    readonly load?: CommandLoader;
+};
 /** A registered command item. */
 type CommandItem = {
-    id: string;
-    label: string;
-    group?: string;
-    shortcut?: string;
-    keywords?: string[];
-    disabled?: boolean;
-    action: CommandAction;
+    readonly id: string;
+    readonly label: string;
+    readonly group?: string;
+    readonly shortcut?: string;
+    readonly keywords?: string[];
+    readonly aliases?: string[];
+    readonly disabled?: CommandPredicate;
+    readonly hidden?: CommandPredicate;
+    readonly enabled?: CommandPredicate;
+    readonly pinned?: boolean;
+    readonly page?: string;
+    readonly load?: CommandLoader;
+    readonly action: CommandAction;
+};
+/** Resolved runtime state for a visible command row. */
+type CommandItemState = {
+    readonly id: string;
+    readonly item: CommandItem;
+    readonly disabled: boolean;
+    readonly hidden: boolean;
+    readonly loading: boolean;
+    readonly pinned: boolean;
+    readonly recent: boolean;
+    readonly rank: number;
+    readonly selectable: boolean;
 };
-/** Config callbacks for the command palette. */
+/** Explicit async lifecycle state for the palette. */
+type CommandExecutionState = "idle" | "loading" | "running";
+/** Config callbacks and behavior for the command palette. */
 type CommandStoreConfig = {
-    onOpen?: () => void;
-    onClose?: () => void;
-    onRun?: (item: CommandItem) => void;
-    filter?: (item: CommandItem, search: string) => boolean;
+    readonly onOpen?: () => void;
+    readonly onClose?: () => void;
+    readonly onRun?: (item: CommandItem) => void;
+    /** @deprecated Use `rank` or `searchStrategy` instead. */
+    readonly filter?: CommandFilterFn;
+    readonly rank?: CommandRankFn;
+    readonly searchStrategy?: CommandSearchStrategy;
+    readonly persistence?: CommandPersistence;
+    readonly overlayId?: string;
+    readonly editableSelector?: string;
+    readonly idPrefix?: string;
+    readonly closeOnRun?: boolean;
+    readonly scroll?: ScrollStore;
+    readonly scrollLock?: boolean;
+};
+/** Normalized options used internally by the controller. */
+type NormalizedCommandOptions = {
+    readonly id?: string;
+    readonly onOpen?: () => void;
+    readonly onClose?: () => void;
+    readonly onRun?: (item: CommandItem) => void;
+    readonly rank: CommandRankFn;
+    readonly searchStrategy: CommandSearchStrategy;
+    readonly persistence: Required<Pick<CommandPersistence, "maxRecent">> & Omit<CommandPersistence, "maxRecent">;
+    readonly overlayId?: string;
+    readonly editableSelector: string;
+    readonly idPrefix: string;
+    readonly closeOnRun: boolean;
+    readonly scroll?: ScrollStore;
+    readonly scrollLock: boolean;
 };
 /** Options accepted by the command plugin factory. */
 interface CommandPluginOptions extends CommandStoreConfig {
     readonly id?: string;
+    /**
+     * `$store` key the Alpine plugin registers under. Defaults to
+     * {@link DEFAULT_COMMAND_STORE_KEY}. Set when the host already owns
+     * a `command` store or another toolkit plugin would collide on that
+     * name — the rename avoids the collision without touching the
+     * controller. Ignored by the standalone `createCommandStore` factory.
+     */
+    readonly storeKey?: string;
+    /**
+     * `$command` magic key the Alpine plugin registers under. Defaults
+     * to {@link DEFAULT_COMMAND_MAGIC_KEY}, or to `storeKey` when that
+     * is renamed (the magic follows the store so consumers only rename
+     * one). Ignored by the standalone factory.
+     */
+    readonly magicKey?: string;
 }
+/** Default `$store` key registered by {@link commandPlugin}. */
+declare const DEFAULT_COMMAND_STORE_KEY = "command";
+/** Default `$command` magic key registered by {@link commandPlugin}. */
+declare const DEFAULT_COMMAND_MAGIC_KEY = "command";
 /** Alpine-facing store surface. */
 interface CommandStore {
     search: string;
     activeIndex: number;
-    /** Whether the palette is visible. */
     visible: boolean;
-    /** Registered command items. */
     items: Record<string, CommandItem>;
-    readonly isOpen: boolean;
+    isOpen: boolean;
+    executionState: CommandExecutionState;
+    runningId: string | null;
+    currentPageId: string;
+    pageStack: string[];
+    pages: Record<string, CommandPage>;
+    loadingIds: string[];
+    pinnedIds: string[];
+    recentIds: string[];
     open(): void;
     close(): void;
     toggle(): void;
-    register(item: CommandItem): void;
+    register(item: CommandItem): () => void;
     unregister(id: string): void;
     run(id: string): Promise<void>;
+    cancelRun(): void;
     handleKeydown(event: KeyboardEvent): void;
-    readonly filteredItems: CommandItem[];
-    readonly groupedItems: Record<string, CommandItem[]>;
+    pushPage(page: CommandPage): Promise<void>;
+    popPage(): void;
+    goBack(): void;
+    itemState(id: string): CommandItemState | null;
+    inputProps(): Record<string, string | boolean | undefined>;
+    listboxProps(): Record<string, string | boolean | undefined>;
+    optionProps(id: string): Record<string, string | number | boolean | undefined>;
+    filteredItems: CommandItem[];
+    visibleItems: CommandItemState[];
+    groupedItems: Record<string, CommandItem[]>;
     destroy(): void;
 }
 /** Typed view of `Alpine` the command plugin uses internally. */
@@ -70,27 +176,23 @@ type CommandPluginCallback = PluginCallback<Alpine$1>;
  * `open` — palette opened.
  * `close` — palette closed.
  * `run` — a command was executed.
+ * `change` — reactive state changed (search, selection, pages, loading).
  */
 interface CommandEvents extends Record<string, unknown> {
     open: undefined;
     close: undefined;
     run: CommandItem;
+    change: undefined;
 }
 
 /**
  * Command palette controller — the framework-agnostic core of
- * `@ailuracode/alpine-command`. Manages a singleton command palette
- * with search, item registry, open/close/toggle, keyboard navigation,
- * and filtered/grouped item views.
- *
- * Emits typed `open`, `close`, and `run` events so consumers can
- * react programmatically.
+ * `@ailuracode/alpine-command`.
  */
 
 /**
- * Headless command palette controller. Manages a singleton command palette
- * with search, item registry, open/close/toggle, keyboard navigation,
- * and filtered/grouped item views.
+ * Headless command palette controller with search ranking, nested pages,
+ * async loading/execution, and ARIA helpers.
  */
 declare class CommandController extends BaseController<CommandEvents> {
     #private;
@@ -102,37 +204,67 @@ declare class CommandController extends BaseController<CommandEvents> {
     set activeIndex(value: number);
     get visible(): boolean;
     get isOpen(): boolean;
+    get executionState(): CommandExecutionState;
+    get runningId(): string | null;
+    get currentPageId(): string;
+    get pageStack(): readonly string[];
+    get pages(): Readonly<Record<string, CommandPage>>;
+    get loadingIds(): readonly string[];
+    get pinnedIds(): readonly string[];
+    get recentIds(): readonly string[];
+    get visibleItems(): readonly CommandItemState[];
     get filteredItems(): CommandItem[];
     get groupedItems(): Record<string, CommandItem[]>;
     open(): void;
     close(): void;
     toggle(): void;
-    register(item: CommandItem): void;
+    register(item: CommandItem): () => void;
     unregister(id: string): void;
+    pushPage(page: CommandPage): Promise<void>;
+    popPage(): void;
+    goBack(): void;
+    itemState(id: string): CommandItemState | null;
+    inputProps(): Record<string, string | boolean | undefined>;
+    listboxProps(): Record<string, string | boolean | undefined>;
+    optionProps(id: string): Record<string, string | number | boolean | undefined>;
+    cancelRun(): void;
     run(id: string): Promise<void>;
     handleKeydown(event: KeyboardEvent): void;
-    /**
-     * Returns a store-shaped object for Alpine's `$store.command`.
-     * The store delegates to this controller.
-     */
     toStore(): CommandStore;
+    destroy(): void;
 }
-/**
- * Creates a CommandController instance.
- * Convenience for non-Alpine consumers.
- */
+/** Creates a CommandController instance. */
 declare function createCommandController(config?: CommandStoreConfig): CommandController;
+/** Creates a CommandStore (store-shaped object) directly. */
+declare function createCommandStore(config?: CommandStoreConfig): CommandStore;
+
 /**
- * Creates a CommandStore (store-shaped object) directly.
- * Backward-compatible alias.
+ * Alpine adapter for the command controller.
+ *
+ * Fields are direct properties (not getters) so the plugin can mirror
+ * controller state onto Alpine's reactive store proxy.
  */
-declare function createCommandStore(config?: CommandStoreConfig): CommandStore;
+
+/** Mirrors controller state into a plain store object for Alpine. */
+declare function syncCommandStore(store: CommandStore, controller: CommandController): void;
+/** Builds the {@link CommandStore} installed at `$store.command`. */
+declare function createCommandAlpineStore(controller: CommandController): CommandStore;
+
+type CommandErrorCode = "COMMAND_DESTROYED" | "COMMAND_DUPLICATE_ID" | "COMMAND_UNKNOWN_ITEM" | "COMMAND_UNKNOWN_PAGE" | "COMMAND_ALREADY_RUNNING";
+declare class CommandError extends Error {
+    readonly code: CommandErrorCode;
+    readonly cause?: unknown;
+    constructor(message: string, code: CommandErrorCode, options?: {
+        cause?: unknown;
+    });
+}
+
+declare const ROOT_PAGE_ID = "root";
+/** Normalizes command controller and plugin options once at construction. */
+declare function normalizeCommandOptions(options?: CommandPluginOptions): NormalizedCommandOptions;
 
 /**
  * Alpine.js integration for `@ailuracode/alpine-command`.
- *
- * Thin adapter that wires {@link CommandController} into
- * `$store.command` and the `$command` magic.
  */
 
 /**
@@ -143,5 +275,7 @@ declare function createCommandStore(config?: CommandStoreConfig): CommandStore;
 declare function commandPlugin(options?: CommandPluginOptions): CommandPluginCallback;
 /** Builds typed command plugin options. */
 declare function commandOptions<const T extends CommandPluginOptions>(options: T): T;
+/** @deprecated Use {@link createCommandAlpineStore} via the plugin adapter. */
+declare function createCommandStoreFromController(controller: CommandController): CommandStore;
 
-export { type CommandAction, type CommandAlpine, CommandController, type CommandEvents, type CommandItem, type CommandPluginCallback, type CommandPluginOptions, type CommandStore, type CommandStoreConfig, commandOptions, commandPlugin, createCommandController, createCommandStore, commandPlugin as default };
+export { type CommandAction, type CommandAlpine, CommandController, CommandError, type CommandErrorCode, type CommandEvents, type CommandExecutionState, type CommandFilterFn, type CommandItem, type CommandItemState, type CommandLoader, type CommandPage, type CommandPersistence, type CommandPluginCallback, type CommandPluginOptions, type CommandPredicate, type CommandRankFn, type CommandSearchStrategy, type CommandStore, type CommandStoreConfig, DEFAULT_COMMAND_MAGIC_KEY, DEFAULT_COMMAND_STORE_KEY, type NormalizedCommandOptions, ROOT_PAGE_ID, commandOptions, commandPlugin, createCommandAlpineStore, createCommandController, createCommandStore, createCommandStoreFromController, commandPlugin as default, normalizeCommandOptions, syncCommandStore };

package/dist/index.js

@@ -1,304 +1 @@
-// src/controller.ts
-import { BaseController, generateId } from "@ailuracode/alpine-core";
-function defaultFilter(item, search) {
-  if (!search.trim()) {
-    return true;
-  }
-  const query = search.trim().toLowerCase();
-  const haystack = [item.label, item.group ?? "", item.shortcut ?? "", ...item.keywords ?? []].join(" ").toLowerCase();
-  return haystack.includes(query);
-}
-function isEditableTarget(target) {
-  if (!(target instanceof HTMLElement)) {
-    return false;
-  }
-  const tag = target.tagName;
-  return tag === "INPUT" || tag === "TEXTAREA" || target.isContentEditable;
-}
-function isTypingKey(event) {
-  return event.key.length === 1 && !event.metaKey && !event.ctrlKey && !event.altKey && !event.isComposing;
-}
-var CommandController = class extends BaseController {
-  #items = {};
-  #search = "";
-  #activeIndex = 0;
-  #visible = false;
-  #filter;
-  #config;
-  constructor(id, config = {}) {
-    super(id ?? generateId("command"));
-    this.#filter = config.filter ?? defaultFilter;
-    this.#config = config;
-  }
-  get items() {
-    return this.#items;
-  }
-  get search() {
-    return this.#search;
-  }
-  set search(value) {
-    this.#search = value;
-  }
-  get activeIndex() {
-    return this.#activeIndex;
-  }
-  set activeIndex(value) {
-    this.#activeIndex = value;
-  }
-  get visible() {
-    return this.#visible;
-  }
-  get isOpen() {
-    return this.#visible;
-  }
-  get filteredItems() {
-    const list = Object.values(this.#items).filter(
-      (item) => !item.disabled && this.#filter(item, this.#search)
-    );
-    if (this.#activeIndex >= list.length) {
-      this.#activeIndex = Math.max(list.length - 1, 0);
-    }
-    return list;
-  }
-  get groupedItems() {
-    const groups = {};
-    for (const item of this.filteredItems) {
-      const group = item.group ?? "General";
-      groups[group] ??= [];
-      groups[group].push(item);
-    }
-    return groups;
-  }
-  open() {
-    if (this.isDestroyed || this.#visible) {
-      return;
-    }
-    this.#visible = true;
-    this.#search = "";
-    this.#activeIndex = 0;
-    this.#config.onOpen?.();
-    this.emit("open", void 0);
-  }
-  close() {
-    if (this.isDestroyed || !this.#visible) {
-      return;
-    }
-    this.#visible = false;
-    this.#search = "";
-    this.#activeIndex = 0;
-    this.#config.onClose?.();
-    this.emit("close", void 0);
-  }
-  toggle() {
-    if (this.#visible) {
-      this.close();
-    } else {
-      this.open();
-    }
-  }
-  register(item) {
-    if (this.isDestroyed) {
-      return;
-    }
-    this.#items[item.id] = item;
-  }
-  unregister(id) {
-    if (this.isDestroyed) {
-      return;
-    }
-    delete this.#items[id];
-  }
-  async run(id) {
-    if (this.isDestroyed) {
-      return;
-    }
-    const item = this.#items[id];
-    if (!item || item.disabled) {
-      return;
-    }
-    await item.action();
-    this.#config.onRun?.(item);
-    this.emit("run", item);
-    this.close();
-  }
-  handleKeydown(event) {
-    if (this.isDestroyed || !this.#visible) {
-      return;
-    }
-    const list = this.filteredItems;
-    if (isEditableTarget(event.target)) {
-    } else if (event.key === "Backspace") {
-      event.preventDefault();
-      this.#search = this.#search.slice(0, -1);
-      this.#activeIndex = 0;
-      return;
-    } else if (isTypingKey(event)) {
-      event.preventDefault();
-      this.#search += event.key;
-      this.#activeIndex = 0;
-      return;
-    }
-    switch (event.key) {
-      case "ArrowDown":
-        event.preventDefault();
-        this.#activeIndex = list.length === 0 ? 0 : (this.#activeIndex + 1) % list.length;
-        break;
-      case "ArrowUp":
-        event.preventDefault();
-        this.#activeIndex = list.length === 0 ? 0 : (this.#activeIndex - 1 + list.length) % list.length;
-        break;
-      case "Home":
-        event.preventDefault();
-        this.#activeIndex = 0;
-        break;
-      case "End":
-        event.preventDefault();
-        this.#activeIndex = Math.max(list.length - 1, 0);
-        break;
-      case "Enter": {
-        event.preventDefault();
-        const active = list[this.#activeIndex];
-        if (active) {
-          void this.run(active.id);
-        }
-        break;
-      }
-      case "Escape":
-        event.preventDefault();
-        this.close();
-        break;
-      default:
-        break;
-    }
-  }
-  /**
-   * Returns a store-shaped object for Alpine's `$store.command`.
-   * The store delegates to this controller.
-   */
-  toStore() {
-    const controller = this;
-    return {
-      get search() {
-        return controller.search;
-      },
-      set search(value) {
-        controller.search = value;
-      },
-      get activeIndex() {
-        return controller.activeIndex;
-      },
-      set activeIndex(value) {
-        controller.activeIndex = value;
-      },
-      get visible() {
-        return controller.visible;
-      },
-      get items() {
-        return controller.items;
-      },
-      get isOpen() {
-        return controller.isOpen;
-      },
-      open: () => controller.open(),
-      close: () => controller.close(),
-      toggle: () => controller.toggle(),
-      register: (item) => controller.register(item),
-      unregister: (id) => controller.unregister(id),
-      run: (id) => controller.run(id),
-      handleKeydown: (event) => controller.handleKeydown(event),
-      get filteredItems() {
-        return controller.filteredItems;
-      },
-      get groupedItems() {
-        return controller.groupedItems;
-      },
-      destroy: () => controller.destroy()
-    };
-  }
-};
-function createCommandController(config = {}) {
-  return new CommandController(void 0, config);
-}
-function createCommandStore(config = {}) {
-  return new CommandController(void 0, config).toStore();
-}
-
-// src/plugin.ts
-var COMMAND_STORE_KEY = "command";
-function commandPlugin(options = {}) {
-  return function registerCommand(alpine) {
-    const Alpine = alpine;
-    const controller = new CommandController(options.id, options);
-    const store = {
-      search: "",
-      activeIndex: 0,
-      visible: false,
-      items: {},
-      get isOpen() {
-        return this.visible;
-      },
-      get filteredItems() {
-        const defaultFilter2 = (i, s) => {
-          if (!s.trim()) {
-            return true;
-          }
-          const query = s.trim().toLowerCase();
-          const haystack = [i.label, i.group ?? "", i.shortcut ?? "", ...i.keywords ?? []].join(" ").toLowerCase();
-          return haystack.includes(query);
-        };
-        const filter = options.filter ?? defaultFilter2;
-        const list = Object.values(this.items).filter(
-          (item) => !item.disabled && filter(item, this.search)
-        );
-        if (this.activeIndex >= list.length) {
-          this.activeIndex = Math.max(list.length - 1, 0);
-        }
-        return list;
-      },
-      get groupedItems() {
-        const groups = {};
-        for (const item of this.filteredItems) {
-          const group = item.group ?? "General";
-          groups[group] ??= [];
-          groups[group].push(item);
-        }
-        return groups;
-      },
-      open: () => controller.open(),
-      close: () => controller.close(),
-      toggle: () => controller.toggle(),
-      register: (item) => controller.register(item),
-      unregister: (id) => controller.unregister(id),
-      run: (id) => controller.run(id),
-      handleKeydown: (event) => controller.handleKeydown(event),
-      destroy: () => controller.destroy()
-    };
-    Alpine.store(COMMAND_STORE_KEY, store);
-    const reactiveStore = Alpine.store(COMMAND_STORE_KEY);
-    controller.on("open", () => {
-      reactiveStore.visible = true;
-      reactiveStore.search = "";
-      reactiveStore.activeIndex = 0;
-    });
-    controller.on("close", () => {
-      reactiveStore.visible = false;
-      reactiveStore.search = "";
-      reactiveStore.activeIndex = 0;
-    });
-    Alpine.magic(COMMAND_STORE_KEY, () => reactiveStore);
-    if (typeof Alpine.cleanup === "function") {
-      Alpine.cleanup(() => controller.destroy());
-    }
-  };
-}
-function commandOptions(options) {
-  return options;
-}
-export {
-  CommandController,
-  commandOptions,
-  commandPlugin,
-  createCommandController,
-  createCommandStore,
-  commandPlugin as default
-};
+function c(t,e){t.search=e.search,t.activeIndex=e.activeIndex,t.visible=e.visible,t.isOpen=e.isOpen,t.items={...e.items},t.executionState=e.executionState,t.runningId=e.runningId,t.currentPageId=e.currentPageId,Object.assign(t,{pageStack:[...e.pageStack],pages:{...e.pages},loadingIds:[...e.loadingIds],pinnedIds:[...e.pinnedIds],recentIds:[...e.recentIds],visibleItems:[...e.visibleItems],filteredItems:[...e.filteredItems],groupedItems:{...e.groupedItems}})}function m(t){return{search:t.search,activeIndex:t.activeIndex,visible:t.visible,isOpen:t.isOpen,items:{...t.items},executionState:t.executionState,runningId:t.runningId,currentPageId:t.currentPageId,pageStack:[...t.pageStack],pages:{...t.pages},loadingIds:[...t.loadingIds],pinnedIds:[...t.pinnedIds],recentIds:[...t.recentIds],visibleItems:[...t.visibleItems],filteredItems:[...t.filteredItems],groupedItems:{...t.groupedItems},open:()=>t.open(),close:()=>t.close(),toggle:()=>t.toggle(),register:n=>t.register(n),unregister:n=>t.unregister(n),run:n=>t.run(n),cancelRun:()=>t.cancelRun(),handleKeydown:n=>t.handleKeydown(n),pushPage:n=>t.pushPage(n),popPage:()=>t.popPage(),goBack:()=>t.goBack(),itemState:n=>t.itemState(n),inputProps:()=>t.inputProps(),listboxProps:()=>t.listboxProps(),optionProps:n=>t.optionProps(n),destroy:()=>t.destroy()}}import{BaseController as F,generateId as j}from"@ailuracode/alpine-core";function S(t,e){let n=t.target;return n instanceof Element?n.closest(e)?!0:n instanceof HTMLElement&&n.isContentEditable:!1}function v(t){return t.key.length===1&&!t.metaKey&&!t.ctrlKey&&!t.altKey&&!t.isComposing}var l=class extends Error{code;cause;constructor(e,n,i={}){super(e,{cause:i.cause}),this.name="CommandError",this.code=n,this.cause=i.cause}};function T(t){return[t.label,t.group??"",t.shortcut??"",...t.keywords??[],...t.aliases??[]]}function k(t,e){let n=e.trim().toLowerCase();if(!n)return 0;let i=t.label.toLowerCase();if(i.startsWith(n))return 100;if(i.includes(n))return 80;for(let s of t.aliases??[]){let r=s.toLowerCase();if(r.startsWith(n))return 70;if(r.includes(n))return 60}return T(t).join(" ").toLowerCase().includes(n)?50:null}function N(t,e){let n=e.trim().toLowerCase();if(!n)return 0;let i=t.label.toLowerCase(),o=0,s=0;for(let r=0;r<i.length&&s<n.length;r++)i[r]===n[s]&&(o+=10,s++);return s===n.length?o+(i.startsWith(n)?20:0):k(t,e)}function R(t,e){return e||(t==="fuzzy"?N:k)}function O(t){return(e,n)=>t(e,n)?1:null}var K='input, textarea, select, [contenteditable=""], [contenteditable="true"], [contenteditable="plaintext-only"]',C=10,a="root";function f(t={}){let e=t.searchStrategy??"substring",n=t.rank??(t.filter?O(t.filter):R(e));return{id:t.id,onOpen:t.onOpen,onClose:t.onClose,onRun:t.onRun,rank:n,searchStrategy:e,persistence:{maxRecent:t.persistence?.maxRecent??C,getRecent:t.persistence?.getRecent,setRecent:t.persistence?.setRecent,getPinned:t.persistence?.getPinned,setPinned:t.persistence?.setPinned},overlayId:t.overlayId,editableSelector:t.editableSelector??K,idPrefix:t.idPrefix??"command",closeOnRun:t.closeOnRun!==!1,scroll:t.scroll,scrollLock:t.scrollLock!==!1}}function g(t,e){return t===void 0?e:typeof t=="function"?t():t}function E(t,e,n){let i=n.length;if(i===0)return 0;let o=t;for(let s=0;s<i;s++)if(o=(o+e+i)%i,n[o])return o;return t}function z(t){let e=t.findIndex(Boolean);return e===-1?0:e}function U(t){for(let e=t.length-1;e>=0;e--)if(t[e])return e;return 0}function A(t,e){return(t.page??a)===e}function y(t){return g(t.hidden,!1)}function D(t){return y(t)?!0:t.enabled!==void 0?!g(t.enabled,!0):g(t.disabled,!1)}var d=class extends F{#n;#d={};#h={[a]:{id:a,title:"Commands"}};#i=new Set;#l=new Set;#c=new Set;#r=[];#o="";#t=0;#s=!1;#a=[a];#u="idle";#f=null;#y=0;#p=0;#x=!1;#g=0;#m=null;#C;#I;constructor(e,n={}){super(e??j("command")),this.#n=f(n),this.#C=this.#n.scroll,this.#I=this.#n.scrollLock}get items(){return this.#d}get search(){return this.#o}set search(e){this.#o!==e&&(this.#o=e,this.#t=0,this.#e())}get activeIndex(){return this.#t}set activeIndex(e){let n=Math.max(0,e);this.#t!==n&&(this.#t=n,this.#e())}get visible(){return this.#s}get isOpen(){return this.#s}get executionState(){return this.#u}get runningId(){return this.#f}get currentPageId(){return this.#a[this.#a.length-1]??a}get pageStack(){return this.#a}get pages(){return this.#h}get loadingIds(){return[...this.#i]}get pinnedIds(){return[...this.#c]}get recentIds(){return[...this.#r]}get visibleItems(){return this.#v()}get filteredItems(){return this.visibleItems.map(e=>e.item)}get groupedItems(){let e={};for(let n of this.visibleItems){let i=n.item.group??"General";e[i]??=[],e[i].push(n.item)}return e}open(){this.isDestroyed||this.#s||(this.#s=!0,this.#o="",this.#t=0,this.#I&&this.#S(!0),this.#R(),this.#O(),this.#n.onOpen?.(),this.emit("open",void 0),this.#e())}close(){this.isDestroyed||!this.#s||(this.#s=!1,this.#o="",this.#t=0,this.#a=[a],this.#I&&this.#S(!1),this.cancelRun(),this.#n.onClose?.(),this.emit("close",void 0),this.#e())}toggle(){this.#s?this.close():this.open()}register(e){if(this.isDestroyed)throw new l("Cannot register command after destroy()","COMMAND_DESTROYED");if(this.#d[e.id])throw new l(`Command id "${e.id}" is already registered`,"COMMAND_DUPLICATE_ID");return this.#d[e.id]=e,e.pinned&&this.#c.add(e.id),this.#b(),this.#e(),()=>{this.unregister(e.id)}}unregister(e){if(this.isDestroyed)return;delete this.#d[e],this.#i.delete(e),this.#l.delete(e),this.#c.delete(e);let n=this.#r.indexOf(e);n!==-1&&this.#r.splice(n,1),this.#b(),this.#e()}async pushPage(e){this.isDestroyed||(this.#h[e.id]=e,this.#a.push(e.id),this.#o="",this.#t=0,await this.#P(e),this.#e())}popPage(){this.isDestroyed||this.#a.length<=1||(this.#a.pop(),this.#o="",this.#t=0,this.#b(),this.#e())}goBack(){this.popPage()}itemState(e){return this.visibleItems.find(n=>n.id===e)??null}inputProps(){let e=`${this.#n.idPrefix}-listbox`,n=this.visibleItems[this.#t];return{role:"combobox","aria-expanded":this.#s,"aria-controls":e,"aria-activedescendant":n?`${this.#n.idPrefix}-option-${n.id}`:void 0,"aria-autocomplete":"list"}}listboxProps(){return{role:"listbox",id:`${this.#n.idPrefix}-listbox`,"aria-label":this.#h[this.currentPageId]?.title??"Commands"}}optionProps(e){let n=this.itemState(e),i=this.visibleItems.findIndex(o=>o.id===e);return{role:"option",id:`${this.#n.idPrefix}-option-${e}`,"aria-selected":i===this.#t,"aria-disabled":n?.disabled??!1,"data-disabled":n?.disabled??!1,"data-loading":n?.loading??!1}}cancelRun(){this.#y++,this.#f=null,this.#u="idle",this.#e()}async run(e){if(this.isDestroyed)return;let n=this.itemState(e)??this.#k(e);if(!n||n.disabled||n.loading)return;let i=++this.#y;this.#f=e,this.#u="running",this.#e();try{if(await n.item.action(),i!==this.#y||this.isDestroyed)return;if(this.#n.onRun?.(n.item),this.emit("run",n.item),await this.#A(e),this.#n.closeOnRun){this.close();return}}finally{i===this.#y&&(this.#f=null,this.#u="idle",this.#e())}}handleKeydown(e){if(this.isDestroyed||!this.#s)return;if(e.key==="Backspace"&&this.#a.length>1&&this.#o.length===0){e.preventDefault(),this.popPage();return}if(!S(e,this.#n.editableSelector)){if(e.key==="Backspace"){e.preventDefault(),this.#o=this.#o.slice(0,-1),this.#t=0,this.#e();return}if(v(e)){e.preventDefault(),this.#o+=e.key,this.#t=0,this.#e();return}}let n=this.visibleItems,i=n.map(o=>o.selectable);switch(e.key){case"ArrowDown":e.preventDefault(),this.#t=E(this.#t,1,i),this.#e();break;case"ArrowUp":e.preventDefault(),this.#t=E(this.#t,-1,i),this.#e();break;case"Home":e.preventDefault(),this.#t=z(i),this.#e();break;case"End":e.preventDefault(),this.#t=U(i),this.#e();break;case"Enter":{e.preventDefault();let o=n[this.#t];o?.selectable&&this.run(o.id);break}case"Escape":e.preventDefault(),this.#a.length>1?this.popPage():this.close();break;default:break}}toStore(){let e=this,n=m(e),i=()=>{c(n,e)};return e.on("open",i),e.on("close",i),e.on("change",i),Object.defineProperty(n,"search",{get(){return e.search},set(o){e.search=o},enumerable:!0,configurable:!0}),Object.defineProperty(n,"activeIndex",{get(){return e.activeIndex},set(o){e.activeIndex=o},enumerable:!0,configurable:!0}),i(),n}destroy(){if(!this.isDestroyed){this.cancelRun(),this.#p++,this.#m!==null&&(this.#C?.unlock(this.#m),this.#m=null),this.#g=0;for(let e of Object.keys(this.#d))delete this.#d[e];for(let e of Object.keys(this.#h))e!==a&&delete this.#h[e];this.#a=[a],this.#i.clear(),this.#l.clear(),this.#c.clear(),this.#r.length=0,this.#s=!1,this.#o="",this.#t=0,super.destroy()}}#v(){let e=this.currentPageId,n=[];for(let i of Object.values(this.#d)){if(!A(i,e)||y(i))continue;let o=this.#n.rank(i,this.#o);if(o===null)continue;let s=D(i),r=i.pinned===!0||this.#c.has(i.id),u=this.#r.includes(i.id);n.push({id:i.id,item:i,disabled:s,hidden:!1,loading:this.#i.has(i.id),pinned:r,recent:u,rank:o+(r?1e3:0)+(u?100:0),selectable:!(s||this.#i.has(i.id))}),i.load&&!this.#l.has(i.id)&&!this.#i.has(i.id)&&this.#E(i)}return n.sort((i,o)=>o.rank!==i.rank?o.rank-i.rank:i.item.label.localeCompare(o.item.label)),n}#k(e){let n=this.#d[e];if(!(n&&A(n,this.currentPageId))||y(n))return null;let i=D(n);return{id:e,item:n,disabled:i,hidden:!1,loading:this.#i.has(e),pinned:n.pinned===!0||this.#c.has(e),recent:this.#r.includes(e),rank:0,selectable:!(i||this.#i.has(e))}}async#R(){if(this.#x)return;this.#x=!0;let e=await this.#n.persistence.getPinned?.();if(e)for(let i of e)this.#c.add(i);let n=await this.#n.persistence.getRecent?.();n&&this.#r.splice(0,this.#r.length,...n),this.#e()}async#O(){let e=this.#h[this.currentPageId];e&&await this.#P(e)}async#P(e){if(!e.load||this.#l.has(e.id))return;let n=++this.#p;this.#i.add(e.id),this.#u="loading",this.#e();try{if(await e.load(),n!==this.#p||this.isDestroyed)return;this.#l.add(e.id)}finally{this.#i.delete(e.id),this.#i.size===0&&this.#u==="loading"&&(this.#u="idle"),this.#e()}}async#E(e){if(!e.load||this.#l.has(e.id))return;let n=++this.#p;this.#i.add(e.id),this.#e();try{if(await e.load(),n!==this.#p||this.isDestroyed)return;this.#l.add(e.id)}finally{this.#i.delete(e.id),this.#e()}}async#A(e){let n=this.#n.persistence.maxRecent??C,i=[e,...this.#r.filter(o=>o!==e)].slice(0,n);this.#r.splice(0,this.#r.length,...i),await this.#n.persistence.setRecent?.(i),this.#e()}#b(){let e=this.visibleItems.length;this.#t>=e&&(this.#t=Math.max(e-1,0))}#e(){this.isDestroyed||(this.#b(),this.emit("change",void 0))}#S(e){if(e){this.#g===0&&this.#C&&this.#m===null&&(this.#m=this.#C.lock("command")),this.#g++;return}this.#g!==0&&(this.#g--,this.#g===0&&this.#m!==null&&(this.#C?.unlock(this.#m),this.#m=null))}};function B(t={}){return new d(void 0,t)}function G(t={}){return new d(void 0,t).toStore()}import{bridgeControllerStore as Y}from"@ailuracode/alpine-core";var b="command",I="command";function _(t={}){let e=t.storeKey??b,n=t.magicKey??t.storeKey??I;return function(o){let s=o,r=new d(t.id,t),u=m(r);Y({alpine:s,storeKey:e,magicKey:n,store:u,controller:r,packageName:"command",subscribe:x=>{let p=!1,h=()=>{p=!0,c(x,r),p=!1},w=r.on("open",h),L=r.on("close",h),M=r.on("change",h);return o.effect(()=>{if(p)return;let P=x.search;r.search!==P&&(r.search=P)}),h(),()=>{w(),L(),M()}}})}}function $(t){return t}function H(t){return m(t)}export{d as CommandController,l as CommandError,I as DEFAULT_COMMAND_MAGIC_KEY,b as DEFAULT_COMMAND_STORE_KEY,a as ROOT_PAGE_ID,$ as commandOptions,_ as commandPlugin,m as createCommandAlpineStore,B as createCommandController,G as createCommandStore,H as createCommandStoreFromController,_ as default,f as normalizeCommandOptions,c as syncCommandStore};

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@ailuracode/alpine-command",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Alpine.js headless command palette store",
   "type": "module",
   "license": "MIT",
   "author": "ailuracode",
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
@@ -32,14 +33,21 @@
   },
   "types": "./dist/global.d.ts",
   "devDependencies": {
-    "@ailuracode/alpine-core": "0.2.0"
+    "@types/alpinejs": "^3.13.11",
+    "alpinejs": "^3.15.12",
+    "@ailuracode/alpine-scroll": "3.0.0",
+    "@ailuracode/alpine-core": "0.3.0"
   },
   "peerDependencies": {
-    "@ailuracode/alpine-core": "^0.2.0",
+    "@ailuracode/alpine-core": "^0.3.0",
+    "@ailuracode/alpine-scroll": "^3.0.0",
     "alpinejs": "^3.0.0",
     "@types/alpinejs": "^3.13.11"
   },
   "peerDependenciesMeta": {
+    "@ailuracode/alpine-scroll": {
+      "optional": true
+    },
     "@types/alpinejs": {
       "optional": true
     }
@@ -53,8 +61,30 @@
     "spotlight",
     "headless"
   ],
+  "toolkit": {
+    "bundleBudget": {
+      "category": "complex-feature"
+    }
+  },
+  "size-limit": [
+    {
+      "name": "full surface",
+      "path": "dist/index.js",
+      "import": "*",
+      "ignore": [
+        "alpinejs",
+        "@ailuracode/alpine-core",
+        "@types/alpinejs"
+      ],
+      "gzip": true,
+      "brotli": true,
+      "limit": "4 kB"
+    }
+  ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --out-dir dist && cp src/global.d.ts dist/global.d.ts",
-    "test": "vitest run --config ../../vitest.config.ts test"
+    "build": "tsup src/index.ts --format esm --dts --clean --out-dir dist --minify && cp src/global.d.ts dist/global.d.ts",
+    "size": "size-limit",
+    "test": "vitest run --config ../../vitest.config.ts packages/command",
+    "test:e2e": "playwright test --config playwright.config.ts"
   }
 }