@tremolo-ui/vue 0.7.0

package/src/components/_util/placement.ts

@@ -0,0 +1,36 @@
+import { inject, provide, type InjectionKey } from 'vue'
+
+const PLACEMENT: InjectionKey<string> = Symbol('tremolo-ui placement')
+
+/**
+ * Mark the children of this component as being inside `name`, for
+ * {@link checkPlacement}. Call it during `setup`.
+ */
+export function providePlacement(name: string) {
+  provide(PLACEMENT, name)
+}
+
+/**
+ * Warn, in development only, when `child` is rendered outside `parent`. A
+ * part positioned against its parent still renders anywhere else, so nothing
+ * fails when it is misplaced — its position just comes out wrong. The names
+ * are the ones written in templates (`'KnobThumb'`), since they are what the
+ * warning shows. Call it during `setup`.
+ */
+export function checkPlacement(child: string, parent: string) {
+  try {
+    // Inline and first, so that a bundler folds the comparison and drops the
+    // message with it. Wrapped because `process` may not exist at all.
+    if (process.env.NODE_ENV === 'production') return
+    const found = inject(PLACEMENT, null)
+    if (found === parent) return
+    console.warn(
+      `[tremolo-ui] ${child} has to be rendered inside ${parent}` +
+        (found === null ? '.' : `, but it is inside ${found}.`) +
+        ' It renders either way, so nothing fails — its position just' +
+        ' comes out wrong.',
+    )
+  } catch {
+    // No bundler substituted NODE_ENV. Say nothing rather than break.
+  }
+}

package/src/components/_util/props.ts

@@ -0,0 +1,32 @@
+import { type PropType } from 'vue'
+
+import {
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
+  type InputEventOption,
+  type ModifierValue,
+} from '@tremolo-ui/dom'
+
+// The input props every value control shares, with the core's defaults. One
+// constant each rather than an object to spread: a spread inside
+// `defineComponent(...)` counts as a possible side effect to a bundler, which
+// then keeps every component that uses it even when none is imported.
+
+/** How much one notch of the wheel moves the value. `null` turns it off. */
+export const wheelProp = {
+  type: [Array, Object] as PropType<ModifierValue<InputEventOption> | null>,
+  default: () => DEFAULT_WHEEL_OPTIONS,
+}
+
+/** How much one arrow key press moves the value. `null` turns it off. */
+export const keyboardProp = {
+  type: [Array, Object] as PropType<ModifierValue<InputEventOption> | null>,
+  default: () => DEFAULT_KEYBOARD_OPTIONS,
+}
+
+/** How much a drag moves the value, per modifier key. */
+export const dragSensitivityProp = {
+  type: [Number, Object] as PropType<ModifierValue<number>>,
+  default: () => DEFAULT_DRAG_SENSITIVITY,
+}

package/src/components/_util/useCheckSteps.ts

@@ -0,0 +1,22 @@
+import { watchEffect } from 'vue'
+
+import { checkSteps, type CheckStepsOptions } from '@tremolo-ui/dom'
+
+/**
+ * Warn, in development only, when a key press or a wheel notch cannot produce
+ * a change the user can see. The probing is `checkSteps` in the core.
+ *
+ * Takes a getter, so that the check runs again when the settings change.
+ */
+export function useCheckSteps(options: () => CheckStepsOptions) {
+  try {
+    // Inline and first, so that a bundler folds the comparison and drops the
+    // only call to `checkSteps`, which then falls out of the bundle too.
+    if (process.env.NODE_ENV === 'production') return
+    watchEffect(() => {
+      for (const warning of checkSteps(options())) console.warn(warning)
+    })
+  } catch {
+    // No bundler substituted NODE_ENV. Say nothing rather than break.
+  }
+}

package/src/components/_util/visually-hidden-range-input.ts

@@ -0,0 +1,16 @@
+import { h, type VNodeProps } from 'vue'
+
+import { visuallyHiddenStyle } from '@tremolo-ui/dom'
+
+/**
+ * The control underneath a headless part: out of sight, but in the
+ * accessibility tree and the tab order, carrying the ARIA and the keyboard.
+ *
+ * A plain element rather than a component, so that a `ref` on it reaches the
+ * `<input>` itself.
+ */
+export function visuallyHiddenRangeInput(
+  props: VNodeProps & Record<string, unknown>,
+) {
+  return h('input', { ...props, type: 'range', style: visuallyHiddenStyle })
+}

