@tinybigui/react 0.8.0 → 0.9.0

package/dist/index.d.cts

@@ -2264,23 +2264,23 @@ interface CheckboxProps extends AriaCheckboxProps, Omit<React__default.HTMLAttri
  * Material Design 3 Checkbox Component (Layer 3: Styled)
  *
  * Built on React Aria for world-class accessibility.
- * Uses CVA for type-safe variant management.
- * Styled with Tailwind CSS using MD3 design tokens.
+ * Implements the Variants-vs-States architecture: all interaction/selection
+ * states are expressed as data-* attributes on the root and consumed by each
+ * slot via group-data-[x]/checkbox Tailwind selectors — no state variants in CVA.
  *
  * Features:
- * - ✅ 3 states: unchecked, checked, indeterminate
- * - ✅ Error/invalid state support
- * - ✅ Ripple effect (Material Design)
- * - ✅ Full keyboard accessibility (via React Aria)
- * - ✅ Screen reader support (via React Aria)
- * - ✅ Focus management (via React Aria)
- * - ✅ Form integration (name, value props)
+ * - 3 states: unchecked, checked, indeterminate
+ * - Error/invalid state support
+ * - Ripple effect (Material Design)
+ * - Full keyboard accessibility (via React Aria)
+ * - Screen reader support (via React Aria)
+ * - Focus management (via React Aria)
+ * - Form integration (name, value props)
  *
  * MD3 Specifications:
- * - Container: 18x18dp (within 40x40dp touch target)
- * - Corner radius: 2dp (applied via SVG rx/ry attributes)
- * - State layers: 8% hover, 12% focus/pressed
- * - Disabled: 38% opacity
+ * - Box: 18×18dp, 2dp corner radius, within 40×40dp touch target
+ * - State-layer opacities: hover 8% | focus/pressed 10%
+ * - Disabled: 38% opacity on root
  * - Label spacing: 16px (ml-4)
  *
  * @example
@@ -5690,21 +5690,22 @@ declare function SnackbarProvider({ children, maxVisible }: SnackbarProviderProp
 /**
  * The four MD3 chip types, each with distinct interaction semantics.
  *
- * - `assist` – triggers an action (e.g. "Set alarm")
- * - `filter` – toggles a filter on/off (`aria-pressed`)
- * - `input` – represents a value the user entered; can be removed
+ * - `assist`     – triggers an action (e.g. "Set alarm")
+ * - `filter`     – toggles a filter on/off (`aria-pressed`)
+ * - `input`      – represents a value the user entered; can be removed
  * - `suggestion` – offers a contextual suggestion (acts like assist)
  */
 type ChipType = "assist" | "filter" | "input" | "suggestion";
 /**
- * Surface style for Assist and Suggestion chips.
+ * Surface style for chips.
  *
- * - `tonal` – uses secondary-container fill (default)
- * - `elevated` – uses surface-container-low fill with elevation shadow
+ * - `flat`     – transparent container with outline border (MD3 default)
+ * - `elevated` – `surface-container-low` fill with elevation shadow; all four chip types support this
+ * - `tonal`    – @deprecated Use `flat` instead. Will be removed in a future minor version.
  *
- * @default 'tonal'
+ * @default 'flat'
  */
-type ChipSurface = "tonal" | "elevated";
+type ChipSurface = "flat" | "elevated" | "tonal";
 /**
  * Material Design 3 Chip Component Props
  *
@@ -5736,8 +5737,13 @@ interface ChipProps {
      */
     label: string;
     /**
-     * Surface style (Assist and Suggestion chips only).
-     * @default 'tonal'
+     * Surface style applied to the chip.
+     *
+     * - `flat` (default) — transparent container with outline border per MD3 spec.
+     * - `elevated` — `surface-container-low` fill + elevation shadow; works with all chip types.
+     * - `tonal` — @deprecated alias for `flat`; logs a console.warn in development.
+     *
+     * @default 'flat'
      */
     surface?: ChipSurface;
     /**
@@ -5762,6 +5768,11 @@ interface ChipProps {
     onRemove?: () => void;
     /**
      * Icon rendered before the label.
+     * Color follows the MD3 spec per chip type:
+     * - assist → `text-primary`
+     * - filter (unselected) → `text-on-surface-variant`; (selected) → `text-on-secondary-container`
+     * - input → `text-on-surface-variant`
+     * - suggestion → `text-on-surface-variant`
      */
     leadingIcon?: React__default.ReactNode;
     /**
@@ -5778,6 +5789,53 @@ interface ChipProps {
      */
     className?: string;
 }
