@leavepulse/ui 0.24.1 → 0.26.0

package/src/components/LpProgress.vue

@@ -1,29 +1,306 @@
 <script setup lang="ts">
+/*
+ * One determinate value, drawn as a bar or as a ring. Both are the same data —
+ * a fraction of a whole — so they live in one component rather than two: a
+ * caller switching a KPI tile from a bar to a dial changes `variant`, not which
+ * component it imports.
+ *
+ * The ring is the bar wrapped into a circle: same tones, same clamping, same
+ * reka ProgressRoot underneath (so assistive tech reads a progressbar with a
+ * value either way).
+ */
 import { ProgressIndicator, ProgressRoot } from "reka-ui"
-import { computed } from "vue"
+import { computed, onBeforeUnmount, ref, watch } from "vue"
+import { easeOut, prefersReducedMotion } from "../composables/easing"
+import { useReveal } from "../composables/useReveal"
+import LpNumberFlow from "./LpNumberFlow.vue"
 
 const props = withDefaults(
-  defineProps<{ value?: number; max?: number; tone?: "brand" | "action" | "danger" }>(),
-  { value: 0, max: 100, tone: "brand" },
+  defineProps<{
+    value?: number
+    max?: number
+    /**
+     * `"auto"` colours by how full the bar is — calm up to `warnAt`, accent
+     * past it, danger past `dangerAt`.
+     *
+     * A gauge of a finite resource (disk, memory, quota) means something
+     * different at 92% than at 12%, and consumers were each re-deriving that
+     * with their own palette — which also put raw colours back into components
+     * the theme can no longer reach.
+     */
+    tone?: "brand" | "action" | "danger" | "accent" | "auto"
+    /** `auto` tone: the fill fraction, 0–1, where the bar turns accent. */
+    warnAt?: number
+    /** `auto` tone: the fill fraction, 0–1, where it turns danger. */
+    dangerAt?: number
+    /**
+     * Bar only: a name for what is being measured, printed above the bar. With
+     * `caption` it forms the "CPU … 42%" header a usage row wants.
+     */
+    title?: string
+    /**
+     * Bar only: the reading, printed opposite `title`. `true` prints the
+     * rounded percentage; a string says it in the units that matter
+     * ("23 GB / 64 GB"), which a percentage alone cannot.
+     */
+    caption?: boolean | string
+    /** `bar` (default) fills horizontally; `ring` draws a dial. */
+    variant?: "bar" | "ring"
+    /** Ring only: outer diameter in px. */
+    size?: number
+    /** Ring only: stroke width in px. */
+    thickness?: number
+    /**
+     * Ring only: print the rounded percentage in the middle. Pass a string to
+     * label it with something else ("12.4k", "3/8") — the ring shows progress,
+     * the caption says what it is progress of.
+     */
+    label?: boolean | string
+    /**
+     * Grow from empty on first render instead of appearing already filled.
+     *
+     * A dial that arrives complete states a fact; one that fills shows a
+     * quantity being measured, and the eye follows the sweep to where it stops —
+     * which is the number the tile is actually about. Both variants already ease
+     * every later change, so this only concerns the first paint.
+     */
+    animateOnMount?: boolean
+    /** How long the fill takes, in ms. The counter in a ring matches it. */
+    duration?: number
+  }>(),
+  {
+    value: 0,
+    max: 100,
+    tone: "brand",
+    variant: "bar",
+    size: 44,
+    thickness: 4,
+    animateOnMount: true,
+    // A resource is comfortable well past half, uncomfortable in the last
+    // fifth, and urgent in the last tenth — the thresholds a capacity gauge is
+    // read against, rather than an even split of the range.
+    warnAt: 0.8,
+    dangerAt: 0.9,
+    // Slower than the kit's `slow` step: a gauge filling is content, not state
+    // feedback, and at 320ms the sweep was over before it was noticed.
+    duration: 900,
+  },
 )
 
