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

package/src/components/core/FavoriteButton/FavoriteButton.tsx

@@ -0,0 +1,294 @@
+'use client';
+
+import {
+  AnchorHTMLAttributes,
+  ButtonHTMLAttributes,
+  Dispatch,
+  forwardRef,
+  ForwardRefRenderFunction,
+  ReactNode,
+  SetStateAction,
+  useState,
+} from 'react';
+import { twMerge } from 'tailwind-merge';
+import { Icon } from '../../core/Icon';
+
+/**
+ * Handler for click events, expected to manage active state toggling and possibly return a promise for async handling.
+ */
+type OnClickHandler = (
+  active: boolean,
+) => void | boolean | Promise<void | boolean>;
+
+type CommonProps = {
+  className?: string;
+  /**
+   * The initial 'active' state of the component when it mounts.
+   *
+   * ```tsx
+   * <FavoriteButton defaultActive={true} />
+   * ```
+   */
+  defaultActive?: boolean;
+
+  /**
+   * A React node or a function that returns a React node.
+   *
+   * ```tsx
+   * <FavoriteButton>
+   *   <Icon name="eye-off" size="md" />
+   * </FavoriteButton>
+   * ```
+   *
+   * The function receives the current `active` state as a parameter,
+   * enabling the rendering of different content based on the state.
+   *
+   * ```tsx
+   * <FavoriteButton>
+   *   {(active) => (
+   *     <Icon name={active ? 'eye-off' : 'eye-empty'} size="md" />
+   *   )}
+   * </FavoriteButton>
+   * ```
+   *
+   */
+  children?: ReactNode | ((active: boolean) => ReactNode);
+};
+
+type PropsAsButton = CommonProps &
+  Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'children'> & {
+    as: 'button';
+
+    /**
+     * Callback triggered when the component is clicked.
+     *
+     * The handler receives a boolean argument indicating the next 'active' state.
+     * - If the handler returns a boolean, the component's active state will be set to the returned value.
+     * - If a Promise is returned, the component will wait for the Promise to resolve and use the resolved boolean value to update the active state.
+     *
+     * ```tsx
+     * const handleClick = (nextActiveState: boolean) => {
+     *   // Your handling logic here
+     *   return !nextActiveState; // Or return a promise that resolves to a boolean
+     * };
+     *
+     * <FavoriteButton onClick={handleClick} />
+     * ```
+     */
+    onClick?: OnClickHandler;
+  };
+
+type PropsAsAnchor = CommonProps &
+  AnchorHTMLAttributes<HTMLAnchorElement> & {
+    as: 'a';
+  };
+
+type Props = PropsAsButton | PropsAsAnchor;
+
+const createClickHandler = (
+  active: boolean,
+  setPending: Dispatch<SetStateAction<boolean | undefined>>,
+  setActive: Dispatch<SetStateAction<boolean>>,
+  onClick: OnClickHandler | undefined,
+) => {
+  return async () => {
+    if (!onClick) {
+      return;
+    }
+
+    setPending(true);
+
+    const nextActive = !active;
+
+    setActive(nextActive);
+
+    const returnValue = await onClick(nextActive);
+
+    setPending(false);
+
+    if (typeof returnValue !== 'boolean') {
+      return;
+    }
+
+    setActive(returnValue);
+  };
+};
+
+const renderDefaultIcon = (active: boolean) => {
+  if (active) {
+    return (
+      <Icon
+        name="heart-filled"
+        size="md"
+        className="fill-surface-primary-100 text-marine-high-emphasis"
+      />
+    );
+  }
+
+  return (
+    <>
+      <Icon name="heart" size="md" className="sm:group-hover:hidden" />
+      <Icon
+        name="heart-filled"
+        size="md"
+        className="hidden sm:group-hover:block sm:group-hover:fill-surface-secondary-100"
+      />
+    </>
+  );
+};
+
+const renderChildren = (
+  active: boolean,
+  children: Props['children'],
+): ReactNode => {
+  if (typeof children === 'undefined') {
+    return renderDefaultIcon(active);
+  }
+
+  if (typeof children === 'function') {
+    return children(active);
+  }
+
+  return children;
+};
+
+const FavoriteButtonRenderFunction: ForwardRefRenderFunction<
+  HTMLButtonElement | HTMLAnchorElement,
+  Props
+> = (props, ref?) => {
+  const {
+    className,
+    as = 'button',
+    defaultActive = false,
+    onClick,
+    children,
+    ...rest
+  } = props;
+
+  const [active, setActive] = useState(defaultActive);
+  const [pending, setPending] = useState<boolean>();
+
+  const handleClick =
+    as === 'a'
+      ? onClick
+      : createClickHandler(
+          active,
+          setPending,
+          setActive,
+          onClick as OnClickHandler | undefined,
+        );
+
+  const shouldAnimate = typeof pending !== 'undefined' && as !== 'a';
+  const shouldTransition = as !== 'a';
+
+  const elementClassList = [
+    'group inline-flex p-2.5 appearance-none rounded-full',
+    'focus:outline-none focus-visible:shadow-focus-state active:bg-surface-primary-40 disabled:pointer-events-none',
+    active
+      ? 'bg-surface-primary-80 text-marine-high-emphasis'
+      : 'text-marine-high-emphasis sm:hover:bg-surface-secondary-7 sm:hover:text-marine-high-emphasis',
+  ];
+
+  const iconWrapperClassList = [
+    shouldTransition && 'group-active:transition-transform',
+    shouldAnimate ? 'animate-[favorite-pulse_600ms_ease-in-out]' : '',
+    shouldTransition && !active
+      ? 'group-active:scale-[0.66] group-active:animate-none'
+      : '',
+  ];
+
+  const Element = as;
+
+  return (
+    <Element
+      className={twMerge(elementClassList.join(' '), className)}
+      onClick={handleClick}
+      disabled={pending}
+      ref={ref}
+      {...(rest as any)}
+    >
+      <div className={iconWrapperClassList.join(' ')}>
+        {renderChildren(active, children)}
+      </div>
+    </Element>
+  );
+};
+
+/**
+ * `FavoriteButton` is a component, for creating interactive buttons, offering various customization options to fit into different use cases such as liking or favoriting items.
+ *
+ * ```tsx
+ * const handleClick = (active) => alert(active ? 'Liked' : 'Unliked');
+ * <FavoriteButton onClick={handleClick} />
+ * ```
+ *
+ * With the above code, a `FavoriteButton` is rendered using default icons, and it logs the new active state upon being clicked.
+ *
+ * ## Available Props
+ *
+ * | Name | Type | Description |
+ * |---|---|--------|
+ * | `defaultActive`| `boolean` | Sets the initial active state of the component. |
+ * | `onClick` | `OnClickHandler` | Handles click events and state transitions. |
+ * | `as` | `"button"` \| `"a"`  | Determines the HTML element type. |
+ * | `children` | `ReactNode` \| (active: boolean) => ReactNode | Supply your custom icon using children. |
+ * | ...rest |  | Extra props which are forwarded to the element. |
+ *
+ * ## Icon Management
+ *
+ * Iconography within the `FavoriteButton` component is managed dynamically by adopting a strategy that employs render props. This allows you to have absolute control over how icons should appear across distinct states.
+ *
+ * ### Simple Custom Icon Rendering
+ *
+ * For simple use cases just provide an icon as the child of the favorite button.
+ *
+ * ```tsx
+ * <FavoriteButton>
+ *   <Icon name="eye-empty" size="md" />
+ * </FavoriteButton>
+ * ```
+ *
+ * ### Advanced Icon Handling and Styling with Render Props
+ *
+ * Utilize render props for straightforward and effective control over icon presentation and styling across different component states. By employing a function that takes the active state as an argument, you can precisely define icons and apply styles for both the active and inactive states dynamically. The active parameter allows for conditional rendering of icons and the application of styles as per requirements:
+ *
+ * ```tsx
+ * // Icon based on state
+ *
+ * <FavoriteButton>
+ *   {active => <Icon name={active ? 'eye-off' : 'eye-empty'} size="md" />}
+ * </FavoriteButton>
+ *
+ * In the presented code snippet, the `FavoriteButton` renders a colored and filled airplane icon when in an active state. On the other hand, during an inactive state, it depicts the same airplane icon, modifying its color upon hover.
+ *
+ * Using render props in such a manner awards you a significant level of control over the management of icons and their respective styles, fostering subtle visual feedback in response to user interactions with the `FavoriteButton` component. This approach is particularly beneficial in situations that demand comprehensive customization and dynamic styling predicated upon component states, ensuring that your UI remains both dynamic and visually consistent.
+ *
+ * ## Handling Click Events with `onClick`
+ *
+ * Manage click events and synchronize the component’s active state with potential asynchronous actions like API calls via `onClick`:
+ *
+ * ```tsx
+ * const handleClick = async (active) => {
+ *   const serverResponse = await someAsyncAction();
+ *   return serverResponse.liked;
+ * };
+ *
+ * <FavoriteButton onClick={handleClick} />
+ * ```
+ *
+ * Here, upon a user click, the component instantaneously toggles its state. Then, `someAsyncAction` communicates with a server and once the response is returned from the handler, the component ensures to align and represent this new state in the UI.
+ *
+ * ## Rendering as Anchor
+ *
+ * Using `FavoriteButton` as an anchor (`a`) element is straightforward:
+ *
+ * ```tsx
+ * <FavoriteButton as="a" href="#" />
+ * ```
+ *
+ * However, it's pivotal to note that when `FavoriteButton` is rendered as an anchor element (`as="a"`), it operates purely as a navigational link, devoid of internal state management or animations associated with state changes. It exists simply as a stylized link, diverting users to specified URLs without toggling between states or triggering animations on click events.
+ */
+export const FavoriteButton = forwardRef<
+  HTMLButtonElement | HTMLAnchorElement,
+  Props
+>(FavoriteButtonRenderFunction) as typeof FavoriteButtonRenderFunction;