+/**
+ * Props passed through to the chip body element (button) in ChipHeadless.
+ * Allows the styled layer to inject data-* interaction attributes and
+ * merged hover/focus event handlers.
+ */
+interface ChipBodyPassthroughProps {
+    /**
+     * Merged hover/focus/press event handlers from the styled layer.
+     * Spread onto the body <button>.
+     */
+    eventHandlers?: Record<string, unknown>;
+    /**
+     * data-* interaction attributes emitted by getInteractionDataAttributes.
+     * Spread onto the body <button>.
+     */
+    dataAttributes?: Record<string, string | undefined>;
+    /**
+     * onPressStart forwarded into useButton/useToggleButton for isPressed tracking.
+     */
+    onPressStart?: () => void;
+    /**
+     * onPressEnd forwarded into useButton/useToggleButton for isPressed tracking.
+     */
+    onPressEnd?: () => void;
+}
+/**
+ * Props passed through to the remove button element in InputChipImpl.
+ */
+interface ChipRemovePassthroughProps {
+    /**
+     * data-* interaction attributes for the remove button.
+     */
+    dataAttributes?: Record<string, string | undefined>;
+    /**
+     * Merged hover/focus event handlers from useHover + useFocusRing.
+     * Spread onto the remove <button> alongside React Aria's buttonProps.
+     */
+    eventHandlers?: Record<string, unknown>;
+    /**
+     * onPressStart for remove button isPressed tracking.
+     */
+    onPressStart?: () => void;
+    /**
+     * onPressEnd for remove button isPressed tracking.
+     */
+    onPressEnd?: () => void;
+}
 /**
  * Props for the headless ChipHeadless component (Layer 2).
  *
@@ -5827,7 +5885,7 @@ interface ChipHeadlessProps {
      */
     isDisabled?: boolean;
     /**
-     * Additional CSS classes (Tailwind).
+     * Additional CSS classes applied to the chip body button.
      */
     className?: string;
     /**
@@ -5836,7 +5894,7 @@ interface ChipHeadlessProps {
     children?: React__default.ReactNode;
     /**
      * Icon rendered inside the remove button (Input chips only).
-     * Typically an ×/close SVG.
+     * Typically an ×/close SVG wrapped in a fragment with a state layer span.
      */
     removeIcon?: React__default.ReactNode;
     /**
@@ -5848,6 +5906,16 @@ interface ChipHeadlessProps {
      * Used by the styled layer to trigger the ripple effect.
      */
     onMouseDown?: React__default.MouseEventHandler<HTMLButtonElement>;
