`parameter-keyboard`

Internal helper consumed by <PluginParameterKnob> and <PluginParameterSlider> to translate a KeyboardEvent into a clamped next parameter value. The helper is a pure function — no React, no DOM — so it is fully unit-testable without rendering a tree.

Purpose

The <PluginSlot> accessibility requirement mandates an identical keyboard contract on every parameter control: arrow keys for fine / coarse adjustments, PageUp/PageDown for ×10 coarse, Home/End for range endpoints, Enter for type-edit, plus Shift ×10 and Alt ÷10 modifiers. Reimplementing this contract in two component files would double the surface area subject to drift. The shared helper guarantees both primitives interpret the keymap identically.

Features

1 % step base ×1, ×10, ×100 binding factors (from PARAMETER_KEY_BINDINGS).
Shift multiplier ×10, Alt multiplier ÷10.
Clamping to [min, max] on every increment, decrement, and Home/End jump.
Returns the matching KeyBinding so the caller can detect the special Enter action and open a type-edit affordance.

Usage: Basic

import { resolveParameterKeyboardChange } from "./parameter-keyboard.js";

const result = resolveParameterKeyboardChange(
    { key: "ArrowRight", shiftKey: false, altKey: false },
    0,
    -24,
    24
);
// result.handled === true; result.next === 0.48 (1 % of 48)

Usage: Advanced

// Compose with the React keyboard handler in <PluginParameterKnob>:
function onKeyDown(event: React.KeyboardEvent<HTMLDivElement>) {
    const out = resolveParameterKeyboardChange(event, value, min, max);
    if (!out.handled) return;
    event.preventDefault();
    if (out.binding?.action === "enter-value") {
        setEditing(true);
        return;
    }
    onChange(out.next);
}

API Reference

resolveParameterKeyboardChange(event, current, min, max) → ParameterKeyboardResult
- event — { key, shiftKey, altKey }; matches the shape of KeyboardEvent.
- current — current numeric value.
- min / max — declared parameter range.
ParameterKeyboardResult — { handled, next, binding }.

Implementation Notes

The function iterates PARAMETER_KEY_BINDINGS in declaration order. Adding new bindings is purely declarative — the helper picks them up for free.
Home/End deliberately ignore the modifier multipliers; they are endpoint jumps, not stepped moves.
The function never throws; an unrecognised key returns { handled: false, next: current, binding: undefined } so the caller can fall through to other listeners.

2.6 KiB Raw Blame History Unescape Escape

parameter-keyboard