package/src/components/core/FavoriteButton/index.ts

@@ -0,0 +1 @@
+export * from './FavoriteButton';

package/src/components/core/Fieldset/Fieldset.tsx

@@ -0,0 +1,42 @@
+import {
+  FC,
+  PropsWithChildren,
+  ReactNode,
+  FieldsetHTMLAttributes,
+} from 'react';
+import { twMerge } from '@tui-cruises/mein-schiff-web-tailwind-config';
+
+type ElementAttributes = FieldsetHTMLAttributes<HTMLFieldSetElement>;
+
+export type FieldsetProps = ElementAttributes &
+  PropsWithChildren<{
+    headline?: ReactNode;
+    copy?: ReactNode;
+  }>;
+
+export const Fieldset: FC<FieldsetProps> = ({
+  children,
+  headline,
+  copy,
+  ...attrs
+}) => {
+  return (
+    <fieldset
+      {...attrs}
+      className={twMerge(
+        attrs.className,
+        'space-y-8 text-marine-high-emphasis',
+      )}
+    >
+      {(headline || copy) && (
+        <div className="space-y-4">
+          {headline && <div className="headline-md">{headline}</div>}
+
+          {copy && <div>{copy}</div>}
+        </div>
+      )}
+
+      {children && <div className="space-y-4">{children}</div>}
+    </fieldset>
+  );
+};

