@tremolo-ui/react 0.6.0 → 0.8.0

package/src/components/Slider/Thumb.tsx

@@ -1,11 +1,9 @@
 import {
-  AriaAttributes,
   ComponentPropsWithoutRef,
-  CSSProperties,
   forwardRef,
-  ReactNode,
   useImperativeHandle,
   useRef,
+  CSSProperties,
 } from 'react'
 
 import { useCheckPlacement } from '../_util/Placement'
@@ -13,6 +11,8 @@ import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
 
 import { useSliderContext } from './context'
 
+import type { CSSVariables } from '../../css-variables'
+
 export interface SliderThumbProps {
   /**
    * Sets `--color`, for the theme to colour the thumb with. The size is not
@@ -21,18 +21,7 @@ export interface SliderThumbProps {
    */
   color?: string
 
-  className?: string
-  style?: CSSProperties
-  /**
-   * Rendered inside the thumb. The thumb is one element either way, so what
-   * is passed here is decoration on top of it rather than a replacement for
-   * it — `className` and `style` are how its own appearance is changed.
-   */
-  children?: ReactNode
-  'aria-label'?: AriaAttributes['aria-label']
-  'aria-labelledby'?: AriaAttributes['aria-labelledby']
-  'aria-describedby'?: AriaAttributes['aria-describedby']
-  'aria-valuetext'?: AriaAttributes['aria-valuetext']
+  style?: CSSProperties & CSSVariables<'color' | 'translate'>
 }
 
 export interface SliderThumbMethods {
@@ -50,6 +39,11 @@ export const Thumb = /* @__PURE__ */ forwardRef<SliderThumbMethods, Props>(
       children,
       className,
       style,
+      // Pulled out of `props` so that they land on the range input rather than
+      // on the thumb: the input is the control, it takes the focus, and a name
+      // on a plain div would be ignored. No declaration in `SliderThumbProps`
+      // is needed for this — they are already on the div attributes it is
+      // merged with, with the same types.
       'aria-label': ariaLabel,
       'aria-labelledby': ariaLabelledby,
       'aria-describedby': ariaDescribedby,

package/src/components/Slider/Track.tsx

@@ -1,18 +1,14 @@
-import {
-  ComponentPropsWithoutRef,
-  CSSProperties,
-  forwardRef,
-  ReactNode,
-} from 'react'
+import { ComponentPropsWithoutRef, CSSProperties, forwardRef } from 'react'
 
-import { xor } from '@tremolo-ui/functions'
+import { cssLength } from '@tremolo-ui/dom'
 
 import { useComposedRefs } from '../../compose-refs'
-import { cssLength } from '../_util/css-length'
 import { Placement } from '../_util/Placement'
 
 import { useSliderContext } from './context'
 
+import type { CSSVariables } from '../../css-variables'
+
 export interface SliderTrackProps {
   /**
    * How long the track is along the axis the slider runs. Sets `--length`;
@@ -27,10 +23,8 @@ export interface SliderTrackProps {
   /** Colour of the rest of the track. Sets `--inactive`. */
   inactive?: string
 
-  className?: string
-  style?: CSSProperties
-  /** `<Slider.Thumb />` goes here. */
-  children?: ReactNode
+  style?: CSSProperties &
+    CSSVariables<'length' | 'thickness' | 'active' | 'inactive' | 'percent'>
 }
 
 type Props = SliderTrackProps &
@@ -65,7 +59,7 @@ export const Track = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
         data-orientation={vertical ? 'vertical' : 'horizontal'}
         // Which end the value grows from. `percent` is already the position on
         // screen, so this only says which side of it is the filled one.
-        data-flipped={xor(vertical, reverse) ? '' : undefined}
+        data-flipped={vertical !== reverse ? '' : undefined}
         style={
           {
             '--active': active,

package/src/components/Slider/index.tsx

@@ -9,27 +9,26 @@ import React, {
   useRef,
 } from 'react'
 
-import type { AxisOptions, XY } from '@tremolo-ui/dom'
 import {
   applyDelta,
-  linearScale,
-  toFixed,
+  arrowKeyDirection,
+  type AxisOptions,
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
   type InputEventOption,
   type ModifierValue,
   selectModifier,
-  xor,
-  type Scale,
-} from '@tremolo-ui/functions'
+  valuePercent,
+  wheelDirection,
+  type XY,
+} from '@tremolo-ui/dom'
+import { linearScale, type Scale } 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 {
-  DEFAULT_DRAG_SENSITIVITY,
-  DEFAULT_KEYBOARD_OPTIONS,
-  DEFAULT_WHEEL_OPTIONS,
-} from '../../input-event'
 
 import { SliderProvider } from './context'
 import { Marks } from './Marks'
@@ -147,8 +146,6 @@ export interface SliderProps {
    * The parts carry `data-readonly` while it is set.
    */
   readonly?: boolean
-  className?: string
-  style?: CSSProperties
   /** Called with the new value when a drag, the wheel or an arrow key moves it. */
   onChange?: (value: number) => void
   /** Called when a drag starts, with the value where the track was pressed. */
@@ -220,18 +217,13 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
     const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
     const inactive = disabled || readonly
 
-    const p = toFixed(scale.normalize(value, min, max) * 100)
-    const rev = toFixed(100 - p)
-    // NOTE
+    // Measured from the left or the top, as CSS places things:
     // normal -> normal (right)
-    // vertical -> rev (up)
-    // reverse -> rev (left)
+    // vertical -> reversed (up)
+    // reverse -> reversed (left)
     // vertical & reverse -> normal (down)
-    const displayReversed = useMemo(
-      () => xor(vertical, reverse),
-      [vertical, reverse],
-    )
-    const percent = displayReversed ? rev : p
+    const displayReversed = vertical !== reverse
+    const percent = valuePercent(value, { min, max, scale }, displayReversed)
 
     // --- internal functions ---
     // The pointer is normalized against the track on both axes; only the one
@@ -246,14 +238,19 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
 
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLDivElement>) => {
-        const key = event.key
-        if (!['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key))
-          return
+        const direction = arrowKeyDirection(event.key)
+        if (direction === null) return
         event.preventDefault()
         if (!keyboard || !onChange || inactive) return
-        let direction = key === 'ArrowRight' || key === 'ArrowUp' ? 1 : -1
-        if (reverse) direction *= -1
-        onChange(applyDelta(value, direction, keyboard, axis, event))
+        onChange(
+          applyDelta(
+            value,
+            reverse ? -direction : direction,
+            keyboard,
+            axis,
+            event,
+          ),
+        )
       },
       [keyboard, onChange, inactive, reverse, value, axis],
     )
@@ -286,16 +283,14 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
 
     const wheelRefCallback = useWheel<HTMLDivElement>((event) => {
       if (!wheel || !onChange || inactive) return
+      // A notch the slider does not read — a sideways scroll on a vertical
+      // slider — is left to the page rather than swallowed.
+      const direction = wheelDirection(event, { horizontal: !vertical })
+      if (direction === null) return
       event.preventDefault()
-      let direction
-      if (!vertical && event.deltaX !== 0) {
-        direction = event.deltaX > 0 ? 1 : -1
-      } else {
-        if (event.deltaY === 0) return
-        direction = event.deltaY > 0 ? -1 : 1
-      }
-      if (reverse) direction *= -1
-      onChange(applyDelta(value, direction, wheel, axis, event))
+      onChange(
+        applyDelta(value, reverse ? -direction : direction, wheel, axis, event),
+      )
     }, WHEEL_OPTIONS)
 
     // Composed once, so React attaches the refs a single time instead of
@@ -401,4 +396,3 @@ export { type SliderThumbMethods, type SliderThumbProps } from './Thumb'
 export { type SliderTrackProps } from './Track'
 export { type SliderMarksProps } from './Marks'
 export { type SliderMarksOptionProps } from './MarksOption'
-export { type MarksOptions } from './type'

package/src/components/XYPad/Area.tsx

@@ -1,61 +1,34 @@
-import {
-  ComponentPropsWithoutRef,
-  CSSProperties,
-  forwardRef,
-  ReactNode,
-} from 'react'
+import { ComponentPropsWithoutRef, CSSProperties, forwardRef } from 'react'
 
 import { useComposedRefs } from '../../compose-refs'
-import { cssLength } from '../_util/css-length'
 import { Placement } from '../_util/Placement'
 
 import { useXYPadContext } from './context'
 
-export interface XYPadAreaProps {
-  /** Sets `--width`; the size the theme gives it stands when omitted. */
-  width?: number | string
-  /** Sets `--height`; the size the theme gives it stands when omitted. */
-  height?: number | string
-  /** Sets `--color`, for the theme to colour the area with. */
-  color?: string
-  className?: string
-  style?: CSSProperties
-  /** `<XYPad.Thumb />` goes here. */
-  children?: ReactNode
-}
+export const Area = /* @__PURE__ */ forwardRef<
+  HTMLDivElement,
+  ComponentPropsWithoutRef<'div'>
+>(function Area({ children, className, style, ...props }, forwardedRef) {
+  const { areaRef } = useXYPadContext()
 
-type Props = XYPadAreaProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadAreaProps>
+  // The area is what the pointer position is normalized against, so the
+  // context ref is composed with any ref the caller passed.
+  const composedRef = useComposedRefs<HTMLDivElement>(forwardedRef, areaRef)
 
-export const Area = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
-  function Area(
-    { width, height, color, children, className, style, ...props },
-    forwardedRef,
-  ) {
-    const { areaRef } = useXYPadContext()
-
-    // The area is what the pointer position is normalized against, so the
-    // context ref is composed with any ref the caller passed.
-    const composedRef = useComposedRefs<HTMLDivElement>(forwardedRef, areaRef)
-
-    return (
-      <div
-        ref={composedRef}
-        className={className}
-        style={
-          {
-            '--color': color,
-            '--width': cssLength(width),
-            '--height': cssLength(height),
-            // The thumb inside is placed against this box.
-            position: 'relative',
-            ...style,
-          } as CSSProperties
-        }
-        {...props}
-      >
-        <Placement name="XYPad.Area">{children}</Placement>
-      </div>
-    )
-  },
-)
+  return (
+    <div
+      ref={composedRef}
+      className={className}
+      style={
+        {
+          // The thumb inside is placed against this box.
+          position: 'relative',
+          ...style,
+        } as CSSProperties
+      }
+      {...props}
+    >
+      <Placement name="XYPad.Area">{children}</Placement>
+    </div>
+  )
+})

package/src/components/XYPad/Thumb.tsx

@@ -1,17 +1,20 @@
 import {
   AriaAttributes,
   ComponentPropsWithoutRef,
-  CSSProperties,
   forwardRef,
-  ReactNode,
   useImperativeHandle,
   useRef,
+  CSSProperties,
 } from 'react'
 
+import { toXY, type XYInput } from '@tremolo-ui/dom'
+
 import { useCheckPlacement } from '../_util/Placement'
 import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
 
-import { toXY, useXYPadContext, type XYInput } from './context'
+import { useXYPadContext } from './context'
+
+import type { CSSVariables } from '../../css-variables'
 
 export interface XYPadThumbProps {
   /**
@@ -21,15 +24,6 @@ export interface XYPadThumbProps {
    */
   color?: string
 
-  className?: string
-  style?: CSSProperties
-  /**
-   * Rendered inside the thumb. The thumb is one element either way, so what
-   * is passed here is decoration on top of it rather than a replacement for
-   * it — `className` and `style` are how its own appearance is changed.
-   */
-  children?: ReactNode
-
   /**
    * The accessible name of each axis, as `[x, y]`. There are two range inputs
    * inside the thumb, so each takes a name of its own; a single string names
@@ -45,6 +39,8 @@ export interface XYPadThumbProps {
    * `[x, y]` or one for both.
    */
   'aria-valuetext'?: XYInput<AriaAttributes['aria-valuetext']>
+
+  style?: CSSProperties & CSSVariables<'color' | 'translate'>
 }
 
 export interface XYPadThumbMethods {

package/src/components/XYPad/context.tsx

@@ -1,12 +1,10 @@
 import { createContext, RefObject, useContext } from 'react'
 
-import { toXY, type XY, type XYInput } from '@tremolo-ui/dom'
+import { type XY } from '@tremolo-ui/dom'
 import type { Scale } from '@tremolo-ui/functions'
 
 import type { XYPadThumbMethods } from './Thumb'
 
-export { toXY, type XY, type XYInput }
-
 export type XYPadContextValue = {
   value: XY<number>
   min: XY<number>

package/src/components/XYPad/index.tsx

@@ -10,30 +10,32 @@ import {
   useRef,
 } from 'react'
 
-import type { AxisOptions } from '@tremolo-ui/dom'
 import {
   applyDelta,
-  linearScale,
-  toFixed,
+  arrowKeyMove,
+  type AxisOptions,
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
   InputEventOption,
   ModifierState,
   type ModifierValue,
   selectModifier,
-  type Scale,
-} from '@tremolo-ui/functions'
+  toXY,
+  valuePercent,
+  wheelMove,
+  type XY,
+  type XYInput,
+} from '@tremolo-ui/dom'
+import { linearScale, type Scale } 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 {
-  DEFAULT_DRAG_SENSITIVITY,
-  DEFAULT_KEYBOARD_OPTIONS,
-  DEFAULT_WHEEL_OPTIONS,
-} from '../../input-event'
 
 import { Area } from './Area'
-import { toXY, XY, XYInput, XYPadProvider } from './context'
+import { XYPadProvider } from './context'
 import { Thumb, XYPadThumbMethods } from './Thumb'
 
 const defaultExternalStyles: XYPadProps['externalStyles'] = {
@@ -229,14 +231,17 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
     const scale = useMemo(() => toXY(_scale), [_scale])
     const reverse = useMemo(() => toXY(_reverse), [_reverse])
 
-    const percent = useMemo((): XY<number> => {
-      const normalized = [0, 1].map((i) =>
-        scale[i].normalize(value[i], min[i], max[i]),
-      )
-      return [0, 1].map((i) =>
-        toFixed((reverse[i] ? 1 - normalized[i] : normalized[i]) * 100),
-      ) as XY<number>
-    }, [value, min, max, scale, reverse])
+    const percent = useMemo(
+      (): XY<number> =>
+        [0, 1].map((i) =>
+          valuePercent(
+            value[i],
+            { min: min[i], max: max[i], scale: scale[i] },
+            reverse[i],
+          ),
+        ) as XY<number>,
+      [value, min, max, scale, reverse],
+    )
 
     // --- internal functions ---
     // `AxisOptions` extends `ValueRange`, so the same pair also describes the
@@ -293,21 +298,15 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
 
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLDivElement>) => {
-        const key = event.key
-        if (!['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key))
-          return
-
         // The key picks the axis, whichever of the two inputs holds the
-        // focus: the pad is one control to the person moving it, and the focus
-        // lands on the x input, so reading the axis off the input would leave
-        // the y axis with no keys at all.
-        const i: 0 | 1 = key === 'ArrowRight' || key === 'ArrowLeft' ? 0 : 1
+        // focus: the focus lands on the x input, so reading the axis off the
+        // input would leave the y axis with no keys at all.
+        const move = arrowKeyMove(event.key)
+        if (!move) return
         event.preventDefault()
         if (!onChange || inactive || !keyboard) return
-        let direction = 1
-        if (key === 'ArrowLeft' || key === 'ArrowUp') direction *= -1
-        if (reverse[i]) direction *= -1
-        onChange(nudge(i, direction, keyboard, event))
+        const { axis: i, direction } = move
+        onChange(nudge(i, reverse[i] ? -direction : direction, keyboard, event))
       },
       [onChange, inactive, keyboard, reverse, nudge],
     )
@@ -339,19 +338,11 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
 
     const wheelRefCallback = useWheel<HTMLDivElement>((event) => {
       if (!onChange || inactive || !wheel) return
-      // Browsers turn shift+wheel into horizontal scrolling: `deltaY` comes
-      // out empty and `deltaX` carries the movement. Reading whichever axis
-      // moved keeps shift working as the x-axis modifier — and picks up a
-      // trackpad's own horizontal gesture, which never had a modifier.
-      const horizontal = event.deltaX !== 0
-      const delta = horizontal ? event.deltaX : event.deltaY
-      if (delta === 0) return
-      const i: 0 | 1 = horizontal || event.shiftKey ? 0 : 1
+      const move = wheelMove(event)
+      if (!move) return
       event.preventDefault()
-      let direction = 1
-      if (delta < 0) direction *= -1
-      if (reverse[i]) direction *= -1
-      onChange(nudge(i, direction, wheel, event))
+      const { axis: i, direction } = move
+      onChange(nudge(i, reverse[i] ? -direction : direction, wheel, event))
     }, WHEEL_OPTIONS)
 
     // Composed once, so React attaches the refs a single time instead of
@@ -446,10 +437,4 @@ export const XYPad = {
 }
 
 export { type XYPadThumbProps, type XYPadThumbMethods } from './Thumb'
-export { type XYPadAreaProps } from './Area'
-export {
-  useXYPadContext,
-  type XYPadContextValue,
-  type XY,
-  type XYInput,
-} from './context'
+export { useXYPadContext, type XYPadContextValue } from './context'

package/src/components/_util/VisuallyHiddenRangeInput.tsx

@@ -1,18 +1,6 @@
-import { ComponentPropsWithoutRef, CSSProperties, forwardRef } from 'react'
+import { ComponentPropsWithoutRef, forwardRef } from 'react'
 
-const hiddenStyle: CSSProperties = {
-  position: 'absolute',
-  width: 1,
-  height: 1,
-  padding: 0,
-  margin: -1,
-  overflow: 'hidden',
-  clip: 'rect(0, 0, 0, 0)',
-  clipPath: 'inset(50%)',
-  whiteSpace: 'nowrap',
-  border: 0,
-  pointerEvents: 'none',
-}
+import { visuallyHiddenStyle } from '@tremolo-ui/dom'
 
 type Props = Omit<ComponentPropsWithoutRef<'input'>, 'type' | 'style'>
 
@@ -20,5 +8,5 @@ export const VisuallyHiddenRangeInput = /* @__PURE__ */ forwardRef<
   HTMLInputElement,
   Props
 >((props, ref) => (
-  <input {...props} ref={ref} type="range" style={hiddenStyle} />
+  <input {...props} ref={ref} type="range" style={visuallyHiddenStyle} />
 ))

package/src/css-variables.ts

@@ -0,0 +1,23 @@
+/**
+ * CSS custom properties, for a `style` object.
+ *
+ * React's `CSSProperties` has no key starting with `--`, so
+ * `style={{ '--color': 'red' }}` is refused as an unknown property even though
+ * the browser takes it. Every part accepts this alongside `CSSProperties`,
+ * which is how a variable the component or a theme reads is set inline.
+ *
+ * `T` names the custom properties the part itself writes or reads, without the
+ * leading `--`, so that an editor can suggest them. Any other `--` name is
+ * still accepted — a theme reads variables of its own, such as the colours of
+ * each kind of key.
+ *
+ * @example
+ * CSSVariables<'thickness' | 'length'>
+ * // { '--thickness'?: string | number, '--length'?: string | number,
+ * //   [name: `--${string}`]: string | number | undefined }
+ */
+export type CSSVariables<T extends string = never> = {
+  [K in T as `--${K}`]?: string | number
+} & {
+  [K in `--${string}`]?: string | number
+}