@tinybigui/react 0.21.0 → 0.22.0

package/dist/index.d.ts

@@ -6249,12 +6249,13 @@ type ChipVariants = VariantProps<typeof chipVariants>;
  * Structural variant of the MD3 Dialog.
  *
  * - `basic` — Floating dialog with headline, body, and action buttons.
- *   Supports scale + fade entry animation. Closes on scrim click or Escape.
- *   Max width 560dp per MD3 spec.
+ *   Supports scale + fade entry animation (MD3 Expressive, `animate-md-scale-in`).
+ *   Closes on scrim click or Escape. Max width 560dp per MD3 spec.
  *
  * - `fullscreen` — Full viewport overlay suited for mobile and complex forms.
  *   Replaces headline with a top app bar row (close icon + confirm action).
- *   Slide-up entry animation. Does NOT close on scrim click per MD3 spec.
+ *   Slide-up entry animation (`animate-md-slide-in-bottom`). Does NOT close on
+ *   scrim click per MD3 spec.
  *
  * @default 'basic'
  */
@@ -6262,10 +6263,12 @@ type DialogVariant = "basic" | "fullscreen";
 /**
  * Internal animation state machine for the Dialog.
  *
- * - `entering` — initial mount state before transition fires
- * - `visible`  — fully shown, entry animation complete
- * - `exiting`  — exit animation in progress
- * - `exited`   — removed from DOM
+ * - `entering` — initial mount state; dialog starts invisible before animation fires
+ * - `visible`  — entry animation active (`animate-md-scale-in` / `animate-md-slide-in-bottom`)
+ * - `exiting`  — exit animation active (`animate-md-scale-out` / `animate-md-slide-out-bottom`)
+ * - `exited`   — animation complete; portal removes element from DOM
+ *
+ * The scrim receives the same state for its own fade-in/out animation.
  */
 type DialogAnimationState = "entering" | "visible" | "exiting" | "exited";
 /**
@@ -6302,7 +6305,7 @@ interface DialogContextValue {
  *   onOpenChange={setOpen}
  *   aria-label="Confirm action"
  *   className="bg-surface-container-high rounded-xl shadow-elevation-3"
- *   scrimClassName="fixed inset-0 z-40 bg-scrim opacity-32"
+ *   scrimClassName="fixed inset-0 z-40 bg-scrim/32"
  * >
  *   <DialogHeadline>Confirm deletion?</DialogHeadline>
  *   <DialogContent>This action cannot be undone.</DialogContent>
@@ -6337,6 +6340,21 @@ interface DialogHeadlessProps {
      * When `DialogHeadline` is present, `aria-labelledby` is preferred automatically.
      */
     "aria-label"?: string;
+    /**
+     * Optional hero icon rendered centered above the headline per MD3 spec.
+     * When present, sets `data-with-icon` on the panel root so headline and
+     * supporting text center-align via `group-data-[with-icon]/dialog:` selectors.
+     *
+     * Only rendered in the `basic` variant.
+     *
+     * @example
+     * ```tsx
+     * <Dialog icon={<BookmarkIcon />}>
+     *   <DialogHeadline>Save bookmark?</DialogHeadline>
+     * </Dialog>
+     * ```
+     */
+    icon?: ReactNode;
     /**
      * Dialog slot content — typically `DialogHeadline`, `DialogContent`, `DialogActions`.
      */
