etudes 28.2.2 → 29.0.0

package/build/hooks/useDrag.d.ts

@@ -17,7 +17,7 @@ export type UseDragOptions = {
      *
      * @param startPosition The element that was dragged.
      */
-    onDragStart?: (startPosition: Point) => void;
+    onDragStart?: (startPosition: Point.Point) => void;
     /**
      * Handler invoked when dragging.
      *
@@ -27,7 +27,7 @@ export type UseDragOptions = {
      *                        at.
      * @param startPosition The position (in pixels) where the drag started.
      */
-    onDragMove?: (displacement: Point, currentPosition: Point, startPosition: Point) => void;
+    onDragMove?: (displacement: Point.Point, currentPosition: Point.Point, startPosition: Point.Point) => void;
     /**
      * Handler invoked when dragging ends.
      *
@@ -36,7 +36,7 @@ export type UseDragOptions = {
      * @param endPosition The position (in pixels) where the drag ended.
      * @param startPosition The position (in pixels) where the drag started.
      */
-    onDragEnd?: (displacement: Point, endPosition: Point, startPosition: Point) => void;
+    onDragEnd?: (displacement: Point.Point, endPosition: Point.Point, startPosition: Point.Point) => void;
 };
 /**
  * Hook for adding dragging interaction to an element.

package/build/hooks/useImageSize.d.ts

@@ -23,4 +23,4 @@ export type UseImageSizeOptions = {
  * @returns The actual size of the image if loading was successful, `undefined`
  *          otherwise.
  */
-export declare function useImageSize({ sizes, src, srcSet, }: UseImageSizeParams, { preservesSizeBetweenLoads, onError, onLoad, onLoadStart, }?: UseImageSizeOptions): Size | undefined;
+export declare function useImageSize({ sizes, src, srcSet, }: UseImageSizeParams, { preservesSizeBetweenLoads, onError, onLoad, onLoadStart, }?: UseImageSizeOptions): Size.Size | undefined;

package/build/hooks/useInertiaDrag.d.ts

@@ -12,7 +12,7 @@ export type UseInertiaDragOptions = {
     /**
      * Handler invoked when dragging starts.
      */
-    onDragStart?: (startPosition: Point) => void;
+    onDragStart?: (startPosition: Point.Point) => void;
     /**
      * Handler invoked when dragging.
      *
@@ -22,14 +22,14 @@ export type UseInertiaDragOptions = {
      *                        currently at.
      * @param startPosition The position (in pixels) where the drag started.
      */
-    onDragMove?: (displacement: Point, currentPosition: Point, startPosition: Point) => void;
+    onDragMove?: (displacement: Point.Point, currentPosition: Point.Point, startPosition: Point.Point) => void;
     /**
      * Handler invoked when dragging ends.
      *
      * @param endPosition The position (in pixels) where the drag ended.
      * @param startPosition The position (in pixels) where the drag started.
      */
-    onDragEnd?: (endPosition: Point, startPosition: Point) => void;
+    onDragEnd?: (endPosition: Point.Point, startPosition: Point.Point) => void;
 } & Omit<InteractDraggableOptions, 'onend' | 'onmove' | 'onstart'>;
 /**
  * Hook for adding dragging interaction to an element.

package/build/hooks/useRect.d.ts

@@ -6,6 +6,6 @@ import { Rect } from 'spase';
  *
  * @param target The target element or reference.
  *
- * @returns The most current {@link Rect} of the target element.
+ * @returns The most current rect of the target element.
  */
-export declare function useRect(target: HTMLElement | null | RefObject<HTMLElement> | RefObject<HTMLElement | null> | RefObject<HTMLElement | undefined> | undefined): Rect;
+export declare function useRect(target: HTMLElement | null | RefObject<HTMLElement> | RefObject<HTMLElement | null> | RefObject<HTMLElement | undefined> | undefined): Rect.Rect;

package/build/hooks/useScrollPosition.d.ts