package/src/components/core/Fieldset/index.ts

@@ -0,0 +1 @@
+export * from './Fieldset';

package/src/components/core/FormLabel/FormLabel.tsx

@@ -0,0 +1,88 @@
+import {
+  forwardRef,
+  LabelHTMLAttributes,
+  ForwardRefRenderFunction,
+} from 'react';
+import { twJoin } from 'tailwind-merge';
+import { Slot, Slottable } from '@radix-ui/react-slot';
+
+export type FormLabelProps = LabelHTMLAttributes<HTMLLabelElement> & {
+  asChild?: boolean;
+  /** Indicates if the associated field is required. */
+  required?: boolean;
+};
+
+const FormLabelImplementation: ForwardRefRenderFunction<
+  HTMLLabelElement,
+  FormLabelProps
+> = (props, ref) => {
+  const { asChild, className, required, children, ...args } = props;
+
+  const Component = asChild ? Slot : 'label';
+
+  return (
+    <Component
+      {...args}
+      ref={ref}
+      className={twJoin(
+        'block cursor-pointer text-base font-semibold text-marine-high-emphasis data-[invalid]:text-error-100',
+        className,
+      )}
+    >
+      <Slottable>{children}</Slottable>
+      {required && (
+        <abbr
+          className="ml-1 text-error-100 no-underline"
+          title="Required field"
+        >
+          *
+        </abbr>
+      )}
+    </Component>
+  );
+};
+
+/**
+ * `FormLabel` is a component for rendering a label in forms.
+ *
+ * ## Props
+ *
+ * The `FormLabel` component accepts the following properties:
+ *
+ * - `children`: The content of the label.
+ * - `required`: If set, adds an asterisk (*) to denote that the associated field is required.
+ * - `className`: Additional classes for custom styling.
+ * - `as`: Optionally specifies the element type to render. Can be 'label', 'span', or 'Form.Label' from Radix UI.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * // Simple label
+ * <FormLabel>
+ *   Label
+ * </FormLabel>
+ *
+ * // Label for a required field
+ * <FormLabel required>
+ *   Label
+ * </FormLabel>
+ *
+ * // Label with custom styling
+ * <FormLabel required className="custom-class">
+ *   Label
+ * </FormLabel>
+ *
+ * // Using a different element type
+ * <FormLabel as="span">
+ *   Label
+ * </FormLabel>
+ *
+ * // Using Radix UI Form.Label
+ * <FormLabel as={Form.Label}>
+ *   Label
+ * </FormLabel>
+ * ```
+ */
+export const FormLabel = forwardRef(
+  FormLabelImplementation,
+) as typeof FormLabelImplementation;

