@vvedantb/ui 0.5.0 → 0.5.1

package/README.md

@@ -248,7 +248,7 @@ import {
 - `SelectField`: a labelled single select built from `Select`. Children are `SelectItem`s. An empty `value` shows the placeholder. `id` goes to the trigger and the label points at it. `className` merges onto the trigger.
 - Motion: `springTransition`, `springFastTransition` and `fadeUpSpring` presets. `FadePresence` takes optional `variants` (`hidden`, `show`, `exit`); omitted, it keeps its opacity fade. `PanelTransition` wraps children in React `ViewTransition` with `default="none"` and `enter`/`exit` classes (`vt-panel-in`, `vt-panel-out` by default). It needs a React build that exports `ViewTransition`, and the app supplies the `::view-transition-*` CSS.
 
-## App shell (0.5.0)
+## App shell (0.5.0, 0.5.1)
 
 A sidebar and main page layout, extracted from existing app markup. It is router-free: pass your own links (with `asChild`), state and media query result. Tooltips need a `TooltipProvider` above the shell.
 
@@ -298,6 +298,59 @@ import {
 - `SignOutDialog`: `open`, `onOpenChange` (not called with `false` while `pending`), `pending`, `onConfirm`, `description`, `contentClassName`, `title` (`"Sign out"`), `question` (`"Sign out of your account?"`).
 - Class helpers: `railTileClass`, `railTileStateClass(active)`, `railBadgeClass`, `sidebarNavRowClass(isIconOnly)`, `sidebarNavLinkTextClass(isActive)`, `sidebarSectionLabelClass`.
 
+### Resizable panel (0.5.1)
+
+Pass `resizable` to `AppShell`. Widths are panel px, rail excluded. Without it nothing changes.
+
+```tsx
+<AppShell
+  resizable={{ storageKey: "sidebar-width", defaultWidth: 256, minWidth: 200, maxWidth: 480 }}
+  sidebar={<AppSidebar /* as above */ />}
+>
+  {page}
+</AppShell>
+```
+
+- `resizable`: `storageKey`, `defaultWidth`, `minWidth`, `maxWidth`, `label` (default `"Resize sidebar"`). The shell reads the stored width (a JSON number in `localStorage`) on mount, ignores invalid values, clamps it to the bounds and writes each change. Server and hydration renders use `defaultWidth`. `--app-shell-sidebar-width` becomes `calc(<railWidth> + <width>px)` and `sidebarWidth` is ignored. While resizing, the main margin and `<aside>` width transitions are off.
+- `AppSidebar` adds the handle to the `<aside>` right edge on desktop while the panel shows (not `collapsed`, not `panelHidden`). The mobile drawer has none.
+- `SidebarResizeHandle` (`className`): the handle, for custom layouts. Place it in a positioned parent. Dragging past the bounds rubber-bands and springs back on release. ArrowLeft and ArrowRight step 16px. Double-click resets to `defaultWidth`. It renders nothing outside a resizable `AppShell`.
+- `useAppShellResize()`: `{ width, setWidth, isResizing, minWidth, maxWidth, defaultWidth }`, or `null` outside a resizable `AppShell`. `setWidth` takes a number or an updater.
+
+```tsx
+function PanelWidth() {
+  const resize = useAppShellResize();
+  return resize ? <span>{Math.round(resize.width)}px</span> : null;
+}
+```
+
+### Rail tabs (0.5.1)
+
+`SidebarRail tabs` renders the body as a Radix tabs list (arrow-key roving focus, same classes). Wrap the sidebar in a Tabs root with `orientation="vertical"` (the package `Tabs` works). `RailTile tabValue` renders a tabs trigger: tile classes, the children, the label as sr-only text instead of `aria-label`, then the badge. `active` drives the state classes and other props (for example `aria-expanded`) go to the trigger. `asChild` is ignored with `tabValue`. Without `tabs` and `tabValue` the rail renders as before.
+
+```tsx
+<Tabs value={tab} onValueChange={setTab} orientation="vertical">
+  <AppSidebar
+    /* … */
+    rail={
+      <SidebarRail tabs>
+        <RailTile tabValue="files" label="Files" active={tab === "files"} aria-expanded={tab === "files" ? !collapsed : undefined}>
+          <IconFiles size={22} />
+        </RailTile>
+        <RailTile tabValue="search" label="Search" active={tab === "search"}>
+          <IconSearch size={22} />
+        </RailTile>
+      </SidebarRail>
+    }
+    panel={
+      <>
+        <TabsContent value="files">{files}</TabsContent>
+        <TabsContent value="search">{search}</TabsContent>
+      </>
+    }
+  />
+</Tabs>
+```
+
 ## Toaster
 
 ```tsx

package/app/README.md

@@ -0,0 +1,100 @@
+# 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`, needed only for the app helpers: `@clerk/clerk-react` (`useStableAuth`), `@tanstack/react-hotkeys` and `zod`.
+
+`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 shows a sticky "Update available" toast. Refresh calls `closeConvex` (errors ignored), then reloads. `fingerprintFromHtml` and `fetchDeployFingerprint` are exported too. The fingerprint looks for Vite `/assets/*.js` URLs in the index HTML.
+
+## 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one JavaScript entry (primitives, shell pieces, app helpers, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
@@ -52,6 +52,15 @@
   "sideEffects": [
     "./src/ui/sonner.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 tokens/tsconfig.json",
+    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs",
+    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
+    "analyze": "node tokens/verify/analyze.mjs",
+    "prepack": "node tokens/scripts/check-exports.mjs"
+  },
   "peerDependencies": {
     "@clerk/clerk-react": ">=5",
     "@radix-ui/react-accordion": "^1.2.12",
@@ -162,13 +171,5 @@
     "zod": {
       "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 tokens/tsconfig.json",
-    "test": "node tokens/scripts/check-component-tokens.mjs && vitest run && node --test tokens/test/*.test.mjs",
-    "verify": "node tokens/scripts/check-component-tokens.mjs && node tokens/verify/run.mjs",
-    "analyze": "node tokens/verify/analyze.mjs"
   }
-}
+}

package/shell/src/AppShell.tsx

@@ -1,5 +1,10 @@
 import type { CSSProperties, ReactNode } from "react";
 import { cn } from "../../src/utils/cn";
+import {
+  SidebarResizeProvider,
+  useSidebarResizeState,
+  type SidebarResizeOptions,
+} from "./SidebarResize";
 
 export type AppShellProps = {
   /** Rendered between the skip link and `<main>`, usually an `AppSidebar`. */
@@ -13,8 +18,14 @@ export type AppShellProps = {
   panelHidden?: boolean;
   /** Sets `--app-shell-rail-width`. Default `"4rem"`. */
   railWidth?: string;
-  /** Sets `--app-shell-sidebar-width` (rail plus panel). Default `"20rem"`. */
+  /** Sets `--app-shell-sidebar-width` (rail plus panel). Default `"20rem"`. Ignored with `resizable`. */
   sidebarWidth?: string;
+  /**
+   * Opt-in resizable panel. The shell owns the persisted panel width, sets
+   * `--app-shell-sidebar-width` to `calc(<railWidth> + <width>px)` and shares
+   * the state with `AppSidebar`, `SidebarResizeHandle` and `useAppShellResize`.
+   */
+  resizable?: SidebarResizeOptions;
   /** Sets `--app-shell-mobile-header-height`. Default `"calc(3.5rem + env(safe-area-inset-top, 0px))"`. */
   mobileHeaderHeight?: string;
   /** Default `"Skip to main content"`. */
@@ -36,6 +47,7 @@ export function AppShell({
   panelHidden = false,
   railWidth = "4rem",
   sidebarWidth = "20rem",
+  resizable,
   mobileHeaderHeight = "calc(3.5rem + env(safe-area-inset-top, 0px))",
   skipLinkLabel = "Skip to main content",
   mainId = "main-content",
@@ -43,41 +55,45 @@ export function AppShell({
   mainClassName,
   contentClassName,
 }: AppShellProps) {
+  const resize = useSidebarResizeState(resizable);
   const style: ShellVars = {
     "--app-shell-rail-width": railWidth,
-    "--app-shell-sidebar-width": sidebarWidth,
+    "--app-shell-sidebar-width": resize ? `calc(${railWidth} + ${resize.width}px)` : sidebarWidth,
     "--app-shell-mobile-header-height": mobileHeaderHeight,
   };
   return (
-    <div className={cn("relative h-dvh overflow-hidden bg-background", className)} style={style}>
-      <a
-        href={`#${mainId}`}
-        className="sr-only focus:absolute focus:left-3 focus:top-[max(0.75rem,env(safe-area-inset-top))] focus:z-[100] focus:block focus:rounded-lg focus:bg-surface-secondary focus:px-3 focus:py-2 focus:text-sm focus:font-medium focus:text-foreground focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
-      >
-        {skipLinkLabel}
-      </a>
-      {sidebar}
-      <main
-        id={mainId}
-        tabIndex={-1}
-        className={cn(
-          "relative z-10 flex h-full min-h-0 outline-none md:p-2",
-          panelHidden
-            ? "md:ml-[var(--app-shell-rail-width)]"
-            : "md:ml-[var(--app-shell-sidebar-width)]",
-          "md:transition-[margin-left] md:[transition-duration:280ms] md:[transition-timing-function:cubic-bezier(0.22,1,0.36,1)]",
-          mainClassName,
-        )}
-      >
-        <div
+    <SidebarResizeProvider value={resize}>
+      <div className={cn("relative h-dvh overflow-hidden bg-background", className)} style={style}>
+        <a
+          href={`#${mainId}`}
+          className="sr-only focus:absolute focus:left-3 focus:top-[max(0.75rem,env(safe-area-inset-top))] focus:z-[100] focus:block focus:rounded-lg focus:bg-surface-secondary focus:px-3 focus:py-2 focus:text-sm focus:font-medium focus:text-foreground focus:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+        >
+          {skipLinkLabel}
+        </a>
+        {sidebar}
+        <main
+          id={mainId}
+          tabIndex={-1}
           className={cn(
-            "flex min-h-0 flex-1 flex-col overflow-hidden bg-surface pt-[var(--app-shell-mobile-header-height)] md:rounded-lg md:pt-0",
-            contentClassName,
+            "relative z-10 flex h-full min-h-0 outline-none md:p-2",
+            panelHidden
+              ? "md:ml-[var(--app-shell-rail-width)]"
+              : "md:ml-[var(--app-shell-sidebar-width)]",
+            !resize?.isResizing &&
+              "md:transition-[margin-left] md:[transition-duration:280ms] md:[transition-timing-function:cubic-bezier(0.22,1,0.36,1)]",
+            mainClassName,
           )}
         >
-          {children}
-        </div>
-      </main>
-    </div>
+          <div
+            className={cn(
+              "flex min-h-0 flex-1 flex-col overflow-hidden bg-surface pt-[var(--app-shell-mobile-header-height)] md:rounded-lg md:pt-0",
+              contentClassName,
+            )}
+          >
+            {children}
+          </div>
+        </main>
+      </div>
+    </SidebarResizeProvider>
   );
 }

package/shell/src/AppSidebar.tsx

@@ -5,6 +5,7 @@ import { Button } from "../../src/ui/button";
 import { motionEase, motionTiming } from "../../src/motion/presets";
 import { cn } from "../../src/utils/cn";
 import { mobileMenuButtonClass } from "./app-shell-classes";
+import { SidebarResizeHandle, useSidebarResizeContext } from "./SidebarResize";
 
 export type AppSidebarProps = {
   /** Icon rail, usually a `SidebarRail`. */
@@ -41,7 +42,8 @@ const defaultMobileMenuIcon = () => <IconMenu2 size={20} />;
 /**
  * Sidebar chrome: the mobile header, the drawer backdrop and the `<aside>`
  * (fixed on desktop, a swipe-to-close drawer below it). Reads the
- * `--app-shell-*` width variables set by `AppShell`.
+ * `--app-shell-*` width variables set by `AppShell`. Inside a resizable
+ * `AppShell` it adds the resize handle while the panel shows on desktop.
  */
 export function AppSidebar({
   rail,
@@ -62,6 +64,8 @@ export function AppSidebar({
   const autoId = useId();
   const drawerId = id ?? autoId;
   const layout = isDesktop ? "desktop" : "drawer";
+  const resize = useSidebarResizeContext();
+  const showResizeHandle = resize !== null && isDesktop && !collapsed && !panelHidden;
 
   // Reaching the desktop breakpoint closes the drawer, so it does not reopen
   // on the way back down. Runs on breakpoint change only.
@@ -142,7 +146,8 @@ export function AppSidebar({
           collapsed || panelHidden
             ? "md:w-[var(--app-shell-rail-width)]"
             : "md:w-[var(--app-shell-sidebar-width)]",
-          "md:transition-[width] md:[transition-duration:280ms] md:[transition-timing-function:cubic-bezier(0.22,1,0.36,1)]",
+          !resize?.isResizing &&
+            "md:transition-[width] md:[transition-duration:280ms] md:[transition-timing-function:cubic-bezier(0.22,1,0.36,1)]",
           className,
         )}
         initial={false}
@@ -156,6 +161,7 @@ export function AppSidebar({
       >
         {rail}
         {panelHidden ? null : panel}
+        {showResizeHandle ? <SidebarResizeHandle /> : null}
       </motion.aside>
     </>
   );

package/shell/src/SidebarRail.tsx

@@ -1,5 +1,6 @@
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { Slot, Slottable } from "@radix-ui/react-slot";
+import * as TabsPrimitive from "@radix-ui/react-tabs";
 import { Button } from "../../src/ui/button";
 import { cn } from "../../src/utils/cn";
 import { railTileClass, railTileStateClass } from "./app-shell-classes";
@@ -16,6 +17,12 @@ export type SidebarRailProps = Omit<ComponentPropsWithoutRef<"div">, "children"
   showDivider?: boolean;
   /** Render the body as its single child element (for example a tabs list), with the body classes merged. */
   bodyAsChild?: boolean;
+  /**
+   * Render the body as a Radix tabs list (arrow-key roving focus). Use it
+   * inside a Tabs root with `orientation="vertical"` and give each `RailTile`
+   * a `tabValue`. Default `false`.
+   */
+  tabs?: boolean;
   className?: string;
   topClassName?: string;
   bodyClassName?: string;
@@ -29,6 +36,7 @@ export function SidebarRail({
   footer,
   showDivider = false,
   bodyAsChild = false,
+  tabs = false,
   className,
   topClassName,
   bodyClassName,
@@ -36,6 +44,10 @@ export function SidebarRail({
   ...props
 }: SidebarRailProps) {
   const Body = bodyAsChild ? Slot : "div";
+  const bodyClass = cn(
+    "flex w-full flex-1 flex-col items-center gap-1.5 overflow-y-auto py-2",
+    bodyClassName,
+  );
   return (
     <div
       {...props}
@@ -50,14 +62,13 @@ export function SidebarRail({
           {top}
         </div>
       )}
-      <Body
-        className={cn(
-          "flex w-full flex-1 flex-col items-center gap-1.5 overflow-y-auto py-2",
-          bodyClassName,
-        )}
-      >
-        {children}
-      </Body>
+      {tabs ? (
+        <TabsPrimitive.List asChild={bodyAsChild} className={bodyClass}>
+          {children}
+        </TabsPrimitive.List>
+      ) : (
+        <Body className={bodyClass}>{children}</Body>
+      )}
       {footer == null ? null : (
         <div className={cn("flex w-full flex-col items-center gap-1.5 py-3", footerClassName)}>
           {footer}
@@ -80,10 +91,15 @@ export type RailTileProps = Omit<ComponentPropsWithoutRef<"button">, "children">
   badge?: ReactNode;
   /** Render the single child element (for example a router link) as the tile. */
   asChild?: boolean;
+  /**
+   * Render a Radix tabs trigger for this value (inside a `SidebarRail tabs`).
+   * The label is sr-only text instead of `aria-label`; `asChild` is ignored.
+   */
+  tabValue?: string;
   children: ReactNode;
 };
 
-/** Rail tile with a right-side tooltip. Renders a ghost `Button`, or its child with `asChild`. */
+/** Rail tile with a right-side tooltip. Renders a ghost `Button`, its child with `asChild`, or a tabs trigger with `tabValue`. */
 export function RailTile({
   label,
   active = false,
@@ -91,13 +107,24 @@ export function RailTile({
   showTooltip = true,
   badge,
   asChild = false,
+  tabValue,
   className,
   children,
   ...props
 }: RailTileProps) {
   return (
     <SidebarIconTooltip label={tooltip ?? label} enabled={showTooltip}>
-      {asChild ? (
+      {tabValue !== undefined ? (
+        <TabsPrimitive.Trigger
+          {...props}
+          value={tabValue}
+          className={cn(railTileClass, "group relative", railTileStateClass(active), className)}
+        >
+          {children}
+          <span className="sr-only">{label}</span>
+          {badge}
+        </TabsPrimitive.Trigger>
+      ) : asChild ? (
         <Slot
           {...props}
           aria-label={label}

package/shell/src/SidebarResize.tsx

@@ -0,0 +1,257 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type KeyboardEvent,
+  type PointerEvent,
+} from "react";
+import { animate } from "motion";
+import { cn } from "../../src/utils/cn";
+
+/** Opt-in resizable sidebar panel. Widths are panel px, rail excluded. */
+export type SidebarResizeOptions = {
+  /** `localStorage` key for the panel width (a JSON number). */
+  storageKey: string;
+  defaultWidth: number;
+  minWidth: number;
+  maxWidth: number;
+  /** Handle `aria-label`. Default `"Resize sidebar"`. */
+  label?: string;
+};
+
+type WidthUpdate = number | ((width: number) => number);
+type Animation = ReturnType<typeof animate>;
+
+type SidebarResizeState = {
+  width: number;
+  setWidth: (update: WidthUpdate) => void;
+  isResizing: boolean;
+  minWidth: number;
+  maxWidth: number;
+  defaultWidth: number;
+  label: string;
+  /** Latest width, readable between renders (pointer moves can outpace them). */
+  currentWidth: () => number;
+  stopAnimation: () => void;
+  startResizing: () => void;
+  settleToClamp: (velocity: number) => void;
+};
+
+const SidebarResizeContext = createContext<SidebarResizeState | null>(null);
+export const SidebarResizeProvider = SidebarResizeContext.Provider;
+
+const KEYBOARD_STEP = 16;
+
+function rubberband(overshoot: number, dimension: number, constant = 0.55): number {
+  return (overshoot * dimension * constant) / (dimension + constant * Math.abs(overshoot));
+}
+
+type Sample = { x: number; t: number };
+
+function releaseVelocity(samples: Sample[]): number {
+  if (samples.length < 2) return 0;
+  const newest = samples[samples.length - 1];
+  const oldest = samples[0];
+  if (!newest || !oldest) return 0;
+  const dt = newest.t - oldest.t;
+  if (dt <= 0) return 0;
+  return ((newest.x - oldest.x) / dt) * 1000;
+}
+
+function readStoredWidth(storageKey: string | undefined): number | null {
+  if (storageKey === undefined || typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (raw === null || raw.trim() === "") return null;
+    // A JSON number parses the same with Number(); anything else is NaN.
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeStoredWidth(storageKey: string, width: number) {
+  try {
+    window.localStorage.setItem(storageKey, JSON.stringify(width));
+  } catch {
+    // Storage full or blocked: keep the in-memory width.
+  }
+}
+
+const subscribeNever = () => () => {};
+const serverSnapshot = () => null;
+
+/**
+ * Width and resize state for `AppShell`. Returns `null` without options. The
+ * stored width is read through `useSyncExternalStore` (the server snapshot is
+ * `null`, so SSR and hydration render `defaultWidth`); later writes go to
+ * local state and storage.
+ */
+export function useSidebarResizeState(
+  options: SidebarResizeOptions | undefined,
+): SidebarResizeState | null {
+  const storageKey = options?.storageKey;
+  const stored = useSyncExternalStore(subscribeNever, () => readStoredWidth(storageKey), serverSnapshot);
+  const [override, setOverride] = useState<number | null>(null);
+  const [isResizing, setIsResizing] = useState(false);
+  const widthRef = useRef<number | null>(null);
+  const animRef = useRef<Animation | null>(null);
+
+  useEffect(() => () => animRef.current?.stop(), []);
+
+  if (!options) return null;
+  const { defaultWidth, minWidth, maxWidth } = options;
+  const clampWidth = (width: number) => Math.min(maxWidth, Math.max(minWidth, width));
+  const width = override ?? (stored === null ? defaultWidth : clampWidth(stored));
+  const currentWidth = () => widthRef.current ?? width;
+
+  const setWidth = (update: WidthUpdate) => {
+    const next = typeof update === "function" ? update(currentWidth()) : update;
+    widthRef.current = next;
+    setOverride(next);
+    writeStoredWidth(options.storageKey, next);
+  };
+
+  const stopAnimation = () => animRef.current?.stop();
+
+  const settleToClamp = (velocity: number) => {
+    const from = currentWidth();
+    const to = clampWidth(from);
+    setIsResizing(false);
+    if (from === to) return;
+    animRef.current?.stop();
+    animRef.current = animate(from, to, {
+      type: "spring",
+      bounce: 0.2,
+      duration: 0.35,
+      velocity,
+      onUpdate: (value) => setWidth(value),
+    });
+  };
+
+  return {
+    width,
+    setWidth,
+    isResizing,
+    minWidth,
+    maxWidth,
+    defaultWidth,
+    label: options.label ?? "Resize sidebar",
+    currentWidth,
+    stopAnimation,
+    startResizing: () => setIsResizing(true),
+    settleToClamp,
+  };
+}
+
+export function useSidebarResizeContext(): SidebarResizeState | null {
+  return useContext(SidebarResizeContext);
+}
+
+export type AppShellResize = {
+  /** Panel width in px (rail excluded). Can sit past the bounds mid-drag. */
+  width: number;
+  setWidth: (update: WidthUpdate) => void;
+  isResizing: boolean;
+  minWidth: number;
+  maxWidth: number;
+  defaultWidth: number;
+};
+
+/** Panel width and resize state of the nearest resizable `AppShell`, or `null`. */
+export function useAppShellResize(): AppShellResize | null {
+  const resize = useContext(SidebarResizeContext);
+  if (!resize) return null;
+  const { width, setWidth, isResizing, minWidth, maxWidth, defaultWidth } = resize;
+  return { width, setWidth, isResizing, minWidth, maxWidth, defaultWidth };
+}
+
+export type SidebarResizeHandleProps = { className?: string };
+
+/**
+ * Vertical separator on the right edge of its positioned parent. Drag past the
+ * bounds rubber-bands and springs back on release; arrow keys step 16px;
+ * double-click resets. Renders nothing outside a resizable `AppShell`.
+ */
+export function SidebarResizeHandle({ className }: SidebarResizeHandleProps) {
+  const resize = useContext(SidebarResizeContext);
+  const samplesRef = useRef<Sample[]>([]);
+  if (!resize) return null;
+  const { width, setWidth, isResizing, minWidth, maxWidth, defaultWidth } = resize;
+  const clampWidth = (value: number) => Math.min(maxWidth, Math.max(minWidth, value));
+  const softWidth = (value: number) => {
+    if (value < minWidth) return minWidth - rubberband(minWidth - value, minWidth);
+    if (value > maxWidth) return maxWidth + rubberband(value - maxWidth, maxWidth);
+    return value;
+  };
+
+  const handlePointerDown = (event: PointerEvent<HTMLDivElement>) => {
+    event.preventDefault();
+    resize.stopAnimation();
+    event.currentTarget.setPointerCapture(event.pointerId);
+    samplesRef.current = [{ x: resize.currentWidth(), t: performance.now() }];
+    resize.startResizing();
+  };
+
+  const handlePointerMove = (event: PointerEvent<HTMLDivElement>) => {
+    if (!isResizing) return;
+    const next = softWidth(resize.currentWidth() + event.movementX);
+    const now = performance.now();
+    const samples = samplesRef.current;
+    samples.push({ x: next, t: now });
+    while (samples.length > 5 || now - (samples[0]?.t ?? now) > 80) samples.shift();
+    setWidth(next);
+  };
+
+  const handlePointerUp = (event: PointerEvent<HTMLDivElement>) => {
+    event.currentTarget.releasePointerCapture(event.pointerId);
+    resize.settleToClamp(releaseVelocity(samplesRef.current));
+    samplesRef.current = [];
+  };
+
+  const handlePointerCancel = (event: PointerEvent<HTMLDivElement>) => {
+    event.currentTarget.releasePointerCapture(event.pointerId);
+    resize.settleToClamp(0);
+    samplesRef.current = [];
+  };
+
+  const handleDoubleClick = () => {
+    resize.stopAnimation();
+    setWidth(defaultWidth);
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
+    event.preventDefault();
+    resize.stopAnimation();
+    const step = event.key === "ArrowLeft" ? -KEYBOARD_STEP : KEYBOARD_STEP;
+    setWidth((current) => clampWidth(current + step));
+  };
+
+  return (
+    <div
+      role="separator"
+      aria-orientation="vertical"
+      aria-label={resize.label}
+      aria-valuenow={clampWidth(width)}
+      aria-valuemin={minWidth}
+      aria-valuemax={maxWidth}
+      tabIndex={0}
+      className={cn(
+        "absolute inset-y-0 right-0 z-50 h-full w-1.5 cursor-col-resize outline-hidden transition-[background-color] hover:bg-default focus-visible:bg-default",
+        isResizing && "bg-default",
+        className,
+      )}
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+      onPointerCancel={handlePointerCancel}
+      onDoubleClick={handleDoubleClick}
+      onKeyDown={handleKeyDown}
+    />
+  );
+}

package/shell/src/index.ts

@@ -16,6 +16,12 @@ export { AppSidebar } from "./AppSidebar.js";
 export type { AppSidebarProps } from "./AppSidebar.js";
 export { SidebarRail, RailTile, RailDivider } from "./SidebarRail.js";
 export type { SidebarRailProps, RailTileProps, RailDividerProps } from "./SidebarRail.js";
+export { SidebarResizeHandle, useAppShellResize } from "./SidebarResize.js";
+export type {
+  AppShellResize,
+  SidebarResizeHandleProps,
+  SidebarResizeOptions,
+} from "./SidebarResize.js";
 export { SidebarIconTooltip } from "./SidebarIconTooltip.js";
 export type { SidebarIconTooltipProps } from "./SidebarIconTooltip.js";
 export { SidebarPanel } from "./SidebarPanel.js";

package/src/index.ts

@@ -128,6 +128,12 @@ export { AppSidebar } from "../shell/src/AppSidebar";
 export type { AppSidebarProps } from "../shell/src/AppSidebar";
 export { SidebarRail, RailTile, RailDivider } from "../shell/src/SidebarRail";
 export type { SidebarRailProps, RailTileProps, RailDividerProps } from "../shell/src/SidebarRail";
+export { SidebarResizeHandle, useAppShellResize } from "../shell/src/SidebarResize";
+export type {
+  AppShellResize,
+  SidebarResizeHandleProps,
+  SidebarResizeOptions,
+} from "../shell/src/SidebarResize";
 export { SidebarIconTooltip } from "../shell/src/SidebarIconTooltip";
 export type { SidebarIconTooltipProps } from "../shell/src/SidebarIconTooltip";
 export { SidebarPanel } from "../shell/src/SidebarPanel";

package/tokens/README.md

@@ -0,0 +1,98 @@
+# `@vvedantb/ui/tokens`
+
+Design tokens and shared Tailwind v4 CSS for the vvedantb web apps. The CSS and Tailwind preset are subpaths of `@vvedantb/ui`; the native JS tokens are named exports of the root (`tokens`, `Tokens`). Source-exported: no build step. Paths in the `File` column are relative to `packages/ui/tokens/`.
+
+## Exports
+
+| Export | File | What it is |
+| --- | --- | --- |
+| `@vvedantb/ui/tokens`, `@vvedantb/ui/tokens/tokens.css` | `src/tokens.css` | Colour, radius, shadow, ease and font tokens (`@theme`), light/dark variables, `dark` variant, `*` border and `body` defaults. In 0.2.1 it also defines shadcn-style aliases (`primary`, `muted-foreground`, `secondary`, `destructive`, `card`, `popover`, `input`, `ring`) that point at the same tokens. |
+| `tokens` and `Tokens` from `@vvedantb/ui` | `src/native.ts` | JS colours, radii and spacing for React Native. `@vvedantb/native-ui` keeps its own copy in `src/tokens.ts`; a test keeps the two equal. |
+| `@vvedantb/ui/tokens/css/base.css` | `src/css/base.css` | `html` touch/accent, `::selection`, control transitions, pointer cursor, range accent (`@layer base`). |
+| `@vvedantb/ui/tokens/css/dialog.css` | `src/css/dialog.css` | Unlayered `max-width: none` for `@vvedantb/ui` compact (bottom-sheet) dialogs. |
+| `@vvedantb/ui/tokens/css/modal.css` | `src/css/modal.css` | `.t-modal`, `.is-open`, `.is-closing` and `t-modal-presence-wait` (`@layer components`). |
+| `@vvedantb/ui/tokens/css/tabs.css` | `src/css/tabs.css` | `.t-tab`, active colour, `.t-tabs-pill`, small-screen `.t-tabs` scrolling. |
+| `@vvedantb/ui/tokens/css/tabs-pills.css` | `src/css/tabs-pills.css` | `--tabs-*` colour variables, `.t-tabs--segmented`, `.t-tabs--pills` and pill hover / active fills. |
+| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target`, `@utility reveal-on-hover` and `@utility rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`). |
+| `@vvedantb/ui/tokens/css/scrollbar-thin.css` | `src/css/scrollbar-thin.css` | `.scrollbar-thin` (`@layer utilities`, always emitted). |
+| `@vvedantb/ui/tokens/css/animations.css` | `src/css/animations.css` | `animate-aurora`, `animate-fade-in-up`, `animate-indeterminate` as `@theme` (CSS-first apps). |
+| `@vvedantb/ui/tokens/css/compat-shadcn-rgb.css`, `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | `src/css/compat-shadcn-rgb.css` | Replaces `tokens.css` for apps with shadcn-style `R G B` channel variables. Defines only the UI-only `--color-*` names as `rgb(var(--x) / alpha)` references, `--radius-field`, `--scrollbar`, `--field-radius` and a `glass-panel-strong` fallback. Import it **or** `tokens.css`, never both. |
+| `@vvedantb/ui/tokens/css/index.css` | `src/css/index.css` | base + dialog + utilities + scrollbar-thin + animations, for new CSS-first apps. |
+| `@vvedantb/ui/tokens/tailwind-preset` | `src/tailwind-preset.mjs` (+ `.d.mts`) | Tailwind preset for apps that load a JS config with `@config`. |
+
+Every file was extracted because the same rule (same at-rule context, selector and body) sits in 3 or more of the five apps. The measured duplication is in `verify/ANALYSIS.md`, and the proof that each app compiles to the same CSS after migrating is in `verify/RESULTS.md`. Blocks that only 2 apps share, or that drift in a way that would change an app's CSS, stay in the apps; `verify/ANALYSIS.md` lists them.
+
+## Use
+
+CSS-first app (no `tailwind.config`):
+
+```css
+@import "tailwindcss";
+@import "@vvedantb/ui/tokens";
+@import "@vvedantb/ui/tokens/css/animations.css";
+@import "@vvedantb/ui/tokens/css/base.css";
+/* ...app @layer base rules... */
+@import "@vvedantb/ui/tokens/css/modal.css";
+@import "@vvedantb/ui/tokens/css/tabs.css";
+/* ...app @layer components rules... */
+```
+
+App with a JS config (`@config "../tailwind.config.ts"`):
+
+```ts
+import { tokensPreset } from "@vvedantb/ui/tokens/tailwind-preset";
+
+export default {
+  presets: [tokensPreset()],
+  // or tokensPreset({ color: (name) => `color-mix(in oklch, var(--${name}) calc(<alpha-value> * 100%), transparent)` })
+  content: ["./src/**/*.{ts,tsx}"],
+  theme: { extend: { /* app-only colours, fonts, animations */ } },
+  plugins: [tailwindcssAnimate],
+};
+```
+
+The preset holds `darkMode: "class"`, the shared colour map (`border`, `surface.*`, `danger.*`, `field.*`, shadcn aliases `primary`/`secondary`/`destructive`/`card`/`popover`/`input` ...), `borderRadius` lg/md/sm/field, `boxShadow` soft/panel/insetSoft, `ease-smooth`, `screens` xs to 2xl in px, and the aurora / fade-in-up / indeterminate / accordion keyframes. It does not hold plugins, `content`, fonts, `accent`/`muted`/`ring`/`sidebar` (they differ per app) or accordion timings.
+
+Do not import `css/animations.css` in an app that uses the preset: the preset already defines the same keyframes and animations.
+
+### Where to put the imports
+
+Tailwind inlines an `@import` where it sits, even in the middle of a file (it must be at top level, not inside an `@layer` block). Put each import where the app's own copy of the rules was. Within one layer, later rules win at equal specificity, so moving shared rules above or below app rules can flip the result for elements matched by both. `examples/migration.md` gives the exact position for each app, and `pnpm --filter @vvedantb/ui verify` checks it.
+
+### Variables each file needs
+
+| File | Needs | Provided by |
+| --- | --- | --- |
+| `base.css` | `--accent`, `--foreground` | tokens.css or the app theme |
+| `dialog.css` | none | |
+| `modal.css` | `--modal-open-dur`, `--modal-close-dur`, `--modal-scale`, `--modal-scale-close`, `--modal-ease` | app `:root` |
+| `tabs.css` | `--tabs-dur`, `--tabs-ease` (app `:root`); `--tabs-text-muted`, `--tabs-text-active`, `--tabs-pill-bg` | colours: tabs-pills.css or the app theme |
+| `tabs-pills.css` | `--muted`, `--segment`, `--segment-foreground`, `--default` | tokens.css or the app theme |
+| `utilities.css` | `--breakpoint-sm` (Tailwind default or app theme) | Tailwind |
+| `scrollbar-thin.css` | `--scrollbar` | tokens.css or the app theme |
+| `animations.css` | none | |
+| `tailwind-preset` | the CSS variables named in its colour map, `--radius`, `--field-radius` | tokens.css or the app theme |
+
+### Using an existing shadcn RGB theme
+
+See the package `README.md`. With the compat file, `base.css`, `scrollbar-thin.css`, `utilities.css`, `dialog.css`, `modal.css` and `tabs.css` need no `tokens.css`. `base.css` reads `--accent` and `--foreground` and `tabs-pills.css` reads `--muted`, `--segment` and `--default`. Those are not channel-compatible, so skip `tabs-pills.css` and `index.css` (which includes `base.css`) unless the app defines those variables as full colours.
+
+### Parameters
+
+Where apps share a rule but drifted in one value, the value is a custom property whose fallback is the most common value. Set it on `:root` to keep a different value.
+
+| File | Property | Default | Set by |
+| --- | --- | --- | --- |
+| `base.css` | `--tokens-control-transition-property` | `background-color, border-color, color, box-shadow, transform, opacity` | app-c: `background-color, color, transform, opacity` |
+| `base.css` | `--tokens-control-transition-duration` | `240ms` | app-c: `100ms` |
+
+## Develop
+
+```sh
+pnpm --filter @vvedantb/ui build     # export targets exist + tsc (primitives, shell, app)
+pnpm --filter @vvedantb/ui test      # vitest (app helpers) + offline node --test: exports, CSS structure, Tailwind compile, preset
+pnpm --filter @vvedantb/ui analyze   # rule-level duplication across the app clones -> verify/ANALYSIS.tables.md
+pnpm --filter @vvedantb/ui verify    # before/after compile of every app -> verify/RESULTS.md, examples/migration.md
+```
+
+`analyze` and `verify` need the app clones (`APPS_DIR`, default `/workspace/cvx`; name or symlink the clones `app-a` to `app-e` inside it) and network access the first time: they install Tailwind 4.3.3, the plugins, postcss and jiti into a scratch directory (`VERIFY_DIR`, default `/workspace/pk-tokens-verify`, outside the repo). The migration for each app is data in `verify/migrations/<app>.json`. Each removed block must equal the shared file's block with the same context and selector, or the run fails.