@tinybigui/react 0.4.2 → 0.6.0

package/dist/index.d.ts

@@ -1411,53 +1411,48 @@ declare function useOptionalButtonGroup(): ButtonGroupContextValue | null;
 declare function getConnectedRadiusClasses(ctx: ButtonGroupContextValue, value?: string): readonly string[];
 
 /**
- * Material Design 3 IconButton Variants (CVA)
- *
- * Type-safe variant management for IconButton component.
- * Uses Tailwind CSS classes mapped to MD3 design tokens.
- *
- * Key differences from Button:
- * - Circular shape (not pill-shaped)
- * - Fixed square dimensions
- * - No text content support
- * - 'standard' variant instead of 'elevated'
+ * IconButton variant types (MD3 specification)
  */
-declare const iconButtonVariants: (props?: ({
-    variant?: "filled" | "outlined" | "tonal" | "standard" | null | undefined;
-    color?: "primary" | "secondary" | "tertiary" | "error" | null | undefined;
-    size?: "small" | "large" | "medium" | null | undefined;
-    selected?: boolean | null | undefined;
-    isDisabled?: boolean | null | undefined;
-} & class_variance_authority_types.ClassProp) | undefined) => string;
+type IconButtonVariant = "standard" | "filled" | "tonal" | "outlined";
 /**
- * Extract variant prop types from CVA
+ * Color scheme (MD3 color roles)
  */
-type IconButtonVariants = VariantProps<typeof iconButtonVariants>;
-
+type IconButtonColor = "primary" | "secondary" | "tertiary" | "error";
 /**
- * IconButton variant types (MD3 specification)
+ * Icon button sizes — M3 Expressive 5-tier system.
+ *
+ * Container heights (dp → px):
+ * - xsmall: 32dp
+ * - small:  40dp
+ * - medium: 56dp (default)
+ * - large:  96dp
+ * - xlarge: 136dp
  */
-type IconButtonVariant = "standard" | "filled" | "tonal" | "outlined";
+type IconButtonSize = "xsmall" | "small" | "medium" | "large" | "xlarge";
 /**
- * Color scheme
+ * Width variant — adjusts container width relative to height.
+ * - narrow: narrower than height
+ * - default: same width as height (square container)
+ * - wide: wider than height
  */
-type IconButtonColor = "primary" | "secondary" | "tertiary" | "error";
+type IconButtonWidth = "narrow" | "default" | "wide";
 /**
- * IconButton sizes (square dimensions)
+ * Shape variant — controls corner rounding.
+ * - round: fully circular (rounded-full)
+ * - square: size-tiered corner radius (MD3 shape scale)
  */
