@tremolo-ui/vue 0.7.0

package/src/components/Piano/Piano.ts

@@ -0,0 +1,243 @@
+import {
+  computed,
+  defineComponent,
+  h,
+  ref,
+  watch,
+  type HTMLAttributes,
+  type PropType,
+  type SlotsType,
+} from 'vue'
+
+import {
+  blackKeyWidth,
+  createPianoInput,
+  fitWhiteKeyWidth,
+  getNoteRangeArray,
+  notePosition,
+  pianoWidth,
+  type KeyboardShortcuts,
+  type KeyboardShortcutsScope,
+  type NoteRange,
+  type PianoInputInstance,
+  type PianoLayout,
+} from '@tremolo-ui/dom'
+import { isWhiteKey, noteKey } from '@tremolo-ui/functions'
+
+/** What a key is, when the `label` slot or `keyProps` is asked about it. */
+export interface KeyState {
+  /** Position in the note range, counting from `noteRange.first`. */
+  index: number
+  keyType: 'white' | 'black'
+  /** Whether the note is currently sounding. */
+  active: boolean
+  /** Whether the note is above `midiMax` and cannot sound. */
+  disabled: boolean
+}
+
+/** What `keyProps` may return for one key. */
+export type KeyAttributes = HTMLAttributes &
+  Record<`data-${string}`, string | number | boolean | undefined>
+
+/**
+ * Customizable piano. The keys are drawn by the component; what goes inside
+ * one is the `label` slot, which receives the note and its state.
+ */
+export const Piano = /* @__PURE__ */ defineComponent({
+  name: 'Piano',
+  props: {
+    /** The notes drawn, from `first` to `last`. */
+    noteRange: { type: Object as PropType<NoteRange>, required: true },
+    /** Let a pointer slide from one key to the next. @default true */
+    glissando: { type: Boolean, default: true },
+    /** Highest note that can sound. @default 127 */
+    midiMax: { type: Number, default: 127 },
+    /** Play notes from the computer keyboard. See `SHORTCUTS` in `@tremolo-ui/dom`. */
+    keyboardShortcuts: Object as PropType<KeyboardShortcuts>,
+    /** Where keyboard shortcuts listen. @default 'root' */
+    keyboardShortcutsScope: {
+      type: String as PropType<KeyboardShortcutsScope>,
+      default: 'root',
+    },
+    /** Follow the width of the parent element. */
+    resizable: Boolean,
+    /** Width of a white key in pixels. @default 40 */
+    whiteKeyWidth: { type: Number, default: 40 },
+    /** Space between two white keys, in pixels. @default 1 */
+    keyGap: { type: Number, default: 1 },
+    /** Width of a black key, as a fraction of a white one. @default 0.65 */
+    blackKeyWidthRatio: { type: Number, default: 0.65 },
+    /** Height of a black key, as a fraction of the keyboard. @default 0.6 */
+    blackKeyHeightRatio: { type: Number, default: 0.6 },
+    /** Classes for the label inside each key. */
+    classes: Object as PropType<{
+      keyLabelWrapper?: string
+      keyLabel?: string
+    }>,
+    /**
+     * Extra attributes for one key, by note. The geometry of the key is
+     * applied after the returned style and cannot be overridden.
+     */
+    keyProps: Function as PropType<
+      (note: number, state: KeyState) => KeyAttributes
+    >,
+  },
+  emits: {
+    /** A note started sounding. */
+    playNote: (note: number, _velocity?: number) => typeof note === 'number',
+    /** Everything holding a note let go of it. */
+    stopNote: (note: number) => typeof note === 'number',
+  },
+  slots: Object as SlotsType<{
+    label: { note: number; state: KeyState }
+  }>,
+  setup(props, { slots, emit, expose }) {
+    const root = ref<HTMLDivElement | null>(null)
+    const activeNotes = ref<number[]>([])
+    /** Set while `resizable` is on, measured from the parent. */
+    const resizedKeyWidth = ref<number | null>(null)
+
+    const notes = computed(() => getNoteRangeArray(props.noteRange))
+    const layout = computed((): PianoLayout => ({
+      noteRange: props.noteRange,
+      whiteKeyWidth: props.resizable
+        ? (resizedKeyWidth.value ?? props.whiteKeyWidth)
+        : props.whiteKeyWidth,
+      keyGap: props.keyGap,
+      blackKeyWidthRatio: props.blackKeyWidthRatio,
+      blackKeyHeightRatio: props.blackKeyHeightRatio,
+    }))
+    const settings = () => ({
+      layout: layout.value,
+      glissando: props.glissando,
+      midiMax: props.midiMax,
+      keyboardShortcuts: props.keyboardShortcuts,
+      keyboardShortcutsScope: props.keyboardShortcutsScope,
+    })
+
+    let instance: PianoInputInstance | null = null
+
+    // Only the element decides how the instance is wired. Everything else is
+    // pushed with update(), so that changing the layout mid-drag — the parent
+    // being resized under `resizable`, say — does not abort the drag.
+    watch(
+      root,
+      (element, _, onCleanup) => {
+        if (!element) return
+        const current = createPianoInput(element, {
+          ...settings(),
+          onPlayNote: (note, velocity) => emit('playNote', note, velocity),
+          onStopNote: (note) => emit('stopNote', note),
+          onActiveNotesChange: (next) => {
+            activeNotes.value = next
+          },
+        })
+        instance = current
+        onCleanup(() => {
+          instance = null
+          current.destroy()
+        })
+      },
+      { immediate: true, flush: 'post' },
+    )
+    watch(settings, (next) => instance?.update(next))
+
+    watch(
+      () =>
+        [
+          root.value,
+          props.resizable,
+          props.noteRange.first,
+          props.noteRange.last,
+          props.keyGap,
+          props.blackKeyWidthRatio,
+        ] as const,
+      (
+        [element, resizable, first, last, keyGap, blackKeyWidthRatio],
+        _,
+        onCleanup,
+      ) => {
+        if (!resizable || !element) return
+        const parent = element.parentElement
+        if (!parent) throw new Error("doesn't have a parent element.")
+        const observer = new ResizeObserver(() => {
+          resizedKeyWidth.value = fitWhiteKeyWidth(element.clientWidth, {
+            noteRange: { first, last },
+            keyGap,
+            blackKeyWidthRatio,
+          })
+        })
+        observer.observe(parent)
+        onCleanup(() => observer.disconnect())
+      },
+      { immediate: true, flush: 'post' },
+    )
+
+    expose({
+      /** Start a note, as a key would. */
+      playNote: (note: number, velocity?: number) =>
+        instance?.noteOn(note, { source: 'api', velocity }),
+      /** Release a note started with `playNote`. */
+      stopNote: (note: number) => instance?.noteOff(note, { source: 'api' }),
+    })
+
+    // The group can own keyboard shortcuts and must receive focus. The width
+    // is computed from the layout rather than chosen, so it stays inline.
+    return () =>
+      h(
+        'div',
+        {
+          ref: root,
+          role: 'group',
+          tabindex: 0,
+          'data-resizable': props.resizable ? '' : undefined,
+          style: {
+            position: 'relative',
+            width: props.resizable ? '100%' : `${pianoWidth(layout.value)}px`,
+          },
+        },
+        notes.value.map((note, index) => {
+          const state: KeyState = {
+            index,
+            keyType: isWhiteKey(note) ? 'white' : 'black',
+            active: activeNotes.value.includes(note),
+            disabled: note > props.midiMax,
+          }
+          const { style: keyStyle, ...attributes } =
+            props.keyProps?.(note, state) ?? {}
+          const white = state.keyType === 'white'
+          const label = slots.label?.({ note, state })
+          // Placed and sized from the layout; the black keys sit over the
+          // white ones whichever order they are drawn in. The geometry comes
+          // after the caller's style.
+          return h(
+            'div',
+            {
+              key: note,
+              'data-note': note,
+              'data-note-key': noteKey(note),
+              'data-active': state.active ? '' : undefined,
+              'data-disabled': state.disabled ? '' : undefined,
+              ...attributes,
+              style: [
+                { position: 'absolute', zIndex: white ? 1 : 2 },
+                keyStyle,
+                {
+                  left: `${notePosition(note, layout.value)}px`,
+                  width: `${white ? layout.value.whiteKeyWidth : blackKeyWidth(layout.value)}px`,
+                  height: white
+                    ? '100%'
+                    : `${props.blackKeyHeightRatio * 100}%`,
+                },
+              ],
+            },
+            label
+              ? h('div', { class: props.classes?.keyLabelWrapper }, [
+                  h('div', { class: props.classes?.keyLabel }, label),
+                ])
+              : undefined,
+          )
+        }),
+      )
+  },
+})

