@hyphen/hyphen-components 7.7.0 → 7.8.1

package/dist/index.d.ts

@@ -2004,14 +2004,14 @@ interface HeadingProps {
     className?: string;
     /**
      * A variant token identifier to use for the text variant. Available variants found:
-     * [here](https://github.com/hyphen/hyphen-design-tokens/blob/main/properties/color/font.json).
+     * [here](https://github.com/Hyphen/hyphen-components/blob/main/packages/design-tokens/tokens/color/font.json).
      */
     color?: FontColor;
     /**
      * By default, size is determined by the chosen tag (e.g. h1 is bigger than h2).
      * However, size can be set independently so that its size is appropriate for the surrounding content.
      * Available sizes found:
-     * [here](https://github.com/hyphen/hyphen-design-tokens/blob/main/properties/size/font.json).
+     * [here](https://github.com/Hyphen/hyphen-components/blob/main/packages/design-tokens/tokens/size/font.json).
      */
     size?: HeadingSize | ResponsiveProp<HeadingSize>;
     /**
@@ -2271,17 +2271,49 @@ declare function useSidebar(sideOverride?: SidebarSide): {
     toggleSidebar: () => void;
 };
 declare const SidebarProvider: React__default.ForwardRefExoticComponent<Omit<React__default.ClassAttributes<HTMLDivElement> & React__default.HTMLAttributes<HTMLDivElement> & {
+    /**
+     * Initial open state for uncontrolled usage. Pass a boolean for both
+     * sides, or `{ left, right }` to set each side independently.
+     */
     defaultOpen?: SidebarOpenValue;
+    /**
+     * Controlled open state. Pass a boolean for both sides, or
+     * `{ left, right }` to control each side independently.
+     */
     open?: SidebarOpenValue;
+    /**
+     * localStorage key(s) the open state is written to when a sidebar is
+     * toggled. A string applies to the left sidebar, with `_right` appended
+     * for the right sidebar; pass `{ left, right }` to set each explicitly.
+     */
     storageKey?: SidebarStorageKey;
+    /**
+     * Called when a sidebar is toggled, with the new open state and which
+     * side was toggled.
+     */
     onOpenChange?: (open: boolean, side?: SidebarSide) => void;
 }, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
 declare const Sidebar: React__default.ForwardRefExoticComponent<Omit<React__default.ClassAttributes<HTMLDivElement> & React__default.HTMLAttributes<HTMLDivElement> & {
+    /**
+     * Which edge of the viewport the sidebar is attached to.
+     */
     side?: "left" | "right";
+    /**
+     * Collapse behavior when the sidebar is toggled closed: slide fully out
+     * of view (`offcanvas`), collapse to a narrow icon strip (`icon`), or
+     * stay at full width (`none`).
+     */
     collapsible?: "offcanvas" | "icon" | "none";
 }, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
 declare const SidebarTrigger: React__default.ForwardRefExoticComponent<Omit<BaseButtonProps & React__default.ButtonHTMLAttributes<HTMLButtonElement> & React__default.RefAttributes<HTMLButtonElement> & {
+    /**
+     * Which sidebar to toggle. Defaults to the side of the containing
+     * Sidebar, or `left` outside of one.
+     */
     side?: SidebarSide;
+    /**
+     * Icon shown on the trigger button.
+     */
     iconName?: IconName;
 }, "ref"> & React__default.RefAttributes<HTMLButtonElement>>;
 declare const SidebarInset: React__default.ForwardRefExoticComponent<Omit<React__default.DetailedHTMLProps<React__default.HTMLAttributes<HTMLElement>, HTMLElement>, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
