@varialkit/slider 0.1.1

package/src/Slider.tsx

@@ -0,0 +1,574 @@
+import React, { forwardRef, useCallback, useMemo, useRef, useState } from "react";
+import { Tooltip } from "../../tooltip/src/Tooltip";
+import type { SliderOrientation, SliderProps, SliderSize, SliderType, SliderValue } from "./Slider.types";
+import "./Slider.scss";
+
+type SliderThumb = "lower" | "upper";
+
+const sizeAliasMap: Record<SliderSize, "small" | "medium" | "large" | "xlarge"> = {
+  sm: "small",
+  md: "medium",
+  lg: "large",
+  xl: "xlarge",
+  small: "small",
+  medium: "medium",
+  large: "large",
+  xlarge: "xlarge",
+};
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(max, Math.max(min, value));
+
+const roundToStep = (value: number, step: number, min: number) => {
+  if (!Number.isFinite(step) || step <= 0) return value;
+  const steps = Math.round((value - min) / step);
+  return min + steps * step;
+};
+
+const toNumber = (value: unknown, fallback: number) => {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+};
+
+const isRangeValue = (value: SliderValue | undefined) => Array.isArray(value);
+
+/**
+ * A slider component for selecting numeric values within a range.
+ */
+export const Slider = forwardRef<HTMLInputElement, SliderProps>(
+  (
+    {
+      size = "medium",
+      type: sliderType = "knob",
+      showTooltip = false,
+      className,
+      trackClassName,
+      thumbClassName,
+      orientation = "horizontal",
+      min = 0,
+      max = 100,
+      value,
+      defaultValue,
+      onChange,
+      onValueChange,
+      disabled = false,
+      id,
+      step = 1,
+      range,
+      ...props
+    },
+    ref
+  ) => {
+    const resolvedSize = sizeAliasMap[size];
+    const inputId = id ?? React.useId();
+    const trackRef = useRef<HTMLDivElement>(null);
+    const lowerInputRef = useRef<HTMLInputElement>(null);
+    const upperInputRef = useRef<HTMLInputElement>(null);
+    const [isDragging, setIsDragging] = useState(false);
+    const [isHovered, setIsHovered] = useState(false);
+    const [focusedThumb, setFocusedThumb] = useState<SliderThumb | null>(null);
+    const [activeThumb, setActiveThumb] = useState<SliderThumb | null>(null);
+
+    const minValue = Number(min);
+    const maxValue = Number(max);
+
+    const isRange = range ?? (isRangeValue(value) || isRangeValue(defaultValue));
+    const isControlled = value !== undefined;
+
+    const [internalValue, setInternalValue] = useState<SliderValue>(() => {
+      if (value !== undefined) return value;
+      if (defaultValue !== undefined) return defaultValue;
+      return isRange ? [minValue, maxValue] : minValue;
+    });
+
+    React.useEffect(() => {
+      if (value === undefined) return;
+      setInternalValue(value);
+    }, [value]);
+
+    // Forward the ref to the lower (or single) input so external focus works.
+    const setLowerInput = useCallback(
+      (node: HTMLInputElement | null) => {
+        lowerInputRef.current = node;
+        if (!ref) return;
+        if (typeof ref === "function") {
+          ref(node);
+        } else {
+          ref.current = node;
+        }
+      },
+      [ref]
+    );
+
+    // Normalize any incoming range-like value into a safe, ordered tuple.
+    // This is the single place where we clamp to min/max, snap to step, and
+    // guarantee the lower bound never ends up above the upper bound.
+    const normalizeRange = useCallback(
+      (nextValue: SliderValue): [number, number] => {
+        const raw = Array.isArray(nextValue)
+          ? nextValue
+          : [toNumber(nextValue, minValue), toNumber(nextValue, maxValue)];
+        let lower = clamp(roundToStep(toNumber(raw[0], minValue), Number(step), minValue), minValue, maxValue);
+        let upper = clamp(roundToStep(toNumber(raw[1], maxValue), Number(step), minValue), minValue, maxValue);
+
+        if (lower > upper) {
+          [lower, upper] = [upper, lower];
+        }
+
+        return [lower, upper];
+      },
+      [maxValue, minValue, step]
+    );
+
+    const currentValue = isControlled ? value : internalValue;
+    const [lowerValue, upperValue] = isRange
+      ? normalizeRange(currentValue as SliderValue)
+      : [toNumber(currentValue, minValue), toNumber(currentValue, minValue)];
+
+    const rangeValue = maxValue - minValue;
+    const lowerProgress = rangeValue > 0 ? ((lowerValue - minValue) / rangeValue) * 100 : 0;
+    const upperProgress = rangeValue > 0 ? ((upperValue - minValue) / rangeValue) * 100 : 0;
+    const progress = rangeValue > 0 ? ((lowerValue - minValue) / rangeValue) * 100 : 0;
+
+    const isVertical = orientation === "vertical";
+
+    const sliderClasses = [
+      "solara-slider",
+      `solara-slider--size-${resolvedSize}`,
+      `solara-slider--${orientation}`,
+      `solara-slider--type-${sliderType}`,
+      isRange ? "solara-slider--range" : null,
+      disabled ? "solara-slider--disabled" : null,
+      isDragging ? "solara-slider--dragging" : null,
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    const trackClasses = ["solara-slider__track", trackClassName]
+      .filter(Boolean)
+      .join(" ");
+    const thumbClasses = ["solara-slider__thumb", thumbClassName]
+      .filter(Boolean)
+      .join(" ");
+
+    // Pointer-driven track clicks/drags do not come from a native input change
+    // event, but consumers still expect `onChange` to receive the same shape.
+    // This synthetic event keeps single-value sliders backward compatible.
+    const createSyntheticChangeEvent = (next: number) =>
+      ({
+        target: { value: next.toString() },
+        currentTarget: { value: next.toString() },
+      }) as React.ChangeEvent<HTMLInputElement>;
+
+    // Single-value change funnel. All single-slider updates route through here so
+    // controlled and uncontrolled modes, `onValueChange`, and legacy `onChange`
+    // stay in sync no matter whether the value came from pointer, touch, or keys.
+    const emitSingleChange = useCallback(
+      (nextValue: number, event?: React.ChangeEvent<HTMLInputElement>) => {
+        if (!isControlled) {
+          setInternalValue(nextValue);
+        }
+        onValueChange?.(nextValue);
+        if (event) {
+          onChange?.(event);
+        } else {
+          onChange?.(createSyntheticChangeEvent(nextValue));
+        }
+      },
+      [isControlled, onChange, onValueChange]
+    );
+
+    // Range equivalent of `emitSingleChange`. We update the tuple for modern
+    // consumers via `onValueChange`, while `onChange` still receives the active
+    // thumb value so existing single-thumb handlers continue to behave sensibly.
+    const emitRangeChange = useCallback(
+      (
+        nextRange: [number, number],
+        thumbValue: number,
+        event?: React.ChangeEvent<HTMLInputElement>
+      ) => {
+        if (!isControlled) {
+          setInternalValue(nextRange);
+        }
+        onValueChange?.(nextRange);
+        if (event) {
+          onChange?.(event);
+        } else {
+          onChange?.(createSyntheticChangeEvent(thumbValue));
+        }
+      },
+      [isControlled, onChange, onValueChange]
+    );
+
+    // Convert the pointer location on the rendered track into a stepped slider
+    // value. Vertical sliders invert the axis so min stays at the bottom and max
+    // stays at the top.
+    const valueFromPointer = useCallback(
+      (clientX: number, clientY: number) => {
+        if (!trackRef.current) return null;
+        const track = trackRef.current.getBoundingClientRect();
+        const percentage = isVertical
+          ? clamp((track.bottom - clientY) / track.height, 0, 1)
+          : clamp((clientX - track.left) / track.width, 0, 1);
+        const rawValue = percentage * (maxValue - minValue) + minValue;
+        const steppedValue = roundToStep(rawValue, Number(step), minValue);
+        return clamp(steppedValue, minValue, maxValue);
+      },
+      [isVertical, maxValue, minValue, step]
+    );
+
+    // When clicking the track in range mode, move the closest thumb.
+    const pickClosestThumb = useCallback(
+      (nextValue: number) => {
+        const lowerDistance = Math.abs(nextValue - lowerValue);
+        const upperDistance = Math.abs(nextValue - upperValue);
+        if (lowerDistance === upperDistance) {
+          return nextValue < lowerValue ? "lower" : "upper";
+        }
+        return lowerDistance < upperDistance ? "lower" : "upper";
+      },
+      [lowerValue, upperValue]
+    );
+
+    // Update a single thumb while preventing it from crossing the other thumb.
+    const updateRangeValue = useCallback(
+      (nextValue: number, thumb: SliderThumb, event?: React.ChangeEvent<HTMLInputElement>) => {
+        if (disabled) return;
+        const nextLower = thumb === "lower" ? clamp(nextValue, minValue, upperValue) : lowerValue;
+        const nextUpper = thumb === "upper" ? clamp(nextValue, lowerValue, maxValue) : upperValue;
+        emitRangeChange([nextLower, nextUpper], nextValue, event);
+      },
+      [disabled, emitRangeChange, lowerValue, maxValue, minValue, upperValue]
+    );
+
+    // Shared pointer update path for track click, mouse drag, and touch drag.
+    // In range mode we resolve which thumb should move first, then keep focus on
+    // that thumb so keyboard interaction and tooltip visibility stay aligned.
+    const updateValueFromPointer = useCallback(
+      (clientX: number, clientY: number, thumbOverride?: SliderThumb) => {
+        const nextValue = valueFromPointer(clientX, clientY);
+        if (nextValue === null) return;
+
+        if (isRange) {
+          const thumb = thumbOverride ?? pickClosestThumb(nextValue);
+          updateRangeValue(nextValue, thumb);
+          setActiveThumb(thumb);
+          if (thumb === "lower") {
+            lowerInputRef.current?.focus();
+          } else {
+            upperInputRef.current?.focus();
+          }
+        } else {
+          emitSingleChange(nextValue);
+          lowerInputRef.current?.focus();
+        }
+      },
+      [emitSingleChange, isRange, pickClosestThumb, updateRangeValue, valueFromPointer]
+    );
+
+    const handleTrackClick = useCallback(
+      (event: React.MouseEvent<HTMLDivElement>) => {
+        event.preventDefault();
+        event.stopPropagation();
+        if (disabled) return;
+        updateValueFromPointer(event.clientX, event.clientY);
+      },
+      [disabled, updateValueFromPointer]
+    );
+
+    // Mouse dragging locks to whichever thumb was chosen on drag start so the
+    // active thumb does not switch back and forth mid-gesture.
+    const handleMouseDown = useCallback(
+      (event: React.MouseEvent) => {
+        if (disabled) return;
+        event.preventDefault();
+        setIsDragging(true);
+
+        const thumbOverride = isRange
+          ? pickClosestThumb(valueFromPointer(event.clientX, event.clientY) ?? lowerValue)
+          : undefined;
+        if (thumbOverride) {
+          setActiveThumb(thumbOverride);
+        }
+
+        const handleMouseMove = (moveEvent: MouseEvent) => {
+          updateValueFromPointer(moveEvent.clientX, moveEvent.clientY, thumbOverride ?? activeThumb ?? undefined);
+        };
+
+        const handleMouseUp = () => {
+          setIsDragging(false);
+          setActiveThumb(null);
+          document.removeEventListener("mousemove", handleMouseMove);
+          document.removeEventListener("mouseup", handleMouseUp);
+        };
+
+        document.addEventListener("mousemove", handleMouseMove);
+        document.addEventListener("mouseup", handleMouseUp);
+
+        updateValueFromPointer(event.clientX, event.clientY, thumbOverride ?? undefined);
+      },
+      [activeThumb, disabled, isRange, lowerValue, pickClosestThumb, updateValueFromPointer, valueFromPointer]
+    );
+
+    // Touch uses the same thumb-locking behavior as mouse drag, but keeps the
+    // listeners on `document` so the gesture continues even if the finger moves
+    // outside the track bounds.
+    const handleTouchStart = useCallback(
+      (event: React.TouchEvent) => {
+        if (disabled) return;
+        event.preventDefault();
+        setIsDragging(true);
+
+        const initialTouch = event.touches[0];
+        const thumbOverride =
+          isRange && initialTouch
+            ? pickClosestThumb(valueFromPointer(initialTouch.clientX, initialTouch.clientY) ?? lowerValue)
+            : undefined;
+        if (thumbOverride) {
+          setActiveThumb(thumbOverride);
+        }
+
+        const handleTouchMove = (moveEvent: TouchEvent) => {
+          if (moveEvent.touches.length === 0) return;
+          updateValueFromPointer(
+            moveEvent.touches[0].clientX,
+            moveEvent.touches[0].clientY,
+            thumbOverride ?? activeThumb ?? undefined
+          );
+        };
+
+        const handleTouchEnd = () => {
+          setIsDragging(false);
+          setActiveThumb(null);
+          document.removeEventListener("touchmove", handleTouchMove);
+          document.removeEventListener("touchend", handleTouchEnd);
+        };
+
+        document.addEventListener("touchmove", handleTouchMove, { passive: false });
+        document.addEventListener("touchend", handleTouchEnd);
+
+        if (initialTouch) {
+          updateValueFromPointer(initialTouch.clientX, initialTouch.clientY, thumbOverride ?? undefined);
+        }
+      },
+      [activeThumb, disabled, isRange, lowerValue, pickClosestThumb, updateValueFromPointer, valueFromPointer]
+    );
+
+    // Keyboard controls: arrow keys, Home/End.
+    const handleKeyDown = useCallback(
+      (event: React.KeyboardEvent<HTMLInputElement>, thumb: SliderThumb) => {
+        if (disabled) return;
+
+        const stepValue = Number(step) || 1;
+        const currentThumbValue = thumb === "lower" ? lowerValue : upperValue;
+        let nextValue = currentThumbValue;
+
+        switch (event.key) {
+          case "ArrowLeft":
+          case "ArrowDown":
+            event.preventDefault();
+            nextValue = currentThumbValue - stepValue;
+            break;
+          case "ArrowRight":
+          case "ArrowUp":
+            event.preventDefault();
+            nextValue = currentThumbValue + stepValue;
+            break;
+          case "Home":
+            event.preventDefault();
+            nextValue = minValue;
+            break;
+          case "End":
+            event.preventDefault();
+            nextValue = maxValue;
+            break;
+          default:
+            return;
+        }
+
+        const clamped = clamp(nextValue, minValue, maxValue);
+        if (isRange) {
+          updateRangeValue(clamped, thumb);
+        } else {
+          emitSingleChange(clamped);
+        }
+      },
+      [disabled, emitSingleChange, isRange, lowerValue, maxValue, minValue, step, updateRangeValue, upperValue]
+    );
+
+    // Native range inputs still drive keyboard interaction and browser-level
+    // accessibility. This handler normalizes those updates back into the same
+    // single/range change funnels used by pointer interaction.
+    const handleInputChange = useCallback(
+      (event: React.ChangeEvent<HTMLInputElement>, thumb: SliderThumb) => {
+        const nextValue = Number(event.target.value);
+        if (isRange) {
+          updateRangeValue(nextValue, thumb, event);
+        } else {
+          emitSingleChange(nextValue, event);
+        }
+      },
+      [emitSingleChange, isRange, updateRangeValue]
+    );
+
+    // Track fill uses start/end so range mode paints only the selected span.
+    const trackStyle = useMemo(
+      () =>
+        ({
+          // Start/end are used by the track fill to render the active span.
+          "--slider-range-start": `${clamp(isRange ? lowerProgress : 0, 0, 100)}%`,
+          "--slider-range-end": `${clamp(isRange ? upperProgress : progress, 0, 100)}%`,
+        }) as React.CSSProperties,
+      [isRange, lowerProgress, progress, upperProgress]
+    );
+
+    // Thumb and tooltip-trigger positions are driven by CSS custom properties.
+    // We expose both percentage and decimal progress values so the default knob
+    // variant can position from a simple percentage while the thumb variant can
+    // do pixel-accurate math against the track's usable size (track minus padding).
+    const lowerThumbStyle = useMemo(
+      () =>
+        ({
+          // Percent-based progress for the default knob thumb.
+          "--slider-progress": `${clamp(isRange ? lowerProgress : progress, 0, 100)}%`,
+          // Decimal progress lets thumb variants compute pixel-accurate positions.
+          "--slider-progress-decimal": `${clamp(isRange ? lowerProgress : progress, 0, 100) / 100}`,
+        }) as React.CSSProperties,
+      [isRange, lowerProgress, progress]
+    );
+
+    const upperThumbStyle = useMemo(
+      () =>
+        ({
+          // Percent-based progress for the upper thumb in range mode.
+          "--slider-progress": `${clamp(upperProgress, 0, 100)}%`,
+          // Decimal progress mirrors the lower thumb for variant math.
+          "--slider-progress-decimal": `${clamp(upperProgress, 0, 100) / 100}`,
+        }) as React.CSSProperties,
+      [upperProgress]
+    );
+
+    // Tooltip visibility is derived from slider interaction state rather than the
+    // Tooltip component's built-in hover/focus handlers. This keeps value bubbles
+    // visible while dragging and ensures range sliders only show the active thumb.
+    const showLowerTooltip =
+      showTooltip &&
+      (isHovered || focusedThumb === "lower" || (isDragging && (activeThumb === "lower" || !isRange)));
+    const showUpperTooltip =
+      showTooltip && (isHovered || focusedThumb === "upper" || (isDragging && activeThumb === "upper"));
+
+    return (
+      <div
+        className={sliderClasses}
+        onMouseEnter={() => setIsHovered(true)}
+        onMouseLeave={() => setIsHovered(false)}>
+        <div className="solara-slider__container">
+          <div
+            ref={trackRef}
+            className="solara-slider__track-wrapper"
+            onClick={handleTrackClick}
+            onMouseDown={handleMouseDown}
+            onTouchStart={handleTouchStart}>
+            <div className={trackClasses} style={trackStyle}>
+              <div className="solara-slider__range" />
+            </div>
+          </div>
+
+          {isRange ? (
+            <>
+              <input
+                id={`${inputId}-lower`}
+                ref={setLowerInput}
+                type="range"
+                className="solara-slider__input solara-slider__input--range"
+                min={min}
+                max={upperValue}
+                step={step}
+                value={lowerValue}
+                disabled={disabled}
+                onFocus={() => setFocusedThumb("lower")}
+                onBlur={() => setFocusedThumb(null)}
+                onKeyDown={(event) => handleKeyDown(event, "lower")}
+                onChange={(event) => handleInputChange(event, "lower")}
+                tabIndex={disabled ? -1 : 0}
+                aria-valuemin={Number(min)}
+                aria-valuemax={Number(upperValue)}
+                aria-valuenow={Number(lowerValue)}
+                aria-orientation={orientation}
+                {...props}
+              />
+              <input
+                id={`${inputId}-upper`}
+                ref={upperInputRef}
+                type="range"
+                className="solara-slider__input solara-slider__input--range"
+                min={lowerValue}
+                max={max}
+                step={step}
+                value={upperValue}
+                disabled={disabled}
+                onFocus={() => setFocusedThumb("upper")}
+                onBlur={() => setFocusedThumb(null)}
+                onKeyDown={(event) => handleKeyDown(event, "upper")}
+                onChange={(event) => handleInputChange(event, "upper")}
+                tabIndex={disabled ? -1 : 0}
+                aria-valuemin={Number(lowerValue)}
+                aria-valuemax={Number(max)}
+                aria-valuenow={Number(upperValue)}
+                aria-orientation={orientation}
+                {...props}
+              />
+            </>
+          ) : (
+            <input
+              id={inputId}
+              ref={setLowerInput}
+              type="range"
+              className="solara-slider__input"
+              min={min}
+              max={max}
+              step={step}
+              value={lowerValue}
+              disabled={disabled}
+              onFocus={() => setFocusedThumb("lower")}
+              onBlur={() => setFocusedThumb(null)}
+              onKeyDown={(event) => handleKeyDown(event, "lower")}
+              onChange={(event) => handleInputChange(event, "lower")}
+              tabIndex={disabled ? -1 : 0}
+              aria-valuemin={Number(min)}
+              aria-valuemax={Number(max)}
+              aria-valuenow={Number(lowerValue)}
+              aria-orientation={orientation}
+              {...props}
+            />
+          )}
+
+          {/*
+            Tooltip is anchored to a dedicated 1px trigger element that receives the
+            same CSS position variables as the visible thumb. The visible thumb stays
+            separate so Tooltip's internal trigger wrapper cannot disturb thumb layout.
+          */}
+          <span className="solara-slider__tooltip-trigger" style={lowerThumbStyle}>
+            <Tooltip content={lowerValue} position={isVertical ? "right" : "top"} hideArrow open={showLowerTooltip} offset={isVertical ? 14 : 22}>
+              <span className="solara-slider__tooltip-anchor solara-slider__tooltip-anchor--lower" />
+            </Tooltip>
+          </span>
+          <div className={`${thumbClasses} solara-slider__thumb--lower`} style={lowerThumbStyle} />
+          {isRange ? (
+            <>
+              <span className="solara-slider__tooltip-trigger" style={upperThumbStyle}>
+                <Tooltip content={upperValue} position={isVertical ? "right" : "top"} hideArrow open={showUpperTooltip} offset={isVertical ? 14 : 22}>
+                  <span className="solara-slider__tooltip-anchor solara-slider__tooltip-anchor--upper" />
+                </Tooltip>
+              </span>
+              <div className={`${thumbClasses} solara-slider__thumb--upper`} style={upperThumbStyle} />
+            </>
+          ) : null}
+        </div>
+      </div>
+    );
+  }
+);
+
+Slider.displayName = "Slider";

package/src/Slider.types.ts

@@ -0,0 +1,62 @@
+import React from "react";
+
+export type SliderSize = "small" | "medium" | "large" | "xlarge" | "sm" | "md" | "lg" | "xl";
+export type SliderValue = number | [number, number];
+export type SliderOrientation = "horizontal" | "vertical";
+export type SliderType = "knob" | "thumb";
+
+export interface SliderProps
+  extends Omit<
+    React.InputHTMLAttributes<HTMLInputElement>,
+    "size" | "onChange" | "value" | "defaultValue" | "type"
+  > {
+  /**
+   * Visual style of the slider.
+   */
+  type?: SliderType;
+  /**
+   * Size of the slider.
+   */
+  size?: SliderSize;
+  /**
+   * Orientation of the slider.
+   */
+  orientation?: SliderOrientation;
+  /**
+   * Enable range selection (two thumbs).
+   * When omitted, range mode is inferred from `value` or `defaultValue`.
+   */
+  range?: boolean;
+  /**
+   * Controlled value for the slider (number for single, tuple for range).
+   */
+  value?: SliderValue;
+  /**
+   * Uncontrolled default value (number for single, tuple for range).
+   */
+  defaultValue?: SliderValue;
+  /**
+   * Show tooltip with the current value.
+   */
+  showTooltip?: boolean;
+  /**
+   * Custom class name for the slider container.
+   */
+  className?: string;
+  /**
+   * Custom class name for the track element.
+   */
+  trackClassName?: string;
+  /**
+   * Custom class name for the thumb element.
+   */
+  thumbClassName?: string;
+  /**
+   * Callback when value changes.
+   */
+  onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+  /**
+   * Callback when value changes (number for single, tuple for range).
+   */
+  onValueChange?: (value: SliderValue) => void;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { Slider } from "./Slider";
+export type { SliderProps, SliderSize, SliderValue, SliderOrientation, SliderType } from "./Slider.types";