@bysivin/jumpbar 0.1.0 → 0.2.0

package/package.json

@@ -1,22 +1,37 @@
 {
   "name": "@bysivin/jumpbar",
-  "version": "0.1.0",
+  "version": "0.2.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",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./types/core.d.ts",
+      "import": "./dist/core.js",
+      "default": "./dist/core.js"
+    },
     "./tailwind": "./tailwind.cjs",
+    "./theme.css": "./theme.css",
     "./package.json": "./package.json"
   },
   "files": [
-    "src",
-    "!src/**/specs",
-    "tailwind.cjs"
+    "dist",
+    "types",
+    "tailwind.cjs",
+    "theme.css"
+  ],
+  "sideEffects": [
+    "*.css"
   ],
-  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
@@ -33,16 +48,24 @@
     "fuzzy-search"
   ],
   "scripts": {
+    "build": "vite build",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm build && pnpm test"
   },
   "peerDependencies": {
     "vue": "^3.4.0"
   },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@vitejs/plugin-vue": "^5.2.4",
     "@vue/test-utils": "^2.4.6",
     "jsdom": "^27.2.0",
+    "vite": "^6.4.4",
     "vitest": "3.0.5",
     "vue": "^3.5.12"
   }

package/tailwind.cjs

@@ -1,6 +1,28 @@
+const TOKENS = [
+  'background',
+  'foreground',
+  'muted-foreground',
+  'subtle-foreground',
+  'muted',
+  'subtle',
+  'border',
+  'ring',
+  'primary',
+  'primary-soft',
+  'overlay',
+  'online',
+  'busy',
+  'offline',
+];
+
 module.exports = {
   theme: {
     extend: {
+      colors: {
+        jumpbar: Object.fromEntries(
+          TOKENS.map(name => [name, `var(--jumpbar-${name})`])
+        ),
+      },
       keyframes: {
         'pop-in': {
           '0%': { opacity: 0, transform: 'scale(0.8) translateY(0.25rem)' },

package/theme.css

@@ -0,0 +1,33 @@
+:root {
+  --jumpbar-background: #ffffff;
+  --jumpbar-foreground: #1c2024;
+  --jumpbar-muted-foreground: #60646c;
+  --jumpbar-subtle-foreground: #80838d;
+  --jumpbar-muted: rgb(0 0 0 / 0.05);
+  --jumpbar-subtle: rgb(0 0 0 / 0.03);
+  --jumpbar-border: rgb(0 0 0 / 0.08);
+  --jumpbar-ring: rgb(0 0 0 / 0.14);
+  --jumpbar-primary: #0090ff;
+  --jumpbar-primary-soft: rgb(0 144 255 / 0.1);
+  --jumpbar-overlay: rgb(0 0 0 / 0.45);
+  --jumpbar-online: #12a594;
+  --jumpbar-busy: #ffba18;
+  --jumpbar-offline: #80838d;
+}
+
+.dark {
+  --jumpbar-background: #18191b;
+  --jumpbar-foreground: #edeef0;
+  --jumpbar-muted-foreground: #b0b4ba;
+  --jumpbar-subtle-foreground: #777b84;
+  --jumpbar-muted: rgb(255 255 255 / 0.07);
+  --jumpbar-subtle: rgb(255 255 255 / 0.04);
+  --jumpbar-border: rgb(255 255 255 / 0.1);
+  --jumpbar-ring: rgb(255 255 255 / 0.16);
+  --jumpbar-primary: #0090ff;
+  --jumpbar-primary-soft: rgb(0 144 255 / 0.15);
+  --jumpbar-overlay: rgb(0 0 0 / 0.6);
+  --jumpbar-online: #12a594;
+  --jumpbar-busy: #ffba18;
+  --jumpbar-offline: #777b84;
+}

package/types/core.d.ts

@@ -0,0 +1,76 @@
+export type Context = { scopes?: string[] } & Record<string, unknown>;
+
+export interface Avatar {
+  name: string;
+  src?: string | null;
+  status?: 'online' | 'busy' | 'offline';
+}
+
+export interface Item {
+  id: string;
+  title: string;
+  subtitle?: string;
+  section?: string;
+  icon?: string;
+  avatar?: Avatar;
+  badge?: string;
+  shortcut?: string[];
+  keywords?: string[];
+  scopes?: string[];
+  prefix?: string;
+  weight?: number;
+  place?: 'first' | 'last';
+  searchFromRoot?: boolean;
+  page?: boolean;
+  placeholder?: string;
+  parent?: string;
+  run?: (context: Context) => void;
+}
+
+export interface RankedItem extends Item {
+  parentTitle?: string;
+}
+
+export interface Section<T extends Item = RankedItem> {
+  section: string | null;
+  items: T[];
+}
+
+export interface Frecency {
+  record(id: string): void;
+  score(id: string): number;
+}
+
+export interface FrecencyStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+export interface FrecencyOptions {
+  storage: FrecencyStorage;
+  key: string;
+  now?: () => number;
+  limit?: number;
+}
+
+export interface RankOptions {
+  text?: string;
+  prefix?: string | null;
+  page?: string | null;
+  scopes?: string[];
+  frecency?: Pick<Frecency, 'score'>;
+}
+
+export function normalize(value: unknown): string;
+export function fuzzyScore(
+  query: string,
+  text: string,
+  options?: { subsequence?: boolean }
+): number;
+export function parseQuery(
+  input: string,
+  prefixes?: string[]
+): { prefix: string | null; text: string };
+export function createFrecency(options: FrecencyOptions): Frecency;
+export function rank(items: Item[], options: RankOptions): RankedItem[];
+export function groupBySection<T extends Item>(items: T[]): Section<T>[];

package/types/index.d.ts

@@ -0,0 +1,77 @@
+import type { ComputedRef, DefineComponent, Ref } from 'vue';
+import type { Context, Frecency, Item, RankedItem, Section } from './core';
+
+export * from './core';
+
+export interface Request {
+  query: string;
+  text: string;
+  prefix: string | null;
+  page: string | null;
+  context: Context;
+}
+
+export interface SearchRequest extends Request {
+  matches: number;
+  signal: AbortSignal;
+}
+
+export interface Source {
+  id: string;
+  minQuery?: number;
+  debounce?: number;
+  when?: (request: Request | SearchRequest) => boolean;
+  commands?: (request: Request) => Item[];
+  search?: (request: SearchRequest) => Promise<Item[]> | Item[];
+}
+
+export interface CommandBarOptions {
+  prefixes?: string[];
+  context?: () => Context;
+  frecency?: Frecency;
+  onSelect?: (item: Item) => void;
+  onClose?: () => void;
+  onError?: (error: unknown, source: Source) => void;
+  debounce?: number;
+  limit?: number;
+}
+
+export interface CommandBarInstance {
+  isOpen: Ref<boolean>;
+  query: Ref<string>;
+  page: ComputedRef<Item | null>;
+  pages: Ref<Item[]>;
+  visible: ComputedRef<RankedItem[]>;
+  sections: ComputedRef<Section[]>;
+  selectedIndex: Ref<number>;
+  selected: ComputedRef<RankedItem | null>;
+  isLoading: ComputedRef<boolean>;
+  open(options?: { page?: string | null; query?: string }): void;
+  close(): void;
+  toggle(): void;
+  back(): void;
+  select(item: Item | null | undefined): void;
+  setQuery(value: string): void;
+  moveSelection(delta: number): void;
+  register(source: Source): () => void;
+  configure(overrides: CommandBarOptions): void;
+  dispose(): void;
+}
+
+export function createCommandBar(options?: CommandBarOptions): CommandBarInstance;
+export function useCommandBar(): CommandBarInstance;
+
+export interface Hint {
+  keys: string[];
+  label: string;
+}
+
+export interface CommandBarProps {
+  placeholder?: string;
+  emptyText?: string;
+  scopeLabel?: string;
+  hints?: Hint[];
+  dir?: 'ltr' | 'rtl';
+}
+
+export const CommandBar: DefineComponent<CommandBarProps>;

package/src/core/frecency.js

@@ -1,41 +0,0 @@
-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

@@ -1,71 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -1,70 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -1,173 +0,0 @@
-<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>