@vvedantb/ui 0.5.3 → 0.6.0

package/README.md

@@ -69,7 +69,7 @@ import { InputArea, InputBanners, buildComposerSlashItems } from "@vvedantb/ui";
 
 | Prop | Default | Notes |
 | --- | --- | --- |
-| `value`, `onChange`, `defaultValue` | uncontrolled, `""` | `onSubmit` clears the draft through `onChange("")` first. Restore it yourself if sending fails. |
+| `value`, `onChange`, `defaultValue` | uncontrolled, `""` | `onSubmit` clears the draft through `onChange("")` first. Restore it yourself if sending fails. A value of `"\n"` shows as an empty editor with the placeholder, and the editor never reports a trailing line holder newline (0.5.4). |
 | `onSubmit(text)` | none | Trimmed text. Not called while `isSending`, or when send is disabled. |
 | `onStop`, `isStreaming`, `isSending`, `isUploading` | off | While streaming, stop shows next to send, and send queues. Sending or uploading shows a spinner and disables send. |
 | `canSubmit` | text, or `fileCount` or `chipCount` above 0 | Overrides when send is enabled. |
@@ -215,6 +215,7 @@ import { ConfirmDialog, SlideOverPanel, ToolbarSearchInput } from "@vvedantb/ui"
 - `SlideOverPanel`: a right-side panel, absolutely positioned inside its nearest positioned parent. It is not a portal or dialog. It slides in with a spring and is hidden below `md`. Only the close button closes it (no Escape, no outside click). `width` is `"w-96"` (default) or `"w-80"`. `closeLabel` defaults to `"Close panel"`. `className` merges last.
 - `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. `"md"` (0.5.2) is dismissible like `"sm"`, with the title in a header (`pb-4`), the description in its own section (`py-6`) and a footer (`pt-4`) with default-size buttons. It has the same Cancel and confirm behaviour as `"sm"`.
+- Legacy (still supported): the `ConfirmDialog` `size`, `variant`, `cancelLabel` and `confirmLabel` props. For anything they do not cover, compose the parts (see [Composable parts](#composable-parts-060)).
 
 ## Buttons, menus and fields (0.4.4)
 
@@ -250,7 +251,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 to 0.5.3)
+## App shell (0.5.0 to 0.5.4)
 
 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.
 
@@ -291,13 +292,13 @@ import {
 
 - 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`, `mobileHeaderActions` (0.5.2; trailing actions such as icon buttons, in place of the end spacer), `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.
+- `AppSidebar`: legacy (still supported) `rail`, `panel` and `mobile*` props; compose `Sidebar.*` instead. `rail`, `panel` (not rendered while `panelHidden`), `collapsed`, `panelHidden`, `isDesktop`, `mobileOpen`, `onMobileOpenChange`, `id` (default from `useId`), `asideProps` (`data-*` attributes for the `<aside>`), `className`, `mobileTitle`, `mobileHeaderActions` (0.5.2; trailing actions such as icon buttons, in place of the end spacer), `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. The mobile header is a three-column grid, so the title and trailing actions stay on one row and a long title truncates (0.5.4).
+- `SidebarRail`: legacy (still supported) `top`, `footer`, `bodyAsChild`, `tabs` and `*ClassName` props; compose `Sidebar.Rail` parts instead. `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 native `<button type="button">` (0.5.3), so icons keep their authored size; 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). 0.5.2 adds `badge` (unread dot beside the trigger, in a `relative` wrapper around the menu, so the trigger's dimming and press scale skip it: `true` shows it, `false` fades it out, omitted renders no wrapper and no dot), `triggerProps` (spread onto the trigger `Button` after the defaults; `className` merges last) and `contentProps` (spread onto `DropdownMenuContent`, for example `fitViewport` or `aria-label`; no `className`, use `contentClassName`). `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?"`).
+- `SidebarPanel`: legacy (still supported) `headerTrailing`, `onClose`, `closeLabel` and `closeButtonClassName`; compose `Sidebar.Panel` parts instead. `title`, `headerTrailing`, `onClose` (adds the close button; pass it on the mobile drawer only), `closeLabel`, `closeButtonClassName`, `collapsed` (`md:hidden`), `className`, `children`.
+- `SidebarAccountMenu`: legacy (still supported) `badge`, `triggerProps`, `contentProps` and `stackedLabel`; compose `Sidebar.Account*` parts instead. `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). 0.5.2 adds `badge` (unread dot beside the trigger, in a `relative` wrapper around the menu, so the trigger's dimming and press scale skip it: `true` shows it, `false` fades it out, omitted renders no wrapper and no dot), `triggerProps` (spread onto the trigger `Button` after the defaults; `className` merges last) and `contentProps` (spread onto `DropdownMenuContent`, for example `fitViewport` or `aria-label`; no `className`, use `contentClassName`). `SidebarAccountMenuPlaceholder` is the tile-sized loading box.
+- `SignOutDialog`: legacy (still supported) `question` and `title`; compose `ConfirmDialog` parts with `alert={false}` for other copy. `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`.
 
 ### Header actions and account badge (0.5.2)
@@ -380,6 +381,163 @@ function PanelWidth() {
 </Tabs>
 ```
 
