@tinybigui/react 0.14.0 → 0.15.0

package/dist/index.d.cts

@@ -7093,9 +7093,9 @@ type RichTooltipVariants = VariantProps<typeof richTooltipVariants>;
 /**
  * Visual density based on content lines (MD3 List)
  *
- * - `one-line`: headline only (48dp)
- * - `two-line`: headline + supporting text (64dp)
- * - `three-line`: overline + headline + supporting text (88dp)
+ * - `one-line`: headline only (56dp min-height)
+ * - `two-line`: headline + supporting text (72dp min-height)
+ * - `three-line`: overline + headline + supporting text (88dp min-height)
  */
 type ListDensity = "one-line" | "two-line" | "three-line";
 /**
@@ -7201,8 +7201,6 @@ interface ListItemProps {
     insetDivider?: boolean;
     /** Additional CSS classes */
     className?: string;
-    /** Item-specific action callback */
-    onAction?: (value: string | number) => void;
 }
 /**
  * Props for the ListItem leading slot
@@ -7276,24 +7274,44 @@ declare const List: React__default.ForwardRefExoticComponent<ListProps & React__
 /**
  * Material Design 3 List Item (Layer 3: Styled)
  *
- * Renders an accessible list item with MD3 visual treatment:
- * state layer, ripple, density-driven height, and slot-based layout.
+ * Architecture: Variants-vs-States
+ * - Design-time variant: `density` (auto-derived from content).
+ * - All interaction/selection states are expressed as data-* attributes on the root <li>
+ *   via `getInteractionDataAttributes`, consumed by each slot via group-data-[x]/list-item.
+ * - Content flags (`data-with-leading`, `data-with-trailing`) describe structure, set explicitly.
  *
- * - **Interactive mode** (inside a `List` with `selectionMode` or `onAction`):
- *   uses `useOption` for ARIA semantics, renders state layer + ripple.
- * - **Static mode**: renders `<li role="listitem">` without interactive
- *   affordances.
+ * Two operating modes:
+ * - **Interactive** (inside a `List` with `selectionMode` or `onAction`):
+ *   uses `useOption` for ARIA semantics, renders state layer + focus ring + ripple.
+ * - **Static**: renders `<li role="listitem">`, no interactive affordances.
  *
  * Density is auto-derived from content:
- * - one-line (56dp) — headline only
- * - two-line (72dp) — headline + supportingText
+ * - one-line (56dp)   — headline only
+ * - two-line (72dp)   — headline + supportingText
  * - three-line (88dp) — overline present
+ *
+ * @example
+ * ```tsx
+ * // Static
+ * <List aria-label="Settings">
+ *   <ListItem value="wifi" headline="Wi-Fi" supportingText="Connected" leadingType="icon" leadingSlot={<IconWifi />} />
+ * </List>
+ *
+ * // Interactive single-select
+ * <List aria-label="Alignment" selectionMode="single">
+ *   <ListItem value="left" headline="Left" />
+ *   <ListItem value="center" headline="Center" />
+ * </List>
+ * ```
  */
 declare const ListItem: React__default.ForwardRefExoticComponent<ListItemProps & React__default.RefAttributes<HTMLLIElement>>;
 
 /**
  * MD3 ListItem leading slot.
  *
+ * Uses `listItemLeadingVariants` CVA so icon/text colors automatically react to
+ * the parent `group/list-item` data-selected and data-disabled attributes.
+ *
  * For `checkbox` and `radio` types the children are wrapped with
  * `aria-hidden="true"` and `tabIndex={-1}` because the parent
  * `ListItem`'s `useOption` already conveys selection state to
@@ -7304,6 +7322,9 @@ declare const ListItemLeading: React$1.ForwardRefExoticComponent<ListItemLeading
 /**
  * MD3 ListItem trailing slot.
  *
+ * Uses `listItemTrailingVariants` CVA so icon/text colors automatically react to
+ * the parent `group/list-item` data-selected and data-disabled attributes.
+ *
  * For `checkbox` and `radio` types the children are wrapped with
  * `aria-hidden="true"` and `tabIndex={-1}` — selection semantics
  * come from the parent `ListItem`'s `useOption`.
@@ -7313,6 +7334,9 @@ declare const ListItemTrailing: React$1.ForwardRefExoticComponent<ListItemTraili
 /**
  * MD3 ListItem text block — overline + headline + supporting text.
  *
+ * Each text element uses its own slot CVA so colors automatically react to
+ * the parent `group/list-item` data-selected and data-disabled attributes.
+ *
  * Uses `min-w-0` to allow text truncation inside flex containers.
  */
 declare const ListItemText: React$1.ForwardRefExoticComponent<ListItemTextProps & React$1.RefAttributes<HTMLDivElement>>;
