@tinybigui/react 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -1702,141 +1702,250 @@ interface IconButtonHeadlessProps extends AriaButtonProps {
 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)
@@ -1844,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>>;