etudes 31.0.0 → 32.0.0

package/build/hooks/useDrag.d.ts

@@ -43,7 +43,6 @@ export type UseDragOptions = {
  *
  * @param target The target element or reference
  * @param options Additional options.
- * @param deps Dependencies that trigger this effect.
  *
  * @returns The states created for this effect.
  */

package/build/hooks/{useScrollPosition.d.ts → useScrollPositionObserver.d.ts}

@@ -15,6 +15,6 @@ type Target = HTMLElement | null | RefObject<HTMLElement> | RefObject<HTMLElemen
  * @param onChange Handler invoked when the scroll position changes.
  * @param deps Optional dependency list to control when the hook should re-run.
  */
-export declare function useScrollPosition(target: Target, onChange: (newInfo: ScrollPositionInfo, oldInfo: ScrollPositionInfo | undefined) => void, deps?: DependencyList): void;
-export declare function useScrollPosition(onChange: (newInfo: ScrollPositionInfo, oldInfo: ScrollPositionInfo | undefined) => void, deps?: DependencyList): void;
+export declare function useScrollPositionObserver(target: Target, onChange: (newInfo: ScrollPositionInfo, oldInfo: ScrollPositionInfo | undefined) => void, deps?: DependencyList): void;
+export declare function useScrollPositionObserver(onChange: (newInfo: ScrollPositionInfo, oldInfo: ScrollPositionInfo | undefined) => void, deps?: DependencyList): void;
 export {};

package/build/index.d.ts

@@ -32,7 +32,7 @@ export * from './hooks/useMouseLeave.js';
 export * from './hooks/useOS.js';
 export * from './hooks/usePrevious.js';
 export * from './hooks/useRect.js';
-export * from './hooks/useScrollPosition.js';
+export * from './hooks/useScrollPositionObserver.js';
 export * from './hooks/useSessionCache.js';
 export * from './hooks/useSize.js';
 export * from './hooks/useSizeObserver.js';
@@ -65,6 +65,7 @@ export * from './primitives/TextArea.js';
 export * from './primitives/TextField.js';
 export * from './primitives/Toggle.js';
 export * from './primitives/Video.js';
+export * from './providers/ScrollPositionProvider.js';
 export * from './types/ImageSource.js';
 export * from './utils/asClassNameDict.js';
 export * from './utils/asComponentDict.js';

package/build/primitives/Image.d.ts

@@ -19,15 +19,14 @@ export declare namespace Image {
          */
         loadingMode?: 'eager' | 'lazy';
         /**
-         * Optional image source. If provided, this will be used to set the `sizes`
-         * and `srcSet` attributes of the `<img>` element.
+         * Either a string URL or a tuple of the form `[src, ImageSource]`, where
+         * `src` is a fallback image URL and `ImageSource` provides additional
+         * information for responsive images. If a tuple is provided, the `src` will
+         * be used as the `src` attribute of the `<img>` element, while the
+         * properties of `ImageSource` will be used to set the `sizes` and `srcSet`
+         * attributes.
          */
-        source?: Omit<ImageSource, 'media' | 'type'>;
-        /**
-         * Fallback image URL for browsers that do not support the `srcSet`
-         * attribute.
-         */
-        src: string;
+        source: [string, Omit<ImageSource, 'media' | 'type'>] | string;
         /**
          * Handler invoked when image load begins.
          */
@@ -52,7 +51,7 @@ export declare namespace Image {
  * A component that renders an image with support for lazy loading, `srcSet`,
  * and `sizes` attributes.
  */
-export declare function Image({ ref, alt, loadingMode, source, src: fallbackSrc, onError, onLoad, onLoadStart, onSizeChange, ...props }: Image.Props): import("react/jsx-runtime").JSX.Element;
+export declare function Image({ ref, alt, loadingMode, source, onError, onLoad, onLoadStart, onSizeChange, ...props }: Image.Props): import("react/jsx-runtime").JSX.Element;
 export declare namespace Image {
     var displayName: string;
 }

package/build/primitives/Picture.d.ts

@@ -10,10 +10,10 @@ export declare namespace Picture {
          * Reference to the root element.
          */
         ref?: Ref<HTMLPictureElement>;
-        sources?: ImageSource[];
-    } & HTMLAttributes<HTMLPictureElement> & Pick<Image.Props, 'alt' | 'loadingMode' | 'onError' | 'onLoad' | 'onLoadStart' | 'onSizeChange' | 'src'>;
+        source: [string, ...ImageSource[]] | string;
+    } & HTMLAttributes<HTMLPictureElement> & Pick<Image.Props, 'alt' | 'loadingMode' | 'onError' | 'onLoad' | 'onLoadStart' | 'onSizeChange'>;
 }
-export declare function Picture({ ref, alt, loadingMode, sources, src, onError, onLoad, onLoadStart, onSizeChange, ...props }: Picture.Props): import("react/jsx-runtime").JSX.Element;
+export declare function Picture({ ref, alt, loadingMode, source, onError, onLoad, onLoadStart, onSizeChange, ...props }: Picture.Props): import("react/jsx-runtime").JSX.Element;
 export declare namespace Picture {
     var displayName: string;
 }

package/build/primitives/RangeSlider.d.ts

@@ -8,7 +8,7 @@ import { HTMLAttributes, Ref } from 'react';
  * @exports RangeSlider.Track Component for the track.
  * @exports RangeSlider.TrackHighlight Component for the track highlight.
  */
-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 function RangeSlider({ 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;
 }

package/build/primitives/Slider.d.ts

@@ -13,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, orientation, position, trackPadding, isClipped, isInverted, isTrackInteractive, formatLabel, onChange, onDragEnd, onDragStart, ...props }: Readonly<Slider.Props>): import("react/jsx-runtime").JSX.Element;
+export declare function Slider({ 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;
 }

package/build/primitives/StepSlider.d.ts

@@ -18,7 +18,7 @@ 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, 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 function StepSlider({ 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;
 }

package/build/primitives/Video.d.ts

@@ -28,7 +28,7 @@ export declare namespace Video {
         /**
          * The URL of the video poster when video is unavailable or loading.
          */
-        posterSrc?: string;
+        poster?: string;
         /**
          * Reference to the root element.
          */
@@ -36,7 +36,7 @@ export declare namespace Video {
         /**
          * The URL of the video to play.
          */
-        src: string;
+        source: string;
         /**
          * Handler invoked when the video is ready to play.
          */
@@ -98,7 +98,7 @@ export declare namespace Video {
  *
  * @see {@link https://www.npmjs.com/package/hls.js}
  */
-export declare function Video({ ref, autoLoop, autoPlay, playsInline, posterSrc, src, hasControls, isMuted, onCanPlay, onEnd, onFullscreenChange, onLoadMetadata, onLoadMetadataComplete, onLoadMetadataError, onPause, onPlay, onSizeChange, onTimeUpdate, ...props }: Video.Props): import("react/jsx-runtime").JSX.Element;
+export declare function Video({ ref, autoLoop, autoPlay, playsInline, poster, source, hasControls, isMuted, onCanPlay, onEnd, onFullscreenChange, onLoadMetadata, onLoadMetadataComplete, onLoadMetadataError, onPause, onPlay, onSizeChange, onTimeUpdate, ...props }: Video.Props): import("react/jsx-runtime").JSX.Element;
 export declare namespace Video {
     var displayName: string;
 }

package/build/providers/ScrollPositionProvider.d.ts

@@ -0,0 +1,40 @@
+import { PropsWithChildren, RefObject } from 'react';
+import { Point } from 'spase';
+type Target = HTMLElement | null | RefObject<HTMLElement> | RefObject<HTMLElement | null> | RefObject<HTMLElement | undefined> | undefined;
+type ContextValue = {
+    current: Point.Point;
+    end: Point.Point;
+    progress: Point.Point;
+    start: Point.Point;
+};
+type ProviderProps = PropsWithChildren<{
+    target?: Target;
+}>;
+/**
+ * Provides scroll position information to its descendants.
+ */
+export declare function ScrollPositionProvider({ children, target, }: ProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to determine if the scroll position is at the top of the scrollable
+ * area.
+ *
+ * @returns `true` if the scroll position is at the top, `false` otherwise.
+ */
+export declare function useIsScrollTop(): boolean;
+/**
+ * Hook to determine if the scroll position is at the bottom of the scrollable
+ * area.
+ *
+ * @returns `true` if the scroll position is at the bottom, `false` otherwise.
+ */
+export declare function useIsScrollBottom(): boolean;
+/**
+ * Hook to access the current scroll position information from the nearest
+ * `ScrollPositionProvider` in the component tree.
+ *
+ * @returns The current scroll position information, including the current
+ *          scroll position. If the hook is used outside of a
+ *          `ScrollPositionProvider`, it will return zero values.
+ */
+export declare function useScrollPosition(): ContextValue;
+export {};

package/build/types/ImageSource.d.ts

@@ -53,6 +53,30 @@ export type ImageSource = {
     type?: string;
 };
 export declare namespace ImageSource {
+    /**
+     * Convenience function to create an `ImageSource` object from a list of image
+     * sources and a size descriptor.
+     *
+     * @param size A CSS size value indicating the size of the image's slot on the
+     *             page, i.e. `100px`, `100vw`, `50%`, etc.
+     * @param srcSet A list of tuples, where each tuple contains a URL specifying
+     *               an image location and either an intrinsic width (in pixels)
+     *               of the image expressed as a positive integer or a pixel
+     *               density of the image expressed as a positive floating number.
+     *
+     * @returns An `ImageSource` object with the specified size and image sources.
+     */
+    function make(size: string, srcSet: [string, number][]): ImageSource;
+    /**
+     * Converts an `ImageSource` object into props that can be spread onto a
+     * `<source>` or `<img>` element, including validation of the `ImageSource`
+     * object.
+     *
+     * @param imageSource The `ImageSource` object to convert into props.
+     *
+     * @returns An object containing the props to spread onto a `<source>` or
+     *          `<img>` element.
+     */
     function asProps(imageSource: ImageSource): {
         media: string | undefined;
         sizes: string | undefined;

package/package.json

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

package/build/utils/createLocalCache.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/build/utils/createSessionCache.spec.d.ts

@@ -1 +0,0 @@
-export {};