@skdx/react 0.27.0 → 0.29.0

package/dist/carousel/CarouselContent.d.ts

@@ -1,9 +1,7 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { CarouselContentProps } from './types.js';
 /**
- * Wrapper around the slide `CarouselItem`s: renders a plain `<div>` with
- * `data-orientation` reflecting the carousel's axis. Layout (e.g. hiding
- * overflow) is entirely up to your CSS.
+ * Slide wrapper and live region whose `aria-live` politeness follows `playing` state — `off` during autoplay, `polite` after.
  *
  * @example
  * ```tsx
@@ -13,4 +11,7 @@ import type { CarouselContentProps } from './types.js';
  * </CarouselContent>
  * ```
  */
-export declare const CarouselContent: React.ForwardRefExoticComponent<Omit<CarouselContentProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const CarouselContent: {
+    ({ ref: forwardedRef, ...props }: CarouselContentProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselIndicator.d.cts

@@ -0,0 +1,14 @@
+import type * as React from 'react';
+import type { CarouselIndicatorProps } from './types.cjs';
+/**
+ * Slide dot button that calls `scrollToIndex(index)` and carries `data-state` `"active"`/`"inactive"`, with `aria-disabled="true"` on the current slide.
+ *
+ * @example
+ * ```tsx
+ * <CarouselIndicator index={0} />
+ * ```
+ */
+export declare const CarouselIndicator: {
+    ({ index, label, ref: forwardedRef, ...props }: CarouselIndicatorProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselIndicator.d.ts

@@ -0,0 +1,14 @@
+import type * as React from 'react';
+import type { CarouselIndicatorProps } from './types.js';
+/**
+ * Slide dot button that calls `scrollToIndex(index)` and carries `data-state` `"active"`/`"inactive"`, with `aria-disabled="true"` on the current slide.
+ *
+ * @example
+ * ```tsx
+ * <CarouselIndicator index={0} />
+ * ```
+ */
+export declare const CarouselIndicator: {
+    ({ index, label, ref: forwardedRef, ...props }: CarouselIndicatorProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselIndicators.d.cts

@@ -0,0 +1,23 @@
+import type * as React from 'react';
+import type { CarouselIndicatorsProps } from './types.cjs';
+/**
+ * Container for slide dots — `role="group"` with `data-orientation`, since slides are not tabpanels.
+ *
+ * @example
+ * ```tsx
+ * function Dots() {
+ *   const { itemIds } = useCarouselContext('Dots');
+ *   return (
+ *     <CarouselIndicators aria-label="Slides">
+ *       {itemIds.map((id, index) => (
+ *         <CarouselIndicator key={id} index={index} />
+ *       ))}
+ *     </CarouselIndicators>
+ *   );
+ * }
+ * ```
+ */
+export declare const CarouselIndicators: {
+    ({ ref: forwardedRef, ...props }: CarouselIndicatorsProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselIndicators.d.ts

@@ -0,0 +1,23 @@
+import type * as React from 'react';
+import type { CarouselIndicatorsProps } from './types.js';
+/**
+ * Container for slide dots — `role="group"` with `data-orientation`, since slides are not tabpanels.
+ *
+ * @example
+ * ```tsx
+ * function Dots() {
+ *   const { itemIds } = useCarouselContext('Dots');
+ *   return (
+ *     <CarouselIndicators aria-label="Slides">
+ *       {itemIds.map((id, index) => (
+ *         <CarouselIndicator key={id} index={index} />
+ *       ))}
+ *     </CarouselIndicators>
+ *   );
+ * }
+ * ```
+ */
+export declare const CarouselIndicators: {
+    ({ ref: forwardedRef, ...props }: CarouselIndicatorsProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselItem.d.cts

@@ -1,12 +1,7 @@
 import * as React from 'react';
 import type { CarouselItemProps } from './types.cjs';
 /**
- * A single slide: `role="group"` with `aria-roledescription="slide"`,
- * `data-state` (`active`/`inactive`), and `data-orientation`. Registers
- * itself with the parent `Carousel` on mount to establish slide order.
- * Only the slides in the active window (`slidesPerPage` of them, starting at
- * the carousel's `value`) render content — the rest are present in the DOM but
- * `hidden`.
+ * A single slide in the carousel, rendered as `role="group"` with `data-state`; only slides in the active window render content.
  *
  * @example
  * ```tsx
@@ -16,4 +11,7 @@ import type { CarouselItemProps } from './types.cjs';
  * </CarouselContent>
  * ```
  */
-export declare const CarouselItem: React.ForwardRefExoticComponent<Omit<CarouselItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const CarouselItem: {
+    ({ ref: forwardedRef, ...props }: CarouselItemProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselItem.d.ts

@@ -1,12 +1,7 @@
 import * as React from 'react';
 import type { CarouselItemProps } from './types.js';
 /**
- * A single slide: `role="group"` with `aria-roledescription="slide"`,
- * `data-state` (`active`/`inactive`), and `data-orientation`. Registers
- * itself with the parent `Carousel` on mount to establish slide order.
- * Only the slides in the active window (`slidesPerPage` of them, starting at
- * the carousel's `value`) render content — the rest are present in the DOM but
- * `hidden`.
+ * A single slide in the carousel, rendered as `role="group"` with `data-state`; only slides in the active window render content.
  *
  * @example
  * ```tsx
@@ -16,4 +11,7 @@ import type { CarouselItemProps } from './types.js';
  * </CarouselContent>
  * ```
  */
-export declare const CarouselItem: React.ForwardRefExoticComponent<Omit<CarouselItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const CarouselItem: {
+    ({ ref: forwardedRef, ...props }: CarouselItemProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselNext.d.cts

@@ -1,14 +1,14 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { CarouselNextProps } from './types.cjs';
 /**
- * Button that steps forward by the carousel's `slidesPerMove` when clicked,
- * wrapping to the first slide when `loop` is enabled. Disabled (native
- * `disabled` plus `data-disabled`) once the last page is showing and `loop` is
- * `false`, or when there are no slides.
+ * Button that steps forward by `slidesPerMove`. Wraps to first slide if `loop` is enabled; disabled at carousel end when `loop` is false or if no slides.
  *
  * @example
  * ```tsx
  * <CarouselNext aria-label="Next slide">→</CarouselNext>
  * ```
  */
-export declare const CarouselNext: React.ForwardRefExoticComponent<Omit<CarouselNextProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const CarouselNext: {
+    ({ ref: forwardedRef, ...props }: CarouselNextProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselNext.d.ts

@@ -1,14 +1,14 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { CarouselNextProps } from './types.js';
 /**
- * Button that steps forward by the carousel's `slidesPerMove` when clicked,
- * wrapping to the first slide when `loop` is enabled. Disabled (native
- * `disabled` plus `data-disabled`) once the last page is showing and `loop` is
- * `false`, or when there are no slides.
+ * Button that steps forward by `slidesPerMove`. Wraps to first slide if `loop` is enabled; disabled at carousel end when `loop` is false or if no slides.
  *
  * @example
  * ```tsx
  * <CarouselNext aria-label="Next slide">→</CarouselNext>
  * ```
  */
-export declare const CarouselNext: React.ForwardRefExoticComponent<Omit<CarouselNextProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const CarouselNext: {
+    ({ ref: forwardedRef, ...props }: CarouselNextProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselPlayPause.d.cts

@@ -1,17 +1,17 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { CarouselPlayPauseProps } from './types.cjs';
 /**
- * The autoplay pause/resume control WCAG 2.2.2 requires next to any carousel
- * that moves on its own: a `<button>` carrying `data-state` of
- * `"playing"`/`"paused"`, which toggles the carousel's timer on click.
- *
- * It stays functional when `autoplay` is `false` — pressing it starts playback
- * — so the same control serves as a play button. Give it an accessible name
- * that reflects the *action*, swapping it with `data-state`.
+ * Autoplay pause/resume button — WCAG 2.2.2 requires this next to any carousel that moves on its own, carrying `data-state` of `"playing"`/`"paused"`.
  *
  * @example
  * ```tsx
- * <CarouselPlayPause aria-label={playing ? 'Pause slideshow' : 'Play slideshow'} />
+ * <Carousel autoplay aria-label="Featured products">
+ *   <CarouselPlayPause aria-label={playing ? 'Pause slideshow' : 'Play slideshow'} />
+ *   <CarouselContent>…</CarouselContent>
+ * </Carousel>
  * ```
  */
-export declare const CarouselPlayPause: React.ForwardRefExoticComponent<Omit<CarouselPlayPauseProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const CarouselPlayPause: {
+    ({ ref: forwardedRef, ...props }: CarouselPlayPauseProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselPlayPause.d.ts

@@ -1,17 +1,17 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { CarouselPlayPauseProps } from './types.js';
 /**
- * The autoplay pause/resume control WCAG 2.2.2 requires next to any carousel
- * that moves on its own: a `<button>` carrying `data-state` of
- * `"playing"`/`"paused"`, which toggles the carousel's timer on click.
- *
- * It stays functional when `autoplay` is `false` — pressing it starts playback
- * — so the same control serves as a play button. Give it an accessible name
- * that reflects the *action*, swapping it with `data-state`.
+ * Autoplay pause/resume button — WCAG 2.2.2 requires this next to any carousel that moves on its own, carrying `data-state` of `"playing"`/`"paused"`.
  *
  * @example
  * ```tsx
- * <CarouselPlayPause aria-label={playing ? 'Pause slideshow' : 'Play slideshow'} />
+ * <Carousel autoplay aria-label="Featured products">
+ *   <CarouselPlayPause aria-label={playing ? 'Pause slideshow' : 'Play slideshow'} />
+ *   <CarouselContent>…</CarouselContent>
+ * </Carousel>
  * ```
  */
-export declare const CarouselPlayPause: React.ForwardRefExoticComponent<Omit<CarouselPlayPauseProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const CarouselPlayPause: {
+    ({ ref: forwardedRef, ...props }: CarouselPlayPauseProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselPrevious.d.cts

@@ -1,14 +1,14 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { CarouselPreviousProps } from './types.cjs';
 /**
- * Button that steps back by the carousel's `slidesPerMove` when clicked,
- * wrapping to the last page when `loop` is enabled. Disabled (native
- * `disabled` plus `data-disabled`) at the first slide when `loop` is
- * `false`, or when there are no slides.
+ * Button that steps back by `slidesPerMove`. Wraps to last slide if `loop` is enabled; disabled at carousel start when `loop` is false or if no slides.
  *
  * @example
  * ```tsx
  * <CarouselPrevious aria-label="Previous slide">←</CarouselPrevious>
  * ```
  */
-export declare const CarouselPrevious: React.ForwardRefExoticComponent<Omit<CarouselPreviousProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const CarouselPrevious: {
+    ({ ref: forwardedRef, ...props }: CarouselPreviousProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselPrevious.d.ts

@@ -1,14 +1,14 @@
-import * as React from 'react';
+import type * as React from 'react';
 import type { CarouselPreviousProps } from './types.js';
 /**
- * Button that steps back by the carousel's `slidesPerMove` when clicked,
- * wrapping to the last page when `loop` is enabled. Disabled (native
- * `disabled` plus `data-disabled`) at the first slide when `loop` is
- * `false`, or when there are no slides.
+ * Button that steps back by `slidesPerMove`. Wraps to last slide if `loop` is enabled; disabled at carousel start when `loop` is false or if no slides.
  *
  * @example
  * ```tsx
  * <CarouselPrevious aria-label="Previous slide">←</CarouselPrevious>
  * ```
  */
-export declare const CarouselPrevious: React.ForwardRefExoticComponent<Omit<CarouselPreviousProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+export declare const CarouselPrevious: {
+    ({ ref: forwardedRef, ...props }: CarouselPreviousProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselProgress.d.cts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import type { CarouselProgressProps } from './types.cjs';
+/**
+ * Slide position readout built from the `format` function (1-based position, total count).
+ *
+ * @example
+ * ```tsx
+ * <CarouselProgress format={(current, total) => `${current} / ${total}`} />
+ * ```
+ */
+export declare const CarouselProgress: {
+    ({ format, children, ref: forwardedRef, ...props }: CarouselProgressProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/CarouselProgress.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import type { CarouselProgressProps } from './types.js';
+/**
+ * Slide position readout built from the `format` function (1-based position, total count).
+ *
+ * @example
+ * ```tsx
+ * <CarouselProgress format={(current, total) => `${current} / ${total}`} />
+ * ```
+ */
+export declare const CarouselProgress: {
+    ({ format, children, ref: forwardedRef, ...props }: CarouselProgressProps): React.ReactNode;
+    displayName: string;
+};

package/dist/carousel/index.d.cts

@@ -1,7 +1,2 @@
-export * from './Carousel.cjs';
-export { CarouselContent } from './CarouselContent.cjs';
-export { CarouselItem } from './CarouselItem.cjs';
-export { CarouselPrevious } from './CarouselPrevious.cjs';
-export { CarouselNext } from './CarouselNext.cjs';
-export { CarouselPlayPause } from './CarouselPlayPause.cjs';
-export type { CarouselProps, CarouselContentProps, CarouselItemProps, CarouselPreviousProps, CarouselNextProps, CarouselPlayPauseProps, } from './types.cjs';
+export { Carousel, useCarouselContext } from './Carousel.cjs';
+export type { CarouselContextValue, CarouselProps } from './types.cjs';

package/dist/carousel/index.d.ts

@@ -1,7 +1,2 @@
-export * from './Carousel.js';
-export { CarouselContent } from './CarouselContent.js';
-export { CarouselItem } from './CarouselItem.js';
-export { CarouselPrevious } from './CarouselPrevious.js';
-export { CarouselNext } from './CarouselNext.js';
-export { CarouselPlayPause } from './CarouselPlayPause.js';
-export type { CarouselProps, CarouselContentProps, CarouselItemProps, CarouselPreviousProps, CarouselNextProps, CarouselPlayPauseProps, } from './types.js';
+export { Carousel, useCarouselContext } from './Carousel.js';
+export type { CarouselContextValue, CarouselProps } from './types.js';

package/dist/carousel/primitives.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Advanced primitives for `Carousel` — the parts the recipe composes, for full manual composition.
+ *
+ * @example
+ * ```tsx
+ * import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from '@skdx/react/primitives/carousel';
+ *
+ * <Carousel aria-label="Featured products" loop spacing={16}>
+ *   <CarouselContent>
+ *     <CarouselItem>Slide 1</CarouselItem>
+ *     <CarouselItem>Slide 2</CarouselItem>
+ *   </CarouselContent>
+ *   <CarouselPrevious>Prev</CarouselPrevious>
+ *   <CarouselNext>Next</CarouselNext>
+ * </Carousel>
+ * ```
+ */
+export { Carousel } from './Carousel.cjs';
+export { CarouselContent } from './CarouselContent.cjs';
+export { CarouselItem } from './CarouselItem.cjs';
+export { CarouselPrevious } from './CarouselPrevious.cjs';
+export { CarouselNext } from './CarouselNext.cjs';
+export { CarouselPlayPause } from './CarouselPlayPause.cjs';
+export { CarouselIndicators } from './CarouselIndicators.cjs';
+export { CarouselIndicator } from './CarouselIndicator.cjs';
+export { CarouselProgress } from './CarouselProgress.cjs';
+export type { CarouselProps, CarouselContentProps, CarouselItemProps, CarouselPreviousProps, CarouselNextProps, CarouselPlayPauseProps, CarouselIndicatorsProps, CarouselIndicatorProps, CarouselProgressProps, } from './types.cjs';

package/dist/carousel/primitives.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Advanced primitives for `Carousel` — the parts the recipe composes, for full manual composition.
+ *
+ * @example
+ * ```tsx
+ * import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from '@skdx/react/primitives/carousel';
+ *
+ * <Carousel aria-label="Featured products" loop spacing={16}>
+ *   <CarouselContent>
+ *     <CarouselItem>Slide 1</CarouselItem>
+ *     <CarouselItem>Slide 2</CarouselItem>
+ *   </CarouselContent>
+ *   <CarouselPrevious>Prev</CarouselPrevious>
+ *   <CarouselNext>Next</CarouselNext>
+ * </Carousel>
+ * ```
+ */
+export { Carousel } from './Carousel.js';
+export { CarouselContent } from './CarouselContent.js';
+export { CarouselItem } from './CarouselItem.js';
+export { CarouselPrevious } from './CarouselPrevious.js';
+export { CarouselNext } from './CarouselNext.js';
+export { CarouselPlayPause } from './CarouselPlayPause.js';
+export { CarouselIndicators } from './CarouselIndicators.js';
+export { CarouselIndicator } from './CarouselIndicator.js';
+export { CarouselProgress } from './CarouselProgress.js';
+export type { CarouselProps, CarouselContentProps, CarouselItemProps, CarouselPreviousProps, CarouselNextProps, CarouselPlayPauseProps, CarouselIndicatorsProps, CarouselIndicatorProps, CarouselProgressProps, } from './types.js';

package/dist/carousel/types.d.cts

@@ -1,3 +1,4 @@
+import type * as React from 'react';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 /** Shape returned by the exported `useCarouselContext` hook; distributed from {@link Carousel} to its parts via context. */
 export interface CarouselContextValue {
@@ -5,8 +6,11 @@ export interface CarouselContextValue {
     setValue: (index: number) => void;
     orientation: 'horizontal' | 'vertical';
     loop: boolean;
+    /** Every registered slide's id, in DOM order — the order a derived Indicators list must draw its dots in. */
     itemIds: string[];
-    registerItem: (id: string) => void;
+    /** Registers one slide, placing its id by the element's DOM position rather than by when it mounted. */
+    registerItem: (id: string, element: HTMLElement | null) => void;
+    /** Removes a slide's id from the registry when it unmounts. */
     unregisterItem: (id: string) => void;
     /** How many slides are visible at once. */
     slidesPerPage: number;
@@ -14,84 +18,114 @@ export interface CarouselContextValue {
     slidesPerMove: number;
     /** Highest index the carousel can rest at — `max(0, count - slidesPerPage)`, so the last page stays full. */
     maxIndex: number;
-    /** Moves to `index`, clamped into `[0, maxIndex]`. Ignores out-of-range values rather than throwing. */
+    /** Moves to `index`, clamped into `[0, maxIndex]`, ignoring out-of-range values rather than throwing. */
     scrollToIndex: (index: number) => void;
-    /** Steps forward by `slidesPerMove`, wrapping to the start when `loop` is set. The one stepping rule Next and the arrow keys share. */
+    /** Stepper forward by `slidesPerMove`, wrapping to the start when `loop` is set. */
     next: () => void;
-    /** Steps back by `slidesPerMove`, wrapping to the last page when `loop` is set. */
+    /** Stepper back by `slidesPerMove`, wrapping to the last page when `loop` is set. */
     previous: () => void;
+    /** Whether `next()` has somewhere to go — false at the last page of a non-looping carousel, and with no slides. */
+    canScrollNext: boolean;
+    /** Whether `previous()` has somewhere to go — false at the first slide of a non-looping carousel, and with no slides. */
+    canScrollPrev: boolean;
     /**
-     * Whether autoplay is switched on. This is the user's setting, not the live
-     * timer state — hover/focus/page-hidden suspend the timer without flipping it.
+     * User's autoplay intent, not live timer state — hover and a hidden page suspend the timer without flipping it, but focus entering the carousel does.
      */
     playing: boolean;
     /** Starts or stops autoplay — what `CarouselPlayPause` calls. */
     setPlaying: (playing: boolean) => void;
 }
-/** Props for the {@link Carousel} root. */
-export interface CarouselProps extends PrimitivePropsWithRef<'div'> {
+/**
+ * Props for {@link Carousel}, which tracks a controllable current-slide index
+ * over slides supplied as `items` or as children, with optional derived
+ * controls, indicators and an autoplay pause button — there is no
+ * track/transform sliding and no swipe gesture.
+ */
+export interface CarouselProps<T = unknown> extends PrimitivePropsWithRef<'div'> {
     /**
-     * Index of the active slide, for controlled usage. Pair with `onValueChange`.
-     * @default undefined — uncontrolled, tracks its own active slide internally.
+     * Manually-composed parts — `CarouselContent`, `CarouselItem`, etc. — for full control over the anatomy; omitted, the carousel derives it from `items` and related props.
+     * @default undefined — the carousel derives its anatomy.
      */
-    value?: number;
+    children?: React.ReactNode | undefined;
     /**
-     * Initial active slide index, for uncontrolled usage.
+     * Index of the first visible slide for controlled usage, paired with `onValueChange`.
+     * @default undefined — uncontrolled, tracks its own active window internally.
+     */
+    value?: number | undefined;
+    /**
+     * Initial index of the first slide in the active window, for uncontrolled usage.
      * @default 0
      */
-    defaultValue?: number;
+    defaultValue?: number | undefined;
     /**
      * Fires with the new active index whenever the slide changes, controlled or not.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (index: number) => void;
+    onValueChange?: ((index: number) => void) | undefined;
     /**
      * Layout axis, exposed as `data-orientation` and used to pick Arrow
      * Left/Right vs Arrow Up/Down for keyboard navigation.
      * @default 'horizontal'
      */
-    orientation?: 'horizontal' | 'vertical';
+    orientation?: 'horizontal' | 'vertical' | undefined;
     /**
-     * Whether stepping past the last slide (via keyboard or `CarouselNext`)
-     * wraps to the first, and vice versa for `CarouselPrevious`. When `false`,
-     * `CarouselPrevious`/`CarouselNext` disable themselves at the ends.
+     * Whether stepping past the last slide wraps to the first (and vice versa for `CarouselPrevious`); when `false`, both disable themselves at the ends.
      * @default false
      */
-    loop?: boolean;
+    loop?: boolean | undefined;
     /**
-     * How many slides are visible at once. Slides from `value` up to
-     * `value + slidesPerPage - 1` are active; the rest stay `hidden`. Values
-     * below 1 are treated as 1.
+     * How many slides are visible at once, from `value` up to `value + slidesPerPage - 1`; values below 1 are treated as 1.
      * @default 1
      */
-    slidesPerPage?: number;
+    slidesPerPage?: number | undefined;
     /**
-     * How many slides one Previous/Next step (or Arrow keypress) advances by.
-     * Set it equal to `slidesPerPage` for page-at-a-time paging.
+     * How many slides one Previous/Next step (or Arrow keypress) advances by; set equal to `slidesPerPage` for page-at-a-time paging.
      * @default 1
      */
-    slidesPerMove?: number;
+    slidesPerMove?: number | undefined;
     /**
-     * Gap between slides, published as the `--skdx-carousel-spacing` custom
-     * property on the root so your CSS can consume it (`gap: var(--skdx-carousel-spacing)`).
-     * A number is treated as pixels; a string is used verbatim.
+     * Gap between slides, published as the `--skdx-carousel-spacing` custom property; a number is treated as pixels, a string used verbatim.
      * @default undefined — the property is not set, and your CSS decides.
      */
-    spacing?: number | string;
+    spacing?: number | string | undefined;
     /**
-     * Advances the carousel on a timer. Off by default, per WCAG 2.2.2: moving
-     * content that starts automatically needs a way to pause it, which
-     * `CarouselPlayPause` provides. Autoplay never starts under
-     * `prefers-reduced-motion: reduce`, and pauses while the pointer is over the
-     * root, while focus is inside it, and while the page is hidden.
+     * Auto-advances on a timer; off by default (WCAG 2.2.2), never starts under `prefers-reduced-motion`, and pairs with `CarouselPlayPause` to pause.
      * @default false
      */
-    autoplay?: boolean;
+    autoplay?: boolean | undefined;
     /**
      * Milliseconds to wait between automatic slide advances.
      * @default 5000
      */
-    autoplayInterval?: number;
+    autoplayInterval?: number | undefined;
+    /**
+     * Data the derived anatomy renders one `CarouselItem` slide per, instead of
+     * hand-written children. Ignored when `children` is given.
+     * @default undefined — no slides render.
+     */
+    items?: T[] | undefined;
+    /**
+     * Renders one derived slide's content, in place of its `String(item)`
+     * fallback. Ignored when `children` is given.
+     * @default undefined — each slide renders `String(item)`.
+     */
+    renderItem?: ((item: T, index: number) => React.ReactNode) | undefined;
+    /**
+     * Whether the derived anatomy renders a `CarouselIndicators` strip, one dot
+     * per item. Ignored when `children` is given.
+     * @default false
+     */
+    showIndicators?: boolean | undefined;
+    /**
+     * Accessible names for derived indicator dots, one per `items` entry in order; a shorter list falls back to the positional default for the rest.
+     * @default undefined
+     */
+    indicatorLabels?: readonly string[] | undefined;
+    /**
+     * Renders derived `CarouselPrevious` / `CarouselNext` controls; `CarouselPlayPause` renders whenever `autoplay` is set, independent of this.
+     * @default true
+     */
+    showControls?: boolean | undefined;
 }
 /** Props for {@link CarouselContent}, the wrapper around the slide `CarouselItem`s. */
 export interface CarouselContentProps extends PrimitivePropsWithRef<'div'> {
@@ -108,3 +142,29 @@ export interface CarouselNextProps extends PrimitivePropsWithRef<'button'> {
 /** Props for {@link CarouselPlayPause}, the autoplay pause/resume control. */
 export interface CarouselPlayPauseProps extends PrimitivePropsWithRef<'button'> {
 }
+/** Props for {@link CarouselIndicators}, the `role="group"` strip of slide dots. */
+export interface CarouselIndicatorsProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for a single {@link CarouselIndicator} dot. */
+export interface CarouselIndicatorProps extends PrimitivePropsWithRef<'button'> {
+    /** Zero-based slide index this dot jumps to when pressed. */
+    index: number;
+    /**
+     * Accessible name for this dot, replacing the positional default "Go to slide N"; a consumer's own `aria-label` takes precedence.
+     * @default undefined
+     */
+    label?: string | undefined;
+}
+/** Props for {@link CarouselProgress}, the "slide 2 of 5" position readout. */
+export interface CarouselProgressProps extends Omit<PrimitivePropsWithRef<'div'>, 'children'> {
+    /**
+     * Formats the position text from the 1-based current slide and total count, consumer-supplied for translation.
+     * @default (current, total) => `Slide ${current} of ${total}`
+     */
+    format?: ((current: number, total: number) => string) | undefined;
+    /**
+     * With `asChild`, the element the formatted text is cloned onto, replacing its own children with the readout.
+     * @default undefined
+     */
+    children?: React.ReactElement | undefined;
+}