etudes 30.2.0 → 31.0.0

package/build/index.d.ts

@@ -20,7 +20,6 @@ export * from './hooks/useDropzone.js';
 export * from './hooks/useImageLoader.js';
 export * from './hooks/useImageSize.js';
 export * from './hooks/useInertiaDrag.js';
-export * from './hooks/useInertiaDragValue.js';
 export * from './hooks/useIntersectionObserver.js';
 export * from './hooks/useInterval.js';
 export * from './hooks/useIsMounted.js';

package/build/primitives/Panorama.d.ts

@@ -1,5 +1,12 @@
 import { HTMLAttributes, Ref } from 'react';
 import { Size } from 'spase';
+/**
+ * A component containing a pannable 360° panorama image.
+ */
+export declare function Panorama({ ref, angle, speed, src, zeroAnchor, onAngleChange, onDragEnd, onDragStart, onImageSizeChange, onLoadImageComplete, onLoadImageError, onLoadImageStart, onPositionChange, ...props }: Panorama.Props): import("react/jsx-runtime").JSX.Element;
+export declare namespace Panorama {
+    var displayName: string;
+}
 export declare namespace Panorama {
     /**
      * Type describing the props of {@link Panorama}.
@@ -32,24 +39,17 @@ export declare namespace Panorama {
          */
         zeroAnchor?: number;
         /**
-         * Handler invoked when the position changes. This can either be invoked
-         * from the `angle` prop being changed or from the image being dragged.
+         * Handler invoked when the position changes.
          *
          * @param position The current position.
-         * @param isDragging Specifies if the position change is due to dragging.
          */
-        onPositionChange?: (position: number, isDragging: boolean) => void;
+        onPositionChange?: (position: number) => void;
         /**
-         * Handler invoked when the angle changes. This can either be invoked from
-         * the `angle` prop being changed or from the image being dragged. When
-         * `angle` is being double-bound, ensure that the value is only being set by
-         * this handler when `isDragging` is `true` to avoid potential update
-         * overflow.
+         * Handler invoked when the angle changes.
          *
          * @param angle The current angle.
-         * @param isDragging Specifies if the angle change is due to dragging.
          */
-        onAngleChange?: (angle: number, isDragging: boolean) => void;
+        onAngleChange?: (angle: number) => void;
         /**
          * Handler invoked when dragging starts.
          */
@@ -74,17 +74,8 @@ export declare namespace Panorama {
          * Handler invoked when the image size changes. This is the actual size of
          * the loaded image. When no images are loaded yet, the size is `undefined`.
          *
-         * @param size The actual size of the loaded image. If no images are loaded
-         *               yet, the size is `undefined`.
+         * @param size The actual size of the loaded image.
          */
         onImageSizeChange?: (size?: Size.Size) => void;
     } & Omit<HTMLAttributes<HTMLDivElement>, 'aria-valuenow' | 'role'>;
 }
-/**
- * A component containing a pannable 360° panorama image. The angle supports
- * two-way binding.
- */
-export declare function Panorama({ ref, angle: externalAngle, speed, src, zeroAnchor, onAngleChange, onDragEnd, onDragStart, onImageSizeChange, onLoadImageComplete, onLoadImageError, onLoadImageStart, onPositionChange, ...props }: Panorama.Props): import("react/jsx-runtime").JSX.Element;
-export declare namespace Panorama {
-    var displayName: string;
-}

package/build/primitives/RangeSlider.d.ts

@@ -2,13 +2,13 @@ import { HTMLAttributes, Ref } from 'react';
 /**
  * A slider component that allows the user to select a range of values.
  *
- * @exports RangeSlider.Gutter Component for the gutter.
- * @exports RangeSlider.Highlight Component for the highlight.
  * @exports RangeSlider.Knob Component for the knob.
  * @exports RangeSlider.KnobContainer Component for the container of the knob.
  * @exports RangeSlider.Label Component for the label.
+ * @exports RangeSlider.Track Component for the track.
+ * @exports RangeSlider.TrackHighlight Component for the track highlight.
  */
-export declare function RangeSlider({ className, ref, children, decimalPlaces, knobHeight, knobPadding, knobWidth, max: maxValue, min: minValue, orientation, range: externalRange, steps, isClipped, onChange, ...props }: RangeSlider.Props): import("react/jsx-runtime").JSX.Element;
+export declare function RangeSlider({ className, ref, children, knobHeight, knobPadding, knobWidth, max: maxValue, min: minValue, orientation, range, steps, isClipped, formatLabel, onChange, onDragEnd, onDragStart, ...props }: RangeSlider.Props): import("react/jsx-runtime").JSX.Element;
 export declare namespace RangeSlider {
     var displayName: string;
 }
