@tinybigui/react 0.9.0 → 0.11.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"
@@ -9178,6 +9192,22 @@ interface BottomSheetHandleProps {
  */
 declare const BottomSheet: React$1.ForwardRefExoticComponent<BottomSheetProps & React$1.RefAttributes<HTMLDivElement>>;
 
+/**
+ * `BottomSheetHandle` — the draggable handle at the top of the Bottom Sheet.
+ *
+ * Implements the Variants-vs-States architecture used across TinyBigUI:
+ * - Carries `group/handle` on its wrapper so child slots consume data-* selectors.
+ * - Emits `getInteractionDataAttributes` for hover/focus/pressed states from React Aria.
+ * - Emits `data-dragging` as a component-specific content flag (ternary encoding).
+ * - Renders three slots inside the wrapper (stacked via absolute positioning):
+ *   1. State layer — hover/focus/pressed/dragged opacity feedback (aria-hidden)
+ *   2. Focus ring overlay — keyboard focus indicator (aria-hidden)
+ *   3. Pill — the visible 32×4dp decoration (aria-hidden)
+ *
+ * Pointer and keyboard props are injected from `BottomSheetContext` (via `useBottomSheetDrag`).
+ * React Aria `useHover` and `useFocusRing` are merged on top — they do not conflict with the
+ * existing `onPointerDown`/`onPointerUp` drag handlers.
+ */
 declare function BottomSheetHandle({ className, "aria-label": ariaLabelOverride, }: BottomSheetHandleProps): ReactElement;
 declare namespace BottomSheetHandle {
     var displayName: string;
@@ -9283,13 +9313,40 @@ interface UseBottomSheetDragReturn {
  */
 declare function useBottomSheetDrag({ snapPoints, onSnapChange, onClose, }: UseBottomSheetDragOptions): UseBottomSheetDragReturn;
 
+/**
+ * Material Design 3 Bottom Sheet Variants
+ *
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (no state variants, no state compoundVariants).
+ * - The drag handle's interaction states are driven by data-* attributes on its wrapper
+ *   via group-data-[x]/handle Tailwind selectors in each slot's base classes.
+ * - Content flags (data-dragging) are set explicitly by the component, not via helper.
+ *
+ * Slot responsibilities:
+ *   bottomSheetVariants               — fixed container; surface, shape, elevation, snap spring
+ *   bottomSheetScrimVariants          — modal scrim overlay; opacity fade (screen-level token)
+ *   bottomSheetAnimationVariants      — enter/exit animation state machine classes
+ *   bottomSheetHandleWrapperVariants  — 48dp touch target; carries `group/handle`; data-* host
+ *   bottomSheetHandleStateLayerVariants — hover/focus/pressed/dragged opacity ring around pill
+ *   bottomSheetHandleFocusRingVariants  — keyboard focus outline overlay (opacity-driven)
+ *   bottomSheetHandlePillVariants     — 32×4dp pill decoration; pointer-events-none
+ *
+ * MD3 Spec:
+ *   Container surface: surface-container-low, elevation level-1
+ *   Shape: extra-large top corners (28dp), square bottom (attached to screen edge)
+ *   Width: full width up to 640dp; centered at max-width 640dp on wider viewports
+ *   Top margin: 72dp default, 56dp when viewport > 640dp
+ *   Drag handle: 32dp × 4dp, on-surface-variant, centered, 22dp top/bottom padding → 48dp target
+ *   Scrim: bg-scrim, 32% opacity
+ *   State-layer opacities: hover 8% | focus 10% | pressed 10% | dragged 16%
+ */
 /**
  * CVA animation state variants for the Bottom Sheet panel.
  *
  * Motion decision rationale:
  * - Bottom sheet is a standard-size component → `default` speed tier
  * - Slides in/out of screen → composite `animate-md-*` utilities (not manual spring tokens)
- * - Scrim opacity is an effects property → `duration-short4 ease-standard` (legacy screen-level token)
+ * - Scrim opacity is an effects property → `duration-short4 ease-standard` (legacy screen-level)
  * - Snap spring is a spatial on-screen transition → `ease-spring-standard-default-spatial` +
  *   `duration-spring-standard-default-spatial` (applied in bottomSheetVariants base)
  * - Standard personality (not expressive) — sheets are utility UI, not moments of delight
@@ -9299,53 +9356,64 @@ declare const bottomSheetAnimationVariants: (props?: ({
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type BottomSheetAnimationVariants = VariantProps<typeof bottomSheetAnimationVariants>;
 /**
- * CVA variants for the Bottom Sheet container panel.
+ * Root container — the bottom sheet panel.
  *
  * MD3 tokens applied:
  * - Surface: bg-surface-container-low
  * - Elevation: shadow-elevation-1
- * - Shape: rounded-t-xl (top-left + top-right 28dp, bottom 0)
- * - Width: full width up to 640dp; centered at max-width 640dp on wider viewports
- *   (`mx-auto + max-w-[640px]` — at 752dp viewport this naturally produces the MD3-spec 56dp side margins)
- * - Height: constrained by max-height (72dp top margin by default, 56dp on > 640dp viewport)
- *   The sheet is always anchored to `bottom-0`; "top margin" is expressed as max-height so
- *   the sheet cannot overlap the top portion of the screen.
- * - Drag resize: height animates via `transition-[height]`; the sheet grows/shrinks from the
- *   bottom edge, always staying anchored — matching the MD3 spec "resize to another height" behaviour.
+ * - Shape: extra-large top corners (28dp via rounded-t-xl), square bottom (attached to edge)
+ * - Width: full width up to 640dp (mx-auto + w-[640px] max-w-full)
+ * - Height: snap-point driven via inline style; constrained by max-height to enforce top margin
+ *   Default: 72dp top margin → max-h-[calc(100vh-72px)]
+ *   Wide (> 640dp): 56dp top margin → sm:max-h-[calc(100vh-56px)]
+ * - Snap spring: spatial on-screen transition → spring-standard default spatial pair
+ *   data-[dragging]:transition-none suppresses spring during active drag (1:1 pointer tracking)
+ *
+ * NOTE: overflow-hidden clips content during height transitions. The handle's state layer and
+ * focus-ring overlay are sized/positioned to fit within the wrapper, so they are not clipped.
  */
 declare const bottomSheetVariants: (props?: ({
     variant?: "standard" | "modal" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type BottomSheetVariants = VariantProps<typeof bottomSheetVariants>;
 /**
- * CVA for the scrim overlay (modal variant only).
+ * Scrim overlay (modal variant only).
  *
  * MD3 tokens applied:
  * - bg-scrim: scrim surface role
  * - opacity-32: 32% opacity per MD3 spec
- * - Transition: opacity fade (scrim is an effects property — legacy screen-level tokens)
+ * - Transition: opacity fade (scrim is a screen-level effects property → legacy duration tokens)
  */
 declare const bottomSheetScrimVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
 type BottomSheetScrimVariants = VariantProps<typeof bottomSheetScrimVariants>;
 /**
- * CVA for the drag handle wrapper (touch/click target area).
+ * Drag handle wrapper — 48dp touch target area + group scope host.
+ *
+ * Carries `group/handle` so all handle child slots can consume data-* interaction
+ * states via `group-data-[x]/handle:` Tailwind selectors without any CVA variant props.
  *
- * MD3 spec: the top 48dp of the sheet is the interactive touch target area
- * when the drag handle is present. The wrapper provides this touch target.
+ * MD3 spec: 22dp top + 4dp handle + 22dp bottom = 48dp interaction zone.
+ * NOTE: py-[22px] is a measurement-derived value from MD3 spec; permitted exception.
+ *
+ * `relative` provides positioning context for the state layer and focus ring overlays.
+ * `focus-visible:outline-none` suppresses the browser default — the focus ring overlay
+ * in `bottomSheetHandleFocusRingVariants` provides the MD3-spec visible indicator instead.
  */
 declare const bottomSheetHandleWrapperVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
+type BottomSheetHandleWrapperVariants = VariantProps<typeof bottomSheetHandleWrapperVariants>;
 /**
- * CVA for the drag handle pill visual element.
+ * Drag handle pill — the visible 32×4dp decoration.
  *
  * MD3 tokens applied:
- * - bg-on-surface-variant: handle color
- * - w-8: 32dp width per MD3 spec
- * - h-1: 4dp height per MD3 spec
- * - rounded-full: fully rounded pill shape
- * - opacity-40: per MD3 spec (token deprecated but value still in spec)
+ * - bg-on-surface-variant: handle color (muted, low-emphasis by role — no opacity override needed)
+ * - w-8 / h-1: 32dp × 4dp per MD3 spec (measurement-derived; permitted exception)
+ * - rounded-full: fully-rounded pill shape
+ *
+ * `pointer-events-none` — all interaction is handled by the wrapper.
+ * `relative z-10` — renders above the state layer overlay.
  */
 declare const bottomSheetHandlePillVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
-type BottomSheetHandleVariants = VariantProps<typeof bottomSheetHandleWrapperVariants>;
+type BottomSheetHandleVariants = BottomSheetHandleWrapperVariants;
 
 /**
  * Variant of the MD3 Time Picker.

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"
@@ -9178,6 +9192,22 @@ interface BottomSheetHandleProps {
  */
 declare const BottomSheet: React$1.ForwardRefExoticComponent<BottomSheetProps & React$1.RefAttributes<HTMLDivElement>>;
 
+/**
+ * `BottomSheetHandle` — the draggable handle at the top of the Bottom Sheet.
+ *
+ * Implements the Variants-vs-States architecture used across TinyBigUI:
+ * - Carries `group/handle` on its wrapper so child slots consume data-* selectors.
+ * - Emits `getInteractionDataAttributes` for hover/focus/pressed states from React Aria.
+ * - Emits `data-dragging` as a component-specific content flag (ternary encoding).
+ * - Renders three slots inside the wrapper (stacked via absolute positioning):
+ *   1. State layer — hover/focus/pressed/dragged opacity feedback (aria-hidden)
+ *   2. Focus ring overlay — keyboard focus indicator (aria-hidden)
+ *   3. Pill — the visible 32×4dp decoration (aria-hidden)
+ *
+ * Pointer and keyboard props are injected from `BottomSheetContext` (via `useBottomSheetDrag`).
+ * React Aria `useHover` and `useFocusRing` are merged on top — they do not conflict with the
+ * existing `onPointerDown`/`onPointerUp` drag handlers.
+ */
 declare function BottomSheetHandle({ className, "aria-label": ariaLabelOverride, }: BottomSheetHandleProps): ReactElement;
 declare namespace BottomSheetHandle {
     var displayName: string;
@@ -9283,13 +9313,40 @@ interface UseBottomSheetDragReturn {
  */
 declare function useBottomSheetDrag({ snapPoints, onSnapChange, onClose, }: UseBottomSheetDragOptions): UseBottomSheetDragReturn;
 
+/**
+ * Material Design 3 Bottom Sheet Variants
+ *
+ * Architecture: Variants vs States
+ * - CVA holds design-time structure only (no state variants, no state compoundVariants).
+ * - The drag handle's interaction states are driven by data-* attributes on its wrapper
+ *   via group-data-[x]/handle Tailwind selectors in each slot's base classes.
+ * - Content flags (data-dragging) are set explicitly by the component, not via helper.
+ *
+ * Slot responsibilities:
+ *   bottomSheetVariants               — fixed container; surface, shape, elevation, snap spring
+ *   bottomSheetScrimVariants          — modal scrim overlay; opacity fade (screen-level token)
+ *   bottomSheetAnimationVariants      — enter/exit animation state machine classes
+ *   bottomSheetHandleWrapperVariants  — 48dp touch target; carries `group/handle`; data-* host
+ *   bottomSheetHandleStateLayerVariants — hover/focus/pressed/dragged opacity ring around pill
+ *   bottomSheetHandleFocusRingVariants  — keyboard focus outline overlay (opacity-driven)
+ *   bottomSheetHandlePillVariants     — 32×4dp pill decoration; pointer-events-none
+ *
+ * MD3 Spec:
+ *   Container surface: surface-container-low, elevation level-1
+ *   Shape: extra-large top corners (28dp), square bottom (attached to screen edge)
+ *   Width: full width up to 640dp; centered at max-width 640dp on wider viewports
+ *   Top margin: 72dp default, 56dp when viewport > 640dp
+ *   Drag handle: 32dp × 4dp, on-surface-variant, centered, 22dp top/bottom padding → 48dp target
+ *   Scrim: bg-scrim, 32% opacity
+ *   State-layer opacities: hover 8% | focus 10% | pressed 10% | dragged 16%
+ */
 /**
  * CVA animation state variants for the Bottom Sheet panel.
  *
  * Motion decision rationale:
  * - Bottom sheet is a standard-size component → `default` speed tier
  * - Slides in/out of screen → composite `animate-md-*` utilities (not manual spring tokens)
- * - Scrim opacity is an effects property → `duration-short4 ease-standard` (legacy screen-level token)
+ * - Scrim opacity is an effects property → `duration-short4 ease-standard` (legacy screen-level)
  * - Snap spring is a spatial on-screen transition → `ease-spring-standard-default-spatial` +
  *   `duration-spring-standard-default-spatial` (applied in bottomSheetVariants base)
  * - Standard personality (not expressive) — sheets are utility UI, not moments of delight
@@ -9299,53 +9356,64 @@ declare const bottomSheetAnimationVariants: (props?: ({
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type BottomSheetAnimationVariants = VariantProps<typeof bottomSheetAnimationVariants>;
 /**
- * CVA variants for the Bottom Sheet container panel.
+ * Root container — the bottom sheet panel.
  *
  * MD3 tokens applied:
  * - Surface: bg-surface-container-low
  * - Elevation: shadow-elevation-1
- * - Shape: rounded-t-xl (top-left + top-right 28dp, bottom 0)
- * - Width: full width up to 640dp; centered at max-width 640dp on wider viewports
- *   (`mx-auto + max-w-[640px]` — at 752dp viewport this naturally produces the MD3-spec 56dp side margins)
- * - Height: constrained by max-height (72dp top margin by default, 56dp on > 640dp viewport)
- *   The sheet is always anchored to `bottom-0`; "top margin" is expressed as max-height so
- *   the sheet cannot overlap the top portion of the screen.
- * - Drag resize: height animates via `transition-[height]`; the sheet grows/shrinks from the
- *   bottom edge, always staying anchored — matching the MD3 spec "resize to another height" behaviour.
+ * - Shape: extra-large top corners (28dp via rounded-t-xl), square bottom (attached to edge)
+ * - Width: full width up to 640dp (mx-auto + w-[640px] max-w-full)
+ * - Height: snap-point driven via inline style; constrained by max-height to enforce top margin
+ *   Default: 72dp top margin → max-h-[calc(100vh-72px)]
+ *   Wide (> 640dp): 56dp top margin → sm:max-h-[calc(100vh-56px)]
+ * - Snap spring: spatial on-screen transition → spring-standard default spatial pair
+ *   data-[dragging]:transition-none suppresses spring during active drag (1:1 pointer tracking)
+ *
+ * NOTE: overflow-hidden clips content during height transitions. The handle's state layer and
+ * focus-ring overlay are sized/positioned to fit within the wrapper, so they are not clipped.
  */
 declare const bottomSheetVariants: (props?: ({
     variant?: "standard" | "modal" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type BottomSheetVariants = VariantProps<typeof bottomSheetVariants>;
 /**
- * CVA for the scrim overlay (modal variant only).
+ * Scrim overlay (modal variant only).
  *
  * MD3 tokens applied:
  * - bg-scrim: scrim surface role
  * - opacity-32: 32% opacity per MD3 spec
- * - Transition: opacity fade (scrim is an effects property — legacy screen-level tokens)
+ * - Transition: opacity fade (scrim is a screen-level effects property → legacy duration tokens)
  */
 declare const bottomSheetScrimVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
 type BottomSheetScrimVariants = VariantProps<typeof bottomSheetScrimVariants>;
 /**
- * CVA for the drag handle wrapper (touch/click target area).
+ * Drag handle wrapper — 48dp touch target area + group scope host.
+ *
+ * Carries `group/handle` so all handle child slots can consume data-* interaction
+ * states via `group-data-[x]/handle:` Tailwind selectors without any CVA variant props.
  *
- * MD3 spec: the top 48dp of the sheet is the interactive touch target area
- * when the drag handle is present. The wrapper provides this touch target.
+ * MD3 spec: 22dp top + 4dp handle + 22dp bottom = 48dp interaction zone.
+ * NOTE: py-[22px] is a measurement-derived value from MD3 spec; permitted exception.
+ *
+ * `relative` provides positioning context for the state layer and focus ring overlays.
+ * `focus-visible:outline-none` suppresses the browser default — the focus ring overlay
+ * in `bottomSheetHandleFocusRingVariants` provides the MD3-spec visible indicator instead.
  */
 declare const bottomSheetHandleWrapperVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
+type BottomSheetHandleWrapperVariants = VariantProps<typeof bottomSheetHandleWrapperVariants>;
 /**
- * CVA for the drag handle pill visual element.
+ * Drag handle pill — the visible 32×4dp decoration.
  *
  * MD3 tokens applied:
- * - bg-on-surface-variant: handle color
- * - w-8: 32dp width per MD3 spec
- * - h-1: 4dp height per MD3 spec
- * - rounded-full: fully rounded pill shape
- * - opacity-40: per MD3 spec (token deprecated but value still in spec)
+ * - bg-on-surface-variant: handle color (muted, low-emphasis by role — no opacity override needed)
+ * - w-8 / h-1: 32dp × 4dp per MD3 spec (measurement-derived; permitted exception)
+ * - rounded-full: fully-rounded pill shape
+ *
+ * `pointer-events-none` — all interaction is handled by the wrapper.
+ * `relative z-10` — renders above the state layer overlay.
  */
 declare const bottomSheetHandlePillVariants: (props?: class_variance_authority_types.ClassProp | undefined) => string;
-type BottomSheetHandleVariants = VariantProps<typeof bottomSheetHandleWrapperVariants>;
+type BottomSheetHandleVariants = BottomSheetHandleWrapperVariants;
 
 /**
  * Variant of the MD3 Time Picker.