-const pct = computed(() => Math.max(0, Math.min(100, (props.value / props.max) * 100)))
+/*
+ * The arc and the counter are driven by ONE animated value rather than by two
+ * animations of the same length.
+ *
+ * Matching their durations is not enough: a CSS transition and LpNumberFlow's
+ * own easing decelerate on different curves, so the ring ran ahead of the
+ * figure through the middle of the sweep — and shortening one merely moved the
+ * gap to the other end. Interpolating here and handing both the same number
+ * keeps them exactly level, because there is only one number.
+ */
+const eased = ref(props.animateOnMount ? 0 : 1)
+let raf = 0
+
+/* Where the current sweep began, so one interrupted mid-way continues from the
+   arc's present position rather than snapping back to empty. */
+let from = props.animateOnMount ? 0 : props.value
+
+const runSweep = (ms: number) => {
+  if (raf) cancelAnimationFrame(raf)
+  if (prefersReducedMotion() || ms <= 0) {
+    eased.value = 1
+    return
+  }
+  const t0 = performance.now()
+  const step = (now: number) => {
+    const t = Math.min(1, (now - t0) / ms)
+    // The kit's shared curve — the same function LpNumberFlow eases on, so the
+    // arc and the counter agree by construction rather than by comment.
+    eased.value = easeOut(t)
+    raf = t < 1 ? requestAnimationFrame(step) : 0
+  }
+  raf = requestAnimationFrame(step)
+}
+
+onBeforeUnmount(() => {
+  if (raf) cancelAnimationFrame(raf)
+})
+
+/*
+ * The sweep starts when the ring is looked at, not when it is built. A row of
+ * these on a dashboard mounts all at once; started on mount, every one below
+ * the fold is already sitting at its final value by the time it is scrolled to,
+ * and the sweep — the whole point of a ring filling up — is never seen.
+ *
+ * reka's ProgressRoot is a component, so the ref holds an instance; take its
+ * host element to observe.
+ */
+const { el: revealAnchor, revealed } = useReveal({ immediate: () => !props.animateOnMount })
+
+const bindReveal = (instance: unknown) => {
+  revealAnchor.value = (instance as { $el?: Element } | null)?.$el ?? null
+}
+
+watch(revealed, (visible) => {
+  if (visible && props.animateOnMount) runSweep(props.duration)
+}, { immediate: true })
+
+/* A later change re-runs the sweep from where it stands, so the ring eases to
+   its new value instead of jumping. */
+watch(
+  () => [props.value, props.max],
+  () => {
+    from = shown.value
+    runSweep(props.duration)
+  },
+)
+
+/** The value both the arc and the counter render: one interpolation, one truth. */
+const shown = computed(() => from + (props.value - from) * eased.value)
+
+const pct = computed(() =>
+  Math.max(0, Math.min(100, (shown.value / props.max) * 100)),
+)
+
+/*
+ * The tone actually painted. `auto` reads the fill and crosses two thresholds;
+ * every other value passes straight through.
+ *
+ * Thresholds are compared against the TARGET, not the animated position, so a
+ * bar does not change colour partway through its own sweep — it fills in the
+ * colour its reading warrants.
+ */
+const paintedTone = computed(() => {
+  if (props.tone !== "auto") return props.tone
+  const fraction = props.max > 0 ? props.value / props.max : 0
+  if (fraction >= props.dangerAt) return "danger"
+  if (fraction >= props.warnAt) return "accent"
+  return "action"
+})
+
+const captionText = computed(() => {
+  if (props.caption === undefined || props.caption === false) return ""
+  return typeof props.caption === "string" ? props.caption : `${Math.round(pct.value)}%`
+})
+
 const bar: Record<string, string> = {
   brand: "bg-brand",
   action: "bg-action",
   danger: "bg-danger",
+  accent: "bg-accent",
+}
+
+const stroke: Record<string, string> = {
+  brand: "var(--color-brand)",
+  action: "var(--color-action)",
+  danger: "var(--color-danger)",
+  accent: "var(--color-accent)",
 }
