beez-ui 2.7.1 → 3.0.1

package/dist/components/carousel.d.ts

@@ -1,55 +1,71 @@
 /**
- * Carousel on Embla with Arc's carousel design (https://uiarc.dev, MIT License, see THIRD_PARTY_NOTICES.md): round
- * outlined controls on the surface that answer hover on fine pointers and press in, a grab cursor while the track can
- * be dragged, Home and End to reach the edges, and optional Arc indicators whose pill stretches and travels with the
- * slides frame by frame. Embla keeps dragging, snapping, looping and plugins.
+ * Arc's Carousel (https://uiarc.dev, MIT License, see THIRD_PARTY_NOTICES.md) as a closed component: one child per
+ * slide, a centered slide row that is dragged, flicked or arrowed through, and a control row under it with an optional
+ * rotation control, the indicator tab list and the arrows. Embla runs inside and is never exposed; the beez-ui
+ * extensions (`loop`, `duration`, `watchFocus`, `onSettle`, deferred re-initialization, labels and visibility of the
+ * controls) cover media viewers that used Embla's API directly.
  */
 import * as React from "react";
-import useEmblaCarousel, { type UseEmblaCarouselType } from "embla-carousel-react";
-import { type CarouselOrientation } from "../constants/carousel.js";
-import { ControlButton } from "./control-button.js";
-type CarouselApi = UseEmblaCarouselType[1];
-type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
-type CarouselOptions = UseCarouselParameters[0];
-type CarouselPlugin = UseCarouselParameters[1];
+/** Props of {@link Carousel}: Arc's carousel API plus the beez-ui extensions marked below. */
 type CarouselProps = {
-    opts?: CarouselOptions;
-    plugins?: CarouselPlugin;
-    orientation?: CarouselOrientation;
-    setApi?: (api: CarouselApi) => void;
-};
-type CarouselContextProps = {
-    carouselRef: ReturnType<typeof useEmblaCarousel>[0];
-    api: ReturnType<typeof useEmblaCarousel>[1];
-    scrollPrev: () => void;
-    scrollNext: () => void;
-    canScrollPrev: boolean;
-    canScrollNext: boolean;
-} & CarouselProps;
-declare function useCarousel(): CarouselContextProps;
-declare function Carousel({ orientation, opts, setApi, plugins, className, children, ...props }: React.ComponentProps<"div"> & CarouselProps): React.JSX.Element;
-/**
- * The clipped viewport and the slide track. While the track can be dragged it shows Arc's grab cursor on fine
- * pointers, and a grabbing cursor while a drag is held.
- */
-declare function CarouselContent({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
-declare function CarouselItem({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
-declare function CarouselPrevious({ className, variant, size, ...props }: React.ComponentProps<typeof ControlButton>): React.JSX.Element;
-declare function CarouselNext({ className, variant, size, ...props }: React.ComponentProps<typeof ControlButton>): React.JSX.Element;
-type CarouselIndicatorsProps = Omit<React.ComponentProps<"div">, "children"> & {
-    /** Accessible name of the indicator list. Defaults to "Elegir una diapositiva". */
-    label?: string;
-    /** Names each indicator. Defaults to "Diapositiva 2 de 5". */
+    /** Names the carousel for assistive technology, for example "Fotos del encuentro". */
+    label: string;
+    /** One child per slide. Give each a stable `key` when the list can change. */
+    children: React.ReactNode;
+    /** Controlled active slide. Pair with `onIndexChange`. */
+    index?: number;
+    /** Initial slide when uncontrolled. Defaults to 0. */
+    defaultIndex?: number;
+    /** Called as soon as the active slide changes, when the scroll toward it starts. */
+    onIndexChange?: (index: number) => void;
+    /** Width of one slide as a CSS length; `cqw` is a share of the carousel width. Defaults to `min(80cqw, 340px)`. */
+    slideSize?: string;
+    /** Names each slide and its indicator. Defaults to "Diapositiva 2 de 5". */
     slideLabel?: (index: number, count: number) => string;
+    /**
+     * Milliseconds per slide. Adds a play control that rotates through the slides; rotation pauses on hover, keyboard
+     * focus, drag, offscreen and in hidden tabs; with reduced motion the control stays but is disabled.
+     */
+    interval?: number;
+    /** Starts rotating on mount. Off by default, so motion begins with the viewer. */
+    autoplay?: boolean;
+    /** Class of the root section. */
+    className?: string;
+    /** beez-ui: wraps from the last slide to the first and back. Defaults to `false`. */
+    loop?: boolean;
+    /** beez-ui: speed of a scroll between slides, in Embla's units (higher is slower). Defaults to Embla's 25. */
+    duration?: number;
+    /**
+     * beez-ui: scrolls to a slide when something inside it receives focus. Defaults to `true`; turn it off when a slide
+     * holds content that keeps focus, such as an embedded player, so it never pulls the carousel back.
+     */
+    watchFocus?: boolean;
+    /** beez-ui: called once a scroll has come to rest on a slide, the moment to mount heavy slide content. */
+    onSettle?: (index: number) => void;
+    /** beez-ui: accessible name of the previous arrow. Defaults to "Diapositiva anterior". */
+    previousLabel?: string;
+    /** beez-ui: accessible name of the next arrow. Defaults to "Diapositiva siguiente". */
+    nextLabel?: string;
+    /** beez-ui: shows the previous and next arrows. Defaults to `true`. */
+    showControls?: boolean;
+    /** beez-ui: shows the indicator tab list. Defaults to `true`. */
+    showIndicators?: boolean;
+    /** beez-ui: class added to every slide panel. */
+    slideClassName?: string;
+    /**
+     * beez-ui: class of the clipped, focusable viewport around the slide track, for example to give a media viewer a
+     * definite height.
+     */
+    viewportClassName?: string;
+    /** beez-ui: class of the slide track inside the viewport, which lays the slides out in a row. */
+    trackClassName?: string;
 };
 /**
- * Arc's page indicator for a carousel: one dot per snap point, where the current one stretches into a pill that
- * follows the track frame by frame while it is dragged or scrolled. The dots are buttons in a named group and the
- * current one carries `aria-current`; activating a dot scrolls to its slide, and when a dot has focus the carousel's
- * arrow, Home and End keys move the focus to the dot of the new slide. It renders
- * once Embla has measured the slides. Place it inside `Carousel`.
- * @param props - Optional accessible copy plus native attributes of the list.
- * @returns The indicator list, or nothing until there is more than one snap point.
+ * A centered row of slides browsed by drag, flick, the arrow keys, Home and End, the arrows or the indicator tabs, with
+ * optional rotation. Neighbouring slides stay in view as a hint that there is more, and are inert until selected.
+ * @param props - Arc's carousel props plus the beez-ui extensions.
+ * @returns The carousel section.
  */
-declare function CarouselIndicators({ className, label, slideLabel, ...props }: CarouselIndicatorsProps): React.JSX.Element | null;
-export { type CarouselApi, type CarouselIndicatorsProps, Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext, CarouselIndicators, useCarousel, };
+declare function Carousel({ label, children, index: controlledIndex, defaultIndex, onIndexChange, slideSize, slideLabel, interval, autoplay, className, loop, duration, watchFocus, onSettle, previousLabel, nextLabel, showControls, showIndicators, slideClassName, viewportClassName, trackClassName, }: CarouselProps): React.JSX.Element;
+export { Carousel };
+export type { CarouselProps };