@tinybigui/react 0.18.0 → 0.20.0

package/dist/index.d.cts

@@ -5477,10 +5477,19 @@ type SnackbarSeverity = "default" | "error";
 /**
  * Internal animation state machine for the Snackbar.
  *
- * - `entering` → zoom-in start: scale-75 + opacity-0 (no duration, paints before transition)
- * - `visible`  → scale-100 + opacity-100 (medium1 / standard-decelerate = 250ms)
- * - `exiting`  → scale-75 + opacity-0 (short4 / standard-accelerate = 200ms)
+ * - `entering` → initial paint: opacity-0 + directional translate offset (no duration)
+ * - `visible`  → slide in + fade in: translate-y-0 + opacity-100
+ *                (spring-standard-default-effects = 200ms, no overshoot)
+ * - `exiting`  → slide out + fade out: offset + opacity-0
+ *                (spring-standard-fast-effects = 150ms)
  * - `exited`   → removed from DOM / stack updated
+ *
+ * The translate direction is position-aware:
+ *   bottom positions → slide up from below (translate-y-3 → translate-y-0)
+ *   top positions    → slide down from above (-translate-y-3 → translate-y-0)
+ *
+ * When `prefers-reduced-motion` is active, the translate offset is suppressed
+ * and only opacity transitions (fade-only).
  */
 type SnackbarAnimationState = "entering" | "visible" | "exiting" | "exited";
 /**
@@ -5679,14 +5688,23 @@ interface SnackbarProviderProps {
  * Renders one of four MD3 Snackbar content configurations:
  * 1. Single-line message only
  * 2. Two-line message + `supportingText`
- * 3. Single-line with text `action` button (styled `Button variant="text"` with
- *    `inverse-primary` color per MD3 spec)
+ * 3. Single-line with text `action` button (styled with `inverse-primary` per MD3 spec)
  * 4. Single-line with close icon (or combined with action)
  *
  * Uses `SnackbarHeadless` for all behavioral concerns (ARIA live region,
  * auto-dismiss timer with pause/resume, animation state machine) and CVA
  * variants for MD3-compliant visual styling.
  *
+ * **Motion**: Position-aware slide + fade using spring-standard effects tokens.
+ * Automatically respects `prefers-reduced-motion` (fade-only when reduced motion
+ * is preferred — no translate offset).
+ *
+ * **State layers**: Dedicated slot components (`SnackbarActionButton`,
+ * `SnackbarCloseButton`) replace the shared `Button`/`IconButton` components.
+ * This ensures the state-layer colors are MD3-correct on an `inverse-surface`:
+ * - Action button state layer: `bg-inverse-primary`
+ * - Close button state layer: `bg-inverse-on-surface`
+ *
  * For typical app usage, render inside `SnackbarProvider` and trigger via
  * the `useSnackbar` hook. For declarative/test usage, it can be rendered
  * standalone.
@@ -8845,6 +8863,26 @@ type SliderOrientation = "horizontal" | "vertical";
  * @example ['Min price', 'Max price']
  */
 type SliderRangeThumbLabels = [string, string];
+/**
+ * Render state provided to `renderThumbContent` for each thumb slot.
+ *
+ * The styled layer (`Slider`) uses this to render the visual handle,
+ * state layer, and value indicator inside the React Aria thumb element.
+ */
+interface SliderThumbRenderState {
+    /** Zero-based index of this thumb (0 for single-thumb, 0 or 1 for range). */
+    index: number;
+    /** Current numeric value of this thumb (from React Stately state). */
+    value: number;
+    /** Whether this thumb is currently being dragged (pointer down). */
+    isDragging: boolean;
+    /** Whether keyboard focus ring is visible on this thumb. */
+    isFocusVisible: boolean;
+    /** Whether pointer is hovering over this thumb. */
+    isHovered: boolean;
+    /** Whether the slider is disabled. */
+    isDisabled: boolean;
+}
 /**
  * Props for the headless `SliderHeadless` primitive (Layer 2).
  *
@@ -8949,10 +8987,33 @@ interface SliderHeadlessProps {
      */
     isDisabled?: boolean;
     /**
-     * Content (children) rendered inside the slider container.
-     * Used by the styled layer to inject track, handle, stops, etc.
+     * Content (children) rendered inside the slider track element.
+     * Used by the styled layer to inject track layout.
      */
     children?: React__default.ReactNode;
