@tremolo-ui/react 0.5.0 → 0.7.0

package/src/components/Knob/ActiveLine.tsx

@@ -1,7 +1,8 @@
-import clsx from 'clsx'
 import { SVGProps } from 'react'
 
-import { arcRadius, pointOnArc, useKnobContext } from './context'
+import { useCheckPlacement } from '../_util/Placement'
+
+import { arcPath, arcRadius, useKnobContext } from './context'
 
 export function ActiveLine({
   stroke = 'currentColor',
@@ -9,17 +10,17 @@ export function ActiveLine({
   className,
   ...props
 }: Omit<SVGProps<SVGPathElement>, 'd'>) {
+  useCheckPlacement('Knob.ActiveLine', 'Knob.SVGRoot')
+
   const r2 = useKnobContext((s) => s.r2)
   const r3 = useKnobContext((s) => s.r3)
 
   const radius = arcRadius(strokeWidth)
-  const start = pointOnArc(r2, radius)
-  const end = pointOnArc(r3, radius)
 
   return (
     <path
-      className={clsx('tremolo-knob-active-line', className)}
-      d={`M ${start.x} ${start.y} A ${radius} ${radius} -135 ${r3 - r2 > 180 ? 1 : 0} 1 ${end.x} ${end.y}`}
+      className={className}
+      d={arcPath(r2, r3, radius)}
       fill="none"
       stroke={stroke}
       strokeWidth={strokeWidth}

package/src/components/Knob/InactiveLine.tsx

@@ -1,7 +1,8 @@
-import clsx from 'clsx'
 import { SVGProps } from 'react'
 
-import { arcRadius, pointOnArc, useKnobContext } from './context'
+import { useCheckPlacement } from '../_util/Placement'
+
+import { arcPath, arcRadius, useKnobContext } from './context'
 
 export function InactiveLine({
   stroke = 'currentColor',
@@ -9,6 +10,8 @@ export function InactiveLine({
   className,
   ...props
 }: Omit<SVGProps<SVGPathElement>, 'd'>) {
+  useCheckPlacement('Knob.InactiveLine', 'Knob.SVGRoot')
+
   const min = useKnobContext((s) => s.min)
   const max = useKnobContext((s) => s.max)
   const startValue = useKnobContext((s) => s.startValue)
@@ -19,17 +22,13 @@ export function InactiveLine({
   const r4 = useKnobContext((s) => s.r4)
 
   const radius = arcRadius(strokeWidth)
-  const p1 = pointOnArc(r1, radius)
-  const p2 = pointOnArc(r2, radius)
-  const p3 = pointOnArc(r3, radius)
-  const p4 = pointOnArc(r4, radius)
 
   return (
     <>
       {startValue > min && (
         <path
-          className={clsx('tremolo-knob-inactive-line', className)}
-          d={`M ${p1.x} ${p1.y} A ${radius} ${radius} -135 ${r2 - r1 > 180 ? 1 : 0} 1 ${p2.x} ${p2.y}`}
+          className={className}
+          d={arcPath(r1, r2, radius)}
           fill="none"
           stroke={stroke}
           strokeWidth={strokeWidth}
@@ -38,8 +37,8 @@ export function InactiveLine({
       )}
       {startValue < max && (
         <path
-          className={clsx('tremolo-knob-inactive-line', className)}
-          d={`M ${p3.x} ${p3.y} A ${radius} ${radius} -135 ${r4 - r3 > 180 ? 1 : 0} 1 ${p4.x} ${p4.y}`}
+          className={className}
+          d={arcPath(r3, r4, radius)}
           fill="none"
           stroke={stroke}
           strokeWidth={strokeWidth}

package/src/components/Knob/SVGRoot.tsx

@@ -1,8 +1,10 @@
 import { ReactNode, SVGProps } from 'react'
 
+import { Placement } from '../_util/Placement'
+
 import { viewBoxSize } from './context'
 
-export interface SVGRootProps {
+export interface KnobSVGRootProps {
   /**
    * `<Knob.InactiveLine />`, `<Knob.ActiveLine />` and `<Knob.Thumb />` go
    * here, in the order you want them painted.
@@ -14,7 +16,7 @@ export function SVGRoot({
   children,
   style,
   ...props
-}: SVGRootProps & Omit<SVGProps<SVGSVGElement>, keyof SVGRootProps>) {
+}: KnobSVGRootProps & Omit<SVGProps<SVGSVGElement>, keyof KnobSVGRootProps>) {
   return (
     <svg
       viewBox={`0 0 ${viewBoxSize} ${viewBoxSize}`}
@@ -24,7 +26,7 @@ export function SVGRoot({
       }}
       {...props}
     >
-      {children}
+      <Placement name="Knob.SVGRoot">{children}</Placement>
     </svg>
   )
 }

package/src/components/Knob/Thumb.tsx

@@ -1,24 +1,44 @@
-import clsx from 'clsx'
 import { SVGProps } from 'react'
 
 import { clamp } from '@tremolo-ui/functions'
 
+import { useCheckPlacement } from '../_util/Placement'
+
 import { useKnobContext, viewBoxSize } from './context'
 
-interface Props {
-  /** color */
+export interface KnobThumbProps {
+  /**
+   * Fill colour of the circle.
+   * @default 'currentColor'
+   */
   thumb?: string
-  /** color */
+  /**
+   * Colour of the line that points at the value.
+   * @default 'currentColor'
+   */
   thumbLine?: string
-  /** percent (0-100) */
+  /**
+   * Diameter of the circle, as a percentage of the knob.
+   * @default 84
+   */
   thumbSize?: number
-  /** percent (0-100) */
+  /**
+   * Thickness of the line, as a percentage of the knob.
+   * @default 6
+   */
   thumbLineWeight?: number
-  /** percent (0-100) */
+  /**
+   * How far down the line reaches, as a percentage of the knob from its top.
+   * The line starts at the edge of the circle.
+   * @default 35
+   */
   thumbLineLength?: number
 
+  /**
+   * Classes for what the thumb draws inside itself: `thumbLine` is the line
+   * that points at the value.
+   */
   classes?: {
-    thumb?: string
     thumbLine?: string
   }
 }
@@ -34,17 +54,19 @@ export function Thumb({
   classes,
 
   ...props
-}: Props & Omit<SVGProps<SVGSVGElement>, 'd' | keyof Props>) {
+}: KnobThumbProps & Omit<SVGProps<SVGSVGElement>, 'd' | keyof KnobThumbProps>) {
+  useCheckPlacement('Knob.Thumb', 'Knob.SVGRoot')
+
   const angleRange = useKnobContext((s) => s.angleRange)
 
   const p = useKnobContext((s) => s.p)
   const r1 = useKnobContext((s) => s.r1)
 
   return (
-    <svg className={clsx('tremolo-knob-thumb', classes?.thumb)} {...props}>
+    <svg className={className} {...props}>
       <circle cx="50%" cy="50%" r={`${thumbSize / 2}%`} fill={thumb} />
       <line
-        className={clsx('tremolo-knob-thumb-line', classes?.thumbLine)}
+        className={classes?.thumbLine}
         x1="50%"
         y1={`${(viewBoxSize - clamp(thumbSize, 0, 100)) / 2}%`}
         x2="50%"

package/src/components/Knob/context.tsx

@@ -51,6 +51,22 @@ export function arcRadius(strokeWidth: number | string | undefined) {
   return Number.isFinite(width) ? center - width / 2 : center
 }
 
+/** Build an SVG path for an arc, splitting full turns into drawable segments. */
+export function arcPath(startAngle: number, endAngle: number, radius: number) {
+  const start = pointOnArc(startAngle, radius)
+  const sweep = endAngle - startAngle
+  const segmentCount = Math.max(1, Math.ceil(Math.abs(sweep) / 180))
+  const segmentSweep = sweep / segmentCount
+  let path = `M ${start.x} ${start.y}`
+
+  for (let i = 1; i <= segmentCount; i += 1) {
+    const end = pointOnArc(startAngle + segmentSweep * i, radius)
+    path += ` A ${radius} ${radius} 0 0 ${segmentSweep >= 0 ? 1 : 0} ${end.x} ${end.y}`
+  }
+
+  return path
+}
+
 /** 設定から描画に必要な角度を導出する。レンダー中に呼ぶ。 */
 export function calcAngles({
   value,
@@ -71,7 +87,7 @@ export function calcAngles({
   return { p, r1, r2, r3, r4 }
 }
 
-const KnobContext = createContext<KnobContextValue | null>(null)
+const KnobContext = /* @__PURE__ */ createContext<KnobContextValue | null>(null)
 
 export const KnobProvider = KnobContext.Provider
 

package/src/components/Knob/index.tsx

@@ -1,6 +1,6 @@
-import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
+  CSSProperties,
   forwardRef,
   ReactNode,
   useCallback,
@@ -9,19 +9,26 @@ import {
   useRef,
 } from 'react'
 
-import type { AxisOptions, XY } from '@tremolo-ui/dom'
 import {
   applyDelta,
-  InputEventOption,
-  linearScale,
-  type Scale,
-  type ValueRange,
-} from '@tremolo-ui/functions'
+  type AxisOptions,
+  type InputEventOption,
+  type ModifierValue,
+  selectModifier,
+  type XY,
+} from '@tremolo-ui/dom'
+import { linearScale, type Scale, type ValueRange } from '@tremolo-ui/functions'
 
+import { useComposedRefs } from '../../compose-refs'
+import { useCheckSteps } from '../../hooks/_internal/useCheckSteps'
 import { useDragValue } from '../../hooks/useDragValue'
 import { useWheel } from '../../hooks/useWheel'
-import { addUserSelectNone, Cursor, removeUserSelectNone } from '../_util'
-import { useComposedRefs } from '../_util/composeRefs'
+import {
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
+} from '../../input-event'
+import { cssLength } from '../_util/css-length'
 
 import { ActiveLine } from './ActiveLine'
 import { calcAngles, KnobProvider } from './context'
@@ -29,18 +36,26 @@ import { InactiveLine } from './InactiveLine'
 import { SVGRoot } from './SVGRoot'
 import { Thumb } from './Thumb'
 
+import type { CSSVariables } from '../../css-variables'
+
 const defaultExternalStyles: KnobProps['externalStyles'] = {
-  userSelectNone: true,
   cursor: 'grabbing',
 }
 
 export interface KnobProps {
-  // required
+  /** The current value. The knob shows only this, so update it from `onChange`. */
   value: number
+  /** The value with the knob turned all the way down. */
   min: number
+  /** The value with the knob turned all the way up. */
   max: number
 
-  // optional
+  /**
+   * Granularity of the value. A drag, the wheel and the arrow keys snap it to
+   * multiples of `step`.
+   *
+   * @default 1
+   */
   step?: number
   /**
    * How the value is distributed across the travel.
@@ -53,52 +68,123 @@ export interface KnobProps {
    */
   scale?: Scale
   /**
-   * value set when double-clicking
-   * restriction: enableDoubleClickDefault = true
+   * The value a double click restores, while `enableDoubleClickDefault` is on.
    * @default min
-   * @see enableDoubleClickDefault
    */
   defaultValue?: number
 
   /**
-   * Value to be used as the starting point of the line when drawing.
+   * Where the active arc starts. Put it at the centre of a bipolar control,
+   * such as a pan knob, so that the arc grows from there either way.
    * @default min
    */
   startValue?: number
 
-  /** width and height */
   /**
-   * Width and height of the knob.
-   * Defaults to the `--knob-size` CSS variable (50px).
+   * Width and height of the knob. Sets `--knob-size`; the size the theme
+   * gives it stands when this is omitted.
    */
   size?: number | string
 
   /**
-   * Global style to apply when dragged
-   * @default defaultExternalStyles
+   * The cursor to show while dragging. It is set on the dragged element, so it
+   * stays while the pointer is outside the knob.
+   *
+   * @default { cursor: 'grabbing' }
    */
   externalStyles?: {
-    userSelectNone?: boolean
-    cursor?: Cursor
+    cursor?: CSSProperties['cursor']
   }
   /**
-   * wheel control option
-   * 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 knob 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 a drag moves the value, per modifier key.
+   *
+   * `1` is the normal travel of 100px for the whole range; `0.1` makes the
+   * same movement cover a tenth of it. Shift is bound to `0.1` by default, to
+   * match what it does on the arrow keys.
+   *
+   * Pressing or releasing the key mid-drag does not disturb the value: the
+   * travel so far is kept and the new sensitivity applies from there. It takes
+   * effect on the next movement, since a key on its own produces no pointer
+   * event.
+   *
+   * @default { default: 1, shift: 0.1 }
+   */
+  dragSensitivity?: ModifierValue<number>
+
+  /**
+   * Hide the cursor while dragging and read the pointer movement directly,
+   * rather than letting it wander off across the screen.
+   *
+   * A knob does not care where the pointer is, only how far it moved, and
+   * letting it wander costs twice: the cursor ends up far from the knob it is
+   * holding, and **the drag stops at the edge of the screen**, where the
+   * operating system pins the pointer and the coordinates stop changing. A
+   * `dragSensitivity` below 1 reaches that edge quickly.
+   *
+   * Off by default because it is not free: the browser shows its own notice,
+   * Esc takes the lock back, and the request needs a user gesture and can be
+   * refused. A refused request is not an error — the drag simply carries on as
+   * an ordinary one.
+   *
+   * @default false
+   */
+  pointerLock?: boolean
+
+  /**
+   * 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] }
    */
-  wheel?: InputEventOption | null
+  keyboard?: ModifierValue<InputEventOption> | null
   /**
-   * keyboard control option
-   * If null, no event will be triggered
+   * Restore `defaultValue` on a double click.
+   * @default true
    */
-  keyboard?: InputEventOption | null
   enableDoubleClickDefault?: boolean
 
+  /**
+   * Make the knob unchangeable and remove it from the tab order.
+   * The parts carry `data-disabled` while it is set.
+   */
   disabled?: boolean
+  /**
+   * Make the knob unchangeable while leaving it focusable.
+   * The parts carry `data-readonly` while it is set.
+   */
   readonly?: boolean
 
-  /** angle range [degree] */
+  /**
+   * How far the knob turns from `min` to `max`, in degrees, centred on the
+   * top.
+   * @default 270
+   */
   angleRange?: number
 
+  /**
+   * Called with the new value when a drag, the wheel, an arrow key or a double
+   * click moves it.
+   */
   onChange?: (value: number) => void
 
   /**
@@ -115,6 +201,8 @@ export interface KnobProps {
    * </Knob.Root>
    */
   children: ReactNode
+
+  style?: CSSProperties & CSSVariables<'knob-size'>
 }
 
 export interface KnobMethods {
@@ -130,7 +218,7 @@ type Props = KnobProps & Omit<ComponentPropsWithoutRef<'div'>, keyof KnobProps>
  */
 const WHEEL_OPTIONS = { requireFocus: true }
 
-export const Root = forwardRef<KnobMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
   (
     {
       value,
@@ -142,8 +230,10 @@ export const Root = forwardRef<KnobMethods, Props>(
       startValue = min,
       size,
       externalStyles: _externalStyles,
-      wheel = ['raw', 1],
-      keyboard = ['raw', 1],
+      wheel = DEFAULT_WHEEL_OPTIONS,
+      keyboard = DEFAULT_KEYBOARD_OPTIONS,
+      dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
+      pointerLock = false,
       enableDoubleClickDefault = true,
       disabled = false,
       readonly = false,
@@ -162,6 +252,7 @@ export const Root = forwardRef<KnobMethods, Props>(
     const elmRef = useRef<HTMLElement | SVGElement>(null)
 
     const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
+    const inactive = disabled || readonly
 
     // --- internal functions ---
     const range: ValueRange = useMemo(
@@ -169,17 +260,19 @@ export const Root = forwardRef<KnobMethods, Props>(
       [min, max, step, scale],
     )
 
+    useCheckSteps({ component: 'Knob', range, keyboard, wheel })
+
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLOrSVGElement>) => {
-        if (!keyboard || !onChange || readonly) return
+        if (!keyboard || !onChange || inactive) return
         const key = event.key
         if (['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key)) {
           event.preventDefault()
-          const direction = key == 'ArrowRight' || key == 'ArrowUp' ? 1 : -1
-          onChange(applyDelta(value, direction, keyboard, range))
+          const direction = key === 'ArrowRight' || key === 'ArrowUp' ? 1 : -1
+          onChange(applyDelta(value, direction, keyboard, range, event))
         }
       },
-      [keyboard, onChange, readonly, value, range],
+      [keyboard, onChange, inactive, value, range],
     )
 
     // --- hooks ---
@@ -197,25 +290,23 @@ export const Root = forwardRef<KnobMethods, Props>(
     >({
       axis,
       getValue: () => [value, value],
+      sensitivity: (state) =>
+        selectModifier(dragSensitivity, state.event).value,
       threshold: 1,
-      cursor: readonly ? undefined : externalStyles.cursor,
+      cursor: inactive ? undefined : externalStyles.cursor,
+      pointerLock: inactive ? false : pointerLock,
+      shouldStart: () => !inactive,
       onChange: (v) => {
-        if (readonly) return
+        if (inactive) return
         onChange?.(v[1])
       },
-      onDragStart: () => {
-        if (externalStyles.userSelectNone) addUserSelectNone()
-      },
-      onDragEnd: () => {
-        if (externalStyles.userSelectNone) removeUserSelectNone()
-      },
     })
 
     const wheelRefCallback = useWheel<HTMLElement>((event) => {
-      if (!wheel || readonly) return
+      if (!wheel || inactive) return
       event.preventDefault()
-      if (!onChange || event.deltaY == 0) return
-      onChange(applyDelta(value, -Math.sign(event.deltaY), wheel, range))
+      if (!onChange || event.deltaY === 0) return
+      onChange(applyDelta(value, -Math.sign(event.deltaY), wheel, range, event))
     }, WHEEL_OPTIONS)
 
     // Composed once, so React attaches the refs a single time instead of
@@ -234,35 +325,38 @@ export const Root = forwardRef<KnobMethods, Props>(
     useImperativeHandle(forwardedRef, () => {
       return {
         focus() {
-          elmRef.current?.focus()
+          if (!disabled) elmRef.current?.focus()
         },
         blur() {
           elmRef.current?.blur()
         },
       }
-    }, [])
+    }, [disabled])
 
     return (
       <KnobProvider value={context}>
         <div
           ref={rootRefCallback}
-          className={clsx('tremolo-knob', className)}
-          tabIndex={0}
+          className={className}
+          tabIndex={disabled ? -1 : 0}
           role="slider"
           aria-valuenow={value}
           aria-valuemin={min}
           aria-valuemax={max}
           aria-disabled={disabled}
           aria-readonly={readonly}
-          data-dragging={dragging}
-          style={{
-            width: size,
-            height: size,
-            ...style,
-          }}
+          data-disabled={disabled ? '' : undefined}
+          data-readonly={readonly ? '' : undefined}
+          data-dragging={dragging ? '' : undefined}
+          style={
+            {
+              '--knob-size': cssLength(size),
+              ...style,
+            } as CSSProperties
+          }
           onPointerDown={onPointerDown}
           onDoubleClick={(event) => {
-            if (enableDoubleClickDefault && onChange) {
+            if (!inactive && enableDoubleClickDefault && onChange) {
               onChange(defaultValue)
             }
             onDoubleClick?.(event)
@@ -291,4 +385,6 @@ export const Knob = {
   Thumb,
 }
 
-export { useKnobContext } from './context'
+export { useKnobContext, type KnobContextValue } from './context'
+export { type KnobSVGRootProps } from './SVGRoot'
+export { type KnobThumbProps } from './Thumb'

package/src/components/NumberInput/DecrementStepper.tsx

@@ -1,18 +1,11 @@
-import { ComponentPropsWithoutRef } from 'react'
-
 import {
   StepperArrow,
   StepperButton,
-  StepperButtonProps,
-} from './stepperButton'
-
-export type DecrementStepperProps = StepperButtonProps
+  type StepperButtonProps,
+} from './StepperButton'
 
 /** Lowers the value by one `step`, repeating while held. */
-export function DecrementStepper(
-  props: DecrementStepperProps &
-    Omit<ComponentPropsWithoutRef<'div'>, keyof DecrementStepperProps>,
-) {
+export function DecrementStepper(props: StepperButtonProps) {
   return (
     <StepperButton
       direction={-1}

package/src/components/NumberInput/IncrementStepper.tsx

@@ -1,18 +1,11 @@
-import { ComponentPropsWithoutRef } from 'react'
-
 import {
   StepperArrow,
   StepperButton,
-  StepperButtonProps,
-} from './stepperButton'
-
-export type IncrementStepperProps = StepperButtonProps
+  type StepperButtonProps,
+} from './StepperButton'
 
 /** Raises the value by one `step`, repeating while held. */
-export function IncrementStepper(
-  props: IncrementStepperProps &
-    Omit<ComponentPropsWithoutRef<'div'>, keyof IncrementStepperProps>,
-) {
+export function IncrementStepper(props: StepperButtonProps) {
   return (
     <StepperButton
       direction={1}