@leavepulse/ui 0.70.1 → 0.71.0

package/src/components/uptimeBar.ts

@@ -0,0 +1,98 @@
+/*
+ * The arithmetic behind LpUptimeBar, kept pure so the corners are tested
+ * without a DOM: what share of the time was up, how that figure is printed,
+ * and how a slice's span reads in its tooltip.
+ */
+import { toEpoch } from "./timeSpan"
+
+export type UptimeStatus = "operational" | "degraded" | "down" | "maintenance" | "empty"
+
+export type UptimeMoment = Date | string | number
+
+/** Something that happened inside a slice: a restart, a deploy, an alert. */
+export interface UptimeEvent {
+  text: string
+  at?: UptimeMoment
+  status?: UptimeStatus
+}
+
+export interface UptimeSegment {
+  /** Health of this slice. `empty` renders a faded placeholder (no data). */
+  status: UptimeStatus
+  /** Optional rich tooltip body; falls back to a humanised status. */
+  label?: string
+  /** When the slice begins and ends. Shown in the tooltip, and weights the uptime figure. */
+  start?: UptimeMoment
+  end?: UptimeMoment
+  /**
+   * Time spent in each state inside the slice, in ms. With it the figure
+   * counts real time rather than slices (one bad minute in a day no longer
+   * costs the whole day), and the tooltip says how long each state lasted.
+   */
+  durations?: Partial<Record<Exclude<UptimeStatus, "empty">, number>>
+  /** What happened in the slice, a line each in the tooltip. */
+  events?: UptimeEvent[]
+}
+
+const UP: ReadonlySet<UptimeStatus> = new Set(["operational", "maintenance"])
+
+/** Worst first: the order a tooltip lists the time a slice spent in each state. */
+export const UPTIME_SEVERITY: readonly Exclude<UptimeStatus, "empty">[] = ["down", "degraded", "maintenance", "operational"]
+
+function span(seg: UptimeSegment): number | null {
+  if (seg.start === undefined || seg.end === undefined) return null
+  const ms = toEpoch(seg.end) - toEpoch(seg.start)
+  return Number.isFinite(ms) && ms > 0 ? ms : null
+}
+
+/**
+ * Percent of the tracked time that was up (operational or planned
+ * maintenance). Slices with `durations` count their real minutes; the rest
+ * count by their span when every one of them has a span, and as one slice
+ * each otherwise. Empty slices are not tracked. Null when nothing is.
+ */
+export function uptimeShare(segments: readonly UptimeSegment[]): number | null {
+  const tracked = segments.filter((s) => s.status !== "empty")
+  const bySpan = tracked.every((s) => s.durations || span(s) !== null)
+  let up = 0
+  let total = 0
+  for (const seg of tracked) {
+    if (seg.durations) {
+      for (const [status, ms] of Object.entries(seg.durations)) {
+        if (!ms || ms < 0) continue
+        total += ms
+        if (UP.has(status as UptimeStatus)) up += ms
+      }
+      continue
+    }
+    const weight = bySpan ? (span(seg) ?? 0) : 1
+    total += weight
+    if (UP.has(seg.status)) up += weight
+  }
+  return total > 0 ? (up / total) * 100 : null
+}
+
+/**
+ * The figure and its decimal places: trailing zeros trimmed (100, 99.9), and
+ * never rounded up to 100 while some time was down — 99.999 prints as 99.99,
+ * because "100%" over an outage reads as no outage at all.
+ */
+export function uptimeFigure(pct: number): { value: number; decimals: number } {
+  let value = Number(pct.toFixed(2))
+  if (pct < 100 && value >= 100) value = 99.99
+  const decimals = Number.isInteger(value) ? 0 : String(value).split(".")[1].length
+  return { value, decimals }
+}
+
+/** "26 Oct, 12:00 – 12:15", the date written once when both ends share a day. */
+export function uptimeRange(start: UptimeMoment, end: UptimeMoment | undefined, locale?: string): string {
+  const from = toEpoch(start)
+  if (!Number.isFinite(from)) return ""
+  const full = new Intl.DateTimeFormat(locale, { day: "numeric", month: "short", hour: "2-digit", minute: "2-digit" })
+  if (end === undefined) return full.format(from)
+  const to = toEpoch(end)
+  if (!Number.isFinite(to)) return full.format(from)
+  const sameDay = new Date(from).toDateString() === new Date(to).toDateString()
+  const tail = sameDay ? new Intl.DateTimeFormat(locale, { hour: "2-digit", minute: "2-digit" }) : full
+  return `${full.format(from)} – ${tail.format(to)}`
+}

