@tremolo-ui/react 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tremolo-ui/react",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "React component library for audio app",
   "type": "module",
   "sideEffects": false,
@@ -30,7 +30,7 @@
     "@testing-library/react": "16.3.3",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
-    "jotai": "2.20.3",
+    "jotai": "3.0.0",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "storybook": "10.6.0",
@@ -41,8 +41,8 @@
     "react-dom": "^18 || ^19"
   },
   "dependencies": {
-    "@tremolo-ui/dom": "^0.6.0",
-    "@tremolo-ui/functions": "^0.6.0"
+    "@tremolo-ui/dom": "^0.7.0",
+    "@tremolo-ui/functions": "^0.7.0"
   },
   "files": [
     "dist",

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'

package/src/components/Knob/index.tsx

@@ -9,16 +9,15 @@ import {
   useRef,
 } from 'react'
 
-import type { AxisOptions, XY } from '@tremolo-ui/dom'
 import {
   applyDelta,
+  type AxisOptions,
   type InputEventOption,
   type ModifierValue,
   selectModifier,
-  linearScale,
-  type Scale,
-  type ValueRange,
-} from '@tremolo-ui/functions'
+  type XY,
+} from '@tremolo-ui/dom'
+import { linearScale, type Scale, type ValueRange } from '@tremolo-ui/functions'
 
 import { useComposedRefs } from '../../compose-refs'
 import { useCheckSteps } from '../../hooks/_internal/useCheckSteps'
@@ -37,6 +36,8 @@ import { InactiveLine } from './InactiveLine'
 import { SVGRoot } from './SVGRoot'
 import { Thumb } from './Thumb'
 
+import type { CSSVariables } from '../../css-variables'
+
 const defaultExternalStyles: KnobProps['externalStyles'] = {
   cursor: 'grabbing',
 }
