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

package/src/helpers/i18n.ts

@@ -0,0 +1,197 @@
+import template from 'lodash/template';
+import {
+  ComponentPropsWithoutRef,
+  ComponentType,
+  createElement,
+  JSX,
+} from 'react';
+// import * as DOMPurify from 'dompurify';
+
+/**
+ * A type to create i18n objects used in component props.
+ *
+ * ```ts
+ *
+ * type Props = {
+ *   ...
+ *   i18n?: I18NInterface<'title' | 'description'>;
+ * }
+ *
+ * // Equivalent to
+ * type Props = {
+ *  ...
+ *  i18n?: {
+ *    title?: string;
+ *    description?: string;
+ *  };
+ * };
+ *
+ * const MyComponent = ({ i18n }: Props) => {
+ *   return (
+ *     <h1>{i18n?.title ?? 'Default Title'}</h1>
+ *     <p>{i18n?.description ?? 'Default Description'}</p>
+ *     ...
+ *   );
+ * }
+ * ```
+ */
+export type I18NInterface<Name extends string, Type extends any = string> = {
+  [key in Name]: Type;
+};
+
+/**
+ * A type to extract the i18n object from a component's props.
+ *
+ * ```ts
+ * Props = {
+ *   ...
+ *   i18n?: I18NFromComponent<typeof SomeOtherComponent>;
+ * }
+ * ```
+ *
+ * You can also use it to compose i18n objects:
+ *
+ * ```ts
+ * type I18N = I18NFromComponent<typeof SomeOtherComponent> & I18NInterface<'title' | 'description'>;
+ * ```
+ *
+ * See {@link I18NInterface} for more details about the usage of i18n objects.
+ */
+export type I18NFromComponent<Component extends ComponentType<any>> =
+  ComponentPropsWithoutRef<Component>['i18n'];
+
+/**
+ * Expands given message with given parameters. Uses given fallback if the message is undefined.
+ *
+ * ```ts
+ * const expanded = expand('Hello {{name}}!', 'Hello World!', { name: 'John'});
+ * // Returns 'Hello John!'
+ *
+ * const expanded = expand(undefined, 'Hello World!', { name: 'John'});
+ * // Returns 'Hello World!'
+ * ```
+ *
+ * It's intended to be used with i18n objects:
+ *
+ * ```tsx
+ * type Props = {
+ *   userName: string;
+ *   i18n?: I18NInterface<'welcomeMessage'>;
+ * };
+ *
+ * const MyComponent = ({ userName, i18n }: Props) => {
+ *  const message = expand(i18n?.welcomeMessage, 'Hello {{name}}!', { name: userName});
+ *
+ *   return (
+ *     <h1>{message}</h1>
+ *   );
+ * }
+ * ```
+ */
+export const expandStringWithFallback = (
+  message: string | undefined,
+  fallback: string,
+  params?: Record<string, any>,
+): string => {
+  return expandString(message ?? fallback, params) ?? fallback;
+};
+
+export function expandString(
+  message: undefined,
+  params?: Record<string, any>,
+): undefined;
+export function expandString(
+  message: string,
+  params?: Record<string, any>,
+): string;
+
+/**
+ * Expands given message with given parameters.
+ *
+ * ```ts
+ * const expanded = expand('Hello {{name}}!', { name: 'John'});
+ * // Returns 'Hello John!'
+ * ```
+ */
+export function expandString(
+  message: string | undefined,
+  params?: Record<string, any>,
+): string | undefined {
+  if (typeof message === 'undefined') {
+    return undefined;
+  }
+
+  if (typeof params === 'undefined') {
+    return message;
+  }
+
+  const compiled = template(message, {
+    interpolate: /{{([\s\S]+?)}}/g,
+  });
+
+  return compiled(params);
+}
+
+/**
+ * Parses given html expression to react elements wrapped by given `as`.
+ * It's intended to be used with i18n objects. Avoid using it for other purposes.
+ * The html expression is sanitized and wrapped in a span element to avoid usage of additional third party libraries.
+ *
+ * ```tsx
+ * type Props = {
+ *   userName: string;
+ *   i18n?: I18NInterface<'welcomeMessage'>;
+ * };
+ *
+ * const MyComponent = ({ userName, i18n }: Props) => {
+ *  const message = expand(i18n?.welcomeMessage, 'Hello {{name}}!', {
+ *    name: `<strong>${userName}</strong>`,
+ *  });
+ *
+ *   return (
+ *     <h1>{parse(message)}</h1>
+ *   );
+ *
+ *   // Results in `<h1>Hello <span><strong>Jane</strong></span></h1>`.
+ * }
+ * ```
+ *
+ * If you need to modify the wrapping element, provide the element's name in the `as` argument.
+ *
+ * ```tsx
+ * type Props = {
+ *   userName: string;
+ *   i18n?: I18NInterface<'welcomeMessage'>;
+ * };
+ *
+ * const MyComponent = ({ userName, i18n }: Props) => {
+ *  const message = expand(i18n?.welcomeMessage, 'Hello {{name}}!', {
+ *    name: `<strong>${userName}</strong>`,
+ *  });
+ *
+ *   return (
+ *     <h1>{parse(message, 'div')}</h1>
+ *   );
+ *
+ *   // Results in `<h1>Hello <div><strong>Jane</strong></div></h1>`.
+ * }
+ * ```
+ */
+export const parse = (
+  htmlExpression: string,
+  as: keyof JSX.IntrinsicElements = 'span',
+) => {
+  //TODO: Re-Implement sanitation wich works on server & client components.
+  // One possible lib is: https://www.npmjs.com/package/isomorphic-dompurify
+  // But there is an issue which needs to be resolved: https://github.com/kkomelin/isomorphic-dompurify/issues/54
+  // There is a proposed solution in the GitHub issue thread which can be applied.
+
+  // const sanitized = DOMPurify.sanitize(htmlExpression);
+  const sanitized = htmlExpression;
+
+  return createElement(as, {
+    dangerouslySetInnerHTML: {
+      __html: sanitized,
+    },
+  });
+};

