@tremolo-ui/vue 0.7.0

package/src/components/NumberInput/NumberInput.ts

@@ -0,0 +1,258 @@
+import { computed, defineComponent, h, provide, ref, type PropType } from 'vue'
+
+import {
+  commitNumberInputText,
+  numberInputBounds,
+  numberInputRanges,
+  nudgeNumberInput,
+  parseNumberText,
+  wheelDirection,
+} from '@tremolo-ui/dom'
+import { linearScale, type Scale } from '@tremolo-ui/functions'
+
+import { useWheel } from '../../composables/useWheel'
+import { dragSensitivityProp, keyboardProp, wheelProp } from '../_util/props'
+import { useCheckSteps } from '../_util/useCheckSteps'
+
+import { NumberInputKey } from './context'
+
+/** Input with some useful functions for entering numbers. Bind it with `v-model`. */
+export const NumberInput = /* @__PURE__ */ defineComponent({
+  name: 'NumberInput',
+  props: {
+    /** The current value. Bind it with `v-model`. */
+    modelValue: { type: Number, required: true },
+    /** The lowest value. Leave it out for no lower end. */
+    min: Number,
+    /** The highest value. Leave it out for no upper end. */
+    max: Number,
+    /** Granularity of the value. @default 1 */
+    step: { type: Number, default: 1 },
+    /** How the value is distributed, for a `normalized` amount. */
+    scale: { type: Object as PropType<Scale>, default: () => linearScale },
+    /** The text shown for a value. @default String */
+    format: {
+      type: Function as PropType<(value: number) => string>,
+      default: String,
+    },
+    /** Read a value back out of the text. Has to undo `format`. */
+    parse: {
+      type: Function as PropType<(text: string) => number>,
+      default: parseNumberText,
+    },
+    /** Keep the value within `min` and `max` when committed or stepped. */
+    clampValue: { type: Boolean, default: true },
+    wheel: wheelProp,
+    keyboard: keyboardProp,
+    dragSensitivity: dragSensitivityProp,
+    /** Pixels of vertical drag on the stepper per `step`. `null` turns it off. */
+    drag: { type: Number as PropType<number | null>, default: 1 },
+    /** Hide the cursor while dragging the stepper. */
+    pointerLock: Boolean,
+    /** Select the text when the field takes focus. @default 'none' */
+    selectOnFocus: {
+      type: String as PropType<'all' | 'number' | 'none'>,
+      default: 'none',
+    },
+    /** Show the plain value while the field has focus. */
+    unformatOnFocus: Boolean,
+    /** Put the caret back at the same digit after an arrow key step. */
+    keepCaretOnStep: Boolean,
+    /** Commit and leave the field on Enter. @default true */
+    blurOnEnter: { type: Boolean, default: true },
+    /** Make the input unchangeable and remove it from the tab order. */
+    disabled: Boolean,
+    /** Make the value unchangeable while leaving the field focusable. */
+    readonly: Boolean,
+  },
+  emits: {
+    'update:modelValue': (value: number) => typeof value === 'number',
+  },
+  setup(props, { slots, emit, expose }) {
+    const root = ref<HTMLDivElement | null>(null)
+    /**
+     * The text being typed. The only state here: not a copy of the value, but
+     * the half-finished entry that has no value to be derived from yet.
+     */
+    const draft = ref<string | null>(null)
+    let input: HTMLInputElement | null = null
+
+    const inactive = computed(() => props.disabled || props.readonly)
+    const ranges = computed(() =>
+      numberInputRanges({
+        min: props.min,
+        max: props.max,
+        step: props.step,
+        scale: props.scale,
+        clampValue: props.clampValue,
+      }),
+    )
+    const bounds = computed(() =>
+      numberInputBounds(props.modelValue, {
+        min: props.min,
+        max: props.max,
+        clampValue: props.clampValue,
+      }),
+    )
+    const text = computed(() => draft.value ?? props.format(props.modelValue))
+
+    // An open end has no travel to sample, so the check is skipped.
+    useCheckSteps(() => ({
+      component: 'NumberInput',
+      range:
+        props.min !== undefined &&
+        props.max !== undefined &&
+        props.min < props.max
+          ? {
+              min: props.min,
+              max: props.max,
+              step: props.step,
+              scale: props.scale,
+            }
+          : null,
+      keyboard: props.keyboard,
+      wheel: props.wheel,
+      format: props.format,
+    }))
+
+    function changeValue(next: number) {
+      if (inactive.value) return
+      draft.value = null
+      if (next !== props.modelValue) emit('update:modelValue', next)
+    }
+
+    provide(NumberInputKey, {
+      get value() {
+        return props.modelValue
+      },
+      get min() {
+        return props.min
+      },
+      get max() {
+        return props.max
+      },
+      get step() {
+        return props.step
+      },
+      get disabled() {
+        return props.disabled
+      },
+      get readonly() {
+        return props.readonly
+      },
+      get keyboard() {
+        return props.keyboard
+      },
+      get drag() {
+        return props.drag
+      },
+      get dragSensitivity() {
+        return props.dragSensitivity
+      },
+      get pointerLock() {
+        return props.pointerLock
+      },
+      get selectOnFocus() {
+        return props.selectOnFocus
+      },
+      get unformatOnFocus() {
+        return props.unformatOnFocus
+      },
+      get keepCaretOnStep() {
+        return props.keepCaretOnStep
+      },
+      get blurOnEnter() {
+        return props.blurOnEnter
+      },
+      get text() {
+        return text.value
+      },
+      get editing() {
+        return draft.value !== null
+      },
+      get outOfRange() {
+        return draft.value === null && bounds.value.outOfRange
+      },
+      get atMin() {
+        return bounds.value.atMin
+      },
+      get atMax() {
+        return bounds.value.atMax
+      },
+      get rawRange() {
+        return ranges.value.raw
+      },
+      setDraft: (next) => {
+        if (inactive.value) return
+        draft.value = next
+        // Deliberately unclamped: clamping here would make "1500" impossible
+        // to type into an input whose max is 100.
+        const parsed = props.parse(next)
+        if (Number.isFinite(parsed)) emit('update:modelValue', parsed)
+      },
+      commitDraft: () => {
+        if (draft.value === null || inactive.value) return
+        const committed = commitNumberInputText(draft.value, props.parse, {
+          min: props.min,
+          max: props.max,
+          clampValue: props.clampValue,
+        })
+        // Text with no number is not a value: the field goes back to what it
+        // was showing.
+        if (committed === null) draft.value = null
+        else changeValue(committed)
+      },
+      changeValue,
+      nudge: (direction, option, modifiers) =>
+        changeValue(
+          nudgeNumberInput(
+            props.modelValue,
+            direction,
+            option,
+            ranges.value,
+            modifiers,
+          ),
+        ),
+      setInput: (element) => {
+        input = element
+      },
+    })
+
+    useWheel(
+      root,
+      (event) => {
+        const direction = wheelDirection(event)
+        if (!props.wheel || inactive.value || direction === null) return
+        event.preventDefault()
+        changeValue(
+          nudgeNumberInput(
+            props.modelValue,
+            direction,
+            props.wheel,
+            ranges.value,
+            event,
+          ),
+        )
+      },
+      { requireFocus: true },
+    )
+
+    expose({
+      focus: () => {
+        if (!props.disabled) input?.focus()
+      },
+      blur: () => input?.blur(),
+    })
+
+    return () =>
+      h(
+        'div',
+        {
+          ref: root,
+          'data-disabled': props.disabled ? '' : undefined,
+          'data-readonly': props.readonly ? '' : undefined,
+        },
+        slots.default?.(),
+      )
+  },
+})

