@sableui/react 0.6.1 → 0.7.0

package/dist/components/show-more/show-more.meta.js

@@ -0,0 +1,79 @@
+// src/components/show-more/show-more.meta.ts
+var showMoreMeta = {
+  name: "ShowMore",
+  summary: "Collapsible content region that clips children to a collapsed height, fades the cut edge, and reveals the rest with a toggle.",
+  status: "stable",
+  keywords: [
+    "show more",
+    "disclosure",
+    "truncate",
+    "expand"
+  ],
+  usage: {
+    description: "Use ShowMore to reveal additional content after an intentionally shortened preview.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it when the preview is useful on its own and the rest is optional."
+      },
+      {
+        guidance: "do",
+        description: "Make the expanded state reversible when collapsing helps users regain context."
+      },
+      {
+        guidance: "dont",
+        description: "Do not place it on a card or tinted surface without checking the fade. The cut-edge gradient fades to the page background color, so on any other surface it reads as a visible band."
+      },
+      {
+        guidance: "dont",
+        description: "Do not hide required steps, important warnings, or primary actions behind ShowMore."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it to hide content search engines or screen readers need. Collapsed content is still in the DOM here, but if the user must read it to act, it should not be behind a toggle."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Collapsible"
+    ]
+  },
+  props: [
+    {
+      name: "collapsedHeight",
+      type: "number",
+      default: "96",
+      description: "Collapsed height of the content region in px. The inner wrapper clips to this height until expanded. The toggle and fade only appear when the measured content is taller than this; content that already fits shows in full with no control. Expanding animates to the measured height."
+    },
+    {
+      name: "collapsedLines",
+      type: "number",
+      description: "Collapsed height as a count of the content's own lines (measured from its line height). Wins over collapsedHeight, and is the one to prefer: the preview keeps the same number of lines when the type scale or density changes, where a px height shows fewer as type grows."
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "The content to collapse and reveal."
+    }
+  ],
+  tokensUsed: ["background", "foreground", "ring"],
+  a11y: [
+    "The toggle is a real <button> with aria-expanded reflecting the open state.",
+    "The fade overlay is pointer-events-none and decorative; it never traps clicks.",
+    "Collapsed content stays in the DOM, so screen readers can still reach it."
+  ],
+  examples: [
+    {
+      label: "Long paragraph",
+      code: '<ShowMore><p className="text-body-md text-foreground">A long paragraph that exceeds the collapsed height\u2026</p></ShowMore>'
+    },
+    {
+      label: "Collapsed to a line count",
+      code: '<ShowMore collapsedLines={6}><p className="text-body-md text-foreground">{post.description}</p></ShowMore>'
+    }
+  ]
+};
+export {
+  showMoreMeta
+};

package/dist/components/side-nav/index.js

@@ -0,0 +1,13 @@
+// src/components/side-nav/index.ts
+import {
+  SideNav,
+  SideNavGroup,
+  SideNavItem
+} from "./side-nav.js";
+import { sideNavMeta } from "./side-nav.meta.js";
+export {
+  SideNav,
+  SideNavGroup,
+  SideNavItem,
+  sideNavMeta
+};

package/dist/components/side-nav/side-nav.js