package/src/helpers/price.ts

@@ -0,0 +1,26 @@
+import { Locale } from '@tuic/i18n';
+
+export type Price = Intl.NumberFormatOptions & {
+  price: number;
+};
+
+/**
+ * Formats a price based on given locale.
+ *
+ * ```ts
+ * const priceExpression = formatPrice('de', {
+ *   currency: 'EUR',
+ *   price: 1234,
+ *   maximumFractionDigits: 0,
+ * });
+ * ```
+ */
+export const formatPrice = (locale: Locale, details: Price) => {
+  const formatter = new Intl.NumberFormat(locale, {
+    currencyDisplay: 'narrowSymbol',
+    ...(details ?? {}),
+    style: 'currency',
+  });
+
+  return formatter.format(details.price);
+};

package/src/helpers/responsive-property.ts

@@ -0,0 +1,118 @@
+import { ScreenName } from './screen';
+
+//TODO: Create a documentation page in storybook for these things.
+
+export type ResponsiveValue<T> = T | [T, ScreenNameIndexedValues<T>?];
+
+type ScreenNameIndexedValues<T> = {
+  [screenName in ScreenName]?: T;
+};
+
+type ScreenNameIndexedValuesWithInitial<T> = {
+  [screenName in ScreenName | 'initial']?: T;
+};
+
+/**
+ * Resolves given responsive property value to screen name indexed values including an initial key for the initial screen.
+ */
+export const getScreenIndexedResponsiveValue = <T extends any = any>(
+  propValue: ResponsiveValue<T> | undefined,
+  defaultValue: T,
+): ScreenNameIndexedValuesWithInitial<T> => {
+  if (typeof propValue === 'undefined' || !Array.isArray(propValue)) {
+    return {
+      initial: propValue ?? defaultValue,
+      xs: undefined,
+      sm: undefined,
+      md: undefined,
+      lg: undefined,
+      xl: undefined,
+      xxl: undefined,
+    };
+  }
+
+  const [initial, screenNameIndexedValues] = propValue;
+
+  if (typeof screenNameIndexedValues === 'undefined') {
+    return {
+      initial,
+      xs: undefined,
+      sm: undefined,
+      md: undefined,
+      lg: undefined,
+      xl: undefined,
+      xxl: undefined,
+    };
+  }
+
+  return {
+    initial,
+    xs: screenNameIndexedValues.xs ?? undefined,
+    sm: screenNameIndexedValues.sm ?? undefined,
+    md: screenNameIndexedValues.md ?? undefined,
+    lg: screenNameIndexedValues.lg ?? undefined,
+    xl: screenNameIndexedValues.xl ?? undefined,
+    xxl: screenNameIndexedValues.xxl ?? undefined,
+  };
+};
+
+/**
+ * Resolves given responsive property value to screen name indexed values.
+ */
+export const getScreenIndexedResponsiveValueForEachScreen = <
+  T extends any = any,
+>(
+  propValue: ResponsiveValue<T> | undefined,
+  defaultValue: T,
+): ScreenNameIndexedValues<T> => {
+  const screenNameIndexedValues = getScreenIndexedResponsiveValue(
+    propValue,
+    defaultValue,
+  );
+
+  const screens: Record<ScreenName, T | undefined> = {
+    xs: screenNameIndexedValues.xs,
+    sm: screenNameIndexedValues.sm,
+    md: screenNameIndexedValues.md,
+    lg: screenNameIndexedValues.lg,
+    xl: screenNameIndexedValues.xl,
+    xxl: screenNameIndexedValues.xxl,
+  };
+
+  screens.xs = screens.xs ?? screenNameIndexedValues.initial;
+  screens.sm = screens.sm ?? screens.xs;
+  screens.md = screens.md ?? screens.sm;
+  screens.lg = screens.lg ?? screens.md;
+  screens.xl = screens.xl ?? screens.lg;
+  screens.xxl = screens.xxl ?? screens.xl;
+
+  return screens;
+};
+
+/**
+ * Get responsive value from prop value.
+ */
+export const getResponsiveValue = <T extends any = any>(
+  propValue: ResponsiveValue<T> | undefined,
+  defaultValue: T,
+  screen?: ScreenName,
+): T => {
+  if (typeof screen !== 'undefined') {
+    const screens = getScreenIndexedResponsiveValueForEachScreen(
+      propValue,
+      defaultValue,
+    );
+
+    return screens[screen] ?? defaultValue;
+  }
+
+  if (typeof propValue === 'undefined') {
+    return defaultValue;
+  }
+
+  if (!Array.isArray(propValue)) {
+    return propValue;
+  }
+
+  return propValue[0];
+};

