@leavepulse/ui 0.71.2 → 0.72.1

package/src/components/LpSidebarNav.vue

@@ -12,19 +12,15 @@ export default { inheritAttrs: false }
  * in two shells — the static desktop rail and the swipeable mobile drawer —
  * without duplicating markup. Not exported on its own; an LpSidebar detail.
  */
-import { Motion } from "motion-v"
 import { CollapsibleContent, CollapsibleRoot, CollapsibleTrigger } from "reka-ui"
 import { computed, ref } from "vue"
-import { useLocale } from "../composables/useLocale"
-import { usePillTransition } from "../composables/usePillTransition"
 import LpBadge from "./LpBadge.vue"
 import LpContextMenu from "./LpContextMenu.vue"
 import LpIcon from "./LpIcon.vue"
 import LpScrollArea from "./LpScrollArea.vue"
 import LpSkeleton from "./LpSkeleton.vue"
-import type { SidebarItem, SidebarSection } from "./sidebar"
-import { resolveLink, type ResolvedLink } from "./link"
-import { useLinkComponent } from "../composables/useLpConfig"
+import LpSidebarRow from "./LpSidebarRow.vue"
+import { waiting, type SidebarItem, type SidebarSection } from "./sidebar"
 import { useMergedAttrs } from "../composables/useMergedClass"
 
 const props = withDefaults(
@@ -52,22 +48,24 @@ const props = withDefaults(
      * short rail (an app switcher, a settings list) can turn it on.
      */
     hoverFollow?: boolean
+    /** Icons only, each row's name in a card beside it. */
+    compact?: boolean
+    /** Rows offer "Pin to top" in their menu; `pinned` are shown first. */
+    pinnable?: boolean
+    pinned?: SidebarItem[]
+    previewDelay?: number
+    labels: { pinned: string; pin: string; unpin: string; expand: string }
   }>(),
-  { skeletonRows: 6, skeletonHeader: true, collapsedKeys: () => [], hoverFollow: false },
+  { skeletonRows: 6, skeletonHeader: true, collapsedKeys: () => [], hoverFollow: false, pinned: () => [], previewDelay: 900 },
 )
 
 const emit = defineEmits<{
   (e: "activate", item: SidebarItem): void
   (e: "toggle-section", key: string, collapsed: boolean): void
+  (e: "toggle-pin", id: string): void
 }>()
 
 /** `key` when the app set one, else the title — see SidebarSection.key. */
-// A count reads in the app's locale like every other figure: "7 563", not "7563".
-const locale = useLocale()
-function badgeText(badge: number | string): string {
-  return typeof badge === "number" ? badge.toLocaleString(locale.value) : badge
-}
-
 function sectionKey(section: SidebarSection): string {
   return section.key ?? section.title ?? ""
 }