@@ -2291,8 +2323,18 @@ declare const SidebarContent: React__default.ForwardRefExoticComponent<Omit<Reac
 declare const SidebarMenu: React__default.ForwardRefExoticComponent<Omit<React__default.DetailedHTMLProps<React__default.HTMLAttributes<HTMLUListElement>, HTMLUListElement>, "ref"> & React__default.RefAttributes<HTMLUListElement>>;
 declare const SidebarMenuItem: React__default.ForwardRefExoticComponent<Omit<React__default.DetailedHTMLProps<React__default.LiHTMLAttributes<HTMLLIElement>, HTMLLIElement>, "ref"> & React__default.RefAttributes<HTMLLIElement>>;
 declare const SidebarMenuButton: React__default.ForwardRefExoticComponent<Omit<React__default.ClassAttributes<HTMLButtonElement> & React__default.ButtonHTMLAttributes<HTMLButtonElement> & {
+    /**
+     * Render the child element (e.g. a router link) instead of a `button`.
+     */
     asChild?: boolean;
+    /**
+     * Marks the item as the current page.
+     */
     isActive?: boolean;
+    /**
+     * Tooltip shown when the sidebar is collapsed to icons (desktop only).
+     * Pass a string, or TooltipContent props for full control.
+     */
     tooltip?: string | React__default.ComponentProps<typeof TooltipContent>;
 }, "ref"> & React__default.RefAttributes<HTMLButtonElement>>;
 declare const SidebarGroup: React__default.ForwardRefExoticComponent<Omit<React__default.DetailedHTMLProps<React__default.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React__default.RefAttributes<HTMLDivElement>>;

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@hyphen/hyphen-components",
-  "version": "7.7.0",
-  "packageManager": "pnpm@10.20.0",
+  "version": "7.8.1",
   "license": "MIT",
   "author": {
     "name": "@hyphen"
@@ -16,34 +15,8 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Hyphen/hyphen-components.git"
-  },
-  "scripts": {
-    "build": "cross-env IS_PUBLISHING=true tsup && cross-env IS_PUBLISHING=true webpack --config webpack.config.js && node scripts/create-cjs-shim.js",
-    "build-storybook": "storybook build",
-    "build-storybook-docs": "storybook build --docs",
-    "storybook-docs": "storybook dev --docs",
-    "lint": "eslint src --ext .ts,.tsx",
-    "lint-fix": "eslint src --ext .ts,.tsx --fix",
-    "size": "size-limit",
-    "start": "tsup --watch",
-    "storybook": "storybook dev -p 6006",
-    "test": "jest --passWithNoTests",
-    "test-watch": "jest --coverage --watch",
-    "semantic-release": "semantic-release",
-    "prepare": "pnpm run build",
-    "chromatic": "chromatic --project-token=chpt_8fddffb5556f0b7 --only-changed"
-  },
-  "husky": {
-    "hooks": {
-      "pre-commit": "eslint src --ext .ts,.tsx"
-    }
-  },
-  "prettier": {
-    "printWidth": 80,
-    "semi": true,
-    "singleQuote": true,
-    "trailingComma": "es5"
+    "url": "git+https://github.com/Hyphen/hyphen-components.git",
+    "directory": "packages/components"
   },
   "peerDependencies": {
     "react": ">=16"
@@ -64,7 +37,6 @@
   "dependencies": {
     "@daypicker/react": "^10.0.1",
     "@emotion/react": "^11.14.0",
-    "@hyphen/hyphen-design-tokens": "^7.7.0",
     "@radix-ui/react-aspect-ratio": "^1.1.9",
     "@radix-ui/react-collapsible": "^1.1.13",
     "@radix-ui/react-dropdown-menu": "^2.1.17",
@@ -83,12 +55,12 @@
     "react-router-dom": "^6.30.4",
     "react-select": "^5.10.0",
     "react-select-event": "^5.5.1",
-    "uuid": "^11.1.1"
+    "uuid": "^11.1.1",
+    "@hyphen/hyphen-design-tokens": "^7.8.1"
   },
   "devDependencies": {
     "@babel/core": "^7.27.4",
     "@chromatic-com/storybook": "^5.2.1",
-    "@semantic-release/commit-analyzer": "^11.1.0",
     "@size-limit/preset-small-lib": "^11.2.0",
     "@storybook/addon-a11y": "10.4.2",
     "@storybook/addon-docs": "10.4.2",
@@ -124,7 +96,6 @@
     "eslint-plugin-react": "^7.34.0",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-storybook": "10.4.2",
-    "husky": "^8.0.3",
     "identity-obj-proxy": "^3.0.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^30.2.0",
@@ -137,9 +108,9 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-is": "^18.3.1",
+    "remark-gfm": "^4.0.1",
     "sass": "^1.77.8",
     "sass-loader": "^13.3.3",
-    "semantic-release": "^25.0.2",
     "size-limit": "^11.2.0",
     "storybook": "10.4.2",
     "ts-jest": "^29.4.6",
@@ -152,5 +123,19 @@
     "webpack": "^5.94.0",
     "webpack-cli": "^5.1.4",
     "webpack-fix-style-only-entries": "^0.6.1"
+  },
+  "scripts": {
+    "build": "cross-env IS_PUBLISHING=true tsup && cross-env IS_PUBLISHING=true webpack --config webpack.config.js && node scripts/create-cjs-shim.js",
+    "build-storybook": "storybook build",
+    "build-storybook-docs": "storybook build --docs",
+    "storybook-docs": "storybook dev --docs",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint-fix": "eslint src --ext .ts,.tsx --fix",
+    "size": "size-limit",
+    "start": "tsup --watch",
+    "storybook": "storybook dev -p 6006",
+    "test": "jest --passWithNoTests",
+    "test-watch": "jest --coverage --watch",
+    "chromatic": "chromatic --only-changed"
   }
-}
+}