package/src/components/Piano/index.ts

@@ -0,0 +1 @@
+export { Piano, type KeyAttributes, type KeyState } from './Piano'

package/src/components/PointsEditor/PointsEditor.ts

@@ -0,0 +1,146 @@
+import {
+  computed,
+  defineComponent,
+  h,
+  onScopeDispose,
+  provide,
+  shallowRef,
+  watchEffect,
+  type PropType,
+} from 'vue'
+
+import {
+  createPointsEditor,
+  DEFAULT_DRAG_SENSITIVITY,
+  POINTS_EDITOR_DEFAULT_KEYBOARD,
+  POINTS_EDITOR_DEFAULT_WHEEL,
+  type InputEventOption,
+  type ModifierValue,
+  type SelectionBoxRect,
+} from '@tremolo-ui/dom'
+
+import { PointsEditorKey } from './context'
+
+const EMPTY: readonly string[] = []
+
+/**
+ * Multiple point controller. Bind the selection with `v-model:selection` to
+ * hold it yourself; the editor keeps its own otherwise.
+ */
+export const PointsEditor = /* @__PURE__ */ defineComponent({
+  name: 'PointsEditor',
+  props: {
+    /** Make the points unchangeable and remove them from the tab order. */
+    disabled: Boolean,
+    /** Make the points unmovable. */
+    readonly: Boolean,
+    /** The cursor to show while dragging a point. @default { cursor: 'grabbing' } */
+    externalStyles: Object as PropType<{ cursor?: string }>,
+    /** How much one wheel notch moves the focused point. */
+    wheel: {
+      type: [Array, Object] as PropType<ModifierValue<InputEventOption> | null>,
+      default: () => POINTS_EDITOR_DEFAULT_WHEEL,
+    },
+    /** How much one arrow key press moves a point. */
+    keyboard: {
+      type: [Array, Object] as PropType<ModifierValue<InputEventOption> | null>,
+      default: () => POINTS_EDITOR_DEFAULT_KEYBOARD,
+    },
+    /** How much a drag moves a point, per modifier key. */
+    dragSensitivity: {
+      type: [Number, Object] as PropType<ModifierValue<number>>,
+      default: () => DEFAULT_DRAG_SENSITIVITY,
+    },
+    /**
+     * Let points be selected, and a selection be moved as one. A selection
+     * updates several points in the same tick.
+     */
+    selectable: Boolean,
+    /** Ids of the selected points. Bind it with `v-model:selection`. */
+    selection: Array as PropType<string[]>,
+  },
+  emits: {
+    'update:selection': (selection: string[]) => Array.isArray(selection),
+  },
+  setup(props, { slots, emit }) {
+    const ownSelection = shallowRef<string[]>(props.selection ?? [])
+    const selectionBox = shallowRef<SelectionBoxRect | null>(null)
+    const container = shallowRef<HTMLElement | null>(null)
+
+    // Nothing is selected while selection is off, so a drag picks up only
+    // the point it started on.
+    const current = computed(() =>
+      props.selectable ? (props.selection ?? ownSelection.value) : EMPTY,
+    )
+
+    // The selection lives here, where Vue state can hold it; which points a
+    // press or a box selects, and how a selection moves, is the core's.
+    const editor = createPointsEditor({
+      onSelectionBoxChange: (rect) => {
+        selectionBox.value = rect
+      },
+      onSelectionChange: (next) => {
+        ownSelection.value = next
+        emit('update:selection', next)
+      },
+    })
+    watchEffect(
+      () =>
+        editor.update({
+          selectable: props.selectable,
+          selection: current.value,
+        }),
+      { flush: 'sync' },
+    )
+    onScopeDispose(() => editor.destroy())
+
+    provide(PointsEditorKey, {
+      get disabled() {
+        return props.disabled
+      },
+      get readonly() {
+        return props.readonly
+      },
+      get wheel() {
+        return props.wheel
+      },
+      get keyboard() {
+        return props.keyboard
+      },
+      get dragSensitivity() {
+        return props.dragSensitivity
+      },
+      get cursor() {
+        return props.externalStyles?.cursor ?? 'grabbing'
+      },
+      get selectable() {
+        return props.selectable
+      },
+      get selection() {
+        return current.value
+      },
+      get selectionBox() {
+        return selectionBox.value
+      },
+      get container() {
+        return container.value
+      },
+      editor,
+      setContainer: (element) => {
+        container.value = element
+      },
+    })
+
+    // The layers inside are placed against this box.
+    return () =>
+      h(
+        'div',
+        {
+          'data-disabled': props.disabled ? '' : undefined,
+          'data-readonly': props.readonly ? '' : undefined,
+          style: { position: 'relative' },
+        },
+        slots.default?.(),
+      )
+  },
+})

