@tremolo-ui/react 0.6.0 → 0.7.0

package/src/components/PointsEditor/Container.tsx

@@ -1,4 +1,4 @@
-import { ComponentPropsWithoutRef, forwardRef, ReactNode } from 'react'
+import { ComponentPropsWithoutRef, forwardRef } from 'react'
 
 import { useComposedRefs } from '../../compose-refs'
 import { useDragValue } from '../../hooks/useDragValue'
@@ -8,13 +8,7 @@ import { Placement } from '../_util/Placement'
 import { usePointsEditorContext } from './context'
 import { AXIS } from './Point'
 
-export interface PointsEditorContainerProps {
-  /** `<PointsEditor.Point />` goes here. */
-  children?: ReactNode
-}
-
-type Props = PointsEditorContainerProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorContainerProps>
+type Props = ComponentPropsWithoutRef<'div'>
 
 export const Container = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   function Container({ children, className, style, ...props }, forwardedRef) {

package/src/components/PointsEditor/Point.tsx

@@ -1,7 +1,6 @@
 import {
   ComponentPropsWithoutRef,
   CSSProperties,
-  ReactNode,
   useCallback,
   useEffect,
   useId,
@@ -11,12 +10,12 @@ import {
 
 import {
   applyDelta,
-  clamp,
   type InputEventOption,
   type ModifierState,
   type ModifierValue,
   selectModifier,
-} from '@tremolo-ui/functions'
+} from '@tremolo-ui/dom'
+import { clamp } from '@tremolo-ui/functions'
 
 import { useComposedRefs } from '../../compose-refs'
 import { useDragValue } from '../../hooks/useDragValue'
@@ -26,6 +25,8 @@ import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
 
 import { type PointRegistration, usePointsEditorContext } from './context'
 
+import type { CSSVariables } from '../../css-variables'
+
 export type PointBaseType = { x: number; y: number }
 
 export function clampPoint(
@@ -45,8 +46,6 @@ export interface PointsEditorPointProps<T extends PointBaseType> {
    * growing downwards.
    */
   value: T
-  /** Drawn inside the point: the theme's own dot stands when it is left out. */
-  children?: ReactNode
   /**
    * How the selection refers to this point. One is generated when it is left
    * out, which lasts as long as the point is mounted — give your own if the
@@ -94,6 +93,9 @@ export interface PointsEditorPointProps<T extends PointBaseType> {
   onDragStart?: (value: PointBaseType) => void
   /** Called when that drag ends, with where the point is. */
   onDragEnd?: (value: PointBaseType) => void
+
+  style?: CSSProperties &
+    CSSVariables<'width' | 'height' | 'color' | 'translate'>
 }
 
 /**

package/src/components/PointsEditor/SelectionBox.tsx

@@ -1,14 +1,9 @@
-import { ComponentPropsWithoutRef, CSSProperties, ReactNode } from 'react'
+import { ComponentPropsWithoutRef, CSSProperties } from 'react'
 
 import { useCheckPlacement } from '../_util/Placement'
 
 import { usePointsEditorContext } from './context'
 
-export interface PointsEditorSelectionBoxProps {
-  /** Drawn inside the box, which is only there while a drag is running. */
-  children?: ReactNode
-}
-
 /**
  * The box a drag on empty space draws, and what it covers is selected.
  *
@@ -20,8 +15,7 @@ export function SelectionBox({
   className,
   style,
   ...props
-}: PointsEditorSelectionBoxProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorSelectionBoxProps>) {
+}: ComponentPropsWithoutRef<'div'>) {
   useCheckPlacement('PointsEditor.SelectionBox', 'PointsEditor.Container')
 
   const selectionBox = usePointsEditorContext((s) => s.selectionBox)

package/src/components/PointsEditor/context.tsx

@@ -1,11 +1,11 @@
 import { createContext, CSSProperties, RefObject, useContext } from 'react'
 
-import type { SelectionBoxRect } from '@tremolo-ui/dom'
-import type {
-  InputEventOption,
-  ModifierState,
-  ModifierValue,
-} from '@tremolo-ui/functions'
+import {
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+  type SelectionBoxRect,
+} from '@tremolo-ui/dom'
 
 import type { PointBaseType } from './Point'
 

package/src/components/PointsEditor/index.tsx

@@ -12,19 +12,16 @@ import {
 } from 'react'
 
 import {
+  applyDelta,
   createSelectionBox,
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
   type SelectionBoxInstance,
   type SelectionBoxRect,
   type XY,
 } from '@tremolo-ui/dom'
-import {
-  applyDelta,
-  clamp,
-  type InputEventOption,
-  type ModifierState,
-  type ModifierValue,
-  toPrecision,
-} from '@tremolo-ui/functions'
+import { clamp, toPrecision } from '@tremolo-ui/functions'
 
 import { DEFAULT_DRAG_SENSITIVITY } from '../../input-event'
 import { cssLength } from '../_util/css-length'
@@ -35,6 +32,8 @@ import { type PointRegistration, PointsEditorProvider } from './context'
 import { AXIS, Point, type PointBaseType } from './Point'
 import { SelectionBox } from './SelectionBox'
 
+import type { CSSVariables } from '../../css-variables'
+
 /** One array for every editor with selection turned off, so memos hold still. */
 const EMPTY: readonly string[] = []
 
@@ -213,6 +212,8 @@ export interface PointsEditorProps {
    * </PointsEditor.Root>
    */
   children: ReactNode
+
+  style?: CSSProperties & CSSVariables<'width' | 'height'>
 }
 
 type Props = PointsEditorProps &
@@ -554,9 +555,6 @@ export {
   usePointsEditorContext,
   type PointsEditorContextValue,
 } from './context'
-export { type PointsEditorBackgroundProps } from './Background'
-export { type PointsEditorContainerProps } from './Container'
-export { type PointsEditorSelectionBoxProps } from './SelectionBox'
 export {
   clampPoint,
   type PointBaseType,

package/src/components/Slider/Marks.tsx

@@ -1,6 +1,4 @@
-import { ComponentPropsWithoutRef, CSSProperties, ReactNode } from 'react'
-
-import { xor } from '@tremolo-ui/functions'
+import { ComponentPropsWithoutRef, CSSProperties } from 'react'
 
 import { cssLength } from '../_util/css-length'
 import { Placement } from '../_util/Placement'
@@ -9,6 +7,8 @@ import { useSliderContext } from './context'
 import { MarksOption } from './MarksOption'
 import { generateOptionsList, MarksOptions } from './type'
 
+import type { CSSVariables } from '../../css-variables'
+
 export interface SliderMarksProps {
   /**
    * Space between the marks and the track. Sets `--gap`; the theme's own
@@ -24,11 +24,8 @@ export interface SliderMarksProps {
    * `'step'` makes one per step, which is a great many for a fine `step`.
    */
   options?: MarksOptions
-  /**
-   * `<Slider.MarksOption />` goes here, one per mark. Ignored while `options`
-   * is set.
-   */
-  children?: ReactNode
+
+  style?: CSSProperties & CSSVariables<'gap'>
 }
 
 export function Marks({
@@ -49,7 +46,7 @@ export function Marks({
   const optionsList = options
     ? generateOptionsList(options, min, max, step)
     : []
-  if (xor(vertical, reverse)) optionsList.reverse()
+  if (vertical !== reverse) optionsList.reverse()
 
   return (
     <div

package/src/components/Slider/MarksOption.tsx

@@ -1,12 +1,14 @@
 import { ComponentPropsWithoutRef, CSSProperties, useCallback } from 'react'
 
-import { toFixed, xor } from '@tremolo-ui/functions'
+import { toFixed } from '@tremolo-ui/functions'
 
 import { cssLength } from '../_util/css-length'
 import { useCheckPlacement } from '../_util/Placement'
 
 import { useSliderContext } from './context'
 
+import type { CSSVariables } from '../../css-variables'
+
 export interface SliderMarksOptionProps {
   /** Where the mark sits, on the same scale as the thumb. */
   value: number
@@ -39,6 +41,9 @@ export interface SliderMarksOptionProps {
     mark?: CSSProperties
     label?: CSSProperties
   }
+
+  style?: CSSProperties &
+    CSSVariables<'thickness' | 'length' | 'gap' | 'label-width' | 'translate'>
 }
 
 export function MarksOption({
@@ -68,7 +73,7 @@ export function MarksOption({
     (value: number) => {
       // The marks have to sit on the same curve the thumb runs along.
       const percent = scale.normalize(value, min, max) * 100
-      return toFixed(xor(vertical, reverse) ? 100 - percent : percent)
+      return toFixed(vertical !== reverse ? 100 - percent : percent)
     },
     [vertical, reverse, max, min, scale],
   )

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,11 +1,4 @@
-import {
-  ComponentPropsWithoutRef,
-  CSSProperties,
-  forwardRef,
-  ReactNode,
-} from 'react'
-
-import { xor } from '@tremolo-ui/functions'
+import { ComponentPropsWithoutRef, CSSProperties, forwardRef } from 'react'
 
 import { useComposedRefs } from '../../compose-refs'
 import { cssLength } from '../_util/css-length'
@@ -13,6 +6,8 @@ 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 +22,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 +58,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,17 +9,15 @@ import React, {
   useRef,
 } from 'react'
 
-import type { AxisOptions, XY } from '@tremolo-ui/dom'
 import {
   applyDelta,
-  linearScale,
-  toFixed,
+  type AxisOptions,
   type InputEventOption,
   type ModifierValue,
   selectModifier,
-  xor,
-  type Scale,
-} from '@tremolo-ui/functions'
+  type XY,
+} from '@tremolo-ui/dom'
+import { linearScale, type Scale, toFixed } from '@tremolo-ui/functions'
 
 import { useComposedRefs } from '../../compose-refs'
 import { useCheckSteps } from '../../hooks/_internal/useCheckSteps'
@@ -147,8 +145,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. */
@@ -227,10 +223,7 @@ export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
     // vertical -> rev (up)
     // reverse -> rev (left)
     // vertical & reverse -> normal (down)
-    const displayReversed = useMemo(
-      () => xor(vertical, reverse),
-      [vertical, reverse],
-    )
+    const displayReversed = vertical !== reverse
     const percent = displayReversed ? rev : p
 
     // --- internal functions ---

package/src/components/Slider/type.ts

@@ -1,4 +1,6 @@
-import { decimalPart, toFixed } from '@tremolo-ui/functions'
+import { toFixed } from '@tremolo-ui/functions'
+
+import { decimalDigits } from '../_util/decimal-digits'
 
 /**
  * How `Slider.Marks` fills itself in when it is given no children: one option
@@ -36,7 +38,7 @@ export function generateOptionsList(
   for (let i = 0; i < count; i++) {
     const value = toFixed(
       interval * (Math.ceil(min / interval) + i),
-      decimalPart(interval)?.length,
+      decimalDigits(interval),
     )
     optionsList.push({ value: value, mark: mark, label: label })
   }

package/src/components/XYPad/Area.tsx

@@ -1,9 +1,4 @@
-import {
-  ComponentPropsWithoutRef,
-  CSSProperties,
-  forwardRef,
-  ReactNode,
-} from 'react'
+import { ComponentPropsWithoutRef, CSSProperties, forwardRef } from 'react'
 
 import { useComposedRefs } from '../../compose-refs'
 import { cssLength } from '../_util/css-length'
@@ -11,6 +6,8 @@ import { Placement } from '../_util/Placement'
 
 import { useXYPadContext } from './context'
 
+import type { CSSVariables } from '../../css-variables'
+
 export interface XYPadAreaProps {
   /** Sets `--width`; the size the theme gives it stands when omitted. */
   width?: number | string
@@ -18,10 +15,8 @@ export interface XYPadAreaProps {
   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
+
+  style?: CSSProperties & CSSVariables<'width' | 'height' | 'color'>
 }
 
 type Props = XYPadAreaProps &

package/src/components/XYPad/Thumb.tsx

@@ -1,11 +1,10 @@
 import {
   AriaAttributes,
   ComponentPropsWithoutRef,
-  CSSProperties,
   forwardRef,
-  ReactNode,
   useImperativeHandle,
   useRef,
+  CSSProperties,
 } from 'react'
 
 import { useCheckPlacement } from '../_util/Placement'
@@ -13,6 +12,8 @@ import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
 
 import { toXY, useXYPadContext, type XYInput } from './context'
 
+import type { CSSVariables } from '../../css-variables'
+
 export interface XYPadThumbProps {
   /**
    * Sets `--color`, for the theme to colour the thumb with. The size is not
@@ -21,15 +22,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 +37,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/index.tsx

@@ -10,17 +10,15 @@ import {
   useRef,
 } from 'react'
 
-import type { AxisOptions } from '@tremolo-ui/dom'
 import {
   applyDelta,
-  linearScale,
-  toFixed,
+  type AxisOptions,
   InputEventOption,
   ModifierState,
   type ModifierValue,
   selectModifier,
-  type Scale,
-} from '@tremolo-ui/functions'
+} from '@tremolo-ui/dom'
+import { linearScale, type Scale, toFixed } from '@tremolo-ui/functions'
 
 import { useComposedRefs } from '../../compose-refs'
 import { useCheckSteps } from '../../hooks/_internal/useCheckSteps'

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 './visually-hidden'
 
 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/components/_util/decimal-digits.ts

@@ -0,0 +1,23 @@
+/**
+ * How many digits a number carries after the decimal point.
+ *
+ * `Slider.Marks` builds its labels by multiplying an interval, which leaves
+ * binary debris in the last digits (`0.1 * 3` is `0.30000000000000004`). The
+ * count is what tells `toFixed` how far to round that back.
+ *
+ * The exponent form has to be handled separately: `String(1e-7)` is `'1e-7'`,
+ * which has no decimal point at all, so reading the text after the point
+ * reports no digits and the interval rounds away to whole numbers.
+ */
+export function decimalDigits(x: number): number {
+  if (!Number.isFinite(x)) return 0
+
+  const text = String(x)
+  const e = text.indexOf('e')
+  if (e === -1) return text.split('.')[1]?.length ?? 0
+
+  const fraction = text.slice(0, e).split('.')[1]?.length ?? 0
+  // A negative exponent pushes the point further right, a positive one pulls
+  // it back past the digits that are there.
+  return Math.max(0, fraction - Number(text.slice(e + 1)))
+}

package/src/components/_util/visually-hidden.ts

@@ -0,0 +1,25 @@
+import type { CSSProperties } from 'react'
+
+/**
+ * Take an element out of sight while leaving it in the accessibility tree and
+ * in the tab order.
+ *
+ * `display: none` and `visibility: hidden` would remove it from both, and the
+ * native control underneath a headless component is what carries the ARIA and
+ * the keyboard behaviour. `pointer-events: none` is safe because nothing is
+ * ever clicked here directly: a `<label>` forwards its click, and a drag is
+ * handled by the part that is visible.
+ */
+export const visuallyHiddenStyle: 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',
+}

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
+}

package/src/hooks/_internal/useCheckSteps.ts

@@ -2,12 +2,11 @@ import { useEffect } from 'react'
 
 import {
   applyDelta,
-  linearScale,
   type InputEventOption,
   type ModifierState,
   type ModifierValue,
-  type ValueRange,
-} from '@tremolo-ui/functions'
+} from '@tremolo-ui/dom'
+import { linearScale, type ValueRange } from '@tremolo-ui/functions'
 
 /** Positions probed across the travel. The ends are left out so that the
  * clamp at `min` and `max` cannot be mistaken for a press that does nothing. */

package/src/hooks/useDrag.ts

@@ -4,10 +4,14 @@ import { createDrag, type DragState } from '@tremolo-ui/dom'
 
 import { useCallbackRef } from './_internal/useCallbackRef'
 
-interface UseDragProps {
+export interface UseDragOptions {
   /**
-   * Threshold at which the onDrag event fires.
-   * Prevents onDrag events from firing, for example, when double-clicking.
+   * Pixels the pointer has to travel before the drag counts as one.
+   *
+   * A click moves the pointer by a pixel or two, so without a threshold a
+   * double click reports a drag between the two presses.
+   *
+   * @default 1
    */
   threshold?: number
 
@@ -24,6 +28,9 @@ interface UseDragProps {
   pointerLock?: boolean
 
   /**
+   * Called on every move once the drag has started, with the pointer position
+   * relative to the element and how far it moved since the last call.
+   *
    * @param state the whole drag, for anything the four numbers leave out —
    * the pointer event and its modifier keys, most of all.
    */
@@ -34,7 +41,9 @@ interface UseDragProps {
     deltaY: number,
     state: DragState,
   ) => void
+  /** Called once the pointer has moved past `threshold`, not on pointerdown. */
   onDragStart?: (state: DragState) => void
+  /** Called when the pointer is released, only if the drag ever started. */
   onDragEnd?: (state: DragState) => void
 }
 
@@ -50,7 +59,7 @@ export function useDrag<T extends Element>({
   onDrag,
   onDragStart,
   onDragEnd,
-}: UseDragProps): (node: T | null) => void {
+}: UseDragOptions): (node: T | null) => void {
   const dragHandler = useCallbackRef(onDrag)
   const dragStartHandler = useCallbackRef(onDragStart)
   const dragEndHandler = useCallbackRef(onDragEnd)