@ngrok/mantle 0.82.0 → 0.82.1

package/dist/sidebar.d.ts

@@ -1,8 +1,9 @@
-import { n as WithAsChild } from "./as-child-D23mGo4f.js";
-import { n as IconButtonProps } from "./button-C7vAl6lS.js";
+import { n as WithAsChild, t as SelfClosingWithAsChild } from "./as-child-D23mGo4f.js";
 import { t as WithDataSlot } from "./data-slot-CChfb_cv.js";
+import { n as IconButtonProps } from "./button-C7vAl6lS.js";
 import { n as Separator } from "./separator-B5UmkVRL.js";
-import { ComponentProps, ReactNode } from "react";
+import { t as Tooltip } from "./tooltip-mrpLz4DZ.js";
+import { ComponentProps, ReactElement, ReactNode } from "react";
 //#region src/components/sidebar/sidebar.d.ts
 /**
  * The breakpoints below which `Sidebar.Nav` swaps from the inline desktop
@@ -84,7 +85,7 @@ type SidebarState = {
  * `Sidebar.Root` so misuse fails loudly. Use it to build custom triggers,
  * a keyboard shortcut, or close-on-navigate behavior.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#usesidebar
  *
  * @example
  * ```tsx
@@ -100,6 +101,11 @@ type SidebarState = {
  */
 declare function useSidebar(): SidebarState;
 type SidebarRootProps = {
+  /**
+   * The sidebar's parts — a `Sidebar.Nav` and anything that reads the state,
+   * including a `Sidebar.Trigger` rendered anywhere below (an
+   * `AppLayout.Header`, for example). `Root` renders no DOM of its own.
+   */
   children?: ReactNode;
   /**
    * The initial desktop expanded state for the uncontrolled case.
@@ -132,10 +138,18 @@ type SidebarRootProps = {
   mobileBreakpoint?: SidebarMobileBreakpoint;
   /**
    * Toggle the sidebar with `⌘B` (macOS) / `Ctrl+B` (Windows/Linux). The
-   * shortcut requires exactly the platform modifier + `b` — combinations with
-   * `Shift`/`Alt` (e.g. the browser's own `⌘⇧B`) are left alone. Set `false`
-   * to opt out, e.g. when the app embeds a rich-text editor where `⌘B` means
-   * bold.
+   * shortcut requires exactly the platform modifier + `b`: `⌘` on Apple
+   * platforms and `Ctrl` everywhere else, resolved per host — the two never
+   * substitute for each other, so macOS's native `Ctrl+B` ("move the caret
+   * back one character") is left alone. Combinations with `Shift`/`Alt` (e.g.
+   * the browser's own `⌘⇧B`) pass through too.
+   *
+   * The shortcut is also ignored while focus is in a text-editing or form
+   * control — an `<input>`, `<textarea>`, `<select>`, or any `contenteditable`
+   * host — because the chord is usually already bound there (`⌘B` is "bold")
+   * and this is a `window` listener that calls `preventDefault()`. That covers
+   * embedded editors like Monaco and CodeMirror, which attach to exactly those
+   * elements. Set `false` to opt out entirely.
    *
    * The shortcut has exactly one owner per window: the first mounted root
    * with the shortcut enabled. Additional roots (nested or siblings) queue
@@ -156,13 +170,24 @@ type SidebarRootProps = {
  * Render exactly one `Sidebar.Nav` per `Sidebar.Root`. Nested roots shadow
  * the outer sidebar for everything below them.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarroot
  *
  * @example
  * ```tsx
  * <Sidebar.Root>
  *   <Sidebar.Nav aria-label="Main">
- *     <Sidebar.Header>…</Sidebar.Header>
+ *     <Sidebar.Header>
+ *       <DropdownMenu.Root>
+ *         <DropdownMenu.Trigger asChild>
+ *           <Sidebar.SwitcherTrigger>
+ *             <GlobeIcon />
+ *             <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
+ *             <CaretDownIcon className="text-muted size-4 shrink-0" />
+ *           </Sidebar.SwitcherTrigger>
+ *         </DropdownMenu.Trigger>
+ *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+ *       </DropdownMenu.Root>
+ *     </Sidebar.Header>
  *     <Sidebar.Body>
  *       <Sidebar.Group>
  *         <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
@@ -178,11 +203,21 @@ type SidebarRootProps = {
  *         </Sidebar.List>
  *       </Sidebar.Group>
  *     </Sidebar.Body>
- *     <Sidebar.Footer>…</Sidebar.Footer>
+ *     <Sidebar.Footer>
+ *       <Sidebar.Separator />
+ *       <DropdownMenu.Root>
+ *         <DropdownMenu.Trigger asChild>
+ *           <Sidebar.SwitcherTrigger>
+ *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
+ *             <Sidebar.UserAvatar alt="Jane Doe" />
+ *           </Sidebar.SwitcherTrigger>
+ *         </DropdownMenu.Trigger>
+ *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+ *       </DropdownMenu.Root>
+ *     </Sidebar.Footer>
  *   </Sidebar.Nav>
- *   <main>
- *     <Sidebar.Trigger />
- *   </main>
+ *   <Sidebar.Trigger />
  * </Sidebar.Root>
  * ```
  */
@@ -226,19 +261,39 @@ type SidebarNavProps = ComponentProps<"div"> & WithDataSlot;
  * opens from. Override `--sidebar-width` at `:root` to move both together, or
  * set `--sidebar-row-width` on the outside surface itself.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * **Data attributes:**
+ *
+ * | Data Attribute | Value | Description |
+ * | --- | --- | --- |
+ * | `data-state` | `"expanded"` \| `"collapsed"` | On the desktop panel surface. Mirrors the root's expanded state and drives the width collapse to the icon rail; descendant parts style off it with `group-data-[state=collapsed]/sidebar-nav:`. |
+ * | `data-hydrated` | present after hydration | Presence-only, desktop panel surface. The CSS-side twin of the `isHydrated` gate: descendant collapse transitions are enabled only under `group-data-[hydrated]/sidebar-nav:`, so an SSR state correction snaps instead of animating on page load. |
+ * | `data-mobile` | present in the mobile sheet | Presence-only. Marks the `Sheet.Content` presentation used below the root's `mobileBreakpoint`. |
+ * | `data-state` | `"open"` \| `"closed"` | In the mobile sheet only, where the panel *is* the `Sheet`'s Radix dialog content element and Radix owns the attribute — the sheet's open/close animation state, not the desktop expanded state. Consumers style against it too. |
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarnav
  *
  * @example
  * ```tsx
  * <Sidebar.Root>
  *   <Sidebar.Nav aria-label="Main">
- *     <Sidebar.Header>…</Sidebar.Header>
+ *     <Sidebar.Header>
+ *       <DropdownMenu.Root>
+ *         <DropdownMenu.Trigger asChild>
+ *           <Sidebar.SwitcherTrigger>
+ *             <GlobeIcon />
+ *             <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
+ *             <CaretDownIcon className="text-muted size-4 shrink-0" />
+ *           </Sidebar.SwitcherTrigger>
+ *         </DropdownMenu.Trigger>
+ *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+ *       </DropdownMenu.Root>
+ *     </Sidebar.Header>
  *     <Sidebar.Body>
  *       <Sidebar.Group>
  *         <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
  *         <Sidebar.List>
  *           <Sidebar.Item>
- *             <Sidebar.ItemButton asChild>
+ *             <Sidebar.ItemButton asChild current>
  *               <a href="/endpoints">
  *                 <GraphIcon />
  *                 Endpoints
@@ -248,8 +303,21 @@ type SidebarNavProps = ComponentProps<"div"> & WithDataSlot;
  *         </Sidebar.List>
  *       </Sidebar.Group>
  *     </Sidebar.Body>
- *     <Sidebar.Footer>…</Sidebar.Footer>
+ *     <Sidebar.Footer>
+ *       <Sidebar.Separator />
+ *       <DropdownMenu.Root>
+ *         <DropdownMenu.Trigger asChild>
+ *           <Sidebar.SwitcherTrigger>
+ *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
+ *             <Sidebar.UserAvatar alt="Jane Doe" />
+ *           </Sidebar.SwitcherTrigger>
+ *         </DropdownMenu.Trigger>
+ *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+ *       </DropdownMenu.Root>
+ *     </Sidebar.Footer>
  *   </Sidebar.Nav>
+ *   <Sidebar.Trigger />
  * </Sidebar.Root>
  * ```
  */
@@ -296,7 +364,16 @@ type SidebarTriggerProps = Omit<IconButtonProps, "appearance" | "asChild" | "chi
  * `AppLayout.Header`) — it must stay visible at every breakpoint where the
  * sidebar can collapse, or users have no way to reopen it.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * **Data attributes:**
