@tinybigui/react 0.22.0 → 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
  */

package/dist/index.d.ts

@@ -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
  */