@tremolo-ui/react 0.4.0 → 0.6.0

package/src/components/XYPad/Area.tsx

@@ -1,42 +1,61 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef, CSSProperties, ReactElement } from 'react'
+import {
+  ComponentPropsWithoutRef,
+  CSSProperties,
+  forwardRef,
+  ReactNode,
+} 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
-  children?: ReactElement
-
-  /** inherit */
-  __thumb?: ReactElement
+  /** `<XYPad.Thumb />` goes here. */
+  children?: ReactNode
 }
 
-export function Area({
-  width = 120,
-  height = 120,
-  color,
-  children,
-  className,
-  style,
-  __thumb,
-  ...props
-}: XYPadAreaProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadAreaProps>) {
-  return (
-    <div
-      className={clsx('tremolo-xy-pad-area', className)}
-      style={{
-        ...{ '--color': color },
-        width: width,
-        height: height,
-        ...style,
-      }}
-      {...props}
-    >
-      {children}
-      {__thumb}
-    </div>
-  )
-}
+type Props = XYPadAreaProps &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadAreaProps>
+
+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>
+    )
+  },
+)

package/src/components/XYPad/Thumb.tsx

@@ -1,5 +1,5 @@
-import clsx from 'clsx'
 import {
+  AriaAttributes,
   ComponentPropsWithoutRef,
   CSSProperties,
   forwardRef,
@@ -8,24 +8,43 @@ import {
   useRef,
 } from 'react'
 
-export interface XYPadThumbProps {
-  size?: number | string
-  width?: number | string
-  height?: number | string
+import { useCheckPlacement } from '../_util/Placement'
+import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
 
-  color?: string
+import { toXY, useXYPadContext, type XYInput } from './context'
 
-  wrapperClassName?: string
-  wrapperStyle?: CSSProperties
+export interface XYPadThumbProps {
+  /**
+   * Sets `--color`, for the theme to colour the thumb with. The size is not
+   * set here but by `--thumb-size` on `XYPad.Root`, so that the root can leave
+   * the matching room around the area.
+   */
+  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
 
-  /** @internal */
-  __disabled?: boolean
-  /** @internal */
-  __readonly?: boolean
-  /** @internal */
-  __css?: CSSProperties
+  /**
+   * 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
+   * them both, which is rarely what you want.
+   */
+  'aria-label'?: XYInput<AriaAttributes['aria-label']>
+  /** The ids of what labels each axis, as `[x, y]` or one for both. */
+  'aria-labelledby'?: XYInput<AriaAttributes['aria-labelledby']>
+  /** The ids of what describes each axis, as `[x, y]` or one for both. */
+  'aria-describedby'?: XYInput<AriaAttributes['aria-describedby']>
+  /**
+   * What the value of each axis means, when the number does not say it, as
+   * `[x, y]` or one for both.
+   */
+  'aria-valuetext'?: XYInput<AriaAttributes['aria-valuetext']>
 }
 
 export interface XYPadThumbMethods {
@@ -36,66 +55,108 @@ export interface XYPadThumbMethods {
 type Props = XYPadThumbProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadThumbProps>
 
-export const Thumb = forwardRef<XYPadThumbMethods, Props>(
-  (
+export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
+  function Thumb(
     {
-      size,
-      width = 22,
-      height = 22,
       color,
       children,
-      wrapperClassName,
-      wrapperStyle,
       className,
       style,
-      __disabled,
-      __readonly,
-      __css,
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledby,
+      'aria-describedby': ariaDescribedby,
+      'aria-valuetext': ariaValuetext,
       ...props
-    }: Props,
-    ref,
-  ) => {
-    const wrapperRef = useRef<HTMLDivElement>(null)
+    },
+    forwardedRef,
+  ) {
+    const xInputRef = useRef<HTMLInputElement>(null)
+    const yInputRef = useRef<HTMLInputElement>(null)
+    const {
+      value,
+      min,
+      max,
+      step,
+      disabled,
+      readonly,
+      onChange,
+      percent,
+      thumbRef,
+    } = useXYPadContext()
+
+    // The thumb is positioned against the area.
+    useCheckPlacement('XYPad.Thumb', 'XYPad.Area')
 
-    useImperativeHandle(ref, () => {
-      return {
-        focus() {
-          wrapperRef.current?.focus()
-        },
-        blur() {
-          wrapperRef.current?.blur()
-        },
-      }
-    }, [])
+    // Per axis, since the thumb holds one input for each.
+    const labels = toXY(ariaLabel)
+    const labelledby = toXY(ariaLabelledby)
+    const describedby = toXY(ariaDescribedby)
+    const valueText = toXY(ariaValuetext)
+
+    const methods = () => ({
+      focus() {
+        if (!disabled) xInputRef.current?.focus()
+      },
+      blur() {
+        xInputRef.current?.blur()
+        yInputRef.current?.blur()
+      },
+    })
+
+    useImperativeHandle(forwardedRef, methods, [disabled])
+    // Root focuses the thumb when a drag starts, wherever the user placed it.
+    useImperativeHandle(thumbRef, methods, [disabled])
 
     return (
       <div
-        className={clsx('tremolo-xy-pad-thumb-wrapper', wrapperClassName)}
+        className={className}
+        data-disabled={disabled ? '' : undefined}
+        data-readonly={readonly ? '' : undefined}
+        {...props}
         style={{
-          ...__css,
-          ...wrapperStyle,
+          ...{ '--color': color },
+          // Not a style but the mechanics of the position below: the thumb is
+          // placed by a percentage of the area, which needs it out of flow and
+          // measured from its own centre.
+          position: 'absolute',
+          translate: 'var(--translate, -50% -50%)',
+          zIndex: 100,
+          ...style,
+          // Where the thumb sits is the component's decision, not a style: a
+          // `left` from the caller would take it off the area, so it is written
+          // after theirs.
+          left: `${percent[0]}%`,
+          top: `${percent[1]}%`,
         }}
-        {...props}
       >
-        {children ? (
-          children
-        ) : (
-          // default thumb
-          <div
-            ref={wrapperRef}
-            className={clsx('tremolo-xy-pad-thumb', className)}
-            // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
-            tabIndex={0}
-            aria-disabled={__disabled}
-            aria-readonly={__readonly}
-            style={{
-              ...{ '--color': color },
-              width: size ?? width,
-              height: size ?? height,
-              ...style,
+        {([0, 1] as const).map((axis) => (
+          <VisuallyHiddenRangeInput
+            key={axis}
+            ref={axis === 0 ? xInputRef : yInputRef}
+            data-axis={axis === 0 ? 'x' : 'y'}
+            value={value[axis]}
+            min={min[axis]}
+            max={max[axis]}
+            step={step[axis]}
+            disabled={disabled}
+            aria-readonly={readonly}
+            aria-orientation={axis === 0 ? 'horizontal' : 'vertical'}
+            aria-label={labels[axis] ?? (axis === 0 ? 'x' : 'y')}
+            aria-labelledby={labelledby[axis]}
+            aria-describedby={describedby[axis]}
+            aria-valuetext={valueText[axis]}
+            onChange={(event) => {
+              if (readonly) {
+                event.currentTarget.value = String(value[axis])
+                return
+              }
+              const next = [...value] as [number, number]
+              next[axis] = event.currentTarget.valueAsNumber
+              onChange?.(next)
             }}
-          ></div>
-        )}
+          />
+        ))}
+        {children}
       </div>
     )
   },

package/src/components/XYPad/context.tsx

@@ -0,0 +1,49 @@
+import { createContext, RefObject, useContext } from 'react'
+
+import { toXY, type XY, type XYInput } 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>
+  max: XY<number>
+  step: XY<number>
+  /** How the value of each axis is distributed across the travel. */
+  scale: XY<Scale>
+  reverse: XY<boolean>
+  disabled: boolean
+  readonly: boolean
+  onChange?: (value: XY<number>) => void
+
+  /**
+   * Position of the thumb, 0-100 per axis, already accounting for `reverse`.
+   */
+  percent: XY<number>
+
+  /** `Area` registers its element here; `Root` normalizes the pointer against it. */
+  areaRef: RefObject<HTMLDivElement | null>
+  /** `Thumb` registers itself here; `Root` focuses it when a drag starts. */
+  thumbRef: RefObject<XYPadThumbMethods | null>
+}
+
+const XYPadContext = /* @__PURE__ */ createContext<XYPadContextValue | null>(
+  null,
+)
+
+export const XYPadProvider = XYPadContext.Provider
+
+/**
+ * Everything here is derived during render, so there is no state to keep in
+ * sync: `value` comes from the props of `Root` and the rest follows from it.
+ */
+export function useXYPadContext(): XYPadContextValue
+export function useXYPadContext<T>(selector: (state: XYPadContextValue) => T): T
+export function useXYPadContext<T>(selector?: (state: XYPadContextValue) => T) {
+  const context = useContext(XYPadContext)
+  if (!context) throw new Error('Missing XYPadContext.Provider in the tree')
+  return selector ? selector(context) : context
+}