@tui-cruises/mein-schiff-web-react-component-library 2.0.0-rc.1

package/src/components/shared/UniversalCarousel/CarouselContext.ts

@@ -0,0 +1,61 @@
+import { createContext, Dispatch, SetStateAction } from 'react';
+import { ScrollToIndex } from './CarouselInterface';
+
+export type TCarouselContext = {
+  /**
+   * Indicates if the carousel is currently enabled.
+   */
+  enabled: boolean;
+
+  /**
+   * The indexes of the items that are currently fully visible.
+   */
+  visibleIndexes: number[];
+
+  /**
+   * The number of currently fully visible items.
+   */
+  visibleItems: number;
+
+  /**
+   * The index of the last item.
+   */
+  lastIndex: number;
+
+  /**
+   * The number of pixels the stage is scrolled.
+   */
+  stageScrollLeft: number;
+
+  /**
+   * The amount of pixels the stage would require to be rendered without a scrollbar -- its "width".
+   */
+  stageScrollWidth: number;
+
+  /**
+   * The current width of the stage -- its "width" as visible to the user.
+   */
+  stageWidth: number;
+
+  scrollToIndex: ScrollToIndex;
+
+  /**
+   * A setter for the context.
+   */
+  set: Dispatch<SetStateAction<TCarouselContext>>;
+};
+
+/**
+ * A context that provides information about the current state of the carousel, a helper function to scroll to a specific index and a setter for the context itself.
+ */
+export const CarouselContext = createContext<TCarouselContext>({
+  enabled: false,
+  visibleIndexes: [0],
+  visibleItems: 0,
+  lastIndex: 0,
+  scrollToIndex: () => {},
+  stageScrollLeft: 0,
+  stageScrollWidth: 0,
+  stageWidth: 0,
+  set: () => {},
+});

package/src/components/shared/UniversalCarousel/CarouselDefaultPagination.tsx

@@ -0,0 +1,92 @@
+'use client';
+
+import type { FC, HTMLAttributes } from 'react';
+import { twMerge } from '@tuic/tailwind-config';
+import { CarouselInterface } from './CarouselInterface';
+import { Pagination, PaginationProps } from '../../core/Pagination';
+
+export type CarouselDefaultPaginationProps = Omit<
+  HTMLAttributes<HTMLElement>,
+  'children'
+> & {
+  i18n?: PaginationProps['i18n'];
+  className?: string;
+};
+
+/**
+ * Render the default carousel pagination in your carousel.
+ *
+ * > ⚠️ Important: This component is designed to function exclusively as a descendant of the `Carousel` component.
+ *
+ * ```tsx
+ * <UniversalCarousel>
+ *   <CarouselStage>
+ *     <Image src="..." className="aspect-4/3" />
+ *     <Image src="..." className="aspect-4/3" />
+ *     <Image src="..." className="aspect-4/3" />
+ *     // Add as many items as needed ...
+ *   </CarouselStage>
+ *   <CarouselDefaultPagination />
+ * </UniversalCarousel>
+ * ```
+ */
+export const CarouselDefaultPagination: FC<CarouselDefaultPaginationProps> = ({
+  ...attrs
+}) => {
+  return (
+    <CarouselInterface>
+      {context => {
+        const {
+          visibleItems,
+          visibleIndexes,
+          lastIndex,
+          scrollToIndex,
+          stageWidth,
+          stageScrollWidth,
+        } = context;
+
+        if (stageScrollWidth <= stageWidth) {
+          return null; // No pagination needed if all items fit
+        }
+
+        const stepSize = visibleItems || 1; // Number of items per page
+        const totalPages = Math.ceil((lastIndex + 1) / stepSize); // Total number of pages
+        const firstVisibleIndex = Math.min(...visibleIndexes); // First currently visible item index
+        const lastVisibleIndex = Math.max(...visibleIndexes); // Last currently visible item index
+
+        // Calculate current page: Ensure correct page number on partial visibility
+        const currentPage = Math.ceil((lastVisibleIndex + 1) / stepSize);
+
+        // Boundaries for disabling prev/next buttons
+        const isPrevDisabled = firstVisibleIndex <= 0;
+        const isNextDisabled = lastVisibleIndex >= lastIndex;
+
+        const handlePrev = () => {
+          const targetIndex = Math.max(0, firstVisibleIndex - stepSize);
+          scrollToIndex(targetIndex, 'start');
+        };
+
+        const handleNext = () => {
+          const targetIndex = Math.min(
+            lastVisibleIndex + 1,
+            lastIndex - stepSize + 1,
+          );
+          scrollToIndex(targetIndex, 'start');
+        };
+
+        return (
+          <Pagination
+            {...attrs}
+            total={totalPages}
+            current={currentPage}
+            onPrevious={isPrevDisabled ? undefined : handlePrev}
+            onNext={isNextDisabled ? undefined : handleNext}
+            forcePreviousClickable={!isPrevDisabled}
+            forceNextClickable={!isNextDisabled}
+            className={twMerge('mt-8', attrs.className)}
+          />
+        );
+      }}
+    </CarouselInterface>
+  );
+};

