@vvedantb/ui 0.4.3 → 0.5.0

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. |
@@ -214,6 +214,90 @@ import { ConfirmDialog, SlideOverPanel, ToolbarSearchInput } from "@vvedantb/ui"
 - `ToolbarSearchInput`: a compact `h-8` search field for toolbars, with a search icon and a clear button. The clear button stays mounted and is hidden while the value is blank. Clearing calls `onChange("")` and does not move focus. Defaults: `placeholder="Search..."`, `label="Search"` (the `aria-label`), `clearLabel="Clear search"`. The ref goes to the `<input>`.
 - `ConfirmDialog` `size`: `"default"` keeps the alert dialog. `"sm"` renders a compact, dismissible dialog (outside click, Escape and the close button close it) with small Cancel and confirm buttons. Cancel calls `onCancel` and then `onOpenChange(false)`. Confirm calls `onConfirm` only, so the caller closes it.
 
+## Buttons, menus and fields (0.4.4)
+
+All of these are opt-in. Without the new props, components render as before.
+
+```tsx
+import {
+  Button, CardHeader, CommandDialog, DropdownMenuContent, DropdownMenuItem,
+  FadePresence, PanelTransition, PopoverContent, SelectField, SelectItem,
+  fadeUpSpring, restoreModalScrollLock,
+} from "@vvedantb/ui";
+
+<Button variant="flat" loading={saving} endContent={<IconArrowRight />}>Save</Button>
+
+<DropdownMenuContent fitViewport suppressAltKey restoreScrollLockOnClose>
+  <DropdownMenuItem startContent={<IconFile />} endContent={<Kbd>⌘O</Kbd>}>Open</DropdownMenuItem>
+</DropdownMenuContent>
+
+<SelectField id="tone" label="Tone" placeholder="Pick one" value={tone} onValueChange={setTone}>
+  <SelectItem value="calm">Calm</SelectItem>
+</SelectField>
+
+<FadePresence show={visible} variants={fadeUpSpring}>…</FadePresence>
+```
+
+- `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`.
+- `PopoverContent` `fitViewport`: grows from the trigger (`--radix-popper-transform-origin`), defaults `collisionPadding` to 8 (your value wins) and, on small screens, caps width to `100vw - 1.5rem` and height as above.
+- `CommandDialog`: `title` and `description` add a visually hidden dialog header. `className` merges onto the dialog content. `shouldFilter` goes to `Command`. `listLayout` is `"pinned"` (default, fixed list height) or `"auto"` (the list sizes itself and items keep your styling).
+- `restoreModalScrollLock()`: clears body `pointer-events`, and, when no dialog or alert dialog is open, the body and root `overflow` and body `padding-right` left by a modal menu.
+- `CardHeader`: `flex flex-col space-y-1.5 p-6`.
+- `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)
+
+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`.
+
 ## Toaster
 
 ```tsx
@@ -255,7 +339,7 @@ Helpers: `createToasterClassNames`, `mergeToastClassNames`, `mergeToastOptions`,
 
 ## Colour names in components
 
-Components use `text-muted-foreground`, `primary` and `--color-*` theme variables. They no longer use `text-muted`, `*-accent` or raw `var(--muted)` reads, which clash with shadcn names. `tokens.css` still defines `--color-muted` and `--color-accent`. `pnpm --filter @vvedantb/ui check:tokens` fails if a component brings the old names back (it also runs in `build`, `test` and `verify`).
+Components use `text-muted-foreground`, `primary` and `--color-*` theme variables. They no longer use `text-muted`, `*-accent` or raw `var(--muted)` reads, which clash with shadcn names. Exceptions that match existing app markup on purpose: the `InputArea` ghost text, the `Button` `flat` variant and the `CommandDialog` `listLayout="auto"` group headings use `text-muted`. `tokens.css` still defines `--color-muted` and `--color-accent`. `pnpm --filter @vvedantb/ui check:tokens` fails if a component brings the old names back (it also runs in `build`, `test` and `verify`).
 
 ## Using an existing shadcn RGB theme
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "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",

package/shell/src/AppShell.tsx

@@ -0,0 +1,83 @@
+import type { CSSProperties, ReactNode } from "react";
+import { cn } from "../../src/utils/cn";
+
+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"`. */
+  sidebarWidth?: string;
+  /** 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",
+  mobileHeaderHeight = "calc(3.5rem + env(safe-area-inset-top, 0px))",
+  skipLinkLabel = "Skip to main content",
+  mainId = "main-content",
+  className,
+  mainClassName,
+  contentClassName,
+}: AppShellProps) {
+  const style: ShellVars = {
+    "--app-shell-rail-width": railWidth,
+    "--app-shell-sidebar-width": 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
+          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>
+  );
+}

package/shell/src/AppSidebar.tsx

@@ -0,0 +1,162 @@
+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";
+
+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`.
+ */
+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";
+
+  // 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)]",
+          "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}
+      </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)} />;
+}

