@vvedantb/ui 0.30.2 → 0.31.1

package/README.md

@@ -260,6 +260,17 @@ import {
 <FadePresence show={visible} variants={fadeUpSpring}>…</FadePresence>
 ```
 
+- `Button` `shape` (0.31.0, a default change): `"pill"` (default) is `rounded-full` for every variant and size, so the icon sizes are circles. `"rounded"` keeps the radius from before 0.31.0: `rounded-lg`, and `rounded-md` on `xs` and `icon-xs`. Use `shape="rounded"` for buttons that join other edges (inside a `ButtonGroup`) or sit in square chrome. A `className` radius still wins over both. `InputGroupButton`, the message branch arrows and the sidebar `AccountTrigger`, `MobileMenuButton` and `PanelClose` already use `"rounded"`. With the default `--radius` (1rem), buttons 32px tall or less were already fully round, so the visible change is on `default`, `lg` and `icon`.
+
+  ```tsx
+  <Button>Save</Button>                          {/* pill */}
+  <Button size="icon" aria-label="Add"><IconPlus /></Button>  {/* circle */}
+  <ButtonGroup>
+    <Button variant="outline" shape="rounded">Day</Button>
+    <Button variant="outline" shape="rounded">Week</Button>
+  </ButtonGroup>
+  ```
+
 - `Button`: variants `flat`, `success` and `warning` (each is `ghost` plus an override). `loading` disables the button, sets `data-loading="true"` and shows a spinner in place of `startContent`; without `loading` there is no `data-loading` attribute. `endContent` renders after the children. Both are ignored with `asChild` (`loading` still disables).
 - `DropdownMenuContent`: `fitViewport` caps the height on small screens and scrolls. It reads the optional `--vv-height` CSS variable, which the app may set to the visual viewport height (falls back to `70dvh`). `suppressAltKey` stops a bare Alt press from moving focus. `restoreScrollLockOnClose` calls `restoreModalScrollLock` on close (now and on the next tick). `ContextMenuContent` takes `suppressAltKey` too.
 - `DropdownMenuItem` `endContent` and `ContextMenuItem` `startContent`, `description` and `endContent`: the label moves into a growing column (`min-w-0 flex-1`), the description sits under it and `endContent` sits at the end. `DropdownMenuSubTrigger` and `ContextMenuSubTrigger` take `startContent`.
@@ -438,7 +449,7 @@ Convention: compound parts are static members of a namespace object, `<Namespace
 | --- | --- |
 | `Root` | No DOM. Holds `isDesktop`, `mobileOpen`, `onMobileOpenChange`, `collapsed`, `panelHidden` and the drawer `id`. Closes the drawer at the desktop breakpoint. The chrome parts need it. |
 | `MobileHeader` | Fixed header below `md`, a three-column grid (menu button, title, actions). Escape closes the drawer. Keep all three children so the columns line up. |
-| `MobileMenuButton` | Opens the drawer. `label`, `icon` (`(open) => node`). |
+| `MobileMenuButton` | Opens the drawer. `label`, `icon` (`(open) => node`). Keeps `rounded-lg` (`Button` `shape="rounded"`); change it with `className`. |
 | `MobileTitle` | Centred `<h1>` that truncates. Without children, an empty `<span>` keeps the middle column. |
 | `MobileActions` | Trailing header actions. Without children, a spacer that keeps the title centred. |
 | `Backdrop` | Drawer backdrop; a click closes the drawer. `label` (`"Close navigation"`). |
@@ -452,11 +463,11 @@ Convention: compound parts are static members of a namespace object, `<Namespace
 | `Panel` | Panel column. `collapsed` (`md:hidden`) and `panelHidden` (renders nothing) default to the Root values. |
 | `PanelHeader` | Padded header row for `PanelTitle` and `PanelActions`. |
 | `PanelTitle` / `PanelActions` | The `<h2>` and the trailing actions. |
-| `PanelClose` | Ghost close button. `label` (`"Close navigation"`). Without `onClick` it closes the drawer. |
+| `PanelClose` | Ghost close button. `label` (`"Close navigation"`). Without `onClick` it closes the drawer. Keeps `rounded-lg` (`Button` `shape="rounded"`); change it with `className`. |
 | `NavItem` | Panel nav row (`sidebarNavItemClass`). `active` (fill, `font-medium`, `aria-current="page"`), `iconOnly`, `icon` (element; gets `sidebarNavIconClass`), `asChild` for a router link. A `<button type="button">` without `asChild`. 0.7.2: `selected`, `indent`, `dragging`, `dropTarget`; see [Sidebar nav row parts (0.7.2)](#sidebar-nav-row-parts-072). |
 | `NavItemLeading` / `NavItemLabel` / `NavItemTrailing` / `NavItemActions` | Row parts (0.7.2): leading slot, truncated label, always-visible trailing content and hover-revealed actions. `<span>`, or the child with `asChild`. |
 | `AccountMenu` | Dropdown root. `badge` adds the unread dot (`AccountBadge`) in a `relative` wrapper. |
-| `AccountTrigger` | Rail-tile-sized avatar button. `userName` (default `title` and `aria-label`, and the initials), `imageUrl`, plus `Button` props; native `name` goes to the button. |
+| `AccountTrigger` | Rail-tile-sized avatar button. `userName` (default `title` and `aria-label`, and the initials), `imageUrl`, plus `Button` props except `asChild` and `shape` (it keeps the rail tile `rounded-lg`); native `name` goes to the button. |
 | `AccountAvatar` | Avatar image or initials. `userName`, `imageUrl`. |
 | `AccountContent` | Menu content. Defaults `align="center"`, `side="right"`, `sideOffset={8}`, `w-56`. |
 | `AccountLabel` | Identity label: avatar, `userName`, optional `email`, `stacked`. |
@@ -882,9 +893,11 @@ links under a separator.
 ### `Icon*` app icons
 
 Tabler-style plain app glyphs: `IconVibot`, `IconVhub`, `IconVmem`, `IconVerve`,
-`IconVelth` and `IconProjectV`. No background. Each sits on an equalised square viewBox, so all apps look the same size. `APP_ICONS[app]`
+`IconVelth`, `IconProjectV`, `IconEva` and `IconBee`. No background. Each sits on an equalised square viewBox, so all apps look the same size. `APP_ICONS[app]`
 looks one up by `AppName`.
 
+`IconEva` (a filled four-point star) and `IconBee` (an orb with eyes, stripes and antennae) are icons only. `eva` and `bee` are in `APP_NAMES`, `APP_MARKS` and `APP_ICONS`, but not in `FAMILY_APPS` or `V_PRO_APP_BENEFITS`, and `AppWordmark` and `PricingModal` do not take them.
+
 ```tsx
 import { IconVerve } from "@vvedantb/ui"
 
@@ -940,13 +953,14 @@ import { AppWordmark } from "@vvedantb/ui"
 ### `AppMark` (deprecated)
 
 Deprecated in favour of the `Icon*` components for plain marks. Tiles stay here.
-Family app icons: `app` (`projectv`, `vibot`, `vhub`, `vmem`, `verve`, `velth`),
+Family app icons: `app` (`projectv`, `vibot`, `vhub`, `vmem`, `verve`, `velth`, and the icon-only `eva` and `bee`),
 `variant`, `size`, `title`.
 
 - `variant="mark"` (default) is the plain logo in `currentColor`. It sits
   on a square viewBox. The five apps (`vibot`, `vhub`, `vmem`, `verve`, `velth`) keep one
   frame size, 629 x 629 (`APP_MARK_CROP_VIEWBOX` is the historical `173 197 629 629`), so relative
-  glyph sizes match the tiles. Each viewBox origin is centred on that glyph's `markBBox`, so no
+  glyph sizes match the tiles. `eva` and `bee` use the same 629 side, but the historical crop does not
+  include them. Each viewBox origin is centred on that glyph's `markBBox`, so no
   glyph sits off-centre in its square. `projectv` is a brand mark, so it keeps its own 687 frame,
   centred on its bbox (`PROJECTV_MARK_VIEWBOX`, `171.5 181 687 687`). `size` sets both width and
   height; a string `size` (for example `"2rem"`) is any CSS length. `APP_MARK_VIEWBOX` holds the
@@ -971,7 +985,7 @@ default) and `renderCheckout`.
 
 #### Multi-plan (0.22.0)
 