-type IconButtonSize = "small" | "medium" | "large";
+type IconButtonShape = "round" | "square";
 /**
- * Material Design 3 IconButton Component Props
+ * Material Design 3 Expressive IconButton Component Props
  *
- * Icon-only button component with 4 variants and mandatory accessibility.
- *
- * **Key Features:**
+ * Icon-only button component following the M3 Expressive spec with:
+ * - 5 sizes: xsmall, small, medium (default), large, xlarge
+ * - 3 width options: narrow, default, wide
+ * - 2 shapes: round (circular), square (corner-radius scale)
+ * - Press shape-morph: corners tighten on press when `shape="round"`
+ * - Toggle support: `selected` + `selectedIcon`
  * - 4 variants: standard, filled, tonal, outlined
- * - Icon only (no text content)
- * - Circular shape (MD3 specification)
  * - Mandatory `aria-label` for accessibility
- * - Toggle support with `selected` prop
- * - 48×48px minimum touch target
  *
  * @example
  * ```tsx
@@ -1471,13 +1466,19 @@ type IconButtonSize = "small" | "medium" | "large";
  *   <IconHeart />
  * </IconButton>
  *
- * // Toggle button
+ * // Toggle button with selectedIcon
  * <IconButton
  *   aria-label={isFavorite ? "Remove from favorites" : "Add to favorites"}
  *   selected={isFavorite}
  *   onPress={() => setIsFavorite(!isFavorite)}
+ *   selectedIcon={<IconStarFilled />}
  * >
- *   {isFavorite ? <IconStarFilled /> : <IconStarOutline />}
+ *   <IconStarOutline />
+ * </IconButton>
+ *
+ * // Large square shape
+ * <IconButton aria-label="Settings" size="large" shape="square">
+ *   <IconSettings />
  * </IconButton>
  *
  * // Disabled
@@ -1498,21 +1499,48 @@ interface IconButtonProps extends AriaButtonProps {
      */
     color?: IconButtonColor;
     /**
-     * Size variant
+     * Size tier (M3 Expressive 5-tier system)
      * @default 'medium'
      */
     size?: IconButtonSize;
     /**
-     * Icon content (React node). Recommended size:
-     * - small: 20×20px
-     * - medium: 24×24px
-     * - large: 28×28px
+     * Container width relative to height.
+     * - `narrow`: slimmer than the container height
+     * - `default`: square container (width = height)
+     * - `wide`: wider than the container height
+     *
+     * @default 'default'
+     */
+    width?: IconButtonWidth;
+    /**
+     * Corner shape.
+     * - `round`: fully circular (pill-shaped)
+     * - `square`: size-tiered corner radius from the MD3 shape scale
+     *
+     * Applies a press shape-morph (corners tighten on press, spring back on release).
+     *
+     * @default 'round'
+     */
+    shape?: IconButtonShape;
+    /**
+     * Icon content. Recommended icon sizes per container size:
+     * - xsmall: 20×20px
+     * - small / medium: 24×24px
+     * - large: 32×32px
+     * - xlarge: 40×40px
      */
     children: React__default.ReactNode;
     /**
-     * Toggle state (for toggle buttons)
-     * When true, button shows selected state
-     * @default false
+     * Icon to display when `selected` is `true`.
+     * When provided with a `selected` prop the button becomes a toggle button.
+     * If omitted, `children` is shown in both states.
+     */
+    selectedIcon?: React__default.ReactNode;
+    /**
+     * Toggle state.
+     * When defined (even as `false`) the button behaves as a toggle button and
+     * `aria-pressed` is set.
+     * @default undefined
      */
     selected?: boolean;
     /**
@@ -1531,8 +1559,8 @@ interface IconButtonProps extends AriaButtonProps {
      */
     value?: string;
     /**
-     * HTML title attribute for tooltip
-     * Recommended for better UX on desktop
+     * HTML title attribute for tooltip.
+     * Recommended for better UX on desktop.
      */
     title?: string;
     /**
@@ -1540,8 +1568,8 @@ interface IconButtonProps extends AriaButtonProps {
      */
     onMouseDown?: (e: React__default.MouseEvent<HTMLButtonElement>) => void;
     /**
-     * REQUIRED: Accessible label for screen readers
-     * Since IconButton has no visible text, this is mandatory
+     * REQUIRED: Accessible label for screen readers.
+     * Since IconButton has no visible text, this is mandatory.
      *
      * @example
      * aria-label="Delete item"
@@ -1552,19 +1580,27 @@ interface IconButtonProps extends AriaButtonProps {
 }
 
 /**
- * Material Design 3 IconButton Component
+ * Material Design 3 Expressive — IconButton Component (Layer 3: Styled)
  *
- * Icon-only button component following MD3 specifications.
- * Supports 4 variants, toggle mode, and enforces accessibility.
+ * Built on React Aria for world-class accessibility. Implements the
+ * Variants-vs-States architecture: all interaction/selection states are
+ * expressed as data-* attributes (emitted by IconButtonHeadless) and consumed
+ * by each slot via group-data-[x]/icon-button Tailwind selectors — no state
+ * variants in CVA.
  *
- * **Key Features:**
- * - 4 variants: standard, filled, tonal, outlined
- * - Circular shape (MD3 specification)
- * - Mandatory `aria-label` for accessibility
- * - Toggle support with `selected` prop
- * - Ripple effect on interaction
- * - 48×48px minimum touch target
- * - ButtonGroup-aware: applies connected corner radii and min-width when inside a group
+ * Features:
+ * - ✅ M3 Expressive 5-tier sizes: xsmall, small, medium, large, xlarge
+ * - ✅ 3 width options: narrow, default, wide
+ * - ✅ 2 shapes: round (circular), square (MD3 corner scale)
+ * - ✅ Press shape-morph (round shape springs into square corner on press)
+ * - ✅ 4 variants: standard, filled, tonal, outlined
+ * - ✅ 4 color roles: primary, secondary, tertiary, error
+ * - ✅ Toggle support (selected + selectedIcon)
+ * - ✅ MD3-correct state layer: per-variant color, opacity-8/10/10
+ * - ✅ MD3-correct disabled: content opacity-38 + container on-surface/12
+ * - ✅ Ripple effect on press
+ * - ✅ ButtonGroup-aware: connected corner radii + min-width
+ * - ✅ Mandatory aria-label for accessibility
  *
  * @example
  * ```tsx
@@ -1573,226 +1609,343 @@ interface IconButtonProps extends AriaButtonProps {
  *   <IconDelete />
  * </IconButton>
  *
- * // Filled with color
- * <IconButton aria-label="Favorite" variant="filled" color="error">
+ * // Filled with color, large
+ * <IconButton aria-label="Favorite" variant="filled" color="error" size="large">
  *   <IconHeart />
  * </IconButton>
  *
- * // Toggle button
+ * // Toggle button with selectedIcon
  * <IconButton
  *   aria-label={selected ? "Remove favorite" : "Add favorite"}
  *   selected={selected}
  *   onPress={() => setSelected(!selected)}
+ *   selectedIcon={<IconStarFilled />}
  * >
- *   {selected ? <IconStarFilled /> : <IconStarOutline />}
+ *   <IconStarOutline />
  * </IconButton>
  *
- * // Inside a connected ButtonGroup (corner radii applied automatically)
- * <ButtonGroup variant="connected" selectionMode="multi" aria-label="Quick settings">
- *   <IconButton aria-label="Bluetooth"><BluetoothIcon /></IconButton>
- *   <IconButton aria-label="Wi-Fi"><WifiIcon /></IconButton>
- * </ButtonGroup>
+ * // Square shape, wide width
+ * <IconButton aria-label="Menu" shape="square" width="wide" size="medium">
+ *   <IconMenu />
+ * </IconButton>
  * ```
  */