+    /**
+     * Interaction data attributes + merged handlers from the styled layer.
+     * Spread onto the body <button> to enable group-data-[x]/chip slot selectors.
+     */
+    bodyPassthrough?: ChipBodyPassthroughProps;
+    /**
+     * Interaction data attributes + handlers for the remove button (Input chips only).
+     * Spread onto the remove <button>.
+     */
+    removePassthrough?: ChipRemovePassthroughProps;
 }
 /**
  * Props for the ChipSet container component.
@@ -5879,6 +5947,10 @@ interface ChipSetProps {
  * Unstyled chip primitive covering all four MD3 chip types. Delegates to the
  * correct React Aria hook per `type` — bring your own styles.
  *
+ * The styled layer (Chip.tsx) passes `bodyPassthrough` to inject data-* interaction
+ * attributes and merged hover/focus handlers onto the body button, enabling the
+ * group-data-[x]/chip slot selectors defined in Chip.variants.ts.
+ *
  * | type         | Hook                                    | Key behaviour                    |
  * |------------- |-----------------------------------------|----------------------------------|
  * | `assist`     | `useButton`                             | Enter/Space → `onPress`          |
@@ -5908,18 +5980,33 @@ declare const ChipHeadless: React$1.ForwardRefExoticComponent<ChipHeadlessProps
  *
  * Unified styled chip covering all four MD3 chip types.
  * Built on `ChipHeadless` for world-class accessibility via React Aria.
- * Uses CVA for type-safe variant management.
  *
- * | Type         | Surface       | Selection | Remove |
- * |--------------|---------------|-----------|--------|
- * | `assist`     | tonal/elevated | —         | —      |
- * | `filter`     | fixed tonal   | ✅         | —      |
- * | `input`      | fixed tonal   | —         | ✅     |
- * | `suggestion` | tonal/elevated | —         | —      |
+ * Implements the Variants-vs-States architecture: all interaction/selection
+ * states are expressed as `data-*` attributes on the root and consumed by each
+ * slot via `group-data-[x]/chip` Tailwind selectors — no state variants in CVA.
+ *
+ * Features:
+ * - ✅ 4 MD3 chip types: assist, filter, input, suggestion
+ * - ✅ 2 surfaces: flat (transparent + outline), elevated (shadow + fill)
+ * - ✅ MD3-correct per-type icon colors (assist leading = primary, etc.)
+ * - ✅ Filter chip checkmark with spring animation
+ * - ✅ Input chip removal with animate-md-fade-out
+ * - ✅ Proper MD3 state layer (hover 8%, focus 10%, pressed 10%)
+ * - ✅ Spring motion tokens (no hardcoded durations)
+ * - ✅ Dedicated focus ring slot (outside overflow-hidden)
+ * - ✅ Full keyboard accessibility (via React Aria)
+ * - ✅ Deprecated `surface="tonal"` — warns and maps to `flat`
+ *
+ * MD3 Specifications:
+ * - Height: 32dp (h-8), corner-small 8dp (rounded-sm)
+ * - Padding: 16dp base; 8dp leading side when icon present
+ * - Icon size: 18px × 18px
+ * - State layers: 8% hover, 10% focus/pressed
+ * - Elevation: level-1 base → level-2 hover (elevated surface)
  *
  * @example
  * ```tsx
- * // Assist chip
+ * // Assist chip (default flat surface)
  * <Chip type="assist" label="Set alarm" onPress={handlePress} />
  *
  * // Elevated assist chip
@@ -5956,27 +6043,64 @@ declare const Chip: React__default.ForwardRefExoticComponent<ChipProps & React__
 declare const ChipSet: React$1.ForwardRefExoticComponent<ChipSetProps & React$1.RefAttributes<HTMLDivElement>>;
 
 /**
- * Material Design 3 Chip Variants (CVA)
+ * Material Design 3 Chip Variants (Slot-based "Variants vs States" architecture)
+ *
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (chipType × surface).
+ * - All interaction/selection states are driven by data-* attributes on the root
+ *   via group-data-[x]/chip Tailwind selectors in each slot's base classes.
+ * - Content flags (data-with-leading, data-with-trailing) are set explicitly by
+ *   the component and consumed by the root slot for padding adjustments.
+ *
+ * Slot responsibilities:
+ *   chipVariants             — root button/span; shape, color, elevation, padding
+ *   chipStateLayerVariants   — hover/focus/press opacity overlay (absolute inset)
+ *   chipFocusRingVariants    — keyboard focus outline, outside overflow-hidden
+ *   chipLeadingIconVariants  — leading icon wrapper; color per type + selected/disabled
+ *   chipTrailingIconVariants — trailing icon wrapper; assist/suggestion only
+ *   chipCheckmarkVariants    — filter chip checkmark container (width spring)
+ *   chipLabelVariants        — label text slot
+ *   chipRemoveButtonVariants — input chip remove button wrapper
+ *   chipRemoveStateLayerVariants — state layer inside remove button circle
+ *
+ * MD3 Spec (Expressive):
+ *   Shape:   corner-small (8dp) → rounded-sm
+ *   Height:  32dp → h-8
+ *   Padding: 16dp base; 8dp leading side with icon
+ *   Gap:     8dp → gap-2
+ *   Icon:    18px × 18px
+ *   State-layer opacities: hover 8% | focus 10% | pressed 10%
+ *   Disabled: container transparent, border 12% opacity, content 38% opacity
+ *
+ * Per-type color tokens (MD3 strict):
+ *   assist:     bg=transparent border=outline      label=on-surface     leadingIcon=primary   stateLayer=on-surface
+ *   filter:     bg=transparent border=outline      label=on-surface-variant                   stateLayer=on-surface-variant
+ *   filter sel: bg=secondary-container border=none label=on-secondary-container               stateLayer=on-secondary-container
+ *   input:      bg=transparent border=outline-variant label=on-surface-variant                stateLayer=on-surface-variant
+ *   suggestion: bg=transparent border=outline      label=on-surface-variant                   stateLayer=on-surface-variant
+ *
+ * Elevation per state (elevated surface):
+ *   base=1 → hover=2 → focus/pressed=1 (doubled pressed selector wins over hover)
+ */
+/**
+ * Root chip element.
  *
- * Covers all four chip types (assist, filter, input, suggestion) with
- * surface, selection, disabled, and padding variants.
+ * IMPORTANT — overflow is intentionally NOT on the root.
+ * Clipping is delegated to the state-layer and ripple containers via
+ * `overflow-hidden rounded-[inherit]` so the focus ring span (inset-[-3px])
+ * can extend outside the chip boundary and remain fully visible.
  *
- * Padding resolution (via tailwind-merge in `cn()`):
- *   base `px-4`  →  hasLeadingIcon overrides with `pl-3 pr-4`
- *                →  hasRemoveButton overrides with `pl-3 pr-3`
- * Both can be combined and the last-applied wins through tailwind-merge.
+ * Padding is driven by content flags:
+ *   base px-4 (16dp)
+ *   data-[with-leading]: pl-2 pr-4  (8dp leading, 16dp trailing)
+ *   data-[with-trailing]: pl-4 pr-2
+ *   data-[with-leading][with-trailing]: pl-2 pr-2
+ * These are self-targeting data-[x]: selectors (no group scope needed).
  */
 declare const chipVariants: (props?: ({
     chipType?: "filter" | "input" | "assist" | "suggestion" | null | undefined;
-    surface?: "tonal" | "elevated" | null | undefined;
-    selected?: boolean | null | undefined;
-    isDisabled?: boolean | null | undefined;
-    hasLeadingIcon?: boolean | null | undefined;
-    hasRemoveButton?: boolean | null | undefined;
+    surface?: "tonal" | "elevated" | "flat" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
-/**
- * Extract variant prop types from CVA
- */
 type ChipVariants = VariantProps<typeof chipVariants>;
 
 /**

package/dist/index.d.ts

@@ -2264,23 +2264,23 @@ interface CheckboxProps extends AriaCheckboxProps, Omit<React__default.HTMLAttri
  * Material Design 3 Checkbox Component (Layer 3: Styled)
  *
  * Built on React Aria for world-class accessibility.
- * Uses CVA for type-safe variant management.
- * Styled with Tailwind CSS using MD3 design tokens.
+ * Implements the Variants-vs-States architecture: all interaction/selection
+ * states are expressed as data-* attributes on the root and consumed by each
+ * slot via group-data-[x]/checkbox Tailwind selectors — no state variants in CVA.
  *
  * Features:
- * - ✅ 3 states: unchecked, checked, indeterminate
- * - ✅ Error/invalid state support
- * - ✅ Ripple effect (Material Design)
- * - ✅ Full keyboard accessibility (via React Aria)
- * - ✅ Screen reader support (via React Aria)
- * - ✅ Focus management (via React Aria)
- * - ✅ Form integration (name, value props)
+ * - 3 states: unchecked, checked, indeterminate
+ * - Error/invalid state support
+ * - Ripple effect (Material Design)
+ * - Full keyboard accessibility (via React Aria)
+ * - Screen reader support (via React Aria)
+ * - Focus management (via React Aria)
+ * - Form integration (name, value props)
  *
  * MD3 Specifications:
- * - Container: 18x18dp (within 40x40dp touch target)
- * - Corner radius: 2dp (applied via SVG rx/ry attributes)
- * - State layers: 8% hover, 12% focus/pressed
- * - Disabled: 38% opacity
+ * - Box: 18×18dp, 2dp corner radius, within 40×40dp touch target
+ * - State-layer opacities: hover 8% | focus/pressed 10%
+ * - Disabled: 38% opacity on root
  * - Label spacing: 16px (ml-4)
  *
  * @example
@@ -5690,21 +5690,22 @@ declare function SnackbarProvider({ children, maxVisible }: SnackbarProviderProp
 /**
  * The four MD3 chip types, each with distinct interaction semantics.
  *
- * - `assist` – triggers an action (e.g. "Set alarm")
- * - `filter` – toggles a filter on/off (`aria-pressed`)
- * - `input` – represents a value the user entered; can be removed
+ * - `assist`     – triggers an action (e.g. "Set alarm")
+ * - `filter`     – toggles a filter on/off (`aria-pressed`)
+ * - `input`      – represents a value the user entered; can be removed
  * - `suggestion` – offers a contextual suggestion (acts like assist)
  */
 type ChipType = "assist" | "filter" | "input" | "suggestion";
 /**
- * Surface style for Assist and Suggestion chips.
+ * Surface style for chips.
  *
- * - `tonal` – uses secondary-container fill (default)
- * - `elevated` – uses surface-container-low fill with elevation shadow
+ * - `flat`     – transparent container with outline border (MD3 default)
+ * - `elevated` – `surface-container-low` fill with elevation shadow; all four chip types support this
+ * - `tonal`    – @deprecated Use `flat` instead. Will be removed in a future minor version.
  *
- * @default 'tonal'
+ * @default 'flat'
  */
-type ChipSurface = "tonal" | "elevated";
+type ChipSurface = "flat" | "elevated" | "tonal";
 /**
  * Material Design 3 Chip Component Props
  *
@@ -5736,8 +5737,13 @@ interface ChipProps {
      */
     label: string;
     /**
-     * Surface style (Assist and Suggestion chips only).
-     * @default 'tonal'
+     * Surface style applied to the chip.
+     *
+     * - `flat` (default) — transparent container with outline border per MD3 spec.
+     * - `elevated` — `surface-container-low` fill + elevation shadow; works with all chip types.
+     * - `tonal` — @deprecated alias for `flat`; logs a console.warn in development.
+     *
+     * @default 'flat'
      */
     surface?: ChipSurface;
     /**
@@ -5762,6 +5768,11 @@ interface ChipProps {
     onRemove?: () => void;
     /**
      * Icon rendered before the label.
+     * Color follows the MD3 spec per chip type:
+     * - assist → `text-primary`
+     * - filter (unselected) → `text-on-surface-variant`; (selected) → `text-on-secondary-container`
+     * - input → `text-on-surface-variant`
+     * - suggestion → `text-on-surface-variant`
      */
     leadingIcon?: React__default.ReactNode;
     /**
@@ -5778,6 +5789,53 @@ interface ChipProps {
      */
     className?: string;
 }
+/**
+ * Props passed through to the chip body element (button) in ChipHeadless.
+ * Allows the styled layer to inject data-* interaction attributes and
+ * merged hover/focus event handlers.
+ */
+interface ChipBodyPassthroughProps {
+    /**
+     * Merged hover/focus/press event handlers from the styled layer.
+     * Spread onto the body <button>.
+     */
+    eventHandlers?: Record<string, unknown>;
+    /**
+     * data-* interaction attributes emitted by getInteractionDataAttributes.
+     * Spread onto the body <button>.
+     */
+    dataAttributes?: Record<string, string | undefined>;
+    /**
+     * onPressStart forwarded into useButton/useToggleButton for isPressed tracking.
+     */
+    onPressStart?: () => void;
+    /**
+     * onPressEnd forwarded into useButton/useToggleButton for isPressed tracking.
+     */
+    onPressEnd?: () => void;
+}
+/**
+ * Props passed through to the remove button element in InputChipImpl.
+ */
+interface ChipRemovePassthroughProps {
+    /**
+     * data-* interaction attributes for the remove button.
+     */
+    dataAttributes?: Record<string, string | undefined>;
+    /**
+     * Merged hover/focus event handlers from useHover + useFocusRing.
+     * Spread onto the remove <button> alongside React Aria's buttonProps.
+     */
+    eventHandlers?: Record<string, unknown>;
+    /**
+     * onPressStart for remove button isPressed tracking.
+     */
+    onPressStart?: () => void;
+    /**
+     * onPressEnd for remove button isPressed tracking.
+     */
+    onPressEnd?: () => void;
+}
 /**
  * Props for the headless ChipHeadless component (Layer 2).
  *
@@ -5827,7 +5885,7 @@ interface ChipHeadlessProps {
      */
     isDisabled?: boolean;
     /**
-     * Additional CSS classes (Tailwind).
+     * Additional CSS classes applied to the chip body button.
      */
     className?: string;
     /**
@@ -5836,7 +5894,7 @@ interface ChipHeadlessProps {
     children?: React__default.ReactNode;
     /**
      * Icon rendered inside the remove button (Input chips only).
-     * Typically an ×/close SVG.
+     * Typically an ×/close SVG wrapped in a fragment with a state layer span.
      */
     removeIcon?: React__default.ReactNode;
     /**
@@ -5848,6 +5906,16 @@ interface ChipHeadlessProps {
      * Used by the styled layer to trigger the ripple effect.
      */
     onMouseDown?: React__default.MouseEventHandler<HTMLButtonElement>;
+    /**
+     * Interaction data attributes + merged handlers from the styled layer.
+     * Spread onto the body <button> to enable group-data-[x]/chip slot selectors.
+     */
+    bodyPassthrough?: ChipBodyPassthroughProps;
+    /**
+     * Interaction data attributes + handlers for the remove button (Input chips only).
+     * Spread onto the remove <button>.
+     */
+    removePassthrough?: ChipRemovePassthroughProps;
 }
 /**
  * Props for the ChipSet container component.
@@ -5879,6 +5947,10 @@ interface ChipSetProps {
  * Unstyled chip primitive covering all four MD3 chip types. Delegates to the
  * correct React Aria hook per `type` — bring your own styles.
  *
+ * The styled layer (Chip.tsx) passes `bodyPassthrough` to inject data-* interaction
+ * attributes and merged hover/focus handlers onto the body button, enabling the
+ * group-data-[x]/chip slot selectors defined in Chip.variants.ts.
+ *
  * | type         | Hook                                    | Key behaviour                    |
  * |------------- |-----------------------------------------|----------------------------------|
  * | `assist`     | `useButton`                             | Enter/Space → `onPress`          |
@@ -5908,18 +5980,33 @@ declare const ChipHeadless: React$1.ForwardRefExoticComponent<ChipHeadlessProps
  *
  * Unified styled chip covering all four MD3 chip types.
  * Built on `ChipHeadless` for world-class accessibility via React Aria.
- * Uses CVA for type-safe variant management.
  *
- * | Type         | Surface       | Selection | Remove |
- * |--------------|---------------|-----------|--------|
- * | `assist`     | tonal/elevated | —         | —      |
- * | `filter`     | fixed tonal   | ✅         | —      |
- * | `input`      | fixed tonal   | —         | ✅     |
- * | `suggestion` | tonal/elevated | —         | —      |
+ * Implements the Variants-vs-States architecture: all interaction/selection
+ * states are expressed as `data-*` attributes on the root and consumed by each
+ * slot via `group-data-[x]/chip` Tailwind selectors — no state variants in CVA.
+ *
+ * Features:
+ * - ✅ 4 MD3 chip types: assist, filter, input, suggestion
+ * - ✅ 2 surfaces: flat (transparent + outline), elevated (shadow + fill)
+ * - ✅ MD3-correct per-type icon colors (assist leading = primary, etc.)
+ * - ✅ Filter chip checkmark with spring animation
+ * - ✅ Input chip removal with animate-md-fade-out
+ * - ✅ Proper MD3 state layer (hover 8%, focus 10%, pressed 10%)
+ * - ✅ Spring motion tokens (no hardcoded durations)
+ * - ✅ Dedicated focus ring slot (outside overflow-hidden)
+ * - ✅ Full keyboard accessibility (via React Aria)
+ * - ✅ Deprecated `surface="tonal"` — warns and maps to `flat`
+ *
+ * MD3 Specifications:
+ * - Height: 32dp (h-8), corner-small 8dp (rounded-sm)
+ * - Padding: 16dp base; 8dp leading side when icon present
+ * - Icon size: 18px × 18px
+ * - State layers: 8% hover, 10% focus/pressed
+ * - Elevation: level-1 base → level-2 hover (elevated surface)
  *
  * @example
  * ```tsx
- * // Assist chip
+ * // Assist chip (default flat surface)
  * <Chip type="assist" label="Set alarm" onPress={handlePress} />
  *
  * // Elevated assist chip
@@ -5956,27 +6043,64 @@ declare const Chip: React__default.ForwardRefExoticComponent<ChipProps & React__
 declare const ChipSet: React$1.ForwardRefExoticComponent<ChipSetProps & React$1.RefAttributes<HTMLDivElement>>;
 
 /**
- * Material Design 3 Chip Variants (CVA)
+ * Material Design 3 Chip Variants (Slot-based "Variants vs States" architecture)
+ *
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (chipType × surface).
+ * - All interaction/selection states are driven by data-* attributes on the root
+ *   via group-data-[x]/chip Tailwind selectors in each slot's base classes.
+ * - Content flags (data-with-leading, data-with-trailing) are set explicitly by
+ *   the component and consumed by the root slot for padding adjustments.
+ *
+ * Slot responsibilities:
+ *   chipVariants             — root button/span; shape, color, elevation, padding
+ *   chipStateLayerVariants   — hover/focus/press opacity overlay (absolute inset)
+ *   chipFocusRingVariants    — keyboard focus outline, outside overflow-hidden
+ *   chipLeadingIconVariants  — leading icon wrapper; color per type + selected/disabled
+ *   chipTrailingIconVariants — trailing icon wrapper; assist/suggestion only
+ *   chipCheckmarkVariants    — filter chip checkmark container (width spring)
+ *   chipLabelVariants        — label text slot
+ *   chipRemoveButtonVariants — input chip remove button wrapper
+ *   chipRemoveStateLayerVariants — state layer inside remove button circle
+ *
+ * MD3 Spec (Expressive):
+ *   Shape:   corner-small (8dp) → rounded-sm
+ *   Height:  32dp → h-8
+ *   Padding: 16dp base; 8dp leading side with icon
+ *   Gap:     8dp → gap-2
+ *   Icon:    18px × 18px
+ *   State-layer opacities: hover 8% | focus 10% | pressed 10%
+ *   Disabled: container transparent, border 12% opacity, content 38% opacity
+ *
+ * Per-type color tokens (MD3 strict):
+ *   assist:     bg=transparent border=outline      label=on-surface     leadingIcon=primary   stateLayer=on-surface
+ *   filter:     bg=transparent border=outline      label=on-surface-variant                   stateLayer=on-surface-variant
+ *   filter sel: bg=secondary-container border=none label=on-secondary-container               stateLayer=on-secondary-container
+ *   input:      bg=transparent border=outline-variant label=on-surface-variant                stateLayer=on-surface-variant
+ *   suggestion: bg=transparent border=outline      label=on-surface-variant                   stateLayer=on-surface-variant
+ *
+ * Elevation per state (elevated surface):
+ *   base=1 → hover=2 → focus/pressed=1 (doubled pressed selector wins over hover)
+ */
+/**
+ * Root chip element.
  *
- * Covers all four chip types (assist, filter, input, suggestion) with
- * surface, selection, disabled, and padding variants.
+ * IMPORTANT — overflow is intentionally NOT on the root.
+ * Clipping is delegated to the state-layer and ripple containers via
+ * `overflow-hidden rounded-[inherit]` so the focus ring span (inset-[-3px])
+ * can extend outside the chip boundary and remain fully visible.
  *
- * Padding resolution (via tailwind-merge in `cn()`):
- *   base `px-4`  →  hasLeadingIcon overrides with `pl-3 pr-4`
- *                →  hasRemoveButton overrides with `pl-3 pr-3`
- * Both can be combined and the last-applied wins through tailwind-merge.
+ * Padding is driven by content flags:
+ *   base px-4 (16dp)
+ *   data-[with-leading]: pl-2 pr-4  (8dp leading, 16dp trailing)
+ *   data-[with-trailing]: pl-4 pr-2
+ *   data-[with-leading][with-trailing]: pl-2 pr-2
+ * These are self-targeting data-[x]: selectors (no group scope needed).
  */
 declare const chipVariants: (props?: ({
     chipType?: "filter" | "input" | "assist" | "suggestion" | null | undefined;
-    surface?: "tonal" | "elevated" | null | undefined;
-    selected?: boolean | null | undefined;
-    isDisabled?: boolean | null | undefined;
-    hasLeadingIcon?: boolean | null | undefined;
-    hasRemoveButton?: boolean | null | undefined;
+    surface?: "tonal" | "elevated" | "flat" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
-/**
- * Extract variant prop types from CVA
- */
 type ChipVariants = VariantProps<typeof chipVariants>;
 
 /**