@tremolo-ui/react 0.1.5 → 0.1.6

package/src/components/Piano/index.tsx

@@ -3,11 +3,13 @@ import React, {
   ComponentPropsWithoutRef,
   createRef,
   CSSProperties,
+  forwardRef,
   ReactElement,
   ReactNode,
   RefObject,
   useCallback,
   useEffect,
+  useImperativeHandle,
   useMemo,
   useRef,
   useState,
@@ -35,13 +37,9 @@ import {
 import { KeyboardShortcuts } from './keyboardShortcuts'
 
 /**
- * Piano component
- *
- * TODO:
- * - add scale highlight
+ * [noteRange.first, noteRange.first + 1 ..., noteRange.last]
+ * @category Piano
  */
-
-/** @category Piano */
 export function getNoteRangeArray(noteRange: NoteRange) {
   return Array.from(
     { length: noteRange.last - noteRange.first + 1 },
@@ -51,10 +49,8 @@ export function getNoteRangeArray(noteRange: NoteRange) {
 
 /** @category Piano */
 export interface PianoProps {
-  // required
   noteRange: NoteRange
 
-  // optional
   glissando?: boolean
   midiMax?: number
   keyboardShortcuts?: KeyboardShortcuts
@@ -62,11 +58,10 @@ export interface PianoProps {
   whiteNoteWidth?: number
   blackNoteWidth?: number
   height?: number | string
-
   style?: CSSProperties
 
-  onPlayNote?: (noteNumber: number) => void
-  onStopNote?: (noteNumber: number) => void
+  onPlayNote?: (note: number, velocity?: number) => void
+  onStopNote?: (note: number) => void
 
   label?: (note: number, index: number) => ReactNode
 
@@ -78,236 +73,277 @@ export interface PianoProps {
 
 const blackPerWhiteWidth = defaultBlackKeyWidth / defaultWhiteKeyWidth // 0.65
 
+/**
+ * @category Piano
+ */
+export interface PianoMethods {
+  playNote: (note: number, velocity?: number) => void
+  stopNote: (note: number) => void
+}
+
+type Props = PianoProps &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof PianoProps>
+
 /**
  * Customizable piano component.
  * @category Piano
  */
-export function Piano({
-  noteRange,
-  glissando = true,
-  midiMax = 127,
-  keyboardShortcuts,
-  fill = false,
-  height = fill ? '100%' : 160,
-  whiteNoteWidth: _whiteNoteWidth = defaultWhiteKeyWidth,
-  style,
-  className,
-  onPlayNote,
-  onStopNote,
-  label,
-  children,
-  onPointerDown,
-  ...props
-}: PianoProps & Omit<ComponentPropsWithoutRef<'div'>, keyof PianoProps>) {
-  // -- state and ref ---
-  const [whiteNoteWidth, setWhiteNoteWidth] = useState(_whiteNoteWidth)
-  const keyRefs = useRef<RefObject<KeyMethods | null>[]>([])
-  for (let i = 0; i < noteRange.last - noteRange.first + 1; i++) {
-    keyRefs.current[i] = createRef<KeyMethods>()
-  }
-  const pianoRef = useRef<HTMLDivElement>(null)
-  const hitKeyIndex = useRef(-1)
+export const Piano = forwardRef<PianoMethods, Props>(
+  (
+    {
+      noteRange,
+      glissando = true,
+      midiMax = 127,
+      keyboardShortcuts,
+      fill = false,
+      height = fill ? '100%' : 160,
+      whiteNoteWidth: _whiteNoteWidth = defaultWhiteKeyWidth,
+      style,
+      className,
+      onPlayNote,
+      onStopNote,
+      label,
+      children,
+      onPointerDown,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    // -- state and ref ---
+    const [whiteNoteWidth, setWhiteNoteWidth] = useState(_whiteNoteWidth)
+    const keyRefs = useRef<RefObject<KeyMethods | null>[]>([])
+    for (let i = 0; i < noteRange.last - noteRange.first + 1; i++) {
+      keyRefs.current[i] = createRef<KeyMethods>()
+    }
+    const pianoRef = useRef<HTMLDivElement>(null)
+    const hitKeyIndex = useRef(-1)
 
-  // --- interpret props ---
-  const noteRangeArray = getNoteRangeArray(noteRange)
-  const whiteNotes = noteRangeArray.filter((v) => isWhiteKey(v))
-  const blackNotes = noteRangeArray.filter((v) => isBlackKey(v))
-  const whiteNoteCount = whiteNotes.length
-  const padding = 1
-  const staticWidth = (whiteNoteWidth + padding) * whiteNoteCount
-  // const blackNoteShiftPercent = 0.3
+    // --- interpret props ---
+    const noteRangeArray = getNoteRangeArray(noteRange)
+    const whiteNotes = noteRangeArray.filter((v) => isWhiteKey(v))
+    const blackNotes = noteRangeArray.filter((v) => isBlackKey(v))
+    const whiteNoteCount = whiteNotes.length
+    const padding = 1
+    const staticWidth = (whiteNoteWidth + padding) * whiteNoteCount
+    // const blackNoteShiftPercent = 0.3
 
-  const childrenWithProps = useMemo(() => {
-    return (
-      children &&
-      React.Children.map(children, (child, index) => {
-        if (React.isValidElement(child)) {
-          const __width =
-            child.type == WhiteKey ? whiteNoteWidth : whiteNoteWidth * 0.65
-          const props = { ref: keyRefs.current[index], __width }
-          return React.cloneElement(child, props)
+    const childrenWithProps = useMemo(() => {
+      return (
+        children &&
+        React.Children.map(children, (child, index) => {
+          if (React.isValidElement(child)) {
+            const __width =
+              child.type == WhiteKey ? whiteNoteWidth : whiteNoteWidth * 0.65
+            const props = { ref: keyRefs.current[index], __width }
+            return React.cloneElement(child, props)
+          }
+          return child
+        })
+      )
+    }, [children, whiteNoteWidth])
+
+    // --- internal functions ---
+    const notePosition = useCallback(
+      (note: number) => {
+        const pitchPositions: Record<NoteKey, number> = {
+          C: 0,
+          'C#': 1,
+          D: 1,
+          'D#': 2,
+          E: 2,
+          F: 3,
+          'F#': 4,
+          G: 4,
+          'G#': 5,
+          A: 5,
+          'A#': 6,
+          B: 6,
         }
-        return child
-      })
-    )
-  }, [children, whiteNoteWidth])
 
-  // --- internal functions ---
-  const notePosition = useCallback(
-    (note: number) => {
-      const pitchPositions: Record<NoteKey, number> = {
-        C: 0,
-        'C#': 1,
-        D: 1,
-        'D#': 2,
-        E: 2,
-        F: 3,
-        'F#': 4,
-        G: 4,
-        'G#': 5,
-        A: 5,
-        'A#': 6,
-        B: 6,
-      }
+        const blackNoteWidth = whiteNoteWidth * blackPerWhiteWidth
+        const padding = 1
+        const targetNoteKey = noteKey(note)
+        const firstNoteKey = noteKey(noteRange.first)
+        const octave = Math.floor((note - noteRange.first) / 12)
+        const octaveOffset =
+          noteKeys.indexOf(firstNoteKey) > noteKeys.indexOf(targetNoteKey)
+            ? 1
+            : 0
+        const w = whiteNoteWidth + padding
+        const pos = pitchPositions[targetNoteKey] - pitchPositions[firstNoteKey]
+        const blackKeyOffset = isBlackKey(note) ? blackNoteWidth / 2 : 0
+        return pos * w + (octave + octaveOffset) * 7 * w - blackKeyOffset
+      },
+      [noteRange.first, whiteNoteWidth],
+    )
 
-      const blackNoteWidth = whiteNoteWidth * blackPerWhiteWidth
-      const padding = 1
-      const targetNoteKey = noteKey(note)
-      const firstNoteKey = noteKey(noteRange.first)
-      const octave = Math.floor((note - noteRange.first) / 12)
-      const octaveOffset =
-        noteKeys.indexOf(firstNoteKey) > noteKeys.indexOf(targetNoteKey) ? 1 : 0
-      const w = whiteNoteWidth + padding
-      const pos = pitchPositions[targetNoteKey] - pitchPositions[firstNoteKey]
-      const blackKeyOffset = isBlackKey(note) ? blackNoteWidth / 2 : 0
-      return pos * w + (octave + octaveOffset) * 7 * w - blackKeyOffset
-    },
-    [noteRange.first, whiteNoteWidth],
-  )
+    const getHitKeyIndex = useCallback(
+      (x: number, y: number) => {
+        if (!pianoRef.current) return -1
+        const containerHeight = pianoRef.current.clientHeight
+        const notes = [...blackNotes, ...whiteNotes]
+        for (let i = 0; i < notes.length; i++) {
+          const note = notes[i]
+          const pos = notePosition(note)
+          const w = isWhiteKey(note)
+            ? whiteNoteWidth
+            : whiteNoteWidth * blackPerWhiteWidth
+          const h = isWhiteKey(note) ? containerHeight : containerHeight * 0.6
+          if (pos <= x && x < pos + w && 0 <= y && y < h) {
+            return note
+          }
+        }
+        return -1
+      },
+      [blackNotes, notePosition, whiteNoteWidth, whiteNotes],
+    )
 
-  const getHitKeyIndex = useCallback(
-    (x: number, y: number) => {
-      if (!pianoRef.current) return -1
-      const containerHeight = pianoRef.current.clientHeight
-      const notes = [...blackNotes, ...whiteNotes]
-      for (let i = 0; i < notes.length; i++) {
-        const note = notes[i]
-        const pos = notePosition(note)
-        const w = isWhiteKey(note)
-          ? whiteNoteWidth
-          : whiteNoteWidth * blackPerWhiteWidth
-        const h = isWhiteKey(note) ? containerHeight : containerHeight * 0.6
-        if (pos <= x && x < pos + w && 0 <= y && y < h) {
-          return note
+    // TODO: 単一のポインターに対しては、useDragで対応可能だが、
+    // マルチタッチに対しては、TouchEventを使う必要がありそう
+    // 取り敢えず、シングルタッチだけ対応
+    const onDrag = useCallback(
+      (perX: number, perY: number) => {
+        if (!pianoRef.current) return
+        const x = perX * staticWidth
+        const y = perY * pianoRef.current.clientHeight
+        const note = getHitKeyIndex(x, y)
+        const index = noteRangeArray.indexOf(note)
+        if (index == -1) return
+        if (hitKeyIndex.current != index) {
+          keyRefs.current[hitKeyIndex.current]?.current?.stop()
+          keyRefs.current[index]?.current?.play()
+          hitKeyIndex.current = index
         }
-      }
-      return -1
-    },
-    [blackNotes, notePosition, whiteNoteWidth, whiteNotes],
-  )
+      },
+      [getHitKeyIndex, noteRangeArray, staticWidth],
+    )
 
-  // TODO: 単一のポインターに対しては、useDragで対応可能だが、
-  // マルチタッチに対しては、TouchEventを使う必要がありそう
-  // 取り敢えず、シングルタッチだけ対応
-  const onDrag = useCallback(
-    (perX: number, perY: number) => {
-      if (!pianoRef.current) return
-      const x = perX * staticWidth
-      const y = perY * pianoRef.current.clientHeight
-      const note = getHitKeyIndex(x, y)
-      const index = noteRangeArray.indexOf(note)
-      if (index == -1) return
-      if (hitKeyIndex.current != index) {
+    const onDragEnd = useCallback(() => {
+      if (keyRefs.current[hitKeyIndex.current]?.current?.played()) {
         keyRefs.current[hitKeyIndex.current]?.current?.stop()
-        keyRefs.current[index]?.current?.play()
-        hitKeyIndex.current = index
       }
-    },
-    [getHitKeyIndex, noteRangeArray, staticWidth],
-  )
+      hitKeyIndex.current = -1
+    }, [keyRefs])
 
-  const onDragEnd = useCallback(() => {
-    if (keyRefs.current[hitKeyIndex.current]?.current?.played()) {
-      keyRefs.current[hitKeyIndex.current]?.current?.stop()
-    }
-    hitKeyIndex.current = -1
-  }, [keyRefs])
+    // --- hooks ---
+    useEffect(() => {
+      if (fill && pianoRef.current) {
+        const parent = pianoRef.current.parentElement
+        if (!parent) throw new Error("doesn't have a parent element.")
+        const resizeObserver = new ResizeObserver(() => {
+          const w = pianoRef.current!.clientWidth
+          setWhiteNoteWidth(w / whiteNoteCount - padding)
+        })
+        resizeObserver.observe(parent)
+        return () => {
+          resizeObserver.unobserve(parent)
+        }
+      } else {
+        setWhiteNoteWidth(_whiteNoteWidth)
+      }
+    }, [fill, _whiteNoteWidth, whiteNoteCount])
 
-  // --- hooks ---
-  useEffect(() => {
-    if (fill && pianoRef.current) {
-      const parent = pianoRef.current.parentElement
-      if (!parent) throw new Error("doesn't have a parent element.")
-      const resizeObserver = new ResizeObserver(() => {
-        const w = pianoRef.current!.clientWidth
-        setWhiteNoteWidth(w / whiteNoteCount - padding)
+    const [touchMoveRefCallback, pointerDownHandler] =
+      useDragWithElement<HTMLDivElement>({
+        baseElementRef: pianoRef,
+        onDrag: onDrag,
+        onDragEnd: onDragEnd,
       })
-      resizeObserver.observe(parent)
-      return () => {
-        resizeObserver.unobserve(parent)
-      }
-    } else {
-      setWhiteNoteWidth(_whiteNoteWidth)
-    }
-  }, [fill, _whiteNoteWidth, whiteNoteCount])
 
-  const [touchMoveRefCallback, pointerDownHandler] =
-    useDragWithElement<HTMLDivElement>({
-      baseElementRef: pianoRef,
-      onDrag: onDrag,
-      onDragEnd: onDragEnd,
+    useEventListener(globalThis.window, 'keydown', (e) => {
+      if (e.repeat) return
+      if (!keyboardShortcuts) return
+      const index = keyboardShortcuts.keys.indexOf(e.key)
+      if (index != -1) {
+        if (!keyRefs.current[index]?.current?.played()) {
+          keyRefs.current[index]?.current?.play()
+        }
+      }
     })
 
-  useEventListener(globalThis.window, 'keydown', (e) => {
-    if (e.repeat) return
-    if (!keyboardShortcuts) return
-    const index = keyboardShortcuts.keys.indexOf(e.key)
-    if (index != -1) {
-      if (!keyRefs.current[index]?.current?.played()) {
-        keyRefs.current[index]?.current?.play()
+    useEventListener(globalThis.window, 'keyup', (e) => {
+      if (e.repeat) return
+      if (!keyboardShortcuts) return
+      const index = keyboardShortcuts.keys.indexOf(e.key)
+      if (index != -1) {
+        keyRefs.current[index]?.current?.stop()
       }
-    }
-  })
+    })
 
-  useEventListener(globalThis.window, 'keyup', (e) => {
-    if (e.repeat) return
-    if (!keyboardShortcuts) return
-    const index = keyboardShortcuts.keys.indexOf(e.key)
-    if (index != -1) {
-      keyRefs.current[index]?.current?.stop()
-    }
-  })
+    useImperativeHandle(forwardedRef, () => {
+      return {
+        playNote(note, velocity) {
+          const index = noteRangeArray.indexOf(note)
+          if (index != -1) {
+            if (!keyRefs.current[index]?.current?.played()) {
+              keyRefs.current[index]?.current?.play(velocity)
+            }
+          } else {
+            onPlayNote?.(note, velocity)
+          }
+        },
+        stopNote(note: number) {
+          const index = noteRangeArray.indexOf(note)
+          if (index != -1) {
+            keyRefs.current[index]?.current?.stop()
+          } else {
+            onStopNote?.(note)
+          }
+        },
+      }
+    }, [noteRangeArray, onPlayNote, onStopNote])
 
-  return (
-    <PianoProvider
-      notePosition={notePosition}
-      noteRange={noteRange}
-      glissando={glissando}
-      midiMax={midiMax}
-      fill={fill}
-      onPlayNote={onPlayNote}
-      onStopNote={onStopNote}
-      label={label}
-    >
-      <div
-        ref={(div) => {
-          pianoRef.current = div
-          touchMoveRefCallback(div)
-        }}
-        className={clsx('tremolo-piano', className)}
-        style={{
-          width: fill ? '100%' : staticWidth,
-          height: height,
-          ...style,
-        }}
-        onPointerDown={(event) => {
-          pointerDownHandler(event)
-          onPointerDown?.(event)
-        }}
-        {...props}
+    return (
+      <PianoProvider
+        notePosition={notePosition}
+        noteRange={noteRange}
+        glissando={glissando}
+        midiMax={midiMax}
+        fill={fill}
+        onPlayNote={onPlayNote}
+        onStopNote={onStopNote}
+        label={label}
       >
-        {childrenWithProps ||
-          noteRangeArray.map((note, index) =>
-            isWhiteKey(note) ? (
-              <WhiteKey
-                ref={keyRefs.current[index]}
-                key={note}
-                noteNumber={note}
-                __width={whiteNoteWidth}
-              />
-            ) : (
-              <BlackKey
-                ref={keyRefs.current[index]}
-                key={note}
-                noteNumber={note}
-                __width={whiteNoteWidth * blackPerWhiteWidth}
-              />
-            ),
-          )}
-      </div>
-    </PianoProvider>
-  )
-}
+        <div
+          ref={(div) => {
+            pianoRef.current = div
+            touchMoveRefCallback(div)
+          }}
+          className={clsx('tremolo-piano', className)}
+          style={{
+            width: fill ? '100%' : staticWidth,
+            height: height,
+            ...style,
+          }}
+          onPointerDown={(event) => {
+            pointerDownHandler(event)
+            onPointerDown?.(event)
+          }}
+          {...props}
+        >
+          {childrenWithProps ||
+            noteRangeArray.map((note, index) =>
+              isWhiteKey(note) ? (
+                <WhiteKey
+                  ref={keyRefs.current[index]}
+                  key={note}
+                  noteNumber={note}
+                  __width={whiteNoteWidth}
+                />
+              ) : (
+                <BlackKey
+                  ref={keyRefs.current[index]}
+                  key={note}
+                  noteNumber={note}
+                  __width={whiteNoteWidth * blackPerWhiteWidth}
+                />
+              ),
+            )}
+        </div>
+      </PianoProvider>
+    )
+  },
+)
 
 export { type KeyboardShortcuts, SHORTCUTS } from './keyboardShortcuts'
 export { WhiteKey, BlackKey, type KeyProps, type KeyMethods } from './key'

package/src/components/Piano/key.tsx

@@ -40,7 +40,7 @@ export interface KeyProps {
  * @category Piano
  */
 export interface KeyMethods {
-  play: () => void
+  play: (velocity?: number) => void
   stop: () => void
   played: () => boolean
 }
@@ -92,10 +92,10 @@ const KeyImpl = forwardRef<KeyMethods, ImplProps>(
 
     useImperativeHandle(ref, () => {
       return {
-        play() {
+        play(velocity) {
           if (disabled) return
           setPlayed(true)
-          if (onPlayNote) onPlayNote(noteNumber)
+          if (onPlayNote) onPlayNote(noteNumber, velocity)
         },
         stop() {
           setPlayed(false)

package/src/components/Slider/Track.tsx

@@ -64,8 +64,8 @@ export function SliderTrack({
           : {
               ...colors,
               background: xor(vertical, reverse)
-                ? `linear-gradient(to ${direction}, var(--inactive, #eee) ${__percent}%, var(--active, #7998ec) ${__percent}%)`
-                : `linear-gradient(to ${direction}, var(--active, #7998ec) ${__percent}%, var(--inactive, #eee) ${__percent}%)`,
+                ? `linear-gradient(to ${direction}, var(--inactive) ${__percent}%, var(--active) ${__percent}%)`
+                : `linear-gradient(to ${direction}, var(--active) ${__percent}%, var(--inactive) ${__percent}%)`,
               borderRadius: styleHelper(thickness!, '/', 2),
               width: !vertical ? length : thickness,
               height: vertical ? length : thickness,

package/src/components/Slider/index.tsx

@@ -112,7 +112,7 @@ export const Slider = forwardRef<SliderMethods, Props>(
       onKeyDown,
       ...props
     }: Props,
-    ref,
+    forwardedRef,
   ) => {
     // -- state and ref ---
     const trackElementRef = useRef<HTMLDivElement>(null)
@@ -245,7 +245,7 @@ export const Slider = forwardRef<SliderMethods, Props>(
       [wheel, vertical, readonly, onChange, updateValueByEvent],
     )
 
-    useImperativeHandle(ref, () => {
+    useImperativeHandle(forwardedRef, () => {
       return {
         focus() {
           thumbRef.current?.focus()

package/src/components/XYPad/index.tsx

@@ -106,7 +106,7 @@ export const XYPad = forwardRef<XYPadMethods, Props>(
       children,
       ...props
     }: Props,
-    ref,
+    forwardedRef,
   ) => {
     const x = useMemo(() => {
       return { ...defaultValueOptions, ..._x }
@@ -276,7 +276,7 @@ export const XYPad = forwardRef<XYPadMethods, Props>(
       [x, y, onChange, readonly, updateValueByEvent],
     )
 
-    useImperativeHandle(ref, () => {
+    useImperativeHandle(forwardedRef, () => {
       return {
         focus() {
           thumbRef.current?.focus()

package/src/hooks/useAnimationFrame.ts

@@ -1,5 +1,8 @@
 import { DependencyList, useCallback, useEffect, useRef } from 'react'
 
+/**
+ * @category hooks
+ */
 export function useAnimationFrame(
   callback = () => {},
   deps: DependencyList = [],

package/src/hooks/useCallbackRef.ts

@@ -1,8 +1,8 @@
 import { useCallback, useInsertionEffect, useRef } from 'react'
 
 /**
- * This hook is user-land implementation of the experimental `useEffectEvent` hook.
- * React docs: https://react.dev/learn/separating-events-from-effects#declaring-an-effect-event
+ * Internal
+ * @private
  */
 export function useCallbackRef<Args extends unknown[], Return>(
   callback: ((...args: Args) => Return) | undefined,

package/src/hooks/useDrag.ts

@@ -3,7 +3,7 @@ import { useRef, useCallback } from 'react'
 import { useEventListener } from './useEventListener'
 import { useRefCallbackEvent } from './useRefCallbackEvent'
 
-export interface UseDragProps {
+interface UseDragProps {
   threshold?: number
 
   onDrag: (x: number, y: number, deltaX: number, deltaY: number) => void
@@ -12,6 +12,7 @@ export interface UseDragProps {
 }
 
 /**
+ * @category hooks
  * @returns [refCallback, pointerDownHandler]
  */
 export function useDrag<T extends Element>({

package/src/hooks/useDragWithElement.ts

@@ -5,7 +5,7 @@ import { normalizeValue } from '@tremolo-ui/functions'
 import { useEventListener } from './useEventListener'
 import { useRefCallbackEvent } from './useRefCallbackEvent'
 
-export interface UseDragWithElementProps<T extends Element> {
+interface UseDragWithElementProps<T extends Element> {
   baseElementRef: RefObject<T | null>
   onDrag: (normalizedX: number, normalizedY: number) => void
   onDragStart?: (normalizedX: number, normalizedY: number) => void
@@ -13,6 +13,7 @@ export interface UseDragWithElementProps<T extends Element> {
 }
 
 /**
+ * @category hooks
  * @returns [refCallback, pointerDownHandler]
  */
 export function useDragWithElement<T extends Element>({