@tremolo-ui/react 0.5.0 → 0.6.0

package/src/components/NumberInput/context.tsx

@@ -1,6 +1,12 @@
 import { createContext, RefObject, useContext } from 'react'
 
-import type { InputEventOption, Scale, ValueRange } from '@tremolo-ui/functions'
+import type {
+  InputEventOption,
+  ModifierState,
+  ModifierValue,
+  Scale,
+  ValueRange,
+} from '@tremolo-ui/functions'
 
 export type NumberInputContextValue = {
   value: number
@@ -21,14 +27,29 @@ export type NumberInputContextValue = {
   clampValue: boolean
 
   /**
-   * The effective scaling for `applyDelta` and for clamping on commit, with the
-   * unbounded ends filled in. Ignores `min` / `max` when `clampValue` is off.
+   * The effective scaling for `applyDelta`, with unbounded ends filled in.
+   * Ignores `min` / `max` when `clampValue` is off.
    */
   range: ValueRange
+  /** The effective range for raw input, whose open ends cover finite numbers. */
+  rawRange: ValueRange
 
-  keyboard: InputEventOption | null
+  keyboard: ModifierValue<InputEventOption> | null
   /** Pixels of vertical drag on `Stepper` that move the value by one `step`. */
   drag: number | null
+  /** How much a `Stepper` drag counts, per modifier key. */
+  dragSensitivity: ModifierValue<number>
+  /** Whether a `Stepper` drag hides the pointer and reads its movement. */
+  pointerLock: boolean
+
+  /** What `InputField` selects when it takes focus. */
+  selectOnFocus: 'all' | 'number' | 'none'
+  /** Whether `InputField` shows the plain value while it has focus. */
+  unformatOnFocus: boolean
+  /** Whether `InputField` puts the caret back after an arrow key steps the value. */
+  keepCaretOnStep: boolean
+  /** Whether Enter leaves `InputField` as well as committing. */
+  blurOnEnter: boolean
 
   /** What the input shows: the draft while editing, the formatted value otherwise. */
   text: string
@@ -44,18 +65,23 @@ export type NumberInputContextValue = {
 
   /** Typing. Replaces the draft and reports the parsed value, unclamped. */
   setDraft: (text: string) => void
-  /** Blur or Enter. Clamps the draft, reports it, and drops the draft. */
+  /** Blur or Enter. Optionally clamps the draft, reports it, and drops it. */
   commitDraft: () => void
   /** Drops the draft and replaces the value: steppers, wheel, keyboard, drag. */
   changeValue: (next: number) => void
   /** Moves the value by one `option` in `direction`, normally +1 or -1. */
-  nudge: (direction: number, option: InputEventOption) => void
+  nudge: (
+    direction: number,
+    option: ModifierValue<InputEventOption>,
+    modifiers?: ModifierState,
+  ) => void
 
   /** `InputField` registers itself here; `Root` focuses it through its methods. */
   inputRef: RefObject<HTMLInputElement | null>
 }
 
-const NumberInputContext = createContext<NumberInputContextValue | null>(null)
+const NumberInputContext =
+  /* @__PURE__ */ createContext<NumberInputContextValue | null>(null)
 
 export const NumberInputProvider = NumberInputContext.Provider
 
@@ -81,7 +107,8 @@ export type StepperContextValue = {
   draggingRef: RefObject<boolean>
 }
 
-const StepperContext = createContext<StepperContextValue | null>(null)
+const StepperContext =
+  /* @__PURE__ */ createContext<StepperContextValue | null>(null)
 
 export const StepperProvider = StepperContext.Provider
 

package/src/components/NumberInput/index.tsx

@@ -1,4 +1,3 @@
-import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
   CSSProperties,
@@ -13,17 +12,22 @@ import {
 
 import {
   applyDelta,
-  clamp,
-  formatValue,
   InputEventOption,
+  ModifierState,
+  type ModifierValue,
   linearScale,
-  parseValue,
+  selectInputEvent,
   type Scale,
-  type Units,
   type ValueRange,
 } from '@tremolo-ui/functions'
 
+import { useCheckSteps } from '../../hooks/_internal/useCheckSteps'
 import { useWheel } from '../../hooks/useWheel'
+import {
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
+} from '../../input-event'
 
 import { NumberInputProvider } from './context'
 import { DecrementStepper } from './DecrementStepper'
@@ -38,8 +42,27 @@ export interface NumberInputProps {
    */
   value: number
 
+  /**
+   * Lowest value. Leave it out for no lower bound.
+   *
+   * It is enforced when a value is committed or stepped, while `clampValue` is
+   * on. A value below it carries `data-out-of-range` on `InputField`.
+   */
   min?: number
+  /**
+   * Highest value. Leave it out for no upper bound.
+   *
+   * It is enforced when a value is committed or stepped, while `clampValue` is
+   * on. A value above it carries `data-out-of-range` on `InputField`.
+   */
   max?: number
+  /**
+   * Granularity of the value. The steppers, a drag on `Stepper`, the wheel and
+   * the arrow keys snap it to multiples of `step`; a typed value is left as it
+   * is.
+   *
+   * @default 1
+   */
   step?: number
   /**
    * How the value is distributed across the travel of a drag or a
@@ -50,26 +73,20 @@ export interface NumberInputProps {
   scale?: Scale
 
   /**
-   * Unit to display the value in, or a list to pick from by magnitude.
-   * Builds the default `format` and `parse`.
+   * Render the value as text. Plain digits by default.
+   *
+   * `unitFormat` from `@tremolo-ui/functions` builds this and `parse` together
+   * for a unit, as a pair to spread into the root.
    *
    * @example
-   * units='Hz'
-   * units={[['Hz', 1], ['kHz', 1000]]}
-   * units={[['ms', 1], ['s', 1000]]}
+   * <NumberInput.Root {...unitFormat('Hz', { digits: 2 })} value={v} />
    */
-  units?: string | Units
+  format?: (value: number) => string
   /**
-   * Digits after the decimal point, for the default `format`.
+   * Read a value back out of the text. Has to undo `format`.
    *
-   * @example
-   * // units={[['Hz', 1], ['kHz', 1000]]} digit={2}
-   * // 100 -> 100.00Hz, 1600 -> 1.60kHz
+   * Text with no number in it reads as `NaN`, which leaves the value alone.
    */
-  digit?: number
-  /** Render the value as text. Takes precedence over `units` / `digit`. */
-  format?: (value: number) => string
-  /** Read a value back out of the text. Takes precedence over `units`. */
   parse?: (text: string) => number
 
   /**
@@ -80,37 +97,135 @@ export interface NumberInputProps {
   clampValue?: boolean
 
   /**
-   * Wheel control option. Only applies while the focus is inside, so that
-   * scrolling past the input does not change it.
-   * If null, no event will be triggered
+   * How much one notch of the wheel moves the value. It only acts while the
+   * focus is inside, so that scrolling the page past the input leaves it
+   * alone.
+   *
+   * `['raw', n]` moves the value by `n`, and `['normalized', n]` by `n` of the
+   * range between `min` and `max`. The result is snapped to `step`, except for
+   * an amount set on a modifier key (`{ default: …, shift: … }`). `null` turns
+   * the wheel off.
+   *
+   * @default ['raw', 1]
    */
-  wheel?: InputEventOption | null
+  wheel?: ModifierValue<InputEventOption> | null
   /**
-   * keyboard control option
-   * If null, no event will be triggered
+   * How much one arrow key press moves the value.
+   *
+   * `['raw', n]` moves the value by `n`, and `['normalized', n]` by `n` of the
+   * range between `min` and `max`. The result is snapped to `step`, except for
+   * an amount set on a modifier key, which is what lets shift move off the
+   * grid. `null` turns the arrow keys off.
+   *
+   * The default moves by 1, and by 0.1 with shift. With a `step` above 1, raise
+   * the amount to match: 1 would round straight back to where it started, and
+   * a development build warns about it.
+   *
+   * @default { default: ['raw', 1], shift: ['raw', 0.1] }
    */
-  keyboard?: InputEventOption | null
+  keyboard?: ModifierValue<InputEventOption> | null
   /**
    * Pixels of vertical drag on `Stepper` that move the value by one `step`.
-   * If null, no event will be triggered
+   * `null` turns the drag off.
    * @default 1
    */
   drag?: number | null
 
   /**
-   * Only the appearance will change.
-   * Please consider using with readonly.
-   * aria-disabled property is also applied.
+   * How much a `Stepper` drag counts, per modifier key.
+   *
+   * `1` is `drag` pixels per `step`; `0.1` makes the same movement cover a
+   * tenth of that. Shift is bound to `0.1` by default, to match what it does
+   * on the arrow keys.
+   *
+   * A modifier entry is not snapped to `step`, which is what lets a finer
+   * amount move at all.
+   *
+   * @default { default: 1, shift: 0.1 }
+   */
+  dragSensitivity?: ModifierValue<number>
+
+  /**
+   * Hide the cursor while dragging a `Stepper` and read the pointer movement
+   * directly, rather than letting it wander off across the screen.
+   *
+   * The drag is already relative, so the pointer position carries nothing —
+   * but it still runs into the edge of the screen, where the operating system
+   * pins it and the coordinates stop changing.
+   *
+   * Off by default: the browser shows its own notice, Esc takes the lock back,
+   * and the request can be refused. A refused request is not an error, and the
+   * drag carries on as an ordinary one.
+   *
+   * @default false
+   */
+  pointerLock?: boolean
+
+  /**
+   * Select the text when `InputField` takes focus: `'all'` selects all of it,
+   * `'number'` only the leading number, leaving whatever the format appended,
+   * and `'none'` leaves the caret where the click put it.
+   * @default 'none'
+   */
+  selectOnFocus?: 'all' | 'number' | 'none'
+  /**
+   * Show the plain value while `InputField` has focus, dropping whatever
+   * `format` put around it: an input reading `1.23kHz` shows `1230` to be
+   * typed over.
+   *
+   * The number shown is the value itself, not the number inside the formatted
+   * text. Those differ whenever the format scales — `1.23` out of `1.23kHz`
+   * would read back as 1.23 and lose a factor of a thousand — and it is also
+   * why a rounded display no longer becomes the value: `1.6` shown as `2Hz`
+   * offers `1.6` for editing, not `2`.
+   *
+   * @default false
+   */
+  unformatOnFocus?: boolean
+  /**
+   * Put the caret in `InputField` back where it was after an arrow key steps
+   * the value.
+   *
+   * A controlled input whose `value` is replaced drops the caret at the end,
+   * so without this the second press of a repeated step always acts on the
+   * last digit. With it, the digit under the caret stays under the caret and
+   * a column can be held while stepping.
+   *
+   * The position is measured from the decimal point rather than from either
+   * end, so it survives the number growing or shrinking: the caret between
+   * `9` and `.9` is still between `10` and `.0`.
+   *
+   * It only restores the caret. Which digit it sits on does not change the
+   * size of the step — that is `keyboard`'s to say.
+   *
+   * @default false
+   */
+  keepCaretOnStep?: boolean
+  /**
+   * Commit and leave `InputField` when Enter is pressed. Enter commits either
+   * way.
+   * @default true
+   */
+  blurOnEnter?: boolean
+
+  /**
+   * Make the input unchangeable and remove it from the tab order.
+   * The parts carry `data-disabled` while it is set.
    */
   disabled?: boolean
   /**
    * Make the value unchangeable.
-   * aria-readonly property is also applied.
+   * The parts carry `data-readonly` while it is set.
    */
   readonly?: boolean
 
   className?: string
   style?: CSSProperties
+  /**
+   * Called with the new value. While the user types, it is called for every
+   * entry that reads as a number, unclamped; committing the entry calls it
+   * again if clamping changes the value.
+   */
   onChange?: (value: number) => void
 
   /**
@@ -134,10 +249,24 @@ export interface NumberInputMethods {
   blur: () => void
 }
 
+/**
+ * A number at the start of the text, and nothing read after it. A half-typed
+ * entry still yields the number in front of it, but text with no number is
+ * `NaN` rather than 0, so that "unreadable" and "the user typed 0" stay apart.
+ */
+const LEADING_NUMBER = /^\s*([+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)/
+
+const defaultFormat = (value: number) => String(value)
+
+const defaultParse = (text: string) => {
+  const match = text.match(LEADING_NUMBER)
+  return match ? Number(match[1]) : NaN
+}
+
 type Props = NumberInputProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof NumberInputProps>
 
-export const Root = forwardRef<NumberInputMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
   (
     {
       value,
@@ -145,14 +274,18 @@ export const Root = forwardRef<NumberInputMethods, Props>(
       max,
       step = 1,
       scale = linearScale,
-      units,
-      digit,
       format: formatProp,
       parse: parseProp,
       clampValue = true,
-      wheel = ['raw', 1],
-      keyboard = ['raw', 1],
+      wheel = DEFAULT_WHEEL_OPTIONS,
+      keyboard = DEFAULT_KEYBOARD_OPTIONS,
       drag = 1,
+      dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
+      pointerLock = false,
+      selectOnFocus = 'none',
+      unformatOnFocus = false,
+      keepCaretOnStep = false,
+      blurOnEnter = true,
       disabled = false,
       readonly = false,
       className,
@@ -170,20 +303,15 @@ export const Root = forwardRef<NumberInputMethods, Props>(
      * but the half-finished entry that has no value to be derived from yet.
      */
     const [draft, setDraft] = useState<string | null>(null)
+    const inactive = disabled || readonly
 
     // --- interpret props ---
-    const format = useCallback(
-      (v: number) =>
-        formatProp ? formatProp(v) : formatValue(v, units, digit),
-      [formatProp, units, digit],
-    )
-    const parse = useCallback(
-      (t: string) => (parseProp ? parseProp(t) : parseValue(t, units)),
-      [parseProp, units],
-    )
+    const format = formatProp ?? defaultFormat
+    const parse = parseProp ?? defaultParse
 
-    // An unbounded end, and a range the caller opted out of enforcing, both
-    // become the widest range the value pipeline can express.
+    // Normalized input needs a finite span even when an end is unbounded or
+    // the caller opted out of clamping. Safe integers provide one without
+    // overflowing the span calculation used by a scale.
     const range: ValueRange = useMemo(
       () => ({
         min: (clampValue ? min : undefined) ?? Number.MIN_SAFE_INTEGER,
@@ -194,53 +322,108 @@ export const Root = forwardRef<NumberInputMethods, Props>(
       [clampValue, min, max, step, scale],
     )
 
+    // Raw input does not need a finite span for normalization, so its open
+    // ends can cover every finite JavaScript number instead of stopping at the
+    // safe-integer range.
+    const rawRange: ValueRange = useMemo(
+      () => ({
+        min: (clampValue ? min : undefined) ?? -Number.MAX_VALUE,
+        max: (clampValue ? max : undefined) ?? Number.MAX_VALUE,
+        step,
+        scale,
+      }),
+      [clampValue, min, max, step, scale],
+    )
+
+    // The pipeline range stands in the safe-integer range when an end is
+    // open, and there is no travel to sample across that. Probing is skipped
+    // rather than run against a range nobody set.
+    const probeRange = useMemo(
+      () =>
+        min !== undefined && max !== undefined && min < max
+          ? { min, max, step, scale }
+          : null,
+      [min, max, step, scale],
+    )
+
+    useCheckSteps({
+      component: 'NumberInput',
+      range: probeRange,
+      keyboard,
+      wheel,
+      format,
+    })
+
     const text = draft ?? format(value)
-    const editing = draft != null
+    const editing = draft !== null
     const outOfRange =
       !editing &&
-      ((min != undefined && value < min) || (max != undefined && value > max))
+      ((min !== undefined && value < min) || (max !== undefined && value > max))
 
     // --- internal functions ---
     const handleDraft = useCallback(
       (next: string) => {
-        if (readonly) return
+        if (inactive) return
         setDraft(next)
         // Deliberately unclamped: clamping here would make "1500" impossible
         // to type into an input whose max is 100.
         const parsed = parse(next)
         if (Number.isFinite(parsed)) onChange?.(parsed)
       },
-      [readonly, parse, onChange],
+      [inactive, parse, onChange],
     )
 
     const changeValue = useCallback(
       (next: number) => {
-        if (readonly) return
+        if (inactive) return
         setDraft(null)
-        if (next != value) onChange?.(next)
+        if (next !== value) onChange?.(next)
       },
-      [readonly, value, onChange],
+      [inactive, value, onChange],
     )
 
     const commitDraft = useCallback(() => {
-      if (draft == null || readonly) return
-      // `range` is already the widest possible range when clampValue is off.
-      changeValue(clamp(parse(draft), range.min, range.max))
-    }, [draft, readonly, parse, range, changeValue])
+      if (draft === null || inactive) return
+      const parsed = parse(draft)
+      // Text with no number in it is not a value. Dropping the draft puts the
+      // input back to what it was showing, rather than committing a zero the
+      // user never typed.
+      if (!Number.isFinite(parsed)) {
+        setDraft(null)
+        return
+      }
+      let committed = parsed
+      if (clampValue && min !== undefined) committed = Math.max(committed, min)
+      if (clampValue && max !== undefined) committed = Math.min(committed, max)
+      changeValue(committed)
+    }, [draft, inactive, parse, clampValue, min, max, changeValue])
 
     const nudge = useCallback(
-      (direction: number, option: InputEventOption) => {
-        changeValue(applyDelta(value, direction, option, range))
+      (
+        direction: number,
+        option: ModifierValue<InputEventOption>,
+        modifiers?: ModifierState,
+      ) => {
+        const [mode] = selectInputEvent(option, modifiers).option
+        changeValue(
+          applyDelta(
+            value,
+            direction,
+            option,
+            mode === 'raw' ? rawRange : range,
+            modifiers,
+          ),
+        )
       },
-      [changeValue, value, range],
+      [changeValue, value, rawRange, range],
     )
 
     // --- hooks ---
     const wheelRefCallback = useWheel<HTMLDivElement>(
       (event) => {
-        if (!wheel || readonly || event.deltaY == 0) return
+        if (!wheel || inactive || event.deltaY === 0) return
         event.preventDefault()
-        nudge(-Math.sign(event.deltaY), wheel)
+        nudge(-Math.sign(event.deltaY), wheel, event)
       },
       { requireFocus: true },
     )
@@ -256,12 +439,19 @@ export const Root = forwardRef<NumberInputMethods, Props>(
         readonly,
         clampValue,
         range,
+        rawRange,
         keyboard,
         text,
         editing,
         outOfRange,
-        atMin: clampValue && min != undefined && value <= min,
-        atMax: clampValue && max != undefined && value >= max,
+        dragSensitivity,
+        pointerLock,
+        selectOnFocus,
+        unformatOnFocus,
+        keepCaretOnStep,
+        blurOnEnter,
+        atMin: clampValue && min !== undefined && value <= min,
+        atMax: clampValue && max !== undefined && value >= max,
         drag,
         format,
         parse,
@@ -281,11 +471,18 @@ export const Root = forwardRef<NumberInputMethods, Props>(
         readonly,
         clampValue,
         range,
+        rawRange,
         keyboard,
         text,
         editing,
         outOfRange,
         drag,
+        dragSensitivity,
+        pointerLock,
+        selectOnFocus,
+        unformatOnFocus,
+        keepCaretOnStep,
+        blurOnEnter,
         format,
         parse,
         handleDraft,
@@ -298,21 +495,21 @@ export const Root = forwardRef<NumberInputMethods, Props>(
     useImperativeHandle(forwardedRef, () => {
       return {
         focus() {
-          inputRef.current?.focus()
+          if (!disabled) inputRef.current?.focus()
         },
         blur() {
           inputRef.current?.blur()
         },
       }
-    }, [])
+    }, [disabled])
 
     return (
       <NumberInputProvider value={context}>
         <div
           ref={wheelRefCallback}
-          className={clsx('tremolo-number-input', className)}
-          aria-disabled={disabled}
-          aria-readonly={readonly}
+          className={className}
+          data-disabled={disabled ? '' : undefined}
+          data-readonly={readonly ? '' : undefined}
           style={style}
           {...props}
         >
@@ -334,8 +531,8 @@ export const NumberInput = {
   DecrementStepper,
 }
 
-export { useNumberInputContext } from './context'
-export { type NumberInputFieldProps } from './InputField'
-export { type StepperProps } from './Stepper'
-export { type IncrementStepperProps } from './IncrementStepper'
-export { type DecrementStepperProps } from './DecrementStepper'
+export { useNumberInputContext, type NumberInputContextValue } from './context'
+export { type NumberInputInputFieldProps } from './InputField'
+export { type NumberInputStepperProps } from './Stepper'
+export { type NumberInputIncrementStepperProps } from './IncrementStepper'
+export { type NumberInputDecrementStepperProps } from './DecrementStepper'