package/src/components/NumberInput/NumberInputDecrementStepper.ts

@@ -0,0 +1,7 @@
+import { stepperButton } from './stepper-button'
+
+/** Lowers the value by one `step`, repeating while held. */
+export const NumberInputDecrementStepper = /* @__PURE__ */ stepperButton(
+  'NumberInputDecrementStepper',
+  -1,
+)

package/src/components/NumberInput/NumberInputField.ts

@@ -0,0 +1,128 @@
+import {
+  computed,
+  defineComponent,
+  h,
+  nextTick,
+  onBeforeUnmount,
+  ref,
+  watchEffect,
+} from 'vue'
+
+import {
+  caretAtDecimalOffset,
+  caretDecimalOffset,
+  numberSpan,
+} from '@tremolo-ui/dom'
+
+import { useNumberInputContext } from './context'
+
+/**
+ * The text field, and the only place the value can be typed. While the user
+ * types, their own text stands rather than `format(value)`.
+ */
+export const NumberInputField = /* @__PURE__ */ defineComponent({
+  name: 'NumberInputField',
+  setup(_, { expose }) {
+    const field = useNumberInputContext()
+    const input = ref<HTMLInputElement | null>(null)
+    const focused = ref(false)
+    watchEffect(() => field.setInput(input.value))
+    onBeforeUnmount(() => field.setInput(null))
+
+    // Only until the first keystroke: from then on the draft is the user's
+    // own text and stands on its own, formatted or not.
+    const shown = computed(() =>
+      field.unformatOnFocus && focused.value && !field.editing
+        ? String(field.value)
+        : field.text,
+    )
+
+    async function select() {
+      if (field.selectOnFocus === 'none') return
+      // Selecting has to wait for `unformatOnFocus` to swap the text in, or
+      // it would cover the wrong characters.
+      await nextTick()
+      const element = input.value
+      if (!element || !focused.value) return
+      const span =
+        field.selectOnFocus === 'all'
+          ? { start: 0, end: element.value.length }
+          : numberSpan(element.value)
+      if (span) element.setSelectionRange(span.start, span.end)
+    }
+
+    async function step(direction: number, event: KeyboardEvent) {
+      const element = event.currentTarget as HTMLInputElement
+      const from = element.value
+      const offset =
+        field.keepCaretOnStep && element.selectionStart !== null
+          ? caretDecimalOffset(from, element.selectionStart)
+          : null
+      field.nudge(direction, field.keyboard!, event)
+      if (offset === null) return
+      await nextTick()
+      // The step may have been clamped away, leaving the text as it was.
+      if (element.value === from) return
+      const caret = caretAtDecimalOffset(element.value, offset)
+      element.setSelectionRange(caret, caret)
+    }
+
+    expose({
+      focus: () => input.value?.focus(),
+      blur: () => input.value?.blur(),
+    })
+
+    // Not type="number": that brings native spinners and a value the browser
+    // parses itself, neither of which survives a unit suffix.
+    return () =>
+      h('input', {
+        ref: input,
+        type: 'text',
+        inputmode: 'decimal',
+        role: 'spinbutton',
+        value: shown.value,
+        disabled: field.disabled,
+        readonly: field.readonly,
+        'aria-disabled': field.disabled,
+        'aria-readonly': field.readonly,
+        'aria-valuenow': field.value,
+        'aria-valuemin': field.min,
+        'aria-valuemax': field.max,
+        // The formatted text even while the plain number is shown: it is the
+        // one that says what the value means.
+        'aria-valuetext': field.text,
+        step: field.step,
+        'data-disabled': field.disabled ? '' : undefined,
+        'data-readonly': field.readonly ? '' : undefined,
+        'data-out-of-range': field.outOfRange ? '' : undefined,
+        onInput: (event: Event) =>
+          field.setDraft((event.target as HTMLInputElement).value),
+        onFocus: () => {
+          focused.value = true
+          select()
+        },
+        onBlur: () => {
+          focused.value = false
+          // Nothing was typed, so there is no draft and this returns at once.
+          field.commitDraft()
+        },
+        onKeydown: (event: KeyboardEvent) => {
+          const key = event.key
+          if (key === 'Enter') {
+            field.commitDraft()
+            if (field.blurOnEnter) (event.target as HTMLInputElement).blur()
+          } else if (
+            field.keyboard &&
+            !field.disabled &&
+            !field.readonly &&
+            (key === 'ArrowUp' || key === 'ArrowDown') &&
+            // Arrow keys pick a candidate while an IME is converting.
+            !event.isComposing
+          ) {
+            event.preventDefault()
+            step(key === 'ArrowUp' ? 1 : -1, event)
+          }
+        },
+      })
+  },
+})

