@tinybigui/react 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -2,18 +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, ButtonHTMLAttributes } 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, AriaTabProps, AriaTabPanelProps, Key as Key$1, AriaDialogProps, AriaLinkOptions } from 'react-aria';
-import { Key } from 'react-stately';
+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
@@ -21,10 +23,16 @@ import { Key } from 'react-stately';
  * // => '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;
@@ -700,7 +708,7 @@ declare const AppBarHeadless: React$1.ForwardRefExoticComponent<AppBarHeadlessPr
 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;
@@ -906,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;
@@ -1138,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;
@@ -3391,4 +3399,1523 @@ declare const HeadlessDrawer: React__default.ForwardRefExoticComponent<HeadlessD
  */
 declare const HeadlessDrawerItem: React__default.ForwardRefExoticComponent<HeadlessDrawerItemProps & React__default.RefAttributes<HTMLElement>>;
 
-export { AppBar, AppBarHeadless, type AppBarHeadlessProps, type AppBarProps, type AppBarVariant, Button, type ButtonColor, type ButtonProps, type ButtonSize, type ButtonVariant, Checkbox, type CheckboxProps, 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, 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, NavigationBar, type NavigationBarBadge, NavigationBarItem, type NavigationBarItemConfig, type NavigationBarItemProps, type NavigationBarItemRenderProps, type NavigationBarProps, Radio, RadioGroup, RadioGroupHeadless, type RadioGroupHeadlessProps, type RadioGroupProps, RadioHeadless, type RadioHeadlessProps, type RadioProps, STATE_LAYER_OPACITY, 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, withOpacity };
+/**
+ * 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 };