package/src/composables/scroll.ts

@@ -26,6 +26,17 @@ export function scrollParent(el: Element | null | undefined, { axis = "y", self
   return null
 }
 
+/**
+ * Whether `el`'s scroller (or the page) has no more room to scroll down.
+ * `slack` absorbs the pixel a rounded-up scrollHeight can sit above the sum.
+ */
+export function atScrollEnd(el: Element | null | undefined, slack = 2): boolean {
+  if (!el) return false
+  const box = scrollParent(el) ?? (el.ownerDocument.scrollingElement as HTMLElement | null)
+  if (!box) return true
+  return box.scrollTop + box.clientHeight >= box.scrollHeight - slack
+}
+
 export interface ScrollToElementOptions {
   /** `nearest` scrolls only when the element is out of view. */
   block?: "nearest" | "center" | "start"

package/src/composables/useField.ts

@@ -9,6 +9,10 @@ import type { FieldNoticeOptions } from "./useFieldNotice"
  */
 export interface FieldContext {
   id: string
+  /** Human-readable name shared by controls and contextual commands. */
+  label?: string
+  hint?: string
+  error?: string
   /** Id of the visible label, for controls a `<label for>` cannot name (groups). */
   labelId?: string
   describedBy?: string
@@ -74,6 +78,9 @@ export function useFieldControl(
     return {
       id: state.id ?? field?.id,
       labelId: field?.labelId,
+      label: field?.label,
+      hint: field?.hint,
+      error: field?.error,
       describedBy: field?.describedBy,
       invalid: !!state.invalid || !!field?.invalid,
       required: !!state.required || !!field?.required,

package/src/composables/usePaletteCommands.ts

@@ -0,0 +1,220 @@
+import { computed, getCurrentInstance, h, inject, onMounted, onUpdated, onScopeDispose, provide, ref, shallowReactive, shallowRef, toValue, useId, type Component, type Directive, type InjectionKey, type MaybeRefOrGetter } from "vue"
+import type { Command } from "../components/LpCommandPalette.vue"
+import { provideField, useField } from "./useField"
+import { useLabels } from "./useLpConfig"
+
+export interface PaletteRegistration {
+  commands: () => readonly Command[]
+  priority: number
+  /** Discovered from a component rather than written by the app: an id clash numbers it instead of hiding it. */
+  automatic?: boolean
+}
+
+function uniqueCommands(commands: readonly Command[]): Command[] {
+  const found = new Map<string, Command>()
+  for (const command of commands) if (!found.has(command.id)) found.set(command.id, command)
+  return [...found.values()]
+}
+
+/*
+ * A discovered command is keyed by its scope and label, not by a generated id:
+ * `useId` follows mount order, so a pin or a recent entry on a field pointed at
+ * another field (or nothing) once the page mounted its parts differently. Two
+ * fields with one label in one scope would then share an id, so the second and
+ * later get `~2`, `~3` in mount order instead of the second vanishing. A manual
+ * definition with the same id still replaces the discovered one.
+ */
+function numbered(entries: readonly PaletteRegistration[]): Command[] {
+  const manual = new Set<string>()
+  const seen = new Map<string, number>()
+  const out: Command[] = []
+  for (const entry of entries) {
+    for (const command of entry.commands()) {
+      if (!entry.automatic) {
+        manual.add(command.id)
+        out.push(command)
+        continue
+      }
+      if (manual.has(command.id)) continue
+      const count = (seen.get(command.id) ?? 0) + 1
+      seen.set(command.id, count)
+      if (count === 1) {
+        out.push(command)
+        continue
+      }
+      const id = `${command.id}~${count}`
+      out.push({ ...command, id, actions: command.actions?.map(action => ({ ...action, id: action.id.replace(command.id, id) })) })
+    }
+  }
+  return uniqueCommands(out)
+}
+
+/** One registry per application/provider; never shared between SSR requests. */
+export function createPaletteRegistry() {
+  const entries = shallowReactive(new Map<symbol, PaletteRegistration>())
+  const commands = computed(() => numbered([...entries.values()].sort((a, b) => b.priority - a.priority)))
+  return {
+    commands,
+    register(entry: PaletteRegistration) {
+      const key = Symbol()
+      entries.set(key, entry)
+      return () => { entries.delete(key) }
+    },
+  }
+}
+export type PaletteRegistry = ReturnType<typeof createPaletteRegistry>
+
+export interface PaletteScope {
+  registry: PaletteRegistry
+  id: string
+  label: string
+  depth: number
+  enabled: boolean
+  discover: boolean
+}
+const SCOPE: InjectionKey<PaletteScope> = Symbol.for("lp-palette-scope")
+const BLOCKED: InjectionKey<boolean> = Symbol.for("lp-palette-blocked")
+const scopeElements = new WeakMap<Element, PaletteScope>()
+export function bindPaletteScopeElement(element: Element, scope: PaletteScope) { scopeElements.set(element, scope) }
+export const usePaletteScope = () => inject(SCOPE, null)
+export const providePaletteScope = (scope: PaletteScope) => provide(SCOPE, scope)
+/** Preview controls and compound controls must not discover their own implementation. */
+export function suppressPaletteDiscovery() { provide(BLOCKED, true) }
+
+export function usePaletteCommands(commands: MaybeRefOrGetter<readonly Command[]>, options: { automatic?: boolean; scope?: PaletteScope } = {}) {
+  const scope = options.scope ?? usePaletteScope()
+  const blocked = inject(BLOCKED, false)
+  if (!scope || blocked) return
+  const unregister = scope.registry.register({
+    automatic: options.automatic,
+    priority: scope.depth * 100 + (options.automatic ? 0 : 10),
+    commands: () => scope.enabled && (!options.automatic || scope.discover)
+      ? toValue(commands).map(command => ({ ...command, group: command.group ?? scope.label })) : [],
+  })
+  onScopeDispose(unregister)
+}
+
+/** Manual definitions override a discovered command without changing its place. */
+export function mergePaletteCommands(discovered: readonly Command[], manual: readonly Command[]): Command[] {
+  const overrides = new Map(manual.map(command => [command.id, command]))
+  return uniqueCommands([...discovered.map(command => overrides.get(command.id) ?? command), ...manual])
+}
+
+export type PaletteControlOptions = false | { id?: string; label?: string; description?: string; keywords?: string[] }
+
+export interface PaletteTargetOptions { id: string; label: string; description?: string; keywords?: string[]; action?: "click" | "focus" }
+const targets = new WeakMap<HTMLElement, { update: (value: PaletteTargetOptions) => void; stop: () => void }>()
+/** Native/custom markup opt-in; editing values still goes through the component's own binding. */
+export const vPalette: Directive<HTMLElement, PaletteTargetOptions> = {
+  mounted(el, binding) {
+    if (el.closest("[data-lp-command-preview]")) return
+    const owner = binding.instance?.$ as { provides?: Record<symbol, unknown> } | undefined
+    const ancestor = el.closest("[data-lp-command-scope]")
+    const scope = (ancestor && scopeElements.get(ancestor)) ?? owner?.provides?.[SCOPE as symbol] as PaletteScope | undefined
+    if (!scope) return
+    const value = shallowRef(binding.value)
+    const stop = scope.registry.register({ priority: scope.depth * 100 + 10, commands: () => scope.enabled ? [{
+      id: `${scope.id}/${value.value.id}`, label: value.value.label,
+      description: value.value.description, keywords: value.value.keywords, group: scope.label,
+      disabled: el.matches(":disabled,[aria-disabled=true]"),
+      afterClose: () => {
+        if (!el.isConnected || el.matches(":disabled,[aria-disabled=true]")) return
+        el.scrollIntoView({ block: "nearest" })
+        if (value.value.action === "click") el.click()
+        else el.focus({ preventScroll: true })
+      },
+    }] : [] })
+    targets.set(el, { stop, update: next => { value.value = { ...next } } })
+  },
+  updated(el, binding) { targets.get(el)?.update(binding.value) },
+  unmounted(el) { targets.get(el)?.stop(); targets.delete(el) },
+}
+
+export function usePaletteAction(options: { label?: () => string | undefined; element: () => HTMLElement | null | undefined; disabled?: () => boolean }) {
+  const instance = getCurrentInstance()
+  const scope = usePaletteScope()
+  if (!instance || !scope || inject(BLOCKED, false)) return
+  const domLabel = ref("")
+  const syncLabel = () => { domLabel.value = options.element()?.textContent?.trim() ?? "" }
+  onMounted(syncLabel)
+  onUpdated(syncLabel)
+  usePaletteCommands(() => {
+    const config = instance.props.palette as PaletteControlOptions | undefined
+    const label = (config || {}).label ?? options.label?.() ?? domLabel.value
+    if (config === false || !label) return []
+    return [{
+      id: `${scope.id}/${config?.id ?? label}`, label, description: config?.description,
+      keywords: config?.keywords, disabled: options.disabled?.(),
+      afterClose: () => { if (!options.disabled?.()) options.element()?.click() },
+    }]
+  }, { automatic: true })
+}
+
+export function usePaletteControl(options: {
+  label?: () => string | undefined
+  disabled?: () => boolean
+  invalid?: () => boolean
+  available?: () => boolean
+  ownsChildren?: boolean
+  editorProps?: () => Record<string, unknown>
+} = {}) {
+  const instance = getCurrentInstance()
+  const scope = usePaletteScope()
+  const blocked = inject(BLOCKED, false)
+  if (options.ownsChildren) suppressPaletteDiscovery()
+  if (!instance || !scope || blocked) return
+  const text = useLabels("paletteControl", { focus: "Go to field" })
+  const field = useField()
+  const settings = () => (instance.attrs.palette ?? instance.props.palette) as PaletteControlOptions | undefined
+  const label = () => (settings() || {}).label ?? options.label?.() ?? field?.value.label
+    ?? instance.attrs["aria-label"] as string | undefined
+  const error = () => instance.props.error as string | undefined ?? field?.value.error
+  const hint = () => instance.props.hint as string | undefined ?? field?.value.hint
+  const writable = () => !!(instance.vnode.props?.["onUpdate:modelValue"] || instance.vnode.props?.["onUpdate:model-value"] || instance.props.action)
+  const focus = () => {
+    const el = instance.proxy?.$el as HTMLElement | undefined
+    const target = el?.matches?.('input,button,textarea,select,[tabindex="0"]') ? el
+      : el?.querySelector<HTMLElement>('input:not([type="hidden"]),button,textarea,select,[tabindex="0"]')
+    target?.scrollIntoView({ block: "nearest" })
+    target?.focus({ preventScroll: true })
+  }
+  const Editor: Component = {
+    name: "PaletteControlEditor",
+    setup() {
+      suppressPaletteDiscovery()
+      const editorId = `lp-palette-editor-${useId()}`
+      provideField(computed(() => ({
+        id: editorId, label: label(), labelId: `${editorId}-label`,
+        describedBy: error() || hint() ? `${editorId}-message` : undefined,
+        required: !!(field?.value.required ?? instance.props.required),
+        disabled: !!options.disabled?.(), invalid: !!options.invalid?.(),
+      })))
+      return () => {
+        const raw = { ...instance.vnode.props, ...instance.props, ...options.editorProps?.() }
+        for (const key of Object.keys(raw)) if (key === "ref" || key === "key" || key.startsWith("onVnode")) delete raw[key]
+        return h("div", { class: "flex flex-col gap-3" }, [
+          h(raw.label ? "h3" : "label", { id: `${editorId}-label`, for: raw.label ? undefined : editorId, class: "text-sm font-semibold text-ink" }, label()),
+          h(instance.type as Component, {
+            ...raw, id: undefined, name: undefined, form: undefined, autofocus: undefined, palette: false,
+            disabled: options.disabled?.() || !writable(), invalid: options.invalid?.(),
+            required: field?.value.required ?? instance.props.required,
+            "aria-label": label(), class: "w-full", style: undefined,
+          }, instance.slots),
+          error() || hint() ? h("p", { id: `${editorId}-message`, class: error() ? "text-xs text-danger" : "text-xs text-muted", role: error() ? "alert" : undefined }, error() || hint()) : null,
+        ])
+      }
+    },
+  }
+  usePaletteCommands(() => {
+    const config = settings()
+    const name = label()
+    if (config === false || !name || options.available?.() === false) return []
+    const id = `${scope.id}/${config?.id ?? (instance.attrs.id as string | undefined) ?? name}`
+    return [{
+      id, label: name, description: config?.description, keywords: config?.keywords,
+      disabled: options.disabled?.(), previewComponent: Editor, editInPreview: writable(),
+      afterClose: writable() ? undefined : focus,
+      actions: [{ id: `${id}/focus`, label: text.value.focus, description: name, icon: "lucide:focus", afterClose: focus }],
+    }]
+  }, { automatic: true })
+}

package/src/composables/useReveal.ts

@@ -1,5 +1,6 @@
 import { onBeforeUnmount, ref, toValue, watch, type MaybeRefOrGetter, type Ref } from "vue"
 import { prefersReducedMotion } from "./easing"
+import { atScrollEnd } from "./scroll"
 
 /*
  * "Has this element actually been SEEN yet?"
@@ -67,10 +68,16 @@ export function useReveal(options: UseRevealOptions = {}): UseReveal {
   const revealed = ref(typeof window === "undefined")
 
   let observer: IntersectionObserver | null = null
+  let edge: IntersectionObserver | null = null
+  let onScroll: (() => void) | null = null
 
   function stop() {
     observer?.disconnect()
     observer = null
+    edge?.disconnect()
+    edge = null
+    if (onScroll) window.removeEventListener("scroll", onScroll, true)
+    onScroll = null
   }
 
   function reveal() {
@@ -103,6 +110,28 @@ export function useReveal(options: UseRevealOptions = {}): UseReveal {
         { threshold, rootMargin },
       )
       observer.observe(node)
+
+      /*
+       * The margin shrinks the viewport from below, so the last element of a
+       * page sits in that strip for good: there is no more scroll to lift it
+       * out, and its count-up never started (a figure at the bottom of a
+       * dashboard stayed at 0). On screen with nowhere left to scroll is an
+       * arrival too.
+       */
+      let onScreen = false
+      const check = () => {
+        if (onScreen && atScrollEnd(node)) reveal()
+      }
+      edge = new IntersectionObserver(
+        (entries) => {
+          onScreen = entries.some((entry) => entry.isIntersecting)
+          check()
+        },
+        { threshold },
+      )
+      edge.observe(node)
+      onScroll = check
+      window.addEventListener("scroll", onScroll, { capture: true, passive: true })
     },
     { immediate: true, flush: "post" },
   )

package/src/composables/useView.ts

@@ -60,7 +60,10 @@ const FORWARDED = ["pointerdown", "pointerup", "click", "focusin", "keydown"] as
 
 export function forwardViewEvents(from: Document, to: Document): () => void {
   const forward = (event: Event) => {
-    if (event.type === "keydown" && (event as KeyboardEvent).key !== "Escape") return
+    if (event.type === "keydown") {
+      const key = event as KeyboardEvent
+      if (key.defaultPrevented || (key.key !== "Escape" && !key.ctrlKey && !key.metaKey)) return
+    }
     const Copy = event.constructor as new (type: string, init: Event) => Event
     const copy = new Copy(event.type, event) as Marked
     copy[ORIGIN] = from
@@ -68,6 +71,7 @@ export function forwardViewEvents(from: Document, to: Document): () => void {
     Object.defineProperty(copy, "target", { value: event.target })
     copy.composedPath = () => path
     to.dispatchEvent(copy)
+    if (copy.defaultPrevented) event.preventDefault()
   }
   for (const type of FORWARDED) from.addEventListener(type, forward)
   return () => {

package/src/index.ts

@@ -452,7 +452,7 @@ export { TONE_ALIASES, TONES, toneLook, toneOf } from "./components/tone"
 export type { Tone, ToneLook, ToneName } from "./components/tone"
 export { formatAmount, quotaSegments, quotaState } from "./components/quota"
 export type { QuotaPart, QuotaSegment, QuotaState, QuotaUnit } from "./components/quota"
-export { compactNumber, formatBytes } from "./components/format"
+export { compactNumber, decimalMark, formatBytes } from "./components/format"
 export type { CompactNumberOptions, FormatBytesOptions } from "./components/format"
 export { STATUS_LABELS, STATUS_LOOK } from "./components/status"
 export type { StatusKind, StatusLook } from "./components/status"
@@ -555,3 +555,20 @@ export { default as LpGlowBorder } from "./components/LpGlowBorder.vue"
 export { default as LpMagnetic } from "./components/LpMagnetic.vue"
 export { spotlightPoint, useSpotlight } from "./composables/useSpotlight"
 export type { UseSpotlight, UseSpotlightOptions } from "./composables/useSpotlight"
+
+export { default as LpCommandScope } from "./components/LpCommandScope.vue"
+export { createPaletteRegistry, usePaletteCommands, mergePaletteCommands } from "./composables/usePaletteCommands"
+export type { PaletteRegistry, PaletteControlOptions } from "./composables/usePaletteCommands"
+export { PALETTE_MODES } from "./components/commandPalette"
+export type { PaletteMode } from "./components/commandPalette"
+export { searchCommandItems, swapCommandLayout } from "./components/commandSearch"
+export type { CommandPrompt } from "./components/LpCommandPalette.vue"
+
+export { usePaletteTheme } from "./theme/palette"
+export { default as LpPaletteTheme } from "./components/LpPaletteTheme.vue"
+
+export { vPalette } from "./composables/usePaletteCommands"
+export type { PaletteTargetOptions } from "./composables/usePaletteCommands"
+export { menuPaletteCommands } from "./components/commandPalette"
+
+export type { PreviewableThemeStudio } from "./theme/studio"