@@ -7357,20 +7381,58 @@ declare const ListHeadless: React__default.ForwardRefExoticComponent<ListProps &
 declare const ListItemHeadless: React__default.ForwardRefExoticComponent<ListItemProps & React__default.RefAttributes<HTMLLIElement>>;
 
 /**
- * MD3 List container CVA variants.
+ * Material Design 3 List Variants
+ *
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (density, slot type).
+ * - All interaction/selection states are driven by data-* attributes on the root <li>
+ *   via group-data-[x]/list-item Tailwind selectors in each slot's base classes.
+ * - Content flags (data-with-leading, data-with-trailing) are set explicitly by ListItem.
+ *
+ * Slot responsibilities:
+ *   listVariants               — container <ul>; bg-surface
+ *   listItemVariants           — root <li>; group/list-item; density height; cursor; disabled
+ *   listItemStateLayerVariants — absolute inset overlay; hover/focus/pressed opacity ring
+ *   listItemFocusRingVariants  — keyboard focus indicator outline
+ *   listItemLeadingVariants    — leading slot wrapper; type-specific size/shape + color states
+ *   listItemTrailingVariants   — trailing slot wrapper; type-specific size/shape + color states
+ *   listItemOverlineVariants   — overline text; color reacts to selected/disabled
+ *   listItemHeadlineVariants   — headline text; color reacts to selected/disabled
+ *   listItemSupportingTextVariants — supporting text; color reacts to selected/disabled
+ *
+ * MD3 Spec (lists/specs):
+ *   One-line:   56dp min-height
+ *   Two-line:   72dp min-height
+ *   Three-line: 88dp min-height (leading/trailing top-aligned)
+ *   Padding: 16dp horizontal, 8dp vertical
+ *   Leading icon: 24dp, text-on-surface-variant
+ *   Leading avatar: 40dp circle
+ *   State-layer opacities: hover 8% | focus 10% | pressed 10%
+ *   Disabled: content 38% opacity, pointer-events none
+ *   Selected: bg-secondary-container, text/icons on-secondary-container
+ */
+/**
+ * List container (<ul>).
+ * MD3: Lists use `surface` color role for their container.
  */
 declare const listVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
 /**
- * MD3 ListItem CVA variants.
+ * Root <li> element — carries `group/list-item` and emits data-* interaction attributes.
  *
- * Density is auto-derived from content (overline / supportingText), not a user prop.
- * Three-line items use `items-start` so leading/trailing slots top-align.
+ * Design-time variant: `density` only.
+ * All interaction/selection states are driven via group-data-[x]/list-item selectors
+ * in the slot CVAs below — NOT as CVA variant keys here.
+ *
+ *   one-line:   56dp (min-h-14)
+ *   two-line:   72dp (min-h-18)
+ *   three-line: 88dp (min-h-22, items-start for top-aligned slots)
+ *
+ * Selected background: group-data-[selected]/list-item:bg-secondary-container
+ * Interactive cursor: data-[interactive]:cursor-pointer
+ * Disabled: self-targeting data-[disabled]: selectors (38% + no pointer)
  */
 declare const listItemVariants: (props?: ({
     density?: "one-line" | "two-line" | "three-line" | null | undefined;
-    isSelected?: boolean | null | undefined;
-    isDisabled?: boolean | null | undefined;
-    isInteractive?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type ListVariants = VariantProps<typeof listVariants>;
 type ListItemVariants = VariantProps<typeof listItemVariants>;

package/dist/index.d.ts

@@ -7093,9 +7093,9 @@ type RichTooltipVariants = VariantProps<typeof richTooltipVariants>;
 /**
  * Visual density based on content lines (MD3 List)
  *
- * - `one-line`: headline only (48dp)
- * - `two-line`: headline + supporting text (64dp)
- * - `three-line`: overline + headline + supporting text (88dp)
+ * - `one-line`: headline only (56dp min-height)
+ * - `two-line`: headline + supporting text (72dp min-height)
+ * - `three-line`: overline + headline + supporting text (88dp min-height)
  */
 type ListDensity = "one-line" | "two-line" | "three-line";
 /**
@@ -7201,8 +7201,6 @@ interface ListItemProps {
     insetDivider?: boolean;
     /** Additional CSS classes */
     className?: string;
-    /** Item-specific action callback */
-    onAction?: (value: string | number) => void;
 }
 /**
  * Props for the ListItem leading slot
@@ -7276,24 +7274,44 @@ declare const List: React__default.ForwardRefExoticComponent<ListProps & React__
 /**
  * Material Design 3 List Item (Layer 3: Styled)
  *
- * Renders an accessible list item with MD3 visual treatment:
- * state layer, ripple, density-driven height, and slot-based layout.
+ * Architecture: Variants-vs-States
+ * - Design-time variant: `density` (auto-derived from content).
+ * - All interaction/selection states are expressed as data-* attributes on the root <li>
+ *   via `getInteractionDataAttributes`, consumed by each slot via group-data-[x]/list-item.
+ * - Content flags (`data-with-leading`, `data-with-trailing`) describe structure, set explicitly.
  *
- * - **Interactive mode** (inside a `List` with `selectionMode` or `onAction`):
- *   uses `useOption` for ARIA semantics, renders state layer + ripple.
- * - **Static mode**: renders `<li role="listitem">` without interactive
- *   affordances.
+ * Two operating modes:
+ * - **Interactive** (inside a `List` with `selectionMode` or `onAction`):
+ *   uses `useOption` for ARIA semantics, renders state layer + focus ring + ripple.
+ * - **Static**: renders `<li role="listitem">`, no interactive affordances.
  *
  * Density is auto-derived from content:
- * - one-line (56dp) — headline only
- * - two-line (72dp) — headline + supportingText
+ * - one-line (56dp)   — headline only
+ * - two-line (72dp)   — headline + supportingText
  * - three-line (88dp) — overline present
+ *
+ * @example
+ * ```tsx
+ * // Static
+ * <List aria-label="Settings">
+ *   <ListItem value="wifi" headline="Wi-Fi" supportingText="Connected" leadingType="icon" leadingSlot={<IconWifi />} />
+ * </List>
+ *
+ * // Interactive single-select
+ * <List aria-label="Alignment" selectionMode="single">
+ *   <ListItem value="left" headline="Left" />
+ *   <ListItem value="center" headline="Center" />
+ * </List>
+ * ```
  */
 declare const ListItem: React__default.ForwardRefExoticComponent<ListItemProps & React__default.RefAttributes<HTMLLIElement>>;
 
 /**
  * MD3 ListItem leading slot.
  *
+ * Uses `listItemLeadingVariants` CVA so icon/text colors automatically react to
+ * the parent `group/list-item` data-selected and data-disabled attributes.
+ *
  * For `checkbox` and `radio` types the children are wrapped with
  * `aria-hidden="true"` and `tabIndex={-1}` because the parent
  * `ListItem`'s `useOption` already conveys selection state to
@@ -7304,6 +7322,9 @@ declare const ListItemLeading: React$1.ForwardRefExoticComponent<ListItemLeading
 /**
  * MD3 ListItem trailing slot.
  *
+ * Uses `listItemTrailingVariants` CVA so icon/text colors automatically react to
+ * the parent `group/list-item` data-selected and data-disabled attributes.
+ *
  * For `checkbox` and `radio` types the children are wrapped with
  * `aria-hidden="true"` and `tabIndex={-1}` — selection semantics
  * come from the parent `ListItem`'s `useOption`.
@@ -7313,6 +7334,9 @@ declare const ListItemTrailing: React$1.ForwardRefExoticComponent<ListItemTraili
 /**
  * MD3 ListItem text block — overline + headline + supporting text.
  *
+ * Each text element uses its own slot CVA so colors automatically react to
+ * the parent `group/list-item` data-selected and data-disabled attributes.
+ *
  * Uses `min-w-0` to allow text truncation inside flex containers.
  */
 declare const ListItemText: React$1.ForwardRefExoticComponent<ListItemTextProps & React$1.RefAttributes<HTMLDivElement>>;
@@ -7357,20 +7381,58 @@ declare const ListHeadless: React__default.ForwardRefExoticComponent<ListProps &
 declare const ListItemHeadless: React__default.ForwardRefExoticComponent<ListItemProps & React__default.RefAttributes<HTMLLIElement>>;
 
 /**
- * MD3 List container CVA variants.
+ * Material Design 3 List Variants
+ *
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (density, slot type).
+ * - All interaction/selection states are driven by data-* attributes on the root <li>
+ *   via group-data-[x]/list-item Tailwind selectors in each slot's base classes.
+ * - Content flags (data-with-leading, data-with-trailing) are set explicitly by ListItem.
+ *
+ * Slot responsibilities:
+ *   listVariants               — container <ul>; bg-surface
+ *   listItemVariants           — root <li>; group/list-item; density height; cursor; disabled
+ *   listItemStateLayerVariants — absolute inset overlay; hover/focus/pressed opacity ring
+ *   listItemFocusRingVariants  — keyboard focus indicator outline
+ *   listItemLeadingVariants    — leading slot wrapper; type-specific size/shape + color states
+ *   listItemTrailingVariants   — trailing slot wrapper; type-specific size/shape + color states
+ *   listItemOverlineVariants   — overline text; color reacts to selected/disabled
+ *   listItemHeadlineVariants   — headline text; color reacts to selected/disabled
+ *   listItemSupportingTextVariants — supporting text; color reacts to selected/disabled
+ *
+ * MD3 Spec (lists/specs):
+ *   One-line:   56dp min-height
+ *   Two-line:   72dp min-height
+ *   Three-line: 88dp min-height (leading/trailing top-aligned)
+ *   Padding: 16dp horizontal, 8dp vertical
+ *   Leading icon: 24dp, text-on-surface-variant
+ *   Leading avatar: 40dp circle
+ *   State-layer opacities: hover 8% | focus 10% | pressed 10%
+ *   Disabled: content 38% opacity, pointer-events none
+ *   Selected: bg-secondary-container, text/icons on-secondary-container
+ */
+/**
+ * List container (<ul>).
+ * MD3: Lists use `surface` color role for their container.
  */
 declare const listVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
 /**
- * MD3 ListItem CVA variants.
+ * Root <li> element — carries `group/list-item` and emits data-* interaction attributes.
  *
- * Density is auto-derived from content (overline / supportingText), not a user prop.
- * Three-line items use `items-start` so leading/trailing slots top-align.
+ * Design-time variant: `density` only.
+ * All interaction/selection states are driven via group-data-[x]/list-item selectors
+ * in the slot CVAs below — NOT as CVA variant keys here.
+ *
+ *   one-line:   56dp (min-h-14)
+ *   two-line:   72dp (min-h-18)
+ *   three-line: 88dp (min-h-22, items-start for top-aligned slots)
+ *
+ * Selected background: group-data-[selected]/list-item:bg-secondary-container
+ * Interactive cursor: data-[interactive]:cursor-pointer
+ * Disabled: self-targeting data-[disabled]: selectors (38% + no pointer)
  */
 declare const listItemVariants: (props?: ({
     density?: "one-line" | "two-line" | "three-line" | null | undefined;
-    isSelected?: boolean | null | undefined;
-    isDisabled?: boolean | null | undefined;
-    isInteractive?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type ListVariants = VariantProps<typeof listVariants>;
 type ListItemVariants = VariantProps<typeof listItemVariants>;