@vvedantb/ui 0.26.1 → 0.27.0

package/README.md

@@ -1184,8 +1184,31 @@ import { DatePicker, DateTimePicker, MonthPicker } from "@vvedantb/ui";
 - `DatePicker`: `value` "YYYY-MM-DD" or "". The trigger matches `TimePicker` and shows the date with `dateStyle: "medium"` (`locale`) or `placeholder` ("Pick a date"). `min` and `max` disable days; `clearable` adds a clear control (`onChange("")`); `name` adds a hidden input. `className` goes on the wrapper, `triggerClassName` merges onto the button (default `w-40`). A width on either sizes the field, and `w-full` on either fills the row; pill inputs can pass `triggerClassName="h-10 w-full rounded-full px-4 text-sm"`. `ariaLabel` names the trigger, followed by the shown text.
 - `DateTimePicker`: `value` "YYYY-MM-DDTHH:mm" or "". A date with no time uses `defaultTime` ("00:00"); a time with no date uses today. Only the date part of `min` and `max` applies. `triggerClassName` goes to both triggers, a width only to the date.
 - `MonthPicker`: `value` "YYYY-MM" or "", with year navigation and a month grid. `min` and `max` are "YYYY-MM".
+- `TimePicker`: `value` "HH:mm" (24h) or "". `hourCycle={12}` (0.27.0) shows "02:30 PM" and adds an AM/PM column; `value` stays 24h. Each column opens centred on the selected item.
 - `Calendar`: the styled `DayPicker` for custom layouts (every `DayPicker` prop). `parseDateValue` and `formatDateValue` convert between "YYYY-MM-DD" and a local `Date`.
 