package/src/helpers/screen.ts

@@ -0,0 +1,14 @@
+export type ScreenName = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+
+export type Screens = {
+  [name in ScreenName]: number;
+};
+
+export const screens: Screens = {
+  xs: 360,
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  xxl: 1600,
+};

package/src/helpers/sleep.ts

@@ -0,0 +1,5 @@
+/**
+ * Wait for given number of milliseconds.
+ * This is used to simulate async action in stories.
+ */
+export const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));

package/src/helpers/slot.tsx

@@ -0,0 +1,68 @@
+import { Children, cloneElement, isValidElement, ReactNode } from 'react';
+
+/**
+ * Dynamically wraps the children intended for a Radix UI `Slot` with a specified wrapper element or component.
+ * This utility function is particularly useful when working with Radix UI's slotting mechanism, enabling the conditional
+ * application of additional styling or structure around slotted children based on the `asChild` prop.
+ *
+ * The function checks the `asChild` prop: if it's true, indicating that the children are being directly passed
+ * to a `Slot` component, it attempts to wrap only the slottable children with the provided wrapper. This is required
+ * for cases where the default rendering needs to be overridden or augmented for specific design requirements.
+ *
+ * ```tsx
+ * // Usage in a component to conditionally wrap its children with additional styling:
+ *
+ * const MyComponent = ({asChild, children}) => {
+ *   const Comp = asChild ? Slot : 'button';
+ *
+ *   return (
+ *     <Comp>
+ *       <Icon />
+ *       <Slottable>
+ *         {wrapSlottableChildren(asChild, children, (children) => (
+ *           <span className="underline">{children}</span>
+ *         ))}
+ *       </Slottable>
+ *     </Comp>
+ *   );
+ * };
+ *
+ * // Example usage:
+ * <MyComponent asChild>
+ *   <a href="#">Click Me!</a>
+ * </MyComponent>
+ *
+ * // This results in the following rendering when `asChild` is true:
+ * // <a href="#">
+ * //   <div className="icon" ... />
+ * //   <span className="underline">Click Me!</span>
+ * // </a>
+ * ```
+ */
+export const wrapSlottableChildren = (
+  asChild: boolean | undefined,
+  children: ReactNode,
+  wrapper: (children: ReactNode) => ReactNode,
+) => {
+  if (!children) {
+    return null;
+  }
+
+  if (!asChild) {
+    return wrapper(children);
+  }
+
+  const childrenAsArray = Children.toArray(children);
+
+  if (childrenAsArray.length !== 1) {
+    return wrapper(children);
+  }
+
+  const child = childrenAsArray[0];
+
+  if (!isValidElement(child)) {
+    return wrapper(children);
+  }
+
+  return cloneElement(child, undefined, wrapper(child.props.children));
+};