package/src/components/FormControl/FormControl.stories.tsx

@@ -0,0 +1,92 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+import { FormControl } from './FormControl';
+
+const meta = {
+  component: FormControl,
+  tags: ['ai-generated'],
+} satisfies Meta<typeof FormControl>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    id: 'first-name',
+    label: 'First name',
+  },
+  render: (args) => (
+    <FormControl {...args}>
+      <input id={args.id} type="text" />
+    </FormControl>
+  ),
+  play: async ({ canvas }) => {
+    // Proves the FormLabel htmlFor/input id wiring, not just that it mounted.
+    await expect(canvas.getByLabelText('First name')).toBeVisible();
+  },
+};
+
+export const WithHelpText: Story = {
+  args: {
+    id: 'email',
+    label: 'Email address',
+    helpText: 'We will never share your email.',
+  },
+  render: (args) => (
+    <FormControl {...args}>
+      <input id={args.id} type="email" />
+    </FormControl>
+  ),
+};
+
+export const WithError: Story = {
+  args: {
+    id: 'password',
+    label: 'Password',
+    error: 'Password must be at least 8 characters.',
+  },
+  render: (args) => (
+    <FormControl {...args}>
+      <input id={args.id} type="password" />
+    </FormControl>
+  ),
+  play: async ({ canvas }) => {
+    // The error prop renders as an InputValidationMessage below the input.
+    await expect(
+      canvas.getByText('Password must be at least 8 characters.')
+    ).toBeVisible();
+  },
+};
+
+export const Required: Story = {
+  args: {
+    id: 'username',
+    label: 'Username',
+    isRequired: true,
+  },
+  render: (args) => (
+    <FormControl {...args}>
+      <input id={args.id} type="text" required />
+    </FormControl>
+  ),
+};
+
+export const HiddenLabel: Story = {
+  args: {
+    id: 'search',
+    label: 'Search',
+    hideLabel: true,
+  },
+  render: (args) => (
+    <FormControl {...args}>
+      <input id={args.id} type="search" aria-label={args.label} />
+    </FormControl>
+  ),
+  play: async ({ canvas }) => {
+    // hideLabel suppresses the visible FormLabel entirely.
+    await expect(canvas.queryByText('Search')).not.toBeInTheDocument();
+    // The input must still be accessible via its aria-label.
+    await expect(canvas.getByLabelText('Search')).toBeVisible();
+  },
+};

package/src/components/Heading/Heading.tsx

@@ -26,14 +26,14 @@ export interface HeadingProps {
   className?: string;
   /**
    * A variant token identifier to use for the text variant. Available variants found:
-   * [here](https://github.com/hyphen/hyphen-design-tokens/blob/main/properties/color/font.json).
+   * [here](https://github.com/Hyphen/hyphen-components/blob/main/packages/design-tokens/tokens/color/font.json).
    */
   color?: FontColor;
   /**
    * By default, size is determined by the chosen tag (e.g. h1 is bigger than h2).
    * However, size can be set independently so that its size is appropriate for the surrounding content.
    * Available sizes found:
-   * [here](https://github.com/hyphen/hyphen-design-tokens/blob/main/properties/size/font.json).
+   * [here](https://github.com/Hyphen/hyphen-components/blob/main/packages/design-tokens/tokens/size/font.json).
    */
   size?: HeadingSize | ResponsiveProp<HeadingSize>;
   /**

package/src/components/HelpText/HelpText.stories.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { HelpText } from './HelpText';
+import { Box } from '../Box/Box';
+
+const meta = {
+  component: HelpText,
+  tags: ['ai-generated'],
+} satisfies Meta<typeof HelpText>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: 'Additional clarifying text to help describe the input.',
+  },
+};
+
+export const BelowAnInput: Story = {
+  render: () => (
+    <Box gap="2xs">
+      <label htmlFor="help-text-example">Email address</label>
+      <input
+        id="help-text-example"
+        type="email"
+        aria-describedby="help-text-example-hint"
+      />
+      {/* HelpText doesn't forward an id, so associate via a wrapper. */}
+      <div id="help-text-example-hint">
+        <HelpText>We will only use this to send your receipt.</HelpText>
+      </div>
+    </Box>
+  ),
+};
+
+export const WithRichContent: Story = {
+  args: {
+    children: (
+      <>
+        Must contain at least <strong>8 characters</strong>.
+      </>
+    ),
+  },
+};

