@bysivin/jumpbar 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sivin Varghese
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# jumpbar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A lightweight command palette for Vue 3. The ranking core is plain JavaScript
+with no dependencies (about 1 KB gzipped); the shell is a native `<dialog>`
+rendered with Tailwind utilities (about 5 KB gzipped with the core).
+
+- Fuzzy matching with accent folding, sections, nested pages and prefixes
+- Frecency so the things you use rise to the top
+- Sync `commands` sources ranked on every keystroke, async `search` sources
+  with per-source debounce, minimum query length and `AbortSignal`
+- Keyboard and pointer handling, open/close motion, skeleton rows while
+  remote results load, RTL and IME aware
+
+## Install
+
+```sh
+pnpm add @bysivin/jumpbar
+```
+
+`vue` 3.4 or newer is a peer dependency. The package ships source, so your
+bundler compiles the `.vue` files like your own.
+
+## Styling
+
+The shell is styled with Tailwind classes and expects three things from the
+host project:
+
+1. Add the package to `content` so its classes are generated, and add the
+   preset that defines the open/close keyframes:
+
+   ```js
+   // tailwind.config.js
+   module.exports = {
+     presets: [require('@bysivin/jumpbar/tailwind')],
+     content: ['./node_modules/@bysivin/jumpbar/src/**/*.{vue,js}'],
+   };
+   ```
+
+2. Define these colour tokens in your theme: `n-background`, `n-strong`,
+   `n-weak`, `n-brand`, `n-alpha-1`, `n-alpha-2`, `n-alpha-black1`,
+   `n-slate-3`, `n-slate-10`, `n-slate-11`, `n-slate-12`, `n-teal-10`,
+   `n-amber-10`.
+
+3. Provide the icon classes `i-lucide-search`, `i-lucide-loader-circle` and
+   `i-lucide-chevron-right` (for example through `@egoist/tailwindcss-icons`
+   with the Lucide set). Items bring their own icon class.
+
+## Usage
+
+```vue
+<script setup>
+import { CommandBar, createFrecency, useCommandBar } from '@bysivin/jumpbar';
+
+const bar = useCommandBar();
+
+bar.configure({
+  prefixes: ['@', '#'],
+  context: () => ({ scopes: ['conversation'] }),
+  frecency: createFrecency({ storage: localStorage, key: 'palette-usage' }),
+  onSelect: item => track(item),
+  onClose: () => {},
+  onError: (error, source) => report(error),
+  limit: 100,
+});
+
+bar.register({
+  id: 'navigation',
+  commands: () => [
+    {
+      id: 'inbox',
+      title: 'Go to inbox',
+      section: 'Navigation',
+      icon: 'i-lucide-inbox',
+      shortcut: ['⌥', 'I'],
+      run: () => router.push('/inbox'),
+    },
+  ],
+});
+
+bar.register({
+  id: 'contacts',
+  minQuery: 3,
+  debounce: 300,
+  when: ({ page }) => !page,
+  search: async ({ text, signal }) => {
+    const contacts = await api.search(text, { signal });
+    return contacts.map(contact => ({
+      id: `contact-${contact.id}`,
+      title: contact.name,
+      subtitle: contact.email,
+      section: 'Contacts',
+      avatar: { name: contact.name, src: contact.thumbnail },
+      run: () => router.push(`/contacts/${contact.id}`),
+    }));
+  },
+});
+</script>
+
+<template>
+  <CommandBar
+    placeholder="Search or jump to"
+    empty-text="No matches"
+    :hints="[
+      { keys: ['↑', '↓'], label: 'navigate' },
+      { keys: ['↵'], label: 'select' },
+      { keys: ['esc'], label: 'close' },
+    ]"
+  />
+</template>
+```
+
+Bind the global shortcut yourself and call `bar.toggle()`. `bar.open({ page,
+query })` opens straight into a page, for example a snooze picker.
+
+`CommandBar` props: `placeholder`, `emptyText`, `scopeLabel` (a chip before the
+input, for example the selected record), `hints` and `dir` (`ltr` or `rtl`).
+
+## Items
+
+Sources return plain objects:
+
+| Field            | Meaning                                                                  |
+| ---------------- | ------------------------------------------------------------------------ |
+| `id`             | Unique across all sources. Frecency and dedupe key on it.                |
+| `title`          | Row label. Children are matched through `parentTitle title` too.         |
+| `subtitle`       | Muted text after the title. Truncates before the title does.             |
+| `section`        | Group header. Groups keep the order of their first item.                 |
+| `icon`           | CSS class rendered as the leading glyph.                                 |
+| `avatar`         | `{ name, src, status }` instead of the icon, initials as fallback; `status` is `online`, `busy` or `offline`. |
+| `badge`          | Short trailing text.                                                     |
+| `shortcut`       | Trailing key labels, for example `['⌥', 'E']`.                           |
+| `keywords`       | Extra words the matcher sees (word-start matches only).                  |
+| `scopes`         | Ranks first when one matches `context.scopes`.                           |
+| `prefix`         | Typing this character first lists only items carrying it.                |
+| `weight`         | Static boost between 0 and 1.                                            |
+| `place`          | `first` or `last`: sorts around every other match, in declared order.    |
+| `searchFromRoot` | `false` keeps a child out of root searches (prefix and page only).       |
+| `page`           | Selecting opens a page listing the items whose `parent` is its id.       |
+| `placeholder`    | Input placeholder while that page is open.                               |
+| `parent`         | Id of the page this item lives under.                                    |
+| `run`            | Called with the context as the bar starts closing; the dialog leaves the top layer about 150 ms later. Rows without it are inert. |
+
+## Sources
+
+```js
+bar.register({
+  id: 'conversations',
+  minQuery: 2,
+  debounce: 300,
+  when: ({ page }) => !page,
+  commands: request => [],
+  search: async request => [],
+});
+```
+
+`commands` runs on every keystroke and is ranked. `search` runs after the
+debounce with an `AbortSignal`; its results keep their own order, append after
+the ranked commands at the root, and replace the static children on a page.
+The request carries `query`, `text`, `prefix`, `page`, `context` and, for
+`search`, `matches` (how many commands matched locally) and `signal`.
+`register` returns a function that removes the source again. A searcher that
+throws has its rows dropped and `onError(error, source)` called; the default
+rethrows. Text queries show at most `limit` ranked commands (default 100).
+
+## Ranking
+
+Titles match by exact, prefix, word start, every-word-starts-a-word, then
+scattered characters. Subtitles and keywords only match on word starts, so a
+long description never floods the list. Items in `context.scopes` get a boost,
+recently used items another, `weight` a small static one. `place: 'first'`
+and `place: 'last'` sit outside the scoring entirely.
+
+## Keyboard
+
+`↑` `↓` move, `Enter` selects, `Esc` closes, `Backspace` on an empty query goes
+back one page. Hover only changes the selection when the pointer really moves,
+so arrow keys keep working under a resting cursor.
+
+## Development
+
+```sh
+pnpm install
+pnpm test
+```

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@bysivin/jumpbar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Lightweight command palette for Vue 3: a framework-free ranking core with fuzzy matching, sections, pages, prefixes and frecency, plus a native <dialog> shell with async sources.",
+  "license": "MIT",
+  "author": "Sivin Varghese",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./tailwind": "./tailwind.cjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "!src/**/specs",
+    "tailwind.cjs"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iamsivin/jumpbar.git"
+  },
+  "keywords": [
+    "command-palette",
+    "command-bar",
+    "spotlight",
+    "vue",
+    "headless",
+    "fuzzy-search"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "vue": "^3.4.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.4",
+    "@vue/test-utils": "^2.4.6",
+    "jsdom": "^27.2.0",
+    "vitest": "3.0.5",
+    "vue": "^3.5.12"
+  }
+}

