beez-ui 2.7.1 → 3.0.0

package/dist/components/primitives/carousel.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Internal carousel composition on Embla with Arc's carousel design (https://uiarc.dev, MIT License, see
+ * THIRD_PARTY_NOTICES.md): a focusable, draggable slide area with Arc's grab cursor, round outlined controls on the
+ * surface that answer hover on fine pointers and press in, Home and End to reach the edges, and Arc's indicator tab list
+ * whose pill stretches and travels with the slides frame by frame. Embla keeps dragging, snapping and looping.
+ *
+ * Not exported from the package: the public `Carousel` (`../carousel.tsx`) composes these parts behind Arc's closed API.
+ */
+import * as React from "react";
+import useEmblaCarousel, { type UseEmblaCarouselType } from "embla-carousel-react";
+import type { MotionValue } from "motion/react";
+import { ControlButton } from "../control-button.js";
+/** Embla's API, kept inside beez-ui. */
+type CarouselApi = UseEmblaCarouselType[1];
+/** Embla options the public carousel forwards. */
+type CarouselOptions = Parameters<typeof useEmblaCarousel>[0];
+type CarouselProps = {
+    /** Embla options. Keep the object's values stable: Embla re-initializes when they change. */
+    opts?: CarouselOptions;
+    /** Receives Embla's API once it is created, and `undefined` when it is destroyed. */
+    setApi?: (api: CarouselApi) => void;
+};
+type CarouselContextProps = {
+    carouselRef: ReturnType<typeof useEmblaCarousel>[0];
+    api: CarouselApi;
+    opts?: CarouselOptions;
+    scrollPrev: () => void;
+    scrollNext: () => void;
+    canScrollPrev: boolean;
+    canScrollNext: boolean;
+};
+/**
+ * Reads the carousel the part is rendered in.
+ * @returns The shared Embla API, scroll actions and edge state.
+ */
+declare function useCarousel(): CarouselContextProps;
+/**
+ * The carousel root: a named section that owns the arrow, Home and End keys pressed inside it.
+ * @param props - Embla options and API callback plus native section attributes.
+ * @returns The carousel section.
+ */
+declare function Carousel({ opts, setApi, className, children, ...props }: React.ComponentProps<"section"> & CarouselProps): React.JSX.Element;
+type CarouselContentProps = React.ComponentProps<"div"> & {
+    /** Accessible name of the focusable slide area. */
+    viewportLabel?: string;
+    /** Class of the clipped viewport around the slide track. */
+    viewportClassName?: string;
+};
+/**
+ * The clipped, focusable 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. A click on a neighbouring slide selects it, as in Arc.
+ * @param props - Viewport copy and class plus native attributes of the track.
+ * @returns The viewport holding the track.
+ */
+declare function CarouselContent({ className, viewportLabel, viewportClassName, ...props }: CarouselContentProps): React.JSX.Element;
+/**
+ * One slide. Its trailing margin is the gap to the next slide, so Embla measures it and centers the slide itself. It is
+ * a group described as a slide; pass `role="tabpanel"` only when indicator tabs control it.
+ * @param props - Native attributes of the slide panel.
+ * @returns The slide panel.
+ */
+declare function CarouselItem({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+/**
+ * Moves to the previous slide. It stays focusable and reports `aria-disabled` at the first slide, so focus is never
+ * lost when the carousel reaches its edge.
+ * @param props - Control button attributes; `aria-label` defaults to "Diapositiva anterior".
+ * @returns The previous control.
+ */
+declare function CarouselPrevious({ className, onClick, ...props }: React.ComponentProps<typeof ControlButton>): React.JSX.Element;
+/**
+ * Moves to the next slide. It stays focusable and reports `aria-disabled` at the last slide.
+ * @param props - Control button attributes; `aria-label` defaults to "Diapositiva siguiente".
+ * @returns The next control.
+ */
+declare function CarouselNext({ className, onClick, ...props }: React.ComponentProps<typeof ControlButton>): React.JSX.Element;
+/**
+ * Default accessible name of one slide and its indicator, for example "Diapositiva 2 de 5".
+ * @param index - Zero-based slide position.
+ * @param count - Number of slides.
+ * @returns The Spanish slide label.
+ */
+declare function defaultCarouselSlideLabel(index: number, count: number): string;
+type CarouselIndicatorsProps = Omit<React.ComponentProps<"div">, "children"> & {
+    /** Accessible name of the indicator tab list. Defaults to "Elegir una diapositiva". */
+    label?: string;
+    /** Names each indicator. Defaults to "Diapositiva 2 de 5". */
+    slideLabel?: (index: number, count: number) => string;
+    /** Id of the slide panel an indicator controls. */
+    getSlideId?: (index: number) => string;
+    /** Rotation time spent on the selected slide, from 0 to 1; it drains the selected pill from its end. */
+    drain?: MotionValue<number>;
+    /** Snap points expected before Embla measures, so server-rendered tabs keep their place. Defaults to 0. */
+    initialCount?: number;
+    /** Selected snap expected before Embla measures. Defaults to 0. */
+    initialIndex?: number;
+};
+/**
+ * Arc's page indicator: a tab per snap point, where the selected one stretches into a pill that follows the track frame
+ * by frame while it is dragged or scrolled. Only the selected tab is in the tab order; activating a tab scrolls to its
+ * slide, and while a tab has focus the carousel's arrow, Home and End keys move the focus to the tab of the new slide.
+ * It renders once Embla has measured the slides, or from `initialCount` until then. Place it inside `Carousel`.
+ * @param props - Optional accessible copy, slide ids and rotation drain plus native attributes of the list.
+ * @returns The indicator tab list, or nothing until there is more than one snap point.
+ */
+declare function CarouselIndicators({ className, label, slideLabel, getSlideId, drain, initialCount, initialIndex, ...props }: CarouselIndicatorsProps): React.JSX.Element | null;
+export { type CarouselApi, type CarouselOptions, type CarouselIndicatorsProps, Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext, CarouselIndicators, defaultCarouselSlideLabel, useCarousel, };