+## Composable parts (0.6.0)
+
+Shadcn-style building blocks. The prop-driven components above are thin compositions of them and render the same DOM.
+
+Convention: compound parts are static members of a namespace object, `<Namespace>.<Part>`. There are three namespaces: `ConfirmDialog.*`, `AppShell.*` and `Sidebar.*`. `ConfirmDialog` and `AppShell` stay callable with their legacy props. `Sidebar` is a plain object. Prop types are exported flat, for example `ConfirmDialogRootProps`, `AppShellMainProps` and `SidebarRailItemProps`. Every part that renders an element merges `className` last and forwards native props.
+
+### `ConfirmDialog.*`
+
+| Part | Purpose |
+| --- | --- |
+| `Root` | Radix dialog root. `size` (`"default"`, `"sm"`, `"md"`: layout slot for the other parts), `alert` (blocking alert dialog; default `size === "default"`), `pending` (swallows close requests, disables Cancel, Action shows its pending state), `confirmPhrase` (type-to-confirm; the typed text resets each time the dialog opens). |
+| `Content` | `AlertDialogContent` with `alert`, else `DialogContent`. `sm` and `md` add `sm:max-w-96`. Takes every `DialogContent` prop (`role`, `hideCloseButton`, ...). |
+| `Header` | `DialogHeader`; `md` adds `pb-4`. |
+| `Title` | `DialogTitle`; `sm` adds `mb-2 text-sm font-medium`. |
+| `Description` | `DialogDescription`; `sm` and `md` add their spacing. |
+| `Body` | Plain `<div>` for extra content. No default classes. |
+| `Footer` | `DialogFooter` (`md` adds `pt-4`); `sm` renders a `flex justify-end gap-2` row. |
+| `Cancel` | Alert: the outline `AlertDialogCancel` (closes through Radix). Otherwise a ghost `Button` that runs `onClick`, then (unless it called `preventDefault()`) the Root `onOpenChange(false)`. Disabled while pending. Default text `"Cancel"`. |
+| `Action` | Confirm button. Never closes the dialog. Disabled while `disabled`, pending, or until `confirmPhrase` matches. `pendingLabel` replaces the children with a spinner (`spinnerSize`, default 14) and the label while pending. |
+| `Field` | Type-to-confirm input bound to `confirmPhrase` (trimmed, case-insensitive). `label` replaces the label content, `onEnter` runs on Enter while the phrase matches, `inputProps` go to the `Input`. |
+
+`useConfirmDialog()` returns `{ size, alert, pending, phraseMatches, typed, setTyped, requestClose }` for custom parts.
+
+### `AppShell.*`
+
+| Part | Purpose |
+| --- | --- |
+| `Root` | Frame `<div>`. Sets the `--app-shell-*` variables (`railWidth`, `sidebarWidth`, `mobileHeaderHeight`), owns the `resizable` state, and passes `panelHidden` and `mainId` to the parts. `style` merges over the variables. |
+| `SkipLink` | Visually hidden link to `<main>`. `label` (`"Skip to main content"`), `targetId` (default the Root `mainId`). |
+| `Main` | The `<main>`. Offsets by the sidebar width, or the rail width while `panelHidden`. `id` defaults to the Root `mainId` (`"main-content"`). |
+| `Content` | The content card inside `<main>`. |
+
+### `Sidebar.*`
+
+| Part | Purpose |
+| --- | --- |
+| `Root` | No DOM. Holds `isDesktop`, `mobileOpen`, `onMobileOpenChange`, `collapsed`, `panelHidden` and the drawer `id`. Closes the drawer at the desktop breakpoint. The chrome parts need it. |
+| `MobileHeader` | Fixed header below `md`, a three-column grid (menu button, title, actions). Escape closes the drawer. Keep all three children so the columns line up. |
+| `MobileMenuButton` | Opens the drawer. `label`, `icon` (`(open) => node`). |
+| `MobileTitle` | Centred `<h1>` that truncates. Without children, an empty `<span>` keeps the middle column. |
+| `MobileActions` | Trailing header actions. Without children, a spacer that keeps the title centred. |
+| `Backdrop` | Drawer backdrop; a click closes the drawer. `label` (`"Close navigation"`). |
+| `Aside` | The `<aside>`: fixed on desktop, a swipe-to-close drawer below it. `id` overrides the Root id. |
+| `ResizeHandle` | `SidebarResizeHandle` in a resizable `AppShell`, shown on desktop while the panel shows. Place it inside `Aside`. |
+| `Rail` | Rail column. `showDivider`. |
+| `RailHeader` / `RailBody` / `RailFooter` | Top block, scroll body (`asChild`, `tabs` for a Radix tabs list) and bottom block. `Footer` is an alias of `RailFooter`. |
+| `RailItem` | Rail tile with tooltip (`RailTile`): `label`, `active`, `tooltip`, `showTooltip`, `badge`, `asChild`, `tabValue`. |
+| `RailSeparator` | Short rule between rail items (`RailDivider`). |
+| `Tooltip` | Right-side icon tooltip (`SidebarIconTooltip`). |
+| `Panel` | Panel column. `collapsed` (`md:hidden`) and `panelHidden` (renders nothing) default to the Root values. |
+| `PanelHeader` | Padded header row for `PanelTitle` and `PanelActions`. |
+| `PanelTitle` / `PanelActions` | The `<h2>` and the trailing actions. |
+| `PanelClose` | Ghost close button. `label` (`"Close navigation"`). Without `onClick` it closes the drawer. |
+| `AccountMenu` | Dropdown root. `badge` adds the unread dot (`AccountBadge`) in a `relative` wrapper. |
+| `AccountTrigger` | Rail-tile-sized avatar button. `userName` (default `title` and `aria-label`, and the initials), `imageUrl`, plus `Button` props; native `name` goes to the button. |
+| `AccountAvatar` | Avatar image or initials. `userName`, `imageUrl`. |
+| `AccountContent` | Menu content. Defaults `align="center"`, `side="right"`, `sideOffset={8}`, `w-56`. |
+| `AccountLabel` | Identity label: avatar, `userName`, optional `email`, `stacked`. |
+| `AccountSeparator` | Separator after the label. Kept separate so the label can stand alone. |
+| `AccountBadge` | Unread dot. `visible` (default `true`; `false` fades it out). |
+
+### Examples
+
+A destructive confirm with a pending state and type-to-confirm:
+
+```tsx
+<ConfirmDialog.Root open={open} onOpenChange={setOpen} pending={deleting} confirmPhrase={item.name}>
+  <ConfirmDialog.Content>
+    <ConfirmDialog.Header>
+      <ConfirmDialog.Title>Delete item?</ConfirmDialog.Title>
+      <ConfirmDialog.Description>This cannot be undone.</ConfirmDialog.Description>
+    </ConfirmDialog.Header>
+    <ConfirmDialog.Field onEnter={remove} />
+    <ConfirmDialog.Footer>
+      <ConfirmDialog.Cancel />
+      <ConfirmDialog.Action variant="destructive" pendingLabel="Deleting..." onClick={remove}>
+        Delete
+      </ConfirmDialog.Action>
+    </ConfirmDialog.Footer>
+  </ConfirmDialog.Content>
+</ConfirmDialog.Root>
+```
+
+A dismissible rename dialog:
+
+```tsx
+<ConfirmDialog.Root open={open} onOpenChange={setOpen} alert={false}>
+  <ConfirmDialog.Content>
+    <ConfirmDialog.Header>
+      <ConfirmDialog.Title>Rename</ConfirmDialog.Title>
+    </ConfirmDialog.Header>
+    <ConfirmDialog.Body>
+      <Input value={name} onChange={(event) => setName(event.target.value)} aria-label="Name" />
+    </ConfirmDialog.Body>
+    <ConfirmDialog.Footer>
+      <ConfirmDialog.Cancel />
+      <ConfirmDialog.Action disabled={!name.trim()} onClick={save}>Save</ConfirmDialog.Action>
+    </ConfirmDialog.Footer>
+  </ConfirmDialog.Content>
+</ConfirmDialog.Root>
+```
+
+A full shell:
+
+```tsx
+<AppShell.Root panelHidden={collapsed || !hasPanel} resizable={resizeOptions}>
+  <AppShell.SkipLink />
+  <Sidebar.Root
+    isDesktop={isDesktop}
+    mobileOpen={open}
+    onMobileOpenChange={setOpen}
+    collapsed={collapsed}
+    panelHidden={!hasPanel}
+  >
+    <Sidebar.MobileHeader>
+      <Sidebar.MobileMenuButton />
+      <Sidebar.MobileTitle>{pageTitle}</Sidebar.MobileTitle>
+      <Sidebar.MobileActions />
+    </Sidebar.MobileHeader>
+    <Sidebar.Backdrop />
+    <Sidebar.Aside>
+      <Sidebar.Rail showDivider>
+        <Sidebar.RailHeader>
+          <Sidebar.RailItem asChild label="Home" active={isHome}>
+            <Link to="/"><IconHome size={22} /></Link>
+          </Sidebar.RailItem>
+        </Sidebar.RailHeader>
+        <Sidebar.RailBody>
+          <Sidebar.RailItem label="Search"><IconSearch size={22} /></Sidebar.RailItem>
+        </Sidebar.RailBody>
+        <Sidebar.RailFooter>
+          <Sidebar.AccountMenu>
+            <Sidebar.AccountTrigger userName={name} imageUrl={avatarUrl} />
+            <Sidebar.AccountContent>
+              <Sidebar.AccountLabel userName={name} email={email} imageUrl={avatarUrl} />
+              <Sidebar.AccountSeparator />
+              <DropdownMenuItem>Settings</DropdownMenuItem>
+            </Sidebar.AccountContent>
+          </Sidebar.AccountMenu>
+        </Sidebar.RailFooter>
+      </Sidebar.Rail>
+      <Sidebar.Panel>
+        <Sidebar.PanelHeader>
+          <Sidebar.PanelTitle>Library</Sidebar.PanelTitle>
+          <Sidebar.PanelActions>{isDesktop ? null : <Sidebar.PanelClose />}</Sidebar.PanelActions>
+        </Sidebar.PanelHeader>
+        {nav}
+      </Sidebar.Panel>
+      <Sidebar.ResizeHandle />
+    </Sidebar.Aside>
+  </Sidebar.Root>
+  <AppShell.Main>
+    <AppShell.Content>{page}</AppShell.Content>
+  </AppShell.Main>
+</AppShell.Root>
+```
+
 ## Toaster
 
 ```tsx

package/package.json

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

package/shell/src/AppShell.tsx

@@ -1,7 +1,8 @@
-import type { CSSProperties, ReactNode } from "react";
+import { createContext, useContext, type ComponentProps, type CSSProperties, type ReactNode } from "react";
 import { cn } from "../../src/utils/cn";
 import {
   SidebarResizeProvider,
+  useSidebarResizeContext,
   useSidebarResizeState,
   type SidebarResizeOptions,
 } from "./SidebarResize";
@@ -40,60 +41,146 @@ export type AppShellProps = {
 
 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,
+type AppShellContextValue = { mainId: string; panelHidden: boolean };
+
+const AppShellContext = createContext<AppShellContextValue>({
+  mainId: "main-content",
+  panelHidden: false,
+});
+
+export type AppShellRootProps = ComponentProps<"div"> &
+  Pick<AppShellProps, "panelHidden" | "railWidth" | "sidebarWidth" | "resizable" | "mobileHeaderHeight" | "mainId">;
+
+/** Frame `<div>`: sets the `--app-shell-*` variables and owns the resize state. `style` merges over the variables. */
+function Root({
   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) {
+  style,
+  ...props
+}: AppShellRootProps) {
   const resize = useSidebarResizeState(resizable);
-  const style: ShellVars = {
+  const vars: 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>
+    <AppShellContext.Provider value={{ mainId, panelHidden }}>
+      <SidebarResizeProvider value={resize}>
+        <div
+          {...props}
+          className={cn("relative h-dvh overflow-hidden bg-background", className)}
+          style={{ ...vars, ...style }}
+        />
+      </SidebarResizeProvider>
+    </AppShellContext.Provider>
+  );
+}
+
+export type AppShellSkipLinkProps = Omit<ComponentProps<"a">, "children" | "href"> & {
+  /** Default `"Skip to main content"`. */
+  label?: ReactNode;
+  /** Default the Root `mainId`. */
+  targetId?: string;
+};
+
+/** Visually hidden link to `<main>`, shown on focus. */
+function SkipLink({ label = "Skip to main content", targetId, className, ...props }: AppShellSkipLinkProps) {
+  const { mainId } = useContext(AppShellContext);
+  return (
+    <a
+      href={`#${targetId ?? mainId}`}
+      {...props}
+      className={cn(
+        "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",
+        className,
+      )}
+    >
+      {label}
+    </a>
+  );
+}
+
+export type AppShellMainProps = ComponentProps<"main">;
+
+/** `<main>`, offset by the sidebar (or rail while the Root `panelHidden`). `id` defaults to the Root `mainId`. */
+function Main({ id, className, ...props }: AppShellMainProps) {
+  const { mainId, panelHidden } = useContext(AppShellContext);
+  const resize = useSidebarResizeContext();
+  return (
+    <main
+      id={id ?? mainId}
+      tabIndex={-1}
+      {...props}
+      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)]",
+        className,
+      )}
+    />
   );
 }
