@tremolo-ui/react 0.4.0 → 0.6.0

package/src/components/NumberInput/index.tsx

@@ -1,90 +1,247 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef, forwardRef, ReactNode } from 'react'
+import {
+  ComponentPropsWithoutRef,
+  CSSProperties,
+  forwardRef,
+  ReactNode,
+  useCallback,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 
-import { InputEventOption } from '@tremolo-ui/functions'
+import {
+  applyDelta,
+  InputEventOption,
+  ModifierState,
+  type ModifierValue,
+  linearScale,
+  selectInputEvent,
+  type Scale,
+  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'
 import { IncrementStepper } from './IncrementStepper'
-import { InternalInput } from './InternalInput'
+import { InputField } from './InputField'
 import { Stepper } from './Stepper'
-import { Units } from './type'
-
-/*
-TODO
-- numberMode: focusが当たった時だけ、parse + type="number"にする
-- skew
-*/
 
 export interface NumberInputProps {
-  value: number | string
+  /**
+   * The value. What the input shows is `format(value)`, except while the user
+   * is typing, when their own text stands until it is committed.
+   */
+  value: number
 
   /**
-   * Number.MIN_SAFE_INTEGER
+   * 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
   /**
-   * Number.MAX_SAFE_INTEGER
+   * 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
+   * `'normalized'` wheel / keyboard nudge.
+   *
+   * @default linearScale
+   */
+  scale?: Scale
 
   /**
+   * 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} />
+   */
+  format?: (value: number) => string
+  /**
+   * Read a value back out of the text. Has to undo `format`.
+   *
+   * Text with no number in it reads as `NaN`, which leaves the value alone.
    */
-  units?: string | Units
+  parse?: (text: string) => number
 
   /**
-   * Digits for rounding numbers.
-   * @example
-   * with:
-   * units={[['Hz', 1], ['kHz', 1000]]}
-   * digit={3}
-   * results:
-   * value=100 -> 100Hz, value=1600 -> 1.60Hz
+   * Keep the value within `min` and `max` when it is committed or stepped.
+   * Typing is never clamped, so that a value can be entered digit by digit.
+   * @default true
    */
-  digit?: number
+  clampValue?: boolean
 
-  readonly?: boolean
+  /**
+   * 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?: ModifierValue<InputEventOption> | null
+  /**
+   * 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?: ModifierValue<InputEventOption> | null
+  /**
+   * Pixels of vertical drag on `Stepper` that move the value by one `step`.
+   * `null` turns the drag off.
+   * @default 1
+   */
+  drag?: number | null
 
-  variant?: 'outline' | 'filled' | 'flushed' | 'unstyled'
+  /**
+   * 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>
 
-  selectWithFocus?: 'all' | 'number' | 'none'
-  blurOnEnter?: boolean
-  keepWithinRange?: boolean
-  clampValueOnBlur?: boolean
+  /**
+   * 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
 
   /**
-   * wheel control option
-   * If null, no event will be triggered
+   * 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'
    */
-  wheel?: InputEventOption | null
+  selectOnFocus?: 'all' | 'number' | 'none'
   /**
-   * keyboard control option
-   * If null, no event will be triggered
+   * 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
    */
-  keyboard?: InputEventOption | null
-
-  activeColor?: string
+  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
 
-  wrapperClassName?: string
+  /**
+   * 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.
+   * The parts carry `data-readonly` while it is set.
+   */
+  readonly?: boolean
 
-  onChange?: (value: number, text: string) => void
-  onFocus?: (
-    value: number,
-    text: string,
-    event: React.FocusEvent<HTMLInputElement, Element>,
-  ) => void
-  onBlur?: (
-    value: number,
-    text: string,
-    event: React.FocusEvent<HTMLInputElement, Element>,
-  ) => void
+  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
 
-  children?: ReactNode
+  /**
+   * The input renders exactly what you compose here; there is no default
+   * markup to fall back to.
+   *
+   * @example
+   * <NumberInput.Root value={value} min={0} max={100} onChange={setValue}>
+   *   <NumberInput.InputField />
+   *   <NumberInput.Stepper>
+   *     <NumberInput.IncrementStepper />
+   *     <NumberInput.DecrementStepper />
+   *   </NumberInput.Stepper>
+   * </NumberInput.Root>
+   */
+  children: ReactNode
 }
 
 export interface NumberInputMethods {
@@ -92,78 +249,270 @@ 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<'input'>, keyof NumberInputProps | 'type'>
+  Omit<ComponentPropsWithoutRef<'div'>, keyof NumberInputProps>
 
-const Root = forwardRef<NumberInputMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
   (
     {
       value,
       min,
       max,
       step = 1,
-      units,
-      readonly = false,
-      disabled = false,
-      digit,
-      variant = 'outline',
-      selectWithFocus = 'none',
+      scale = linearScale,
+      format: formatProp,
+      parse: parseProp,
+      clampValue = true,
+      wheel = DEFAULT_WHEEL_OPTIONS,
+      keyboard = DEFAULT_KEYBOARD_OPTIONS,
+      drag = 1,
+      dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
+      pointerLock = false,
+      selectOnFocus = 'none',
+      unformatOnFocus = false,
+      keepCaretOnStep = false,
       blurOnEnter = true,
-      keepWithinRange = true,
-      clampValueOnBlur = true,
-      wheel = ['raw', 1],
-      keyboard = ['raw', 1],
-      activeColor,
-      wrapperClassName,
+      disabled = false,
+      readonly = false,
       className,
+      style,
       onChange,
-      onFocus,
-      onBlur,
       children,
       ...props
     }: Props,
     forwardedRef,
   ) => {
-    const colors: Record<string, string | undefined> = {
-      '--active-color': activeColor,
-    }
+    // --- state and ref ---
+    const inputRef = useRef<HTMLInputElement>(null)
+    /**
+     * The text being typed. The only state here: it is not a copy of `value`,
+     * 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 = formatProp ?? defaultFormat
+    const parse = parseProp ?? defaultParse
+
+    // 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,
+        max: (clampValue ? max : undefined) ?? Number.MAX_SAFE_INTEGER,
+        step,
+        scale,
+      }),
+      [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 outOfRange =
+      !editing &&
+      ((min !== undefined && value < min) || (max !== undefined && value > max))
+
+    // --- internal functions ---
+    const handleDraft = useCallback(
+      (next: string) => {
+        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)
+      },
+      [inactive, parse, onChange],
+    )
+
+    const changeValue = useCallback(
+      (next: number) => {
+        if (inactive) return
+        setDraft(null)
+        if (next !== value) onChange?.(next)
+      },
+      [inactive, value, onChange],
+    )
+
+    const commitDraft = useCallback(() => {
+      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: ModifierValue<InputEventOption>,
+        modifiers?: ModifierState,
+      ) => {
+        const [mode] = selectInputEvent(option, modifiers).option
+        changeValue(
+          applyDelta(
+            value,
+            direction,
+            option,
+            mode === 'raw' ? rawRange : range,
+            modifiers,
+          ),
+        )
+      },
+      [changeValue, value, rawRange, range],
+    )
+
+    // --- hooks ---
+    const wheelRefCallback = useWheel<HTMLDivElement>(
+      (event) => {
+        if (!wheel || inactive || event.deltaY === 0) return
+        event.preventDefault()
+        nudge(-Math.sign(event.deltaY), wheel, event)
+      },
+      { requireFocus: true },
+    )
+
+    const context = useMemo(
+      () => ({
+        value,
+        min,
+        max,
+        step,
+        scale,
+        disabled,
+        readonly,
+        clampValue,
+        range,
+        rawRange,
+        keyboard,
+        text,
+        editing,
+        outOfRange,
+        dragSensitivity,
+        pointerLock,
+        selectOnFocus,
+        unformatOnFocus,
+        keepCaretOnStep,
+        blurOnEnter,
+        atMin: clampValue && min !== undefined && value <= min,
+        atMax: clampValue && max !== undefined && value >= max,
+        drag,
+        format,
+        parse,
+        setDraft: handleDraft,
+        commitDraft,
+        changeValue,
+        nudge,
+        inputRef,
+      }),
+      [
+        value,
+        min,
+        max,
+        step,
+        scale,
+        disabled,
+        readonly,
+        clampValue,
+        range,
+        rawRange,
+        keyboard,
+        text,
+        editing,
+        outOfRange,
+        drag,
+        dragSensitivity,
+        pointerLock,
+        selectOnFocus,
+        unformatOnFocus,
+        keepCaretOnStep,
+        blurOnEnter,
+        format,
+        parse,
+        handleDraft,
+        commitDraft,
+        changeValue,
+        nudge,
+      ],
+    )
+
+    useImperativeHandle(forwardedRef, () => {
+      return {
+        focus() {
+          if (!disabled) inputRef.current?.focus()
+        },
+        blur() {
+          inputRef.current?.blur()
+        },
+      }
+    }, [disabled])
+
     return (
-      <NumberInputProvider
-        value={String(value)}
-        min={min}
-        max={max}
-        step={step}
-        units={units}
-        digit={digit}
-        readonly={readonly}
-        keepWithinRange={keepWithinRange}
-        onChange={onChange}
-      >
+      <NumberInputProvider value={context}>
         <div
-          className={clsx('tremolo-number-input-wrapper', wrapperClassName)}
-          // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
-          tabIndex={0}
-          style={{
-            ...colors,
-          }}
-          data-stepper={!!children}
-          data-variant={variant}
+          ref={wheelRefCallback}
+          className={className}
+          data-disabled={disabled ? '' : undefined}
+          data-readonly={readonly ? '' : undefined}
+          style={style}
+          {...props}
         >
-          <InternalInput
-            ref={forwardedRef}
-            readonly={readonly}
-            disabled={disabled}
-            selectWithFocus={selectWithFocus}
-            blurOnEnter={blurOnEnter}
-            clampValueOnBlur={clampValueOnBlur}
-            wheel={wheel}
-            keyboard={keyboard}
-            className={className}
-            onChange={onChange}
-            onFocus={onFocus}
-            onBlur={onBlur}
-            {...props}
-          />
           {children}
         </div>
       </NumberInputProvider>
@@ -176,12 +525,14 @@ const Root = forwardRef<NumberInputMethods, Props>(
  */
 export const NumberInput = {
   Root,
+  InputField,
   Stepper,
   IncrementStepper,
   DecrementStepper,
 }
 
-export { type StepperProps } from './Stepper'
-export { type IncrementStepperProps } from './IncrementStepper'
-export { type DecrementStepperProps } from './DecrementStepper'
-export { type Units } from './type'
+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'