@limonify/zest-ui 0.1.0

package/src/slider/control/SliderControl.tsx

@@ -0,0 +1,131 @@
+'use client';
+import * as React from 'react';
+import { View, type LayoutChangeEvent } from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import { useSliderRootContext } from '../root/SliderRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { SliderRootState } from '../root/SliderRoot';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * The interactive area of the slider: it measures itself, owns the drag gesture,
+ * and turns a touch position into a value.
+ * Renders a `<View>` wrapped in a `GestureDetector`.
+ *
+ * Requires `react-native-gesture-handler`, and the app to be wrapped in
+ * `<GestureHandlerRootView>`.
+ */
+export function SliderControl(componentProps: SliderControl.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const { testID } = elementProps;
+
+  const {
+    commitValue,
+    disabled,
+    getClosestThumbIndex,
+    getValueFromPosition,
+    orientation,
+    setControlSize,
+    setDragging,
+    setThumbValue,
+    state,
+  } = useSliderRootContext();
+
+  // The gesture runs outside React's render, so the thumb being dragged is kept
+  // in a ref rather than state.
+  const activeThumbRef = React.useRef(0);
+
+  const handleLayout = React.useCallback(
+    (event: LayoutChangeEvent) => {
+      const { width, height } = event.nativeEvent.layout;
+      setControlSize(orientation === 'vertical' ? height : width);
+    },
+    [setControlSize, orientation],
+  );
+
+  const moveTo = React.useCallback(
+    (position: number, index: number) => {
+      const value = getValueFromPosition(position);
+      if (value === undefined) {
+        return;
+      }
+
+      setThumbValue(index, value, createChangeEventDetails(REASONS.drag));
+    },
+    [setThumbValue, getValueFromPosition],
+  );
+
+  const follow = React.useCallback(
+    (event: { x: number; y: number }) => {
+      moveTo(orientation === 'vertical' ? event.y : event.x, activeThumbRef.current);
+    },
+    [moveTo, orientation],
+  );
+
+  const gesture = React.useMemo(
+    () =>
+      Gesture.Pan()
+        .enabled(!disabled)
+        // A gesture is invisible to the rendered tree, so `fireGestureHandler`
+        // can only reach it through gesture-handler's own registry, which is
+        // keyed by this id (and only populated under a test env). Forwarding the
+        // control's `testID` is what makes the drag testable at all — without it
+        // consumers could not test their own sliders either.
+        .withTestId(testID ?? 'slider-control')
+        // A press anywhere on the control jumps the nearest thumb to it, then
+        // that same thumb follows the finger.
+        .onBegin((event) => {
+          const position = orientation === 'vertical' ? event.y : event.x;
+          const value = getValueFromPosition(position);
+          if (value === undefined) {
+            return;
+          }
+
+          activeThumbRef.current = getClosestThumbIndex(value);
+          setDragging(true);
+          moveTo(position, activeThumbRef.current);
+        })
+        // The move that activates the pan arrives as `onStart`, and every move
+        // after it as `onUpdate` — the thumb has to follow both.
+        .onStart(follow)
+        .onUpdate(follow)
+        .onFinalize(() => {
+          setDragging(false);
+          commitValue(createChangeEventDetails(REASONS.drag));
+        })
+        // The handlers touch React state, so they must not run on the UI thread.
+        .runOnJS(true),
+    [
+      disabled,
+      testID,
+      orientation,
+      follow,
+      getClosestThumbIndex,
+      getValueFromPosition,
+      moveTo,
+      setDragging,
+      commitValue,
+    ],
+  );
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [{ onLayout: handleLayout }, elementProps],
+  });
+
+  return <GestureDetector gesture={gesture}>{element}</GestureDetector>;
+}
+
+export interface SliderControlState extends SliderRootState {}
+
+export interface SliderControlProps
+  extends ZestUIComponentProps<typeof View, SliderControlState> {}
+
+export namespace SliderControl {
+  export type State = SliderControlState;
+  export type Props = SliderControlProps;
+}