package/src/core/frecency.js

@@ -0,0 +1,41 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HALF_LIFE_DAYS = 7;
+const USES_FOR_FULL_SCORE = 3;
+const MAX_IDLE_DAYS = 30;
+
+const load = (storage, key) => {
+  try {
+    return JSON.parse(storage.getItem(key)) ?? {};
+  } catch {
+    return {};
+  }
+};
+
+export const createFrecency = ({
+  storage,
+  key,
+  now = Date.now,
+  limit = 10,
+}) => {
+  const uses = load(storage, key);
+
+  const record = id => {
+    const at = now();
+    uses[id] = [...(uses[id] ?? []), at].slice(-limit);
+    Object.keys(uses).forEach(other => {
+      if (at - uses[other].at(-1) > MAX_IDLE_DAYS * DAY_MS) delete uses[other];
+    });
+    storage.setItem(key, JSON.stringify(uses));
+  };
+
+  const score = id => {
+    const total = (uses[id] ?? []).reduce(
+      (sum, usedAt) =>
+        sum + 0.5 ** ((now() - usedAt) / DAY_MS / HALF_LIFE_DAYS),
+      0
+    );
+    return Math.min(1, total / USES_FOR_FULL_SCORE);
+  };
+
+  return { record, score };
+};

package/src/core/match.js

