@zag-js/slider 0.23.0 → 0.25.0

package/src/slider.types.ts

@@ -6,7 +6,12 @@ import type { CommonProperties, Context, DirectionProperty, PropTypes, RequiredB
  * -----------------------------------------------------------------------------*/
 
 export interface ValueChangeDetails {
-  value: number
+  value: number[]
+}
+
+export interface FocusChangeDetails {
+  focusedIndex: number
+  value: number[]
 }
 
 /* -----------------------------------------------------------------------------
@@ -15,32 +20,40 @@ export interface ValueChangeDetails {
 
 type ElementIds = Partial<{
   root: string
-  thumb: string
+  thumb(index: number): string
   control: string
   track: string
   range: string
   label: string
   output: string
-  hiddenInput: string
+  marker(index: number): string
 }>
 
 interface PublicContext extends DirectionProperty, CommonProperties {
   /**
-   * The ids of the elements in the slider. Useful for composition.
+   * The ids of the elements in the range slider. Useful for composition.
    */
   ids?: ElementIds
   /**
-   * The value of the slider
+   * The aria-label of each slider thumb. Useful for providing an accessible name to the slider
    */
-  value: number
+  "aria-label"?: string[]
+  /**
+   * The `id` of the elements that labels each slider thumb. Useful for providing an accessible name to the slider
+   */
+  "aria-labelledby"?: string[]
   /**
-   * The name associated with the slider (when used in a form)
+   * The name associated with each slider thumb (when used in a form)
    */
   name?: string
   /**
    * The associate form of the underlying input element.
    */
   form?: string
+  /**
+   * The value of the range slider
+   */
+  value: number[]
   /**
    * Whether the slider is disabled
    */
@@ -50,58 +63,50 @@ interface PublicContext extends DirectionProperty, CommonProperties {
    */
   readOnly?: boolean
   /**
-   * Whether the slider value is invalid
+   * Whether the slider is invalid
    */
   invalid?: boolean
   /**
-   * The minimum value of the slider
-   */
-  min: number
-  /**
-   * The maximum value of the slider
-   */
-  max: number
-  /**
-   * The step value of the slider
+   * Function invoked when the value of the slider changes
    */
-  step: number
+  onValueChange?(details: ValueChangeDetails): void
   /**
-   * The orientation of the slider
+   * Function invoked when the slider value change is done
    */
-  orientation?: "vertical" | "horizontal"
+  onValueChangeEnd?(details: ValueChangeDetails): void
   /**
-   * - "start": Useful when the value represents an absolute value
-   * - "center": Useful when the value represents an offset (relative)
+   * Function invoked when the slider's focused index changes
    */
-  origin?: "start" | "center"
+  onFocusChange?(details: FocusChangeDetails): void
   /**
-   * The aria-label of the slider. Useful for providing an accessible name to the slider
+   * Function that returns a human readable value for the slider thumb
    */
-  "aria-label"?: string
+  getAriaValueText?(value: number, index: number): string
   /**
-   * The `id` of the element that labels the slider. Useful for providing an accessible name to the slider
+   * The minimum value of the slider
    */
-  "aria-labelledby"?: string
+  min: number
   /**
-   * Whether to focus the slider thumb after interaction (scrub and keyboard)
+   * The maximum value of the slider
    */
-  focusThumbOnChange?: boolean
+  max: number
   /**
-   * Function that returns a human readable value for the slider
+   * The step value of the slider
    */
-  getAriaValueText?(value: number): string
+  step: number
   /**
-   * Function invoked when the value of the slider changes
+   * The minimum permitted steps between multiple thumbs.
    */
-  onValueChange?(details: ValueChangeDetails): void
+  minStepsBetweenThumbs: number
   /**
-   * Function invoked when the slider value change is done
+   * The orientation of the slider
    */
-  onValueChangeEnd?(details: ValueChangeDetails): void
+  orientation: "vertical" | "horizontal"
   /**
-   * Function invoked when the slider value change is started
+   * - "start": Useful when the value represents an absolute value
+   * - "center": Useful when the value represents an offset (relative)
    */
-  onValueChangeStart?(details: ValueChangeDetails): void
+  origin?: "start" | "center"
   /**
    * The alignment of the slider thumb relative to the track
    * - `center`: the thumb will extend beyond the bounds of the slider track.
@@ -109,9 +114,9 @@ interface PublicContext extends DirectionProperty, CommonProperties {
    */
   thumbAlignment?: "contain" | "center"
   /**
-   * The slider thumb dimensions.If not provided, the thumb size will be measured automatically.
+   * The slider thumbs dimensions
    */
-  thumbSize: Size | null
+  thumbSize: { width: number; height: number } | null
 }
 
 export type UserDefinedContext = RequiredBy<PublicContext, "id">
@@ -119,24 +124,29 @@ export type UserDefinedContext = RequiredBy<PublicContext, "id">
 type ComputedContext = Readonly<{
   /**
    * @computed
-   * Whether the slider is interactive
+   * Whether the slider thumb has been measured
    */
-  isInteractive: boolean
+  hasMeasuredThumbSize: boolean
   /**
    * @computed
-   * Whether the thumb size has been measured
+   * Whether the slider is interactive
    */
-  hasMeasuredThumbSize: boolean
+  isInteractive: boolean
   /**
    * @computed
-   * Whether the slider is horizontal
+   * The raw value of the space between each thumb
    */
-  isHorizontal: boolean
+  spacing: number
   /**
    * @computed
    * Whether the slider is vertical
    */
   isVertical: boolean
+  /**
+   * @computed
+   * Whether the slider is horizontal
+   */
+  isHorizontal: boolean
   /**
    * @computed
    * Whether the slider is in RTL mode
@@ -144,9 +154,9 @@ type ComputedContext = Readonly<{
   isRtl: boolean
   /**
    * @computed
-   * The value of the slider as a percentage
+   * The percentage of the slider value relative to the slider min/max
    */
-  valuePercent: number
+  valuePercent: number[]
   /**
    * @computed
    * Whether the slider is disabled
@@ -157,9 +167,10 @@ type ComputedContext = Readonly<{
 type PrivateContext = Context<{
   /**
    * @internal
-   * The move threshold of the slider thumb before it is considered to be moved
+   * The active index of the range slider. This represents
+   * the currently dragged/focused thumb.
    */
-  threshold: number
+  focusedIndex: number
   /**
    * @internal
    * Whether the slider fieldset is disabled
@@ -181,68 +192,86 @@ export type Send = S.Send<S.AnyEventObject>
  * Component API
  * -----------------------------------------------------------------------------*/
 
-export interface Point {
-  x: number
-  y: number
-}
-
 interface Size {
   width: number
   height: number
 }
 
-interface MarkerProps {
+export interface MarkerProps {
   value: number
 }
 
+export interface ThumbProps {
+  index: number
+}
+
 export interface MachineApi<T extends PropTypes = PropTypes> {
   /**
-   * Whether the slider is focused.
+   * The value of the slider.
    */
-  isFocused: boolean
+  value: number[]
   /**
    * Whether the slider is being dragged.
    */
   isDragging: boolean
   /**
-   * The value of the slider.
+   * Whether the slider is focused.
    */
-  value: number
+  isFocused: boolean
   /**
-   * The value of the slider as a percent.
+   * Function to set the value of the slider.
    */
-  percent: number
+  setValue(value: number[]): void
   /**
-   * Function to set the value of the slider.
+   * Returns the value of the thumb at the given index.
    */
-  setValue(value: number): void
+  getThumbValue(index: number): number
   /**
-   * Returns the value of the slider at the given percent.
+   * Sets the value of the thumb at the given index.
    */
-  getPercentValue: (percent: number) => number
+  setThumbValue(index: number, value: number): void
   /**
-   * Returns the percent of the slider at the given value.
+   * Returns the percent of the thumb at the given index.
    */
   getValuePercent: (value: number) => number
   /**
-   * Function to focus the slider.
+   * Returns the value of the thumb at the given percent.
    */
-  focus(): void
+  getPercentValue: (percent: number) => number
   /**
-   * Function to increment the value of the slider by the step.
+   * Returns the percent of the thumb at the given index.
    */
-  increment(): void
+  getThumbPercent(index: number): number
   /**
-   * Function to decrement the value of the slider by the step.
+   * Sets the percent of the thumb at the given index.
    */
-  decrement(): void
-
-  rootProps: T["element"]
+  setThumbPercent(index: number, percent: number): void
+  /**
+   * Returns the min value of the thumb at the given index.
+   */
+  getThumbMin(index: number): number
+  /**
+   * Returns the max value of the thumb at the given index.
+   */
+  getThumbMax(index: number): number
+  /**
+   * Function to increment the value of the slider at the given index.
+   */
+  increment(index: number): void
+  /**
+   * Function to decrement the value of the slider at the given index.
+   */
+  decrement(index: number): void
+  /**
+   * Function to focus the slider. This focuses the first thumb.
+   */
+  focus(): void
   labelProps: T["label"]
-  thumbProps: T["element"]
-  hiddenInputProps: T["input"]
+  rootProps: T["element"]
   outputProps: T["output"]
   trackProps: T["element"]
+  getThumbProps(props: ThumbProps): T["element"]
+  getHiddenInputProps(props: ThumbProps): T["input"]
   rangeProps: T["element"]
   controlProps: T["element"]
   markerGroupProps: T["element"]

package/src/slider.utils.ts

@@ -1,31 +1,64 @@
-import { clampValue, getNextStepValue, getPreviousStepValue, snapValueToStep } from "@zag-js/numeric-range"
+import {
+  clampValue,
+  getClosestValueIndex,
+  getNextStepValue,
+  getPreviousStepValue,
+  getValueRanges,
+  snapValueToStep,
+} from "@zag-js/numeric-range"
 import type { MachineContext as Ctx } from "./slider.types"
 
+export function normalizeValues(ctx: Ctx, nextValues: number[]) {
+  return nextValues.map((value, index, values) => {
+    return constrainValue({ ...ctx, value: values }, value, index)
+  })
+}
+
 export function clampPercent(percent: number) {
   return clampValue(percent, 0, 1)
 }
 
-export function constrainValue(ctx: Ctx, value: number) {
+export function getRangeAtIndex(ctx: Ctx, index: number) {
+  return getValueRanges(ctx.value, ctx.min, ctx.max, ctx.minStepsBetweenThumbs)[index]
+}
+
+export function constrainValue(ctx: Ctx, value: number, index: number) {
+  const range = getRangeAtIndex(ctx, index)
   const snapValue = snapValueToStep(value, ctx.min, ctx.max, ctx.step)
-  return clampValue(snapValue, ctx.min, ctx.max)
+  return clampValue(snapValue, range.min, range.max)
 }
 
-export function decrement(ctx: Ctx, step?: number) {
-  const index = 0
-  const values = getPreviousStepValue(index, {
-    ...ctx,
+export function decrement(ctx: Ctx, index?: number, step?: number) {
+  const idx = index ?? ctx.focusedIndex
+  const range = getRangeAtIndex(ctx, idx)
+  const nextValues = getPreviousStepValue(idx, {
+    ...range,
     step: step ?? ctx.step,
-    values: [ctx.value],
+    values: ctx.value,
   })
-  return values[index]
+  nextValues[idx] = clampValue(nextValues[idx], range.min, range.max)
+  return nextValues
 }
 
-export function increment(ctx: Ctx, step?: number) {
-  const index = 0
-  const values = getNextStepValue(index, {
-    ...ctx,
+export function increment(ctx: Ctx, index?: number, step?: number) {
+  const idx = index ?? ctx.focusedIndex
+  const range = getRangeAtIndex(ctx, idx)
+  const nextValues = getNextStepValue(idx, {
+    ...range,
     step: step ?? ctx.step,
-    values: [ctx.value],
+    values: ctx.value,
   })
-  return values[index]
+  nextValues[idx] = clampValue(nextValues[idx], range.min, range.max)
+  return nextValues
+}
+
+export function getClosestIndex(ctx: Ctx, pointValue: number) {
+  return getClosestValueIndex(ctx.value, pointValue)
+}
+
+export function assignArray(current: number[], next: number[]) {
+  for (let i = 0; i < next.length; i++) {
+    const value = next[i]
+    current[i] = value
+  }
 }