package/shell/src/SidebarIconTooltip.tsx

@@ -0,0 +1,34 @@
+import type { ReactElement } from "react";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../../src/ui/tooltip";
+
+export type SidebarIconTooltipProps = {
+  label: string;
+  enabled: boolean;
+  children: ReactElement;
+  /** Default `"right"`. */
+  side?: "top" | "right" | "bottom" | "left";
+  /** Default `8`. */
+  sideOffset?: number;
+};
+
+// radix tooltip for icon-only sidebar rail — skipped when labels are visible
+export function SidebarIconTooltip({
+  label,
+  enabled,
+  children,
+  side = "right",
+  sideOffset = 8,
+}: SidebarIconTooltipProps) {
+  if (!enabled) {
+    return children;
+  }
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{children}</TooltipTrigger>
+      <TooltipContent side={side} sideOffset={sideOffset}>
+        {label}
+      </TooltipContent>
+    </Tooltip>
+  );
+}

package/shell/src/SidebarPanel.tsx

@@ -0,0 +1,71 @@
+import type { ReactNode } from "react";
+import { IconX } from "@tabler/icons-react";
+import { Button } from "../../src/ui/button";
+import { cn } from "../../src/utils/cn";
+import { panelCloseButtonClass } from "./app-shell-classes";
+import { SidebarHeader } from "./SidebarHeader";
+
+export type SidebarPanelProps = {
+  title: string;
+  /** Rendered in the header, before the close button. */
+  headerTrailing?: ReactNode;
+  /** When set, a close button follows `headerTrailing`. Pass it on the mobile drawer only. */
+  onClose?: () => void;
+  /** Close button label. Default `"Close navigation"`. */
+  closeLabel?: string;
+  /** Merged onto the close button. */
+  closeButtonClassName?: string;
+  /** Desktop: hides the panel (`md:hidden`) and leaves the rail. */
+  collapsed?: boolean;
+  className?: string;
+  /** Panel body: nav, footer and so on. */
+  children?: ReactNode;
+};
+
+/** Sidebar panel column beside the rail: a `SidebarHeader` and the app's body. */
+export function SidebarPanel({
+  title,
+  headerTrailing,
+  onClose,
+  closeLabel = "Close navigation",
+  closeButtonClassName,
+  collapsed = false,
+  className,
+  children,
+}: SidebarPanelProps) {
+  const trailing =
+    headerTrailing || onClose ? (
+      <>
+        {headerTrailing}
+        {onClose ? (
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon-sm"
+            onClick={onClose}
+            aria-label={closeLabel}
+            className={cn(panelCloseButtonClass, closeButtonClassName)}
+          >
+            <IconX className="h-4 w-4" />
+          </Button>
+        ) : null}
+      </>
+    ) : null;
+
+  return (
+    <div
+      className={cn(
+        // No border-r: the main content card floats beside this panel, so a
+        // right edge line reads as a hard divider.
+        "relative flex h-full min-w-0 flex-1 flex-col overflow-hidden bg-background",
+        collapsed && "md:hidden",
+        className,
+      )}
+    >
+      <div className="px-2 pt-3">
+        <SidebarHeader title={title} trailing={trailing} />
+      </div>
+      {children}
+    </div>
+  );
+}