@tremolo-ui/vue 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tremolo-ui/vue",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Vue component library for audio app",
   "type": "module",
   "sideEffects": false,
@@ -19,15 +19,15 @@
     "clean:sb": "rimraf ./storybook-static"
   },
   "devDependencies": {
-    "@storybook/addon-a11y": "10.6.0",
-    "@storybook/addon-docs": "10.6.0",
-    "@storybook/vue3-vite": "10.6.0",
+    "@storybook/addon-a11y": "10.6.1",
+    "@storybook/addon-docs": "10.6.1",
+    "@storybook/vue3-vite": "10.6.1",
     "@testing-library/jest-dom": "7.0.1",
     "@testing-library/vue": "8.1.0",
     "@vitejs/plugin-vue": "6.0.9",
     "@vue/test-utils": "2.5.1",
-    "esbuild": "0.28.1",
-    "storybook": "10.6.0",
+    "esbuild": "0.28.2",
+    "storybook": "10.6.1",
     "vue-tsc": "3.3.11",
     "vue": "3.5.43"
   },
@@ -35,8 +35,8 @@
     "vue": "^3.5.0"
   },
   "dependencies": {
-    "@tremolo-ui/dom": "^0.7.0",
-    "@tremolo-ui/functions": "^0.7.0"
+    "@tremolo-ui/dom": "0.9.0",
+    "@tremolo-ui/functions": "^0.9.0"
   },
   "files": [
     "dist",

package/src/components/AnimationCanvas/AnimationCanvas.ts

@@ -1,53 +1,50 @@
 import {
+  type ComponentObjectPropsOptions,
   defineComponent,
+  type ExtractPublicPropTypes,
   h,
+  type PropType,
   ref,
   shallowRef,
   watch,
   watchEffect,
-  type PropType,
 } from 'vue'
 
 import {
   createAnimationCanvas,
   type AnimationCanvasInstance,
-  type AnimationFrame,
+  type CanvasDrawFunction,
+  type CanvasInitFunction,
 } from '@tremolo-ui/dom'
 
-/** Called once the canvas is ready, and again whenever it is resized. */
-export type InitFunction = (
-  context: CanvasRenderingContext2D,
-  size: { width: number; height: number },
-) => void
+const animationCanvasProps = {
+  /** Draws a frame. */
+  draw: { type: Function as PropType<CanvasDrawFunction>, required: true },
+  /** Sets the canvas up, once, before the first frame. */
+  init: Function as PropType<CanvasInitFunction>,
+  /** Draw on every animation frame. @default true */
+  animate: { type: Boolean, default: true },
+  /** Settings for the 2D context. Read once, when the canvas is created. */
+  options: Object as PropType<CanvasRenderingContext2DSettings>,
+  /** Keep the drawing while the canvas is resized. @default true */
+  reduceFlickering: { type: Boolean, default: true },
+  /** Follow the size of the parent element; `width` and `height` are ignored. */
+  resizable: Boolean,
+  /** Width in CSS pixels, while not `resizable`. @default 100 */
+  width: { type: Number, default: 100 },
+  /** Height in CSS pixels, while not `resizable`. @default 100 */
+  height: { type: Number, default: 100 },
+} satisfies ComponentObjectPropsOptions
 
-/** Called on every frame while `animate` is on, and once otherwise. */
-export type DrawFunction = (
-  context: CanvasRenderingContext2D,
-  frame: AnimationFrame,
-) => void
+export type AnimationCanvasProps = ExtractPublicPropTypes<
+  typeof animationCanvasProps
+>
 
 /** A `<canvas>` drawn by `draw` on every animation frame. */
 export const AnimationCanvas = /* @__PURE__ */ defineComponent({
   name: 'AnimationCanvas',
   inheritAttrs: false,
-  props: {
-    /** Draws a frame. */
-    draw: { type: Function as PropType<DrawFunction>, required: true },
-    /** Sets the canvas up before the first frame and after a resize. */
-    init: Function as PropType<InitFunction>,
-    /** Draw on every animation frame. @default true */
-    animate: { type: Boolean, default: true },
-    /** Settings for the 2D context. Read once, when the canvas is created. */
-    options: Object as PropType<CanvasRenderingContext2DSettings>,
-    /** Keep the drawing while the canvas is resized. @default true */
-    reduceFlickering: { type: Boolean, default: true },
-    /** Follow the size of the parent element; `width` and `height` are ignored. */
-    resizable: Boolean,
-    /** Width in CSS pixels, while not `resizable`. @default 100 */
-    width: { type: Number, default: 100 },
-    /** Height in CSS pixels, while not `resizable`. @default 100 */
-    height: { type: Number, default: 100 },
-  },
+  props: animationCanvasProps,
   setup(props, { attrs }) {
     const canvas = ref<HTMLCanvasElement | null>(null)
     const instance = shallowRef<AnimationCanvasInstance | null>(null)

package/src/components/AnimationCanvas/index.ts

@@ -1,5 +1 @@
-export {
-  AnimationCanvas,
-  type DrawFunction,
-  type InitFunction,
-} from './AnimationCanvas'
+export { AnimationCanvas, type AnimationCanvasProps } from './AnimationCanvas'

package/src/components/DropZone/DropZone.ts

@@ -1,18 +1,28 @@
-import { defineComponent, h, ref } from 'vue'
+import {
+  type ComponentObjectPropsOptions,
+  defineComponent,
+  type ExtractPublicPropTypes,
+  h,
+  ref,
+} from 'vue'
 
 import { useDropZone } from '../../composables/useDropZone'
 
+const dropZoneProps = {
+  /** Which files to take, as the `accept` attribute of a file input. */
+  accept: String,
+  /** Take every file dropped, rather than the first. */
+  multiple: Boolean,
+  /** Ignore drops. The zone carries `data-disabled`. */
+  disabled: Boolean,
+} satisfies ComponentObjectPropsOptions
+
+export type DropZoneProps = ExtractPublicPropTypes<typeof dropZoneProps>
+
 /** A region that takes dropped files. */
 export const DropZone = /* @__PURE__ */ defineComponent({
   name: 'DropZone',
-  props: {
-    /** Which files to take, as the `accept` attribute of a file input. */
-    accept: String,
-    /** Take every file dropped, rather than the first. */
-    multiple: Boolean,
-    /** Ignore drops. The zone carries `data-disabled`. */
-    disabled: Boolean,
-  },
+  props: dropZoneProps,
   emits: {
     /** The dropped files that satisfy `accept`. */
     drop: (files: File[], _event: DragEvent) => Array.isArray(files),

package/src/components/DropZone/index.ts

@@ -1 +1 @@
-export { DropZone } from './DropZone'
+export { DropZone, type DropZoneProps } from './DropZone'

package/src/components/FileInput/FileInput.ts

@@ -1,9 +1,34 @@
-import { defineComponent, h, provide, useId } from 'vue'
+import {
+  type ComponentObjectPropsOptions,
+  defineComponent,
+  type ExtractPublicPropTypes,
+  h,
+  provide,
+  useId,
+} from 'vue'
 
-import { partitionByAccept, visuallyHiddenStyle } from '@tremolo-ui/dom'
+import {
+  partitionByAccept,
+  visuallyHiddenStyle,
+} from '@tremolo-ui/dom/internal'
 
 import { FileInputKey } from './context'
 
+const fileInputProps = {
+  /**
+   * Which files to take: extensions, MIME types and type groups. It is
+   * checked again when the files arrive, since the picker only takes it as
+   * a hint.
+   */
+  accept: String,
+  /** Let several files be picked at once. */
+  multiple: Boolean,
+  /** Make the input unusable. The parts carry `data-disabled`. */
+  disabled: Boolean,
+} satisfies ComponentObjectPropsOptions
+
+export type FileInputProps = ExtractPublicPropTypes<typeof fileInputProps>
+
 /**
  * Picks files. The control is the native file input, out of sight but in the
  * tab order, with `FileInputTrigger` as its label.
@@ -11,18 +36,7 @@ import { FileInputKey } from './context'
 export const FileInput = /* @__PURE__ */ defineComponent({
   name: 'FileInput',
   inheritAttrs: false,
-  props: {
-    /**
-     * Which files to take: extensions, MIME types and type groups. It is
-     * checked again when the files arrive, since the picker only takes it as
-     * a hint.
-     */
-    accept: String,
-    /** Let several files be picked at once. */
-    multiple: Boolean,
-    /** Make the input unusable. The parts carry `data-disabled`. */
-    disabled: Boolean,
-  },
+  props: fileInputProps,
   emits: {
     /** The picked files that satisfy `accept`. */
     change: (files: File[]) => Array.isArray(files),

package/src/components/FileInput/index.ts

@@ -1,3 +1,3 @@
 export { useFileInputContext, type FileInputContextValue } from './context'
-export { FileInput } from './FileInput'
+export { FileInput, type FileInputProps } from './FileInput'
 export { FileInputTrigger } from './FileInputTrigger'

package/src/components/Knob/Knob.ts

@@ -1,82 +1,118 @@
-import { computed, defineComponent, h, provide, ref, type PropType } from 'vue'
+import {
+  type ComponentObjectPropsOptions,
+  computed,
+  defineComponent,
+  type ExtractPublicPropTypes,
+  h,
+  type PropType,
+  provide,
+  ref,
+} from 'vue'
 
 import {
-  applyDelta,
-  arrowKeyDirection,
-  cssLength,
   DEFAULT_DRAG_SENSITIVITY,
   DEFAULT_KEYBOARD_OPTIONS,
   DEFAULT_WHEEL_OPTIONS,
   knobAngles,
   relativeMapping,
-  selectModifier,
-  wheelDirection,
   type AxisOptions,
+  type ChangeSource,
   type InputEventOption,
   type ModifierValue,
   type XY,
 } from '@tremolo-ui/dom'
+import {
+  applyDelta,
+  arrowKeyDirection,
+  cssLength,
+  selectModifier,
+  wheelDirection,
+} from '@tremolo-ui/dom/internal'
 import { linearScale, type Scale } from '@tremolo-ui/functions'
 
 import { useDragValue } from '../../composables/useDragValue'
 import { useWheel } from '../../composables/useWheel'
+import { useChangeGesture } from '../_util/change-gesture'
 import { useCheckSteps } from '../_util/useCheckSteps'
 
 import { KnobKey } from './context'
 
+const knobProps = {
+  /** The current value. Bind it with `v-model`. */
+  modelValue: { type: Number, required: true },
+  /** The value with the knob turned all the way down. */
+  min: { type: Number, required: true },
+  /** The value with the knob turned all the way up. */
+  max: { type: Number, required: true },
+  /** Granularity of the value. @default 1 */
+  step: { type: Number, default: 1 },
+  /** How the value is distributed across the travel. @default linearScale */
+  scale: { type: Object as PropType<Scale>, default: () => linearScale },
+  /**
+   * The value a double click restores. `null` turns the double click off.
+   * @default startValue
+   */
+  resetValue: {
+    type: Number as PropType<number | null>,
+    default: undefined,
+  },
+  /** Where the active arc starts. @default min */
+  startValue: Number,
+  /** Width and height of the knob. Sets `--knob-size`. */
+  size: [Number, String],
+  /** The cursor to show while dragging. @default 'grabbing' */
+  dragCursor: { type: String, default: 'grabbing' },
+  /** How much one notch of the wheel moves the value. `null` turns it off. */
+  wheel: {
+    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. */
+  keyboard: {
+    type: [Array, Object] as PropType<ModifierValue<InputEventOption> | null>,
+    default: () => DEFAULT_KEYBOARD_OPTIONS,
+  },
+  /** How much a drag moves the value, per modifier key. */
+  dragSensitivity: {
+    type: [Number, Object] as PropType<ModifierValue<number>>,
+    default: () => DEFAULT_DRAG_SENSITIVITY,
+  },
+  /** Hide the cursor while dragging and read the movement directly. */
+  pointerLock: Boolean,
+  /** Make the knob unchangeable and remove it from the tab order. */
+  disabled: Boolean,
+  /** Make the knob unchangeable while leaving it focusable. */
+  readonly: Boolean,
+  /**
+   * How long after the last wheel notch or arrow key a change counts as over,
+   * in milliseconds, for `change-end`.
+   * @default 500
+   */
+  changeEndDelay: { type: Number, default: 500 },
+  /** How far the knob turns from `min` to `max`, in degrees. @default 270 */
+  angleRange: { type: Number, default: 270 },
+} satisfies ComponentObjectPropsOptions
+
+export type KnobProps = ExtractPublicPropTypes<typeof knobProps>
+
 /**
  * Interactive rotary knob, drawn in SVG by `KnobSVGRoot` and the parts inside
  * it. Bind the value with `v-model`.
  */
 export const Knob = /* @__PURE__ */ defineComponent({
   name: 'Knob',
-  props: {
-    /** The current value. Bind it with `v-model`. */
-    modelValue: { type: Number, required: true },
-    /** The value with the knob turned all the way down. */
-    min: { type: Number, required: true },
-    /** The value with the knob turned all the way up. */
-    max: { type: Number, required: true },
-    /** Granularity of the value. @default 1 */
-    step: { type: Number, default: 1 },
-    /** How the value is distributed across the travel. @default linearScale */
-    scale: { type: Object as PropType<Scale>, default: () => linearScale },
-    /** The value a double click restores. @default min */
-    defaultValue: Number,
-    /** Where the active arc starts. @default min */
-    startValue: Number,
-    /** Width and height of the knob. Sets `--knob-size`. */
-    size: [Number, String],
-    /** The cursor to show while dragging. @default { cursor: 'grabbing' } */
-    externalStyles: Object as PropType<{ cursor?: string }>,
-    /** How much one notch of the wheel moves the value. `null` turns it off. */
-    wheel: {
-      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. */
-    keyboard: {
-      type: [Array, Object] as PropType<ModifierValue<InputEventOption> | null>,
-      default: () => DEFAULT_KEYBOARD_OPTIONS,
-    },
-    /** How much a drag moves the value, per modifier key. */
-    dragSensitivity: {
-      type: [Number, Object] as PropType<ModifierValue<number>>,
-      default: () => DEFAULT_DRAG_SENSITIVITY,
-    },
-    /** Hide the cursor while dragging and read the movement directly. */
-    pointerLock: Boolean,
-    /** Restore `defaultValue` on a double click. @default true */
-    enableDoubleClickDefault: { type: Boolean, default: true },
-    /** Make the knob unchangeable and remove it from the tab order. */
-    disabled: Boolean,
-    /** Make the knob unchangeable while leaving it focusable. */
-    readonly: Boolean,
-    /** How far the knob turns from `min` to `max`, in degrees. @default 270 */
-    angleRange: { type: Number, default: 270 },
-  },
+  props: knobProps,
   emits: {
     'update:modelValue': (value: number) => typeof value === 'number',
+    /**
+     * A change of the value started, with the value before it and what it is
+     * made with.
+     */
+    changeStart: (value: number, _source: ChangeSource) =>
+      typeof value === 'number',
+    /** The change ended, with the value it ended on. */
+    changeEnd: (value: number, _source: ChangeSource) =>
+      typeof value === 'number',
   },
   setup(props, { slots, emit, expose }) {
     const root = ref<HTMLDivElement | null>(null)
@@ -133,7 +169,17 @@ export const Knob = /* @__PURE__ */ defineComponent({
       },
     })
 
-    const change = (next: number) => emit('update:modelValue', next)
+    const gesture = useChangeGesture({
+      value: () => props.modelValue,
+      inactive: () => inactive.value,
+      endDelay: () => props.changeEndDelay,
+      onStart: (value, source) => emit('changeStart', value, source),
+      onEnd: (value, source) => emit('changeEnd', value, source),
+    })
+    const change = (next: number) => {
+      gesture.changed(next)
+      emit('update:modelValue', next)
+    }
 
     // The knob has no travel of its own: 100px of movement spans the whole
     // range, and only the vertical axis carries a value, reversed so that
@@ -147,9 +193,7 @@ export const Knob = /* @__PURE__ */ defineComponent({
       }),
       getValue: (): XY<number> => [props.modelValue, props.modelValue],
       threshold: 1,
-      cursor: inactive.value
-        ? undefined
-        : (props.externalStyles?.cursor ?? 'grabbing'),
+      cursor: inactive.value ? undefined : props.dragCursor,
       pointerLock: inactive.value ? false : props.pointerLock,
       shouldStart: () => !inactive.value,
       onChange: (v) => {
@@ -157,9 +201,11 @@ export const Knob = /* @__PURE__ */ defineComponent({
       },
       onDragStart: () => {
         dragging.value = true
+        if (!inactive.value) gesture.hold('pointer')
       },
       onDragEnd: () => {
         dragging.value = false
+        gesture.end()
       },
     }))
 
@@ -172,6 +218,7 @@ export const Knob = /* @__PURE__ */ defineComponent({
         const direction = wheelDirection(event)
         if (direction === null) return
         event.preventDefault()
+        gesture.pulse('wheel')
         change(
           applyDelta(
             props.modelValue,
@@ -215,6 +262,7 @@ export const Knob = /* @__PURE__ */ defineComponent({
             const direction = arrowKeyDirection(event.key)
             if (direction === null) return
             event.preventDefault()
+            gesture.pulse('keyboard')
             change(
               applyDelta(
                 props.modelValue,
@@ -226,8 +274,10 @@ export const Knob = /* @__PURE__ */ defineComponent({
             )
           },
           onDblclick: () => {
-            if (!inactive.value && props.enableDoubleClickDefault) {
-              change(props.defaultValue ?? props.min)
+            if (!inactive.value && props.resetValue !== null) {
+              gesture.instant('doubleClick', () =>
+                change(props.resetValue ?? props.startValue ?? props.min),
+              )
             }
           },
         },

package/src/components/Knob/KnobThumb.ts

@@ -1,4 +1,10 @@
-import { defineComponent, h, type PropType } from 'vue'
+import {
+  type ComponentObjectPropsOptions,
+  defineComponent,
+  type ExtractPublicPropTypes,
+  h,
+  type PropType,
+} from 'vue'
 
 import { KNOB_VIEWBOX_SIZE } from '@tremolo-ui/dom'
 import { clamp } from '@tremolo-ui/functions'
@@ -7,23 +13,27 @@ import { checkPlacement } from '../_util/placement'
 
 import { useKnobContext } from './context'
 
+const knobThumbProps = {
+  /** Fill colour of the circle. @default 'currentColor' */
+  color: { type: String, default: 'currentColor' },
+  /** Colour of the line that points at the value. @default 'currentColor' */
+  lineColor: { type: String, default: 'currentColor' },
+  /** Diameter of the circle, as a percentage of the knob. @default 84 */
+  size: { type: Number, default: 84 },
+  /** Thickness of the line, as a percentage of the knob. @default 6 */
+  lineWeight: { type: Number, default: 6 },
+  /** How far down the line reaches, as a percentage. @default 35 */
+  lineLength: { type: Number, default: 35 },
+  /** Classes for the line that points at the value. */
+  classes: Object as PropType<{ line?: string }>,
+} satisfies ComponentObjectPropsOptions
+
+export type KnobThumbProps = ExtractPublicPropTypes<typeof knobThumbProps>
+
 /** The circle that turns with the value, and the line on it that points at it. */
 export const KnobThumb = /* @__PURE__ */ defineComponent({
   name: 'KnobThumb',
-  props: {
-    /** Fill colour of the circle. @default 'currentColor' */
-    thumb: { type: String, default: 'currentColor' },
-    /** Colour of the line that points at the value. @default 'currentColor' */
-    thumbLine: { type: String, default: 'currentColor' },
-    /** Diameter of the circle, as a percentage of the knob. @default 84 */
-    thumbSize: { type: Number, default: 84 },
-    /** Thickness of the line, as a percentage of the knob. @default 6 */
-    thumbLineWeight: { type: Number, default: 6 },
-    /** How far down the line reaches, as a percentage. @default 35 */
-    thumbLineLength: { type: Number, default: 35 },
-    /** Classes for the line that points at the value. */
-    classes: Object as PropType<{ thumbLine?: string }>,
-  },
+  props: knobThumbProps,
   setup(props) {
     checkPlacement('KnobThumb', 'KnobSVGRoot')
     const knob = useKnobContext()
@@ -32,17 +42,17 @@ export const KnobThumb = /* @__PURE__ */ defineComponent({
         h('circle', {
           cx: '50%',
           cy: '50%',
-          r: `${props.thumbSize / 2}%`,
-          fill: props.thumb,
+          r: `${props.size / 2}%`,
+          fill: props.color,
         }),
         h('line', {
-          class: props.classes?.thumbLine,
+          class: props.classes?.line,
           x1: '50%',
-          y1: `${(KNOB_VIEWBOX_SIZE - clamp(props.thumbSize, 0, 100)) / 2}%`,
+          y1: `${(KNOB_VIEWBOX_SIZE - clamp(props.size, 0, 100)) / 2}%`,
           x2: '50%',
-          y2: `${props.thumbLineLength}%`,
-          stroke: props.thumbLine,
-          'stroke-width': `${props.thumbLineWeight}%`,
+          y2: `${props.lineLength}%`,
+          stroke: props.lineColor,
+          'stroke-width': `${props.lineWeight}%`,
           style: {
             transform: `rotate(${knob.angles.r1 + knob.angles.p * knob.angleRange}deg)`,
             transformOrigin: '50% 50%',

package/src/components/Knob/index.ts

@@ -1,6 +1,6 @@
 export { useKnobContext, type KnobContextValue } from './context'
-export { Knob } from './Knob'
+export { Knob, type KnobProps } from './Knob'
 export { KnobActiveLine } from './KnobActiveLine'
 export { KnobInactiveLine } from './KnobInactiveLine'
 export { KnobSVGRoot } from './KnobSVGRoot'
-export { KnobThumb } from './KnobThumb'
+export { KnobThumb, type KnobThumbProps } from './KnobThumb'