+
+/*
+ * The arc is drawn by dashing the circumference: one dash as long as the filled
+ * fraction, one gap covering the rest. Rotated -90° so it starts at twelve
+ * o'clock, which is where a dial is read from.
+ */
+const radius = computed(() => (props.size - props.thickness) / 2)
+const circumference = computed(() => 2 * Math.PI * radius.value)
+
+/*
+ * Round caps add half a stroke at each end, so a nearly-full arc closes its own
+ * gap and 97% renders as a solid ring — indistinguishable from done. Hold the
+ * arc short of the seam unless the value really is complete.
+ */
+const dash = computed(() => {
+  const full = circumference.value
+  const raw = (pct.value / 100) * full
+  if (pct.value >= 100) return full
+  return Math.min(raw, full - props.thickness * 1.5)
+})
+
+/* A string label is verbatim — it isn't a number and has nothing to count. */
+const staticCaption = computed(() =>
+  typeof props.label === "string" ? props.label : null,
+)
 </script>
 
 <template>
   <ProgressRoot
+    v-if="variant === 'ring'"
+    :ref="bindReveal"
+    :model-value="value"
+    :max="max"
+    class="relative inline-flex shrink-0 items-center justify-center"
+    :style="{ width: `${size}px`, height: `${size}px` }"
+  >
+    <svg :width="size" :height="size" class="-rotate-90">
+      <circle
+        :cx="size / 2"
+        :cy="size / 2"
+        :r="radius"
+        fill="none"
+        stroke="var(--color-surface-soft)"
+        :stroke-width="thickness"
+      />
+      <circle
+        :cx="size / 2"
+        :cy="size / 2"
+        :r="radius"
+        fill="none"
+        :stroke="stroke[paintedTone]"
+        :stroke-width="thickness"
+        stroke-linecap="round"
+        :stroke-dasharray="`${dash} ${circumference - dash}`"
+      />
+    </svg>
+    <!-- Reads the same interpolated value as the arc — no animation of its own,
+         or the two would drift apart again. -->
+    <span
+      v-if="label !== false && label !== undefined"
+      class="absolute font-mono text-[11px] font-medium text-ink"
+    >
+      <template v-if="staticCaption">{{ staticCaption }}</template>
+      <LpNumberFlow
+        v-else
+        :value="pct"
+        suffix="%"
+        :duration="0"
+        :animate-on-mount="false"
+        :style="{ '--lp-nf-spin': '90ms' }"
+      />
+    </span>
+  </ProgressRoot>
+
+  <!-- Wrapped only when there is a header to carry. A bare bar stays the single
+       element it has always been, so an existing caller's layout is untouched. -->
+  <div v-else-if="title || captionText" class="flex w-full flex-col gap-1">
+    <div class="flex items-baseline justify-between gap-2 text-xs">
+      <span class="text-muted">{{ title }}</span>
+      <!-- Tabular, so a figure ticking upward doesn't shuffle its own width. -->
+      <span class="font-mono tabular-nums text-muted-strong">{{ captionText }}</span>
+    </div>
+    <ProgressRoot
+      :ref="bindReveal"
+      :model-value="value"
+      :max="max"
+      class="h-1.5 w-full overflow-hidden rounded-pill bg-surface-soft"
+    >
+      <ProgressIndicator
+        class="h-full rounded-pill transition-colors duration-medium"
+        :class="bar[paintedTone]"
+        :style="{ width: `${pct}%` }"
+      />
+    </ProgressRoot>
+  </div>
+
+  <ProgressRoot
+    v-else
+    :ref="bindReveal"
     :model-value="value"
     :max="max"
     class="h-1.5 w-full overflow-hidden rounded-pill bg-surface-soft"
   >
     <ProgressIndicator
-      class="h-full rounded-pill transition-[width] duration-slow ease-[var(--ease-emphasized)]"
-      :class="bar[tone]"
+      class="h-full rounded-pill transition-colors duration-medium"
+      :class="bar[paintedTone]"
       :style="{ width: `${pct}%` }"
     />
   </ProgressRoot>

package/src/components/LpRollingText.vue