package/src/components/NumberInput/NumberInputIncrementStepper.ts

@@ -0,0 +1,7 @@
+import { stepperButton } from './stepper-button'
+
+/** Raises the value by one `step`, repeating while held. */
+export const NumberInputIncrementStepper = /* @__PURE__ */ stepperButton(
+  'NumberInputIncrementStepper',
+  1,
+)

package/src/components/NumberInput/NumberInputStepper.ts

@@ -0,0 +1,54 @@
+import { computed, defineComponent, h, provide, ref, watch } from 'vue'
+
+import { createStepperDrag, type StepperDragInstance } from '@tremolo-ui/dom'
+
+import { StepperKey, useNumberInputContext } from './context'
+
+/**
+ * The area the steppers sit in, and a drag handle in its own right: dragging
+ * it up and down moves the value one `step` every `drag` pixels.
+ */
+export const NumberInputStepper = /* @__PURE__ */ defineComponent({
+  name: 'NumberInputStepper',
+  setup(_, { slots }) {
+    const field = useNumberInputContext()
+    const el = ref<HTMLDivElement | null>(null)
+    let instance: StepperDragInstance | null = null
+
+    // Only attached while it can do something: `createDrag` puts
+    // `touch-action: none` on the element, and a stepper that cannot be
+    // dragged should not stop the page scrolling under a finger.
+    const enabled = computed(
+      () => field.drag !== null && !field.disabled && !field.readonly,
+    )
+    const options = () => ({
+      range: field.rawRange,
+      pixels: field.drag ?? 1,
+      sensitivity: field.dragSensitivity,
+      pointerLock: field.pointerLock,
+    })
+
+    watch(
+      [el, enabled],
+      ([element, on], _, onCleanup) => {
+        if (!element || !on) return
+        const current = createStepperDrag(element, {
+          ...options(),
+          getValue: () => field.value,
+          onChange: (next) => field.changeValue(next),
+        })
+        instance = current
+        onCleanup(() => {
+          current.destroy()
+          if (instance === current) instance = null
+        })
+      },
+      { immediate: true, flush: 'post' },
+    )
+    watch(options, (next) => instance?.update(next))
+
+    provide(StepperKey, { moved: () => instance?.moved() ?? false })
+
+    return () => h('div', { ref: el }, slots.default?.())
+  },
+})