package/src/slider/index.parts.ts

@@ -0,0 +1,7 @@
+export { SliderRoot as Root } from './root/SliderRoot';
+export { SliderLabel as Label } from './label/SliderLabel';
+export { SliderValue as Value } from './value/SliderValue';
+export { SliderControl as Control } from './control/SliderControl';
+export { SliderTrack as Track } from './track/SliderTrack';
+export { SliderIndicator as Indicator } from './indicator/SliderIndicator';
+export { SliderThumb as Thumb } from './thumb/SliderThumb';

package/src/slider/index.ts

@@ -0,0 +1,10 @@
+export * as Slider from './index.parts';
+
+export type * from './root/SliderRoot';
+export type * from './label/SliderLabel';
+export type * from './value/SliderValue';
+export type * from './control/SliderControl';
+export type * from './track/SliderTrack';
+export type * from './indicator/SliderIndicator';
+export type * from './thumb/SliderThumb';
+export { useSliderRootContext } from './root/SliderRootContext';

package/src/slider/indicator/SliderIndicator.tsx

@@ -0,0 +1,55 @@
+'use client';
+import { View } from 'react-native';
+import { useSliderRootContext } from '../root/SliderRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { SliderRootState } from '../root/SliderRoot';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * The filled portion of the track.
+ * Renders a `<View>` positioned to span the selected range.
+ */
+export function SliderIndicator(componentProps: SliderIndicator.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const { max, min, orientation, state, values } = useSliderRootContext();
+
+  // A single-thumb slider fills from the start; a range fills between thumbs.
+  const start = values.length > 1 ? Math.min(...values) : min;
+  const end = values.length > 1 ? Math.max(...values) : values[0]!;
+
+  const startPercent = toPercent(start, min, max);
+  const endPercent = toPercent(end, min, max);
+
+  const offset = `${startPercent}%` as const;
+  const size = `${endPercent - startPercent}%` as const;
+
+  const positionStyle =
+    orientation === 'vertical'
+      ? { position: 'absolute' as const, bottom: offset, height: size }
+      : { position: 'absolute' as const, left: offset, width: size };
+
+  return useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [{ style: positionStyle }, elementProps],
+  });
+}
+
+function toPercent(value: number, min: number, max: number) {
+  if (max === min) {
+    return 0;
+  }
+
+  return ((value - min) / (max - min)) * 100;
+}
+
+export interface SliderIndicatorState extends SliderRootState {}
+
+export interface SliderIndicatorProps
+  extends ZestUIComponentProps<typeof View, SliderIndicatorState> {}
+
+export namespace SliderIndicator {
+  export type State = SliderIndicatorState;
+  export type Props = SliderIndicatorProps;
+}

package/src/slider/label/SliderLabel.tsx

@@ -0,0 +1,44 @@
+'use client';
+import { Text } from 'react-native';
+import { useSliderRootContext } from '../root/SliderRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useId } from '../../hooks/useId';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
+import type { SliderRootState } from '../root/SliderRoot';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * An accessible label that is automatically associated with the slider thumbs.
+ * Renders a `<Text>`.
+ *
+ * Upstream also focuses a thumb when the label is pressed. React Native has no
+ * programmatic focus for a `View`, and the thumb is `accessibilityRole="adjustable"`
+ * already, so the association is expressed purely through `accessibilityLabelledBy`.
+ */
+export function SliderLabel(componentProps: SliderLabel.Props) {
+  const { render, className, style, nativeID: idProp, ref, ...elementProps } = componentProps;
+
+  const { setLabelId, state } = useSliderRootContext();
+
+  const id = useId(idProp ?? undefined);
+
+  useIsoLayoutEffect(() => {
+    setLabelId(id);
+    return () => setLabelId(undefined);
+  }, [id, setLabelId]);
+
+  return useRenderElement(Text, componentProps, {
+    state,
+    ref,
+    props: [{ nativeID: id }, elementProps],
+  });
+}
+
+export interface SliderLabelState extends SliderRootState {}
+
+export interface SliderLabelProps extends ZestUIComponentProps<typeof Text, SliderLabelState> {}
+
+export namespace SliderLabel {
+  export type State = SliderLabelState;
+  export type Props = SliderLabelProps;
+}

