@tremolo-ui/react 0.5.0 → 0.7.0

package/package.json

@@ -1,22 +1,21 @@
 {
   "name": "@tremolo-ui/react",
-  "version": "0.5.0",
+  "version": "0.7.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",
-    "jotai": "2.20.3",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jotai": "3.0.0",
+    "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.7.0",
+    "@tremolo-ui/functions": "^0.7.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/DropZone/index.tsx

@@ -0,0 +1,100 @@
+import { ComponentPropsWithoutRef, forwardRef, ReactNode } from 'react'
+
+import { useComposedRefs } from '../../compose-refs'
+import { useDropZone } from '../../hooks/useDropZone'
+
+export interface DropZoneProps {
+  /**
+   * Which files to take, written the way the `accept` attribute of a file
+   * input is: a comma separated list of extensions (`.wav`), MIME types
+   * (`audio/wav`) and type groups (`audio/*`).
+   *
+   * What does not match goes to `onReject` rather than `onDrop`. While the
+   * drag is still in the air the element is marked `[data-invalid]`, as far as
+   * the browser lets it be told apart — a rule written as an extension cannot
+   * be decided until the drop.
+   */
+  accept?: string
+  /**
+   * Take more than one file from a single drop. With it off, only the first
+   * accepted file is reported, as a file input without `multiple` does.
+   *
+   * @default false
+   */
+  multiple?: boolean
+  /**
+   * Refuse the drop. The drag is still swallowed rather than let through: an
+   * unhandled drop makes the browser leave the page and open the file.
+   *
+   * @default false
+   */
+  disabled?: boolean
+
+  /**
+   * Called with the dropped files that match `accept`.
+   *
+   * @param event the drop, for anything the files leave out — where on the
+   * element it landed, most of all.
+   */
+  onDrop?: (files: File[], event: DragEvent) => void
+  /**
+   * Called with the dropped files that do not match `accept`, so that the
+   * reason can be shown.
+   */
+  onReject?: (files: File[], event: DragEvent) => void
+
+  /** What the zone shows. */
+  children: ReactNode
+}
+
+type Props = DropZoneProps &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof DropZoneProps>
+
+/**
+ * An area that takes files dropped onto it.
+ *
+ * To make an element you already have into a drop target, without wrapping it
+ * in anything, use the `useDropZone` hook this is built on.
+ */
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
+  (
+    {
+      accept,
+      multiple = false,
+      disabled = false,
+      onDrop,
+      onReject,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const { refCallback, over, invalid } = useDropZone<HTMLDivElement>({
+      accept,
+      multiple,
+      disabled,
+      onDrop,
+      onReject,
+    })
+    const composedRef = useComposedRefs<HTMLDivElement>(ref, refCallback)
+
+    return (
+      <div
+        ref={composedRef}
+        data-dragover={over ? '' : undefined}
+        data-invalid={invalid ? '' : undefined}
+        data-disabled={disabled ? '' : undefined}
+        {...props}
+      >
+        {children}
+      </div>
+    )
+  },
+)
+
+/**
+ * An area that takes files dropped onto it.
+ */
+export const DropZone = {
+  Root,
+}

package/src/components/FileInput/Trigger.tsx

@@ -0,0 +1,39 @@
+import { ComponentPropsWithoutRef, forwardRef, ReactNode } from 'react'
+
+import { useFileInputContext } from './context'
+
+export interface FileInputTriggerProps {
+  /** What the trigger reads. It is the accessible name of the file input. */
+  children: ReactNode
+}
+
+type Props = FileInputTriggerProps &
+  Omit<
+    ComponentPropsWithoutRef<'label'>,
+    keyof FileInputTriggerProps | 'htmlFor'
+  >
+
+/**
+ * Opens the file picker, and names the input for a screen reader.
+ *
+ * A `<label>` rather than a `<button>`: the browser forwards the click to the
+ * input on its own, the input stays the one thing in the tab order, and its
+ * accessible name comes from this text without an `aria-label` to keep in
+ * step. A disabled input ignores the click, so nothing has to be intercepted.
+ */
+export const Trigger = /* @__PURE__ */ forwardRef<HTMLLabelElement, Props>(
+  ({ children, ...props }, ref) => {
+    const { inputId, disabled } = useFileInputContext()
+
+    return (
+      <label
+        ref={ref}
+        htmlFor={inputId}
+        data-disabled={disabled ? '' : undefined}
+        {...props}
+      >
+        {children}
+      </label>
+    )
+  },
+)

package/src/components/FileInput/context.tsx

@@ -0,0 +1,24 @@
+import { createContext, useContext } from 'react'
+
+export type FileInputContextValue = {
+  /** The id of the hidden `<input type="file">`, for `Trigger`'s `htmlFor`. */
+  inputId: string
+  disabled: boolean
+}
+
+const FileInputContext =
+  /* @__PURE__ */ createContext<FileInputContextValue | null>(null)
+
+export const FileInputProvider = FileInputContext.Provider
+
+export function useFileInputContext(): FileInputContextValue
+export function useFileInputContext<T>(
+  selector: (state: FileInputContextValue) => T,
+): T
+export function useFileInputContext<T>(
+  selector?: (state: FileInputContextValue) => T,
+) {
+  const context = useContext(FileInputContext)
+  if (!context) throw new Error('Missing FileInputContext.Provider in the tree')
+  return selector ? selector(context) : context
+}

package/src/components/FileInput/index.tsx

@@ -0,0 +1,144 @@
+import {
+  ChangeEvent,
+  ComponentPropsWithoutRef,
+  forwardRef,
+  ReactNode,
+  useId,
+  useMemo,
+} from 'react'
+
+import { matchesAccept } from '@tremolo-ui/dom'
+
+import { visuallyHiddenStyle } from '../_util/visually-hidden'
+
+import { FileInputProvider } from './context'
+import { Trigger } from './Trigger'
+
+export interface FileInputProps {
+  /**
+   * Which files to take, written the way the HTML attribute is: a comma
+   * separated list of extensions (`.wav`), MIME types (`audio/wav`) and type
+   * groups (`audio/*`).
+   *
+   * **The browser treats it as a hint to the picker, not a rule.** A person
+   * can switch the picker to "All Files", so what arrives is checked again
+   * here, and anything that does not match goes to `onReject` instead.
+   */
+  accept?: string
+  /**
+   * Let more than one file be picked at a time.
+   * @default false
+   */
+  multiple?: boolean
+  /**
+   * Refuse to open the picker, and mark every part with `[data-disabled]`.
+   * @default false
+   */
+  disabled?: boolean
+
+  /**
+   * Called with the files that were picked and match `accept`.
+   *
+   * It is not called at all when the picker is dismissed, or when every file
+   * picked was rejected — an empty array never arrives, so there is no need to
+   * tell "nothing was chosen" from "the choice was cleared".
+   */
+  onChange?: (files: File[]) => void
+  /**
+   * Called with the files that were picked and do not match `accept`, so that
+   * the reason can be shown. Given alongside `onChange` when a selection held
+   * both.
+   */
+  onReject?: (files: File[]) => void
+
+  /** Normally a `FileInput.Trigger`, and whatever shows what was picked. */
+  children: ReactNode
+}
+
+type Props = FileInputProps &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof FileInputProps>
+
+/**
+ * Hands over the files a person picked.
+ *
+ * The `<input type="file">` is here, kept out of sight but in the tab order,
+ * because it is the control: it takes the focus, opens the picker on Enter,
+ * and carries the accessible name. What is on screen is whatever the children
+ * draw.
+ */
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
+  (
+    {
+      accept,
+      multiple = false,
+      disabled = false,
+      onChange,
+      onReject,
+      children,
+      // Pulled out of `props` so that they land on the input rather than on
+      // the wrapper: it is the control, and a description is only announced
+      // from the element that takes the focus. No declaration in
+      // `FileInputProps` is needed for this — they are already on the div
+      // attributes it is merged with, with the same types.
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledby,
+      'aria-describedby': ariaDescribedby,
+      ...props
+    },
+    ref,
+  ) => {
+    const inputId = useId()
+
+    const context = useMemo(() => ({ inputId, disabled }), [inputId, disabled])
+
+    function handleChange(event: ChangeEvent<HTMLInputElement>) {
+      const picked = Array.from(event.target.files ?? [])
+
+      // Picking the same file twice fires no second change event while the
+      // value is still on the input, so it is cleared as soon as it is read.
+      // Nothing is lost: the files are already in hand.
+      event.target.value = ''
+
+      const accepted: File[] = []
+      const rejected: File[] = []
+      for (const file of picked) {
+        if (matchesAccept(file, accept)) accepted.push(file)
+        else rejected.push(file)
+      }
+
+      if (rejected.length > 0) onReject?.(rejected)
+      if (accepted.length > 0) onChange?.(accepted)
+    }
+
+    return (
+      <FileInputProvider value={context}>
+        <div ref={ref} data-disabled={disabled ? '' : undefined} {...props}>
+          <input
+            id={inputId}
+            type="file"
+            accept={accept}
+            multiple={multiple}
+            disabled={disabled}
+            style={visuallyHiddenStyle}
+            aria-label={ariaLabel}
+            aria-labelledby={ariaLabelledby}
+            aria-describedby={ariaDescribedby}
+            onChange={handleChange}
+          />
+          {children}
+        </div>
+      </FileInputProvider>
+    )
+  },
+)
+
+/**
+ * Picks files, and hands them over as `File`s.
+ */
+export const FileInput = {
+  Root,
+  Trigger,
+}
+
+export { useFileInputContext, type FileInputContextValue } from './context'
+export { type FileInputTriggerProps } from './Trigger'