@tremolo-ui/react 0.5.0 → 0.6.0

package/package.json

@@ -1,22 +1,21 @@
 {
   "name": "@tremolo-ui/react",
-  "version": "0.5.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",
@@ -24,31 +23,32 @@
   },
   "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",
+    "@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",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "storybook": "10.6.0",
-    "tone": "15.1.22",
-    "@storybook/addon-docs": "10.6.0"
+    "tone": "15.1.22"
   },
   "peerDependencies": {
     "react": "^18 ||^19",
     "react-dom": "^18 || ^19"
   },
   "dependencies": {
-    "@tremolo-ui/dom": "^0.5.0",
-    "@tremolo-ui/functions": "^0.5.0",
-    "clsx": "^2.1.1"
+    "@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"
@@ -82,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,7 +1,6 @@
-import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
-  ReactElement,
+  forwardRef,
   useEffect,
   useRef,
   useState,
@@ -13,6 +12,8 @@ import {
   type AnimationFrame,
 } from '@tremolo-ui/dom'
 
+import { useComposedRefs } from '../../compose-refs'
+
 export type InitFunction = (
   context: CanvasRenderingContext2D,
   option: {
@@ -28,9 +29,27 @@ export type DrawFunction = (
   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
@@ -39,59 +58,88 @@ export interface CommonProps {
    * @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)
+
+type Props = AnimationCanvasProps &
+  Omit<
+    ComponentPropsWithoutRef<'canvas'>,
+    keyof AnimationCanvasCommonProps | 'resizable' | 'width' | 'height'
+  >
 
 /**
  * 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 = 100,
-  height = 100,
-  // relative
-  relativeSize = false,
-  reduceFlickering = true,
-  // canvas props
-  className,
-  onContextMenu = (event) => event.preventDefault(),
-  ...props
-}: AnimationCanvasProps &
-  Omit<
-    ComponentPropsWithoutRef<'canvas'>,
-    keyof AnimationCanvasProps
-  >): ReactElement {
+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.
@@ -105,8 +153,26 @@ export function AnimationCanvas({
     options,
   })
   const instanceRef = useRef<AnimationCanvasInstance | null>(null)
-  /** Set while the instance below is newer than the effect that pushes into it. */
-  const justCreated = useRef(false)
+
+  // 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(() => {
+    latest.current = {
+      draw,
+      init,
+      animate,
+      width,
+      height,
+      reduceFlickering,
+      options,
+    }
+    instanceRef.current?.update({
+      animate,
+      size: { width, height },
+      reduceFlickering,
+    })
+  })
 
   useEffect(() => {
     if (!node) return
@@ -118,54 +184,27 @@ export function AnimationCanvas({
       animate: current.animate,
       size: { width: current.width, height: current.height },
       reduceFlickering: current.reduceFlickering,
-      relativeSize,
+      resizable,
       contextAttributes: current.options,
     })
     instanceRef.current = instance
-    justCreated.current = true
 
     return () => {
       instanceRef.current = null
       instance.destroy()
     }
-    // Only `relativeSize` decides how the instance is wired, so it is the one
+    // 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, relativeSize])
-
-  // Runs after every render: the handlers come from props and are cheap to
-  // push, and updating in place keeps the frame count and elapsed time going.
-  useEffect(() => {
-    latest.current = {
-      draw,
-      init,
-      animate,
-      width,
-      height,
-      reduceFlickering,
-      options,
-    }
-    // The instance was built from `latest` a moment ago, so there is nothing
-    // to push yet. Skipping matters with `animate` off, where `update()` draws
-    // a frame and would otherwise paint the same one twice on mount.
-    if (justCreated.current) {
-      justCreated.current = false
-      return
-    }
-    instanceRef.current?.update({
-      animate,
-      size: { width, height },
-      reduceFlickering,
-    })
-  })
+  }, [node, resizable])
 
   return (
     <canvas
-      className={clsx('tremolo-animation-canvas', className)}
-      ref={setNode}
+      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 { arcRadius, pointOnArc, 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 radius = arcRadius(strokeWidth)
-  const start = pointOnArc(r2, radius)
-  const end = pointOnArc(r3, radius)
 
   return (
     <path
-      className={clsx('tremolo-knob-active-line', className)}
-      d={`M ${start.x} ${start.y} A ${radius} ${radius} -135 ${r3 - r2 > 180 ? 1 : 0} 1 ${end.x} ${end.y}`}
+      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 { arcRadius, pointOnArc, 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)
@@ -19,17 +22,13 @@ export function InactiveLine({
   const r4 = useKnobContext((s) => s.r4)
 
   const radius = arcRadius(strokeWidth)
-  const p1 = pointOnArc(r1, radius)
-  const p2 = pointOnArc(r2, radius)
-  const p3 = pointOnArc(r3, radius)
-  const p4 = pointOnArc(r4, radius)
 
   return (
     <>
       {startValue > min && (
         <path
-          className={clsx('tremolo-knob-inactive-line', className)}
-          d={`M ${p1.x} ${p1.y} A ${radius} ${radius} -135 ${r2 - r1 > 180 ? 1 : 0} 1 ${p2.x} ${p2.y}`}
+          className={className}
+          d={arcPath(r1, r2, radius)}
           fill="none"
           stroke={stroke}
           strokeWidth={strokeWidth}
@@ -38,8 +37,8 @@ export function InactiveLine({
       )}
       {startValue < max && (
         <path
-          className={clsx('tremolo-knob-inactive-line', className)}
-          d={`M ${p3.x} ${p3.y} A ${radius} ${radius} -135 ${r4 - r3 > 180 ? 1 : 0} 1 ${p4.x} ${p4.y}`}
+          className={className}
+          d={arcPath(r3, r4, radius)}
           fill="none"
           stroke={stroke}
           strokeWidth={strokeWidth}

package/src/components/Knob/SVGRoot.tsx

@@ -1,8 +1,10 @@
 import { ReactNode, SVGProps } from 'react'
 
+import { Placement } from '../_util/Placement'
+
 import { viewBoxSize } from './context'
 
-export interface SVGRootProps {
+export interface KnobSVGRootProps {
   /**
    * `<Knob.InactiveLine />`, `<Knob.ActiveLine />` and `<Knob.Thumb />` go
    * here, in the order you want them painted.
@@ -14,7 +16,7 @@ export function SVGRoot({
   children,
   style,
   ...props
-}: SVGRootProps & Omit<SVGProps<SVGSVGElement>, keyof SVGRootProps>) {
+}: KnobSVGRootProps & Omit<SVGProps<SVGSVGElement>, keyof KnobSVGRootProps>) {
   return (
     <svg
       viewBox={`0 0 ${viewBoxSize} ${viewBoxSize}`}
@@ -24,7 +26,7 @@ export function SVGRoot({
       }}
       {...props}
     >
-      {children}
+      <Placement name="Knob.SVGRoot">{children}</Placement>
     </svg>
   )
 }

package/src/components/Knob/Thumb.tsx

@@ -1,24 +1,44 @@
-import clsx from 'clsx'
 import { SVGProps } from 'react'
 
 import { clamp } from '@tremolo-ui/functions'
 
+import { useCheckPlacement } from '../_util/Placement'
+
 import { useKnobContext, viewBoxSize } from './context'
 
-interface Props {
-  /** color */
+export interface KnobThumbProps {
+  /**
+   * Fill colour of the circle.
+   * @default 'currentColor'
+   */
   thumb?: string
-  /** color */
+  /**
+   * Colour of the line that points at the value.
+   * @default 'currentColor'
+   */
   thumbLine?: string
-  /** percent (0-100) */
+  /**
+   * Diameter of the circle, as a percentage of the knob.
+   * @default 84
+   */
   thumbSize?: number
-  /** percent (0-100) */
+  /**
+   * Thickness of the line, as a percentage of the knob.
+   * @default 6
+   */
   thumbLineWeight?: number
-  /** percent (0-100) */
+  /**
+   * 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
 
+  /**
+   * Classes for what the thumb draws inside itself: `thumbLine` is the line
+   * that points at the value.
+   */
   classes?: {
-    thumb?: string
     thumbLine?: string
   }
 }
@@ -34,17 +54,19 @@ export function Thumb({
   classes,
 
   ...props
-}: Props & Omit<SVGProps<SVGSVGElement>, 'd' | keyof Props>) {
+}: KnobThumbProps & Omit<SVGProps<SVGSVGElement>, 'd' | keyof KnobThumbProps>) {
+  useCheckPlacement('Knob.Thumb', 'Knob.SVGRoot')
+
   const angleRange = useKnobContext((s) => s.angleRange)
 
   const p = useKnobContext((s) => s.p)
   const r1 = useKnobContext((s) => s.r1)
 
   return (
-    <svg className={clsx('tremolo-knob-thumb', classes?.thumb)} {...props}>
+    <svg className={className} {...props}>
       <circle cx="50%" cy="50%" r={`${thumbSize / 2}%`} fill={thumb} />
       <line
-        className={clsx('tremolo-knob-thumb-line', classes?.thumbLine)}
+        className={classes?.thumbLine}
         x1="50%"
         y1={`${(viewBoxSize - clamp(thumbSize, 0, 100)) / 2}%`}
         x2="50%"

package/src/components/Knob/context.tsx

@@ -51,6 +51,22 @@ export function arcRadius(strokeWidth: number | string | undefined) {
   return Number.isFinite(width) ? center - width / 2 : center
 }
 
+/** Build an SVG path for an arc, splitting full turns into drawable segments. */
+export function arcPath(startAngle: number, endAngle: number, radius: number) {
+  const start = pointOnArc(startAngle, radius)
+  const sweep = endAngle - startAngle
+  const segmentCount = Math.max(1, Math.ceil(Math.abs(sweep) / 180))
+  const segmentSweep = sweep / segmentCount
+  let path = `M ${start.x} ${start.y}`
+
+  for (let i = 1; i <= segmentCount; i += 1) {
+    const end = pointOnArc(startAngle + segmentSweep * i, radius)
+    path += ` A ${radius} ${radius} 0 0 ${segmentSweep >= 0 ? 1 : 0} ${end.x} ${end.y}`
+  }
+
+  return path
+}
+
 /** 設定から描画に必要な角度を導出する。レンダー中に呼ぶ。 */
 export function calcAngles({
   value,
@@ -71,7 +87,7 @@ export function calcAngles({
   return { p, r1, r2, r3, r4 }
 }
 
-const KnobContext = createContext<KnobContextValue | null>(null)
+const KnobContext = /* @__PURE__ */ createContext<KnobContextValue | null>(null)
 
 export const KnobProvider = KnobContext.Provider