+ *
+ * | Data Attribute | Value | Description |
+ * | --- | --- | --- |
+ * | `data-state` | `"expanded"` \| `"collapsed"` | Mirrors what the trigger toggles: the mobile sheet below the root's `mobileBreakpoint`, the desktop panel otherwise. Pairs with `aria-expanded`. |
+ * | `data-appearance` | `"ghost"` \| `"outlined"` | Read, not stamped: the underlying `IconButton` reflects its `appearance`, which this part defaults to `"ghost"`. |
+ * | `data-intent` | `"accent"` \| `"danger"` \| `"neutral"` | Read, not stamped: the underlying `IconButton` reflects its `intent`, which this part defaults to `"neutral"`. |
+ * | `data-size` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | Read, not stamped: the underlying `IconButton` reflects its `size` and its own `"md"` default. |
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebartrigger
  *
  * @example
  * ```tsx
@@ -351,15 +428,15 @@ type SidebarTriggerProps = Omit<IconButtonProps, "appearance" | "asChild" | "chi
  * Placement within an `AppLayout` shell:
  * ```tsx
  * <Sidebar.Root>
- *   <Sidebar.Nav aria-label="Main">…</Sidebar.Nav>
- *   <AppLayout.Inset>
+ *   <AppLayout.Workspace>
+ *     <Sidebar.Nav aria-label="Main">…</Sidebar.Nav>
  *     <AppLayout.Content>
  *       <AppLayout.Header>
  *         <Sidebar.Trigger />
  *       </AppLayout.Header>
- *       …
+ *       <AppLayout.Body>…</AppLayout.Body>
  *     </AppLayout.Content>
