@bug-on/md3-react 2.0.0 → 2.0.2

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

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

@@ -0,0 +1,259 @@
+/**
+ * @file slider.types.ts
+ * MD3 Expressive Slider — TypeScript prop definitions.
+ * Spec: https://m3.material.io/components/sliders/overview
+ * Reference: docs/m3/sliders/Slider.kt
+ */
+import type * as React from "react";
+/** Track size variants mapping to physical px values. */
+export type SliderTrackSize = "xs" | "s" | "m" | "l" | "xl";
+export type SliderVariant = "primary" | "secondary" | "tertiary" | "error";
+export type SliderTrackShape = "md3" | "full" | number;
+/** Slider layout direction. */
+export type SliderOrientation = "horizontal" | "vertical";
+/**
+ * Internal context shared between Slider sub-components.
+ * @internal
+ */
+export interface SliderContextValue {
+    /** Minimum allowed value. */
+    min: number;
+    /** Maximum allowed value. */
+    max: number;
+    /**
+     * Step size. When > 0, slider is discrete and snaps to multiples of step.
+     * When 0, slider is continuous.
+     */
+    step: number;
+    /** Whether the slider is interactive. */
+    disabled: boolean;
+    /** Layout orientation. */
+    orientation: SliderOrientation;
+    /** Physical size of the track. */
+    trackSize: SliderTrackSize;
+    /** Color variant. */
+    variant: SliderVariant;
+    /**
+     * When true, active track originates from center (50%) instead of the min end.
+     * Mirrors Compose's `SliderDefaults.Track(drawCenteredTrack = true)`.
+     */
+    isCentered: boolean;
+    /** Show the floating value tooltip on hover/drag. */
+    showValueIndicator: boolean;
+    /** Ref to the track DOM element — used for drag constraint. */
+    trackRef: React.RefObject<HTMLDivElement | null>;
+}
+/**
+ * Props for the `<Slider>` component.
+ *
+ * Supports both controlled (`value` + `onValueChange`) and
+ * uncontrolled (`defaultValue`) usage patterns per React standards.
+ *
+ * @example
+ * ```tsx
+ * // Controlled
+ * <Slider value={volume} onValueChange={setVolume} min={0} max={100} />
+ *
+ * // Uncontrolled
+ * <Slider defaultValue={50} />
+ *
+ * // Discrete (step snapping)
+ * <Slider defaultValue={0} step={10} />
+ *
+ * // Vertical orientation
+ * <Slider defaultValue={50} orientation="vertical" />
+ *
+ * // Centered active track
+ * <Slider defaultValue={0} isCentered />
+ * ```
+ */
+export interface SliderProps {
+    /** Controlled current value. Use with `onValueChange`. */
+    value?: number;
+    /** Initial value for uncontrolled usage. @default midpoint of min/max */
+    defaultValue?: number;
+    /** Called whenever the value changes during interaction. */
+    onValueChange?: (value: number) => void;
+    /** Called when the user finishes dragging / commits a keyboard change. */
+    onValueChangeEnd?: (value: number) => void;
+    /** Minimum value. @default 0 */
+    min?: number;
+    /** Maximum value. @default 100 */
+    max?: number;
+    /**
+     * Step size. When > 0, slider snaps to multiples of `step` from `min`
+     * and renders tick marks. When 0, slider is continuous.
+     * @default 0
+     */
+    step?: number;
+    /** Layout orientation. @default "horizontal" */
+    orientation?: SliderOrientation;
+    /**
+     * Physical track size.
+     * Horizontal: height. Vertical: width.
+     * @default "m"
+     */
+    trackSize?: SliderTrackSize;
+    /**
+     * Color variant.
+     * @default "primary"
+     */
+    variant?: SliderVariant;
+    /**
+     * When true, the active track segment grows from the center (50%)
+     * outward toward the thumb position.
+     * @default false
+     */
+    isCentered?: boolean;
+    /** Disables all interaction. @default false */
+    disabled?: boolean;
+    /**
+     * When true, shows a floating value indicator tooltip above the thumb.
+     * @default false
+     */
+    showValueIndicator?: boolean;
+    /**
+     * When true, shows tick marks along the track.
+     * Only applicable if `step` > 0.
+     * @default false
+     */
+    showTicks?: boolean;
+    /**
+     * Track shape configuration for border radius.
+     * - "md3": Default MD3 specific border radius per size
+     * - "full": Fully rounded ends (pill shape - size/2)
+     * - number: Custom border radius in px
+     * @default "md3"
+     */
+    trackShape?: SliderTrackShape;
+    /**
+     * Icon rendered inside the track (inset icon).
+     * MD3 spec: only valid for M, L, XL track sizes.
+     * The icon moves from the active track to the inactive track
+     * when there's not enough space at low values.
+     * Do not use with `isCentered` or `RangeSlider`.
+     */
+    insetIcon?: React.ReactNode;
+    /**
+     * Alternate icon shown when value equals `min`.
+     * Swaps with `insetIcon` at the minimum value
+     * (e.g., a mute icon replacing a volume icon when volume = 0).
+     */
+    insetIconAtMin?: React.ReactNode;
+    /**
+     * Icon rendered inside the track at the trailing end (right side).
+     * Only valid for track sizes >= 40dp (e.g. XL).
+     */
+    insetIconTrailing?: React.ReactNode;
+    /**
+     * Alternate icon shown when value equals `max`.
+     * Swaps with `insetIconTrailing` at the maximum value.
+     */
+    insetIconAtMax?: React.ReactNode;
+    /** Additional CSS class applied to the outermost wrapper. */
+    className?: string;
+    /**
+     * Accessible label for the slider when no visible label exists.
+     * Required if parent does not have a visible label.
+     */
+    "aria-label"?: string;
+    /** ID of a visible label element. Required if `aria-label` is not provided. */
+    "aria-labelledby"?: string;
+    /**
+     * Format function for the displayed value in the value indicator tooltip.
+     * Defaults to `String(value)`.
+     */
+    formatValue?: (value: number) => string;
+}
+/**
+ * Props for the `<RangeSlider>` component.
+ *
+ * Extends `SliderProps` with tuple-based value API.
+ * The two thumbs cannot cross each other.
+ *
+ * @example
+ * ```tsx
+ * <RangeSlider
+ *   value={[20, 80]}
+ *   onValueChange={([start, end]) => setRange([start, end])}
+ * />
+ * ```
+ */
+export interface RangeSliderProps extends Omit<SliderProps, "value" | "defaultValue" | "onValueChange" | "onValueChangeEnd" | "isCentered"> {
+    /** Controlled [start, end] tuple. Use with `onValueChange`. */
+    value?: [number, number];
+    /** Initial [start, end] tuple for uncontrolled usage. */
+    defaultValue?: [number, number];
+    /** Called whenever [start, end] changes during interaction. */
+    onValueChange?: (value: [number, number]) => void;
+    /** Called when the user finishes dragging either thumb. */
+    onValueChangeEnd?: (value: [number, number]) => void;
+}
+/**
+ * Props for `<SliderTrack>`.
+ * @internal
+ */
+export interface SliderTrackProps {
+    /** Current thumb position as 0–1 fraction. */
+    percent: number;
+    trackSize: SliderTrackSize;
+    orientation: SliderOrientation;
+    variant: SliderVariant;
+    isCentered: boolean;
+    /** For discrete mode: step size. 0 = no ticks. */
+    step: number;
+    min: number;
+    max: number;
+    disabled: boolean;
+    trackShape?: SliderTrackShape;
+    /** Ref forwarded to the root track element for drag constraint. */
+    trackRef: React.RefObject<HTMLDivElement | null>;
+    /** onClick handler on the track for click-to-jump. */
+    onTrackPointerDown?: (e: React.PointerEvent<HTMLDivElement>) => void;
+    /**
+     * Icon rendered inside the track (inset icon).
+     * @internal — passed down from Slider after guard check.
+     */
+    insetIcon?: React.ReactNode;
+    /** Alternate icon swapped in when value === min. @internal */
+    insetIconAtMin?: React.ReactNode;
+    /** Icon rendered at the trailing end (right side). @internal */
+    insetIconTrailing?: React.ReactNode;
+    /** Alternate icon swapped in when value === max. @internal */
+    insetIconAtMax?: React.ReactNode;
+    /** Current slider value — used for inset icon swap at min/max. @internal */
+    value?: number;
+}
+/**
+ * Props for `<SliderThumb>`.
+ * @internal
+ */
+export interface SliderThumbProps {
+    /** Current value (for ARIA). */
+    value: number;
+    /** Current 0–1 fraction (for positioning). */
+    percent: number;
+    min: number;
+    max: number;
+    step: number;
+    disabled: boolean;
+    orientation: SliderOrientation;
+    showValueIndicator: boolean;
+    /** For the drag constraint ref. */
+    trackRef: React.RefObject<HTMLDivElement | null>;
+    trackSize: SliderTrackSize;
+    variant: SliderVariant;
+    /** Called during pointer drag with new value. */
+    onValueChange: (value: number) => void;
+    /** Called on drag end / keyboard commit. */
+    onValueChangeEnd?: (value: number) => void;
+    /** Value display formatter. */
+    formatValue?: (value: number) => string;
+    /** Unique ID for ARIA. */
+    thumbId?: string;
+    /** zIndex for RangeSlider layering. */
+    zIndex?: number;
+    /** Optional accessible label for this specific thumb. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+}

package/dist/ui/snackbar/snackbar.d.ts

@@ -146,6 +146,7 @@ export declare namespace SnackbarHost {
 interface SnackbarContextValue {
     showSnackbar: (visuals: SnackbarVisuals) => Promise<SnackbarResult>;
 }
+export declare const SnackbarContext: React.Context<SnackbarContextValue | null>;
 /**
  * MD3 SnackbarProvider — context provider for imperative snackbar API.
  *

package/dist/ui/theme-provider/index.d.ts

@@ -1,5 +1,7 @@
 import { type ReactNode } from "react";
 import { type ThemeMode } from "../../lib/theme-utils";
+import { Typography } from "../typography/typography";
+import { type FontVariationAxes } from "../typography/typography-tokens";
 interface ThemeContextValue {
     sourceColor: string;
     setSourceColor: (color: string) => void;
@@ -11,8 +13,36 @@ export interface MD3ThemeProviderProps {
     sourceColor?: string;
     defaultMode?: ThemeMode;
     persistToLocalStorage?: boolean;
+    /**
+     * A fully custom `Typography` instance.
+     * When provided, `fontFamily` and `fontVariationAxes` are ignored.
+     */
+    typography?: Typography;
+    /**
+     * Override the CSS `font-family` for all typography styles.
+     * Ignored when `typography` prop is provided.
+     * @example "'Inter', sans-serif"
+     */
+    fontFamily?: string;
+    /**
+     * Variable font axes applied globally via `font-variation-settings`.
+     * Merged on top of defaults (`ROND: 100`). Ignored when `typography` is provided.
+     * @example { ROND: 50 }
+     */
+    fontVariationAxes?: FontVariationAxes;
+    /**
+     * When `true`, mounts `SnackbarHost` inside the provider and exposes
+     * `useSnackbar()` to all descendants — no separate `<SnackbarProvider>` needed.
+     *
+     * Opt-in, default `false`. For advanced usage (e.g., scoped snackbars or
+     * custom host positioning), keep this `false` and use `<SnackbarProvider>`
+     * or `<SnackbarHost>` directly.
+     *
+     * @default false
+     */
+    enableSnackbar?: boolean;
 }