@@ -0,0 +1,71 @@
+const COMBINING_MARKS = /[\u0300-\u036f]/g;
+
+const EXACT = 1;
+const PREFIX = 0.9;
+const WORD_START = 0.8;
+const ALL_WORDS = 0.7;
+const SUBSEQUENCE_MAX = 0.6;
+const SUBSEQUENCE_MIN = 0.2;
+
+const NORMALIZED_CACHE_LIMIT = 5000;
+const normalized = new Map();
+
+export const normalize = value => {
+  const raw = String(value ?? '');
+  const cached = normalized.get(raw);
+  if (cached !== undefined) return cached;
+  if (normalized.size >= NORMALIZED_CACHE_LIMIT) normalized.clear();
+  const result = raw
+    .normalize('NFD')
+    .replace(COMBINING_MARKS, '')
+    .toLowerCase()
+    .trim();
+  normalized.set(raw, result);
+  return result;
+};
+
+const tightestSpan = (query, text) => {
+  let best = Infinity;
+  for (
+    let start = text.indexOf(query[0]);
+    start !== -1;
+    start = text.indexOf(query[0], start + 1)
+  ) {
+    let cursor = start;
+    let matched = true;
+    for (let i = 1; i < query.length; i += 1) {
+      cursor = text.indexOf(query[i], cursor + 1);
+      if (cursor === -1) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched) best = Math.min(best, cursor - start + 1);
+  }
+  return best;
+};
+
+export const fuzzyScore = (query, text, { subsequence = true } = {}) => {
+  const needle = normalize(query);
+  if (!needle) return EXACT;
+  const haystack = normalize(text);
+  if (haystack === needle) return EXACT;
+  if (haystack.startsWith(needle)) return PREFIX;
+
+  const words = haystack.split(/\s+/);
+  if (words.some(word => word.startsWith(needle))) return WORD_START;
+
+  const needleWords = needle.split(/\s+/);
+  if (needleWords.every(part => words.some(word => word.startsWith(part)))) {
+    return ALL_WORDS;
+  }
+
+  if (!subsequence) return 0;
+  const compact = needle.replace(/\s+/g, '');
+  const span = tightestSpan(compact, haystack);
+  if (span === Infinity) return 0;
+  return (
+    SUBSEQUENCE_MIN +
+    (SUBSEQUENCE_MAX - SUBSEQUENCE_MIN) * (compact.length / span)
+  );
+};

package/src/core/parse.js

@@ -0,0 +1,6 @@
+export const parseQuery = (input, prefixes = []) => {
+  const trimmed = String(input ?? '').trim();
+  const prefix = prefixes.includes(trimmed[0]) ? trimmed[0] : null;
+  const text = prefix ? trimmed.slice(1).trim() : trimmed;
+  return { prefix, text };
+};

package/src/core/rank.js

@@ -0,0 +1,70 @@
+import { fuzzyScore } from './match';
+
+const SCOPE_BOOST = 0.3;
+const FRECENCY_BOOST = 0.2;
+const WEIGHT_BOOST = 0.1;
+
+const NO_FRECENCY = { score: () => 0 };
+const TIERS = { first: 0, last: 2 };
+const tierOf = item => TIERS[item.place] ?? 1;
+
+const visibleItems = (items, { text, prefix, page }) => {
+  if (page) return items.filter(item => item.parent === page);
+  if (prefix) return items.filter(item => item.prefix === prefix);
+  if (!text) return items.filter(item => !item.parent);
+  return items.filter(item => item.searchFromRoot !== false);
+};
+
+const detailText = item =>
+  [item.subtitle, ...(item.keywords ?? [])].filter(Boolean).join(' ');
+
+const matchScore = (text, item, parentTitle) =>
+  Math.max(
+    fuzzyScore(text, item.title),
+    parentTitle ? fuzzyScore(text, `${parentTitle} ${item.title}`) : 0,
+    fuzzyScore(text, detailText(item), { subsequence: false })
+  );
+
+export const rank = (
+  items,
+  { text = '', prefix = null, page = null, scopes = [], frecency = NO_FRECENCY }
+) => {
+  const titles = new Map(items.map(item => [item.id, item.title]));
+
+  return visibleItems(items, { text, prefix, page })
+    .map(item => {
+      const parentTitle =
+        item.parent && !page ? titles.get(item.parent) : undefined;
+      const match = text ? matchScore(text, item, parentTitle) : 1;
+      const inScope = item.scopes?.some(scope => scopes.includes(scope))
+        ? 1
+        : 0;
+      const score =
+        match +
+        SCOPE_BOOST * inScope +
+        FRECENCY_BOOST * frecency.score(item.id) +
+        WEIGHT_BOOST * (item.weight ?? 0);
+      return {
+        item: parentTitle ? { ...item, parentTitle } : item,
+        match,
+        score,
+      };
+    })
+    .filter(entry => entry.match > 0)
+    .sort((a, b) => {
+      const tier = tierOf(a.item) - tierOf(b.item);
+      if (tier) return tier;
+      return a.item.place ? 0 : b.score - a.score;
+    })
+    .map(entry => entry.item);
+};
+
+export const groupBySection = items => {
+  const groups = new Map();
+  items.forEach(item => {
+    const section = item.section ?? null;
+    if (!groups.has(section)) groups.set(section, []);
+    groups.get(section).push(item);
+  });
+  return [...groups].map(([section, members]) => ({ section, items: members }));
+};