- *   </AppLayout.Inset>
+ *   </AppLayout.Workspace>
  * </Sidebar.Root>
  * ```
  */
@@ -382,7 +459,7 @@ type SidebarHeaderProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  * | --- | --- | --- |
  * | `--sidebar-header-height` | `4.5rem` | The header row height (72px). Set it on a common ancestor of the sidebar and `AppLayout.Header`, not on `Sidebar.Nav`, so both rows read one value. |
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarheader
  *
  * @example
  * ```tsx
@@ -442,7 +519,7 @@ type SidebarBodyProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  * `scroll-fade-y` mask; inside the collapsed icon rail the scrollbar and its
  * reserved gutter are hidden and the fade is the only overflow signal.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarbody
  *
  * @example
  * ```tsx
@@ -501,7 +578,7 @@ type SidebarFooterProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  * switcher row (`Sidebar.SwitcherTrigger` with `Sidebar.AccountAvatar` and
  * `Sidebar.UserAvatar`).
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarfooter
  *
  * @example
  * ```tsx
@@ -560,7 +637,7 @@ type SidebarGroupProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  * group wires it to the list via `aria-labelledby` so assistive technology
  * announces the list with the group's name.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebargroup
  *
  * @example
  * ```tsx
@@ -620,7 +697,7 @@ type SidebarGroupLabelProps = ComponentProps<"div"> & WithAsChild & WithDataSlot
  * the sibling list via `aria-labelledby`. Pass `asChild` to render a heading
  * at a level you control.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebargrouplabel
  *
  * @example
  * ```tsx
@@ -678,7 +755,7 @@ type SidebarListProps = ComponentProps<"ul"> & WithAsChild & WithDataSlot;
  * has a `Sidebar.GroupLabel`, the list is announced with the group's name via
  * `aria-labelledby`.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarlist
  *
  * @example
  * ```tsx
@@ -736,7 +813,7 @@ type SidebarItemProps = ComponentProps<"li"> & WithAsChild & WithDataSlot;
  * element is the `Sidebar.ItemButton` child, so props, `ref`, and `className`
  * all target the list item itself.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaritem
  *
  * @example
  * ```tsx
@@ -793,6 +870,10 @@ type SidebarItemButtonProps = ComponentProps<"button"> & WithAsChild & WithDataS
    * Marks this row as the current page: sets `aria-current="page"` and the
    * `data-current` styling state. Consumers control it from their router,
    * e.g. `current={pathname === "/endpoints"}`.
+   *
+   * A composed child that sets `aria-current="page"` itself — react-router's
+   * `NavLink` does — already gets the current-row treatment, so it needs no
+   * `current`. This prop is for the rows whose parent knows.
    */
   current?: boolean;
 };
@@ -802,6 +883,20 @@ type SidebarItemButtonProps = ComponentProps<"button"> & WithAsChild & WithDataS
  * compose with a router link. `current` sets `aria-current="page"` and the
  * `data-current` visual state.
  *
+ * The current-row treatment follows either attribute, so a composed child that
+ * marks itself as the current page gets it without `current` — a react-router
+ * `NavLink` needs nothing but its `to`, since it already resolved the match the
+ * parent would otherwise re-derive:
+ *
+ * ```tsx
+ * <Sidebar.ItemButton asChild>
+ *   <NavLink to="/endpoints">
+ *     <GraphIcon />
+ *     Endpoints
+ *   </NavLink>
+ * </Sidebar.ItemButton>
+ * ```
+ *
  * The row sizes its **leading** icon to 20px and leaves trailing visuals — a
  * caret, a count, a status dot — to size themselves, so a row composed with
  * `DropdownMenu.Trigger asChild` can end in `<CaretDownIcon className="text-muted
@@ -811,7 +906,15 @@ type SidebarItemButtonProps = ComponentProps<"button"> & WithAsChild & WithDataS
  * it keeps the expanded row's width instead of shrinking to this row's 28px
  * rail chip (see `Sidebar.SwitcherTrigger` for the whole contract).
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * **Data attributes:**
+ *
+ * | Data Attribute | Value | Description |
+ * | --- | --- | --- |
+ * | `data-current` | present when `current` | Presence-only — never `"false"`, since the `data-current:` variant matches the attribute's existence. Styles the current row. |
+ * | `aria-current` | `"page"` when `current` | Set alongside `data-current`. The current-row styling follows *either*, so a composed child that marks itself (react-router's `NavLink`) gets the treatment without the prop. |
+ * | `data-state` | `"open"` | **Read, not stamped** — supplied by a composing `DropdownMenu.Trigger` / `Dialog.Trigger`. The row styles against it so it stays highlighted while its menu is open. |
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaritembutton
  *
  * @example
  * ```tsx
@@ -891,7 +994,13 @@ type SidebarSwitcherTriggerProps = ComponentProps<"button"> & WithAsChild & With
  * `--sidebar-width-mobile` whenever you widen `--sidebar-width`, or the floor
  * overhangs the sheet.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * **Data attributes:**
