@tremolo-ui/react 0.4.0 → 0.6.0

package/package.json

@@ -1,55 +1,54 @@
 {
   "name": "@tremolo-ui/react",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "React component library for audio app",
   "type": "module",
-  "sideEffects": [
-    "*.css"
-  ],
+  "sideEffects": false,
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.cts",
   "scripts": {
-    "sb": "storybook dev -p 6006",
+    "sb": "storybook dev",
     "typecheck": "tsc",
-    "build:sb": "storybook build",
+    "build:sb": "storybook build -o storybook-static/i/storybook-react && cp .storybook/_headers storybook-static/_headers",
     "serve": "http-server ./storybook-static",
     "lint": "eslint --fix --ext .ts,.tsx .",
     "format": "prettier --write .",
-    "test": "jest",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "build:package": "tsc && tsdown",
     "clean": "npm run clean:build && npm run clean:sb",
     "clean:build": "rimraf ./dist",
     "clean:sb": "rimraf ./storybook-static"
   },
   "devDependencies": {
-    "@storybook/addon-a11y": "10.5.10",
-    "@storybook/addon-links": "10.5.10",
-    "@storybook/react-vite": "10.5.10",
+    "@storybook/addon-a11y": "10.6.0",
+    "@storybook/addon-docs": "10.6.0",
+    "@storybook/addon-links": "10.6.0",
+    "@storybook/react-vite": "10.6.0",
+    "@testing-library/jest-dom": "7.0.1",
     "@testing-library/react": "16.3.3",
-    "@types/react": "19.2.18",
-    "@types/react-dom": "19.2.5",
-    "jest-environment-jsdom": "29.7.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "jotai": "2.20.3",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
-    "storybook": "10.5.10",
-    "tone": "15.1.22",
-    "@storybook/addon-docs": "10.5.10"
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "storybook": "10.6.0",
+    "tone": "15.1.22"
   },
   "peerDependencies": {
     "react": "^18 ||^19",
     "react-dom": "^18 || ^19"
   },
   "dependencies": {
-    "@tremolo-ui/dom": "^0.4.0",
-    "@tremolo-ui/functions": "^0.4.0",
-    "clsx": "^2.1.1",
-    "zustand": "^5.0.3"
+    "@tremolo-ui/dom": "^0.6.0",
+    "@tremolo-ui/functions": "^0.6.0"
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "!src/**/*.test.{ts,tsx}",
+    "!src/**/*.stories.{ts,tsx}"
   ],
   "publishConfig": {
     "access": "public"
@@ -83,13 +82,15 @@
         "default": "./dist/index.js"
       }
     },
-    "./styles/index.css": "./dist/index.css",
-    "./styles/global.css": "./src/styles/global.css",
-    "./styles/Knob.css": "./src/components/Knob/index.css",
-    "./styles/NumberInput.css": "./src/components/NumberInput/index.css",
-    "./styles/Piano.css": "./src/components/Piano/index.css",
-    "./styles/PointsEditor.css": "./src/components/PointsEditor/index.css",
-    "./styles/Slider.css": "./src/components/Slider/index.css",
-    "./styles/XYPad.css": "./src/components/XYPad/index.css"
+    "./compose-refs": {
+      "require": {
+        "types": "./dist/compose-refs.d.cts",
+        "default": "./dist/compose-refs.cjs"
+      },
+      "import": {
+        "types": "./dist/compose-refs.d.ts",
+        "default": "./dist/compose-refs.js"
+      }
+    }
   }
 }

package/src/components/AnimationCanvas/index.tsx

@@ -1,19 +1,18 @@
-import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
-  ReactElement,
-  RefObject,
-  useCallback,
+  forwardRef,
   useEffect,
   useRef,
