@leavepulse/ui 0.24.0 → 0.25.0

package/src/components/LpSparkline.vue

@@ -0,0 +1,312 @@
+<script setup lang="ts">
+/*
+ * A trend, inline. No axes, no grid, no legend — just the shape of a series,
+ * sized to sit inside a table cell or beside a stat's value.
+ *
+ * Deliberately NOT LpChart with everything switched off. LpChart answers "what
+ * were the values" and pays for it: a ResizeObserver, two scales, a tooltip
+ * spring, a context menu. A sparkline answers "up or down", and there are forty
+ * of them on a list page — so it measures nothing, observes nothing and holds
+ * no state. The viewBox is fixed and the browser scales the path; the geometry
+ * is the same `chart.ts` the full chart uses, so a line reads identically in
+ * both.
+ *
+ *   <LpSparkline :data="cpu" />
+ *   <LpSparkline :data="load" area tone="danger" :width="72" />
+ */
+import { computed } from "vue"
+import { useReveal } from "../composables/useReveal"
+import { areaPath, extent, linePath, normalise, type Box } from "./chart"
+
+const props = withDefaults(
+  defineProps<{
+    /** Oldest → newest. `null` breaks the line, as in LpChart. */
+    data: (number | null)[]
+    /** Rendered size in px. The path scales to it; stroke width does not. */
+    width?: number
+    height?: number
+    /** Any CSS colour. Defaults to the brand token. */
+    color?: string
+    /** Named theme tones, for callers that don't want to spell a var(). */
+    tone?: "brand" | "action" | "danger" | "accent" | "muted"
+    /** Fill under the line. */
+    area?: boolean
+    /** Curve tension, as in LpChart. 0 draws a polyline. */
+    smooth?: number
+    /** Dot on the final point — "you are here" on a trend. */
+    showLast?: boolean
+    /**
+     * Pin the vertical range instead of fitting the data. Without it a flat
+     * series fills the box with noise, and two sparklines in one column can't
+     * be compared: each would be scaled to its own extremes.
+     */
+    min?: number
+    max?: number
+    /** Accessible description; falls back to a direction + latest value. */
+    ariaLabel?: string
+    /**
+     * Draw the line on from oldest to newest when it first appears. Turn it off
+     * for a table that renders many at once — dozens of simultaneous sweeps
+     * read as flicker.
+     */
+    animate?: boolean
+    /**
+     * Draw time in ms. The stroke travels at a near-even rate (see
+     * `--ease-travel`), so this is roughly how long the line is actually
+     * watched being drawn — not a figure mostly spent easing out.
+     */
+    duration?: number
+  }>(),
+  { width: 84, height: 24, tone: "brand", smooth: 0.9, animate: true, duration: 900 },
+)
+
+const TONE: Record<string, string> = {
+  brand: "var(--color-brand)",
+  action: "var(--color-action)",
+  danger: "var(--color-danger)",
+  accent: "var(--color-accent)",
+  muted: "var(--color-muted)",
+}
+
+const stroke = computed(() => props.color ?? TONE[props.tone])
+
+const series = computed(() => normalise([{ name: "s", data: props.data }]))
+
+/*
+ * The path is built in the viewBox's own coordinates and the SVG scales it, so
+ * nothing here depends on layout — which is what lets this render identically
+ * on the server and in a cell that hasn't been measured yet.
+ *
+ * Inset by half a stroke so the line's own width can't be clipped at the edges,
+ * and by a little more vertically so a peak sitting exactly at the maximum
+ * keeps its round cap.
+ */
+const PAD = 2
+
+const box = computed<Box>(() => ({
+  width: props.width,
+  height: props.height,
+  left: PAD,
+  right: PAD,
+  top: PAD,
+  bottom: PAD,
+}))
+
+const bounds = computed(() => {
+  const auto = extent(series.value, false)
+  return { min: props.min ?? auto.min, max: props.max ?? auto.max }
+})
+
+const geo = computed(() => ({
+  min: bounds.value.min,
+  max: bounds.value.max,
+  box: box.value,
+  count: props.data.length,
+  banded: false,
+}))
+
+const d = computed(() => linePath(series.value[0].values, geo.value, props.smooth))
+const fill = computed(() =>
+  props.area ? areaPath(series.value[0].values, geo.value, props.smooth) : "",
+)
+
+/** Last point that actually has a value — the dot goes there, not on a gap. */
+const lastPoint = computed(() => {
+  const values = series.value[0].values
+  for (let i = values.length - 1; i >= 0; i--) {
+    const v = values[i]
+    if (v == null) continue
+    const span = bounds.value.max - bounds.value.min || 1
+    const w = props.width - PAD * 2
+    const h = props.height - PAD * 2
+    return {
+      x: props.data.length <= 1 ? PAD + w / 2 : PAD + (w / (props.data.length - 1)) * i,
+      y: PAD + h - ((v - bounds.value.min) / span) * h,
+      v,
+    }
+  }
+  return null
+})
+
+const hasData = computed(() => series.value[0].values.some((v) => v != null))
+
+/* A bare <svg> is invisible to a screen reader; say the shape out loud. */
+const label = computed(() => {
+  if (props.ariaLabel) return props.ariaLabel
+  const values = series.value[0].values.filter((v): v is number => v != null)
+  if (!values.length) return "No data"
+  const first = values[0]
+  const last = values[values.length - 1]
+  const dir = last > first ? "trending up" : last < first ? "trending down" : "flat"
+  return `${dir}, latest ${last}`
+})
+
+/*
+ * Dash-offset reveal: the stroke is dashed with one dash as long as the whole
+ * path and the offset animated from that length to zero, so the line appears to
+ * be drawn. The dash length only has to be an OVER-estimate — the bounding box
+ * diagonal per segment always is — which avoids measuring the path in the DOM
+ * and keeps the component render-only, as SSR needs.
+ */
+const pathLength = computed(() => {
+  const n = Math.max(1, props.data.length - 1)
+  const segment = Math.hypot((props.width - PAD * 2) / n, props.height - PAD * 2)
+  return Math.ceil(segment * n + 4)
+})
+
+/*
+ * The sweep is held until the svg is actually on screen. Forty of these sit in
+ * a list, most of them below the fold; started on mount they would all have
+ * finished before the rows carrying them were ever scrolled to.
+ */
+const { el, revealed } = useReveal({ immediate: () => !props.animate })
+
+const revealStyle = computed(() =>
+  props.animate
+    ? {
+        "--lp-spark-len": `${pathLength.value}`,
+        "--lp-spark-dur": `${props.duration}ms`,
+      }
+    : undefined,
+)
+
+/*
+ * Three states, not two: no animation at all (paint it), waiting to be seen
+ * (hold it back), and drawing. The waiting state has to be marked on the
+ * element, because the animation's own "from" cannot express it — a paused
+ * keyframe still needs the dash variables set, and those are exactly what a
+ * finished-looking fallback resolves to.
+ */
+const revealClass = computed(() => (props.animate && !revealed.value ? "lp-spark--waiting" : ""))
+
+const gradientId = `lp-spark-${Math.random().toString(36).slice(2, 9)}`
+</script>
+
+<template>
+  <svg
+    v-if="hasData"
+    ref="el"
+    :width="width"
+    :height="height"
+    :viewBox="`0 0 ${width} ${height}`"
+    role="img"
+    :aria-label="label"
+    class="shrink-0 overflow-visible"
+  >
+    <defs v-if="area">
+      <linearGradient :id="gradientId" x1="0" y1="0" x2="0" y2="1">
+        <stop offset="0%" :stop-color="stroke" stop-opacity="0.3" />
+        <stop offset="100%" :stop-color="stroke" stop-opacity="0.02" />
+      </linearGradient>
+    </defs>
+
+    <!--
+      The line DRAWS ITSELF from oldest to newest, and the fill and the end dot
+      arrive behind it.
+
+      A trend has a direction, and a sparkline that simply appears states a
+      shape without it. Stroking it left to right replays the reading order the
+      data already has — and in a list of them, the eye is drawn to the row that
+      just refreshed. `animate: false` for a table that renders dozens at once,
+      where the sweep would read as flicker rather than as arrival.
+    -->
+    <path
+      v-if="area"
+      :d="fill"
+      :fill="`url(#${gradientId})`"
+      class="lp-spark__area"
+      :class="revealClass"
+      :style="revealStyle"
+    />
+    <path
+      :d="d"
+      fill="none"
+      :stroke="stroke"
+      stroke-width="1.5"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      vector-effect="non-scaling-stroke"
+      class="lp-spark__line"
+      :class="revealClass"
+      :style="revealStyle"
+    />
+    <circle
+      v-if="showLast && lastPoint"
+      :cx="lastPoint.x"
+      :cy="lastPoint.y"
+      r="2"
+      :fill="stroke"
+      class="lp-spark__dot"
+      :class="revealClass"
+      :style="revealStyle"
+    />
+  </svg>
+
+  <!-- Keeps the row's rhythm when a machine has reported nothing yet. -->
+  <span
+    v-else
+    class="inline-block shrink-0 rounded-pill bg-surface-soft"
+    :style="{ width: `${width}px`, height: '2px' }"
+    role="img"
+    :aria-label="label"
+  />
+</template>
+
+<style>
+/*
+ * Unscoped and namespaced: the reveal is driven by CSS variables the component
+ * sets inline, and keyframes cannot live in a scoped block that the animated
+ * element may not carry the attribute for.
+ *
+ * Only elements that were given the variables animate — `animate: false` omits
+ * them, the `var()` fallbacks resolve to a finished state, and nothing moves.
+ *
+ * `--waiting` is the third state: the element is on the page but has not been
+ * scrolled to, so it is held at the animation's first frame. It cannot simply
+ * be left un-animated, because that is indistinguishable from finished.
+ */
+.lp-spark__line {
+  stroke-dasharray: var(--lp-spark-len, none);
+  stroke-dashoffset: 0;
+  animation: lp-spark-draw var(--lp-spark-dur, 0ms) var(--ease-travel) both;
+}
+
+.lp-spark__area,
+.lp-spark__dot {
+  /* Behind the line: the fill and the end marker belong to a line that has
+     already been drawn, so they fade in over its last third. */
+  animation: lp-spark-fade var(--lp-spark-dur, 0ms) ease both;
+}
+
+.lp-spark--waiting.lp-spark__line {
+  stroke-dashoffset: var(--lp-spark-len, 0);
+  animation: none;
+}
+
+.lp-spark--waiting.lp-spark__area,
+.lp-spark--waiting.lp-spark__dot {
+  opacity: 0;
+  animation: none;
+}
+
+@keyframes lp-spark-draw {
+  from {
+    stroke-dashoffset: var(--lp-spark-len, 0);
+  }
+}
+
+@keyframes lp-spark-fade {
+  0%,
+  60% {
+    opacity: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .lp-spark__line,
+  .lp-spark__area,
+  .lp-spark__dot {
+    animation: none;
+  }
+}
+</style>

package/src/components/LpStat.vue

@@ -3,11 +3,24 @@
 // subtitle. A product pattern, fully token-driven — re-skins with the theme.
 import { computed } from "vue"
 import LpIcon from "./LpIcon.vue"
+import LpNumberFlow from "./LpNumberFlow.vue"
 
 const props = withDefaults(
   defineProps<{
     label: string
-    value: string
+    /**
+     * A string is printed as given; a NUMBER counts to its new value on
+     * LpNumberFlow's digit wheels. A tile on a live dashboard is the one place
+     * a figure changes while somebody is looking at it, and a value that cuts
+     * from 41 to 43 says nothing about which way it moved.
+     */
+    value: string | number
+    /** Formatting for a numeric `value` — see LpNumberFlow. */
+    compact?: boolean
+    grouped?: boolean
+    decimals?: number
+    prefix?: string
+    valueSuffix?: string
     hint?: string
     icon?: string
     online?: boolean
@@ -22,7 +35,7 @@ const props = withDefaults(
      *  downward trend reads as positive (action) and upward as danger. */
     invertTrend?: boolean
   }>(),
-  { trend: "auto" },
+  { trend: "auto", decimals: 0 },
 )
 
 // Resolve the trend direction: explicit wins; "auto" reads a numeric delta.
@@ -61,6 +74,18 @@ const deltaText = computed(() => {
 })
 
 const showDelta = computed(() => props.delta != null)
+
+/*
+ * Read off the delta itself rather than taken as a prop: a change is quoted at
+ * whatever precision it was measured (+2.4%, +12), and the tile's own
+ * `decimals` describes the VALUE, which is a different quantity. Rounding
+ * +0.4 to +0 would report no change at all.
+ */
+const deltaDecimals = computed(() => {
+  if (typeof props.delta !== "number") return 0
+  const [, fraction] = String(props.delta).split(".")
+  return Math.min(fraction?.length ?? 0, 4)
+})
 </script>
 
 <template>
@@ -74,7 +99,16 @@ const showDelta = computed(() => props.delta != null)
     </div>
     <div class="flex items-baseline gap-2">
       <span class="font-mono text-3xl font-medium tracking-tight text-ink">
-        {{ value }}
+        <LpNumberFlow
+          v-if="typeof value === 'number'"
+          :value="value"
+          :compact="compact"
+          :grouped="grouped"
+          :decimals="decimals"
+          :prefix="prefix"
+          :suffix="valueSuffix"
+        />
+        <template v-else>{{ value }}</template>
       </span>
       <span
         v-if="showDelta"
@@ -82,7 +116,21 @@ const showDelta = computed(() => props.delta != null)
         :class="trendColor"
       >
         <LpIcon :name="trendIcon" :size="14" />
-        {{ deltaText }}
+        <!-- Rolls like the value it sits beside. Two figures on one line, one
+             cutting and one counting, reads as the delta failing to update. -->
+        <LpNumberFlow
+          v-if="typeof delta === 'number'"
+          :value="delta"
+          :decimals="deltaDecimals"
+          :prefix="delta > 0 ? '+' : ''"
+          :suffix="deltaSuffix"
+        />
+        <template v-else>{{ deltaText }}</template>
+      </span>
+      <!-- A delta says how much it moved; the shape says how it got there. Put
+           an LpSparkline (or a ring) here to answer both at once. -->
+      <span v-if="$slots.trend" class="ml-3 self-center">
+        <slot name="trend" />
       </span>
     </div>
     <span v-if="hint" class="text-sm text-muted">{{ hint }}</span>

package/src/components/LpTooltip.vue

@@ -34,9 +34,15 @@ import {
   TooltipRoot,
   TooltipTrigger,
 } from "reka-ui"
+import { onBeforeUnmount, ref, watch } from "vue"
+import {
+  springSettled,
+  springStep,
+  type SpringState,
+} from "../composables/usePillTransition"
 import { PANEL_SURFACE, TOOLTIP_ANIM } from "./dropdown"
 
-withDefaults(
+const props = withDefaults(
   defineProps<{
     content?: string
     sideOffset?: number
@@ -55,28 +61,185 @@ withDefaults(
      * pops up after every mouse click on the trigger is noise.
      */
     showOnPointerFocus?: boolean
+    /**
+     * Track the pointer instead of anchoring to the trigger's edge.
+     *
+     * For a trigger that is large or oddly shaped — a chart slice, a canvas, a
+     * map region — where the element's bounding box says little about what the
+     * pointer is actually over: anchored to the box, the tip can appear far from
+     * the thing it describes. Following the cursor keeps it next to the reading.
+     */
+    followCursor?: boolean
+    /**
+     * Suppress the tip. For a trigger whose tip only applies to part of it — a
+     * chart wrapper where the pointer may be over a mark or over empty canvas —
+     * so an empty panel never opens over the gaps.
+     *
+     * This also FORCES CLOSED a tip that is already showing. reka's own
+     * `disabled` does not: it stops managing the tooltip where it stands, so one
+     * that was open when the flag flipped stayed on screen for good — outliving
+     * the pointer, letting a second chart open its own beside it, and surviving
+     * a scroll that should have dismissed it.
+     */
+    disabled?: boolean
   }>(),
   { delay: 200, side: "top" },
 )
+
+/*
+ * Follow mode. reka positions the tip against the trigger's BOX and exposes no
+ * virtual anchor for tooltips (PopperAnchor isn't part of its public surface),
+ * so the tip is placed as usual and then offset to the cursor.
+ *
+ * Both axes are followed. Following x alone left the tip pinned to the vertical
+ * middle of the trigger, which for a tall target — a pie 180px across, a canvas,
+ * a map — parks it a long way from the pointer. The offset is measured from the
+ * box's centre on each axis, and reka's own side placement still decides which
+ * way the tip sits relative to that point.
+ *
+ * The tip TRAILS the cursor on a spring rather than being pinned to it: chasing
+ * the pointer exactly reads as jitter, while a slight lag reads as following.
+ * Same reasoning, and the same shared "float" feel, as LpChart's readout.
+ */
+const target = { x: 0, y: 0 }
+const offset = ref({ x: 0, y: 0 })
+
+/*
+ * The spring constants come from the kit's shared "float" feel — the same ones
+ * LpChart hands to motion-v for its readout. Only the mechanism differs: this
+ * panel is portalled and positioned by reka, so there is no absolute target for
+ * a declarative animation to own and the spring is integrated by hand.
+ */
+let sx: SpringState = { value: 0, velocity: 0 }
+let sy: SpringState = { value: 0, velocity: 0 }
+let frame = 0
+let lastFrame = 0
+
+const settle = (now: number) => {
+  const dt = lastFrame ? (now - lastFrame) / 1000 : 1 / 60
+  lastFrame = now
+  frame = 0
+
+  sx = springStep(sx, target.x, "float", dt)
+  sy = springStep(sy, target.y, "float", dt)
+
+  // Close enough to have arrived: snap and stop, so an idle tooltip isn't
+  // holding a rAF loop open forever.
+  if (springSettled(sx, target.x) && springSettled(sy, target.y)) {
+    sx = { value: target.x, velocity: 0 }
+    sy = { value: target.y, velocity: 0 }
+    offset.value = { x: target.x, y: target.y }
+    lastFrame = 0
+    return
+  }
+
+  offset.value = { x: sx.value, y: sy.value }
+  frame = requestAnimationFrame(settle)
+}
+
+const onPointerMove = (e: PointerEvent) => {
+  if (!props.followCursor) return
+  const el = e.currentTarget as HTMLElement | null
+  if (!el) return
+  const rect = el.getBoundingClientRect()
+  const halfX = props.side === "left" || props.side === "right" ? rect.width / 2 : 0
+  const dirX = props.side === "right" ? -1 : 1
+  target.x = e.clientX - (rect.left + rect.width / 2) + halfX * dirX
+  /*
+   * reka clears the tip past the whole box's EDGE, not past the pointer, so on
+   * a tall trigger it ends up half the box above the cursor — measured at 96px
+   * on a 180px circle. Adding the half-height back re-references the placement
+   * to the pointer itself; `side` then keeps its meaning (the tip still sits
+   * above for "top"), now relative to the cursor rather than the box.
+   */
+  const half = props.side === "top" || props.side === "bottom" ? rect.height / 2 : 0
+  const dir = props.side === "bottom" ? -1 : 1
+  target.y = e.clientY - (rect.top + rect.height / 2) + half * dir
+  if (!frame) frame = requestAnimationFrame(settle)
+}
+
+/*
+ * Open state is held here rather than left to reka, so that `disabled` can shut
+ * a tip that is already showing. Left to reka, disabling only detaches its
+ * handlers — whatever was on screen stayed there.
+ */
+const open = ref(false)
+/* What reka last asked for, regardless of whether it was allowed at the time. */
+const wanted = ref(false)
+
+const onOpenChange = (next: boolean) => {
+  // What reka wants, kept apart from what is currently allowed.
+  wanted.value = next
+  open.value = next && !props.disabled
+  if (!open.value || !props.followCursor) return
+  // A fresh open starts at the cursor instead of flying in from wherever the
+  // last one came to rest.
+  offset.value = { x: target.x, y: target.y }
+  sx = { value: target.x, velocity: 0 }
+  sy = { value: target.y, velocity: 0 }
+  lastFrame = 0
+}
+
+/*
+ * `disabled` is driven by what the pointer is over, and that is resolved a tick
+ * AFTER reka decides to open — so an open request could arrive while the flag
+ * was still true from the last gap and be dropped on the floor. The tooltip then
+ * refused to appear until the pointer moved again, which read as "hovering does
+ * nothing any more".
+ *
+ * Remembering that a request was made, and honouring it once the obstacle
+ * clears, closes that race in the only direction that matters: enabling shows
+ * what was asked for, disabling still hides immediately.
+ */
+watch(
+  () => props.disabled,
+  (off) => {
+    if (off) open.value = false
+    else if (wanted.value) open.value = true
+  },
+)
+
+onBeforeUnmount(() => {
+  if (frame) cancelAnimationFrame(frame)
+})
 </script>
 
 <template>
   <TooltipProvider :delay-duration="delay">
-    <TooltipRoot :ignore-non-keyboard-focus="!showOnPointerFocus">
+    <!--
+      `disable-closing-trigger` in follow mode: reka dismisses a tip when its
+      trigger is clicked, which is right for a button (the tip explained the
+      thing you just did) and wrong for a chart, where clicking selects a mark
+      and the pointer never left it — the reading would vanish mid-interaction.
+    -->
+    <TooltipRoot
+      :open="open"
+      :ignore-non-keyboard-focus="!showOnPointerFocus"
+      :disable-hoverable-content="followCursor"
+      :disable-closing-trigger="followCursor"
+      @update:open="onOpenChange"
+    >
       <!-- `as-child` merges these onto the caller's own element, so the label
            lands on the real button rather than on a wrapper. -->
-      <TooltipTrigger as-child :aria-label="label ? content : undefined">
+      <TooltipTrigger
+        as-child
+        :aria-label="label ? content : undefined"
+        @pointermove="onPointerMove"
+      >
         <slot />
       </TooltipTrigger>
       <TooltipPortal>
         <TooltipContent
           :side="side"
           :side-offset="sideOffset ?? 6"
+          :collision-padding="8"
+          :data-lp-follow="followCursor ? '' : undefined"
           :class="[
             PANEL_SURFACE,
             TOOLTIP_ANIM,
             'z-(--z-tooltip) max-w-[min(20rem,90vw)] px-2.5 py-1.5 text-xs text-ink',
           ]"
+          :style="followCursor ? { translate: `${offset.x}px ${offset.y}px` } : undefined"
         >
           <slot name="content">{{ content }}</slot>
         </TooltipContent>
@@ -84,3 +247,22 @@ withDefaults(
     </TooltipRoot>
   </TooltipProvider>
 </template>
+
+<style>
+/*
+ * Unscoped: the element that has to be made transparent is reka's own
+ * positioning wrapper, which this component never renders and a scoped
+ * attribute therefore never reaches.
+ *
+ * In follow mode the tip is placed AT the cursor, so both the panel and that
+ * wrapper sit under the pointer. The panel alone being transparent was not
+ * enough — the wrapper still took the events, the trigger never received its
+ * pointerleave, and the tip stayed open: it lingered after the pointer left,
+ * a second chart could open its own on top, and a scroll left them stranded
+ * because the trigger had never been told the pointer had gone.
+ */
+:has(> [data-lp-follow]),
+[data-lp-follow] {
+  pointer-events: none;
+}
+</style>