@tremolo-ui/react 0.7.0 → 0.9.0

package/src/components/Slider/Track.tsx

@@ -1,7 +1,8 @@
 import { ComponentPropsWithoutRef, CSSProperties, forwardRef } from 'react'
 
+import { cssLength } from '@tremolo-ui/dom/internal'
+
 import { useComposedRefs } from '../../compose-refs'
-import { cssLength } from '../_util/css-length'
 import { Placement } from '../_util/Placement'
 
 import { useSliderContext } from './context'
@@ -17,13 +18,15 @@ export interface SliderTrackProps {
   /** How thick the track is across that axis. Sets `--thickness`. */
   thickness?: number | string
 
-  /** Colour of the part from `min` to the value. Sets `--active`. */
-  active?: string
-  /** Colour of the rest of the track. Sets `--inactive`. */
-  inactive?: string
+  /** Colour of the part from `min` to the value. Sets `--active-color`. */
+  activeColor?: string
+  /** Colour of the rest of the track. Sets `--inactive-color`. */
+  inactiveColor?: string
 
   style?: CSSProperties &
-    CSSVariables<'length' | 'thickness' | 'active' | 'inactive' | 'percent'>
+    CSSVariables<
+      'length' | 'thickness' | 'active-color' | 'inactive-color' | 'percent'
+    >
 }
 
 type Props = SliderTrackProps &