+## Hooks, media and list motion (0.27.0)
+
+Generic pieces lifted from an app. Components that use `m` need the app's `LazyMotion`.
+
+```tsx
+import {
+  ErrorBoundary, ListEnter, useFirstPaintGate, CountPop, countLabel, UnreadDot,
+  MarqueeOnHover, RelativeDateTime, ImageLightbox, ImageGalleryPreview, ScreenshotPreview, VideoPreview,
+  useMediaQuery, useDocumentVisible, useIdleCallback, useSingleFlight, usePersistedScrollParent,
+  convexErrorMessage, userFacingErrorMessage, useHeldResult,
+} from "@vvedantb/ui";
+```
+
+- `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`.
+- `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`).
+- 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`.
+
 ## Slider (0.16.0, dark contrast and className props 0.16.1)
 
 shadcn's slider on `@radix-ui/react-slider` (a peer dependency), with package tokens.

package/app/src/convex/errorMessage.ts

@@ -0,0 +1,62 @@
+/**
+ * The message to show the user for a failed Convex call.
+ *
+ * Production Convex redacts plain `Error` messages to "Server Error", so
+ * `error.message` alone leaves the user with a request id and no reason. Only
+ * `ConvexError` data crosses the wire intact — read that first. Matched by
+ * `name` rather than `instanceof`, so this module does not import `convex`.
+ */
+export function convexErrorMessage(error: unknown, fallback: string): string {
+  if (
+    error instanceof Error &&
+    error.name === "ConvexError" &&
+    "data" in error &&
+    typeof error.data === "string"
+  ) {
+    return error.data;
+  }
+  return error instanceof Error ? error.message : fallback;
+}
+
+const UNCAUGHT = "Uncaught Error:";
+const PLAIN = "Error:";
+
+/**
+ * The same failure, stripped of everything the Convex client wraps around it.
+ *
+ * A client-side rejection reads
+ * `[CONVEX M(teams:create)] [Request ID: abc] Server Error\nUncaught Error: Team
+ * name is required\n    at handler (../convex/teams.ts:107:12)`. Shown verbatim
+ * in a form's error slot that is a stack trace with the sentence buried in the
+ * middle, so take the text the handler actually threw: after the last
+ * `Uncaught Error:` / `Error:`, up to the newline or the stack frame.
+ *
+ * `error` is deliberately not `unknown` — callers catch `unknown` and narrow at
+ * the boundary with `err instanceof Error ? err : null`.
+ */
+export function userFacingErrorMessage(
+  error: Error | string | null | undefined,
+  fallback: string,
+): string {
+  const raw = typeof error === "string" ? error : (error?.message ?? "");
+
+  let start = 0;
+  const uncaught = raw.lastIndexOf(UNCAUGHT);
+  if (uncaught !== -1) {
+    start = uncaught + UNCAUGHT.length;
+  } else {
+    const plain = raw.lastIndexOf(PLAIN);
+    if (plain !== -1) start = plain + PLAIN.length;
+  }
+
+  let text = raw.slice(start);
+  const newline = text.indexOf("\n");
+  if (newline !== -1) text = text.slice(0, newline);
+  const frame = text.indexOf(" at ");
+  if (frame !== -1) text = text.slice(0, frame);
+  text = text.trim();
+
+  // Nothing survived the strip, or the whole thing was the client's envelope.
+  if (text.length === 0 || text.startsWith("[CONVEX")) return fallback;
+  return text;
+}

package/app/src/convex/useHeldResult.ts

@@ -0,0 +1,26 @@
+import { useState } from "react";
+
+/**
+ * Keeps the last loaded `result` while a query is skipped, instead of
+ * flipping to `undefined`. Pair it with any `useQuery`:
+ *
+ *   const result = useQuery(api.x.get, args);
+ *   const shown = useHeldResult(result, args === "skip" ? null : JSON.stringify(args));
+ *
+ * `key` names what the result is for, and `null` means skipped. While skipped
+ * the last result stays (so a hidden pane that pauses its subscription does
+ * not flash a spinner when shown again). A new non-null key loads as
+ * `undefined` rather than showing the previous key's data; pass a stable key
+ * on purpose to keep the last result across argument changes.
+ */
+export function useHeldResult<T>(result: T | undefined, key: string | null): T | undefined {
+  // State, not a ref: reading a ref during render makes the React Compiler
+  // skip the file. Adjusting state during render is the supported way to
+  // remember a previous value.
+  const [held, setHeld] = useState({ key, value: result });
+  if (result !== undefined && (result !== held.value || key !== held.key)) {
+    setHeld({ key, value: result });
+  }
+  if (result !== undefined) return result;
+  return key === null || key === held.key ? held.value : undefined;
+}

package/app/src/index.ts

@@ -22,11 +22,17 @@ export {
   type UpdateToastOptions,
 } from "./update/updateWatcher.js";
 
-export { SettingsSection } from "./settings/SettingsSection.js";
+export {
+  SettingsSection,
+  type SettingsSectionConfig,
+} from "./settings/SettingsSection.js";
 export { SettingsField } from "./settings/SettingsField.js";
 export { SettingsStack } from "./settings/SettingsStack.js";
 export { SettingsToggleRow } from "./settings/SettingsToggleRow.js";
-export { SettingsEmptyState } from "./settings/SettingsEmptyState.js";
+export {
+  SettingsEmptyState,
+  type SettingsEmptyStateConfig,
+} from "./settings/SettingsEmptyState.js";
 export {
   DefaultSettingsLayout,
   SettingsPage,
@@ -89,3 +95,5 @@ export {
   type ViteEnvName,
 } from "./convex/env.js";
 export { useEnsureUser, type EnsureUserMutation } from "./convex/useEnsureUser.js";
+export { convexErrorMessage, userFacingErrorMessage } from "./convex/errorMessage.js";
+export { useHeldResult } from "./convex/useHeldResult.js";

package/app/src/settings/SettingsEmptyState.tsx

@@ -1,4 +1,15 @@
 import type { ComponentType, ReactNode } from "react";
+import { useUiConfig } from "../../../src/ui/ui-config";
+
+const ICON_CLASS = "mb-5 text-muted-foreground opacity-50";
+
+/** `UiConfig.SettingsEmptyState`: replaces the built-in classes of a part. */
+export interface SettingsEmptyStateConfig {
+  classes?: {
+    /** The icon above the title (colour, opacity, spacing). */
+    icon?: string;
+  };
+}
 
 interface SettingsEmptyStateProps {
   /** Tabler icon component, rendered muted above the copy. */
@@ -23,9 +34,11 @@ export function SettingsEmptyState({
   description,
   action,
 }: SettingsEmptyStateProps) {
+  const iconClass =
+    useUiConfig("SettingsEmptyState")?.classes?.icon ?? ICON_CLASS;
   return (
     <div className="flex flex-col items-center justify-center px-4 py-16 text-center">
-      <Icon size={28} className="mb-5 text-muted-foreground opacity-50" />
+      <Icon size={28} className={iconClass} />
       <h4 className="text-sm font-medium text-foreground">{title}</h4>
       {description ? (
         <p className="mt-2 max-w-sm text-xs leading-relaxed text-muted-foreground">

package/app/src/settings/SettingsSection.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 
-import { cn } from "../cn.js";
+import { useCn, useUiConfig } from "../../../src/ui/ui-config";
 
 type SettingsSectionBodyVariant = "form" | "list" | "compact";
 
@@ -10,6 +10,23 @@ const BODY_VARIANT_CLASS: Record<SettingsSectionBodyVariant, string> = {
   compact: "px-4 py-3",
 };
 
+const CARD_CLASS =
+  "rounded-lg bg-surface-card [&_input]:bg-field-background [&_textarea]:bg-field-background [&_[data-slot=select-trigger]]:bg-field-background [&_[role=combobox]]:border-border [&_[role=combobox]]:bg-field-background";
+const FOOTER_CLASS =
+  "flex items-center justify-end gap-2 rounded-b-lg bg-surface-secondary px-4 py-3";
+
+/** `UiConfig.SettingsSection`: replaces the built-in classes of a part. */
+export interface SettingsSectionConfig {
+  classes?: {
+    /** The card behind the body and footer (tone, radius, nested field fills). */
+    card?: string;
+    /** The bottom bar that holds `footer`. */
+    footer?: string;
+    /** Body padding per `bodyVariant`. */
+    body?: Partial<Record<SettingsSectionBodyVariant, string>>;
+  };
+}
+
 interface SettingsSectionProps {
   /** Section heading. Kept short — the description carries the detail. */
   title: ReactNode;
@@ -49,6 +66,9 @@ export function SettingsSection({
   bodyClassName,
   className,
 }: SettingsSectionProps) {
+  const config = useUiConfig("SettingsSection");
+  const cn = useCn();
+  const classes = config?.classes;
   const hasBody = children != null;
   const hasCard = hasBody || footer != null;
 
@@ -71,17 +91,22 @@ export function SettingsSection({
       {hasCard ? (
         <div
           className={cn(
-            "rounded-lg bg-surface-card [&_input]:bg-field-background [&_textarea]:bg-field-background [&_[data-slot=select-trigger]]:bg-field-background [&_[role=combobox]]:border-border [&_[role=combobox]]:bg-field-background",
+            classes?.card ?? CARD_CLASS,
             bodyVariant === "list" && "overflow-hidden",
           )}
         >
           {hasBody ? (
-            <div className={cn(BODY_VARIANT_CLASS[bodyVariant], bodyClassName)}>
+            <div
+              className={cn(
+                classes?.body?.[bodyVariant] ?? BODY_VARIANT_CLASS[bodyVariant],
+                bodyClassName,
+              )}
+            >
               {children}
             </div>
           ) : null}
           {footer ? (
-            <div className="flex items-center justify-end gap-2 rounded-b-lg bg-surface-secondary px-4 py-3">
+            <div className={classes?.footer ?? FOOTER_CLASS}>
               {footer}
             </div>
           ) : null}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one 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), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
@@ -34,6 +34,7 @@
     "./tokens/css/compat-shadcn-rgb.css": "./tokens/src/css/compat-shadcn-rgb.css",
     "./tokens/css/border-beam.css": "./tokens/src/css/border-beam.css",
     "./tokens/css/markdown.css": "./tokens/src/css/markdown.css",
+    "./tokens/css/marquee.css": "./tokens/src/css/marquee.css",
     "./tokens/compat/shadcn-rgb.css": "./tokens/src/css/compat-shadcn-rgb.css",
     "./tokens/css/*.css": "./tokens/src/css/*.css",
     "./tokens/tailwind-preset": {

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+export { useMediaQuery } from "./use-media-query";
+export { useDocumentVisible } from "./use-document-visible";
+export { createIdleCallback, useIdleCallback } from "./use-idle-callback";
+export { useSingleFlight } from "./use-single-flight";
+export { usePersistedScrollParent } from "./use-persisted-scroll-parent";

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

@@ -0,0 +1,15 @@
+import { useSyncExternalStore } from "react";
+
+function subscribe(onStoreChange: () => void) {
+  document.addEventListener("visibilitychange", onStoreChange);
+  return () => document.removeEventListener("visibilitychange", onStoreChange);
+}
+
+/** True while the tab is visible. Server snapshot is `true`, so SSR renders as visible. */
+export function useDocumentVisible(): boolean {
+  return useSyncExternalStore(
+    subscribe,
+    () => document.visibilityState === "visible",
+    () => true,
+  );
+}

package/src/hooks/use-idle-callback.ts

@@ -0,0 +1,51 @@
+import { useState } from "react";
+
+/** Anything worth passing through a debounced callback. */
+type CallbackArgs = ReadonlyArray<string | number | boolean | null | object>;
+
+/**
+ * The debounce itself, free of React so it can be tested with fake timers.
+ * `getFn` is read at fire time rather than captured, so the caller always runs
+ * the latest render's closure.
+ */
+export function createIdleCallback<Args extends CallbackArgs>(
+  ms: number,
+  getFn: () => (...args: Args) => void,
+): (...args: Args) => void {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  return (...args: Args) => {
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      getFn()(...args);
+    }, ms);
+  };
+}
+
+/**
+ * Returns a stable callback that runs `fn` once `ms` has passed since the last
+ * call; each call cancels the pending one. Trailing edge only — nothing fires
+ * until the caller goes quiet.
+ */
+export function useIdleCallback<Args extends CallbackArgs>(
+  ms: number,
+  fn: (...args: Args) => void,
+): (...args: Args) => void {
+  // No refs and no direct writes to state: the React Compiler skips a file
+  // that does either during render. The holder keeps the latest `fn` in a
+  // closure; the caller stores it on each call (always an event handler
+  // holding the current render's closure), and the timer reads it on fire.
+  const [idle] = useState(() => {
+    let current = fn;
+    return {
+      setFn: (next: (...args: Args) => void) => {
+        current = next;
+      },
+      run: createIdleCallback<Args>(ms, () => current),
+    };
+  });
+  return (...args: Args) => {
+    idle.setFn(fn);
+    idle.run(...args);
+  };
+}

package/src/hooks/use-media-query.ts

@@ -0,0 +1,17 @@
+import { useSyncExternalStore } from "react";
+
+/**
+ * Subscribe to a CSS media query without setState-in-effect.
+ * `useSyncExternalStore` is the React 18+ recommended pattern for browser APIs.
+ */
+export function useMediaQuery(query: string): boolean {
+  return useSyncExternalStore(
+    (onStoreChange) => {
+      const mql = window.matchMedia(query);
+      mql.addEventListener("change", onStoreChange);
+      return () => mql.removeEventListener("change", onStoreChange);
+    },
+    () => window.matchMedia(query).matches,
+    () => false,
+  );
+}

package/src/hooks/use-persisted-scroll-parent.ts

@@ -0,0 +1,70 @@
+import { useLayoutEffect, useState, type RefCallback } from "react";
+
+/** Re-apply after a virtualised list measures; first paint often resets scrollTop. */
+function applyScrollTop(el: HTMLElement, scrollTop: number): void {
+  el.scrollTop = scrollTop;
+  requestAnimationFrame(() => {
+    el.scrollTop = scrollTop;
+    requestAnimationFrame(() => {
+      el.scrollTop = scrollTop;
+    });
+  });
+}
+
+function readScrollTop(key: string): number {
+  try {
+    // Stored as JSON; a JSON number is also a plain numeric string.
+    const value = Number(sessionStorage.getItem(key) ?? 0);
+    return Number.isFinite(value) ? value : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** JSON, so a value written by an older `useSessionStorage` reads back. */
+function writeScrollTop(key: string, scrollTop: number): void {
+  try {
+    sessionStorage.setItem(key, JSON.stringify(Math.round(scrollTop)));
+  } catch {
+    // Ignore quota / private-mode failures.
+  }
+}
+
+/**
+ * Scroll-container ref that saves `scrollTop` to `sessionStorage` under
+ * `storageKey` and restores it when the container mounts again, so a list keeps
+ * its place when a route swaps it out for a detail page and back. Per tab:
+ * closing the tab clears it. Writes are throttled to one per frame and do not
+ * re-render.
+ */
+export function usePersistedScrollParent(storageKey: string): {
+  scrollParent: HTMLDivElement | null;
+  scrollRef: RefCallback<HTMLDivElement>;
+} {
+  const [scrollParent, scrollRef] = useState<HTMLDivElement | null>(null);
+
+  useLayoutEffect(() => {
+    if (!scrollParent) return;
+
+    const initial = readScrollTop(storageKey);
+    if (initial > 0) applyScrollTop(scrollParent, initial);
+
+    let rafId = 0;
+    const onScroll = () => {
+      if (rafId !== 0) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = 0;
+        writeScrollTop(storageKey, scrollParent.scrollTop);
+      });
+    };
+
+    scrollParent.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      if (rafId !== 0) cancelAnimationFrame(rafId);
+      writeScrollTop(storageKey, scrollParent.scrollTop);
+      scrollParent.removeEventListener("scroll", onScroll);
+    };
+  }, [scrollParent, storageKey]);
+
+  return { scrollParent, scrollRef };
+}

package/src/hooks/use-single-flight.ts

@@ -0,0 +1,59 @@
+import { useRef } from "react";
+
+type NoPending = { has: false };
+type HasPending<TArgs> = { has: true; args: TArgs };
+type Pending<TArgs> = NoPending | HasPending<TArgs>;
+
+const NO_PENDING: NoPending = { has: false };
+
+/**
+ * Wraps an async function so at most one invocation runs at a time.
+ * While a call is in flight, subsequent calls are coalesced — only the
+ * latest args are kept, and they run once the current invocation settles.
+ *
+ * Designed for autosave-on-keystroke: prevents stampeding mutations when
+ * the user types quickly, while ensuring the final state is always saved.
+ */
+export function useSingleFlight<TArgs, TRet>(
+  fn: (args: TArgs) => Promise<TRet>,
+): (args: TArgs) => Promise<TRet | undefined> {
+  const inFlight = useRef(false);
+  const pending = useRef<Pending<TArgs>>(NO_PENDING);
+
+  const invoke = async (args: TArgs): Promise<TRet | undefined> => {
+    const runPending = (): void => {
+      const next: Pending<TArgs> = pending.current;
+      pending.current = NO_PENDING;
+      if (next.has) {
+        // Recurse with the latest coalesced args — return value discarded
+        // intentionally since the original caller already received undefined.
+        void invoke(next.args);
+      }
+    };
+
+    if (inFlight.current) {
+      pending.current = { has: true, args };
+      return undefined;
+    }
+
+    inFlight.current = true;
+    pending.current = NO_PENDING;
+
+    // Avoid `finally` here: TypeScript narrows discriminated unions to `never`
+    // inside `finally` blocks when the try body is async, making `next.args`
+    // inaccessible. Use explicit try/catch instead.
+    let result: TRet | undefined;
+    try {
+      result = await fn(args);
+    } catch (err) {
+      inFlight.current = false;
+      runPending();
+      throw err;
+    }
+    inFlight.current = false;
+    runPending();
+    return result;
+  };
+
+  return invoke;
+}

package/src/index.ts

@@ -8,6 +8,8 @@ export { fieldFocusClass, fieldFocusWithinClass } from "./ui/_field-classes";
 export * from "./ui/surface-classes";
 export * from "./motion/presets";
 export * from "./motion/panel-transition";
+export { ListEnter, useFirstPaintGate } from "./motion/list-enter";
+export type { ListEnterProps } from "./motion/list-enter";
 // Gesture physics and animation budget helpers (shared clock, on-screen and
 // page-visibility pausing for infinite animations).
 export { DRAG_ACTIVATION_DISTANCE_PX, projectVelocity, rubberband } from "./utils/gesture";
@@ -22,6 +24,18 @@ export { CAT_SLOT_COUNT, catColorForId, catColorForSlot, catSlotForId } from "./
 export type { CatColorClasses, CatSlot } from "./utils/cat-color";
 export { CONTROL_RADIUS_CLASS, SURFACE_RADIUS_CLASS } from "./utils/surface-radius";
 export { restoreModalScrollLock } from "./ui/overlay-a11y";
+// Generic hooks: media query, page visibility, trailing debounce,
+// single-flight async calls and a persisted scroll container.
+export * from "./hooks";
+export { ErrorBoundary } from "./ui/error-boundary";
+export type { ErrorBoundaryProps } from "./ui/error-boundary";
+export { CountPop, countLabel, UnreadDot } from "./ui/count-pop";
+export { MarqueeOnHover } from "./ui/marquee-on-hover";
+export { RelativeDateTime } from "./ui/relative-date-time";
+export type { RelativeDateTimeProps } from "./ui/relative-date-time";
+export { ImageLightbox } from "./ui/image-lightbox";
+export type { GalleryImage } from "./ui/image-lightbox";
+export { ImageGalleryPreview, ScreenshotPreview, VideoPreview } from "./ui/media-preview";
 
 export * from "./ui/avatar";
 export * from "./ui/badge";

package/src/motion/list-enter.tsx

@@ -0,0 +1,65 @@
+import { useEffect, useRef, type ReactNode } from "react";
+import { m } from "motion/react";
+import { staggerDelay, tokenTransition } from "./presets";
+
+/**
+ * `true` until the list has painted once. Pass `firstPaint.current` to
+ * `ListEnter` so a virtualised list's recycled rows (and later overscan) do
+ * not restagger. Stable keys already skip a remount on a data refresh.
+ */
+export function useFirstPaintGate() {
+  const firstPaint = useRef(true);
+  useEffect(() => {
+    firstPaint.current = false;
+  }, []);
+  return firstPaint;
+}
+
+export interface ListEnterProps {
+  index: number;
+  children: ReactNode;
+  className?: string;
+  /** `tokenTransition.fast` instead of `.base`. */
+  fast?: boolean;
+  /** When `false`, skip the enter (recycled rows, later overscan). */
+  firstPaint?: boolean;
+  staggerStep?: number;
+  staggerMax?: number;
+  /** Fade only, for rows that must not shift (e.g. gantt bars). Default `true`. */
+  slide?: boolean;
+  /** `tr` / `li` when the parent is a table or list; an `m.div` there is invalid HTML. */
+  as?: "div" | "tr" | "li";
+}
+
+/**
+ * First-paint fade and 8px slide for a list item, staggered by `index`.
+ * Uses `m`, so the app must render it inside `LazyMotion`.
+ */
+export function ListEnter({
+  index,
+  children,
+  className,
+  fast = false,
+  firstPaint,
+  staggerStep,
+  staggerMax,
+  slide = true,
+  as = "div",
+}: ListEnterProps) {
+  const skip = firstPaint === false;
+  const transition = fast ? tokenTransition.fast : tokenTransition.base;
+  const MotionTag = as === "tr" ? m.tr : as === "li" ? m.li : m.div;
+  return (
+    <MotionTag
+      className={className}
+      initial={skip ? false : { opacity: 0, y: slide ? 8 : 0 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{
+        ...transition,
+        delay: skip ? 0 : staggerDelay(index, staggerStep, staggerMax),
+      }}
+    >
+      {children}
+    </MotionTag>
+  );
+}

package/src/ui/count-pop.tsx

@@ -0,0 +1,67 @@
+import { AnimatePresence, m } from "motion/react";
+import type { ReactNode } from "react";
+import { tokenTransition } from "../motion/presets";
+import { useCn } from "./ui-config";
+
+/**
+ * The entrance and exit for a live count badge (unread dots, a drafts pill, a
+ * running count). The number usually changes while the user looks elsewhere,
+ * so the badge says *that it changed*: it pops from `scale(0.5)` on an
+ * emphasized curve, and pops again on every change because `label` is the
+ * key (2 → 3 remounts). Exit is a plain shrink on `tokenTransition.fast`.
+ *
+ * `mode="popLayout"` takes the leaving badge out of flow, so 9 → 10 does not
+ * push its neighbours sideways during the crossfade. Only the motion lives
+ * here; the caller owns the look through `className`. Uses `m`, so the app
+ * must render it inside `LazyMotion`.
+ */
+export function CountPop({
+  label,
+  className,
+  children,
+}: {
+  /** Rendered content, and the remount key. `null` renders nothing. */
+  label: string | null;
+  className?: string;
+  /** Defaults to `label`; pass children for a badge with more than a number. */
+  children?: ReactNode;
+}) {
+  return (
+    <AnimatePresence mode="popLayout">
+      {label === null ? null : (
+        <m.span
+          key={label}
+          initial={{ opacity: 0, scale: 0.5 }}
+          animate={{ opacity: 1, scale: 1 }}
+          exit={{ opacity: 0, scale: 0.5, transition: tokenTransition.fast }}
+          transition={{ ...tokenTransition.base, ease: [0.2, 0.8, 0.2, 1] }}
+          className={className}
+        >
+          {children ?? label}
+        </m.span>
+      )}
+    </AnimatePresence>
+  );
+}
+
+/** A count badge label: `null` for nothing to show, `"99+"` above 99. */
+export function countLabel(count: number | undefined): string | null {
+  if (count === undefined || count <= 0) return null;
+  return count > 99 ? "99+" : String(count);
+}
+
+/**
+ * The unread mark for rows, cards and tabs: a `bg-primary` dot, so it follows
+ * the theme accent. `CountPop` gives it the pop-in and the exit.
+ */
+export function UnreadDot({ show, className }: { show: boolean; className?: string }) {
+  const cn = useCn();
+  return (
+    <CountPop
+      label={show ? "unread" : null}
+      className={cn("size-1.5 shrink-0 rounded-full bg-primary", className)}
+    >
+      <span className="sr-only">Unread</span>
+    </CountPop>
+  );
+}