+
+export type AppShellContentProps = ComponentProps<"div">;
+
+/** Content card inside `<main>`. Pads for the mobile header below `md`. */
+function Content({ className, ...props }: AppShellContentProps) {
+  return (
+    <div
+      {...props}
+      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",
+        className,
+      )}
+    />
+  );
+}
+
+/**
+ * Legacy (still supported): full-height app frame with a skip link, a sidebar
+ * slot and the main content card. Composed from `AppShell.Root`, `.SkipLink`,
+ * `.Main` and `.Content`.
+ */
+function LegacyAppShell({
+  sidebar,
+  children,
+  panelHidden = false,
+  railWidth,
+  sidebarWidth,
+  resizable,
+  mobileHeaderHeight,
+  skipLinkLabel,
+  mainId = "main-content",
+  className,
+  mainClassName,
+  contentClassName,
+}: AppShellProps) {
+  return (
+    <Root
+      panelHidden={panelHidden}
+      railWidth={railWidth}
+      sidebarWidth={sidebarWidth}
+      resizable={resizable}
+      mobileHeaderHeight={mobileHeaderHeight}
+      mainId={mainId}
+      className={className}
+    >
+      <SkipLink label={skipLinkLabel} targetId={mainId} />
+      {sidebar}
+      <Main id={mainId} className={mainClassName}>
+        <Content className={contentClassName}>{children}</Content>
+      </Main>
+    </Root>
+  );
+}
+LegacyAppShell.displayName = "AppShell";
+
+/** App frame. Call it with props (legacy), or compose `AppShell.Root`, `.SkipLink`, `.Main` and `.Content`. */
+export const AppShell = Object.assign(LegacyAppShell, { Root, SkipLink, Main, Content });

