@tremolo-ui/react 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tremolo-ui/react",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "React component library for audio app",
   "type": "module",
   "sideEffects": false,
@@ -22,18 +22,18 @@
     "clean:sb": "rimraf ./storybook-static"
   },
   "devDependencies": {
-    "@storybook/addon-a11y": "10.6.0",
-    "@storybook/addon-docs": "10.6.0",
-    "@storybook/addon-links": "10.6.0",
-    "@storybook/react-vite": "10.6.0",
+    "@storybook/addon-a11y": "10.6.1",
+    "@storybook/addon-docs": "10.6.1",
+    "@storybook/addon-links": "10.6.1",
+    "@storybook/react-vite": "10.6.1",
     "@testing-library/jest-dom": "7.0.1",
     "@testing-library/react": "16.3.3",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
-    "jotai": "3.0.0",
+    "jotai": "3.0.1",
     "react": "19.3.0",
     "react-dom": "19.3.0",
-    "storybook": "10.6.0",
+    "storybook": "10.6.1",
     "tone": "15.1.22"
   },
   "peerDependencies": {
@@ -41,8 +41,8 @@
     "react-dom": "^18 || ^19"
   },
   "dependencies": {
-    "@tremolo-ui/dom": "^0.8.0",
-    "@tremolo-ui/functions": "^0.8.0"
+    "@tremolo-ui/dom": "0.9.0",
+    "@tremolo-ui/functions": "^0.9.0"
   },
   "files": [
     "dist",

package/src/components/AnimationCanvas/index.tsx

@@ -9,26 +9,12 @@ import {
 import {
   createAnimationCanvas,
   type AnimationCanvasInstance,
-  type AnimationFrame,
+  type CanvasDrawFunction,
+  type CanvasInitFunction,
 } from '@tremolo-ui/dom'
 
 import { useComposedRefs } from '../../compose-refs'
 
-export type InitFunction = (
-  context: CanvasRenderingContext2D,
-  option: {
-    /** current canvas width */
-    width: number
-    /** current canvas height */
-    height: number
-  },
-) => void
-
-export type DrawFunction = (
-  context: CanvasRenderingContext2D,
-  option: AnimationFrame,
-) => void
-
 export interface AnimationCanvasCommonProps {
   /**
    * Draw one frame. It is given the 2D context and the frame: the size in CSS
@@ -37,12 +23,12 @@ export interface AnimationCanvasCommonProps {
    * A new function replaces the old one in place, so writing it inline does
    * not restart anything.
    */
-  draw: DrawFunction
+  draw: CanvasDrawFunction
   /**
    * Called once before the first frame, with the context and the size in CSS
    * pixels. Set up what every frame shares here.
    */
-  init?: InitFunction
+  init?: CanvasInitFunction
   /**
    * Redraw on every animation frame. Turn it off to draw only when there is a
    * reason to: when the canvas mounts, when it is resized, and when the

package/src/components/FileInput/index.tsx

@@ -7,7 +7,10 @@ import {
   useMemo,
 } from 'react'
 
-import { partitionByAccept, visuallyHiddenStyle } from '@tremolo-ui/dom'
+import {
+  partitionByAccept,
+  visuallyHiddenStyle,
+} from '@tremolo-ui/dom/internal'
 
 import { FileInputProvider } from './context'
 import { Trigger } from './Trigger'

package/src/components/Knob/Thumb.tsx

@@ -12,46 +12,46 @@ export interface KnobThumbProps {
    * Fill colour of the circle.
    * @default 'currentColor'
    */
-  thumb?: string
+  color?: string
   /**
    * Colour of the line that points at the value.
    * @default 'currentColor'
    */
-  thumbLine?: string
+  lineColor?: string
   /**
    * Diameter of the circle, as a percentage of the knob.
    * @default 84
    */
-  thumbSize?: number
+  size?: number
   /**
    * Thickness of the line, as a percentage of the knob.
    * @default 6
    */
-  thumbLineWeight?: number
+  lineWeight?: number
   /**
    * How far down the line reaches, as a percentage of the knob from its top.
    * The line starts at the edge of the circle.
    * @default 35
    */
-  thumbLineLength?: number
+  lineLength?: number
 
   /**
-   * Classes for what the thumb draws inside itself: `thumbLine` is the line
-   * that points at the value.
+   * Classes for what the thumb draws inside itself: `line` is the line that
+   * points at the value.
    */
   classes?: {
-    thumbLine?: string
+    line?: string
   }
 }
 
 export function Thumb({
   className,
 
-  thumb = 'currentColor',
-  thumbLine = 'currentColor',
-  thumbSize = 84,
-  thumbLineWeight = 6,
-  thumbLineLength = 35,
+  color = 'currentColor',
+  lineColor = 'currentColor',
+  size = 84,
+  lineWeight = 6,
+  lineLength = 35,
   classes,
 
   ...props
@@ -65,15 +65,15 @@ export function Thumb({
 
   return (
     <svg className={className} {...props}>
-      <circle cx="50%" cy="50%" r={`${thumbSize / 2}%`} fill={thumb} />
+      <circle cx="50%" cy="50%" r={`${size / 2}%`} fill={color} />
       <line
-        className={classes?.thumbLine}
+        className={classes?.line}
         x1="50%"
-        y1={`${(KNOB_VIEWBOX_SIZE - clamp(thumbSize, 0, 100)) / 2}%`}
+        y1={`${(KNOB_VIEWBOX_SIZE - clamp(size, 0, 100)) / 2}%`}
         x2="50%"
-        y2={`${thumbLineLength}%`}
-        stroke={thumbLine}
-        strokeWidth={`${thumbLineWeight}%`}
+        y2={`${lineLength}%`}
+        stroke={lineColor}
+        strokeWidth={`${lineWeight}%`}
         // NOTE
         // https://bugs.webkit.org/show_bug.cgi?id=201854
         // https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/transform-origin#browser_compatibility

package/src/components/Knob/index.tsx

@@ -3,6 +3,7 @@ import {
   CSSProperties,
   forwardRef,
   ReactNode,
+  Ref,
   useCallback,
   useImperativeHandle,
   useMemo,
@@ -10,23 +11,27 @@ import {
 } from 'react'
 
 import {
-  applyDelta,
-  arrowKeyDirection,
   type AxisOptions,
-  cssLength,
+  type ChangeSource,
   DEFAULT_DRAG_SENSITIVITY,
   DEFAULT_KEYBOARD_OPTIONS,
   DEFAULT_WHEEL_OPTIONS,
   type InputEventOption,
   knobAngles,
   type ModifierValue,
-  selectModifier,
-  wheelDirection,
   type XY,
 } from '@tremolo-ui/dom'
+import {
+  applyDelta,
+  arrowKeyDirection,
+  cssLength,
+  selectModifier,
+  wheelDirection,
+} from '@tremolo-ui/dom/internal'
 import { linearScale, type Scale, type ValueRange } 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'
@@ -39,10 +44,6 @@ import { Thumb } from './Thumb'
 
 import type { CSSVariables } from '../../css-variables'
 
-const defaultExternalStyles: KnobProps['externalStyles'] = {
-  cursor: 'grabbing',
-}
-
 export interface KnobProps {
   /** The current value. The knob shows only this, so update it from `onChange`. */
   value: number
@@ -69,10 +70,10 @@ export interface KnobProps {
    */
   scale?: Scale
   /**
-   * The value a double click restores, while `enableDoubleClickDefault` is on.
-   * @default min
+   * The value a double click restores. `null` turns the double click off.
+   * @default startValue
    */
-  defaultValue?: number
+  resetValue?: number | null
 
   /**
    * Where the active arc starts. Put it at the centre of a bipolar control,
@@ -91,11 +92,9 @@ export interface KnobProps {
    * The cursor to show while dragging. It is set on the dragged element, so it
    * stays while the pointer is outside the knob.
    *
-   * @default { cursor: 'grabbing' }
+   * @default 'grabbing'
    */
-  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 knob leaves it alone.
@@ -158,11 +157,6 @@ export interface KnobProps {
    * @default { default: ['raw', 1], shift: ['raw', 0.1] }
    */
   keyboard?: ModifierValue<InputEventOption> | null
-  /**
-   * Restore `defaultValue` on a double click.
-   * @default true
-   */
-  enableDoubleClickDefault?: boolean
 
   /**
    * Make the knob unchangeable and remove it from the tab order.
@@ -173,7 +167,7 @@ export interface KnobProps {
    * Make the knob unchangeable while leaving it focusable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean
+  readOnly?: boolean
 
   /**
    * How far the knob turns from `min` to `max`, in degrees, centred on the
@@ -187,6 +181,25 @@ export interface KnobProps {
    * click moves it.
    */
   onChange?: (value: number) => void
+  /**
+   * Called when a change of the value starts — a drag, a double click, 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 knob renders exactly what you compose here; there is no default
@@ -204,6 +217,13 @@ export interface KnobProps {
   children: ReactNode
 
   style?: CSSProperties & CSSVariables<'knob-size'>
+
+  /**
+   * Receives `focus` and `blur`. They do nothing while the knob is disabled,
+   * where the element's own `focus()` would still focus it. `ref` reaches the
+   * root element itself.
+   */
+  actionsRef?: Ref<KnobMethods>
 }
 
 export interface KnobMethods {
@@ -219,7 +239,7 @@ type Props = KnobProps & Omit<ComponentPropsWithoutRef<'div'>, keyof KnobProps>
  */
 const WHEEL_OPTIONS = { requireFocus: true }
 
-export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   (
     {
       value,
@@ -227,33 +247,35 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
       max,
       step = 1,
       scale = linearScale,
-      defaultValue = min,
+      resetValue,
       startValue = min,
       size,
-      externalStyles: _externalStyles,
+      dragCursor = 'grabbing',
       wheel = DEFAULT_WHEEL_OPTIONS,
       keyboard = DEFAULT_KEYBOARD_OPTIONS,
       dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
       pointerLock = false,
-      enableDoubleClickDefault = true,
       disabled = false,
-      readonly = false,
+      readOnly = false,
       angleRange = 270,
       onChange,
+      onChangeStart,
+      onChangeEnd,
+      changeEndDelay,
       onKeyDown,
       onPointerDown,
       onDoubleClick,
       className,
       style,
       children,
+      actionsRef,
       ...props
     }: Props,
     forwardedRef,
   ) => {
-    const elmRef = useRef<HTMLElement | SVGElement>(null)
+    const elmRef = useRef<HTMLDivElement>(null)
 
-    const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
-    const inactive = disabled || readonly
+    const inactive = disabled || readOnly
 
     // --- internal functions ---
     const range: ValueRange = useMemo(
@@ -263,15 +285,29 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
 
     useCheckSteps({ component: 'Knob', range, 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<HTMLOrSVGElement>) => {
         if (!keyboard || !onChange || inactive) return
         const direction = arrowKeyDirection(event.key)
         if (direction === null) return
         event.preventDefault()
-        onChange(applyDelta(value, direction, keyboard, range, event))
+        gesture.pulse('keyboard')
+        change(applyDelta(value, direction, keyboard, range, event))
       },
-      [keyboard, onChange, inactive, value, range],
+      [keyboard, onChange, inactive, value, range, gesture, change],
     )
 
     // --- hooks ---
@@ -292,13 +328,17 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
       sensitivity: (state) =>
         selectModifier(dragSensitivity, state.event).value,
       threshold: 1,
-      cursor: inactive ? undefined : externalStyles.cursor,
+      cursor: inactive ? undefined : dragCursor,
       pointerLock: inactive ? false : pointerLock,
       shouldStart: () => !inactive,
       onChange: (v) => {
         if (inactive) return
-        onChange?.(v[1])
+        change(v[1])
+      },
+      onDragStart: () => {
+        if (!inactive) gesture.hold('pointer')
       },
+      onDragEnd: () => gesture.end(),
     })
 
     const wheelRefCallback = useWheel<HTMLElement>((event) => {
@@ -309,12 +349,14 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
       if (direction === null) return
       event.preventDefault()
       if (!onChange) return
-      onChange(applyDelta(value, direction, wheel, range, event))
+      gesture.pulse('wheel')
+      change(applyDelta(value, direction, wheel, range, 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<HTMLElement | SVGElement>(
+    const rootRefCallback = useComposedRefs<HTMLDivElement>(
+      forwardedRef,
       elmRef,
       dragRefCallback,
       wheelRefCallback,
@@ -325,7 +367,7 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
       return { ...config, ...knobAngles(config) }
     }, [value, min, max, step, scale, startValue, angleRange])
 
-    useImperativeHandle(forwardedRef, () => {
+    useImperativeHandle(actionsRef, () => {
       return {
         focus() {
           if (!disabled) elmRef.current?.focus()
@@ -347,9 +389,9 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
           aria-valuemin={min}
           aria-valuemax={max}
           aria-disabled={disabled}
-          aria-readonly={readonly}
+          aria-readonly={readOnly}
           data-disabled={disabled ? '' : undefined}
-          data-readonly={readonly ? '' : undefined}
+          data-readonly={readOnly ? '' : undefined}
           data-dragging={dragging ? '' : undefined}
           style={
             {
@@ -359,8 +401,10 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
           }
           onPointerDown={onPointerDown}
           onDoubleClick={(event) => {
-            if (!inactive && enableDoubleClickDefault && onChange) {
-              onChange(defaultValue)
+            if (!inactive && resetValue !== null && onChange) {
+              gesture.instant('doubleClick', () =>
+                change(resetValue ?? startValue),
+              )
             }
             onDoubleClick?.(event)
           }}

package/src/components/NumberInput/InputField.tsx

@@ -11,11 +11,11 @@ import {
   caretAtDecimalOffset,
   caretDecimalOffset,
   numberSpan,
-} from '@tremolo-ui/dom'
+} from '@tremolo-ui/dom/internal'
 
 import { useComposedRefs } from '../../compose-refs'
 
-import { useNumberInputContext } from './context'
+import { useNumberInputContext, useNumberInputGesture } from './context'
 
 // The value belongs to `NumberInput.Root`, and the field is always text.
 type Props = Omit<
@@ -43,7 +43,7 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
       max,
       step,
       disabled,
-      readonly,
+      readOnly,
       keyboard,
       selectOnFocus,
       unformatOnFocus,
@@ -58,6 +58,7 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
       inputRef,
     } = useNumberInputContext()
 
+    const gesture = useNumberInputGesture()
     const [focused, setFocused] = useState(false)
 
     // Only until the first keystroke: from then on the draft is the user's own
@@ -119,11 +120,11 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
         role="spinbutton"
         value={shown}
         disabled={disabled}
-        readOnly={readonly}
+        readOnly={readOnly}
         aria-disabled={disabled}
-        aria-readonly={readonly}
+        aria-readonly={readOnly}
         data-disabled={disabled ? '' : undefined}
-        data-readonly={readonly ? '' : undefined}
+        data-readonly={readOnly ? '' : undefined}
         aria-valuenow={value}
         aria-valuemin={min}
         aria-valuemax={max}
@@ -159,7 +160,7 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
           } else if (
             keyboard &&
             !disabled &&
-            !readonly &&
+            !readOnly &&
             (key === 'ArrowUp' || key === 'ArrowDown') &&
             // Arrow keys pick a candidate while an IME is converting. Stepping
             // the value there would fight the conversion, and moving the caret
@@ -174,6 +175,7 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
                 from: input.value,
               }
             }
+            gesture?.key()
             nudge(key === 'ArrowUp' ? 1 : -1, keyboard, event)
           }
           onKeyDown?.(event)

package/src/components/NumberInput/Stepper.tsx

@@ -7,11 +7,18 @@ import {
   useState,
 } from 'react'
 
-import { createStepperDrag, type StepperDragInstance } from '@tremolo-ui/dom'
+import {
+  createStepperDrag,
+  type StepperDragInstance,
+} from '@tremolo-ui/dom/internal'
 
 import { useComposedRefs } from '../../compose-refs'
 
-import { StepperProvider, useNumberInputContext } from './context'
+import {
+  StepperProvider,
+  useNumberInputContext,
+  useNumberInputGesture,
+} from './context'
 
 type Props = ComponentPropsWithoutRef<'div'>
 
@@ -24,21 +31,25 @@ type Props = ComponentPropsWithoutRef<'div'>
  * off text selection on whatever element it is attached to.
  */
 export const Stepper = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
-  function Stepper({ className, style, children, ...props }, forwardedRef) {
+  function Stepper(
+    { className, style, children, onPointerDown, ...props },
+    forwardedRef,
+  ) {
     const {
       value,
       disabled,
-      readonly,
+      readOnly,
       drag,
       dragSensitivity,
       pointerLock,
+      dragCursor,
       rawRange,
       changeValue,
     } = useNumberInputContext()
     // Only attached while it can do something: `createDrag` puts
     // `touch-action: none` on the element, and a stepper that cannot be
     // dragged has no reason to stop the page scrolling under a finger.
-    const enabled = drag !== null && !disabled && !readonly
+    const enabled = drag !== null && !disabled && !readOnly
 
     // See useDrag for why the node is held in state rather than a ref.
     const [node, setNode] = useState<HTMLDivElement | null>(null)
@@ -49,6 +60,7 @@ export const Stepper = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
       pixels: drag ?? 1,
       sensitivity: dragSensitivity,
       pointerLock,
+      cursor: dragCursor,
     }
     const optionsRef = useRef(options)
 
@@ -73,6 +85,7 @@ export const Stepper = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
       }
     }, [node, enabled])
 
+    const gesture = useNumberInputGesture()
     const composedRef = useComposedRefs<HTMLDivElement>(forwardedRef, setNode)
 
     const context = useMemo(
@@ -82,7 +95,18 @@ export const Stepper = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
 
     return (
       <StepperProvider value={context}>
-        <div ref={composedRef} className={className} style={style} {...props}>
+        <div
+          ref={composedRef}
+          className={className}
+          style={style}
+          onPointerDown={(event) => {
+            // A drag on the stepper is a press like any other: held from here
+            // until the pointer is released.
+            if (enabled) gesture?.press()
+            onPointerDown?.(event)
+          }}
+          {...props}
+        >
           {children}
         </div>
       </StepperProvider>

package/src/components/NumberInput/StepperButton.tsx

@@ -2,7 +2,11 @@ import { ComponentPropsWithoutRef, ReactNode, CSSProperties } from 'react'
 
 import { useLongPress } from '../../hooks/useLongPress'
 
-import { useNumberInputContext, useStepperContext } from './context'
+import {
+  useNumberInputContext,
+  useNumberInputGesture,
+  useStepperContext,
+} from './context'
 
 import type { CSSVariables } from '../../css-variables'
 
@@ -37,9 +41,10 @@ export function StepperButton({
   variant: 'increment' | 'decrement'
   icon: ReactNode
 }) {
-  const { step, disabled, readonly, atMin, atMax, nudge } =
+  const { step, disabled, readOnly, atMin, atMax, nudge } =
     useNumberInputContext()
   const stepper = useStepperContext()
+  const gesture = useNumberInputGesture()
 
   // Not memoized: `useLongPress` only ever calls it through a ref, so a fresh
   // identity per render costs nothing.
@@ -64,10 +69,13 @@ export function StepperButton({
       data-disabled={
         disabled || (direction > 0 ? atMax : atMin) ? '' : undefined
       }
-      data-readonly={readonly ? '' : undefined}
+      data-readonly={readOnly ? '' : undefined}
       style={style}
       onPointerDown={(event) => {
-        if (!disabled && !readonly) press(event)
+        if (!disabled && !readOnly) {
+          gesture?.press()
+          press(event)
+        }
         onPointerDown?.(event)
       }}
       {...props}