@vvedantb/ui 0.5.4 → 0.6.1

package/README.md

@@ -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-options-061)).
 
 ## Buttons, menus and fields (0.4.4)
 
@@ -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. 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`: `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,184 @@ function PanelWidth() {
 </Tabs>
 ```
 
+## Composable parts (0.6.0, options 0.6.1)
+
+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). 0.6.1: `dismissibleWhilePending` (Escape, outside click and the close button still close while `pending`; Cancel stays disabled), `focusCancel` (with `alert={false}`, Cancel gets `data-alert-cancel` so a `role="alertdialog"` Content focuses it on open). |
+| `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. 0.6.1: `row` keeps a right-aligned row at every width, compact sheet included (`justify-end flex-row!`); no-op for `sm`. |
+| `Cancel` | Alert: the outline `AlertDialogCancel` (closes through Radix). Otherwise a ghost `Button` that runs `onClick`, then (unless it called `preventDefault()`) the Root `onOpenChange(false)`. In both modes `preventDefault()` in `onClick` skips the close, and `variant` overrides the default. 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. `pending` on Action alone shows the pending state without blocking close. 0.6.1: `spinnerClassName` merges after `animate-spin` (for example `"mr-2"`). |
+| `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, focusCancel, 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 dismissible alert (0.6.1 options) that focuses Cancel, keeps a button row on mobile, and can still be closed while busy:
+
+```tsx
+<ConfirmDialog.Root open={open} onOpenChange={setOpen} alert={false} focusCancel pending={busy} dismissibleWhilePending>
+  <ConfirmDialog.Content role="alertdialog">
+    <ConfirmDialog.Header>
+      <ConfirmDialog.Title>Delete item?</ConfirmDialog.Title>
+      <ConfirmDialog.Description>This cannot be undone.</ConfirmDialog.Description>
+    </ConfirmDialog.Header>
+    <ConfirmDialog.Footer row>
+      <ConfirmDialog.Cancel variant="outline" />
+      <ConfirmDialog.Action variant="destructive" pendingLabel="Delete" spinnerSize={16} spinnerClassName="mr-2" onClick={remove}>
+        Delete
+      </ConfirmDialog.Action>
+    </ConfirmDialog.Footer>
+  </ConfirmDialog.Content>
+</ConfirmDialog.Root>
+```
+
+Parts read the nearest Root through context, so `Footer`, `Cancel` and `Action` work inside a child component or a `<form>` rendered in `Content`. To show another step, render a different footer (and Content `role`) conditionally inside the same Root and Content.
+
+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/app/README.md

@@ -0,0 +1,100 @@
+# App helpers (`@vvedantb/ui`)
+
+Shared web React helpers that were duplicated across apps. Source-exported as the `./app` subpath of `@vvedantb/ui`.
+
+## Install
+
+```sh
+npm install @vvedantb/ui
+```
+
+## Peers
+
+Required: `react` and `react-dom` (>=19). Optional peers of `@vvedantb/ui`, needed only for the app helpers: `@clerk/clerk-react` (`useStableAuth`), `@tanstack/react-hotkeys` and `zod`.
+
+`sonner` is not a dependency. The update watcher takes the toast API as an option. The app source uses a local class join, which the root does not export (the root `cn` is the clsx and tailwind-merge one). Tailwind must scan `node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}` so the class names are generated, and the app needs the `@vvedantb/ui/tokens` names (`bg-surface-card`, `divide-separator`, `text-muted-foreground` and so on).
+
+```css
+@source "../node_modules/@vvedantb/ui/app/src/**/*.{ts,tsx}";
+```
+
+## Confirm skip (Alt-click)
+
+```tsx
+import { ConfirmSkipHint, skipConfirmTitle, useRequestConfirm } from "@vvedantb/ui";
+
+const { request } = useRequestConfirm();
+
+<DropdownMenuItem
+  title={skipConfirmTitle("Delete")}
+  onSelect={(event) => request(() => setOpen(true), () => remove(), event)}
+>
+  Delete <ConfirmSkipHint />
+</DropdownMenuItem>
+```
+
+- `useRequestConfirm` does not subscribe to Alt. It reads `getAltHeld()` when the request happens, so the menu owner does not re-render when Alt goes down. It returns `{ request }` only.
+- `ConfirmSkipHint` stays mounted and gains a `hidden` class when Alt is not held, so an open Radix menu keeps a stable child tree.
+- The Alt store resets when the last subscriber leaves, clears on blur and tab hide, and cancels a bare Alt keydown only inside `[role='menu']` or `[data-radix-menu-content]`.
+- Also exported: `useAltHeld`, `getAltHeld`, `createAltHeldStore`, `bindToWindow`, `shouldSkipConfirm`, `requestConfirm`.
+
+## Update available watcher
+
+```ts
+import { toast } from "sonner";
+import { startUpdateAvailableWatcher } from "@vvedantb/ui";
+
+useEffect(
+  () =>
+    startUpdateAvailableWatcher({
+      origin: window.location.origin,
+      toast,
+      closeConvex: () => void convex.close(),
+      enabled: !import.meta.env.DEV,
+    }),
+  [],
+);
+```
+
+Options: `origin`, `toast`, `closeConvex?`, `pollMs?` (default 60000), `toastId?` (default `app-update-available`), `enabled?` (default true), `reload?` (default `window.location.reload`). On a changed asset fingerprint it shows a sticky "Update available" toast. Refresh calls `closeConvex` (errors ignored), then reloads. `fingerprintFromHtml` and `fetchDeployFingerprint` are exported too. The fingerprint looks for Vite `/assets/*.js` URLs in the index HTML.
+
+## Settings chrome
+
+```tsx
+import { SettingsPage, SettingsSection, SettingsToggleRow } from "@vvedantb/ui";
+
+<SettingsPage
+  title="Notifications"
+  layout={({ title, headerRight, toolbar, tabs, fillHeight, children }) => (
+    <PageContainer title={title} rightSection={headerRight} toolbar={toolbar} tabs={tabs} noScroll={fillHeight}>
+      {children}
+    </PageContainer>
+  )}
+>
+  <SettingsSection title="Email" bodyVariant="list">
+    <SettingsToggleRow title="Weekly digest" action={<Switch />} />
+  </SettingsSection>
+</SettingsPage>
+```
+
+Exports: `SettingsSection`, `SettingsField`, `SettingsStack`, `SettingsToggleRow`, `SettingsEmptyState` (icon is `ComponentType<{ size?: number; className?: string }>`), `SettingsPage`. `SettingsField` `layout`: `"stacked"` (default) puts the label above the control. `"horizontal"` renders one row with the label and description on the left and the control on the right. Without `layout`, `SettingsPage` renders a plain `div` with a heading and the optional slots.
+
+## useStableAuth
+
+```ts
+import { useStableAuth } from "@vvedantb/ui"; // 2000 ms debounce, wraps Clerk useAuth
+import { createUseStableAuth } from "@vvedantb/ui";
+
+const useAuth = createUseStableAuth(useClerkAuth, { debounceMs: 3000 });
+```
+
+After a signed-in session, a drop to signed-out reports `isLoaded: false` for the debounce window so Convex does not cascade. State is module-level. `resetStableAuthSession()` clears it and is for tests only.
+
+## Develop
+
+```sh
+pnpm --filter @vvedantb/ui typecheck
+pnpm --filter @vvedantb/ui test
+```
+
+Source is in `app/src` and tests in `app/tests`. Publish steps are in the root `README.md`.

package/package.json

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

package/shell/src/AppShell.tsx

@@ -1,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 });