vue-command-kit 0.1.0 → 0.1.2

package/README.md

@@ -11,89 +11,23 @@
   Press <kbd>⌘K</kbd> and take control.
 </p>
 
----
-
-## 🧠 Inspiration
-
-This project is heavily inspired by two great projects:
-
-| Project | Author | Description |
-| --- | --- | --- |
-| [`vue-command-palette`](https://github.com/xiaoluoboding/vue-command-palette) | [@xiaoluoboding](https://github.com/xiaoluoboding) | The first composable command palette for Vue, with 590 ★ |
-| [`cmdk`](https://github.com/pacocoursey/cmdk) | [@pacocoursey](https://github.com/pacocoursey) | Fast, unstyled command menu React component (10k+ ★) |
-
-### Why another one?
-
-[`vue-command-palette`](https://github.com/xiaoluoboding/vue-command-palette) pioneered the ⌘K experience for Vue. Big thanks to [@xiaoluoboding](https://github.com/xiaoluoboding) for the original idea and work 🙌
-
-However, the project has been **inactive since September 2023** — 9 issues remain unanswered, no dependencies have been updated in years, and the bundle size is 28 kB. The Vue ecosystem deserves a **well-maintained, lightweight alternative** that keeps up with modern standards.
-
-**vue-cmdk** is built to fill that gap: same compound component API, zero dependencies, half the size, with full TypeScript support and a commitment to ongoing maintenance.
-
-### vs vue-command-palette (legacy reference)
-
-| Feature          |  `vue-command-palette`   |  `vue-cmdk`   |
-| ---------------- | :----------------------: | :-----------: |
-| 📦 Bundle (min)  |         28.2 kB          |  **11.8 kB**  |
-| 📦 Bundle (gzip) |          9.6 kB          |  **3.4 kB**   |
-| 🔍 Search        |   fuse.js (extra dep)    | **Built-in**  |
-| 📋 TypeScript    |         Partial          |   **Full**    |
-| 🔄 Async items   |            ❌            |      ✅       |
-| 🧩 Custom filter |            ❌            |      ✅       |
-| 🔒 Focus trap    |            ❌            |      ✅       |
-| 🧹 Dependencies  | 3 (fuse.js, nanoid, ...) |     **0**     |
-| 🔧 Maintenance   |  ❌ Inactive since 2023  | ✅ **Active** |
-
----
+<p align="center">
+  <img src="./demo.gif" alt="vue-cmdk demo" width="720">
+</p>
 
 ## ✨ Features
 
-- **🧩 Compound component API** — `<Command.Dialog>`, `<Command.List>`, `<Command.Item>`, etc.
+- **🧩 Compound component API** — `<Command.Dialog>`, `<Command.Input>`, `<Command.Item>`, etc.
 - **💄 Unstyled** — Bring your own CSS, zero opinions, full design control
 - **🔍 Built-in search** — Fast case-insensitive filtering with keyword matching
 - **⌨️ Keyboard-first** — Arrow keys, Enter, Escape — all built-in, no config needed
+- **🔊 Global shortcut** — Register shortcuts on items (e.g. `⌘S`) and they work globally
 - **📦 Tiny** — 3.4 kB gzipped, **zero runtime dependencies** (peer: `vue` only)
 - **🎯 TypeScript** — Full type inference and declaration files
 - **🔄 Dynamic items** — Pass items as a reactive array, swap anytime
 - **🛠 Custom filter** — Provide your own filter function
 - **♿ Accessible** — ARIA attributes, focus trap, `aria-live` region
 
-## 📊 Comparison with React cmdk
-
-`vue-cmdk` is a Vue 3 port inspired by the excellent [`cmdk`](https://github.com/pacocoursey/cmdk) (React). Below is the current feature parity status:
-
-| #   | Feature                                      |  React `cmdk`   |    `vue-cmdk`    |   Status   |
-| --- | -------------------------------------------- | :-------------: | :--------------: | :--------: |
-| 1   | `Command` root `value` / `onValueChange`     |       ✅        |        ❌        | 📋 Planned |
-| 2   | `Command` root `shouldFilter`                |       ✅        |        ❌        | 📋 Planned |
-| 3   | `Command` root `loop`                        |       ✅        |        ❌        | 📋 Planned |
-| 4   | `Command` root `label` (aria-label)          |       ✅        |        ❌        | 📋 Planned |
-| 5   | `Command.Dialog` `open` / `onOpenChange`     |    ✅ `open`    |   ✅ `visible`   |     ✅     |
-| 6   | `Command.Dialog` `container` (portal target) |       ✅        |        ❌        | 💡 Future  |
-| 7   | `Command.Input` `value` / `onValueChange`    |       ✅        | ✅ `searchQuery` |     ✅     |
-| 8   | `Command.Item` `forceMount`                  |       ✅        |        ❌        | 📋 Planned |
-| 9   | `Command.Item` `keywords`                    |       ✅        |        ✅        |     ✅     |
-| 10  | `Command.Item` `onSelect`                    |       ✅        |        ✅        |     ✅     |
-| 11  | `Command.Item` auto value from textContent   |       ✅        |        ❌        | 📋 Planned |
-| 12  | `Command.Group` `forceMount`                 |       ✅        |        ❌        | 📋 Planned |
-| 13  | `Command.Group` `heading`                    |       ✅        |        ✅        |     ✅     |
-| 14  | `Command.Separator` `alwaysRender`           |       ✅        |        ❌        | 💡 Future  |
-| 15  | `Command.Empty`                              |       ✅        |        ✅        |     ✅     |
-| 16  | `Command.Loading`                            |       ✅        |        ✅        |     ✅     |
-| 17  | `useCommandState()` state selector           |       ✅        |        ❌        | 📋 Planned |
-| 18  | **Nested items / Pages**                     |  ✅ (pattern)   |        ❌        | 📋 Planned |
-| 19  | **Built-in search / filtering**              |       ✅        |        ✅        |     ✅     |
-| 20  | **Custom filter function**                   | ✅ (rank-based) | ✅ (item-based)  |     ✅     |
-| 21  | **Global shortcut listener**                 |   ❌ (manual)   |  ✅ (built-in)   |  ✅ Bonus  |
-| 22  | **Keyboard navigation**                      |       ✅        |        ✅        |     ✅     |
-| 23  | **Focus trap**                               |   ✅ (Radix)    |   ✅ (custom)    |     ✅     |
-| 24  | **Zero dependencies**                        |  ❌ (Radix UI)  |   ✅ (0 deps)    | ✅ Better  |
-| 25  | **TypeScript**                               |       ✅        |        ✅        |     ✅     |
-| 26  | **Unstyled**                                 |       ✅        |        ✅        |     ✅     |
-| 27  | **Bundle size (gzip)**                       |      ~7 kB      |    **3.4 kB**    | ✅ Smaller |
-
-> **Legend** — ✅ Done · 📋 High/Medium priority · 💡 Low priority / Nice to have
-
 ## 🚀 Install
 
 ```bash
@@ -106,20 +40,20 @@ npm install vue-command-kit
 
 ```vue
 <script setup lang="ts">
-  import { ref } from 'vue'
-  import { Command } from 'vue-command-kit'
-  import type { CommandItemData } from 'vue-command-kit'
+import { ref } from 'vue'
+import { Command } from 'vue-command-kit'
+import type { CommandItemData } from 'vue-command-kit'
 
-  const visible = ref(false)
+const visible = ref(false)
 
-  const items: CommandItemData[] = [
-    { value: 'settings', label: 'Open settings', shortcut: '⌘,' },
-    { value: 'home', label: 'Go to home', shortcut: '⌘H' },
-  ]
+const items: CommandItemData[] = [
+  { value: 'settings', label: 'Open settings', shortcut: '⌘,' },
+  { value: 'home', label: 'Go to home', shortcut: '⌘H' },
+]
 
-  function onSelect(item: CommandItemData) {
-    console.log('selected:', item.value)
-  }
+function onSelect(item: CommandItemData) {
+  console.log('selected:', item.value)
+}
 </script>
 
 <template>
@@ -155,74 +89,151 @@ npm install vue-command-kit
 
 ```vue
 <script setup lang="ts">
-  import { Command } from 'vue-command-kit'
+import { Command } from 'vue-command-kit'
 
-  function myFilter(items: CommandItemData[], query: string) {
-    // Return filtered items, or null to use default filter
-    return items.filter((item) => item.label?.includes(query))
-  }
+function myFilter(items: CommandItemData[], query: string) {
+  return items.filter((item) => item.label?.includes(query))
+}
+</script>
+
+<template>
+  <Command.Dialog :filter="myFilter" ... />
+</template>
+```
+
+### With v-model:searchQuery
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Command } from 'vue-command-kit'
+import type { CommandItemData } from 'vue-command-kit'
+
+const visible = ref(false)
+const query = ref('')
+
+const items: CommandItemData[] = [
+  { value: 'home', label: 'Home', keywords: ['dashboard'] },
+  { value: 'settings', label: 'Settings' },
+]
 </script>
 
 <template>
   <Command.Dialog
-    :filter="myFilter"
-    ...
+    :visible="visible"
+    :items="items"
+    v-model:searchQuery="query"
+    @update:visible="visible = $event"
   />
 </template>
 ```
 
-## 📖 API
+### Async data + loading
 
-### `<Command.Dialog>` Props
-
-| Prop            | Type                | Default               | Description                  |
-| --------------- | ------------------- | --------------------- | ---------------------------- |
-| `visible`       | `boolean`           | `false`               | Controlled open state        |
-| `items`         | `CommandItemData[]` | `[]`                  | Items to display             |
-| `placeholder`   | `string`            | `'Type a command...'` | Input placeholder            |
-| `filter`        | `FilterFn`          | —                     | Custom filter function       |
-| `loading`       | `boolean`           | `false`               | Show loading state           |
-| `autoFocus`     | `boolean`           | `true`                | Auto-focus input on open     |
-| `closeOnSelect` | `boolean`           | `true`                | Close dialog after selection |
+```vue
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import { Command } from 'vue-command-kit'
+import type { CommandItemData } from 'vue-command-kit'
+
+const visible = ref(false)
+const loading = ref(false)
+const items = ref<CommandItemData[]>([])
+
+watch(visible, async (v) => {
+  if (v) {
+    loading.value = true
+    const data = await fetch('/api/commands').then((r) => r.json())
+    items.value = data.map((d: any) => ({
+      value: d.id,
+      label: d.name,
+      group: d.category,
+    }))
+    loading.value = false
+  }
+})
+</script>
 
-### `<Command.Dialog>` Events
+<template>
+  <Command.Dialog
+    :visible="visible"
+    :items="items"
+    :loading="loading"
+    @update:visible="visible = $event"
+    @select="console.log('selected', $event)"
+  />
+</template>
+```
 
-| Event            | Payload           | Description                      |
-| ---------------- | ----------------- | -------------------------------- |
-| `update:visible` | `boolean`         | Emitted when visibility changes  |
-| `select`         | `CommandItemData` | Emitted when an item is selected |
+## 📖 API
 
 ### Components
 
 | Component             | Description                                    |
 | --------------------- | ---------------------------------------------- |
 | `<Command.Dialog>`    | Modal dialog with mask, transition, focus trap |
-| `<Command.Menu>`      | Inline command menu (non-modal)                |
+| `<Command.Menu>`      | Inline command menu (non-modal) with slots     |
 | `<Command.Input>`     | Search input with keyboard navigation          |
-| `<Command.List>`      | Scrollable list rendering `groupedItems`       |
+| `<Command.List>`      | Scrollable list rendering grouped items        |
 | `<Command.Group>`     | Group of items with heading                    |
 | `<Command.Item>`      | Single selectable command item                 |
 | `<Command.Empty>`     | Shown when no results match                    |
 | `<Command.Separator>` | Visual separator                               |
 | `<Command.Loading>`   | Loading indicator                              |
 
+### `<Command.Dialog>` Props
+
+| Prop            | Type                | Default                         | Description                                    |
+| --------------- | ------------------- | ------------------------------- | ---------------------------------------------- |
+| `visible`       | `boolean`           | `false`                         | Controlled open state                          |
+| `items`         | `CommandItemData[]` | `[]`                            | Items to display                               |
+| `searchQuery`   | `string`            | `''`                            | Search query (`v-model:searchQuery`)           |
+| `value`         | `string`            | —                               | Selected item value (`v-model:value`)          |
+| `placeholder`   | `string`            | `'Type a command or search...'` | Input placeholder                              |
+| `filter`        | `FilterFn`          | —                               | Custom filter function                         |
+| `loading`       | `boolean`           | `false`                         | Show loading state                             |
+| `autoFocus`     | `boolean`           | `true`                          | Auto-focus input on open                       |
+| `closeOnSelect` | `boolean`           | `true`                          | Close dialog after selection                   |
+| `shouldFilter`  | `boolean`           | `true`                          | When `false`, skip built-in filtering          |
+| `loop`          | `boolean`           | `true`                          | When `false`, keyboard nav stops at boundaries |
+| `label`         | `string`            | `'Command menu'`                | `aria-label` for the dialog                    |
+
+### `<Command.Dialog>` Events
+
+| Event                | Payload           | Description                       |
+| -------------------- | ----------------- | --------------------------------- |
+| `update:visible`     | `boolean`         | Emitted when visibility changes   |
+| `update:searchQuery` | `string`          | Emitted when search query changes |
+| `update:value`       | `string`          | Emitted when an item is selected  |
+| `select`             | `CommandItemData` | Emitted when an item is selected  |
+
 ### `CommandItemData`
 
 ```ts
 interface CommandItemData {
+  /** Unique value for this item */
   value: string
+  /** Display label (falls back to value) */
   label?: string
+  /** Optional keywords for search matching */
   keywords?: string[]
+  /** Optional shortcut display (e.g. "⌘S") */
   shortcut?: string
+  /** Group this item belongs to */
   group?: string
+  /** Disabled state */
   disabled?: boolean
-  icon?: Component
+  /** Custom render icon or prefix */
+  icon?: Component | VNode | (() => VNode)
+  /** Callback when item is selected */
   onSelect?: (item: CommandItemData) => void
 }
 ```
 
 ### `useCommandMenu()` Composable
 
+Use the composable for programmatic control outside of `Command.Dialog` / `Command.Menu`.
+
 ```ts
 import { useCommandMenu } from 'vue-command-kit'
 import type { UseCommandMenuReturn, FilterFn } from 'vue-command-kit'
@@ -234,6 +245,38 @@ menu.close()
 menu.toggle()
 ```
 
+Returns:
+
+| Return            | Type                      | Description                                      |
+| ----------------- | ------------------------- | ------------------------------------------------ |
+| `visible`         | `Ref<boolean>`            | Open state                                       |
+| `searchQuery`     | `Ref<string>`             | Current search query                             |
+| `activeIndex`     | `Ref<number>`             | Currently highlighted item index                 |
+| `items`           | `Ref<CommandItemData[]>`  | Raw item list                                    |
+| `filteredItems`   | `ComputedRef<...>`        | Items after filtering                            |
+| `groupedItems`    | `ComputedRef<...>`        | Filtered items grouped by `group` field          |
+| `open()`          | `() => void`              | Open the menu                                    |
+| `close()`         | `() => void`              | Close and reset search                           |
+| `toggle()`        | `() => void`              | Toggle open state                                |
+| `selectNext()`    | `() => void`              | Move active index down                           |
+| `selectPrev()`    | `() => void`              | Move active index up                             |
+| `selectCurrent()` | `() => void`              | Select currently active item                     |
+| `defaultFilter()` | `(items, query) => items` | Default filter implementation (case-insensitive) |
+
+## 📦 Bundle Size
+
+| Format  | Size       |
+| ------- | ---------- |
+| ESM     | 11.8 kB    |
+| UMD     | 11.8 kB    |
+| Gzipped | **3.4 kB** |
+
+Zero runtime dependencies. Peer dependency only on `vue ^3.4.0`.
+
+## 🤝 Acknowledgements
+
+vue-cmdk is inspired by [`cmdk`](https://github.com/pacocoursey/cmdk) by [@pacocoursey](https://github.com/pacocoursey) — a fast, unstyled command menu for React.
+
 ### Keyboard
 
 | Key      | Action                                 |
@@ -245,17 +288,70 @@ menu.toggle()
 
 ## 🤝 Contributing
 
+### Prerequisites
+
+- **Node.js** >= 22.13
+- **pnpm** >= 11.x
+
+### Setup
+
 ```bash
-# dev
+# Clone the repo
+git clone https://github.com/yvng-jie/vue-cmdk.git
+cd vue-cmdk
+
+# Install dependencies
+pnpm install
+
+# Start demo dev server
 pnpm dev
+```
+
+### Scripts
 
-# type check
-pnpm typecheck
+| Command           | Description                               |
+| ----------------- | ----------------------------------------- |
+| `pnpm dev`        | Start demo dev server at `localhost:5173` |
+| `pnpm build`      | Build the library + type declarations     |
+| `pnpm typecheck`  | Run TypeScript type checking              |
+| `pnpm preview`    | Preview production build                  |
+| `pnpm build:demo` | Build demo site to `dist-demo/`           |
 
-# build
-pnpm build
+### Project Structure
+
+```
+src/
+├── useCommandMenu.ts     # core composable (state, filter, shortcuts)
+├── useCommandRoot.ts     # shared composable (provide/inject wiring)
+├── types.ts              # TypeScript type definitions
+├── injectionKeys.ts      # provide/inject keys
+├── utils/
+│   └── injectStrict.ts   # type-safe inject helper
+├── CommandMenu.vue       # inline command menu
+├── CommandDialog.vue     # modal dialog command palette
+├── CommandInput.vue      # search input
+├── CommandList.vue       # scrollable filtered list
+├── CommandGroup.vue      # group with heading
+├── CommandItem.vue       # single selectable item
+├── CommandEmpty.vue      # empty state
+├── CommandSeparator.vue  # visual separator
+├── CommandLoading.vue    # loading indicator
+├── index.ts              # barrel exports
+└── env.d.ts              # type shims
+demo/
+├── App.vue               # demo application
+├── main.ts               # demo entry
+└── style.css             # demo styles
 ```
 
+### Pull Request Process
+
+1. Fork the repo and create a feature branch from `main`
+2. Make your changes and run `pnpm typecheck && pnpm build`
+3. Test your changes with `pnpm dev` (demo app)
+4. Update `CHANGELOG.md` with a description of your changes
+5. Submit a PR with a clear description of what and why
+
 PRs and issues are welcome!
 
 ## 📄 License

package/dist/__tests__/CommandDialog.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/CommandInput.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/CommandItem.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/CommandList.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/injectStrict.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/parseShortcut.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/useCommandMenu.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/useCommandRoot.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -6,15 +6,15 @@ export type * from './types'
 import type { Component } from 'vue'
 
 export const Command: {
-  Menu: Component
-  Dialog: Component
-  Input: Component
-  List: Component
-  Group: Component
-  Item: Component
-  Empty: Component
-  Separator: Component
-  Loading: Component
+  CommandMenu: Component
+  CommandDialog: Component
+  CommandInput: Component
+  CommandList: Component
+  CommandGroup: Component
+  CommandItem: Component
+  CommandEmpty: Component
+  CommandSeparator: Component
+  CommandLoading: Component
 }
 export const CommandMenu: Component
 export const CommandDialog: Component

package/dist/injectionKeys.d.ts

@@ -5,3 +5,4 @@ export declare const CMDK_STATE: InjectionKey<UseCommandMenuReturn>;
 export declare const CMDK_LOADING: InjectionKey<() => boolean>;
 export declare const CMDK_CLOSE_ON_SELECT: InjectionKey<() => boolean>;
 export declare const CMDK_SELECT_HANDLER: InjectionKey<(item: CommandItemData) => void>;
+export declare const CMDK_ITEM_INDEX_MAP: InjectionKey<() => Map<string, number>>;

package/dist/types.d.ts

@@ -34,13 +34,27 @@ export interface CommandRootProps {
     closeOnSelect?: boolean;
     /** Whether the menu is loading */
     loading?: boolean;
+    /** aria-label for the dialog/menu */
+    label?: string;
+    /** When false, skip built-in filtering and show all items (custom filter still applies) */
+    shouldFilter?: boolean;
+    /** When false, keyboard navigation stops at boundaries instead of wrapping around */
+    loop?: boolean;
+    /** Controlled selected item value (v-model) */
+    value?: string;
 }
 /** Emitted events */
 export interface CommandRootEmits {
     (e: 'update:visible', value: boolean): void;
     (e: 'update:searchQuery', value: string): void;
+    (e: 'update:value', value: string): void;
     (e: 'select', item: CommandItemData): void;
 }
+/** Props for CommandDialog — extends shared root props with items array */
+export interface CommandDialogProps extends CommandRootProps {
+    /** Command items to display */
+    items?: CommandItemData[];
+}
 /** Group definition */
 export interface CommandGroupData {
     heading: string;

package/dist/useCommandMenu.d.ts

@@ -1,10 +1,19 @@
 import { Ref, ComputedRef } from 'vue';
 import { CommandItemData, CommandGroupData } from './types';
 export type FilterFn = (items: CommandItemData[], query: string) => CommandItemData[] | null;
+export interface UseCommandMenuOptions {
+    /** Custom filter function */
+    filter?: FilterFn;
+    /** When false, skip built-in filtering */
+    shouldFilter?: boolean;
+    /** When false, keyboard navigation stops at boundaries */
+    loop?: boolean;
+}
 export interface UseCommandMenuReturn {
     visible: Ref<boolean>;
     searchQuery: Ref<string>;
     activeIndex: Ref<number>;
+    selectedValue: Ref<string | undefined>;
     items: Ref<CommandItemData[]>;
     toggle: () => void;
     open: () => void;
@@ -17,4 +26,4 @@ export interface UseCommandMenuReturn {
     selectPrev: () => void;
     selectCurrent: () => void;
 }
-export declare function useCommandMenu(customFilter?: FilterFn, onItemSelect?: (item: CommandItemData) => void): UseCommandMenuReturn;
+export declare function useCommandMenu(optionsOrFilter?: UseCommandMenuOptions | FilterFn, onItemSelect?: (item: CommandItemData) => void): UseCommandMenuReturn;

package/dist/useCommandRoot.d.ts

@@ -0,0 +1,22 @@
+import { CommandItemData, CommandRootEmits } from './types';
+import { useCommandMenu, FilterFn } from './useCommandMenu';
+export interface UseCommandRootOptions {
+    filter?: FilterFn;
+    loading?: boolean;
+    closeOnSelect?: boolean;
+    shouldFilter?: boolean;
+    loop?: boolean;
+    value?: string;
+}
+export interface UseCommandRootReturn {
+    state: ReturnType<typeof useCommandMenu>;
+    handleSelect: (item: CommandItemData) => void;
+}
+/**
+ * Shared composable for root command components (Menu, Dialog).
+ *
+ * - Creates the command menu state
+ * - Provides all injection keys so child components can consume them
+ * - Returns the state and a select handler
+ */
+export declare function useCommandRoot(options: UseCommandRootOptions, emit: CommandRootEmits, onItemSelect?: (item: CommandItemData) => void): UseCommandRootReturn;

package/dist/utils/injectStrict.d.ts

@@ -0,0 +1,8 @@
+import { InjectionKey } from 'vue';
+/**
+ * Type-safe inject that throws a clear error when a required value is missing.
+ *
+ * Use this instead of `inject(key)!` to get early feedback when a child
+ * component is used outside of `<CommandMenu>` or `<CommandDialog>`.
+ */
+export declare function injectStrict<T>(key: InjectionKey<T>, componentName: string): T;