@@ -0,0 +1,75 @@
+"use client";
+
+// src/components/side-nav/side-nav.tsx
+import { useRender } from "@base-ui/react/use-render";
+import { createContext, useContext } from "react";
+import { cn } from "../../lib/cn.js";
+import { sideNavItemIconVariants, sideNavItemVariants } from "./side-nav.variants.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var SideNavContext = createContext({
+  size: "md",
+  activeVariant: "content"
+});
+function SideNav({
+  className,
+  size = "md",
+  activeVariant = "content",
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(SideNavContext.Provider, { value: { size, activeVariant }, children: /* @__PURE__ */ jsx("nav", { className: cn("flex flex-col gap-0.5", className), ...props }) });
+}
+SideNav.displayName = "SideNav";
+function SideNavGroup({
+  label,
+  className,
+  children,
+  ...props
+}) {
+  return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col gap-0.5", className), ...props, children: [
+    label ? /* @__PURE__ */ jsx("div", { className: "px-3 pt-3 pb-1 text-caption text-muted-foreground", children: label }) : null,
+    children
+  ] });
+}
+SideNavGroup.displayName = "SideNavGroup";
+function SideNavItem({
+  label,
+  icon,
+  active,
+  badge,
+  size,
+  activeVariant,
+  render,
+  className,
+  ...props
+}) {
+  const context = useContext(SideNavContext);
+  const resolvedSize = size ?? context.size;
+  const resolvedActiveVariant = activeVariant ?? context.activeVariant;
+  return useRender({
+    render: render ?? /* @__PURE__ */ jsx("button", { type: "button" }),
+    props: {
+      ...props,
+      "data-active": active ? "" : void 0,
+      "aria-current": active ? "page" : void 0,
+      className: cn(
+        sideNavItemVariants({
+          size: resolvedSize,
+          activeVariant: resolvedActiveVariant
+        }),
+        className
+      ),
+      children: /* @__PURE__ */ jsxs(Fragment, { children: [
+        icon ? /* @__PURE__ */ jsx("span", { className: sideNavItemIconVariants({ size: resolvedSize }), children: icon }) : null,
+        /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate", children: label }),
+        badge ? /* @__PURE__ */ jsx("span", { className: "ms-auto shrink-0", children: badge }) : null
+      ] })
+    },
+    defaultTagName: "button"
+  });
+}
+SideNavItem.displayName = "SideNavItem";
+export {
+  SideNav,
+  SideNavGroup,
+  SideNavItem
+};

package/dist/components/side-nav/side-nav.meta.js

