@bug-on/m3-expressive 1.0.0

package/dist/text-field-eAIpz9z1.d.mts

@@ -0,0 +1,1038 @@
+import * as React from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+
+/**
+ * @file checkbox.tsx
+ * MD3 Expressive Checkbox — 2-state and tri-state support.
+ * Spec: https://m3.material.io/components/checkbox/overview
+ */
+
+/**
+ * Tri-state value: `"unchecked"` | `"checked"` | `"indeterminate"`.
+ */
+type CheckboxState = "unchecked" | "checked" | "indeterminate";
+/**
+ * Props for `Checkbox`. Supports boolean (`checked`/`onCheckedChange`)
+ * and tri-state (`state`/`onStateChange`) modes.
+ */
+interface CheckboxProps {
+    /** Controlled checked value (2-state mode). */
+    checked?: boolean;
+    /** Initial value for uncontrolled mode. @default false */
+    defaultChecked?: boolean;
+    /** Forces indeterminate rendering regardless of `checked`. */
+    indeterminate?: boolean;
+    /** Fired on checked change (simple mode). Not called when disabled. */
+    onCheckedChange?: (checked: boolean) => void;
+    /** Controlled tri-state value. Takes priority over `checked`/`indeterminate`. */
+    state?: CheckboxState;
+    /** Fired on tri-state change. Cycles: unchecked → checked → indeterminate. */
+    onStateChange?: (state: CheckboxState) => void;
+    /** Disables interaction and applies 0.38 opacity. */
+    disabled?: boolean;
+    /** Error state — changes colors to `m3-error` and sets `aria-invalid`. */
+    error?: boolean;
+    /** Adjacent label text. Wraps checkbox + span in `<label>`. */
+    label?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-required"?: boolean;
+    /** Passed to the hidden `<input>` for form submission. */
+    name?: string;
+    /** Passed to the hidden `<input>` for form submission. */
+    value?: string;
+    /** ID for the hidden `<input>`. Auto-generated when `label` is set. */
+    id?: string;
+    /** Extra class names on the outermost wrapper. */
+    className?: string;
+    /** Ref pointing to the hidden `<input type="checkbox">`. */
+    ref?: React.Ref<HTMLInputElement>;
+}
+/**
+ * `TriStateCheckbox` props — requires `state` + `onStateChange`.
+ */
+interface TriStateCheckboxProps extends Omit<CheckboxProps, "checked" | "defaultChecked" | "onCheckedChange"> {
+    state: CheckboxState;
+    onStateChange: (state: CheckboxState) => void;
+}
+/**
+ * MD3 Expressive Checkbox component.
+ *
+ * Supports 2-state and tri-state patterns. Fully animated per MD3 spec:
+ * checkmark draw, indeterminate dash morph, container fill, state layer, and ripple.
+ *
+ * @example
+ * ```tsx
+ * <Checkbox checked={isChecked} onCheckedChange={setIsChecked} label="Accept terms" />
+ * <Checkbox state={parentState} onStateChange={setParentState} label="Select all" />
+ * <Checkbox error label="Required field" aria-describedby="err-msg" />
+ * ```
+ * @see https://m3.material.io/components/checkbox/overview
+ */
+declare const Checkbox: React.NamedExoticComponent<Omit<CheckboxProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+/**
+ * MD3 Expressive Tri-State Checkbox.
+ *
+ * Convenience wrapper around `Checkbox` that enforces `state` + `onStateChange`.
+ * Ideal for parent-child selection patterns.
+ *
+ * @example
+ * ```tsx
+ * <TriStateCheckbox state={parentState} onStateChange={setParentState} label="Select all" />
+ * ```
+ */
+declare const TriStateCheckbox: React.NamedExoticComponent<Omit<TriStateCheckboxProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+
+declare const chipVariants: (props?: ({
+    variant?: "input" | "filter" | "assist" | "suggestion" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface ChipProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+    /**
+     * Chip variant.
+     * - `assist`     → Smart/automated actions. Flat by default, can be elevated.
+     * - `filter`     → Toggleable tag/filter. Shows animated checkmark when selected.
+     * - `input`      → Entity representation (tag, contact). Has optional avatar + remove button.
+     * - `suggestion` → Contextual suggestions. Like assist, flat by default, can be elevated.
+     * @default 'assist'
+     */
+    variant?: VariantProps<typeof chipVariants>["variant"];
+    /**
+     * Renders with elevation shadow (Level 1) and fills background with `surface-container-low`.
+     * Applicable to `assist`, `filter` (unselected), and `suggestion` variants.
+     * Source: AssistChipTokens.ElevatedContainerColor / SuggestionChipTokens.ElevatedContainerColor
+     */
+    elevated?: boolean;
+    /**
+     * Toggle/selection state.
+     * - `filter`:  selected → bg `secondary-container`, animated checkmark appears.
+     * - `input`:   selected → bg `secondary-container`.
+     * Used for `role="checkbox"` (filter) / `aria-pressed` (input).
+     */
+    selected?: boolean;
+    /**
+     * Disables the chip. Applies:
+     * - `pointer-events-none` – no mouse/touch interaction
+     * - `opacity-[0.38]`      – DisabledLabelTextOpacity (0.38) per MD3 tokens
+     * - `aria-disabled="true"`
+     * - `tabIndex={-1}`
+     */
+    disabled?: boolean;
+    /**
+     * Visible label. Required. Can be a string or ReactNode.
+     */
+    label: React.ReactNode;
+    /**
+     * Optional leading icon element (18×18px recommended).
+     * For `filter` chips with `selected=true`, this is replaced by an animated checkmark.
+     * For `assist`/`suggestion`: icon color → `primary`
+     * For `input` (unselected): icon color → `on-surface-variant`
+     */
+    leadingIcon?: React.ReactNode;
+    /**
+     * Optional trailing icon element (18×18px recommended).
+     * Color: `on-surface-variant` (unselected) / `on-secondary-container` (selected).
+     */
+    trailingIcon?: React.ReactNode;
+    /**
+     * Avatar element for `input` chips. Takes priority over `leadingIcon`.
+     * Rendered as a 24×24px circle (InputChipTokens: AvatarSize = 24.dp, AvatarShape = CornerFull).
+     */
+    avatar?: React.ReactNode;
+    /**
+     * Callback when the trailing remove (×) button is activated on `input` chips.
+     * When provided, a dedicated tabbable close button with `aria-label="Remove {label}"` is rendered.
+     */
+    onRemove?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+}
+/**
+ * MD3 Expressive Chip — 4-variant interactive tag component.
+ *
+ * @remarks
+ * - `filter` chips accept `selected` and render an animated checkmark.
+ * - `input` chips accept `onRemove` to render a compound close button.
+ * - `elevated` is supported on `assist`, `filter` (unselected), and `suggestion`.
+ * - Fully accessible: `role="checkbox"` for filter, `role="group"` for compound chips.
+ *
+ * @example
+ * ```tsx
+ * // Assist chip
+ * <Chip variant="assist" label="Share" onClick={share} />
+ *
+ * // Filter chip
+ * <Chip variant="filter" label="Unread" selected={showUnread} onClick={toggle} />
+ *
+ * // Input chip with remove
+ * <Chip variant="input" label="React" onRemove={() => removeTag("React")} />
+ * ```
+ *
+ * @see https://m3.material.io/components/chips/overview
+ */
+declare const Chip: React.NamedExoticComponent<ChipProps & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * @file radio-button.tsx
+ * MD3 Expressive RadioButton — single-select with RadioGroup support.
+ * Spec: https://m3.material.io/components/radio-button/overview
+ */
+
+/**
+ * Color variant for `RadioButton`.
+ * - `"primary"` — standard selection (default)
+ * - `"error"` — error/invalid state
+ */
+type RadioButtonColors = "primary" | "error";
+/** Props for `RadioButton`. */
+interface RadioButtonProps {
+    /** Whether this radio is selected. */
+    selected?: boolean;
+    /** Initial selected state (uncontrolled). @default false */
+    defaultSelected?: boolean;
+    /** Called when user clicks. Pass `null` to disable interaction. */
+    onClick?: (() => void) | null;
+    /** Disables the radio — visual disabled state + no interaction. @default false */
+    disabled?: boolean;
+    /** Color variant. @default "primary" */
+    color?: RadioButtonColors;
+    /** Error state — changes colors to `m3-error`. @default false */
+    error?: boolean;
+    /** Adjacent label text. Renders a `<label>` wrapper. */
+    label?: string;
+    /** Value used for form submission. */
+    value?: string;
+    /** Name for grouping (used in RadioGroup context). */
+    name?: string;
+    /** ID for the hidden `<input>`. Auto-generated when `label` is set. */
+    id?: string;
+    /** Extra class names on the outermost wrapper. */
+    className?: string;
+    /** ARIA label for the radio when no visible label exists. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    /** Whether the radio is required for form submission. */
+    required?: boolean;
+    /** Ref to the hidden `<input type="radio">`. */
+    ref?: React.Ref<HTMLInputElement>;
+}
+/** Props for `RadioGroup`. */
+interface RadioGroupProps {
+    /** The name attribute shared across all child RadioButtons. */
+    name: string;
+    /** The currently selected value (controlled). */
+    value?: string;
+    /** Default value (uncontrolled). */
+    defaultValue?: string;
+    /** Called when selection changes. */
+    onValueChange?: (value: string) => void;
+    /** Disables all radio buttons in the group. */
+    disabled?: boolean;
+    /** Error state for the entire group. */
+    error?: boolean;
+    /** Label for the group (renders as visually hidden or visible heading). */
+    label?: string;
+    /** ID of an external element that labels this group. */
+    "aria-labelledby"?: string;
+    /** Direction of layout. @default "vertical" */
+    orientation?: "horizontal" | "vertical";
+    /** Whether at least one radio in the group must be selected. */
+    required?: boolean;
+    children: React.ReactNode;
+    className?: string;
+}
+/**
+ * MD3 Expressive RadioButton component.
+ *
+ * Single-select control. Supports standalone (controlled/uncontrolled) and
+ * `RadioGroup` context. Animated per MD3 spec: inner dot radius morph,
+ * outer ring color transition, state layer, and ripple.
+ *
+ * @example
+ * ```tsx
+ * <RadioButton selected={isSelected} onClick={() => setSelected(true)} label="Option A" />
+ *
+ * <RadioGroup name="plan" value={plan} onValueChange={setPlan}>
+ *   <RadioButton value="free" label="Free" />
+ *   <RadioButton value="pro" label="Pro" />
+ * </RadioGroup>
+ * ```
+ * @see https://m3.material.io/components/radio-button/overview
+ */
+declare const RadioButton: React.NamedExoticComponent<Omit<RadioButtonProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+/**
+ * MD3 Expressive RadioGroup component.
+ *
+ * Groups multiple `RadioButton` components under a shared `name` with keyboard
+ * navigation (Arrow keys with wrapping) and ARIA `radiogroup` semantics.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup name="theme" value={theme} onValueChange={setTheme} label="Theme">
+ *   <RadioButton value="light" label="Light" />
+ *   <RadioButton value="dark" label="Dark" />
+ *   <RadioButton value="system" label="System" />
+ * </RadioGroup>
+ * ```
+ * @see https://m3.material.io/components/radio-button/overview
+ */
+declare const RadioGroup: React.NamedExoticComponent<RadioGroupProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * @file slider.types.ts
+ * MD3 Expressive Slider — TypeScript prop definitions.
+ * Spec: https://m3.material.io/components/sliders/overview
+ * Reference: docs/m3/sliders/Slider.kt
+ */
+
+/** Track size variants mapping to physical px values. */
+type SliderTrackSize = "xs" | "s" | "m" | "l" | "xl";
+type SliderVariant = "primary" | "secondary" | "tertiary" | "error";
+type SliderTrackShape = "md3" | "full" | number;
+/** Slider layout direction. */
+type SliderOrientation = "horizontal" | "vertical";
+/**
+ * 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 />
+ * ```
+ */
+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])}
+ * />
+ * ```
+ */
+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 `<SliderThumb>`.
+ * @internal
+ */
+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;
+}
+
+/**
+ * @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
+ */
+
+/**
+ * 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
+ */
+declare const RangeSlider: React.NamedExoticComponent<RangeSliderProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * @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
+ */
+
+/**
+ * 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
+ */
+declare const Slider: React.NamedExoticComponent<SliderProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * @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.
+ */
+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.
+ */
+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)";
+};
+
+/**
+ * @file switch.types.ts
+ * MD3 Expressive Switch — TypeScript prop definitions.
+ * Spec: https://m3.material.io/components/switch/overview
+ */
+
+/**
+ * Props for the `Switch` component.
+ *
+ * @example
+ * ```tsx
+ * <Switch checked={isOn} onCheckedChange={setIsOn} label="Wi-Fi" />
+ * ```
+ */
+interface SwitchProps {
+    /** Controlled checked (on) state. */
+    checked: boolean;
+    /** Called when the switch is toggled. Not called when disabled. */
+    onCheckedChange: (checked: boolean) => void;
+    /** Disables interaction and applies disabled visual state. @default false */
+    disabled?: boolean;
+    /**
+     * Optional icon content rendered inside the thumb.
+     * Expected to measure 16dp (SwitchTokens.iconSize).
+     */
+    thumbContent?: React.ReactNode;
+    /**
+     * When true, shows thumb icons in both selected and unselected states.
+     * Requires `thumbContent` to be provided.
+     * @default false
+     */
+    icons?: boolean;
+    /**
+     * When true, shows the icon only in the selected/checked state.
+     * Requires `thumbContent` to be provided.
+     * @default false
+     */
+    showOnlySelectedIcon?: boolean;
+    /**
+     * Visible label text rendered adjacent to the switch.
+     * When provided, wraps the switch in a `<label>` for accessibility.
+     */
+    label?: string;
+    /**
+     * Overrides the accessible name. Used when no visible `label` is provided.
+     * Maps to the `aria-label` attribute.
+     */
+    ariaLabel?: string;
+    /** Additional CSS class names applied to the outermost wrapper. */
+    className?: string;
+    /** Override track background color when checked. Defaults to MD3 primary. */
+    checkedTrackColor?: string;
+    /** Override track background color when unchecked. Defaults to MD3 surface-container-highest. */
+    uncheckedTrackColor?: string;
+    /** Override thumb color when checked. Defaults to MD3 on-primary. */
+    checkedThumbColor?: string;
+    /** Override thumb color when unchecked. Defaults to MD3 outline. */
+    uncheckedThumbColor?: string;
+}
+
+/**
+ * @file switch.tsx
+ * MD3 Expressive Switch — ARIA switch pattern with Framer Motion animations.
+ * Spec: https://m3.material.io/components/switch/overview
+ *
+ * Key decisions:
+ * - Uses `<button role="switch">` (no <input>) per MD3 accessibility spec
+ * - Framer Motion for ALL animations (thumb x, size morph, state layer, icons)
+ * - Hover state via useState (required for Framer Motion color animate)
+ * - Disabled colors via rgba() literals (color-mix() not animatable by FM)
+ */
+
+/**
+ * MD3 Expressive Switch component.
+ *
+ * Toggles a single item on or off. Implements the ARIA switch pattern
+ * (`role="switch"`) without `<input>`. Fully animated per MD3 spec:
+ * thumb translation, size morph (16→24→28px), state layer, and icon cross-fade.
+ *
+ * @example
+ * ```tsx
+ * <Switch checked={isOn} onCheckedChange={setIsOn} label="Wi-Fi" />
+ * <Switch checked={isOn} onCheckedChange={setIsOn} icons thumbContent={<CheckIcon />} />
+ * <Switch checked={isOn} onCheckedChange={setIsOn} disabled />
+ * ```
+ *
+ * @see https://m3.material.io/components/switch/overview
+ */
+declare const Switch: React.NamedExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * @file switch.tokens.ts
+ * MD3 Expressive Switch — Design tokens ported from SwitchTokens.kt.
+ * All dimensional values are in px (dp equivalent for web).
+ * @see docs/m3/switch/SwitchTokens.kt
+ */
+/**
+ * Design tokens for the MD3 Expressive Switch component.
+ *
+ * Maps directly from `SwitchTokens.kt` (v0_210) to CSS/JS values.
+ * Use these as the single source of truth for sizing and opacity.
+ *
+ * Color tokens are NOT included here — they reference CSS custom properties
+ * from the project's MD3 theme system (`--md-sys-color-*`).
+ */
+declare const SwitchTokens: {
+    /** SwitchTokens.TrackWidth = 52dp */
+    readonly trackWidth: 52;
+    /** SwitchTokens.TrackHeight = 32dp */
+    readonly trackHeight: 32;
+    /** SwitchTokens.TrackOutlineWidth = 2dp */
+    readonly trackOutlineWidth: 2;
+    /** SwitchTokens.SelectedHandleWidth/Height = 24dp */
+    readonly selectedHandleSize: 24;
+    /** SwitchTokens.UnselectedHandleWidth/Height = 16dp */
+    readonly unselectedHandleSize: 16;
+    /** SwitchTokens.IconHandleWidth/Height = 24dp (when thumb has icon content) */
+    readonly iconHandleSize: 24;
+    /** SwitchTokens.PressedHandleWidth/Height = 28dp */
+    readonly pressedHandleSize: 28;
+    /** SwitchTokens.StateLayerSize = 40dp */
+    readonly stateLayerSize: 40;
+    /** SwitchTokens.SelectedIconSize / UnselectedIconSize = 16dp */
+    readonly iconSize: 16;
+    /** SwitchTokens.DisabledTrackOpacity = 0.12 */
+    readonly disabledTrackOpacity: 0.12;
+    /** SwitchTokens.DisabledSelectedHandleOpacity = 1.0 */
+    readonly disabledSelectedHandleOpacity: 1;
+    /** SwitchTokens.DisabledUnselectedHandleOpacity = 0.38 */
+    readonly disabledUnselectedHandleOpacity: 0.38;
+    /** SwitchTokens.DisabledSelectedIconOpacity = 0.38 */
+    readonly disabledSelectedIconOpacity: 0.38;
+    /** SwitchTokens.DisabledUnselectedIconOpacity = 0.38 */
+    readonly disabledUnselectedIconOpacity: 0.38;
+};
+/**
+ * CSS custom property references for Switch colors.
+ * These map to the project's `--md-sys-color-*` tokens in `colors.css`.
+ *
+ * DO NOT hardcode hex values — always use these references so the
+ * component automatically adapts to light/dark theme switching.
+ */
+declare const SwitchColors: {
+    readonly checkedTrack: "var(--md-sys-color-primary)";
+    readonly uncheckedTrack: "var(--md-sys-color-surface-container-highest)";
+    readonly uncheckedTrackOutline: "var(--md-sys-color-outline)";
+    readonly checkedThumb: "var(--md-sys-color-on-primary)";
+    readonly uncheckedThumb: "var(--md-sys-color-outline)";
+    readonly hoverCheckedThumb: "var(--md-sys-color-primary-container)";
+    readonly hoverUncheckedThumb: "var(--md-sys-color-on-surface-variant)";
+    readonly disabledCheckedThumb: "var(--md-sys-color-surface)";
+    readonly checkedIcon: "var(--md-sys-color-on-primary-container)";
+    readonly uncheckedIcon: "var(--md-sys-color-surface-container-highest)";
+    readonly checkedStateLayer: "var(--md-sys-color-primary)";
+    readonly uncheckedStateLayer: "var(--md-sys-color-on-surface)";
+    readonly focusIndicator: "var(--md-sys-color-secondary)";
+};
+
+/**
+ * @file text-field.types.ts
+ * TypeScript interfaces and types for TextField MD3 Expressive component.
+ * @see https://m3.material.io/components/text-fields/overview
+ */
+
+type TextFieldVariant = "filled" | "outlined";
+type TextFieldInputType = "text" | "email" | "number" | "password" | "search" | "tel" | "url" | "textarea";
+type TextFieldTrailingIconMode = "none" | "clear" | "password-toggle" | "custom";
+/**
+ * Imperative handle exposed via forwardRef.
+ * Allows parent components to programmatically control the text field.
+ */
+interface TextFieldHandle {
+    /** Focuses the input element. */
+    focus(): void;
+    /** Blurs the input element. */
+    blur(): void;
+    /** Selects all text in the input. */
+    select(): void;
+    /** Clears the current value and fires onChange with empty string. */
+    clear(): void;
+    /** Sets a custom validation message on the native input. */
+    setCustomValidity(message: string): void;
+    /** Returns true if the input is valid. Does not show validation UI. */
+    checkValidity(): boolean;
+    /** Returns true if the input is valid. Shows validation UI if invalid. */
+    reportValidity(): boolean;
+    /** Returns the current value string. */
+    getValue(): string;
+    /** Returns the underlying input or textarea element. */
+    getInputElement(): HTMLInputElement | HTMLTextAreaElement | null;
+}
+interface TextFieldProps {
+    /** Filled or outlined variant. @default 'filled' */
+    variant?: TextFieldVariant;
+    /** Floating label text. Also used as accessible name when no aria-label is set. */
+    label?: string;
+    /** Controlled value. Use with onChange for controlled mode. */
+    value?: string;
+    /** Initial value for uncontrolled mode. */
+    defaultValue?: string;
+    /** Fires when value changes. Receives new value string and native event. */
+    onChange?: (value: string, event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+    /** Input type. Use 'textarea' for multi-line input. @default 'text' */
+    type?: TextFieldInputType;
+    /** Placeholder text — shown only when no label OR label is floated. */
+    placeholder?: string;
+    name?: string;
+    id?: string;
+    autoComplete?: string;
+    inputMode?: React.HTMLAttributes<HTMLInputElement>["inputMode"];
+    /** Number of rows for textarea type. @default 2 */
+    rows?: number;
+    /** Number of columns for textarea type. @default 20 */
+    cols?: number;
+    /** Whether the textarea should automatically resize to fit its content. @default false */
+    autoResize?: boolean;
+    /** Maximum number of rows when autoResize is true. */
+    maxRows?: number;
+    /** CSS direction override for input text. */
+    textDirection?: "ltr" | "rtl" | "";
+    /** Marks field as required. Shows asterisk on label. */
+    required?: boolean;
+    /** Hides the asterisk even when required=true. */
+    noAsterisk?: boolean;
+    /** Manual error override — forces error visual state. */
+    error?: boolean;
+    /** Error message shown below the field (replaces supportingText). */
+    errorText?: string;
+    minLength?: number;
+    /** When set, enables character counter display. */
+    maxLength?: number;
+    min?: string;
+    max?: string;
+    step?: string;
+    pattern?: string;
+    /** For type="email" — allows multiple email addresses. */
+    multiple?: boolean;
+    /** Helper text shown below the field. Replaced by errorText when in error state. */
+    supportingText?: string;
+    /** Text displayed before the input value (e.g., "$"). */
+    prefixText?: string;
+    /** Text displayed after the input value (e.g., ".00"). */
+    suffixText?: string;
+    /** Icon node for the leading slot. Should be 24×24px. */
+    leadingIcon?: React.ReactNode;
+    /** Custom trailing icon node. Used when trailingIconMode='custom'. */
+    trailingIcon?: React.ReactNode;
+    /**
+     * Built-in trailing icon behavior.
+     * - 'none' — no trailing icon
+     * - 'clear' — ✕ button, clears value when clicked
+     * - 'password-toggle' — eye icon, toggles password visibility
+     * - 'custom' — uses trailingIcon prop
+     * @default 'none'
+     */
+    trailingIconMode?: TextFieldTrailingIconMode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    /** Hides spinner arrows on type="number". */
+    noSpinner?: boolean;
+    form?: string;
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    "aria-labelledby"?: string;
+    /** Extra class applied to the root wrapper element. */
+    className?: string;
+    /** Makes the component fill its container width. */
+    fullWidth?: boolean;
+    /** Dense variant — reduced height (48px instead of 56px). */
+    dense?: boolean;
+    onFocus?: React.FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+    onBlur?: React.FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+    onKeyDown?: React.KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+    onKeyUp?: React.KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+    ref?: React.Ref<TextFieldHandle>;
+    /**
+     * Controls when the scrollbars are visible when type="textarea".
+     * - `hover`: Show on hover (default)
+     * - `scroll`: Show only while scrolling
+     * - `always`: Always visible
+     * - `none`: Never visible
+     */
+    scrollAreaType?: "hover" | "scroll" | "always" | "none";
+}
+
+/**
+ * @file text-field.tsx
+ * MD3 Expressive TextField — Filled & Outlined variants.
+ *
+ * Features:
+ * - Floating label animation (Framer Motion)
+ * - Filled (active indicator) and Outlined (notch border) variants
+ * - Controlled & uncontrolled value handling
+ * - Built-in clear button, password toggle
+ * - Prefix / suffix text
+ * - Supporting text, error text, character counter
+ * - Leading & trailing icon slots
+ * - Textarea support
+ * - Native form validation + imperative handle
+ * - Full WCAG AA accessibility
+ * - prefers-reduced-motion support
+ *
+ * @see https://m3.material.io/components/text-fields/overview
+ */
+
+/**
+ * MD3 Expressive TextField.
+ *
+ * Supports `filled` and `outlined` variants, floating label animation,
+ * prefix/suffix, leading/trailing icons, supporting text, character counter,
+ * textarea mode, clear button, password toggle, and native form validation.
+ *
+ * @example
+ * ```tsx
+ * // Filled (default)
+ * <TextField label="Email" type="email" />
+ *
+ * // Outlined with error
+ * <TextField variant="outlined" label="Username" error errorText="Already taken" />
+ *
+ * // With clear button
+ * <TextField label="Search" trailingIconMode="clear" />
+ *
+ * // Password with toggle
+ * <TextField label="Password" type="password" trailingIconMode="password-toggle" />
+ *
+ * // With character counter
+ * <TextField label="Bio" maxLength={140} supportingText="Describe yourself" />
+ * ```
+ *
+ * @see https://m3.material.io/components/text-fields/overview
+ */
+declare const TextField: React.NamedExoticComponent<Omit<TextFieldProps, "ref"> & React.RefAttributes<TextFieldHandle>>;
+
+export { type TriStateCheckboxProps as A, type SliderThumbProps as B, Checkbox as C, RadioButton as R, Slider as S, TextField as T, type CheckboxProps as a, type CheckboxState as b, Chip as c, type ChipProps as d, type RadioButtonColors as e, type RadioButtonProps as f, RadioGroup as g, type RadioGroupProps as h, RangeSlider as i, type RangeSliderProps as j, SliderColors as k, type SliderOrientation as l, type SliderProps as m, SliderTokens as n, type SliderTrackSize as o, type SliderVariant as p, Switch as q, SwitchColors as r, type SwitchProps as s, SwitchTokens as t, type TextFieldHandle as u, type TextFieldInputType as v, type TextFieldProps as w, type TextFieldTrailingIconMode as x, type TextFieldVariant as y, TriStateCheckbox as z };