{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"range-ruler","type":"registry:component","title":"Range ruler","description":"Two hairline needles across a graduated scale. Thumbs glide without layout thrash and repel each other on contact.","author":"Hairline UI","dependencies":[],"registryDependencies":["https://hairlineui.com/r/number-roll.json"],"files":[{"path":"registry/range-ruler.tsx","type":"registry:component","content":"// Hairline UI · range-ruler · MIT License\n// Copyright (c) 2026 Hairline UI · https://hairlineui.com/license#components\n\n'use client';\n\n/* ─────────────────────────────────────────────────────────\n * RANGE RULER: dual needles on a graduated hairline ruler\n *\n * ruler an axis with 1px SVG tick marks; major ticks\n * mark intervals, minor ticks subdivide steps\n * needles two tactile hairline sliders with 1px indicators;\n * dragging glides with zero layout thrash\n * repulsion drag the lower needle into the upper one and it\n * pushes the upper needle forward instead of\n * clipping; drag backwards and it pushes down\n * badges floating metric pills roll with NumberRoll;\n * when needles get within 48px, the badges glide\n * together into a single merged span\n * settle values commit on pointer release, and numbers\n * roll smoothly to their settled positions\n *\n * Both needles are accessible sliders with full arrow, Home,\n * End, and Page keys.\n * ───────────────────────────────────────────────────────── */\n\nimport * as React from 'react';\nimport { NumberRoll } from './number-roll';\nimport { INTERACTION_FOCUS, useInteractionReducedMotion } from './ui-interaction-motion';\nimport { snapRulerValue, useRangeRuler } from './use-range-ruler';\n\nexport type RangeValue = [number, number];\n\nexport interface RangeRulerProps extends Omit, 'onChange' | 'defaultValue'> {\n label?: string;\n value?: RangeValue;\n defaultValue?: RangeValue;\n min?: number;\n max?: number;\n step?: number;\n minDistance?: number;\n unit?: string;\n disabled?: boolean;\n onValueChange?: (value: RangeValue) => void;\n onValueCommit?: (value: RangeValue) => void;\n format?: Intl.NumberFormatOptions;\n locales?: string | string[];\n}\n\nexport function RangeRuler({\n label,\n value,\n defaultValue = [20, 80],\n min = 0,\n max = 100,\n step = 1,\n minDistance = 0,\n unit = '',\n disabled = false,\n onValueChange,\n onValueCommit,\n format,\n locales,\n className = '',\n ...props\n}: RangeRulerProps) {\n const reduced = useInteractionReducedMotion();\n const lower = Number.isFinite(min) ? min : 0;\n const upper = Number.isFinite(max) && max > lower ? max : lower + 100;\n const increment = Number.isFinite(step) && step > 0 ? step : 1;\n\n const [own, setOwn] = React.useState(defaultValue);\n const currentVal = value ?? own;\n\n const safeVal: RangeValue = React.useMemo(() => {\n const l = snapRulerValue(currentVal[0], lower, upper - minDistance, increment);\n const u = snapRulerValue(currentVal[1], l + minDistance, upper, increment);\n return [l, u];\n }, [currentVal, lower, upper, minDistance, increment]);\n\n const decimals = Math.min(4, Math.max(0, (String(increment).split('.')[1] ?? '').length));\n\n const formatNumber = React.useCallback(\n (n: number) => {\n const formatted = n.toFixed(decimals);\n return unit ? `${formatted} ${unit}` : formatted;\n },\n [decimals, unit]\n );\n\n const formatAria = React.useCallback(\n (n: number) => `${n.toFixed(decimals)}${unit ? ` ${unit}` : ''}`,\n [decimals, unit]\n );\n\n const handleChange = React.useCallback(\n (next: RangeValue) => onValueChange?.(next),\n [onValueChange]\n );\n\n const handleCommit = React.useCallback(\n (next: RangeValue) => {\n if (value === undefined) setOwn(next);\n onValueCommit?.(next);\n },\n [value, onValueCommit]\n );\n\n const ruler = useRangeRuler({\n value: safeVal,\n min: lower,\n max: upper,\n step: increment,\n minDistance,\n disabled,\n reduced,\n onChange: handleChange,\n onCommit: handleCommit,\n format: formatAria,\n formatNumber,\n });\n\n const rangeSpan = upper - lower;\n const tickCount = Math.min(81, Math.max(11, Math.round(rangeSpan / increment) + 1));\n const majorInterval = Math.max(1, Math.round(tickCount / 8));\n\n const ticks = React.useMemo(() => {\n return Array.from({ length: tickCount }, (_, i) => {\n const fraction = i / (tickCount - 1);\n const isMajor = i % majorInterval === 0 || i === tickCount - 1;\n return { fraction, isMajor, key: i };\n });\n }, [tickCount, majorInterval]);\n\n const lowerHint = React.useId();\n const upperHint = React.useId();\n\n return (\n \n {label && (\n
\n {label}\n \n {formatNumber(safeVal[0])} — {formatNumber(safeVal[1])}\n \n
\n )}\n\n {/* Floating Readout Badges */}\n
\n {ruler.isMerged ? (\n
\n
\n \n {formatNumber(safeVal[0])} – {formatNumber(safeVal[1])}\n \n \n \n –\n \n {unit && {unit}}\n \n
\n
\n ) : (\n
\n \n
\n \n {formatNumber(safeVal[0])}\n \n \n \n {unit && {unit}}\n \n
\n
\n\n \n
\n \n {formatNumber(safeVal[1])}\n \n \n \n {unit && {unit}}\n \n
\n
\n \n )}\n \n\n {/* The Track & Graduated Hairline Ruler */}\n
\n {/* SVG Graduated Ruler Ticks */}\n
\n \n {/* Base Hairline Axis */}\n \n {ticks.map((t) => (\n \n ))}\n \n
\n\n {/* Track gesture container */}\n
\n {/* Active Highlight Band */}\n \n\n {/* Lower Needle Thumb */}\n \n {/* 1px Vertical Needle */}\n \n \n\n {/* Upper Needle Thumb */}\n \n {/* 1px Vertical Needle */}\n \n \n
\n\n {/* Lower / Upper Bound Labels */}\n
\n {formatNumber(lower)}\n {formatNumber(upper)}\n
\n
\n\n

\n Adjust minimum. Left arrow decreases, right arrow increases. Shift increases step by 10. Home sets to minimum, End to maximum.\n

\n

\n Adjust maximum. Left arrow decreases, right arrow increases. Shift increases step by 10. Home sets to minimum, End to maximum.\n

\n \n );\n}\n"},{"path":"registry/use-range-ruler.ts","type":"registry:component","content":"// Hairline UI · range-ruler · MIT License\n// Copyright (c) 2026 Hairline UI · https://hairlineui.com/license#components\n\n'use client';\n\nimport * as React from 'react';\nimport { EASE_OUT } from './ui-interaction-motion';\n\nexport function snapRulerValue(value: number, min: number, max: number, step: number) {\n if (!Number.isFinite(value) || value <= min) return min;\n if (value >= max) return max;\n const snapped = min + Math.round((value - min) / step) * step;\n return Number(Math.max(min, Math.min(max, snapped)).toFixed(6));\n}\n\ntype Range = [number, number];\n\ntype RangeRulerOptions = {\n value: Range;\n min: number;\n max: number;\n step: number;\n minDistance?: number;\n disabled: boolean;\n reduced: boolean;\n onChange?: (value: Range) => void;\n onCommit?: (value: Range) => void;\n format: (value: number) => string;\n formatNumber: (value: number) => string;\n};\n\n/** High-performance gesture controller for a dual-needle graduated ruler. */\nexport function useRangeRuler(options: RangeRulerOptions) {\n const trackRef = React.useRef(null);\n const lowerThumbRef = React.useRef(null);\n const upperThumbRef = React.useRef(null);\n const highlightRef = React.useRef(null);\n const lowerReadoutRef = React.useRef(null);\n const upperReadoutRef = React.useRef(null);\n const mergedReadoutRef = React.useRef(null);\n const badgeWrapRef = React.useRef(null);\n\n const optionsRef = React.useRef(options);\n optionsRef.current = options;\n\n const [activeThumb, setActiveThumb] = React.useState<'lower' | 'upper' | null>(null);\n const [isMerged, setIsMerged] = React.useState(false);\n\n // Active drag state kept strictly in refs to prevent layout thrash and React re-renders.\n const gesture = React.useRef<{\n id: number;\n thumb: 'lower' | 'upper';\n startVal: Range;\n currentVal: Range;\n trackLeft: number;\n trackWidth: number;\n } | null>(null);\n\n const getRatio = React.useCallback(\n (val: number) => {\n const { min, max } = optionsRef.current;\n return Math.max(0, Math.min(1, (val - min) / (max - min)));\n },\n []\n );\n\n const paint = React.useCallback(\n (range: Range, animate: boolean) => {\n const o = optionsRef.current;\n const track = trackRef.current;\n const width = track ? track.offsetWidth : 0;\n if (!width) return;\n\n const [lower, upper] = range;\n const lowerRatio = getRatio(lower);\n const upperRatio = getRatio(upper);\n\n const lowerPx = lowerRatio * width;\n const upperPx = upperRatio * width;\n\n const transition = animate && !o.reduced ? `transform 360ms ${EASE_OUT}` : 'none';\n const barTransition = animate && !o.reduced ? `left 360ms ${EASE_OUT}, width 360ms ${EASE_OUT}` : 'none';\n\n if (lowerThumbRef.current) {\n lowerThumbRef.current.style.transition = transition;\n lowerThumbRef.current.style.transform = `translateX(${lowerPx}px)`;\n lowerThumbRef.current.setAttribute('aria-valuenow', String(lower));\n lowerThumbRef.current.setAttribute('aria-valuetext', o.format(lower));\n }\n\n if (upperThumbRef.current) {\n upperThumbRef.current.style.transition = transition;\n upperThumbRef.current.style.transform = `translateX(${upperPx}px)`;\n upperThumbRef.current.setAttribute('aria-valuenow', String(upper));\n upperThumbRef.current.setAttribute('aria-valuetext', o.format(upper));\n }\n\n if (highlightRef.current) {\n highlightRef.current.style.transition = barTransition;\n highlightRef.current.style.left = `${lowerPx}px`;\n highlightRef.current.style.width = `${Math.max(0, upperPx - lowerPx)}px`;\n }\n\n if (lowerReadoutRef.current) lowerReadoutRef.current.textContent = o.formatNumber(lower);\n if (upperReadoutRef.current) upperReadoutRef.current.textContent = o.formatNumber(upper);\n if (mergedReadoutRef.current) {\n mergedReadoutRef.current.textContent = lower === upper ? o.formatNumber(lower) : `${o.formatNumber(lower)} – ${o.formatNumber(upper)}`;\n }\n\n const merged = upperPx - lowerPx < 48;\n setIsMerged(merged);\n },\n [getRatio]\n );\n\n const commit = React.useCallback(\n (next: Range, animate = true) => {\n const o = optionsRef.current;\n const dist = o.minDistance ?? 0;\n let lower = snapRulerValue(next[0], o.min, o.max - dist, o.step);\n let upper = snapRulerValue(next[1], o.min + dist, o.max, o.step);\n\n if (lower > upper - dist) {\n if (next[0] > o.value[0]) upper = Math.min(o.max, lower + dist);\n else lower = Math.max(o.min, upper - dist);\n }\n\n const clean: Range = [lower, upper];\n paint(clean, animate);\n o.onChange?.(clean);\n o.onCommit?.(clean);\n },\n [paint]\n );\n\n const finish = React.useCallback(\n (cancelled: boolean) => {\n const g = gesture.current;\n if (!g) return;\n gesture.current = null;\n setActiveThumb(null);\n\n if (cancelled) {\n paint(g.startVal, true);\n optionsRef.current.onChange?.(g.startVal);\n } else {\n commit(g.currentVal, false);\n }\n },\n [commit, paint]\n );\n\n React.useLayoutEffect(() => {\n if (!gesture.current) paint(options.value, true);\n }, [options.value, options.min, options.max, options.reduced, paint]);\n\n // Handle window resizing to recalibrate positions\n React.useEffect(() => {\n const handleResize = () => {\n if (!gesture.current) paint(optionsRef.current.value, false);\n };\n window.addEventListener('resize', handleResize);\n return () => window.removeEventListener('resize', handleResize);\n }, [paint]);\n\n React.useEffect(() => {\n const interrupted = () => finish(true);\n const hidden = () => {\n if (document.hidden) interrupted();\n };\n window.addEventListener('blur', interrupted);\n document.addEventListener('visibilitychange', hidden);\n return () => {\n window.removeEventListener('blur', interrupted);\n document.removeEventListener('visibilitychange', hidden);\n };\n }, [finish]);\n\n React.useEffect(() => {\n if (options.disabled) finish(true);\n }, [options.disabled, finish]);\n\n const startDrag = React.useCallback(\n (thumb: 'lower' | 'upper', event: React.PointerEvent) => {\n if (event.button !== 0 || !event.isPrimary || optionsRef.current.disabled) return;\n const track = trackRef.current;\n if (!track) return;\n\n const rect = track.getBoundingClientRect();\n event.currentTarget.setPointerCapture(event.pointerId);\n event.currentTarget.focus({ preventScroll: true });\n\n gesture.current = {\n id: event.pointerId,\n thumb,\n startVal: [...optionsRef.current.value] as Range,\n currentVal: [...optionsRef.current.value] as Range,\n trackLeft: rect.left,\n trackWidth: Math.max(1, rect.width),\n };\n\n setActiveThumb(thumb);\n paint(optionsRef.current.value, false);\n },\n [paint]\n );\n\n const onPointerMove = React.useCallback(\n (event: React.PointerEvent) => {\n const g = gesture.current;\n const o = optionsRef.current;\n if (!g || g.id !== event.pointerId) return;\n\n const clientX = event.clientX;\n const fraction = Math.max(0, Math.min(1, (clientX - g.trackLeft) / g.trackWidth));\n const targetVal = snapRulerValue(o.min + fraction * (o.max - o.min), o.min, o.max, o.step);\n const dist = o.minDistance ?? 0;\n\n let [lower, upper] = g.currentVal;\n\n if (g.thumb === 'lower') {\n lower = Math.min(o.max - dist, targetVal);\n // Repulsion physics: lower pushes upper forward\n if (lower > upper - dist) {\n upper = Math.min(o.max, lower + dist);\n }\n } else {\n upper = Math.max(o.min + dist, targetVal);\n // Repulsion physics: upper pushes lower backward\n if (upper < lower + dist) {\n lower = Math.max(o.min, upper - dist);\n }\n }\n\n if (lower === g.currentVal[0] && upper === g.currentVal[1]) return;\n\n g.currentVal = [lower, upper];\n paint([lower, upper], false);\n o.onChange?.([lower, upper]);\n },\n [paint]\n );\n\n const makeKeyHandler = React.useCallback(\n (thumb: 'lower' | 'upper') => (event: React.KeyboardEvent) => {\n if (event.key === 'Escape') {\n event.preventDefault();\n finish(true);\n return;\n }\n\n const o = optionsRef.current;\n if (!['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'PageUp', 'PageDown', 'Home', 'End'].includes(event.key)) return;\n\n event.preventDefault();\n const isUp = ['ArrowRight', 'ArrowUp', 'PageUp'].includes(event.key);\n const mult = event.key.startsWith('Page') || event.shiftKey ? 10 : 1;\n const delta = o.step * mult * (isUp ? 1 : -1);\n const dist = o.minDistance ?? 0;\n\n let [lower, upper] = o.value;\n\n if (thumb === 'lower') {\n if (event.key === 'Home') lower = o.min;\n else if (event.key === 'End') lower = upper - dist;\n else lower = Math.max(o.min, Math.min(o.max - dist, lower + delta));\n\n if (lower > upper - dist) upper = Math.min(o.max, lower + dist);\n } else {\n if (event.key === 'Home') upper = lower + dist;\n else if (event.key === 'End') upper = o.max;\n else upper = Math.max(o.min + dist, Math.min(o.max, upper + delta));\n\n if (upper < lower + dist) lower = Math.max(o.min, upper - dist);\n }\n\n commit([lower, upper]);\n },\n [commit, finish]\n );\n\n return {\n trackRef,\n lowerThumbRef,\n upperThumbRef,\n highlightRef,\n lowerReadoutRef,\n upperReadoutRef,\n mergedReadoutRef,\n badgeWrapRef,\n activeThumb,\n isMerged,\n commit,\n lowerHandlers: {\n onPointerDown: (e: React.PointerEvent) => startDrag('lower', e),\n onPointerMove,\n onPointerUp: (e: React.PointerEvent) => {\n if (e.pointerId === gesture.current?.id) finish(false);\n },\n onPointerCancel: (e: React.PointerEvent) => {\n if (e.pointerId === gesture.current?.id) finish(true);\n },\n onLostPointerCapture: (e: React.PointerEvent) => {\n if (e.pointerId === gesture.current?.id) finish(true);\n },\n onBlur: () => finish(true),\n onKeyDown: makeKeyHandler('lower'),\n },\n upperHandlers: {\n onPointerDown: (e: React.PointerEvent) => startDrag('upper', e),\n onPointerMove,\n onPointerUp: (e: React.PointerEvent) => {\n if (e.pointerId === gesture.current?.id) finish(false);\n },\n onPointerCancel: (e: React.PointerEvent) => {\n if (e.pointerId === gesture.current?.id) finish(true);\n },\n onLostPointerCapture: (e: React.PointerEvent) => {\n if (e.pointerId === gesture.current?.id) finish(true);\n },\n onBlur: () => finish(true),\n onKeyDown: makeKeyHandler('upper'),\n },\n };\n}\n"},{"path":"registry/ui-interaction-motion.ts","type":"registry:component","content":"// Hairline UI · range-ruler · MIT License\n// Copyright (c) 2026 Hairline UI · https://hairlineui.com/license#components\n\n'use client';\n\nimport * as React from 'react';\n\nexport const EASE_OUT = 'cubic-bezier(0.16, 1, 0.3, 1)';\nexport const EASE_SETTLE = 'cubic-bezier(0.22, 1.18, 0.36, 1)';\nexport const INTERACTION_FOCUS = 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:ring-offset-2 focus-visible:ring-offset-background';\n\nconst query = '(prefers-reduced-motion: reduce)';\nconst subscribe = (notify: () => void) => {\n const media = window.matchMedia(query);\n media.addEventListener('change', notify);\n return () => media.removeEventListener('change', notify);\n};\nexport const useInteractionReducedMotion = () => React.useSyncExternalStore(subscribe, () => window.matchMedia(query).matches, () => false);\n\nexport function useInteractionActivity() {\n const ref = React.useRef(null);\n const [visible, setVisible] = React.useState(false);\n const [hidden, setHidden] = React.useState(false);\n React.useEffect(() => {\n const el = ref.current;\n if (!el) return;\n const observer = new IntersectionObserver(([entry]) => setVisible(entry.isIntersecting));\n observer.observe(el);\n const visibility = () => setHidden(document.hidden);\n visibility(); document.addEventListener('visibilitychange', visibility);\n return () => { observer.disconnect(); document.removeEventListener('visibilitychange', visibility); };\n }, []);\n return { ref, active: visible && !hidden };\n}\n\nexport function interactionIcon(on: boolean, reduced: boolean): React.CSSProperties {\n return { opacity: on ? 1 : 0, transform: on ? 'none' : 'scale(0.6)', filter: on ? 'blur(0px)' : 'blur(3px)', transition: reduced ? 'none' : `opacity 220ms ${EASE_OUT}, transform 380ms ${EASE_OUT}, filter 220ms ${EASE_OUT}` };\n}\n\n/** Sample recent movement rather than averaging a long drag and losing its release velocity. */\nexport type PointerSample = { x: number; time: number };\nexport function samplePointer(samples: PointerSample[], x: number, time: number) {\n samples.push({ x, time });\n while (samples.length > 2 && time - samples[0].time > 100) samples.shift();\n}\nexport function releaseVelocity(samples: PointerSample[], now: number) {\n if (samples.length < 2 || now - samples[samples.length - 1].time > 100) return 0;\n const first = samples[0], last = samples[samples.length - 1];\n return (last.x - first.x) / Math.max(1, last.time - first.time);\n}\n\n/** A damped spring sampled by WAAPI: no React renders or perpetual frame loop. */\nexport function springFrames(from: number, to: number, velocity = 0, duration = 520) {\n const omega = 20, damping = 0.82, damped = omega * Math.sqrt(1 - damping * damping);\n const displacement = from - to;\n const coefficient = (velocity * 1000 + damping * omega * displacement) / damped;\n return Array.from({ length: 33 }, (_, i) => {\n const t = (i / 32) * duration / 1000;\n const value = to + Math.exp(-damping * omega * t) * (displacement * Math.cos(damped * t) + coefficient * Math.sin(damped * t));\n return { value: i === 32 ? to : value, offset: i / 32 };\n });\n}\n"}],"css":{},"docs":"Docs and live preview: https://hairlineui.com/ui/range-ruler. MIT licensed: https://hairlineui.com/license#components","meta":{"license":"MIT"}}