+  useState,
 } from 'react'
 
 import {
-  DrawingContext,
-  drawingState,
-  DrawingStateValue,
-  setDprConfig,
-} from './canvas'
+  createAnimationCanvas,
+  type AnimationCanvasInstance,
+  type AnimationFrame,
+} from '@tremolo-ui/dom'
+
+import { useComposedRefs } from '../../compose-refs'
 
 export type InitFunction = (
   context: CanvasRenderingContext2D,
@@ -27,216 +26,185 @@ export type InitFunction = (
 
 export type DrawFunction = (
   context: CanvasRenderingContext2D,
-  option: {
-    /** current canvas width */
-    width: number
-    /** current canvas height */
-    height: number
-    /** frame count */
-    count: number
-    /** delta time (ms) */
-    deltaTime: number
-    /** elapsed time (ms) */
-    elapsedTime: number
-    /** frame per second */
-    fps: number
-  },
+  option: AnimationFrame,
 ) => void
 
-export interface CommonProps {
+export interface AnimationCanvasCommonProps {
+  /**
+   * Draw one frame. It is given the 2D context and the frame: the size in CSS
+   * pixels, `count`, `deltaTime`, `elapsedTime` and `fps`.
+   *
+   * A new function replaces the old one in place, so writing it inline does
+   * not restart anything.
+   */
   draw: DrawFunction
+  /**
+   * Called once before the first frame, with the context and the size in CSS
+   * pixels. Set up what every frame shares here.
+   */
   init?: InitFunction
+  /**
+   * 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
+   * component re-renders.
+   *
+   * @default true
+   */
   animate?: boolean
   /**
+   * Read once, when the 2D context is created, so changing it later has no
+   * effect. Passing a fresh object on every render is therefore harmless.
+   *
    * @see https://developer.mozilla.org/docs/Web/API/HTMLCanvasElement/getContext#contextattributes
    */
   options?: CanvasRenderingContext2DSettings
+  /**
+   * Carry the drawing across a resize, so that the canvas does not blank for a
+   * frame while the new size is drawn. A fixed canvas is resized too, when its
+   * `width` or `height` changes.
+   *
+   * @default true
+   */
+  reduceFlickering?: boolean
 }
 
-export interface AbsoluteSizingProps {
+/** A canvas of the size given in CSS pixels. This is the default. */
+export interface AnimationCanvasFixedProps {
+  /** Leave it out, or pass `false`, for a canvas of the size below. */
+  resizable?: false
+  /**
+   * Width of the canvas in CSS pixels.
+   * @default 100
+   */
   width?: number
+  /**
+   * Height of the canvas in CSS pixels.
+   * @default 100
+   */
   height?: number
 }
 
-export interface RelativeSizingProps {
-  relativeSize?: boolean
-  reduceFlickering?: boolean
+/**
+ * A canvas that follows the size of its parent element, so the parent needs a
+ * size of its own.
+ */
+export interface AnimationCanvasResizableProps {
+  /**
+   * Follow the size of the parent element instead of `width` and `height`.
+   * Switching it rebuilds the canvas.
+   */
+  resizable: true
+  /** Not accepted: the size comes from the parent element. */
+  width?: never
+  /** Not accepted: the size comes from the parent element. */
+  height?: never
 }
 
-export type AnimationCanvasProps = CommonProps &
-  AbsoluteSizingProps &
-  RelativeSizingProps
+export type AnimationCanvasProps = AnimationCanvasCommonProps &
+  (AnimationCanvasFixedProps | AnimationCanvasResizableProps)
 
-/**
- * A simple animatable canvas with requestAnimationFrame()
- */
-export function AnimationCanvas(
-  props: CommonProps &
-    AbsoluteSizingProps &
-    Omit<ComponentPropsWithoutRef<'canvas'>, keyof AnimationCanvasProps>,
-): ReactElement
-export function AnimationCanvas(
-  pros: CommonProps &
-    RelativeSizingProps &
-    Omit<ComponentPropsWithoutRef<'canvas'>, keyof AnimationCanvasProps>,
-): ReactElement
-export function AnimationCanvas({
-  // common
-  draw,
-  init,
-  animate = true,
-  options,
-  // absolute
-  width: _width = 100,
-  height: _height = 100,
-  // relative
-  relativeSize,
-  reduceFlickering = true,
-  // canvas props
-  className,
-  onContextMenu = (event) => event.preventDefault(),
-  ...props
-}: AnimationCanvasProps &
+type Props = AnimationCanvasProps &
   Omit<
     ComponentPropsWithoutRef<'canvas'>,
-    keyof AnimationCanvasProps
-  >): ReactElement {
-  const canvasRef = useRef<HTMLCanvasElement>(null)
-  const memoCanvasRef = useRef<HTMLCanvasElement>(null)
-  const reqIdRef = useRef(-1)
-  const widthRef = useRef(0)
-  const heightRef = useRef(0)
-  const deltaMemoRef = useRef(-1)
-  const startTimeRef = useRef(-1)
-
-  const loop = useCallback(
-    (
-      context: CanvasRenderingContext2D,
-      width: RefObject<number>,
-      height: RefObject<number>,
-      count: number,
-    ) => {
-      const now = performance.now()
-      const deltaTime = now - deltaMemoRef.current
-      const elapsedTime = now - startTimeRef.current
-      deltaMemoRef.current = now
-      if (animate) {
-        reqIdRef.current = requestAnimationFrame(() =>
-          loop(context, width, height, count + 1),
-        )
-      }
-      draw(context, {
-        width: width.current,
-        height: height.current,
-        count: count + 1,
-        deltaTime,
-        elapsedTime,
-        fps: 1000 / deltaTime,
-      })
-    },
-    [draw, animate],
-  )
+    keyof AnimationCanvasCommonProps | 'resizable' | 'width' | 'height'
+  >
 
+/**
+ * A simple animatable canvas with requestAnimationFrame()
+ */
+export const AnimationCanvas = /* @__PURE__ */ forwardRef<
+  HTMLCanvasElement,
+  Props
+>(function AnimationCanvas(
+  {
+    // common
+    draw,
+    init,
+    animate = true,
+    options,
+    reduceFlickering = true,
+    // fixed
+    width = 100,
+    height = 100,
+    // resizable
+    resizable = false,
+    // canvas props
+    className,
+    onContextMenu = (event) => event.preventDefault(),
+    ...props
+  },
+  forwardedRef,
+) {
+  // See useDrag for why the node is held in state rather than a ref: an inline
+  // ref would be re-attached on every render and tear the instance down.
+  const [node, setNode] = useState<HTMLCanvasElement | null>(null)
+  // The caller's ref gets the same element.
+  const composedRef = useComposedRefs<HTMLCanvasElement>(forwardedRef, setNode)
+
+  // Read when the instance is created. The effect below keeps it current, and
+  // runs right after, so a stale handler is replaced within the same commit.
+  const latest = useRef({
+    draw,
+    init,
+    animate,
+    width,
+    height,
+    reduceFlickering,
+    options,
+  })
+  const instanceRef = useRef<AnimationCanvasInstance | null>(null)
+
+  // Runs before the creation effect below. This keeps a rebuilt instance on
+  // the current render's size and handlers while updating an existing one in
+  // place on ordinary renders.
   useEffect(() => {
-    if (!canvasRef.current) return
-    const canvas = canvasRef.current
-    const context = canvas.getContext('2d', options)
-    if (!context) throw new Error('Cannot get canvas context.')
-    const dpr = globalThis.devicePixelRatio
-
-    const firstRendering = (width: number, height: number) => {
-      setDprConfig(canvas, context, width, height, dpr)
-      widthRef.current = width
-      heightRef.current = height
-
-      if (init) init(context, { width, height })
-      const now = performance.now()
-      deltaMemoRef.current = now
-      startTimeRef.current = now
-      loop(context, widthRef, heightRef, -1)
+    latest.current = {
+      draw,
+      init,
+      animate,
+      width,
+      height,
+      reduceFlickering,
+      options,
     }
+    instanceRef.current?.update({
+      animate,
+      size: { width, height },
+      reduceFlickering,
+    })
+  })
 
-    if (relativeSize) {
-      const parent = canvas.parentElement
-      if (!parent) throw new Error("Canvas doesn't have a parent element.")
-      const memoCanvas = memoCanvasRef.current
-      const memoContext = memoCanvas?.getContext('2d', options)
-
-      const ro = new ResizeObserver((entries) => {
-        for (const entry of entries) {
-          const w = entry.contentRect.width
-          const h = entry.contentRect.height
-          const contextMemo = {} as DrawingContext
-          if (reduceFlickering && memoCanvas && memoContext) {
-            // Prevents loss of some context when the canvas is resized
-            for (const prop of drawingState) {
-              ;(contextMemo[prop] as DrawingStateValue) = context[prop]
-            }
-            memoCanvas.width = w * dpr
-            memoCanvas.height = h * dpr
-            memoContext.scale(1 / dpr, 1 / dpr)
-            if (canvas.width > 0 && canvas.height > 0) {
-              memoContext.drawImage(canvas, 0, 0)
-            }
-          }
-
-          setDprConfig(canvas, context, w, h, dpr)
-          widthRef.current = w
-          heightRef.current = h
-
-          if (
-            reduceFlickering &&
-            memoContext &&
-            memoCanvas &&
-            memoCanvas.width > 0 &&
-            memoCanvas.height > 0
-          ) {
-            for (const prop of drawingState) {
-              ;(context[prop] as DrawingStateValue) = contextMemo[prop]
-            }
-
-            context.drawImage(memoContext.canvas, 0, 0)
-          }
-
-          if (!animate) {
-            // re rendering
-            loop(context, widthRef, heightRef, -1)
-          }
-        }
-      })
-      ro.observe(parent)
-
-      const width = parent.clientWidth
-      const height = parent.clientHeight
-      firstRendering(width, height)
-
-      return () => {
-        if (reqIdRef.current) cancelAnimationFrame(reqIdRef.current)
-        ro.disconnect()
-      }
-    } else {
-      const { width, height } = canvas.getBoundingClientRect()
-      firstRendering(width, height)
-
-      return () => {
-        if (reqIdRef.current) cancelAnimationFrame(reqIdRef.current)
-      }
+  useEffect(() => {
+    if (!node) return
+
+    const current = latest.current
+    const instance = createAnimationCanvas(node, {
+      draw: (context, frame) => latest.current.draw(context, frame),
+      init: (context, size) => latest.current.init?.(context, size),
+      animate: current.animate,
+      size: { width: current.width, height: current.height },
+      reduceFlickering: current.reduceFlickering,
+      resizable,
+      contextAttributes: current.options,
+    })
+    instanceRef.current = instance
+
+    return () => {
+      instanceRef.current = null
+      instance.destroy()
     }
-  }, [loop, init, options, reduceFlickering, relativeSize, animate])
+    // Only `resizable` decides how the instance is wired, so it is the one
+    // setting that rebuilds it. `options` is read from the ref above rather
+    // than depended on: it is almost always written inline, and depending on
+    // it would tear the canvas down on every render.
+  }, [node, resizable])
 
   return (
-    <>
-      <canvas
-        className={clsx('tremolo-animation-canvas', className)}
-        width={relativeSize ? 0 : _width}
-        height={relativeSize ? 0 : _height}
-        ref={canvasRef}
-        onContextMenu={onContextMenu}
-        {...props}
-      ></canvas>
-      {relativeSize && reduceFlickering && (
-        <canvas style={{ display: 'none' }} ref={memoCanvasRef}></canvas>
-      )}
-    </>
+    <canvas
+      className={className}
+      ref={composedRef}
+      onContextMenu={onContextMenu}
+      {...props}
+    />
   )
-}
+})

package/src/components/Knob/ActiveLine.tsx

@@ -1,7 +1,8 @@
-import clsx from 'clsx'
 import { SVGProps } from 'react'
 
-import { center, useKnobContext } from './context'
+import { useCheckPlacement } from '../_util/Placement'
+
+import { arcPath, arcRadius, useKnobContext } from './context'
 
 export function ActiveLine({
   stroke = 'currentColor',
@@ -9,17 +10,17 @@ export function ActiveLine({
   className,
   ...props
 }: Omit<SVGProps<SVGPathElement>, 'd'>) {
+  useCheckPlacement('Knob.ActiveLine', 'Knob.SVGRoot')
+
   const r2 = useKnobContext((s) => s.r2)
   const r3 = useKnobContext((s) => s.r3)
-  const x2 = useKnobContext((s) => s.x2)
-  const y2 = useKnobContext((s) => s.y2)
-  const x3 = useKnobContext((s) => s.x3)
-  const y3 = useKnobContext((s) => s.y3)
+
+  const radius = arcRadius(strokeWidth)
 
   return (
     <path
-      className={clsx('tremolo-knob-active-line', className)}
-      d={`M ${x2} ${y2} A ${center} ${center} -135 ${r3 - r2 > 180 ? 1 : 0} 1 ${x3} ${y3}`}
+      className={className}
+      d={arcPath(r2, r3, radius)}
       fill="none"
       stroke={stroke}
       strokeWidth={strokeWidth}

package/src/components/Knob/InactiveLine.tsx

@@ -1,7 +1,8 @@
-import clsx from 'clsx'
 import { SVGProps } from 'react'
 
-import { center, useKnobContext } from './context'
+import { useCheckPlacement } from '../_util/Placement'
+
+import { arcPath, arcRadius, useKnobContext } from './context'
 
 export function InactiveLine({
   stroke = 'currentColor',
@@ -9,6 +10,8 @@ export function InactiveLine({
   className,
   ...props
 }: Omit<SVGProps<SVGPathElement>, 'd'>) {
+  useCheckPlacement('Knob.InactiveLine', 'Knob.SVGRoot')
+
   const min = useKnobContext((s) => s.min)
   const max = useKnobContext((s) => s.max)
   const startValue = useKnobContext((s) => s.startValue)
@@ -17,21 +20,15 @@ export function InactiveLine({
   const r2 = useKnobContext((s) => s.r2)
   const r3 = useKnobContext((s) => s.r3)
   const r4 = useKnobContext((s) => s.r4)
-  const x1 = useKnobContext((s) => s.x1)
-  const y1 = useKnobContext((s) => s.y1)
-  const x2 = useKnobContext((s) => s.x2)
-  const y2 = useKnobContext((s) => s.y2)
-  const x3 = useKnobContext((s) => s.x3)
-  const y3 = useKnobContext((s) => s.y3)
-  const x4 = useKnobContext((s) => s.x4)
-  const y4 = useKnobContext((s) => s.y4)
+
+  const radius = arcRadius(strokeWidth)
 
   return (
     <>
       {startValue > min && (
         <path
-          className={clsx('tremolo-knob-inactive-line', className)}
-          d={`M ${x1} ${y1} A ${center} ${center} -135 ${r2 - r1 > 180 ? 1 : 0} 1 ${x2} ${y2}`}
+          className={className}
+          d={arcPath(r1, r2, radius)}
           fill="none"
           stroke={stroke}
           strokeWidth={strokeWidth}
@@ -40,8 +37,8 @@ export function InactiveLine({
       )}
       {startValue < max && (
         <path
-          className={clsx('tremolo-knob-inactive-line', className)}
-          d={`M ${x3} ${y3} A ${center} ${center} -135 ${r4 - r3 > 180 ? 1 : 0} 1 ${x4} ${y4}`}
+          className={className}
+          d={arcPath(r3, r4, radius)}
           fill="none"
           stroke={stroke}
           strokeWidth={strokeWidth}

package/src/components/Knob/SVGRoot.tsx

@@ -1,39 +1,32 @@
-import { SVGProps } from 'react'
+import { ReactNode, SVGProps } from 'react'
 
-import { Override } from '../_util/type'
+import { Placement } from '../_util/Placement'
 
-import { ActiveLine } from './ActiveLine'
 import { viewBoxSize } from './context'
-import { InactiveLine } from './InactiveLine'
-import { Thumb } from './Thumb'
 
-interface SVGRoot {
-  block?: boolean
-  overflowVisible?: boolean
+export interface KnobSVGRootProps {
+  /**
+   * `<Knob.InactiveLine />`, `<Knob.ActiveLine />` and `<Knob.Thumb />` go
+   * here, in the order you want them painted.
+   */
+  children: ReactNode
 }
 
 export function SVGRoot({
   children,
   style,
   ...props
-}: Override<SVGRoot, SVGProps<SVGSVGElement>>) {
+}: KnobSVGRootProps & Omit<SVGProps<SVGSVGElement>, keyof KnobSVGRootProps>) {
   return (
     <svg
       viewBox={`0 0 ${viewBoxSize} ${viewBoxSize}`}
       style={{
         display: 'block',
-        overflow: 'visible',
         ...style,
       }}
       {...props}
     >
-      {children || (
-        <>
-          <InactiveLine />
-          <ActiveLine />
-          <Thumb />
-        </>
-      )}
+      <Placement name="Knob.SVGRoot">{children}</Placement>
     </svg>
   )
 }