@@ -0,0 +1,139 @@
+// src/components/side-nav/side-nav.meta.ts
+var sideNavMeta = {
+  name: "SideNav",
+  summary: "A lightweight in-content vertical navigation list - the settings / docs sub-nav, distinct from the app-chrome Sidebar. Router-agnostic items, optional SideNavGroup sections, and an explicit active-state vocabulary for content rails or sidebar chrome.",
+  keywords: [
+    "side nav",
+    "navigation",
+    "settings nav",
+    "sidebar",
+    "rail",
+    "docs nav",
+    "active item",
+    "group"
+  ],
+  usage: {
+    description: "Use SideNav for vertical navigation inside a settings page, documentation area, dashboard rail, or sidebar chrome. It is router-agnostic: compose items with render={<Link />} and choose activeVariant based on whether the nav sits in content or app chrome.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use aria-label on SideNav when a page contains more than one nav landmark."
+      },
+      {
+        guidance: "do",
+        description: "Group related items with SideNavGroup when the rail has more than one conceptual area."
+      },
+      {
+        guidance: "do",
+        description: "Use size='lg' and activeVariant='sidebar' when the nav is part of persistent app chrome."
+      },
+      {
+        guidance: "do",
+        description: "Rows are rounded-sm, which nests in the usual rounded-lg p-2 frame. In any other rounded, padded frame give each item rounded-concentric-<outer>/<inset> \u2014 a same-radius row inset into a frame reads as a second system."
+      },
+      {
+        guidance: "dont",
+        description: "Use SideNav for bottom mobile navigation; use BottomNav in AppShell's bottomNav slot."
+      },
+      {
+        guidance: "dont",
+        description: "Mix content and sidebar active variants in the same rail unless individual items intentionally override the group."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Nav",
+        required: true,
+        description: "The landmark container for the vertical navigation list."
+      },
+      {
+        name: "Group",
+        required: false,
+        description: "Optional labelled cluster of related navigation items."
+      },
+      {
+        name: "Item",
+        required: true,
+        description: "Interactive row with label, optional icon, optional badge, and active state."
+      },
+      {
+        name: "Badge",
+        required: false,
+        description: "Trailing count or state indicator aligned to the row end."
+      }
+    ]
+  },
+  related: {
+    components: ["Sidebar", "AppShell", "BottomNav", "Badge", "Icon"],
+    patterns: ["SettingsPage", "DashboardPage"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "size",
+      type: '"md" | "lg"',
+      description: 'Density shared by all items. "md" (default) = the lightweight in-content sub-nav; "lg" = chrome-weight (larger label + icon, roomier rows) for a rail that pairs with the app Sidebar.'
+    },
+    {
+      name: "activeVariant",
+      type: '"content" | "sidebar"',
+      default: '"content"',
+      description: 'Active-state token vocabulary shared by all items. "content" uses bg-accent/text-accent-foreground for local rails inside the content area; "sidebar" uses bg-sidebar-accent/text-sidebar-accent-foreground for SideNavs rendered inside app chrome.'
+    }
+  ],
+  subcomponents: [
+    {
+      name: "SideNavItem",
+      type: '{ label: ReactNode; icon?: ReactNode; active?: boolean; badge?: ReactNode; size?: "md" | "lg"; activeVariant?: "content" | "sidebar"; render?: useRender.RenderProp } + button props',
+      description: 'A single row. label is the row text; icon is an optional leading icon; active marks the current sub-section (active fill + aria-current="page"); badge is a trailing node (e.g. a count) pushed to the row end; size and activeVariant override the enclosing SideNav per item; render composes another element, e.g. render={<Link to="/x" />}.'
+    },
+    {
+      name: "SideNavGroup",
+      type: "{ label?: ReactNode } + div props",
+      description: "A labelled section within a SideNav - groups settings into areas. label renders an optional sentence-case caption heading above the group's items."
+    }
+  ],
+  a11y: [
+    "SideNav renders a <nav> landmark; pair multiple navs with aria-label to distinguish them.",
+    'The active item carries aria-current="page".',
+    "Items expose a focus-visible ring; the active state is reinforced by weight + fill, not colour alone.",
+    'Use activeVariant="content" for local in-page rails and activeVariant="sidebar" when a SideNav is placed on Sidebar chrome.'
+  ],
+  tokensUsed: [
+    "muted",
+    "muted-foreground",
+    "foreground",
+    "accent",
+    "accent-foreground",
+    "ring",
+    "sidebar-foreground",
+    "sidebar-accent",
+    "sidebar-accent-foreground",
+    "sidebar-ring"
+  ],
+  examples: [
+    {
+      label: "Settings sub-nav",
+      code: '<SideNav><SideNavItem label="Profile" active render={<Link to="/settings/profile" />} /><SideNavItem label="Account" render={<Link to="/settings/account" />} /><SideNavItem label="Notifications" render={<Link to="/settings/notifications" />} /></SideNav>'
+    },
+    {
+      label: "Grouped",
+      code: '<SideNav><SideNavGroup label="Account"><SideNavItem label="Profile" active render={<Link to="/settings/profile" />} /><SideNavItem label="Security" render={<Link to="/settings/security" />} /></SideNavGroup><SideNavGroup label="Workspace"><SideNavItem label="Members" render={<Link to="/settings/members" />} /></SideNavGroup></SideNav>'
+    },
+    {
+      label: "Chrome-weight rail (size=lg)",
+      code: '<SideNav size="lg"><SideNavItem label="Profile" active render={<Link to="/settings/profile" />} /><SideNavItem label="Wallets" render={<Link to="/settings/wallets" />} /><SideNavItem label="Security" render={<Link to="/settings/security" />} /></SideNav>'
+    },
+    {
+      label: "Inside Sidebar chrome",
+      code: '<SideNav size="lg" activeVariant="sidebar"><SideNavItem label="Overview" active render={<Link to="/" />} /><SideNavItem label="Reports" render={<Link to="/reports" />} /><SideNavItem label="Settings" render={<Link to="/settings" />} /></SideNav>'
+    },
+    {
+      label: "Grouped with icons and badges",
+      code: '<SideNav aria-label="Settings sections"><SideNavGroup label="Account"><SideNavItem icon={<Icon name="user" />} label="Profile" active render={<Link to="/settings/profile" />} /><SideNavItem icon={<Icon name="lock" />} label="Security" badge={<Badge tone="warning" size="sm">2</Badge>} render={<Link to="/settings/security" />} /></SideNavGroup><SideNavGroup label="Workspace"><SideNavItem icon={<Icon name="bell" />} label="Notifications" render={<Link to="/settings/notifications" />} /></SideNavGroup></SideNav>'
+    }
+  ]
+};
+export {
+  sideNavMeta
+};