@@ -1,10 +1,10 @@
 import { DependencyList, RefObject } from 'react';
 import { Point } from 'spase';
 export type ScrollPositionInfo = {
-    current: Point;
-    end: Point;
-    progress: Point;
-    start: Point;
+    current: Point.Point;
+    end: Point.Point;
+    progress: Point.Point;
+    start: Point.Point;
 };
 type Target = HTMLElement | null | RefObject<HTMLElement> | RefObject<HTMLElement | null> | RefObject<HTMLElement | undefined> | undefined;
 /**

package/build/hooks/useSize.d.ts

@@ -5,6 +5,6 @@ import { Size } from 'spase';
  *
  * @param target Reference to the target element.
  *
- * @returns The most current {@link Size} of the target element.
+ * @returns The most current size of the target element.
  */
-export declare function useSize(target: HTMLElement | null | RefObject<HTMLElement> | RefObject<HTMLElement | null> | RefObject<HTMLElement | undefined> | undefined): Size;
+export declare function useSize(target: HTMLElement | null | RefObject<HTMLElement> | RefObject<HTMLElement | null> | RefObject<HTMLElement | undefined> | undefined): Size.Size;

package/build/hooks/useVideoSize.d.ts

@@ -19,5 +19,5 @@ type UseVideoSizeOptions = {
  * @returns The actual size of the video if loading was successful, `undefined`
  *          otherwise.
  */
-export declare function useVideoSize(src?: string, { preservesSizeBetweenLoads, onError, onLoad, onLoadStart, }?: UseVideoSizeOptions): Size | undefined;
+export declare function useVideoSize(src?: string, { preservesSizeBetweenLoads, onError, onLoad, onLoadStart, }?: UseVideoSizeOptions): Size.Size | undefined;
 export {};

package/build/hooks/useViewportSize.d.ts

@@ -4,4 +4,4 @@ import { Size } from 'spase';
  *
  * @returns The most current viewport size.
  */
-export declare function useViewportSize(): Size;
+export declare function useViewportSize(): Size.Size;

package/build/index.d.ts

@@ -1,3 +1,4 @@
+export * from './animations/useAnimatedValue.js';
 export * from './components/Burger.js';
 export * from './components/BurgerButton.js';
 export * from './components/CoverImage.js';
@@ -58,6 +59,7 @@ export * from './primitives/MasonryGrid.js';
 export * from './primitives/Panorama.js';
 export * from './primitives/Picture.js';
 export * from './primitives/RangeSlider.js';
+export * from './primitives/ScrollableCarousel.js';
 export * from './primitives/Select.js';
 export * from './primitives/Slider.js';
 export * from './primitives/StepSlider.js';

package/build/primitives/Carousel.d.ts

@@ -1,4 +1,35 @@
-import { ComponentType, HTMLAttributes, Ref } from 'react';
+import { HTMLAttributes, Ref } from 'react';
+type CarouselItemContextValue = {
+    exposure: number | undefined;
+    index: number;
+    isActive: boolean;
+};
+/**
+ * A headless carousel component that displays a list of items and lets the user
+ * drag (mouse or touch) to switch between them.
+ *
+ * Notable features:
+ *   - Supports horizontal and vertical orientations.
+ *   - Supports auto-advancing to the next item after a specified interval.
+ *   - Supports tracking item exposure (0-1) to determine how much of the
+ *     current item is visible in the viewport.
+ *   - Supports rubber-band resistance when dragging past the first or last
+ *     item.
+ *
+ * The root element is rendered with `role='region'`. To meet accessibility
+ * requirements for landmark regions, pass `aria-label` (or `aria-labelledby`)
+ * so the region has an accessible name.
+ *
+ * @exports Carousel.Viewport Component for the viewport.
+ * @exports Carousel.Content Component for the list holding all items.
+ * @exports Carousel.ItemContainer Component containing each item.
+ * @exports useCarouselItem Hook for reading the current item's index, exposure,
+ *                          and active state from within an item's subtree.
+ */
+export declare function Carousel({ ref, animationDuration, autoAdvanceInterval, children, dragSpeed, dragThreshold, index, orientation, overscrollResistance, swipeLiftWindow, swipeVelocityThreshold, shouldTrackExposure, onAutoAdvancePause, onAutoAdvanceResume, onIndexChange, ...props }: Carousel.Props): import("react/jsx-runtime").JSX.Element;
+export declare namespace Carousel {
+    var displayName: string;
+}
 export declare namespace Carousel {
     /**
      * Type describing the orientation of {@link Carousel}.
@@ -7,39 +38,68 @@ export declare namespace Carousel {
     /**
      * Type describing the props of {@link Carousel}.
      */
-    type Props<I> = {
+    type Props = {
         /**
-         * Current item index.
+         * Reference to the root element.
          */
-        index?: number;
+        ref?: Ref<HTMLDivElement>;
+        /**
+         * The duration in milliseconds for the animation when changing items. This
+         * is used when the user drags and releases, or when the index changes
+         * without dragging (e.g. auto advance or external index change). The
+         * default value is `200` ms.
+         */
+        animationDuration?: number;
         /**
          * The interval in milliseconds to wait before automatically advancing to
          * the next item (auto loops).
          */
         autoAdvanceInterval?: number;
         /**
-         * Whether the carousel is draggable.
+         * The drag speed multiplier. Higher values result in faster dragging. The
+         * default value is `1`.
+         */
+        dragSpeed?: number;
+        /**
+         * Minimum pixel distance the pointer must travel between pointer-down and
+         * pointer-up for the gesture to be classified as a drag. Movements within
+         * this threshold are treated as a click and are allowed to propagate.
          */
-        isDragEnabled?: boolean;
+        dragThreshold?: number;
         /**
-         * Props for each item component
+         * Current item index.
          */
-        items?: Omit<I, 'exposure'>[];
+        index?: number;
         /**
          * Orientation of the carousel.
          */
         orientation?: Orientation;
         /**
-         * The drag speed multiplier. Higher values result in faster dragging. The
-         * default value is `1`. This is only applicable when dragging with a
-         * non-touch pointer (e.g. mouse).
+         * Resistance applied when the user drags past the first or last item. `0`
+         * lets the overshoot track the pointer 1:1 (no resistance); `1` clamps hard
+         * at the boundary (max resistance, no overshoot). Values in between produce
+         * a rubber-band effect—higher means more resistance.
          */
-        dragSpeed?: number;
+        overscrollResistance?: number;
         /**
          * Whether to track item exposure (0-1, 0 meaning the item is fully scrolled
          * out of view, 1 meaning the item is fully scrolled into view).
          */
         shouldTrackExposure?: boolean;
+        /**
+         * Maximum gap in milliseconds between the last pointer move and the pointer
+         * release for the gesture to register as a swipe. If the pointer was held
+         * stationary longer than this before release, no swipe is detected and the
+         * release falls back to position-based snapping.
+         */
+        swipeLiftWindow?: number;
+        /**
+         * Minimum axial pointer velocity (in pixels per millisecond) at release for
+         * the gesture to register as a swipe. A detected swipe advances the index
+         * by one in the swipe direction, regardless of how far the displacement has
+         * traveled.
+         */
+        swipeVelocityThreshold?: number;
         /**
          * Handler invoked when auto advance pauses. This is invoked only when
          * {@link autoAdvanceInterval} is greater than 0.
@@ -56,24 +116,33 @@ export declare namespace Carousel {
          * @param index The item index.
          */
         onIndexChange?: (index: number) => void;
-        /**
-         * The component to render for each item.
-         */
-        ItemComponent: ComponentType<I>;
-        ref?: Ref<HTMLDivElement>;
-    } & Omit<HTMLAttributes<HTMLDivElement>, 'onClick' | 'onPointerCancel' | 'onPointerDown' | 'onPointerLeave' | 'onPointerUp' | 'role'>;
+    } & Omit<HTMLAttributes<HTMLDivElement>, 'onClick' | 'onPointerCancel' | 'onPointerDown' | 'onPointerMove' | 'onPointerUp' | 'role'>;
+    /**
+     * Component for the viewport of a {@link Carousel}.
+     */
+    const Viewport: {
+        ({ children, ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    /**
+     * Component for the list holding all items inside a {@link Carousel}.
+     */
+    const Content: {
+        ({ children, ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+    /**
+     * Component containing each item in a {@link Carousel}.
+     */
+    const ItemContainer: {
+        ({ children, ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
 }
 /**
- * A carousel component that displays a list of items in a scrollable view.
- *
- * Notable features:
- *   - Supports horizontal and vertical orientations.
- *   - Supports auto-advancing to the next item after a specified interval.
- *   - Supports auto-snapping to each item when scrolling.
- *   - Supports tracking item exposure (0-1) to determine how much of the
- *     current item is visible in the viewport.
+ * Hook for reading the current item's `index`, `exposure`, and `isActive` state
+ * from within a {@link Carousel} item's subtree. Throws when called outside of
+ * an item.
  */
-export declare function Carousel<I extends HTMLAttributes<HTMLElement>>({ ref, autoAdvanceInterval, dragSpeed, index, ItemComponent, items, orientation, isDragEnabled, shouldTrackExposure, onAutoAdvancePause, onAutoAdvanceResume, onIndexChange, ...props }: Carousel.Props<I>): import("react/jsx-runtime").JSX.Element;
-export declare namespace Carousel {
-    var displayName: string;
-}
+export declare function useCarouselItem(): CarouselItemContextValue;
+export {};

package/build/primitives/Image.d.ts

@@ -45,7 +45,7 @@ export declare namespace Image {
          *
          * @param size Size of the loaded image.
          */
-        onSizeChange?: (size?: Size) => void;
+        onSizeChange?: (size?: Size.Size) => void;
     } & Omit<ImgHTMLAttributes<HTMLImageElement>, 'alt' | 'loading' | 'onError' | 'onLoad' | 'onLoadStart' | 'sizes' | 'src' | 'srcSet'>;
 }
 /**

package/build/primitives/Panorama.d.ts

@@ -77,7 +77,7 @@ export declare namespace Panorama {
          * @param size The actual size of the loaded image. If no images are loaded
          *               yet, the size is `undefined`.
          */
-        onImageSizeChange?: (size?: Size) => void;
+        onImageSizeChange?: (size?: Size.Size) => void;
     } & Omit<HTMLAttributes<HTMLDivElement>, 'aria-valuenow' | 'role'>;
 }
 /**

package/build/primitives/ScrollableCarousel.d.ts

@@ -0,0 +1,82 @@
+import { ComponentType, HTMLAttributes, Ref } from 'react';
+export declare namespace ScrollableCarousel {
+    /**
+     * Type describing the orientation of {@link ScrollableCarousel}.
+     */
+    type Orientation = 'horizontal' | 'vertical';
+    /**
+     * Type describing the props of {@link ScrollableCarousel}.
+     */
+    type Props<I> = {
+        /**
+         * Reference to the root element.
+         */
+        ref?: Ref<HTMLDivElement>;
+        /**
+         * Current item index.
+         */
+        index?: number;
+        /**
+         * The interval in milliseconds to wait before automatically advancing to
+         * the next item (auto loops).
+         */
+        autoAdvanceInterval?: number;
+        /**
+         * Whether the carousel is draggable.
+         */
+        isDragEnabled?: boolean;
+        /**
+         * Props for each item component
+         */
+        items?: Omit<I, 'exposure'>[];
+        /**
+         * Orientation of the carousel.
+         */
+        orientation?: Orientation;
+        /**
+         * The drag speed multiplier. Higher values result in faster dragging. The
+         * default value is `1`. This is only applicable when dragging with a
+         * non-touch pointer (e.g. mouse).
+         */
+        dragSpeed?: number;
+        /**
+         * Whether to track item exposure (0-1, 0 meaning the item is fully scrolled
+         * out of view, 1 meaning the item is fully scrolled into view).
+         */
+        shouldTrackExposure?: boolean;
+        /**
+         * Handler invoked when auto advance pauses. This is invoked only when
+         * {@link autoAdvanceInterval} is greater than 0.
+         */
+        onAutoAdvancePause?: () => void;
+        /**
+         * Handler invoked when auto advance resumes. This is invoked only when
+         * {@link autoAdvanceInterval} is greater than 0.
+         */
+        onAutoAdvanceResume?: () => void;
+        /**
+         * Handler invoked when the item index changes.
+         *
+         * @param index The item index.
+         */
+        onIndexChange?: (index: number) => void;
+        /**
+         * The component to render for each item.
+         */
+        ItemComponent: ComponentType<I>;
+    } & Omit<HTMLAttributes<HTMLDivElement>, 'onClick' | 'onPointerCancel' | 'onPointerDown' | 'onPointerLeave' | 'onPointerUp' | 'role'>;
+}
+/**
+ * A carousel component that displays a list of items in a scrollable view.
+ *
+ * Notable features:
+ *   - Supports horizontal and vertical orientations.
+ *   - Supports auto-advancing to the next item after a specified interval.
+ *   - Supports auto-snapping to each item when scrolling.
+ *   - Supports tracking item exposure (0-1) to determine how much of the
+ *     current item is visible in the viewport.
+ */
+export declare function ScrollableCarousel<I extends HTMLAttributes<HTMLElement>>({ ref, autoAdvanceInterval, dragSpeed, index, ItemComponent, items, orientation, isDragEnabled, shouldTrackExposure, onAutoAdvancePause, onAutoAdvanceResume, onIndexChange, ...props }: ScrollableCarousel.Props<I>): import("react/jsx-runtime").JSX.Element;
+export declare namespace ScrollableCarousel {
+    var displayName: string;
+}

package/build/primitives/Select.d.ts

@@ -7,7 +7,7 @@ import { HTMLAttributes, Ref } from 'react';
  * @exports Select.Option Component for each option.
  * @exports Select.Toggle Component for the toggle.
  */
-export declare function Select<T extends string>({ id, ref, children, formatValue, name, options, placeholder, value, isRequired, onChange, ...props }: Select.Props<T>): import("react/jsx-runtime").JSX.Element;
+export declare function Select<T extends string>({ id, ref, children, name, options, placeholder, value, isRequired, formatValue, onChange, ...props }: Select.Props<T>): import("react/jsx-runtime").JSX.Element;
 export declare namespace Select {
     var displayName: string;
 }

package/build/primitives/Video.d.ts

@@ -77,7 +77,7 @@ export declare namespace Video {
          *
          * @param size The new size of the video.
          */
-        onSizeChange?: (size?: Size) => void;
+        onSizeChange?: (size?: Size.Size) => void;
         /**
          * Handler invoked when the video time updates.
          *

package/build/utils/measureIntrinsicSize.d.ts

@@ -9,4 +9,4 @@ import { Size } from 'spase';
  * @returns The intrinsic size of the element, considering the max width
  *          constraint if provided.
  */
-export declare function measureIntrinsicSize(element: HTMLElement, maxWidth?: number): Size;
+export declare function measureIntrinsicSize(element: HTMLElement, maxWidth?: number): Size.Size;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "etudes",
-  "version": "28.2.2",
+  "version": "29.0.0",
   "description": "A study of headless React components",
   "type": "module",
   "sideEffects": false,
@@ -24,7 +24,8 @@
     "prepages": "rimraf .gh-pages",
     "pages": "vite build -c demo/vite.config.ts",
     "dev": "concurrently \"vite build -w\" \"wait-on build && vite dev --host -c demo/vite.config.ts --port 8080\"",
-    "test": "vitest run --coverage",
+    "test": "npm run test:unit",
+    "test:unit": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "lint": "eslint",
     "lint:fix": "eslint --fix"
@@ -42,40 +43,40 @@
   "author": "Andrew Wei <andrewscwei@gmail.com>",
   "license": "MIT",
   "devDependencies": {
-    "@commitlint/config-conventional": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.3",
     "@eslint/js": "^10.0.1",
     "@semantic-release/git": "^10.0.1",
     "@stylistic/eslint-plugin": "^5.10.0",
-    "@tailwindcss/vite": "^4.2.2",
+    "@tailwindcss/vite": "^4.2.4",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.6.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
-    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/coverage-v8": "^4.1.5",
     "concurrently": "^9.2.1",
-    "eslint": "^10.2.0",
-    "eslint-plugin-perfectionist": "^5.8.0",
+    "eslint": "^10.3.0",
+    "eslint-plugin-perfectionist": "^5.9.0",
     "happy-dom": "^20.9.0",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "rimraf": "^6.1.3",
     "semantic-release": "^25.0.3",
-    "tailwindcss": "^4.2.2",
-    "typescript": "^6.0.2",
-    "typescript-eslint": "^8.58.2",
-    "vite": "^8.0.8",
-    "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.1.4",
+    "tailwindcss": "^4.2.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.2",
+    "vite": "^8.0.11",
+    "vite-plugin-dts": "^5.0.0",
+    "vitest": "^4.1.5",
     "wait-on": "^9.0.5"
   },
   "dependencies": {
     "clsx": "^2.1.1",
     "fast-deep-equal": "^3.1.3",
-    "fast-xml-parser": "^5.6.0",
+    "fast-xml-parser": "^5.7.3",
     "interactjs": "^1.10.27",
-    "spase": "^12.1.0"
+    "spase": "^13.1.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"