package/src/index.js

@@ -0,0 +1,6 @@
+export { fuzzyScore, normalize } from './core/match';
+export { parseQuery } from './core/parse';
+export { createFrecency } from './core/frecency';
+export { rank, groupBySection } from './core/rank';
+export { createCommandBar, useCommandBar } from './vue/useCommandBar';
+export { default as CommandBar } from './vue/CommandBar.vue';

package/src/vue/CommandBar.vue

@@ -0,0 +1,173 @@
+<script setup>
+import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue';
+import { useCommandBar } from './useCommandBar';
+import CommandBarList from './CommandBarList.vue';
+
+const props = defineProps({
+  placeholder: { type: String, default: '' },
+  emptyText: { type: String, default: '' },
+  scopeLabel: { type: String, default: '' },
+  hints: { type: Array, default: () => [] },
+  dir: { type: String, default: 'ltr' },
+});
+
+const CLOSE_ANIMATION_MS = 150;
+const PLACEHOLDER_DELAY_MS = 150;
+
+const bar = useCommandBar();
+const dialogRef = ref(null);
+const inputRef = ref(null);
+const isClosing = ref(false);
+let closeTimer = null;
+
+const placeholder = computed(
+  () => bar.page.value?.placeholder ?? props.placeholder
+);
+const activeId = computed(() =>
+  bar.selected.value ? `command-bar-item-${bar.selected.value.id}` : undefined
+);
+const isEmpty = computed(
+  () => !bar.visible.value.length && !bar.isLoading.value
+);
+const showPlaceholder = ref(false);
+let placeholderTimer = null;
+
+watch(bar.isLoading, loading => {
+  clearTimeout(placeholderTimer);
+  if (!loading) {
+    showPlaceholder.value = false;
+    return;
+  }
+  placeholderTimer = setTimeout(() => {
+    showPlaceholder.value = true;
+  }, PLACEHOLDER_DELAY_MS);
+});
+
+const KEY_ACTIONS = {
+  ArrowDown: () => bar.moveSelection(1),
+  ArrowUp: () => bar.moveSelection(-1),
+  Enter: () => bar.select(bar.selected.value),
+  Escape: () => bar.close(),
+  Backspace: () => (bar.query.value ? false : bar.back()),
+};
+
+const onKeydown = event => {
+  if (event.isComposing || event.keyCode === 229) return;
+  const action = KEY_ACTIONS[event.key];
+  if (!action || action() === false) return;
+  event.preventDefault();
+};
+
+watch(bar.isOpen, async open => {
+  clearTimeout(closeTimer);
+  if (!open) {
+    isClosing.value = true;
+    closeTimer = setTimeout(() => {
+      dialogRef.value.close();
+      isClosing.value = false;
+    }, CLOSE_ANIMATION_MS);
+    return;
+  }
+  isClosing.value = false;
+  if (!dialogRef.value.open) dialogRef.value.showModal();
+  await nextTick();
+  inputRef.value.focus();
+});
+
+onBeforeUnmount(() => {
+  clearTimeout(closeTimer);
+  clearTimeout(placeholderTimer);
+});
+</script>
+
+<template>
+  <Teleport to="body">
+    <dialog
+      ref="dialogRef"
+      :dir="dir"
+      class="w-[calc(100vw-2rem)] max-w-2xl p-0 mx-auto mt-[clamp(2rem,10vh,6rem)] mb-auto overflow-hidden shadow-2xl rounded-2xl bg-n-background outline outline-1 outline-n-strong/50 text-n-slate-12 motion-reduce:animate-none backdrop:bg-n-alpha-black1 max-sm:w-full max-sm:max-w-full max-sm:mt-auto max-sm:mb-0 max-sm:rounded-b-none"
+      :class="
+        isClosing
+          ? 'animate-command-bar-out backdrop:animate-fade-out'
+          : 'animate-pop-in backdrop:animate-fade-in'
+      "
+      @cancel.prevent="bar.close"
+      @close="bar.close"
+      @click.self="bar.close"
+    >
+      <div class="flex items-center gap-2 px-4 h-14">
+        <span class="flex-shrink-0 i-lucide-search size-4 text-n-slate-10" />
+        <span
+          v-if="scopeLabel"
+          class="flex-shrink-0 px-2 py-0.5 text-xs rounded-md bg-n-alpha-2 text-n-slate-11 max-w-48 truncate"
+        >
+          {{ scopeLabel }}
+        </span>
+        <span
+          v-if="bar.page.value"
+          class="flex-shrink-0 px-2 py-0.5 text-xs font-medium rounded-md bg-n-brand/10 text-n-brand max-w-48 truncate"
+        >
+          {{ bar.page.value.title }}
+        </span>
+        <input
+          ref="inputRef"
+          role="combobox"
+          aria-autocomplete="list"
+          aria-controls="command-bar-list"
+          :aria-expanded="bar.isOpen.value"
+          :aria-activedescendant="activeId"
+          :value="bar.query.value"
+          :placeholder="placeholder"
+          autocomplete="off"
+          spellcheck="false"
+          class="flex-1 h-full min-w-0 text-base bg-transparent border-0 outline-none text-n-slate-12 placeholder:text-n-slate-10"
+          @input="bar.setQuery($event.target.value)"
+          @keydown="onKeydown"
+        />
+        <span
+          v-if="bar.isLoading.value"
+          class="flex-shrink-0 i-lucide-loader-circle size-4 animate-spin text-n-slate-10"
+        />
+      </div>
+      <div class="border-t border-n-weak">
+        <CommandBarList
+          v-if="bar.visible.value.length || showPlaceholder"
+          id="command-bar-list"
+          :key="bar.page.value?.id ?? 'root'"
+          class="max-h-[60vh] max-sm:max-h-[70vh] animate-fade-in-up motion-reduce:animate-none"
+          :sections="bar.sections.value"
+          :items="bar.visible.value"
+          :selected-index="bar.selectedIndex.value"
+          :pending="showPlaceholder"
+          @activate="bar.selectedIndex.value = $event"
+          @select="bar.select"
+        />
+        <p
+          v-else-if="isEmpty"
+          class="px-4 py-10 text-sm text-center text-n-slate-11"
+        >
+          {{ emptyText }}
+        </p>
+      </div>
+      <div
+        v-if="hints.length"
+        class="flex items-center gap-4 px-4 text-xs border-t h-9 border-n-weak text-n-slate-10"
+      >
+        <span
+          v-for="hint in hints"
+          :key="hint.label"
+          class="flex items-center gap-1"
+        >
+          <kbd
+            v-for="key in hint.keys"
+            :key="key"
+            class="inline-flex items-center justify-center h-5 px-1 rounded min-w-5 text-n-slate-11 bg-n-alpha-1 outline outline-1 outline-n-weak"
+          >
+            {{ key }}
+          </kbd>
+          <span class="ms-0.5">{{ hint.label }}</span>
+        </span>
+      </div>
+    </dialog>
+  </Teleport>
+</template>

