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

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

@@ -0,0 +1,206 @@
+import {
+  Children,
+  ComponentPropsWithoutRef,
+  createElement,
+  MouseEventHandler,
+  ReactElement,
+  RefObject,
+} from 'react';
+import { isElement, isFragment } from 'react-is';
+import { CarouselStage } from './CarouselStage';
+import { ScrollToIndex } from './CarouselInterface';
+import { logger } from '@tuic/logger';
+
+type StageRef = RefObject<HTMLUListElement>;
+
+type ItemsChildren = ComponentPropsWithoutRef<typeof CarouselStage>['children'];
+
+/**
+ * Converts children props of CarouselItems into an array of React elements, filtering out any non-element nodes.
+ */
+export const getChildrenAsArrayOfElements = (
+  children: ItemsChildren,
+): ReactElement[] => {
+  const asArray = Children.toArray(children).filter(
+    (node): node is ReactElement => isElement(node),
+  );
+
+  if (asArray.length !== 1) {
+    return asArray;
+  }
+
+  // Check if the only child is a fragment ...
+  const maybeFragment = asArray[0];
+
+  if (!isFragment(maybeFragment)) {
+    return asArray;
+  }
+
+  // ... and if so, return its children instead.
+  // We could make this recursive, but let's not dive too deep into the rabbit hole.
+  return Children.toArray(maybeFragment.props.children).filter(
+    (node): node is ReactElement => isElement(node),
+  );
+};
+
+/**
+ * Creates a function to scroll the carousel to a specific index with customizable position and scroll behavior.
+ *
+ * @param stageRef - Reference to the carousel container element.
+ * @param lastIdx - The index of the last item in the carousel.
+ * @returns A function that scrolls the carousel to a specified index.
+ */
+export const createToIndexScroller = (
+  stageRef: StageRef,
+  lastIdx: number,
+): ScrollToIndex => {
+  return (
+    idx: number,
+    position: 'start' | 'center' | 'end',
+    scrollBehavior: 'auto' | 'smooth' | 'instant' = 'smooth',
+  ) => {
+    if (!stageRef.current) {
+      logger.error('Stage reference is not available.');
+      return;
+    }
+
+    // Verify that the index is within bounds & wrap around if necessary.
+    if (idx < 0) {
+      idx = lastIdx;
+    }
+
+    if (idx > lastIdx) {
+      idx = 0;
+    }
+
+    // Get the target list item
+    const target = [
+      ...stageRef.current.querySelectorAll<HTMLLIElement>(':scope > li'),
+    ][idx];
+
+    if (!target) {
+      logger.error(`Target not found at index ${idx}.`);
+      return;
+    }
+
+    const { offsetLeft, offsetWidth } = target;
+    const stageWidth = stageRef.current.offsetWidth;
+    let left = offsetLeft;
+
+    // Adjust scroll position based on the `position` argument
+    if (position === 'center') {
+      left = offsetLeft + offsetWidth / 2 - stageWidth / 2;
+    } else if (position === 'end') {
+      left = offsetLeft + offsetWidth - stageWidth;
+    }
+
+    /*
+    logger.debug(
+      `Scrolling to index ${idx} (position: ${position}) with left offset: ${left}`,
+    );
+    */
+
+    // Scroll to the calculated position
+    stageRef.current.scrollTo({
+      left,
+      behavior: scrollBehavior,
+    });
+  };
+};
+
+/**
+ * Calculate the visible percentage of an item in the carousel based on its current position
+ * and the scroll position of the carousel.
+ */
+const calculateVisiblePercentage = (
+  list: HTMLUListElement,
+  item: HTMLLIElement,
+) => {
+  // Calculate the relative position of the left point of the item within the carousel.
+  let leftPoint = item.offsetLeft - list.scrollLeft;
+
+  // Set to zero if the point is beyond the left border of the carousel.
+  if (leftPoint < 0) {
+    leftPoint = 0;
+  }
+
+  // Calculate the relative position of the right point of the item within the carousel.
+  let rightPoint = item.offsetLeft + item.offsetWidth - list.scrollLeft;
+
+  // Set to the width of the carousel if the point is beyond the right border of the carousel.
+  if (rightPoint > list.offsetWidth) {
+    rightPoint = list.offsetWidth;
+  }
+
+  // Set to zero if the point is beyond the left border of the carousel.
+  if (rightPoint < 0) {
+    rightPoint = 0;
+  }
+
+  // As we have the positions calculated and contained within the stage, we can calculate their distance.
+  let visiblePx = rightPoint - leftPoint;
+
+  // It shouldn't be zero, but let's be cautious.
+  if (visiblePx < 0) {
+    visiblePx = 0;
+  }
+
+  // Calculate the percentage of the item that is visible.
+  const visiblePercentage = (visiblePx / item.offsetWidth) * 100;
+
+  // Cap the percentage at 100% to avoid rounding errors.
+  return visiblePercentage > 100 ? 100 : visiblePercentage;
+};
+
+/**
+ * Retrieve the indexes of items in the carousel that are currently visible.
+ */
+export const getVisibleIndexes = (stageRef: StageRef): number[] => {
+  // If the stage is not yet rendered, return a visible index of 0.
+  if (!stageRef.current) {
+    return [0];
+  }
+
+  const stage = stageRef.current;
+  const stageWidth = stageRef.current.offsetWidth;
+
+  // If the stage has no width, return a visible index of 0.
+  if (stageWidth === 0) {
+    return [0];
+  }
+
+  //TODO: Check if this has enough browser support: https://caniuse.com/?search=queryselector%20scope
+  const percentages = [
+    ...stage.querySelectorAll<HTMLLIElement>(':scope > li'),
+  ].map((item, idx) => {
+    return calculateVisiblePercentage(stage, item);
+  });
+
+  // Find the highest percentage and use it as the maximum, but reduce it by 1%, so we add a slight buffer.
+  const maxPercentage = Math.max(...percentages) * 0.99;
+
+  // Find the indexes of items that have a percentage equal to or higher than the maximum.
+  const visibleIndexes = percentages
+    .map((percentage, idx) => {
+      return percentage >= maxPercentage ? idx : -1;
+    })
+    .filter(idx => idx >= 0);
+
+  // If no items are visible, return a visible index of 0, otherwise return the indexes of the visible items.
+  return visibleIndexes.length === 0 ? [0] : visibleIndexes;
+};
+
+/**
+ * Combines multiple event handlers into a single event handler.
+ */
+export const combineEventHandlers = (
+  events: (MouseEventHandler<HTMLUListElement> | undefined)[],
+): MouseEventHandler<HTMLUListElement> => {
+  const filtered = events.filter(
+    (event): event is MouseEventHandler => typeof event === 'function',
+  );
+
+  return ev => {
+    filtered.forEach(handler => handler(ev));
+  };
+};

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

