@allxsmith/bestax-bulma 5.41.0 → 5.42.0

package/dist/types/components/Carousel.d.ts

@@ -4,7 +4,10 @@ import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
  * Props for the CarouselItem component.
  */
 export interface CarouselItemProps extends React.HTMLAttributes<HTMLDivElement> {
-    /** Whether this item is active (set automatically). */
+    /**
+     * Whether this item is in view. `Carousel` sets it on every item in view,
+     * so with several in view several are active.
+     */
     active?: boolean;
 }
 /**
@@ -24,20 +27,93 @@ type IconLibrary = 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols';
  */
 export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'color'>, BulmaClassesProps {
     /**
-     * Current active slide index (controlled).
+     * Index of the first item in view (controlled); with one item in view, the
+     * slide shown. A value between two of the positions a step lands on (see
+     * `itemsToScroll`) is shown as given, and the next step goes on from it.
+     * With `repeat`, a value past either end wraps around; without it, one
+     * that would leave empty space after the last item shows the last full
+     * view. Neither correction calls `onChange`. A value that takes the item
+     * holding focus out of view moves focus to the first item in view, as a
+     * swipe or a change of width does.
      * @defaultValue 0
      */
     value?: number;
-    /** Enable auto-play. */
+    /**
+     * Enable auto-play: one step (`itemsToScroll` items) per `interval`.
+     * Without `repeat` it stops at the last position. It waits while the
+     * pointer is over the carousel (see `pauseOnHover`) and while focus is
+     * inside one of its items, so an item being read or used never moves out
+     * of view.
+     */
     autoplay?: boolean;
     /** Auto-play interval in milliseconds. Default: 5000. */
     interval?: number;
     /** Pause auto-play on hover. Default: true. */
     pauseOnHover?: boolean;
-    /** Loop back to first slide after last. Default: true. */
+    /**
+     * Loop back to the first position after the last. Default: true. With
+     * several items in view, the view runs on past the last item into the
+     * first ones, so it can show the end and the start side by side. Only
+     * loops when some item is out of view.
+     */
     repeat?: boolean;
-    /** Enable drag/swipe navigation. Default: true. */
+    /**
+     * Enable drag/swipe navigation. Default: true. A swipe moves one step,
+     * however far it travels.
+     */
     hasDrag?: boolean;
+    /**
+     * How many items are in view at once, at every width no
+     * `itemsToShow<Viewport>` prop covers. Those props read the way a
+     * `Column`'s `size<Viewport>` props do: `itemsToShowMobile` applies below
+     * Bulma's tablet breakpoint, each of the others from its own breakpoint
+     * up, and where several apply the widest one wins. A whole number, rounded
+     * down and at least 1. The widths come from the stylesheet, so they are
+     * right on the first paint; the arrows, indicators and steps use the
+     * count for the window's width once the page has hydrated, and this one
+     * until then. With this many children or fewer, every item keeps its
+     * share of the width, nothing moves, and no arrows or indicators render.
+     * @defaultValue 1
+     */
+    itemsToShow?: number;
+    /**
+     * Items in view at any width below Bulma's tablet breakpoint (769px),
+     * fractional ones included. Falls back to `itemsToShow`.
+     */
+    itemsToShowMobile?: number;
+    /**
+     * Items in view from Bulma's tablet breakpoint (769px) up, until a wider
+     * viewport's prop takes over. Falls back to `itemsToShow`.
+     */
+    itemsToShowTablet?: number;
+    /**
+     * Items in view from Bulma's desktop breakpoint (1024px) up, until a wider
+     * viewport's prop takes over. Falls back to `itemsToShowTablet`, then
+     * `itemsToShow`.
+     */
+    itemsToShowDesktop?: number;
+    /**
+     * Items in view from Bulma's widescreen breakpoint (1216px) up, until
+     * `itemsToShowFullhd` takes over. Falls back to `itemsToShowDesktop`, and
+     * on down to `itemsToShow`.
+     */
+    itemsToShowWidescreen?: number;
+    /**
+     * Items in view from Bulma's fullhd breakpoint (1408px) up. Falls back to
+     * `itemsToShowWidescreen`, and on down to `itemsToShow`.
+     */
+    itemsToShowFullhd?: number;
+    /**
+     * How many items one step moves, for an arrow, an arrow key, a swipe or an
+     * autoplay tick. A whole number, capped at the count in view so a step
+     * never skips an item. Without `repeat`, the last step stops at the last
+     * full view, so it can be shorter; with `repeat`, the step after the last
+     * position goes on to the first one. The indicators mark these positions,
+     * one per step rather than one per item. When the count in view changes
+     * with the window's width, the first item in view stays in view.
+     * @defaultValue 1
+     */
+    itemsToScroll?: number;
     /**
      * Show navigation arrows. Default: true. They render `type="button"`, so a
      * carousel inside a form is not submitted by moving between slides.
@@ -46,8 +122,9 @@ export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     /** Only show arrows on hover. */
     arrowHover?: boolean;
     /**
-     * Show slide indicators. Default: true. They render `type="button"`, so a
-     * carousel inside a form is not submitted by picking a slide.
+     * Show slide indicators. Default: true. There is one for each position a
+     * step can land on (see `itemsToScroll`). They render `type="button"`, so
+     * a carousel inside a form is not submitted by picking a slide.
      */
     indicator?: boolean;
     /** Position indicators inside carousel. */
@@ -74,7 +151,10 @@ export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     arrowColor?: 'light' | 'dark';
     /** Accessible label for the carousel region. Default: 'Image carousel'. */
     ariaLabel?: string;
-    /** Callback when slide changes. */
+    /**
+     * Called with the index of the first item in view when an arrow, an arrow
+     * key, an indicator, a swipe or autoplay moves the carousel.
+     */
     onChange?: (value: number) => void;
     /** CarouselItem children. */
     children?: React.ReactNode;
@@ -105,6 +185,14 @@ export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>
  *     <img src="image2.jpg" alt="Slide 2" />
  *   </CarouselItem>
  * </Carousel>
+ *
+ * @example
+ * // Three cards in view on desktop, two on tablet, one on mobile
+ * <Carousel itemsToShow={1} itemsToShowTablet={2} itemsToShowDesktop={3}>
+ *   {cards.map(card => (
+ *     <CarouselItem key={card.id}>{card.body}</CarouselItem>
+ *   ))}
+ * </Carousel>
  */
 export declare const Carousel: React.ForwardRefExoticComponent<CarouselProps & React.RefAttributes<HTMLDivElement>>;
 export default Carousel;

package/dist/types-cjs/components/Carousel.d.ts

@@ -4,7 +4,10 @@ import { BulmaClassesProps } from '../helpers/useBulmaClasses.js';
  * Props for the CarouselItem component.
  */
 export interface CarouselItemProps extends React.HTMLAttributes<HTMLDivElement> {
-    /** Whether this item is active (set automatically). */
+    /**
+     * Whether this item is in view. `Carousel` sets it on every item in view,
+     * so with several in view several are active.
+     */
     active?: boolean;
 }
 /**
@@ -24,20 +27,93 @@ type IconLibrary = 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols';
  */
 export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'color'>, BulmaClassesProps {
     /**
-     * Current active slide index (controlled).
+     * Index of the first item in view (controlled); with one item in view, the
+     * slide shown. A value between two of the positions a step lands on (see
+     * `itemsToScroll`) is shown as given, and the next step goes on from it.
+     * With `repeat`, a value past either end wraps around; without it, one
+     * that would leave empty space after the last item shows the last full
+     * view. Neither correction calls `onChange`. A value that takes the item
+     * holding focus out of view moves focus to the first item in view, as a
+     * swipe or a change of width does.
      * @defaultValue 0
      */
     value?: number;
-    /** Enable auto-play. */
+    /**
+     * Enable auto-play: one step (`itemsToScroll` items) per `interval`.
+     * Without `repeat` it stops at the last position. It waits while the
+     * pointer is over the carousel (see `pauseOnHover`) and while focus is
+     * inside one of its items, so an item being read or used never moves out
+     * of view.
+     */
     autoplay?: boolean;
     /** Auto-play interval in milliseconds. Default: 5000. */
     interval?: number;
     /** Pause auto-play on hover. Default: true. */
     pauseOnHover?: boolean;
-    /** Loop back to first slide after last. Default: true. */
+    /**
+     * Loop back to the first position after the last. Default: true. With
+     * several items in view, the view runs on past the last item into the
+     * first ones, so it can show the end and the start side by side. Only
+     * loops when some item is out of view.
+     */
     repeat?: boolean;
-    /** Enable drag/swipe navigation. Default: true. */
+    /**
+     * Enable drag/swipe navigation. Default: true. A swipe moves one step,
+     * however far it travels.
+     */
     hasDrag?: boolean;
+    /**
+     * How many items are in view at once, at every width no
+     * `itemsToShow<Viewport>` prop covers. Those props read the way a
+     * `Column`'s `size<Viewport>` props do: `itemsToShowMobile` applies below
+     * Bulma's tablet breakpoint, each of the others from its own breakpoint
+     * up, and where several apply the widest one wins. A whole number, rounded
+     * down and at least 1. The widths come from the stylesheet, so they are
+     * right on the first paint; the arrows, indicators and steps use the
+     * count for the window's width once the page has hydrated, and this one
+     * until then. With this many children or fewer, every item keeps its
+     * share of the width, nothing moves, and no arrows or indicators render.
+     * @defaultValue 1
+     */
+    itemsToShow?: number;
+    /**
+     * Items in view at any width below Bulma's tablet breakpoint (769px),
+     * fractional ones included. Falls back to `itemsToShow`.
+     */
+    itemsToShowMobile?: number;
+    /**
+     * Items in view from Bulma's tablet breakpoint (769px) up, until a wider
+     * viewport's prop takes over. Falls back to `itemsToShow`.
+     */
+    itemsToShowTablet?: number;
+    /**
+     * Items in view from Bulma's desktop breakpoint (1024px) up, until a wider
+     * viewport's prop takes over. Falls back to `itemsToShowTablet`, then
+     * `itemsToShow`.
+     */
+    itemsToShowDesktop?: number;
+    /**
+     * Items in view from Bulma's widescreen breakpoint (1216px) up, until
+     * `itemsToShowFullhd` takes over. Falls back to `itemsToShowDesktop`, and
+     * on down to `itemsToShow`.
+     */
+    itemsToShowWidescreen?: number;
+    /**
+     * Items in view from Bulma's fullhd breakpoint (1408px) up. Falls back to
+     * `itemsToShowWidescreen`, and on down to `itemsToShow`.
+     */
+    itemsToShowFullhd?: number;
+    /**
+     * How many items one step moves, for an arrow, an arrow key, a swipe or an
+     * autoplay tick. A whole number, capped at the count in view so a step
+     * never skips an item. Without `repeat`, the last step stops at the last
+     * full view, so it can be shorter; with `repeat`, the step after the last
+     * position goes on to the first one. The indicators mark these positions,
+     * one per step rather than one per item. When the count in view changes
+     * with the window's width, the first item in view stays in view.
+     * @defaultValue 1
+     */
+    itemsToScroll?: number;
     /**
      * Show navigation arrows. Default: true. They render `type="button"`, so a
      * carousel inside a form is not submitted by moving between slides.
@@ -46,8 +122,9 @@ export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     /** Only show arrows on hover. */
     arrowHover?: boolean;
     /**
-     * Show slide indicators. Default: true. They render `type="button"`, so a
-     * carousel inside a form is not submitted by picking a slide.
+     * Show slide indicators. Default: true. There is one for each position a
+     * step can land on (see `itemsToScroll`). They render `type="button"`, so
+     * a carousel inside a form is not submitted by picking a slide.
      */
     indicator?: boolean;
     /** Position indicators inside carousel. */
@@ -74,7 +151,10 @@ export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     arrowColor?: 'light' | 'dark';
     /** Accessible label for the carousel region. Default: 'Image carousel'. */
     ariaLabel?: string;
-    /** Callback when slide changes. */
+    /**
+     * Called with the index of the first item in view when an arrow, an arrow
+     * key, an indicator, a swipe or autoplay moves the carousel.
+     */
     onChange?: (value: number) => void;
     /** CarouselItem children. */
     children?: React.ReactNode;
@@ -105,6 +185,14 @@ export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>
  *     <img src="image2.jpg" alt="Slide 2" />
  *   </CarouselItem>
  * </Carousel>
+ *
+ * @example
+ * // Three cards in view on desktop, two on tablet, one on mobile
+ * <Carousel itemsToShow={1} itemsToShowTablet={2} itemsToShowDesktop={3}>
+ *   {cards.map(card => (
+ *     <CarouselItem key={card.id}>{card.body}</CarouselItem>
+ *   ))}
+ * </Carousel>
  */
 export declare const Carousel: React.ForwardRefExoticComponent<CarouselProps & React.RefAttributes<HTMLDivElement>>;
 export default Carousel;