@@ -200,6 +201,8 @@ export interface KnobProps {
    * </Knob.Root>
    */
   children: ReactNode
+
+  style?: CSSProperties & CSSVariables<'knob-size'>
 }
 
 export interface KnobMethods {

package/src/components/NumberInput/DecrementStepper.tsx

@@ -1,22 +1,11 @@
-import { ComponentPropsWithoutRef } from 'react'
-
 import {
   StepperArrow,
   StepperButton,
-  StepperButtonProps,
+  type StepperButtonProps,
 } from './StepperButton'
 
-// An interface rather than an alias; see `NumberInputIncrementStepperProps`.
-export interface NumberInputDecrementStepperProps extends StepperButtonProps {}
-
 /** Lowers the value by one `step`, repeating while held. */
-export function DecrementStepper(
-  props: NumberInputDecrementStepperProps &
-    Omit<
-      ComponentPropsWithoutRef<'div'>,
-      keyof NumberInputDecrementStepperProps
-    >,
-) {
+export function DecrementStepper(props: StepperButtonProps) {
   return (
     <StepperButton
       direction={-1}

package/src/components/NumberInput/IncrementStepper.tsx

@@ -1,23 +1,11 @@
-import { ComponentPropsWithoutRef } from 'react'
-
 import {
   StepperArrow,
   StepperButton,
-  StepperButtonProps,
+  type StepperButtonProps,
 } from './StepperButton'
 
-// An interface rather than an alias, so that typedoc lists the props: the
-// shared `StepperButtonProps` is not exported for it to follow.
-export interface NumberInputIncrementStepperProps extends StepperButtonProps {}
-
 /** Raises the value by one `step`, repeating while held. */
-export function IncrementStepper(
-  props: NumberInputIncrementStepperProps &
-    Omit<
-      ComponentPropsWithoutRef<'div'>,
-      keyof NumberInputIncrementStepperProps
-    >,
-) {
+export function IncrementStepper(props: StepperButtonProps) {
   return (
     <StepperButton
       direction={1}

package/src/components/NumberInput/InputField.tsx

@@ -1,6 +1,5 @@
 import {
   ComponentPropsWithoutRef,
-  CSSProperties,
   forwardRef,
   useEffect,
   useLayoutEffect,
@@ -12,16 +11,11 @@ import { useComposedRefs } from '../../compose-refs'
 
 import { useNumberInputContext } from './context'
 
-export interface NumberInputInputFieldProps {
-  className?: string
-  style?: CSSProperties
-}
-
-type Props = NumberInputInputFieldProps &
-  Omit<
-    ComponentPropsWithoutRef<'input'>,
-    keyof NumberInputInputFieldProps | 'type' | 'value' | 'defaultValue'
-  >
+// The value belongs to `NumberInput.Root`, and the field is always text.
+type Props = Omit<
+  ComponentPropsWithoutRef<'input'>,
+  'type' | 'value' | 'defaultValue'
+>
 
 /** The leading number of the displayed text, whatever the format put around it. */
 const NUMBER_PREFIX = /^\s*-?[\d.,]*/

package/src/components/NumberInput/Stepper.tsx

@@ -1,33 +1,18 @@
-import {
-  ComponentPropsWithoutRef,
-  CSSProperties,
-  forwardRef,
-  ReactNode,
-  useMemo,
-  useRef,
-} from 'react'
+import { ComponentPropsWithoutRef, forwardRef, useMemo, useRef } from 'react'
 
 import {
   applyDelta,
+  type InputEventOption,
   mapModifier,
   selectModifier,
-  type InputEventOption,
-} from '@tremolo-ui/functions'
+} from '@tremolo-ui/dom'
 
 import { useComposedRefs } from '../../compose-refs'
 import { useDrag } from '../../hooks/useDrag'
 
 import { StepperProvider, useNumberInputContext } from './context'
 
-export interface NumberInputStepperProps {
-  className?: string
-  style?: CSSProperties
-  /** `<NumberInput.IncrementStepper />` and `<NumberInput.DecrementStepper />` go here. */
-  children?: ReactNode
-}
-
-type Props = NumberInputStepperProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof NumberInputStepperProps>
+type Props = ComponentPropsWithoutRef<'div'>
 
 /**
  * The area the steppers sit in, and a drag handle in its own right: dragging it

package/src/components/NumberInput/StepperButton.tsx

@@ -1,18 +1,23 @@
-import { ComponentPropsWithoutRef, CSSProperties, ReactNode } from 'react'
+import { ComponentPropsWithoutRef, ReactNode, CSSProperties } from 'react'
 
 import { useLongPress } from '../../hooks/useLongPress'
 
 import { useNumberInputContext, useStepperContext } from './context'
 
-export interface StepperButtonProps {
-  className?: string
-  style?: CSSProperties
-  /** Replaces the default arrow. Size it with the `--stepper-icon-size` variable. */
-  children?: ReactNode
+import type { CSSVariables } from '../../css-variables'
+
+/**
+ * `--stepper-icon-size` is read by the default arrow inside, and set on the
+ * button so that it inherits there.
+ */
+export type StepperButtonProps = Omit<
+  ComponentPropsWithoutRef<'div'>,
+  'style'
+> & {
+  style?: CSSProperties & CSSVariables<'stepper-icon-size'>
 }
 
-type Props = StepperButtonProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof StepperButtonProps>
+type Props = StepperButtonProps
 
 /**
  * Shared body of `IncrementStepper` and `DecrementStepper`: the two differ only

package/src/components/NumberInput/context.tsx

@@ -1,12 +1,11 @@
 import { createContext, RefObject, useContext } from 'react'
 
-import type {
-  InputEventOption,
-  ModifierState,
-  ModifierValue,
-  Scale,
-  ValueRange,
-} from '@tremolo-ui/functions'
+import {
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+} from '@tremolo-ui/dom'
+import { type Scale, type ValueRange } from '@tremolo-ui/functions'
 
 export type NumberInputContextValue = {
   value: number

package/src/components/NumberInput/index.tsx

@@ -1,6 +1,5 @@
 import {
   ComponentPropsWithoutRef,
-  CSSProperties,
   forwardRef,
   ReactNode,
   useCallback,
@@ -15,11 +14,9 @@ import {
   InputEventOption,
   ModifierState,
   type ModifierValue,
-  linearScale,
-  selectInputEvent,
-  type Scale,
-  type ValueRange,
-} from '@tremolo-ui/functions'
+  selectModifier,
+} from '@tremolo-ui/dom'
+import { linearScale, type Scale, type ValueRange } from '@tremolo-ui/functions'
 
 import { useCheckSteps } from '../../hooks/_internal/useCheckSteps'
 import { useWheel } from '../../hooks/useWheel'
@@ -219,8 +216,6 @@ export interface NumberInputProps {
    */
   readonly?: boolean
 
-  className?: string
-  style?: CSSProperties
   /**
    * Called with the new value. While the user types, it is called for every
    * entry that reads as a number, unclamped; committing the entry calls it
@@ -404,7 +399,7 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         option: ModifierValue<InputEventOption>,
         modifiers?: ModifierState,
       ) => {
-        const [mode] = selectInputEvent(option, modifiers).option
+        const [mode] = selectModifier(option, modifiers).value
         changeValue(
           applyDelta(
             value,
@@ -532,7 +527,3 @@ export const NumberInput = {
 }
 
 export { useNumberInputContext, type NumberInputContextValue } from './context'
-export { type NumberInputInputFieldProps } from './InputField'
-export { type NumberInputStepperProps } from './Stepper'
-export { type NumberInputIncrementStepperProps } from './IncrementStepper'
-export { type NumberInputDecrementStepperProps } from './DecrementStepper'

package/src/components/Piano/index.tsx

@@ -11,23 +11,25 @@ import {
   useState,
 } from 'react'
 
-import { createPianoInput, type PianoInputInstance } from '@tremolo-ui/dom'
 import {
   blackKeyWidth,
+  createPianoInput,
   getNoteRangeArray,
-  isWhiteKey,
-  noteKey,
   notePosition,
   pianoWidth,
   type NoteRange,
+  type PianoInputInstance,
   type PianoLayout,
-} from '@tremolo-ui/functions'
+} from '@tremolo-ui/dom'
+import { isWhiteKey, noteKey } from '@tremolo-ui/functions'
 
 import { useEventListener } from '../../hooks/useEventListener'
 import { cssLength } from '../_util/css-length'
 
 import { KeyboardShortcuts } from './keyboard-shortcuts'
 
+import type { CSSVariables } from '../../css-variables'
+
 type KeyboardShortcutsScope = 'root' | 'window'
 
 function isEditableTarget(target: EventTarget | null) {
@@ -48,12 +50,6 @@ function shortcutKey(event: KeyboardEvent) {
   return event.code || event.key
 }
 
-/**
- * `style` that also takes CSS custom properties, which is how a key's colours
- * are set: see `index.css` for the ones each key type reads.
- */
-export type CSSVariables = Record<`--${string}`, string | number | undefined>
-
 /**
  * What {@link PianoProps.keyProps} may return for one key.
  *
@@ -62,7 +58,8 @@ export type CSSVariables = Record<`--${string}`, string | number | undefined>
  * mark a key out.
  */
 export type KeyAttributes = Omit<ComponentPropsWithoutRef<'div'>, 'style'> & {
-  style?: CSSProperties & CSSVariables
+  style?: CSSProperties &
+    CSSVariables<'color' | 'bg' | 'active-color' | 'active-bg'>
 } & Record<`data-${string}`, string | number | boolean | undefined>
 
 /** What a key is, when {@link PianoProps.label} or `keyProps` is asked about it. */
@@ -161,8 +158,6 @@ export interface PianoProps {
    */
   height?: number | string
 
-  style?: CSSProperties & CSSVariables
-
   /**
    * What to draw inside a key. `''`, `null` and `undefined` leave it bare, so
    * a layout with gaps — {@link SHORTCUTS.HOME_ROW_NATURAL}, say — needs no
@@ -194,6 +189,8 @@ export interface PianoProps {
   onPlayNote?: (note: number, velocity?: number) => void
   /** Called once everything holding a note has let go of it. */
   onStopNote?: (note: number) => void
+
+  style?: CSSProperties & CSSVariables<'height'>
 }
 
 export interface PianoMethods {

package/src/components/PointsEditor/Background.tsx

@@ -1,17 +1,11 @@
-import { ComponentPropsWithoutRef, ReactNode } from 'react'
-
-export interface PointsEditorBackgroundProps {
-  /** Whatever the points are placed over: a graph, a canvas, an image. */
-  children?: ReactNode
-}
+import { ComponentPropsWithoutRef } from 'react'
 
 export function Background({
   className,
   children,
   style,
   ...props
-}: PointsEditorBackgroundProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorBackgroundProps>) {
+}: ComponentPropsWithoutRef<'div'>) {
   return (
     <div
       className={className}