@tinybigui/react 0.10.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)
  *
- * ## Variants
+ * - **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.
  *
- * - **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.
+ * ## State layer (interactive only)
+ *
+ * `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.
@@ -9192,6 +9236,22 @@ interface BottomSheetHandleProps {
  */
 declare const BottomSheet: React$1.ForwardRefExoticComponent<BottomSheetProps & React$1.RefAttributes<HTMLDivElement>>;
 
+/**
+ * `BottomSheetHandle` — the draggable handle at the top of the Bottom Sheet.
+ *
+ * Implements the Variants-vs-States architecture used across TinyBigUI:
+ * - Carries `group/handle` on its wrapper so child slots consume data-* selectors.
+ * - Emits `getInteractionDataAttributes` for hover/focus/pressed states from React Aria.
+ * - Emits `data-dragging` as a component-specific content flag (ternary encoding).
+ * - Renders three slots inside the wrapper (stacked via absolute positioning):
+ *   1. State layer — hover/focus/pressed/dragged opacity feedback (aria-hidden)
+ *   2. Focus ring overlay — keyboard focus indicator (aria-hidden)
+ *   3. Pill — the visible 32×4dp decoration (aria-hidden)
+ *
+ * Pointer and keyboard props are injected from `BottomSheetContext` (via `useBottomSheetDrag`).
+ * React Aria `useHover` and `useFocusRing` are merged on top — they do not conflict with the
+ * existing `onPointerDown`/`onPointerUp` drag handlers.
+ */
 declare function BottomSheetHandle({ className, "aria-label": ariaLabelOverride, }: BottomSheetHandleProps): ReactElement;
 declare namespace BottomSheetHandle {
     var displayName: string;
@@ -9297,13 +9357,40 @@ interface UseBottomSheetDragReturn {
  */
 declare function useBottomSheetDrag({ snapPoints, onSnapChange, onClose, }: UseBottomSheetDragOptions): UseBottomSheetDragReturn;
 
+/**
+ * Material Design 3 Bottom Sheet Variants
+ *
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (no state variants, no state compoundVariants).
+ * - The drag handle's interaction states are driven by data-* attributes on its wrapper
+ *   via group-data-[x]/handle Tailwind selectors in each slot's base classes.
+ * - Content flags (data-dragging) are set explicitly by the component, not via helper.
+ *
+ * Slot responsibilities:
+ *   bottomSheetVariants               — fixed container; surface, shape, elevation, snap spring
+ *   bottomSheetScrimVariants          — modal scrim overlay; opacity fade (screen-level token)
+ *   bottomSheetAnimationVariants      — enter/exit animation state machine classes
+ *   bottomSheetHandleWrapperVariants  — 48dp touch target; carries `group/handle`; data-* host
+ *   bottomSheetHandleStateLayerVariants — hover/focus/pressed/dragged opacity ring around pill
+ *   bottomSheetHandleFocusRingVariants  — keyboard focus outline overlay (opacity-driven)
+ *   bottomSheetHandlePillVariants     — 32×4dp pill decoration; pointer-events-none
+ *
+ * MD3 Spec:
+ *   Container surface: surface-container-low, elevation level-1
+ *   Shape: extra-large top corners (28dp), square bottom (attached to screen edge)
+ *   Width: full width up to 640dp; centered at max-width 640dp on wider viewports
+ *   Top margin: 72dp default, 56dp when viewport > 640dp
+ *   Drag handle: 32dp × 4dp, on-surface-variant, centered, 22dp top/bottom padding → 48dp target
+ *   Scrim: bg-scrim, 32% opacity
+ *   State-layer opacities: hover 8% | focus 10% | pressed 10% | dragged 16%
+ */
 /**
  * CVA animation state variants for the Bottom Sheet panel.
  *
  * Motion decision rationale:
  * - Bottom sheet is a standard-size component → `default` speed tier
  * - Slides in/out of screen → composite `animate-md-*` utilities (not manual spring tokens)
- * - Scrim opacity is an effects property → `duration-short4 ease-standard` (legacy screen-level token)
+ * - Scrim opacity is an effects property → `duration-short4 ease-standard` (legacy screen-level)
  * - Snap spring is a spatial on-screen transition → `ease-spring-standard-default-spatial` +
  *   `duration-spring-standard-default-spatial` (applied in bottomSheetVariants base)
  * - Standard personality (not expressive) — sheets are utility UI, not moments of delight
@@ -9313,53 +9400,64 @@ declare const bottomSheetAnimationVariants: (props?: ({
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type BottomSheetAnimationVariants = VariantProps<typeof bottomSheetAnimationVariants>;
 /**
- * CVA variants for the Bottom Sheet container panel.
+ * Root container — the bottom sheet panel.
  *
  * MD3 tokens applied:
  * - Surface: bg-surface-container-low
  * - Elevation: shadow-elevation-1
- * - Shape: rounded-t-xl (top-left + top-right 28dp, bottom 0)
- * - Width: full width up to 640dp; centered at max-width 640dp on wider viewports
- *   (`mx-auto + max-w-[640px]` — at 752dp viewport this naturally produces the MD3-spec 56dp side margins)
- * - Height: constrained by max-height (72dp top margin by default, 56dp on > 640dp viewport)
- *   The sheet is always anchored to `bottom-0`; "top margin" is expressed as max-height so
- *   the sheet cannot overlap the top portion of the screen.
- * - Drag resize: height animates via `transition-[height]`; the sheet grows/shrinks from the
- *   bottom edge, always staying anchored — matching the MD3 spec "resize to another height" behaviour.
+ * - Shape: extra-large top corners (28dp via rounded-t-xl), square bottom (attached to edge)
+ * - Width: full width up to 640dp (mx-auto + w-[640px] max-w-full)
+ * - Height: snap-point driven via inline style; constrained by max-height to enforce top margin
+ *   Default: 72dp top margin → max-h-[calc(100vh-72px)]
+ *   Wide (> 640dp): 56dp top margin → sm:max-h-[calc(100vh-56px)]
+ * - Snap spring: spatial on-screen transition → spring-standard default spatial pair
+ *   data-[dragging]:transition-none suppresses spring during active drag (1:1 pointer tracking)
+ *
+ * NOTE: overflow-hidden clips content during height transitions. The handle's state layer and
+ * focus-ring overlay are sized/positioned to fit within the wrapper, so they are not clipped.
  */
 declare const bottomSheetVariants: (props?: ({
     variant?: "standard" | "modal" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type BottomSheetVariants = VariantProps<typeof bottomSheetVariants>;
 /**
- * CVA for the scrim overlay (modal variant only).
+ * Scrim overlay (modal variant only).
  *
  * MD3 tokens applied:
  * - bg-scrim: scrim surface role
  * - opacity-32: 32% opacity per MD3 spec
- * - Transition: opacity fade (scrim is an effects property — legacy screen-level tokens)
+ * - Transition: opacity fade (scrim is a screen-level effects property → legacy duration tokens)
  */
 declare const bottomSheetScrimVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
 type BottomSheetScrimVariants = VariantProps<typeof bottomSheetScrimVariants>;
 /**
- * CVA for the drag handle wrapper (touch/click target area).
+ * Drag handle wrapper — 48dp touch target area + group scope host.
+ *
+ * Carries `group/handle` so all handle child slots can consume data-* interaction
+ * states via `group-data-[x]/handle:` Tailwind selectors without any CVA variant props.
  *
- * MD3 spec: the top 48dp of the sheet is the interactive touch target area
- * when the drag handle is present. The wrapper provides this touch target.
+ * MD3 spec: 22dp top + 4dp handle + 22dp bottom = 48dp interaction zone.
+ * NOTE: py-[22px] is a measurement-derived value from MD3 spec; permitted exception.
+ *
+ * `relative` provides positioning context for the state layer and focus ring overlays.
+ * `focus-visible:outline-none` suppresses the browser default — the focus ring overlay
+ * in `bottomSheetHandleFocusRingVariants` provides the MD3-spec visible indicator instead.
  */
 declare const bottomSheetHandleWrapperVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
+type BottomSheetHandleWrapperVariants = VariantProps<typeof bottomSheetHandleWrapperVariants>;
 /**
- * CVA for the drag handle pill visual element.
+ * Drag handle pill — the visible 32×4dp decoration.
  *
  * MD3 tokens applied:
- * - bg-on-surface-variant: handle color
- * - w-8: 32dp width per MD3 spec
- * - h-1: 4dp height per MD3 spec
- * - rounded-full: fully rounded pill shape
- * - opacity-40: per MD3 spec (token deprecated but value still in spec)
+ * - bg-on-surface-variant: handle color (muted, low-emphasis by role — no opacity override needed)
+ * - w-8 / h-1: 32dp × 4dp per MD3 spec (measurement-derived; permitted exception)
+ * - rounded-full: fully-rounded pill shape
+ *
+ * `pointer-events-none` — all interaction is handled by the wrapper.
+ * `relative z-10` — renders above the state layer overlay.
  */
 declare const bottomSheetHandlePillVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
-type BottomSheetHandleVariants = VariantProps<typeof bottomSheetHandleWrapperVariants>;
+type BottomSheetHandleVariants = BottomSheetHandleWrapperVariants;
 
 /**
  * Variant of the MD3 Time Picker.