@tinybigui/react 0.21.1 → 0.23.0

package/dist/index.d.cts

@@ -756,12 +756,21 @@ declare const AppBarHeadless: React$1.ForwardRefExoticComponent<AppBarHeadlessPr
  * - Content flags (data-with-icon, data-loading) are set explicitly by the component.
  *
  * Slot responsibilities:
- *   buttonVariants           — root <button>; shape, color, elevation
+ *   buttonVariants           — root <button>; shape, text color, elevation (shadow)
+ *   buttonContainerVariants  — absolute inset child; background color + disabled bg override
  *   buttonStateLayerVariants — hover/focus/press opacity ring (absolute inset overlay)
  *   buttonFocusRingVariants  — keyboard focus outline, MUST NOT be inside overflow-hidden
  *   buttonIconVariants       — leading/trailing icon wrapper
  *   buttonLabelVariants      — label text slot
  *
+ * Why background lives on a child slot (buttonContainerVariants) rather than the root:
+ *   Tailwind `group-data-[x]/button:` generates a descendant combinator selector —
+ *   `.group\/button[data-x] .target`. The root <button> IS the group host and cannot
+ *   be its own descendant, so group selectors cannot target it directly. Moving the
+ *   background to an absolutely-positioned child span lets us use the proven
+ *   `group-data-[disabled]/button:bg-on-surface/12` pattern (same as Switch track)
+ *   to override the container background on disabled, guaranteeing correct specificity.
+ *
  * MD3 Spec:
  *   Shape: rounded-full (corner-full)
  *   Height: 32dp small | 40dp medium | 56dp large
@@ -780,12 +789,19 @@ declare const AppBarHeadless: React$1.ForwardRefExoticComponent<AppBarHeadlessPr
 /**
  * Root <button> element.
  *
+ * Owns: shape, text color, elevation (box-shadow), cursor, layout.
+ * Does NOT own background-color — that lives on buttonContainerVariants so
+ * the group-data disabled override can reach it via descendant selector.
+ *
  * IMPORTANT — overflow is intentionally NOT on the root.
  * Overflow clipping is delegated to the ripple container and state layer
  * via `overflow-hidden rounded-[inherit]` on those children. This lets the
  * focus ring span (`inset-[-3px]`) extend outside the button boundary and
  * remain fully visible — if overflow-hidden were on the root it would be
  * clipped to zero width.
+ *
+ * Elevation state classes use self-targeting `data-[x]:` (not group-data)
+ * because the root is the group host and cannot be its own descendant.
  */
 declare const buttonVariants: (props?: ({
     variant?: "text" | "filled" | "outlined" | "tonal" | "elevated" | null | undefined;
@@ -5331,10 +5347,17 @@ declare namespace MenuTrigger {
 /**
  * MD3 styled MenuItem component (Layer 3).
  *
- * All MD3 styles (selection colors, typography, density height) are applied
- * directly to the `<li role="menuitem">` element via RAC's render-prop className,
- * ensuring tests and assistive technologies see the correct classes on the
- * semantically meaningful element.
+ * Slot architecture (mirrors Button/Switch):
+ *   root (group/menuitem)        — layout, cursor, color, density height
+ *   highlight (z-0)              — selected/active background fill
+ *   stateLayer (z-[1])           — hover/press opacity overlay
+ *   focusRing (z-[2])            — keyboard focus outline (inset, not on state-layer)
+ *   ripple (z-[3])               — press ripple feedback
+ *   content (z-10)               — icon, label, trailing text/icon, description
+ *
+ * All interaction/selection styles are driven by data-* attributes that RAC
+ * MenuItem emits natively (data-hovered, data-pressed, data-focus-visible,
+ * data-selected, data-disabled, data-open) consumed via group-data selectors.
  *
  * @example
  * ```tsx
@@ -5351,6 +5374,10 @@ declare const MenuItem: React$1.ForwardRefExoticComponent<MenuItemProps & React$
  * Groups related `MenuItem` elements with an optional section header and an
  * optional top divider.
  *
+ * The section header color adapts to the `colorScheme` from `MenuContext`:
+ *   standard → text-on-surface-variant
+ *   vibrant  → text-on-tertiary-container
+ *
  * **Implementation note**: The divider is rendered as a SIBLING BEFORE the
  * `RACMenuSection`, NOT inside it. RAC's `Section`/`MenuSection` only accepts
  * `Header` and `MenuItem` children — placing a `Separator` inside the section
@@ -5435,17 +5462,20 @@ declare function HeadlessMenuDivider({ className, ...props }: SeparatorProps & {
 /**
  * Material Design 3 Menu container variants (CVA).
  *
- * Elevation: `shadow-elevation-2` (both styles)
- * Width: min 112dp / max 280dp per MD3 spec
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (menuStyle, colorScheme).
+ * - Animation (enter/exit motion) lives on `menuPopoverVariants` which is
+ *   applied to the RAC Popover element — the element where RAC actually emits
+ *   data-entering, data-exiting, and data-placement.
  *
  * Shape per menuStyle:
- * - baseline: `rounded-xs` (4dp extra-small)
- * - vertical: `rounded-lg` (16dp large)
+ *   baseline: `rounded-xs` (4dp extra-small)
+ *   vertical: `rounded-lg` (16dp large, MD3 Expressive)
  *
- * Background per colorScheme + menuStyle:
- * - baseline + standard: `bg-surface-container`
- * - vertical + standard: `bg-surface-container-low`
- * - vertical + vibrant:  `bg-tertiary-container`
+ * Background per menuStyle:
+ *   baseline: bg-surface-container (solid, houses all items)
+ *   vertical: bg-transparent (items paint their own segment cards; gap reveals
+ *             the page background between segments — acting as the divider)
  *
  * @see https://m3.material.io/components/menus/specs
  */
@@ -6249,12 +6279,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 +6293,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 +6335,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 +6370,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 +6394,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 +6445,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 +6492,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 +6563,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 +6621,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 +6673,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 +6724,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 +6773,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 +6859,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 +6882,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' })
  *   }