@bug-on/md3-react 2.0.0 → 2.0.2

package/dist/ui/app-bar/bottom-app-bar.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file bottom-app-bar.tsx
+ * MD3 Expressive Bottom App Bar.
+ *
+ * Fixed to bottom of screen. Contains action icons and optional FAB.
+ * Height: 80px | Background: surface-container | Elevation: Level2 (always)
+ *
+ * @see docs/m3/app-bars/BottomAppBarTokens.kt
+ */
+import type { BottomAppBarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Bottom App Bar.
+ *
+ * @example
+ * ```tsx
+ * // With FAB
+ * <BottomAppBar
+ *   actions={
+ *     <>
+ *       <IconButton aria-label="Check"><Icon>check_box</Icon></IconButton>
+ *       <IconButton aria-label="Brush"><Icon>brush</Icon></IconButton>
+ *     </>
+ *   }
+ *   floatingActionButton={<FAB aria-label="Compose">...</FAB>}
+ * />
+ *
+ * // Auto-hide on scroll
+ * <BottomAppBar scrollBehavior="hidden" actions={...} />
+ * ```
+ */
+export declare function BottomAppBar({ actions, floatingActionButton, scrollBehavior, scrollElement, className, }: BottomAppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/docked-toolbar.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file docked-toolbar.tsx
+ * MD3 Expressive Docked Toolbar.
+ *
+ * Secondary navigation component. NOT an App Bar.
+ * Usually appears directly below the main App Bar.
+ * Height: 64px | Background: surface-container
+ * Typical content: chips, segmented buttons, filter actions.
+ *
+ * @see docs/m3/app-bars/DockedToolbarTokens.kt
+ */
+import type { DockedToolbarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Docked Toolbar.
+ *
+ * @example
+ * ```tsx
+ * <DockedToolbar aria-label="Filter options">
+ *   <Chip label="All" selected onClick={() => setFilter('all')} />
+ *   <Chip label="Unread" onClick={() => setFilter('unread')} />
+ *   <Chip label="Starred" onClick={() => setFilter('starred')} />
+ * </DockedToolbar>
+ * ```
+ */
+export declare function DockedToolbar({ children, "aria-label": ariaLabel, className, }: DockedToolbarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/hooks/use-app-bar-scroll.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file use-app-bar-scroll.ts
+ * MD3 Expressive App Bar — Scroll behavior hook.
+ *
+ * Tracks scroll state for App Bar behaviors:
+ * - `pinned`: background color change only
+ * - `enterAlways`: hide/show based on scroll direction
+ * - `exitUntilCollapsed`: drives collapse fraction (0 = expanded, 1 = collapsed)
+ */
+import * as React from "react";
+import type { AppBarScrollBehavior, UseAppBarScrollReturn } from "../app-bar.types";
+interface UseAppBarScrollOptions {
+    /** Ref to the scrollable container. Defaults to `window`. */
+    scrollElement?: React.RefObject<HTMLElement | null>;
+    /** Scroll behavior mode. @default "pinned" */
+    behavior?: AppBarScrollBehavior;
+    /** Collapsed height in px — used for `exitUntilCollapsed`. @default 64 */
+    collapsedHeight?: number;
+    /** Expanded height in px — used for `exitUntilCollapsed`. @default 112 */
+    expandedHeight?: number;
+}
+/**
+ * Tracks scroll position and derives App Bar state for all three behaviors.
+ *
+ * @example
+ * ```tsx
+ * // pinned (color change only)
+ * const { isScrolled } = useAppBarScroll({ behavior: 'pinned' });
+ *
+ * // enterAlways (hide/show)
+ * const { isHidden } = useAppBarScroll({ behavior: 'enterAlways' });
+ *
+ * // exitUntilCollapsed (collapse animation)
+ * const { collapsedFraction } = useAppBarScroll({
+ *   behavior: 'exitUntilCollapsed',
+ *   collapsedHeight: 64,
+ *   expandedHeight: 112,
+ * });
+ * ```
+ */
+export declare function useAppBarScroll({ scrollElement, behavior, collapsedHeight, expandedHeight, }?: UseAppBarScrollOptions): UseAppBarScrollReturn;
+export {};

package/dist/ui/app-bar/hooks/use-flexible-app-bar.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file use-flexible-app-bar.ts
+ * Shared animation hook for MediumFlexibleAppBar and LargeFlexibleAppBar.
+ *
+ * Extracts common scroll-driven animation state to avoid duplication.
+ */
+import type { MotionValue } from "motion/react";
+import type { RefObject } from "react";
+import type { AppBarColors } from "../app-bar.types";
+interface UseFlexibleAppBarOptions {
+    collapsedHeight: number;
+    expandedHeight: number;
+    scrollElement?: RefObject<HTMLElement | null>;
+    colors?: AppBarColors;
+    /** [start, end] progress range where large title fades from 1 → 0 */
+    largeTitleFadeRange: [number, number];
+    /** [start, end] progress range where small title fades from 0 → 1 */
+    smallTitleFadeRange: [number, number];
+    /** [start, end] progress range where subtitle fades from 1 → 0 */
+    subtitleFadeRange: [number, number];
+    /** [start, end] progress range where headerContent fades from 1 → 0 */
+    headerContentFadeRange: [number, number];
+    /** [expanded, collapsed] Y offset for large title */
+    largeTitleYRange: [number, number];
+}
+export interface FlexibleAppBarAnimationState {
+    height: MotionValue<number>;
+    currentBg: string;
+    cssTransition: string | undefined;
+    largeTitleOpacity: MotionValue<number>;
+    largeTitleY: MotionValue<number>;
+    smallTitleOpacity: MotionValue<number>;
+    subtitleOpacity: MotionValue<number>;
+    headerContentOpacity: MotionValue<number>;
+}
+export declare function useFlexibleAppBar({ collapsedHeight, expandedHeight, scrollElement, colors, largeTitleFadeRange, smallTitleFadeRange, subtitleFadeRange, headerContentFadeRange, largeTitleYRange, }: UseFlexibleAppBarOptions): FlexibleAppBarAnimationState;
+export {};

package/dist/ui/app-bar/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file index.ts
+ * MD3 Expressive App Bar — Public API exports.
+ *
+ * Components:
+ * - SmallAppBar: Single-row, 64px height, TitleLarge
+ * - MediumFlexibleAppBar: Collapsible, HeadlineMedium → TitleLarge
+ * - LargeFlexibleAppBar: Collapsible, DisplaySmall → TitleLarge
+ * - SearchAppBar: Pill search bar with layoutId for SearchView transition
+ * - SearchView: Full-screen search overlay
+ * - SearchViewContainer: Wraps SearchView with AnimatePresence
+ * - BottomAppBar: Fixed bottom nav with optional FAB
+ * - DockedToolbar: Secondary navigation bar
+ * - AppBarRow: Horizontal actions with overflow
+ * - AppBarColumn: Vertical actions with overflow
+ * - AppBarOverflowIndicator: More-vert dropdown trigger
+ *
+ * Hook:
+ * - useAppBarScroll: Drives scroll-based behavior (pinned / enterAlways / exitUntilCollapsed)
+ *
+ * Tokens:
+ * - AppBarTokens: Dimensional tokens (heights, spacing)
+ * - appBarTypography: Typography class strings
+ * - APP_BAR_COLORS: CSS custom property color references
+ * - Animation constants (APP_BAR_COLOR_TRANSITION, etc.)
+ */
+export { APP_BAR_BOTTOM_SPRING, APP_BAR_COLOR_TRANSITION, APP_BAR_COLORS, APP_BAR_ENTER_ALWAYS_SPRING, APP_BAR_TITLE_FADE, AppBarTokens, appBarTypography, SEARCH_VIEW_SPRING, } from "./app-bar.tokens";
+export type { AppBarColors, AppBarColumnProps, AppBarItem, AppBarItemType, AppBarMenuState, AppBarOverflowIndicatorProps, AppBarRowProps, AppBarScrollBehavior, BaseAppBarProps, BottomAppBarProps, DockedToolbarProps, FlexibleAppBarProps, SearchAppBarProps, SearchBarVariant, SearchViewProps, SmallAppBarProps, TitleAlignment, UseAppBarScrollReturn, } from "./app-bar.types";
+export { AppBarColumn } from "./app-bar-column";
+export { AppBarOverflowIndicator } from "./app-bar-overflow-indicator";
+export { AppBarRow } from "./app-bar-row";
+export { BottomAppBar } from "./bottom-app-bar";
+export { DockedToolbar } from "./docked-toolbar";
+export { useAppBarScroll } from "./hooks/use-app-bar-scroll";
+export { LargeFlexibleAppBar } from "./large-flexible-app-bar";
+export { MediumFlexibleAppBar } from "./medium-flexible-app-bar";
+export { SearchAppBar } from "./search-app-bar";
+export { SearchView, SearchViewContainer } from "./search-view";
+export { SmallAppBar } from "./small-app-bar";

package/dist/ui/app-bar/large-flexible-app-bar.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file large-flexible-app-bar.tsx
+ * MD3 Expressive Large Flexible App Bar.
+ *
+ * Like MediumFlexibleAppBar but with larger typography.
+ * Expanded height: 120px (no subtitle) / 152px (with subtitle)
+ * Collapsed height: 64px
+ * Title crossfade: DisplaySmall (expanded) ↔ TitleLarge (collapsed)
+ *
+ * @see docs/m3/app-bars/AppBarLargeFlexibleTokens.kt
+ */
+import type { FlexibleAppBarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Large Flexible App Bar.
+ *
+ * @example
+ * ```tsx
+ * <LargeFlexibleAppBar
+ *   title="Discover"
+ *   subtitle="Trending today"
+ *   navigationIcon={<IconButton aria-label="Open menu"><Icon>menu</Icon></IconButton>}
+ *   headerContent={<img src="/banner.jpg" alt="" className="rounded-xl h-20 w-full object-cover" />}
+ * />
+ * ```
+ */
+export declare function LargeFlexibleAppBar({ title, subtitle, titleAlignment, navigationIcon, actions, colors, scrollElement, headerContent, collapsedHeight, expandedHeight, className, }: FlexibleAppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/medium-flexible-app-bar.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file medium-flexible-app-bar.tsx
+ * MD3 Expressive Medium Flexible App Bar.
+ *
+ * Two-row layout in expanded state, collapses to single row on scroll.
+ * Expanded height: 112px (no subtitle) / 136px (with subtitle)
+ * Collapsed height: 64px
+ * Title crossfade: HeadlineMedium (expanded) ↔ TitleLarge (collapsed)
+ *
+ * Supports `exitUntilCollapsed` scroll behavior only.
+ *
+ * @see docs/m3/app-bars/AppBarMediumFlexibleTokens.kt
+ */
+import type { FlexibleAppBarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Medium Flexible App Bar.
+ *
+ * @example
+ * ```tsx
+ * <MediumFlexibleAppBar
+ *   title="Settings"
+ *   subtitle="Manage your preferences"
+ *   navigationIcon={<IconButton aria-label="Go back"><Icon>arrow_back</Icon></IconButton>}
+ *   actions={<IconButton aria-label="More options"><Icon>more_vert</Icon></IconButton>}
+ * />
+ * ```
+ */
+export declare function MediumFlexibleAppBar({ title, subtitle, titleAlignment, navigationIcon, actions, colors, scrollElement, headerContent, collapsedHeight, expandedHeight, className, }: FlexibleAppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/search-app-bar.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @file search-app-bar.tsx
+ * MD3 Expressive Search App Bar.
+ *
+ * New variant in MD3 Expressive (May 2025).
+ * Replaces the title area with a pill-shaped search bar.
+ * Uses Framer Motion layoutId to enable shared element transition with <SearchView>.
+ *
+ * @see docs/m3/app-bars/AppBar.kt — SearchAppBar
+ */
+import type { SearchAppBarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Search App Bar.
+ *
+ * When the search bar is clicked, callers should open a `<SearchView>` overlay.
+ * Uses Framer Motion `layoutId` (via `searchBarId`) for a smooth shared-element
+ * transition between this bar and the search view.
+ *
+ * @example
+ * ```tsx
+ * const [searchOpen, setSearchOpen] = useState(false);
+ *
+ * <SearchAppBar
+ *   searchBarId="main-search"
+ *   searchPlaceholder="Search messages..."
+ *   onSearchFocus={() => setSearchOpen(true)}
+ *   trailingSearchActions={
+ *     <IconButton aria-label="Voice search"><Icon>mic</Icon></IconButton>
+ *   }
+ *   externalActions={<Avatar src={user.avatar} />}
+ * />
+ *
+ * <AnimatePresence>
+ *   {searchOpen && (
+ *     <SearchView
+ *       searchBarId="main-search"
+ *       onClose={() => setSearchOpen(false)}
+ *     />
+ *   )}
+ * </AnimatePresence>
+ * ```
+ */
+export declare function SearchAppBar({ searchPlaceholder, searchValue, onSearchFocus, leadingSearchIcon, trailingSearchActions, externalActions, navigationIcon, colors, scrollBehavior, scrollElement, searchBarId, className, }: SearchAppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/search-view.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file search-view.tsx
+ * MD3 Expressive Search View.
+ *
+ * Full-screen overlay activated when a SearchAppBar's search bar is clicked.
+ * Shares a Framer Motion `layoutId` with the SearchAppBar search bar for a
+ * smooth shared element transition.
+ *
+ * Usage pattern:
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * // In render:
+ * <SearchAppBar searchBarId="main" onSearchFocus={() => setOpen(true)} />
+ * <AnimatePresence>
+ *   {open && <SearchView searchBarId="main" onClose={() => setOpen(false)} />}
+ * </AnimatePresence>
+ * ```
+ *
+ * Design notes:
+ * - The SearchView is intentionally separate from SearchAppBar to allow consumers
+ *   to customize the results/suggestions content without coupling.
+ * - The `searchBarId` prop must match between SearchAppBar and SearchView to
+ *   enable the shared element transition.
+ * - Focus is moved to the search input when the view opens.
+ * - Escape key closes the view and returns focus to the search bar.
+ */
+import type { SearchViewProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Search View.
+ *
+ * Renders a full-screen search overlay with a shared element transition
+ * from the triggering `<SearchAppBar>` search bar.
+ *
+ * Mount/unmount this component via `<AnimatePresence>` in the consumer.
+ */
+export declare function SearchView({ searchBarId, value, onChange, onClose, placeholder, children, leadingIcon, trailingAction, className, }: SearchViewProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Convenience wrapper that handles the AnimatePresence + open state.
+ *
+ * @example
+ * ```tsx
+ * <SearchBar
+ *   isOpen={searchOpen}
+ *   onClose={() => setSearchOpen(false)}
+ *   searchBarId="main-search"
+ * >
+ *   <SearchResultsList results={results} />
+ * </SearchBar>
+ * ```
+ */
+export declare function SearchViewContainer({ isOpen, ...props }: SearchViewProps & {
+    isOpen: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/ui/app-bar/small-app-bar.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file small-app-bar.tsx
+ * MD3 Expressive Small App Bar.
+ *
+ * Single-row layout: [navigationIcon][title + subtitle][actions]
+ * Height: 64px | Title: TitleLarge (22sp) | Subtitle: LabelMedium (12sp)
+ *
+ * Scroll behaviors:
+ * - pinned: changes background color surface → surface-container
+ * - enterAlways: slides up when scrolling down, slides down when scrolling up
+ *
+ * @see docs/m3/app-bars/AppBarSmallTokens.kt
+ */
+import type { SmallAppBarProps } from "./app-bar.types";
+/**
+ * MD3 Expressive Small App Bar.
+ *
+ * @example
+ * ```tsx
+ * // Left-aligned (default)
+ * <SmallAppBar
+ *   title="Inbox"
+ *   navigationIcon={<IconButton aria-label="Go back"><Icon>arrow_back</Icon></IconButton>}
+ *   actions={<IconButton aria-label="Search"><Icon>search</Icon></IconButton>}
+ *   scrollBehavior="pinned"
+ * />
+ *
+ * // Center-aligned with subtitle
+ * <SmallAppBar
+ *   title="Profile"
+ *   subtitle="@username"
+ *   titleAlignment="center"
+ *   scrollBehavior="enterAlways"
+ * />
+ * ```
+ */
+export declare function SmallAppBar({ title, subtitle, titleAlignment, navigationIcon, actions, colors, scrollBehavior, scrollElement, className, }: SmallAppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/slider/hooks/useSliderMath.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @file useSliderMath.ts
+ * MD3 Expressive Slider — Math utility hook.
+ *
+ * Handles all slider math in one place:
+ * - value coercion to [min, max]
+ * - step snapping for discrete mode
+ * - value ↔ percent conversion
+ * - keyboard delta calculation
+ * - tick position generation
+ *
+ * Exported as a pure hook for testability and reuse in both Slider and RangeSlider.
+ */
+/**
+ * Clamps `value` to the closed interval `[min, max]`.
+ *
+ * @example coerceValue(150, 0, 100) → 100
+ */
+export declare function coerceValue(value: number, min: number, max: number): number;
+/**
+ * Rounds `value` to the nearest multiple of `step` relative to `min`.
+ * When `step === 0`, returns `value` unchanged (continuous mode).
+ *
+ * @example snapToStep(23, 0, 10) → 20
+ * @example snapToStep(27, 0, 10) → 30
+ */
+export declare function snapToStep(value: number, min: number, step: number): number;
+/**
+ * Converts a raw value to a 0–1 fraction of the [min, max] range.
+ * Returns 0 when max === min (degenerate range).
+ *
+ * @example valueToPercent(50, 0, 100) → 0.5
+ */
+export declare function valueToPercent(value: number, min: number, max: number): number;
+/**
+ * Converts a 0–1 fraction to a value within [min, max], then snaps to step.
+ * The result is also coerced to [min, max].
+ *
+ * @example percentToValue(0.5, 0, 100, 10) → 50
+ * @example percentToValue(0.23, 0, 100, 10) → 20
+ */
+export declare function percentToValue(percent: number, min: number, max: number, step: number): number;
+/**
+ * Computes the keyboard increment for a given key.
+ *
+ * Key mappings per WAI-ARIA Slider pattern:
+ * - ArrowRight/Up → +step (or +1% of range if continuous)
+ * - ArrowLeft/Down → -step (or -1% of range)
+ * - PageUp → +10% of range (snapped to step)
+ * - PageDown → -10% of range (snapped to step)
+ * - Home / End → handled by the caller (jump to min/max)
+ *
+ * @returns the signed delta to add to current value, or `null` for Home/End.
+ */
+export declare function getKeyboardDelta(key: string, step: number, min: number, max: number): number | null;
+/**
+ * Generates the list of value positions for tick marks.
+ * Returns an empty array when `step === 0` (continuous mode).
+ *
+ * @example generateTicks(0, 100, 10) → [0, 10, 20, ..., 100]
+ */
+export declare function generateTicks(min: number, max: number, step: number): number[];
+export interface UseSliderMathOptions {
+    min: number;
+    max: number;
+    step: number;
+}
+export interface UseSliderMathReturn {
+    /** Clamp value to [min, max]. */
+    coerce: (v: number) => number;
+    /** Snap value to nearest step (no-op if step=0). */
+    snap: (v: number) => number;
+    /** Value → percent [0, 1]. */
+    toPercent: (v: number) => number;
+    /** Percent [0, 1] → snapped value. */
+    fromPercent: (pct: number) => number;
+    /**
+     * Signed delta for a keyboard key.
+     * Returns `null` for Home/End (jump to min/max, handled by caller).
+     */
+    getKeyDelta: (key: string) => number | null;
+    /** Tick positions. Empty array in continuous mode. */
+    ticks: number[];
+}
+/**
+ * Math utility hook for MD3 Slider components.
+ *
+ * Memoizes all math functions against `min`, `max`, `step` changes.
+ * Use this in both `<Slider>` and `<RangeSlider>` to share logic.
+ *
+ * @example
+ * ```ts
+ * const { coerce, snap, toPercent, fromPercent, getKeyDelta, ticks } =
+ *   useSliderMath({ min: 0, max: 100, step: 10 });
+ *
+ * const percent = toPercent(value);          // → 0.5 for value=50
+ * const newValue = fromPercent(dragPercent); // → 50
+ * const delta = getKeyDelta("ArrowRight");   // → 10
+ * ```
+ */
+export declare function useSliderMath({ min, max, step, }: UseSliderMathOptions): UseSliderMathReturn;

package/dist/ui/slider/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file index.ts
+ * MD3 Expressive Slider — Public API exports.
+ */
+export { RangeSlider } from "./range-slider";
+export { Slider } from "./slider";
+export { SliderColors, SliderTokens } from "./slider.tokens";
+export type { RangeSliderProps, SliderOrientation, SliderProps, SliderTrackSize, SliderVariant, } from "./slider.types";
+export { SliderThumb } from "./slider-thumb";

package/dist/ui/slider/range-slider.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file range-slider.tsx
+ * MD3 Expressive RangeSlider — Two-thumb slider with crossover prevention.
+ *
+ * Extends the core Slider architecture with:
+ * - Two SliderThumb instances (start + end)
+ * - Crossover prevention: start cannot exceed end and vice versa
+ * - Z-index management: last-dragged thumb always on top
+ * - Active track spans from startPercent to endPercent
+ *
+ * Design decisions:
+ * - The track renders a custom "range" segment between the two thumbs.
+ * - Each thumb has independent onValueChange callbacks + crossover clamping.
+ * - Last-active thumb gets zIndex=2 to appear on top when thumbs are at same position.
+ *
+ * @see https://m3.material.io/components/sliders/overview
+ * @see docs/m3/sliders/Slider.kt#RangeSlider
+ */
+import * as React from "react";
+import type { RangeSliderProps } from "./slider.types";
+/**
+ * MD3 Expressive RangeSlider component.
+ *
+ * Two-thumb slider where the active track spans between the two thumbs.
+ * Thumbs cannot cross each other (crossover prevention built in).
+ *
+ * @example
+ * ```tsx
+ * // Controlled
+ * <RangeSlider
+ *   value={[20, 80]}
+ *   onValueChange={([start, end]) => setRange([start, end])}
+ *   aria-label="Price range"
+ * />
+ *
+ * // Discrete
+ * <RangeSlider defaultValue={[0, 100]} step={10} />
+ *
+ * // Vertical
+ * <div className="h-64">
+ *   <RangeSlider defaultValue={[25, 75]} orientation="vertical" />
+ * </div>
+ * ```
+ *
+ * @see https://m3.material.io/components/sliders/overview
+ */
+export declare const RangeSlider: React.NamedExoticComponent<RangeSliderProps & React.RefAttributes<HTMLDivElement>>;

package/dist/ui/slider/slider-thumb.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file slider-thumb.tsx
+ * MD3 Expressive Slider — Animated pill-shaped thumb (handle).
+ *
+ * Design decisions:
+ * 1. POINTER EVENTS (not Framer Motion drag): We use React pointer events
+ *    + useMotionValue for real-time position tracking without re-render lag.
+ *    Framer Motion's `drag` prop adds momentum/inertia that conflicts with MD3
+ *    precise positioning; direct pointer handling gives us full control.
+ * 2. SQUEEZE ANIMATION: `whileTap` shrinks width from 4px → 2px via spring.
+ * 3. INVERTED Y-AXIS: Vertical slider maps bottom=min, top=max by inverting
+ *    the pointer delta direction.
+ * 4. VALUE INDICATOR: AnimatePresence pill tooltip with teardrop origin point.
+ * 5. ACCESSIBILITY: role=slider, full ARIA attributes, keyboard nav.
+ * 6. prefers-reduced-motion: Disables all animations for accessibility.
+ *
+ * @see docs/m3/sliders/Slider.kt#SliderDefaults.Thumb
+ */
+import * as React from "react";
+import type { SliderThumbProps } from "./slider.types";
+/**
+ * MD3 Expressive Slider Thumb (handle).
+ *
+ * - Pill shape: 4px wide × 44px tall by default.
+ * - Squeezes to 2px wide on press/drag (Framer Motion spring).
+ * - Floats above track via absolute positioning at `percent` along the track.
+ * - Handles pointer drag via React PointerEvents + useMotionValue.
+ * - Full keyboard navigation per WAI-ARIA Slider pattern.
+ * - Value indicator tooltip with AnimatePresence.
+ *
+ * @internal — consumed by `<Slider>` and `<RangeSlider>`
+ */
+export declare const SliderThumb: React.NamedExoticComponent<SliderThumbProps>;

package/dist/ui/slider/slider-track.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @file slider-track.tsx
+ * MD3 Expressive Slider — Track with asymmetric corner radii, 6px thumb gaps,
+ * discrete tick marks, and centered-mode support.
+ *
+ * Design decisions:
+ * 1. GAP MATH: The 6px gap between track and thumb is calculated mathematically
+ *    using CSS calc() — NOT using margin/padding which would break layout.
+ * 2. ASYMMETRIC RADII: Inner corners (facing thumb) = 2px; outer ends = size/2 (pill cap).
+ * 3. CENTERED MODE: Active segment spans from 50% outward to thumb, not from min.
+ * 4. TICKS: 4×4px dots positioned absolutely along track center axis.
+ *    Color differs on active vs inactive portions of the track.
+ * 5. VERTICAL: Uses height/top instead of width/left, with inverted axis
+ *    (bottom=0%, top=100%) per MD3 vertical spec.
+ *
+ * @see docs/m3/sliders/Slider.kt#SliderDefaults.Track
+ */
+import * as React from "react";
+import type { SliderTrackProps } from "./slider.types";
+/**
+ * MD3 Expressive Slider Track.
+ */
+export declare const SliderTrack: React.NamedExoticComponent<Omit<SliderTrackProps, "step"> & {
+    ticks?: number[];
+}>;

package/dist/ui/slider/slider.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @file slider.tsx
+ * MD3 Expressive Slider — Main composition component.
+ *
+ * Supports:
+ * - Controlled and uncontrolled usage patterns
+ * - Horizontal and vertical orientations
+ * - Discrete mode (step snapping + tick marks)
+ * - Centered active track (isCentered)
+ * - Value indicator tooltip
+ * - Full keyboard navigation (ARIA Slider pattern)
+ * - Click-to-jump on track
+ *
+ * Architecture: Flat (no Context needed for single thumb variant).
+ * Track + Thumb are internal sub-components composed here.
+ *
+ * @see https://m3.material.io/components/sliders/overview
+ * @see docs/m3/sliders/Slider.kt
+ */
+import * as React from "react";
+import type { SliderProps } from "./slider.types";
+/**
+ * MD3 Expressive Slider component.
+ *
+ * A pill-shaped vertical handle that slides along a rounded track.
+ * Supports continuous and discrete (step) modes, horizontal/vertical
+ * orientations, and centered active track.
+ *
+ * Features:
+ * - M3 Expressive handle: 4px pill that squeezes to 2px on press
+ * - 6px transparent gap between track and thumb
+ * - Asymmetric corner radii: outer ends=9999px, inner ends=2px
+ * - Tick marks for discrete mode
+ * - Optional floating value indicator tooltip
+ * - Full keyboard navigation per WAI-ARIA Slider pattern
+ *
+ * @example
+ * ```tsx
+ * // Basic controlled
+ * <Slider value={volume} onValueChange={setVolume} aria-label="Volume" />
+ *
+ * // Discrete with ticks
+ * <Slider defaultValue={0} step={10} min={0} max={100} />
+ *
+ * // Vertical orientation
+ * <div className="h-64">
+ *   <Slider defaultValue={50} orientation="vertical" aria-label="Brightness" />
+ * </div>
+ *
+ * // Centered active track
+ * <Slider defaultValue={0} isCentered showValueIndicator />
+ *
+ * // Large track with value tooltip
+ * <Slider defaultValue={50} trackSize="l" showValueIndicator
+ *   formatValue={(v) => `${v}%`} />
+ * ```
+ *
+ * @see https://m3.material.io/components/sliders/overview
+ */
+export declare const Slider: React.NamedExoticComponent<SliderProps & React.RefAttributes<HTMLDivElement>>;