package/src/vue/CommandBarList.vue

@@ -0,0 +1,173 @@
+<script setup>
+import { computed, reactive, ref, watch } from 'vue';
+
+const props = defineProps({
+  sections: { type: Array, required: true },
+  items: { type: Array, required: true },
+  selectedIndex: { type: Number, required: true },
+  pending: { type: Boolean, default: false },
+});
+
+const emit = defineEmits(['select', 'activate']);
+
+const PLACEHOLDER_ROWS = 3;
+
+const STATUS_CLASSES = {
+  online: 'bg-n-teal-10',
+  busy: 'bg-n-amber-10',
+  offline: 'bg-n-slate-10',
+};
+
+const listRef = ref(null);
+const failedImages = reactive(new Set());
+let pointer = { x: null, y: null };
+
+const onPointerMove = (event, index) => {
+  if (event.clientX === pointer.x && event.clientY === pointer.y) return;
+  pointer = { x: event.clientX, y: event.clientY };
+  emit('activate', index);
+};
+
+const indexes = computed(
+  () => new Map(props.items.map((item, index) => [item.id, index]))
+);
+
+const initials = name =>
+  (name ?? '')
+    .split(/\s+/)
+    .slice(0, 2)
+    .map(word => [...word][0] ?? '')
+    .join('')
+    .toUpperCase();
+
+watch(
+  [() => props.selectedIndex, () => props.sections],
+  ([index]) => {
+    const list = listRef.value;
+    if (!list) return;
+    if (index === 0) list.scrollTop = 0;
+    else {
+      list
+        .querySelector('[aria-selected="true"]')
+        ?.scrollIntoView({ block: 'nearest' });
+    }
+  },
+  { flush: 'post' }
+);
+</script>
+
+<template>
+  <div ref="listRef" role="listbox" class="px-2 py-2 overflow-y-auto">
+    <div
+      v-for="section in sections"
+      :key="section.section ?? ''"
+      role="group"
+      :aria-label="section.section ?? undefined"
+    >
+      <p
+        v-if="section.section"
+        class="px-3 pt-3 pb-1 text-xs font-medium text-n-slate-11 first:pt-1"
+      >
+        {{ section.section }}
+      </p>
+      <div
+        v-for="item in section.items"
+        :id="`command-bar-item-${item.id}`"
+        :key="item.id"
+        role="option"
+        :aria-selected="indexes.get(item.id) === selectedIndex"
+        class="relative flex items-center h-10 gap-3 px-3 text-sm rounded-lg cursor-pointer select-none text-n-slate-12 transition-colors duration-75"
+        :class="{
+          'bg-n-alpha-2 before:absolute before:inset-y-2 before:start-0 before:w-0.5 before:rounded-full before:bg-n-brand':
+            indexes.get(item.id) === selectedIndex,
+        }"
+        @mousedown.prevent
+        @mousemove="onPointerMove($event, indexes.get(item.id))"
+        @click="emit('select', item)"
+      >
+        <span
+          v-if="item.avatar"
+          class="relative flex items-center justify-center flex-shrink-0 rounded-md size-6 bg-n-alpha-2 text-n-slate-11"
+        >
+          <img
+            v-if="item.avatar.src && !failedImages.has(item.avatar.src)"
+            :src="item.avatar.src"
+            :alt="item.avatar.name"
+            class="object-cover rounded-md size-6"
+            @error="failedImages.add(item.avatar.src)"
+          />
+          <span v-else class="text-xs font-medium leading-none">
+            {{ initials(item.avatar.name) }}
+          </span>
+          <span
+            v-if="item.avatar.status"
+            class="absolute -bottom-px -end-px border rounded-full size-2 border-n-slate-3"
+            :class="STATUS_CLASSES[item.avatar.status]"
+          />
+        </span>
+        <span
+          v-else
+          class="flex items-center justify-center flex-shrink-0 size-6"
+        >
+          <span
+            class="size-4"
+            :class="[
+              item.icon,
+              indexes.get(item.id) === selectedIndex
+                ? 'text-n-slate-12'
+                : 'text-n-slate-11',
+            ]"
+          />
+        </span>
+        <span class="flex items-center flex-1 min-w-0 gap-1.5 overflow-hidden">
+          <template v-if="item.parentTitle">
+            <span class="truncate text-n-slate-11">{{ item.parentTitle }}</span>
+            <span
+              class="flex-shrink-0 i-lucide-chevron-right size-3 text-n-slate-10 rtl:-scale-x-100"
+            />
+          </template>
+          <span class="flex-shrink-0 max-w-full truncate">{{
+            item.title
+          }}</span>
+          <span v-if="item.subtitle" class="truncate text-n-slate-11">
+            {{ item.subtitle }}
+          </span>
+        </span>
+        <span v-if="item.badge" class="flex-shrink-0 text-xs text-n-slate-11">
+          {{ item.badge }}
+        </span>
+        <span v-if="item.shortcut" class="flex items-center gap-1">
+          <kbd
+            v-for="key in item.shortcut"
+            :key="key"
+            class="inline-flex items-center justify-center h-5 px-1 text-xs rounded min-w-5 text-n-slate-11 bg-n-alpha-1 outline outline-1 outline-n-weak"
+          >
+            {{ key }}
+          </kbd>
+        </span>
+        <span
+          v-if="item.page"
+          class="flex-shrink-0 i-lucide-chevron-right size-4 text-n-slate-10 rtl:-scale-x-100"
+        />
+      </div>
+    </div>
+    <div
+      v-if="pending"
+      aria-hidden="true"
+      class="animate-pulse motion-reduce:animate-none"
+    >
+      <div class="px-3 pt-3 pb-1">
+        <span class="block w-20 h-3 rounded bg-n-alpha-2" />
+      </div>
+      <div
+        v-for="row in PLACEHOLDER_ROWS"
+        :key="row"
+        class="flex items-center h-10 gap-3 px-3"
+      >
+        <span class="flex-shrink-0 rounded-md size-6 bg-n-alpha-2" />
+        <span class="h-3 rounded w-36 bg-n-alpha-2" />
+        <span class="h-3 rounded w-24 bg-n-alpha-1" />
+      </div>
+    </div>
+  </div>
+</template>