package/shell/src/AppSidebar.tsx

@@ -1,11 +1,5 @@
-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";
+import type { ReactNode } from "react";
+import { SidebarChromeParts as Parts } from "./SidebarChrome";
 
 export type AppSidebarProps = {
   /** Icon rail, usually a `SidebarRail`. */
@@ -39,13 +33,15 @@ export type AppSidebarProps = {
   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.
+ *
+ * Legacy (still supported): the `rail`, `panel` and `mobile*` slot props.
+ * Compose `Sidebar.Root`, `.MobileHeader`, `.Backdrop`, `.Aside` and
+ * `.ResizeHandle` instead.
  */
 export function AppSidebar({
   rail,
@@ -60,118 +56,30 @@ export function AppSidebar({
   className,
   mobileTitle,
   mobileHeaderActions,
-  mobileMenuIcon = defaultMobileMenuIcon,
-  mobileMenuLabel = "Open navigation menu",
-  closeLabel = "Close navigation",
+  mobileMenuIcon,
+  mobileMenuLabel,
+  closeLabel,
 }: 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-surface 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))] 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}
-        {mobileHeaderActions ? (
-          <div data-app-sidebar-mobile-actions="" className="ml-auto flex shrink-0 items-center gap-2">
-            {mobileHeaderActions}
-          </div>
-        ) : (
-          <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}
-      >
+    <Parts.Root
+      isDesktop={isDesktop}
+      mobileOpen={mobileOpen}
+      onMobileOpenChange={onMobileOpenChange}
+      collapsed={collapsed}
+      panelHidden={panelHidden}
+      id={id}
+    >
+      <Parts.MobileHeader>
+        <Parts.MobileMenuButton label={mobileMenuLabel} icon={mobileMenuIcon} />
+        <Parts.MobileTitle>{mobileTitle}</Parts.MobileTitle>
+        <Parts.MobileActions>{mobileHeaderActions}</Parts.MobileActions>
+      </Parts.MobileHeader>
+      <Parts.Backdrop label={closeLabel} />
+      <Parts.Aside {...asideProps} className={className}>
         {rail}
         {panelHidden ? null : panel}
-        {showResizeHandle ? <SidebarResizeHandle /> : null}
-      </motion.aside>
-    </>
+        <Parts.ResizeHandle />
+      </Parts.Aside>
+    </Parts.Root>
   );
 }