@tinybigui/react 0.8.1 → 0.10.0

package/dist/index.d.cts

@@ -598,6 +598,9 @@ interface AppBarProps {
  * Renders a `<header role="banner">` and manages scroll elevation state.
  * Use this for full visual control when the styled `AppBar` is not sufficient.
  *
+ * Extends `React.HTMLAttributes<HTMLElement>` so all standard HTML attributes
+ * (including `data-*` attributes) are forwarded to the underlying `<header>`.
+ *
  * @example
  * ```tsx
  * <AppBarHeadless
@@ -609,11 +612,7 @@ interface AppBarProps {
  * </AppBarHeadless>
  * ```
  */
-interface AppBarHeadlessProps {
-    /**
-     * Additional CSS classes
-     */
-    className?: string;
+interface AppBarHeadlessProps extends React__default.HTMLAttributes<HTMLElement> {
     /**
      * The content to render inside the header
      */
@@ -630,26 +629,41 @@ interface AppBarHeadlessProps {
 }
 
 /**
- * Material Design 3 Top App Bar Component
+ * Material Design 3 Top App Bar Component (M3 Expressive Flexible)
  *
  * Provides context and actions for the current screen. Supports four size variants,
- * a navigation icon slot, title, and trailing action icon slots. Implements
- * scroll-triggered elevation changes per MD3 specification.
+ * a navigation icon slot, title, optional subtitle, and trailing action icon slots.
+ * Implements scroll-triggered elevation changes per MD3 specification.
  *
  * **Architecture:**
- * - Layer 3 (this file): MD3 styled, CVA variants, layout composition
+ * - Layer 3 (this file): MD3 styled, CVA slot variants, layout composition
  * - Layer 2: `AppBarHeadless` — `<header role="banner">`, scroll state
  * - Layer 1: React Aria via `<IconButton>` in consumer slots
  *
+ * **Slot-based styling:**
+ * All layout and state styling follows the Variants vs States pattern:
+ * - `variant` prop drives design-time choices (height, type scale, alignment)
+ * - Scroll elevation state is emitted as `data-scrolled=""` on the root and
+ *   consumed by `group-data-[scrolled]/appbar:*` selectors (presence-based)
+ * - Subtitle presence is emitted as `data-with-subtitle=""` on the root and
+ *   used to grow medium/large bar heights (group-data-[with-subtitle]/appbar:*)
+ *
  * **Key Features:**
  * - 4 MD3 variants: small, center-aligned, medium, large
- * - Optional subtitle (per M3 Expressive spec) with per-variant typography
+ * - M3 Expressive flexible: medium and large grow vertically with a subtitle
+ *   (136dp / 152dp respectively), per the M3 Expressive flexible spec
  * - Composable API: pass `<IconButton>` nodes into navigation and action slots
- * - Scroll elevation: flat (bg-surface) at rest → bg-surface-container + shadow-elevation-2 on scroll
+ * - Scroll elevation: bg-surface at rest → bg-surface-container + shadow-elevation-2
  * - Controlled and uncontrolled scroll state
+ * - MD3 motion: background-color + box-shadow use standard effects spring pair
  * - WCAG 2.1 AA: `role="banner"` landmark, keyboard accessible slots
  * - Dark mode via existing token system
  *
+ * **M3 Expressive Flexible subtitle type scales:**
+ * - small / center-aligned: label-medium, on-surface-variant
+ * - medium expanded: label-large, on-surface-variant
+ * - large expanded: title-medium, on-surface-variant
+ *
  * **MD3 Accessibility (m3.material.io/components/app-bars/accessibility):**
  * - Focus lands on the leading navigation button first (first interactive element in DOM)
  * - Tab navigates: leading icon → trailing action icons (left to right)
@@ -682,7 +696,7 @@ interface AppBarHeadlessProps {
  *   onScrollStateChange={setIsScrolled}
  * />
  *
- * // Medium with expanded title and subtitle
+ * // Medium with expanded title and subtitle (grows to 136dp with subtitle)
  * <AppBar
  *   variant="medium"
  *   title="Article Title"
@@ -5690,21 +5704,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 +5751,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 +5782,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 +5803,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 +5899,7 @@ interface ChipHeadlessProps {
      */
     isDisabled?: boolean;
     /**
-     * Additional CSS classes (Tailwind).
+     * Additional CSS classes applied to the chip body button.
      */
     className?: string;
     /**
@@ -5836,7 +5908,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 +5920,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 +5961,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 +5994,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 +6057,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)
  *
- * Covers all four chip types (assist, filter, input, suggestion) with
- * surface, selection, disabled, and padding variants.
+ * 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
  *
- * 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.
+ * Elevation per state (elevated surface):
+ *   base=1 → hover=2 → focus/pressed=1 (doubled pressed selector wins over hover)
+ */
+/**
+ * Root chip element.
+ *
+ * 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 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>;
 
 /**