package/src/slider/root/SliderRoot.tsx

@@ -0,0 +1,328 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { useControlled } from '../../hooks/useControlled';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
+import { useStableCallback } from '../../hooks/useStableCallback';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { clamp } from '../../utils/clamp';
+import type { ZestUIComponentProps, Orientation } from '../../types';
+import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
+import type { REASONS } from '../../utils/reasons';
+import { SliderRootContext } from './SliderRootContext';
+
+/**
+ * Groups all parts of the slider.
+ * Renders a `<View>`.
+ *
+ * Drop the web-only props: `name`/`form` (React Native has no form submission),
+ * `largeStep` (a PageUp/PageDown affordance), and `thumbAlignment` (CSS).
+ */
+export function SliderRoot<Value extends number | readonly number[] = number>(
+  componentProps: SliderRoot.Props<Value>,
+) {
+  const {
+    className,
+    defaultValue,
+    disabled = false,
+    format,
+    locale,
+    max = 100,
+    min = 0,
+    minStepsBetweenValues = 0,
+    onValueChange,
+    onValueCommitted,
+    orientation = 'horizontal',
+    render,
+    step = 1,
+    style,
+    value,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  // A range slider is just a slider whose value is an array; remember which
+  // shape the consumer used so callbacks hand back the same one.
+  const isRange = Array.isArray(value ?? defaultValue);
+
+  const controlledValues = React.useMemo(
+    () => (value === undefined ? undefined : toArray(value)),
+    [value],
+  );
+  const defaultValues = React.useMemo(
+    () => (value !== undefined ? undefined : toArray(defaultValue ?? (min as Value))),
+    [value, defaultValue, min],
+  );
+
+  const [values, setValuesState] = useControlled<readonly number[]>({
+    controlled: controlledValues,
+    default: defaultValues,
+    name: 'Slider',
+    state: 'value',
+  });
+
+  const [dragging, setDragging] = React.useState(false);
+  const [controlSize, setControlSize] = React.useState<number | undefined>(undefined);
+  const [labelId, setLabelId] = React.useState<string | undefined>(undefined);
+
+  // A drag emits several changes in one synchronous batch — its final move and
+  // its finalize land before React re-renders — so the value logic cannot read
+  // `values` from render or it would work against the previous batch's state.
+  // The effect has no dependency array on purpose: it must also resync when a
+  // controlled consumer ignores a change, which re-renders nothing.
+  const valuesRef = React.useRef(values);
+  useIsoLayoutEffect(() => {
+    valuesRef.current = values;
+  });
+
+  const roundToStep = useStableCallback((raw: number) => {
+    const stepped = Math.round((raw - min) / step) * step + min;
+    // Steps like 0.1 accumulate float error; round to the step's precision.
+    const decimals = countDecimals(step);
+    const rounded = Number(stepped.toFixed(decimals));
+    return clamp(rounded, min, max);
+  });
+
+  const getValueFromPosition = useStableCallback((position: number) => {
+    // Nothing can be derived from a position until the control has reported its
+    // size; callers must bail rather than fall back to a value, or a touch
+    // landing before the first layout would snap the slider to `min`.
+    if (!controlSize) {
+      return undefined;
+    }
+
+    const ratio = clamp(position / controlSize, 0, 1);
+    // A vertical slider grows upwards, so its position axis is inverted.
+    const percent = orientation === 'vertical' ? 1 - ratio : ratio;
+
+    return roundToStep(min + percent * (max - min));
+  });
+
+  const getClosestThumbIndex = useStableCallback((target: number) => {
+    let closest = 0;
+    let smallestDistance = Number.POSITIVE_INFINITY;
+
+    valuesRef.current.forEach((thumbValue, index) => {
+      const distance = Math.abs(thumbValue - target);
+      if (distance < smallestDistance) {
+        smallestDistance = distance;
+        closest = index;
+      }
+    });
+
+    return closest;
+  });
+
+  const emit = useStableCallback(
+    (nextValues: readonly number[], eventDetails: SliderRoot.ChangeEventDetails) => {
+      onValueChange?.(fromArray(nextValues, isRange) as Value, eventDetails);
+
+      if (eventDetails.isCanceled) {
+        return;
+      }
+
+      valuesRef.current = nextValues;
+      setValuesState(nextValues);
+    },
+  );
+
+  const setThumbValue = useStableCallback(
+    (index: number, nextValue: number, eventDetails: SliderRoot.ChangeEventDetails) => {
+      if (disabled) {
+        return;
+      }
+
+      const current = valuesRef.current;
+
+      // Thumbs may not cross, and `minStepsBetweenValues` keeps a gap between them.
+      const gap = minStepsBetweenValues * step;
+      const lowerBound = index > 0 ? current[index - 1]! + gap : min;
+      const upperBound = index < current.length - 1 ? current[index + 1]! - gap : max;
+
+      const clamped = clamp(nextValue, lowerBound, upperBound);
+
+      if (clamped === current[index]) {
+        return;
+      }
+
+      const nextValues = current.slice();
+      nextValues[index] = clamped;
+
+      emit(nextValues, eventDetails);
+    },
+  );
+
+  const commitValue = useStableCallback((eventDetails: SliderRoot.ChangeEventDetails) => {
+    onValueCommitted?.(fromArray(valuesRef.current, isRange) as Value, eventDetails);
+  });
+
+  const state: SliderRootState = React.useMemo(
+    () => ({ disabled, dragging, max, min, orientation, values }),
+    [disabled, dragging, max, min, orientation, values],
+  );
+
+  const contextValue: SliderRootContext = React.useMemo(
+    () => ({
+      commitValue,
+      controlSize,
+      disabled,
+      dragging,
+      format,
+      getClosestThumbIndex,
+      getValueFromPosition,
+      labelId,
+      locale,
+      max,
+      min,
+      orientation,
+      setControlSize,
+      setDragging,
+      setLabelId,
+      setThumbValue,
+      state,
+      step,
+      values,
+    }),
+    [
+      commitValue,
+      controlSize,
+      disabled,
+      dragging,
+      format,
+      getClosestThumbIndex,
+      getValueFromPosition,
+      labelId,
+      locale,
+      max,
+      min,
+      orientation,
+      setThumbValue,
+      state,
+      step,
+      values,
+    ],
+  );
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [{ 'aria-orientation': orientation }, elementProps],
+  });
+
+  return <SliderRootContext.Provider value={contextValue}>{element}</SliderRootContext.Provider>;
+}
+
+function toArray(value: number | readonly number[]): readonly number[] {
+  return Array.isArray(value) ? value : [value as number];
+}
+
+function fromArray(values: readonly number[], isRange: boolean): number | readonly number[] {
+  return isRange ? values : values[0]!;
+}
+
+function countDecimals(value: number) {
+  const text = String(value);
+  const separator = text.indexOf('.');
+  return separator === -1 ? 0 : text.length - separator - 1;
+}
+
+export interface SliderRootState {
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * Whether a thumb is currently being dragged.
+   */
+  dragging: boolean;
+  /**
+   * The maximum allowed value.
+   */
+  max: number;
+  /**
+   * The minimum allowed value.
+   */
+  min: number;
+  /**
+   * The component orientation.
+   */
+  orientation: Orientation;
+  /**
+   * The current value of every thumb.
+   */
+  values: readonly number[];
+}
+
+export interface SliderRootProps<Value extends number | readonly number[] = number>
+  extends Omit<ZestUIComponentProps<typeof View, SliderRootState>, 'value'> {
+  /**
+   * The value of the slider. Pass an array for a range slider.
+   *
+   * To render an uncontrolled slider, use the `defaultValue` prop instead.
+   */
+  value?: Value | undefined;
+  /**
+   * The initial value of the slider.
+   *
+   * To render a controlled slider, use the `value` prop instead.
+   */
+  defaultValue?: Value | undefined;
+  /**
+   * Event handler called while a thumb is being dragged.
+   */
+  onValueChange?: ((value: Value, eventDetails: SliderRoot.ChangeEventDetails) => void) | undefined;
+  /**
+   * Event handler called once the drag ends.
+   */
+  onValueCommitted?:
+    | ((value: Value, eventDetails: SliderRoot.ChangeEventDetails) => void)
+    | undefined;
+  /**
+   * The minimum allowed value.
+   * @default 0
+   */
+  min?: number | undefined;
+  /**
+   * The maximum allowed value.
+   * @default 100
+   */
+  max?: number | undefined;
+  /**
+   * The granularity the value must adhere to.
+   * @default 1
+   */
+  step?: number | undefined;
+  /**
+   * The minimum number of steps to keep between the thumbs of a range slider.
+   * @default 0
+   */
+  minStepsBetweenValues?: number | undefined;
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+  /**
+   * @default 'horizontal'
+   */
+  orientation?: Orientation | undefined;
+  /**
+   * Options for formatting the value in `Slider.Value`.
+   */
+  format?: Intl.NumberFormatOptions | undefined;
+  /**
+   * The locale used to format the value in `Slider.Value`.
+   */
+  locale?: Intl.LocalesArgument | undefined;
+}
+
+export type SliderRootChangeEventReason = typeof REASONS.drag | typeof REASONS.none;
+
+export type SliderRootChangeEventDetails = ZestChangeEventDetails<SliderRootChangeEventReason>;
+
+export namespace SliderRoot {
+  export type State = SliderRootState;
+  export type Props<Value extends number | readonly number[] = number> = SliderRootProps<Value>;
+  export type ChangeEventReason = SliderRootChangeEventReason;
+  export type ChangeEventDetails = SliderRootChangeEventDetails;
+}