@@ -34,8 +37,8 @@ export const Track = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
     {
       length,
       thickness,
-      active,
-      inactive,
+      activeColor,
+      inactiveColor,
       children,
       className,
       style,
@@ -43,7 +46,7 @@ export const Track = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
     },
     forwardedRef,
   ) {
-    const { vertical, reverse, disabled, percent, trackRef } =
+    const { orientation, reverse, disabled, percent, trackRef } =
       useSliderContext()
 
     // The track is what the pointer position is normalized against, so the
@@ -55,14 +58,14 @@ export const Track = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
         ref={composedRef}
         className={className}
         data-disabled={disabled ? '' : undefined}
-        data-orientation={vertical ? 'vertical' : 'horizontal'}
+        data-orientation={orientation}
         // Which end the value grows from. `percent` is already the position on
         // screen, so this only says which side of it is the filled one.
-        data-flipped={vertical !== reverse ? '' : undefined}
+        data-flipped={(orientation === 'vertical') !== reverse ? '' : undefined}
         style={
           {
-            '--active': active,
-            '--inactive': inactive,
+            '--active-color': activeColor,
+            '--inactive-color': inactiveColor,
             '--length': cssLength(length),
             '--thickness': cssLength(thickness),
             // Where the value sits, for the theme to paint the fill with. The

package/src/components/Slider/context.tsx

@@ -11,14 +11,14 @@ export type SliderContextValue = {
   step: number
   /** How the value is distributed across the travel. */
   scale: Scale
-  vertical: boolean
+  orientation: 'horizontal' | 'vertical'
   reverse: boolean
   disabled: boolean
-  readonly: boolean
+  readOnly: boolean
   onChange?: (value: number) => void
   /**
    * Position of the thumb, 0-100, already accounting for the display direction
-   * implied by `vertical` and `reverse`.
+   * implied by `orientation` and `reverse`.
    */
   percent: number
 

package/src/components/Slider/index.tsx

@@ -3,6 +3,7 @@ import React, {
   CSSProperties,
   forwardRef,
   ReactNode,
+  Ref,
   useCallback,
   useImperativeHandle,
   useMemo,
@@ -10,24 +11,29 @@ import React, {
 } from 'react'
 
 import {
-  applyDelta,
   type AxisOptions,
+  type ChangeSource,
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
   type InputEventOption,
   type ModifierValue,
-  selectModifier,
+  valuePercent,
   type XY,
 } from '@tremolo-ui/dom'
-import { linearScale, type Scale, toFixed } from '@tremolo-ui/functions'
+import {
+  applyDelta,
+  arrowKeyDirection,
+  selectModifier,
+  wheelDirection,
+} from '@tremolo-ui/dom/internal'
+import { linearScale, type Scale } from '@tremolo-ui/functions'
 
 import { useComposedRefs } from '../../compose-refs'
+import { useChangeGesture } from '../../hooks/_internal/useChangeGesture'
 import { useCheckSteps } from '../../hooks/_internal/useCheckSteps'
 import { useDragValue } from '../../hooks/useDragValue'
 import { useWheel } from '../../hooks/useWheel'
-import {
-  DEFAULT_DRAG_SENSITIVITY,
-  DEFAULT_KEYBOARD_OPTIONS,
-  DEFAULT_WHEEL_OPTIONS,
-} from '../../input-event'
 
 import { SliderProvider } from './context'
 import { Marks } from './Marks'
@@ -35,10 +41,6 @@ import { MarksOption } from './MarksOption'
 import { Thumb, SliderThumbMethods } from './Thumb'
 import { Track } from './Track'
 
-const defaultExternalStyles: SliderProps['externalStyles'] = {
-  cursor: 'pointer',
-}
-
 export interface SliderProps {
   /** The current value. The slider shows only this, so update it from `onChange`. */
   value: number
@@ -65,14 +67,15 @@ export interface SliderProps {
    */
   scale?: Scale
   /**
-   * Run the slider vertically, with the value growing upwards. The range input
-   * inside the thumb takes its `aria-orientation` from this.
+   * Which way the slider runs. A vertical slider grows upwards. Every part
+   * carries the same value as `data-orientation`, and the range input inside
+   * the thumb takes its `aria-orientation` from it.
    *
-   * @default false
+   * @default 'horizontal'
    */
-  vertical?: boolean
+  orientation?: 'horizontal' | 'vertical'
   /**
-   * Grow the value the other way: leftwards, or downwards when `vertical`.
+   * Grow the value the other way: leftwards, or downwards when vertical.
    * The arrow keys follow the direction on screen.
    *
    * @default false
@@ -83,11 +86,9 @@ export interface SliderProps {
    * The cursor to show while dragging. It is set on the dragged element, so it
    * stays while the pointer is outside the slider.
    *
-   * @default { cursor: 'pointer' }
+   * @default 'pointer'
    */
-  externalStyles?: {
-    cursor?: CSSProperties['cursor']
-  }
+  dragCursor?: CSSProperties['cursor']
   /**
    * How much one notch of the wheel moves the value. It only acts while the
    * focus is inside, so that scrolling the page past the slider leaves it
@@ -144,13 +145,28 @@ export interface SliderProps {
    * Make the value unchangeable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean
+  readOnly?: boolean
   /** Called with the new value when a drag, the wheel or an arrow key moves it. */
   onChange?: (value: number) => void
-  /** Called when a drag starts, with the value where the track was pressed. */
-  onDragStart?: (value: number) => void
-  /** Called when the drag ends, with the value it ended on. */
-  onDragEnd?: (value: number) => void
+  /**
+   * Called when a change of the value starts — a press on the track, the first wheel notch
+   * or arrow key — with the value
+   * before it and what it is made with. A host recording automation can treat
+   * the control as touched from here until `onChangeEnd`.
+   */
+  onChangeStart?: (value: number, source: ChangeSource) => void
+  /**
+   * Called when the change ends, with the value it ended on: on release, or
+   * `changeEndDelay` after the last wheel notch or arrow key.
+   */
+  onChangeEnd?: (value: number, source: ChangeSource) => void
+  /**
+   * How long after the last wheel notch or arrow key the change counts as
+   * over, in milliseconds. Neither has an event that says it is done.
+   *
+   * @default 500
+   */
+  changeEndDelay?: number
   /**
    * The slider renders exactly what you compose here; there is no default
    * markup to fall back to.
@@ -163,6 +179,13 @@ export interface SliderProps {
    * </Slider.Root>
    */
   children: ReactNode
+
+  /**
+   * Receives `focus` and `blur`, which act on the range input inside the thumb —
+   * the element that takes the focus — and do nothing while the slider is
+   * disabled. `ref` reaches the root element itself.
+   */
+  actionsRef?: Ref<SliderMethods>
 }
 
 export interface SliderMethods {
@@ -179,7 +202,7 @@ type Props = SliderProps &
  */
 const WHEEL_OPTIONS = { requireFocus: true }
 
-export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   (
     {
       value,
@@ -187,17 +210,18 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
       max,
       step = 1,
       scale = linearScale,
-      vertical = false,
+      orientation = 'horizontal',
       reverse = false,
-      externalStyles: _externalStyles,
+      dragCursor = 'pointer',
       wheel = DEFAULT_WHEEL_OPTIONS,
       keyboard = DEFAULT_KEYBOARD_OPTIONS,
       dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
       disabled = false,
-      readonly = false,
+      readOnly = false,
       onChange,
-      onDragStart,
-      onDragEnd,
+      onChangeStart,
+      onChangeEnd,
+      changeEndDelay,
       className,
       style,
       children,
@@ -205,6 +229,7 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
       onBlur,
       onPointerDown,
       onKeyDown,
+      actionsRef,
       ...props
     }: Props,
     forwardedRef,
@@ -213,18 +238,16 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
     const trackRef = useRef<HTMLDivElement>(null)
     const thumbRef = useRef<SliderThumbMethods>(null)
     // --- interpret props ---
-    const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
-    const inactive = disabled || readonly
+    const inactive = disabled || readOnly
 
-    const p = toFixed(scale.normalize(value, min, max) * 100)
-    const rev = toFixed(100 - p)
-    // NOTE
+    // Measured from the left or the top, as CSS places things:
     // normal -> normal (right)
-    // vertical -> rev (up)
-    // reverse -> rev (left)
+    // vertical -> reversed (up)
+    // reverse -> reversed (left)
     // vertical & reverse -> normal (down)
+    const vertical = orientation === 'vertical'
     const displayReversed = vertical !== reverse
-    const percent = displayReversed ? rev : p
+    const percent = valuePercent(value, { min, max, scale }, displayReversed)
 
     // --- internal functions ---
     // The pointer is normalized against the track on both axes; only the one
@@ -237,18 +260,37 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
 
     useCheckSteps({ component: 'Slider', range: axis, keyboard, wheel })
 
+    const gesture = useChangeGesture(
+      value,
+      { onChangeStart, onChangeEnd, changeEndDelay },
+      inactive,
+    )
+    const change = useCallback(
+      (next: number) => {
+        gesture.changed(next)
+        onChange?.(next)
+      },
+      [gesture, onChange],
+    )
+
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLDivElement>) => {
-        const key = event.key
-        if (!['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key))
-          return
+        const direction = arrowKeyDirection(event.key)
+        if (direction === null) return
         event.preventDefault()
         if (!keyboard || !onChange || inactive) return
-        let direction = key === 'ArrowRight' || key === 'ArrowUp' ? 1 : -1
-        if (reverse) direction *= -1
-        onChange(applyDelta(value, direction, keyboard, axis, event))
+        gesture.pulse('keyboard')
+        change(
+          applyDelta(
+            value,
+            reverse ? -direction : direction,
+            keyboard,
+            axis,
+            event,
+          ),
+        )
       },
-      [keyboard, onChange, inactive, reverse, value, axis],
+      [keyboard, onChange, inactive, reverse, value, axis, gesture, change],
     )
 
     // --- hooks ---
@@ -257,43 +299,40 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
     const { refCallback: dragRefCallback } = useDragValue<HTMLDivElement>({
       axis,
       baseElementRef: trackRef,
-      cursor: inactive ? undefined : externalStyles.cursor,
+      cursor: inactive ? undefined : dragCursor,
       shouldStart: () => !inactive,
       sensitivity: (state) =>
         selectModifier(dragSensitivity, state.event).value,
       updateOnPointerDown: true,
       onChange: (v) => {
         if (inactive) return
-        onChange?.(valueOf(v))
+        change(valueOf(v))
       },
-      onDragStart: (v) => {
+      onDragStart: () => {
         if (inactive) return
+        gesture.hold('pointer')
         thumbRef.current?.focus()
-        onDragStart?.(valueOf(v))
-      },
-      onDragEnd: (v) => {
-        if (inactive) return
-        onDragEnd?.(valueOf(v))
       },
+      onDragEnd: () => gesture.end(),
     })
 
     const wheelRefCallback = useWheel<HTMLDivElement>((event) => {
       if (!wheel || !onChange || inactive) return
+      // A notch the slider does not read — a sideways scroll on a vertical
+      // slider — is left to the page rather than swallowed.
+      const direction = wheelDirection(event, { horizontal: !vertical })
+      if (direction === null) return
       event.preventDefault()
-      let direction
-      if (!vertical && event.deltaX !== 0) {
-        direction = event.deltaX > 0 ? 1 : -1
-      } else {
-        if (event.deltaY === 0) return
-        direction = event.deltaY > 0 ? -1 : 1
-      }
-      if (reverse) direction *= -1
-      onChange(applyDelta(value, direction, wheel, axis, event))
+      gesture.pulse('wheel')
+      change(
+        applyDelta(value, reverse ? -direction : direction, wheel, axis, event),
+      )
     }, WHEEL_OPTIONS)
 
     // Composed once, so React attaches the refs a single time instead of
     // detaching and re-attaching on every render.
     const rootRefCallback = useComposedRefs<HTMLDivElement>(
+      forwardedRef,
       dragRefCallback,
       wheelRefCallback,
     )
@@ -305,10 +344,10 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
         max,
         step,
         scale,
-        vertical,
+        orientation,
         reverse,
         disabled,
-        readonly,
+        readOnly,
         onChange,
         percent,
         trackRef,
@@ -320,16 +359,16 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
         max,
         step,
         scale,
-        vertical,
+        orientation,
         reverse,
         disabled,
-        readonly,
+        readOnly,
         onChange,
         percent,
       ],
     )
 
-    useImperativeHandle(forwardedRef, () => {
+    useImperativeHandle(actionsRef, () => {
       return {
         focus() {
           if (!disabled) thumbRef.current?.focus()
@@ -352,9 +391,9 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
           // body — undoing the focus the drag just gave the input. Taking the
           // focus here keeps it inside, and `onFocus` passes it to the input.
           tabIndex={-1}
-          data-orientation={vertical ? 'vertical' : 'horizontal'}
+          data-orientation={orientation}
           data-disabled={disabled ? '' : undefined}
-          data-readonly={readonly ? '' : undefined}
+          data-readonly={readOnly ? '' : undefined}
           style={style}
           onPointerDown={onPointerDown}
           onKeyDown={(event) => {
@@ -394,4 +433,3 @@ export { type SliderThumbMethods, type SliderThumbProps } from './Thumb'
 export { type SliderTrackProps } from './Track'
 export { type SliderMarksProps } from './Marks'
 export { type SliderMarksOptionProps } from './MarksOption'
-export { type MarksOptions } from './type'

package/src/components/XYPad/Area.tsx

@@ -1,56 +1,34 @@
 import { ComponentPropsWithoutRef, CSSProperties, forwardRef } from 'react'
 
 import { useComposedRefs } from '../../compose-refs'
-import { cssLength } from '../_util/css-length'
 import { Placement } from '../_util/Placement'
 
 import { useXYPadContext } from './context'
 
-import type { CSSVariables } from '../../css-variables'
-
-export interface XYPadAreaProps {
-  /** Sets `--width`; the size the theme gives it stands when omitted. */
-  width?: number | string
-  /** Sets `--height`; the size the theme gives it stands when omitted. */
-  height?: number | string
-  /** Sets `--color`, for the theme to colour the area with. */
-  color?: string
-
-  style?: CSSProperties & CSSVariables<'width' | 'height' | 'color'>
-}
-
-type Props = XYPadAreaProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadAreaProps>
-
-export const Area = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
-  function Area(
-    { width, height, color, children, className, style, ...props },
-    forwardedRef,
-  ) {
-    const { areaRef } = useXYPadContext()
-
-    // The area is what the pointer position is normalized against, so the
-    // context ref is composed with any ref the caller passed.
-    const composedRef = useComposedRefs<HTMLDivElement>(forwardedRef, areaRef)
-
-    return (
-      <div
-        ref={composedRef}
-        className={className}
-        style={
-          {
-            '--color': color,
-            '--width': cssLength(width),
-            '--height': cssLength(height),
-            // The thumb inside is placed against this box.
-            position: 'relative',
-            ...style,
-          } as CSSProperties
-        }
-        {...props}
-      >
-        <Placement name="XYPad.Area">{children}</Placement>
-      </div>
-    )
-  },
-)
+export const Area = /* @__PURE__ */ forwardRef<
+  HTMLDivElement,
+  ComponentPropsWithoutRef<'div'>
+>(function Area({ children, className, style, ...props }, forwardedRef) {
+  const { areaRef } = useXYPadContext()
+
+  // The area is what the pointer position is normalized against, so the
+  // context ref is composed with any ref the caller passed.
+  const composedRef = useComposedRefs<HTMLDivElement>(forwardedRef, areaRef)
+
+  return (
+    <div
+      ref={composedRef}
+      className={className}
+      style={
+        {
+          // The thumb inside is placed against this box.
+          position: 'relative',
+          ...style,
+        } as CSSProperties
+      }
+      {...props}
+    >
+      <Placement name="XYPad.Area">{children}</Placement>
+    </div>
+  )
+})

package/src/components/XYPad/Thumb.tsx

@@ -1,16 +1,20 @@
 import {
   AriaAttributes,
   ComponentPropsWithoutRef,
+  CSSProperties,
   forwardRef,
+  Ref,
   useImperativeHandle,
   useRef,
-  CSSProperties,
 } from 'react'
 
+import { type XYInput } from '@tremolo-ui/dom'
+import { toXY } from '@tremolo-ui/dom/internal'
+
 import { useCheckPlacement } from '../_util/Placement'
 import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
 
-import { toXY, useXYPadContext, type XYInput } from './context'
+import { useXYPadContext } from './context'
 
 import type { CSSVariables } from '../../css-variables'
 
@@ -39,6 +43,12 @@ export interface XYPadThumbProps {
   'aria-valuetext'?: XYInput<AriaAttributes['aria-valuetext']>
 
   style?: CSSProperties & CSSVariables<'color' | 'translate'>
+
+  /**
+   * Receives `focus` and `blur` for the range inputs inside, which do nothing
+   * while the pad is disabled. `ref` reaches the thumb element itself.
+   */
+  actionsRef?: Ref<XYPadThumbMethods>
 }
 
 export interface XYPadThumbMethods {
@@ -49,7 +59,7 @@ export interface XYPadThumbMethods {
 type Props = XYPadThumbProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadThumbProps>
 
-export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
+export const Thumb = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   function Thumb(
     {
       color,
@@ -60,6 +70,7 @@ export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
       'aria-labelledby': ariaLabelledby,
       'aria-describedby': ariaDescribedby,
       'aria-valuetext': ariaValuetext,
+      actionsRef,
       ...props
     },
     forwardedRef,
@@ -72,7 +83,7 @@ export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
       max,
       step,
       disabled,
-      readonly,
+      readOnly,
       onChange,
       percent,
       thumbRef,
@@ -97,15 +108,16 @@ export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
       },
     })
 
-    useImperativeHandle(forwardedRef, methods, [disabled])
+    useImperativeHandle(actionsRef, methods, [disabled])
     // Root focuses the thumb when a drag starts, wherever the user placed it.
     useImperativeHandle(thumbRef, methods, [disabled])
 
     return (
       <div
+        ref={forwardedRef}
         className={className}
         data-disabled={disabled ? '' : undefined}
-        data-readonly={readonly ? '' : undefined}
+        data-readonly={readOnly ? '' : undefined}
         {...props}
         style={{
           ...{ '--color': color },
@@ -133,14 +145,14 @@ export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
             max={max[axis]}
             step={step[axis]}
             disabled={disabled}
-            aria-readonly={readonly}
+            aria-readonly={readOnly}
             aria-orientation={axis === 0 ? 'horizontal' : 'vertical'}
             aria-label={labels[axis] ?? (axis === 0 ? 'x' : 'y')}
             aria-labelledby={labelledby[axis]}
             aria-describedby={describedby[axis]}
             aria-valuetext={valueText[axis]}
             onChange={(event) => {
-              if (readonly) {
+              if (readOnly) {
                 event.currentTarget.value = String(value[axis])
                 return
               }

package/src/components/XYPad/context.tsx

@@ -1,12 +1,10 @@
 import { createContext, RefObject, useContext } from 'react'
 
-import { toXY, type XY, type XYInput } from '@tremolo-ui/dom'
+import { type XY } from '@tremolo-ui/dom'
 import type { Scale } from '@tremolo-ui/functions'
 
 import type { XYPadThumbMethods } from './Thumb'
 
-export { toXY, type XY, type XYInput }
-
 export type XYPadContextValue = {
   value: XY<number>
   min: XY<number>
@@ -16,7 +14,7 @@ export type XYPadContextValue = {
   scale: XY<Scale>
   reverse: XY<boolean>
   disabled: boolean
-  readonly: boolean
+  readOnly: boolean
   onChange?: (value: XY<number>) => void
 
   /**