@leavepulse/ui 0.37.11 → 0.38.0

package/src/components/LpCommandPalette.vue

@@ -6,9 +6,11 @@
  * arrows move the highlight — the pattern the LeavePulse frontend palette uses.
  *
  * Presentation-only and data-agnostic: the consumer supplies `commands` (a
- * composable can assemble them from routes/docs/API). Scoring ranks label >
- * keywords > description; matches are highlighted; the active row scrolls into
- * view. Open state is v-model:open; a global ⌘K/Ctrl-K toggle is on by default.
+ * composable can assemble them from routes/docs/API). Every query word must
+ * hit, in any order; scoring ranks label > keywords > description > a typo in
+ * the label, with a keyboard-layout retry when nothing matches; matches are
+ * highlighted; the active row scrolls into view. Open state is v-model:open;
+ * a global ⌘K/Ctrl-K toggle is on by default.
  *
  * Three things a palette outgrows the moment it stops being a list of routes,
  * all of them here rather than in each app that hit the wall:
@@ -34,10 +36,11 @@ import {
   DialogRoot,
   DialogTitle,
 } from "reka-ui"
-import { computed, nextTick, ref, shallowRef, watch } from "vue"
+import { computed, nextTick, ref, shallowRef, useId, watch } from "vue"
 import LpIcon from "./LpIcon.vue"
 import LpScrollArea from "./LpScrollArea.vue"
 import { useAsyncTask } from "../composables/useAsyncTask"