+ *
+ * | Data Attribute | Value | Description |
+ * | --- | --- | --- |
+ * | `data-state` | `"open"` | **Read, not stamped** — supplied by the composing `DropdownMenu.Trigger` / `Dialog.Trigger`. The row styles against it so it stays highlighted while its menu is open. |
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarswitchertrigger
  *
  * @example
  * ```tsx
@@ -943,7 +1052,108 @@ type SidebarSwitcherTriggerProps = ComponentProps<"button"> & WithAsChild & With
  * ```
  */
 declare const SwitcherTrigger: ({ asChild, children, className, "data-slot": dataSlot, type, ...props }: SidebarSwitcherTriggerProps) => import("react").JSX.Element;
-type SidebarSeparatorProps = ComponentProps<typeof Separator>;
+/**
+ * The props for `Sidebar.Tooltip`. `Tooltip.Content`'s props — so `className`,
+ * `style`, `ref`, `asChild`, and any `data-*` reach the tooltip surface — except
+ * the parts this row owns: `children` is the row being labeled (not the tooltip
+ * body, which is `label`), and `side` becomes optional with a sidebar default.
+ */
+type SidebarTooltipProps = Omit<ComponentProps<typeof Tooltip.Content>, "children" | "side"> & WithDataSlot & {
+  /**
+   * The row this labels — a `Sidebar.ItemButton` or `Sidebar.SwitcherTrigger`,
+   * optionally already wrapped in a `DropdownMenu.Trigger asChild`.
+   *
+   * A single element, required: `Tooltip.Trigger asChild` clones its child, so
+   * text renders nothing a pointer can hover and no children renders no row at
+   * all — both silently.
+   */
+  children: ReactElement;
+  /**
+   * What the tooltip says. Normally the row's own label text: the rail clips the
+   * visible one, so this is what a sighted pointer user reads.
+   */
+  label: ReactNode;
+  /**
+   * Which side of the row the tooltip opens on. The rail sits at the inline
+   * start of the viewport, so the default points the tooltip away from it.
+   *
+   * @default "right"
+   */
+  side?: ComponentProps<typeof Tooltip.Content>["side"];
+};
+/**
+ * Labels a sidebar row while — and only while — the desktop panel is collapsed
+ * to the icon rail. Wrap it around a `Sidebar.ItemButton` or
+ * `Sidebar.SwitcherTrigger`.
+ *
+ * The collapsed rail keeps every row's label in the accessibility tree (clipped,
+ * not removed), which serves screen-reader users but leaves a sighted pointer
+ * user with an unlabeled icon column. This restores the label for them without
+ * duplicating it for anyone else: expanded rows already read their own text, and
+ * the mobile sheet shows full labels, so the tooltip content only mounts in the
+ * collapsed desktop rail.
+ *
+ * **Requires a `TooltipProvider` ancestor**, like any `Tooltip.Root` — mount one
+ * at your app root. This part deliberately does not provide its own, so tooltip
+ * delay and hover settings stay app-wide rather than being overridden per row.
+ *
+ * It composes with a menu trigger: nest `DropdownMenu.Root >
+ * Sidebar.Tooltip > DropdownMenu.Trigger asChild > Sidebar.ItemButton` for a
+ * row that opens a menu *and* labels itself in the rail. `DropdownMenu.Root` must
+ * stay **outside** the tooltip — it is renderless, and `Tooltip.Trigger asChild`
+ * needs a real element to clone.
+ *
+ * `children` is the row; `label` is what the tooltip says. Every other prop is
+ * `Tooltip.Content`'s and lands on the tooltip surface — `className`, `style`,
+ * `ref`, `data-*`, positioning props such as `align` and `sideOffset`, and
+ * `asChild`, which Radix's `Tooltip.Content` implements itself. `side` defaults
+ * to `"right"` so the tooltip opens away from the rail.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebartooltip
+ *
+ * @example
+ * ```tsx
+ * <TooltipProvider>
+ *   <Sidebar.Root>
+ *     <Sidebar.Nav aria-label="Main">
+ *       <Sidebar.Body>
+ *         <Sidebar.Group>
+ *           <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
+ *           <Sidebar.List>
+ *             <Sidebar.Item>
+ *               <Sidebar.Tooltip label="Endpoints">
+ *                 <Sidebar.ItemButton asChild current>
+ *                   <a href="/endpoints">
+ *                     <GraphIcon />
+ *                     Endpoints
+ *                   </a>
+ *                 </Sidebar.ItemButton>
+ *               </Sidebar.Tooltip>
+ *             </Sidebar.Item>
+ *           </Sidebar.List>
+ *         </Sidebar.Group>
+ *       </Sidebar.Body>
+ *       <Sidebar.Footer>
+ *         <DropdownMenu.Root>
+ *           <Sidebar.Tooltip label="Help">
+ *             <DropdownMenu.Trigger asChild>
+ *               <Sidebar.ItemButton>
+ *                 <QuestionIcon />
+ *                 Help
+ *               </Sidebar.ItemButton>
+ *             </DropdownMenu.Trigger>
+ *           </Sidebar.Tooltip>
+ *           <DropdownMenu.Content>…</DropdownMenu.Content>
+ *         </DropdownMenu.Root>
+ *       </Sidebar.Footer>
+ *     </Sidebar.Nav>
+ *     <Sidebar.Trigger />
+ *   </Sidebar.Root>
+ * </TooltipProvider>
+ * ```
+ */
+declare const SidebarTooltip: ({ children, "data-slot": dataSlot, label, side, ...props }: SidebarTooltipProps) => import("react").JSX.Element;
+type SidebarSeparatorProps = ComponentProps<typeof Separator> & WithDataSlot;
 /**
  * An inset hairline between sidebar regions. Composes the mantle `Separator`,
  * staying aligned with the `px-3` content padding of `Sidebar.Body` and
@@ -952,7 +1162,7 @@ type SidebarSeparatorProps = ComponentProps<typeof Separator>;
  * to the same 36px chip width as `Sidebar.SwitcherTrigger`, balancing the
  * adjacent app-content gutter that sits outside the rail.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarseparator
  *
  * @example
  * ```tsx
@@ -1003,8 +1213,17 @@ type SidebarSeparatorProps = ComponentProps<typeof Separator>;
  * </Sidebar.Root>
  * ```
  */