package/src/slider/root/SliderRootContext.ts

@@ -0,0 +1,62 @@
+'use client';
+import * as React from 'react';
+import type { Orientation } from '../../types';
+import type { SliderRoot, SliderRootState } from './SliderRoot';
+
+export interface SliderRootContext {
+  values: readonly number[];
+  min: number;
+  max: number;
+  step: number;
+  disabled: boolean;
+  orientation: Orientation;
+  dragging: boolean;
+  state: SliderRootState;
+  format: Intl.NumberFormatOptions | undefined;
+  locale: Intl.LocalesArgument | undefined;
+  /**
+   * The measured size of the control along its main axis, which is what turns a
+   * touch position into a value.
+   */
+  controlSize: number | undefined;
+  setControlSize: (size: number) => void;
+  setDragging: (dragging: boolean) => void;
+  /**
+   * The id of the `Slider.Label`, associated with every thumb. `undefined` when
+   * there is no label.
+   */
+  labelId: string | undefined;
+  setLabelId: (id: string | undefined) => void;
+  /**
+   * Commits a value for one thumb, clamped to the range and to its neighbours.
+   */
+  setThumbValue: (
+    index: number,
+    value: number,
+    eventDetails: SliderRoot.ChangeEventDetails,
+  ) => void;
+  /**
+   * Converts a position along the control into a value, or `undefined` while the
+   * control has not been measured yet.
+   */
+  getValueFromPosition: (position: number) => number | undefined;
+  /**
+   * The index of the thumb closest to a value, used to pick which thumb a drag
+   * should move.
+   */
+  getClosestThumbIndex: (value: number) => number;
+  commitValue: (eventDetails: SliderRoot.ChangeEventDetails) => void;
+}
+
+export const SliderRootContext = React.createContext<SliderRootContext | undefined>(undefined);
+
+export function useSliderRootContext() {
+  const context = React.useContext(SliderRootContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: SliderRootContext is missing. Slider parts must be placed within <Slider.Root>.',
+    );
+  }
+
+  return context;
+}