@leavepulse/ui 0.43.4 → 0.44.0

package/src/components/color.ts

@@ -50,7 +50,15 @@ export function clampHsv(c: Hsv): Hsv {
   }
 }
 
-export function hsvToRgb({ h, s, v, a }: Hsv): Rgb {
+// NaN and Infinity read as 0: one bad channel must not throw out of a public
+// conversion or poison the others.
+const finite = (n: number) => (Number.isFinite(n) ? n : 0)
+
+export function hsvToRgb(color: Hsv): Rgb {
+  const h = finite(color.h)
+  const s = clamp(finite(color.s), 0, 1)
+  const v = clamp(finite(color.v), 0, 1)
+  const a = Number.isFinite(color.a) ? color.a : 1
   const hue = normalizeHue(h) / 60
   const c = v * s
   const x = c * (1 - Math.abs((hue % 2) - 1))
@@ -99,10 +107,20 @@ export function rgbToHsv({ r, g, b, a }: Rgb): Hsv {
 
 const hex2 = (n: number) => clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0")
 
+/**
+ * Alpha quantised to the one precision every format can carry, a byte, so hex,
+ * rgb and hsl agree on whether a colour is opaque: 0.996 used to print as an
+ * opaque rgb() and as "#…fe" in hex.
+ */
+function alphaByte(a: number): number {
+  return Math.round(clamp(a, 0, 1) * 255)
+}
+
 /** "#rrggbb", or "#rrggbbaa" when the colour is not fully opaque. */
 export function rgbToHex({ r, g, b, a }: Rgb): string {
   const base = `#${hex2(r)}${hex2(g)}${hex2(b)}`
-  return a >= 1 ? base : base + hex2(a * 255)
+  const byte = alphaByte(a)
+  return byte >= 255 ? base : base + hex2(byte)
 }
 
 /**
@@ -199,20 +217,23 @@ export function hsvToHsl({ h, s, v }: Hsv): { h: number; s: number; l: number }
 /** The colour as a CSS string in the requested format. */
 export function formatColor(c: Hsv, format: ColorFormat): string {
   const rgb = hsvToRgb(c)
-  const a = Math.round(clamp(c.a, 0, 1) * 100) / 100
+  const byte = alphaByte(rgb.a)
+  const a = Math.round((byte / 255) * 1000) / 1000
 
   if (format === "hex") return rgbToHex(rgb)
   if (format === "rgb") {
-    return a >= 1
+    return byte >= 255
       ? `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`
       : `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${a})`
   }
 
-  const { h, s, l } = hsvToHsl(c)
-  const hh = Math.round(h)
-  const ss = Math.round(s * 100)
-  const ll = Math.round(l * 100)
-  return a >= 1 ? `hsl(${hh}, ${ss}%, ${ll}%)` : `hsla(${hh}, ${ss}%, ${ll}%, ${a})`
+  // One decimal: whole percentages drift up to 4 per channel on the way back.
+  const { h, s, l } = hsvToHsl({ ...c, h: finite(c.h), s: clamp(finite(c.s), 0, 1), v: clamp(finite(c.v), 0, 1) })
+  const dec = (n: number) => Math.round(n * 10) / 10
+  const hh = dec(h) % 360
+  const ss = dec(s * 100)
+  const ll = dec(l * 100)
+  return byte >= 255 ? `hsl(${hh}, ${ss}%, ${ll}%)` : `hsla(${hh}, ${ss}%, ${ll}%, ${a})`
 }
 
 /** Always opaque — for the swatch behind an alpha checkerboard, and for rails. */

package/src/components/confirm.ts

@@ -0,0 +1,58 @@
+import { reactive } from "vue"
+
+/*
+ * Imperative confirmation: `if (await confirm({ title: "Delete?" })) ...`.
+ * Requests queue here and the one mounted LpConfirmHost shows them one at a
+ * time. Pinned to a global symbol like the toast queue, so a barrel and a deep
+ * import share one host.
+ */
+
+export interface ConfirmOptions {
+  title: string
+  description?: string
+  danger?: boolean
+  icon?: string
+  confirmLabel?: string
+  cancelLabel?: string
+  loadingLabel?: string
+  /**
+   * Work to run on confirm. The dialog stays open with a loading state while it
+   * runs and shows the error's message if it rejects; the promise from
+   * `confirm()` resolves true only once it succeeded.
+   */
+  action?: () => unknown
+}
+
+export interface ConfirmRequest extends ConfirmOptions {
+  id: number
+  resolve: (confirmed: boolean) => void
+}
+
+const STATE_KEY = Symbol.for("@leavepulse/ui:confirm-queue")
+type GlobalWithConfirm = typeof globalThis & {
+  [STATE_KEY]?: { queue: ConfirmRequest[]; nextId: number }
+}
+const g = globalThis as GlobalWithConfirm
+const state = (g[STATE_KEY] ??= { queue: reactive<ConfirmRequest[]>([]), nextId: 0 })
+
+export const confirmQueue = state.queue
+
+/** Ask for confirmation. Resolves false when the user cancels or dismisses. */
+export function confirm(options: ConfirmOptions): Promise<boolean> {
+  if (typeof window === "undefined") return Promise.resolve(false)
+  return new Promise((resolve) => {
+    state.queue.push({ ...options, id: state.nextId++, resolve })
+  })
+}
+
+/** Settle a request and drop it from the queue. Used by the host. */
+export function settleConfirm(id: number, confirmed: boolean): void {
+  const i = state.queue.findIndex((r) => r.id === id)
+  if (i === -1) return
+  const [request] = state.queue.splice(i, 1)
+  request?.resolve(confirmed)
+}
+
+export function useConfirm(): typeof confirm {
+  return confirm
+}

package/src/components/countries.ts

@@ -65,3 +65,15 @@ export function matchCountryByValue(
   }
   return best
 }
+
+/**
+ * Countries matching a search query: by name, or by dial code when the query
+ * carries digits ("+44", "44"). A query without digits must not match on the
+ * dial code at all, or every country would match the empty string.
+ */
+export function filterCountries(list: Country[], query: string): Country[] {
+  const q = query.trim().toLowerCase()
+  if (!q) return list
+  const digits = q.replace(/\D/g, "")
+  return list.filter((c) => c.name.toLowerCase().includes(q) || (digits !== "" && c.dial.includes(digits)))
+}

package/src/components/fileTree.ts

@@ -126,7 +126,8 @@ export function formatSize(bytes: number): string {
   const units = ["KB", "MB", "GB", "TB", "PB"]
   let value = bytes / 1024
   let i = 0
-  while (value >= 1024 && i < units.length - 1) {
+  // Compare the value as it will print, so 1 048 575 B is "1.0 MB", not "1024 KB".
+  while (Math.round(value) >= 1024 && i < units.length - 1) {
     value /= 1024
     i++
   }
@@ -191,14 +192,20 @@ export function checkStateOf(node: FileNode, checked: ReadonlySet<string>): Chec
   }
   let all = true
   let any = false
+  let considered = 0
   for (const child of node.children) {
     const state = checkStateOf(child, checked)
+    // A locked, unticked entry can never be ticked, so it must not hold its
+    // folder at "indeterminate" forever.
+    if (child.disabled && state === "unchecked") continue
+    considered++
     if (state === "checked") any = true
     else if (state === "indeterminate") {
       any = true
       all = false
     } else all = false
   }
+  if (!considered) return checked.has(node.id) ? "checked" : "unchecked"
   if (all) return "checked"
   return any ? "indeterminate" : "unchecked"
 }
@@ -271,14 +278,18 @@ export function computeStats(
     let total = 0
     let bytes = 0
     let sized = node.size !== undefined
+    let considered = 0
 
     for (const child of node.children) {
       const childStats = visit(child)
-      if (childStats.state === "checked") any = true
-      else if (childStats.state === "indeterminate") {
-        any = true
-        all = false
-      } else all = false
+      if (!child.disabled || childStats.state !== "unchecked") {
+        considered++
+        if (childStats.state === "checked") any = true
+        else if (childStats.state === "indeterminate") {
+          any = true
+          all = false
+        } else all = false
+      }
       count += childStats.checked
       total += childStats.total
       if (childStats.size !== undefined) {
@@ -287,8 +298,9 @@ export function computeStats(
       }
     }
 
+    const own: CheckState = checked.has(node.id) ? "checked" : "unchecked"
     const self: NodeStats = {
-      state: all ? "checked" : any ? "indeterminate" : "unchecked",
+      state: !considered ? own : all ? "checked" : any ? "indeterminate" : "unchecked",
       checked: count,
       total,
       // An explicit size on the directory wins: a server-side listing usually

package/src/components/imageCrop.ts

@@ -0,0 +1,107 @@
+/*
+ * Geometry shared by LpImageEditor's preview and its export, so what is drawn
+ * on screen and what is written to the Blob come from one calculation.
+ *
+ * Three spaces are involved:
+ * - source: the picture's own pixels, origin at its centre;
+ * - upright: the source after the rotation, as the person sees it, origin at
+ *   its centre, still in source-pixel units;
+ * - frame: the crop box on screen, origin at its centre, in CSS pixels.
+ *
+ * A turn of θ (clockwise, as CSS and canvas both rotate in a y-down space)
+ * maps source to upright by u = R(θ)·q. The picture is drawn at `cover` CSS
+ * pixels per source pixel, then panned by `offset` and zoomed by `scale`, so a
+ * frame point f shows the upright point (f / scale − offset) / cover.
+ */
+
+export interface Point {
+  x: number
+  y: number
+}
+
+export interface CropInput {
+  sourceWidth: number
+  sourceHeight: number
+  frameWidth: number
+  frameHeight: number
+  /** Accumulated rotation in degrees; any angle, not only quarter turns. */
+  rotation: number
+  /** Zoom factor, 1 = the picture just covers the frame. */
+  scale: number
+  /** Pan in frame pixels before the zoom, as useZoomPan reports it. */
+  offset: Point
+}
+
+export interface CropGeometry {
+  /** CSS pixels per source pixel at zoom 1. */
+  cover: number
+  /** Crop size in upright (source-pixel) units. */
+  width: number
+  height: number
+  /** Crop centre in upright space. */
+  centre: Point
+}
+
+const radians = (deg: number) => (deg * Math.PI) / 180
+
+/** Rotate a point clockwise by `deg` in a y-down space. */
+export function rotatePoint(p: Point, deg: number): Point {
+  const a = radians(deg)
+  const cos = Math.cos(a)
+  const sin = Math.sin(a)
+  return { x: p.x * cos - p.y * sin, y: p.x * sin + p.y * cos }
+}
+
+/** The source pixel (from the source's top-left) under an upright-space point. */
+export function uprightToSource(u: Point, rotation: number, sourceWidth: number, sourceHeight: number): Point {
+  const q = rotatePoint(u, -rotation)
+  return { x: q.x + sourceWidth / 2, y: q.y + sourceHeight / 2 }
+}
+
+/**
+ * Smallest scale at which the turned picture still covers the whole frame.
+ *
+ * Covering the bounding box of a turned picture is not enough at a free angle:
+ * its corners are empty. The frame, turned back by the same angle, has to fit
+ * inside the unturned picture; for a quarter turn this reduces to the usual
+ * object-cover of the swapped dimensions.
+ */
+export function coverScale(
+  sourceWidth: number,
+  sourceHeight: number,
+  frameWidth: number,
+  frameHeight: number,
+  rotation: number,
+): number {
+  const a = radians(rotation)
+  const cos = Math.abs(Math.cos(a))
+  const sin = Math.abs(Math.sin(a))
+  return Math.max(
+    (frameWidth * cos + frameHeight * sin) / sourceWidth,
+    (frameWidth * sin + frameHeight * cos) / sourceHeight,
+  )
+}
+
+/** What the frame holds, in upright space. */
+export function cropGeometry(input: CropInput): CropGeometry {
+  const cover = coverScale(
+    input.sourceWidth,
+    input.sourceHeight,
+    input.frameWidth,
+    input.frameHeight,
+    input.rotation,
+  )
+  const shown = cover * input.scale
+  return {
+    cover,
+    width: input.frameWidth / shown,
+    height: input.frameHeight / shown,
+    centre: { x: -input.offset.x / cover, y: -input.offset.y / cover },
+  }
+}
+
+/** Whether the turn is closer to sideways than to upright. */
+export function isSideways(rotation: number): boolean {
+  const quarters = Math.round(rotation / 90)
+  return ((quarters % 2) + 2) % 2 === 1
+}

package/src/components/link.ts

@@ -0,0 +1,34 @@
+import type { Component } from "vue"
+
+/*
+ * How a navigation target renders: an internal destination goes through the
+ * configured link component (RouterLink, NuxtLink) so it navigates client-side,
+ * anything else is a plain anchor. Shared by every kit piece that links.
+ */
+export type LinkTarget = string | Record<string, unknown>
+
+export interface ResolvedLink {
+  is: Component | string
+  props: Record<string, unknown>
+}
+
+/** An app-relative path: "/x", not "//host" or "https://…". */
+export function isInternalHref(href: string): boolean {
+  return href.startsWith("/") && !href.startsWith("//")
+}
+
+export function resolveLink(
+  linkComponent: Component | string,
+  target: { to?: LinkTarget; href?: string },
+): ResolvedLink | null {
+  const router = linkComponent !== "a"
+  if (target.to != null) {
+    if (router) return { is: linkComponent, props: { to: target.to } }
+    return typeof target.to === "string" ? { is: "a", props: { href: target.to } } : null
+  }
+  if (target.href != null) {
+    if (router && isInternalHref(target.href)) return { is: linkComponent, props: { to: target.href } }
+    return { is: "a", props: { href: target.href } }
+  }
+  return null
+}

package/src/components/modalDepth.ts

@@ -1,16 +1,47 @@
-import { computed, ref, type ComputedRef } from "vue"
+import { computed, ref, type ComputedRef, type Ref } from "vue"
 
 const STEP = 20
 
-const stack = ref<number[]>([])
-let nextId = 0
+/*
+ * One opening-order stack for every modal surface. Pinned to a global symbol
+ * like the toast queue: a barrel import and a deep import can load this module
+ * twice, and two stacks would put a deep-imported dialog's scrim under a
+ * barrel-imported drawer's panel.
+ */
+const STATE_KEY = Symbol.for("@leavepulse/ui:modal-stack")
+type GlobalWithStack = typeof globalThis & {
+  [STATE_KEY]?: {
+    stack: Ref<number[]>
+    nextId: number
+    elements: Map<number, () => HTMLElement | null | undefined>
+  }
+}
+const g = globalThis as GlobalWithStack
+const state = (g[STATE_KEY] ??= { stack: ref<number[]>([]), nextId: 0, elements: new Map() })
+const stack = state.stack
 
-export function useModalLayer(): {
+export interface ModalLayer {
+  /** Join the stack on top. Ignored on the server, where nothing would ever release it. */
   claim: () => void
   release: () => void
+  /** z-index values for this surface's scrim and panel, and whether another modal is under it. */
   layer: ComputedRef<{ scrim: string; panel: string; nested: boolean }>
-} {
-  const id = nextId++
+  /** Whether this surface is the topmost open one. */
+  top: ComputedRef<boolean>
+}
+
+export interface ModalLayerOptions {
+  /** The surface's panel, so keyboard handling can tell what sits inside the top modal. */
+  element?: () => HTMLElement | null | undefined
+}
+
+/**
+ * Put an overlay on the shared modal stack, so a surface opened from another
+ * one (a dialog from a drawer, a lightbox from a dialog) lands above it with
+ * its scrim, whatever component either of them is.
+ */
+export function useModalLayer(options: ModalLayerOptions = {}): ModalLayer {
+  const id = state.nextId++
 
   const fromTop = computed(() => {
     const at = stack.value.indexOf(id)
@@ -19,9 +50,12 @@ export function useModalLayer(): {
 
   return {
     claim: () => {
+      if (typeof window === "undefined") return
+      if (options.element) state.elements.set(id, options.element)
       if (!stack.value.includes(id)) stack.value = [...stack.value, id]
     },
     release: () => {
+      state.elements.delete(id)
       stack.value = stack.value.filter((x) => x !== id)
     },
     layer: computed(() => {
@@ -32,9 +66,17 @@ export function useModalLayer(): {
         nested: stack.value.indexOf(id) > 0,
       }
     }),
+    top: computed(() => stack.value[stack.value.length - 1] === id),
   }
 }
 
 export function anyModalOpen(): boolean {
   return stack.value.length > 0
 }
+
+/** The panel of the topmost modal, when it registered one. */
+export function topModalElement(): HTMLElement | null {
+  const id = stack.value[stack.value.length - 1]
+  if (id === undefined) return null
+  return state.elements.get(id)?.() ?? null
+}

package/src/components/otp.ts

@@ -0,0 +1,16 @@
+/*
+ * The bridge between reka PinInput's per-cell array and LpOtpInput's string
+ * model. reka empties a cell by deleting its slot (numeric mode) or setting it
+ * to "", so the array can have holes in the middle.
+ */
+export type OtpCells = (string | number | undefined)[]
+
+/** The code typed so far: the filled cells in order. */
+export function joinCells(cells: OtpCells): string {
+  return Array.from(cells, (c) => (c === undefined ? "" : String(c))).join("")
+}
+
+/** Cells for a code given from outside, one character each. */
+export function splitCode(code: string | undefined, length: number): string[] {
+  return (code ?? "").split("").slice(0, length)
+}

package/src/components/sidebar.ts

@@ -10,8 +10,14 @@ export interface SidebarItem {
   id: string
   label: string
   icon?: string
-  /** Render as a link instead of a button. */
+  /**
+   * Render as a link instead of a button. An app-relative path goes through
+   * the link component from provideLpConfig (NuxtLink under the Nuxt module),
+   * so it navigates client-side; other URLs render a plain anchor.
+   */
   href?: string
+  /** Router destination (rendered through the configured link component). */
+  to?: string | Record<string, unknown>
   /** Count chip on the right (number or short string). */
   badge?: number | string
   disabled?: boolean

package/src/components/tableSort.ts

@@ -0,0 +1,37 @@
+const COLLATOR = new Intl.Collator(undefined, { numeric: true })
+
+const rank = (v: unknown): number => {
+  if (v == null || (typeof v === "number" && Number.isNaN(v))) return 0
+  if (typeof v === "boolean") return 1
+  if (typeof v === "number" || typeof v === "bigint") return 2
+  if (v instanceof Date) return Number.isNaN(v.getTime()) ? 0 : 3
+  return 4
+}
+
+/**
+ * Ascending order for raw cell values. Empty values (null, undefined, NaN, an
+ * invalid Date) come first; numbers, bigints and Dates compare by magnitude,
+ * booleans false before true, everything else as text with numeric runs read as
+ * numbers ("file 2" before "file 10"). Mixed kinds group by kind so the order
+ * is total and a sort is stable from one run to the next.
+ */
+export function compareValues(a: unknown, b: unknown): number {
+  const ra = rank(a)
+  const rb = rank(b)
+  if (ra !== rb) return ra - rb
+  switch (ra) {
+    case 0:
+      return 0
+    case 1:
+      return Number(a) - Number(b)
+    case 2: {
+      const x = a as number | bigint
+      const y = b as number | bigint
+      return x < y ? -1 : x > y ? 1 : 0
+    }
+    case 3:
+      return (a as Date).getTime() - (b as Date).getTime()
+    default:
+      return COLLATOR.compare(String(a), String(b))
+  }
+}

package/src/composables/useField.ts

@@ -0,0 +1,79 @@
+import { computed, inject, provide, useId, type ComputedRef, type InjectionKey } from "vue"
+
+/*
+ * What a form field tells the control inside it: the id its label points at,
+ * the id of the hint/error line the control should be described by, and the
+ * states the control should reflect. LpFormField provides it; every kit control
+ * consumes it, and so can a consumer's own control placed inside a field.
+ */
+export interface FieldContext {
+  id: string
+  /** Id of the visible label, for controls a `<label for>` cannot name (groups). */
+  labelId?: string
+  describedBy?: string
+  invalid: boolean
+  required: boolean
+  disabled: boolean
+}
+
+export const LP_FIELD: InjectionKey<ComputedRef<FieldContext>> = Symbol.for("lp-field")
+
+export function provideField(context: ComputedRef<FieldContext>): void {
+  provide(LP_FIELD, context)
+}
+
+/** The nearest LpFormField's context, or null outside one. */
+export function useField(): ComputedRef<FieldContext> | null {
+  return inject(LP_FIELD, null)
+}
+
+export function fieldMessageId(id: string): string {
+  return `${id}-message`
+}
+
+export interface FieldControlState {
+  /** The control wraps itself in its own LpFormField (it has a label, hint or error prop). */
+  wrapped: boolean
+  /** That own field renders a hint or error line. */
+  hasMessage?: boolean
+  /** An id the consumer set on the control, which must win over a generated one. */
+  id?: string
+  invalid?: boolean
+  required?: boolean
+  disabled?: boolean
+}
+
+/**
+ * The field state a control renders with: its own wrapping field when it has
+ * one, otherwise the field around it, with the control's own flags or-ed in.
+ * `id` is undefined only for a bare control outside any field.
+ */
+export function useFieldControl(
+  own: () => FieldControlState,
+): ComputedRef<Omit<FieldContext, "id"> & { id?: string }> {
+  const outer = useField()
+  const generated = useId()
+  return computed(() => {
+    const state = own()
+    if (state.wrapped) {
+      const id = state.id ?? generated
+      return {
+        id,
+        labelId: undefined,
+        describedBy: state.hasMessage ? fieldMessageId(id) : undefined,
+        invalid: !!state.invalid,
+        required: !!state.required,
+        disabled: !!state.disabled,
+      }
+    }
+    const field = outer?.value
+    return {
+      id: state.id ?? field?.id,
+      labelId: field?.labelId,
+      describedBy: field?.describedBy,
+      invalid: !!state.invalid || !!field?.invalid,
+      required: !!state.required || !!field?.required,
+      disabled: !!state.disabled || !!field?.disabled,
+    }
+  })
+}