@@ -0,0 +1,157 @@
+<script setup lang="ts">
+/*
+ * Text that CHANGES rather than being replaced.
+ *
+ * Swapping a label in place gives the reader nothing: they see the new value
+ * and have no idea it used to be something else. Moving the old one out while
+ * the new one arrives makes the change itself visible — which is the whole
+ * point in a spot that updates while being watched: a donut's centre following
+ * the hovered slice, a live counter's caption, a status line.
+ *
+ * Two motions, because they say different things:
+ *
+ *   "slide" — the old line leaves upward, the new one arrives from below (or
+ *     the reverse, per `direction`). Reads as a reel advancing: same kind of
+ *     thing, next item. The default.
+ *   "flip"  — the box turns on its X axis, the old face rotating away and the
+ *     new one turning in behind it. Reads as one object showing another side;
+ *     heavier, so it suits a headline that changes rarely.
+ *
+ *   <LpRollingText :value="label" />
+ *   <LpRollingText :value="status" mode="flip" />
+ */
+import { computed } from "vue"
+
+const props = withDefaults(
+  defineProps<{
+    /** The text. A change to this is what triggers the transition. */
+    value: string | number
+    mode?: "slide" | "flip"
+    /** Which way "slide" travels. `up` moves the old text up and out. */
+    direction?: "up" | "down"
+    duration?: number
+    /**
+     * Alignment inside the clipped box, for when the two values differ in
+     * width — a value that grows shouldn't shove its neighbours.
+     */
+    align?: "start" | "center" | "end"
+  }>(),
+  { mode: "slide", direction: "up", duration: 320, align: "center" },
+)
+
+/* The key is what makes Vue treat a new value as a new element rather than a
+   text patch — without it there is nothing to transition between. */
+const key = computed(() => String(props.value))
+
+const name = computed(() =>
+  props.mode === "flip" ? "lp-roll-flip" : `lp-roll-${props.direction}`,
+)
+
+const justify = computed(
+  () =>
+    ({ start: "justify-start", center: "justify-center", end: "justify-end" })[props.align],
+)
+
+const style = computed(() => ({
+  "--lp-roll-duration": `${props.duration}ms`,
+  // The leaving copy is taken out of flow so both can occupy the same line;
+  // without this the box would grow to hold two lines mid-transition.
+  "--lp-roll-perspective": props.mode === "flip" ? "300px" : "none",
+}))
+</script>
+
+<template>
+  <span
+    class="lp-roll relative inline-flex overflow-hidden align-bottom"
+    :class="justify"
+    :style="style"
+  >
+    <Transition :name="name">
+      <span :key="key" class="lp-roll__item">
+        <slot :value="value">{{ value }}</slot>
+      </span>
+    </Transition>
+  </span>
+</template>
+
+<style>
+/*
+ * Unscoped on purpose: the transition classes are applied to the element Vue
+ * clones during the leave phase, which a scoped attribute selector doesn't
+ * reliably reach. Everything is namespaced under .lp-roll instead.
+ */
+.lp-roll {
+  perspective: var(--lp-roll-perspective);
+}
+
+.lp-roll__item {
+  display: inline-block;
+  white-space: nowrap;
+  backface-visibility: hidden;
+}
+
+/* The outgoing copy leaves the flow so the incoming one keeps the baseline. */
+.lp-roll-up-leave-active,
+.lp-roll-down-leave-active,
+.lp-roll-flip-leave-active {
+  position: absolute;
+  inset: 0;
+}
+
+.lp-roll-up-enter-active,
+.lp-roll-up-leave-active,
+.lp-roll-down-enter-active,
+.lp-roll-down-leave-active {
+  transition:
+    transform var(--lp-roll-duration) var(--ease-emphasized),
+    opacity var(--lp-roll-duration) var(--ease-emphasized);
+}
+
+.lp-roll-up-enter-from {
+  transform: translateY(100%);
+  opacity: 0;
+}
+.lp-roll-up-leave-to {
+  transform: translateY(-100%);
+  opacity: 0;
+}
+
+.lp-roll-down-enter-from {
+  transform: translateY(-100%);
+  opacity: 0;
+}
+.lp-roll-down-leave-to {
+  transform: translateY(100%);
+  opacity: 0;
+}
+
+.lp-roll-flip-enter-active,
+.lp-roll-flip-leave-active {
+  transition:
+    transform var(--lp-roll-duration) var(--ease-emphasized),
+    opacity calc(var(--lp-roll-duration) * 0.6) linear;
+  transform-origin: center center;
+}
+
+/* Quarter turns, not halves: the two faces meet edge-on at the midpoint, so
+   the box reads as turning rather than as one label briefly vanishing. */
+.lp-roll-flip-enter-from {
+  transform: rotateX(-90deg);
+  opacity: 0;
+}
+.lp-roll-flip-leave-to {
+  transform: rotateX(90deg);
+  opacity: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .lp-roll-up-enter-active,
+  .lp-roll-up-leave-active,
+  .lp-roll-down-enter-active,
+  .lp-roll-down-leave-active,
+  .lp-roll-flip-enter-active,
+  .lp-roll-flip-leave-active {
+    transition: none;
+  }
+}
+</style>

