vue-command-kit 0.1.2 → 0.2.0

package/README.md

@@ -2,33 +2,26 @@
   <img src="https://img.shields.io/npm/v/vue-command-kit?color=blue&label=version" alt="npm">
   <img src="https://img.shields.io/badge/vue-3.4%2B-brightgreen" alt="vue">
   <img src="https://img.shields.io/badge/license-MIT-blue" alt="license">
-  <img src="https://img.shields.io/badge/bundle-3.4kB_gzip-green" alt="size">
+  <img src="https://img.shields.io/badge/bundle-5.0kB_gzip-green" alt="size">
+  <img src="https://img.shields.io/badge/tests-117_passed-brightgreen" alt="tests">
 </p>
 
 <h1 align="center">⌘K — vue-cmdk</h1>
 <p align="center">
-  <b>A fast, composable, unstyled command palette for Vue 3.</b><br>
-  Press <kbd>⌘K</kbd> and take control.
+  A fast, composable, unstyled command palette for Vue 3.
 </p>
 
-<p align="center">
-  <img src="./demo.gif" alt="vue-cmdk demo" width="720">
-</p>
-
-## ✨ Features
+## Features
 
-- **🧩 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
+- **Compound component API** — Declarative composition with `<Command.Dialog>`, `<Command.Input>`, `<Command.Item>`, and more
+- **Built-in search** — Case-insensitive filtering with keyword matching and result highlighting
+- **Force render** — `forceMount` prop keeps items in the DOM when filtered out (for animations)
+- **Keyboard-first** — Arrow key navigation, Enter to select, Escape to close, global shortcuts
+- **Unstyled** — Zero CSS opinions; bring your own styles
+- **TypeScript** — Full type inference, exported types, and declaration files
+- **Zero runtime dependencies** — Peer dependency only on `vue ^3.4.0`
 
-## 🚀 Install
+## Installation
 
 ```bash
 npm install vue-command-kit
@@ -36,7 +29,7 @@ npm install vue-command-kit
 
 ## Quick Start
 
-### Simple — items prop
+### With items prop
 
 ```vue
 <script setup lang="ts">
@@ -68,7 +61,7 @@ function onSelect(item: CommandItemData) {
 </template>
 ```
 
-### Advanced — custom slot content
+### With custom slot content
 
 ```vue
 <Command.Dialog :visible="visible" @update:visible="visible = $event">
@@ -85,87 +78,7 @@ function onSelect(item: CommandItemData) {
 </Command.Dialog>
 ```
 
-### With custom filter
-
-```vue
-<script setup lang="ts">
-import { Command } from 'vue-command-kit'
-
-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
-    :visible="visible"
-    :items="items"
-    v-model:searchQuery="query"
-    @update:visible="visible = $event"
-  />
-</template>
-```
-
-### Async data + loading
-
-```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>
-
-<template>
-  <Command.Dialog
-    :visible="visible"
-    :items="items"
-    :loading="loading"
-    @update:visible="visible = $event"
-    @select="console.log('selected', $event)"
-  />
-</template>
-```
-
-## 📖 API
+## API
 
 ### Components
 
@@ -177,26 +90,27 @@ watch(visible, async (v) => {
 | `<Command.List>`      | Scrollable list rendering grouped items        |
 | `<Command.Group>`     | Group of items with heading                    |
 | `<Command.Item>`      | Single selectable command item                 |
+| `<Command.Separator>` | Visual separator with optional `alwaysRender`  |
 | `<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                    |
+| 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                    |
+| `container`     | `string \| HTMLElement` | `'body'`                        | Teleport target for the dialog                 |
 
 ### `<Command.Dialog>` Events
 
@@ -211,155 +125,61 @@ watch(visible, async (v) => {
 
 ```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
-  /** Custom render icon or prefix */
+  forceMount?: boolean
   icon?: Component | VNode | (() => VNode)
-  /** Callback when item is selected */
   onSelect?: (item: CommandItemData) => void
 }
 ```
 
-### `useCommandMenu()` Composable
+### `useCommandMenu()`
 
-Use the composable for programmatic control outside of `Command.Dialog` / `Command.Menu`.
+The composable provides programmatic control outside of `Command.Dialog` / `Command.Menu`.
 
 ```ts
 import { useCommandMenu } from 'vue-command-kit'
-import type { UseCommandMenuReturn, FilterFn } from 'vue-command-kit'
 
-const menu: UseCommandMenuReturn = useCommandMenu(customFilter?)
+const menu = useCommandMenu()
 menu.items.value = [...]
 menu.open()
 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                                 |
-| -------- | -------------------------------------- |
-| `↑` `↓`  | Navigate items (wraps around)          |
-| `Enter`  | Select current item                    |
-| `Escape` | Close dialog                           |
-| `Tab`    | Moves focus within dialog (focus trap) |
-
-## 🤝 Contributing
-
-### Prerequisites
-
-- **Node.js** >= 22.13
-- **pnpm** >= 11.x
-
-### Setup
-
-```bash
-# 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
-
-| 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/`           |
-
-### 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
-
-MIT © [yvng-jie](https://github.com/yvng-jie)
+| 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            |
+
+## Bundle Size
+
+| Format  | Size    |
+| ------- | ------- |
+| ESM     | 17.0 kB |
+| UMD     | 13.5 kB |
+| Gzipped | 5.0 kB  |
+
+## License
+
+MIT &copy; [yvng-jie](https://github.com/yvng-jie)
 
 ---
 
 <p align="center">
-  <sub>Made with ❤️ for the Vue community. Thanks to <a href="https://github.com/xiaoluoboding">@xiaoluoboding</a> for the original <a href="https://github.com/xiaoluoboding/vue-command-palette">vue-command-palette</a>.</sub>
+  <a href="./CONTRIBUTING.md">Contributing Guide</a>
 </p>

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

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

package/dist/types.d.ts

@@ -15,6 +15,8 @@ export interface CommandItemData {
     disabled?: boolean;
     /** Custom render icon or prefix */
     icon?: Component | VNode | (() => VNode);
+    /** Whether to force this item to always appear in filtered results */
+    forceMount?: boolean;
     /** Callback when item is selected */
     onSelect?: (item: CommandItemData) => void;
 }
@@ -54,6 +56,8 @@ export interface CommandRootEmits {
 export interface CommandDialogProps extends CommandRootProps {
     /** Command items to display */
     items?: CommandItemData[];
+    /** Teleport target for the dialog (defaults to 'body') */
+    container?: string | HTMLElement;
 }
 /** Group definition */
 export interface CommandGroupData {

package/dist/utils/highlight.d.ts

@@ -0,0 +1,9 @@
+export interface HighlightSegment {
+    text: string;
+    highlighted: boolean;
+}
+/**
+ * Split text into segments, marking parts that match the query.
+ * Matching is case-insensitive.
+ */
+export declare function highlightText(text: string, query: string): HighlightSegment[];

package/dist/utils/shortcut.d.ts

@@ -0,0 +1,12 @@
+/** Parsed shortcut descriptor */
+export interface ShortcutDescriptor {
+    key: string;
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    shiftKey?: boolean;
+}
+/** Parse a shortcut string like "⌘S" or "⌘⇧F" into a key+modifiers descriptor */
+export declare function parseShortcut(shortcut: string): ShortcutDescriptor | null;
+/** Check if a KeyboardEvent matches a parsed shortcut descriptor */
+export declare function eventMatchesShortcut(e: KeyboardEvent, desc: ShortcutDescriptor | null): boolean;