package/src/vue/useCommandBar.js

@@ -0,0 +1,261 @@
+import { computed, ref, shallowRef } from 'vue';
+import { parseQuery } from '../core/parse';
+import { rank, groupBySection } from '../core/rank';
+
+const DEFAULT_DEBOUNCE = 120;
+const DEFAULT_LIMIT = 100;
+const NO_FRECENCY = { record: () => {}, score: () => 0 };
+
+export const createCommandBar = (initialOptions = {}) => {
+  const options = {
+    prefixes: [],
+    context: () => ({}),
+    frecency: NO_FRECENCY,
+    onSelect: () => {},
+    onClose: () => {},
+    onError: error => {
+      throw error;
+    },
+    debounce: DEFAULT_DEBOUNCE,
+    limit: DEFAULT_LIMIT,
+    ...initialOptions,
+  };
+
+  let sources = [];
+  let context = {};
+  let controller = null;
+  let timers = [];
+  let sequence = 0;
+
+  const isOpen = ref(false);
+  const query = ref('');
+  const pages = shallowRef([]);
+  const items = shallowRef([]);
+  const results = shallowRef([]);
+  const selectedIndex = ref(0);
+  const pendingCount = ref(0);
+
+  const page = computed(() => pages.value.at(-1) ?? null);
+  const isLoading = computed(() => pendingCount.value > 0);
+
+  const sections = computed(() => {
+    const list =
+      page.value && results.value.length
+        ? results.value
+        : [...items.value, ...results.value];
+    const seen = new Set();
+    const unique = list.filter(item => {
+      if (seen.has(item.id)) return false;
+      seen.add(item.id);
+      return true;
+    });
+    return groupBySection(unique);
+  });
+  const visible = computed(() =>
+    sections.value.flatMap(section => section.items)
+  );
+  const selected = computed(() => visible.value[selectedIndex.value] ?? null);
+
+  const buildRequest = () => {
+    const { prefix, text } = parseQuery(query.value, options.prefixes);
+    return {
+      query: query.value,
+      text,
+      prefix,
+      page: page.value?.id ?? null,
+      context,
+    };
+  };
+
+  const isActive = (source, request) =>
+    request.text.length >= (source.minQuery ?? 0) &&
+    (source.when?.(request) ?? true);
+
+  const collectCommands = request =>
+    sources.flatMap(source =>
+      source.commands && isActive(source, request)
+        ? source.commands(request)
+        : []
+    );
+
+  const delayOf = source => source.debounce ?? options.debounce;
+
+  const publish = batch => {
+    results.value = batch.searchers.flatMap(
+      searcher => batch.fresh.get(searcher.id) ?? []
+    );
+    selectedIndex.value = Math.min(
+      selectedIndex.value,
+      Math.max(visible.value.length - 1, 0)
+    );
+  };
+
+  const runSearchers = (batch, delay) => {
+    batch.searchers
+      .filter(source => delayOf(source) === delay)
+      .forEach(async source => {
+        try {
+          const list = await source.search({
+            ...batch.request,
+            signal: batch.signal,
+          });
+          if (batch.sequence !== sequence) return;
+          batch.fresh.set(source.id, list);
+          publish(batch);
+        } catch (error) {
+          if (batch.sequence !== sequence) return;
+          batch.fresh.set(source.id, []);
+          publish(batch);
+          options.onError(error, source);
+        } finally {
+          if (batch.sequence === sequence) pendingCount.value -= 1;
+        }
+      });
+  };
+
+  const run = () => {
+    timers.forEach(clearTimeout);
+    timers = [];
+    controller?.abort();
+    sequence += 1;
+
+    const request = buildRequest();
+    if (!request.text) results.value = [];
+    const ranked = rank(collectCommands(request), {
+      text: request.text,
+      prefix: request.prefix,
+      page: request.page,
+      scopes: context.scopes ?? [],
+      frecency: options.frecency,
+    });
+    items.value = request.text ? ranked.slice(0, options.limit) : ranked;
+    selectedIndex.value = 0;
+
+    const searchRequest = { ...request, matches: items.value.length };
+    const searchers = sources.filter(
+      source => source.search && isActive(source, searchRequest)
+    );
+    pendingCount.value = searchers.length;
+    if (!searchers.length) {
+      results.value = [];
+      return;
+    }
+
+    controller = new AbortController();
+    const batch = {
+      sequence,
+      request: searchRequest,
+      signal: controller.signal,
+      fresh: new Map(),
+      searchers,
+    };
+    new Set(searchers.map(delayOf)).forEach(delay => {
+      timers.push(setTimeout(() => runSearchers(batch, delay), delay));
+    });
+  };
+
+  const navigate = (nextPages, nextQuery = '') => {
+    pages.value = nextPages;
+    query.value = nextQuery;
+    results.value = [];
+    run();
+  };
+
+  const open = ({ page: pageId = null, query: initialQuery = '' } = {}) => {
+    context = options.context();
+    isOpen.value = true;
+    pages.value = [];
+    query.value = '';
+    const target = pageId
+      ? (collectCommands(buildRequest()).find(item => item.id === pageId) ?? {
+          id: pageId,
+        })
+      : null;
+    navigate(target ? [target] : [], initialQuery);
+  };
+
+  const close = () => {
+    if (!isOpen.value) return;
+    timers.forEach(clearTimeout);
+    timers = [];
+    controller?.abort();
+    sequence += 1;
+    pendingCount.value = 0;
+    isOpen.value = false;
+    options.onClose();
+  };
+
+  const back = () => {
+    if (!page.value) return;
+    navigate(pages.value.slice(0, -1));
+  };
+
+  const select = item => {
+    if (!item) return;
+    if (item.page) {
+      navigate([...pages.value, item]);
+      return;
+    }
+    if (!item.run) return;
+    options.frecency.record(item.id);
+    options.onSelect(item);
+    close();
+    item.run(context);
+  };
+
+  const setQuery = value => {
+    query.value = value;
+    run();
+  };
+
+  const moveSelection = delta => {
+    const count = visible.value.length;
+    if (!count) return;
+    selectedIndex.value = (selectedIndex.value + delta + count) % count;
+  };
+
+  const toggle = () => (isOpen.value ? close() : open());
+
+  const register = source => {
+    sources = [...sources, source];
+    return () => {
+      sources = sources.filter(registered => registered !== source);
+    };
+  };
+
+  const configure = overrides => Object.assign(options, overrides);
+
+  const dispose = () => {
+    close();
+    sources = [];
+  };
+
+  return {
+    isOpen,
+    query,
+    page,
+    pages,
+    visible,
+    sections,
+    selectedIndex,
+    selected,
+    isLoading,
+    open,
+    close,
+    toggle,
+    back,
+    select,
+    setQuery,
+    moveSelection,
+    register,
+    configure,
+    dispose,
+  };
+};
+
+let shared = null;
+
+export const useCommandBar = () => {
+  shared ??= createCommandBar();
+  return shared;
+};