package/src/composables/useDrag.ts

@@ -0,0 +1,22 @@
+import { type MaybeRefOrGetter } from 'vue'
+
+import { createDrag, type DragOptions } from '@tremolo-ui/dom'
+
+import { useInstance } from './useInstance'
+
+/**
+ * Track a pointer drag on an element. See `createDrag` in `@tremolo-ui/dom`
+ * for the options.
+ *
+ * @example
+ * const el = useTemplateRef('el')
+ * useDrag(el, { onDrag: (state) => (x.value += state.deltaX) })
+ */
+export function useDrag(
+  target: MaybeRefOrGetter<Element | null | undefined>,
+  options: MaybeRefOrGetter<DragOptions> = {},
+) {
+  useInstance(target, options, createDrag, (instance, next) =>
+    instance.update(next),
+  )
+}

package/src/composables/useDragValue.ts

@@ -0,0 +1,20 @@
+import { type MaybeRefOrGetter } from 'vue'
+
+import { createDragValue, type DragValueOptions } from '@tremolo-ui/dom'
+
+import { useInstance } from './useInstance'
+
+/**
+ * Drive a value with a pointer drag. See `createDragValue` in
+ * `@tremolo-ui/dom` for the options; `elementMapping` and `relativeMapping`
+ * from there choose how the pointer becomes a value. `mapping` is read when
+ * the element is attached.
+ */
+export function useDragValue(
+  target: MaybeRefOrGetter<Element | null | undefined>,
+  options: MaybeRefOrGetter<DragValueOptions>,
+) {
+  useInstance(target, options, createDragValue, (instance, next) =>
+    instance.update(next),
+  )
+}

package/src/composables/useDropZone.ts

@@ -0,0 +1,32 @@
+import { shallowRef, toValue, type MaybeRefOrGetter } from 'vue'
+
+import {
+  createDropZone,
+  type DropZoneOptions,
+  type DropZoneState,
+} from '@tremolo-ui/dom'
+
+import { useInstance } from './useInstance'
+
+/**
+ * Take files dropped on an element. See `createDropZone` in
+ * `@tremolo-ui/dom`. Returns whether files are over it, and whether they
+ * would be refused, for styling it while they are.
+ */
+export function useDropZone(
+  target: MaybeRefOrGetter<Element | null | undefined>,
+  options: MaybeRefOrGetter<DropZoneOptions> = {},
+) {
+  const state = shallowRef<DropZoneState>({ over: false, invalid: false })
+  const withState = () => ({
+    ...toValue(options),
+    onStateChange: (next: DropZoneState) => {
+      state.value = next
+      toValue(options).onStateChange?.(next)
+    },
+  })
+  useInstance(target, withState, createDropZone, (instance, next) =>
+    instance.update(next),
+  )
+  return state
+}

package/src/composables/useInstance.ts

@@ -0,0 +1,52 @@
+import { toValue, watch, type MaybeRefOrGetter } from 'vue'
+
+import { replaceOptions } from '@tremolo-ui/dom'
+
+/**
+ * Create an instance for the element `target` holds, and destroy it when the
+ * element goes away or changes. Options are pushed to the instance with
+ * `update` as they change, so that changing them does not interrupt a drag in
+ * progress.
+ *
+ * Call it during `setup`: the watchers stop with the component.
+ */
+export function useInstance<
+  E extends Element,
+  O extends object,
+  I extends { destroy: () => void },
+>(
+  target: MaybeRefOrGetter<E | null | undefined>,
+  options: MaybeRefOrGetter<O>,
+  create: (element: E, options: O) => I,
+  update: (instance: I, options: Partial<O>) => void,
+): { current: () => I | null } {
+  let instance: I | null = null
+
+  watch(
+    () => toValue(target),
+    (element, _, onCleanup) => {
+      if (!element) return
+      const current = create(element, toValue(options))
+      instance = current
+      onCleanup(() => {
+        current.destroy()
+        if (instance === current) instance = null
+      })
+    },
+    { immediate: true, flush: 'post' },
+  )
+
+  // A copy, so that the watch reads every property: a `reactive()` object
+  // whose `requireFocus` changes is then seen, not only a new object. The
+  // copy is what the instance is left with — what it no longer carries is
+  // cleared rather than kept.
+  watch(
+    () => ({ ...toValue(options) }),
+    (next, previous) => {
+      if (instance) update(instance, replaceOptions(previous, next))
+    },
+    { flush: 'post' },
+  )
+
+  return { current: () => instance }
+}

