@beydesign/storybook 0.2.30 → 0.3.0

package/dist/index.d.ts

@@ -8,8 +8,6 @@ export * from './stories/Buttons';
 export * from './stories/Typography';
 export * from './stories/Credits';
 export * from './stories/Navigation';
-export * from './stories/Drawer';
-export * from './stories/Settings';
 export * from './stories/Typography';
 export * from './stories/UI';
 export * from './stories/StripeProduct';

package/dist/index.js

@@ -8,8 +8,6 @@ export * from './stories/Buttons';
 export * from './stories/Typography';
 export * from './stories/Credits';
 export * from './stories/Navigation';
-export * from './stories/Drawer';
-export * from './stories/Settings';
 export * from './stories/Typography';
 export * from './stories/UI';
 export * from './stories/StripeProduct';

package/dist/stories/{Drawer → Navigation/Drawer}/Drawer.d.ts

@@ -6,5 +6,9 @@ import { DrawerProps } from './types';
  * toggle. Collapse state can be controlled (`collapsed` + `onToggle`) or left
  * uncontrolled (`defaultCollapsed`). Every colour, space and radius resolves to
  * `@beydesign/tokens` CSS variables, so it renders correctly in light and dark.
+ *
+ * Below the mobile breakpoint there is no room for this beside a settings
+ * sub-nav — use `MobileNav`, which renders the same {@link DrawerBody} as one
+ * pane of a single overlay.
  */
 export declare const Drawer: React.FC<DrawerProps>;

package/dist/stories/Navigation/Drawer/Drawer.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import styled from '@emotion/styled';
+import { DrawerSize } from './types';
+import { DrawerBody } from './DrawerBody';
+import { NavPanel } from '../internal';
+import { getIconComponent } from '../../../utils';
+const EXPANDED_WIDTH = '238px';
+const COLLAPSED_WIDTH = '68px';
+/** Composed from the semantic `shadow-sm` design token. */
+const SHADOW_SM = 'var(--global-shadows-shadow-sm-offset-x) var(--global-shadows-shadow-sm-offset-y) var(--global-shadows-shadow-sm-blur) var(--global-shadows-shadow-sm-spread) var(--global-shadows-shadow-sm-color)';
+/**
+ * Non-clipping outer shell. The toggle lives here (a sibling of the panel) so
+ * it can overhang the right edge without being clipped by the panel's
+ * `overflow`.
+ */
+const Shell = styled.aside `
+  position: relative;
+  flex-shrink: 0;
+  height: 100vh;
+  width: ${({ $collapsed }) => ($collapsed ? COLLAPSED_WIDTH : EXPANDED_WIDTH)};
+  transition: width 0.3s ease-in-out;
+`;
+const ToggleButton = styled.button `
+  appearance: none;
+  position: absolute;
+  top: 52px;
+  right: -16px;
+  z-index: 2;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  border: 1px solid var(--color-border-border-subtle);
+  border-radius: var(--spacing-tokens-size-in-px-radius-radius-full);
+  background-color: var(--color-background-bg-element);
+  color: var(--color-text-text-paragraph);
+  cursor: pointer;
+  box-shadow: ${SHADOW_SM};
+  transition: color 0.2s ease-in-out;
+
+  &:hover {
+    color: var(--color-text-text-clicable);
+  }
+`;
+/** Rotates the chevron smoothly between expanded (◀) and collapsed (▶). */
+const ToggleIcon = styled.span `
+  display: inline-flex;
+  transform: rotate(${({ $collapsed }) => ($collapsed ? '180deg' : '0deg')});
+  transition: transform 0.3s ease-in-out;
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+`;
+/**
+ * Composed application sidebar ("Drawer"): logo header, navigation list,
+ * credits card and user-profile footer, with a floating collapse/expand
+ * toggle. Collapse state can be controlled (`collapsed` + `onToggle`) or left
+ * uncontrolled (`defaultCollapsed`). Every colour, space and radius resolves to
+ * `@beydesign/tokens` CSS variables, so it renders correctly in light and dark.
+ *
+ * Below the mobile breakpoint there is no room for this beside a settings
+ * sub-nav — use `MobileNav`, which renders the same {@link DrawerBody} as one
+ * pane of a single overlay.
+ */
+export const Drawer = ({ navItems, activeKey, collapsed, defaultCollapsed = false, onToggle, showToggle = true, credits, creditsLoading = false, profile, profileLoading = false, logo, className, style, testId, }) => {
+    const isControlled = collapsed !== undefined;
+    const [internalCollapsed, setInternalCollapsed] = useState(defaultCollapsed);
+    const isCollapsed = isControlled ? collapsed : internalCollapsed;
+    const drawerSize = isCollapsed ? DrawerSize.Collapsed : DrawerSize.Expanded;
+    const handleToggle = () => {
+        const next = !isCollapsed;
+        if (!isControlled)
+            setInternalCollapsed(next);
+        onToggle?.(next);
+    };
+    return (_jsxs(Shell, { "$collapsed": isCollapsed, className: className, style: style, "data-testid": testId, children: [_jsx(NavPanel, { children: _jsx(DrawerBody, { navItems: navItems, activeKey: activeKey, size: drawerSize, credits: credits, creditsLoading: creditsLoading, profile: profile, profileLoading: profileLoading, logo: logo }) }), showToggle && (_jsx(ToggleButton, { type: "button", onClick: handleToggle, "aria-label": isCollapsed ? 'Expand sidebar' : 'Collapse sidebar', children: _jsx(ToggleIcon, { "$collapsed": isCollapsed, children: getIconComponent('CaretLeft', { size: 16, weight: 'bold' }) }) }))] }));
+};

