@tinybigui/react 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -9192,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;
@@ -9297,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
@@ -9313,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

@@ -9192,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;
@@ -9297,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
@@ -9313,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.js

@@ -11155,7 +11155,7 @@ var BottomSheetModalPanel = ({
       "aria-modal": "true",
       className: cn(className, getAnimationClassName?.(animationState)),
       "data-animation-state": animationState,
-      "data-dragging": isDragging || void 0,
+      "data-dragging": isDragging ? "" : void 0,
       style: panelStyle,
       onTransitionEnd,
       children
@@ -11292,7 +11292,7 @@ var BottomSheetHeadless = forwardRef(
           ref,
           className: cn(className, getAnimationClassName?.(animationState)),
           "data-animation-state": animationState,
-          "data-dragging": isDragging || void 0,
+          "data-dragging": isDragging ? "" : void 0,
           style: panelStyle,
           onTransitionEnd: handleTransitionEnd,
           children
@@ -11307,7 +11307,6 @@ var bottomSheetAnimationVariants = cva("", {
   variants: {
     animationState: {
       // entering: initial mount frame — sheet starts below viewport (translateY(100%))
-      // The CSS is handled inside animate-md-slide-in-bottom keyframes
       entering: ["opacity-0"],
       // visible: entry animation active — animate-md-slide-in-bottom runs once
       visible: ["animate-md-slide-in-bottom"],
@@ -11324,52 +11323,38 @@ var bottomSheetAnimationVariants = cva("", {
 var bottomSheetVariants = cva(
   [
     // Position: fixed to bottom edge, full width
-    "fixed",
-    "bottom-0",
-    "left-0",
-    "right-0",
+    "fixed bottom-0 left-0 right-0",
     // Surface token
     "bg-surface-container-low",
     // Elevation level 1 per MD3 spec
     "shadow-elevation-1",
-    // Shape: extra-large top corners (28dp), bottom corners are 0 (attached to screen edge)
+    // Shape: extra-large top corners (28dp), square bottom (screen-attached)
+    // NOTE: measurement-derived value from MD3 spec; permitted exception per component-variants rule
     "rounded-t-xl",
     // Layout
-    "flex",
-    "flex-col",
-    // Max width constraint (full width up to 640dp)
+    "flex flex-col",
+    // Width constraint (full width up to 640dp)
     "mx-auto",
     // NOTE: measurement-derived value from MD3 spec; permitted exception
     "w-[640px] max-w-full",
-    // Clip content during height transitions (sheet shrinks/grows from bottom edge)
+    // Clip content during height transitions
     "overflow-hidden",
-    // Transition: height for snap spring (MD3 spec — sheet "resizes" between heights)
-    // Standard personality, default speed tier, spatial: no overshoot.
-    // During drag, data-[dragging=true]:transition-none suppresses this so the
-    // sheet height follows the pointer 1:1 without transition lag.
-    // After drag release, the spring transition animates height to the new snap position.
+    // Snap spring: spatial property (height), standard personality, default tier
     "transition-[height]",
     "duration-spring-standard-default-spatial",
     "ease-spring-standard-default-spatial",
-    "data-[dragging=true]:transition-none",
+    // Suppress spring while dragging so the sheet follows the pointer 1:1
+    "data-[dragging]:transition-none",
     "will-change-[height]",
-    // Responsive layout: when viewport > 640dp, apply wider top margin per MD3 spec.
-    // The sheet remains bottom-anchored at all sizes. Side centering is handled by
-    // mx-auto + max-w-[640px] — at 752dp viewport this naturally produces 56dp side
-    // margins on each side (exactly matching MD3 measurements).
-    // Top margin is expressed as max-height so the sheet cannot overlap the top edge:
-    // - Default: 72dp top margin (max-h-[calc(100vh-72px)])
-    // - Wide viewport (> 640dp): 56dp top margin (sm:max-h-[calc(100vh-56px)])
+    // Responsive layout: top margin expressed as max-height
     // NOTE: measurement-derived values from MD3 spec; permitted exception
     "max-h-[calc(100vh-72px)]",
-    "sm:max-h-[calc(100vh-56px)]",
-    // Top corners rounded at wide layout (sheet floats away from screen edge)
-    "rounded-t-xl"
+    "sm:max-h-[calc(100vh-56px)]"
   ],
   {
     variants: {
       variant: {
-        // Modal: above scrim (z-50)
+        // Modal: rendered above the scrim (z-50)
         modal: "z-50",
         // Standard: sits above normal content but below overlays
         standard: "z-10"
@@ -11381,62 +11366,96 @@ var bottomSheetVariants = cva(
   }
 );
 var bottomSheetScrimVariants = cva([
-  "fixed",
-  "inset-0",
-  "z-40",
-  "bg-scrim",
-  "opacity-32",
-  "transition-opacity",
-  "duration-short4",
-  "ease-standard"
+  "fixed inset-0 z-40",
+  "bg-scrim opacity-32",
+  // Screen-level effects transition (scrim enters/exits the screen, not an on-screen state change)
+  "transition-opacity duration-short4 ease-standard"
 ]);
 var bottomSheetHandleWrapperVariants = cva([
-  // Center the handle pill horizontally
-  "flex",
-  "items-center",
-  "justify-center",
-  // Top/bottom padding creates the 48dp touch target area
-  // 22dp top + 4dp handle + 22dp bottom ≈ 48dp interaction zone (per MD3 measurements)
+  // Center the pill horizontally; provide positioning context for overlays
+  "relative flex items-center justify-center w-full",
+  // 48dp touch target (22dp top + 4dp pill + 22dp bottom)
   // NOTE: measurement-derived value from MD3 spec; permitted exception
   "py-[22px]",
-  // Full width so the touch target spans the sheet
-  "w-full",
-  // Focus ring styling for keyboard/switch navigation
-  // MD3 spec: focus indicator color = secondary, thickness = 3dp, offset = 2dp
+  // Suppress browser default focus outline — the focus-ring overlay slot handles it
   "focus-visible:outline-none",
-  "focus-visible:ring-3",
-  "focus-visible:ring-secondary",
-  "focus-visible:ring-offset-2",
-  "focus-visible:rounded-sm",
-  // Cursor affordance
+  // Cursor affordance for drag interaction
   "cursor-ns-resize"
 ]);
+var bottomSheetHandleStateLayerVariants = cva([
+  // Overlay positioned centrally — sits behind the pill
+  "absolute pointer-events-none",
+  // Pill-shaped to complement the handle's form
+  "rounded-full",
+  // Sized wider than the pill to provide a visible state layer halo
+  // 48dp wide × 16dp tall — centred by the flex wrapper
+  "w-12 h-4",
+  // State-layer color (same role as the pill)
+  "bg-on-surface-variant",
+  // Effects transition — opacity must NOT overshoot
+  "transition-opacity duration-spring-standard-fast-effects ease-spring-standard-fast-effects",
+  // Opacity at rest
+  "opacity-0",
+  // Hover: 8%
+  "group-data-[hovered]/handle:opacity-8",
+  // Focus-visible: 10%
+  "group-data-[focus-visible]/handle:opacity-10",
+  // Pressed: 10% (doubled selector wins over hover at same cascade position)
+  "group-data-[pressed]/handle:group-data-[pressed]/handle:opacity-10",
+  // Dragging: 16% (MD3 dragged state — highest on-screen opacity)
+  // Doubled selector wins over hover + pressed
+  "group-data-[dragging]/handle:group-data-[dragging]/handle:opacity-16"
+]);
+var bottomSheetHandleFocusRingVariants = cva([
+  "absolute pointer-events-none",
+  "rounded-full",
+  // Sized to sit around the state layer halo
+  "w-14 h-5",
+  // MD3 focus indicator: secondary color, 2dp weight
+  "outline outline-2 outline-offset-0 outline-secondary",
+  // Effects transition — opacity change must NOT overshoot
+  "transition-opacity duration-spring-standard-fast-effects ease-spring-standard-fast-effects",
+  // Hidden at rest; shown on keyboard/programmatic focus
+  "opacity-0",
+  "group-data-[focus-visible]/handle:opacity-100"
+]);
 var bottomSheetHandlePillVariants = cva([
+  "relative z-10 pointer-events-none",
   "bg-on-surface-variant",
-  "opacity-40",
   "rounded-full",
   // Dimensions: 32dp × 4dp per MD3 spec (measurement-derived; permitted exception)
   "w-8",
-  // 32dp = 2rem = w-8
-  "h-1",
-  // 4dp = 0.25rem = h-1
-  // Pill itself is decorative; the wrapper handles interaction
-  "pointer-events-none"
+  // 32dp = 2rem
+  "h-1"
+  // 4dp  = 0.25rem
 ]);
 function BottomSheetHandle({
   className,
   "aria-label": ariaLabelOverride
 }) {
   const { handleProps, isDragging } = useBottomSheetContext();
-  return /* @__PURE__ */ jsx(
+  const { isHovered, hoverProps } = useHover({});
+  const { isFocusVisible, focusProps } = useFocusRing();
+  const mergedHandleProps = mergeProps$1(handleProps, hoverProps, focusProps);
+  return /* @__PURE__ */ jsxs(
     "div",
     {
-      ...handleProps,
+      ...mergedHandleProps,
       ...ariaLabelOverride !== void 0 ? { "aria-label": ariaLabelOverride } : {},
-      className: cn(bottomSheetHandleWrapperVariants(), className),
+      className: cn(bottomSheetHandleWrapperVariants(), "group/handle", className),
       "data-testid": "bottom-sheet-handle",
-      "data-dragging": isDragging || void 0,
-      children: /* @__PURE__ */ jsx("span", { className: bottomSheetHandlePillVariants(), "aria-hidden": "true" })
+      ...getInteractionDataAttributes({
+        isHovered,
+        isFocusVisible,
+        // Treat active drag as pressed — drives the state layer to 10% opacity
+        isPressed: isDragging
+      }),
+      "data-dragging": isDragging ? "" : void 0,
+      children: [
+        /* @__PURE__ */ jsx("span", { className: cn(bottomSheetHandleStateLayerVariants()), "aria-hidden": "true" }),
+        /* @__PURE__ */ jsx("span", { className: cn(bottomSheetHandleFocusRingVariants()), "aria-hidden": "true" }),
+        /* @__PURE__ */ jsx("span", { className: cn(bottomSheetHandlePillVariants()), "aria-hidden": "true" })
+      ]
     }
   );
 }