+import { useClipboard } from "../composables/useClipboard"
 import { useHotkeys } from "../composables/useHotkeys"
 
 export interface Command {
@@ -45,6 +48,19 @@ export interface Command {
   label: string
   /** Second line under the label. */
   description?: string
+  /**
+   * A passage of the matched text, wrapped over several lines (clamped by
+   * `excerptLines`) instead of truncated to one. For results a server found
+   * inside long text — a docs section, a ticket, a message — where the reason
+   * the row matched is the part worth reading before opening it.
+   */
+  excerpt?: string
+  /**
+   * Extra words to highlight besides the typed query. A server that matches
+   * word forms or typos knows which words actually matched; the query alone
+   * would leave those unmarked.
+   */
+  highlight?: string[]
   icon?: string
   /** Right-aligned hint, e.g. "⌘P". */
   shortcut?: string
@@ -77,6 +93,27 @@ export interface Command {
    * reopening and retyping.
    */
   keepOpen?: boolean
+  /**
+   * Where the command leads. The row renders as a real link, so Ctrl/⌘-click,
+   * Shift-click and middle-click open it the way the browser opens any link,
+   * and Ctrl/⌘+Enter opens it in a new tab from the keyboard. A plain pick
+   * still runs `onSelect` (a router push, say); without one it follows the
+   * link.
+   */
+  href?: string
+  /**
+   * Further things to do with this result besides opening it — copy its id,
+   * open it elsewhere, share it. Tab on the highlighted row lists them as a
+   * mode named after the row. A command with `href` gets "open in new tab"
+   * and "copy link" after its own.
+   */
+  actions?: Command[]
+  /**
+   * The whole text behind this result, for the preview pane (`previewPane`):
+   * the section a docs hit points into, the ticket body, the message. Line
+   * breaks are kept. Without it the pane shows the `excerpt`.
+   */
+  preview?: string
   onSelect?: () => void
 }
 
@@ -88,6 +125,19 @@ export interface PaletteLabels {
   /** Hint for leaving a mode, shown only while inside one. */
   back: string
   searching: string
+  /** Shown when `search` (or a fetching mode) threw. */
+  searchFailed: string
+  retry: string
+  /** The row that unfolds a group cut by `groupLimit`; `{count}` is how many are hidden. */
+  showMore: string
+  /** Footer hint for Tab while the highlighted row has actions. */
+  actions: string
+  openInNewTab: string
+  copyLink: string
+  /** Toast after "copy link"; empty for none. */
+  linkCopied: string
+  /** The preview pane when the highlighted row has nothing to show. */
+  noPreview: string
 }
 
 const props = withDefaults(
@@ -126,6 +176,29 @@ const props = withDefaults(
     resultsLabel?: string
     /** Footer hints and the mode chip, spelled out for translation. */
     labels?: Partial<PaletteLabels>
+    /** Lines an `excerpt` may wrap to before it is clamped. */
+    excerptLines?: number
+    /**
+     * Rows a group shows before folding the rest behind a "Show N more" row.
+     * One provider answering with thirty people would otherwise push every
+     * other group off the screen. 0 shows everything.
+     */
+    groupLimit?: number
+    /**
+     * When the query matches nothing, retry it as if typed in the other
+     * keyboard layout (QWERTY ↔ ЙЦУКЕН). Off for an app whose commands are
+     * meant to be typed in one layout only.
+     */
+    layoutFallback?: boolean
+    /**
+     * A pane beside the list showing the highlighted result in full — its
+     * `preview` text, or the `preview` slot. For palettes that search
+     * content rather than commands: the excerpt says why a row matched, the
+     * pane lets it be read without leaving the page. Opt-in and fixed while
+     * open, so the dialog does not change width as results come and go.
+     * Hidden below the md breakpoint, where there is no room beside the list.
+     */
+    previewPane?: boolean
   }>(),
   {
     placeholder: "Type a command or search…",
@@ -136,6 +209,10 @@ const props = withDefaults(
     recentLimit: 5,
     recentLabel: "Recent",
     resultsLabel: "Results",
+    excerptLines: 4,
+    groupLimit: 0,
+    layoutFallback: true,
+    previewPane: false,
   },
 )
 
@@ -145,6 +222,14 @@ const DEFAULT_LABELS: PaletteLabels = {
   close: "close",
   back: "back",
   searching: "Searching…",
+  searchFailed: "Search is unavailable right now.",
+  retry: "Retry",
+  showMore: "Show {count} more",
+  actions: "actions",
+  openInNewTab: "Open in new tab",
+  copyLink: "Copy link",
+  linkCopied: "Link copied",
+  noPreview: "No preview",
 }
 
 const text = computed<PaletteLabels>(() => ({ ...DEFAULT_LABELS, ...props.labels }))
@@ -161,6 +246,16 @@ const emit = defineEmits<{
 }>()
 
 const query = ref("")
+/*
+ * The input is a combobox over a listbox: focus never leaves the box, so the
+ * highlighted row has to be announced through aria-activedescendant — without
+ * it a screen reader hears the query and nothing as the arrows move.
+ */
+const listId = `lp-cmd-${useId()}`
+function optionId(index: number): string {
+  return `${listId}-${index}`
+}
+const activeId = computed(() => (flat.value.length ? optionId(selectedIndex.value) : undefined))
 const selectedIndex = ref(0)
 const inputRef = ref<HTMLInputElement | null>(null)
 const scrollRef = ref<{ viewportEl: HTMLElement | null } | null>(null)
@@ -185,6 +280,50 @@ const mode = computed<Command | null>(() => trail.value[trail.value.length - 1]
  */
 const modeItems = shallowRef<Command[]>([])
 
+const { copy } = useClipboard()
+
+function actionsOf(c: Command | undefined): Command[] {
+  if (!c || c.disabled || moreOf.has(c)) return []
+  const own = c.actions ?? []
+  const href = c.href
+  if (!href) return own
+  const link = new URL(href, window.location.href).href
+  return [
+    ...own,
+    {
+      id: `${c.id}:open-in-new-tab`,
+      label: text.value.openInNewTab,
+      icon: "lucide:external-link",
+      onSelect: () => window.open(href, "_blank", "noopener"),
+    },
+    {
+      id: `${c.id}:copy-link`,
+      label: text.value.copyLink,
+      icon: "lucide:link",
+      onSelect: () => void copy(link, { toast: text.value.linkCopied || false }),
+    },
+  ]
+}
+
+const selectedActions = computed(() => actionsOf(flat.value[selectedIndex.value]))
+
+/*
+ * Tab is free for this: the rows are out of the tab order and the box is the
+ * only field, so Tab otherwise just walks off to the dialog's edge. Without
+ * actions it keeps that default.
+ */
+function onTab(event: KeyboardEvent) {
+  if (event.shiftKey) return
+  const c = flat.value[selectedIndex.value]
+  const actions = selectedActions.value
+  if (!c || !actions.length) return
+  // The dialog's focus trap handles Tab too, and would hand focus to the
+  // mode chip this is about to render.
+  event.preventDefault()
+  event.stopPropagation()
+  enter({ id: `${c.id}:actions`, label: c.label, icon: c.icon, children: actions })
+}
+
 function enter(c: Command) {
   trail.value = [...trail.value, c]
   query.value = ""
@@ -241,9 +380,18 @@ function cancel() {
   task.cancel()
 }
 
+/*
+ * A provider that threw used to leave the list as if it had answered "nothing
+ * matches", which is a claim about the data the palette cannot make. A failure
+ * says so and offers the same request again. Aborts never land here: the task
+ * drops a superseded request before `fail` runs.
+ */
+const failed = ref(false)
+
 function refresh() {
   cancel()
   found.value = []
+  failed.value = false
   const run = fetcher()
   if (!run) return
   const q = query.value.trim()
@@ -252,11 +400,15 @@ function refresh() {
   // not — ⌘K would fire a request at every open.
   const inMode = mode.value !== null
   if (!inMode && q.length < Math.max(1, props.minChars)) return
-  // Abort or a failing provider: the static commands still stand.
+  // A failing provider: the static commands still stand, with a line saying
+  // that the rest could not be fetched.
   task.run((signal) => run(q, signal), {
     delay: props.debounce,
     apply: (hits) => (found.value = hits),
-    fail: () => (found.value = []),
+    fail: () => {
+      found.value = []
+      failed.value = true
+    },
   })
 }
 
@@ -269,26 +421,98 @@ function refresh() {
  */
 const source = computed<Command[]>(() => (mode.value ? modeItems.value : props.commands))
 
-// No query → everything (grouped). With a query, score by where it hits:
-// label > keywords > description, then alphabetical. Mirrors the app palette.
-const ranked = computed<Command[]>(() => {
-  const q = query.value.trim().toLowerCase()
-  // Empty query: show everything EXCEPT hidden commands (they only surface once
-  // typed). With a query, hidden commands rank like any other.
-  if (!q) return source.value.filter((c) => !c.hidden)
-  return source.value
-    .map((c) => {
-      const label = c.label.toLowerCase().includes(q)
-      const kw = (c.keywords ?? []).some((k) => k.toLowerCase().includes(q))
-      const desc = c.description?.toLowerCase().includes(q) ?? false
-      const score = (label ? 4 : 0) + (kw ? 3 : 0) + (desc ? 2 : 0)
-      return { c, score }
-    })
+/*
+ * Keyboard layouts typed through each other: the query "cthdth" is "сервер"
+ * typed with the wrong layout on. Only the QWERTY ↔ ЙЦУКЕН pair is mapped —
+ * the one bilingual setup common enough to be worth a table — and it is a
+ * fallback, tried only when the query as typed matches nothing.
+ */
+const LATIN = "qwertyuiop[]asdfghjkl;'zxcvbnm,.`"
+const CYRILLIC = "йцукенгшщзхъфывапролджэячсмитьбюё"
+const SWAP = new Map<string, string>()
+for (let i = 0; i < LATIN.length; i++) {
+  SWAP.set(LATIN[i]!, CYRILLIC[i]!)
+  SWAP.set(CYRILLIC[i]!, LATIN[i]!)
+}
+
+function swapLayout(term: string): string {
+  return [...term].map((ch) => SWAP.get(ch) ?? ch).join("")
+}
+
+/** Damerau-Levenshtein distance, giving up past 1: all a typo check needs. */
+function withinOne(a: string, b: string): boolean {
+  if (Math.abs(a.length - b.length) > 1) return false
+  let i = 0
+  while (i < a.length && i < b.length && a[i] === b[i]) i++
+  if (i === a.length || i === b.length) return true
+  const rest = (x: number, y: number) => a.slice(i + x) === b.slice(i + y)
+  return rest(1, 1) || rest(1, 0) || rest(0, 1) || (a[i] === b[i + 1] && a[i + 1] === b[i] && rest(2, 2))
+}
+
+/*
+ * A typo in a word long enough to have one: a slip in a three-letter word
+ * makes it a different word. Compared against the word and its start, so
+ * "deplyo" finds "deploy" and "deployment" alike.
+ */
+const TYPO_MIN = 5
+function nearWord(term: string, label: string): boolean {
+  if (term.length < TYPO_MIN) return false
+  return label
+    .split(/[^\p{L}\p{N}]+/u)
+    .some((word) => withinOne(term, word) || (word.length > term.length && withinOne(term, word.slice(0, term.length))))
+}
+
+/*
+ * Every word of the query has to land somewhere, in any order: "branch deploy"
+ * finds "Deploy current branch". Per word, label > keywords > description,
+ * the same weights the palette always had; a typo match ranks below all of
+ * them, so an exact hit is never outranked by a near one.
+ */
+function score(c: Command, terms: string[]): number {
+  const label = c.label.toLowerCase()
+  const keywords = (c.keywords ?? []).map((k) => k.toLowerCase())
+  const description = c.description?.toLowerCase() ?? ""
+  let total = 0
+  for (const term of terms) {
+    let hit =
+      (label.includes(term) ? 4 : 0) +
+      (keywords.some((k) => k.includes(term)) ? 3 : 0) +
+      (description.includes(term) ? 2 : 0)
+    if (!hit && nearWord(term, label)) hit = 1
+    if (!hit) return 0
+    total += hit
+  }
+  return total
+}
+
+function rank(items: Command[], terms: string[]): Command[] {
+  return items
+    .map((c) => ({ c, score: score(c, terms) }))
     .filter((e) => e.score > 0)
     .sort((a, b) => b.score - a.score || a.c.label.localeCompare(b.c.label))
     .map((e) => e.c)
+}
+
+const typedTerms = computed(() => query.value.trim().toLowerCase().split(/\s+/).filter(Boolean))
+
+/*
+ * The local match and the terms it matched with — the swapped ones when the
+ * layout fallback is what found it, so the highlight marks what actually hit.
+ */
+const local = computed<{ items: Command[]; terms: string[] }>(() => {
+  const terms = typedTerms.value
+  // Empty query: show everything EXCEPT hidden commands (they only surface once
+  // typed). With a query, hidden commands rank like any other.
+  if (!terms.length) return { items: source.value.filter((c) => !c.hidden), terms }
+  const items = rank(source.value, terms)
+  if (items.length || !props.layoutFallback) return { items, terms }
+  const swapped = terms.map(swapLayout)
+  const other = rank(source.value, swapped)
+  return other.length ? { items: other, terms: swapped } : { items, terms }
 })
 
+const ranked = computed<Command[]>(() => local.value.items)
+
 /*
  * Fetched results sit under their own heading unless they brought a group of
  * their own, so they never look like they were part of the static list. An id
@@ -339,11 +563,64 @@ const grouped = computed<{ name: string; items: Command[] }[]>(() => {
   // the same row on screen twice with nothing to tell them apart.
   for (const c of ranked.value) if (!recent.includes(c)) push(c, c.group ?? "")
   for (const c of fetched.value) push(c, c.group ?? "")
-  return order.map((name) => ({ name, items: map.get(name)! }))
+  return order.map((name) => ({ name, items: folded(name, map.get(name)!) }))
 })
 
+/*
+ * Groups unfolded by their "Show more" row. Reset with the list it applies
+ * to: a new query or another mode is a new list, and its groups start folded.
+ */
+const expanded = ref(new Set<string>())
+const moreOf = new WeakMap<Command, string>()
+
+/*
+ * Folding hides at least two rows: a "Show 1 more" row takes the same space
+ * as the row it hides.
+ */
+function folded(name: string, items: Command[]): Command[] {
+  const limit = props.groupLimit
+  if (!limit || items.length <= limit + 1 || expanded.value.has(name)) return items
+  const more: Command = {
+    id: `lp-cmd-more:${name}`,
+    label: text.value.showMore.replace("{count}", String(items.length - limit)),
+    icon: "lucide:chevron-down",
+    keepOpen: true,
+  }
+  moreOf.set(more, name)
+  return [...items.slice(0, limit), more]
+}
+
 // Flat list in render order — what arrow keys walk through.
 const flat = computed(() => grouped.value.flatMap((g) => g.items))
+
+defineSlots<{
+  /** Body of the preview pane for the highlighted command. */
+  preview?: (props: { command: Command }) => unknown
+}>()
+
+const active = computed<Command | undefined>(() => {
+  const c = flat.value[selectedIndex.value]
+  return c && !moreOf.has(c) ? c : undefined
+})
+const previewRef = ref<{ viewportEl: HTMLElement | null } | null>(null)
+
+/*
+ * A preview is opened for the match, so the pane lands on it: the first
+ * highlighted word is brought into view, and a result without one starts
+ * from the top rather than wherever the previous result was scrolled to.
+ */
+watch(
+  () => active.value?.id,
+  async () => {
+    if (!props.previewPane) return
+    await nextTick()
+    const viewport = previewRef.value?.viewportEl
+    if (!viewport) return
+    const mark = viewport.querySelector("mark")
+    if (mark) mark.scrollIntoView({ block: "center" })
+    else viewport.scrollTop = 0
+  },
+)
 function flatIndexOf(c: Command): number {
   return flat.value.indexOf(c)
 }
@@ -355,8 +632,8 @@ interface Part {
   text: string
   hit: boolean
 }
-function highlight(value: string): Part[] {
-  const terms = [...new Set(query.value.toLowerCase().trim().split(/\s+/).filter((t) => t.length >= 2))].sort(
+function highlight(value: string, extra: string[] = []): Part[] {
+  const terms = [...new Set([...local.value.terms, ...extra.map((t) => t.toLowerCase())].filter((t) => t.length >= 2))].sort(
     (a, b) => b.length - a.length,
   )
   if (!value || terms.length === 0) return value ? [{ text: value, hit: false }] : []
@@ -389,6 +666,9 @@ watch(query, () => {
   selectedIndex.value = 0
   refresh()
 })
+watch([query, trail, () => props.open], () => {
+  expanded.value = new Set()
+})
 watch(
   () => flat.value.length,
   (len) => {
@@ -415,14 +695,46 @@ function moveUp() {
   const len = flat.value.length
   if (len) selectedIndex.value = (selectedIndex.value - 1 + len) % len
 }
-function runSelected() {
-  run(flat.value[selectedIndex.value])
+function runSelected(event?: KeyboardEvent) {
+  const c = flat.value[selectedIndex.value]
+  if (c?.href && !c.disabled && (event?.ctrlKey || event?.metaKey)) {
+    openInNewTab(c)
+    return
+  }
+  run(c)
+}
+
+function openInNewTab(c: Command) {
+  if (!c.href) return
+  window.open(c.href, "_blank", "noopener")
+  emit("run", c.id, c)
+  emit("update:open", false)
+}
+
+/*
+ * A modified click on a link is the browser's to handle: it opens a tab or a
+ * window and this page stays where it is, so the palette neither runs the
+ * command nor closes. Only the plain click is taken over.
+ */
+function onRowClick(event: MouseEvent, c: Command) {
+  if (c.href && (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey || event.button !== 0)) return
+  event.preventDefault()
+  run(c)
 }
 
 function run(c: Command | undefined) {
   if (!c || c.disabled) return
+  // The highlight stays on the same index, which is now the first row that
+  // was hidden: the arrows carry on from where the fold was.
+  const group = moreOf.get(c)
+  if (group !== undefined) {
+    expanded.value = new Set([...expanded.value, group])
+    inputRef.value?.focus()
+    return
+  }
   emit("select", c)
   c.onSelect?.()
+  if (!c.onSelect && c.href && !c.children) window.location.assign(c.href)
   // A command with children drills in instead of closing, and is navigation
   // rather than a pick — so it stays out of the recency history.
   if (c.children) {
@@ -477,6 +789,7 @@ watch(
     trail.value = []
     modeItems.value = []
     found.value = []
+    failed.value = false
     if (o) {
       await nextTick()
       inputRef.value?.focus()
@@ -509,7 +822,8 @@ useHotkeys(() =>
         class="lp-scrim fixed inset-0 z-(--z-overlay) data-[state=open]:animate-[fade-in_150ms_ease] data-[state=closed]:animate-[fade-out_130ms_ease]"
       />
       <DialogContent
-        class="fixed left-1/2 top-[12vh] z-(--z-modal) flex max-h-[76vh] w-[min(92vw,40rem)] -translate-x-1/2 flex-col overflow-hidden rounded-card border border-line bg-surface-raised shadow-panel outline-none data-[state=open]:animate-[pop-in_160ms_var(--ease-emphasized)] data-[state=closed]:animate-[pop-out_130ms_ease]"
+        class="fixed left-1/2 top-[12vh] z-(--z-modal) flex max-h-[76vh] w-[min(92vw,40rem)] -translate-x-1/2 flex-col overflow-hidden rounded-card border border-line lp-glass-overlay shadow-panel outline-none data-[state=open]:animate-[pop-in_160ms_var(--ease-emphasized)] data-[state=closed]:animate-[pop-out_130ms_ease]"
+        :class="previewPane && 'md:h-[min(76vh,36rem)] md:w-[min(92vw,64rem)]'"
         @open-auto-focus.prevent
       >
         <DialogTitle class="sr-only">Command palette</DialogTitle>
@@ -544,6 +858,11 @@ useHotkeys(() =>
             ref="inputRef"
             v-model="query"
             type="text"
+            role="combobox"
+            aria-autocomplete="list"
+            aria-expanded="true"
+            :aria-controls="listId"
+            :aria-activedescendant="activeId"
             :placeholder="mode?.childPlaceholder ?? placeholder"
             class="h-12 min-w-0 flex-1 bg-transparent text-sm text-ink outline-none placeholder:text-muted"
             @keydown.down.prevent="moveDown"
@@ -551,63 +870,151 @@ useHotkeys(() =>
             @keydown.enter.prevent="runSelected"
             @keydown.backspace="onBackspace"
             @keydown.esc="onEscape"
+            @keydown.tab="onTab"
           />
           <kbd class="shrink-0 rounded border border-line px-1.5 py-0.5 text-[10px] text-muted">esc</kbd>
         </div>
 
         <!-- Results -->
-        <LpScrollArea ref="scrollRef" class="min-h-0 flex-1" content-class="p-2">
-          <!-- While a request is out there is nothing to say yet: "no results"
-               under a spinner reads as an answer, and it is not one. -->
-          <p v-if="flat.length === 0" class="px-2 py-10 text-center text-sm text-muted">
-            {{ searching ? text.searching : emptyText }}
-          </p>
-
-          <template v-for="group in grouped" :key="group.name">
+        <div class="flex min-h-0 flex-1">
+          <LpScrollArea ref="scrollRef" class="min-h-0 min-w-0 flex-1" content-class="p-2">
+            <!-- While a request is out there is nothing to say yet: "no results"
+                 under a spinner reads as an answer, and it is not one. -->
+            <p v-if="flat.length === 0 && !failed" class="px-2 py-10 text-center text-sm text-muted">
+              {{ searching ? text.searching : emptyText }}
+            </p>
+
+            <div :id="listId" role="listbox">
+              <div
+                v-for="(group, gi) in grouped"
+                :key="group.name"
+                role="group"
+                :aria-labelledby="group.name ? `${listId}-g${gi}` : undefined"
+              >
+                <div
+                  v-if="group.name"
+                  :id="`${listId}-g${gi}`"
+                  class="px-2 pb-1 pt-3 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted"
+                >
+                  {{ group.name }}
+                </div>
+                <!-- tabindex -1: the rows are reached with the arrows from the box,
+                     so Tab should not walk through every one of them. -->
+                <component
+                  :is="c.href ? 'a' : 'button'"
+                  v-for="c in group.items"
+                  :id="optionId(flatIndexOf(c))"
+                  :key="c.id"
+                  :href="c.disabled ? undefined : c.href"
+                  :type="c.href ? undefined : 'button'"
+                  role="option"
+                  tabindex="-1"
+                  :aria-selected="flatIndexOf(c) === selectedIndex"
+                  :aria-disabled="c.disabled || undefined"
+                  :data-cmd-index="flatIndexOf(c)"
+                  :disabled="c.href ? undefined : c.disabled"
+                  class="lp-cmd-item flex w-full gap-3 rounded-md px-2.5 py-2 text-left text-sm outline-none transition-colors duration-[var(--duration-fast)] disabled:pointer-events-none disabled:opacity-45 aria-disabled:pointer-events-none aria-disabled:opacity-45"
+                  :class="[
+                    c.excerpt ? 'items-start' : 'items-center',
+                    flatIndexOf(c) === selectedIndex
+                      ? 'bg-brand-soft text-brand'
+                      : moreOf.has(c)
+                        ? 'text-muted hover:bg-surface-soft/60'
+                        : 'text-ink hover:bg-surface-soft/60',
+                  ]"
+                  @click="onRowClick($event, c)"
+                  @pointerenter="selectedIndex = flatIndexOf(c)"
+                >
+                  <LpIcon v-if="c.icon" :name="c.icon" :size="16" class="shrink-0" :class="{ 'mt-0.5': c.excerpt }" />
+                  <span class="min-w-0 flex-1">
+                    <span class="block truncate font-medium">
+                      <template v-for="(p, pi) in highlight(c.label, c.highlight)" :key="`l${pi}`">
+                        <mark v-if="p.hit" class="rounded-xs bg-brand/25 text-ink">{{ p.text }}</mark>
+                        <template v-else>{{ p.text }}</template>
+                      </template>
+                    </span>
+                    <span v-if="c.description" class="mt-0.5 block truncate text-xs text-muted">
+                      <template v-for="(p, pi) in highlight(c.description, c.highlight)" :key="`d${pi}`">
+                        <mark v-if="p.hit" class="rounded-xs bg-brand/20 text-ink">{{ p.text }}</mark>
+                        <template v-else>{{ p.text }}</template>
+                      </template>
+                    </span>
+                    <!-- Wraps rather than truncates: a passage cut to one line
+                         stops before the part that explains the match. Ink, not
+                         brand, on the active row: a paragraph in accent colour is
+                         hard to read. -->
+                    <span
+                      v-if="c.excerpt"
+                      class="lp-cmd-excerpt mt-1 block text-[13px] leading-snug text-ink/80"
+                      :style="{ '-webkit-line-clamp': excerptLines }"
+                    >
+                      <template v-for="(p, pi) in highlight(c.excerpt, c.highlight)" :key="`e${pi}`">
+                        <mark v-if="p.hit" class="rounded-xs bg-brand/20 text-ink">{{ p.text }}</mark>
+                        <template v-else>{{ p.text }}</template>
+                      </template>
+                    </span>
+                  </span>
+                  <kbd v-if="c.shortcut" class="shrink-0 text-xs text-muted">{{ c.shortcut }}</kbd>
+                  <!-- Drills in rather than runs: worth saying before the click,
+                       since the two look identical otherwise. -->
+                  <LpIcon
+                    v-else-if="c.children"
+                    name="lucide:chevron-right"
+                    :size="14"
+                    class="shrink-0 text-muted"
+                  />
+                </component>
+              </div>
+            </div>
+            <!-- Below what was found: the static matches are still worth
+                 picking, and the failure is about the part that is missing. -->
             <div
-              v-if="group.name"
-              class="px-2 pb-1 pt-3 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted"
+              v-if="failed"
+              role="alert"
+              class="flex items-center justify-center gap-2 px-2 text-sm text-muted"
+              :class="flat.length ? 'pb-1 pt-3' : 'py-10'"
             >
-              {{ group.name }}
+              <LpIcon name="lucide:circle-alert" :size="15" class="shrink-0" />
+              <span>{{ text.searchFailed }}</span>
+              <button
+                type="button"
+                class="rounded-md px-1.5 py-0.5 font-medium text-brand outline-none transition-colors hover:bg-brand-soft focus-visible:ring-2 focus-visible:ring-ring"
+                @click="refresh(); inputRef?.focus()"
+              >
+                {{ text.retry }}
+              </button>
             </div>
-            <button
-              v-for="c in group.items"
-              :key="c.id"
-              type="button"
-              :data-cmd-index="flatIndexOf(c)"
-              :disabled="c.disabled"
-              class="lp-cmd-item flex w-full items-center gap-3 rounded-md px-2.5 py-2 text-left text-sm outline-none transition-colors duration-[var(--duration-fast)] disabled:pointer-events-none disabled:opacity-45"
-              :class="flatIndexOf(c) === selectedIndex ? 'bg-brand-soft text-brand' : 'text-ink hover:bg-surface-soft/60'"
-              @click="run(c)"
-              @pointerenter="selectedIndex = flatIndexOf(c)"
-            >
-              <LpIcon v-if="c.icon" :name="c.icon" :size="16" class="shrink-0" />
-              <span class="min-w-0 flex-1">
-                <span class="block truncate font-medium">
-                  <template v-for="(p, pi) in highlight(c.label)" :key="`l${pi}`">
-                    <mark v-if="p.hit" class="rounded-xs bg-brand/25 text-ink">{{ p.text }}</mark>
-                    <template v-else>{{ p.text }}</template>
-                  </template>
-                </span>
-                <span v-if="c.description" class="mt-0.5 block truncate text-xs text-muted">
-                  <template v-for="(p, pi) in highlight(c.description)" :key="`d${pi}`">
-                    <mark v-if="p.hit" class="rounded-xs bg-brand/20 text-ink">{{ p.text }}</mark>
-                    <template v-else>{{ p.text }}</template>
-                  </template>
-                </span>
-              </span>
-              <kbd v-if="c.shortcut" class="shrink-0 text-xs text-muted">{{ c.shortcut }}</kbd>
-              <!-- Drills in rather than runs: worth saying before the click,
-                   since the two look identical otherwise. -->
-              <LpIcon
-                v-else-if="c.children"
-                name="lucide:chevron-right"
-                :size="14"
-                class="shrink-0 text-muted"
-              />
-            </button>
-          </template>
-        </LpScrollArea>
+          </LpScrollArea>
+          <aside
+            v-if="previewPane"
+            class="hidden min-h-0 w-[56%] shrink-0 flex-col border-l border-line md:flex"
+          >
+            <LpScrollArea ref="previewRef" class="min-h-0 flex-1" content-class="px-5 py-4">
+              <template v-if="active">
+                <slot name="preview" :command="active">
+                  <div class="flex items-center gap-2 text-ink">
+                    <LpIcon v-if="active.icon" :name="active.icon" :size="16" class="shrink-0 text-muted" />
+                    <h3 class="min-w-0 text-base font-semibold">{{ active.label }}</h3>
+                  </div>
+                  <p v-if="active.description" class="mt-0.5 text-xs text-muted">{{ active.description }}</p>
+                  <p
+                    v-if="active.preview || active.excerpt"
+                    class="mt-3 whitespace-pre-line text-sm leading-relaxed text-ink/90"
+                  >
+                    <template
+                      v-for="(p, pi) in highlight(active.preview ?? active.excerpt ?? '', active.highlight)"
+                      :key="`p${pi}`"
+                    >
+                      <mark v-if="p.hit" class="rounded-xs bg-brand/25 text-ink">{{ p.text }}</mark>
+                      <template v-else>{{ p.text }}</template>
+                    </template>
+                  </p>
+                  <p v-else class="mt-3 text-sm text-muted">{{ text.noPreview }}</p>
+                </slot>
+              </template>
+            </LpScrollArea>
+          </aside>
+        </div>
 
         <!-- Footer hints -->
         <div
@@ -624,6 +1031,10 @@ useHotkeys(() =>
           </span>
           <!-- Only inside a mode: at the root Backspace just edits the query,
                and advertising it there would be a lie. -->
+          <span v-if="selectedActions.length" class="flex items-center gap-1">
+            <kbd class="rounded border border-line px-1 text-[10px]">tab</kbd>
+            {{ text.actions }}
+          </span>
           <span v-if="trail.length" class="flex items-center gap-1">
             <kbd class="rounded border border-line px-1 text-[10px]">⌫</kbd>
             {{ text.back }}
@@ -639,6 +1050,11 @@ useHotkeys(() =>
 </template>
 
 <style scoped>
+.lp-cmd-excerpt {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
 /* Each result eases in; honours reduced motion. */
 .lp-cmd-item {
   animation: lp-cmd-in 140ms ease-out both;