package/src/components/InputValidationMessage/InputValidationMessage.stories.tsx

@@ -0,0 +1,50 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+import { InputValidationMessage } from './InputValidationMessage';
+import { Box } from '../Box/Box';
+
+const meta = {
+  component: InputValidationMessage,
+  tags: ['ai-generated'],
+} satisfies Meta<typeof InputValidationMessage>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: 'This field is required.',
+  },
+};
+
+export const Sizes: Story = {
+  args: {
+    children: 'This field is required.',
+  },
+  render: () => (
+    <Box gap="sm">
+      <InputValidationMessage size="xs">
+        Extra small validation message
+      </InputValidationMessage>
+      <InputValidationMessage size="sm">
+        Small validation message
+      </InputValidationMessage>
+      <InputValidationMessage size="md">
+        Medium validation message
+      </InputValidationMessage>
+    </Box>
+  ),
+};
+
+export const CssCheck: Story = {
+  args: {
+    children: 'This field is required.',
+  },
+  play: async ({ canvas }) => {
+    const message = canvas.getByText('This field is required.');
+    // font-color-danger resolves to --color-font-danger (#dc2626 in the light
+    // theme) — fails if the design-token CSS did not load in the preview.
+    await expect(getComputedStyle(message).color).toBe('rgb(220, 38, 38)');
+  },
+};

package/src/components/Sidebar/Sidebar.mdx