@@ -0,0 +1,4 @@
+export * from './CarouselDefaultPagination';
+export * from './CarouselInterface';
+export * from './CarouselStage';
+export * from './UniversalCarousel';

package/src/helpers/children.ts

@@ -0,0 +1,27 @@
+import { Children, PropsWithChildren, ReactElement } from 'react';
+import { isElement, isFragment } from 'react-is';
+
+export const getChildrenAsArrayOfElements = (
+  children: PropsWithChildren['children'],
+): ReactElement[] => {
+  const asArray = Children.toArray(children).filter(
+    (node): node is ReactElement => isElement(node),
+  );
+
+  if (asArray.length !== 1) {
+    return asArray;
+  }
+
+  // Check if the only child is a fragment ...
+  const maybeFragment = asArray[0];
+
+  if (!isFragment(maybeFragment)) {
+    return asArray;
+  }
+
+  // ... and if so, return its children instead.
+  // We could make this recursive, but let's not dive too deep into the rabbit hole.
+  return Children.toArray(maybeFragment.props.children).filter(
+    (node): node is ReactElement => isElement(node),
+  );
+};

package/src/helpers/cookies.ts

@@ -0,0 +1,22 @@
+'use client';
+
+export function setCookie(name: string, value: string | number, days: number) {
+  const date = new Date();
+  date.setTime(date.getTime() + days * 24 * 60 * 60 * 1000);
+  const expires = 'expires=' + date.toUTCString();
+  document.cookie = name + '=' + value + ';' + expires + ';path=/';
+}
+
+export function getCookie(name: string): string | null {
+  const cookieName = `${encodeURIComponent(name)}=`;
+  const cookies = document.cookie.split(';');
+
+  for (let cookie of cookies) {
+    cookie = cookie.trim();
+    if (cookie.startsWith(cookieName)) {
+      return decodeURIComponent(cookie.substring(cookieName.length));
+    }
+  }
+
+  return null;
+}

package/src/helpers/dateFormat.ts

