@tinybigui/react 0.11.0 → 0.11.1

package/dist/index.d.cts

@@ -4587,6 +4587,12 @@ interface CardHeadlessProps extends AriaButtonProps, Pick<HTMLAttributes<HTMLDiv
      * Card content.
      */
     children?: ReactNode;
+    /**
+     * Presence-based interaction/content `data-*` attributes forwarded onto the
+     * root element (e.g. `data-hovered`, `data-pressed`, `data-interactive`,
+     * `data-dragged`). Consumed by slot `group-data-[x]/card:` selectors.
+     */
+    [dataAttr: `data-${string}`]: unknown;
 }
 /**
  * Props for the `CardMedia` sub-component.
@@ -4695,29 +4701,37 @@ interface CardActionsProps {
 }
 
 /**
- * `Card` — Layer 3 MD3 Styled Card Component.
+ * Material Design 3 Card Component (Layer 3: Styled).
  *
- * Wraps `CardHeadless` with Material Design 3 visual styling: elevation shadows,
- * state layer, ripple feedback, and all three card variants.
+ * Wraps `CardHeadless` with MD3 visual styling using 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]/card` selectors — no
+ * state variants live in CVA.
  *
  * ## Modes
  *
- * | Condition | Rendered as | Ripple | State layer |
- * |---|---|---|---|
- * | `onPress` or `href` provided | `role="button"` | ✅ | ✅ |
- * | Neither provided | `role="article"` | ❌ | ❌ |
+ * | Condition | Rendered as | Ripple | State layer | Focus ring |
+ * |---|---|---|---|---|
+ * | `onPress` or `href` provided | `role="button"` | ✅ | ✅ | ✅ |
+ * | Neither provided | `role="article"` | ❌ | ❌ | ❌ |
+ *
+ * ## Variants & elevation per state (MD3 comp tokens)
+ *
+ * - **elevated** — `surface-container-low`; 1 base → 2 hover → 1 focus/pressed → 4 dragged.
+ * - **filled** — `surface-container-highest`; 0 base → 1 hover → 0 focus/pressed → 3 dragged.
+ * - **outlined** — `surface` + `outline-variant` border; 0 base → 1 hover → 0 focus/pressed → 3 dragged.
  *
- * ## Variants
+ * ## State layer (interactive only)
  *
- * - **elevated** — `surface-container-low` background, elevation 1dp at rest (2dp on hover).
- * - **filled** — `surface-container-highest` background, no elevation.
- * - **outlined** — `surface` background, `outline-variant` border, no elevation.
+ * `on-surface` overlay: 8% hover, 10% focus/pressed, 16% dragged. Rendered below
+ * the content (which carries `z-10`) so the surface is tinted without reducing
+ * text legibility.
  *
  * ## Dragged state
  *
- * When `isDraggable` is `true`, the card tracks its own drag state via mouse events.
- * While dragging, the `elevated` variant jumps to elevation 4dp using a slower,
- * decelerate transition curve per MD3 motion spec.
+ * When `isDraggable` is `true`, the card tracks its own drag state via mouse
+ * events and exposes it as `data-dragged`. While dragging, elevation rises to
+ * its MD3 dragged level and the state layer reaches 16% opacity.
  *
  * @example
  * ```tsx
@@ -4824,64 +4838,94 @@ declare const CardActions: React$1.ForwardRefExoticComponent<CardActionsProps &
 /**
  * `CardHeadless` — Layer 2 headless primitive.
  *
- * Provides all MD3 Card interaction semantics without any visual styling.
+ * Provides MD3 Card interaction semantics (press, keyboard activation, link
+ * behavior) without any visual styling. Pure behavior — all interaction-state
+ * styling is driven by the Layer 3 `Card` via forwarded `data-*` attributes.
  *
  * ## Dual-mode behavior
  *
- * | Condition | Role | Keyboard | Focus ring |
- * |---|---|---|---|
- * | `onPress` or `href` present | `role="button"` | Enter / Space activate | `data-focus-visible="true"` on keyboard focus |
- * | Neither present | `role="article"` | No activation | Not applicable |
+ * | Condition | Role | Keyboard |
+ * |---|---|---|
+ * | `onPress` or `href` present | `role="button"` | Enter / Space activate |
+ * | Neither present | `role="article"` | No activation, not a tab stop |
  *
- * Both `useButton` and `useFocusRing` are **always** called (React Rules of Hooks).
- * When the card is non-interactive, `buttonProps` are not spread onto the element
- * so no keyboard interaction or tab-stop is added.
+ * `useButton` is always called (Rules of Hooks); its `buttonProps` are only
+ * applied to the element when the card is interactive, so a static card adds
+ * no tab stop or keyboard handlers.
  *
- * ## Focus ring
+ * ## Prop passthrough
  *
- * The `data-focus-visible` attribute is set to `"true"` only when focus was
- * triggered by keyboard navigation (`useFocusRing` → `isFocusVisible`).
- * Mouse/touch focus leaves the attribute unset. The styled Card layer reads
- * this attribute to conditionally render the MD3 focus ring.
+ * Any `data-*` attributes (e.g. `data-hovered`, `data-pressed`, `data-dragged`,
+ * `data-interactive`) and DOM event handlers (`onMouseDown`, `onFocus`, …) are
+ * spread onto the root element so the styled layer can drive `group-data-[x]/card`
+ * selectors and ripple/drag tracking.
  *
  * @example
  * ```tsx
  * // Interactive
- * <CardHeadless
- *   onPress={handlePress}
- *   aria-label="View details"
- *   className="rounded-xl p-4"
- * >
+ * <CardHeadless onPress={handlePress} aria-label="View details" className="rounded-xl p-4">
  *   Card content
  * </CardHeadless>
  *
  * // Static
- * <CardHeadless className="rounded-xl p-4">
- *   Card content
- * </CardHeadless>
+ * <CardHeadless className="rounded-xl p-4">Card content</CardHeadless>
  * ```
  */
 declare const CardHeadless: React__default.ForwardRefExoticComponent<CardHeadlessProps & React__default.RefAttributes<HTMLDivElement>>;
 
 /**
- * Material Design 3 Card Variants (CVA)
+ * Material Design 3 Card Variants
  *
- * Type-safe variant management for the Card component.
- * Uses Tailwind CSS classes mapped to MD3 design tokens.
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (the `variant` axis). No interaction
+ *   state variants (hovered/pressed/focused/dragged/disabled) live in CVA.
+ * - All interaction states are driven by data-* attributes on the root via
+ *   `data-[x]:` (self-targeting) on the root and `group-data-[x]/card:` selectors
+ *   in each slot's base classes.
+ * - Content flags (`data-interactive`) are set explicitly by the component.
  *
- * MD3 Specifications:
- * - Shape: medium (12dp) → `rounded-md`
- * - Elevated: surface-container-low + elevation-1 (resting), elevation-2 (hover/interactive)
- * - Filled: surface-container-highest + elevation-0
- * - Outlined: surface + outline-variant border + elevation-0
- * - Dragged state (elevated only): elevation-4, slower shadow transition
- * - Disabled: on-surface at 12% opacity (`opacity-38`) + no pointer events
+ * Slot responsibilities:
+ *   cardVariants           — root container; shape, color, per-state elevation
+ *   cardStateLayerVariants — hover/focus/press/drag opacity ring (absolute overlay)
+ *   cardFocusRingVariants  — keyboard focus outline (inset so overflow-hidden never clips it)
+ *
+ * MD3 Spec (https://m3.material.io/components/cards/specs):
+ *   Shape: medium corner (12dp) → `rounded-md`
+ *   State-layer color: on-surface (all variants)
+ *   State-layer opacities: hover 8% | focus 10% | pressed 10% | dragged 16%
+ *   Disabled: container 38% opacity, no pointer events
+ *
+ * Elevation per state (MD3 comp tokens):
+ *   Elevated  enabled=1  hover=2  focus=1  pressed=1  dragged=4
+ *   Filled    enabled=0  hover=1  focus=0  pressed=0  dragged=3
+ *   Outlined  enabled=0  hover=1  focus=0  pressed=0  dragged=3
+ *
+ * Motion tier: Standard **default** (cards are standard-size components alongside
+ *   dialogs/menus — not the fast tier used for small <48dp controls like buttons).
+ *   All effect transitions use `duration-spring-standard-default-effects` (200ms) +
+ *   `ease-spring-standard-default-effects`.
+ *
+ * Specificity strategy (self-targeting `data-[x]:` on the root):
+ *   base → hover (single) → focus (single) → pressed (doubled) → dragged (tripled)
+ *   Doubling/tripling the attribute selector guarantees the later state wins
+ *   regardless of Tailwind's emitted class order. `pressed` (and `dragged`,
+ *   which co-occurs with a held pointer) therefore beat `hover` deterministically.
+ */
+/**
+ * Root container element.
+ *
+ * `overflow-hidden` clips full-bleed media (CardMedia), the ripple, and the
+ * state layer to the card's rounded shape. Because the root clips, the focus
+ * ring is rendered as an INSET overlay (see `cardFocusRingVariants`) rather than
+ * an outset ring, so it is never cut off.
+ *
+ * Elevation responds to the root's own `data-*` state attributes via
+ * self-targeting selectors (the root carries both `group/card` and the state
+ * attributes). The shadow, opacity, and border-color changes are effects, so
+ * they use the standard-default-effects spring (200ms, no overshoot).
  */
 declare const cardVariants: (props?: ({
     variant?: "filled" | "outlined" | "elevated" | null | undefined;
-    isInteractive?: boolean | null | undefined;
-    isDragged?: boolean | null | undefined;
-    isDisabled?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 /**
  * Extract variant prop types from CVA for typed usage.

package/dist/index.d.ts

@@ -4587,6 +4587,12 @@ interface CardHeadlessProps extends AriaButtonProps, Pick<HTMLAttributes<HTMLDiv
      * Card content.
      */
     children?: ReactNode;
+    /**
+     * Presence-based interaction/content `data-*` attributes forwarded onto the
+     * root element (e.g. `data-hovered`, `data-pressed`, `data-interactive`,
+     * `data-dragged`). Consumed by slot `group-data-[x]/card:` selectors.
+     */
+    [dataAttr: `data-${string}`]: unknown;
 }
 /**
  * Props for the `CardMedia` sub-component.
@@ -4695,29 +4701,37 @@ interface CardActionsProps {
 }
 
 /**
- * `Card` — Layer 3 MD3 Styled Card Component.
+ * Material Design 3 Card Component (Layer 3: Styled).
  *
- * Wraps `CardHeadless` with Material Design 3 visual styling: elevation shadows,
- * state layer, ripple feedback, and all three card variants.
+ * Wraps `CardHeadless` with MD3 visual styling using 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]/card` selectors — no
+ * state variants live in CVA.
  *
  * ## Modes
  *
- * | Condition | Rendered as | Ripple | State layer |
- * |---|---|---|---|
- * | `onPress` or `href` provided | `role="button"` | ✅ | ✅ |
- * | Neither provided | `role="article"` | ❌ | ❌ |
+ * | Condition | Rendered as | Ripple | State layer | Focus ring |
+ * |---|---|---|---|---|
+ * | `onPress` or `href` provided | `role="button"` | ✅ | ✅ | ✅ |
+ * | Neither provided | `role="article"` | ❌ | ❌ | ❌ |
+ *
+ * ## Variants & elevation per state (MD3 comp tokens)
+ *
+ * - **elevated** — `surface-container-low`; 1 base → 2 hover → 1 focus/pressed → 4 dragged.
+ * - **filled** — `surface-container-highest`; 0 base → 1 hover → 0 focus/pressed → 3 dragged.
+ * - **outlined** — `surface` + `outline-variant` border; 0 base → 1 hover → 0 focus/pressed → 3 dragged.
  *
- * ## Variants
+ * ## State layer (interactive only)
  *
- * - **elevated** — `surface-container-low` background, elevation 1dp at rest (2dp on hover).
- * - **filled** — `surface-container-highest` background, no elevation.
- * - **outlined** — `surface` background, `outline-variant` border, no elevation.
+ * `on-surface` overlay: 8% hover, 10% focus/pressed, 16% dragged. Rendered below
+ * the content (which carries `z-10`) so the surface is tinted without reducing
+ * text legibility.
  *
  * ## Dragged state
  *
- * When `isDraggable` is `true`, the card tracks its own drag state via mouse events.
- * While dragging, the `elevated` variant jumps to elevation 4dp using a slower,
- * decelerate transition curve per MD3 motion spec.
+ * When `isDraggable` is `true`, the card tracks its own drag state via mouse
+ * events and exposes it as `data-dragged`. While dragging, elevation rises to
+ * its MD3 dragged level and the state layer reaches 16% opacity.
  *
  * @example
  * ```tsx
@@ -4824,64 +4838,94 @@ declare const CardActions: React$1.ForwardRefExoticComponent<CardActionsProps &
 /**
  * `CardHeadless` — Layer 2 headless primitive.
  *
- * Provides all MD3 Card interaction semantics without any visual styling.
+ * Provides MD3 Card interaction semantics (press, keyboard activation, link
+ * behavior) without any visual styling. Pure behavior — all interaction-state
+ * styling is driven by the Layer 3 `Card` via forwarded `data-*` attributes.
  *
  * ## Dual-mode behavior
  *
- * | Condition | Role | Keyboard | Focus ring |
- * |---|---|---|---|
- * | `onPress` or `href` present | `role="button"` | Enter / Space activate | `data-focus-visible="true"` on keyboard focus |
- * | Neither present | `role="article"` | No activation | Not applicable |
+ * | Condition | Role | Keyboard |
+ * |---|---|---|
+ * | `onPress` or `href` present | `role="button"` | Enter / Space activate |
+ * | Neither present | `role="article"` | No activation, not a tab stop |
  *
- * Both `useButton` and `useFocusRing` are **always** called (React Rules of Hooks).
- * When the card is non-interactive, `buttonProps` are not spread onto the element
- * so no keyboard interaction or tab-stop is added.
+ * `useButton` is always called (Rules of Hooks); its `buttonProps` are only
+ * applied to the element when the card is interactive, so a static card adds
+ * no tab stop or keyboard handlers.
  *
- * ## Focus ring
+ * ## Prop passthrough
  *
- * The `data-focus-visible` attribute is set to `"true"` only when focus was
- * triggered by keyboard navigation (`useFocusRing` → `isFocusVisible`).
- * Mouse/touch focus leaves the attribute unset. The styled Card layer reads
- * this attribute to conditionally render the MD3 focus ring.
+ * Any `data-*` attributes (e.g. `data-hovered`, `data-pressed`, `data-dragged`,
+ * `data-interactive`) and DOM event handlers (`onMouseDown`, `onFocus`, …) are
+ * spread onto the root element so the styled layer can drive `group-data-[x]/card`
+ * selectors and ripple/drag tracking.
  *
  * @example
  * ```tsx
  * // Interactive
- * <CardHeadless
- *   onPress={handlePress}
- *   aria-label="View details"
- *   className="rounded-xl p-4"
- * >
+ * <CardHeadless onPress={handlePress} aria-label="View details" className="rounded-xl p-4">
  *   Card content
  * </CardHeadless>
  *
  * // Static
- * <CardHeadless className="rounded-xl p-4">
- *   Card content
- * </CardHeadless>
+ * <CardHeadless className="rounded-xl p-4">Card content</CardHeadless>
  * ```
  */
 declare const CardHeadless: React__default.ForwardRefExoticComponent<CardHeadlessProps & React__default.RefAttributes<HTMLDivElement>>;
 
 /**
- * Material Design 3 Card Variants (CVA)
+ * Material Design 3 Card Variants
  *
- * Type-safe variant management for the Card component.
- * Uses Tailwind CSS classes mapped to MD3 design tokens.
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (the `variant` axis). No interaction
+ *   state variants (hovered/pressed/focused/dragged/disabled) live in CVA.
+ * - All interaction states are driven by data-* attributes on the root via
+ *   `data-[x]:` (self-targeting) on the root and `group-data-[x]/card:` selectors
+ *   in each slot's base classes.
+ * - Content flags (`data-interactive`) are set explicitly by the component.
  *
- * MD3 Specifications:
- * - Shape: medium (12dp) → `rounded-md`
- * - Elevated: surface-container-low + elevation-1 (resting), elevation-2 (hover/interactive)
- * - Filled: surface-container-highest + elevation-0
- * - Outlined: surface + outline-variant border + elevation-0
- * - Dragged state (elevated only): elevation-4, slower shadow transition
- * - Disabled: on-surface at 12% opacity (`opacity-38`) + no pointer events
+ * Slot responsibilities:
+ *   cardVariants           — root container; shape, color, per-state elevation
+ *   cardStateLayerVariants — hover/focus/press/drag opacity ring (absolute overlay)
+ *   cardFocusRingVariants  — keyboard focus outline (inset so overflow-hidden never clips it)
+ *
+ * MD3 Spec (https://m3.material.io/components/cards/specs):
+ *   Shape: medium corner (12dp) → `rounded-md`
+ *   State-layer color: on-surface (all variants)
+ *   State-layer opacities: hover 8% | focus 10% | pressed 10% | dragged 16%
+ *   Disabled: container 38% opacity, no pointer events
+ *
+ * Elevation per state (MD3 comp tokens):
+ *   Elevated  enabled=1  hover=2  focus=1  pressed=1  dragged=4
+ *   Filled    enabled=0  hover=1  focus=0  pressed=0  dragged=3
+ *   Outlined  enabled=0  hover=1  focus=0  pressed=0  dragged=3
+ *
+ * Motion tier: Standard **default** (cards are standard-size components alongside
+ *   dialogs/menus — not the fast tier used for small <48dp controls like buttons).
+ *   All effect transitions use `duration-spring-standard-default-effects` (200ms) +
+ *   `ease-spring-standard-default-effects`.
+ *
+ * Specificity strategy (self-targeting `data-[x]:` on the root):
+ *   base → hover (single) → focus (single) → pressed (doubled) → dragged (tripled)
+ *   Doubling/tripling the attribute selector guarantees the later state wins
+ *   regardless of Tailwind's emitted class order. `pressed` (and `dragged`,
+ *   which co-occurs with a held pointer) therefore beat `hover` deterministically.
+ */
+/**
+ * Root container element.
+ *
+ * `overflow-hidden` clips full-bleed media (CardMedia), the ripple, and the
+ * state layer to the card's rounded shape. Because the root clips, the focus
+ * ring is rendered as an INSET overlay (see `cardFocusRingVariants`) rather than
+ * an outset ring, so it is never cut off.
+ *
+ * Elevation responds to the root's own `data-*` state attributes via
+ * self-targeting selectors (the root carries both `group/card` and the state
+ * attributes). The shadow, opacity, and border-color changes are effects, so
+ * they use the standard-default-effects spring (200ms, no overshoot).
  */
 declare const cardVariants: (props?: ({
     variant?: "filled" | "outlined" | "elevated" | null | undefined;
-    isInteractive?: boolean | null | undefined;
-    isDragged?: boolean | null | undefined;
-    isDisabled?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 /**
  * Extract variant prop types from CVA for typed usage.