@tremolo-ui/vue 0.8.0 → 0.9.0

package/src/components/Slider/SliderThumb.ts

@@ -1,10 +1,25 @@
-import { defineComponent, h, onBeforeUnmount, ref, watchEffect } from 'vue'
+import {
+  type ComponentObjectPropsOptions,
+  defineComponent,
+  type ExtractPublicPropTypes,
+  h,
+  onBeforeUnmount,
+  ref,
+  watchEffect,
+} from 'vue'
 
 import { checkPlacement } from '../_util/placement'
 import { visuallyHiddenRangeInput } from '../_util/visually-hidden-range-input'
 
 import { useSliderContext } from './context'
 
+const sliderThumbProps = {
+  /** Sets `--color`, for the theme to colour the thumb with. */
+  color: String,
+} satisfies ComponentObjectPropsOptions
+
+export type SliderThumbProps = ExtractPublicPropTypes<typeof sliderThumbProps>
+
 /**
  * The thumb, placed at the value. The ARIA (`aria-label` and friends) lands
  * on the range input inside it, which is the control and takes the focus.
@@ -12,10 +27,7 @@ import { useSliderContext } from './context'
 export const SliderThumb = /* @__PURE__ */ defineComponent({
   name: 'SliderThumb',
   inheritAttrs: false,
-  props: {
-    /** Sets `--color`, for the theme to colour the thumb with. */
-    color: String,
-  },
+  props: sliderThumbProps,
   setup(props, { slots, attrs, expose }) {
     const slider = useSliderContext()
     checkPlacement('SliderThumb', 'SliderTrack')
@@ -56,8 +68,14 @@ export const SliderThumb = /* @__PURE__ */ defineComponent({
             },
             style,
             {
-              top: slider.vertical ? `${slider.percent}%` : '50%',
-              left: slider.vertical ? '50%' : `${slider.percent}%`,
+              top:
+                slider.orientation === 'vertical'
+                  ? `${slider.percent}%`
+                  : '50%',
+              left:
+                slider.orientation === 'vertical'
+                  ? '50%'
+                  : `${slider.percent}%`,
             },
           ],
         },
@@ -70,7 +88,7 @@ export const SliderThumb = /* @__PURE__ */ defineComponent({
             step: slider.step,
             disabled: slider.disabled,
             'aria-readonly': slider.readonly,
-            'aria-orientation': slider.vertical ? 'vertical' : 'horizontal',
+            'aria-orientation': slider.orientation,
             'aria-label': ariaLabel,
             'aria-labelledby': ariaLabelledby,
             'aria-describedby': ariaDescribedby,

package/src/components/Slider/SliderTrack.ts

@@ -1,24 +1,36 @@
-import { defineComponent, h, onBeforeUnmount, ref, watchEffect } from 'vue'
+import {
+  type ComponentObjectPropsOptions,
+  defineComponent,
+  type ExtractPublicPropTypes,
+  h,
+  onBeforeUnmount,
+  ref,
+  watchEffect,
+} from 'vue'
 
-import { cssLength } from '@tremolo-ui/dom'
+import { cssLength } from '@tremolo-ui/dom/internal'
 
 import { providePlacement } from '../_util/placement'
 
 import { useSliderContext } from './context'
 
+const sliderTrackProps = {
+  /** How long the track is along the axis the slider runs. Sets `--length`. */
+  length: [Number, String],
+  /** How thick the track is across that axis. Sets `--thickness`. */
+  thickness: [Number, String],
+  /** Colour of the part from `min` to the value. Sets `--active-color`. */
+  activeColor: String,
+  /** Colour of the rest of the track. Sets `--inactive-color`. */
+  inactiveColor: String,
+} satisfies ComponentObjectPropsOptions
+
+export type SliderTrackProps = ExtractPublicPropTypes<typeof sliderTrackProps>
+
 /** The track the thumb runs along, and what the pointer is measured against. */
 export const SliderTrack = /* @__PURE__ */ defineComponent({
   name: 'SliderTrack',
-  props: {
-    /** How long the track is along the axis the slider runs. Sets `--length`. */
-    length: [Number, String],
-    /** How thick the track is across that axis. Sets `--thickness`. */
-    thickness: [Number, String],
-    /** Colour of the part from `min` to the value. Sets `--active`. */
-    active: String,
-    /** Colour of the rest of the track. Sets `--inactive`. */
-    inactive: String,
-  },
+  props: sliderTrackProps,
   setup(props, { slots }) {
     const slider = useSliderContext()
     providePlacement('SliderTrack')
@@ -33,11 +45,14 @@ export const SliderTrack = /* @__PURE__ */ defineComponent({
         {
           ref: el,
           'data-disabled': slider.disabled ? '' : undefined,
-          'data-orientation': slider.vertical ? 'vertical' : 'horizontal',
-          'data-flipped': slider.vertical !== slider.reverse ? '' : undefined,
+          'data-orientation': slider.orientation,
+          'data-flipped':
+            (slider.orientation === 'vertical') !== slider.reverse
+              ? ''
+              : undefined,
           style: {
-            '--active': props.active,
-            '--inactive': props.inactive,
+            '--active-color': props.activeColor,
+            '--inactive-color': props.inactiveColor,
             '--length': cssLength(props.length),
             '--thickness': cssLength(props.thickness),
             '--percent': `${slider.percent}%`,

package/src/components/Slider/context.ts

@@ -11,7 +11,7 @@ export interface SliderContextValue {
   readonly max: number
   readonly step: number
   readonly scale: Scale
-  readonly vertical: boolean
+  readonly orientation: 'horizontal' | 'vertical'
   readonly reverse: boolean
   readonly disabled: boolean
   readonly readonly: boolean

package/src/components/Slider/index.ts

@@ -1,6 +1,9 @@
 export { useSliderContext, type SliderContextValue } from './context'
-export { Slider } from './Slider'
-export { SliderMarks } from './SliderMarks'
-export { SliderMarksOption } from './SliderMarksOption'
-export { SliderThumb } from './SliderThumb'
-export { SliderTrack } from './SliderTrack'
+export { Slider, type SliderProps } from './Slider'
+export { SliderMarks, type SliderMarksProps } from './SliderMarks'
+export {
+  SliderMarksOption,
+  type SliderMarksOptionProps,
+} from './SliderMarksOption'
+export { SliderThumb, type SliderThumbProps } from './SliderThumb'
+export { SliderTrack, type SliderTrackProps } from './SliderTrack'

package/src/components/XYPad/XYPad.ts

@@ -1,78 +1,108 @@
-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,
-  arrowKeyMove,
   elementMapping,
-  selectModifier,
-  toXY,
   valuePercent,
-  wheelMove,
-  type AxisMove,
   type AxisOptions,
+  type ChangeSource,
   type InputEventOption,
   type ModifierState,
   type ModifierValue,
   type XY,
   type XYInput,
 } from '@tremolo-ui/dom'
+import {
+  applyDelta,
+  arrowKeyMove,
+  selectModifier,
+  toXY,
+  wheelMove,
+  type AxisMove,
+} 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 { dragSensitivityProp, keyboardProp, wheelProp } from '../_util/props'
 import { useCheckSteps } from '../_util/useCheckSteps'
 
 import { XYPadKey } from './context'
 
+const xyPadProps = {
+  /** The current value as `[x, y]`. Bind it with `v-model`. */
+  modelValue: {
+    type: Array as unknown as PropType<XY<number>>,
+    required: true,
+  },
+  /** The value at the start of the travel, per axis. */
+  min: {
+    type: [Number, Array] as PropType<XYInput<number>>,
+    required: true,
+  },
+  /** The value at the end of the travel, per axis. */
+  max: {
+    type: [Number, Array] as PropType<XYInput<number>>,
+    required: true,
+  },
+  /** Granularity of the value, per axis. @default 1 */
+  step: { type: [Number, Array] as PropType<XYInput<number>>, default: 1 },
+  /** How the value is distributed, per axis. @default linearScale */
+  scale: {
+    type: [Object, Array] as PropType<XYInput<Scale>>,
+    default: () => linearScale,
+  },
+  /** Grow the value the other way, per axis. `y` grows downwards unless reversed. */
+  reverse: {
+    type: [Boolean, Array] as PropType<XYInput<boolean>>,
+    default: false,
+  },
+  /** The cursor to show while dragging. @default 'pointer' */
+  dragCursor: { type: String, default: 'pointer' },
+  wheel: wheelProp,
+  keyboard: keyboardProp,
+  dragSensitivity: dragSensitivityProp,
+  /** Make the pad unchangeable and remove it from the tab order. */
+  disabled: Boolean,
+  /** Make the value unchangeable. */
+  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 },
+} satisfies ComponentObjectPropsOptions
+
+export type XYPadProps = ExtractPublicPropTypes<typeof xyPadProps>
+
 /**
  * Two-dimensional slider. The per-axis settings are `[x, y]` tuples, and a
  * plain value applies to both axes. Bind the value with `v-model`.
  */
 export const XYPad = /* @__PURE__ */ defineComponent({
   name: 'XYPad',
-  props: {
-    /** The current value as `[x, y]`. Bind it with `v-model`. */
-    modelValue: {
-      type: Array as unknown as PropType<XY<number>>,
-      required: true,
-    },
-    /** The value at the start of the travel, per axis. */
-    min: {
-      type: [Number, Array] as PropType<XYInput<number>>,
-      required: true,
-    },
-    /** The value at the end of the travel, per axis. */
-    max: {
-      type: [Number, Array] as PropType<XYInput<number>>,
-      required: true,
-    },
-    /** Granularity of the value, per axis. @default 1 */
-    step: { type: [Number, Array] as PropType<XYInput<number>>, default: 1 },
-    /** How the value is distributed, per axis. @default linearScale */
-    scale: {
-      type: [Object, Array] as PropType<XYInput<Scale>>,
-      default: () => linearScale,
-    },
-    /** Grow the value the other way, per axis. `y` grows downwards unless reversed. */
-    reverse: {
-      type: [Boolean, Array] as PropType<XYInput<boolean>>,
-      default: false,
-    },
-    /** The cursor to show while dragging. @default { cursor: 'pointer' } */
-    externalStyles: Object as PropType<{ cursor?: string }>,
-    wheel: wheelProp,
-    keyboard: keyboardProp,
-    dragSensitivity: dragSensitivityProp,
-    /** Make the pad unchangeable and remove it from the tab order. */
-    disabled: Boolean,
-    /** Make the value unchangeable. */
-    readonly: Boolean,
-  },
+  props: xyPadProps,
   emits: {
     'update:modelValue': (value: XY<number>) => Array.isArray(value),
-    dragStart: (value: XY<number>) => Array.isArray(value),
-    dragEnd: (value: XY<number>) => Array.isArray(value),
+    /**
+     * A change of the value started, with the value before it and what it is
+     * made with.
+     */
+    changeStart: (value: XY<number>, _source: ChangeSource) =>
+      Array.isArray(value),
+    /** The change ended, with the value it ended on. */
+    changeEnd: (value: XY<number>, _source: ChangeSource) =>
+      Array.isArray(value),
   },
   setup(props, { slots, emit, expose }) {
     const root = ref<HTMLDivElement | null>(null)
@@ -121,7 +151,17 @@ export const XYPad = /* @__PURE__ */ defineComponent({
       }))
     }
 
-    const change = (next: XY<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: XY<number>) => {
+      gesture.changed(next)
+      emit('update:modelValue', next)
+    }
 
     /** Move one axis by one press of `option`, in screen coordinates. */
     function nudge(
@@ -184,21 +224,17 @@ export const XYPad = /* @__PURE__ */ defineComponent({
           selectModifier(props.dragSensitivity, state.event).value,
       }),
       updateOnPointerDown: true,
-      cursor: inactive.value
-        ? undefined
-        : (props.externalStyles?.cursor ?? 'pointer'),
+      cursor: inactive.value ? undefined : props.dragCursor,
       shouldStart: () => !inactive.value,
       onChange: (v) => {
         if (!inactive.value) change(v)
       },
-      onDragStart: (v) => {
+      onDragStart: () => {
         if (inactive.value) return
+        gesture.hold('pointer')
         thumb?.focus()
-        emit('dragStart', v)
-      },
-      onDragEnd: (v) => {
-        if (!inactive.value) emit('dragEnd', v)
       },
+      onDragEnd: () => gesture.end(),
     }))
 
     useWheel(
@@ -208,6 +244,7 @@ export const XYPad = /* @__PURE__ */ defineComponent({
         const move = wheelMove(event)
         if (!move) return
         event.preventDefault()
+        gesture.pulse('wheel')
         nudge(move, props.wheel, event)
       },
       { requireFocus: true },
@@ -236,6 +273,7 @@ export const XYPad = /* @__PURE__ */ defineComponent({
             if (!move) return
             event.preventDefault()
             if (props.keyboard && !inactive.value) {
+              gesture.pulse('keyboard')
               nudge(move, props.keyboard, event)
             }
           },

package/src/components/XYPad/XYPadThumb.ts

@@ -1,13 +1,16 @@
 import {
+  type ComponentObjectPropsOptions,
   defineComponent,
+  type ExtractPublicPropTypes,
   h,
   onBeforeUnmount,
+  type PropType,
   ref,
   watchEffect,
-  type PropType,
 } from 'vue'
 
-import { toXY, type XYInput } from '@tremolo-ui/dom'
+import { type XYInput } from '@tremolo-ui/dom'
+import { toXY } from '@tremolo-ui/dom/internal'
 
 import { checkPlacement } from '../_util/placement'
 import { visuallyHiddenRangeInput } from '../_util/visually-hidden-range-input'
@@ -16,22 +19,26 @@ import { useXYPadContext } from './context'
 
 type PerAxis = XYInput<string | undefined>
 
+const xyPadThumbProps = {
+  /** Sets `--color`, for the theme to colour the thumb with. */
+  color: String,
+  /** The accessible name of each axis, as `[x, y]`. */
+  ariaLabel: [String, Array] as PropType<PerAxis>,
+  /** The ids of what labels each axis, as `[x, y]` or one for both. */
+  ariaLabelledby: [String, Array] as PropType<PerAxis>,
+  /** The ids of what describes each axis, as `[x, y]` or one for both. */
+  ariaDescribedby: [String, Array] as PropType<PerAxis>,
+  /** What the value of each axis means, as `[x, y]` or one for both. */
+  ariaValuetext: [String, Array] as PropType<PerAxis>,
+} satisfies ComponentObjectPropsOptions
+
+export type XYPadThumbProps = ExtractPublicPropTypes<typeof xyPadThumbProps>
+
 /** The thumb, placed at the value, with one range input per axis inside. */
 export const XYPadThumb = /* @__PURE__ */ defineComponent({
   name: 'XYPadThumb',
   inheritAttrs: false,
-  props: {
-    /** Sets `--color`, for the theme to colour the thumb with. */
-    color: String,
-    /** The accessible name of each axis, as `[x, y]`. */
-    ariaLabel: [String, Array] as PropType<PerAxis>,
-    /** The ids of what labels each axis, as `[x, y]` or one for both. */
-    ariaLabelledby: [String, Array] as PropType<PerAxis>,
-    /** The ids of what describes each axis, as `[x, y]` or one for both. */
-    ariaDescribedby: [String, Array] as PropType<PerAxis>,
-    /** What the value of each axis means, as `[x, y]` or one for both. */
-    ariaValuetext: [String, Array] as PropType<PerAxis>,
-  },
+  props: xyPadThumbProps,
   setup(props, { slots, attrs, expose }) {
     const pad = useXYPadContext()
     checkPlacement('XYPadThumb', 'XYPadArea')

package/src/components/XYPad/index.ts

@@ -1,4 +1,4 @@
 export { useXYPadContext, type XYPadContextValue } from './context'
-export { XYPad } from './XYPad'
+export { XYPad, type XYPadProps } from './XYPad'
 export { XYPadArea } from './XYPadArea'
-export { XYPadThumb } from './XYPadThumb'
+export { XYPadThumb, type XYPadThumbProps } from './XYPadThumb'

package/src/components/_util/change-gesture.ts

@@ -0,0 +1,44 @@
+import { onScopeDispose, watch, watchEffect } from 'vue'
+
+import { createChangeGesture, type ChangeSource } from '@tremolo-ui/dom'
+
+export interface ChangeGestureOptions<V> {
+  /** The value now, read when a gesture starts. */
+  value: () => V
+  inactive: () => boolean
+  endDelay: () => number | undefined
+  onStart: (value: V, source: ChangeSource) => void
+  onEnd: (value: V, source: ChangeSource) => void
+}
+
+/**
+ * The core's change gesture, reporting the control's value: the start gets
+ * the value before the change, the end the last one the control emitted.
+ * `modelValue` lags behind until the parent renders, and a drag ends in the
+ * same event as its last change, so the component reports each value it
+ * emits through `changed`.
+ */
+export function useChangeGesture<V>(options: ChangeGestureOptions<V>) {
+  let last = options.value()
+  const gesture = createChangeGesture({
+    onStart: (source) => {
+      last = options.value()
+      options.onStart(last, source)
+    },
+    onEnd: (source) => options.onEnd(last, source),
+  })
+
+  watchEffect(() => gesture.update({ endDelay: options.endDelay() }))
+  // A control that turns inactive mid-gesture, or goes away, should not leave
+  // a host thinking it is still being touched.
+  watch(options.inactive, (inactive) => {
+    if (inactive) gesture.end()
+  })
+  onScopeDispose(() => gesture.end())
+
+  return Object.assign(gesture, {
+    changed: (value: V) => {
+      last = value
+    },
+  })
+}

package/src/components/_util/useCheckSteps.ts

@@ -1,6 +1,6 @@
 import { watchEffect } from 'vue'
 
-import { checkSteps, type CheckStepsOptions } from '@tremolo-ui/dom'
+import { checkSteps, type CheckStepsOptions } from '@tremolo-ui/dom/internal'
 
 /**
  * Warn, in development only, when a key press or a wheel notch cannot produce

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

@@ -1,6 +1,6 @@
 import { h, type VNodeProps } from 'vue'
 
-import { visuallyHiddenStyle } from '@tremolo-ui/dom'
+import { visuallyHiddenStyle } from '@tremolo-ui/dom/internal'
 
 /**
  * The control underneath a headless part: out of sight, but in the

package/src/composables/useInstance.ts

@@ -1,6 +1,6 @@
 import { toValue, watch, type MaybeRefOrGetter } from 'vue'
 
-import { replaceOptions } from '@tremolo-ui/dom'
+import { replaceOptions } from '@tremolo-ui/dom/internal'
 
 /**
  * Create an instance for the element `target` holds, and destroy it when the

package/src/composables/useWheel.ts

@@ -12,12 +12,15 @@ import { useInstance } from './useInstance'
 export function useWheel(
   target: MaybeRefOrGetter<Element | null | undefined>,
   onWheel: (event: WheelEvent) => void,
-  options: MaybeRefOrGetter<WheelOptions> = {},
+  // `onWheel` is left out: the handler is the second argument, and an option
+  // of the same name would replace it on the first update.
+  options: MaybeRefOrGetter<Omit<WheelOptions, 'onWheel'>> = {},
 ) {
   useInstance(
     target,
     options,
-    (element, opts) => createWheel(element, (event) => onWheel(event), opts),
+    (element, opts) =>
+      createWheel(element, { ...opts, onWheel: (event) => onWheel(event) }),
     (instance, next) => instance.update(next),
   )
 }

package/src/index.ts

@@ -1,15 +1,15 @@
 // components
 export {
   AnimationCanvas,
-  type DrawFunction,
-  type InitFunction,
+  type AnimationCanvasProps,
 } from './components/AnimationCanvas'
-export { DropZone } from './components/DropZone'
+export { DropZone, type DropZoneProps } from './components/DropZone'
 export {
   FileInput,
   FileInputTrigger,
   useFileInputContext,
   type FileInputContextValue,
+  type FileInputProps,
 } from './components/FileInput'
 export {
   Knob,
@@ -19,6 +19,8 @@ export {
   KnobThumb,
   useKnobContext,
   type KnobContextValue,
+  type KnobProps,
+  type KnobThumbProps,
 } from './components/Knob'
 export {
   NumberInput,
@@ -28,8 +30,14 @@ export {
   NumberInputStepper,
   useNumberInputContext,
   type NumberInputContextValue,
+  type NumberInputProps,
 } from './components/NumberInput'
-export { Piano, type KeyAttributes, type KeyState } from './components/Piano'
+export {
+  Piano,
+  type KeyAttributes,
+  type KeyState,
+  type PianoProps,
+} from './components/Piano'
 export {
   PointsEditor,
   PointsEditorBackground,
@@ -38,6 +46,8 @@ export {
   PointsEditorSelectionBox,
   usePointsEditorContext,
   type PointsEditorContextValue,
+  type PointsEditorPointProps,
+  type PointsEditorProps,
 } from './components/PointsEditor'
 export {
   Slider,
@@ -47,6 +57,11 @@ export {
   SliderTrack,
   useSliderContext,
   type SliderContextValue,
+  type SliderMarksOptionProps,
+  type SliderMarksProps,
+  type SliderProps,
+  type SliderThumbProps,
+  type SliderTrackProps,
 } from './components/Slider'
 export {
   XYPad,
@@ -54,6 +69,8 @@ export {
   XYPadThumb,
   useXYPadContext,
   type XYPadContextValue,
+  type XYPadProps,
+  type XYPadThumbProps,
 } from './components/XYPad'
 
 // composables