package/src/components/NumberInput/context.ts

@@ -0,0 +1,63 @@
+import { type InjectionKey } from 'vue'
+
+import {
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+} from '@tremolo-ui/dom'
+import { type ValueRange } from '@tremolo-ui/functions'
+
+import { injectContext } from '../_util/context'
+
+/** What `NumberInput` shares with its parts. The fields are getters. */
+export interface NumberInputContextValue {
+  readonly value: number
+  readonly min: number | undefined
+  readonly max: number | undefined
+  readonly step: number
+  readonly disabled: boolean
+  readonly readonly: boolean
+  readonly keyboard: ModifierValue<InputEventOption> | null
+  readonly drag: number | null
+  readonly dragSensitivity: ModifierValue<number>
+  readonly pointerLock: boolean
+  readonly selectOnFocus: 'all' | 'number' | 'none'
+  readonly unformatOnFocus: boolean
+  readonly keepCaretOnStep: boolean
+  readonly blurOnEnter: boolean
+  /** The text the field shows: the draft while typing, else `format(value)`. */
+  readonly text: string
+  /** Whether the user has typed since the value was last committed. */
+  readonly editing: boolean
+  readonly outOfRange: boolean
+  readonly atMin: boolean
+  readonly atMax: boolean
+  /** The range a raw amount moves across, for the stepper drag. */
+  readonly rawRange: ValueRange
+  /** Keep typed text as the draft, reporting the number in it. */
+  setDraft: (text: string) => void
+  /** Commit the draft, clamped, or drop it when it holds no number. */
+  commitDraft: () => void
+  /** Set the value, dropping any draft. */
+  changeValue: (value: number) => void
+  /** Move the value by one press of `option`. */
+  nudge: (
+    direction: number,
+    option: ModifierValue<InputEventOption>,
+    modifiers?: ModifierState,
+  ) => void
+  /** @internal `NumberInputField` registers the element focus() moves to. */
+  setInput: (input: HTMLInputElement | null) => void
+}
+
+export const NumberInputKey: InjectionKey<NumberInputContextValue> =
+  Symbol('NumberInput')
+
+/** The context of the enclosing `NumberInput`, for a part of your own. */
+export function useNumberInputContext(): NumberInputContextValue {
+  return injectContext(NumberInputKey, 'NumberInput')
+}
+
+/** @internal Whether the drag on `NumberInputStepper` has moved the value. */
+export const StepperKey: InjectionKey<{ moved: () => boolean }> =
+  Symbol('NumberInputStepper')