package/src/helpers/ssr.ts

@@ -0,0 +1,5 @@
+import * as process from 'process';
+
+export function isSSR() {
+  return typeof window === 'undefined';
+}

package/src/helpers/store.ts

@@ -0,0 +1,75 @@
+export type Store<T extends any = unknown> = {
+  /**
+   * Returns the value from the store.
+   */
+  get: () => T;
+
+  /**
+   * Sets a new value in the store.
+   */
+  set: (value: SetValueType<T>) => void;
+
+  /**
+   * Adds a change listener to the store.
+   */
+  onChange: (handleChange: ChangeListener<T>) => () => void;
+};
+
+type ChangeListener<T> = (value: T) => void;
+
+type SetValueType<T> = T | ((prev: T) => T);
+
+function valueIsClosure<T>(value: SetValueType<T>): value is (prev: T) => T {
+  return typeof value === 'function';
+}
+
+export function createStore<T>(initialValue: T): Store<T>;
+export function createStore<T extends any = undefined>(): Store<T | undefined>;
+
+/**
+ * Creates a store. You can utilize the store for simple shared state.
+ *
+ * ### Create a Store
+ *
+ * Make sure to create your store only once and save it in a dedicated file.
+ *
+ * ```tsx
+ * // my-count-store.ts
+ *
+ * export const myCountStore = createStore<number>(0);
+ * ```
+ *
+ * ### Hook
+ *
+ * Usually you would pair the store with the usage of the {@link useStore} hook -- head over to learn how to use a created store in your components.
+ *
+ * The hook abstracts all the React related boilerplate away, so you can use the store like a simple `useState()`.
+ */
+export function createStore<T = undefined>(
+  initialValue?: T,
+): Store<T | undefined> {
+  let value = initialValue;
+
+  const listeners: ChangeListener<T | undefined>[] = [];
+
+  return {
+    get: () => value,
+    set: newValue => {
+      if (valueIsClosure(newValue)) {
+        value = newValue(value);
+      } else {
+        value = newValue;
+      }
+
+      listeners.forEach(listener => listener(value));
+    },
+    onChange: handleChange => {
+      listeners.push(handleChange);
+      const idx = listeners.length - 1;
+
+      return () => {
+        listeners.splice(idx, 1);
+      };
+    },
+  };
+}

package/src/helpers/types.ts

@@ -0,0 +1,18 @@
+import type {
+  EventClickArea,
+  EventClickAttributes,
+  EventClickElement,
+  FormAttributionAttributes,
+} from '@tuic/tracking/src/types';
+
+export type DataAttributes = {
+  [EventClickAttributes.Area]?: EventClickArea | undefined;
+  [EventClickAttributes.Element]?: EventClickElement | undefined;
+  [EventClickAttributes.Category]?: string | undefined;
+  [EventClickAttributes.Label]?: string | undefined;
+  [EventClickAttributes.Module]?: string | undefined;
+  [EventClickAttributes.Dialog]?: string | undefined;
+  [FormAttributionAttributes.FieldName]?: string | undefined;
+  [FormAttributionAttributes.FormName]?: string | undefined;
+  [key: `data-${string}`]: string | undefined;
+};