package/dist/components/side-nav/side-nav.variants.js

@@ -0,0 +1,33 @@
+// src/components/side-nav/side-nav.variants.ts
+import { cva } from "class-variance-authority";
+var RAIL_ROW_INLINE = "gap-3 px-3";
+var sideNavItemVariants = cva(
+  "flex w-full items-center text-start motion-interactive focus-visible:outline-none focus-visible:ring-2 data-[active]:font-semibold",
+  {
+    variants: {
+      size: {
+        md: "gap-2.5 rounded-sm px-3 py-1.5 text-body-sm",
+        lg: "gap-3 rounded-sm px-3 py-2 text-body-md",
+        // The app rail (Sidebar): chrome-weight rows on the label tier.
+        rail: `${RAIL_ROW_INLINE} rounded-sm py-2.5 text-label-lg`
+      },
+      activeVariant: {
+        content: "text-foreground hover:bg-muted focus-visible:ring-ring data-[active]:bg-accent data-[active]:text-accent-foreground",
+        sidebar: "text-sidebar-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-sidebar-ring data-[active]:bg-sidebar-accent data-[active]:text-sidebar-accent-foreground"
+      }
+    },
+    defaultVariants: { size: "md", activeVariant: "content" }
+  }
+);
+var sideNavItemIconVariants = cva(
+  "grid shrink-0 place-items-center",
+  {
+    variants: { size: { md: "size-5 text-xl", lg: "size-6 text-xl", rail: "size-6 text-2xl" } },
+    defaultVariants: { size: "md" }
+  }
+);
+export {
+  RAIL_ROW_INLINE,
+  sideNavItemIconVariants,
+  sideNavItemVariants
+};

package/dist/components/sidebar/index.js

@@ -0,0 +1,21 @@
+// src/components/sidebar/index.ts
+import {
+  Sidebar,
+  SidebarHeader,
+  SidebarBrand,
+  SidebarNav,
+  SidebarFooter,
+  SidebarItem,
+  useSidebar
+} from "./sidebar.js";
+import { sidebarMeta } from "./sidebar.meta.js";
+export {
+  Sidebar,
+  SidebarBrand,
+  SidebarFooter,
+  SidebarHeader,
+  SidebarItem,
+  SidebarNav,
+  sidebarMeta,
+  useSidebar
+};

package/dist/components/sidebar/sidebar.js