package/src/components/shared/UniversalCarousel/CarouselInterface.tsx

@@ -0,0 +1,152 @@
+'use client';
+
+import type { FC, ReactNode } from 'react';
+import { useCallback, useContext } from 'react';
+import { CarouselContext } from './CarouselContext';
+
+/**
+ * Scrolls the carousel to a specified index with customizable position and behavior.
+ *
+ * @param idx - The target index. Out of bounds values are wrapped around.
+ * @param position - The target item position: `'start'`, `'center'`, or `'end'`.
+ * @param scrollBehavior - The scroll behavior: `'auto'`, `'smooth'`, or `'instant'`.
+ */
+export type ScrollToIndex = (
+  idx: number,
+  position: 'start' | 'center' | 'end',
+  scrollBehavior?: 'auto' | 'smooth' | 'instant',
+) => void;
+
+export type CarouselInterfaceContext = {
+  /**
+   * Indicates if the carousel is currently
+   */
+  enabled: boolean;
+
+  /**
+   * An array of indexes of the currently fully visible items.
+   */
+  visibleIndexes: number[];
+
+  /**
+   * The number of currently fully visible items.
+   */
+  visibleItems: number;
+
+  /**
+   * The index of the last item.
+   * If you want to display the total number of items, you can use this value by adding 1.
+   */
+  lastIndex: number;
+
+  /**
+   * The number of pixels the stage is scrolled.
+   */
+  stageScrollLeft: number;
+
+  /**
+   * The amount of pixels the stage would require to be rendered without a scrollbar -- its "width".
+   */
+  stageScrollWidth: number;
+
+  /**
+   * The current width of the stage -- its "width" as visible to the user.
+   */
+  stageWidth: number;
+
+  scrollToIndex: ScrollToIndex;
+
+  /**
+   * A function that scrolls the carousel to the next item. The carousel loops to the first item, when invoked at the end of the carousel.
+   */
+  next: () => void;
+
+  /**
+   * A function that scrolls the carousel to the previous item. The carousel loops to the last item, when invoked at the start of the carousel.
+   */
+  prev: () => void;
+};
+
+type Props = {
+  children: (context: CarouselInterfaceContext) => ReactNode;
+};
+
+/**
+ * `CarouselInterface` acts as a comprehensive control and indicator system for the carousel, allowing for enhanced interaction and information display regarding the carousel's state.
+ *
+ * Utilize this component for various functionalities, including:
+ *
+ * - Showcasing the total number of items along with the position of the current item, for example, `Picture 1 of 5`.
+ * - Implementing navigational controls, such as previous and next buttons, for seamless navigation through carousel items.
+ * - Introducing visual indicators or "bullets" that represent the quantity of items and indicate the currently visible item.
+ * - Integrating sophisticated control logic using the `scrollToIndex` function, enabling direct navigation to any item within the carousel.
+ *
+ * > ⚠️ It's imperative to use this component as a direct descendant of the `Carousel` component to ensure proper functionality.
+ *
+ * Below is a practical example of how to integrate the `CarouselInterface` within the `Carousel` component:
+ *
+ * ```tsx
+ * <UniversalCarousel>
+ *   <CarouselItems>
+ *     ...
+ *   </CarouselItems>
+ *   <CarouselInterface>
+ *     {(carouselContext) => {
+ *       // Extracting properties from the carousel context
+ *       const {visibleIndexes, lastIndex, prev, next} = carouselContext;
+ *
+ *       // Constructing the carousel navigation interface
+ *       return (
+ *         <div>
+ *           <button onClick={prev}>Previous</button>
+ *
+ *           Picture {visibleIndexes[0] + 1} of {lastIndex + 1}
+ *
+ *           <button onClick={next}>Next</button>
+ *         </div>
+ *       );
+ *     }}
+ *   </CarouselInterface>
+ * </UniversalCarousel>
+ * ```
+ *
+ * This code snippet illustrates a simple setup where users can navigate through items and view the current item's context within the carousel. Adjust the logic within `CarouselInterface` to suit specific use cases or UI requirements.
+ */
+export const CarouselInterface: FC<Props> = ({ children }) => {
+  const {
+    enabled,
+    visibleIndexes,
+    visibleItems,
+    lastIndex,
+    scrollToIndex,
+    stageScrollLeft,
+    stageScrollWidth,
+    stageWidth,
+  } = useContext(CarouselContext);
+
+  const prev = useCallback(() => {
+    scrollToIndex(Math.min(...visibleIndexes) - 1, 'start');
+  }, [visibleIndexes, scrollToIndex]);
+
+  const next = useCallback(() => {
+    if (visibleIndexes.indexOf(lastIndex) > -1) {
+      scrollToIndex(0, 'start');
+      return;
+    }
+
+    scrollToIndex(Math.min(...visibleIndexes) + 1, 'start');
+  }, [visibleIndexes, lastIndex, scrollToIndex]);
+
+  return children({
+    enabled,
+    visibleIndexes,
+    visibleItems,
+    lastIndex,
+    scrollToIndex,
+    stageScrollLeft,
+    stageScrollWidth,
+    stageWidth,
+    prev,
+    next,
+  });
+};