package/tailwind.cjs

@@ -0,0 +1,34 @@
+module.exports = {
+  theme: {
+    extend: {
+      keyframes: {
+        'pop-in': {
+          '0%': { opacity: 0, transform: 'scale(0.8) translateY(0.25rem)' },
+          '60%': { opacity: 1, transform: 'scale(1.04) translateY(0)' },
+          '100%': { opacity: 1, transform: 'scale(1) translateY(0)' },
+        },
+        'fade-in': {
+          '0%': { opacity: 0 },
+        },
+        'fade-in-up': {
+          '0%': { opacity: 0, transform: 'translateY(0.5rem)' },
+          '100%': { opacity: 1, transform: 'translateY(0)' },
+        },
+        'command-bar-out': {
+          from: { opacity: 1, transform: 'scale(1) translateY(0)' },
+          to: { opacity: 0, transform: 'scale(0.92) translateY(0.5rem)' },
+        },
+        'fade-out': {
+          to: { opacity: 0 },
+        },
+      },
+      animation: {
+        'pop-in': 'pop-in 0.3s cubic-bezier(0.34, 1.56, 0.64, 1) backwards',
+        'fade-in': 'fade-in 0.3s ease-out',
+        'fade-in-up': 'fade-in-up 0.3s ease-out',
+        'command-bar-out': 'command-bar-out 0.15s ease-in forwards',
+        'fade-out': 'fade-out 0.15s ease-in forwards',
+      },
+    },
+  },
+};