@ycparak/spring-carousel 0.0.0-stage → 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,158 @@
+import * as react from 'react';
+import { ComponentProps } from 'react';
+
+type ProgressListener = (progress: number) => void;
+/**
+ * The carousel's continuous position, in slides: 0 is the first slide, 1.5 is
+ * halfway between the second and third. It changes every animation frame without
+ * re-rendering React; read it with `get()` or listen with `subscribe()`.
+ */
+interface CarouselProgress {
+    get(): number;
+    /** Slides per second. */
+    getVelocity(): number;
+    /** Calls `listener` immediately with the current value, then on every change. */
+    subscribe(listener: ProgressListener): () => void;
+}
+
+/**
+ * Physical spring parameters. Defaults reproduce the original Kami carousel.
+ */
+interface PhysicalSpring {
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    duration?: never;
+    bounce?: never;
+}
+/**
+ * Perceptual spring parameters, as in SwiftUI and Motion's `visualDuration`.
+ * `duration` is in seconds; `bounce` runs from -1 (overdamped) through 0 (critically
+ * damped) to 1 (undamped).
+ */
+interface PerceptualSpring {
+    duration: number;
+    bounce?: number;
+    stiffness?: never;
+    damping?: never;
+    mass?: never;
+}
+type SpringOptions = PhysicalSpring | PerceptualSpring;
+
+type KeyboardMode = 'focus' | 'global' | false;
+type ReducedMotionMode = 'user' | 'always' | 'never';
+interface NavigateOptions {
+    /** Set to false to move instantly. Defaults to true. */
+    animate?: boolean;
+    /** Starting velocity in slides per second. Defaults to the current velocity. */
+    velocity?: number;
+}
+
+interface SlideContextValue {
+    index: number;
+    isActive: boolean;
+}
+
+interface CarouselApi {
+    /** The slide the carousel is on, or heading to. */
+    index: number;
+    /** How many slides are mounted. 0 until the first client render. */
+    count: number;
+    /** True while a pointer is dragging the slides. */
+    isDragging: boolean;
+    canPrev: boolean;
+    canNext: boolean;
+    goTo: (index: number, options?: NavigateOptions) => void;
+    next: (options?: NavigateOptions) => void;
+    prev: (options?: NavigateOptions) => void;
+    /** The continuous position, updated every frame without re-rendering. */
+    progress: CarouselProgress;
+}
+/**
+ * Reads the carousel's state and controls from any component inside
+ * `<Carousel.Root>`. Re-renders when the index, count or drag state changes, never
+ * per frame; use `useCarouselProgress` for per-frame work.
+ */
+declare function useCarousel(): CarouselApi;
+/**
+ * Calls `listener` with the carousel's position on every frame it moves, and once
+ * on mount. Use it to drive styles imperatively (captions, parallax, progress bars)
+ * without re-rendering. The listener always sees the latest props and state.
+ */
+declare function useCarouselProgress(listener: ProgressListener): void;
+/** Reads the enclosing `<Carousel.Slide>`'s index and whether it is the current slide. */
+declare function useSlide(): SlideContextValue;
+
+/** How present an item is at a given progress: 1 when it is the current slide, 0 a slide or more away. */
+declare function presence(progress: number, index: number): number;
+
+interface RootProps extends ComponentProps<'section'> {
+    /** The current slide, for a controlled carousel. Pair with `onIndexChange`. */
+    index?: number;
+    /** The slide to start on, for an uncontrolled carousel. Defaults to 0. */
+    defaultIndex?: number;
+    /** Called when a gesture, key, tab or button asks for a new slide. */
+    onIndexChange?: (index: number) => void;
+    /**
+     * The spring that moves the carousel: `{ stiffness, damping, mass }` or
+     * `{ duration, bounce }` with `duration` in seconds.
+     * Defaults to `{ stiffness: 90, damping: 18.1, mass: 0.9 }`.
+     */
+    spring?: SpringOptions;
+    /**
+     * Where arrow keys move the carousel: `"focus"` when focus is inside it, `"global"`
+     * anywhere on the page outside text fields and other arrow-key widgets, or `false`.
+     * Defaults to `"focus"`.
+     */
+    keyboard?: KeyboardMode;
+    /** Lets horizontal trackpad swipes page through slides. Defaults to true. */
+    wheel?: boolean;
+    /** Lets pointers drag the slides. Defaults to true. */
+    draggable?: boolean;
+    /**
+     * `"user"` follows `prefers-reduced-motion`, `"always"` moves instantly and
+     * `"never"` always animates. Defaults to `"user"`.
+     */
+    reducedMotion?: ReducedMotionMode;
+}
+declare function CarouselRoot({ index: indexProp, defaultIndex, onIndexChange, spring, keyboard, wheel, draggable, reducedMotion, ref, style, children, ...props }: RootProps): react.JSX.Element;
+type ViewportProps = ComponentProps<'div'>;
+declare function CarouselViewport({ ref, ...props }: ViewportProps): react.JSX.Element;
+type TrackProps = ComponentProps<'div'>;
+declare function CarouselTrack({ ref, ...props }: TrackProps): react.JSX.Element;
+interface SlideProps extends ComponentProps<'div'> {
+    /** This slide's position, from 0. Indexes must run 0, 1, 2… without gaps. */
+    index: number;
+}
+declare function CarouselSlide({ index, ref, style, children, ...props }: SlideProps): react.JSX.Element;
+type TabsProps = ComponentProps<'div'>;
+declare function CarouselTabs({ ref, ...props }: TabsProps): react.JSX.Element;
+interface TabProps extends ComponentProps<'button'> {
+    /** The index of the slide this tab shows. */
+    index: number;
+}
+declare function CarouselTab({ index, ref, style, onClick, ...props }: TabProps): react.JSX.Element;
+type PrevProps = ComponentProps<'button'>;
+type NextProps = ComponentProps<'button'>;
+/**
+ * Stays focusable at the first slide (with `aria-disabled`) so keyboard focus is
+ * not dropped to the page when it stops being useful.
+ */
+declare function CarouselPrev({ onClick, children, ...props }: PrevProps): react.JSX.Element;
+declare function CarouselNext({ onClick, children, ...props }: NextProps): react.JSX.Element;
+
+type parts_NextProps = NextProps;
+type parts_PrevProps = PrevProps;
+type parts_RootProps = RootProps;
+type parts_SlideProps = SlideProps;
+type parts_TabProps = TabProps;
+type parts_TabsProps = TabsProps;
+type parts_TrackProps = TrackProps;
+type parts_ViewportProps = ViewportProps;
+declare namespace parts {
+  export { CarouselNext as Next, CarouselPrev as Prev, CarouselRoot as Root, CarouselSlide as Slide, CarouselTab as Tab, CarouselTabs as Tabs, CarouselTrack as Track, CarouselViewport as Viewport };
+  export type { parts_NextProps as NextProps, parts_PrevProps as PrevProps, parts_RootProps as RootProps, parts_SlideProps as SlideProps, parts_TabProps as TabProps, parts_TabsProps as TabsProps, parts_TrackProps as TrackProps, parts_ViewportProps as ViewportProps };
+}
+
+export { parts as Carousel, presence, useCarousel, useCarouselProgress, useSlide };
+export type { CarouselApi, CarouselProgress, KeyboardMode, NavigateOptions, NextProps, PerceptualSpring, PhysicalSpring, PrevProps, ProgressListener, ReducedMotionMode, RootProps, SlideContextValue, SlideProps, SpringOptions, TabProps, TabsProps, TrackProps, ViewportProps };

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+import * as react from 'react';
+import { ComponentProps } from 'react';
+
+type ProgressListener = (progress: number) => void;
+/**
+ * The carousel's continuous position, in slides: 0 is the first slide, 1.5 is
+ * halfway between the second and third. It changes every animation frame without
+ * re-rendering React; read it with `get()` or listen with `subscribe()`.
+ */
+interface CarouselProgress {
+    get(): number;
+    /** Slides per second. */
+    getVelocity(): number;
+    /** Calls `listener` immediately with the current value, then on every change. */
+    subscribe(listener: ProgressListener): () => void;
+}
+
+/**
+ * Physical spring parameters. Defaults reproduce the original Kami carousel.
+ */
+interface PhysicalSpring {
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    duration?: never;
+    bounce?: never;
+}
+/**
+ * Perceptual spring parameters, as in SwiftUI and Motion's `visualDuration`.
+ * `duration` is in seconds; `bounce` runs from -1 (overdamped) through 0 (critically
+ * damped) to 1 (undamped).
+ */
+interface PerceptualSpring {
+    duration: number;
+    bounce?: number;
+    stiffness?: never;
+    damping?: never;
+    mass?: never;
+}
+type SpringOptions = PhysicalSpring | PerceptualSpring;
+
+type KeyboardMode = 'focus' | 'global' | false;
+type ReducedMotionMode = 'user' | 'always' | 'never';
+interface NavigateOptions {
+    /** Set to false to move instantly. Defaults to true. */
+    animate?: boolean;
+    /** Starting velocity in slides per second. Defaults to the current velocity. */
+    velocity?: number;
+}
+
+interface SlideContextValue {
+    index: number;
+    isActive: boolean;
+}
+
+interface CarouselApi {
+    /** The slide the carousel is on, or heading to. */
+    index: number;
+    /** How many slides are mounted. 0 until the first client render. */
+    count: number;
+    /** True while a pointer is dragging the slides. */
+    isDragging: boolean;
+    canPrev: boolean;
+    canNext: boolean;
+    goTo: (index: number, options?: NavigateOptions) => void;
+    next: (options?: NavigateOptions) => void;
+    prev: (options?: NavigateOptions) => void;
+    /** The continuous position, updated every frame without re-rendering. */
+    progress: CarouselProgress;
+}
+/**
+ * Reads the carousel's state and controls from any component inside
+ * `<Carousel.Root>`. Re-renders when the index, count or drag state changes, never
+ * per frame; use `useCarouselProgress` for per-frame work.
+ */
+declare function useCarousel(): CarouselApi;
+/**
+ * Calls `listener` with the carousel's position on every frame it moves, and once
+ * on mount. Use it to drive styles imperatively (captions, parallax, progress bars)
+ * without re-rendering. The listener always sees the latest props and state.
+ */
+declare function useCarouselProgress(listener: ProgressListener): void;
+/** Reads the enclosing `<Carousel.Slide>`'s index and whether it is the current slide. */
+declare function useSlide(): SlideContextValue;
+
+/** How present an item is at a given progress: 1 when it is the current slide, 0 a slide or more away. */
+declare function presence(progress: number, index: number): number;
+
+interface RootProps extends ComponentProps<'section'> {
+    /** The current slide, for a controlled carousel. Pair with `onIndexChange`. */
+    index?: number;
+    /** The slide to start on, for an uncontrolled carousel. Defaults to 0. */
+    defaultIndex?: number;
+    /** Called when a gesture, key, tab or button asks for a new slide. */
+    onIndexChange?: (index: number) => void;
+    /**
+     * The spring that moves the carousel: `{ stiffness, damping, mass }` or
+     * `{ duration, bounce }` with `duration` in seconds.
+     * Defaults to `{ stiffness: 90, damping: 18.1, mass: 0.9 }`.
+     */
+    spring?: SpringOptions;
+    /**
+     * Where arrow keys move the carousel: `"focus"` when focus is inside it, `"global"`
+     * anywhere on the page outside text fields and other arrow-key widgets, or `false`.
+     * Defaults to `"focus"`.
+     */
+    keyboard?: KeyboardMode;
+    /** Lets horizontal trackpad swipes page through slides. Defaults to true. */
+    wheel?: boolean;
+    /** Lets pointers drag the slides. Defaults to true. */
+    draggable?: boolean;
+    /**
+     * `"user"` follows `prefers-reduced-motion`, `"always"` moves instantly and
+     * `"never"` always animates. Defaults to `"user"`.
+     */
+    reducedMotion?: ReducedMotionMode;
+}
+declare function CarouselRoot({ index: indexProp, defaultIndex, onIndexChange, spring, keyboard, wheel, draggable, reducedMotion, ref, style, children, ...props }: RootProps): react.JSX.Element;
+type ViewportProps = ComponentProps<'div'>;
+declare function CarouselViewport({ ref, ...props }: ViewportProps): react.JSX.Element;
+type TrackProps = ComponentProps<'div'>;
+declare function CarouselTrack({ ref, ...props }: TrackProps): react.JSX.Element;
+interface SlideProps extends ComponentProps<'div'> {
+    /** This slide's position, from 0. Indexes must run 0, 1, 2… without gaps. */
+    index: number;
+}
+declare function CarouselSlide({ index, ref, style, children, ...props }: SlideProps): react.JSX.Element;
+type TabsProps = ComponentProps<'div'>;
+declare function CarouselTabs({ ref, ...props }: TabsProps): react.JSX.Element;
+interface TabProps extends ComponentProps<'button'> {
+    /** The index of the slide this tab shows. */
+    index: number;
+}
+declare function CarouselTab({ index, ref, style, onClick, ...props }: TabProps): react.JSX.Element;
+type PrevProps = ComponentProps<'button'>;
+type NextProps = ComponentProps<'button'>;
+/**
+ * Stays focusable at the first slide (with `aria-disabled`) so keyboard focus is
+ * not dropped to the page when it stops being useful.
+ */
+declare function CarouselPrev({ onClick, children, ...props }: PrevProps): react.JSX.Element;
+declare function CarouselNext({ onClick, children, ...props }: NextProps): react.JSX.Element;
+
+type parts_NextProps = NextProps;
+type parts_PrevProps = PrevProps;
+type parts_RootProps = RootProps;
+type parts_SlideProps = SlideProps;
+type parts_TabProps = TabProps;
+type parts_TabsProps = TabsProps;
+type parts_TrackProps = TrackProps;
+type parts_ViewportProps = ViewportProps;
+declare namespace parts {
+  export { CarouselNext as Next, CarouselPrev as Prev, CarouselRoot as Root, CarouselSlide as Slide, CarouselTab as Tab, CarouselTabs as Tabs, CarouselTrack as Track, CarouselViewport as Viewport };
+  export type { parts_NextProps as NextProps, parts_PrevProps as PrevProps, parts_RootProps as RootProps, parts_SlideProps as SlideProps, parts_TabProps as TabProps, parts_TabsProps as TabsProps, parts_TrackProps as TrackProps, parts_ViewportProps as ViewportProps };
+}
+
+export { parts as Carousel, presence, useCarousel, useCarouselProgress, useSlide };
+export type { CarouselApi, CarouselProgress, KeyboardMode, NavigateOptions, NextProps, PerceptualSpring, PhysicalSpring, PrevProps, ProgressListener, ReducedMotionMode, RootProps, SlideContextValue, SlideProps, SpringOptions, TabProps, TabsProps, TrackProps, ViewportProps };