@@ -0,0 +1,245 @@
+import { DateTime, Settings } from 'luxon';
+
+/*
+ * Central collection of commonly used date formats in accordance to the TUIC guidelines and NOT to ISO-8601.
+ * Resources on the ISO-8601 as reference for comparison:
+ * - https://en.wikipedia.org/wiki/List_of_date_formats_by_country
+ * - https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom
+ * - https://moment.github.io/luxon/#/formatting
+ */
+
+const getValidLocale = (locale: undefined | string) => {
+  if (locale === 'en') {
+    return 'en-GB';
+  }
+  return 'de';
+};
+
+const getValidDate = (
+  date: undefined | Date | DateTime,
+  locale: undefined | string = 'de',
+): undefined | DateTime => {
+  if (!date) {
+    return undefined;
+  }
+  const newDate = date instanceof DateTime ? date : DateTime.fromJSDate(date);
+  if (!newDate || !newDate.isValid) {
+    return undefined;
+  }
+  return newDate.setLocale(getValidLocale(locale));
+};
+
+/**
+ * Returns a rezoned datetime instance.
+ */
+export const getRezonedDateTime = (dateTime: DateTime | string) => {
+  const datetime =
+    typeof dateTime !== 'string'
+      ? dateTime
+      : DateTime.fromISO(dateTime, {
+          setZone: true,
+        });
+
+  return datetime.setZone(Settings.defaultZone, {
+    keepLocalTime: true,
+  });
+};
+
+const monthNamesShort_enGB: { [key: number]: string } = {
+  1: 'Jan',
+  2: 'Feb',
+  3: 'Mar',
+  4: 'Apr',
+  5: 'May',
+  6: 'Jun',
+  7: 'Jul',
+  8: 'Aug',
+  9: 'Sep',
+  10: 'Oct',
+  11: 'Nov',
+  12: 'Dec',
+};
+
+/**
+ * European Standard format:  09.09.2024   or shortened as   09.09.
+ */
+export const formatDateEuropeanStandard = (
+  date: undefined | Date | DateTime,
+  locale: undefined | string = 'de',
+  short: boolean = false,
+): string => {
+  const validDate = getValidDate(date, locale);
+  return (
+    (short
+      ? validDate?.toFormat('dd.MM.')
+      : validDate?.toFormat('dd.MM.yyyy')) ?? ''
+  );
+};
+
+/**
+ * Date with written month, shortened:
+ * i.e. for 'de':     27. Sept. 2024
+ * i.e. for 'en-GB':  27 Sep 2024
+ */
+export const formatDateWithWrittenMonthShortened = (
+  date: undefined | Date | DateTime,
+  locale: undefined | string = 'de',
+): string => {
+  // English date
+  const validDate = getValidDate(date, locale);
+  const day = validDate?.day;
+  const month = validDate?.month;
+  const year = validDate?.year;
+  if (locale === 'en' && !!day && !!month && !!year) {
+    return `${day} ${monthNamesShort_enGB[month]} ${year}`;
+  }
+
+  return (
+    getValidDate(date, locale)?.toLocaleString({
+      day: '2-digit',
+      month: 'short',
+      year: 'numeric',
+    }) ?? ''
+  );
+};
+
+/**
+ * Date with weekday, shortened:
+ * i.e. for 'de':     Fr., 30. Sep.
+ * i.e. for 'en-GB':  Fr, 30 Sep
+ */
+export const formatDateWithWeekdayShortened = (
+  date: undefined | Date | DateTime,
+  locale: undefined | string = 'de',
+): string => {
+  // English date
+  const validDate = getValidDate(date, locale);
+  const day = validDate?.day;
+  const weekday: undefined | string = validDate?.toLocaleString({
+    weekday: 'short',
+  });
+  const month = validDate?.month;
+  if (locale === 'en' && !!weekday && !!day && !!month) {
+    return `${weekday}, ${day} ${monthNamesShort_enGB[month]}`;
+  }
+
+  return (
+    getValidDate(date, locale)?.toLocaleString({
+      weekday: 'short',
+      day: '2-digit',
+      month: 'short',
+    }) ?? ''
+  );
+};
+
+/**
+ * Date with weekday and year, shortened:
+ * i.e. for 'de':     Fr., 30. Aug. 2024
+ * i.e. for 'en-GB':  Fr, 30 Aug 2024
+ */
+export const formatDateWithWeekdayAndYearShortened = (
+  date: undefined | Date | DateTime,
+  locale: undefined | string = 'de',
+): string => {
+  // English date
+  const validDate = getValidDate(date, locale);
+  const day = validDate?.day;
+  const weekday: undefined | string = validDate?.toLocaleString({
+    weekday: 'short',
+  });
+  const month = validDate?.month;
+  const year = validDate?.year;
+  if (locale === 'en' && !!weekday && !!day && !!month && !!year) {
+    return `${weekday}, ${day} ${monthNamesShort_enGB[month]} ${year}`;
+  }
+
+  return (
+    getValidDate(date, locale)?.toLocaleString({
+      weekday: 'short',
+      day: '2-digit',
+      month: 'short',
+      year: 'numeric',
+    }) ?? ''
+  );
+};
+
+/*
+ * ISO stabdard dates
+ */
+/**
+ * European Standard format:
+ * i.e. for 'de':     09.09.2024   or shortened as   09.09.
+ * i.e. for 'en-GB':  09/09/2024   or shortened as   09/09
+ */
+export const formatDateEuropeanStandardISO8601 = (
+  date: undefined | Date | DateTime,
+  locale: undefined | string = 'de',
+  short: boolean = false,
+): string => {
+  return (
+    getValidDate(date, locale)?.toLocaleString({
+      day: '2-digit',
+      month: '2-digit',
+      year: short ? undefined : 'numeric',
+    }) ?? ''
+  );
+};
+
+/**
+ * Date with weekday, shortened:
+ * i.e. for 'de':     Fr., 30. Aug.
+ * i.e. for 'en-GB':  Fr, 30 Aug
+ */
+export const formatDateWithWeekdayShortenedISO8601 = (
+  date: undefined | Date | DateTime,
+  locale: undefined | string = 'de',
+): string => {
+  return (
+    getValidDate(date, locale)?.toLocaleString({
+      weekday: 'short',
+      day: '2-digit',
+      month: 'short',
+    }) ?? ''
+  );
+};
+
+/**
+ * Date with weekday and year, shortened:
+ * i.e. for 'de':     Fr., 30. Aug. 2024
+ * i.e. for 'en-GB':  Fr, 30 Aug 2024
+ */
+export const formatDateWithWeekdayAndYearShortenedISO8601 = (
+  date: undefined | Date | DateTime,
+  locale: undefined | string = 'de',
+): string => {
+  return (
+    getValidDate(date, locale)?.toLocaleString({
+      weekday: 'short',
+      day: '2-digit',
+      month: 'short',
+      year: 'numeric',
+    }) ?? ''
+  );
+};
+
+export type DateSegment = 'day' | 'hour' | 'minute' | 'second';
+export function getDateSegmentDifference(
+  date: Date,
+  diffType: DateSegment,
+): number {
+  const now = new Date();
+  const diffInMs = date.getTime() - now.getTime();
+
+  switch (diffType) {
+    case 'day':
+      return Math.floor(diffInMs / (1000 * 60 * 60 * 24));
+    case 'hour':
+      return Math.floor((diffInMs % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
+    case 'minute':
+      return Math.floor((diffInMs % (1000 * 60 * 60)) / (1000 * 60));
+    case 'second':
+      return Math.floor((diffInMs % (1000 * 60)) / 1000);
+    default:
+      return 0;
+  }
+}

package/src/helpers/dateToYearMonthDay.ts

@@ -0,0 +1,17 @@
+/**
+ * Simple helper to convert a date into the 'YYYY-MM-DD' string format.
+ * @param date
+ * @param locale
+ */
+export function dateToYearMonthDay(date: Date, locale: string = 'de'): string {
+  const fromYear = new Intl.DateTimeFormat(locale, { year: 'numeric' }).format(
+    date,
+  );
+  const fromMonth = new Intl.DateTimeFormat(locale, {
+    month: '2-digit',
+  }).format(date);
+  const fromDay = new Intl.DateTimeFormat(locale, { day: '2-digit' }).format(
+    date,
+  );
+  return `${fromYear}-${fromMonth}-${fromDay}`;
+}

package/src/helpers/elementVisibility.ts

@@ -0,0 +1,53 @@
+/**
+ * getMostVisibleElement
+ * Method to determine a single element from a list of elements that is most visible on the current screen.
+ *
+ * @param elements
+ */
+export const getMostVisibleElement = (
+  elements: HTMLDivElement[] | HTMLCollectionOf<HTMLDivElement>,
+): undefined | HTMLDivElement => {
+  let currentElement = undefined;
+  const viewportHeight: number = window.innerHeight;
+  let highestVisibleHeightOnScreen: number = 0;
+
+  for (let i = 0; i < elements.length; i++) {
+    const visiblePixel = getVisibleHeightInPixel(elements[i], viewportHeight);
+    if (visiblePixel > highestVisibleHeightOnScreen) {
+      highestVisibleHeightOnScreen = visiblePixel;
+      currentElement = elements[i];
+    }
+  }
+
+  return currentElement;
+};
+
+const getVisibleHeightInPixel = (
+  element: HTMLDivElement,
+  viewportHeight: number,
+): number => {
+  const rect = element.getBoundingClientRect();
+  const height = rect.bottom - rect.top;
+  const visible = {
+    top: rect.top >= 0 && rect.top < viewportHeight,
+    bottom: rect.bottom > 0 && rect.bottom < viewportHeight,
+  };
+  let visiblePixel: number = 0;
+
+  if (visible.top && visible.bottom) {
+    // Whole element is visible
+    visiblePixel = height;
+  } else if (visible.top) {
+    visiblePixel = viewportHeight - rect.top;
+  } else if (visible.bottom) {
+    visiblePixel = rect.bottom;
+  } else if (height > viewportHeight && rect.top < 0) {
+    const absTop = Math.abs(rect.top);
+    if (absTop < height) {
+      // Part of the element is visible
+      visiblePixel = height - absTop;
+    }
+  }
+
+  return visiblePixel;
+};