@vvedantb/ui 0.30.1 → 0.30.2

package/README.md

@@ -1196,9 +1196,10 @@ Generic pieces lifted from an app. Components that use `m` need the app's `LazyM
 
 ```tsx
 import {
-  ErrorBoundary, ListEnter, useFirstPaintGate, CountPop, countLabel, UnreadDot,
+  ErrorBoundary, ListEnter, useFirstPaintGate, CountPop, countLabel, UnreadDot, RollingNumber,
   MarqueeOnHover, RelativeDateTime, ImageLightbox, ImageGalleryPreview, ScreenshotPreview, VideoPreview,
-  useMediaQuery, useDocumentVisible, useIdleCallback, useSingleFlight, usePersistedScrollParent,
+  useMediaQuery, useDocumentVisible, useDocumentAppearance, useIdleCallback, useSingleFlight, usePersistedScrollParent,
+  useCountUpDisplay, parseCountable,
   convexErrorMessage, userFacingErrorMessage, useHeldResult,
 } from "@vvedantb/ui";
 ```
@@ -1206,12 +1207,16 @@ import {
 - `ErrorBoundary` (`fallback` node or `(retry) => node`, `onError`): contains a failure to its subtree; `retry` clears the error.
 - `ListEnter` (`index`, `fast`, `firstPaint`, `staggerStep`, `staggerMax`, `slide`, `as` `div | tr | li`) and `useFirstPaintGate()`: first-paint fade and 8px slide, staggered with `staggerDelay`. Pass `firstPaint={gate.current}` so recycled rows do not restagger.
 - `CountPop` (`label`, `className`, `children`): pop-in and shrink-out for a live count, re-popping on each change. `countLabel(n)` gives `null`, the number or `"99+"`. `UnreadDot` (`show`): a `bg-primary` dot on `CountPop`.
+- `RollingNumber` (`value`, `className`): shows an already formatted string ("1m 05s", "42%", "$1.20") and rolls each digit to its new value; other characters swap at once. Columns are keyed from the right, so "9s" → "10s" mounts only the new column. The full value stays in an `sr-only` span. For numbers that tick while the user watches; `CountPop` is for a badge that changes while the user looks elsewhere.
 - `MarqueeOnHover`: a single-line label that scrolls its hidden tail into view on hover (or on hover of a `group` ancestor). Import `@vvedantb/ui/tokens/css/marquee.css`; `--mq-delay` sets the dwell.
 - `RelativeDateTime` (`at`, `emptyLabel` default "—", `exactFormat` default "DD/MM/YYYY HH:mm"): "15m" / "2d" with the exact time in a tooltip.
 - `ImageLightbox` (`images`, `index` or `null`, `onIndexChange`, `onClose`): fullscreen viewer with arrow keys, buttons and swipe. `ImageGalleryPreview` (`images`): up to a 2×2 grid with a "+N" tile. `ScreenshotPreview` (`url`, `alt`) and `VideoPreview` (`url`).
-- Hooks: `useMediaQuery(query)`, `useDocumentVisible()`, `useIdleCallback(ms, fn)` (trailing debounce; `createIdleCallback` is the React-free core), `useSingleFlight(fn)` (one call at a time, latest args run next), `usePersistedScrollParent(storageKey)` (restores a container's `scrollTop` from `sessionStorage`).
+- Hooks: `useMediaQuery(query)`, `useDocumentVisible()`, `useDocumentAppearance()` (`"light" | "dark"` from `<html>`'s `dark` class or `data-theme`; `readDocumentAppearance` / `subscribeDocumentAppearance` are the React-free core), `useIdleCallback(ms, fn)` (trailing debounce; `createIdleCallback` is the React-free core), `useSingleFlight(fn)` (one call at a time, latest args run next), `usePersistedScrollParent(storageKey)` (restores a container's `scrollTop` from `sessionStorage`).
+- `useCountUpDisplay(value)`: counts a number, or a label with one number ("45%", "12h", "$1.20"), from the last value to the new one over `tokenTransition.base`, keeping the prefix, suffix and decimal places. Where `RollingNumber` rolls each digit, this counts through the numbers between. The first value counts up from 0, and the same amount again does not replay. Labels it cannot count ("1h 12m", "—") show as they are, and so does every value while `PageMotionProvider` is `disabled`. `parseCountable(value)` is the parser: `{ amount, prefix, suffix, decimals }` or `null`.
 - Convex: `convexErrorMessage(error, fallback)` reads `ConvexError` data first; `userFacingErrorMessage(error, fallback)` strips the client envelope and stack. `useHeldResult(result, key)` keeps the last result while a query is skipped (`key` `null`). None of these import `convex`.
 
+Fixture for `RollingNumber`, `SendQueueIcon`, `PromptInputSubmit` `queued`, the `ActivityTasks` clock and `useCountUpDisplay`: `examples/motion-primitives/`.
+
 ## Chrome extensions (0.28.0)
 
 Extension pages (popup, side panel, options, welcome) run under the MV3 extension-page CSP, which blocks remote font stylesheets, and should not load `@vvedantb/server`. Three pieces cover them. Web apps change nothing unless they opt in.
@@ -1497,6 +1502,7 @@ const config = {
   Outside a `StickToBottom` (for example a page outline) use `JumpRail` with `items` (`{ id, title, preview?, level? }`), a `scrollRef` or `getScrollElement`, and `targetAttribute="data-toc-id"` or `resolveTarget`. `onReveal` runs when a target is not in the DOM; `onBeforeScroll` runs just before it. `onSelect(id)` runs after a click or Enter/Space pick, once the scroll has started or `onReveal` has run, so an app can move focus to the target for keyboard users; `ChatJumpRail` accepts it too. `observeKey` re-observes when the rendered window changes. The geometry helpers (`resolveJumpRailTopPercent`, `resolveJumpRailIndexFromPointer`, `resolveJumpRailHeightStyle`, `resolveJumpRailTickWidthClass`, `resolveJumpRailTickLevelStyle`) are exported.
 - `Message`: `classes.root`, `classes.user`, `classes.assistant` (the role classes of `Message`), `classes.content` (all `MessageContent` classes), `classes.branchSelector`, `classes.branchIcon` (a class in place of the arrows' `size={14}`), and `lazyActionTooltips`: a `MessageAction` mounts its tooltip on first hover or focus (focus opens it), not with the button.
 - `PromptInput`: `classes.group` (the input group, default `overflow-hidden`), `classes.groupIdle` / `classes.groupDragOver` (added while no drag / an accepted drag is over the form), `classes.groupDefault` (added when no `containerClassName` is given), `classes.textarea`, `classes.footer`, `classes.submit`, `classes.tabItem`; `submitIcons.<send|submitted|streaming|error>`, `submitCrossfade` (cross-fade the submit icon on status change) and `menuTriggerAsChild` (`PromptInputActionMenuTrigger` becomes the Radix trigger instead of a button inside it). New `PromptInput` props: `dataDrop` (`{ type, onDrop }`: a non-file drag of that MIME type counts as a drag over the form and `onDrop` gets its string payload) and `inputGroupClassName` (same as `containerClassName`). The attachments context adds `replace(id, file)`; `accept` now matches extension patterns such as `.html` by file name; `useOptionalPromptInputController` is exported.
+- `PromptInputSubmit`: new prop `queued` (0.30.0). Set it when a send would join a queue (the agent is still working). The send icon becomes `SendQueueIcon`, an up arrow that morphs into a stack of bars while `queued` is `true`. Leave it unset to keep `submitIcons.send`. `SendQueueIcon` (`queued`, `className` default `size-4`) is exported for other send buttons. It uses `m`, so `queued` needs the app's `LazyMotion`.
 - `PromptInputSettings` (new): an overflow menu with a "Model" submenu (one radio list, or a submenu per provider). Entry: `providerLabel(provider)` (default the id), `providerIcon(provider)` (default none), `classes.trigger`.
 - `TraitsPanel` (new, with `isUltrathinkPrompt`, `applyUltrathinkPrefix`): reasoning, speed, context and thinking segments for a model picker; inside a `PromptInputProvider` it offers "Ultrathink" by editing the prompt. Entry: `classes.label`, `classes.empty`, `classes.option`, `classes.optionSelected`, `classes.optionIdle`, `classes.note`.
 - `PromptInputSpeech`, `useSpeechRecognition`, `getSpeechRecognition` (new): Web Speech API dictation; the button renders nothing without the API.
@@ -1518,7 +1524,7 @@ New dependency (installed with the package): `katex`. `streamdown` and the `@str
 
 AI surfaces that came from an app, exported from the root. Fills use `surface-secondary` (`bg-surface-secondary`, `from-surface-secondary/40`), which is the app's `--muted` under `compat-shadcn-rgb.css` and the secondary surface under `tokens.css`. They also use the shadcn colour names `bg-secondary`, `bg-popover` and `bg-card` and a few app utilities (`motion-press`, `smooth-shadow-*`, `scrollbar`, `scrollbar-none`, `text-2xs`, `text-3xs`), so they look as intended with `compat-shadcn-rgb.css` and an app that defines those utilities. They merge a caller `className` with `UiConfig.cn` when set.
 
-- `ActivityTasks` (`steps`, `isStreaming`, `name`, `startedAt`, `duration`, `layout` `folded | inline`, `onOpenFile`, `onRequestFullDetail`): an agent turn as a timeline. Tool runs fold behind one summary line, reasoning and mid-turn text render as Markdown, subtasks nest their steps, long timelines cap behind "Show N more". `OpenSubagentContext` gives subtask rows a "View" link.
+- `ActivityTasks` (`steps`, `isStreaming`, `name`, `startedAt`, `duration`, `layout` `folded | inline`, `onOpenFile`, `onRequestFullDetail`): an agent turn as a timeline. Tool runs fold behind one summary line, reasoning and mid-turn text render as Markdown, subtasks nest their steps, long timelines cap behind "Show N more". While `isStreaming` and before the first row, a header shows the time since `startedAt` as a `RollingNumber` clock. `OpenSubagentContext` gives subtask rows a "View" link.
 - The step model: `ActivityStep`, `ActivityTodoItem`, `ActivityQuestion`, `ActivityQuestionOption`, `ActivityStepOutput`, `ActivityStepEdit`, `activityStepHasRichDetail`, `activityStepConfig` (glyph and fallback label per step type), `ActivityThinkingIcon`, `useActivitySpinnerVerb`, `getRandomActivityVerb`, `useActivityElapsedSeconds`, `formatActivityElapsed`, `useStreamingDisclosure`.
 - Tool-call details show files with `FileChip` and output in a `CodeBlock` (`plain`) with its copy button, so the `CodeBlock` entry (see "App config: AI chat") styles those frames too.
 - `ActivityQuestionCard` (`questions`, `answers`): the read-only record of a multiple-choice question and its answer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.30.1",
+  "version": "0.30.2",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one main JavaScript entry (primitives, shell pieces, app helpers including the Convex and Clerk provider, VITE env parsing and ensure-user, artifact viewers over the @vvedantb/server artifacts core, native tokens), a client entry without @vvedantb/server, convex or Clerk for Chrome extensions, design-token CSS, shared Tailwind v4 CSS, a Tailwind preset and packaged Instrument Sans fonts.",
   "type": "module",

package/src/hooks/index.ts

@@ -1,5 +1,12 @@
 export { useMediaQuery } from "./use-media-query";
 export { useDocumentVisible } from "./use-document-visible";
+export {
+  readDocumentAppearance,
+  subscribeDocumentAppearance,
+  useDocumentAppearance,
+  type DocumentAppearance,
+} from "./use-document-appearance";
 export { createIdleCallback, useIdleCallback } from "./use-idle-callback";
 export { useSingleFlight } from "./use-single-flight";
 export { usePersistedScrollParent } from "./use-persisted-scroll-parent";
+export { parseCountable, useCountUpDisplay } from "./use-count-up-display";

package/src/hooks/use-count-up-display.ts

@@ -0,0 +1,80 @@
+import { animate } from "motion/react";
+import { useEffect, useRef, useState } from "react";
+import { useDisablePageMotion } from "../../app/src/page-motion/PageMotionProvider";
+import { motionEase, tokenTransition } from "../motion/presets";
+
+/** Suffixes we will count; compound durations like "1h 12m" stay static. */
+const COUNTABLE_SUFFIX = /^(?:%|h|k|m|s|ms)?$/i;
+
+/**
+ * Splits a label into the number to count and the text around it. A finite
+ * number passes through; a string needs one number with an optional prefix
+ * ("$", "~") and a suffix of `%`, `h`, `k`, `m`, `s` or `ms`. Anything else
+ * (`—`, "1h 12m", "3 of 5") is `null`.
+ */
+export function parseCountable(value: string | number): {
+  amount: number;
+  prefix: string;
+  suffix: string;
+  decimals: number;
+} | null {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return null;
+    return { amount: value, prefix: "", suffix: "", decimals: 0 };
+  }
+  const match = value.trim().match(/^(\D*?)(-?\d+(?:\.\d+)?)(\D*)$/);
+  if (!match) return null;
+  const prefix = match[1] ?? "";
+  const raw = match[2] ?? "";
+  const suffix = (match[3] ?? "").trim();
+  if (!COUNTABLE_SUFFIX.test(suffix)) return null;
+  const amount = Number(raw);
+  if (!Number.isFinite(amount)) return null;
+  const decimals = raw.includes(".") ? (raw.split(".")[1]?.length ?? 0) : 0;
+  return { amount, prefix, suffix, decimals };
+}
+
+/**
+ * Counts from the last seen number to `value` on `--motion-base`
+ * (`tokenTransition.base`), keeping the prefix, suffix and decimal places. The
+ * first value counts up from 0. The same amount again (a refetch) is a no-op,
+ * so the number does not replay on every write. Labels `parseCountable` rejects
+ * (`—`, "1h 12m") render as they are, and so does every value while
+ * `PageMotionProvider` is `disabled`.
+ */
+export function useCountUpDisplay(value: string | number): string | number {
+  const parsed = parseCountable(value);
+  const [display, setDisplay] = useState(value);
+  const lastAmount = useRef<number | null>(null);
+  const skipMotion = useDisablePageMotion();
+
+  useEffect(() => {
+    if (skipMotion) {
+      lastAmount.current = parsed?.amount ?? null;
+      setDisplay(value);
+      return;
+    }
+    if (!parsed) {
+      lastAmount.current = null;
+      setDisplay(value);
+      return;
+    }
+    if (lastAmount.current === parsed.amount) {
+      setDisplay(value);
+      return;
+    }
+    const from = lastAmount.current ?? 0;
+    lastAmount.current = parsed.amount;
+    const controls = animate(from, parsed.amount, {
+      duration: tokenTransition.base.duration,
+      ease: motionEase,
+      onUpdate: (latest) => {
+        const rounded = parsed.decimals > 0 ? latest.toFixed(parsed.decimals) : String(Math.round(latest));
+        setDisplay(`${parsed.prefix}${rounded}${parsed.suffix}`);
+      },
+    });
+    return () => controls.stop();
+  }, [parsed?.amount, parsed?.prefix, parsed?.suffix, parsed?.decimals, skipMotion, value]);
+
+  return display;
+}

package/src/hooks/use-document-appearance.ts

@@ -0,0 +1,46 @@
+import { useSyncExternalStore } from "react";
+
+/** Light or dark, as the page currently draws itself. Neutral is dark-family. */
+export type DocumentAppearance = "light" | "dark";
+
+/**
+ * Reads the appearance from `<html>`: the `dark` class (Tailwind's convention,
+ * set before paint by the app's boot script) or `data-theme="dark"`.
+ *
+ * Use this rather than a theme context when code can run outside the app's
+ * theme provider (a signed-out marketing page, a canvas effect): the class is
+ * the one source every page shares.
+ */
+export function readDocumentAppearance(): DocumentAppearance {
+  const root = document.documentElement;
+  return root.classList.contains("dark") ||
+    root.getAttribute("data-theme") === "dark"
+    ? "dark"
+    : "light";
+}
+
+/** Calls `onChange` whenever `<html>`'s class or `data-theme` changes. */
+export function subscribeDocumentAppearance(onChange: () => void): () => void {
+  const observer = new MutationObserver(onChange);
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["class", "data-theme"],
+  });
+  return () => observer.disconnect();
+}
+
+function readServerAppearance(): DocumentAppearance {
+  return "light";
+}
+
+/**
+ * The page's appearance, re-rendering when it changes. Server snapshot is
+ * `"light"`, matching a page with no `dark` class.
+ */
+export function useDocumentAppearance(): DocumentAppearance {
+  return useSyncExternalStore(
+    subscribeDocumentAppearance,
+    readDocumentAppearance,
+    readServerAppearance,
+  );
+}

package/src/markdown/mermaid.ts

@@ -1,6 +1,10 @@
 import type { MermaidConfig } from "@streamdown/mermaid";
 import { useSyncExternalStore } from "react";
 import type { DiagramPlugin } from "streamdown";
+import {
+  readDocumentAppearance,
+  subscribeDocumentAppearance,
+} from "../hooks/use-document-appearance";
 
 /**
  * Mermaid for markdown, loaded on first use. `@streamdown/mermaid` imports
@@ -102,18 +106,9 @@ function subscribe(key: string, notify: () => void): () => void {
   };
 }
 
-/** The app theme lives as a `dark` class on `<html>` (neutral is dark-family). */
+/** Mermaid's theme for the page's current appearance (neutral is dark-family). */
 function readTheme(): MermaidTheme {
-  return document.documentElement.classList.contains("dark") ? "dark" : "default";
-}
-
-function subscribeTheme(notify: () => void): () => void {
-  const observer = new MutationObserver(notify);
-  observer.observe(document.documentElement, {
-    attributes: true,
-    attributeFilter: ["class"],
-  });
-  return () => observer.disconnect();
+  return readDocumentAppearance() === "dark" ? "dark" : "default";
 }
 
 /**
@@ -145,7 +140,7 @@ export function useMermaidRender(
   code: string,
   enabled: boolean,
 ): { theme: MermaidTheme; status: Entry["status"] } {
-  const theme = useSyncExternalStore(subscribeTheme, readTheme);
+  const theme = useSyncExternalStore(subscribeDocumentAppearance, readTheme);
   const key = enabled ? cacheKey(theme, code) : "";
   const entry = useSyncExternalStore(
     (notify) => (key === "" ? () => {} : subscribe(key, notify)),

package/src/ui/clearInputDissolve.ts

@@ -1,5 +1,7 @@
 /** transitions.dev input clear with dissolve — see 13-input-clear-dissolve.md */
 
+import { readDocumentAppearance } from "../hooks/use-document-appearance";
+
 // Times come back in ms. CSS minifiers rewrite `1000ms` as `1s`, so a value
 // in seconds is converted rather than read as 1.
 export function readCssNumber(
@@ -53,13 +55,6 @@ export function readCssEase(root: HTMLElement, name: string): (t: number) => num
   };
 }
 
-function isDarkTheme(root: HTMLElement): boolean {
-  return (
-    root.classList.contains("dark") ||
-    root.getAttribute("data-theme") === "dark"
-  );
-}
-
 function measureCanvas(): CanvasRenderingContext2D | null {
   const canvas = document.createElement("canvas");
   return canvas.getContext("2d");
@@ -93,7 +88,7 @@ function buildGlowBackground(
     return "";
   }
   canvas.font = getComputedStyle(input).font;
-  const dark = isDarkTheme(root);
+  const dark = readDocumentAppearance() === "dark";
   const rgb = dark ? "255,255,255" : "0,0,0";
   const width = wrap.clientWidth || 280;
   const padLeft = parseFloat(getComputedStyle(input).paddingLeft) || 12;