package/src/components/NumberInput/index.ts

@@ -0,0 +1,6 @@
+export { useNumberInputContext, type NumberInputContextValue } from './context'
+export { NumberInput } from './NumberInput'
+export { NumberInputDecrementStepper } from './NumberInputDecrementStepper'
+export { NumberInputField } from './NumberInputField'
+export { NumberInputIncrementStepper } from './NumberInputIncrementStepper'
+export { NumberInputStepper } from './NumberInputStepper'

package/src/components/NumberInput/stepper-button.ts

@@ -0,0 +1,65 @@
+import { computed, defineComponent, h, inject } from 'vue'
+
+import { useLongPress } from '../../composables/useLongPress'
+
+import { StepperKey, useNumberInputContext } from './context'
+
+/** The body of `NumberInputIncrementStepper` and `NumberInputDecrementStepper`. */
+export function stepperButton(name: string, direction: 1 | -1) {
+  return defineComponent({
+    name,
+    setup(_, { slots }) {
+      const field = useNumberInputContext()
+      const stepper = inject(StepperKey, null)
+      const blocked = computed(
+        () => field.disabled || (direction > 0 ? field.atMax : field.atMin),
+      )
+      const press = useLongPress({
+        onPress: () => {
+          if (field.disabled || field.readonly) return
+          // Once the pointer has actually travelled, the drag on the stepper
+          // owns the value; repeating on top of it would move it twice.
+          if (stepper?.moved()) return
+          field.nudge(direction, ['raw', field.step])
+        },
+      })
+      // A bare arrow has no accessible name of its own. Overridable, since a
+      // caller may need it in their own language. `role="button"` does not
+      // take aria-readonly, so that state reaches the styles through the data
+      // attribute alone.
+      return () =>
+        h(
+          'div',
+          {
+            role: 'button',
+            tabindex: -1,
+            'aria-label': direction > 0 ? 'Increment' : 'Decrement',
+            'aria-disabled': blocked.value,
+            'data-disabled': blocked.value ? '' : undefined,
+            'data-readonly': field.readonly ? '' : undefined,
+            onPointerdown: (event: PointerEvent) => press(event),
+          },
+          slots.default
+            ? slots.default()
+            : h(
+                'svg',
+                {
+                  style: {
+                    width: 'var(--stepper-icon-size)',
+                    height: 'var(--stepper-icon-size)',
+                  },
+                  viewBox: '0 0 24 24',
+                  fill: 'none',
+                  stroke: 'currentColor',
+                  'stroke-width': 2,
+                  'stroke-linecap': 'round',
+                  'stroke-linejoin': 'round',
+                },
+                h('polyline', {
+                  points: direction > 0 ? '18 15 12 9 6 15' : '6 9 12 15 18 9',
+                }),
+              ),
+        )
+    },
+  })
+}