@tremolo-ui/react 0.8.0 → 0.9.0

package/src/components/PointsEditor/context.tsx

@@ -9,16 +9,15 @@ import {
 
 export type PointsEditorContextValue = {
   disabled: boolean
-  readonly: boolean
+  readOnly: boolean
   /** Inherited by every `Point`; `null` turns the wheel off. */
   wheel: ModifierValue<InputEventOption> | null
   /** Inherited by every `Point`; `null` turns the keyboard off. */
   keyboard: ModifierValue<InputEventOption> | null
   /** Inherited by every `Point`. See `PointsEditorProps.dragSensitivity`. */
   dragSensitivity: ModifierValue<number>
-  externalStyles: {
-    cursor?: CSSProperties['cursor']
-  }
+  /** Inherited by every `Point`. See `PointsEditorProps.dragCursor`. */
+  dragCursor: CSSProperties['cursor']
   /**
    * `Container` registers its element here; `Point` normalizes the pointer
    * against it, so a point is placed by its position within the container.

package/src/components/PointsEditor/index.tsx

@@ -14,10 +14,12 @@ import {
   DEFAULT_DRAG_SENSITIVITY,
   type InputEventOption,
   type ModifierValue,
-  POINTS_EDITOR_DEFAULT_KEYBOARD,
-  POINTS_EDITOR_DEFAULT_WHEEL,
   type SelectionBoxRect,
 } from '@tremolo-ui/dom'
+import {
+  POINTS_EDITOR_DEFAULT_KEYBOARD,
+  POINTS_EDITOR_DEFAULT_WHEEL,
+} from '@tremolo-ui/dom/internal'
 
 import { Background } from './Background'
 import { Container } from './Container'
@@ -38,17 +40,15 @@ export interface PointsEditorProps {
    * Make the points unmovable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean
+  readOnly?: boolean
 
   /**
    * The cursor to show while dragging a point. It is set on the dragged
    * point, so it stays while the pointer is outside it.
    *
-   * @default { cursor: 'grabbing' }
+   * @default 'grabbing'
    */
-  externalStyles?: {
-    cursor?: CSSProperties['cursor']
-  }
+  dragCursor?: CSSProperties['cursor']
 
   /**
    * How much one notch of the wheel moves the focused `Point`. Scrolling
@@ -155,7 +155,7 @@ export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   (
     {
       disabled = false,
-      readonly = false,
+      readOnly = false,
       wheel = POINTS_EDITOR_DEFAULT_WHEEL,
       keyboard = POINTS_EDITOR_DEFAULT_KEYBOARD,
       dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
@@ -163,7 +163,7 @@ export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
       selection: selectionProp,
       defaultSelection,
       onSelectionChange,
-      externalStyles,
+      dragCursor = 'grabbing',
       style,
       className,
       children,
@@ -174,7 +174,6 @@ export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
     const containerRef = useRef<HTMLDivElement>(null)
     // Picked apart so that the memo below depends on values rather than on the
     // object literal a caller writes inline, which is new on every render.
-    const { cursor = 'grabbing' } = externalStyles ?? {}
 
     // --- selection ---
     // The selection lives here, where React state can hold it; which points a
@@ -214,11 +213,11 @@ export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
     const context = useMemo(
       () => ({
         disabled,
-        readonly,
+        readOnly,
         wheel,
         keyboard,
         dragSensitivity,
-        externalStyles: { cursor },
+        dragCursor,
         containerRef,
         selectable,
         selection,
@@ -227,11 +226,11 @@ export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
       }),
       [
         disabled,
-        readonly,
+        readOnly,
         wheel,
         keyboard,
         dragSensitivity,
-        cursor,
+        dragCursor,
         selectable,
         selection,
         editor,
@@ -245,7 +244,7 @@ export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
           ref={forwardedRef}
           className={className}
           data-disabled={disabled ? '' : undefined}
-          data-readonly={readonly ? '' : undefined}
+          data-readonly={readOnly ? '' : undefined}
           style={
             {
               // The layers inside are placed against this box.

package/src/components/Slider/Marks.tsx

@@ -1,6 +1,7 @@
 import { ComponentPropsWithoutRef, CSSProperties } from 'react'
 
-import { cssLength, type MarksOptions, sliderMarks } from '@tremolo-ui/dom'
+import { type MarksOptions } from '@tremolo-ui/dom'
+import { cssLength, sliderMarks } from '@tremolo-ui/dom/internal'
 
 import { Placement } from '../_util/Placement'
 
@@ -40,7 +41,7 @@ export function Marks({
   const min = useSliderContext((s) => s.min)
   const max = useSliderContext((s) => s.max)
   const step = useSliderContext((s) => s.step)
-  const vertical = useSliderContext((s) => s.vertical)
+  const vertical = useSliderContext((s) => s.orientation === 'vertical')
   const reverse = useSliderContext((s) => s.reverse)
 
   const optionsList = options ? sliderMarks(options, min, max, step) : []

package/src/components/Slider/MarksOption.tsx

@@ -1,6 +1,7 @@
 import { ComponentPropsWithoutRef, CSSProperties } from 'react'
 
-import { cssLength, valuePercent } from '@tremolo-ui/dom'
+import { valuePercent } from '@tremolo-ui/dom'
+import { cssLength } from '@tremolo-ui/dom/internal'
 
 import { useCheckPlacement } from '../_util/Placement'
 
@@ -62,7 +63,7 @@ export function MarksOption({
   const min = useSliderContext((s) => s.min)
   const max = useSliderContext((s) => s.max)
   const scale = useSliderContext((s) => s.scale)
-  const vertical = useSliderContext((s) => s.vertical)
+  const vertical = useSliderContext((s) => s.orientation === 'vertical')
   const reverse = useSliderContext((s) => s.reverse)
 
   // The marks have to sit on the same curve the thumb runs along.

package/src/components/Slider/Thumb.tsx

@@ -1,9 +1,10 @@
 import {
   ComponentPropsWithoutRef,
+  CSSProperties,
   forwardRef,
+  Ref,
   useImperativeHandle,
   useRef,
-  CSSProperties,
 } from 'react'
 
 import { useCheckPlacement } from '../_util/Placement'
@@ -22,6 +23,12 @@ export interface SliderThumbProps {
   color?: string
 
   style?: CSSProperties & CSSVariables<'color' | 'translate'>
+
+  /**
+   * Receives `focus` and `blur` for the range input inside, which do nothing
+   * while the slider is disabled. `ref` reaches the thumb element itself.
+   */
+  actionsRef?: Ref<SliderThumbMethods>
 }
 
 export interface SliderThumbMethods {
@@ -32,7 +39,7 @@ export interface SliderThumbMethods {
 type Props = SliderThumbProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof SliderThumbProps>
 
-export const Thumb = /* @__PURE__ */ forwardRef<SliderThumbMethods, Props>(
+export const Thumb = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   function Thumb(
     {
       color,
@@ -48,6 +55,7 @@ export const Thumb = /* @__PURE__ */ forwardRef<SliderThumbMethods, Props>(
       'aria-labelledby': ariaLabelledby,
       'aria-describedby': ariaDescribedby,
       'aria-valuetext': ariaValuetext,
+      actionsRef,
       ...props
     },
     forwardedRef,
@@ -58,9 +66,9 @@ export const Thumb = /* @__PURE__ */ forwardRef<SliderThumbMethods, Props>(
       min,
       max,
       step,
-      vertical,
+      orientation,
       disabled,
-      readonly,
+      readOnly,
       onChange,
       percent,
       thumbRef,
@@ -78,15 +86,16 @@ export const Thumb = /* @__PURE__ */ forwardRef<SliderThumbMethods, 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 },
@@ -101,8 +110,8 @@ export const Thumb = /* @__PURE__ */ forwardRef<SliderThumbMethods, Props>(
           // Where the thumb sits is the component's decision, not a style: a
           // `left` from the caller would take it off the track, so it is
           // written after theirs.
-          top: vertical ? `${percent}%` : '50%',
-          left: !vertical ? `${percent}%` : '50%',
+          top: orientation === 'vertical' ? `${percent}%` : '50%',
+          left: orientation === 'vertical' ? '50%' : `${percent}%`,
         }}
       >
         <VisuallyHiddenRangeInput
@@ -112,14 +121,14 @@ export const Thumb = /* @__PURE__ */ forwardRef<SliderThumbMethods, Props>(
           max={max}
           step={step}
           disabled={disabled}
-          aria-readonly={readonly}
-          aria-orientation={vertical ? 'vertical' : 'horizontal'}
+          aria-readonly={readOnly}
+          aria-orientation={orientation}
           aria-label={ariaLabel}
           aria-labelledby={ariaLabelledby}
           aria-describedby={ariaDescribedby}
           aria-valuetext={ariaValuetext}
           onChange={(event) => {
-            if (readonly) {
+            if (readOnly) {
               event.currentTarget.value = String(value)
               return
             }

package/src/components/Slider/Track.tsx

@@ -1,6 +1,6 @@
 import { ComponentPropsWithoutRef, CSSProperties, forwardRef } from 'react'
 
-import { cssLength } from '@tremolo-ui/dom'
+import { cssLength } from '@tremolo-ui/dom/internal'
 
 import { useComposedRefs } from '../../compose-refs'
 import { Placement } from '../_util/Placement'
@@ -18,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 &
@@ -35,8 +37,8 @@ export const Track = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
     {
       length,
       thickness,
-      active,
-      inactive,
+      activeColor,
+      inactiveColor,
       children,
       className,
       style,
@@ -44,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
@@ -56,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,22 +11,26 @@ import React, {
 } from 'react'
 
 import {
-  applyDelta,
-  arrowKeyDirection,
   type AxisOptions,
+  type ChangeSource,
   DEFAULT_DRAG_SENSITIVITY,
   DEFAULT_KEYBOARD_OPTIONS,
   DEFAULT_WHEEL_OPTIONS,
   type InputEventOption,
   type ModifierValue,
-  selectModifier,
   valuePercent,
-  wheelDirection,
   type XY,
 } from '@tremolo-ui/dom'
+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'
@@ -36,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
@@ -66,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
@@ -84,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
@@ -145,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.
@@ -164,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 {
@@ -180,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,
@@ -188,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,
@@ -206,6 +229,7 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
       onBlur,
       onPointerDown,
       onKeyDown,
+      actionsRef,
       ...props
     }: Props,
     forwardedRef,
@@ -214,14 +238,14 @@ 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
 
     // Measured from the left or the top, as CSS places things:
     // normal -> normal (right)
     // vertical -> reversed (up)
     // reverse -> reversed (left)
     // vertical & reverse -> normal (down)
+    const vertical = orientation === 'vertical'
     const displayReversed = vertical !== reverse
     const percent = valuePercent(value, { min, max, scale }, displayReversed)
 
@@ -236,13 +260,27 @@ 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 direction = arrowKeyDirection(event.key)
         if (direction === null) return
         event.preventDefault()
         if (!keyboard || !onChange || inactive) return
-        onChange(
+        gesture.pulse('keyboard')
+        change(
           applyDelta(
             value,
             reverse ? -direction : direction,
@@ -252,7 +290,7 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
           ),
         )
       },
-      [keyboard, onChange, inactive, reverse, value, axis],
+      [keyboard, onChange, inactive, reverse, value, axis, gesture, change],
     )
 
     // --- hooks ---
@@ -261,24 +299,21 @@ 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) => {
@@ -288,7 +323,8 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
       const direction = wheelDirection(event, { horizontal: !vertical })
       if (direction === null) return
       event.preventDefault()
-      onChange(
+      gesture.pulse('wheel')
+      change(
         applyDelta(value, reverse ? -direction : direction, wheel, axis, event),
       )
     }, WHEEL_OPTIONS)
@@ -296,6 +332,7 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
     // 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,
     )
@@ -307,10 +344,10 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
         max,
         step,
         scale,
-        vertical,
+        orientation,
         reverse,
         disabled,
-        readonly,
+        readOnly,
         onChange,
         percent,
         trackRef,
@@ -322,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()
@@ -354,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) => {