@@ -80,7 +78,7 @@ function sectionKey(section: SidebarSection): string {
 const foldedKeys = computed(() => {
   const holdsActive = new Set(
     props.groups
-      .filter((g) => g.items.some((i) => props.itemActive(i)))
+      .filter((g) => g.items.some((i) => props.itemActive(i) || onPath(i)))
       .map(sectionKey),
   )
   return new Set(
@@ -89,11 +87,10 @@ const foldedKeys = computed(() => {
 })
 
 function isOpen(section: SidebarSection): boolean {
-  return !foldedKeys.value.has(sectionKey(section))
+  // Compact, a group has no heading to unfold it by.
+  return props.compact || !foldedKeys.value.has(sectionKey(section))
 }
 
-const pillTransition = usePillTransition()
-
 const hovered = ref<string | null>(null)
 
 function hover(item: SidebarItem) {
@@ -105,16 +102,112 @@ function pillUnder(item: SidebarItem): boolean {
   return hovered.value ? hovered.value === item.id : props.itemActive(item)
 }
 
-const linkComponent = useLinkComponent()
+/** One of the item's pages is the current one. */
+function onPath(item: SidebarItem): boolean {
+  return !!item.children?.some((c) => props.itemActive(c))
+}
+
+// Pages under a row open with the current page among them and otherwise when
+// asked; the asked-for ones are remembered for as long as the nav lives.
+const opened = ref(new Set<string>())
+function expanded(item: SidebarItem): boolean {
+  return onPath(item) || opened.value.has(item.id)
+}
+function toggle(item: SidebarItem) {
+  const next = new Set(opened.value)
+  if (next.has(item.id)) next.delete(item.id)
+  else next.add(item.id)
+  opened.value = next
+}
+
+const pinnedIds = computed(() => new Set(props.pinned.map((i) => i.id)))
+function menuOf(item: SidebarItem) {
+  const own = item.menu ?? []
+  if (!props.pinnable) return own
+  const pinned = pinnedIds.value.has(item.id)
+  return [
+    ...own,
+    {
+      label: pinned ? props.labels.unpin : props.labels.pin,
+      icon: pinned ? "lucide:pin-off" : "lucide:pin",
+      separatorBefore: own.length > 0,
+      onSelect: () => emit("toggle-pin", item.id),
+    },
+  ]
+}
 
 /*
- * A disabled item is always a disabled button: an anchor cannot be disabled,
- * and the old enabled-button fallback for a disabled link stayed focusable.
+ * The keyboard, as a tree: arrows walk the rows that are showing, right and
+ * left open and close a group or the pages under a row (left from such a page
+ * goes back to its row), Home and End jump to the ends, and typing jumps to the
+ * next row starting with what was typed. Tab still reaches every row, so this
+ * only adds a faster way through a long nav.
  */
-function rowOf(item: SidebarItem): ResolvedLink {
-  const link = item.disabled ? null : resolveLink(linkComponent.value, { to: item.to, href: item.href })
-  if (link) return link
-  return { is: "button", props: { type: "button", disabled: item.disabled || undefined } }
+let typed = ""
+let typedAt = 0
+
+function onKey(event: KeyboardEvent) {
+  const box = event.currentTarget as HTMLElement
+  const list = [...box.querySelectorAll<HTMLElement>("[data-lp-nav-row]")].filter((r) => r.offsetParent !== null)
+  const at = list.indexOf(document.activeElement as HTMLElement)
+  if (at < 0) return
+  const row = list[at]!
+  const go = (i: number) => {
+    event.preventDefault()
+    list[(i + list.length) % list.length]?.focus()
+  }
+  switch (event.key) {
+    case "ArrowDown":
+      return go(at + 1)
+    case "ArrowUp":
+      return go(at - 1)
+    case "Home":
+      return go(0)
+    case "End":
+      return go(list.length - 1)
+    case "ArrowRight":
+    case "ArrowLeft": {
+      const open = event.key === "ArrowRight"
+      const toggle = row.hasAttribute("aria-expanded")
+        ? row
+        : row.parentElement?.querySelector<HTMLElement>(":scope > button[aria-expanded]")
+      if (toggle && (toggle.getAttribute("aria-expanded") === "true") !== open) {
+        event.preventDefault()
+        toggle.click()
+        return
+      }
+      if (!open && row.dataset.lpNavNested !== undefined) {
+        for (let i = at - 1; i >= 0; i--) if (list[i]!.dataset.lpNavNested === undefined) return go(i)
+      }
+      return
+    }
+  }
+  if (event.key.length !== 1 || event.ctrlKey || event.metaKey || event.altKey) return
+  const now = Date.now()
+  typed = now - typedAt > 700 ? event.key : typed + event.key
+  typedAt = now
+  const needle = typed.toLocaleLowerCase()
+  for (let k = 1; k <= list.length; k++) {
+    const next = list[(at + k) % list.length]!
+    if ((next.textContent ?? "").trim().toLocaleLowerCase().startsWith(needle)) return go(at + k)
+  }
+}
+
+const SECTION = "lp-section:"
+function sectionItem(section: SidebarSection): SidebarItem {
+  const icon = section.icon ?? section.items.find((i) => i.icon)?.icon
+  return {
+    id: `${SECTION}${sectionKey(section)}`,
+    label: section.title ?? "",
+    icon,
+    children: section.items,
+  }
+}
+
+function activate(item: SidebarItem) {
+  if (item.id.startsWith(SECTION)) return
+  if (item.children?.length && !item.to && !item.href) toggle(item)
+  emit("activate", item)
 }
 
 // The nav fills the remaining height with a fixed gap between groups; a short sidebar needs both under the consumer's control.
@@ -151,12 +244,51 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
   <LpScrollArea
     v-else
     class="min-h-0 flex-1"
-    content-class="flex min-h-full flex-col gap-4"
+    :content-class="compact ? 'flex min-h-full flex-col gap-1' : 'flex min-h-full flex-col gap-4'"
     @pointerleave="hovered = null"
   >
+    <!-- `contents`: no box of its own, only somewhere for the rows' keys to bubble to. -->
+    <div class="contents" @keydown="onKey">
+    <!-- Pinned pages come first and carry no pill: the same page further down
+         already holds it, and one pill shared by two rows would jump between
+         them. -->
+    <div v-if="pinned.length" class="flex flex-col gap-0.5">
+      <p v-if="!compact" class="px-2 pb-1 pt-2 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted">
+        {{ labels.pinned }}
+      </p>
+      <LpSidebarRow
+        v-for="item in pinned"
+        :key="`pinned:${item.id}`"
+        :item="item"
+        :active="itemActive(item)"
+        :pill="false"
+        :pill-id="pillId"
+        :compact="compact"
+        :menu="menuOf(item)"
+        :preview-delay="previewDelay"
+        :item-active="itemActive"
+        @activate="activate"
+      />
+    </div>
+    <template v-for="(section, si) in groups" :key="si">
+    <!-- Compact, a group that folds is one icon: its pages open in the card
+         beside it, as a page's own pages do. A hundred initials in a column
+         would be no nav at all. -->
+    <div v-if="compact && section.collapsible && section.title" class="flex flex-col gap-0.5">
+      <LpSidebarRow
+        :item="sectionItem(section)"
+        :active="false"
+        :pill="false"
+        :pill-id="pillId"
+        compact
+        :on-path="section.items.some((i) => itemActive(i) || onPath(i))"
+        :preview-delay="previewDelay"
+        :item-active="itemActive"
+        @activate="activate"
+      />
+    </div>
     <CollapsibleRoot
-      v-for="(section, si) in groups"
-      :key="si"
+      v-else
       as="div"
       class="flex flex-col gap-0.5"
       :open="isOpen(section)"
@@ -165,8 +297,10 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
     >
       <!-- A plain heading while the group is fixed; a control once it folds,
            because a thing that reacts to a click must look like one. -->
+      <div v-if="compact && (si > 0 || pinned.length)" class="mx-3 mb-1 border-t border-line" />
       <CollapsibleTrigger
-        v-if="section.title && section.collapsible"
+        v-else-if="!compact && section.title && section.collapsible"
+        data-lp-nav-row
         class="group/section mt-2 flex cursor-pointer items-center gap-2 rounded-control px-2 py-1 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:bg-ink/[0.04] hover:text-ink focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring"
       >
         <LpIcon
@@ -182,6 +316,11 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
              It is always rendered and merely fades, never removed: taking it
              out of the row changes the heading's height, and a heading that
              resizes under the cursor makes its own click feel like a misfire. -->
+        <span
+          v-if="section.items.some(waiting)"
+          class="size-1.5 shrink-0 rounded-full bg-brand transition-opacity duration-[var(--duration-fast)] motion-reduce:transition-none"
+          :class="isOpen(section) ? 'opacity-0' : 'opacity-100'"
+        />
         <LpBadge
           tone="neutral"
           class="shrink-0 transition-opacity duration-[var(--duration-fast)] motion-reduce:transition-none"
@@ -197,7 +336,7 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
         />
       </CollapsibleTrigger>
       <p
-        v-else-if="section.title"
+        v-else-if="!compact && section.title"
         class="px-2 pb-1 pt-2 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted"
       >
         {{ section.title }}
@@ -206,58 +345,52 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
       <CollapsibleContent
         class="flex flex-col gap-0.5 overflow-hidden data-[state=open]:animate-[collapsible-down_260ms_var(--ease-emphasized)] data-[state=closed]:animate-[collapsible-up_200ms_var(--ease-emphasized)] motion-reduce:animate-none"
       >
-      <!-- Optional right-click menu per item; passthrough when item.menu is
-           absent or empty, so the item keeps the native context menu. Headed
-           by the item's label and icon unless it names its own. -->
-      <LpContextMenu
-        v-for="item in section.items"
-        :key="item.id"
-        :items="item.menu ?? []"
-        :title="(item.menuTitle ?? item.label) || undefined"
-        :title-icon="item.icon"
-      >
-        <component
-          :is="rowOf(item).is"
-          v-bind="rowOf(item).props"
-          :aria-current="itemActive(item) ? 'page' : undefined"
-          :aria-disabled="item.disabled || undefined"
-          class="group/item relative flex items-center gap-3 rounded-control px-3 py-2 text-sm font-medium outline-none transition-colors duration-[var(--duration-fast)] focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring"
-          :class="item.disabled
-            ? 'cursor-not-allowed text-muted/50'
-            : itemActive(item) || hovered === item.id
-              ? 'text-ink'
-              : 'text-muted hover:text-ink'"
-          @click="emit('activate', item)"
-          @pointerenter="hover(item)"
+      <template v-for="item in section.items" :key="item.id">
+        <LpSidebarRow
+          :item="item"
+          :active="itemActive(item)"
+          :pill="pillUnder(item)"
+          :pill-id="pillId"
+          :compact="compact"
+          :menu="menuOf(item)"
+          :expandable="!compact && !!item.children?.length"
+          :expanded="expanded(item)"
+          :on-path="onPath(item)"
+          :preview-delay="previewDelay"
+          :hovered="hovered === item.id"
+          :expand-label="labels.expand"
+          :item-active="itemActive"
+          @activate="activate"
+          @hover="hover"
+          @toggle="toggle(item)"
         >
-          <!-- Sliding active pill -->
-          <Motion
-            v-if="pillUnder(item)"
-            :layout-id="pillId"
-            :transition="pillTransition"
-            class="absolute inset-0 z-0 rounded-control bg-brand-soft"
-          />
-          <!-- #item slot for fully custom rows; falls back to icon+label+badge. -->
-          <slot name="item" :item="item" :active="itemActive(item)">
-            <LpIcon
-              v-if="item.icon"
-              :name="item.icon"
-              :size="17"
-              class="relative z-10 shrink-0 transition-colors"
-              :class="itemActive(item) ? 'text-brand' : ''"
+          <template v-if="$slots.item" #default="slotProps"><slot name="item" v-bind="slotProps" /></template>
+        </LpSidebarRow>
+        <CollapsibleRoot v-if="!compact && item.children?.length" :open="expanded(item)">
+          <CollapsibleContent
+            class="flex flex-col gap-0.5 overflow-hidden data-[state=open]:animate-[collapsible-down_220ms_var(--ease-emphasized)] data-[state=closed]:animate-[collapsible-up_180ms_var(--ease-emphasized)] motion-reduce:animate-none"
+          >
+            <LpSidebarRow
+              v-for="child in item.children"
+              :key="child.id"
+              nested
+              :item="child"
+              :active="itemActive(child)"
+              :pill="pillUnder(child)"
+              :pill-id="pillId"
+              :menu="menuOf(child)"
+              :preview-delay="previewDelay"
+              :hovered="hovered === child.id"
+              :item-active="itemActive"
+              @activate="activate"
+              @hover="hover"
             />
-            <span class="relative z-10 min-w-0 flex-1 truncate text-left">{{ item.label }}</span>
-            <LpBadge
-              v-if="item.badge != null"
-              :tone="itemActive(item) ? 'brand' : 'neutral'"
-              class="relative z-10 shrink-0"
-            >
-              {{ badgeText(item.badge) }}
-            </LpBadge>
-          </slot>
-        </component>
-      </LpContextMenu>
+          </CollapsibleContent>
+        </CollapsibleRoot>
+      </template>
       </CollapsibleContent>
     </CollapsibleRoot>
+    </template>
+    </div>
   </LpScrollArea>
 </template>

package/src/components/LpSidebarRow.vue

@@ -0,0 +1,242 @@
+<script setup lang="ts">
+/*
+ * One row of LpSidebarNav: the link or button, its active pill, icon, label,
+ * count and keys, its right-click menu and the card beside it. A page, a page
+ * under another and a pinned page are drawn by this one component, so the
+ * three never disagree on what a row looks like. Not exported on its own.
+ *
+ * The card beside the row does two jobs that are one mechanism: in a compact
+ * sidebar it is the row's name (and the pages under it), since the row shows
+ * only an icon; with a `preview` it is a glance at the page before going there.
+ */
+import { Motion } from "motion-v"
+import { computed, onBeforeUnmount, ref, watch } from "vue"
+import { useLocale } from "../composables/useLocale"
+import { usePillTransition } from "../composables/usePillTransition"
+import { useLinkComponent } from "../composables/useLpConfig"
+import LpBadge from "./LpBadge.vue"
+import LpContextMenu, { type ContextMenuItemDef } from "./LpContextMenu.vue"
+import LpHoverCard from "./LpHoverCard.vue"
+import LpIcon from "./LpIcon.vue"
+import LpKeys from "./LpKeys.vue"
+import LpNumberFlow from "./LpNumberFlow.vue"
+import { waiting, type SidebarItem } from "./sidebar"
+import { resolveLink, type ResolvedLink } from "./link"
+
+const props = withDefaults(
+  defineProps<{
+    item: SidebarItem
+    active: boolean
+    /** The pill sits under this row (active, or hovered while following hover). */
+    pill: boolean
+    pillId: string
+    compact?: boolean
+    /** A page under another: indented, a size smaller. */
+    nested?: boolean
+    menu?: ContextMenuItemDef[]
+    /** Has pages under it; `expanded` says whether they show. */
+    expandable?: boolean
+    expanded?: boolean
+    /** One of its pages is the current one: the row reads as on the path. */
+    onPath?: boolean
+    previewDelay?: number
+    hovered?: boolean
+    expandLabel?: string
+    itemActive?: (item: SidebarItem) => boolean
+  }>(),
+  { previewDelay: 900, menu: () => [] },
+)
+
+const emit = defineEmits<{
+  (e: "activate", item: SidebarItem): void
+  (e: "hover", item: SidebarItem): void
+  (e: "toggle"): void
+}>()
+
+const locale = useLocale()
+const pillTransition = usePillTransition()
+const linkComponent = useLinkComponent()
+
+/*
+ * A disabled item is always a disabled button: an anchor cannot be disabled,
+ * and the old enabled-button fallback for a disabled link stayed focusable.
+ */
+function rowOf(item: SidebarItem): ResolvedLink {
+  const link = item.disabled ? null : resolveLink(linkComponent.value, { to: item.to, href: item.href })
+  if (link) return link
+  return { is: "button", props: { type: "button", disabled: item.disabled || undefined } }
+}
+
+// A count that grows pulses once: a number that changes in place is easy to
+// miss in the corner of the eye, and the nav is exactly the corner of the eye.
+const bumped = ref(false)
+let bumpTimer: ReturnType<typeof setTimeout> | undefined
+watch(
+  () => props.item.badge,
+  (now, was) => {
+    if (typeof now !== "number" || typeof was !== "number" || now <= was) return
+    bumped.value = true
+    clearTimeout(bumpTimer)
+    bumpTimer = setTimeout(() => (bumped.value = false), 1200)
+  },
+)
+onBeforeUnmount(() => clearTimeout(bumpTimer))
+
+/** A compact row without an icon shows the first letters of its name. */
+const initials = computed(() =>
+  props.item.label
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((w) => [...w][0])
+    .join(""),
+)
+
+// Something waiting on a page under this row shows on the row while those pages
+// are out of sight, folded away or behind a compact icon: otherwise closing a
+// group would hide that anything is waiting in it.
+const hidden = computed(() => (props.compact || !props.expanded) && !!props.item.children?.some(waiting))
+const hasBadge = computed(() => props.item.badge != null || !!props.item.dot || hidden.value)
+const card = computed(() => !props.item.disabled && (props.compact || !!props.item.preview))
+const delay = computed(() => (props.compact && !props.item.preview ? 250 : props.previewDelay))
+</script>
+
+<template>
+  <LpHoverCard
+      :disabled="!card"
+      side="right"
+      align="start"
+      :side-offset="compact ? 12 : 16"
+      :open-delay="delay"
+      :close-delay="120"
+      touch="none"
+      :panel-class="item.preview ? 'w-80 p-0 overflow-hidden' : 'w-56 p-2'"
+    >
+      <!-- The card anchors on a plain box: the context menu inside it renders a
+           fragment, which an as-child trigger cannot take. -->
+      <template #trigger>
+        <div class="relative flex flex-col">
+        <LpContextMenu :items="menu" :title="(item.menuTitle ?? item.label) || undefined" :title-icon="item.icon">
+        <component
+          :is="rowOf(item).is"
+          v-bind="rowOf(item).props"
+          :aria-current="active ? 'page' : undefined"
+          :aria-disabled="item.disabled || undefined"
+          :aria-label="compact ? item.label : undefined"
+          data-lp-nav-row
+          :aria-keyshortcuts="item.hotkey"
+          :aria-busy="item.busy ? true : undefined"
+          :data-lp-nav-nested="nested || undefined"
+          class="group/item relative flex items-center rounded-control font-medium outline-none transition-colors duration-[var(--duration-fast)] focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring"
+          :class="[
+            compact ? ['ml-1 size-10 justify-center', onPath && !active ? 'bg-ink/[0.06]' : ''] : nested ? 'gap-2.5 py-1.5 pl-9 pr-3 text-[13px]' : 'gap-3 px-3 py-2 text-sm',
+            item.disabled
+              ? 'cursor-not-allowed text-muted/50'
+              : active || hovered || onPath
+                ? 'text-ink'
+                : 'text-muted hover:text-ink',
+          ]"
+          @click="emit('activate', item)"
+          @pointerenter="emit('hover', item)"
+        >
+          <span
+            v-if="item.busy !== undefined && item.busy !== false"
+            class="pointer-events-none absolute bottom-0.5 z-10 h-0.5 overflow-hidden rounded-pill bg-brand/15"
+            :class="compact ? 'inset-x-2' : 'inset-x-3'"
+          >
+            <span
+              v-if="typeof item.busy === 'number'"
+              class="block h-full rounded-pill bg-brand transition-[width] duration-(--duration-medium) ease-[var(--ease-emphasized)]"
+              :style="{ width: `${Math.round(Math.min(1, Math.max(0, item.busy)) * 100)}%` }"
+            />
+            <span v-else class="lp-sweep absolute inset-y-0 left-0 w-2/5 rounded-pill bg-brand" />
+          </span>
+          <Motion v-if="pill" :layout-id="pillId" :transition="pillTransition" class="absolute inset-0 z-0 rounded-control bg-brand-soft" />
+          <slot :item="item" :active="active">
+            <span v-if="item.icon" class="relative z-10 shrink-0">
+              <LpIcon :name="item.icon" :size="nested ? 15 : 17" class="transition-colors" :class="active ? 'text-brand' : ''" />
+              <!-- Compact, the count has no room: a dot on the icon says there is one. -->
+              <span
+                v-if="compact && hasBadge"
+                class="absolute -right-1 -top-1 size-2 rounded-full bg-brand ring-2 ring-surface-raised"
+                :class="bumped ? 'animate-pulse' : ''"
+              />
+            </span>
+            <span v-else-if="compact" class="relative z-10 text-xs font-semibold uppercase">{{ initials }}</span>
+            <span v-else-if="nested" class="relative z-10 size-1 shrink-0 rounded-full bg-current opacity-50" />
+            <template v-if="!compact">
+              <span class="relative z-10 min-w-0 flex-1 truncate text-left">{{ item.label }}</span>
+              <!-- Over the row's end and only where nothing else sits there: in
+                   the flow, keys that show on hover would take the label's
+                   width even while hidden. -->
+              <LpKeys
+                v-if="item.hotkey && !hasBadge && !expandable"
+                :combo="item.hotkey"
+                size="sm"
+                aria-hidden="true"
+                class="pointer-events-none absolute right-2 z-10 rounded-small bg-surface-raised/90 opacity-0 transition-opacity duration-(--duration-fast) group-hover/item:opacity-100 group-focus-visible/item:opacity-100"
+              />
+              <span v-if="hasBadge && item.badge == null" class="relative z-10 size-2 shrink-0 rounded-full bg-brand" />
+              <LpBadge v-if="item.badge != null" :tone="active ? 'brand' : 'neutral'" class="relative z-10 shrink-0">
+                <span v-if="bumped" class="absolute inset-0 animate-ping rounded-pill bg-brand/30" />
+                <LpNumberFlow v-if="typeof item.badge === 'number'" :value="item.badge" grouped :locale="locale" :animate-on-mount="false" />
+                <template v-else>{{ item.badge }}</template>
+              </LpBadge>
+              <span v-if="expandable" class="w-5 shrink-0" aria-hidden="true" />
+            </template>
+          </slot>
+        </component>
+        </LpContextMenu>
+        <!-- Beside the row, not inside it: a control within the link or button
+             would be one control to a screen reader, and the pages under a
+             link have to open without following it. -->
+        <button
+          v-if="expandable && !compact"
+          type="button"
+          class="absolute right-2 top-1/2 z-20 grid size-6 -translate-y-1/2 place-items-center rounded-small text-muted outline-none transition-colors hover:bg-ink/[0.06] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
+          :aria-label="expandLabel"
+          :aria-expanded="expanded"
+          @click="emit('toggle')"
+        >
+          <LpIcon
+            name="lucide:chevron-right"
+            :size="14"
+            class="transition-transform duration-(--duration-fast) ease-[var(--ease-emphasized)] motion-reduce:transition-none"
+            :class="expanded ? 'rotate-90' : ''"
+          />
+        </button>
+        </div>
+      </template>
+
+      <div v-if="item.preview" class="flex flex-col">
+        <div v-if="compact" class="flex items-center gap-2 border-b border-line px-3 py-2 text-sm font-medium text-ink">
+          <span class="min-w-0 flex-1 truncate">{{ item.label }}</span>
+          <LpKeys v-if="item.hotkey" :combo="item.hotkey" size="sm" />
+        </div>
+        <component :is="item.preview" />
+      </div>
+      <div v-else class="flex flex-col gap-0.5">
+        <div class="flex items-center gap-2 px-2 py-1 text-sm font-medium text-ink">
+          <span class="min-w-0 flex-1 truncate">{{ item.label }}</span>
+          <LpBadge v-if="item.badge != null" tone="neutral">{{ typeof item.badge === "number" ? item.badge.toLocaleString(locale) : item.badge }}</LpBadge>
+          <LpKeys v-if="item.hotkey" :combo="item.hotkey" size="sm" />
+        </div>
+        <div v-if="item.children?.length" class="flex max-h-[min(70vh,30rem)] flex-col gap-0.5 overflow-y-auto">
+          <component
+            :is="rowOf(child).is"
+            v-for="child in item.children"
+            :key="child.id"
+            v-bind="rowOf(child).props"
+            :aria-current="itemActive?.(child) ? 'page' : undefined"
+            class="flex shrink-0 items-center gap-2 rounded-control px-2 py-1.5 text-left text-[13px] outline-none transition-colors hover:bg-ink/[0.05] focus-visible:ring-2 focus-visible:ring-ring"
+            :class="child.disabled ? 'opacity-50' : itemActive?.(child) ? 'text-brand' : 'text-muted hover:text-ink'"
+            @click="emit('activate', child)"
+          >
+            <LpIcon v-if="child.icon" :name="child.icon" :size="15" class="shrink-0" />
+            <span class="min-w-0 flex-1 truncate">{{ child.label }}</span>
+            <LpBadge v-if="child.badge != null" tone="neutral">{{ child.badge }}</LpBadge>
+          </component>
+        </div>
+      </div>
+    </LpHoverCard>
+</template>

package/src/components/LpStat.vue

@@ -29,6 +29,11 @@ const props = withDefaults(
     /** Formatting for a numeric `value` — see LpNumberFlow. */
     compact?: boolean
     grouped?: boolean
+    /**
+     * Count up from zero when the tile first shows (the default), or show the
+     * value outright: a report or a screenshot wants the figure, not the run.
+     */
+    animateOnMount?: boolean
     decimals?: number
     prefix?: string
     valueSuffix?: string
@@ -54,7 +59,7 @@ const props = withDefaults(
      */
     loading?: boolean
   }>(),
-  { trend: "auto", decimals: 0 },
+  { trend: "auto", decimals: 0, animateOnMount: true },
 )
 
 // Resolve the trend direction: explicit wins; "auto" reads a numeric delta.
@@ -159,6 +164,7 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
               :value="value"
               :compact="compact"
               :grouped="grouped"
+              :animate-on-mount="animateOnMount"
               :decimals="decimals"
               :prefix="prefix"
               :suffix="valueSuffix"