@@ -0,0 +1,208 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
+import {
+  SidebarProvider,
+  Sidebar,
+  SidebarTrigger,
+  SidebarMenuButton,
+} from './Sidebar';
+import * as Stories from './Sidebar.stories';
+
+<Meta of={Stories} />
+
+{/*
+  The embedded stories render in iframes, and the iframe is the story's
+  viewport. Keep it at least as wide as the desktop breakpoint (992px) so
+  the examples show the desktop sidebar instead of the mobile drawer,
+  scrolling horizontally when the docs column is narrower. Scoped to this
+  page's Canvas blocks via the sidebar-docs-canvas class.
+*/}
+
+<style>
+  {`
+    .sidebar-docs-canvas .docs-story { overflow-x: auto; }
+    .sidebar-docs-canvas .docs-story iframe { min-width: 1100px; }
+  `}
+</style>
+
+# Sidebar
+
+A composable, collapsible app sidebar for primary navigation. Use it to build an application sidebar with a header, scrollable content, grouped menus, and a footer, all wired to expand/collapse state that persists across visits and adapts to mobile automatically.
+
+<Canvas of={Stories.SidebarExample} />
+
+## Anatomy
+
+The Sidebar is composed from small building blocks. Compose only the pieces you need:
+
+| Component              | Purpose                                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `SidebarProvider`      | Provides sidebar state (left and right) and keyboard shortcuts. Wrap your whole layout in it.       |
+| `Sidebar`              | The sidebar container itself. Configure `side` and `collapsible` behavior.                          |
+| `SidebarHeader`        | Sticky top region, typically an org/team switcher.                                                  |
+| `SidebarContent`       | The scrollable middle region of the sidebar.                                                        |
+| `SidebarFooter`        | Sticky bottom region, typically the user menu.                                                      |
+| `SidebarGroup`         | A section within `SidebarContent`.                                                                  |
+| `SidebarGroupLabel`    | Label for a group. Hidden automatically when collapsed to icons.                                    |
+| `SidebarMenu`          | A menu (`ul`) of navigation items.                                                                  |
+| `SidebarMenuItem`      | A single item (`li`) within a `SidebarMenu`.                                                        |
+| `SidebarMenuButton`    | The interactive element of an item. Supports `asChild`, `isActive`, and a collapsed-state `tooltip`.|
+| `SidebarMenuAction`    | A secondary action button rendered at the edge of a menu item (e.g. a "more" menu).                 |
+| `SidebarMenuBadge`     | A badge (e.g. a count) rendered at the edge of a menu item.                                         |
+| `SidebarMenuSub`       | A nested sub-menu, typically inside a `Collapsible`.                                                |
+| `SidebarMenuSubItem`   | A single item within a `SidebarMenuSub`.                                                            |
+| `SidebarMenuSubButton` | The interactive element of a sub-menu item. Supports `asChild` and `isActive`.                      |
+| `SidebarTrigger`       | A button that toggles the sidebar. Place it in your page content or mobile header.                  |
+| `SidebarRail`          | A slim hover target on the sidebar edge for toggling with the mouse.                                |
+| `SidebarInset`         | The `main` content area that sits alongside the sidebar.                                            |
+| `useSidebar`           | Hook for reading and controlling sidebar state from your own components.                            |
+
+A typical app sidebar composition looks like this:
+
+```tsx
+<SidebarProvider>
+  <Sidebar side="left" collapsible="icon">
+    <SidebarHeader>{/* org switcher */}</SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>Platform</SidebarGroupLabel>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton asChild isActive tooltip="Dashboard">
+              <a href="/">
+                <Icon name="dashboard" />
+                <span>Dashboard</span>
+              </a>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+    <SidebarFooter>{/* user menu */}</SidebarFooter>
+    <SidebarRail />
+  </Sidebar>
+  <SidebarInset>
+    <SidebarTrigger />
+    {/* page content */}
+  </SidebarInset>
+</SidebarProvider>
+```
+
+## Usage Guidelines
+
+- Wrap the entire layout — sidebar and page content — in a single `SidebarProvider`. One provider manages both a left and a right sidebar.
+- Wrap your app (or the layout) in `ResponsiveProvider` so `useIsMobile` can detect the viewport; below the `desktop` breakpoint the sidebar renders inside a [Drawer](/docs/components-drawer--docs) and is toggled with `SidebarTrigger`.
+- Use `SidebarMenuButton asChild` to render your router's link component (or an `a` tag) so navigation items are real links.
+- Give menu buttons a `tooltip` so labels remain discoverable when the sidebar is collapsed to icons.
+- Set `isActive` on the menu button for the current route.
+- Include a `SidebarRail` so users can toggle the sidebar by clicking its edge.
+
+## Collapsible Behavior
+
+The `collapsible` prop on `Sidebar` controls what happens when the sidebar is toggled closed:
+
+- `offcanvas` (default) — the sidebar slides fully out of view.
+- `icon` — the sidebar collapses to a narrow icon strip; menu button tooltips appear on hover.
+- `none` — the sidebar cannot collapse and stays at full width.
+
+## Right Sidebar
+
+Set `side="right"` to render a sidebar on the opposite edge, useful for contextual panels. A right sidebar is wider by default (`24rem` vs `16rem`). Use `SidebarTrigger side="right"` to toggle it from within your content.
+
+<Canvas of={Stories.SidebarRightExample} />
+
+## Left and Right Together
+
+One `SidebarProvider` manages both sides independently. Pass per-side values to `defaultOpen` and `storageKey` as objects with `left` and `right` keys.
+
+<Canvas of={Stories.SidebarBothSides} />
+
+## Collapsed by Default
+
+Pass `defaultOpen={false}` to the provider to start collapsed.
+
+<Canvas of={Stories.SidebarCollapsed} />
+
+## State Persistence
+
+Whenever the user toggles a sidebar, the provider writes the new state to `localStorage` under the resolved `storageKey` (a string key applies to the left sidebar, with `_right` appended for the right sidebar; pass an object to set each side explicitly). Reading the stored value back is left to your app — pass it to `defaultOpen` on mount:
+
+```tsx
+// Guard the read so it is safe in SSR environments (e.g. Next.js),
+// where localStorage does not exist on the server.
+const startExpanded =
+  typeof window !== 'undefined'
+    ? localStorage.getItem('sidebar_expanded') !== 'false'
+    : true;
+
+<SidebarProvider storageKey="sidebar_expanded" defaultOpen={startExpanded}>
+  ...
+</SidebarProvider>;
+```
+
+## Controlled Sidebar
+
+Pass `open` (boolean, or `{ left, right }`) to control the sidebar yourself, and use `onOpenChange(open, side)` to respond to toggle requests. Omit `open` for uncontrolled behavior with `defaultOpen`.
+
+## Keyboard Shortcuts
+
+- <kbd>[</kbd> toggles the left sidebar.
+- <kbd>]</kbd> toggles the right sidebar.
+
+Shortcuts are ignored while focus is in an input, textarea, select, or content-editable element.
+
+## useSidebar
+
+Call `useSidebar()` inside a `SidebarProvider` to read or control sidebar state from your own components. Inside a `Sidebar` it resolves to that sidebar's side; elsewhere pass the side explicitly: `useSidebar('right')`.
+
+It returns:
+
+| Property        | Type                          | Description                                        |
+| --------------- | ----------------------------- | -------------------------------------------------- |
+| `state`         | `'expanded' \| 'collapsed'`   | Current visual state.                              |
+| `open`          | `boolean`                     | Whether the (desktop) sidebar is open.             |
+| `setOpen`       | `(open: boolean) => void`     | Set the desktop open state.                        |
+| `openMobile`    | `boolean`                     | Whether the mobile drawer is open.                 |
+| `setOpenMobile` | `(open: boolean) => void`     | Set the mobile drawer state.                       |
+| `toggleSidebar` | `() => void`                  | Toggle the sidebar (desktop or mobile as needed).  |
+| `isMobile`      | `boolean`                     | Whether the viewport is below the desktop breakpoint. |
+| `side`          | `'left' \| 'right'`           | Which side this state refers to.                   |
+
+## Props
+
+All components forward refs and accept the standard props of the elements they render (`className`, `style`, event handlers, etc.).
+
+### SidebarProvider
+
+<ArgTypes of={SidebarProvider} />
+
+### Sidebar
+
+<ArgTypes of={Sidebar} />
+
+### SidebarTrigger
+
+Extends [Button](/docs/components-button--docs).
+
+<ArgTypes of={SidebarTrigger} />
+
+### SidebarMenuButton
+
+<ArgTypes of={SidebarMenuButton} />
+
+## Theming
+
+The sidebar exposes CSS custom properties you can override on `SidebarProvider` (via `style`) or a parent element:
+
+| Custom Property                | Default    | Description                                     |
+| ------------------------------ | ---------- | ----------------------------------------------- |
+| `--sidebar-width`              | `16rem`    | Expanded width (`24rem` for a right sidebar).   |
+| `--sidebar-width-icon`         | `44px`     | Width when collapsed to icons.                  |
+| `--sidebar-transition-duration`| `200ms`    | Expand/collapse animation duration.             |
+| `--sidebar-transition-timing`  | `linear`   | Expand/collapse animation timing function.      |
+
+## Accessibility
+
+- `SidebarTrigger` renders a real button with an `aria-label` of "Toggle left sidebar" / "Toggle right sidebar".
+- `SidebarRail` is removed from the tab order (`tabIndex={-1}`) since `SidebarTrigger` and the keyboard shortcuts cover keyboard users; it exposes an `aria-label` and a `title` with the shortcut.
+- `SidebarMenu` and `SidebarMenuSub` render semantic lists, and `asChild` lets menu items render real links for correct link semantics.
+- On mobile the sidebar renders inside a [Drawer](/docs/components-drawer--docs), which traps focus and closes with <kbd>Esc</kbd>.

package/src/components/Sidebar/Sidebar.stories.tsx

@@ -50,6 +50,19 @@ const meta: Meta<typeof Sidebar> = {
   parameters: {
     layout: 'fullscreen',
     overrideDecorator: true,
+    // The sidebar examples fill 100svh, so render them in a fixed-height
+    // iframe on the docs page instead of inline at full height.
+    docs: {
+      story: {
+        inline: false,
+        height: '640px',
+      },
+      // Scopes the docs-page CSS in Sidebar.mdx (which forces a desktop-width
+      // viewport on the story iframes) to this page's Canvas blocks only.
+      canvas: {
+        className: 'sidebar-docs-canvas',
+      },
+    },
     chromatic: {
       modes: {
         light: allModes['light'],