package/src/components/PointsEditor/PointsEditorBackground.ts

@@ -0,0 +1,17 @@
+import { defineComponent, h } from 'vue'
+
+/**
+ * Behind the points, filling the editor. The order of the layers holds
+ * whichever way they are written, so the z-index is part of the mechanics.
+ */
+export const PointsEditorBackground = /* @__PURE__ */ defineComponent({
+  name: 'PointsEditorBackground',
+  setup(_, { slots }) {
+    return () =>
+      h(
+        'div',
+        { style: { position: 'absolute', inset: 0, zIndex: 0 } },
+        slots.default?.(),
+      )
+  },
+})

package/src/components/PointsEditor/PointsEditorContainer.ts

@@ -0,0 +1,73 @@
+import { computed, defineComponent, h, ref, watch, watchEffect } from 'vue'
+
+import {
+  createDragValue,
+  elementMapping,
+  POINT_AXIS,
+  wheelMove,
+} from '@tremolo-ui/dom'
+
+import { useWheel } from '../../composables/useWheel'
+import { providePlacement } from '../_util/placement'
+
+import { usePointsEditorContext } from './context'
+
+/** The layer the points are placed in, over the background. */
+export const PointsEditorContainer = /* @__PURE__ */ defineComponent({
+  name: 'PointsEditorContainer',
+  setup(_, { slots }) {
+    const points = usePointsEditorContext()
+    providePlacement('PointsEditorContainer')
+    const el = ref<HTMLDivElement | null>(null)
+    watchEffect(() => points.setContainer(el.value))
+
+    // A drag on empty space draws a selection box. It is only attached while
+    // there is a selection to draw: `createDrag` puts `touch-action: none` on
+    // what it holds, and an editor that cannot select should not stop the
+    // page scrolling under a finger.
+    const selecting = computed(() => points.selectable && !points.disabled)
+    watch(
+      [el, selecting],
+      ([element, on], _, onCleanup) => {
+        if (!element || !on) return
+        const drag = createDragValue(element, {
+          axis: POINT_AXIS,
+          mapping: elementMapping(() => element),
+          // A press that landed on a point belongs to that point. Declining
+          // here rather than later matters: by then the container would
+          // already have taken the pointer capture away from the point.
+          shouldStart: (event) =>
+            !points.editor.isPointElement(event.target as Element | null),
+          onDragStart: ([x, y], state) =>
+            points.editor.beginSelectionBox({ x, y }, state.event),
+          onChange: ([x, y]) => points.editor.moveSelectionBox({ x, y }),
+          onDragEnd: () => points.editor.endSelectionBox(),
+        })
+        onCleanup(() => drag.destroy())
+      },
+      { immediate: true, flush: 'post' },
+    )
+
+    // One listener for the whole editor rather than one per point: a wheel
+    // event only reaches what the cursor is over.
+    useWheel(el, (event) => {
+      // Scrolling up moves the point towards y = 0; shift switches to x.
+      const move = wheelMove(event)
+      if (!move) return
+      const axis = move.axis === 0 ? 'x' : 'y'
+      if (points.editor.nudgeFocusedPoint(axis, move.direction, event)) {
+        event.preventDefault()
+      }
+    })
+
+    return () =>
+      h(
+        'div',
+        {
+          ref: el,
+          style: { position: 'absolute', inset: 0, zIndex: 10 },
+        },
+        slots.default?.(),
+      )
+  },
+})