@@ -6346,13 +6364,28 @@ interface DialogHeadlessProps {
      */
     className?: string;
     /**
-     * Additional CSS classes applied to the scrim overlay element.
+     * Additional CSS classes applied to the centering/positioning wrapper element.
+     * Consumed from `dialogWrapperVariants` by the styled `Dialog` layer.
      */
-    scrimClassName?: string;
+    wrapperClassName?: string;
+    /**
+     * Returns CSS classes for the scrim based on the current animation state.
+     * Called at render time to apply the correct fade-in/out animation.
+     * When `undefined`, falls back to a static base scrim class.
+     *
+     * @example
+     * ```tsx
+     * getScrimClassName={(state) => dialogScrimVariants({ animationState: state })}
+     * ```
+     */
+    getScrimClassName?: (state: DialogAnimationState) => string;
     /**
      * Additional CSS classes injected based on the current animation state.
      * Called at render time to merge CVA animation classes onto the panel.
      *
+     * Returns empty string when `prefers-reduced-motion: reduce` is active
+     * (handled by the styled `Dialog` layer via `useReducedMotion`).
+     *
      * @example
      * ```tsx
      * getAnimationClassName={(state) => dialogAnimationVariants({ animationState: state, variant })}
@@ -6382,6 +6415,16 @@ interface DialogHeadlessProps {
  *   </DialogActions>
  * </Dialog>
  *
+ * // With hero icon
+ * <Dialog icon={<BookmarkIcon />} open={open} onOpenChange={setOpen}>
+ *   <DialogHeadline>Save bookmark?</DialogHeadline>
+ *   <DialogContent>The page will be saved to your bookmarks.</DialogContent>
+ *   <DialogActions>
+ *     <Button variant="text" onPress={() => setOpen(false)}>Cancel</Button>
+ *     <Button variant="filled" onPress={handleSave}>Save</Button>
+ *   </DialogActions>
+ * </Dialog>
+ *
  * // Full-screen dialog (controlled)
  * <Dialog variant="fullscreen" open={open} onOpenChange={setOpen}>
  *   <DialogHeadline
@@ -6419,6 +6462,19 @@ interface DialogProps {
      * Accessible label for the dialog when no `DialogHeadline` is present.
      */
     "aria-label"?: string;
+    /**
+     * Optional hero icon rendered centered above the headline per MD3 spec.
+     * When present, headline and supporting text center-align automatically.
+     * Only rendered in the `basic` variant.
+     *
+     * @example
+     * ```tsx
+     * <Dialog icon={<BookmarkIcon />}>
+     *   <DialogHeadline>Save bookmark?</DialogHeadline>
+     * </Dialog>
+     * ```
+     */
+    icon?: ReactNode;
     /**
      * Dialog slot content — `DialogHeadline`, `DialogContent`, `DialogActions`.
      */
@@ -6477,6 +6533,10 @@ interface DialogHeadlineProps {
  * Renders as a scrollable `<div>` and provides its `id` to `DialogContext`
  * so the parent dialog panel can reference it via `aria-describedby`.
  *
+ * Shows MD3 scroll dividers (`border-outline-variant`) at the top and/or bottom
+ * of the scroll container when content overflows. Dividers are toggled via
+ * `data-scroll-divider-top` and `data-scroll-divider-bottom` attributes.
+ *
  * @example
  * ```tsx
  * <DialogContent>
@@ -6531,17 +6591,24 @@ interface DialogActionsProps {
  * **Basic** (default):
  * - Floating card: `bg-surface-container-high`, `rounded-xl`, `shadow-elevation-3`
  * - Centered in viewport (min 280dp, max 560dp width)
- * - Scale + fade entry animation (`duration-medium4 / ease-emphasized-decelerate`)
- * - Fade exit animation (`duration-short2 / ease-emphasized-accelerate`)
+ * - Scale + fade entry animation (`animate-md-scale-in`, expressive-fast-spatial 350ms)
+ * - Scale + fade exit animation (`animate-md-scale-out`, emphasized-accelerate 200ms)
+ * - Scrim fades in/out (`animate-md-fade-in` / `animate-md-fade-out`)
  * - Closes on scrim click or Escape key
+ * - Optional hero icon above headline (`icon` prop) — centers headline + content text
  *
  * **Full-screen**:
  * - Full viewport coverage — suited for mobile and complex forms
  * - No rounded corners, no elevation shadow
- * - Slide-up entry / slide-down exit animation
+ * - Slide-up entry / slide-down exit animation (`animate-md-slide-in-bottom` / out)
  * - Does NOT close on scrim click per MD3 spec (only via Escape or close button)
  * - Headline replaced by top app bar row (close icon + confirm action)
  *
+ * **Reduced motion**:
+ * - When `prefers-reduced-motion: reduce` is active, all keyframe animations are
+ *   suppressed (no animate-md-* class applied). Dialog appears/disappears instantly.
+ * - `transition-none` is appended so any inherited transitions are also disabled.
+ *
  * Both variants:
  * - `role="dialog"` + `aria-modal="true"` (React Aria `useDialog`)
  * - `aria-labelledby` pointing to `DialogHeadline` id
@@ -6576,6 +6643,16 @@ interface DialogActionsProps {
  *   );
  * }
  *
+ * // With hero icon
+ * <Dialog icon={<BookmarkIcon />} open={open} onOpenChange={setOpen}>
+ *   <DialogHeadline>Save bookmark?</DialogHeadline>
+ *   <DialogContent>The page will be saved to your bookmarks.</DialogContent>
+ *   <DialogActions>
+ *     <Button variant="text" onPress={() => setOpen(false)}>Cancel</Button>
+ *     <Button variant="filled" onPress={handleSave}>Save</Button>
+ *   </DialogActions>
+ * </Dialog>
+ *
  * // Full-screen dialog — mobile form flow
  * function NewEventDialog() {
  *   const [open, setOpen] = useState(false);
@@ -6617,9 +6694,15 @@ declare const Dialog: React$1.ForwardRefExoticComponent<DialogProps & React$1.Re
  * Renders as an `<h2>` element and registers its `id` with the parent
  * `DialogContext` so the dialog panel can wire `aria-labelledby` correctly.
  *
+ * When the parent dialog has a hero `icon` prop, the panel root carries
+ * `data-with-icon` and `group/dialog`, so the `group-data-[with-icon]/dialog:text-center`
+ * selector in `dialogHeadlineVariants` automatically centers the headline text —
+ * no additional props needed here.
+ *
  * For the `fullscreen` variant, the headline renders as a top app bar row
  * containing optional `closeButton` (leading icon button) and `confirmButton`
- * (trailing text action) per MD3 Full-screen Dialog spec.
+ * (trailing text action) per MD3 Full-screen Dialog spec. The fullscreen app bar
+ * always shows a `border-b border-outline-variant` divider below it.
  *
  * Must be rendered inside a `<Dialog>` or `<DialogHeadless>` component.
  *
@@ -6660,6 +6743,13 @@ declare const DialogHeadline: React$1.ForwardRefExoticComponent<DialogHeadlinePr
  * Styled with `text-body-medium` and `text-on-surface-variant` per MD3 spec.
  * Overflows vertically when content exceeds the available height.
  *
+ * **Scroll dividers**: Shows `border-outline-variant` dividers at the top and/or
+ * bottom edge when content overflows and is not scrolled to the respective edge.
+ * Dividers are toggled by setting `data-scroll-divider-top` / `data-scroll-divider-bottom`
+ * presence attributes on the element. The CVA base class uses
+ * `data-[scroll-divider-top]:border-t` and `data-[scroll-divider-bottom]:border-b`
+ * to apply the borders — no style props needed.
+ *
  * Must be rendered inside a `<Dialog>` or `<DialogHeadless>` component.
  *
  * @example
@@ -6739,7 +6829,12 @@ declare function useDialogContext(): DialogContextValue;
  *   Basic variant is dismissable (Escape + outside click);
  *   Full-screen variant is Escape-dismissable only (no scrim click) per MD3 spec.
  * - **Animation state machine**: `entering → visible → exiting → exited`
- *   mirrors the Snackbar animation pattern.
+ *   Exit advances on `onAnimationEnd` with `e.target === e.currentTarget` guard
+ *   (prevents child animation events from advancing the state machine), plus a
+ *   250ms fallback timer in case the animation event doesn't fire.
+ * - **Scrim animation**: state-driven via `getScrimClassName(animationState)`.
+ * - **Hero icon**: optional `icon` prop renders centered above headline;
+ *   sets `data-with-icon` on panel root for group-data centering of headline/content.
  * - **ARIA wiring**: `DialogContext` provides stable IDs for `aria-labelledby`
  *   and `aria-describedby`, consumed by slot sub-components.
  *
@@ -6757,8 +6852,9 @@ declare function useDialogContext(): DialogContextValue;
  *   variant="basic"
  *   open={open}
  *   onOpenChange={setOpen}
- *   className={cn(dialogWrapperVariants({ variant: 'basic' }), dialogPanelVariants({ variant: 'basic' }))}
- *   scrimClassName={dialogScrimVariants()}
+ *   className={cn(dialogPanelVariants({ variant: 'basic' }))}
+ *   wrapperClassName={dialogWrapperVariants({ variant: 'basic' })}
+ *   getScrimClassName={(state) => dialogScrimVariants({ animationState: state })}
  *   getAnimationClassName={(state) =>
  *     dialogAnimationVariants({ animationState: state, variant: 'basic' })
  *   }
@@ -6796,13 +6892,19 @@ interface TooltipTriggerStyledProps {
  * machine so that tooltips fade/scale in on open and fade/scale out before
  * unmounting from the DOM, per MD3 motion specs.
  *
- * Animation state machine:
+ * When `prefers-reduced-motion: reduce` is active the overlay is unmounted
+ * immediately on close — no exit animation, no `animationend` dependency.
+ * This prevents the stuck-mount bug that occurs when the global CSS reset
+ * collapses animations and `animationend` never fires.
+ *
+ * Animation state machine (standard motion):
  * 1. RA fires `onOpenChange(true)`  → mount overlay, play entry animation
  * 2. RA fires `onOpenChange(false)` → keep mounted, play exit animation
  * 3. `animationend` fires          → unmount overlay
  *
- * The controlled `isOpen={isMounted}` prop passed to `TooltipTriggerHeadless`
- * is what keeps the overlay alive during the exit animation phase.
+ * Animation state machine (reduced motion):
+ * 1. RA fires `onOpenChange(true)`  → mount overlay, no animation
+ * 2. RA fires `onOpenChange(false)` → unmount overlay immediately
  *
  * @example
  * ```tsx
@@ -6971,15 +7073,18 @@ interface TooltipHeadlessProps {
  * Renders a single-line text label with MD3 inverse-surface styling.
  * Animation is driven by the `TooltipAnimationContext` provided by
  * `TooltipTrigger`:
- * - Entry: `animate-md-scale-in`  (scale 0.85 + fade → natural)
- * - Exit:  `animate-md-scale-out` (natural → scale 0.85 + fade)
+ * - Entry: `animate-md-scale-in`  (expressive-fast-spatial: 350ms, scale 0.85 → 1 + fade)
+ * - Exit:  `animate-md-scale-out` (emphasized-accelerate: 200ms, scale 1 → 0.85 + fade)
+ * - None:  no animation class when `prefers-reduced-motion: reduce` is active
  *
  * MD3 Tokens applied:
- * - `bg-inverse-surface`     — inverted surface for max contrast
- * - `text-inverse-on-surface` — content color on inverted surface
- * - `rounded-xs`             — 4dp corner radius
- * - `max-w-50`               — 200dp maximum width
- * - `text-body-small`        — MD3 body-small typography
+ * - `bg-inverse-surface`      — inverted surface for maximum contrast
+ * - `text-inverse-on-surface` — content colour on inverted surface
+ * - `rounded-xs`              — 4dp corner radius (CornerExtraSmall)
+ * - `text-body-small`         — BodySmall typescale (12sp)
+ * - `min-h-6`                 — 24dp minimum height
+ * - `max-w-50`                — 200dp maximum width
+ * - `px-2 py-1`               — 8dp × 4dp padding
  *
  * Must be used as the second child of `TooltipTrigger`.
  *
@@ -6996,19 +7101,29 @@ declare const Tooltip: React$1.ForwardRefExoticComponent<TooltipProps & React$1.
 /**
  * `RichTooltip` — Layer 3 MD3 Rich Tooltip styled component.
  *
- * Supports an optional title, multi-line supporting text, and an optional
- * action button per MD3 Rich Tooltip specification.
+ * Supports an optional title (subhead), multi-line supporting text, and an
+ * optional action button per MD3 Rich Tooltip specification.
  * Animation is driven by the `TooltipAnimationContext` provided by
  * `TooltipTrigger`:
- * - Entry: `animate-md-scale-in`  (scale 0.85 + fade → natural)
- * - Exit:  `animate-md-scale-out` (natural → scale 0.85 + fade)
- *
- * MD3 Tokens applied:
- * - `bg-surface-container`  — surface container background
- * - `text-on-surface`       — content color on surface
- * - `shadow-elevation-2`    — MD3 elevation level 2
- * - `rounded-md`            — medium corner radius
- * - `max-w-80`              — 320dp maximum width
+ * - Entry: `animate-md-scale-in`  (expressive-fast-spatial: 350ms)
+ * - Exit:  `animate-md-scale-out` (emphasized-accelerate: 200ms)
+ * - None:  no animation class when `prefers-reduced-motion: reduce` is active
+ *
+ * MD3 Tokens applied — container:
+ * - `bg-surface-container`   — surface container background
+ * - `text-on-surface`        — base content colour
+ * - `shadow-elevation-2`     — MD3 elevation level 2
+ * - `rounded-md`             — 12dp corner radius (CornerMedium)
+ * - `max-w-80`               — 320dp maximum width
+ * - `px-4 py-3`              — 16dp × 12dp padding
+ *
+ * MD3 Tokens applied — subhead (title):
+ * - `text-title-small`        — TitleSmall typescale
+ * - `text-on-surface-variant` — subhead colour role per MD3 spec
+ *
+ * MD3 Tokens applied — supporting text:
+ * - `text-body-medium`        — BodyMedium typescale
+ * - `text-on-surface-variant` — same colour role as subhead
  *
  * Must be used as the second child of `TooltipTrigger`.
  *
@@ -7091,46 +7206,50 @@ declare function TooltipTriggerHeadless({ children, delay, isDisabled, isOpen, d
 declare function TooltipOverlayHeadless({ tooltipProps: incomingTooltipProps, triggerRef, placement, offset, className, children, onPointerEnter, onPointerLeave, }: TooltipHeadlessProps): JSX$1.Element | null;
 
 /**
- * Material Design 3 Plain Tooltip Variants (CVA)
+ * Plain tooltip container.
+ *
+ * Renders an inline-flex pill that vertically centres a single-line text label
+ * against the 24dp minimum height.
  *
- * Base tokens per MD3 spec:
- * - bg-inverse-surface / text-inverse-on-surface — inverted surface for contrast
- * - rounded-xs — 4dp corner radius (CornerExtraSmall)
- * - min-h-6 — 24dp minimum height
- * - max-w-50 — 200dp maximum width
- * - w-fit — shrink-wrap to content width
- * - px-2 py-1 — 8dp horizontal, 4dp vertical padding
- * - text-body-small — MD3 BodySmall typography (12px)
+ * MD3 Tokens:
+ * - `bg-inverse-surface`       — inverted surface for maximum contrast
+ * - `text-inverse-on-surface`  — content colour on inverted surface
+ * - `rounded-xs`               — 4dp corner radius (CornerExtraSmall)
+ * - `text-body-small`          — BodySmall typescale (12sp)
+ * - `min-h-6`                  — 24dp minimum height
+ * - `max-w-50`                 — 200dp maximum width
+ * - `px-2 py-1`                — 8dp × 4dp padding
+ * - `z-50`                     — above all page content
  *
- * `isVisible` drives the entry/exit animation class:
- * - true  → animate-md-scale-in  (component entering with scale+fade)
- * - false → animate-md-scale-out (component exiting with scale+fade)
+ * Motion:
+ * - `enter` → `animate-md-scale-in`  (expressive-fast-spatial: 350ms, scale 0.85 → 1 + fade)
+ * - `exit`  → `animate-md-scale-out` (emphasized-accelerate: 200ms, scale 1 → 0.85 + fade)
+ * - `none`  → no animation class     (prefers-reduced-motion guard)
  */
 declare const tooltipVariants: (props?: ({
-    isVisible?: boolean | null | undefined;
+    animation?: "none" | "enter" | "exit" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 /**
- * Material Design 3 Rich Tooltip Variants (CVA)
+ * Rich tooltip container.
+ *
+ * Wraps the title, supporting text, and optional action row in a flex column.
  *
- * Base tokens per MD3 spec:
- * - bg-surface-container / text-on-surface — surface container background
- * - shadow-elevation-2  — MD3 elevation level 2
- * - rounded-md          — 12dp corner radius (CornerMedium)
- * - min-h-6             — 24dp minimum height
- * - max-w-80            — 320dp maximum width
- * - w-fit               — shrink-wrap to content width
- * - px-4 py-3           — 16dp horizontal, 12dp vertical padding
+ * MD3 Tokens:
+ * - `bg-surface-container`   — surface container background
+ * - `text-on-surface`        — content colour on surface
+ * - `shadow-elevation-2`     — MD3 elevation level 2
+ * - `rounded-md`             — 12dp corner radius (CornerMedium)
+ * - `min-h-6`                — 24dp minimum height
+ * - `max-w-80`               — 320dp maximum width
+ * - `px-4 py-3`              — 16dp × 12dp padding
+ * - `z-50`                   — above all page content
  *
- * `isVisible` drives the entry/exit animation class:
- * - true  → animate-md-scale-in  (component entering with scale+fade)
- * - false → animate-md-scale-out (component exiting with scale+fade)
+ * Motion: same `animation` variant as plain tooltip.
  */
 declare const richTooltipVariants: (props?: ({
-    isVisible?: boolean | null | undefined;
+    animation?: "none" | "enter" | "exit" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
-/** Variant prop types inferred from `tooltipVariants`. */
 type TooltipVariants = VariantProps<typeof tooltipVariants>;
-/** Variant prop types inferred from `richTooltipVariants`. */
 type RichTooltipVariants = VariantProps<typeof richTooltipVariants>;
 
 /**