@pagopa/io-app-design-system 3.0.0 → 3.1.0

package/src/components/layout/HeaderSecondLevel.tsx

@@ -178,22 +178,19 @@ export const HeaderSecondLevel = ({
   /* Visual attributes when there are transitions between states */
   const HEADER_DEFAULT_BG_COLOR: IOColors = theme["appBackground-primary"];
 
-  const headerBgColorTransparentState = backgroundColor
-    ? hexToRgba(backgroundColor, 0)
-    : transparent
-    ? hexToRgba(IOColors[HEADER_DEFAULT_BG_COLOR], 0)
-    : IOColors[HEADER_DEFAULT_BG_COLOR];
-
   const headerBgColorSolidState =
     backgroundColor ?? IOColors[HEADER_DEFAULT_BG_COLOR];
 
+  const headerBgColorTransparentState = transparent
+    ? hexToRgba(headerBgColorSolidState, 0)
+    : headerBgColorSolidState;
+
   const borderColorDefault = IOColors[theme["divider-default"]];
 
-  const borderColorTransparentState = backgroundColor
-    ? hexToRgba(backgroundColor, 0)
-    : hexToRgba(borderColorDefault, 0);
   const borderColorSolidState = backgroundColor ?? borderColorDefault;
 
+  const borderColorTransparentState = hexToRgba(borderColorSolidState, 0);
+
   useLayoutEffect(() => {
     if (isTitleAccessible) {
       const reactNode = findNodeHandle(titleRef.current);

package/src/components/tooltip/Arrows.tsx

@@ -0,0 +1,36 @@
+import Svg, { Path } from 'react-native-svg';
+import React from 'react';
+import { IOColors } from '../../core';
+
+export const LeftArrow = ({ color = IOColors.white }: { color?: string }) => (
+  <Svg fill="none" >
+    <Path
+      d="M12.6955 15.2C14.8289 13.6 14.8289 10.4 12.6955 8.8L0.962204 0V24L12.6955 15.2Z"
+      fill={color}
+    />
+  </Svg>
+);
+export const RightArrow = ({ color = IOColors.white }: { color?: string }) => (
+  <Svg fill={color}>
+    <Path
+      d="M2.30448 15.2031C0.171145 13.6031 0.171145 10.4031 2.30448 8.80314L14.0378 0.00314331V24.0031L2.30448 15.2031Z"
+      fill={color}
+    />
+  </Svg>
+);
+export const BottomArrow = ({ color = IOColors.white }: { color?: string }) => (
+  <Svg fill={color}>
+    <Path
+      d="M15.2 2.26667C13.6 0.133334 10.4 0.133333 8.8 2.26667L0 14L24 14L15.2 2.26667Z"
+      fill={color}
+    />
+  </Svg>
+);
+export const TopArrow = ({ color = IOColors.white }: { color?: string }) => (
+  <Svg fill={color}>
+    <Path
+      d="M15.2 11.7333C13.6 13.8667 10.4 13.8667 8.8 11.7333L0 0L24 0L15.2 11.7333Z"
+      fill={color}
+    />
+  </Svg>
+);

package/src/components/tooltip/Tooltip.tsx

@@ -0,0 +1,313 @@
+import React, {
+  useState,
+  useRef,
+  PropsWithChildren,
+  useEffect,
+  useCallback,
+  JSXElementConstructor,
+  useMemo,
+  ReactElement
+} from "react";
+import {
+  View,
+  Modal,
+  Dimensions,
+  LayoutChangeEvent,
+  TouchableWithoutFeedback
+} from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { every, some } from "lodash";
+import { IOColors } from "../../core";
+import { Body, H6 } from "../typography";
+import { IconButton } from "../buttons";
+import { BottomArrow, LeftArrow, RightArrow, TopArrow } from "./Arrows";
+import {
+  ARROW_HEIGHT,
+  EMPTY_SPACE,
+  getArrowBoxByPlacement,
+  getArrowCoords,
+  getArrowVerticalAlignment,
+  getDisplayInsets,
+  getTooltipCoords,
+  getTooltipVerticalAlignment,
+  isDefined,
+  isNotZero
+} from "./utils";
+import { getChildrenPosition, tooltipStyles } from "./styles";
+import {
+  ChildrenCoords,
+  DisplayInsets,
+  Placement,
+  TooltipLayout
+} from "./utils/types";
+
+const screenDimensions = Dimensions.get("window");
+const INITIAL_COORDS: ChildrenCoords = {
+  x: 0,
+  y: 0,
+  width: 0,
+  height: 0
+};
+const ARROWS_BY_PLACEMENT: Record<
+  Placement,
+  JSXElementConstructor<{ color: string }>
+> = {
+  top: TopArrow,
+  bottom: BottomArrow,
+  left: LeftArrow,
+  right: RightArrow
+};
+
+type CommonProps = {
+  /**
+   * The title text displayed at the top of the tooltip.
+   */
+  title: string;
+  /**
+   * The tooltip text content.
+   */
+  content: string;
+  /**
+   * Controls the visibility of the tooltip.
+   */
+  isVisible: boolean;
+  /**
+   * Initial tooltip position; can be 'top', 'bottom', 'left', or 'right'.
+   * @default top
+   */
+  placement?: Placement;
+  /**
+   * Insets for adjusting tooltip position within screen boundaries.
+   * @default {}
+   */
+  displayInsets?: Partial<DisplayInsets>;
+  /**
+   * Accessibility label for the close icon button.
+   */
+  closeIconAccessibilityLabel: string;
+  /**
+   * Determines whether interactions with the tooltip's children are allowed when `isVisible` is set to true.
+   * @default false
+   */
+  childrenInteractionsEnabled?: boolean;
+  /**
+   *  Callback function triggered when the tooltip is closed.
+   */
+  onClose: () => void;
+};
+type CloseWithTapOnBackground = {
+  /**
+   * Allows closing the tooltip by tapping outside of it.
+   */
+  allowCloseOnBackgroundTap: true;
+  /**
+   * Accessibility label for the tooltip background mask.
+   */
+  backgroundAccessibilityLabel: string;
+};
+type CloseWithBackgroundTapDisabled = {
+  allowCloseOnBackgroundTap?: false;
+};
+type Props = CommonProps & (CloseWithTapOnBackground | CloseWithBackgroundTapDisabled);
+
+/**
+ * Tooltip component that displays a contextual tooltip around its children.
+ * The tooltip position is controlled by the `placement` prop and can adjust
+ * dynamically if there is insufficient space.
+ * @param {Props} props - The component props
+ *
+ * @returns {ReactElement} A tooltip component rendered around the specified children.
+ */
+export const Tooltip = ({
+  children,
+  title,
+  content,
+  placement: initialPlacement = "top",
+  closeIconAccessibilityLabel,
+  isVisible,
+  displayInsets = {},
+  allowCloseOnBackgroundTap,
+  childrenInteractionsEnabled = false,
+  onClose
+}: PropsWithChildren<Props>): ReactElement => {
+  const insets = useSafeAreaInsets();
+  const [currentPlacement, setCurrentPlacement] =
+    useState<Placement>(initialPlacement);
+  const [childrenCoords, setChildrenCoords] = useState<ChildrenCoords>(INITIAL_COORDS);
+  const [tooltipLayout, setTooltipLayout] = useState<TooltipLayout>();
+  const childRef = useRef<View>(null);
+  const titleRef = useRef<View>(null);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout>>();
+
+  const Arrow = useMemo(
+    () => ARROWS_BY_PLACEMENT[currentPlacement],
+    [currentPlacement]
+  );
+  const isChildrenMeasurementFinished =
+    every(childrenCoords, isDefined)
+    && some(childrenCoords, isNotZero);
+  const isTooltipMeasurementCompleted = isDefined(tooltipLayout);
+  const tooltipVisibility = { opacity: isTooltipMeasurementCompleted ? 1 : 0 };
+
+  /**
+   * This function sets the `Tooltip` children coordinates
+   */
+  const measureChildrenCoords = useCallback(() => {
+    if (childRef.current && typeof childRef.current.measure === "function") {
+      childRef.current.measure((_, __, width, height, px, py) => {
+        const coords = {
+          x: px,
+          y: py,
+          width,
+          height
+        };
+        if (every(coords, isDefined)) {
+          setChildrenCoords(coords);
+        }
+      });
+    }
+  }, []);
+
+  useEffect(() => {
+    if (isVisible) {
+      // A new measure is executed every time the `Tooltip` is visible
+      // This is required for use within ScrollView components.
+      // eslint-disable-next-line functional/immutable-data
+      timeoutRef.current = setTimeout(measureChildrenCoords, 100);
+    } else {
+      setChildrenCoords(INITIAL_COORDS);
+      setCurrentPlacement(initialPlacement);
+    }
+
+    return () => {
+      if (isVisible) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, [isVisible, initialPlacement, measureChildrenCoords]);
+
+  /**
+   * This function works with `top` and `bottom` placement and sets the current placement to their opposite value
+   * if in the selected one there is no space to prompt the tooltip
+   */
+  const invertPlacementIfNeeded = useCallback(
+    (nativeEvent: LayoutChangeEvent["nativeEvent"]) => {
+      if (initialPlacement === "top") {
+        const hasSpace = nativeEvent.layout.y >= insets.top;
+
+        if (!hasSpace) {
+          setCurrentPlacement("bottom");
+        }
+      }
+      if (initialPlacement === "bottom") {
+        const remainingSpace =
+          screenDimensions.height - nativeEvent.layout.y - insets.bottom;
+        const tooltipMinHeight =
+          nativeEvent.layout.height + ARROW_HEIGHT + EMPTY_SPACE;
+        const hasSpace = remainingSpace >= tooltipMinHeight;
+
+        if (!hasSpace) {
+          setCurrentPlacement("top");
+        }
+      }
+    },
+    [insets.bottom, insets.top, initialPlacement]
+  );
+
+  const handleTooltipOnLayout = useCallback(
+    ({ nativeEvent }: LayoutChangeEvent) => {
+      invertPlacementIfNeeded(nativeEvent);
+      setTooltipLayout(nativeEvent.layout);
+    },
+    [invertPlacementIfNeeded]
+  );
+
+  const handleTapOnBackground = useCallback(() => {
+    if (allowCloseOnBackgroundTap) {
+      onClose();
+    }
+  }, [allowCloseOnBackgroundTap, onClose]);
+
+  return (
+    <>
+      <View
+        // This prop is necessary for .measure to work correctly, as explained here: https://github.com/facebook/react-native/issues/29712
+        collapsable={false}
+        ref={childRef}
+      >
+        {children}
+      </View>
+      <Modal transparent visible={isVisible && isChildrenMeasurementFinished}>
+        <View
+          accessibilityElementsHidden={!childrenInteractionsEnabled}
+          importantForAccessibility={childrenInteractionsEnabled ? 'auto' : 'no-hide-descendants'}
+          pointerEvents={childrenInteractionsEnabled ? "auto" : "box-only"}
+          style={[
+            tooltipStyles.childrenContainer,
+            getChildrenPosition(childrenCoords)
+          ]}
+        >
+          {children}
+        </View>
+        <TouchableWithoutFeedback
+          accessible={allowCloseOnBackgroundTap}
+          accessibilityRole={allowCloseOnBackgroundTap ? "button" : "none"}
+          importantForAccessibility={allowCloseOnBackgroundTap ? 'yes' : 'no'}
+          accessibilityElementsHidden={!allowCloseOnBackgroundTap}
+          onPress={handleTapOnBackground}
+        >
+          <View
+            style={[
+              tooltipStyles.overlay,
+              { height: screenDimensions.height }
+            ]}
+          />
+        </TouchableWithoutFeedback>
+        <View
+          onLayout={handleTooltipOnLayout}
+          style={[
+            tooltipStyles.tooltipContainer,
+            getTooltipCoords(
+              currentPlacement,
+              childrenCoords,
+              getDisplayInsets(displayInsets),
+              screenDimensions
+            ),
+            getTooltipVerticalAlignment(
+              currentPlacement,
+              childrenCoords.height,
+              tooltipLayout?.height
+            ),
+            tooltipVisibility
+          ]}
+        >
+          <H6 ref={titleRef}>{title}</H6>
+          <View style={tooltipStyles.closeIcon}>
+            <IconButton
+              color="neutral"
+              icon="closeSmall"
+              accessibilityLabel={closeIconAccessibilityLabel}
+              onPress={onClose}
+            />
+          </View>
+          <Body>{content}</Body>
+        </View>
+        <View
+          style={[
+            tooltipStyles.arrowContainer,
+            getArrowBoxByPlacement(currentPlacement),
+            getArrowCoords(
+              currentPlacement,
+              childrenCoords,
+              screenDimensions
+            ),
+            getArrowVerticalAlignment(currentPlacement, childrenCoords.height),
+            tooltipVisibility
+          ]}
+        >
+          <Arrow color={IOColors.white} />
+        </View>
+      </Modal>
+    </>
+  );
+};

package/src/components/tooltip/index.ts

@@ -0,0 +1 @@
+export * from "./Tooltip";

package/src/components/tooltip/styles.ts

@@ -0,0 +1,44 @@
+import { StyleSheet } from 'react-native';
+import { IOColors } from '../../core';
+import { ChildrenCoords } from './utils/types';
+
+export const tooltipStyles = StyleSheet.create({
+  overlay: {
+    position: "absolute",
+    width: "100%",
+    height: "100%",
+    backgroundColor: IOColors["grey-850"],
+    opacity: 0.6,
+    zIndex: 997
+  },
+  childrenContainer: {
+    position: "absolute",
+    zIndex: 1000
+  },
+  tooltipContainer: {
+    position: "absolute",
+    paddingHorizontal: 16,
+    paddingVertical: 16,
+    backgroundColor: IOColors.white,
+    borderRadius: 8,
+    zIndex: 2000,
+    overflow: "visible"
+  },
+  arrowContainer: {
+    position: "absolute",
+    display: 'flex',
+    zIndex: 3000
+  },
+  closeIcon: {
+    position: 'absolute',
+    right: 8,
+    top: 9 // It's been used `9` instead of `8` to fix accessibility focus order. In this way title is read before close icon.
+  }
+});
+
+export const getChildrenPosition = (childrenCoords: ChildrenCoords) => ({
+  top: childrenCoords.y,
+  left: childrenCoords.x,
+  width: childrenCoords.width,
+  height: childrenCoords.height
+});

package/src/components/tooltip/utils/index.ts

@@ -0,0 +1,179 @@
+import { ScaledSize } from 'react-native';
+import { IOVisualCostants } from '../../../core';
+import { ChildrenCoords, DisplayInsets, Placement } from './types';
+
+export const ARROW_WIDTH = 24;
+export const ARROW_HEIGHT = 14;
+export const EMPTY_SPACE = 8;
+const DEFAULT_INSETS: DisplayInsets = {
+  top: 0,
+  bottom: 0,
+  left: IOVisualCostants.appMarginDefault,
+  right: IOVisualCostants.appMarginDefault,
+};
+
+/**
+ * @param displayInsets custom display insets
+ * @returns An `object` based on `DEFAULT_INSETS` and `displayInsets`
+ */
+export const getDisplayInsets = (
+  displayInsets: Partial<DisplayInsets>
+): DisplayInsets => ({ ...DEFAULT_INSETS, ...displayInsets });
+
+/**
+ * 
+ * @param placement The `Tooltip` placement
+ * @returns The `Arrow` box `width` and `height` based on `placement` value
+ */
+export const getArrowBoxByPlacement = (placement: Placement) => {
+  switch (placement) {
+    case 'left':
+    case 'right':
+      return {
+        width: ARROW_HEIGHT,
+        height: ARROW_WIDTH,
+      };
+    default:
+      return {
+        height: ARROW_HEIGHT,
+        width: ARROW_WIDTH,
+      };
+  }
+};
+
+/**
+ * A utility function to calculate the `Tooltip` coordinates and dimensions
+ * @param placement The `Tooltip` placement in relation of its children
+ * @param childrenCoords The measures in screen of the `Tooltip` children
+ * @param displayInsets The active display insets
+ * @param screenDimensions The dimensions of the device screen
+ * @returns The `Tooltip` coordinates
+ */
+export const getTooltipCoords = (
+  placement: Placement,
+  childrenCoords: ChildrenCoords,
+  displayInsets: DisplayInsets,
+  screenDimensions: ScaledSize
+) => {
+  const { width: screenWidth, height: screenHeight } = screenDimensions;
+
+  switch (placement) {
+    case "top":
+      return {
+        bottom: screenHeight - childrenCoords.y + ARROW_HEIGHT + EMPTY_SPACE,
+        left: displayInsets.left,
+        width: screenWidth - displayInsets.left - displayInsets.right
+      };
+    case "bottom":
+      return {
+        top: childrenCoords.y + childrenCoords.height + ARROW_HEIGHT + EMPTY_SPACE,
+        left: displayInsets.left,
+        width: screenWidth - displayInsets.left - displayInsets.right
+      };
+    case "left":
+      return {
+        top: childrenCoords.y,
+        left: displayInsets.left,
+        width:
+          screenWidth - (screenWidth - childrenCoords.x) - ARROW_HEIGHT - displayInsets.left - EMPTY_SPACE
+      };
+    case "right":
+      const elementSize = childrenCoords.width + childrenCoords.x + ARROW_HEIGHT + EMPTY_SPACE;
+
+      return {
+        top: childrenCoords.y,
+        left: elementSize,
+        width:
+          screenWidth -
+          (elementSize + displayInsets.right)
+      };
+    // TODO: provide a default center position in case of Tooltip without children
+    default:
+      return {};
+  }
+};
+
+/**
+ * A utility function to calculate the `Tooltip`'s `Arrow` coordinates
+ * @param placement The `Arrow` placement in relation of the `Tooltip` children
+ * @param childrenCoords The measures in screen of the `Tooltip` children
+ * @param screenDimensions The active display insets
+ * @returns The `Tooltip`'s Arrow coordinates
+ */
+export const getArrowCoords = (
+  placement: Placement,
+  childrenCoords: ChildrenCoords,
+  screenDimensions: ScaledSize
+) => {
+  const { width: screenWidth, height: screenHeight } = screenDimensions;
+
+  switch (placement) {
+    case "top":
+      return {
+        bottom: screenHeight - childrenCoords.y + EMPTY_SPACE,
+        left: childrenCoords.x + childrenCoords.width / 2 - ARROW_WIDTH / 2
+      };
+    case "bottom":
+      return {
+        top: childrenCoords.y + childrenCoords.height + EMPTY_SPACE,
+        left: childrenCoords.x + childrenCoords.width / 2 - ARROW_WIDTH / 2
+      };
+    case "left":
+      return {
+        top: childrenCoords.y,
+        left: screenWidth - (screenWidth - childrenCoords.x) - ARROW_HEIGHT - EMPTY_SPACE - 1, // FIXME -> This `-1` is necessary because of the Svg size doesn't match the box size
+      };
+    case "right":
+      return {
+        top: childrenCoords.y,
+        left: childrenCoords.width + childrenCoords.x + EMPTY_SPACE
+      };
+    default:
+      // TODO: provide a default center position in case of Tooltip without children
+      return {};
+  }
+};
+
+/**
+ * A utility function to calculate the `Tooltip` vertical alignment
+ * @param placement The `Tooltip` placement in relation of its children
+ * @param childrenHeight The `Tooltip`'s children height
+ * @param tooltipHeight The `Tooltip`'s height
+ * @returns If placement is `left` or `right` it returns the vertical tranlsation to align the `Tooltip` center with its `children` center, 
+ * otherwise `null` is returned
+ */
+export const getTooltipVerticalAlignment = (placement: Placement, childrenHeight: number, tooltipHeight?: number) => {
+  if ((placement === "left" || placement === "right") && tooltipHeight) {
+    return {
+      transform: [
+        {
+          translateY:
+            -tooltipHeight / 2 + childrenHeight / 2
+        }
+      ]
+    };
+  }
+  return null;
+};
+
+/**
+ * A utility function to calculate the `Arrow` vertical alignment
+ * @param placement The `Tooltip` placement in relation of its children
+ * @param childrenHeight The `Tooltip`'s children height
+*/
+export const getArrowVerticalAlignment = (placement: Placement, childrenHeight: number) => {
+  if (placement === "left" || placement === "right") {
+    return {
+      transform: [
+        {
+          translateY:
+            -ARROW_WIDTH / 2 + childrenHeight / 2
+        }
+      ]
+    };
+  }
+  return null;
+};
+
+export const isDefined = <T>(v: T) => v !== undefined;
+export const isNotZero = (v: number) => v !== 0;

package/src/components/tooltip/utils/types.ts

@@ -0,0 +1,9 @@
+export type DisplayInsets = Record<Placement, number>;
+export type Placement = "top" | "bottom" | "left" | "right";
+export type ChildrenCoords = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+export type TooltipLayout = ChildrenCoords;