@bug-on/md3-react 1.0.0 → 2.0.1

package/dist/material-symbols-self-hosted.css

@@ -53,28 +53,9 @@
 }
 
 /*
- * Rounded variant — uncomment nếu dùng
- *
-@font-face {
-  font-family: 'Material Symbols Rounded';
-  font-style: normal;
-  font-weight: 100 700;
-  font-display: block;
-  src: url('/fonts/MaterialSymbolsRounded[FILL,GRAD,opsz,wght].woff2') format('woff2');
-}
-*/
-
-/*
- * Sharp variant — uncomment nếu dùng
- *
-@font-face {
-  font-family: 'Material Symbols Sharp';
-  font-style: normal;
-  font-weight: 100 700;
-  font-display: block;
-  src: url('/fonts/MaterialSymbolsSharp[FILL,GRAD,opsz,wght].woff2') format('woff2');
-}
-*/
+ * Rounded variants and Sharp variants are not included by default to save space.
+ * You can declare them similarly if you download the respective woff2 files.
+ */
 
 /* ─────────────────────────────────────────────────────────────────────────────
  * BASE ICON STYLES

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>>;

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

@@ -0,0 +1,151 @@
+/**
+ * @file slider.tokens.ts
+ * MD3 Expressive Slider — Design tokens ported from:
+ *   - SliderTokens.kt (Jetpack Compose M3 Expressive)
+ *   - M3 Expressive visual spec (handle squeeze, gaps, asymmetric radii)
+ *
+ * All dimensional values are in px (dp equivalents for web).
+ * Colors reference CSS custom properties — do NOT hardcode hex.
+ * @see docs/m3/sliders/Slider.kt
+ */
+/**
+ * Core dimensional design tokens for the MD3 Expressive Slider.
+ * Maps directly from SliderTokens.kt to CSS/JS values.
+ */
+export declare const SliderTokens: {
+    readonly trackSizes: {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    };
+    readonly trackShapes: {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    };
+    /** Thumb height grows with track size */
+    readonly thumbHeights: {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    };
+    /**
+     * Thumb width at rest and on hover.
+     * MD3 Expressive handle pill: 4dp wide.
+     */
+    readonly thumbWidthDefault: 4;
+    /**
+     * Thumb width while pressed/dragging.
+     * "Squeeze" animation: 4dp → 2dp (M3 Expressive behavior).
+     */
+    readonly thumbWidthPressed: 2;
+    /**
+     * Transparent gap between the active/inactive track segments and the thumb.
+     * Maps to ActiveHandleLeadingSpace / ActiveHandleTrailingSpace = 6dp.
+     *
+     * This gap is rendered by mathematically subtracting it from the track
+     * segment width — NOT using margin/padding.
+     */
+    readonly thumbGap: 6;
+    /**
+     * Corner radius on the INNER ends of each track segment (facing the thumb).
+     * Fixed to 2px according to MD3 Expressive Slider specs (TrackInsideCornerSize).
+     * Outer ends use `trackSize / 2` (pill cap) — computed inline per component.
+     */
+    readonly trackInnerRadius: 2;
+    /** Tick dot size (width and height). = 4dp. */
+    readonly tickSize: 4;
+    /**
+     * Minimum touch target for the thumb wrapper.
+     * MD3 requires 48dp minimum touch target for interactive elements.
+     */
+    readonly thumbTouchTarget: 48;
+    /** Offset above the thumb center for the value indicator tooltip. */
+    readonly valueIndicatorOffset: 52;
+    /** Standard icon size map for inset icons inside the track. */
+    readonly insetIconSizes: {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    };
+    /**
+     * Padding between icon and track edge (horizontal).
+     * Keeps the icon visually centered within the pill track.
+     */
+    readonly insetIconPadding: 4;
+};
+/**
+ * CSS custom property references for Slider colors.
+ * Maps to --md-sys-color-* tokens in the MD3 theme system.
+ *
+ * DO NOT hardcode hex/rgba values — these references automatically
+ * adapt to light/dark theme.
+ */
+export declare const SliderColors: {
+    /** Active track color. Maps to ActiveTrackColor token. */
+    readonly activeTrack: "var(--md-sys-color-primary)";
+    /** Inactive track color. Maps to InactiveTrackColor token. */
+    readonly inactiveTrack: "var(--md-sys-color-secondary-container)";
+    /**
+     * Disabled track color.
+     * Uses opacity + on-surface per MD3 disabled state spec.
+     */
+    readonly disabledActiveTrack: "var(--md-sys-color-on-surface)";
+    readonly disabledInactiveTrack: "var(--md-sys-color-on-surface)";
+    /** Thumb (handle) color. Maps to HandleColor token. */
+    readonly thumb: "var(--md-sys-color-primary)";
+    /** Disabled thumb color. */
+    readonly disabledThumb: "var(--md-sys-color-on-surface)";
+    /** Value indicator (tooltip) background. Maps to InverseSurface. */
+    readonly valueIndicatorBg: "var(--md-sys-color-inverse-surface)";
+    /** Value indicator (tooltip) text. Maps to InverseOnSurface. */
+    readonly valueIndicatorText: "var(--md-sys-color-inverse-on-surface)";
+    /**
+     * Tick on the INACTIVE portion of the track.
+     * Maps to TickMarkActiveContainerColor (in spec: primary color stands out).
+     */
+    readonly tickOnInactive: "var(--md-sys-color-primary)";
+    /**
+     * Tick on the ACTIVE portion of the track.
+     * Maps to TickMarkInactiveContainerColor (secondary-container blends in).
+     */
+    readonly tickOnActive: "var(--md-sys-color-secondary-container)";
+    readonly disabledTick: "var(--md-sys-color-on-surface)";
+};
+/**
+ * FastSpatial spring for thumb width squeeze animation.
+ * Equivalent to MotionSchemeKeyTokens.FastSpatial in Compose.
+ */
+export declare const SLIDER_THUMB_SPRING: {
+    readonly type: "spring";
+    readonly stiffness: 500;
+    readonly damping: 40;
+};
+/**
+ * DefaultSpatial spring for thumb position/track updates.
+ * Slightly looser feel for position changes.
+ */
+export declare const SLIDER_POSITION_SPRING: {
+    readonly type: "spring";
+    readonly stiffness: 400;
+    readonly damping: 38;
+};
+/** Color crossfade for active/inactive track color transitions. */
+export declare const SLIDER_COLOR_TRANSITION: {
+    readonly duration: 0.18;
+    readonly ease: "easeInOut";
+};
+/** Value indicator appear/disappear animation. */
+export declare const SLIDER_INDICATOR_TRANSITION: {
+    readonly type: "spring";
+    readonly stiffness: 450;
+    readonly damping: 32;
+};