package/src/composables/useLongPress.ts

@@ -0,0 +1,20 @@
+import { onScopeDispose, toValue, watch, type MaybeRefOrGetter } from 'vue'
+
+import { createLongPress, type LongPressOptions } from '@tremolo-ui/dom'
+
+/**
+ * Repeat `onPress` while a pointer is held down: once on the press, then
+ * every `interval` after `delay`. See `createLongPress` in `@tremolo-ui/dom`.
+ *
+ * Returns the function that starts a press, for `@pointerdown`.
+ */
+export function useLongPress(options: MaybeRefOrGetter<LongPressOptions>) {
+  const instance = createLongPress(toValue(options))
+  watch(
+    () => toValue(options),
+    (next) => instance.update(next),
+  )
+  onScopeDispose(() => instance.destroy())
+  return (event?: Pick<PointerEvent, 'button' | 'pointerId'>) =>
+    instance.start(event)
+}

package/src/composables/useMIDIAccess.ts

@@ -0,0 +1,58 @@
+import {
+  computed,
+  onMounted,
+  onScopeDispose,
+  shallowRef,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+} from 'vue'
+
+import {
+  createMIDIAccess,
+  type MIDIAccessOptions,
+  type MIDIAccessState,
+} from '@tremolo-ui/dom'
+
+/**
+ * Request MIDI access in the browser. Call it during `setup`.
+ *
+ * `state` holds the access, the error and the connected inputs, and follows
+ * devices as they are plugged in and unplugged.
+ *
+ * @param requestOnMount ask for access once the component is mounted — never
+ * during server rendering, where there is no MIDI to ask for. Leave it off to
+ * ask from a click instead, so that opening a page does not bring up a
+ * permission prompt. A ref or a getter asks once it turns true.
+ */
+export function useMIDIAccess(
+  requestOnMount: MaybeRefOrGetter<boolean> = true,
+) {
+  const instance = createMIDIAccess()
+  const state = shallowRef<MIDIAccessState>(instance.getState())
+  const unsubscribe = instance.subscribe(() => {
+    state.value = instance.getState()
+  })
+  onMounted(() => {
+    watch(
+      () => toValue(requestOnMount),
+      (request) => {
+        if (request) instance.request()
+      },
+      { immediate: true },
+    )
+  })
+  onScopeDispose(() => {
+    unsubscribe()
+    instance.destroy()
+  })
+  return {
+    // Read-only, and without wrapping MIDIAccess in a proxy.
+    state: computed(() => state.value),
+    /**
+     * Ask for access. Takes `{ sysex: true }` when the app needs system
+     * exclusive messages, which browsers treat as a separate permission.
+     */
+    request: (options?: MIDIAccessOptions) => instance.request(options),
+  }
+}

package/src/composables/useMIDIInput.ts

@@ -0,0 +1,33 @@
+import { toValue, watch, type MaybeRefOrGetter } from 'vue'
+
+import { createMIDIInput, type MIDIInputHandlers } from '@tremolo-ui/dom'
+
+/**
+ * Handle the channel voice messages of every connected input. Call it during
+ * `setup`. See `createMIDIInput` in `@tremolo-ui/dom` for the handlers.
+ *
+ * The listeners follow `midiAccess` as it is granted, and new handlers
+ * replace the old ones without re-subscribing.
+ */
+export function useMIDIInput(
+  midiAccess: MaybeRefOrGetter<MIDIAccess | null>,
+  handlers: MaybeRefOrGetter<MIDIInputHandlers>,
+) {
+  let instance: ReturnType<typeof createMIDIInput> | null = null
+  watch(
+    () => toValue(midiAccess),
+    (access, _, onCleanup) => {
+      const current = createMIDIInput(access, toValue(handlers))
+      instance = current
+      onCleanup(() => {
+        current.destroy()
+        if (instance === current) instance = null
+      })
+    },
+    { immediate: true },
+  )
+  watch(
+    () => toValue(handlers),
+    (next) => instance?.update(next),
+  )
+}