+    /**
+     * CSS classes applied to the `data-track` region element.
+     * The styled layer uses this to carry the size-based height/width and
+     * `touch-none` on the element React Aria measures for pointer math.
+     * When omitted, the track region defaults to `relative w-full`.
+     */
+    trackClassName?: string;
+    /**
+     * Render prop called for each thumb to produce visual thumb content
+     * (handle, state layer, value indicator). Receives the thumb's current
+     * render state. When provided, visual content is rendered inside the
+     * React Aria thumb element (which is absolutely positioned at the value %).
+     *
+     * Used by the styled `Slider` layer; advanced users of `SliderHeadless`
+     * may supply custom thumb visuals.
+     */
+    renderThumbContent?: (state: SliderThumbRenderState) => React__default.ReactNode;
+    /**
+     * Called when any thumb's dragging state changes.
+     * Receives the thumb index and a boolean indicating whether it is dragging.
+     * Used by the styled layer to suppress track animation during pointer drag.
+     */
+    onThumbDraggingChange?: (index: number, isDragging: boolean) => void;
     /**
      * Additional CSS classes applied to the slider root element.
      */
@@ -9046,7 +9107,7 @@ interface SliderThumbProps {
  * />
  * ```
  */
-interface SliderProps extends Omit<SliderHeadlessProps, "children"> {
+interface SliderProps extends Omit<SliderHeadlessProps, "children" | "renderThumbContent" | "onThumbDraggingChange"> {
     /**
      * MD3 Expressive size preset.
      * Controls track height, handle height, corner radius, and icon size.
@@ -9077,7 +9138,11 @@ interface SliderProps extends Omit<SliderHeadlessProps, "children"> {
 }
 /**
  * Interactive state of a slider thumb.
- * Used internally by the styled layer for state-dependent styling.
+ *
+ * @deprecated The styled Slider now drives interaction states via React Aria
+ *   hooks + `data-*` attributes (group-data-[x]/slider-thumb selectors) instead
+ *   of a manual state machine. This type is retained only for backwards
+ *   compatibility with existing usages of `SliderHeadlessProps`.
  *
  * @internal
  */
@@ -9085,6 +9150,10 @@ type SliderThumbState = "enabled" | "hovered" | "pressed" | "disabled";
 /**
  * Render state passed to internal sub-components for conditional styling.
  *
+ * @deprecated The styled Slider now uses `SliderThumbRenderState` (per-thumb
+ *   render state) provided by the `renderThumbContent` render prop. This type
+ *   is retained only for backwards compatibility.
+ *
  * @internal
  */
 interface SliderRenderState {
@@ -9103,15 +9172,31 @@ interface SliderRenderState {
 /**
  * Material Design 3 Slider Component (Layer 3: Styled)
  *
- * Wraps SliderHeadless with CVA styling for all five MD3 Expressive sizes.
- * Renders the visual track layout (active track → handle → inactive track) as
- * children inside the headless track element.
- *
+ * Wraps `SliderHeadless` with CVA styling for all five MD3 Expressive sizes.
+ * Renders the visual track layout (active/inactive tracks) as children inside
+ * the headless track element. The visual handle, state layer, and value indicator
+ * are rendered as children of the React Aria thumb element via `renderThumbContent`,
+ * which positions them exactly at the value percentage.
+ *
+ * **Architecture (Variants-vs-States)**
+ * - Interaction states (hover, pressed/dragging, disabled, focus) are driven by
+ *   React Aria hooks → `getInteractionDataAttributes` → `data-*` on the RA thumb
+ *   (`group/slider-thumb`) → `group-data-[x]/slider-thumb:*` CSS selectors.
+ * - No manual pointer state machine — React Aria's `isDragging`, `isHovered`,
+ *   and `isFocusVisible` are the single source of truth.
+ * - Disabled track/stop colors use `group-data-[disabled]/slider:*` selectors
+ *   from the root `group/slider` scope.
+ *
+ * **Geometry (documented inline-style exception)**
  * Track widths are driven by runtime values and use inline `flexBasis` styles —
  * a documented exception for geometry that cannot be expressed as design tokens.
  *
- * Motion: MD3 Appendix E token pairings applied; JS-driven animations are
- * guarded with `useReducedMotion()`.
+ * **Motion**
+ * - Track fill: spring-standard-fast-spatial (suppressed during drag + reduced motion)
+ * - Handle width: spring-standard-fast-spatial (suppressed for reduced motion)
+ * - State layer opacity: spring-standard-fast-effects (always present; CSS media
+ *   query handles `prefers-reduced-motion` for CSS-driven changes)
+ * - Value indicator: spring-standard-fast-spatial (suppressed for reduced motion)
  *
  * @example
  * ```tsx
@@ -9143,6 +9228,8 @@ declare const Slider: React__default.ForwardRefExoticComponent<SliderProps & Rea
  * - Discrete stepping support
  * - Live value announcements via <output>
  * - data-* attributes for styled layer targeting
+ * - `group/slider-thumb` scope on each thumb for group-data CSS selectors
+ * - `renderThumbContent` render prop for injecting visual content inside RA thumb
  *
  * @example
  * ```tsx
@@ -9161,81 +9248,98 @@ declare const Slider: React__default.ForwardRefExoticComponent<SliderProps & Rea
 declare const SliderHeadless: React__default.ForwardRefExoticComponent<SliderHeadlessProps & React__default.RefAttributes<HTMLDivElement>>;
 
 /**
- * CVA variants for the Slider container (root element — the `role="group"` div).
+ * Slider root container variants.
+ *
+ * The root element carries:
+ * - `group/slider` — scope for track/stop disabled-state selectors
+ *   (`group-data-[disabled]/slider:*`)
  *
- * MD3 spec §4.2: Container height equals handle height for each size.
- * MD3 spec §4.1, §10.9: In vertical orientation, container width = handle height (dimensions transposed).
- * Applied via className on SliderHeadless so the groupProps div receives these classes.
+ * Horizontal layout: CSS grid with label (col 1) + output (col 2) in the first
+ * row, and the full-width track region spanning both columns in the second row.
+ * This matches the canonical React Aria / MD3 layout and prevents the track
+ * from collapsing when label + output are inline siblings.
+ *
+ * Vertical layout: flex-col so label is above the track.
+ * The size-based HEIGHT lives on the track region, not here (the container is
+ * auto-height in horizontal so it wraps the grid rows naturally).
  */
 declare const sliderContainerVariants: (props?: ({
-    size?: "small" | "large" | "medium" | "xsmall" | "xlarge" | null | undefined;
     orientation?: "vertical" | "horizontal" | null | undefined;
-    disabled?: boolean | null | undefined;
+    size?: "small" | "large" | "medium" | "xsmall" | "xlarge" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 /**
- * CVA for the active track (filled portion).
+ * Absolute-fill container that holds the active and inactive track segments.
+ *
+ * Segments are `position: absolute` children sharing the same percentage
+ * coordinate space as the React Aria thumbs, so fills always align with
+ * handle positions regardless of value or orientation.
+ *
+ * The MD3 6dp thumb-track gap (`thumbTrackGapSize`) is applied as a symmetric
+ * 3px offset on each side of the thumb in the parent's inline position styles.
+ *
+ * `pointer-events-none` lets React Aria's track click-to-seek events
+ * reach the `data-track` region without interference.
+ */
+declare const sliderTrackLayoutVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
+/**
+ * The filled (active) portion of the slider track.
+ *
+ * **Color**: `bg-primary`
+ * **Disabled**: driven by `group-data-[disabled]/slider:*` — no CVA disabled variant.
+ * **Transition**: `flex-basis` spring (spatial) when not dragging/reduced-motion.
  *
- * MD3 spec §6, §8.1, §10.2: `bg-primary`, size-dependent outer corners, 2dp inner corners.
- * Inner corner (near handle) is always 2dp regardless of size.
- * MD3 spec §10.9: In vertical orientation, track thickness becomes width (not height).
- * Transition: flex-basis spatial spring (md3-motion spring-standard-fast-spatial).
+ * MD3 §6, §10.2: outer corner = size corner token, inner corner (near handle) = 2dp.
+ * NOTE: measurement-derived corner values from MD3 spec §6; permitted exception.
  */
 declare const sliderActiveTrackVariants: (props?: ({
     size?: "small" | "large" | "medium" | "xsmall" | "xlarge" | null | undefined;
     orientation?: "vertical" | "horizontal" | null | undefined;
-    disabled?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 /**
- * CVA for the inactive track (unfilled portion).
+ * The unfilled (inactive) portion of the slider track.
+ *
+ * **Color**: `bg-secondary-container`
+ * **Disabled**: driven by `group-data-[disabled]/slider:*` — no CVA disabled variant.
  *
- * MD3 spec §6, §8.1, §10.2: `bg-secondary-container`, 2dp inner corners, size-dependent outer corners.
- * MD3 spec §10.9: In vertical orientation, track thickness becomes width (not height).
- * Disabled: `bg-on-surface` at 10% opacity via Tailwind alpha modifier.
+ * MD3 §6, §10.2: inner corner (near handle) = 2dp, outer corner = size corner token.
+ * NOTE: measurement-derived corner values from MD3 spec §6; permitted exception.
  */
 declare const sliderInactiveTrackVariants: (props?: ({
     size?: "small" | "large" | "medium" | "xsmall" | "xlarge" | null | undefined;
     orientation?: "vertical" | "horizontal" | null | undefined;
-    disabled?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 /**
- * CVA for the handle/thumb element.
+ * Visual handle (thumb indicator) element inside the React Aria thumb container.
  *
- * MD3 spec §6, §9, §10.3: 4dp wide, full container height, 2dp border-radius.
- * MD3 spec §10.9: In vertical orientation, width and height are transposed —
- *   handle becomes 4dp tall (main axis) × full width (cross axis).
- * Width narrows to 2dp on press (md3 spec §9.3).
- * Motion: transition-[width] with duration-short2 + ease-standard applied conditionally
- * in Slider.tsx based on useReducedMotion() guard (MD3 Appendix E).
+ * **Architecture**: This element lives inside the `group/slider-thumb` scope (the
+ * RA-positioned thumb div). All interaction states are driven by
+ * `group-data-[x]/slider-thumb:*` selectors — no CVA interaction-state variants.
+ *
+ * **Pressed width**: `group-data-[pressed]/slider-thumb:w-[2px]` (4dp → 2dp, MD3 spec)
+ * **Motion**: `transition-[width]` with spring-standard-fast-spatial tokens.
+ *   Applied conditionally in `Slider.tsx` (suppressed for `useReducedMotion()`).
  */
 declare const sliderHandleVariants: (props?: ({
     size?: "small" | "large" | "medium" | "xsmall" | "xlarge" | null | undefined;
     orientation?: "vertical" | "horizontal" | null | undefined;
-    pressed?: boolean | null | undefined;
-    disabled?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 /**
- * CVA for the handle's state layer overlay.
+ * State layer overlay on the handle (hover ripple).
  *
- * MD3 spec §8.3: Inset overlay within the handle.
- * - Hover: on-primary at 8% opacity
- * - Focus/Pressed: on-primary at 10% opacity
- * Motion: transition-opacity with duration-short1 + ease-standard applied conditionally
- * in Slider.tsx based on useReducedMotion() guard (MD3 Appendix E).
- */
-declare const sliderHandleStateLayerVariants: (props?: ({
-    state?: "disabled" | "enabled" | "hovered" | "pressed" | "focused" | null | undefined;
-} & class_variance_authority_types.ClassProp) | undefined) => string;
-/**
- * CVA for the track layout container (holds active track + handle + inactive track).
+ * **Architecture**: Lives inside `group/slider-thumb`; opacity driven entirely
+ * by `group-data-[x]/slider-thumb:opacity-*` selectors — no CVA state variant.
+ *
+ * State-layer opacities per MD3 spec:
+ * - hover:   8%   (`opacity-8`)
+ * - focused: 10%  (`opacity-10`)
+ * - pressed: 10%  (`opacity-10`)
+ * - dragged: 16%  (`opacity-16`) — note: drag = pressed in RA isDragging → data-pressed
  *
- * MD3 spec §7, §10.2: Flex row with 6dp gap between handle and track segments.
- * The 6dp gap is the `thumbTrackGapSize` token from MD3 spec.
- * MD3 spec §10.9: Vertical orientation uses flex-col-reverse for bottom-to-top fill.
- * `relative` is required so the absolute stops overlay is positioned within.
+ * **Motion**: `transition-opacity` with spring-standard-fast-effects tokens.
+ *   Always present; `@media prefers-reduced-motion` suppresses the transition at
+ *   the CSS level.
  */
-declare const sliderTrackLayoutVariants: (props?: ({
-    orientation?: "vertical" | "horizontal" | null | undefined;
-} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare const sliderHandleStateLayerVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
 
 /**
  * Structural variant of the MD3 Bottom Sheet.