-declare const IconButton: React__default.ForwardRefExoticComponent<IconButtonProps & Omit<IconButtonVariants, "isDisabled" | "selected"> & React__default.RefAttributes<HTMLButtonElement>>;
+declare const IconButton: React__default.ForwardRefExoticComponent<IconButtonProps & React__default.RefAttributes<HTMLButtonElement>>;
 
 /**
  * Headless IconButton Component (Layer 2)
  *
  * Unstyled icon button primitive using React Aria for accessibility.
- * Provides behavior only - bring your own styles.
+ * Provides behavior AND emits MD3-compliant data-* interaction attributes
+ * so the styled Layer 3 can drive all visual states through CSS alone.
+ *
+ * Emitted data attributes (via getInteractionDataAttributes):
+ * - `data-hovered`       — pointer is over the button
+ * - `data-focus-visible` — keyboard/programmatic focus is visible
+ * - `data-pressed`       — button is being pressed
+ * - `data-selected`      — toggle button is in the ON state
+ * - `data-disabled`      — button is non-interactive
+ *
+ * Content flags (set explicitly):
+ * - `data-toggle`        — button is a toggle (selected prop is defined)
  *
  * Features:
  * - Full keyboard navigation (Enter, Space)
- * - Screen reader support
+ * - Screen reader support (aria-pressed for toggle buttons)
  * - Touch/pointer event handling
  * - Focus management
+ * - Hover detection (useHover — pointer-only, not keyboard)
  * - Disabled state handling
- * - Toggle button support (aria-pressed)
  *
  * @example
  * ```tsx
- * // Use for custom styling
- * <IconButtonHeadless className="custom-icon-button-class" aria-label="Delete">
+ * // Advanced custom styling
+ * <IconButtonHeadless
+ *   aria-label="Delete"
+ *   className="group/icon-button my-custom-classes"
+ *   isSelected={false}
+ *   isToggle={false}
+ *   isDisabled={false}
+ * >
  *   <IconDelete />
  * </IconButtonHeadless>
  * ```
  */
 interface IconButtonHeadlessProps extends AriaButtonProps {
-    /**
-     * Additional CSS classes
-     */
+    /** Additional CSS classes */
     className?: string;
-    /**
-     * Icon content (React node)
-     */
+    /** Icon content */
     children: React.ReactNode;
-    /**
-     * Tab index for keyboard navigation
-     * @default 0
-     */
+    /** Tab index for keyboard navigation @default 0 */
     tabIndex?: number;
-    /**
-     * Mouse down handler (for ripple effect)
-     */
+    /** Mouse down handler (for ripple effect) */
     onMouseDown?: (e: React.MouseEvent<HTMLButtonElement>) => void;
-    /**
-     * Button type attribute
-     * @default 'button'
-     */
+    /** Button type attribute @default 'button' */
     type?: "button" | "submit" | "reset";
     /**
-     * Toggle state (for toggle buttons)
-     * Sets aria-pressed attribute
+     * Toggle selected state.
+     * When defined, sets aria-pressed and emits data-selected / data-toggle.
      */
-    selected?: boolean;
+    isSelected?: boolean;
     /**
-     * REQUIRED: Accessible label for screen readers
+     * Whether this button behaves as a toggle (i.e. selected prop was passed).
+     * Drives `data-toggle` attribute; determines whether aria-pressed is set.
      */
+    isToggle?: boolean;
+    /** Whether the button is disabled */
+    isDisabled?: boolean;
+    /** REQUIRED: Accessible label for screen readers */
     "aria-label": string;
-    /**
-     * HTML title attribute for tooltip
-     */
+    /** HTML title attribute for tooltip */
     title?: string;
 }
 declare const IconButtonHeadless: React$1.ForwardRefExoticComponent<IconButtonHeadlessProps & React$1.RefAttributes<HTMLButtonElement>>;
 
 /**
- * Material Design 3 FAB Variants (CVA)
+ * Material Design 3 FAB Variants — Slot-based architecture
  *
- * Type-safe variant management for FAB component.
- * Uses Tailwind CSS classes mapped to MD3 design tokens.
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (no disabled/loading state variants).
+ * - All interaction states are driven by data-* attributes on the root via
+ *   group-data-[x]/fab Tailwind selectors in each slot's base classes.
+ * - Content flags (data-with-icon, data-loading) are set explicitly by the component.
+ * - Self-targeting data-[x]: selectors handle root-level disabled styling.
  *
- * Key differences from Button/IconButton:
- * - NOT fully rounded (uses specific corner radius: 12px/16px/28px)
- * - Always has elevation (shadow-elevation-3)
- * - Larger sizes (40px/56px/96px)
- * - Extended variant with variable width
+ * Slot responsibilities:
+ *   fabVariants           — root <button>; shape per size, color per variant,
+ *                           elevation (base 3 → hover 4 → focus/pressed 3),
+ *                           self data-[disabled] styling, group/fab scope.
+ *   fabStateLayerVariants — absolute inset overlay, opacity 0/8%/10%/10%,
+ *                           color = icon/on-color per MD3 spec.
+ *   fabFocusRingVariants  — keyboard focus outline ring (inset-[-3px]).
+ *                           MUST NOT sit inside overflow-hidden.
+ *   fabIconVariants       — icon wrapper; size per FAB size variant.
+ *   fabLabelVariants      — extended FAB text label slot.
+ *
+ * MD3 Expressive size scale:
+ *   fab      → 56dp  container, 16dp corner, 24dp icon  (default)
+ *   medium   → 80dp  container, 20dp corner, 28dp icon  (M3 Expressive)
+ *   large    → 96dp  container, 28dp corner, 36dp icon
+ *   extended → 56dp  height,    16dp corner, 24dp icon  (+ text label)
+ *   small    → 40dp  container, 12dp corner, 24dp icon  (@deprecated)
+ *
+ * MD3 Expressive color roles:
+ *   primary-container   → bg-primary-container   / text-on-primary-container   (default)
+ *   secondary-container → bg-secondary-container / text-on-secondary-container
+ *   tertiary-container  → bg-tertiary-container  / text-on-tertiary-container
+ *   primary             → bg-primary             / text-on-primary             (solid, M3 Expressive)
+ *   secondary           → bg-secondary           / text-on-secondary           (solid, M3 Expressive)
+ *   tertiary            → bg-tertiary            / text-on-tertiary            (solid, M3 Expressive)
+ *   surface             → bg-surface-container-high / text-primary             (@deprecated)
+ *
+ * Elevation per state (MD3 spec):
+ *   base    → elevation-3
+ *   hovered → elevation-4  (shadow-elevation-4)
+ *   focused → elevation-3  (doubled selector wins over hover)
+ *   pressed → elevation-3  (doubled selector wins over hover)
+ *   disabled → no shadow
+ *
+ * State-layer opacities (MD3):
+ *   hover  → 8%   (opacity-8)
+ *   focus  → 10%  (opacity-10)
+ *   pressed→ 10%  (opacity-10, doubled selector wins over hover's 8%)
+ *
+ * Important — overflow-hidden is NOT on the root button.
+ * The focus ring span has `inset-[-3px]` to extend outside the button boundary,
+ * which requires the root to not clip overflow. Overflow clipping is delegated
+ * to the state layer and ripple container (overflow-hidden + rounded-[inherit]).
  */
 declare const fabVariants: (props?: ({
-    size?: "small" | "large" | "medium" | "extended" | null | undefined;
-    color?: "primary" | "secondary" | "tertiary" | "surface" | null | undefined;
-    isDisabled?: boolean | null | undefined;
+    size?: "small" | "large" | "medium" | "fab" | "extended" | null | undefined;
+    color?: "primary" | "primary-container" | "secondary" | "secondary-container" | "tertiary" | "tertiary-container" | "surface" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
-/**
- * Extract variant prop types from CVA
- */
 type FABVariants = VariantProps<typeof fabVariants>;
 
 /**
- * FAB size types
+ * FAB size types — MD3 Expressive scale.
+ *
+ * | Value      | Height | Icon  | Corner | Notes                        |
+ * |------------|--------|-------|--------|------------------------------|
+ * | `fab`      | 56dp   | 24dp  | 16dp   | Default. Regular FAB.        |
+ * | `medium`   | 80dp   | 28dp  | 20dp   | Medium FAB (M3 Expressive).  |
+ * | `large`    | 96dp   | 36dp  | 28dp   | Large FAB.                   |
+ * | `extended` | 56dp   | 24dp  | 16dp   | Extended FAB with text label.|
+ * | `small`    | 40dp   | 24dp  | 12dp   | @deprecated — Use `fab`.     |
+ *
+ * @default 'fab'
  */
-type FABSize = "small" | "medium" | "large" | "extended";
+type FABSize = "fab" | "medium" | "large" | "extended" | "small";
 /**
- * FAB color scheme
+ * FAB color styles — MD3 Expressive color roles.
+ *
+ * **Container styles (default set):**
+ * - `primary-container` — bg-primary-container / text-on-primary-container (default)
+ * - `secondary-container` — bg-secondary-container / text-on-secondary-container
+ * - `tertiary-container` — bg-tertiary-container / text-on-tertiary-container
+ *
+ * **Solid styles (M3 Expressive):**
+ * - `primary` — bg-primary / text-on-primary
+ * - `secondary` — bg-secondary / text-on-secondary
+ * - `tertiary` — bg-tertiary / text-on-tertiary
+ *
+ * **Deprecated:**
+ * - `surface` — @deprecated Use `primary-container`. Maps to surface-container-high.
+ *
+ * @default 'primary-container'
  */
-type FABColor = "primary" | "secondary" | "tertiary" | "surface";
+type FABColor = "primary-container" | "secondary-container" | "tertiary-container" | "primary" | "secondary" | "tertiary" | "surface";
 /**
  * Material Design 3 FAB (Floating Action Button) Component Props
  *
- * High-emphasis button for primary screen action.
- * Supports 4 sizes: small (40px), medium (56px), large (96px), extended (variable width with text)
- *
- * ⚠️ IMPORTANT:
- * - Only ONE FAB per screen
- * - aria-label is REQUIRED (even for extended FAB with text)
- * - Use for primary constructive actions only (create, add, compose)
- * - NOT for destructive (delete), navigation (back), or secondary actions
+ * High-emphasis button for the primary screen action.
+ * Implements the MD3 Expressive FAB spec with a slot-based architecture
+ * matching Button and Switch for consistent interaction state handling.
  *
  * @example
  * ```tsx
- * // Standard FAB (medium)
- * <FAB aria-label="Create new item" icon={<IconAdd />} />
+ * // Default FAB (56dp)
+ * <FAB aria-label="Create" icon={<IconAdd />} />
  *
- * // Small FAB
- * <FAB aria-label="Add photo" icon={<IconCamera />} size="small" />
+ * // Medium FAB (80dp, M3 Expressive)
+ * <FAB aria-label="Create" icon={<IconAdd />} size="medium" />
  *
- * // Large FAB
+ * // Large FAB (96dp)
  * <FAB aria-label="Compose" icon={<IconEdit />} size="large" />
  *
- * // Extended FAB (with text)
- * <FAB aria-label="Create new document" icon={<IconAdd />} size="extended">
+ * // Extended FAB (with text label)
+ * <FAB aria-label="Create document" icon={<IconAdd />} size="extended">
  *   Create
  * </FAB>
  *
+ * // Solid primary color (M3 Expressive)
+ * <FAB aria-label="Add" icon={<IconAdd />} color="primary" />
+ *
  * // Loading state
  * <FAB aria-label="Creating" icon={<IconAdd />} loading />
- *
- * // Secondary color
- * <FAB aria-label="Edit" icon={<IconEdit />} color="secondary" />
  * ```
  */
 interface FABProps extends AriaButtonProps {
     /**
-     * FAB size variant
-     * - small: 40×40px (24px icon)
-     * - medium: 56×56px (24px icon) - default
-     * - large: 96×96px (36px icon)
-     * - extended: Variable width with text (24px icon)
-     * @default 'medium'
+     * FAB size variant.
+     *
+     * - `fab` (56dp) — Default. Standard FAB.
+     * - `medium` (80dp) — Medium FAB. M3 Expressive. Previously 56dp; now remapped.
+     * - `large` (96dp) — Large FAB.
+     * - `extended` (56dp height) — Extended FAB with icon and text label.
+     * - `small` (40dp) — @deprecated. Use `fab` instead.
+     *
+     * @default 'fab'
      */
     size?: FABSize;
     /**
-     * Color scheme
-     * @default 'primary'
+     * Color style for the FAB.
+     *
+     * - `primary-container` — Default. bg-primary-container / text-on-primary-container.
+     * - `secondary-container` — bg-secondary-container / text-on-secondary-container.
+     * - `tertiary-container` — bg-tertiary-container / text-on-tertiary-container.
+     * - `primary` — Solid. bg-primary / text-on-primary (M3 Expressive).
+     * - `secondary` — Solid. bg-secondary / text-on-secondary (M3 Expressive).
+     * - `tertiary` — Solid. bg-tertiary / text-on-tertiary (M3 Expressive).
+     * - `surface` — @deprecated. Use `primary-container`.
+     *
+     * @default 'primary-container'
      */
     color?: FABColor;
     /**
      * Icon content (required).
-     * Recommended sizes:
-     * - small/medium/extended: 24x24px
-     * - large: 36x36px
+     * Recommended icon sizes per variant:
+     * - `fab` / `extended` / `small`: 24×24px
+     * - `medium`: 28×28px
+     * - `large`: 36×36px
      */
     icon: React__default.ReactNode;
     /**
-     * Text label (required for extended FAB, ignored for other sizes)
+     * Text label — only rendered for `size="extended"`.
      */
     children?: React__default.ReactNode;
     /**
-     * Mandatory accessible label for the FAB.
-     * This is crucial for screen readers as FAB is icon-based.
-     * Even extended FAB with text requires aria-label.
+     * Mandatory accessible label for all FAB sizes.
+     * Required even for extended FABs that have visible text.
      */
     "aria-label": string;
     /**
-     * Loading state - shows spinner, disables interaction
+     * Shows a loading spinner and disables interaction.
      * @default false
      */
     loading?: boolean;
     /**
-     * Disable ripple effect
+     * Disables the MD3 ripple press-feedback animation.
      * @default false
      */
     disableRipple?: boolean;
     /**
-     * Additional CSS classes (Tailwind)
-     * Can be used for positioning (e.g., "fixed bottom-4 right-4")
+     * Additional Tailwind classes — commonly used for positioning
+     * (e.g. `className="fixed bottom-4 right-4"`).
      */
     className?: string;
     /**
-     * HTML title attribute for tooltip
+     * HTML title attribute for tooltip.
      */
     title?: string;
     /**
-     * Mouse down handler (for ripple effect and custom handling)
+     * Mouse down handler (merged with the internal ripple handler).
      */
     onMouseDown?: (e: React__default.MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * Tab index for keyboard navigation.
+     * @default 0
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Button type attribute.
+     * @default 'button'
+     */
+    type?: "button" | "submit" | "reset";
 }
 
 /**
- * Material Design 3 FAB (Floating Action Button) Component
+ * Material Design 3 FAB (Floating Action Button) — M3 Expressive
+ *
+ * High-emphasis button for the primary screen action.
+ * Implements the Variants-vs-States architecture: all interaction states are
+ * expressed as data-* attributes on the root and consumed by each slot via
+ * group-data-[x]/fab Tailwind selectors — no state variants in CVA.
+ *
+ * Features:
+ * - ✅ MD3 Expressive size scale: fab (56dp), medium (80dp), large (96dp), extended, small (dep)
+ * - ✅ Container + solid color styles (primary-container, primary, secondary*, tertiary*)
+ * - ✅ Elevation 3 base → 4 hover → 3 focus/pressed per MD3 spec
+ * - ✅ State-layer color = icon/on-color per MD3 spec
+ * - ✅ Correct state-layer opacities: hover 8% / focus 10% / pressed 10%
+ * - ✅ Dedicated focus ring slot (inset-[-3px], keyboard-only)
+ * - ✅ Loading state with spinner
+ * - ✅ Ripple effect (Material Design)
+ * - ✅ Full keyboard accessibility via React Aria
  *
- * High-emphasis button for primary screen action.
- * Supports 4 sizes: small, medium, large, extended
- * Implementation uses Tailwind CSS classes mapped to MD3 tokens.
+ * @example
+ * ```tsx
+ * // Default FAB (56dp, primary-container)
+ * <FAB aria-label="Create" icon={<IconAdd />} />
+ *
+ * // Medium FAB (80dp, M3 Expressive)
+ * <FAB aria-label="Create" icon={<IconAdd />} size="medium" />
+ *
+ * // Solid primary color (M3 Expressive)
+ * <FAB aria-label="Add" icon={<IconAdd />} color="primary" />
+ *
+ * // Extended FAB with text
+ * <FAB aria-label="Create document" icon={<IconAdd />} size="extended">
+ *   Create
+ * </FAB>
+ * ```
  */
-declare const FAB: React__default.ForwardRefExoticComponent<FABProps & Omit<FABVariants, "isDisabled"> & React__default.RefAttributes<HTMLButtonElement>>;
+declare const FAB: React__default.ForwardRefExoticComponent<FABProps & Omit<FABVariants, never> & React__default.RefAttributes<HTMLButtonElement>>;
 
 /**
  * Headless FAB Component (Layer 2)
  *
  * Unstyled FAB primitive using React Aria for accessibility.
- * Provides behavior only - bring your own styles.
+ * Provides behavior only — bring your own styles.
  *
  * Features:
  * - Full keyboard navigation (Enter, Space)
@@ -1800,45 +1953,35 @@ declare const FAB: React__default.ForwardRefExoticComponent<FABProps & Omit<FABV
  * - Touch/pointer event handling
  * - Focus management
  * - Disabled state handling
+ * - Press lifecycle callbacks (onPressStart/onPressEnd) for pressed state tracking
  *
  * @example
  * ```tsx
- * // Use for custom styling
- * <FABHeadless className="custom-fab-class" aria-label="Add">
+ * <FABHeadless aria-label="Add" className="custom-fab">
  *   <IconAdd />
  * </FABHeadless>
  * ```
  */
 interface FABHeadlessProps extends AriaButtonProps {
-    /**
-     * Additional CSS classes
-     */
+    /** Additional CSS classes */
     className?: string;
-    /**
-     * FAB content (icon and optional text)
-     */
+    /** FAB content (icon and optional text) */
     children: React.ReactNode;
     /**
-     * Tab index for keyboard navigation
+     * Tab index for keyboard navigation.
      * @default 0
      */
     tabIndex?: number;
-    /**
-     * Mouse down handler (for ripple effect)
-     */
+    /** Mouse down handler (for ripple effect) */
     onMouseDown?: (e: React.MouseEvent<HTMLButtonElement>) => void;
     /**
-     * Button type attribute
+     * Button type attribute.
      * @default 'button'
      */
     type?: "button" | "submit" | "reset";
-    /**
-     * REQUIRED: Accessible label for screen readers
-     */
+    /** REQUIRED: Accessible label for screen readers */
     "aria-label": string;
-    /**
-     * HTML title attribute for tooltip
-     */
+    /** HTML title attribute for tooltip */
     title?: string;
 }
 declare const FABHeadless: React$1.ForwardRefExoticComponent<FABHeadlessProps & React$1.RefAttributes<HTMLButtonElement>>;
@@ -10627,7 +10770,7 @@ type DatePickerContainerVariants = VariantProps<typeof datePickerContainerVarian
  * MD3 spec: 48x48dp circle, various states and types.
  */
 declare const calendarCellVariants: (props?: ({
-    cellType?: "disabled" | "selected" | "default" | "today" | "selected-range-middle" | "outside-month" | null | undefined;
+    cellType?: "disabled" | "default" | "selected" | "today" | "selected-range-middle" | "outside-month" | null | undefined;
     state?: "focused" | "enabled" | "hovered" | "pressed" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type CalendarCellVariants = VariantProps<typeof calendarCellVariants>;