package/src/components/shared/UniversalCarousel/CarouselStage.tsx

@@ -0,0 +1,235 @@
+'use client';
+
+import {
+  FC,
+  HTMLAttributes,
+  MouseEventHandler,
+  ReactElement,
+  ReactNode,
+  useState,
+} from 'react';
+import { Children, useCallback, useContext, useEffect, useRef } from 'react';
+import debounce from 'lodash/debounce';
+import { twMerge } from '@tuic/tailwind-config';
+import { CarouselContext } from './CarouselContext';
+import {
+  combineEventHandlers,
+  createToIndexScroller,
+  getChildrenAsArrayOfElements,
+  getVisibleIndexes,
+} from './helpers';
+import { useMediaQuery } from '@tuic/lib/hooks/use-media-query';
+import { useDraggableScroll } from '@tuic/lib/hooks/use-draggable-scroll';
+import { useScreenName } from '../../../hooks/use-screen-name';
+import { logger } from '@tuic/logger';
+
+type Props = {
+  children: ReactNode;
+
+  /**
+   * Determines if carousel items can be dragged with a mouse. Defaults to false. On touch devices, dragging is enabled by default.
+   */
+  draggable?: boolean;
+
+  /**
+   * Props applied to each li element wrapping individual carousel items. Ideal for consistent styling or item spacing.
+   */
+  itemProps?: HTMLAttributes<HTMLLIElement>;
+} & HTMLAttributes<HTMLUListElement>;
+
+/**
+ * CarouselStage Component
+ *
+ * Encapsulates carousel items within a `ul` element, systematically wrapping each item in a `li`.
+ * Designed to be used exclusively within the `Carousel` component for smooth and customizable scrolling experiences.
+ *
+ * ### Example
+ * ```tsx
+ * <UniversalCarousel>
+ *   <CarouselStage>
+ *     <Image src="..." className="aspect-4/3" />
+ *     <Image src="..." className="aspect-4/3" />
+ *     <Image src="..." className="aspect-4/3" />
+ *   </CarouselStage>
+ * </UniversalCarousel>
+ * ```
+ *
+ * ## Props
+ * - `draggable` (boolean): Enable or disable mouse dragging for the carousel. Defaults to `false`. On touch devices, dragging is always enabled.
+ * - `itemProps` (object): Props applied to each `li` element wrapping the carousel items, ideal for consistent styling or spacing.
+ *
+ * ### Adjusting Item Width
+ * Use the `carousel-item-w-*` utilities to set the width of carousel items.
+ * Items with width set as percentages (e.g., `w-1/3`, `w-[50%]`) automatically account for gaps specified by the `carousel-stage-gap` utility.
+ *
+ * ```tsx
+ * <CarouselStage itemProps={{ className: 'carousel-item-w-1/2' }} />
+ * // Sets each item's width to 50% of the carousel width.
+ *
+ * <CarouselStage itemProps={{ className: 'carousel-item-w-[80%]' }} />
+ * // Each item occupies 80% of the width, partially exposing the next item.
+ * ```
+ *
+ * ### Managing Spacing Between Items
+ *
+ * - **Single Visible Item**: Use `margin` utilities to add space between elements.
+ *   ```tsx
+ *   <CarouselStage itemProps={{ className: 'mr-2 last:mr-0' }} />
+ *   ```
+ *
+ * - **Multiple Visible Items**: Use `carousel-stage-gap` utilities to add gaps. These gaps are automatically considered when using `carousel-item-w`.
+ *   ```tsx
+ *   <CarouselStage className="carousel-stage-gap-2" itemProps={{ className: 'carousel-item-w-1/3' }} />
+ *   ```
+ */
+export const CarouselStage: FC<Props> = ({
+  children,
+  draggable = true,
+  className: propClassName,
+  onScroll: propOnScroll,
+  onMouseDown: propOnMouseDown,
+  itemProps,
+  ...rest
+}) => {
+  const { set: setContextValue, enabled } = useContext(CarouselContext);
+  const ref = useRef<HTMLUListElement>(null);
+  const screenName = useScreenName();
+
+  const [dragging, setDragging] = useState<boolean>(false);
+  const [preventClick, setPreventClick] = useState<boolean>(false);
+  const dragStartPosition = useRef<{ x: number; y: number }>({ x: 0, y: 0 });
+
+  // Create a debounced function that updates the current index.
+  const updateCurrentIndexDebounced = useRef(
+    debounce(() => {
+      setContextValue(prev => ({
+        ...prev,
+        visibleIndexes: getVisibleIndexes(ref),
+        stageScrollLeft: ref.current?.scrollLeft ?? 0,
+        stageScrollWidth: ref.current?.scrollWidth ?? 0,
+        stageWidth: ref.current?.offsetWidth ?? 0,
+      }));
+    }, 100),
+  );
+
+  // Set up the draggable scroll on desktop devices with a fine pointer (a mouse).
+  const hasFinePointer = useMediaQuery('pointer: fine');
+  const isDraggable = enabled && draggable && hasFinePointer;
+
+  const { onMouseDown: onMouseDownDraggable, onScroll: onScrollDraggable } =
+    useDraggableScroll(ref, {
+      direction: 'horizontal',
+      enabled: isDraggable,
+      onDragStart: ev => {
+        setPreventClick(false);
+        dragStartPosition.current = { x: ev.clientX, y: ev.clientY };
+      },
+      onDrag: (dx, dy) => {
+        const distanceMoved = Math.hypot(dx, dy); // Use dx and dy
+        if (distanceMoved > 5) {
+          setPreventClick(true); // Suppress clicks if drag movement exceeds 5px
+        }
+      },
+      onDragEnd: () => {
+        updateCurrentIndexDebounced.current();
+
+        // Conditionally set scroll-snap-type only if it's not already 'x mandatory'
+        ref.current?.style.setProperty('scroll-snap-type', 'x mandatory');
+
+        // Reset preventClick after a short delay
+        setTimeout(() => setPreventClick(false), 100);
+      },
+    });
+
+  // Get the children as an array of (react) elements.
+  let childrenAsArray: ReturnType<typeof getChildrenAsArrayOfElements> = [];
+  try {
+    childrenAsArray = getChildrenAsArrayOfElements(children);
+  } catch (error) {
+    if (process.env.NODE_ENV !== 'production') {
+      throw error;
+    }
+    logger.warn('[CarouselStage] Could not resolve react children', children);
+  }
+  const childrenCount = childrenAsArray.length;
+
+  // Merge the classNames of the wrapping list.
+  const containerClassName = twMerge(
+    enabled && 'snap-x snap-mandatory',
+    propClassName,
+    enabled && 'relative flex overflow-x-auto scrollbar-hidden',
+  );
+
+  // Merge the classNames of the list items.
+  const itemClassName = twMerge(
+    enabled && 'carousel-item-w-full',
+    enabled && !itemProps?.className?.includes('snap-') && 'snap-start',
+    itemProps?.className,
+    enabled && 'shrink-0',
+    dragging && 'pointer-events-none',
+  );
+
+  // Update the context value when the children change.
+  useEffect(() => {
+    const visibleIndexes = getVisibleIndexes(ref);
+    const scrollToIndex = createToIndexScroller(ref, childrenCount - 1);
+
+    setContextValue(prev => ({
+      ...prev,
+      lastIndex: childrenCount - 1,
+      visibleIndexes,
+      visibleItems: visibleIndexes.length,
+      scrollToIndex,
+      stageWidth: ref.current?.offsetWidth ?? 0,
+      stageScrollWidth: ref.current?.scrollWidth ?? 0,
+    }));
+
+    // Scroll to the first item on mount or children change
+    scrollToIndex(0, 'start', 'instant');
+  }, [enabled, childrenCount, setContextValue, screenName]);
+
+  // Combine the event handlers which are required for the draggable scroll.
+  const handleMouseDown = useCallback<MouseEventHandler<HTMLUListElement>>(
+    ev => {
+      combineEventHandlers([onMouseDownDraggable, propOnMouseDown])(ev);
+    },
+    [onMouseDownDraggable, propOnMouseDown],
+  );
+
+  const handleScroll = useCallback<MouseEventHandler<HTMLUListElement>>(
+    ev => {
+      combineEventHandlers([
+        onScrollDraggable,
+        updateCurrentIndexDebounced.current,
+        propOnScroll,
+      ])(ev);
+    },
+    [onScrollDraggable, propOnScroll],
+  );
+
+  return (
+    <ul
+      {...rest}
+      className={containerClassName}
+      ref={ref}
+      onMouseDown={handleMouseDown}
+      onScroll={handleScroll}
+    >
+      {Children.map<ReactNode, ReactElement>(childrenAsArray, (child, idx) => (
+        <li
+          {...itemProps}
+          key={child.key ?? idx}
+          className={itemClassName}
+          onClick={ev => {
+            if (preventClick) {
+              ev.preventDefault(); // Suppress the click if a drag occurred
+              return;
+            }
+          }}
+        >
+          {child}
+        </li>
+      ))}
+    </ul>
+  );
+};

