@vvedantb/ui 0.4.4 → 0.5.1

package/README.md

@@ -4,7 +4,7 @@ Shared React 19 web UI. Source-exported: no build step.
 
 | Import | What it is |
 | --- | --- |
-| `@vvedantb/ui` | The only JavaScript entry. Primitives (Radix-based), AI elements, audio (`playChime`, `useReplyChime`, `playTone`), `toast` and `SonnerToaster`, the composer (`InputArea`, deprecated 0.3 `Composer`), shell (`SidebarHeader`, `PillTabs`, `SessionsHoverCard`), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`), `cn`, and the native tokens `tokens` and `Tokens`. See `app/README.md` in the repository for the app helpers. |
+| `@vvedantb/ui` | The only JavaScript entry. Primitives (Radix-based), AI elements, audio (`playChime`, `useReplyChime`, `playTone`), `toast` and `SonnerToaster`, the composer (`InputArea`, deprecated 0.3 `Composer`), shell (`SidebarHeader`, `PillTabs`, `SessionsHoverCard`, and the app shell: `AppShell`, `AppSidebar`, `SidebarRail`, `RailTile`, `SidebarPanel`, `SidebarAccountMenu`, `SignOutDialog` and related helpers), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`), `cn`, and the native tokens `tokens` and `Tokens`. See `app/README.md` in the repository for the app helpers. |
 | `@vvedantb/ui/tokens` | `tokens.css`: colour, radius, shadow, ease and font tokens for Tailwind v4. CSS. |
 | `@vvedantb/ui/tokens/tokens.css` | Same file as `@vvedantb/ui/tokens`. CSS. |
 | `@vvedantb/ui/tokens/css/*.css` | `index`, `base`, `dialog`, `modal`, `tabs`, `tabs-pills`, `utilities`, `scrollbar-thin`, `animations`, `compat-shadcn-rgb`. CSS. |
