@pagopa/io-app-design-system 3.0.1 → 4.0.0

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;

package/src/components/typography/Body.tsx

@@ -10,7 +10,7 @@ import {
 } from "./IOText";
 
 type BodyStyleProps = TypographicStyleProps & {
-  weight?: Extract<IOFontWeight, "Regular" | "Semibold" | "Bold">;
+  weight?: Extract<IOFontWeight, "Regular" | "Semibold">;
 } & TypographicStyleAsLinkProps;
 
 export const bodyFontSize = 16;

package/src/components/typography/{LabelSmall.tsx → BodySmall.tsx}

@@ -9,20 +9,17 @@ import {
   TypographicStyleProps
 } from "./IOText";
 
-type LabelSmallProps = TypographicStyleProps & {
-  weight?: Extract<IOFontWeight, "Regular" | "Semibold" | "Bold">;
+type BodySmallProps = TypographicStyleProps & {
+  weight?: Extract<IOFontWeight, "Regular" | "Semibold">;
 } & TypographicStyleAsLinkProps;
 
 const fontName: IOFontFamily = "Titillio";
-const fontWeight: IOFontWeight = "Semibold";
-
 const legacyFontName: IOFontFamily = "TitilliumSansPro";
-const legacyFontWeight: IOFontWeight = "Semibold";
 
 /**
- * `LabelSmall` typographic style
+ * `BodySmall` typographic style
  */
-export const LabelSmall = forwardRef<View, LabelSmallProps>(
+export const BodySmall = forwardRef<View, BodySmallProps>(
   (
     { weight: customWeight, color: customColor, asLink, ...props },
     ref?: ForwardedRef<View>
@@ -34,15 +31,11 @@ export const LabelSmall = forwardRef<View, LabelSmallProps>(
       ? theme["interactiveElem-default"]
       : theme["textBody-tertiary"];
 
-    const LabelSmallProps: IOTextProps = {
+    const BodySmallProps: IOTextProps = {
       ...props,
       dynamicTypeRamp: "footnote" /* iOS only */,
       font: isExperimental ? fontName : legacyFontName,
-      weight: customWeight
-        ? customWeight
-        : isExperimental
-        ? fontWeight
-        : legacyFontWeight,
+      weight: customWeight ?? "Regular",
       size: 14,
       lineHeight: 21,
       color: customColor ?? defaultColor,
@@ -55,7 +48,7 @@ export const LabelSmall = forwardRef<View, LabelSmallProps>(
     };
 
     return (
-      <IOText ref={ref} {...LabelSmallProps}>
+      <IOText ref={ref} {...BodySmallProps}>
         {props.children}
       </IOText>
     );

package/src/components/typography/ButtonText.tsx

@@ -2,7 +2,7 @@ import React, { ForwardedRef, forwardRef } from "react";
 import { View } from "react-native";
 import { useIOExperimentalDesign } from "../../core";
 import { IOColors } from "../../core/IOColors";
-import { IOFontFamily, IOFontSize, IOFontWeight } from "../../utils/fonts";
+import { IOFontFamily, IOFontSize } from "../../utils/fonts";
 import { IOText, IOTextProps, TypographicStyleProps } from "./IOText";
 
 export const buttonTextFontSize: IOFontSize = 16;
@@ -10,11 +10,9 @@ export const buttonTextFontSize: IOFontSize = 16;
 `AnimatedText` for color transition through Reanimated */
 const defaultColor: IOColors = "white";
 const fontName: IOFontFamily = "Titillio";
-const fontWeight: IOFontWeight = "Semibold";
 
 // TODO: Remove this when legacy look is deprecated https://pagopa.atlassian.net/browse/IOPLT-153
 const legacyFontName: IOFontFamily = "TitilliumSansPro";
-const legacyFontWeight: IOFontWeight = "Bold";
 
 /**
  * `ButtonText` typographic style
@@ -26,7 +24,7 @@ export const ButtonText = forwardRef<View, TypographicStyleProps>(
     const ButtonTextProps: IOTextProps = {
       ...props,
       font: isExperimental ? fontName : legacyFontName,
-      weight: isExperimental ? fontWeight : legacyFontWeight,
+      weight: "Semibold",
       size: buttonTextFontSize,
       lineHeight: 20,
       color: customColor ?? defaultColor

package/src/components/typography/H3.tsx

@@ -1,26 +1,29 @@
 import React, { ForwardedRef, forwardRef } from "react";
 import { View } from "react-native";
-import { IOTheme, useIOExperimentalDesign, useIOTheme } from "../../core";
+import { useIOExperimentalDesign, useIOTheme } from "../../core";
 import { IOFontFamily, IOFontSize, IOFontWeight } from "../../utils/fonts";
 import { IOText, IOTextProps, TypographicStyleProps } from "./IOText";
 
-const defaultColor: keyof IOTheme = "textHeading-default";
+type H3StyleProps = TypographicStyleProps & {
+  weight?: Extract<IOFontWeight, "Semibold" | "Bold">;
+};
 
 /* Common typographic styles */
 export const h3FontSize: IOFontSize = 22;
 export const h3LineHeight = 33;
 const fontName: IOFontFamily = "Titillio";
-const fontWeight: IOFontWeight = "Semibold";
 
 // TODO: Remove this when legacy look is deprecated https://pagopa.atlassian.net/browse/IOPLT-153
 const legacyFontName: IOFontFamily = "TitilliumSansPro";
-const legacyFontWeight: IOFontWeight = "Semibold";
 
 /**
  * `H3` typographic style
  */
-export const H3 = forwardRef<View, TypographicStyleProps>(
-  ({ color: customColor, ...props }, ref?: ForwardedRef<View>) => {
+export const H3 = forwardRef<View, H3StyleProps>(
+  (
+    { weight: customWeight, color: customColor, ...props },
+    ref?: ForwardedRef<View>
+  ) => {
     const theme = useIOTheme();
     const { isExperimental } = useIOExperimentalDesign();
 
@@ -28,10 +31,10 @@ export const H3 = forwardRef<View, TypographicStyleProps>(
       ...props,
       dynamicTypeRamp: "title2", // iOS only
       font: isExperimental ? fontName : legacyFontName,
-      weight: isExperimental ? fontWeight : legacyFontWeight,
+      weight: customWeight ?? "Semibold",
       size: h3FontSize,
       lineHeight: h3LineHeight,
-      color: customColor ?? theme[defaultColor]
+      color: customColor ?? theme["textHeading-default"]
     };
 
     return (