@tinybigui/react 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -2,17 +2,20 @@ import { ClassValue } from 'clsx';
 import { Theme } from '@material/material-color-utilities';
 export { Theme, argbFromHex, hexFromArgb } from '@material/material-color-utilities';
 import * as React$1 from 'react';
-import React__default, { LabelHTMLAttributes, InputHTMLAttributes, HTMLAttributes, RefObject, ReactNode } from 'react';
+import React__default, { LabelHTMLAttributes, InputHTMLAttributes, HTMLAttributes, RefObject, ReactNode, ButtonHTMLAttributes, Key as Key$2, JSX } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
-import { AriaButtonProps, AriaTextFieldProps, AriaCheckboxProps, AriaSwitchProps, AriaRadioProps, AriaRadioGroupProps } from 'react-aria';
+import { AriaButtonProps, AriaTextFieldProps, AriaCheckboxProps, AriaSwitchProps, AriaRadioProps, AriaRadioGroupProps, AriaTabProps, AriaTabPanelProps, Key as Key$1, AriaDialogProps, AriaLinkOptions, AriaProgressBarProps, AriaMenuTriggerProps, AriaMenuProps } from 'react-aria';
+import { Key, SelectionMode } from 'react-stately';
+import { MenuItemProps as MenuItemProps$1, SeparatorProps } from 'react-aria-components';
 
 /**
  * Combines and merges Tailwind CSS classes efficiently.
  *
- * This utility uses:
- * - `clsx` for conditional class joining
- * - `tailwind-merge` to properly merge/deduplicate Tailwind classes
+ * Uses `clsx` for conditional joining + extended `tailwind-merge` that is
+ * aware of MD3 typography scale utilities (`text-body-large`, etc.) so they
+ * are not incorrectly removed when merged alongside color utilities
+ * (`text-on-surface`, `text-primary`, etc.).
  *
  * @example
  * ```tsx
@@ -20,10 +23,16 @@ import { AriaButtonProps, AriaTextFieldProps, AriaCheckboxProps, AriaSwitchProps
  * // => 'px-2 py-1 bg-blue-500 text-white'
  * ```
  *
- * @example Merging conflicting classes
+ * @example Merging conflicting classes (later wins)
  * ```tsx
  * cn('px-2', 'px-4')
- * // => 'px-4' (later class wins)
+ * // => 'px-4'
+ * ```
+ *
+ * @example MD3 typography + color (both kept — no false conflict)
+ * ```tsx
+ * cn('text-body-large', 'text-on-surface')
+ * // => 'text-body-large text-on-surface'
  * ```
  */
 declare function cn(...inputs: ClassValue[]): string;
@@ -438,6 +447,258 @@ declare function pxToRem(px: number | string): string;
  */
 declare function truncateText(lines?: number): React.CSSProperties;
 