@@ -248,6 +248,109 @@ 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, 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.
+
+```tsx
+import {
+  AppShell, AppSidebar, SidebarRail, RailTile, RailDivider, SidebarPanel,
+  SidebarAccountMenu, DropdownMenuItem, railBadgeClass,
+} from "@vvedantb/ui";
+
+<AppShell
+  panelHidden={collapsed || !hasPanel}
+  sidebar={
+    <AppSidebar
+      isDesktop={isDesktop}
+      collapsed={collapsed}
+      panelHidden={!hasPanel}
+      mobileOpen={open}
+      onMobileOpenChange={setOpen}
+      mobileTitle={pageTitle}
+      rail={
+        <SidebarRail
+          showDivider={hasPanel && !(isDesktop && collapsed)}
+          top={<RailTile asChild label="Home" active={isHome}><Link to="/"><IconHome size={22} /></Link></RailTile>}
+          bodyClassName="scrollbar-thin"
+          footerClassName="border-t border-separator"
+          footer={<SidebarAccountMenu name={name} email={email} imageUrl={avatarUrl}><DropdownMenuItem>Settings</DropdownMenuItem></SidebarAccountMenu>}
+        >
+          <RailDivider />
+        </SidebarRail>
+      }
+      panel={<SidebarPanel title="Library" collapsed={collapsed} onClose={isDesktop ? undefined : () => setOpen(false)}>{nav}</SidebarPanel>}
+    />
+  }
+>
+  {page}
+</AppShell>
+```
+
+- Widths: `AppShell` sets `--app-shell-rail-width` (default `4rem`), `--app-shell-sidebar-width` (rail plus panel, default `20rem`) and `--app-shell-mobile-header-height` (default `calc(3.5rem + env(safe-area-inset-top, 0px))`) as inline style. Change them with `railWidth`, `sidebarWidth` and `mobileHeaderHeight`. The other pieces read these variables. Outside `AppShell`, set the variables yourself or pass a width class with `className`.
+- `AppShell`: `sidebar`, `children`, `panelHidden` (main offsets by the rail width instead of the sidebar width), `skipLinkLabel` (`"Skip to main content"`), `mainId` (`"main-content"`), `className`, `mainClassName`, `contentClassName`.
+- `AppSidebar`: `rail`, `panel` (not rendered while `panelHidden`), `collapsed`, `panelHidden`, `isDesktop`, `mobileOpen`, `onMobileOpenChange`, `id` (default from `useId`), `asideProps` (`data-*` attributes for the `<aside>`), `className`, `mobileTitle`, `mobileMenuIcon` (`(open) => node`, default a menu icon), `mobileMenuLabel` (`"Open navigation menu"`), `closeLabel` (`"Close navigation"`). Swipe left or Escape closes the drawer. The drawer is `inert` while closed on mobile, and closes when `isDesktop` becomes `true`. Close it on route change in the app.
+- `SidebarRail`: `top`, `children` (scroll body), `footer`, `showDivider`, `bodyAsChild` (the single child, for example a tabs list, becomes the body), `className`, `topClassName`, `bodyClassName`, `footerClassName`. Other HTML attributes (`id`, `data-*`, `aria-*`) go to the root `<div>`. The top and footer wrappers render only when their slot is set.
+- `RailTile`: `label` (`aria-label` and tooltip), `active`, `tooltip`, `showTooltip` (default `true`), `badge` (inside the tile, after the children; style it with `railBadgeClass`), `asChild`, `className`. Without `asChild` it is a ghost `Button`; other props go to it. With `asChild` the child (for example a router link) gets the tile classes and `aria-current="page"` when active.
+- `RailDivider`, `SidebarIconTooltip` (`label`, `enabled`, `side` `"right"`, `sideOffset` 8).
+- `SidebarPanel`: `title`, `headerTrailing`, `onClose` (adds the close button; pass it on the mobile drawer only), `closeLabel`, `closeButtonClassName`, `collapsed` (`md:hidden`), `className`, `children`.
+- `SidebarAccountMenu`: `name`, `email` (two-line label when set), `stackedLabel` (two-line layout even without `email`, default `false`), `imageUrl` (initials without it), `align` (`"center"`), `side` (`"right"`), `sideOffset` (8), `collisionPadding`, `contentClassName`, `children` (menu items). `SidebarAccountMenuPlaceholder` is the tile-sized loading box.
+- `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.4.4",
+  "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",
@@ -40,7 +40,7 @@
   "types": "./src/index.ts",
   "files": [
     "src",
-    "shell/src",
+    "shell/src/**/*.{ts,tsx}",
     "app/src",
     "tokens/src",
     "tokens/examples",
@@ -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

@@ -0,0 +1,99 @@
+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`. */
+  sidebar?: ReactNode;
+  children?: ReactNode;
+  /**
+   * `true` when only the rail shows on desktop (sidebar collapsed, or the
+   * current section has no panel). Main then offsets by the rail width
+   * instead of the sidebar width.
+   */
+  panelHidden?: boolean;
+  /** Sets `--app-shell-rail-width`. Default `"4rem"`. */
+  railWidth?: string;
+  /** 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"`. */
+  skipLinkLabel?: string;
+  /** `id` of `<main>` and the skip link target. Default `"main-content"`. */
+  mainId?: string;
+  className?: string;
+  mainClassName?: string;
+  /** Merged onto the content card inside `<main>`. */
+  contentClassName?: string;
+};
+
+type ShellVars = CSSProperties & Record<`--app-shell-${string}`, string>;
+
+/** Full-height app frame: skip link, a sidebar slot and the main content card. */
+export function AppShell({
+  sidebar,
+  children,
+  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",
+  className,
+  mainClassName,
+  contentClassName,
+}: AppShellProps) {
+  const resize = useSidebarResizeState(resizable);
+  const style: ShellVars = {
+    "--app-shell-rail-width": railWidth,
+    "--app-shell-sidebar-width": resize ? `calc(${railWidth} + ${resize.width}px)` : sidebarWidth,
+    "--app-shell-mobile-header-height": mobileHeaderHeight,
+  };
+  return (
+    <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(
+            "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,
+          )}
+        >
+          <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

@@ -0,0 +1,168 @@
+import { useEffect, useId, type KeyboardEvent, type ReactNode } from "react";
+import { AnimatePresence, motion, type PanInfo } from "motion/react";
+import { IconMenu2 } from "@tabler/icons-react";
+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`. */
+  rail: ReactNode;
+  /** Panel beside the rail, usually a `SidebarPanel`. Not rendered while `panelHidden`. */
+  panel?: ReactNode;
+  /** Desktop: show only the rail. The panel stays mounted (hide it with `SidebarPanel collapsed`). */
+  collapsed?: boolean;
+  /** The current section has no panel: the sidebar is rail-wide on every viewport. */
+  panelHidden?: boolean;
+  /** From the app's desktop media query (for example `(min-width: 768px)`). */
+  isDesktop: boolean;
+  /** Mobile drawer state. Owned by the app (which also closes it on route change). */
+  mobileOpen: boolean;
+  onMobileOpenChange: (open: boolean) => void;
+  /** `id` of the drawer, used by the menu button `aria-controls`. Default from `useId`. */
+  id?: string;
+  /** Extra `data-*` attributes for the `<aside>`, for example a view-transition target. */
+  asideProps?: Record<`data-${string}`, string | undefined>;
+  /** Merged onto the `<aside>`. */
+  className?: string;
+  /** Centred in the mobile header when truthy. */
+  mobileTitle?: ReactNode;
+  /** Menu button icon. Default a 20px menu icon. */
+  mobileMenuIcon?: (open: boolean) => ReactNode;
+  /** Default `"Open navigation menu"`. */
+  mobileMenuLabel?: string;
+  /** Backdrop label. Default `"Close navigation"`. */
+  closeLabel?: string;
+};
+
+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`. Inside a resizable
+ * `AppShell` it adds the resize handle while the panel shows on desktop.
+ */
+export function AppSidebar({
+  rail,
+  panel,
+  collapsed = false,
+  panelHidden = false,
+  isDesktop,
+  mobileOpen,
+  onMobileOpenChange,
+  id,
+  asideProps,
+  className,
+  mobileTitle,
+  mobileMenuIcon = defaultMobileMenuIcon,
+  mobileMenuLabel = "Open navigation menu",
+  closeLabel = "Close navigation",
+}: AppSidebarProps) {
+  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.
+  useEffect(() => {
+    if (isDesktop && mobileOpen) onMobileOpenChange(false);
+  }, [isDesktop]);
+
+  const close = () => onMobileOpenChange(false);
+
+  const handleDrawerDragEnd = (
+    _event: MouseEvent | TouchEvent | PointerEvent,
+    info: PanInfo,
+  ) => {
+    if (isDesktop || !mobileOpen) return;
+    if (info.offset.x < -72 || info.velocity.x < -500) {
+      close();
+    }
+  };
+
+  const closeOnEscape = (event: KeyboardEvent) => {
+    if (event.key === "Escape" && !isDesktop && mobileOpen) {
+      close();
+    }
+  };
+
+  return (
+    <>
+      <header
+        onKeyDown={closeOnEscape}
+        className="fixed inset-x-0 top-0 z-30 flex h-[var(--app-shell-mobile-header-height)] items-center gap-2 bg-background/80 px-3 pt-[env(safe-area-inset-top,0px)] pl-[max(0.75rem,env(safe-area-inset-left))] pr-[max(0.75rem,env(safe-area-inset-right))] backdrop-blur-md md:hidden"
+      >
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          onClick={() => onMobileOpenChange(true)}
+          aria-label={mobileMenuLabel}
+          aria-expanded={mobileOpen}
+          aria-controls={drawerId}
+          className={mobileMenuButtonClass}
+        >
+          {mobileMenuIcon(mobileOpen)}
+        </Button>
+        {mobileTitle ? (
+          <h1 className="pointer-events-none absolute inset-x-14 top-[env(safe-area-inset-top,0px)] bottom-0 flex items-center justify-center truncate text-center text-base font-semibold leading-none tracking-tight text-foreground text-balance">
+            {mobileTitle}
+          </h1>
+        ) : null}
+        <div className="ml-auto h-11 w-11 shrink-0" aria-hidden="true" />
+      </header>
+
+      <AnimatePresence initial={false}>
+        {mobileOpen && !isDesktop ? (
+          <motion.button
+            type="button"
+            aria-label={closeLabel}
+            className="fixed inset-0 z-40 bg-backdrop/80 md:hidden"
+            onClick={close}
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            transition={{ duration: motionTiming.sidebar, ease: motionEase }}
+          />
+        ) : null}
+      </AnimatePresence>
+
+      <motion.aside
+        id={drawerId}
+        data-sidebar-layout={layout}
+        {...asideProps}
+        inert={!isDesktop && !mobileOpen}
+        onKeyDown={closeOnEscape}
+        className={cn(
+          "fixed inset-y-0 left-0 z-50 flex bg-background pb-[env(safe-area-inset-bottom,0px)] pt-[env(safe-area-inset-top,0px)] md:py-0",
+          panelHidden
+            ? "w-[var(--app-shell-rail-width)]"
+            : "w-[min(var(--app-shell-sidebar-width),calc(100vw-1.5rem))]",
+          collapsed || panelHidden
+            ? "md:w-[var(--app-shell-rail-width)]"
+            : "md:w-[var(--app-shell-sidebar-width)]",
+          !resize?.isResizing &&
+            "md:transition-[width] md:[transition-duration:280ms] md:[transition-timing-function:cubic-bezier(0.22,1,0.36,1)]",
+          className,
+        )}
+        initial={false}
+        animate={{ x: isDesktop || mobileOpen ? 0 : "-100%" }}
+        transition={{ duration: motionTiming.sidebar, ease: motionEase }}
+        drag={!isDesktop && mobileOpen ? "x" : false}
+        dragDirectionLock
+        dragConstraints={{ left: 0, right: 0 }}
+        dragElastic={{ left: 0.45, right: 0.08 }}
+        onDragEnd={handleDrawerDragEnd}
+      >
+        {rail}
+        {panelHidden ? null : panel}
+        {showResizeHandle ? <SidebarResizeHandle /> : null}
+      </motion.aside>
+    </>
+  );
+}

package/shell/src/SidebarAccountMenu.tsx

@@ -0,0 +1,121 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { Button } from "../../src/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "../../src/ui/dropdown-menu";
+import { cn } from "../../src/utils/cn";
+import { accountEmailClass, railTileClass, railTileStateClass } from "./app-shell-classes";
+
+type ContentProps = ComponentPropsWithoutRef<typeof DropdownMenuContent>;
+
+export type SidebarAccountMenuProps = {
+  /** Trigger `title`, `aria-label` and the menu label. */
+  name: string;
+  /** When set, the label shows the name and email on two lines. */
+  email?: string;
+  /** Always use the two-line label layout, even without `email`. Default `false`. */
+  stackedLabel?: boolean;
+  /** Avatar image. Without it the avatar shows up to two initials of `name`. */
+  imageUrl?: string;
+  /** Default `"center"`. */
+  align?: ContentProps["align"];
+  /** Default `"right"`. */
+  side?: ContentProps["side"];
+  /** Default `8`. */
+  sideOffset?: number;
+  collisionPadding?: ContentProps["collisionPadding"];
+  /** Merged onto the menu content after `w-56`. */
+  contentClassName?: string;
+  /** Menu items after the label and separator. */
+  children?: ReactNode;
+};
+
+function AccountAvatar({ src, name, className }: { src?: string; name: string; className: string }) {
+  if (src) {
+    return (
+      <img
+        src={src}
+        alt=""
+        className={cn(className, "rounded-full object-cover outline outline-1 -outline-offset-1 outline-separator")}
+      />
+    );
+  }
+  const initials = name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase() ?? "")
+    .join("");
+  return (
+    <span
+      className={cn(
+        "flex items-center justify-center rounded-full bg-surface-tertiary text-[10px] font-medium text-foreground outline outline-1 -outline-offset-1 outline-separator",
+        className,
+      )}
+    >
+      {initials || "?"}
+    </span>
+  );
+}
+
+/** Account menu on a rail tile: avatar trigger, identity label, then the app's items. */
+export function SidebarAccountMenu({
+  name,
+  email,
+  stackedLabel = false,
+  imageUrl,
+  align = "center",
+  side = "right",
+  sideOffset = 8,
+  collisionPadding,
+  contentClassName,
+  children,
+}: SidebarAccountMenuProps) {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button
+          type="button"
+          variant="ghost"
+          title={name}
+          aria-label={`Account menu for ${name}`}
+          className={cn(railTileClass, "h-11 w-11 p-0", railTileStateClass(false))}
+        >
+          <AccountAvatar src={imageUrl} name={name} className="h-7 w-7" />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        align={align}
+        side={side}
+        sideOffset={sideOffset}
+        collisionPadding={collisionPadding}
+        className={cn("w-56", contentClassName)}
+      >
+        <DropdownMenuLabel className="flex items-center gap-2 font-normal normal-case tracking-normal">
+          <AccountAvatar src={imageUrl} name={name} className="h-6 w-6 shrink-0" />
+          {stackedLabel || email ? (
+            <span className="min-w-0">
+              <span className="block truncate text-sm font-medium text-foreground">{name}</span>
+              {email ? <span className={accountEmailClass}>{email}</span> : null}
+            </span>
+          ) : (
+            <span className="truncate text-sm font-medium text-foreground">{name}</span>
+          )}
+        </DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        {children}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+export type SidebarAccountMenuPlaceholderProps = { className?: string };
+
+/** Tile-sized placeholder while the account loads. */
+export function SidebarAccountMenuPlaceholder({ className }: SidebarAccountMenuPlaceholderProps) {
+  return <div className={cn("size-11 rounded-lg bg-surface-tertiary", className)} />;
+}