package/src/components/core/FormLabel/index.ts

@@ -0,0 +1 @@
+export * from './FormLabel';

package/src/components/core/Icon/Icon.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+import { dynamicComponents as dynamicComponentsIcons } from '../../../../icons/icons';
+import type { ComponentType, SVGProps } from 'react';
+import { twJoin } from 'tailwind-merge';
+
+// Type for local icons
+type DynamicComponentIconName = keyof typeof dynamicComponentsIcons;
+
+// Union of both types to create a comprehensive IconName type
+export type IconName = DynamicComponentIconName;
+
+export type IconProps = {
+  /**
+   * Additional TailwindCSS utilities can be added with this prop.
+   */
+  className?: string;
+  /**
+   * The name of the icon.
+   */
+  name: IconName;
+
+  /**
+   * The size of the icon. Can be a number for a custom size or
+   * one of the predefined sizes: 'xs' (16x16), 'sm' (20x20),
+   * 'md' (24x24), 'lg' (32x32).
+   *
+   * @default 'md'
+   */
+  size?: number | 'xs' | 'sm' | 'md' | 'lg';
+};
+
+/**
+ *  Component to display an icon, based on the [local icon library](/docs/foundation-icons-pictograms--docs).
+ *
+ *  @component
+ *  @param {IconProps} props - The props for the Icon component.
+ *  @returns {JSX.Element | null} The rendered icon component or null if the icon is not found.
+ */
+const Icon = (props: IconProps) => {
+  const { className, name, size = 'md' } = props;
+
+  const IconComponent = getIconComponent(name);
+  if (!IconComponent) {
+    return null;
+  }
+
+  const iconSize = getIconSize(size);
+
+  return (
+    <IconComponent
+      className={twJoin('pointer-events-none', className)}
+      width={iconSize}
+      height={iconSize}
+    />
+  );
+};
+
+/**
+ * Helper function to get the icon size in pixels.
+ *
+ * @param {NonNullable<IconProps['size']>} size - The size prop, either a number or a predefined size string.
+ * @returns {number} The size in pixels.
+ */
+const getIconSize = (size: NonNullable<IconProps['size']>) => {
+  if (typeof size === 'number') {
+    return size;
+  }
+
+  switch (size) {
+    case 'xs':
+      return 16;
+    case 'sm':
+      return 20;
+    case 'lg':
+      return 32;
+    default:
+      return 24;
+  }
+};
+
+/**
+ * Helper function to get the appropriate icon component.
+ *
+ * @param {IconName} name - The name of the icon to retrieve.
+ * @returns {ComponentType<SVGProps<SVGSVGElement>> | null} The icon component or null if not found.
+ */
+const getIconComponent = (
+  name: IconName,
+): ComponentType<SVGProps<SVGSVGElement>> | null => {
+  // Check if the icon exists in dynamicComponentsIcons (case-sensitive)
+  if (dynamicComponentsIcons[name as DynamicComponentIconName]) {
+    return dynamicComponentsIcons[
+      name as DynamicComponentIconName
+    ] as ComponentType<SVGProps<SVGSVGElement>>;
+  }
+
+  // Icon not found
+  return dynamicComponentsIcons[
+    'fallback' as DynamicComponentIconName
+  ] as ComponentType<SVGProps<SVGSVGElement>>;
+};
+
+Icon.displayName = 'Icon';
+
+export { Icon };

package/src/components/core/Icon/index.ts

@@ -0,0 +1 @@
+export * from './Icon';