-export declare function MD3ThemeProvider({ children, sourceColor: initialSourceColor, defaultMode, persistToLocalStorage, }: MD3ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function MD3ThemeProvider({ children, sourceColor: initialSourceColor, defaultMode, persistToLocalStorage, typography: typographyProp, fontFamily, fontVariationAxes, enableSnackbar, }: MD3ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
 export declare function useTheme(): ThemeContextValue;
 export declare function useThemeMode(): Pick<ThemeContextValue, "mode" | "setMode">;
 export {};

package/dist/ui/toc.d.ts

@@ -14,6 +14,7 @@
  *   (~100px) and early deactivation (~80% from bottom) so the active item changes
  *   before the section scrolls off-screen.
  */
+import { type ScrollAreaProps } from "./scroll-area";
 /**
  * A single entry in the Table of Contents.
  *
@@ -45,6 +46,11 @@ export interface TableOfContentsProps {
      * Use this to control positioning (e.g. sticky, fixed) from the consumer.
      */
     className?: string;
+    /**
+     * Configuration for the internal ScrollArea.
+     * @default { type: "hover" }
+     */
+    scrollAreaProps?: Omit<ScrollAreaProps, "children">;
 }
 /**
  * Table of Contents sidebar component.
@@ -71,4 +77,4 @@ export interface TableOfContentsProps {
  *
  * @see https://m3.material.io/foundations/content-design/navigation
  */
-export declare function TableOfContents({ items, className }: TableOfContentsProps): import("react/jsx-runtime").JSX.Element;
+export declare function TableOfContents({ items, className, scrollAreaProps, }: TableOfContentsProps): import("react/jsx-runtime").JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bug-on/md3-react",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Material Design 3 Expressive React components",
   "author": "Bug Ổn",
   "license": "MIT",