@@ -0,0 +1,196 @@
+"use client";
+
+// src/components/sidebar/sidebar.tsx
+import { useRender } from "@base-ui/react/use-render";
+import {
+  createContext,
+  useContext
+} from "react";
+import { cn } from "../../lib/cn.js";
+import { RAIL_ROW_INLINE, sideNavItemIconVariants, sideNavItemVariants } from "../side-nav/side-nav.variants.js";
+import { SimpleTooltip } from "../tooltip/index.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var SidebarContext = createContext({
+  collapsed: false,
+  icons: true
+});
+function useSidebar() {
+  return useContext(SidebarContext);
+}
+var SIDEBAR_VARIANT = {
+  // Full viewport less an AppShell dock (0 without one), so a persistent
+  // player bar never covers the rail's last rows.
+  app: "hidden lg:flex lg:sticky lg:top-0 lg:h-[calc(100vh-var(--dock-height,0px))] lg:self-start",
+  inline: "flex h-full"
+};
+var SIDEBAR_INK = [
+  "[--background:var(--sidebar)] [--sable-surface-bg:var(--sidebar)]",
+  "[--foreground:var(--sidebar-foreground)]",
+  "[--muted:var(--sidebar-accent)]",
+  "[--muted-foreground:var(--sidebar-muted-foreground,color-mix(in_oklab,var(--sidebar-foreground)_62%,var(--sidebar)))]",
+  "[--accent:var(--sidebar-accent)] [--accent-foreground:var(--sidebar-accent-foreground)]",
+  "[--border:var(--sidebar-border)] [--ring:var(--sidebar-ring)]"
+].join(" ");
+function Sidebar({
+  collapsed = false,
+  icons = true,
+  variant = "app",
+  className,
+  children,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(SidebarContext.Provider, { value: { collapsed, icons }, children: /* @__PURE__ */ jsx(
+    "aside",
+    {
+      "data-collapsed": collapsed || void 0,
+      "data-variant": variant,
+      className: cn(
+        "shrink-0 flex-col border-r border-sidebar-border bg-sidebar text-sidebar-foreground",
+        // The rail is its own surface. Anything placed in it that inks with
+        // page tokens — an Entity account row, an Avatar, a ghost Button,
+        // an OverflowMenu — reads the rail's set instead, so a theme can paint a
+        // dark rail on a light page (Meridian) and the footer row stays
+        // legible. Muted ink is the rail's ink at 62% over the rail, unless
+        // a theme names --sidebar-muted-foreground.
+        SIDEBAR_INK,
+        SIDEBAR_VARIANT[variant],
+        "w-[var(--sidebar-width,16rem)] data-[collapsed]:w-[var(--sidebar-width-collapsed,4rem)]",
+        className
+      ),
+      ...props,
+      children
+    }
+  ) });
+}
+Sidebar.displayName = "Sidebar";
+function SidebarHeader({
+  className,
+  ...props
+}) {
+  const { collapsed } = useSidebar();
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cn(
+        "flex h-16 items-center px-3",
+        // Collapsed, the brand mark centres on the same axis as the item icons.
+        collapsed && "justify-center px-0",
+        className
+      ),
+      ...props
+    }
+  );
+}
+SidebarHeader.displayName = "SidebarHeader";
+function SidebarBrand({ mark, label, render, className, "aria-label": ariaLabel, ...props }) {
+  const { collapsed } = useSidebar();
+  return useRender({
+    render: render ?? /* @__PURE__ */ jsx("div", {}),
+    props: {
+      ...props,
+      // Collapsed shows the mark alone, so a string label still names the link.
+      "aria-label": ariaLabel ?? (collapsed && typeof label === "string" ? label : void 0),
+      className: cn(
+        "flex min-w-0 items-center rounded-sm",
+        // The item row's horizontal geometry, without its height.
+        RAIL_ROW_INLINE,
+        render && "motion-interactive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-sidebar-ring",
+        collapsed && "justify-center px-0",
+        className
+      ),
+      children: /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("span", { className: sideNavItemIconVariants({ size: "rail" }), children: mark }),
+        collapsed ? null : /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate text-title-sm", children: label })
+      ] })
+    },
+    defaultTagName: "div"
+  });
+}
+SidebarBrand.displayName = "SidebarBrand";
+function SidebarNav({
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "nav",
+    {
+      className: cn(
+        // Thin scrollbar so a long nav does not hand a fat platform bar to a
+        // narrow rail, and contained overscroll so a wheel gesture that runs
+        // out of nav stops there instead of scrolling the page behind it.
+        "flex flex-1 flex-col gap-1 overflow-y-auto overscroll-contain px-3 py-4 scrollbar-quiet",
+        className
+      ),
+      ...props
+    }
+  );
+}
+SidebarNav.displayName = "SidebarNav";
+function SidebarFooter({
+  className,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cn(
+        "flex flex-col gap-1 border-t border-sidebar-border px-3 py-4",
+        className
+      ),
+      ...props
+    }
+  );
+}
+SidebarFooter.displayName = "SidebarFooter";
+function SidebarItem({
+  icon,
+  label,
+  active,
+  badge,
+  render,
+  className,
+  "aria-label": ariaLabel,
+  ...props
+}) {
+  const { collapsed, icons } = useSidebar();
+  const showIcon = icon != null && (icons || collapsed);
+  const element = useRender({
+    render: render ?? /* @__PURE__ */ jsx("button", { type: "button" }),
+    props: {
+      ...props,
+      "data-active": active ? "" : void 0,
+      "aria-current": active ? "page" : void 0,
+      // Collapsed rows hide their text, so give the control an accessible name
+      // from a string label (the tooltip supplies the visible one on hover).
+      "aria-label": ariaLabel ?? (collapsed && typeof label === "string" ? label : void 0),
+      className: cn(
+        // SideNav's row recipe on the rail rung — one row, not a copy.
+        sideNavItemVariants({ size: "rail", activeVariant: "sidebar" }),
+        collapsed && "justify-center px-0",
+        className
+      ),
+      children: /* @__PURE__ */ jsxs(Fragment, { children: [
+        showIcon ? /* @__PURE__ */ jsx("span", { className: sideNavItemIconVariants({ size: "rail" }), children: icon }) : null,
+        collapsed ? null : /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate", children: label }),
+          badge ? /* @__PURE__ */ jsx("span", { className: "ms-auto shrink-0", children: badge }) : null
+        ] })
+      ] })
+    },
+    defaultTagName: "button"
+  });
+  if (collapsed) {
+    return /* @__PURE__ */ jsx(SimpleTooltip, { content: label, side: "right", children: element });
+  }
+  return element;
+}
+SidebarItem.displayName = "SidebarItem";
+export {
+  Sidebar,
+  SidebarBrand,
+  SidebarFooter,
+  SidebarHeader,
+  SidebarItem,
+  SidebarNav,
+  useSidebar
+};