package/src/components/LpSkeleton.vue

@@ -1,16 +1,89 @@
 <script setup lang="ts">
-// Loading placeholder. Sizing comes from the consumer's classes (w-/h-).
+/*
+ * Loading placeholder, in two shapes.
+ *
+ * Bare, it is one pulsing block and the consumer's classes size it:
+ *
+ *   <LpSkeleton class="h-4 w-40" />
+ *
+ * Given content, it becomes a WRAPPER instead: it stops pulsing itself and
+ * lends the pulse to any `.lp-skeleton-item` inside it, however deeply nested.
+ *
+ *   <LpSkeleton class="space-y-3">
+ *     <div class="flex items-center gap-3">
+ *       <div class="lp-skeleton-item size-10 rounded-pill" />
+ *       <div class="lp-skeleton-item h-4 w-32" />
+ *     </div>
+ *   </LpSkeleton>
+ *
+ * The second form exists because a real skeleton is a LAYOUT, not a stack of
+ * bars: a profile header is an avatar beside two lines of different widths
+ * above a button. Expressed as one component per block, that is a dozen
+ * <LpSkeleton> tags whose grid has to be rebuilt by hand and kept in step with
+ * the markup it stands in for. As a wrapper, the skeleton can be the real
+ * markup with its content swapped for plain divs — same flex, same gaps, same
+ * responsive classes — so it keeps matching the thing it is standing in for.
+ *
+ * Consumers had already arrived at this and built it themselves; it belongs
+ * here, where every app gets it.
+ */
+import { computed, useSlots } from "vue"
+
 defineProps<{ rounded?: "control" | "card" | "pill" }>()
+
+const slots = useSlots()
+
+/* A wrapper must not pulse as a whole — the container would flash behind its
+   own items. Only the bare form is a placeholder in its own right. */
+const isBlock = computed(() => !slots.default)
 </script>
 
 <template>
   <div
     aria-hidden="true"
-    class="animate-pulse bg-surface-soft"
-    :class="{
-      'rounded-control': rounded === 'control' || !rounded,
-      'rounded-card': rounded === 'card',
-      'rounded-pill': rounded === 'pill',
-    }"
-  />
+    class="lp-skeleton"
+    :class="[
+      isBlock ? 'lp-skeleton-item bg-surface-soft' : '',
+      {
+        'rounded-control': isBlock && (rounded === 'control' || !rounded),
+        'rounded-card': rounded === 'card',
+        'rounded-pill': rounded === 'pill',
+      },
+    ]"
+  >
+    <slot />
+  </div>
 </template>
+
+<style>
+/*
+ * Unscoped: the items are written by the CONSUMER, inside the slot, so they
+ * carry no scope attribute of this component — a scoped rule could never reach
+ * them. Namespaced instead, and only ever applied under `.lp-skeleton`.
+ *
+ * One shared animation name means every item on the page pulses in phase: CSS
+ * animations are timed against the document, not against when each element
+ * mounted, so a skeleton that fills in progressively stays in step with itself.
+ */
+.lp-skeleton-item {
+  animation: lp-skeleton-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+/* Items nested anywhere inside a wrapper, at any depth. */
+.lp-skeleton .lp-skeleton-item {
+  animation: lp-skeleton-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+@keyframes lp-skeleton-pulse {
+  50% {
+    opacity: 0.5;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .lp-skeleton-item {
+    animation: none;
+    opacity: 0.75;
+  }
+}
+</style>