@usefragments/ui 1.0.0

package/src/components/Slider/Slider.contract.json

@@ -0,0 +1,248 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Slider",
+  "description": "Range input control for selecting a numeric value within a defined range. Supports labels, value display, and custom step intervals.",
+  "category": "forms",
+  "tags": [
+    "slider",
+    "range",
+    "input",
+    "number",
+    "control"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Slider/index.tsx",
+  "exportName": "Slider",
+  "propsSummary": [
+    "label: string",
+    "helperText: string",
+    "error: boolean (default: false)",
+    "value: number",
+    "defaultValue: number",
+    "onChange: function",
+    "onValueChange: function",
+    "min: number (default: 0)",
+    "max: number (default: 100)",
+    "step: number (default: 1)",
+    "showValue: boolean (default: false)",
+    "showValueOnDrag: boolean (default: false)",
+    "valueSuffix: string (default: )",
+    "disabled: boolean (default: false)",
+    "name: string",
+    "aria-label: string",
+    "aria-labelledby: string",
+    "aria-describedby: string",
+    "id: string"
+  ],
+  "props": {
+    "label": {
+      "type": "string",
+      "description": "Label text",
+      "required": false
+    },
+    "helperText": {
+      "type": "string",
+      "description": "Helper text shown below the slider",
+      "required": false
+    },
+    "error": {
+      "type": "boolean",
+      "description": "Show error styling",
+      "default": "false",
+      "required": false
+    },
+    "value": {
+      "type": "number",
+      "description": "Controlled value",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "number",
+      "description": "Default value for uncontrolled usage",
+      "required": false
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Called with new value when changed",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "description": "Alias for onChange (Radix convention): (value: number) => void",
+      "required": false
+    },
+    "min": {
+      "type": "number",
+      "description": "Minimum value",
+      "default": "0",
+      "required": false
+    },
+    "max": {
+      "type": "number",
+      "description": "Maximum value",
+      "default": "100",
+      "required": false
+    },
+    "step": {
+      "type": "number",
+      "description": "Step interval",
+      "default": "1",
+      "required": false
+    },
+    "showValue": {
+      "type": "boolean",
+      "description": "Display current value",
+      "default": "false",
+      "required": false
+    },
+    "showValueOnDrag": {
+      "type": "boolean",
+      "description": "Show current value in a floating bubble while dragging the thumb",
+      "default": "false",
+      "required": false
+    },
+    "valueSuffix": {
+      "type": "string",
+      "description": "Suffix after value (e.g., \"%\", \"px\")",
+      "default": "",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disable the slider",
+      "default": "false",
+      "required": false
+    },
+    "name": {
+      "type": "string",
+      "description": "",
+      "required": false
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "Accessible label when visible label is omitted",
+      "required": false
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "Accessible labelled-by relationship",
+      "required": false
+    },
+    "aria-describedby": {
+      "type": "string",
+      "description": "Accessible described-by relationship",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Selecting a value from a continuous range",
+      "Volume or brightness controls",
+      "Price range filters",
+      "Settings that benefit from visual feedback"
+    ],
+    "whenNot": [
+      "Precise numeric input (use Input type=\"number\")",
+      "Discrete options (use RadioGroup or Select)",
+      "Yes/no choices (use Switch)"
+    ],
+    "guidelines": [
+      "Always provide a label describing what the slider controls",
+      "Show the current value when precision matters",
+      "Use appropriate min/max values for the context",
+      "Consider step size for usability"
+    ],
+    "accessibility": [
+      "Label is associated with the slider",
+      "Keyboard accessible with arrow keys",
+      "Current value is announced to screen readers",
+      "Uses native slider semantics"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic slider with label",
+      "code": "<div style={{ width: '300px' }}>\n  <Slider label=\"Volume\" defaultValue={50} />\n</div>"
+    },
+    {
+      "name": "With Value Display",
+      "description": "Shows current value alongside the slider",
+      "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Brightness\"\n    defaultValue={75}\n    showValue\n    valueSuffix=\"%\"\n  />\n</div>"
+    },
+    {
+      "name": "Custom Range",
+      "description": "Custom min, max, and step values",
+      "code": "<div style={{ width: '300px', display: 'flex', flexDirection: 'column', gap: '16px' }}>\n  <Slider\n    label=\"Temperature\"\n    min={60}\n    max={80}\n    step={1}\n    defaultValue={72}\n    showValue\n    valueSuffix=\"°F\"\n  />\n  <Slider\n    label=\"Font Size\"\n    min={12}\n    max={32}\n    step={2}\n    defaultValue={16}\n    showValue\n    valueSuffix=\"px\"\n  />\n</div>"
+    },
+    {
+      "name": "Controlled",
+      "description": "Controlled slider with external state",
+      "code": "<ControlledSliderDemo />"
+    },
+    {
+      "name": "Drag Value Bubble",
+      "description": "Shows a floating value bubble while the thumb is being dragged",
+      "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Mix\"\n    defaultValue={40}\n    showValueOnDrag\n    valueSuffix=\"%\"\n  />\n</div>"
+    },
+    {
+      "name": "With Helper Text",
+      "description": "Slider with helper text guidance",
+      "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Quality\"\n    defaultValue={80}\n    showValue\n    valueSuffix=\"%\"\n    helperText=\"Higher quality increases file size\"\n  />\n</div>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Disabled slider",
+      "code": "<div style={{ width: '300px' }}>\n  <Slider\n    label=\"Locked Setting\"\n    defaultValue={30}\n    showValue\n    disabled\n  />\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Input",
+      "relationship": "alternative",
+      "note": "Use Input for precise numeric entry"
+    },
+    {
+      "component": "Progress",
+      "relationship": "sibling",
+      "note": "Similar visual, but Progress is read-only"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "value: number - controlled value",
+      "defaultValue: number - initial value",
+      "onChange: (value: number) => void - change handler (or onValueChange)",
+      "min/max: number - range bounds",
+      "step: number - increment size",
+      "label: string - field label",
+      "helperText: string - helper text below slider",
+      "error: boolean - error styling",
+      "showValue: boolean - display value",
+      "showValueOnDrag: boolean - show value bubble during drag",
+      "valueSuffix: string - unit suffix"
+    ],
+    "a11yRules": [
+      "A11Y_LABEL_REQUIRED",
+      "A11Y_KEYBOARD_ACCESSIBLE",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:04.141Z"
+  }
+}

package/src/components/Slider/Slider.module.scss

@@ -0,0 +1,147 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// Local component tokens
+$fui-slider-track-height: 4px !default;
+$fui-slider-thumb-size: $fui-target-size-min !default;
+
+.wrapper {
+  display: flex;
+  flex-direction: column;
+}
+
+.header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: var(--fui-space-1, $fui-space-1);
+}
+
+.label {
+  @include label-text;
+}
+
+.value {
+  font-family: var(--fui-font-mono, $fui-font-mono);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  min-width: 60px;
+  text-align: right;
+}
+
+.root {
+  width: 100%;
+}
+
+.control {
+  display: flex;
+  align-items: center;
+  width: 100%;
+}
+
+.track {
+  position: relative;
+  height: var(--fui-slider-track-height, $fui-slider-track-height);
+  width: 100%;
+  background-color: var(--fui-form-group-bg, $fui-bg-secondary);
+  box-shadow: inset 0 0 0 1px var(--fui-form-group-border, $fui-border);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  cursor: pointer;
+
+  &[data-disabled] {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.indicator {
+  position: absolute;
+  height: 100%;
+  background-color: var(--fui-field-selection-border, $fui-color-accent);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+}
+
+.thumb {
+  @include min-target-size;
+
+  position: relative;
+  width: var(--fui-slider-thumb-size, $fui-slider-thumb-size);
+  height: var(--fui-slider-thumb-size, $fui-slider-thumb-size);
+  background-color: var(--fui-bg-primary, $fui-bg-primary);
+  border: 1px solid var(--fui-field-selection-border, $fui-color-accent);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
+  cursor: grab;
+  transition:
+    border-color var(--fui-transition-fast, $fui-transition-fast),
+    box-shadow var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    border-color: color-mix(in srgb, var(--fui-color-accent, $fui-color-accent) 58%, transparent);
+  }
+
+  &:active {
+    cursor: grabbing;
+    box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+
+  &[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+}
+
+.helper {
+  @include helper-text;
+  margin-top: var(--fui-space-1, $fui-space-1);
+}
+
+.helperError {
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+.dragValueBubble {
+  position: absolute;
+  left: 50%;
+  bottom: calc(100% + var(--fui-space-2, $fui-space-2));
+  transform: translateX(-50%);
+  pointer-events: none;
+  white-space: nowrap;
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  background: var(--fui-form-group-bg, $fui-bg-secondary);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  border: 1px solid var(--fui-form-group-border, $fui-border);
+  font-family: var(--fui-font-mono, $fui-font-mono);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  line-height: 1;
+  box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .track {
+    border: 1px solid var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .thumb {
+    border-width: 3px;
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .thumb {
+    transition: none;
+  }
+}

package/src/components/Slider/Slider.stories.tsx

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Slider } from '.';
+
+/**
+ * Slider is a range input control for selecting a numeric value within a
+ * defined range. It supports a label, value display, a custom step interval,
+ * and a value suffix for units.
+ */
+const meta = {
+  title: 'Forms/Slider',
+  component: Slider,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Range input control for selecting a numeric value within a defined range.',
+      },
+    },
+  },
+  argTypes: {
+    showValue: { control: 'boolean', description: 'Display current value' },
+    showValueOnDrag: {
+      control: 'boolean',
+      description: 'Show a floating value bubble while dragging',
+    },
+    error: { control: 'boolean', description: 'Show error styling' },
+    disabled: { control: 'boolean', description: 'Disable the slider' },
+  },
+  args: { label: 'Volume', defaultValue: 50, min: 0, max: 100, step: 1 },
+  render: (args) => (
+    <div style={{ width: 300 }}>
+      <Slider {...args} />
+    </div>
+  ),
+} satisfies Meta<typeof Slider>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { label: 'Volume', defaultValue: 50 },
+};
+
+export const WithValue: Story = {
+  args: { label: 'Brightness', defaultValue: 75, showValue: true, valueSuffix: '%' },
+};
+
+export const CustomRange: Story = {
+  args: {
+    label: 'Temperature',
+    min: 60,
+    max: 80,
+    step: 1,
+    defaultValue: 72,
+    showValue: true,
+    valueSuffix: '°F',
+  },
+};
+
+export const WithHelperText: Story = {
+  args: {
+    label: 'Quality',
+    defaultValue: 80,
+    showValue: true,
+    valueSuffix: '%',
+    helperText: 'Higher quality increases file size',
+  },
+};
+
+export const Disabled: Story = {
+  args: { label: 'Locked setting', defaultValue: 30, showValue: true, disabled: true },
+};

package/src/components/Slider/index.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import * as React from "react";
+import { Field } from "@base-ui/react/field";
+import { Slider as BaseSlider } from "@base-ui/react/slider";
+import styles from "./Slider.module.scss";
+
+/**
+ * Range slider for selecting a numeric value within a defined range.
+ * @see https://usefragments.com/components/slider
+ */
+export interface SliderProps extends Omit<
+  React.HTMLAttributes<HTMLDivElement>,
+  "onChange" | "defaultValue"
+> {
+  /** Visible label text */
+  label?: string;
+  /** Helper text shown below the slider */
+  helperText?: string;
+  /** Show error styling */
+  error?: boolean;
+  /** Controlled value */
+  value?: number;
+  /** Default value for uncontrolled usage */
+  defaultValue?: number;
+  /** Called when the slider value changes */
+  onChange?: (value: number) => void;
+  /** Alias for onChange (Radix convention) */
+  onValueChange?: (value: number) => void;
+  min?: number;
+  max?: number;
+  step?: number;
+  showValue?: boolean;
+  /** Show a value bubble above the thumb while dragging */
+  showValueOnDrag?: boolean;
+  valueSuffix?: string;
+  disabled?: boolean;
+  name?: string;
+  /** ID of the form that owns the hidden slider input */
+  form?: string;
+  /** Callback when the user commits a slider value */
+  onValueCommitted?: (value: number) => void;
+  /** Larger step used for Page Up/Page Down and shift-arrow keyboard input */
+  largeStep?: number;
+  /** How the thumb is aligned at the minimum and maximum edges */
+  thumbAlignment?: "center" | "edge" | "edge-client-only";
+  /** Accessible label when visible label is omitted */
+  "aria-label"?: string;
+  /** Accessible labelled-by relationship */
+  "aria-labelledby"?: string;
+  /** Accessible described-by relationship */
+  "aria-describedby"?: string;
+}
+
+const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(function Slider(
+  {
+    label,
+    helperText,
+    error = false,
+    value,
+    defaultValue,
+    onChange,
+    onValueChange,
+    min = 0,
+    max = 100,
+    step = 1,
+    showValue = false,
+    showValueOnDrag = false,
+    valueSuffix = "",
+    disabled = false,
+    className,
+    name,
+    form,
+    onValueCommitted,
+    largeStep,
+    thumbAlignment,
+    id,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledBy,
+    "aria-describedby": ariaDescribedBy,
+    ...htmlProps
+  },
+  ref
+) {
+  // For controlled component, use value; otherwise track internal state for display
+  const [internalValue, setInternalValue] = React.useState(defaultValue ?? min);
+  const [isDragging, setIsDragging] = React.useState(false);
+  const displayValue = value !== undefined ? value : internalValue;
+
+  const resolvedOnChange = onChange ?? onValueChange;
+  const handleChange = (newValue: number | number[]) => {
+    const val = Array.isArray(newValue) ? newValue[0] : newValue;
+    setInternalValue(val);
+    resolvedOnChange?.(val);
+  };
+
+  const handleValueCommitted = (newValue: number | number[]) => {
+    const val = Array.isArray(newValue) ? newValue[0] : newValue;
+    onValueCommitted?.(val);
+  };
+
+  const handleDragStart = () => {
+    if (!disabled && showValueOnDrag) {
+      setIsDragging(true);
+    }
+  };
+
+  React.useEffect(() => {
+    if (!isDragging) return;
+
+    const handlePointerEnd = () => setIsDragging(false);
+    window.addEventListener("pointerup", handlePointerEnd);
+    window.addEventListener("pointercancel", handlePointerEnd);
+
+    return () => {
+      window.removeEventListener("pointerup", handlePointerEnd);
+      window.removeEventListener("pointercancel", handlePointerEnd);
+    };
+  }, [isDragging]);
+
+  React.useEffect(() => {
+    if (disabled && isDragging) {
+      setIsDragging(false);
+    }
+  }, [disabled, isDragging]);
+
+  const helperClasses = [styles.helper, error && styles.helperError].filter(Boolean).join(" ");
+
+  return (
+    <Field.Root
+      {...htmlProps}
+      disabled={disabled}
+      invalid={error}
+      className={[styles.wrapper, className].filter(Boolean).join(" ")}
+    >
+      <BaseSlider.Root
+        ref={ref}
+        value={value !== undefined ? [value] : undefined}
+        defaultValue={defaultValue !== undefined ? [defaultValue] : undefined}
+        onValueChange={handleChange}
+        min={min}
+        max={max}
+        step={step}
+        disabled={disabled}
+        name={name}
+        form={form}
+        onValueCommitted={handleValueCommitted}
+        largeStep={largeStep}
+        thumbAlignment={thumbAlignment}
+        id={id}
+        aria-label={ariaLabel || (label ? undefined : "Slider")}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={ariaDescribedBy}
+        className={styles.root}
+        onPointerDownCapture={handleDragStart}
+      >
+        {(label || showValue) && (
+          <div className={styles.header}>
+            {label && <BaseSlider.Label className={styles.label}>{label}</BaseSlider.Label>}
+            {showValue && (
+              <span className={styles.value}>
+                {displayValue}
+                {valueSuffix}
+              </span>
+            )}
+          </div>
+        )}
+        <BaseSlider.Control className={styles.control}>
+          <BaseSlider.Track className={styles.track}>
+            <BaseSlider.Indicator className={styles.indicator} />
+            <BaseSlider.Thumb className={styles.thumb}>
+              {showValueOnDrag && isDragging && (
+                <span className={styles.dragValueBubble} aria-hidden="true">
+                  {displayValue}
+                  {valueSuffix}
+                </span>
+              )}
+            </BaseSlider.Thumb>
+          </BaseSlider.Track>
+        </BaseSlider.Control>
+      </BaseSlider.Root>
+      {helperText && <Field.Description className={helperClasses}>{helperText}</Field.Description>}
+    </Field.Root>
+  );
+});
+
+export const Slider = Object.assign(SliderRoot, {
+  Root: SliderRoot,
+});