@tinybigui/react 0.4.2 → 0.5.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
- *
- * Icon-only button component with 4 variants and mandatory accessibility.
+ * Material Design 3 Expressive IconButton Component Props
  *
- * **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,86 +1609,94 @@ 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>>;
@@ -10627,7 +10671,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>;