-declare const SidebarSeparator: ({ className, ...props }: SidebarSeparatorProps) => import("react").JSX.Element;
-type SidebarAccountAvatarProps = Omit<ComponentProps<"div">, "children"> & {
+declare const SidebarSeparator: ({ className, "data-slot": dataSlot, ...props }: SidebarSeparatorProps) => import("react").JSX.Element;
+/**
+ * The props for `Sidebar.AccountAvatar`.
+ *
+ * `children` is valid only with `asChild`, where it is the element the avatar
+ * renders as instead of its own `<div>` — pass an empty one, e.g. `<span />`
+ * when the avatar sits inside a `<button>` (which may not contain a `<div>`).
+ * The initials are derived from `accountName`, which a consumer cannot compute,
+ * so they render *inside* that element in place of its own children.
+ */
+type SidebarAccountAvatarProps = Omit<ComponentProps<"div">, "children"> & SelfClosingWithAsChild & WithDataSlot & {
   /**
    * The account's stable identifier. Used to deterministically select a
    * background swatch from the design system's palette so the same account
@@ -1026,7 +1245,12 @@ type SidebarAccountAvatarProps = Omit<ComponentProps<"div">, "children"> & {
  * Accounts are rendered as squares to differentiate them visually from users,
  * which use a circular `Sidebar.UserAvatar`.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * Pass `asChild` with a single empty element to swap the `<div>` it renders —
+ * a `<span />` inside a `<button>`, or a link. The initials are derived from
+ * `accountName`, so they render inside the swapped element; anything that
+ * element carried of its own is replaced.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaraccountavatar
  *
  * @example
  * ```tsx
@@ -1077,8 +1301,17 @@ type SidebarAccountAvatarProps = Omit<ComponentProps<"div">, "children"> & {
  * </Sidebar.Root>
  * ```
  */
-declare const AccountAvatar: ({ accountId, accountName, className, ...props }: SidebarAccountAvatarProps) => import("react").JSX.Element;
-type SidebarUserAvatarProps = Omit<ComponentProps<"div">, "children"> & {
+declare const AccountAvatar: ({ accountId, accountName, asChild, children, className, "data-slot": dataSlot, ...props }: SidebarAccountAvatarProps) => import("react").JSX.Element;
+/**
+ * The props for `Sidebar.UserAvatar`.
+ *
+ * `children` is valid only with `asChild`, where it is the element the avatar
+ * renders as instead of its own `<div>` — pass an empty one, e.g. `<span />`
+ * when the avatar sits inside a `<button>` (which may not contain a `<div>`).
+ * The avatar's visual (the `src` image, or the silhouette fallback) renders
+ * *inside* that element in place of its own children.
+ */
+type SidebarUserAvatarProps = Omit<ComponentProps<"div">, "children"> & SelfClosingWithAsChild & WithDataSlot & {
   /**
    * Optional URL of the user's profile picture. When provided, the image is
    * rendered to fill the avatar with `object-cover`. When omitted (or while
@@ -1101,7 +1334,12 @@ type SidebarUserAvatarProps = Omit<ComponentProps<"div">, "children"> & {
  * Users are rendered as circles to differentiate them visually from accounts,
  * which use a square `Sidebar.AccountAvatar`.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * Pass `asChild` with a single empty element to swap the `<div>` it renders —
+ * a `<span />` inside a `<button>`, or a link. The image (or the silhouette
+ * fallback) renders inside the swapped element; anything that element carried of
+ * its own is replaced.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaruseravatar
  *
  * @example
  * ```tsx
@@ -1152,7 +1390,7 @@ type SidebarUserAvatarProps = Omit<ComponentProps<"div">, "children"> & {
  * </Sidebar.Root>
  * ```
  */
-declare const UserAvatar: ({ alt, className, src, ...props }: SidebarUserAvatarProps) => import("react").JSX.Element;
+declare const UserAvatar: ({ alt, asChild, children, className, "data-slot": dataSlot, src, ...props }: SidebarUserAvatarProps) => import("react").JSX.Element;
 /**
  * A composable, collapsible app-navigation sidebar. `Sidebar.Root` owns the
  * state (no DOM); `Sidebar.Nav` renders the panel — inline on desktop,
@@ -1180,8 +1418,10 @@ declare const UserAvatar: ({ alt, className, src, ...props }: SidebarUserAvatarP
  * │   │       ├── Sidebar.GroupLabel
  * │   │       └── Sidebar.List
  * │   │           └── Sidebar.Item
- * │   │               └── Sidebar.ItemButton
+ * │   │               └── Sidebar.Tooltip
+ * │   │                   └── Sidebar.ItemButton
  * │   └── Sidebar.Footer
+ * │       ├── Sidebar.ItemButton
  * │       ├── Sidebar.Separator
  * │       └── Sidebar.SwitcherTrigger
  * │           ├── Sidebar.AccountAvatar
@@ -1244,7 +1484,7 @@ declare const Sidebar: {
    * mobile-sheet state to every part below it so the trigger can live in the
    * app shell without coupling it to the sidebar.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarroot
    *
    * @example
    * ```tsx
@@ -1302,7 +1542,16 @@ declare const Sidebar: {
    * `--sidebar-width` / `--sidebar-width-mobile` via its `className` or
    * `style`.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * **Data attributes:**
+   *
+   * | Data Attribute | Value | Description |
+   * | --- | --- | --- |
+   * | `data-state` | `"expanded"` \| `"collapsed"` | On the desktop panel surface. Mirrors the root's expanded state and drives the width collapse to the icon rail; descendant parts style off it with `group-data-[state=collapsed]/sidebar-nav:`. |
+   * | `data-hydrated` | present after hydration | Presence-only, desktop panel surface. The CSS-side twin of the `isHydrated` gate: descendant collapse transitions are enabled only under `group-data-[hydrated]/sidebar-nav:`, so an SSR state correction snaps instead of animating on page load. |
+   * | `data-mobile` | present in the mobile sheet | Presence-only. Marks the `Sheet.Content` presentation used below the root's `mobileBreakpoint`. |
+   * | `data-state` | `"open"` \| `"closed"` | In the mobile sheet only, where the panel *is* the `Sheet`'s Radix dialog content element and Radix owns the attribute — the sheet's open/close animation state, not the desktop expanded state. Consumers style against it too. |
+   *
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarnav
    *
    * @example
    * ```tsx
@@ -1358,7 +1607,16 @@ declare const Sidebar: {
    * The `IconButton` that toggles the sidebar. Place it in the app shell's
    * header; it stays functional at every breakpoint.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * **Data attributes:**
+   *
+   * | Data Attribute | Value | Description |
+   * | --- | --- | --- |
+   * | `data-state` | `"expanded"` \| `"collapsed"` | Mirrors what the trigger toggles: the mobile sheet below the root's `mobileBreakpoint`, the desktop panel otherwise. Pairs with `aria-expanded`. |
+   * | `data-appearance` | `"ghost"` \| `"outlined"` | Read, not stamped: the underlying `IconButton` reflects its `appearance`, which this part defaults to `"ghost"`. |
+   * | `data-intent` | `"accent"` \| `"danger"` \| `"neutral"` | Read, not stamped: the underlying `IconButton` reflects its `intent`, which this part defaults to `"neutral"`. |
+   * | `data-size` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | Read, not stamped: the underlying `IconButton` reflects its `size` and its own `"md"` default. |
+   *
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebartrigger
    *
    * @example
    * ```tsx
@@ -1415,7 +1673,7 @@ declare const Sidebar: {
    * switcher (`Sidebar.SwitcherTrigger` + `DropdownMenu`/`Dialog`). Its
    * height vertically aligns the switcher with an `AppLayout.Header`.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarheader
    *
    * @example
    * ```tsx
@@ -1470,7 +1728,7 @@ declare const Sidebar: {
   /**
    * The scrollable middle region holding the navigation groups.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarbody
    *
    * @example
    * ```tsx
@@ -1526,7 +1784,7 @@ declare const Sidebar: {
    * The pinned bottom container, typically holding cross-product items and
    * the account/user switcher row.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarfooter
    *
    * @example
    * ```tsx
@@ -1582,7 +1840,7 @@ declare const Sidebar: {
    * A grouping container pairing a `GroupLabel` with a `List`; wires the
    * label to the list via `aria-labelledby`.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebargroup
    *
    * @example
    * ```tsx
@@ -1638,7 +1896,7 @@ declare const Sidebar: {
    * The muted label of a group. Renders a `<div>`; pass `asChild` to render
    * a heading at a level you control.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebargrouplabel
    *
    * @example
    * ```tsx
@@ -1693,7 +1951,7 @@ declare const Sidebar: {
   /**
    * The `<ul>` of navigation rows in a group.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarlist
    *
    * @example
    * ```tsx
@@ -1748,7 +2006,7 @@ declare const Sidebar: {
   /**
    * A single `<li>` row wrapper.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaritem
    *
    * @example
    * ```tsx
@@ -1804,7 +2062,15 @@ declare const Sidebar: {
    * The interactive navigation row (icon + truncating label). `asChild` for
    * router links; `current` for the active page.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * **Data attributes:**
+   *
+   * | Data Attribute | Value | Description |
+   * | --- | --- | --- |
+   * | `data-current` | present when `current` | Presence-only — never `"false"`, since the `data-current:` variant matches the attribute's existence. Styles the current row. |
+   * | `aria-current` | `"page"` when `current` | Set alongside `data-current`. The current-row styling follows *either*, so a composed child that marks itself (react-router's `NavLink`) gets the treatment without the prop. |
+   * | `data-state` | `"open"` | **Read, not stamped** — supplied by a composing `DropdownMenu.Trigger` / `Dialog.Trigger`. The row styles against it so it stays highlighted while its menu is open. |
+   *
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaritembutton
    *
    * @example
    * ```tsx
@@ -1860,7 +2126,13 @@ declare const Sidebar: {
    * The styled switcher row for the header/footer. Not state-wired — compose
    * with `DropdownMenu.Trigger asChild` or `Dialog.Trigger asChild`.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * **Data attributes:**
+   *
+   * | Data Attribute | Value | Description |
+   * | --- | --- | --- |
+   * | `data-state` | `"open"` | **Read, not stamped** — supplied by the composing `DropdownMenu.Trigger` / `Dialog.Trigger`. The row styles against it so it stays highlighted while its menu is open. |
+   *
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarswitchertrigger
    *
    * @example
    * ```tsx
@@ -1912,11 +2184,75 @@ declare const Sidebar: {
    * ```
    */
   readonly SwitcherTrigger: typeof SwitcherTrigger;
+  /**
+   * Labels a row while the panel is collapsed to the icon rail — wrap it
+   * around a `Sidebar.ItemButton` or `Sidebar.SwitcherTrigger`. Requires a
+   * `TooltipProvider` ancestor. Takes `Tooltip.Content`'s props (including
+   * `asChild`) on the tooltip surface; `side` defaults to `"right"`.
+   *
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebartooltip
+   *
+   * @example
+   * ```tsx
+   * <TooltipProvider>
+   *   <Sidebar.Root>
+   *     <Sidebar.Nav aria-label="Main">
+   *       <Sidebar.Header>
+   *         <DropdownMenu.Root>
+   *           <DropdownMenu.Trigger asChild>
+   *             <Sidebar.SwitcherTrigger>
+   *               <GlobeIcon />
+   *               <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
+   *               <CaretDownIcon className="text-muted size-4 shrink-0" />
+   *             </Sidebar.SwitcherTrigger>
+   *           </DropdownMenu.Trigger>
+   *           <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+   *         </DropdownMenu.Root>
+   *       </Sidebar.Header>
+   *       <Sidebar.Body>
+   *         <Sidebar.Group>
+   *           <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
+   *           <Sidebar.List>
+   *             <Sidebar.Item>
+   *               <Sidebar.Tooltip label="Endpoints">
+   *                 <Sidebar.ItemButton asChild current>
+   *                   <a href="/endpoints">
+   *                     <GraphIcon />
+   *                     Endpoints
+   *                   </a>
+   *                 </Sidebar.ItemButton>
+   *               </Sidebar.Tooltip>
+   *             </Sidebar.Item>
+   *           </Sidebar.List>
+   *         </Sidebar.Group>
+   *       </Sidebar.Body>
+   *       <Sidebar.Footer>
+   *         <Sidebar.Separator />
+   *         <DropdownMenu.Root>
+   *           <Sidebar.Tooltip label="Acme Corp">
+   *             <DropdownMenu.Trigger asChild>
+   *               <Sidebar.SwitcherTrigger>
+   *                 <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *                 <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
+   *                 <Sidebar.UserAvatar alt="Jane Doe" />
+   *               </Sidebar.SwitcherTrigger>
+   *             </DropdownMenu.Trigger>
+   *           </Sidebar.Tooltip>
+   *           <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+   *         </DropdownMenu.Root>
+   *       </Sidebar.Footer>
+   *     </Sidebar.Nav>
+   *     <Sidebar.Trigger />
+   *   </Sidebar.Root>
+   * </TooltipProvider>
+   * ```
+   */
+  readonly Tooltip: typeof SidebarTooltip;
   /**
    * An inset hairline between sidebar regions, aligned with the content
    * padding.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarseparator
    *
    * @example
    * ```tsx
@@ -1970,9 +2306,10 @@ declare const Sidebar: {
   readonly Separator: typeof SidebarSeparator;
   /**
    * A rounded-square account avatar with deterministic, WCAG-compliant
-   * swatch colors derived from the account id.
+   * swatch colors derived from the account id. `asChild` swaps its `<div>` for
+   * a single empty element and renders the initials inside it.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaraccountavatar
    *
    * @example
    * ```tsx
@@ -2025,9 +2362,10 @@ declare const Sidebar: {
    */
   readonly AccountAvatar: typeof AccountAvatar;
   /**
-   * A circular user avatar with a silhouette fallback.
+   * A circular user avatar with a silhouette fallback. `asChild` swaps its
+   * `<div>` for a single empty element and renders the image inside it.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaruseravatar
    *
    * @example
    * ```tsx
@@ -2081,4 +2419,140 @@ declare const Sidebar: {
   readonly UserAvatar: typeof UserAvatar;
 };
 //#endregion
-export { Sidebar, type SidebarMobileBreakpoint, type SidebarState, useSidebar };
+//#region src/components/sidebar/sidebar-state-cookie.d.ts
+/**
+ * The cookie name {@link extractSidebarStateCookie} reads and
+ * {@link serializeSidebarStateCookie} writes.
+ *
+ * Exported so an app can clear the cookie on sign-out, or read it with its own
+ * cookie library, without hard-coding the name.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebar_state_cookie_name
+ *
+ * @example
+ * ```ts
+ * // clear the persisted rail state on sign-out
+ * headers.append("Set-Cookie", `${SIDEBAR_STATE_COOKIE_NAME}=; Max-Age=0; Path=/`);
+ * ```
+ */
+declare const SIDEBAR_STATE_COOKIE_NAME = "mantle-sidebar-state";
+/**
+ * Parse the sidebar's expanded state out of a raw `Cookie` header.
+ *
+ * This is the server half of cookie-backed persistence: unlike storage-backed
+ * persistence, a cookie is available *before* the server renders, so the
+ * server-rendered HTML already carries the right `data-state` and there is no
+ * first-frame correction to hide. Pass the result straight to `defaultOpen` —
+ * controlled `open` is not required.
+ *
+ * Returns `undefined` — not `false` — when the cookie is absent or holds a
+ * value this helper does not recognize, so a first-time visitor is
+ * distinguishable from one who deliberately collapsed the sidebar. Collapse the
+ * state into your own default at the call site with `?? true`.
+ *
+ * Never throws: a header is client-controlled, and a value with a malformed
+ * percent-escape (`mantle-sidebar-state=%E0%A4%A`) is unparseable rather than
+ * fatal, so one hostile or corrupt cookie cannot fail the server render on
+ * every page load.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#persisting-the-collapsed-state
+ *
+ * @example
+ * ```ts
+ * // app/root.tsx loader
+ * export const loader = ({ request }: Route.LoaderArgs) => ({
+ *   sidebarOpen: extractSidebarStateCookie(request.headers.get("Cookie")) ?? true,
+ * });
+ * ```
+ *
+ * @param cookieHeader - The raw `Cookie` header string from the request, or null/undefined.
+ * @returns `true` when expanded, `false` when collapsed, `undefined` when unset, undecodable, or unparseable.
+ */
+declare function extractSidebarStateCookie(cookieHeader: string | null | undefined): boolean | undefined;
+/**
+ * Attributes for {@link serializeSidebarStateCookie}. Deliberately omits
+ * `HttpOnly`: the browser writes this cookie from `onOpenChange`, so a
+ * server-only cookie could never be updated when the user toggles the rail.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#serializesidebarstatecookie
+ *
+ * @example
+ * ```ts
+ * serializeSidebarStateCookie(open, { maxAge: 60 * 60 * 24 * 365, sameSite: "Lax" });
+ * ```
+ */
+type SerializeSidebarStateCookieOptions = {
+  /**
+   * How long the preference survives, in seconds.
+   *
+   * @default 31_536_000 // one year
+   */
+  maxAge?: number;
+  /**
+   * The path the cookie applies to. Keep the default unless the sidebar only
+   * exists under one route subtree.
+   *
+   * @default "/"
+   */
+  path?: string;
+  /**
+   * The domain the cookie applies to. Omitted by default, which scopes it to
+   * the exact current host. Set it (e.g. `".example.com"`) to share the
+   * preference across subdomains.
+   */
+  domain?: string;
+  /**
+   * `SameSite` policy. `"Lax"` is right for a UI preference — it survives
+   * top-level navigations back to your app without riding along on
+   * cross-site subrequests.
+   *
+   * @default "Lax"
+   */
+  sameSite?: "Lax" | "Strict" | "None";
+  /**
+   * Whether to add the `Secure` attribute. Omitted by default so the same call
+   * works on `http://localhost` — a `Secure` cookie is silently rejected over
+   * http, which would make the preference appear not to persist in local
+   * development. Set it to `true` in production if your CSP or policy requires
+   * it; this cookie holds no secret, only whether a rail is open.
+   *
+   * @default false
+   */
+  secure?: boolean;
+};
+/**
+ * Serialize the sidebar's expanded state as a cookie string.
+ *
+ * Framework-agnostic by design: the returned string is valid for both
+ * `document.cookie` on the client and a `Set-Cookie` response header on the
+ * server, so the same helper covers whichever side of your app owns the write.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#persisting-the-collapsed-state
+ *
+ * @example
+ * ```tsx
+ * // client: persist as the user toggles, and render from the loader value
+ * const { sidebarOpen } = useLoaderData<typeof loader>();
+ * <Sidebar.Root
+ *   defaultOpen={sidebarOpen}
+ *   onOpenChange={(open) => {
+ *     document.cookie = serializeSidebarStateCookie(open);
+ *   }}
+ * >
+ * ```
+ *
+ * @example
+ * ```ts
+ * // server: set it from an action instead
+ * return new Response(null, {
+ *   headers: { "Set-Cookie": serializeSidebarStateCookie(false, { secure: true }) },
+ * });
+ * ```
+ *
+ * @param open - Whether the sidebar is expanded.
+ * @param options - Cookie attributes; see {@link SerializeSidebarStateCookieOptions}.
+ * @returns A cookie string such as `mantle-sidebar-state=collapsed; Max-Age=31536000; Path=/; SameSite=Lax`.
+ */
+declare function serializeSidebarStateCookie(open: boolean, options?: SerializeSidebarStateCookieOptions): string;
+//#endregion
+export { SIDEBAR_STATE_COOKIE_NAME, type SerializeSidebarStateCookieOptions, Sidebar, type SidebarMobileBreakpoint, type SidebarState, extractSidebarStateCookie, serializeSidebarStateCookie, useSidebar };