package/src/helpers/utils.ts

@@ -0,0 +1,3 @@
+export function isNonNullable<T>(check: T): check is NonNullable<T> {
+  return check !== null && check !== undefined;
+}

package/src/hooks/use-active-screen-names.ts

@@ -0,0 +1,100 @@
+'use client';
+
+import { Dispatch, SetStateAction, useEffect, useState } from 'react';
+import { ScreenName, screens } from '../helpers/screen';
+
+type ActiveScreens = {
+  [name in ScreenName]: boolean;
+};
+
+type ActiveScreensQueryLists = {
+  [name in ScreenName]: MediaQueryList;
+};
+
+const listsToState = (lists: ActiveScreensQueryLists): ActiveScreens => ({
+  xs: lists.xs.matches,
+  sm: lists.sm.matches,
+  md: lists.md.matches,
+  lg: lists.lg.matches,
+  xl: lists.xl.matches,
+  xxl: lists.xxl.matches,
+});
+
+const createChangeHandler = (
+  name: ScreenName,
+  setScreenState: Dispatch<SetStateAction<ActiveScreens>>,
+) => {
+  return ({ matches }: MediaQueryListEvent) => {
+    setScreenState(prev => ({
+      ...prev,
+      [name]: matches,
+    }));
+  };
+};
+
+/**
+ * Returns all active screen names.
+ * The returned object's keys are the {@link ScreenName}s and the values indicates
+ * if the screen name is currently active (matches the underlying media query).
+ *
+ * ```tsx
+ * const activeScreens = useActiveScreenNames();
+ *
+ * if (activeScreens.md) {
+ *   ...
+ * }
+ * ```
+ *
+ * This is a hook which keeps track of all the available screen names.
+ * Normally you'd be better off using {@link useScreenName} or {@link useScreenNameAtLeast}.
+ */
+export const useActiveScreenNames = (
+  ssrValues: ActiveScreens = {
+    xs: false,
+    sm: false,
+    md: false,
+    lg: false,
+    xl: false,
+    xxl: false,
+  },
+): ActiveScreens => {
+  const [screenState, setScreenState] = useState<ActiveScreens>(ssrValues);
+
+  useEffect(() => {
+    const lists = {
+      xs: window.matchMedia(`(min-width: ${screens.xs}px)`),
+      sm: window.matchMedia(`(min-width: ${screens.sm}px)`),
+      md: window.matchMedia(`(min-width: ${screens.md}px)`),
+      lg: window.matchMedia(`(min-width: ${screens.lg}px)`),
+      xl: window.matchMedia(`(min-width: ${screens.xl}px)`),
+      xxl: window.matchMedia(`(min-width: ${screens.xxl}px)`),
+    };
+
+    setScreenState(listsToState(lists));
+
+    const handleXsChange = createChangeHandler('xs', setScreenState);
+    const handleSmChange = createChangeHandler('sm', setScreenState);
+    const handleMdChange = createChangeHandler('md', setScreenState);
+    const handleLgChange = createChangeHandler('lg', setScreenState);
+    const handleXlChange = createChangeHandler('xl', setScreenState);
+    const handleXxlChange = createChangeHandler('xxl', setScreenState);
+
+    lists.xs.addEventListener('change', handleXsChange);
+    lists.sm.addEventListener('change', handleSmChange);
+    lists.md.addEventListener('change', handleMdChange);
+    lists.lg.addEventListener('change', handleLgChange);
+    lists.xl.addEventListener('change', handleXlChange);
+    lists.xxl.addEventListener('change', handleXxlChange);
+
+    return () => {
+      lists.xs.removeEventListener('change', handleXsChange);
+      lists.sm.removeEventListener('change', handleSmChange);
+      lists.md.removeEventListener('change', handleMdChange);
+      lists.lg.removeEventListener('change', handleLgChange);
+      lists.xl.removeEventListener('change', handleXlChange);
+      lists.xxl.removeEventListener('change', handleXxlChange);
+    };
+  }, []);
+
+  return screenState;
+};