package/dist/stories/{Drawer → Navigation/Drawer}/Drawer.stories.js

@@ -17,7 +17,7 @@ const navItems = [
     { key: 'developers', text: 'Developers', icon: 'BracketsCurly' },
 ];
 const meta = {
-    title: 'Design System/Components/Drawer/Drawer',
+    title: 'Design System/Components/Navigation/Drawer',
     component: Drawer,
     parameters: {
         layout: 'fullscreen',

package/dist/stories/Navigation/Drawer/DrawerBody.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { DrawerBodyProps } from './types';
+/**
+ * The Drawer's content — logo header, navigation list, credits card and profile
+ * footer — without any panel chrome. `Drawer` wraps it in a `NavPanel` beside a
+ * collapse toggle; `MobileNav` renders the very same body as the root pane of
+ * its overlay, which is why the two never drift apart.
+ */
+export declare const DrawerBody: React.FC<DrawerBodyProps>;

package/dist/stories/Navigation/Drawer/DrawerBody.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import styled from '@emotion/styled';
+import { DrawerNavItemHierarchy, DrawerNavItemState, DrawerSize, } from './types';
+import { DrawerNavItem } from './DrawerNavItem';
+import { DrawerCreditsCard } from './DrawerCreditsCard';
+import { DrawerCreditsCardSkeleton } from './DrawerCreditsCardSkeleton';
+import { DrawerProfile } from './DrawerProfile';
+import { DrawerProfileSkeleton } from './DrawerProfileSkeleton';
+import { Logo, LogoVariant } from '../../UI';
+const LogoHeader = styled.div `
+  display: flex;
+  align-items: center;
+  justify-content: ${({ $collapsed }) => $collapsed ? 'center' : 'flex-start'};
+  height: 38px;
+  min-height: 38px;
+  margin-bottom: 40px;
+`;
+const Nav = styled.nav `
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  justify-content: space-between;
+  gap: var(--spacing-tokens-size-in-px-spacing-spacing-2xl, 24px);
+`;
+const NavTop = styled.div `
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-tokens-size-in-px-spacing-spacing-lg, 12px);
+`;
+const Footer = styled.div `
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-tokens-size-in-px-spacing-spacing-2xl, 24px);
+`;
+const FooterSlot = styled.div `
+  display: flex;
+  justify-content: center;
+`;
+const resolveState = (item, activeKey) => {
+    if (item.state)
+        return item.state;
+    if (item.disabled)
+        return DrawerNavItemState.Disabled;
+    const key = item.key ?? item.text;
+    if (activeKey !== undefined && key === activeKey) {
+        return DrawerNavItemState.Active;
+    }
+    return DrawerNavItemState.Inactive;
+};
+/**
+ * The Drawer's content — logo header, navigation list, credits card and profile
+ * footer — without any panel chrome. `Drawer` wraps it in a `NavPanel` beside a
+ * collapse toggle; `MobileNav` renders the very same body as the root pane of
+ * its overlay, which is why the two never drift apart.
+ */
+export const DrawerBody = ({ navItems, activeKey, size = DrawerSize.Expanded, credits, creditsLoading = false, profile, profileLoading = false, logo, onSubNavOpen, }) => {
+    const isCollapsed = size === DrawerSize.Collapsed;
+    const handleItemClick = (item) => {
+        if (item.disabled)
+            return;
+        if (item.subNav && onSubNavOpen) {
+            onSubNavOpen(item);
+            return;
+        }
+        if (item.link) {
+            window.location.href = item.link;
+        }
+        else {
+            item.onClick?.();
+        }
+    };
+    return (_jsxs(_Fragment, { children: [_jsx(LogoHeader, { "$collapsed": isCollapsed, children: _jsx(Logo, { variant: isCollapsed ? LogoVariant.Icon : LogoVariant.Horizontal, color: logo?.color ?? 'var(--color-foreground-fg-brand-logo)', gradient: logo?.gradient, svgUrl: logo?.svgUrl }) }), _jsxs(Nav, { children: [_jsx(NavTop, { children: navItems.map((item) => (_jsx(DrawerNavItem, { text: item.text, icon: item.icon, state: resolveState(item, activeKey), size: size, hierarchy: item.hierarchy ?? DrawerNavItemHierarchy.First, showBadge: item.showBadge, badgeText: item.badgeText, showSubNavCaret: Boolean(item.subNav && onSubNavOpen), onClick: () => handleItemClick(item) }, item.key ?? item.text))) }), (credits || creditsLoading || profile || profileLoading) && (_jsxs(Footer, { children: [(credits || creditsLoading) && (_jsx(FooterSlot, { children: creditsLoading ? (_jsx(DrawerCreditsCardSkeleton, { size: size })) : (_jsx(DrawerCreditsCard, { ...credits, size: size })) })), (profile || profileLoading) && (_jsx(FooterSlot, { children: profileLoading ? (_jsx(DrawerProfileSkeleton, { size: size })) : (profile && _jsx(DrawerProfile, { ...profile, size: size })) }))] }))] })] }));
+};

package/dist/stories/{Drawer → Navigation/Drawer}/DrawerCreditsCard.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import styled from '@emotion/styled';
 import { DrawerSize } from './types';
-import { Typography, TypographySize, TypographyWeight } from '../Typography';
-import { Popover, ProgressIndicator, ProgressIndicatorMode } from '../UI';
-import { getIconComponent } from '../../utils';
+import { Typography, TypographySize, TypographyWeight } from '../../Typography';
+import { Popover, ProgressIndicator, ProgressIndicatorMode } from '../../UI';
+import { getIconComponent } from '../../../utils';
 import { GemIcon } from './DrawerIcons';
 const DEFAULT_INFO_LINES = [
     'Managed Agents 1 Min = 100 Credits',

package/dist/stories/{Drawer → Navigation/Drawer}/DrawerCreditsCard.stories.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { DrawerCreditsCard } from './DrawerCreditsCard';
 import { DrawerSize } from './types';
 const meta = {
-    title: 'Design System/Components/Drawer/DrawerCreditsCard',
+    title: 'Design System/Components/Navigation/DrawerCreditsCard',
     component: DrawerCreditsCard,
     parameters: {
         layout: 'centered',

package/dist/stories/{Drawer → Navigation/Drawer}/DrawerCreditsCardSkeleton.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import styled from '@emotion/styled';
-import { SkeletonLoader } from '../UI';
+import { SkeletonLoader } from '../../UI';
 import { DrawerSize } from './types';
 /** Mirrors {@link DrawerCreditsCard}'s Card so the skeleton snaps in place. */
 const Card = styled.div `

package/dist/stories/{Drawer → Navigation/Drawer}/DrawerCreditsCardSkeleton.stories.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { DrawerCreditsCardSkeleton } from './DrawerCreditsCardSkeleton';
 import { DrawerSize } from './types';
 const meta = {
-    title: 'Design System/Components/Drawer/DrawerCreditsCardSkeleton',
+    title: 'Design System/Components/Navigation/DrawerCreditsCardSkeleton',
     component: DrawerCreditsCardSkeleton,
     parameters: {
         layout: 'centered',

package/dist/stories/{Drawer → Navigation/Drawer}/DrawerNavItem.d.ts

@@ -3,6 +3,6 @@ import { DrawerNavItemProps } from './types';
 /**
  * A single navigation row for the {@link Drawer}. Supports active / inactive /
  * hover / disabled states, first / secondary hierarchy and expanded / collapsed
- * sizes. All colours resolve to theme tokens, so it adapts to light and dark.
+ * sizes — a top-level configuration of the shared {@link NavRow}.
  */
 export declare const DrawerNavItem: React.FC<DrawerNavItemProps>;

package/dist/stories/Navigation/Drawer/DrawerNavItem.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import styled from '@emotion/styled';
+import { DrawerNavItemState, DrawerNavItemHierarchy, DrawerSize, } from './types';
+import { NavRow } from '../internal';
+import { TypographySize, TypographyWeight } from '../../Typography';
+import { getIconComponent } from '../../../utils';
+const FIRST_PADDING = 'var(--spacing-tokens-size-in-px-spacing-spacing-md, 8px)';
+const SECONDARY_PADDING = 'var(--spacing-tokens-size-in-px-spacing-spacing-xs, 4px) var(--spacing-tokens-size-in-px-spacing-spacing-md, 8px)';
+const Caret = styled.span `
+  display: inline-flex;
+  flex-shrink: 0;
+  color: inherit;
+`;
+/**
+ * A single navigation row for the {@link Drawer}. Supports active / inactive /
+ * hover / disabled states, first / secondary hierarchy and expanded / collapsed
+ * sizes — a top-level configuration of the shared {@link NavRow}.
+ */
+export const DrawerNavItem = ({ text, icon, state = DrawerNavItemState.Inactive, size = DrawerSize.Expanded, hierarchy = DrawerNavItemHierarchy.First, showBadge = false, badgeText = 'Coming Soon', showSubNavCaret = false, onClick, className, style, testId, }) => {
+    const isSecondary = hierarchy === DrawerNavItemHierarchy.Secondary;
+    return (_jsx(NavRow, { text: text, icon: icon, state: state, collapsed: size === DrawerSize.Collapsed, iconSize: 20, typographySize: isSecondary ? TypographySize.TextXS : TypographySize.TextS, typographyWeight: isSecondary ? TypographyWeight.Medium : TypographyWeight.SemiBold, padding: isSecondary ? SECONDARY_PADDING : FIRST_PADDING, showBadge: showBadge, badgeText: badgeText, trailing: showSubNavCaret ? (_jsx(Caret, { children: getIconComponent('CaretRight', { size: 16 }) })) : undefined, onClick: onClick, className: className, style: style, testId: testId }));
+};

package/dist/stories/{Drawer → Navigation/Drawer}/DrawerNavItem.stories.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { DrawerNavItem } from './DrawerNavItem';
 import { DrawerNavItemState, DrawerNavItemHierarchy, DrawerSize, } from './types';
 const meta = {
-    title: 'Design System/Components/Drawer/DrawerNavItem',
+    title: 'Design System/Components/Navigation/DrawerNavItem',
     component: DrawerNavItem,
     parameters: {
         layout: 'centered',

package/dist/stories/{Drawer → Navigation/Drawer}/DrawerProfile.js

@@ -2,9 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useEffect, useRef, useState } from 'react';
 import styled from '@emotion/styled';
 import { DrawerSize } from './types';
-import { Avatar, AvatarSize, AvatarStyle } from '../UI';
-import { Typography, TypographySize, TypographyWeight } from '../Typography';
-import { getIconComponent } from '../../utils';
+import { Avatar, AvatarSize, AvatarStyle } from '../../UI';
+import { Typography, TypographySize, TypographyWeight } from '../../Typography';
+import { getIconComponent } from '../../../utils';
 const Container = styled.div `
   display: flex;
   flex-direction: column;

package/dist/stories/{Drawer → Navigation/Drawer}/DrawerProfile.stories.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { DrawerProfile } from './DrawerProfile';
 import { DrawerSize } from './types';
 const meta = {
-    title: 'Design System/Components/Drawer/DrawerProfile',
+    title: 'Design System/Components/Navigation/DrawerProfile',
     component: DrawerProfile,
     parameters: {
         layout: 'centered',

package/dist/stories/{Drawer → Navigation/Drawer}/DrawerProfileSkeleton.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import styled from '@emotion/styled';
-import { SkeletonLoader } from '../UI';
+import { SkeletonLoader } from '../../UI';
 import { DrawerSize } from './types';
 /**
  * Mirrors {@link DrawerProfile}'s clickable Row so the skeleton snaps in place:

package/dist/stories/{Drawer → Navigation/Drawer}/DrawerProfileSkeleton.stories.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { DrawerProfileSkeleton } from './DrawerProfileSkeleton';
 import { DrawerSize } from './types';
 const meta = {
-    title: 'Design System/Components/Drawer/DrawerProfileSkeleton',
+    title: 'Design System/Components/Navigation/DrawerProfileSkeleton',
     component: DrawerProfileSkeleton,
     parameters: {
         layout: 'centered',

package/dist/stories/{Drawer → Navigation/Drawer}/index.d.ts

@@ -1,4 +1,5 @@
 export * from './Drawer';
+export * from './DrawerBody';
 export * from './DrawerNavItem';
 export * from './DrawerCreditsCard';
 export * from './DrawerCreditsCardSkeleton';

package/dist/stories/{Drawer → Navigation/Drawer}/index.js

@@ -1,4 +1,5 @@
 export * from './Drawer';
+export * from './DrawerBody';
 export * from './DrawerNavItem';
 export * from './DrawerCreditsCard';
 export * from './DrawerCreditsCardSkeleton';

package/dist/stories/{Drawer → Navigation/Drawer}/types.d.ts

@@ -1,31 +1,13 @@
 import { CSSProperties } from 'react';
-import { IconName } from '../../utils';
+import { IconName } from '../../../utils';
+import type { NavItemHierarchy, NavItemState, NavPanelSize, SubNavConfig } from '../internal/types';
 /**
- * Expanded / collapsed size shared across the Drawer and its sub-components.
+ * The canonical declarations live in `../internal/types` so that the shared
+ * `NavRow` and `NavPanel` primitives can consume them without depending on the
+ * Drawer. They are re-exported here under their established public names.
+ * (`SubNavConfig` and friends are re-exported from `../SubNav`, their own home.)
  */
-export declare enum DrawerSize {
-    Expanded = "Expanded",
-    Collapsed = "Collapsed"
-}
-/**
- * Visual state of a single navigation item.
- * `Hover` is mostly useful for documentation/Storybook — at runtime an
- * `Inactive` item also picks up the hover styling on real pointer hover.
- */
-export declare enum DrawerNavItemState {
-    Active = "Active",
-    Inactive = "Inactive",
-    Hover = "Hover",
-    Disabled = "Disabled"
-}
-/**
- * Hierarchy of a navigation item. `First` is a top-level entry (36px row),
- * `Secondary` is a nested sub-item (28px row, lighter weight).
- */
-export declare enum DrawerNavItemHierarchy {
-    First = "First",
-    Secondary = "Secondary"
-}
+export { NavItemState as DrawerNavItemState, NavPanelSize as DrawerSize, NavItemHierarchy as DrawerNavItemHierarchy, } from '../internal/types';
 /**
  * Props for the standalone {@link DrawerNavItem} component.
  */
@@ -35,15 +17,20 @@ export interface DrawerNavItemProps {
     /** Phosphor icon name rendered to the left of the label. */
     icon: IconName;
     /** Visual state of the item. */
-    state?: DrawerNavItemState;
+    state?: NavItemState;
     /** Expanded (icon + label) or Collapsed (icon only). */
-    size?: DrawerSize;
+    size?: NavPanelSize;
     /** Top-level (`First`) or nested (`Secondary`) item. */
-    hierarchy?: DrawerNavItemHierarchy;
+    hierarchy?: NavItemHierarchy;
     /** Show a trailing badge (e.g. "Coming Soon"). Hidden when collapsed. */
     showBadge?: boolean;
     /** Text for the trailing badge. */
     badgeText?: string;
+    /**
+     * Render a trailing caret marking this item as opening a sub-navigation.
+     * Hidden when collapsed.
+     */
+    showSubNavCaret?: boolean;
     /** Click handler. Not fired when the item is disabled. */
     onClick?: () => void;
     className?: string;
@@ -56,7 +43,7 @@ export interface DrawerNavItemProps {
  */
 export interface DrawerCreditsCardProps {
     /** Expanded (full card) or Collapsed (icon only, details in a popover). */
-    size?: DrawerSize;
+    size?: NavPanelSize;
     /** Credits consumed so far. */
     usedCredits?: number;
     /** Total credits available in the plan. */
@@ -82,7 +69,7 @@ export interface DrawerCreditsCardProps {
  */
 export interface DrawerCreditsCardSkeletonProps {
     /** Expanded (full card) or Collapsed (icon-only box). */
-    size?: DrawerSize;
+    size?: NavPanelSize;
     className?: string;
     style?: CSSProperties;
     testId?: string;
@@ -103,7 +90,7 @@ export interface DrawerProfileMenuItem {
  */
 export interface DrawerProfileProps {
     /** Expanded (avatar + text) or Collapsed (avatar only). */
-    size?: DrawerSize;
+    size?: NavPanelSize;
     /** Display name. */
     name: string;
     /** Secondary line, usually the email. */
@@ -129,7 +116,7 @@ export interface DrawerProfileProps {
  */
 export interface DrawerProfileSkeletonProps {
     /** Expanded (avatar + text lines) or Collapsed (avatar circle only). */
-    size?: DrawerSize;
+    size?: NavPanelSize;
     className?: string;
     style?: CSSProperties;
     testId?: string;
@@ -142,15 +129,24 @@ export interface DrawerNavItemConfig {
     key?: string;
     text: string;
     icon: IconName;
-    hierarchy?: DrawerNavItemHierarchy;
+    hierarchy?: NavItemHierarchy;
     /** Force a state. When omitted it is derived from `activeKey` / `disabled`. */
-    state?: DrawerNavItemState;
+    state?: NavItemState;
     disabled?: boolean;
     showBadge?: boolean;
     badgeText?: string;
     /** When set, clicking navigates to this URL. */
     link?: string;
     onClick?: () => void;
+    /**
+     * A secondary navigation this item drills into (e.g. the Settings sub-nav).
+     *
+     * On desktop the item navigates as usual and the sub-nav is rendered as its
+     * own panel beside the Drawer (`SubNav`). Where there is only room for
+     * one panel — `MobileNav` — the item instead grows a trailing caret and
+     * pushes this config as a second pane.
+     */
+    subNav?: SubNavConfig;
 }
 /**
  * Props for the composed {@link Drawer} component.
@@ -186,3 +182,17 @@ export interface DrawerProps {
     style?: CSSProperties;
     testId?: string;
 }
+/**
+ * Props for the {@link DrawerBody} — the Drawer's content without any panel
+ * chrome, so it can be dropped into the `MobileNav` overlay as its root pane.
+ */
+export interface DrawerBodyProps extends Pick<DrawerProps, 'navItems' | 'activeKey' | 'credits' | 'creditsLoading' | 'profile' | 'profileLoading' | 'logo'> {
+    /** Expanded (icon + label) or Collapsed (icon only). */
+    size?: NavPanelSize;
+    /**
+     * When provided, items carrying a `subNav` render a trailing caret and call
+     * this instead of navigating. The desktop `Drawer` omits it, so those items
+     * behave like any other nav entry.
+     */
+    onSubNavOpen?: (item: DrawerNavItemConfig) => void;
+}

package/dist/stories/Navigation/Drawer/types.js

@@ -0,0 +1,7 @@
+/**
+ * The canonical declarations live in `../internal/types` so that the shared
+ * `NavRow` and `NavPanel` primitives can consume them without depending on the
+ * Drawer. They are re-exported here under their established public names.
+ * (`SubNavConfig` and friends are re-exported from `../SubNav`, their own home.)
+ */
+export { NavItemState as DrawerNavItemState, NavPanelSize as DrawerSize, NavItemHierarchy as DrawerNavItemHierarchy, } from '../internal/types';

package/dist/stories/Navigation/MobileNav.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import { MobileNavProps } from './types';
+/**
+ * The single navigation panel for mobile, where there is no room for the
+ * `Drawer` and a settings sub-nav side by side. It slides in over the page and
+ * holds both as pushable panes: the root pane is the very same {@link DrawerBody}
+ * the desktop `Drawer` renders, and any nav item carrying a `subNav` grows a
+ * trailing caret that pushes that config as a {@link SubNavBody} pane with
+ * a back button. Nothing is duplicated — only the chrome around the bodies
+ * changes between desktop and mobile.
+ *
+ * `MobileNavBar` renders this behind its hamburger; use it directly if the app
+ * already has its own mobile header.
+ */
+export declare const MobileNav: React.FC<MobileNavProps>;

package/dist/stories/Navigation/MobileNav.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo, useState } from 'react';
+import { Drawer as MuiDrawer } from '@mui/material';
+import styled from '@emotion/styled';
+import { keyframes } from '@emotion/react';
+import { DrawerBody } from './Drawer';
+import { SubNavBody } from './SubNav';
+import { NavPanel } from './internal';
+const DEFAULT_WIDTH = '315px';
+const slideForward = keyframes `
+  from { transform: translateX(16px); opacity: 0; }
+  to { transform: translateX(0); opacity: 1; }
+`;
+const slideBack = keyframes `
+  from { transform: translateX(-16px); opacity: 0; }
+  to { transform: translateX(0); opacity: 1; }
+`;
+/**
+ * Hosts one pane at a time, growing to fill the panel so the body's own flex
+ * chain (logo header, then a nav that pushes the footer down) still works.
+ *
+ * Keep the default `min-height: auto`: on a short viewport the pane must refuse
+ * to shrink below its content, otherwise the panel scrolls to a height that
+ * excludes the profile footer and clips it.
+ */
+const Pane = styled.div `
+  display: flex;
+  flex-direction: column;
+  flex: 1 0 auto;
+  animation: ${({ $forward }) => ($forward ? slideForward : slideBack)} 0.25s
+    ease-out;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+`;
+/**
+ * The single navigation panel for mobile, where there is no room for the
+ * `Drawer` and a settings sub-nav side by side. It slides in over the page and
+ * holds both as pushable panes: the root pane is the very same {@link DrawerBody}
+ * the desktop `Drawer` renders, and any nav item carrying a `subNav` grows a
+ * trailing caret that pushes that config as a {@link SubNavBody} pane with
+ * a back button. Nothing is duplicated — only the chrome around the bodies
+ * changes between desktop and mobile.
+ *
+ * `MobileNavBar` renders this behind its hamburger; use it directly if the app
+ * already has its own mobile header.
+ */
+export const MobileNav = ({ open, onOpenChange, navItems, activeKey, credits, creditsLoading, profile, profileLoading, logo, width = DEFAULT_WIDTH, className, style, testId, }) => {
+    const [subNav, setSubNav] = useState(null);
+    const close = useCallback(() => onOpenChange(false), [onOpenChange]);
+    /** Navigating away should dismiss the overlay, whichever pane it happened in. */
+    const closingNavItems = useMemo(() => navItems.map((item) => ({
+        ...item,
+        onClick: () => {
+            item.onClick?.();
+            close();
+        },
+    })), [navItems, close]);
+    const closingSubNav = useMemo(() => {
+        if (!subNav)
+            return null;
+        return {
+            ...subNav,
+            sections: subNav.sections.map((section) => ({
+                ...section,
+                items: section.items.map((item) => ({
+                    ...item,
+                    onClick: () => {
+                        item.onClick?.();
+                        close();
+                    },
+                })),
+            })),
+        };
+    }, [subNav, close]);
+    const handleSubNavOpen = (item) => {
+        if (item.subNav)
+            setSubNav(item.subNav);
+    };
+    return (_jsx(MuiDrawer, { anchor: "left", open: open, onClose: close, className: className, 
+        /* Reset to the root pane only once the panel is fully out of sight. */
+        SlideProps: { onExited: () => setSubNav(null) }, PaperProps: {
+            sx: {
+                width,
+                backgroundColor: 'transparent',
+                boxShadow: 'none',
+                border: 'none',
+                overflow: 'hidden',
+            },
+            style,
+        }, sx: {
+            '& .MuiBackdrop-root': {
+                backgroundColor: 'var(--color-background-bg-overlay-2)',
+            },
+        }, "data-testid": testId, children: _jsx(NavPanel, { "$borderColor": "var(--color-border-border-divider)", children: closingSubNav ? (_jsx(Pane, { "$forward": true, children: _jsx(SubNavBody, { title: closingSubNav.title, sections: closingSubNav.sections, activeKey: closingSubNav.activeKey, onBack: () => setSubNav(null) }) }, "sub-nav")) : (_jsx(Pane, { "$forward": false, children: _jsx(DrawerBody, { navItems: closingNavItems, activeKey: activeKey, credits: credits, creditsLoading: creditsLoading, profile: profile, profileLoading: profileLoading, logo: logo, onSubNavOpen: handleSubNavOpen }) }, "root")) }) }));
+};

package/dist/stories/Navigation/MobileNav.stories.d.ts

@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { MobileNav } from './MobileNav';
+/**
+ * Drives the overlay the way an app does: a trigger button, and `open` state
+ * the component reports back through `onOpenChange`.
+ */
+declare const MobileNavExample: ({ navItems, activeKey, ...rest }: Partial<React.ComponentProps<typeof MobileNav>>) => import("react").JSX.Element;
+declare const meta: Meta<typeof MobileNavExample>;
+export default meta;
+type Story = StoryObj<typeof MobileNavExample>;
+/**
+ * The root pane. "Settings" carries a `subNav`, so it renders a trailing caret
+ * and pushes instead of navigating.
+ */
+export declare const Default: Story;
+/**
+ * Without a `subNav` anywhere in `navItems` there is nothing to drill into, so
+ * no item shows a caret and the overlay is a plain single-pane nav.
+ */
+export declare const WithoutSubNav: Story;
+/**
+ * A sub-nav is not a settings-only idea — any item can declare one. Here the
+ * developer entry drills into a subset of the same sections.
+ */
+export declare const CustomSubNav: Story;