@hero-design/rn 8.132.1 → 8.133.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @hero-design/rn
 
+## 8.133.0
+
+### Minor Changes
+
+- [#5297](https://github.com/Thinkei/hero-design/pull/5297) [`bc5f4bb`](https://github.com/Thinkei/hero-design/commit/bc5f4bbaa7cba327b2d529a1960f5b6a3d0817dd) Thanks [@vinhphan-eh](https://github.com/vinhphan-eh)! - [AppCue] Add spotlight cut-out backdrop and controlled visibility (visible/onDismiss)
+
 ## 8.132.1
 
 ### Patch Changes

package/es/index.js

@@ -5,9 +5,9 @@ import React__default, { useState, useEffect, useMemo, useCallback, useRef, useL
 import MaskedView from '@react-native-masked-view/masked-view';
 import { LinearGradient } from 'expo-linear-gradient';
 import { createIconSet } from 'react-native-vector-icons';
+import Svg, { Defs, Mask, Rect, G, ForeignObject, Line as Line$1, Path as Path$1, Circle as Circle$1, ClipPath } from 'react-native-svg';
 import { useSafeAreaInsets, SafeAreaView } from 'react-native-safe-area-context';
 import { MonthYearPickerViewIOS, MonthYearPickerDialogueAndroid } from '@hero-design/react-native-month-year-picker';
-import Svg, { G, ForeignObject, Line as Line$1, Path as Path$1, Rect, Mask, Circle as Circle$1, Defs, ClipPath } from 'react-native-svg';
 import DateTimePicker from '@react-native-community/datetimepicker';
 import RnSlider from '@react-native-community/slider';
 import MultiSlider from '@ptomasroos/react-native-multi-slider';
@@ -7768,7 +7768,8 @@ var getAppCueTheme = function getAppCueTheme(theme) {
     arrowOffset: theme.space.smallMedium
   };
   var radii = {
-    container: theme.radii.large
+    container: theme.radii.large,
+    spotlight: theme.radii['5xlarge']
   };
   return {
     colors: colors,
@@ -9465,17 +9466,16 @@ var StyledContent$1 = index$c(View)(function (_ref) {
     alignSelf: 'center'
   };
 });
-var StyledContainer$a = index$c(View)(function (_ref2) {
-  var theme = _ref2.theme;
-  return {
-    width: '100%',
-    height: '100%',
-    backgroundColor: theme.__hd__.appCue.colors.backdropColor
-  };
+var StyledModalContainer = index$c(View)({
+  width: '100%',
+  height: '100%'
 });
-var StyledIconContainer$2 = index$c(Animated.View)(function (_ref3) {
-  var theme = _ref3.theme,
-    themePlacement = _ref3.themePlacement;
+var StyledContentPositioner = index$c(View)({
+  position: 'absolute'
+});
+var StyledIconContainer$2 = index$c(Animated.View)(function (_ref2) {
+  var theme = _ref2.theme,
+    themePlacement = _ref2.themePlacement;
   return _objectSpread2(_objectSpread2(_objectSpread2(_objectSpread2(_objectSpread2(_objectSpread2(_objectSpread2(_objectSpread2({
     position: 'absolute',
     color: theme.__hd__.appCue.colors.background,
@@ -9524,25 +9524,47 @@ var StyledIconContainer$2 = index$c(Animated.View)(function (_ref3) {
   });
 });
 
-/**
- * Calculates the position of an element based on its placement relative to a reference position.
- *
- * @param {Object} params - The parameters for calculating the position.
- * @param {Object} params.position - The position and size of target element.
- * @param {number} params.position.pageX - The X coordinate of the target position.
- * @param {number} params.position.pageY - The Y coordinate of the target position.
- * @param {number} params.position.width - The width of the reference element.
- * @param {number} params.position.height - The height of the reference element.
- * @param {Object} params.contentSize - The size of the App Cue content.
- * @param {number} params.contentSize.width - The width of the content.
- * @param {number} params.contentSize.height - The height of the content.
- * @param {Placement} params.placement - The placement of the content relative to the reference position ('top', 'bottom', 'right', 'left').
- * @param {number} params.offset - The offset distance to display an arrow.
- *
- * @returns {Object} The calculated position of the App Cue.
- * @returns {number} return.x - The X coordinate of the App Cue.
- * @returns {number} return.y - The Y coordinate of the App Cue.
- */
+var SpotlightBackdrop = function SpotlightBackdrop(_ref) {
+  var bounds = _ref.bounds,
+    testID = _ref.testID;
+  var theme = useTheme();
+  var _useWindowDimensions = useWindowDimensions(),
+    windowWidth = _useWindowDimensions.width,
+    windowHeight = _useWindowDimensions.height;
+  var maxSpotlightRadius = theme.__hd__.appCue.radii.spotlight;
+  var backdropColor = theme.__hd__.appCue.colors.backdropColor;
+  var resolvedRadius = Math.min(bounds.height / 2, bounds.width / 2, maxSpotlightRadius);
+  return /*#__PURE__*/React__default.createElement(Svg, {
+    width: windowWidth,
+    height: windowHeight,
+    style: {
+      position: 'absolute',
+      top: 0,
+      left: 0
+    }
+  }, /*#__PURE__*/React__default.createElement(Defs, null, /*#__PURE__*/React__default.createElement(Mask, {
+    id: "spotlight-mask"
+  }, /*#__PURE__*/React__default.createElement(Rect, {
+    width: windowWidth,
+    height: windowHeight,
+    fill: "white"
+  }), /*#__PURE__*/React__default.createElement(Rect, {
+    x: bounds.x,
+    y: bounds.y,
+    width: bounds.width,
+    height: bounds.height,
+    rx: resolvedRadius,
+    ry: resolvedRadius,
+    fill: "black",
+    testID: testID && "".concat(testID, "-spotlight")
+  }))), /*#__PURE__*/React__default.createElement(Rect, {
+    width: windowWidth,
+    height: windowHeight,
+    fill: backdropColor,
+    mask: "url(#spotlight-mask)"
+  }));
+};
+
 var calculatePosition = function calculatePosition(_ref) {
   var placement = _ref.placement,
     position = _ref.position,
@@ -9553,92 +9575,61 @@ var calculatePosition = function calculatePosition(_ref) {
     case 'top':
       {
         return {
-          // The X coordinate is calculated by adding the half of the width of the target element to the X coordinate of the target element.
-          left: position.pageX + (position.width - contentSize.width) / 2,
-          // The Y coordinate is calculated by subtracting the height of the content and the offset from the Y coordinate of the target element
-          top: position.pageY - contentSize.height - offset
+          left: position.x + (position.width - contentSize.width) / 2,
+          top: position.y - contentSize.height - offset
         };
       }
     case 'bottom':
       {
         return {
-          // The X coordinate is calculated by adding the half of the width of the target element to the X coordinate of the target element.
-          left: position.pageX + (position.width - contentSize.width) / 2,
-          // The Y coordinate is calculated by adding the height of the target element and the offset to the Y coordinate of the target element.
-          top: position.pageY + position.height + offset
+          left: position.x + (position.width - contentSize.width) / 2,
+          top: position.y + position.height + offset
         };
       }
     case 'right':
       {
         return {
-          // The X coordinate is calculated by adding the width of the target element and the offset to the X coordinate of the target element.
-          left: position.pageX + position.width + offset,
-          // The Y coordinate is calculated by adding half of the height of the target element to the Y coordinate of the target element.
-          top: position.pageY + (position.height - contentSize.height) / 2
+          left: position.x + position.width + offset,
+          top: position.y + (position.height - contentSize.height) / 2
         };
       }
     case 'left':
       {
         return {
-          // The X coordinate is calculated by subtracting the width of the content and the offset from the X coordinate of the target element.
-          left: position.pageX - contentSize.width - offset,
-          // The Y coordinate is calculated by adding half of the height of the target element to the Y coordinate of the target element.
-          top: position.pageY + (position.height - contentSize.height) / 2
+          left: position.x - contentSize.width - offset,
+          top: position.y + (position.height - contentSize.height) / 2
         };
       }
     case 'top-left':
       {
         return {
-          // The X coordinate is calculated by subtracting the width of the content from the X coordinate of the target element.
-          right: windowWidth - position.pageX - position.width,
-          // The Y coordinate is calculated by subtracting the height of the content and the offset from the Y coordinate of the target element
-          top: position.pageY - contentSize.height - offset
+          right: windowWidth - position.x - position.width,
+          top: position.y - contentSize.height - offset
         };
       }
     case 'top-right':
       {
         return {
-          // The X coordinate is calculated by adding the width of the target element to the X coordinate of the target element.
-          left: position.pageX,
-          // The Y coordinate is calculated by subtracting the height of the content and the offset from the Y coordinate of the target element.
-          top: position.pageY - contentSize.height - offset
+          left: position.x,
+          top: position.y - contentSize.height - offset
         };
       }
     case 'bottom-left':
       {
         return {
-          // The X coordinate is calculated by subtracting the width of the content from the X coordinate of the target element.
-          right: windowWidth - position.pageX - position.width,
-          // The Y coordinate is calculated by adding the height of the target element and the offset to the Y coordinate of the target element.
-          top: position.pageY + position.height + offset
+          right: windowWidth - position.x - position.width,
+          top: position.y + position.height + offset
         };
       }
     case 'bottom-right':
       {
         return {
-          // The X coordinate is calculated by adding the width of the target element to the X coordinate of the target element.
-          left: position.pageX,
-          // The Y coordinate is calculated by adding the height of the target element and the offset to the Y coordinate of the target element.
-          top: position.pageY + position.height + offset
+          left: position.x,
+          top: position.y + position.height + offset
         };
       }
   }
 };
-/**
- * Calculates the maximum width of the content based on its position, offset, placement, and window width.
- *
- * @param {Object} params - The parameters for the calculation.
- * @param {Object} params.position - The position and dimensions of the target element.
- * @param {number} params.position.pageX - The X coordinate of the target element.
- * @param {number} params.position.pageY - The Y coordinate of the target element.
- * @param {number} params.position.width - The width of the target element.
- * @param {number} params.position.height - The height of the target element.
- * @param {number} params.offset - The offset value to display an arrow.
- * @param {Placement} params.placement - The placement of the content relative to the element.
- * @param {number} params.windowWidth - The width of the window.
- *
- * @returns {number | undefined} The maximum width of the content.
- */
 var calulateContentMaxWidth = function calulateContentMaxWidth(_ref2) {
   var position = _ref2.position,
     offset = _ref2.offset,
@@ -9655,27 +9646,27 @@ var calulateContentMaxWidth = function calulateContentMaxWidth(_ref2) {
       }
     case 'right':
       {
-        return windowWidth - position.pageX - position.width - offset;
+        return windowWidth - position.x - position.width - offset;
       }
     case 'left':
       {
-        return position.pageX - offset;
+        return position.x - offset;
       }
     case 'top-left':
       {
-        return position.pageX + position.width;
+        return position.x + position.width;
       }
     case 'top-right':
       {
-        return windowWidth - position.pageX;
+        return windowWidth - position.x;
       }
     case 'bottom-left':
       {
-        return position.pageX + position.width;
+        return position.x + position.width;
       }
     case 'bottom-right':
       {
-        return windowWidth - position.pageX;
+        return windowWidth - position.x;
       }
   }
 };
@@ -9686,23 +9677,27 @@ var AppCue = function AppCue(_ref) {
     _ref$placement = _ref.placement,
     placement = _ref$placement === void 0 ? 'top' : _ref$placement,
     style = _ref.style,
-    testID = _ref.testID;
+    testID = _ref.testID,
+    controlledVisible = _ref.visible,
+    onDismiss = _ref.onDismiss;
   var targetContainerRef = useRef(null);
+  var isControlled = controlledVisible !== undefined;
   var _React$useState = React__default.useState(false),
     _React$useState2 = _slicedToArray(_React$useState, 2),
-    visible = _React$useState2[0],
-    setVisible = _React$useState2[1];
+    internalVisible = _React$useState2[0],
+    setInternalVisible = _React$useState2[1];
+  var open = isControlled ? controlledVisible : internalVisible;
   var theme = useTheme();
   var offset = theme.__hd__.appCue.space.offset;
   var _React$useState3 = React__default.useState({
-      pageX: 0,
-      pageY: 0,
+      x: 0,
+      y: 0,
       width: 0,
       height: 0
     }),
     _React$useState4 = _slicedToArray(_React$useState3, 2),
-    position = _React$useState4[0],
-    setPosition = _React$useState4[1];
+    bounds = _React$useState4[0],
+    setBounds = _React$useState4[1];
   var _React$useState5 = React__default.useState({
       width: 0,
       height: 0
@@ -9713,23 +9708,36 @@ var AppCue = function AppCue(_ref) {
   var doMeasure = useCallback(function (cb) {
     var _targetContainerRef$c;
     (_targetContainerRef$c = targetContainerRef.current) === null || _targetContainerRef$c === void 0 || _targetContainerRef$c.measure(function (_, __, width, height, pageX, pageY) {
-      setPosition({
-        pageX: pageX,
-        pageY: pageY,
+      setBounds({
+        x: pageX,
+        y: pageY,
         width: width,
         height: height
       });
       cb === null || cb === void 0 || cb();
     });
   }, []);
-  var handleOpen = function handleOpen() {
-    doMeasure(function () {
-      return setVisible(true);
-    });
-  };
+  var handleOpen = useCallback(function () {
+    if (!isControlled) {
+      doMeasure(function () {
+        return setInternalVisible(true);
+      });
+    }
+  }, [isControlled, doMeasure]);
+  var handleDismiss = useCallback(function () {
+    if (!isControlled) {
+      setInternalVisible(false);
+    }
+    onDismiss === null || onDismiss === void 0 || onDismiss();
+  }, [isControlled, onDismiss]);
   useLayoutEffect(function () {
     doMeasure();
   }, [doMeasure]);
+  useEffect(function () {
+    if (open) {
+      doMeasure();
+    }
+  }, [open, doMeasure]);
   var enhancedTarget = /*#__PURE__*/React__default.cloneElement(target, {
     onPress: function onPress() {
       var _target$props, _target$props$onPress;
@@ -9746,14 +9754,14 @@ var AppCue = function AppCue(_ref) {
   var _useWindowDimensions = useWindowDimensions(),
     windowWidth = _useWindowDimensions.width;
   var pos = calculatePosition({
-    position: position,
+    position: bounds,
     contentSize: contentSize,
     placement: placement,
     offset: offset,
     windowWidth: windowWidth
   });
   var maxWidth = calulateContentMaxWidth({
-    position: position,
+    position: bounds,
     offset: offset,
     placement: placement,
     windowWidth: windowWidth
@@ -9776,26 +9784,24 @@ var AppCue = function AppCue(_ref) {
     }
   }, enhancedTarget)), /*#__PURE__*/React__default.createElement(Modal$1, {
     animationType: "fade",
-    visible: visible,
-    onDismiss: function onDismiss() {
-      return setVisible(false);
-    },
+    visible: open,
+    onDismiss: handleDismiss,
     transparent: true,
     presentationStyle: "overFullScreen",
     statusBarTranslucent: true
   }, /*#__PURE__*/React__default.createElement(TouchableWithoutFeedback, {
     testID: testID && "".concat(testID, "-backdrop"),
-    onPress: function onPress() {
-      return setVisible(false);
-    }
-  }, /*#__PURE__*/React__default.createElement(StyledContainer$a, null, /*#__PURE__*/React__default.createElement(View, {
-    style: StyleSheet$1.flatten([{
-      position: 'absolute',
+    onPress: handleDismiss
+  }, /*#__PURE__*/React__default.createElement(StyledModalContainer, null, /*#__PURE__*/React__default.createElement(SpotlightBackdrop, {
+    bounds: bounds,
+    testID: testID
+  }), /*#__PURE__*/React__default.createElement(StyledContentPositioner, {
+    style: [{
       top: pos.top,
       left: pos.left,
       bottom: pos.bottom,
       right: pos.right
-    }, style]),
+    }, style],
     onLayout: measureContent,
     testID: testID
   }, /*#__PURE__*/React__default.createElement(StyledContent$1, {