@@ -29,10 +29,6 @@ export declare namespace RangeSlider {
          * Reference to the root element.
          */
         ref?: Ref<HTMLDivElement>;
-        /**
-         * Number of decimal places to display.
-         */
-        decimalPlaces?: number;
         /**
          * Specifies if the knobs are clipped to the track.
          */
@@ -73,23 +69,46 @@ export declare namespace RangeSlider {
          */
         steps?: number;
         /**
-         * Handler invoked when the range of values changes.
+         * A function that formats the labels displayed on the knobs based on the
+         * selected values. If not provided, no label will be rendered.
+         *
+         * @param value The value of the side specified by `side`.
+         * @param side Specifies which side the label is for, either the 'start' or
+         *             'end' knob.
+         *
+         * @returns The formatted string.
+         */
+        formatLabel?: (value: number, side: 'end' | 'start') => string;
+        /**
+         * Handler invoked when the range of values changes due to dragging a knob.
+         * While dragging it is invoked repeatedly with `isDragging` set to `true`;
+         * when a knob is released it is invoked once more with the stepped range and
+         * `isDragging` set to `false`.
          *
          * @param range The current range of values.
+         * @param isDragging Specifies if the change is from an in-progress drag.
+         */
+        onChange?: (range: Range, isDragging: boolean) => void;
+        /**
+         * Handler invoked when dragging a knob ends.
+         */
+        onDragEnd?: () => void;
+        /**
+         * Handler invoked when dragging a knob begins.
          */
-        onChange?: (range: Range) => void;
+        onDragStart?: () => void;
     } & Omit<HTMLAttributes<HTMLDivElement>, 'aria-valuemax' | 'aria-valuemin' | 'onChange' | 'role'>;
     /**
-     * Component for the gutter of a {@link RangeSlider}.
+     * Component for the track of a {@link RangeSlider}.
      */
-    const Gutter: {
+    const Track: {
         ({ ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
         displayName: string;
     };
     /**
-     * Component for the highlight of a {@link RangeSlider}.
+     * Component for the track highlight of a {@link RangeSlider}.
      */
-    const Highlight: {
+    const TrackHighlight: {
         ({ ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
         displayName: string;
     };

package/build/primitives/Slider.d.ts

@@ -1,12 +1,11 @@
 import { HTMLAttributes, Ref } from 'react';
 /**
- * A slider component supporting both horizontal and vertical orientations whose
- * sliding position (a decimal between 0.0 and 1.0, inclusive) can be two-way
- * bound. The component consists of three customizable elements: a draggable
- * knob, a label on the knob, and a scroll track on either side of the knob.
- * While the width and height of the slider is inferred from its CSS rules, the
- * width and height of the knob are set via props (`knobWidth` and `knobHeight`,
- * respectively). The size of the knob does not impact the size of the slider.
+ * A slider component supporting both horizontal and vertical orientations. The
+ * component consists of three customizable elements: a draggable knob, a label
+ * on the knob, and a scroll track on either side of the knob. While the width
+ * and height of the slider is inferred from its CSS rules, the width and height
+ * of the knob are set via props (`knobWidth` and `knobHeight`, respectively).
+ * The size of the knob does not impact the size of the slider.
  *
  * @exports Slider.Knob Component for the knob.
  * @exports Slider.KnobContainer Component for the container of the knob.
@@ -14,7 +13,7 @@ import { HTMLAttributes, Ref } from 'react';
  * @exports Slider.Track Component for the slide track on either side of the
  *                       knob.
  */
-export declare function Slider({ className, ref, children, knobHeight, knobPadding, knobWidth, labelProvider, orientation, position: externalPosition, trackPadding, isClipped, isInverted, isTrackInteractive, shouldOnlyDispatchOnDragEnd, onChange, onDragEnd, onDragStart, ...props }: Readonly<Slider.Props>): import("react/jsx-runtime").JSX.Element;
+export declare function Slider({ className, ref, children, knobHeight, knobPadding, knobWidth, orientation, position, trackPadding, isClipped, isInverted, isTrackInteractive, formatLabel, onChange, onDragEnd, onDragStart, ...props }: Readonly<Slider.Props>): import("react/jsx-runtime").JSX.Element;
 export declare namespace Slider {
     var displayName: string;
 }
@@ -45,12 +44,6 @@ export declare namespace Slider {
          * Specifies if the track is clickable to set the position of the knob.
          */
         isTrackInteractive?: boolean;
-        /**
-         * Indicates if position change events are dispatched only when dragging
-         * ends. When disabled, aforementioned events are fired repeatedly while
-         * dragging.
-         */
-        shouldOnlyDispatchOnDragEnd?: boolean;
         /**
          * Padding between the track and the knob in pixels.
          */
@@ -76,20 +69,16 @@ export declare namespace Slider {
          */
         position?: number;
         /**
-         * A function that returns the label to be displayed at a given slider
-         * position.
+         * A function that formats the position to be displayed as the slider label.
+         * If not provided, no label will be rendered.
          *
          * @param position The current slider position.
          *
-         * @returns The label.
+         * @returns The formatted string.
          */
-        labelProvider?: (position: number) => string;
+        formatLabel?: (position: number) => string;
         /**
-         * Handler invoked when position changes. This can either be invoked from
-         * the `position` prop being changed or from the slider being dragged. Note
-         * that if the event is emitted at the end of dragging due to
-         * `shouldOnlyDispatchOnDragEnd` set to `true`, the `isDragging` parameter
-         * here is still `true`.
+         * Handler invoked when position changes.
          *
          * @param position The current slider position.
          * @param isDragging Specifies if the position change is due to dragging.

package/build/primitives/StepSlider.d.ts

@@ -1,16 +1,16 @@
 import { HTMLAttributes, Ref } from 'react';
 /**
  * A "step" slider component supporting both horizontal and vertical
- * orientations that automatically snaps to a set of predefined points on the
- * slider when dragged. These points are referred to as "steps", indexed by an
- * integer referred to as "index". This index can be two-way bound. The
- * component consists of four customizable elements: a draggable knob, a label
- * on the knob, a scroll track before the knob and a scroll track after the
- * knob. While the width and height of the slider is inferred from its CSS
- * rules, the width and height of the knob are set via props (`knobWidth` and
- * `knobHeight`, respectively). The size of the knob does not impact the size of
- * the slider. While dragging, the slider still emits a position change event,
- * where the position is a decimal ranging between 0.0 and 1.0, inclusive.
+ * orientations that automatically whose knob snaps to a set of predefined
+ * points on the track upon drag release. These points are referred to as
+ * "steps", indexed by an integer referred to as "index". The index is
+ * controlled via the `index` prop; feed the value reported by `onIndexChange`
+ * back into it to persist changes. While the width and height of the slider is
+ * inferred from its CSS rules, the width and height of the knob are set via
+ * props (`knobWidth` and `knobHeight`, respectively). The size of the knob does
+ * not impact the size of the slider. While dragging, the slider still emits a
+ * position change event, where the position is a decimal ranging between 0.0
+ * and 1.0, inclusive.
  *
  * @exports StepSlider.Knob Component for the knob.
  * @exports StepSlider.KnobContainer Component for the container of the knob.
@@ -18,11 +18,10 @@ import { HTMLAttributes, Ref } from 'react';
  * @exports StepSlider.Track Component for the slide track on either side of the
  *                           knob.
  */
-export declare function StepSlider({ className, ref, children, index: externalIndex, knobHeight, knobPadding, knobWidth, labelProvider, orientation, steps, trackPadding, isClipped, isInverted, isTrackInteractive, shouldOnlyDispatchOnDragEnd, onDragEnd, onDragStart, onIndexChange, onPositionChange, ...props }: StepSlider.Props): import("react/jsx-runtime").JSX.Element;
+export declare function StepSlider({ className, ref, children, index, knobHeight, knobPadding, knobWidth, orientation, steps, trackPadding, isClipped, isInverted, isTrackInteractive, formatLabel: labelProvider, onDragEnd, onDragStart, onIndexChange, onPositionChange, ...props }: StepSlider.Props): import("react/jsx-runtime").JSX.Element;
 export declare namespace StepSlider {
     var displayName: string;
 }
-declare function _generateSteps(length: number): readonly number[];
 export declare namespace StepSlider {
     /**
      * Type describing the orientation of {@link StepSlider}.
@@ -50,12 +49,6 @@ export declare namespace StepSlider {
          * Specifies if the track is clickable to set the position of the knob.
          */
         isTrackInteractive?: boolean;
-        /**
-         * Indicates if position/index change events are dispatched only when dragging
-         * ends. When disabled, aforementioned events are fired repeatedly while
-         * dragging.
-         */
-        shouldOnlyDispatchOnDragEnd?: boolean;
         /**
          * Padding between the track and the knob in pixels.
          */
@@ -97,37 +90,35 @@ export declare namespace StepSlider {
          *
          * @returns The label.
          */
-        labelProvider?: (position: number, index: number) => string;
+        formatLabel?: (position: number, index: number) => string;
+        /**
+         * Handler invoked when dragging ends.
+         */
+        onDragEnd?: () => void;
+        /**
+         * Handler invoked when dragging begins.
+         */
+        onDragStart?: () => void;
         /**
-         * Handler invoked when index changes. This can either be invoked from the
-         * `index` prop being changed or from the slider being dragged. Note that if
-         * the event is emitted at the end of dragging due to
-         * `onlyDispatchesOnDragEnd` set to `true`, the `isDragging` parameter here
-         * is still `true`. This event is emitted right after `onPositionChange`.
+         * Handler invoked when the nearest step index changes due to dragging or a
+         * track click. While dragging it is invoked with `isDragging` set to
+         * `true`; on release (after snapping) and on a track click it is invoked
+         * with `isDragging` set to `false`. Emitted right after `onPositionChange`.
          *
          * @param index The current slider index.
-         * @param isDragging Specifies if the index change is due to dragging.
+         * @param isDragging Specifies if the change is from an in-progress drag.
          */
         onIndexChange?: (index: number, isDragging: boolean) => void;
         /**
-         * Handler invoked when position changes. This can either be invoked from
-         * the `index` prop being changed or from the slider being dragged. Note
-         * that if the event is emitted at the end of dragging due to
-         * `onlyDispatchesOnDragEnd` set to `true`, the `isDragging` parameter here
-         * is still `true`. This event is emitted right before `onIndexChange`.
+         * Handler invoked when the continuous position changes due to dragging or a
+         * track click. While dragging it is invoked with `isDragging` set to
+         * `true`; on release (after snapping) and on a track click it is invoked
+         * with `isDragging` set to `false`. Emitted right before `onIndexChange`.
          *
          * @param position The current slider position.
-         * @param isDragging Specifies if the position change is due to dragging.
+         * @param isDragging Specifies if the change is from an in-progress drag.
          */
         onPositionChange?: (position: number, isDragging: boolean) => void;
-        /**
-         * Handler invoked when dragging ends.
-         */
-        onDragEnd?: () => void;
-        /**
-         * Handler invoked when dragging begins.
-         */
-        onDragStart?: () => void;
     } & Omit<HTMLAttributes<HTMLDivElement>, 'aria-valuenow' | 'onChange' | 'role'>;
     /**
      * Component for the knob of a {@link StepSlider}.
@@ -167,4 +158,5 @@ export declare namespace StepSlider {
      */
     const generateSteps: typeof _generateSteps;
 }
+declare function _generateSteps(length: number): readonly number[];
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "etudes",
-  "version": "30.2.0",
+  "version": "31.0.0",
   "description": "A study of headless React components",
   "type": "module",
   "sideEffects": false,

package/build/hooks/useInertiaDragValue.d.ts

@@ -1,56 +0,0 @@
-import { Dispatch, RefObject, SetStateAction } from 'react';
-import { useInertiaDrag } from './useInertiaDrag.js';
-/**
- * Type describing the output of {@link useInertiaDragValue}.
- */
-export type UseDragValueOutput<T = [number, number]> = {
-    /**
-     * Indicates whether the drag is currently happening.
-     */
-    isDragging: boolean;
-    /**
-     * Indicates whether the drag is currently being released.
-     */
-    isReleasing: boolean;
-    /**
-     * The current associated value of this hook.
-     */
-    value: T;
-    /**
-     * A function that sets the current associated value of this hook.
-     *
-     * @param value The new associated value.
-     */
-    setValue: Dispatch<SetStateAction<T>>;
-};
-/**
- * Type describing the options of {@link useInertiaDragValue}.
- */
-export type UseDragValueOptions<T = [number, number]> = {
-    /**
-     * The initial associated value of this hook.
-     */
-    initialValue: T;
-    /**
-     * A function that transforms the drag move delta values to the associated
-     * value of this hook.
-     *
-     * @param currentValue The current associated value.
-     * @param dx The displacement on the x-axis (in pixels) since the last emitted
-     *           drag move event.
-     * @param dy The displacement on the y-axis (in pixels) since the last emitted
-     *           drag move event.
-     *
-     * @returns The transformed value.
-     */
-    transform: (currentValue: T, dx: number, dy: number) => T;
-} & Parameters<typeof useInertiaDrag>[1];
-/**
- * Hook for adding dragging interaction to an element.
- *
- * @param target The target element or reference to add drag interaction to.
- * @param options Additional options.
- *
- * @returns The states created for this effect.
- */
-export declare function useInertiaDragValue<T = [number, number]>(target: HTMLElement | null | RefObject<HTMLElement> | RefObject<HTMLElement | null> | RefObject<HTMLElement | undefined> | undefined, { initialValue, transform, onDragEnd, onDragMove, onDragStart, ...options }: UseDragValueOptions<T>): UseDragValueOutput<T>;