package/src/components/shared/UniversalCarousel/UniversalCarousel.tsx

@@ -0,0 +1,125 @@
+'use client';
+
+import { FC, ReactNode, useEffect, useRef } from 'react';
+import { useState } from 'react';
+import { CarouselContext, TCarouselContext } from './CarouselContext';
+import {
+  getResponsiveValue,
+  ResponsiveValue,
+} from '../../../helpers/responsive-property';
+import { useScreenName } from '../../../hooks/use-screen-name';
+
+type Props = {
+  enabled?: ResponsiveValue<boolean>;
+  children?: ReactNode;
+  initialIndex?: number;
+};
+
+/**
+ * The UniversalCarousel component provides a flexible and easily customizable UI element that's perfect for showcasing a collection of items that users can scroll through horizontally. The component is comprised of three main elements:
+ *
+ * 1. **`UniversalCarousel`**: The main component that creates the context for the carousel.
+ * 2. **`CarouselStage`**: A wrapper for the items within the carousel. It handles the layout and the scroll behavior of the carousel items.
+ * 3. **`CarouselInterface`**: An optional component that provides control mechanisms (like next and previous buttons) and indicators (like current position).
+ *
+ * Here's a basic example of how to use the `UniversalCarousel` component:
+ *
+ * ```tsx *
+ * <UniversalCarousel>
+ *   <CarouselStage>
+ *     <img src="..." alt="" />
+ *     <img src="..." alt="" />
+ *     <img src="..." alt="" />
+ *     ...
+ *   </CarouselStage>
+ *   <CarouselInterface>
+ *     {({ prev, next }) => (
+ *       <>
+ *         <button onClick={prev}>Previous</button>
+ *         <button onClick={next}>Next</button>
+ *       </>
+ *     )}
+ *   </CarouselInterface>
+ * </UniversalCarousel>
+ * ```
+ *
+ * ## Components
+ *
+ * ### UniversalCarousel
+ *
+ * The `UniversalCarousel` component sets up the context for the carousel and its items. It doesn't render any DOM elements by itself but provides the scaffolding necessary for the `CarouselStage` and `CarouselInterface`.
+ *
+ * #### Props
+ *
+ * - `children`: The elements to be displayed within the carousel. These are usually a combination of `CarouselStage`, `CarouselInterface` and other custom elements you need.
+ *
+ * ### CarouselStage
+ *
+ * `CarouselStage` is where the carousel items are housed. It is a `ul` element that renders each child as an `li`, ensuring proper semantics and accessibility.
+ *
+ * > 👉 Review the **Carousel Stage** documentation to learn more and view usage examples.
+ *
+ * ### CarouselInterface
+ *
+ * `CarouselInterface` is an optional component that exposes controls like "next" and "previous" buttons and indicators like the current position within the carousel.
+ *
+ * > 👉 Review the **Carousel Interface** documentation to learn more and view usage examples.
+ *
+ * ## Accessibility
+ *
+ * While the UniversalCarousel component has been designed with accessibility in mind, it's important to ensure that any custom controls or additional UI elements you add are also accessible. This includes proper use of ARIA attributes, ensuring keyboard navigation is possible, when feasable, and providing alternative text for images.
+ */
+export const UniversalCarousel: FC<Props> = ({
+  enabled: enabledArg,
+  children,
+  initialIndex = 0,
+}) => {
+  let screenName = useScreenName();
+  let enabled = getResponsiveValue(enabledArg, true, screenName);
+
+  const [contextValue, setContextValue] = useState<TCarouselContext>({
+    enabled,
+    visibleItems: 0,
+    visibleIndexes: [initialIndex],
+    lastIndex: 0,
+    stageScrollLeft: 0,
+    stageScrollWidth: 0,
+    stageWidth: 0,
+    scrollToIndex: (idx, position) => {},
+    set: () => {},
+  });
+
+  const isInitialized = useRef(false);
+
+  // Scroll to the initial index when the carousel is first rendered.
+  useEffect(() => {
+    if (
+      !isInitialized.current &&
+      contextValue.scrollToIndex &&
+      initialIndex > 0
+    ) {
+      const timer = setTimeout(() => {
+        contextValue.scrollToIndex(initialIndex, 'start', 'instant');
+        isInitialized.current = true;
+      }, 0);
+      return () => clearTimeout(timer);
+    }
+  }, [initialIndex, contextValue.scrollToIndex, contextValue]);
+
+  useEffect(() => {
+    if (contextValue.enabled === enabled) {
+      return;
+    }
+
+    setContextValue(prev => ({
+      ...prev,
+      enabled,
+    }));
+  }, [contextValue.enabled, enabled, setContextValue]);
+
+  return (
+    <CarouselContext.Provider value={{ ...contextValue, set: setContextValue }}>
+      {children}
+    </CarouselContext.Provider>
+  );
+};