@leavepulse/ui 0.46.0 → 0.48.0

package/src/components/commandPalette.ts

@@ -0,0 +1,264 @@
+import { applyQueryFilters, parsePaletteQuery, type CommandSearchTerms, type HighlightPart, type SearchableCommand } from "./commandSearch"
+
+/*
+ * The parts of LpCommandPalette that are plain logic, kept out of the SFC so
+ * they can be tested without mounting a dialog.
+ */
+
+/** The fields of a command that decide whether the preview pane opens for it. */
+export interface PreviewableCommand {
+  preview?: string
+  excerpt?: string
+  noPreview?: boolean
+}
+
+/**
+ * Whether the pane has something to show for a row. `noPreview` on the row
+ * wins, then the app's `hasPreview`; without either, a row qualifies when the
+ * app supplied a `#preview` slot or the row carries text of its own.
+ */
+export function commandHasPreview<T extends PreviewableCommand>(
+  command: T | undefined,
+  options: { slot: boolean; hasPreview?: (command: T) => boolean },
+): boolean {
+  if (!command || command.noPreview) return false
+  if (options.hasPreview) return options.hasPreview(command)
+  return options.slot || !!(command.preview || command.excerpt)
+}
+
+/** One line of LpPaletteFacts: what it is, and what it is set to now. */
+export interface PaletteFact {
+  /** Text, or the preview slot's `highlight(text)` to mark the query. */
+  label: string | HighlightPart[]
+  /** Right-aligned value; a change rolls in rather than swapping. */
+  value?: string | number
+  /** A second, quieter line under the label. */
+  hint?: string | HighlightPart[]
+  icon?: string
+  /** A colour dot in place of the icon: a role colour, a status. */
+  color?: string
+  /** Marks the row that is in effect now: the current theme, the open tab. */
+  current?: boolean
+  /** Draw the value in the monospace face: ids, paths, versions. */
+  mono?: boolean
+}
+
+/** One tile of LpPaletteStats. */
+export interface PaletteStat {
+  label: string
+  /** A number counts to its new value; text rolls. */
+  value: number | string
+  /** Abbreviate a number: 1.2k, 3.4M. */
+  compact?: boolean
+  suffix?: string
+  format?: (value: number) => string
+}
+
+/** The fields of a command that let typing enter its mode. */
+export interface PrefixedCommand {
+  prefix?: string
+  children?: unknown
+  disabled?: boolean
+}
+
+/**
+ * The mode a query opens by its prefix, and the query left after it. Only a
+ * command with `children` and a non-empty `prefix` qualifies; letters match
+ * in any case, and the longest prefix wins, so "mr " and "m" can live side by
+ * side. Leading spaces are ignored: they are never what someone meant.
+ */
+export function matchModePrefix<T extends PrefixedCommand>(
+  query: string,
+  commands: readonly T[],
+): { command: T; rest: string } | null {
+  const typed = query.trimStart().toLowerCase()
+  let best: T | null = null
+  for (const command of commands) {
+    const prefix = command.prefix?.toLowerCase()
+    if (!prefix || !command.children || command.disabled || !typed.startsWith(prefix)) continue
+    if (!best || prefix.length > (best.prefix?.length ?? 0)) best = command
+  }
+  if (!best) return null
+  return { command: best, rest: query.trimStart().slice(best.prefix!.length) }
+}
+
+/** The fields of a command that make it a "search elsewhere" row. */
+export interface FallbackCommand extends SearchableCommand {
+  fallback?: boolean
+  hidden?: boolean
+}
+
+/**
+ * The fallback rows to show for a query, with their labels filled in. They
+ * appear only while positive words are typed, whatever those words are: the
+ * row offers to search somewhere else for them, so matching it against them
+ * would hide it exactly when it is needed. Exclusions and `in:` scopes still
+ * apply, to the row's own label, keywords and group. `{query}` in the label
+ * becomes the positive words, without the operators.
+ */
+export function fallbackRows<T extends FallbackCommand>(
+  items: readonly T[],
+  raw: string,
+): { command: T; label: string }[] {
+  const parsed = parsePaletteQuery(raw.trim())
+  if (!parsed.text) return []
+  return applyQueryFilters(
+    items.filter((c) => c.fallback),
+    parsed,
+  ).map((command) => ({ command, label: command.label.split("{query}").join(parsed.text) }))
+}
+
+/**
+ * A remembered pick that is not a root command: one chosen inside a mode, or
+ * a result a search fetched. It keeps what the row needs to be drawn again
+ * and where it was found, so the palette can find the live command next time
+ * (`path` through static children, or the app's `resolveRecent`), and fall
+ * back to its `href` when neither can.
+ */
+export interface RecentEntry {
+  id: string
+  label: string
+  description?: string
+  icon?: string
+  image?: string | { src?: string | null; alt?: string; fallback?: string; icon?: string; shape?: "circle" | "soft" | "square" }
+  href?: string
+  /** Ids of the modes it was picked in, outermost first. */
+  path: string[]
+  /** The command's `recentData`, kept as given for `resolveRecent`. */
+  data?: unknown
+}
+
+/** A stored history item: a root command id (the old format), or an entry. */
+export type RecentItem = string | RecentEntry
+
+/** The fields of a command a history entry is built from and resolved to. */
+export interface RecentSource {
+  id: string
+  label: string
+  description?: string
+  icon?: string
+  image?: RecentEntry["image"]
+  href?: string
+  recentData?: unknown
+  disabled?: boolean
+  children?: unknown
+}
+
+function isEntry(value: unknown): value is RecentEntry {
+  if (!value || typeof value !== "object") return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v.id === "string"
+    && typeof v.label === "string"
+    && Array.isArray(v.path)
+    && v.path.every((step) => typeof step === "string")
+  )
+}
+
+/** Stored history, with anything malformed dropped rather than trusted. */
+export function readRecent(stored: unknown): RecentItem[] {
+  if (!Array.isArray(stored)) return []
+  return stored.filter((v): v is RecentItem => typeof v === "string" || isEntry(v))
+}
+
+function recentKey(item: RecentItem): string {
+  return typeof item === "string" ? item : [...item.path, item.id].join("\u0000")
+}
+
+/**
+ * The history item for a pick. A root pick stays a bare id, the format older
+ * versions wrote and still read; anything deeper becomes an entry with only
+ * the fields that survive JSON.
+ */
+export function toRecentItem(command: RecentSource, path: readonly string[]): RecentItem {
+  if (!path.length) return command.id
+  const entry: RecentEntry = { id: command.id, label: command.label, path: [...path] }
+  if (command.description) entry.description = command.description
+  if (command.icon) entry.icon = command.icon
+  if (typeof command.image === "string") entry.image = command.image
+  else if (command.image) {
+    const { src, alt, fallback, icon, shape } = command.image
+    entry.image = { src, alt, fallback, icon, shape }
+  }
+  if (command.href) entry.href = command.href
+  if (command.recentData !== undefined) entry.data = command.recentData
+  return entry
+}
+
+/** The history with `item` first and any earlier copy of it dropped. */
+export function pushRecent(list: readonly RecentItem[], item: RecentItem, keep: number): RecentItem[] {
+  const key = recentKey(item)
+  return [item, ...list.filter((v) => recentKey(v) !== key)].slice(0, keep)
+}
+
+/**
+ * The live commands a history stands for, newest first. A bare id is looked
+ * up among the root commands; an entry is followed down its path through
+ * static children, then offered to `resolve` (for results a fetcher found),
+ * and last rebuilt from its own fields when it has an `href` to follow.
+ * Whatever none of these can find is skipped, so a stored history never
+ * resurrects something that cannot run.
+ */
+export function resolveRecentItems<T extends RecentSource>(
+  items: readonly RecentItem[],
+  commands: readonly T[],
+  options: { limit: number; resolve?: (entry: RecentEntry) => T | null | undefined; fromEntry: (entry: RecentEntry) => T },
+): { command: T; path: string[] }[] {
+  const out: { command: T; path: string[] }[] = []
+  const seen = new Set<string>()
+  for (const item of items) {
+    if (out.length >= options.limit) break
+    const key = recentKey(item)
+    if (seen.has(key)) continue
+    const found = typeof item === "string" ? commands.find((c) => c.id === item) : findEntry(item, commands, options)
+    if (!found || found.disabled || found.children) continue
+    seen.add(key)
+    out.push({ command: found, path: typeof item === "string" ? [] : [...item.path] })
+  }
+  return out
+}
+
+function findEntry<T extends RecentSource>(
+  entry: RecentEntry,
+  commands: readonly T[],
+  options: { resolve?: (entry: RecentEntry) => T | null | undefined; fromEntry: (entry: RecentEntry) => T },
+): T | undefined {
+  let level: readonly T[] | null = commands
+  for (const step of entry.path) {
+    const mode: T | undefined = level?.find((c) => c.id === step)
+    level = mode && Array.isArray(mode.children) ? (mode.children as T[]) : null
+  }
+  const live = level?.find((c) => c.id === entry.id)
+  if (live) return live
+  const resolved = options.resolve?.(entry)
+  if (resolved) return resolved
+  return entry.href ? options.fromEntry(entry) : undefined
+}
+
+/**
+ * Whether a recent row survives the operators typed so far. Recent rows show
+ * while no positive words are typed, so "-theme" or "in:recent" filters them
+ * like any other row; an `in:` scope matches the row's own group or the
+ * Recent heading it sits under.
+ */
+export function recentVisible(command: SearchableCommand, terms: CommandSearchTerms, recentLabel: string): boolean {
+  if (!applyQueryFilters([{ ...command, group: undefined }], { ...terms, groups: [] }).length) return false
+  return terms.groups.every((term) =>
+    [command.group, recentLabel].some((group) => group?.toLowerCase().includes(term)),
+  )
+}
+
+/**
+ * The name a mode's chip shows. `modeLabel` when given; otherwise the label,
+ * with a `{query}` placeholder and the quotes around it taken out, since the
+ * words it stood for are in the box now ("Search mods for "{query}"" reads
+ * "Search mods").
+ */
+export function modeChipLabel(command: { label: string; modeLabel?: string }): string {
+  if (command.modeLabel) return command.modeLabel
+  if (!command.label.includes("{query}")) return command.label
+  return command.label
+    .replace(/\s*["'“”«»]?\{query\}["'“”«»]?/g, "")
+    .replace(/\s+(for|in|on|:)$/i, "")
+    .trim()
+}

package/src/components/commandSearch.ts

@@ -79,3 +79,82 @@ export function rankCommandItems<T extends SearchableCommand>(items: T[], terms:
     .sort((a, b) => b.score - a.score || a.command.label.localeCompare(b.command.label))
     .map((entry) => entry.command)
 }
+
+/**
+ * A query as a fetcher receives it. `text` is what a remote search should be
+ * sent: the positive words and phrases, in the case they were typed, without
+ * the operators a server would not understand. The operators come alongside
+ * as data, so a provider that can scope or exclude on the server may.
+ */
+export interface PaletteQuery extends CommandSearchTerms {
+  /** The box as typed, operators and all. */
+  raw: string
+  /** Positive terms joined by spaces, case kept, quotes dropped. */
+  text: string
+}
+
+export function parsePaletteQuery(raw: string): PaletteQuery {
+  const terms = parseCommandQuery(raw)
+  const words: string[] = []
+  QUERY_TOKEN.lastIndex = 0
+  for (let match; (match = QUERY_TOKEN.exec(raw)); ) {
+    const text = (match[3] ?? match[4] ?? "").trim()
+    if (text && !match[1] && !match[2]) words.push(text)
+  }
+  return { ...terms, raw, text: words.join(" ") }
+}
+
+/**
+ * The operators applied to results someone else matched: a server answered
+ * the positive words, and `-word` and `in:group` still have to hold for what
+ * it sent back. Positive terms are not re-checked here; the server may match
+ * word forms the text does not contain.
+ */
+export function applyQueryFilters<T extends SearchableCommand>(items: T[], terms: CommandSearchTerms): T[] {
+  if (!terms.exclude.length && !terms.groups.length) return items
+  return items.filter((command) => {
+    const group = command.group?.toLowerCase() ?? ""
+    return !terms.exclude.some((term) => matches(command, term)) && terms.groups.every((term) => group.includes(term))
+  })
+}
+
+/** A run of text, and whether it matched the query. */
+export interface HighlightPart {
+  text: string
+  hit: boolean
+}
+
+/**
+ * Text split around the terms that matched, for <mark> without v-html. Terms
+ * shorter than two characters are skipped (one letter would mark half the
+ * text), longer ones win where two start at the same place, and case is
+ * ignored. Pass positive terms only: an excluded word is never a match.
+ */
+export function highlightParts(value: string, terms: readonly string[]): HighlightPart[] {
+  const sorted = [...new Set(terms.map((t) => t.toLowerCase()).filter((t) => t.length >= 2))].sort(
+    (a, b) => b.length - a.length,
+  )
+  if (!value || sorted.length === 0) return value ? [{ text: value, hit: false }] : []
+  const lower = value.toLowerCase()
+  const parts: HighlightPart[] = []
+  let i = 0
+  while (i < value.length) {
+    let at = -1
+    let term = ""
+    for (const t of sorted) {
+      const found = lower.indexOf(t, i)
+      if (found !== -1 && (at === -1 || found < at || (found === at && t.length > term.length))) {
+        at = found
+        term = t
+      }
+    }
+    if (at === -1) {
+      parts.push({ text: value.slice(i), hit: false })
+      break
+    }
+    if (at > i) parts.push({ text: value.slice(i, at), hit: false })
+    parts.push({ text: value.slice(at, at + term.length), hit: true })
+    i = at + term.length
+  }
+  return parts
+}

package/src/components/keys.ts

@@ -0,0 +1,13 @@
+/*
+ * How a written combo splits into caps. One key per "+", except a "+" that is
+ * the key itself: "Ctrl++" is Ctrl and plus, not Ctrl and two blanks. Spaces
+ * separate the steps of a sequence: "G I" reads "G then I".
+ */
+export function comboKeys(chord: string): string[] {
+  return chord.split(/\+(?!$)/)
+}
+
+export function comboSteps(combo: string): string[][] {
+  const trimmed = combo.trim()
+  return trimmed ? trimmed.split(/\s+/).map(comboKeys) : []
+}

package/src/components/videoBackdrop.ts

@@ -0,0 +1,73 @@
+/*
+ * The parts of LpVideoBackdrop that are plain arithmetic, kept out of the SFC
+ * so they can be tested without a media element.
+ */
+
+/** The stretch of a clip that loops, and how long two passes overlap at the seam. */
+export interface LoopPlan {
+  /** Where every pass starts, in seconds of media time. */
+  from: number
+  /** Where every pass ends, in seconds of media time. */
+  to: number
+  /** Media seconds over which the next pass fades in over the ending one; 0 cuts. */
+  fade: number
+}
+
+/**
+ * The loop a backdrop plays, from what was asked and what the clip has.
+ *
+ * `start` and `end` are clamped into the clip and put in order; a stretch
+ * shorter than `minLength` is widened from its start (or, at the clip's end,
+ * backwards), since a loop of a few frames reads as a flicker. The overlap
+ * is at most half the stretch: a seam longer than that would have the next
+ * pass begin before the current one had shown anything of its own.
+ */
+export function planLoop(
+  duration: number,
+  options: { start?: number; end?: number; crossfade?: number; minLength?: number } = {},
+): LoopPlan {
+  if (!Number.isFinite(duration) || duration <= 0) return { from: 0, to: 0, fade: 0 }
+  const clamp = (value: number) => Math.min(duration, Math.max(0, value))
+  let from = clamp(options.start ?? 0)
+  let to = clamp(options.end ?? duration)
+  if (to < from) [from, to] = [to, from]
+  const minLength = Math.min(duration, Math.max(0, options.minLength ?? 0.5))
+  if (to - from < minLength) {
+    to = Math.min(duration, from + minLength)
+    from = Math.max(0, to - minLength)
+  }
+  const fade = Math.min(Math.max(0, options.crossfade ?? 0), (to - from) / 2)
+  return { from, to, fade }
+}
+
+/** Whether the pass at `time` has reached the point where the next one must begin. */
+export function seamReached(plan: LoopPlan, time: number): boolean {
+  return plan.to > plan.from && time >= plan.to - plan.fade
+}
+
+/**
+ * How far the incoming pass is through the seam, 0 to 1, from its own media
+ * time: it starts at `from` and is fully in once it has played `fade` seconds.
+ * Measured on the media clock rather than the wall clock, so the fade keeps
+ * pace with a playback rate and holds still while playback stalls.
+ */
+export function seamProgress(plan: LoopPlan, incomingTime: number): number {
+  if (plan.fade <= 0) return 1
+  return Math.min(1, Math.max(0, (incomingTime - plan.from) / plan.fade))
+}
+
+/** Whether the whole clip loops with nothing cut and no overlap, which the media element does natively. */
+export function isNativeLoop(plan: LoopPlan, duration: number): boolean {
+  return plan.fade === 0 && plan.from === 0 && plan.to >= duration
+}
+
+/** "1:05", "0:07.5": a position on a clip as a range slider labels it. */
+export function formatClipTime(seconds: number, precise = false): string {
+  const safe = Math.max(0, Number.isFinite(seconds) ? seconds : 0)
+  const minutes = Math.floor(safe / 60)
+  const rest = safe - minutes * 60
+  const whole = Math.floor(rest)
+  const tenth = Math.floor((rest - whole) * 10)
+  const secs = String(whole).padStart(2, "0")
+  return precise && tenth ? `${minutes}:${secs}.${tenth}` : `${minutes}:${secs}`
+}

package/src/index.ts

@@ -71,9 +71,18 @@ export {
 } from "./components/color"
 export type { ColorFormat, Hsv, Rgb } from "./components/color"
 export { default as LpCommandPalette } from "./components/LpCommandPalette.vue"
-export type { Command, PaletteLabels } from "./components/LpCommandPalette.vue"
-export { parseCommandQuery, rankCommandItems } from "./components/commandSearch"
-export type { CommandSearchTerms, SearchableCommand } from "./components/commandSearch"
+export type { Command, CommandFetcher, CommandImage, PaletteLabels } from "./components/LpCommandPalette.vue"
+export { applyQueryFilters, highlightParts, parseCommandQuery, parsePaletteQuery, rankCommandItems } from "./components/commandSearch"
+export { commandHasPreview, pushRecent, readRecent, toRecentItem } from "./components/commandPalette"
+export type { PaletteFact, PaletteStat, PreviewableCommand, RecentEntry, RecentItem } from "./components/commandPalette"
+export { default as LpPalettePreview } from "./components/LpPalettePreview.vue"
+export { default as LpPaletteHeader } from "./components/LpPaletteHeader.vue"
+export { default as LpPaletteFacts } from "./components/LpPaletteFacts.vue"
+export { default as LpPaletteStats } from "./components/LpPaletteStats.vue"
+export { default as LpPaletteSwatches } from "./components/LpPaletteSwatches.vue"
+export { default as LpKeys } from "./components/LpKeys.vue"
+export { comboKeys, comboSteps } from "./components/keys"
+export type { CommandSearchTerms, HighlightPart, PaletteQuery, SearchableCommand } from "./components/commandSearch"
 export { default as LpConfirmDialog } from "./components/LpConfirmDialog.vue"
 export type { ConfirmLabels } from "./components/LpConfirmDialog.vue"
 export { default as LpConfirmHost } from "./components/LpConfirmHost.vue"
@@ -171,6 +180,10 @@ export { default as LpSidebar } from "./components/LpSidebar.vue"
 export type { SidebarItem, SidebarSection } from "./components/LpSidebar.vue"
 export { default as LpSkeleton } from "./components/LpSkeleton.vue"
 export { default as LpSlider } from "./components/LpSlider.vue"
+export { default as LpRangeSlider } from "./components/LpRangeSlider.vue"
+export { default as LpVideoBackdrop } from "./components/LpVideoBackdrop.vue"
+export { formatClipTime, isNativeLoop, planLoop, seamProgress, seamReached } from "./components/videoBackdrop"
+export type { LoopPlan } from "./components/videoBackdrop"
 export { default as LpSparkline } from "./components/LpSparkline.vue"
 export { default as LpStat } from "./components/LpStat.vue"
 export { default as LpStepper } from "./components/LpStepper.vue"