+/**
+ * MD3 Top App Bar size variants
+ *
+ * Each variant differs in height, title alignment, and type scale.
+ * - `small`: 64dp height, title left-aligned, title-large type scale
+ * - `center-aligned`: 64dp height, title centered, title-large type scale
+ * - `medium`: 112dp height, title bottom-left, headline-small type scale
+ * - `large`: 152dp height, title bottom-left, display-small type scale
+ *
+ * @see https://m3.material.io/components/top-app-bar/specs
+ */
+type AppBarVariant = "small" | "center-aligned" | "medium" | "large";
+/**
+ * Material Design 3 Top App Bar Component Props
+ *
+ * Provides a top app bar with navigation icon, title, and trailing action icon slots.
+ * Supports scroll-triggered elevation changes with both controlled and uncontrolled modes.
+ *
+ * **Usage:**
+ * - Pass existing `<IconButton>` components into `navigationIcon` and `actions` slots
+ * - No hardcoded slot components — fully composable API
+ *
+ * @example
+ * ```tsx
+ * // Small variant with navigation icon and actions
+ * <AppBar
+ *   title="Page Title"
+ *   navigationIcon={
+ *     <IconButton aria-label="Open navigation">
+ *       <MenuIcon />
+ *     </IconButton>
+ *   }
+ *   actions={
+ *     <IconButton aria-label="Search">
+ *       <SearchIcon />
+ *     </IconButton>
+ *   }
+ * />
+ *
+ * // Center-aligned with controlled scroll state
+ * <AppBar
+ *   variant="center-aligned"
+ *   title="My App"
+ *   scrolled={isScrolled}
+ *   onScrollStateChange={setIsScrolled}
+ * />
+ *
+ * // Large variant for hero/expanded layouts
+ * <AppBar
+ *   variant="large"
+ *   title="Article Title"
+ * />
+ * ```
+ */
+interface AppBarProps {
+    /**
+     * Size variant of the Top App Bar
+     * Controls height, title position, and type scale
+     * @default 'small'
+     */
+    variant?: AppBarVariant;
+    /**
+     * The title content. Accepts a string or any React node.
+     * Typography scale is automatically applied based on `variant`.
+     */
+    title: React__default.ReactNode;
+    /**
+     * Navigation icon slot (leading position, optional).
+     * Expects a React node — typically an `<IconButton>` with `aria-label`.
+     *
+     * @example
+     * ```tsx
+     * navigationIcon={
+     *   <IconButton aria-label="Open navigation menu">
+     *     <MenuIcon />
+     *   </IconButton>
+     * }
+     * ```
+     */
+    navigationIcon?: React__default.ReactNode;
+    /**
+     * Trailing action icon slots (up to 3, optional).
+     * Expects one or more React nodes — typically `<IconButton>` components.
+     *
+     * @example
+     * ```tsx
+     * actions={
+     *   <>
+     *     <IconButton aria-label="Search"><SearchIcon /></IconButton>
+     *     <IconButton aria-label="More options"><MoreIcon /></IconButton>
+     *   </>
+     * }
+     * ```
+     */
+    actions?: React__default.ReactNode;
+    /**
+     * Controlled scroll state.
+     * When provided, the component operates in controlled mode — the consumer
+     * is responsible for managing this value.
+     * When `undefined`, internal scroll detection is used (uncontrolled mode).
+     *
+     * - `false` (default): flat surface, `shadow-elevation-0`
+     * - `true`: elevated surface, `shadow-elevation-2`
+     */
+    scrolled?: boolean;
+    /**
+     * Callback fired when the scroll elevation state changes.
+     * In uncontrolled mode, this fires when the user scrolls past the threshold.
+     * In controlled mode, this is an informational callback — the consumer
+     * decides whether to update `scrolled`.
+     *
+     * @param scrolled - The new scroll state
+     */
+    onScrollStateChange?: (scrolled: boolean) => void;
+    /**
+     * Additional CSS classes to merge onto the root `<header>` element.
+     * Uses Tailwind CSS — conflicting classes are resolved by `cn()`.
+     */
+    className?: string;
+}
+/**
+ * AppBarHeadless Component Props
+ *
+ * Unstyled primitive for the Top App Bar.
+ * Renders a `<header role="banner">` and manages scroll elevation state.
+ * Use this for full visual control when the styled `AppBar` is not sufficient.
+ *
+ * @example
+ * ```tsx
+ * <AppBarHeadless
+ *   className="my-custom-appbar"
+ *   scrolled={scrolled}
+ *   onScrollStateChange={setScrolled}
+ * >
+ *   <div>My custom layout</div>
+ * </AppBarHeadless>
+ * ```
+ */
+interface AppBarHeadlessProps {
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * The content to render inside the header
+     */
+    children: React__default.ReactNode;
+    /**
+     * Controlled scroll state.
+     * When `undefined`, the component uses internal scroll detection.
+     */
+    scrolled?: boolean;
+    /**
+     * Callback fired when scroll state changes
+     */
+    onScrollStateChange?: (scrolled: boolean) => void;
+}
+
+/**
+ * Material Design 3 Top App Bar Component
+ *
+ * Provides context and actions for the current screen. Supports four size variants,
+ * a navigation icon slot, title, and trailing action icon slots. Implements
+ * scroll-triggered elevation changes per MD3 specification.
+ *
+ * **Architecture:**
+ * - Layer 3 (this file): MD3 styled, CVA variants, layout composition
+ * - Layer 2: `AppBarHeadless` — `<header role="banner">`, scroll state
+ * - Layer 1: React Aria via `<IconButton>` in consumer slots
+ *
+ * **Key Features:**
+ * - 4 MD3 variants: small, center-aligned, medium, large
+ * - Composable API: pass `<IconButton>` nodes into navigation and action slots
+ * - Scroll elevation: flat at rest → elevated on scroll (MD3 motion tokens)
+ * - Controlled and uncontrolled scroll state
+ * - WCAG 2.1 AA: `role="banner"` landmark, keyboard accessible slots
+ * - Dark mode via existing token system
+ *
+ * @example
+ * ```tsx
+ * // Small variant (default)
+ * <AppBar
+ *   title="Page Title"
+ *   navigationIcon={
+ *     <IconButton aria-label="Open navigation menu">
+ *       <MenuIcon />
+ *     </IconButton>
+ *   }
+ *   actions={
+ *     <IconButton aria-label="Search">
+ *       <SearchIcon />
+ *     </IconButton>
+ *   }
+ * />
+ *
+ * // Center-aligned with scroll elevation
+ * <AppBar
+ *   variant="center-aligned"
+ *   title="My App"
+ *   scrolled={isScrolled}
+ *   onScrollStateChange={setIsScrolled}
+ * />
+ *
+ * // Medium with expanded title area
+ * <AppBar
+ *   variant="medium"
+ *   title="Article Title"
+ *   navigationIcon={
+ *     <IconButton aria-label="Go back">
+ *       <ArrowBackIcon />
+ *     </IconButton>
+ *   }
+ * />
+ * ```
+ */
+declare const AppBar: React$1.ForwardRefExoticComponent<AppBarProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Headless AppBar Component (Layer 2)
+ *
+ * Unstyled Top App Bar primitive. Renders a `<header role="banner">` landmark
+ * and manages scroll elevation state via the `useScrollElevation` hook.
+ *
+ * Features:
+ * - Semantic `<header>` element with `role="banner"` ARIA landmark
+ * - Controlled scroll state via `scrolled` prop
+ * - Uncontrolled scroll state with internal `window` scroll detection
+ * - `onScrollStateChange` callback for both modes
+ * - Full ref forwarding to the header element
+ *
+ * Use this layer when you need full visual control beyond what the styled
+ * `AppBar` provides.
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled (auto scroll detection)
+ * <AppBarHeadless className="my-custom-appbar">
+ *   <div>My custom layout</div>
+ * </AppBarHeadless>
+ *
+ * // Controlled scroll state
+ * <AppBarHeadless
+ *   scrolled={isScrolled}
+ *   onScrollStateChange={setIsScrolled}
+ *   className="my-custom-appbar"
+ * >
+ *   <div>My custom layout</div>
+ * </AppBarHeadless>
+ * ```
+ */
+declare const AppBarHeadless: React$1.ForwardRefExoticComponent<AppBarHeadlessProps & React$1.RefAttributes<HTMLElement>>;
+
 /**
  * Material Design 3 Button Variants (CVA)
  *
@@ -447,7 +708,7 @@ declare function truncateText(lines?: number): React.CSSProperties;
 declare const buttonVariants: (props?: ({
     variant?: "text" | "filled" | "outlined" | "tonal" | "elevated" | null | undefined;
     color?: "primary" | "secondary" | "tertiary" | "error" | null | undefined;
-    size?: "large" | "medium" | "small" | null | undefined;
+    size?: "small" | "large" | "medium" | null | undefined;
     fullWidth?: boolean | null | undefined;
     disabled?: boolean | null | undefined;
     loading?: boolean | null | undefined;
@@ -653,7 +914,7 @@ declare const Button: React__default.ForwardRefExoticComponent<ButtonProps & Omi
 declare const iconButtonVariants: (props?: ({
     variant?: "filled" | "outlined" | "tonal" | "standard" | null | undefined;
     color?: "primary" | "secondary" | "tertiary" | "error" | null | undefined;
-    size?: "large" | "medium" | "small" | null | undefined;
+    size?: "small" | "large" | "medium" | null | undefined;
     selected?: boolean | null | undefined;
     isDisabled?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
@@ -885,7 +1146,7 @@ declare const IconButtonHeadless: React$1.ForwardRefExoticComponent<IconButtonHe
  * - Extended variant with variable width
  */
 declare const fabVariants: (props?: ({
-    size?: "large" | "medium" | "small" | "extended" | null | undefined;
+    size?: "small" | "large" | "medium" | "extended" | null | undefined;
     color?: "primary" | "secondary" | "tertiary" | "surface" | null | undefined;
     isDisabled?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
@@ -1833,4 +2094,2828 @@ declare const RadioHeadless: React$1.ForwardRefExoticComponent<RadioHeadlessProp
  */
 declare const RadioGroupHeadless: React$1.ForwardRefExoticComponent<RadioGroupHeadlessProps & React$1.RefAttributes<HTMLDivElement>>;
 
-export { Button, type ButtonColor, type ButtonProps, type ButtonSize, type ButtonVariant, Checkbox, type CheckboxProps, FAB, type FABColor, FABHeadless, type FABHeadlessProps, type FABProps, type FABSize, IconButton, type IconButtonColor, IconButtonHeadless, type IconButtonHeadlessProps, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type MD3ColorRole, type MD3TypographyScale, type MD3TypographySize, type MD3TypographyStyle, Radio, RadioGroup, RadioGroupHeadless, type RadioGroupHeadlessProps, type RadioGroupProps, RadioHeadless, type RadioHeadlessProps, type RadioProps, STATE_LAYER_OPACITY, Switch, type SwitchProps, TYPOGRAPHY_ELEMENT_MAP, TYPOGRAPHY_USAGE, TextField, type TextFieldProps, type TextFieldSize, type TextFieldVariant, type TypographyProperty, type TypographyStyleObject, applyStateLayer, cn, generateMD3Theme, getColorValue, getFontFamily, getMD3Color, getResponsiveTypography, getTypographyClassName, getTypographyForElement, getTypographyStyle, getTypographyToken, hexToRgb, pxToRem, remToPx, rgbToHex, truncateText, withOpacity };
+/**
+ * Tab variant following MD3 spec
+ * - primary: active indicator uses bg-primary; active text: text-primary
+ * - secondary: active indicator uses bg-on-surface-variant; active text: text-on-surface
+ */
+type TabVariant = "primary" | "secondary";
+/**
+ * Tab layout mode
+ * - fixed: tabs fill available width equally
+ * - scrollable: tabs overflow horizontally with no wrapping
+ */
+type TabLayout = "fixed" | "scrollable";
+/**
+ * Badge value for a tab item
+ * - number: displays count (999+ for values > 999, hidden for 0)
+ * - true: displays a dot indicator
+ * - false/undefined: no badge
+ */
+type TabBadgeValue = number | boolean;
+/**
+ * Material Design 3 Tabs Wrapper Props
+ *
+ * The Tabs component manages shared state (selected key) and provides
+ * context to TabList and TabPanel children.
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled
+ * <Tabs defaultSelectedKey="tab1" aria-label="Settings tabs">
+ *   <TabList>
+ *     <Tab id="tab1" label="General" />
+ *     <Tab id="tab2" label="Privacy" />
+ *   </TabList>
+ *   <TabPanel id="tab1">General content</TabPanel>
+ *   <TabPanel id="tab2">Privacy content</TabPanel>
+ * </Tabs>
+ *
+ * // Controlled
+ * <Tabs selectedKey={selected} onSelectionChange={setSelected} aria-label="App tabs">
+ *   <TabList variant="secondary">
+ *     <Tab id="a" label="Overview" />
+ *     <Tab id="b" label="Details" />
+ *   </TabList>
+ *   <TabPanel id="a">Overview content</TabPanel>
+ *   <TabPanel id="b">Details content</TabPanel>
+ * </Tabs>
+ * ```
+ */
+interface TabsProps {
+    /**
+     * Controlled selected tab key
+     */
+    selectedKey?: Key;
+    /**
+     * Default selected key for uncontrolled usage
+     */
+    defaultSelectedKey?: Key;
+    /**
+     * Callback when selected tab changes
+     */
+    onSelectionChange?: (key: Key) => void;
+    /**
+     * Tab variant — affects active indicator and label color
+     * @default 'primary'
+     */
+    variant?: TabVariant;
+    /**
+     * Layout mode
+     * @default 'fixed'
+     */
+    layout?: TabLayout;
+    /**
+     * TabList and TabPanel children
+     */
+    children: React__default.ReactNode;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Accessible label for the tabs widget
+     */
+    "aria-label"?: string;
+    /**
+     * Accessible labelledby reference
+     */
+    "aria-labelledby"?: string;
+}
+/**
+ * Material Design 3 TabList Props
+ *
+ * Renders the tab row container with the active indicator.
+ * Must be a child of Tabs.
+ *
+ * @example
+ * ```tsx
+ * <TabList>
+ *   <Tab id="overview" label="Overview" />
+ *   <Tab id="activity" label="Activity" icon={<ActivityIcon />} />
+ * </TabList>
+ * ```
+ */
+interface TabListProps {
+    /**
+     * Tab child elements
+     */
+    children: React__default.ReactNode;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+/**
+ * Material Design 3 Tab Props
+ *
+ * Represents a single tab item inside a TabList.
+ * Supports icon-only, label-only, and icon+label content modes.
+ *
+ * @example
+ * ```tsx
+ * // Label only
+ * <Tab id="overview" label="Overview" />
+ *
+ * // Icon + label
+ * <Tab id="media" icon={<PhotoIcon />} label="Media" />
+ *
+ * // With badge
+ * <Tab id="messages" label="Messages" badge={5} />
+ *
+ * // Dot badge
+ * <Tab id="notifications" label="Notifications" badge={true} />
+ *
+ * // Disabled
+ * <Tab id="archived" label="Archived" isDisabled />
+ * ```
+ */
+interface TabProps {
+    /**
+     * Unique key identifying this tab (used to match with TabPanel)
+     */
+    id: Key;
+    /**
+     * Icon element displayed above or instead of the label
+     * Should be 24x24dp per MD3 Tabs spec
+     */
+    icon?: React__default.ReactNode;
+    /**
+     * Text label for the tab
+     */
+    label?: string;
+    /**
+     * Badge value
+     * - number: shows count (999+ for values > 999, hidden for 0)
+     * - true: shows dot indicator
+     */
+    badge?: TabBadgeValue;
+    /**
+     * Disables the tab (not focusable, not selectable)
+     * @default false
+     */
+    isDisabled?: boolean;
+    /**
+     * Disables ripple effect
+     * @default false
+     */
+    disableRipple?: boolean;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+/**
+ * Material Design 3 TabPanel Props
+ *
+ * Content area associated with a tab. Only the selected tab's panel is visible.
+ * The `id` must match the corresponding Tab's `id`.
+ *
+ * @example
+ * ```tsx
+ * <TabPanel id="overview">
+ *   <p>Overview content here</p>
+ * </TabPanel>
+ * ```
+ */
+interface TabPanelProps {
+    /**
+     * Key matching the associated Tab's `id`
+     */
+    id: Key;
+    /**
+     * Panel content
+     */
+    children: React__default.ReactNode;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+/**
+ * Internal tab item representation for React Aria collection
+ */
+interface TabItem {
+    key: Key;
+    id: Key;
+    label?: string;
+    icon?: React__default.ReactNode;
+    badge?: TabBadgeValue;
+    isDisabled?: boolean;
+    textValue?: string;
+}
+/**
+ * Props for HeadlessTab
+ * Extends AriaTabProps for full React Aria accessibility support
+ */
+interface HeadlessTabProps extends AriaTabProps {
+    /**
+     * Tab item from the collection
+     */
+    item: TabItem;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Mouse down handler (for ripple effect)
+     */
+    onMouseDown?: (e: React__default.MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * Render function receiving interaction states
+     */
+    children?: (state: {
+        isSelected: boolean;
+        isDisabled: boolean;
+        isFocusVisible: boolean;
+        isPressed: boolean;
+    }) => React__default.ReactNode;
+}
+/**
+ * Props for HeadlessTabPanel
+ * Extends AriaTabPanelProps for full React Aria accessibility support
+ */
+interface HeadlessTabPanelProps extends AriaTabPanelProps {
+    /**
+     * Panel content
+     */
+    children: React__default.ReactNode;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+
+/**
+ * Material Design 3 Tabs Component (Layer 3: Styled Wrapper)
+ *
+ * The Tabs component manages shared selected state via useTabListState (React Aria + Stately),
+ * and provides this state to all child TabList, Tab, and TabPanel components via context.
+ *
+ * Architecture:
+ * 1. Extracts Tab metadata from children to build the React Aria collection
+ * 2. Creates tab list state with useTabListState
+ * 3. Provides React Aria state via HeadlessTabsContext
+ * 4. Provides MD3 styling context via TabsContext
+ *
+ * Features:
+ * - ✅ Controlled and uncontrolled selection
+ * - ✅ Primary and secondary variants
+ * - ✅ Fixed and scrollable layouts
+ * - ✅ Full keyboard navigation (via React Aria)
+ * - ✅ WCAG 2.1 AA compliant
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled
+ * <Tabs defaultSelectedKey="tab1" aria-label="Settings">
+ *   <TabList>
+ *     <Tab id="tab1" label="General" />
+ *     <Tab id="tab2" label="Privacy" />
+ *   </TabList>
+ *   <TabPanel id="tab1">General content</TabPanel>
+ *   <TabPanel id="tab2">Privacy content</TabPanel>
+ * </Tabs>
+ *
+ * // Controlled
+ * <Tabs selectedKey={tab} onSelectionChange={setTab} aria-label="App">
+ *   <TabList variant="secondary">
+ *     <Tab id="overview" label="Overview" />
+ *     <Tab id="details" label="Details" />
+ *   </TabList>
+ *   <TabPanel id="overview">Overview</TabPanel>
+ *   <TabPanel id="details">Details</TabPanel>
+ * </Tabs>
+ * ```
+ */
+declare const Tabs: React__default.ForwardRefExoticComponent<TabsProps & React__default.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Material Design 3 TabList Component (Layer 3: Styled)
+ *
+ * Renders the tab row container with an animated active indicator.
+ * Uses React Aria's useTabList for role="tablist", keyboard navigation,
+ * and accessibility attributes.
+ *
+ * The active indicator slides to the selected tab using CSS transitions
+ * with MD3 motion tokens (medium2 duration, emphasized easing).
+ *
+ * MD3 Specifications:
+ * - Container background: bg-surface
+ * - Container height: 48dp
+ * - Bottom border: 1dp, outline-variant color
+ * - Fixed layout: tabs fill width equally
+ * - Scrollable layout: overflow-x, no wrapping
+ *
+ * @example
+ * ```tsx
+ * <Tabs aria-label="Settings" defaultSelectedKey="general">
+ *   <TabList>
+ *     <Tab id="general" label="General" />
+ *     <Tab id="privacy" label="Privacy" />
+ *   </TabList>
+ *   ...
+ * </Tabs>
+ * ```
+ */
+declare const TabList: React__default.ForwardRefExoticComponent<TabListProps & React__default.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Material Design 3 Tab Component (Layer 3: Styled)
+ *
+ * Renders a single tab item inside a TabList.
+ * Supports three content modes: icon-only, label-only, icon + label (stacked).
+ *
+ * Features:
+ * - ✅ Icon-only, label-only, icon + label (stacked) content modes
+ * - ✅ Ripple effect (Material Design)
+ * - ✅ MD3 state layers (hover 8%, pressed 12%)
+ * - ✅ Badge support (numeric, dot, 999+)
+ * - ✅ Disabled state (opacity-38, not focusable)
+ * - ✅ Full keyboard accessibility (via React Aria)
+ * - ✅ Primary/secondary variant colors
+ *
+ * MD3 Specifications:
+ * - Minimum height: 48dp
+ * - Minimum width: 90dp
+ * - Typography: Title Small (14px, weight 500, tracking 0.1px)
+ * - Icon: 24x24dp
+ * - Active indicator: 3dp primary / 2dp secondary
+ * - State layers: 8% hover, 12% pressed/focus
+ *
+ * @example
+ * ```tsx
+ * // Label only
+ * <Tab id="overview" label="Overview" />
+ *
+ * // Icon + label
+ * <Tab id="media" icon={<PhotoIcon />} label="Media" />
+ *
+ * // With numeric badge
+ * <Tab id="messages" label="Messages" badge={5} />
+ *
+ * // With dot badge
+ * <Tab id="notifications" label="Notifications" badge={true} />
+ *
+ * // Disabled
+ * <Tab id="archived" label="Archived" isDisabled />
+ * ```
+ */
+declare const Tab: React__default.ForwardRefExoticComponent<TabProps & React__default.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Material Design 3 TabPanel Component (Layer 3: Styled)
+ *
+ * Renders the content area associated with a tab.
+ * Only the selected tab's panel content is shown.
+ *
+ * Provides full accessibility:
+ * - role="tabpanel"
+ * - aria-labelledby (pointing to the associated tab)
+ * - Focus management for panels without focusable children (tabIndex=-1)
+ *
+ * MD3 Specifications:
+ * - No specific container styling mandated by MD3 for the panel itself
+ * - The panel should be keyboard-reachable per WCAG requirements
+ *
+ * @example
+ * ```tsx
+ * <TabPanel id="overview">
+ *   <h2>Overview</h2>
+ *   <p>Content here...</p>
+ * </TabPanel>
+ * ```
+ */
+declare const TabPanel: React__default.ForwardRefExoticComponent<TabPanelProps & React__default.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Props for the HeadlessTabList container.
+ * State is injected from HeadlessTabsContext (created in Tabs wrapper).
+ */
+interface HeadlessTabListContainerProps {
+    /** Children are Tab elements */
+    children: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * Headless TabList Component (Layer 2)
+ *
+ * Unstyled tab list container. Applies useTabList to the container element
+ * which wires up role="tablist", aria-label, and keyboard navigation.
+ * State must be provided via HeadlessTabsContext (from the Tabs wrapper).
+ *
+ * @example
+ * ```tsx
+ * // Advanced usage via headless primitives
+ * // State is provided by the Tabs wrapper above in the tree
+ * <HeadlessTabList className="my-tablist">
+ *   {items.map(item => <HeadlessTab key={item.key} item={item} />)}
+ * </HeadlessTabList>
+ * ```
+ */
+declare const HeadlessTabList: React$1.ForwardRefExoticComponent<HeadlessTabListContainerProps & React$1.RefAttributes<HTMLDivElement>>;
+/**
+ * Headless Tab Component (Layer 2)
+ *
+ * Unstyled individual tab item. Provides full React Aria accessibility:
+ * - role="tab"
+ * - aria-selected
+ * - aria-controls (pointing to panel)
+ * - roving tabIndex
+ * - keyboard activation
+ *
+ * Must be used within HeadlessTabsContext.
+ *
+ * @example
+ * ```tsx
+ * <HeadlessTab item={item}>
+ *   {({ isSelected, isFocusVisible }) => (
+ *     <span className={isSelected ? 'font-bold' : ''}>
+ *       {item.label}
+ *     </span>
+ *   )}
+ * </HeadlessTab>
+ * ```
+ */
+declare const HeadlessTab: React$1.ForwardRefExoticComponent<HeadlessTabProps & React$1.RefAttributes<HTMLButtonElement>>;
+/**
+ * Headless TabPanel Component (Layer 2)
+ *
+ * Unstyled tab panel. Provides:
+ * - role="tabpanel"
+ * - aria-labelledby (pointing to its tab)
+ * - Focus management for panels without focusable children
+ *
+ * Must be used within HeadlessTabsContext.
+ *
+ * @example
+ * ```tsx
+ * <HeadlessTabPanel>
+ *   <p>Panel content here</p>
+ * </HeadlessTabPanel>
+ * ```
+ */
+declare const HeadlessTabPanel: React$1.ForwardRefExoticComponent<HeadlessTabPanelProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Badge value for a NavigationBarItem.
+ *
+ * - `true` — renders a dot indicator (no count)
+ * - `number` — renders the count; 0 hides the badge; values > 999 display "999+"
+ */
+type NavigationBarBadge = number | true;
+/**
+ * Configuration for a single NavigationBar destination item.
+ *
+ * @example
+ * ```tsx
+ * const item: NavigationBarItemConfig = {
+ *   key: 'home',
+ *   icon: <HomeIcon />,
+ *   label: 'Home',
+ *   badge: 3,
+ * };
+ * ```
+ */
+interface NavigationBarItemConfig {
+    /**
+     * Unique identifier for this destination (used as the selection key).
+     */
+    key: string;
+    /**
+     * Icon element displayed at 24dp. Always visible regardless of `hideLabels`.
+     */
+    icon: ReactNode;
+    /**
+     * Visible label beneath the icon.
+     * Required unless `aria-label` is provided (icon-only mode with `hideLabels`).
+     */
+    label?: string;
+    /**
+     * Badge displayed on the icon.
+     * - `true` renders a dot indicator.
+     * - `0` hides the badge.
+     * - `1–999` renders the count.
+     * - `> 999` renders "999+".
+     */
+    badge?: NavigationBarBadge;
+    /**
+     * When `true`, the item cannot be focused or activated.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /**
+     * Accessible name used when labels are hidden (`hideLabels` mode).
+     * Required for icon-only items; enforced at runtime via dev warning.
+     */
+    "aria-label"?: string;
+}
+/**
+ * Material Design 3 Navigation Bar (Bottom Navigation) props.
+ *
+ * Accepts 3–5 destination items. Item count outside this range triggers a
+ * dev-only `console.warn`.
+ *
+ * **Controlled usage:**
+ * ```tsx
+ * <NavigationBar
+ *   items={items}
+ *   activeKey={activeKey}
+ *   onActiveChange={setActiveKey}
+ *   aria-label="Main navigation"
+ * />
+ * ```
+ *
+ * **Uncontrolled usage:**
+ * ```tsx
+ * <NavigationBar
+ *   items={items}
+ *   defaultActiveKey="home"
+ *   aria-label="Main navigation"
+ * />
+ * ```
+ *
+ * @see https://m3.material.io/components/navigation-bar/overview
+ */
+interface NavigationBarProps {
+    /**
+     * Array of 3–5 destination items.
+     * Item count outside the 3–5 range triggers a dev warning.
+     */
+    items: NavigationBarItemConfig[];
+    /**
+     * Controlled active key. Pair with `onActiveChange`.
+     * Use `null` to explicitly deselect all items.
+     */
+    activeKey?: Key$1 | null;
+    /**
+     * Default active key for uncontrolled usage.
+     */
+    defaultActiveKey?: Key$1;
+    /**
+     * Called when the active destination changes.
+     */
+    onActiveChange?: (key: Key$1) => void;
+    /**
+     * When `true`, hides labels on all items (icon-only mode).
+     * @default false
+     */
+    hideLabels?: boolean;
+    /**
+     * Accessible label for the `<nav>` landmark element. Required.
+     *
+     * @example "Main navigation"
+     */
+    "aria-label": string;
+    /**
+     * Disable ripple effect on all items.
+     * @default false
+     */
+    disableRipple?: boolean;
+    /**
+     * Additional CSS classes merged onto the `<nav>` element via `cn()`.
+     */
+    className?: string;
+}
+/**
+ * Standalone NavigationBarItem props.
+ *
+ * Used internally by `NavigationBar` and available for advanced consumers
+ * composing with `HeadlessNavigationBar`.
+ *
+ * Extends `ButtonHTMLAttributes` (minus `disabled`) so that tab props from
+ * `useTab` can be spread directly onto the rendered `<button>`.
+ */
+interface NavigationBarItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "disabled"> {
+    /**
+     * The unique key for this item (passed to the headless layer).
+     */
+    itemKey: Key$1;
+    /**
+     * Icon element displayed at 24dp.
+     */
+    icon: ReactNode;
+    /**
+     * Visible label beneath the icon.
+     */
+    label?: string;
+    /**
+     * Badge value.
+     */
+    badge?: NavigationBarBadge;
+    /**
+     * Whether this item is the currently selected destination.
+     * @default false
+     */
+    isActive?: boolean;
+    /**
+     * When `true`, hides the label for this item.
+     * @default false
+     */
+    hideLabels?: boolean;
+    /**
+     * Whether this item is disabled.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /**
+     * Disable ripple effect on this item.
+     * @default false
+     */
+    disableRipple?: boolean;
+}
+/**
+ * HeadlessNavigationBar props.
+ *
+ * Provides the accessibility foundation (`role="navigation"`, `role="tablist"`,
+ * `useTabList`, `useTabListState`) without any visual styling.
+ * Intended for advanced consumers who need full visual control.
+ *
+ * @example
+ * ```tsx
+ * <HeadlessNavigationBar
+ *   items={items}
+ *   defaultSelectedKey="home"
+ *   aria-label="Main navigation"
+ *   renderItem={(config) => (
+ *     <HeadlessNavigationBarItem key={config.key} itemKey={config.key}>
+ *       {config.icon}
+ *       <span>{config.label}</span>
+ *     </HeadlessNavigationBarItem>
+ *   )}
+ * />
+ * ```
+ */
+interface HeadlessNavigationBarProps {
+    /**
+     * Array of item configs used to build the React Aria collection.
+     */
+    items: NavigationBarItemConfig[];
+    /**
+     * Controlled selected key. Pair with `onSelectionChange`.
+     * Use `null` to explicitly deselect all items.
+     */
+    selectedKey?: Key$1 | null;
+    /**
+     * Default selected key for uncontrolled usage.
+     */
+    defaultSelectedKey?: Key$1;
+    /**
+     * Called when the selected key changes.
+     */
+    onSelectionChange?: (key: Key$1) => void;
+    /**
+     * Accessible label for the `<nav>` landmark.
+     */
+    "aria-label": string;
+    /**
+     * Additional CSS classes for the inner `<div role="tablist">`.
+     */
+    className?: string;
+    /**
+     * Render function called for each item in the collection.
+     * Receives the item config; use `HeadlessNavigationBarItem` inside.
+     */
+    renderItem: (config: NavigationBarItemConfig) => ReactNode;
+}
+/**
+ * Render props passed to `HeadlessNavigationBarItem`'s children when used as
+ * a render function.
+ */
+interface NavigationBarItemRenderProps {
+    /** Whether this item is the active destination. */
+    isSelected: boolean;
+    /** Whether the item has a visible keyboard focus ring. */
+    isFocusVisible: boolean;
+}
+/**
+ * HeadlessNavigationBarItem props.
+ *
+ * Renders a single tab-accessible button using `useTab` from React Aria.
+ * Must be rendered inside `HeadlessNavigationBar` (reads state from context).
+ *
+ * Accepts children as ReactNode or as a render function receiving state props.
+ *
+ * @example
+ * ```tsx
+ * // Static children
+ * <HeadlessNavigationBarItem itemKey="home">
+ *   Home
+ * </HeadlessNavigationBarItem>
+ *
+ * // Render function (access to isSelected / isFocusVisible)
+ * <HeadlessNavigationBarItem itemKey="home">
+ *   {({ isSelected }) => (
+ *     <span style={{ fontWeight: isSelected ? 'bold' : 'normal' }}>Home</span>
+ *   )}
+ * </HeadlessNavigationBarItem>
+ * ```
+ */
+interface HeadlessNavigationBarItemProps {
+    /**
+     * The key matching `NavigationBarItemConfig.key`. Used to look up the
+     * item in the React Aria collection state.
+     */
+    itemKey: Key$1;
+    /**
+     * Content to render inside the button — either a ReactNode or a render
+     * function receiving `{ isSelected, isFocusVisible }`.
+     */
+    children: ReactNode | ((renderProps: NavigationBarItemRenderProps) => ReactNode);
+    /**
+     * Additional CSS classes merged onto the `<button>` element.
+     */
+    className?: string;
+    /**
+     * Accessible label for icon-only items (when no visible text label is present).
+     * Applied as `aria-label` on the `<button>` element.
+     */
+    "aria-label"?: string;
+}
+
+/**
+ * Material Design 3 Navigation Bar (Bottom Navigation) — Layer 3.
+ *
+ * Renders a fixed bottom navigation bar with 3–5 destination items, each with
+ * an icon, optional label, animated active indicator pill, and optional badge.
+ *
+ * **Architecture:**
+ * - Layer 3 (this file): MD3 styled, CVA variants, `'use client'`
+ * - Layer 2: `HeadlessNavigationBar` + `HeadlessNavigationBarItem` — React Aria
+ * - Layer 1: `useTabList`, `useTab`, `useFocusRing` — accessibility foundation
+ *
+ * **Key Features:**
+ * - 3–5 destination items (dev warning outside this range)
+ * - Animated indicator pill per MD3 motion tokens (scale + opacity)
+ * - Badge: dot, numeric count, "999+" truncation, hidden at 0
+ * - `hideLabels` for icon-only mode
+ * - Controlled (`activeKey` + `onActiveChange`) and uncontrolled (`defaultActiveKey`)
+ * - Full keyboard navigation: Arrow Left/Right, Home, End, roving `tabIndex`
+ * - WCAG 2.1 AA: `role="navigation"` + `aria-label`, `role="tablist"`,
+ *   `role="tab"` + `aria-selected`, visible focus ring
+ *
+ * **Future — Navigation Rail:**
+ * At wider viewports, a NavigationBar may transition to a Navigation Rail.
+ * This is a separate component tracked as a future Phase 5+ item.
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled
+ * <NavigationBar
+ *   items={[
+ *     { key: 'home', icon: <HomeIcon />, label: 'Home' },
+ *     { key: 'search', icon: <SearchIcon />, label: 'Search', badge: 3 },
+ *     { key: 'profile', icon: <ProfileIcon />, label: 'Profile' },
+ *   ]}
+ *   defaultActiveKey="home"
+ *   aria-label="Main navigation"
+ * />
+ *
+ * // Controlled
+ * <NavigationBar
+ *   items={items}
+ *   activeKey={activeKey}
+ *   onActiveChange={setActiveKey}
+ *   aria-label="Main navigation"
+ * />
+ *
+ * // Icon-only mode
+ * <NavigationBar
+ *   items={iconOnlyItems}
+ *   defaultActiveKey="home"
+ *   aria-label="Main navigation"
+ *   hideLabels
+ * />
+ * ```
+ *
+ * @see https://m3.material.io/components/navigation-bar/overview
+ * @see https://m3.material.io/components/navigation-bar/specs
+ */
+declare const NavigationBar: React$1.ForwardRefExoticComponent<NavigationBarProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Material Design 3 Navigation Bar Item (Layer 3).
+ *
+ * Renders a single destination item within a `NavigationBar`. Handles:
+ * - Active indicator pill (`rounded-full`, animated with MD3 motion tokens)
+ * - Icon slot (24dp, always visible)
+ * - Badge (dot, numeric count, 999+ truncation)
+ * - Label (hidden in `hideLabels` mode)
+ * - MD3 state layers (hover `opacity-8`, pressed `opacity-12`)
+ * - Ripple effect via `useRipple`
+ * - Focus ring via `data-focus-visible`
+ *
+ * Used internally by `NavigationBar`. Can also be composed with
+ * `HeadlessNavigationBarItem` for advanced customization.
+ *
+ * **Future — Navigation Rail:**
+ * At wider viewports, a NavigationBar may transition to a Navigation Rail.
+ * This is a separate component tracked as a future Phase 5+ item.
+ *
+ * @example
+ * ```tsx
+ * // Used standalone (advanced consumer with HeadlessNavigationBar)
+ * <NavigationBarItem
+ *   itemKey="home"
+ *   icon={<HomeIcon />}
+ *   label="Home"
+ *   isActive
+ * />
+ * ```
+ */
+declare const NavigationBarItem: React$1.ForwardRefExoticComponent<NavigationBarItemProps & React$1.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Headless Navigation Bar (Layer 2).
+ *
+ * Renders an accessible `<nav role="navigation">` landmark wrapping a
+ * `<div role="tablist">`. Provides keyboard navigation (Arrow Left/Right,
+ * Home, End) and full ARIA semantics via React Aria's `useTabList`.
+ *
+ * All item accessibility is handled by `HeadlessNavigationBarItem`.
+ *
+ * Use this component when you need complete visual control beyond what the
+ * styled `NavigationBar` provides.
+ *
+ * @example
+ * ```tsx
+ * <HeadlessNavigationBar
+ *   items={items}
+ *   defaultSelectedKey="home"
+ *   aria-label="Main navigation"
+ *   renderItem={(config) => (
+ *     <HeadlessNavigationBarItem key={config.key} itemKey={config.key}>
+ *       {config.icon}
+ *       <span>{config.label}</span>
+ *     </HeadlessNavigationBarItem>
+ *   )}
+ * />
+ * ```
+ */
+declare const HeadlessNavigationBar: React$1.ForwardRefExoticComponent<HeadlessNavigationBarProps & React$1.RefAttributes<HTMLElement>>;
+/**
+ * Headless Navigation Bar Item (Layer 2).
+ *
+ * Renders an accessible `<button role="tab">` using React Aria's `useTab`.
+ * Provides `aria-selected`, `aria-disabled`, roving `tabIndex`, and
+ * focus management via `useFocusRing`.
+ *
+ * Must be rendered inside `HeadlessNavigationBar`.
+ *
+ * @example
+ * ```tsx
+ * <HeadlessNavigationBarItem itemKey="home" className="my-item">
+ *   <HomeIcon aria-hidden />
+ *   <span>Home</span>
+ * </HeadlessNavigationBarItem>
+ * ```
+ */
+declare const HeadlessNavigationBarItem: React$1.ForwardRefExoticComponent<HeadlessNavigationBarItemProps & React$1.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Structural variant of the Navigation Drawer.
+ *
+ * - `standard` — inline `<nav>` landmark; no overlay or focus trap; supports
+ *   controlled `open` prop for collapsible layouts.
+ * - `modal` — overlay dialog with scrim backdrop, slide-in animation,
+ *   focus trap, and `Escape` to close.
+ */
+type DrawerVariant = "standard" | "modal";
+/**
+ * Material Design 3 Navigation Drawer props.
+ *
+ * Supports two structural variants — Standard (inline, permanently visible or
+ * togglable) and Modal (overlay with scrim and focus trap).
+ *
+ * @example
+ * ```tsx
+ * // Standard variant
+ * <Drawer variant="standard" open={open} onOpenChange={setOpen} aria-label="App navigation">
+ *   <DrawerItem label="Home" isActive />
+ *   <DrawerItem label="Settings" />
+ * </Drawer>
+ *
+ * // Modal variant with trigger
+ * <Drawer variant="modal" open={open} onOpenChange={setOpen} aria-label="App navigation">
+ *   <DrawerItem label="Home" isActive />
+ *   <DrawerSection header="Account">
+ *     <DrawerItem label="Profile" />
+ *   </DrawerSection>
+ * </Drawer>
+ * ```
+ */
+interface DrawerProps extends AriaDialogProps {
+    /**
+     * Structural variant — drives which React Aria hooks and DOM structure are used.
+     * @default 'standard'
+     */
+    variant?: DrawerVariant;
+    /**
+     * Controlled open state. Pair with `onOpenChange`.
+     */
+    open?: boolean;
+    /**
+     * Default open state for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Called when the open state changes (e.g. Escape key, scrim click).
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Accessible label for the drawer landmark/dialog. Required.
+     *
+     * @example "App navigation"
+     */
+    "aria-label": string;
+    /**
+     * Drawer content — typically `DrawerItem` and `DrawerSection` elements.
+     */
+    children: ReactNode;
+    /**
+     * Additional CSS classes merged onto the drawer panel element.
+     */
+    className?: string;
+    /**
+     * Disable ripple effect on all items within the drawer.
+     * @default false
+     */
+    disableRipple?: boolean;
+}
+/**
+ * Material Design 3 Navigation Drawer Item props.
+ *
+ * Renders as `<a>` when `href` is provided (using `useLink`), or as `<button>`
+ * when no `href` is provided (using `useButton`).
+ *
+ * @example
+ * ```tsx
+ * // Button-based item (no href)
+ * <DrawerItem
+ *   icon={<HomeIcon />}
+ *   label="Home"
+ *   isActive
+ *   onPress={() => setPage('home')}
+ * />
+ *
+ * // Link-based item (with href)
+ * <DrawerItem href="/settings" icon={<SettingsIcon />} label="Settings" />
+ *
+ * // With badge
+ * <DrawerItem label="Inbox" badge={<span>3</span>} />
+ *
+ * // Disabled
+ * <DrawerItem label="Disabled" isDisabled />
+ * ```
+ */
+interface DrawerItemProps extends AriaButtonProps, Pick<AriaLinkOptions, "href"> {
+    /**
+     * Optional URL — when provided, renders the item as `<a>` using `useLink`.
+     * When absent, renders as `<button>` using `useButton`.
+     */
+    href?: string;
+    /**
+     * Optional leading icon (24dp).
+     */
+    icon?: ReactNode;
+    /**
+     * Visible label text. Required.
+     */
+    label: string;
+    /**
+     * Optional trailing badge or secondary indicator element.
+     */
+    badge?: ReactNode;
+    /**
+     * Optional secondary descriptive text rendered below the label.
+     */
+    secondaryText?: string;
+    /**
+     * When `true`, marks this item as the active destination.
+     * Applies `aria-current="page"`, active indicator background, and
+     * `text-on-secondary-container`.
+     * @default false
+     */
+    isActive?: boolean;
+    /**
+     * Disable ripple effect on this specific item.
+     * @default false
+     */
+    disableRipple?: boolean;
+    /**
+     * Additional CSS classes merged via `cn()`.
+     */
+    className?: string;
+}
+/**
+ * Material Design 3 Navigation Drawer Section props.
+ *
+ * Groups related `DrawerItem` elements with an optional header label and
+ * a preceding divider (except the first section).
+ *
+ * @example
+ * ```tsx
+ * <DrawerSection header="Account">
+ *   <DrawerItem label="Profile" />
+ *   <DrawerItem label="Logout" />
+ * </DrawerSection>
+ * ```
+ */
+interface DrawerSectionProps {
+    /**
+     * Optional section header label rendered in `text-title-small`.
+     */
+    header?: string;
+    /**
+     * Section content — typically `DrawerItem` elements.
+     */
+    children: ReactNode;
+    /**
+     * When `true`, renders a top divider line above the section.
+     * @default false
+     */
+    showDivider?: boolean;
+    /**
+     * Additional CSS classes merged via `cn()`.
+     */
+    className?: string;
+}
+/**
+ * Props for the headless Drawer primitive (Layer 2).
+ * Provides behavior and ARIA semantics without visual styling.
+ */
+interface HeadlessDrawerProps {
+    /**
+     * Structural variant — drives which React Aria hooks are used.
+     * @default 'standard'
+     */
+    variant?: DrawerVariant;
+    /**
+     * Controlled open state.
+     */
+    open?: boolean;
+    /**
+     * Default open state for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Called when the open state changes.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Accessible label. Required.
+     */
+    "aria-label": string;
+    /**
+     * Drawer content.
+     */
+    children: ReactNode;
+    /**
+     * Additional CSS classes for the drawer panel element.
+     */
+    className?: string;
+    /**
+     * Additional CSS classes for the scrim element (modal variant only).
+     */
+    scrimClassName?: string;
+    /**
+     * Disable ripple on all items.
+     * @default false
+     */
+    disableRipple?: boolean;
+}
+/**
+ * Props for the headless DrawerItem primitive (Layer 2).
+ */
+interface HeadlessDrawerItemProps extends AriaButtonProps, Pick<AriaLinkOptions, "href"> {
+    /**
+     * Optional URL — determines `<a>` vs `<button>` rendering.
+     */
+    href?: string;
+    /**
+     * Whether this item is active (`aria-current="page"`).
+     * @default false
+     */
+    isActive?: boolean;
+    /**
+     * Item content.
+     */
+    children: ReactNode;
+    /**
+     * Additional CSS classes.
+     */
+    className?: string;
+    /**
+     * Mouse down handler (for ripple effect).
+     */
+    onMouseDown?: (e: React.MouseEvent<HTMLElement>) => void;
+}
+/**
+ * Context value shared between HeadlessDrawer and its children.
+ * @internal
+ */
+interface DrawerContextValue {
+    /** Whether the drawer is currently open. */
+    isOpen: boolean;
+    /** Callback to close the drawer. */
+    close: () => void;
+    /** Whether ripple is disabled for all items. */
+    disableRipple: boolean;
+}
+
+/**
+ * Material Design 3 Navigation Drawer (Layer 3: Styled).
+ *
+ * Supports two structural variants driven by the `variant` prop:
+ *
+ * - **`standard`** — Inline `<nav>` landmark. Permanently visible or
+ *   collapsible via controlled `open` prop. No overlay or focus trap.
+ *   Surface: `bg-surface-container-low`.
+ *
+ * - **`modal`** — Overlay dialog with scrim backdrop, slide-in animation,
+ *   focus trap, and `Escape` to close.
+ *   Surface: `bg-surface-container`, `shadow-elevation-1`.
+ *
+ * Both variants:
+ * - `role="navigation"` on the outer wrapper
+ * - `rounded-r-xl` (28px per MD3 shape extra-large on right side only)
+ * - Slide-in animation: `translate-x` driven by MD3 motion tokens
+ * - `w-drawer` (360dp per MD3 spec)
+ *
+ * Modal-only:
+ * - `role="dialog"` + `aria-modal="true"` on the panel
+ * - `FocusScope` containing focus + restoring on close
+ * - `usePreventScroll` to lock body scroll
+ * - Scrim: `bg-scrim opacity-32` — click closes drawer
+ * - `Escape` key closes drawer
+ *
+ * @example
+ * ```tsx
+ * // Standard variant (collapsible sidebar)
+ * <Drawer
+ *   variant="standard"
+ *   open={sidebarOpen}
+ *   onOpenChange={setSidebarOpen}
+ *   aria-label="App navigation"
+ * >
+ *   <DrawerItem icon={<HomeIcon />} label="Home" isActive />
+ *   <DrawerSection header="Settings" showDivider>
+ *     <DrawerItem icon={<SettingsIcon />} label="Preferences" />
+ *   </DrawerSection>
+ * </Drawer>
+ *
+ * // Modal variant (overlay)
+ * <Drawer
+ *   variant="modal"
+ *   open={drawerOpen}
+ *   onOpenChange={setDrawerOpen}
+ *   aria-label="App navigation"
+ * >
+ *   <DrawerItem label="Home" isActive />
+ *   <DrawerItem label="Inbox" badge={<span>5</span>} />
+ * </Drawer>
+ * ```
+ *
+ * @see https://m3.material.io/components/navigation-drawer/overview
+ */
+declare const Drawer: React$1.ForwardRefExoticComponent<DrawerProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Material Design 3 Navigation Drawer Item (Layer 3: Styled).
+ *
+ * Renders a navigation destination row following MD3 Navigation Drawer specs.
+ * Uses `HeadlessDrawerItem` for behavior and accessibility, CVA for variants.
+ *
+ * Renders as `<a>` when `href` is provided, `<button>` otherwise.
+ *
+ * Features:
+ * - Active indicator: `bg-secondary-container` / `text-on-secondary-container`
+ * - `aria-current="page"` on active item
+ * - Ripple effect on interaction
+ * - Hover/focus/pressed state layers (MD3 spec: 8% / 12%)
+ * - Optional leading icon (24dp slot)
+ * - Optional trailing badge or secondary text
+ * - Disabled state: `opacity-38`, non-interactive
+ *
+ * @example
+ * ```tsx
+ * // Active item with icon
+ * <DrawerItem icon={<HomeIcon />} label="Home" isActive onPress={() => navigate('/')} />
+ *
+ * // Link item
+ * <DrawerItem href="/settings" icon={<SettingsIcon />} label="Settings" />
+ *
+ * // Item with badge
+ * <DrawerItem label="Inbox" badge={<span>3</span>} />
+ *
+ * // Disabled
+ * <DrawerItem label="Disabled Feature" isDisabled />
+ * ```
+ *
+ * @see https://m3.material.io/components/navigation-drawer/specs
+ */
+declare const DrawerItem: React$1.ForwardRefExoticComponent<DrawerItemProps & React$1.RefAttributes<HTMLElement>>;
+
+/**
+ * Material Design 3 Navigation Drawer Section (Layer 3: Styled).
+ *
+ * Groups related `DrawerItem` elements with an optional header label and
+ * a horizontal divider. Follows MD3 Navigation Drawer spec for section
+ * grouping and typography.
+ *
+ * Features:
+ * - Optional header label: `text-title-small text-on-surface-variant`
+ * - Optional top divider: `border-outline-variant`
+ * - Semantic `<hr role="separator">` for the divider
+ *
+ * @example
+ * ```tsx
+ * // Section with header and divider
+ * <DrawerSection header="Account" showDivider>
+ *   <DrawerItem icon={<ProfileIcon />} label="Profile" />
+ *   <DrawerItem icon={<LogoutIcon />} label="Logout" />
+ * </DrawerSection>
+ *
+ * // Section without header (just a visual group)
+ * <DrawerSection showDivider>
+ *   <DrawerItem label="Help" />
+ * </DrawerSection>
+ * ```
+ *
+ * @see https://m3.material.io/components/navigation-drawer/specs
+ */
+declare const DrawerSection: React$1.ForwardRefExoticComponent<DrawerSectionProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Headless Navigation Drawer (Layer 2).
+ *
+ * Provides all behavior and ARIA semantics without any visual styling.
+ * Renders two distinct DOM structures based on the `variant` prop:
+ *
+ * - **`standard`**: `<nav role="navigation">` — no overlay, no focus trap
+ * - **`modal`**: `<nav role="navigation">` containing a `FocusScope`-wrapped
+ *   `<div role="dialog" aria-modal="true">` with scrim overlay
+ *
+ * React Aria hooks used:
+ * - `useDialog` — `role="dialog"`, `aria-modal`, `aria-label` on modal panel
+ * - `useOverlay` — dismiss on Escape key and outside click (modal)
+ * - `usePreventScroll` — locks body scroll when modal is open
+ * - `FocusScope` — focus trap + restoreFocus when modal closes
+ * - `useOverlayTriggerState` — open/close state management
+ *
+ * @example
+ * ```tsx
+ * <HeadlessDrawer variant="modal" open aria-label="Navigation">
+ *   <HeadlessDrawerItem onPress={() => {}}>Home</HeadlessDrawerItem>
+ * </HeadlessDrawer>
+ * ```
+ */
+declare const HeadlessDrawer: React__default.ForwardRefExoticComponent<HeadlessDrawerProps & React__default.RefAttributes<HTMLElement>>;
+/**
+ * Headless Navigation Drawer Item (Layer 2).
+ *
+ * Renders as:
+ * - `<a>` using `useLink` when `href` is provided
+ * - `<button>` using `useButton` when no `href`
+ *
+ * Applies `aria-current="page"` when `isActive` is true.
+ * Uses `useFocusRing` for visible keyboard focus.
+ *
+ * @example
+ * ```tsx
+ * // Button-based item
+ * <HeadlessDrawerItem onPress={() => navigate('home')} isActive>
+ *   Home
+ * </HeadlessDrawerItem>
+ *
+ * // Link-based item
+ * <HeadlessDrawerItem href="/settings">
+ *   Settings
+ * </HeadlessDrawerItem>
+ * ```
+ */
+declare const HeadlessDrawerItem: React__default.ForwardRefExoticComponent<HeadlessDrawerItemProps & React__default.RefAttributes<HTMLElement>>;
+
+/**
+ * Material Design 3 Progress Indicator Component Props
+ *
+ * Built on React Aria for world-class accessibility.
+ * Supports four variants: Linear Determinate, Linear Indeterminate,
+ * Circular Determinate, and Circular Indeterminate.
+ * Implementation uses CVA + Tailwind CSS classes mapped to MD3 tokens.
+ *
+ * @example
+ * ```tsx
+ * // Linear determinate
+ * <Progress type="linear" value={60} label="Loading" />
+ *
+ * // Linear indeterminate
+ * <Progress type="linear" indeterminate aria-label="Loading content" />
+ *
+ * // Circular determinate
+ * <Progress type="circular" value={75} label="Uploading" />
+ *
+ * // Circular indeterminate (default spinner)
+ * <Progress type="circular" indeterminate aria-label="Loading" />
+ *
+ * // Circular with size
+ * <Progress type="circular" indeterminate size="small" aria-label="Loading" />
+ *
+ * // Custom range
+ * <Progress type="linear" minValue={0} maxValue={200} value={150} label="Progress" />
+ * ```
+ */
+interface ProgressProps extends AriaProgressBarProps {
+    /**
+     * The visual type of the progress indicator.
+     * @default "linear"
+     */
+    type?: "linear" | "circular";
+    /**
+     * When true, renders indeterminate (unknown progress) animation.
+     * `value` is ignored when indeterminate is true.
+     * @default false
+     */
+    indeterminate?: boolean;
+    /**
+     * Size of the circular progress indicator (ignored for linear).
+     * small=24dp, medium=48dp (default), large=64dp per MD3 spec.
+     * @default "medium"
+     */
+    size?: "small" | "medium" | "large";
+    /**
+     * Additional CSS classes (Tailwind).
+     */
+    className?: string;
+}
+/**
+ * Props for the headless Progress component.
+ * Provides behavior and accessibility only — bring your own styles.
+ *
+ * @example
+ * ```tsx
+ * <ProgressHeadless
+ *   type="linear"
+ *   value={50}
+ *   label="Upload"
+ *   renderProgress={({ percentage }) => (
+ *     <div style={{ width: `${percentage}%` }} />
+ *   )}
+ * />
+ * ```
+ */
+interface ProgressHeadlessProps extends AriaProgressBarProps {
+    /**
+     * The visual type of the progress indicator.
+     * @default "linear"
+     */
+    type?: "linear" | "circular";
+    /**
+     * When true, renders indeterminate animation.
+     * @default false
+     */
+    indeterminate?: boolean;
+    /**
+     * Size for circular variant.
+     * @default "medium"
+     */
+    size?: "small" | "medium" | "large";
+    /**
+     * Additional CSS classes.
+     */
+    className?: string;
+    /**
+     * Children rendered inside the container.
+     */
+    children?: React__default.ReactNode;
+    /**
+     * Render prop for custom progress visual.
+     * Receives computed state for building custom visuals.
+     */
+    renderProgress?: (state: {
+        percentage: number;
+        isIndeterminate: boolean;
+        type: "linear" | "circular";
+        size: "small" | "medium" | "large";
+    }) => React__default.ReactNode;
+}
+
+/**
+ * Material Design 3 Progress Indicator (Layer 3: Styled)
+ *
+ * Built on React Aria for world-class accessibility.
+ * Supports four variants driven by `type` + `indeterminate` props:
+ *   - Linear Determinate
+ *   - Linear Indeterminate
+ *   - Circular Determinate
+ *   - Circular Indeterminate
+ *
+ * MD3 Specifications:
+ * - Linear track height: 4dp (h-1)
+ * - Linear track shape: rounded-full
+ * - Circular default size: 48dp (medium)
+ * - Circular stroke width: 4dp (SVG attribute)
+ * - Active track: primary
+ * - Inactive track: surface-container-highest
+ * - Determinate transitions: duration-medium4 + ease-standard
+ * - Indeterminate linear cycle: duration-long2
+ * - Indeterminate circular rotation: duration-long4
+ *
+ * @example
+ * ```tsx
+ * // Linear determinate
+ * <Progress type="linear" value={60} label="Uploading" />
+ *
+ * // Linear indeterminate
+ * <Progress type="linear" indeterminate aria-label="Loading" />
+ *
+ * // Circular determinate
+ * <Progress type="circular" value={75} label="Processing" />
+ *
+ * // Circular indeterminate
+ * <Progress type="circular" indeterminate aria-label="Loading" />
+ *
+ * // Circular small spinner
+ * <Progress type="circular" indeterminate size="small" aria-label="Loading" />
+ * ```
+ */
+declare const Progress: React__default.ForwardRefExoticComponent<ProgressProps & React__default.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Headless Progress Indicator Component (Layer 2)
+ *
+ * Unstyled progress bar primitive using React Aria for accessibility.
+ * Provides behavior only — bring your own styles.
+ *
+ * Features:
+ * - role="progressbar" with correct aria-value* attributes
+ * - Determinate and indeterminate progress support
+ * - Internationalized value label formatting via React Aria
+ * - Label linkage via aria-labelledby / aria-label
+ * - Render prop for custom visual rendering
+ *
+ * @example
+ * ```tsx
+ * // Custom visual via render prop
+ * <ProgressHeadless
+ *   value={50}
+ *   label="Upload"
+ *   renderProgress={({ percentage }) => (
+ *     <div style={{ width: `${percentage}%` }} />
+ *   )}
+ * />
+ *
+ * // Children-based rendering
+ * <ProgressHeadless value={75} aria-label="Loading">
+ *   <MyCustomProgressVisual />
+ * </ProgressHeadless>
+ * ```
+ */
+declare const ProgressHeadless: React__default.ForwardRefExoticComponent<ProgressHeadlessProps & React__default.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Color scheme for the MD3 Menu container and items.
+ *
+ * - `standard` — surface-based colors; default for most use cases
+ * - `vibrant` — tertiary-based colors; higher visual emphasis; use sparingly
+ *
+ * @see https://m3.material.io/components/menus/specs#color
+ */
+type MenuColorScheme = "standard" | "vibrant";
+/**
+ * Visual style of the MD3 Menu.
+ *
+ * - `baseline` — original M3 design; 4dp corner radius; surface container background
+ * - `vertical` — M3 Expressive style; 16dp corner radius; more expressive shapes and motion
+ *
+ * @see https://m3.material.io/components/menus/specs#variants
+ */
+type MenuStyle = "baseline" | "vertical";
+/**
+ * Density level for the MD3 Menu (web only).
+ *
+ * Controls item height via top/bottom padding reduction:
+ * - `0`  → 48dp (default)
+ * - `-1` → 44dp
+ * - `-2` → 40dp
+ * - `-3` → 36dp
+ *
+ * @see https://m3.material.io/m3/pages/understanding-layout/density
+ */
+type MenuDensity = 0 | -1 | -2 | -3;
+/**
+ * Props for the `MenuTrigger` component (styled Layer 3).
+ *
+ * Wraps a trigger element and a `Menu`. The first child must be the trigger;
+ * the second must be a `Menu` component.
+ *
+ * @example
+ * ```tsx
+ * <MenuTrigger>
+ *   <Button>Open</Button>
+ *   <Menu aria-label="Actions">
+ *     <MenuItem id="copy">Copy</MenuItem>
+ *   </Menu>
+ * </MenuTrigger>
+ * ```
+ */
+interface MenuTriggerProps extends AriaMenuTriggerProps {
+    /** Trigger element + Menu children. */
+    children: ReactNode;
+    /**
+     * Preferred placement of the menu relative to the trigger.
+     * @default 'bottom start'
+     */
+    placement?: "bottom" | "bottom start" | "bottom end" | "top" | "top start" | "top end";
+    /**
+     * Whether the menu should automatically flip to the opposite side when it
+     * would be cut off by the viewport edge.
+     * @default true
+     */
+    shouldFlip?: boolean;
+}
+/**
+ * Props for the `Menu` component (styled Layer 3).
+ *
+ * @example
+ * ```tsx
+ * <Menu aria-label="Edit">
+ *   <MenuItem id="cut">Cut</MenuItem>
+ *   <MenuItem id="copy">Copy</MenuItem>
+ *   <MenuItem id="paste">Paste</MenuItem>
+ * </Menu>
+ * ```
+ */
+interface MenuProps<T extends object = object> extends AriaMenuProps<T> {
+    /**
+     * Color scheme — standard (surface-based) or vibrant (tertiary-based).
+     * Vibrant is more prominent and should be used sparingly.
+     * @default 'standard'
+     */
+    colorScheme?: MenuColorScheme;
+    /**
+     * Visual style — baseline (4dp corners) or vertical (16dp corners, expressive).
+     * @default 'baseline'
+     */
+    menuStyle?: MenuStyle;
+    /**
+     * Density level controlling item height (web only).
+     * 0 = 48dp, -1 = 44dp, -2 = 40dp, -3 = 36dp.
+     * @default 0
+     */
+    density?: MenuDensity;
+    /** Additional CSS classes merged onto the menu container element. */
+    className?: string;
+    /**
+     * Disable ripple on all menu items.
+     * @default false
+     */
+    disableRipple?: boolean;
+}
+/**
+ * Props for the `MenuItem` component (styled Layer 3).
+ *
+ * A single interactive item within a Menu. Supports leading/trailing icons,
+ * keyboard shortcut labels, supporting text (description), and a badge slot.
+ *
+ * @example
+ * ```tsx
+ * // With leading icon and keyboard shortcut
+ * <MenuItem id="copy" leadingIcon={<CopyIcon />} trailingText="⌘C">
+ *   Copy
+ * </MenuItem>
+ *
+ * // With description
+ * <MenuItem id="export" description="Export to various formats">
+ *   Export
+ * </MenuItem>
+ *
+ * // Disabled
+ * <MenuItem id="paste" isDisabled>Paste</MenuItem>
+ * ```
+ */
+interface MenuItemProps extends MenuItemProps$1 {
+    /** Item label content. */
+    children?: ReactNode;
+    /**
+     * Optional leading icon element (24×24dp).
+     * Rendered with `text-on-surface-variant`.
+     */
+    leadingIcon?: ReactNode;
+    /**
+     * Optional trailing icon element (24×24dp).
+     * Rendered with `text-on-surface-variant`.
+     * Mutually exclusive with `trailingText`.
+     */
+    trailingIcon?: ReactNode;
+    /**
+     * Optional keyboard-shortcut label at the trailing end (e.g. `"⌘C"`, `"Ctrl+V"`).
+     * Screen readers announce this via `aria-keyshortcuts`.
+     * Mutually exclusive with `trailingIcon`.
+     */
+    trailingText?: string;
+    /**
+     * Optional supporting text (description) rendered below the label.
+     * Uses `text-body-medium text-on-surface-variant`.
+     * When present, item height becomes auto (multi-line).
+     *
+     * @see https://m3.material.io/components/menus/specs - Anatomy item 8
+     */
+    description?: ReactNode;
+    /**
+     * Optional badge element rendered between the label and trailing content.
+     *
+     * @see https://m3.material.io/components/menus/specs - Anatomy item 5
+     */
+    badge?: ReactNode;
+    /** Additional CSS classes merged onto the item element. */
+    className?: string;
+    /**
+     * Disable the ripple effect on this specific item.
+     * @default false
+     */
+    disableRipple?: boolean;
+}
+/**
+ * Props for the `MenuSection` component (styled Layer 3).
+ *
+ * Groups related `MenuItem` elements with an optional section header and
+ * an optional top divider.
+ *
+ * @example
+ * ```tsx
+ * <MenuSection header="Clipboard" showDivider>
+ *   <MenuItem id="cut">Cut</MenuItem>
+ *   <MenuItem id="copy">Copy</MenuItem>
+ * </MenuSection>
+ * ```
+ */
+/**
+ * Base props shared by both `MenuSection` variants.
+ */
+interface MenuSectionBaseProps {
+    /** Section content — typically `MenuItem` elements. */
+    children: ReactNode;
+    /**
+     * When `true`, renders a horizontal divider above the section.
+     * @default false
+     */
+    showDivider?: boolean;
+    /** Additional CSS classes. */
+    className?: string;
+}
+/**
+ * Props for the `MenuSection` component (styled Layer 3).
+ *
+ * Either `header` or `aria-label` must be provided so the section has an
+ * accessible name, as required by WCAG 2.1 (ARIA `group` role).
+ *
+ * @example
+ * ```tsx
+ * <MenuSection header="Clipboard" showDivider>
+ *   <MenuItem id="cut">Cut</MenuItem>
+ *   <MenuItem id="copy">Copy</MenuItem>
+ * </MenuSection>
+ * ```
+ */
+type MenuSectionProps = (MenuSectionBaseProps & {
+    /**
+     * Section header label (rendered visually and used as the accessible name).
+     * Uses `text-title-small text-on-surface-variant`.
+     */
+    header: string;
+    "aria-label"?: string;
+}) | (MenuSectionBaseProps & {
+    header?: string;
+    /**
+     * Accessible label for the section. Required when `header` is not provided.
+     */
+    "aria-label": string;
+});
+/**
+ * Props for the standalone `MenuDivider` component.
+ *
+ * Renders a semantic `role="separator"` with `border-outline-variant` styling.
+ * 8dp top/bottom padding per MD3 spec.
+ *
+ * @example
+ * ```tsx
+ * <MenuItem id="cut">Cut</MenuItem>
+ * <MenuDivider />
+ * <MenuItem id="select-all">Select all</MenuItem>
+ * ```
+ */
+interface MenuDividerProps {
+    /** Additional CSS classes merged onto the separator element. */
+    className?: string;
+}
+/**
+ * Props for the headless `HeadlessMenuTrigger` primitive (Layer 2).
+ */
+interface HeadlessMenuTriggerProps extends AriaMenuTriggerProps {
+    children: ReactNode;
+    placement?: MenuTriggerProps["placement"];
+    shouldFlip?: boolean;
+}
+/**
+ * Props for the headless `HeadlessMenu` primitive (Layer 2).
+ */
+interface HeadlessMenuProps<T extends object = object> extends AriaMenuProps<T> {
+    className?: string;
+}
+/**
+ * Props for the headless `HeadlessMenuItem` primitive (Layer 2).
+ *
+ * `className` accepts either a static string or a render-prop function so
+ * MD3 state-dependent styles (selection, disabled) can be applied directly
+ * to the `<li role="menuitem">` element via RAC's render-prop mechanism.
+ */
+type HeadlessMenuItemProps = MenuItemProps$1;
+/**
+ * Props for the headless `HeadlessMenuSection` primitive (Layer 2).
+ *
+ * The section header is handled at Layer 3 (`MenuSection`) using RAC's
+ * `Header` component. At Layer 2, only `aria-label` is used for accessibility.
+ */
+interface HeadlessMenuSectionProps {
+    children: ReactNode;
+    className?: string;
+    "aria-label"?: string;
+}
+/**
+ * Context value shared between the Menu and its item descendants.
+ * @internal
+ */
+interface MenuContextValue {
+    /** Close the menu overlay. */
+    close: () => void;
+    /** Whether ripple is disabled for all items. */
+    disableRipple: boolean;
+    /** Color scheme — standard or vibrant. */
+    colorScheme: MenuColorScheme;
+    /** Visual style — baseline or vertical. */
+    menuStyle: MenuStyle;
+    /** Density level controlling item height. */
+    density: MenuDensity;
+    /** Currently selected keys (for selection menus). */
+    selectedKeys?: Iterable<Key$2>;
+    /** Current selection mode. */
+    selectionMode?: SelectionMode;
+}
+
+/**
+ * MD3 styled Menu component (Layer 3).
+ *
+ * Renders a list of `MenuItem`, `MenuSection`, or `MenuDivider` children.
+ * Intended to be used as `MenuTrigger.Menu` (nested inside a `MenuTrigger`).
+ *
+ * @example
+ * ```tsx
+ * <MenuTrigger>
+ *   <Button>Open</Button>
+ *   <Menu aria-label="Actions">
+ *     <MenuItem id="copy">Copy</MenuItem>
+ *     <MenuItem id="paste">Paste</MenuItem>
+ *   </Menu>
+ * </MenuTrigger>
+ * ```
+ */
+declare const Menu: React$1.ForwardRefExoticComponent<MenuProps<object> & React$1.RefAttributes<HTMLElement>>;
+/**
+ * MD3 styled MenuTrigger component (Layer 3).
+ *
+ * Wraps a trigger element and a `Menu` to create a dropdown.
+ * Attach `MenuTrigger.Menu` to specify the menu content, which gives IDE
+ * autocompletion and makes the parent/child relationship explicit.
+ *
+ * @example
+ * ```tsx
+ * <MenuTrigger>
+ *   <button type="button">Open Menu</button>
+ *   <MenuTrigger.Menu aria-label="Actions">
+ *     <MenuItem id="cut">Cut</MenuItem>
+ *   </MenuTrigger.Menu>
+ * </MenuTrigger>
+ * ```
+ */
+declare function MenuTrigger({ children, placement, shouldFlip, ...rest }: MenuTriggerProps): JSX.Element;
+declare namespace MenuTrigger {
+    var Menu: React$1.ForwardRefExoticComponent<MenuProps<object> & React$1.RefAttributes<HTMLElement>>;
+}
+
+/**
+ * MD3 styled MenuItem component (Layer 3).
+ *
+ * All MD3 styles (selection colors, typography, density height) are applied
+ * directly to the `<li role="menuitem">` element via RAC's render-prop className,
+ * ensuring tests and assistive technologies see the correct classes on the
+ * semantically meaningful element.
+ *
+ * @example
+ * ```tsx
+ * <MenuItem id="copy" leadingIcon={<CopyIcon />} trailingText="⌘C">
+ *   Copy
+ * </MenuItem>
+ * ```
+ */
+declare const MenuItem: React$1.ForwardRefExoticComponent<MenuItemProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * MD3 styled MenuSection component (Layer 3).
+ *
+ * Groups related `MenuItem` elements with an optional section header and an
+ * optional top divider.
+ *
+ * **Implementation note**: The divider is rendered as a SIBLING BEFORE the
+ * `RACMenuSection`, NOT inside it. RAC's `Section`/`MenuSection` only accepts
+ * `Header` and `MenuItem` children — placing a `Separator` inside the section
+ * would create invalid HTML (`<li>` inside `<li role="group">`) and break RAC's
+ * collection rendering.
+ *
+ * @example
+ * ```tsx
+ * <MenuSection header="Clipboard" showDivider aria-label="Clipboard">
+ *   <MenuItem id="cut">Cut</MenuItem>
+ *   <MenuItem id="copy">Copy</MenuItem>
+ * </MenuSection>
+ * ```
+ */
+declare function MenuSection({ children, header, showDivider, className, "aria-label": ariaLabel, }: MenuSectionProps): JSX.Element;
+
+/**
+ * MD3 styled MenuDivider component (Layer 3).
+ *
+ * Renders a horizontal `role="separator"` with `border-outline-variant` styling.
+ * 8dp top/bottom padding (`my-2`) per MD3 spec.
+ *
+ * @example
+ * ```tsx
+ * <MenuItem id="cut">Cut</MenuItem>
+ * <MenuDivider />
+ * <MenuItem id="select-all">Select all</MenuItem>
+ * ```
+ */
+declare function MenuDivider({ className }: MenuDividerProps): JSX.Element;
+
+declare const MenuContext: React$1.Context<MenuContextValue | null>;
+declare function useMenuContext(): MenuContextValue | null;
+/**
+ * Layer 2 headless primitive.
+ *
+ * Uses `RACMenuTrigger` (Layer 1) as the foundation. `RACMenuTrigger` manages:
+ * - `aria-haspopup="menu"` and `aria-expanded` on the trigger (dynamic)
+ * - Open/close state and keyboard opening (ArrowDown → focus first item)
+ * - `OverlayTriggerStateContext` so the Popover can close on Escape / outside click
+ * - `PopoverGroupContext` so the Popover's `ariaHideOutside` does NOT hide the
+ *   trigger button while the menu is open
+ *
+ * `TriggerBridge` adapts the context-injected button props to work with any
+ * plain HTML element (native `<button>`, custom components, etc.).
+ */
+declare function HeadlessMenuTrigger({ children, placement, shouldFlip, ...rest }: HeadlessMenuTriggerProps): JSX.Element;
+declare namespace HeadlessMenuTrigger {
+    var Menu: typeof HeadlessMenu;
+}
+/**
+ * Layer 2 headless primitive wrapping RAC `Menu`.
+ *
+ * When nested inside `HeadlessMenuTrigger`, RAC automatically threads the
+ * `MenuContext` (containing `autoFocus`, `onClose`, `aria-labelledby`, etc.)
+ * from `RACMenuTrigger` through to `RACMenu`. No manual prop threading needed.
+ *
+ * **aria-label / aria-labelledby precedence fix**: `RACSubmenuTrigger` sets
+ * `aria-labelledby` in `MenuContext` pointing to the trigger item. In ARIA
+ * spec, `aria-labelledby` always overrides `aria-label`. So when the consumer
+ * provides an explicit `aria-label`, we suppress the context's
+ * `aria-labelledby` by passing `aria-labelledby={undefined}`, which takes
+ * precedence over the `MenuContext` value in `useContextProps`'s `mergeProps`
+ * call (last argument wins). This ensures `aria-label="My Submenu"` is
+ * respected as the accessible name.
+ */
+declare function HeadlessMenu<T extends object = object>({ className, children, "aria-label": ariaLabel, ...props }: HeadlessMenuProps<T>): JSX.Element;
+/**
+ * Layer 2 headless primitive wrapping RAC `MenuItem`.
+ *
+ * Accepts `className` as either a static string or a render-prop function
+ * `(renderProps: MenuItemRenderProps) => string`, forwarding it directly to
+ * `RACMenuItem` so MD3 selection-state styles are applied on the `<li>` element
+ * (the element with `role="menuitem"`).
+ */
+declare const HeadlessMenuItem: React$1.ForwardRefExoticComponent<HeadlessMenuItemProps & React$1.RefAttributes<HTMLDivElement>>;
+declare function HeadlessMenuSection({ children, "aria-label": ariaLabel, className, }: HeadlessMenuSectionProps): JSX.Element;
+declare function HeadlessMenuDivider({ className, ...props }: SeparatorProps & {
+    className?: string;
+}): JSX.Element;
+
+/**
+ * Material Design 3 Menu container variants (CVA).
+ *
+ * Elevation: `shadow-elevation-2` (both styles)
+ * Width: min 112dp / max 280dp per MD3 spec
+ *
+ * Shape per menuStyle:
+ * - baseline: `rounded-xs` (4dp extra-small)
+ * - vertical: `rounded-lg` (16dp large)
+ *
+ * Background per colorScheme + menuStyle:
+ * - baseline + standard: `bg-surface-container`
+ * - vertical + standard: `bg-surface-container-low`
+ * - vertical + vibrant:  `bg-tertiary-container`
+ *
+ * @see https://m3.material.io/components/menus/specs
+ */
+declare const menuContainerVariants: (props?: ({
+    colorScheme?: "standard" | "vibrant" | null | undefined;
+    menuStyle?: "vertical" | "baseline" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type MenuContainerVariants = VariantProps<typeof menuContainerVariants>;
+
+/**
+ * Screen position of the Snackbar.
+ *
+ * MD3 default is `bottom-center`. All six positions are supported for
+ * application-specific layout needs (e.g. presence of a FAB or navigation bar).
+ *
+ * @default 'bottom-center'
+ */
+type SnackbarPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+/**
+ * Severity level of the Snackbar message.
+ *
+ * Controls the ARIA live region role:
+ * - `default` → `role="status" aria-live="polite"` (non-urgent information)
+ * - `error`   → `role="alert"  aria-live="assertive"` (urgent error messages)
+ *
+ * @default 'default'
+ */
+type SnackbarSeverity = "default" | "error";
+/**
+ * Internal animation state machine for the Snackbar.
+ *
+ * - `entering` → zoom-in start: scale-75 + opacity-0 (no duration, paints before transition)
+ * - `visible`  → scale-100 + opacity-100 (medium1 / standard-decelerate = 250ms)
+ * - `exiting`  → scale-75 + opacity-0 (short4 / standard-accelerate = 200ms)
+ * - `exited`   → removed from DOM / stack updated
+ */
+type SnackbarAnimationState = "entering" | "visible" | "exiting" | "exited";
+/**
+ * Configuration for the single text action button on the Snackbar.
+ *
+ * @example
+ * ```tsx
+ * action={{ label: "Undo", onAction: () => handleUndo() }}
+ * ```
+ */
+interface SnackbarAction {
+    /** Visible label for the action button. Also used as the accessible name. */
+    label: string;
+    /** Callback fired when the action button is pressed. */
+    onAction: () => void;
+}
+/**
+ * Props for the MD3 Styled `Snackbar` component (Layer 3).
+ *
+ * Renders one of four MD3 content configurations:
+ * 1. Single-line message only
+ * 2. Two-line (message + supportingText)
+ * 3. Single-line with action button
+ * 4. Single-line with close icon
+ *
+ * @example
+ * ```tsx
+ * // Single-line
+ * <Snackbar message="File deleted" />
+ *
+ * // With action
+ * <Snackbar message="File deleted" action={{ label: "Undo", onAction: handleUndo }} />
+ *
+ * // With close icon
+ * <Snackbar message="Connection lost" showClose onClose={() => {}} />
+ *
+ * // Error severity (assertive announcement)
+ * <Snackbar message="Upload failed" severity="error" />
+ * ```
+ */
+interface SnackbarProps {
+    /**
+     * Primary message text shown on the Snackbar.
+     * Styled with `text-body-medium`.
+     */
+    message: string;
+    /**
+     * Optional supporting text shown below the message (two-line configuration).
+     * Styled with `text-body-medium`.
+     */
+    supportingText?: string;
+    /**
+     * Optional text action button configuration.
+     * Action button is styled as `Button variant="text"` with `inverse-primary` color.
+     */
+    action?: SnackbarAction;
+    /**
+     * When `true`, renders a close icon button at the trailing end.
+     * @default false
+     */
+    showClose?: boolean;
+    /**
+     * Auto-dismiss duration in milliseconds. Set to `0` to disable auto-dismiss.
+     * Timer pauses on pointer hover and keyboard focus.
+     * @default 4000
+     */
+    duration?: number;
+    /**
+     * Severity level — controls the ARIA live region role.
+     * @default 'default'
+     */
+    severity?: SnackbarSeverity;
+    /**
+     * Screen position of the Snackbar.
+     * @default 'bottom-center'
+     */
+    position?: SnackbarPosition;
+    /**
+     * Callback fired when the Snackbar finishes its exit animation and is removed.
+     * Also fires when the close icon is pressed.
+     */
+    onClose?: () => void;
+    /**
+     * Additional CSS classes merged onto the Snackbar container.
+     */
+    className?: string;
+}
+/**
+ * Props for the headless `SnackbarHeadless` primitive (Layer 2).
+ *
+ * Provides all Snackbar behavior (ARIA live region, auto-dismiss timer with
+ * pause/resume, animation state machine) without any visual styling.
+ *
+ * @example
+ * ```tsx
+ * <SnackbarHeadless message="Hello" duration={3000} onClose={dismiss}>
+ *   {({ animationState }) => (
+ *     <div className={animationState === 'visible' ? 'opacity-100' : 'opacity-0'}>
+ *       Hello
+ *     </div>
+ *   )}
+ * </SnackbarHeadless>
+ * ```
+ */
+interface SnackbarHeadlessProps extends Omit<SnackbarProps, "className"> {
+    /**
+     * Children as a render function receiving the current animation state and
+     * an imperative `onClose` callback to trigger the exit animation, or
+     * static ReactNode content.
+     */
+    children?: ReactNode | ((state: {
+        animationState: SnackbarAnimationState;
+        onClose: () => void;
+    }) => ReactNode);
+    /**
+     * Additional CSS classes passed to the container element (base/structural classes).
+     */
+    className?: string;
+    /**
+     * Optional callback that returns additional CSS classes based on the current
+     * animation state and position. Used by the styled `Snackbar` layer to inject
+     * CVA animation + position variant classes onto the headless container div.
+     *
+     * @example
+     * ```tsx
+     * getAnimationClassName={(state, pos) =>
+     *   snackbarAnimationVariants({ animationState: state, enterDirection: getEnterDirection(pos) })
+     * }
+     * ```
+     */
+    getAnimationClassName?: (state: SnackbarAnimationState, position: SnackbarPosition) => string;
+}
+/**
+ * Internal queue entry type used by `SnackbarProvider`.
+ * Extends `SnackbarProps` with a unique `id` for queue management.
+ */
+interface SnackbarItem extends SnackbarProps {
+    /** Unique identifier for this Snackbar instance. */
+    id: string;
+}
+/**
+ * Value exposed by `SnackbarContext` and consumed via `useSnackbar`.
+ *
+ * @example
+ * ```tsx
+ * const { showSnackbar } = useSnackbar();
+ * showSnackbar({ message: "Saved successfully" });
+ * ```
+ */
+interface SnackbarContextValue {
+    /**
+     * Show a new Snackbar. Returns the unique id assigned to this item.
+     * Multiple snackbars are displayed simultaneously in a vertical stack,
+     * grouped by their `position` prop. Once the stack reaches `maxVisible`,
+     * additional items wait until existing ones are dismissed.
+     */
+    showSnackbar: (options: SnackbarProps) => string;
+    /**
+     * Imperatively dismiss the oldest currently displayed Snackbar (triggers exit animation).
+     */
+    closeSnackbar: () => void;
+}
+/**
+ * Props for `SnackbarProvider`.
+ *
+ * Wrap your application (or Storybook decorator) with this provider to enable
+ * the Snackbar stack and portal.
+ *
+ * @example
+ * ```tsx
+ * <SnackbarProvider>
+ *   <App />
+ * </SnackbarProvider>
+ *
+ * // Limit visible snackbars per position group
+ * <SnackbarProvider maxVisible={3}>
+ *   <App />
+ * </SnackbarProvider>
+ * ```
+ */
+interface SnackbarProviderProps {
+    /** Application children. */
+    children: ReactNode;
+    /**
+     * Maximum number of snackbars visible at once per position group.
+     * Additional snackbars beyond this cap are queued and shown as existing
+     * ones are dismissed.
+     * @default 5
+     */
+    maxVisible?: number;
+}
+
+/**
+ * `Snackbar` — Layer 3 MD3 Styled Component.
+ *
+ * Renders one of four MD3 Snackbar content configurations:
+ * 1. Single-line message only
+ * 2. Two-line message + `supportingText`
+ * 3. Single-line with text `action` button (styled `Button variant="text"` with
+ *    `inverse-primary` color per MD3 spec)
+ * 4. Single-line with close icon (or combined with action)
+ *
+ * Uses `SnackbarHeadless` for all behavioral concerns (ARIA live region,
+ * auto-dismiss timer with pause/resume, animation state machine) and CVA
+ * variants for MD3-compliant visual styling.
+ *
+ * For typical app usage, render inside `SnackbarProvider` and trigger via
+ * the `useSnackbar` hook. For declarative/test usage, it can be rendered
+ * standalone.
+ *
+ * @example
+ * ```tsx
+ * // Imperative via hook (typical)
+ * const { showSnackbar } = useSnackbar();
+ * showSnackbar({ message: "File deleted", action: { label: "Undo", onAction: handleUndo } });
+ *
+ * // Declarative standalone
+ * <SnackbarProvider>
+ *   <Snackbar message="Saved" severity="default" showClose onClose={() => {}} />
+ * </SnackbarProvider>
+ * ```
+ */
+declare const Snackbar: React$1.ForwardRefExoticComponent<SnackbarProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * SnackbarHeadless — Layer 2 headless primitive.
+ *
+ * Handles all Snackbar behavior without opinionated visual styling:
+ * - ARIA live region with correct `role`/`aria-live` pairing per severity
+ * - Auto-dismiss timer with configurable `duration`
+ * - Timer pause/resume on pointer hover (`mouseenter`/`mouseleave`) and
+ *   keyboard focus (`focusin`/`focusout`)
+ * - Animation state machine: `entering → visible → exiting → exited`
+ * - Exposes `onClose` imperative trigger via render-prop for close icon/action
+ * - Merges base `className` with animation-state-dependent classes via
+ *   the optional `getAnimationClassName` prop
+ *
+ * No React Aria hook covers Snackbar; ARIA live region patterns follow the
+ * ARIA authoring practices specification for status/alert regions.
+ *
+ * @example
+ * ```tsx
+ * // With render-prop children (typical usage from styled layer)
+ * <SnackbarHeadless
+ *   message="Saved"
+ *   duration={3000}
+ *   onClose={dismiss}
+ *   className={baseClasses}
+ *   getAnimationClassName={(state) => snackbarAnimationVariants({ animationState: state })}
+ * >
+ *   {({ onClose }) => (
+ *     <>
+ *       <span>Saved</span>
+ *       <button onClick={onClose}>Dismiss</button>
+ *     </>
+ *   )}
+ * </SnackbarHeadless>
+ * ```
+ */
+declare const SnackbarHeadless: React$1.ForwardRefExoticComponent<SnackbarHeadlessProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * React context for the Snackbar queue.
+ * Consumed via the `useSnackbar` hook.
+ */
+declare const SnackbarContext: React$1.Context<SnackbarContextValue | null>;
+/**
+ * `useSnackbar` — imperative API for triggering Snackbars.
+ *
+ * Must be called inside a component that is a descendant of `SnackbarProvider`.
+ * Throws a descriptive error in development if used outside the provider.
+ *
+ * @example
+ * ```tsx
+ * const { showSnackbar } = useSnackbar();
+ *
+ * // Single-line
+ * showSnackbar({ message: "File deleted" });
+ *
+ * // With action
+ * showSnackbar({
+ *   message: "File deleted",
+ *   action: { label: "Undo", onAction: () => handleUndo() },
+ * });
+ *
+ * // Error severity (assertive announcement)
+ * showSnackbar({ message: "Upload failed", severity: "error" });
+ * ```
+ */
+declare function useSnackbar(): SnackbarContextValue;
+/**
+ * `SnackbarProvider` — context provider, queue manager, and portal host.
+ *
+ * Wrap your application (or Storybook preview) with this component to enable
+ * the Snackbar stack and portal rendering.
+ *
+ * - Multiple `showSnackbar` calls are displayed simultaneously in a vertical
+ *   stack, grouped by their `position` prop.
+ * - Each position group is rendered in its own fixed container via `createPortal`
+ *   into `document.body`.
+ * - Bottom positions stack upward (newest at bottom); top positions stack
+ *   downward (newest at top).
+ * - The `maxVisible` prop caps how many snackbars can be visible at once per
+ *   position group. Snackbars beyond the cap are queued and shown as existing
+ *   ones are dismissed.
+ *
+ * @example
+ * ```tsx
+ * // Application root
+ * <SnackbarProvider>
+ *   <App />
+ * </SnackbarProvider>
+ *
+ * // With custom cap (default is 5)
+ * <SnackbarProvider maxVisible={3}>
+ *   <App />
+ * </SnackbarProvider>
+ *
+ * // Storybook preview.tsx decorator
+ * export const decorators = [
+ *   (Story) => (
+ *     <SnackbarProvider>
+ *       <Story />
+ *     </SnackbarProvider>
+ *   ),
+ * ];
+ * ```
+ */
+declare function SnackbarProvider({ children, maxVisible }: SnackbarProviderProps): JSX.Element;
+
+/**
+ * Structural variant of the MD3 Dialog.
+ *
+ * - `basic` — Floating dialog with headline, body, and action buttons.
+ *   Supports scale + fade entry animation. Closes on scrim click or Escape.
+ *   Max width 560dp per MD3 spec.
+ *
+ * - `fullscreen` — Full viewport overlay suited for mobile and complex forms.
+ *   Replaces headline with a top app bar row (close icon + confirm action).
+ *   Slide-up entry animation. Does NOT close on scrim click per MD3 spec.
+ *
+ * @default 'basic'
+ */
+type DialogVariant = "basic" | "fullscreen";
+/**
+ * Internal animation state machine for the Dialog.
+ *
+ * - `entering` — initial mount state before transition fires
+ * - `visible`  — fully shown, entry animation complete
+ * - `exiting`  — exit animation in progress
+ * - `exited`   — removed from DOM
+ */
+type DialogAnimationState = "entering" | "visible" | "exiting" | "exited";
+/**
+ * Internal context shared between `DialogHeadless` and its slot sub-components
+ * (`DialogHeadline`, `DialogContent`, `DialogActions`).
+ *
+ * Coordinates auto-generated `id` values for `aria-labelledby` and
+ * `aria-describedby`, exposes the close callback, and propagates the variant.
+ *
+ * @internal
+ */
+interface DialogContextValue {
+    /** Stable id for the headline element — used as `aria-labelledby` on the dialog panel. */
+    headlineId: string;
+    /** Stable id for the content element — used as `aria-describedby` on the dialog panel. */
+    contentId: string;
+    /** Callback to programmatically close the dialog (triggers exit animation). */
+    close: () => void;
+    /** Current structural variant, propagated to sub-components for variant-specific rendering. */
+    variant: DialogVariant;
+}
+/**
+ * Props for the headless `DialogHeadless` primitive (Layer 2).
+ *
+ * Provides all Dialog behavior (ARIA roles, focus trap, scroll lock,
+ * portal rendering, animation state machine, open/close state) without
+ * any visual styling.
+ *
+ * @example
+ * ```tsx
+ * <DialogHeadless
+ *   variant="basic"
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   aria-label="Confirm action"
+ *   className="bg-surface-container-high rounded-xl shadow-elevation-3"
+ *   scrimClassName="fixed inset-0 z-40 bg-scrim opacity-32"
+ * >
+ *   <DialogHeadline>Confirm deletion?</DialogHeadline>
+ *   <DialogContent>This action cannot be undone.</DialogContent>
+ *   <DialogActions>
+ *     <Button variant="text" onPress={() => setOpen(false)}>Cancel</Button>
+ *     <Button variant="filled" onPress={handleDelete}>Delete</Button>
+ *   </DialogActions>
+ * </DialogHeadless>
+ * ```
+ */
+interface DialogHeadlessProps {
+    /**
+     * Structural variant — controls animation, scrim dismissal, and DOM structure.
+     * @default 'basic'
+     */
+    variant?: DialogVariant;
+    /**
+     * Controlled open state. Pair with `onOpenChange`.
+     */
+    open?: boolean;
+    /**
+     * Default open state for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Called when the open state changes (e.g. Escape key, scrim click, close button).
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Accessible label for the dialog. Used when no `DialogHeadline` is provided.
+     * When `DialogHeadline` is present, `aria-labelledby` is preferred automatically.
+     */
+    "aria-label"?: string;
+    /**
+     * Dialog slot content — typically `DialogHeadline`, `DialogContent`, `DialogActions`.
+     */
+    children: ReactNode;
+    /**
+     * Additional CSS classes applied to the dialog panel element.
+     */
+    className?: string;
+    /**
+     * Additional CSS classes applied to the scrim overlay element.
+     */
+    scrimClassName?: string;
+    /**
+     * Additional CSS classes injected based on the current animation state.
+     * Called at render time to merge CVA animation classes onto the panel.
+     *
+     * @example
+     * ```tsx
+     * getAnimationClassName={(state) => dialogAnimationVariants({ animationState: state, variant })}
+     * ```
+     */
+    getAnimationClassName?: (state: DialogAnimationState) => string;
+}
+/**
+ * Props for the MD3 Styled `Dialog` component (Layer 3).
+ *
+ * Supports two structural variants — Basic (floating dialog) and Full-screen
+ * (full viewport overlay for mobile / complex forms) — with a composable
+ * slot-based API via `DialogHeadline`, `DialogContent`, and `DialogActions`.
+ *
+ * Supports both controlled (`open` + `onOpenChange`) and uncontrolled
+ * (`defaultOpen`) usage patterns.
+ *
+ * @example
+ * ```tsx
+ * // Basic dialog (controlled)
+ * <Dialog open={open} onOpenChange={setOpen}>
+ *   <DialogHeadline>Delete file?</DialogHeadline>
+ *   <DialogContent>This action cannot be undone.</DialogContent>
+ *   <DialogActions>
+ *     <Button variant="text" onPress={() => setOpen(false)}>Cancel</Button>
+ *     <Button variant="filled" onPress={handleDelete}>Delete</Button>
+ *   </DialogActions>
+ * </Dialog>
+ *
+ * // Full-screen dialog (controlled)
+ * <Dialog variant="fullscreen" open={open} onOpenChange={setOpen}>
+ *   <DialogHeadline
+ *     closeButton={<IconButton aria-label="Close" onPress={() => setOpen(false)}><CloseIcon /></IconButton>}
+ *     confirmButton={<Button variant="text" onPress={handleSave}>Save</Button>}
+ *   >
+ *     New event
+ *   </DialogHeadline>
+ *   <DialogContent>
+ *     <TextField label="Event name" />
+ *   </DialogContent>
+ * </Dialog>
+ * ```
+ */
+interface DialogProps {
+    /**
+     * Structural variant — `basic` (default) or `fullscreen`.
+     * @default 'basic'
+     */
+    variant?: DialogVariant;
+    /**
+     * Controlled open state. Pair with `onOpenChange`.
+     */
+    open?: boolean;
+    /**
+     * Default open state for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Called when the open state changes.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Accessible label for the dialog when no `DialogHeadline` is present.
+     */
+    "aria-label"?: string;
+    /**
+     * Dialog slot content — `DialogHeadline`, `DialogContent`, `DialogActions`.
+     */
+    children: ReactNode;
+    /**
+     * Additional CSS classes merged onto the dialog panel element.
+     */
+    className?: string;
+}
+/**
+ * Props for the `DialogHeadline` slot sub-component.
+ *
+ * Renders as an `<h2>` element and provides its `id` to `DialogContext`
+ * so the parent dialog panel can reference it via `aria-labelledby`.
+ *
+ * For the `fullscreen` variant, accepts optional `closeButton` and
+ * `confirmButton` slots that are rendered in the top app bar row per MD3 spec.
+ *
+ * @example
+ * ```tsx
+ * // Basic variant
+ * <DialogHeadline>Confirm deletion?</DialogHeadline>
+ *
+ * // Full-screen variant
+ * <DialogHeadline
+ *   closeButton={<IconButton aria-label="Close" onPress={onClose}><CloseIcon /></IconButton>}
+ *   confirmButton={<Button variant="text" onPress={onSave}>Save</Button>}
+ * >
+ *   New event
+ * </DialogHeadline>
+ * ```
+ */
+interface DialogHeadlineProps {
+    /**
+     * Headline text content.
+     */
+    children: ReactNode;
+    /**
+     * Additional CSS classes merged onto the headline element.
+     */
+    className?: string;
+    /**
+     * Close icon button slot — rendered leading in the top app bar row
+     * for the `fullscreen` variant only.
+     */
+    closeButton?: ReactNode;
+    /**
+     * Confirm action slot — rendered trailing in the top app bar row
+     * for the `fullscreen` variant only.
+     */
+    confirmButton?: ReactNode;
+}
+/**
+ * Props for the `DialogContent` slot sub-component.
+ *
+ * Renders as a scrollable `<div>` and provides its `id` to `DialogContext`
+ * so the parent dialog panel can reference it via `aria-describedby`.
+ *
+ * @example
+ * ```tsx
+ * <DialogContent>
+ *   <p>This action cannot be undone. All associated data will be permanently removed.</p>
+ * </DialogContent>
+ * ```
+ */
+interface DialogContentProps {
+    /**
+     * Body content — can be any React node.
+     */
+    children: ReactNode;
+    /**
+     * Additional CSS classes merged onto the content element.
+     */
+    className?: string;
+}
+/**
+ * Props for the `DialogActions` slot sub-component.
+ *
+ * Renders a right-aligned flex row of action buttons per MD3 spec.
+ * Typically contains `Button` components with `variant="text"` (secondary)
+ * and `variant="filled"` (primary action).
+ *
+ * Not used in the `fullscreen` variant (confirm action is in the headline row).
+ *
+ * @example
+ * ```tsx
+ * <DialogActions>
+ *   <Button variant="text" onPress={onCancel}>Cancel</Button>
+ *   <Button variant="filled" onPress={onConfirm}>Confirm</Button>
+ * </DialogActions>
+ * ```
+ */
+interface DialogActionsProps {
+    /**
+     * Action button elements — typically `Button` components.
+     */
+    children: ReactNode;
+    /**
+     * Additional CSS classes merged onto the actions container.
+     */
+    className?: string;
+}
+
+/**
+ * `Dialog` — Layer 3 MD3 Styled Dialog Component.
+ *
+ * Supports two structural variants per MD3 spec, with a composable slot-based
+ * API via `DialogHeadline`, `DialogContent`, and `DialogActions`:
+ *
+ * **Basic** (default):
+ * - Floating card: `bg-surface-container-high`, `rounded-xl`, `shadow-elevation-3`
+ * - Centered in viewport (min 280dp, max 560dp width)
+ * - Scale + fade entry animation (`duration-medium4 / ease-emphasized-decelerate`)
+ * - Fade exit animation (`duration-short2 / ease-emphasized-accelerate`)
+ * - Closes on scrim click or Escape key
+ *
+ * **Full-screen**:
+ * - Full viewport coverage — suited for mobile and complex forms
+ * - No rounded corners, no elevation shadow
+ * - Slide-up entry / slide-down exit animation
+ * - Does NOT close on scrim click per MD3 spec (only via Escape or close button)
+ * - Headline replaced by top app bar row (close icon + confirm action)
+ *
+ * Both variants:
+ * - `role="dialog"` + `aria-modal="true"` (React Aria `useDialog`)
+ * - `aria-labelledby` pointing to `DialogHeadline` id
+ * - `aria-describedby` pointing to `DialogContent` id
+ * - Focus trap active while open (`FocusScope`)
+ * - Focus returns to trigger element on close (`FocusScope restoreFocus`)
+ * - Body scroll locked while open (`usePreventScroll`)
+ * - Escape key always closes the dialog
+ * - Portal rendered to `document.body`
+ *
+ * @example
+ * ```tsx
+ * // Basic dialog — controlled
+ * function DeleteDialog() {
+ *   const [open, setOpen] = useState(false);
+ *
+ *   return (
+ *     <>
+ *       <Button onPress={() => setOpen(true)}>Delete file</Button>
+ *       <Dialog open={open} onOpenChange={setOpen}>
+ *         <DialogHeadline>Permanently delete?</DialogHeadline>
+ *         <DialogContent>
+ *           This action cannot be undone. The file and all associated data
+ *           will be permanently removed.
+ *         </DialogContent>
+ *         <DialogActions>
+ *           <Button variant="text" onPress={() => setOpen(false)}>Cancel</Button>
+ *           <Button variant="filled" onPress={handleDelete}>Delete</Button>
+ *         </DialogActions>
+ *       </Dialog>
+ *     </>
+ *   );
+ * }
+ *
+ * // Full-screen dialog — mobile form flow
+ * function NewEventDialog() {
+ *   const [open, setOpen] = useState(false);
+ *
+ *   return (
+ *     <>
+ *       <Button onPress={() => setOpen(true)}>New event</Button>
+ *       <Dialog variant="fullscreen" open={open} onOpenChange={setOpen}>
+ *         <DialogHeadline
+ *           closeButton={
+ *             <IconButton aria-label="Close" onPress={() => setOpen(false)}>
+ *               <CloseIcon />
+ *             </IconButton>
+ *           }
+ *           confirmButton={
+ *             <Button variant="text" onPress={handleSave}>Save</Button>
+ *           }
+ *         >
+ *           New event
+ *         </DialogHeadline>
+ *         <DialogContent>
+ *           <TextField label="Event name" />
+ *           <TextField label="Date" type="date" />
+ *         </DialogContent>
+ *       </Dialog>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @see https://m3.material.io/components/dialogs/overview
+ * @see https://m3.material.io/components/dialogs/specs
+ */
+declare const Dialog: React$1.ForwardRefExoticComponent<DialogProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * `DialogHeadline` — Headline slot sub-component (Layer 3).
+ *
+ * Renders as an `<h2>` element and registers its `id` with the parent
+ * `DialogContext` so the dialog panel can wire `aria-labelledby` correctly.
+ *
+ * For the `fullscreen` variant, the headline renders as a top app bar row
+ * containing optional `closeButton` (leading icon button) and `confirmButton`
+ * (trailing text action) per MD3 Full-screen Dialog spec.
+ *
+ * Must be rendered inside a `<Dialog>` or `<DialogHeadless>` component.
+ *
+ * @example
+ * ```tsx
+ * // Basic variant
+ * <Dialog open onOpenChange={setOpen}>
+ *   <DialogHeadline>Delete file?</DialogHeadline>
+ *   ...
+ * </Dialog>
+ *
+ * // Full-screen variant with app bar controls
+ * <Dialog variant="fullscreen" open onOpenChange={setOpen}>
+ *   <DialogHeadline
+ *     closeButton={
+ *       <IconButton aria-label="Close" onPress={() => setOpen(false)}>
+ *         <CloseIcon />
+ *       </IconButton>
+ *     }
+ *     confirmButton={
+ *       <Button variant="text" onPress={handleSave}>Save</Button>
+ *     }
+ *   >
+ *     New event
+ *   </DialogHeadline>
+ *   ...
+ * </Dialog>
+ * ```
+ */
+declare const DialogHeadline: React$1.ForwardRefExoticComponent<DialogHeadlineProps & React$1.RefAttributes<HTMLHeadingElement>>;
+
+/**
+ * `DialogContent` — Scrollable body slot sub-component (Layer 3).
+ *
+ * Renders as a scrollable `<div>` and registers its `id` with the parent
+ * `DialogContext` so the dialog panel can wire `aria-describedby` correctly.
+ *
+ * Styled with `text-body-medium` and `text-on-surface-variant` per MD3 spec.
+ * Overflows vertically when content exceeds the available height.
+ *
+ * Must be rendered inside a `<Dialog>` or `<DialogHeadless>` component.
+ *
+ * @example
+ * ```tsx
+ * <Dialog open onOpenChange={setOpen}>
+ *   <DialogHeadline>Confirm deletion?</DialogHeadline>
+ *   <DialogContent>
+ *     <p>
+ *       This will permanently delete the file and all associated data.
+ *       This action cannot be undone.
+ *     </p>
+ *   </DialogContent>
+ *   <DialogActions>
+ *     <Button variant="text" onPress={() => setOpen(false)}>Cancel</Button>
+ *     <Button variant="filled" onPress={handleDelete}>Delete</Button>
+ *   </DialogActions>
+ * </Dialog>
+ * ```
+ */
+declare const DialogContent: React$1.ForwardRefExoticComponent<DialogContentProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * `DialogActions` — Action button row slot sub-component (Layer 3).
+ *
+ * Renders a right-aligned flex row of action buttons per MD3 spec.
+ * Intended to contain `Button` components (typically `variant="text"` for
+ * secondary actions and `variant="filled"` for the primary action).
+ *
+ * Not used in the `fullscreen` variant — the confirm action is placed in the
+ * headline top app bar row via `DialogHeadline`'s `confirmButton` slot.
+ *
+ * Must be rendered inside a `<Dialog>` or `<DialogHeadless>` component.
+ *
+ * @example
+ * ```tsx
+ * <Dialog open onOpenChange={setOpen}>
+ *   <DialogHeadline>Discard changes?</DialogHeadline>
+ *   <DialogContent>Your unsaved changes will be lost.</DialogContent>
+ *   <DialogActions>
+ *     <Button variant="text" onPress={() => setOpen(false)}>Cancel</Button>
+ *     <Button variant="filled" onPress={handleDiscard}>Discard</Button>
+ *   </DialogActions>
+ * </Dialog>
+ * ```
+ */
+declare const DialogActions: React$1.ForwardRefExoticComponent<DialogActionsProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Context shared between `DialogHeadless` and slot sub-components
+ * (`DialogHeadline`, `DialogContent`, `DialogActions`).
+ *
+ * Provides stable IDs for aria-labelledby / aria-describedby wiring,
+ * the close callback, and the active variant.
+ *
+ * @internal
+ */
+declare const DialogContext: React__default.Context<DialogContextValue | null>;
+/**
+ * Hook to consume `DialogContext` inside dialog slot sub-components.
+ * Throws a descriptive error if used outside a `DialogHeadless` tree.
+ *
+ * @internal
+ */
+declare function useDialogContext(): DialogContextValue;
+/**
+ * `DialogHeadless` — Layer 2 headless primitive.
+ *
+ * Provides all MD3 Dialog behavior and ARIA semantics without any visual styling:
+ *
+ * - **Portal rendering**: dialog and scrim render in `document.body` via
+ *   `createPortal` to avoid stacking context issues.
+ * - **Open/close state**: via `useOverlayTriggerState` (supports controlled
+ *   `open` + `onOpenChange` and uncontrolled `defaultOpen`).
+ * - **Scroll lock**: `usePreventScroll` locks body scroll while open.
+ * - **Focus trap**: `FocusScope` with `contain`, `restoreFocus`, `autoFocus`.
+ * - **Dismiss behavior**: `useOverlay` handles Escape key and outside click.
+ *   Basic variant is dismissable (Escape + outside click);
+ *   Full-screen variant is Escape-dismissable only (no scrim click) per MD3 spec.
+ * - **Animation state machine**: `entering → visible → exiting → exited`
+ *   mirrors the Snackbar animation pattern.
+ * - **ARIA wiring**: `DialogContext` provides stable IDs for `aria-labelledby`
+ *   and `aria-describedby`, consumed by slot sub-components.
+ *
+ * React Aria hooks used:
+ * - `useDialog` — `role="dialog"`, `aria-modal`, `aria-labelledby`, `aria-describedby`
+ * - `useOverlay` — Escape key + outside-click dismissal
+ * - `usePreventScroll` — body scroll lock
+ * - `FocusScope` — focus trap + restoreFocus on close
+ * - `useOverlayTriggerState` — open/close state management
+ *
+ * @example
+ * ```tsx
+ * // Controlled basic dialog
+ * <DialogHeadless
+ *   variant="basic"
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   className={cn(dialogWrapperVariants({ variant: 'basic' }), dialogPanelVariants({ variant: 'basic' }))}
+ *   scrimClassName={dialogScrimVariants()}
+ *   getAnimationClassName={(state) =>
+ *     dialogAnimationVariants({ animationState: state, variant: 'basic' })
+ *   }
+ * >
+ *   <DialogHeadline>Confirm?</DialogHeadline>
+ *   <DialogContent>This action cannot be undone.</DialogContent>
+ *   <DialogActions>
+ *     <Button variant="text" onPress={() => setOpen(false)}>Cancel</Button>
+ *     <Button variant="filled" onPress={handleDelete}>Delete</Button>
+ *   </DialogActions>
+ * </DialogHeadless>
+ * ```
+ */
+declare const DialogHeadless: React__default.ForwardRefExoticComponent<DialogHeadlessProps & React__default.RefAttributes<HTMLDivElement>>;
+
+export { AppBar, AppBarHeadless, type AppBarHeadlessProps, type AppBarProps, type AppBarVariant, Button, type ButtonColor, type ButtonProps, type ButtonSize, type ButtonVariant, Checkbox, type CheckboxProps, Dialog, DialogActions, type DialogActionsProps, type DialogAnimationState, DialogContent, type DialogContentProps, DialogContext, type DialogContextValue, DialogHeadless, type DialogHeadlessProps, DialogHeadline, type DialogHeadlineProps, type DialogProps, type DialogVariant, Drawer, type DrawerContextValue, DrawerItem, type DrawerItemProps, type DrawerProps, DrawerSection, type DrawerSectionProps, type DrawerVariant, FAB, type FABColor, FABHeadless, type FABHeadlessProps, type FABProps, type FABSize, HeadlessDrawer, HeadlessDrawerItem, type HeadlessDrawerItemProps, type HeadlessDrawerProps, HeadlessMenu, HeadlessMenuDivider, HeadlessMenuItem, type HeadlessMenuItemProps, type HeadlessMenuProps, HeadlessMenuSection, type HeadlessMenuSectionProps, HeadlessMenuTrigger, type HeadlessMenuTriggerProps, HeadlessNavigationBar, HeadlessNavigationBarItem, type HeadlessNavigationBarItemProps, type HeadlessNavigationBarProps, HeadlessTab, HeadlessTabList, HeadlessTabPanel, type HeadlessTabPanelProps, type HeadlessTabProps, IconButton, type IconButtonColor, IconButtonHeadless, type IconButtonHeadlessProps, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type MD3ColorRole, type MD3TypographyScale, type MD3TypographySize, type MD3TypographyStyle, Menu, type MenuContainerVariants, MenuContext, type MenuContextValue, MenuDivider, type MenuDividerProps, MenuItem, type MenuItemProps, type MenuProps, MenuSection, type MenuSectionProps, MenuTrigger, type MenuTriggerProps, NavigationBar, type NavigationBarBadge, NavigationBarItem, type NavigationBarItemConfig, type NavigationBarItemProps, type NavigationBarItemRenderProps, type NavigationBarProps, Progress, ProgressHeadless, type ProgressHeadlessProps, type ProgressProps, Radio, RadioGroup, RadioGroupHeadless, type RadioGroupHeadlessProps, type RadioGroupProps, RadioHeadless, type RadioHeadlessProps, type RadioProps, STATE_LAYER_OPACITY, Snackbar, type SnackbarAction, SnackbarContext, type SnackbarContextValue, SnackbarHeadless, type SnackbarHeadlessProps, type SnackbarItem, type SnackbarProps, SnackbarProvider, type SnackbarProviderProps, type SnackbarSeverity, Switch, type SwitchProps, TYPOGRAPHY_ELEMENT_MAP, TYPOGRAPHY_USAGE, Tab, type TabItem, type TabLayout, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, type TabVariant, Tabs, type TabsProps, TextField, type TextFieldProps, type TextFieldSize, type TextFieldVariant, type TypographyProperty, type TypographyStyleObject, applyStateLayer, cn, generateMD3Theme, getColorValue, getFontFamily, getMD3Color, getResponsiveTypography, getTypographyClassName, getTypographyForElement, getTypographyStyle, getTypographyToken, hexToRgb, pxToRem, remToPx, rgbToHex, truncateText, useDialogContext, useMenuContext, useSnackbar, withOpacity };