package/dist/components/sidebar/sidebar.meta.js

@@ -0,0 +1,118 @@
+// src/components/sidebar/sidebar.meta.ts
+var sidebarMeta = {
+  name: "Sidebar",
+  summary: "Desktop side-navigation rail (in-flow sticky, hidden below lg) with SidebarHeader / SidebarBrand / SidebarNav / SidebarItem / SidebarFooter parts. Items are router-agnostic via the `render` prop; an optional collapsed icon-rail mode reveals labels in tooltips.",
+  status: "stable",
+  keywords: [
+    "sidebar",
+    "navigation",
+    "app chrome",
+    "rail"
+  ],
+  usage: {
+    description: "Use Sidebar for persistent desktop navigation or application chrome outside the main content region.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it for stable app destinations that should remain visible while content changes."
+      },
+      {
+        guidance: "do",
+        description: "Keep item labels predictable and active state obvious."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use Sidebar for page-local settings, filters, or temporary action groups."
+      },
+      {
+        guidance: "dont",
+        description: "Do not put page content in it. It is fixed-width chrome OUTSIDE the content grid, so anything in it is exempt from the page's measure and rhythm."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Sidebar",
+        required: true,
+        description: "The persistent navigation container."
+      },
+      {
+        name: "SidebarItem",
+        required: true,
+        description: "One navigation destination or action."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "SideNav",
+      "BottomNav",
+      "AppShell"
+    ]
+  },
+  props: [
+    {
+      name: "collapsed",
+      type: "boolean",
+      default: "false",
+      description: "Collapse the rail to an icon-only width (--sidebar-width-collapsed). Items hide their label + badge and reveal the label in a hover tooltip; the content area reflows. Controlled \u2014 wire a toggle from app state. Read the state in custom header/footer content via useSidebar()."
+    },
+    {
+      name: "icons",
+      type: "boolean",
+      default: "true",
+      description: "Render the leading icon on each SidebarItem. Set false for a text-only rail. Ignored while collapsed (icon-only by definition)."
+    },
+    {
+      name: "variant",
+      type: '"app" | "inline"',
+      default: '"app"',
+      description: `Where the rail lives. "app" is the page's chrome column \u2014 sticky, full viewport height, hidden below lg where AppHeader + BottomNav take over. "inline" is always visible and fills its parent's height, for a rail inside a bounded frame (a nested shell, an embedded preview). Use it instead of overriding the layout with !important classes.`
+    }
+  ],
+  subcomponents: [
+    {
+      name: "SidebarBrand",
+      type: "{ mark: ReactNode; label: ReactNode; render?: useRender.RenderProp } + div props",
+      description: `The brand row, inside SidebarHeader, on the same grid as SidebarItem: mark in the icons' 24px slot, label on the labels' column, so a logo lines up with the nav below it without copying the rail's inset numbers. Collapsed, it shows the mark alone (named by a string label). render={<Link to="/" />} makes it the home link.`
+    },
+    {
+      name: "SidebarItem",
+      type: "{ label: ReactNode; icon?: ReactNode; active?: boolean; badge?: ReactNode; render?: useRender.RenderProp } + button props",
+      description: 'A single nav row. label is the row text (inline when expanded, in a hover tooltip when collapsed); icon is the leading icon node (the consumer swaps fill weight for the active state); active marks the current route (accent fill + aria-current="page"); badge is a trailing node (e.g. a count) pushed to the row end and hidden when collapsed; render composes another element, e.g. render={<Link to="/x" />}.'
+    }
+  ],
+  a11y: [
+    "SidebarNav renders a <nav> landmark.",
+    'Active item carries aria-current="page".',
+    "Items expose a focus-visible ring (sidebar-ring).",
+    "Collapsed: items take their accessible name from a string label (or aria-label) and reveal the visible label via the tooltip, so the rail stays usable by keyboard and screen readers."
+  ],
+  tokensUsed: [
+    "sidebar",
+    "sidebar-foreground",
+    "sidebar-border",
+    "sidebar-accent",
+    "sidebar-accent-foreground",
+    "sidebar-ring"
+  ],
+  variants: {
+    variant: ["app", "inline"]
+  },
+  examples: [
+    {
+      label: "Rail with nav",
+      code: '<Sidebar><SidebarHeader><SidebarBrand mark={<Icon name="music" variant="solid" />} label="Undertow" render={<Link to="/" />} /></SidebarHeader><SidebarNav><SidebarItem icon={<Icon name="bell" />} label="Notifications" badge={<NotificationBadge count={3} />} render={<Link to="/notifications" />} /></SidebarNav><SidebarFooter>{wallet}</SidebarFooter></Sidebar>'
+    },
+    {
+      label: "Collapsible (icon rail)",
+      code: 'const [collapsed, setCollapsed] = useState(false)\n<Sidebar collapsed={collapsed}><SidebarNav><SidebarItem icon={<Icon name="home" />} label="Home" active render={<Link to="/" />} /></SidebarNav><SidebarFooter><Button variant="ghost" size="icon" onClick={() => setCollapsed((c) => !c)} aria-label="Toggle sidebar"><Icon name="chevron-left" /></Button></SidebarFooter></Sidebar>'
+    },
+    {
+      label: "Inline (inside a bounded frame)",
+      code: '<div className="flex h-80 overflow-hidden rounded-lg border border-border"><Sidebar variant="inline"><SidebarNav><SidebarItem icon={<Icon name="home" />} label="Home" active /></SidebarNav></Sidebar><div className="flex-1 p-6">Content</div></div>'
+    }
+  ]
+};
+export {
+  sidebarMeta
+};