@tinybigui/react 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -598,6 +598,9 @@ interface AppBarProps {
  * Renders a `<header role="banner">` and manages scroll elevation state.
  * Use this for full visual control when the styled `AppBar` is not sufficient.
  *
+ * Extends `React.HTMLAttributes<HTMLElement>` so all standard HTML attributes
+ * (including `data-*` attributes) are forwarded to the underlying `<header>`.
+ *
  * @example
  * ```tsx
  * <AppBarHeadless
@@ -609,11 +612,7 @@ interface AppBarProps {
  * </AppBarHeadless>
  * ```
  */
-interface AppBarHeadlessProps {
-    /**
-     * Additional CSS classes
-     */
-    className?: string;
+interface AppBarHeadlessProps extends React__default.HTMLAttributes<HTMLElement> {
     /**
      * The content to render inside the header
      */
@@ -630,26 +629,41 @@ interface AppBarHeadlessProps {
 }
 
 /**
- * Material Design 3 Top App Bar Component
+ * Material Design 3 Top App Bar Component (M3 Expressive Flexible)
  *
  * Provides context and actions for the current screen. Supports four size variants,
- * a navigation icon slot, title, and trailing action icon slots. Implements
- * scroll-triggered elevation changes per MD3 specification.
+ * a navigation icon slot, title, optional subtitle, and trailing action icon slots.
+ * Implements scroll-triggered elevation changes per MD3 specification.
  *
  * **Architecture:**
- * - Layer 3 (this file): MD3 styled, CVA variants, layout composition
+ * - Layer 3 (this file): MD3 styled, CVA slot variants, layout composition
  * - Layer 2: `AppBarHeadless` — `<header role="banner">`, scroll state
  * - Layer 1: React Aria via `<IconButton>` in consumer slots
  *
+ * **Slot-based styling:**
+ * All layout and state styling follows the Variants vs States pattern:
+ * - `variant` prop drives design-time choices (height, type scale, alignment)
+ * - Scroll elevation state is emitted as `data-scrolled=""` on the root and
+ *   consumed by `group-data-[scrolled]/appbar:*` selectors (presence-based)
+ * - Subtitle presence is emitted as `data-with-subtitle=""` on the root and
+ *   used to grow medium/large bar heights (group-data-[with-subtitle]/appbar:*)
+ *
  * **Key Features:**
  * - 4 MD3 variants: small, center-aligned, medium, large
- * - Optional subtitle (per M3 Expressive spec) with per-variant typography
+ * - M3 Expressive flexible: medium and large grow vertically with a subtitle
+ *   (136dp / 152dp respectively), per the M3 Expressive flexible spec
  * - Composable API: pass `<IconButton>` nodes into navigation and action slots
- * - Scroll elevation: flat (bg-surface) at rest → bg-surface-container + shadow-elevation-2 on scroll
+ * - Scroll elevation: bg-surface at rest → bg-surface-container + shadow-elevation-2
  * - Controlled and uncontrolled scroll state
+ * - MD3 motion: background-color + box-shadow use standard effects spring pair
  * - WCAG 2.1 AA: `role="banner"` landmark, keyboard accessible slots
  * - Dark mode via existing token system
  *
+ * **M3 Expressive Flexible subtitle type scales:**
+ * - small / center-aligned: label-medium, on-surface-variant
+ * - medium expanded: label-large, on-surface-variant
+ * - large expanded: title-medium, on-surface-variant
+ *
  * **MD3 Accessibility (m3.material.io/components/app-bars/accessibility):**
  * - Focus lands on the leading navigation button first (first interactive element in DOM)
  * - Tab navigates: leading icon → trailing action icons (left to right)
@@ -682,7 +696,7 @@ interface AppBarHeadlessProps {
  *   onScrollStateChange={setIsScrolled}
  * />
  *
- * // Medium with expanded title and subtitle
+ * // Medium with expanded title and subtitle (grows to 136dp with subtitle)
  * <AppBar
  *   variant="medium"
  *   title="Article Title"

package/dist/index.d.ts

@@ -598,6 +598,9 @@ interface AppBarProps {
  * Renders a `<header role="banner">` and manages scroll elevation state.
  * Use this for full visual control when the styled `AppBar` is not sufficient.
  *
+ * Extends `React.HTMLAttributes<HTMLElement>` so all standard HTML attributes
+ * (including `data-*` attributes) are forwarded to the underlying `<header>`.
+ *
  * @example
  * ```tsx
  * <AppBarHeadless
@@ -609,11 +612,7 @@ interface AppBarProps {
  * </AppBarHeadless>
  * ```
  */
-interface AppBarHeadlessProps {
-    /**
-     * Additional CSS classes
-     */
-    className?: string;
+interface AppBarHeadlessProps extends React__default.HTMLAttributes<HTMLElement> {
     /**
      * The content to render inside the header
      */
@@ -630,26 +629,41 @@ interface AppBarHeadlessProps {
 }
 
 /**
- * Material Design 3 Top App Bar Component
+ * Material Design 3 Top App Bar Component (M3 Expressive Flexible)
  *
  * Provides context and actions for the current screen. Supports four size variants,
- * a navigation icon slot, title, and trailing action icon slots. Implements
- * scroll-triggered elevation changes per MD3 specification.
+ * a navigation icon slot, title, optional subtitle, and trailing action icon slots.
+ * Implements scroll-triggered elevation changes per MD3 specification.
  *
  * **Architecture:**
- * - Layer 3 (this file): MD3 styled, CVA variants, layout composition
+ * - Layer 3 (this file): MD3 styled, CVA slot variants, layout composition
  * - Layer 2: `AppBarHeadless` — `<header role="banner">`, scroll state
  * - Layer 1: React Aria via `<IconButton>` in consumer slots
  *
+ * **Slot-based styling:**
+ * All layout and state styling follows the Variants vs States pattern:
+ * - `variant` prop drives design-time choices (height, type scale, alignment)
+ * - Scroll elevation state is emitted as `data-scrolled=""` on the root and
+ *   consumed by `group-data-[scrolled]/appbar:*` selectors (presence-based)
+ * - Subtitle presence is emitted as `data-with-subtitle=""` on the root and
+ *   used to grow medium/large bar heights (group-data-[with-subtitle]/appbar:*)
+ *
  * **Key Features:**
  * - 4 MD3 variants: small, center-aligned, medium, large
- * - Optional subtitle (per M3 Expressive spec) with per-variant typography
+ * - M3 Expressive flexible: medium and large grow vertically with a subtitle
+ *   (136dp / 152dp respectively), per the M3 Expressive flexible spec
  * - Composable API: pass `<IconButton>` nodes into navigation and action slots
- * - Scroll elevation: flat (bg-surface) at rest → bg-surface-container + shadow-elevation-2 on scroll
+ * - Scroll elevation: bg-surface at rest → bg-surface-container + shadow-elevation-2
  * - Controlled and uncontrolled scroll state
+ * - MD3 motion: background-color + box-shadow use standard effects spring pair
  * - WCAG 2.1 AA: `role="banner"` landmark, keyboard accessible slots
  * - Dark mode via existing token system
  *
+ * **M3 Expressive Flexible subtitle type scales:**
+ * - small / center-aligned: label-medium, on-surface-variant
+ * - medium expanded: label-large, on-surface-variant
+ * - large expanded: title-medium, on-surface-variant
+ *
  * **MD3 Accessibility (m3.material.io/components/app-bars/accessibility):**
  * - Focus lands on the leading navigation button first (first interactive element in DOM)
  * - Tab navigates: leading icon → trailing action icons (left to right)
@@ -682,7 +696,7 @@ interface AppBarHeadlessProps {
  *   onScrollStateChange={setIsScrolled}
  * />
  *
- * // Medium with expanded title and subtitle
+ * // Medium with expanded title and subtitle (grows to 136dp with subtitle)
  * <AppBar
  *   variant="medium"
  *   title="Article Title"

package/dist/index.js

@@ -206,65 +206,111 @@ function useScrollElevation(options = {}) {
   };
 }
 var AppBarHeadless = forwardRef(
-  ({ className, children, scrolled: scrolledProp, onScrollStateChange }, ref) => {
+  ({ className, children, scrolled: scrolledProp, onScrollStateChange, ...htmlProps }, ref) => {
     const { isScrolled } = useScrollElevation({
       scrolled: scrolledProp,
       onScrollStateChange
     });
-    return /* @__PURE__ */ jsx("header", { ref, role: "banner", className, "data-scrolled": isScrolled, children });
+    return /* @__PURE__ */ jsx(
+      "header",
+      {
+        ...htmlProps,
+        ref,
+        role: "banner",
+        className,
+        "data-scrolled": isScrolled ? "" : void 0,
+        children
+      }
+    );
   }
 );
 AppBarHeadless.displayName = "AppBarHeadless";
 var appBarVariants = cva(
   [
-    // Base classes (always applied)
-    "w-full",
+    // Layout
+    "w-full flex flex-col",
+    // Color (base — at rest)
     "bg-surface text-on-surface",
-    "flex flex-col",
-    // Elevation transition using MD3 motion tokens
-    "transition-shadow duration-medium2 ease-standard"
+    // Elevation base
+    "shadow-elevation-0",
+    // Scroll state — effects properties animated with standard spring (no overshoot)
+    "transition-[background-color,box-shadow]",
+    "duration-spring-standard-default-effects",
+    "ease-spring-standard-default-effects",
+    // On scroll: surface-container background + elevation-2
+    "group-data-[scrolled]/appbar:bg-surface-container",
+    "group-data-[scrolled]/appbar:shadow-elevation-2"
   ],
   {
     variants: {
       /**
-       * Size variant (MD3 specification)
-       * Controls bar height, title placement, and type scale
+       * Size variant — controls bar height and which title row is shown.
+       * With-subtitle height growth is handled via group-data-[with-subtitle]/appbar below.
        */
       variant: {
-        /** 64dp, title left-aligned, title-large */
+        /** 64dp fixed — title left-aligned in top row */
         small: "h-appbar-small",
-        /** 64dp, title centered, title-large */
-        "center-aligned": "h-appbar-small variant-center-aligned",
-        /** min 112dp, title bottom-left, headline-medium (grows with subtitle) */
-        medium: "min-h-appbar-medium",
-        /** min 120dp, title bottom-left, display-small (grows with subtitle) */
-        large: "min-h-appbar-large"
-      },
-      /**
-       * Scroll state — controls surface elevation and background color
-       * MD3: flat surface at rest → surface-container background + elevation-2 on scroll
-       */
-      scrolled: {
-        false: "shadow-elevation-0",
-        true: "bg-surface-container shadow-elevation-2"
+        /** 64dp fixed — title centered in top row */
+        "center-aligned": "h-appbar-small",
+        /**
+         * 112dp no-subtitle / 136dp with-subtitle — title in expanded bottom row.
+         * group-data-[with-subtitle]/appbar switches to the taller token.
+         */
+        medium: [
+          "min-h-appbar-medium",
+          "group-data-[with-subtitle]/appbar:min-h-appbar-medium-subtitle"
+        ],
+        /**
+         * 120dp no-subtitle / 152dp with-subtitle — title in expanded bottom row.
+         * group-data-[with-subtitle]/appbar switches to the taller token.
+         */
+        large: [
+          "min-h-appbar-large",
+          "group-data-[with-subtitle]/appbar:min-h-appbar-large-subtitle"
+        ]
       }
     },
     defaultVariants: {
-      variant: "small",
-      scrolled: false
+      variant: "small"
+    }
+  }
+);
+var appBarTopRowVariants = cva(["flex items-center justify-between", "px-1"], {
+  variants: {
+    variant: {
+      small: "flex-1",
+      "center-aligned": "flex-1",
+      medium: "h-16 shrink-0",
+      large: "h-16 shrink-0"
+    }
+  },
+  defaultVariants: {
+    variant: "small"
+  }
+});
+var appBarLeadingVariants = cva(["flex shrink-0 items-center", "text-on-surface"]);
+var appBarHeadlineBlockVariants = cva(
+  ["flex min-w-0 flex-1 flex-col justify-center", "px-1"],
+  {
+    variants: {
+      variant: {
+        small: "",
+        "center-aligned": "items-center text-center",
+        medium: "",
+        large: ""
+      }
+    },
+    defaultVariants: {
+      variant: "small"
     }
   }
 );
 var appBarTitleVariants = cva("text-on-surface font-normal", {
   variants: {
     variant: {
-      /** title-large: 22px / 28px line-height */
       small: "text-title-large truncate",
-      /** title-large: 22px / 28px line-height, centered */
       "center-aligned": "text-title-large truncate",
-      /** headline-medium: 28px / 36px line-height */
       medium: "text-headline-medium",
-      /** display-small: 36px / 44px line-height */
       large: "text-display-small"
     }
   },
@@ -272,23 +318,27 @@ var appBarTitleVariants = cva("text-on-surface font-normal", {
     variant: "small"
   }
 });
-var appBarSubtitleVariants = cva("font-normal", {
+var appBarSubtitleVariants = cva("text-on-surface-variant font-normal", {
   variants: {
     variant: {
-      /** title-medium: 16px / 24px, on-surface-variant color */
-      small: "text-title-medium text-on-surface-variant truncate",
-      /** title-medium: 16px / 24px, centered, on-surface-variant color */
-      "center-aligned": "text-title-medium text-on-surface-variant truncate",
-      /** title-large: 22px / 28px, on-surface color */
-      medium: "text-title-large text-on-surface",
-      /** headline-small: 24px / 32px, on-surface color */
-      large: "text-headline-small text-on-surface"
+      small: "text-label-medium truncate",
+      "center-aligned": "text-label-medium truncate",
+      medium: "text-label-large",
+      large: "text-title-medium"
     }
   },
   defaultVariants: {
     variant: "small"
   }
 });
+var appBarTrailingVariants = cva([
+  "flex shrink-0 items-center gap-0.5",
+  "text-on-surface-variant"
+]);
+var appBarExpandedTitleVariants = cva([
+  "flex flex-1 flex-col justify-end",
+  "gap-0.5 px-4 pb-4"
+]);
 var AppBar = forwardRef(
   ({
     variant = "small",
@@ -305,76 +355,54 @@ var AppBar = forwardRef(
       onScrollStateChange
     });
     const isExpandedVariant = variant === "medium" || variant === "large";
+    const hasSubtitle = subtitle != null;
     return /* @__PURE__ */ jsxs(
       AppBarHeadless,
       {
         ref,
         scrolled: isScrolled,
-        className: cn(appBarVariants({ variant, scrolled: isScrolled }), className),
+        className: cn(
+          appBarVariants({ variant }),
+          // group/appbar: enables group-data-[scrolled]/appbar and
+          // group-data-[with-subtitle]/appbar child selectors in all slots
+          "group/appbar",
+          className
+        ),
+        "data-with-subtitle": hasSubtitle ? "" : void 0,
         children: [
-          /* @__PURE__ */ jsxs(
-            "div",
-            {
-              "data-slot": "top-row",
-              className: cn(
-                "flex items-center justify-between",
-                "px-1",
-                // Small and center-aligned: fill the full bar height
-                !isExpandedVariant && "flex-1",
-                // Expanded variants: fixed height for the top row (64dp)
-                isExpandedVariant && "h-16 shrink-0"
-              ),
-              children: [
-                navigationIcon != null && /* @__PURE__ */ jsx("div", { "data-slot": "navigation", className: "flex shrink-0 items-center", children: navigationIcon }),
-                !isExpandedVariant && /* @__PURE__ */ jsxs(
-                  "div",
-                  {
-                    className: cn(
-                      "flex min-w-0 flex-1 flex-col justify-center px-1",
-                      variant === "center-aligned" && "text-center"
-                    ),
-                    children: [
-                      /* @__PURE__ */ jsx("span", { "data-testid": "appbar-title", className: cn(appBarTitleVariants({ variant })), children: title }),
-                      subtitle != null && /* @__PURE__ */ jsx(
-                        "span",
-                        {
-                          "data-testid": "appbar-subtitle",
-                          className: cn(appBarSubtitleVariants({ variant })),
-                          children: subtitle
-                        }
-                      )
-                    ]
-                  }
-                ),
-                actions != null && /* @__PURE__ */ jsx("div", { "data-slot": "actions", className: "flex shrink-0 items-center gap-0.5", children: actions })
-              ]
-            }
-          ),
-          isExpandedVariant && /* @__PURE__ */ jsxs(
-            "div",
-            {
-              "data-slot": "expanded-title",
-              className: cn("flex flex-1 flex-col justify-end", "gap-0.5 px-4 pb-4"),
-              children: [
-                /* @__PURE__ */ jsx(
-                  "span",
-                  {
-                    "data-testid": "appbar-title",
-                    className: cn("min-w-0", appBarTitleVariants({ variant })),
-                    children: title
-                  }
-                ),
-                subtitle != null && /* @__PURE__ */ jsx(
-                  "span",
-                  {
-                    "data-testid": "appbar-subtitle",
-                    className: cn("min-w-0", appBarSubtitleVariants({ variant })),
-                    children: subtitle
-                  }
-                )
-              ]
-            }
-          )
+          /* @__PURE__ */ jsxs("div", { "data-slot": "top-row", className: cn(appBarTopRowVariants({ variant })), children: [
+            navigationIcon != null && /* @__PURE__ */ jsx("div", { "data-slot": "navigation", className: cn(appBarLeadingVariants()), children: navigationIcon }),
+            !isExpandedVariant && /* @__PURE__ */ jsxs("div", { className: cn(appBarHeadlineBlockVariants({ variant })), children: [
+              /* @__PURE__ */ jsx("span", { "data-testid": "appbar-title", className: cn(appBarTitleVariants({ variant })), children: title }),
+              hasSubtitle && /* @__PURE__ */ jsx(
+                "span",
+                {
+                  "data-testid": "appbar-subtitle",
+                  className: cn(appBarSubtitleVariants({ variant })),
+                  children: subtitle
+                }
+              )
+            ] }),
+            actions != null && /* @__PURE__ */ jsx("div", { "data-slot": "actions", className: cn(appBarTrailingVariants()), children: actions })
+          ] }),
+          isExpandedVariant && /* @__PURE__ */ jsxs("div", { "data-slot": "expanded-title", className: cn(appBarExpandedTitleVariants()), children: [
+            /* @__PURE__ */ jsx(
+              "span",
+              {
+                "data-testid": "appbar-title",
+                className: cn("min-w-0", appBarTitleVariants({ variant })),
+                children: title
+              }
+            ),
+            hasSubtitle && /* @__PURE__ */ jsx(
+              "span",
+              {
+                "data-testid": "appbar-subtitle",
+                className: cn("min-w-0", appBarSubtitleVariants({ variant })),
+                children: subtitle
+              }
+            )
+          ] })
         ]
       }
     );