package/src/composables/useMIDIMessage.ts

@@ -0,0 +1,30 @@
+import { toValue, watch, type MaybeRefOrGetter } from 'vue'
+
+import { createMIDIMessage } from '@tremolo-ui/dom'
+
+/**
+ * Listen to raw `midimessage` events on every input. Call it during `setup`.
+ * For note and controller events, `useMIDIInput` decodes the message for you.
+ */
+export function useMIDIMessage(
+  midiAccess: MaybeRefOrGetter<MIDIAccess | null>,
+  onMIDIMessage: MaybeRefOrGetter<(event: MIDIMessageEvent) => void>,
+) {
+  let instance: ReturnType<typeof createMIDIMessage> | null = null
+  watch(
+    () => toValue(midiAccess),
+    (access, _, onCleanup) => {
+      const current = createMIDIMessage(access, toValue(onMIDIMessage))
+      instance = current
+      onCleanup(() => {
+        current.destroy()
+        if (instance === current) instance = null
+      })
+    },
+    { immediate: true },
+  )
+  watch(
+    () => toValue(onMIDIMessage),
+    (next) => instance?.update(next),
+  )
+}

package/src/composables/useWheel.ts

@@ -0,0 +1,23 @@
+import { type MaybeRefOrGetter } from 'vue'
+
+import { createWheel, type WheelOptions } from '@tremolo-ui/dom'
+
+import { useInstance } from './useInstance'
+
+/**
+ * Listen to the wheel on an element, as a non-passive listener so that
+ * `preventDefault()` can keep the page from scrolling. See `createWheel` in
+ * `@tremolo-ui/dom`.
+ */
+export function useWheel(
+  target: MaybeRefOrGetter<Element | null | undefined>,
+  onWheel: (event: WheelEvent) => void,
+  options: MaybeRefOrGetter<WheelOptions> = {},
+) {
+  useInstance(
+    target,
+    options,
+    (element, opts) => createWheel(element, (event) => onWheel(event), opts),
+    (instance, next) => instance.update(next),
+  )
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+// components
+export {
+  AnimationCanvas,
+  type DrawFunction,
+  type InitFunction,
+} from './components/AnimationCanvas'
+export { DropZone } from './components/DropZone'
+export {
+  FileInput,
+  FileInputTrigger,
+  useFileInputContext,
+  type FileInputContextValue,
+} from './components/FileInput'
+export {
+  Knob,
+  KnobActiveLine,
+  KnobInactiveLine,
+  KnobSVGRoot,
+  KnobThumb,
+  useKnobContext,
+  type KnobContextValue,
+} from './components/Knob'
+export {
+  NumberInput,
+  NumberInputDecrementStepper,
+  NumberInputField,
+  NumberInputIncrementStepper,
+  NumberInputStepper,
+  useNumberInputContext,
+  type NumberInputContextValue,
+} from './components/NumberInput'
+export { Piano, type KeyAttributes, type KeyState } from './components/Piano'
+export {
+  PointsEditor,
+  PointsEditorBackground,
+  PointsEditorContainer,
+  PointsEditorPoint,
+  PointsEditorSelectionBox,
+  usePointsEditorContext,
+  type PointsEditorContextValue,
+} from './components/PointsEditor'
+export {
+  Slider,
+  SliderMarks,
+  SliderMarksOption,
+  SliderThumb,
+  SliderTrack,
+  useSliderContext,
+  type SliderContextValue,
+} from './components/Slider'
+export {
+  XYPad,
+  XYPadArea,
+  XYPadThumb,
+  useXYPadContext,
+  type XYPadContextValue,
+} from './components/XYPad'
+
+// composables
+export { useDrag } from './composables/useDrag'
+export { useDragValue } from './composables/useDragValue'
+export { useDropZone } from './composables/useDropZone'
+export { useLongPress } from './composables/useLongPress'
+export { useMIDIAccess } from './composables/useMIDIAccess'
+export { useMIDIInput } from './composables/useMIDIInput'
+export { useMIDIMessage } from './composables/useMIDIMessage'
+export { useWheel } from './composables/useWheel'