-Header: `apps` (an `AppName[]`, shown as plain `Icon*` logos at the top left; each links to the app's site in a new tab and shows its display name in a tooltip, from `FAMILY_APPS`),
+Header: `apps` (a `FamilyAppName[]`, shown as plain `Icon*` logos at the top left; each links to the app's site in a new tab and shows its display name in a tooltip, from `FAMILY_APPS`),
 `headline` (centre), a Monthly / Annual switch and a close button (top right).
 Then one card per entry of `plans` (2 to 4 fit) and one `finePrint` line. Cards
 stack on narrow screens.
@@ -986,7 +1000,7 @@ outlined "Current plan" button and does not call `renderCheckout`.
 
 `appBenefits` (`{ app, items }[]`, type `PricingPlanAppBenefit`) groups benefits per app, each under a small heading with that app's icon and display name. It renders after `benefits` and scrolls inside the card when long. Set `currentApp` on the modal to put that app's group first; the other groups keep the array order. The `featured` / `highlighted` plan uses `V_PRO_APP_BENEFITS` (the approved V Pro copy, in the order vibot, vmem, vhub, velth, verve) when it omits `appBenefits`, so apps usually pass only `currentApp`. Other plans show app benefits only when set.
 
-`FAMILY_APPS` (and `familyApp(app)`), exported from the root and `@vvedantb/ui/brand`, is the single list of app display names and sites (`vibot`, `Verve`, `Velth`, `vmem`, `vhub`, `Project V`; URLs without a trailing slash). App names live only under `src/brand/`.
+`FAMILY_APPS` (and `familyApp(app)`), exported from the root and `@vvedantb/ui/brand`, is the single list of app display names and sites (`vibot`, `Verve`, `Velth`, `vmem`, `vhub`, `Project V`; URLs without a trailing slash). Its app type is `FamilyAppName`: `AppName` without the icon-only `eva` and `bee`. App names live only under `src/brand/`.
 
 The `featured` plan's button is a solid primary button (`Button` `variant="default"`). Other plans use `secondary`.
 
@@ -1297,7 +1311,13 @@ import { SonnerToaster, toast } from "@vvedantb/ui";
 />;
 ```
 
-With no new props and no `UiConfig.SonnerToaster` entry the toaster looks as it did in 0.2.1. An entry sets app defaults for any prop (see "App config: AI chat" below). Caller props merge with the package defaults instead of replacing them:
+With no new props and no `UiConfig.SonnerToaster` entry the toaster looks as it did in 0.2.1, except for three changes from 0.31.1:
+
+- Toasts sit at the top right (`position="top-right"`). Sonner's own default is bottom-right. Pass `position`, or set `UiConfig.SonnerToaster.position`, to move them.
+- The text column grows (`content`: `flex min-w-0 grow flex-col`). `unstyled` drops sonner's own grow, so without it the action button left a gap at the right edge. Apps no longer need to set `classes.content` for this.
+- The action and cancel buttons are 28px tall (`h-7 shrink-0 rounded-control px-2.5 text-xs`), up from 24px. The action button presses with `motion-press active:scale-[0.96]` (`motion-press` is an app utility) and hovers with `hover:bg-primary/90`. `classes.actionButton` replaces the string, and `toastOptions.classNames.actionButton` appends to it.
+
+A `UiConfig.SonnerToaster` entry sets app defaults for any prop (see "App config: AI chat" below). Caller props merge with the package defaults instead of replacing them:
 
 - `toastOptions.classNames`: per key, the package classes come first and the caller classes follow, so callers can override utilities. Other `toastOptions` fields (such as `duration`) take the caller value.
 - `icons`: merged per key. With `toastIcons="filled24"` the caller overrides single icons and keeps the rest.
@@ -1319,7 +1339,9 @@ Opt-in props (all default to the current look):
 
 With `closeButtonStyle="hoverChip"`, hover changes the text colour, and sonner may still change the background. The border stays `border-border` (pinned with `hover:border-border!` over sonner's dark hover border), so the ring does not brighten in dark mode.
 
-Helpers: `createToasterClassNames`, `mergeToastClassNames`, `mergeToastOptions`, `mergeToasterStyle`, `filledToastIcons`. Fixture: `tokens/examples/toaster/`.
+Helpers: `createToasterClassNames`, `mergeToastClassNames`, `mergeToastOptions`, `mergeToasterStyle`, `filledToastIcons`. Fixture: `tokens/examples/toaster/` (`update.html` shows the update toast).
+
+For the "Update available" toast, call `showUpdateAvailableToast({ toast, closeConvex })` or let `startUpdateAvailableWatcher` call it. See `app/README.md`.
 
 ## App config
 
@@ -1354,7 +1376,7 @@ const config = {
 } satisfies UiConfig;
 ```
 
-- `Button`: `classes.base`, `classes.variant.<variant>`, `classes.size.<size>`. New size `xs` (`h-7 rounded-md px-2 text-xs hit-target`, 14px icons).
+- `Button`: `classes.base`, `classes.variant.<variant>`, `classes.size.<size>`, `classes.shape.<pill|rounded>` (0.31.0). New size `xs` (`h-7 px-2 text-xs hit-target`, 14px icons). Since 0.31.0 the radius is not in `base` or the size strings: `classes.shape` sets it, one string per shape for every size (built in: `pill` `rounded-full`; `rounded` `rounded-lg`, or `rounded-md` on `xs` and `icon-xs`).
 - `Badge`: `classes.base`, `classes.variant.<variant>`.
 - `Input`, `Textarea`: `classes.base`.
 - `Checkbox`: `classes.root`, `classes.indicator`, `icon`. New prop `icon`: the indicator content (default a 14px check). The `CheckboxProps` type is exported.

package/app/README.md

@@ -0,0 +1,269 @@
+# App helpers (`@vvedantb/ui`)
+
+Shared web React helpers that were duplicated across apps. Source-exported as the `./app` subpath of `@vvedantb/ui`.
+
+## Install
+
+```sh
+npm install @vvedantb/ui
+```
+
+## Peers
+
+Required: `react` and `react-dom` (>=19). Optional peers of `@vvedantb/ui` used by the app helpers: `@clerk/clerk-react` (`useStableAuth`, `ConvexClerkProvider`), `convex` (`ConvexClerkProvider`, `useEnsureUser`), `@tanstack/react-hotkeys` and `zod` (your `z` for `parseClientEnv`). The root imports Clerk and `convex/react` statically, so they must be installed even if you do not use these helpers; see the package README.
+
+`sonner` is not a dependency. The update watcher takes the toast API as an option. The app source uses a local class join, which the root does not export (the root `cn` is the clsx and tailwind-merge one). Tailwind must scan `node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}` so the class names are generated, and the app needs the `@vvedantb/ui/tokens` names (`bg-surface-card`, `divide-separator`, `text-muted-foreground` and so on).
+
+```css
+@source "../node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}";
+```
+
+## Confirm skip (Alt-click)
+
+```tsx
+import { ConfirmSkipHint, skipConfirmTitle, useRequestConfirm } from "@vvedantb/ui";
+
+const { request } = useRequestConfirm();
+
+<DropdownMenuItem
+  title={skipConfirmTitle("Delete")}
+  onSelect={(event) => request(() => setOpen(true), () => remove(), event)}
+>
+  Delete <ConfirmSkipHint />
+</DropdownMenuItem>
+```
+
+- `useRequestConfirm` does not subscribe to Alt. It reads `getAltHeld()` when the request happens, so the menu owner does not re-render when Alt goes down. It returns `{ request }` only.
+- `ConfirmSkipHint` stays mounted and gains a `hidden` class when Alt is not held, so an open Radix menu keeps a stable child tree.
+- The Alt store resets when the last subscriber leaves, clears on blur and tab hide, and cancels a bare Alt keydown only inside `[role='menu']` or `[data-radix-menu-content]`.
+- Also exported: `useAltHeld`, `getAltHeld`, `createAltHeldStore`, `bindToWindow`, `shouldSkipConfirm`, `requestConfirm`.
+
+## Update available watcher
+
+```ts
+import { toast } from "sonner";
+import { startUpdateAvailableWatcher } from "@vvedantb/ui";
+
+useEffect(
+  () =>
+    startUpdateAvailableWatcher({
+      origin: window.location.origin,
+      toast,
+      closeConvex: () => void convex.close(),
+      enabled: !import.meta.env.DEV,
+    }),
+  [],
+);
+```
+
+Options: `origin`, `toast`, `closeConvex?`, `pollMs?` (default 60000), `toastId?` (default `app-update-available`), `enabled?` (default true), `reload?` (default `window.location.reload`). On a changed asset fingerprint it calls `showUpdateAvailableToast` once. `fingerprintFromHtml` and `fetchDeployFingerprint` are exported too. The fingerprint looks for Vite `/assets/*.js` URLs in the index HTML.
+
+`showUpdateAvailableToast({ toast, closeConvex?, toastId?, reload? })` (from 0.31.1) shows the toast on its own, for an app with its own update signal:
+
+```ts
+import { showUpdateAvailableToast, toast } from "@vvedantb/ui";
+
+showUpdateAvailableToast({ toast, closeConvex: () => void convex.close() });
+```
+
+It shows a sticky "Update available" toast, "Refresh to load the latest version.", with a Refresh action. Refresh calls `closeConvex` (errors ignored), then reloads. The same `toastId` replaces an open toast instead of adding a second one. Mount `SonnerToaster`: from 0.31.1 its default `content` class grows the text column, so Refresh sits at the right edge without app classes.
+
+## Settings chrome
+
+```tsx
+import { SettingsPage, SettingsSection, SettingsToggleRow } from "@vvedantb/ui";
+
+<SettingsPage
+  title="Notifications"
+  layout={({ title, headerRight, toolbar, tabs, fillHeight, children }) => (
+    <PageContainer title={title} rightSection={headerRight} toolbar={toolbar} tabs={tabs} noScroll={fillHeight}>
+      {children}
+    </PageContainer>
+  )}
+>
+  <SettingsSection title="Email" bodyVariant="list">
+    <SettingsToggleRow title="Weekly digest" action={<Switch />} />
+  </SettingsSection>
+</SettingsPage>
+```
+
+Exports: `SettingsSection`, `SettingsField`, `SettingsStack`, `SettingsToggleRow`, `SettingsEmptyState` (icon is `ComponentType<{ size?: number; className?: string }>`), `SettingsPage`. `SettingsField` `layout`: `"stacked"` (default) puts the label above the control. `"horizontal"` renders one row with the label and description on the left and the control on the right. Without `layout`, `SettingsPage` renders a plain `div` with a heading and the optional slots.
+
+## useStableAuth
+
+```ts
+import { useStableAuth } from "@vvedantb/ui"; // 2000 ms debounce, wraps Clerk useAuth
+import { createUseStableAuth } from "@vvedantb/ui";
+
+const useAuth = createUseStableAuth(useClerkAuth, { debounceMs: 3000 });
+```
+
+After a signed-in session, a drop to signed-out reports `isLoaded: false` for the debounce window so Convex does not cascade. State is module-level. `resetStableAuthSession()` clears it and is for tests only.
+
+## Develop
+
+```sh
+pnpm --filter @vvedantb/ui typecheck
+pnpm --filter @vvedantb/ui test
+```
+
+Source is in `app/src` and tests in `app/tests`. Publish steps are in the root `README.md`.
+
+## Theme
+
+```tsx
+import { createThemeProvider } from "@vvedantb/ui";
+
+// One kit per app, at module level.
+export const { ThemeProvider, useTheme } = createThemeProvider();
+
+<ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+  <App />
+</ThemeProvider>;
+
+const { theme, resolvedTheme, setTheme, isDark, toggleTheme, mounted } = useTheme();
+```
+
+`createThemeProvider` is a port of next-themes 0.4.6. An app that uses next-themes can switch without a change in behaviour: the same localStorage writes, `<html>` classes and attributes, `style.colorScheme`, `prefers-color-scheme` listener, cross-tab `storage` sync and transition blocking. Parity tests run both side by side.
+
+- Props, as in next-themes: `storageKey` (`"theme"`), `defaultTheme` (`"system"` with `enableSystem`, else `"light"`), `enableSystem` (`true`), `enableColorScheme` (`true`), `attribute` (`"data-theme"`; `"class"`, any `data-*`, or an array), `themes` (`["light", "dark"]`), `value` (theme name to written value), `forcedTheme`, `disableTransitionOnChange` (`false`) and `nonce`.
+- State: `theme`, `setTheme` (a value or a function of the current theme), `resolvedTheme`, `systemTheme`, `forcedTheme` and `themes`, as in next-themes. Added: `mounted` (after the provider's first effect), `isDark` (`mounted && resolvedTheme === "dark"`) and `toggleTheme` (from `resolvedTheme`).
+- `setTheme` is a new function each time `theme` changes and stable otherwise, as in next-themes, so effects that list it re-run at the same times.
+- next-themes reads the DOM options (`attribute`, `themes`, `value`, `enableSystem`, `enableColorScheme`, `defaultTheme`, `disableTransitionOnChange`, `nonce`) once, on the first render, and so does this port. If `enableSystem` starts `false` and later turns `true`, a stored `"system"` is written as the class `system`. `forcedTheme` follows props.
+- A nested `ThemeProvider` from the same kit renders only its children.
+- `createThemeProvider({ missingProviderMessage })`: `useTheme()` outside the provider throws that message. Without it, `useTheme()` returns an empty state with no-op setters, as next-themes does.
+- No inline script is rendered. next-themes renders one for server rendering; React does not run it in a client-rendered app. Keep a pre-paint script in `index.html` if the app has one.
+
+For an app with its own theme state (for example a theme synced from the server), two helpers:
+
+- `getSystemTheme()`: `"dark"` or `"light"` from `prefers-color-scheme`; `"light"` without `window`.
+- `applyThemeClass(theme)`: removes `light` and `dark` from `<html>`, then adds `theme`. No-op without `document`.
+
+## Page title
+
+```tsx
+import { createPageTitleContext } from "@vvedantb/ui";
+
+export const { PageTitleProvider, usePageTitle, usePageTitleSync } = createPageTitleContext({
+  missingProviderMessage: "usePageTitle must be used within a PageTitleProvider",
+});
+
+// The shell reads it:
+const { pageTitle } = usePageTitle();
+// A page publishes it while mounted:
+usePageTitleSync(title);
+```
+
+- `usePageTitle()` returns `{ pageTitle, setPageTitle, mobileActionsSlot, setMobileActionsSlot }`. `mobileActionsSlot` is an element a mobile top bar registers (pass `setMobileActionsSlot` as its `ref`) so pages can portal actions into it.
+- `usePageTitleSync(title)` sets the title while the caller is mounted and clears it on unmount. Titles that are not strings publish `""`.
+- `missingProviderMessage`: `usePageTitle()` outside the provider throws it. Without it, `usePageTitle()` returns an empty title and no-op setters.
+- `documentTitle` (off by default; without it `document.title` is never touched): `{ suffix?, separator? = " · ", fallback? }`. While a page title is set, `document.title` is `` `${pageTitle}${separator}${suffix}` `` (just the page title without a suffix). While it is empty, `fallback`, else the title at mount. The mount-time title comes back on unmount.
+
+## Page motion
+
+```tsx
+import { MotionConfig } from "motion/react";
+import { PageMotionProvider, useDisablePageMotion } from "@vvedantb/ui";
+
+<PageMotionProvider disabled={flags?.disablePageMotion === true} motionConfig={MotionConfig}>
+  <App />
+</PageMotionProvider>;
+```
+
+- Sets `html[data-page-motion]` to `"off"` or `"on"` in a layout effect. The attribute stays after unmount. From 0.15.0 `tokens.css` (through `tokens/css/motion.css`) ships the `"off"` rules: `.ui-page-enter`, `.ui-enter`, `.ui-enter-up` and `.ui-stagger` fade only, `animate-in` / `animate-out`, `.t-modal` and `.t-tabs-pill` stop transitioning, and view transitions stop.
+- Renders `motionConfig` with `reducedMotion` `"always"` when disabled, else `"never"`.
+- `useDisablePageMotion()`: the `disabled` value, `false` outside the provider.
+- This module does not import `motion`. Pass `MotionConfig`, or an app component that wraps it, defined at module level, for example with `LazyMotion`:
+
+```tsx
+function LazyMotionConfig({ reducedMotion, children }: PageMotionConfigProps) {
+  return (
+    <LazyMotion features={domAnimation}>
+      <MotionConfig reducedMotion={reducedMotion}>{children}</MotionConfig>
+    </LazyMotion>
+  );
+}
+```
+
+## Compact relative time
+
+```ts
+import { formatCompactRelativeTime } from "@vvedantb/ui";
+
+formatCompactRelativeTime(createdAt, { justNow: "now" }); // "now", "5m", "3h", "2d", "4mo", "1y"
+formatCompactRelativeTime(updatedAt, { calendar: true }); // "42s", ..., calendar months and years
+```
+
+Pure TypeScript, no dependencies. Options:
+
+- `now`: clock in ms, default `Date.now()`.
+- `justNow`: returned for anything under a minute old, future times included. Without it the result is whole seconds (`"42s"`), and a future time gives `"0s"` or a negative count.
+- `calendar`: `false` (default) counts elapsed time: a day is 24 hours, a month 30 days, a year 12 such months. `true` counts as `dayjs().diff(date, unit)` does: days by the local calendar across DST changes, and calendar months and years.
+
+Strings are parsed with `new Date(string)`. dayjs parses a date-only string such as `"2026-03-01"` as local midnight, `new Date` as UTC midnight; numbers, `Date` objects and ISO strings with a time give the same result either way. An invalid date gives `"NaNy"` (`"0mo"` with `calendar`).
+
+## Convex provider, VITE env and ensure-user (0.10.0)
+
+React and VITE env helpers for Convex apps. The non-React Convex helpers (`mapLoadedQuery`, `forEachLoadedQuery`, `updateAllCachedQueries`, `patchLoadedQuery`, `OptimisticStore`, `tempId`, `createMemoryOptimisticStore`) live in `@vvedantb/server`, so backend packages, tests and React Native can use them without loading this package.
+
+### `ConvexClerkProvider`
+
+```tsx
+import { ConvexClerkProvider, useStableAuth } from "@vvedantb/ui";
+import { ConvexReactClient } from "convex/react";
+
+const convex = new ConvexReactClient(env.VITE_CONVEX_URL);
+
+<ClerkProvider publishableKey={env.VITE_CLERK_PUBLISHABLE_KEY}>
+  <ConvexClerkProvider client={convex} useAuth={useStableAuth}>
+    <App />
+  </ConvexClerkProvider>
+</ClerkProvider>;
+```
+
+| Props | Renders |
+| --- | --- |
+| `client` is `null` or `undefined` | `children` alone (no provider). |
+| `clerk={false}` | `<ConvexProvider client={client}>`. |
+| otherwise | `<ConvexProviderWithClerk client={client} useAuth={useAuth}>`; `useAuth` defaults to `@clerk/clerk-react`'s. |
+
+`clerk` defaults to `true`. Render it inside `ClerkProvider` unless `clerk` is `false`. Types: `ConvexClerkProviderProps`, `ConvexClerkUseAuth`.
+
+### `parseClientEnv`
+
+```ts
+import { z } from "zod";
+import { parseClientEnv } from "@vvedantb/ui";
+
+export const clientEnv = parseClientEnv(import.meta.env, { z, viteEnv: "fallback" });
+// { VITE_CONVEX_URL: string; VITE_CLERK_PUBLISHABLE_KEY: string; VITE_ENV: "development" | "staging" | "production" }
+
+export const extensionEnv = parseClientEnv(import.meta.env, {
+  z,
+  viteEnv: false,
+  extend: { VITE_CLERK_SYNC_HOST: z.string().url() },
+});
+```
+
+The schema is `z.object({ VITE_CONVEX_URL: z.string().min(1), VITE_CLERK_PUBLISHABLE_KEY: z.string().min(1), VITE_ENV: z.enum(["development", "staging", "production"]), ...extend })`, built with your `z` (zod 3.25+ or 4; the package never imports zod at runtime). Only the schema's keys are read from `rawEnv`. Failure throws the `ZodError` from `.parse`.
+
+| `viteEnv` | `VITE_ENV` |
+| --- | --- |
+| `"strict"` (default) | Must be one of `VITE_ENV_NAMES`. |
+| `"fallback"` | Any other value, or none, becomes `"development"` before parsing. |
+| `false` | Not in the schema or the result. |
+
+Types: `ClientEnv`, `ClientEnvWithoutViteEnv`, `ClientEnvOptions`, `ClientEnvSource`, `ViteEnvMode`, `ViteEnvName`.
+
+### `useEnsureUser`
+
+```tsx
+function EnsureUser() {
+  useEnsureUser(api.users.ensureUserExists);
+  return null;
+}
+```
+
+Calls `mutation({})` every time `useConvexAuth().isAuthenticated` becomes `true` (once on mount if already signed in), and logs a rejection with `console.error`. Needs a Convex auth provider above it (`ConvexClerkProvider` with Clerk on). Pair it with `ensureUser` from `@vvedantb/server`. Type: `EnsureUserMutation`.
+
+Tests: `app/tests/convex/` ports each app's copy and runs it beside the helper (env with zod 4 and zod 3.25; provider variants; ensure-user calls over auth sequences). `app/tests-node/convex-esm.test.mjs` loads the helpers in plain Node.

package/app/src/index.ts

@@ -17,7 +17,9 @@ export {
   fingerprintFromHtml,
 } from "./update/deployFingerprint.js";
 export {
+  showUpdateAvailableToast,
   startUpdateAvailableWatcher,
+  type ShowUpdateAvailableToastOptions,
   type UpdateAvailableWatcherOptions,
   type UpdateToastOptions,
 } from "./update/updateWatcher.js";

package/app/src/update/updateWatcher.ts

@@ -16,6 +16,7 @@ export type UpdateAvailableWatcherOptions = {
   closeConvex?: () => void;
   /** Poll interval in ms. Default 60000. */
   pollMs?: number;
+  /** Default `app-update-available`. */
   toastId?: string;
   /** Pass `!import.meta.env.DEV`. When false, nothing starts. Default true. */
   enabled?: boolean;
@@ -23,13 +24,47 @@ export type UpdateAvailableWatcherOptions = {
   reload?: () => void;
 };
 
+export type ShowUpdateAvailableToastOptions = Pick<
+  UpdateAvailableWatcherOptions,
+  "toast" | "closeConvex" | "toastId" | "reload"
+>;
+
 const DEFAULT_POLL_MS = 60_000;
 const DEFAULT_TOAST_ID = "app-update-available";
 
+/**
+ * Show the sticky "Update available" toast with a Refresh action. Refresh
+ * calls `closeConvex` (errors ignored), then reloads. The same `toastId`
+ * replaces an open toast instead of stacking a second one.
+ */
+export function showUpdateAvailableToast({
+  toast,
+  closeConvex,
+  toastId = DEFAULT_TOAST_ID,
+  reload = () => window.location.reload(),
+}: ShowUpdateAvailableToastOptions): void {
+  toast.message("Update available", {
+    id: toastId,
+    description: "Refresh to load the latest version.",
+    duration: Number.POSITIVE_INFINITY,
+    action: {
+      label: "Refresh",
+      onClick: () => {
+        try {
+          closeConvex?.();
+        } catch {
+          // socket may already be closed during teardown
+        }
+        reload();
+      },
+    },
+  });
+}
+
 /**
  * Poll the live index HTML for a new Vite asset fingerprint (and re-check when
- * the tab becomes visible). Shows a sticky "Update available" toast with a
- * Refresh action when a newer deploy is serving. Returns a stop function.
+ * the tab becomes visible). Calls `showUpdateAvailableToast` once when a newer
+ * deploy is serving. Returns a stop function.
  */
 export function startUpdateAvailableWatcher(
   options: UpdateAvailableWatcherOptions,
@@ -39,9 +74,9 @@ export function startUpdateAvailableWatcher(
     toast,
     closeConvex,
     pollMs = DEFAULT_POLL_MS,
-    toastId = DEFAULT_TOAST_ID,
+    toastId,
     enabled = true,
-    reload = () => window.location.reload(),
+    reload,
   } = options;
   if (!enabled) return () => {};
 
@@ -52,22 +87,7 @@ export function startUpdateAvailableWatcher(
   const showToast = (): void => {
     if (shown) return;
     shown = true;
-    toast.message("Update available", {
-      id: toastId,
-      description: "Refresh to load the latest version.",
-      duration: Number.POSITIVE_INFINITY,
-      action: {
-        label: "Refresh",
-        onClick: () => {
-          try {
-            closeConvex?.();
-          } catch {
-            // socket may already be closed during teardown
-          }
-          reload();
-        },
-      },
-    });
+    showUpdateAvailableToast({ toast, closeConvex, toastId, reload });
   };
 
   const check = async (): Promise<void> => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.30.2",
+  "version": "0.31.1",
   "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",
@@ -72,6 +72,17 @@
     "./src/marketing/landing.css",
     "./fonts/instrument-sans.css"
   ],
+  "scripts": {
+    "check:tokens": "node tokens/scripts/check-component-tokens.mjs",
+    "build": "node tokens/scripts/check-exports.mjs && node tokens/scripts/check-component-tokens.mjs && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.consumer.json && tsc -p tsconfig.consumer-speech.json && tsc -p tokens/tsconfig.json",
+    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs app/tests-node/*.test.mjs",
+    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
+    "analyze": "node tokens/verify/analyze.mjs",
+    "brand:assets": "node scripts/build-brand-assets.mjs",
+    "brand:sheet": "node scripts/build-brand-sheet.mjs",
+    "prepack": "node tokens/scripts/check-exports.mjs"
+  },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
@@ -161,6 +172,7 @@
     "@tanstack/react-hotkeys": "^0.13.0",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
+    "@vvedantb/server": "workspace:*",
     "ai": "^5.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -184,8 +196,7 @@
     "vaul": "^1.1.0",
     "vitest": "^3.2.0",
     "zod": "^4.0.0",
-    "zod3": "npm:zod@^3.25.76",
-    "@vvedantb/server": "0.10.0"
+    "zod3": "npm:zod@^3.25.76"
   },
   "peerDependenciesMeta": {
     "@clerk/clerk-react": {
@@ -206,15 +217,5 @@
     "@vvedantb/server": {
       "optional": true
     }
-  },
-  "scripts": {
-    "check:tokens": "node tokens/scripts/check-component-tokens.mjs",
-    "build": "node tokens/scripts/check-exports.mjs && node tokens/scripts/check-component-tokens.mjs && tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.consumer.json && tsc -p tsconfig.consumer-speech.json && tsc -p tokens/tsconfig.json",
-    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs app/tests-node/*.test.mjs",
-    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
-    "analyze": "node tokens/verify/analyze.mjs",
-    "brand:assets": "node scripts/build-brand-assets.mjs",
-    "brand:sheet": "node scripts/build-brand-sheet.mjs"
   }
-}
+}

package/shell/src/SidebarAccountMenu.tsx

@@ -238,19 +238,23 @@ export function AccountAvatar({ imageUrl, userName, className }: SidebarAccountA
   );
 }
 
-export type SidebarAccountTriggerProps = Omit<ButtonProps, "asChild"> & {
+export type SidebarAccountTriggerProps = Omit<ButtonProps, "asChild" | "shape"> & {
   /** Default `title` and `aria-label`, and the avatar initials. Native `name` goes to the button. */
   userName: string;
   imageUrl?: string;
 };
 
-/** Rail-tile-sized avatar button that opens the menu. Children replace the avatar. */
+/**
+ * Rail-tile-sized avatar button that opens the menu. Children replace the avatar.
+ * A rail tile (`rounded-lg`), so `shape="rounded"`; change the radius with `className`.
+ */
 export function AccountTrigger({ userName, imageUrl, className, children, ...props }: SidebarAccountTriggerProps) {
   return (
     <DropdownMenuTrigger asChild>
       <Button
         type="button"
         variant="ghost"
+        shape="rounded"
         title={userName}
         aria-label={`Account menu for ${userName}`}
         {...props}

package/shell/src/SidebarChrome.tsx

@@ -110,14 +110,14 @@ function MobileHeader({ className, onKeyDown, ...props }: SidebarMobileHeaderPro
 
 const defaultMobileMenuIcon = () => <IconMenu2 size={20} />;
 
-export type SidebarMobileMenuButtonProps = Omit<ButtonProps, "children"> & {
+export type SidebarMobileMenuButtonProps = Omit<ButtonProps, "children" | "shape"> & {
   /** `aria-label`. Default `"Open navigation menu"`. */
   label?: string;
   /** Icon for the drawer state. Default a 20px menu icon. */
   icon?: (open: boolean) => ReactNode;
 };
 
-/** Opens the drawer. */
+/** Opens the drawer. `shape="rounded"` (`rounded-lg`); change the radius with `className`. */
 function MobileMenuButton({
   label = "Open navigation menu",
   icon = defaultMobileMenuIcon,
@@ -131,6 +131,7 @@ function MobileMenuButton({
       type="button"
       variant="ghost"
       size="icon"
+      shape="rounded"
       {...props}
       onClick={(event) => {
         onClick?.(event);

package/shell/src/SidebarPanel.tsx

@@ -120,12 +120,15 @@ export function PanelActions({ className, ...props }: SidebarPanelActionsProps)
   return <div {...props} className={cn("flex items-center justify-end gap-0.5", className)} />;
 }
 
-export type SidebarPanelCloseProps = ButtonProps & {
+export type SidebarPanelCloseProps = Omit<ButtonProps, "shape"> & {
   /** `aria-label`. Default `"Close navigation"`. */
   label?: string;
 };
 
-/** Ghost close button. Without `onClick` it closes the `Sidebar.Root` drawer. */
+/**
+ * Ghost close button. Without `onClick` it closes the `Sidebar.Root` drawer.
+ * `shape="rounded"` (`rounded-lg`); change the radius with `className`.
+ */
 export function PanelClose({ label = "Close navigation", onClick, className, children, ...props }: SidebarPanelCloseProps) {
   const sidebar = useOptionalSidebar();
   return (
@@ -133,6 +136,7 @@ export function PanelClose({ label = "Close navigation", onClick, className, chi
       type="button"
       variant="ghost"
       size="icon-sm"
+      shape="rounded"
       {...props}
       onClick={onClick ?? (() => sidebar?.onMobileOpenChange(false))}
       aria-label={label}