@hero-design/rn 8.132.0 → 8.133.0

package/lib/index.js

@@ -5,9 +5,9 @@ var React = require('react');
 var MaskedView = require('@react-native-masked-view/masked-view');
 var expoLinearGradient = require('expo-linear-gradient');
 var reactNativeVectorIcons = require('react-native-vector-icons');
+var Svg = require('react-native-svg');
 var reactNativeSafeAreaContext = require('react-native-safe-area-context');
 var reactNativeMonthYearPicker = require('@hero-design/react-native-month-year-picker');
-var Svg = require('react-native-svg');
 var DateTimePicker = require('@react-native-community/datetimepicker');
 var RnSlider = require('@react-native-community/slider');
 var MultiSlider = require('@ptomasroos/react-native-multi-slider');
@@ -7797,7 +7797,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,
@@ -9494,17 +9495,16 @@ var StyledContent$1 = index$c(reactNative.View)(function (_ref) {
     alignSelf: 'center'
   };
 });
-var StyledContainer$a = index$c(reactNative.View)(function (_ref2) {
-  var theme = _ref2.theme;
-  return {
-    width: '100%',
-    height: '100%',
-    backgroundColor: theme.__hd__.appCue.colors.backdropColor
-  };
+var StyledModalContainer = index$c(reactNative.View)({
+  width: '100%',
+  height: '100%'
 });
-var StyledIconContainer$2 = index$c(reactNative.Animated.View)(function (_ref3) {
-  var theme = _ref3.theme,
-    themePlacement = _ref3.themePlacement;
+var StyledContentPositioner = index$c(reactNative.View)({
+  position: 'absolute'
+});
+var StyledIconContainer$2 = index$c(reactNative.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,
@@ -9553,25 +9553,47 @@ var StyledIconContainer$2 = index$c(reactNative.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 = reactNative.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__namespace.default.createElement(Svg__default.default, {
+    width: windowWidth,
+    height: windowHeight,
+    style: {
+      position: 'absolute',
+      top: 0,
+      left: 0
+    }
+  }, /*#__PURE__*/React__namespace.default.createElement(Svg.Defs, null, /*#__PURE__*/React__namespace.default.createElement(Svg.Mask, {
+    id: "spotlight-mask"
+  }, /*#__PURE__*/React__namespace.default.createElement(Svg.Rect, {
+    width: windowWidth,
+    height: windowHeight,
+    fill: "white"
+  }), /*#__PURE__*/React__namespace.default.createElement(Svg.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__namespace.default.createElement(Svg.Rect, {
+    width: windowWidth,
+    height: windowHeight,
+    fill: backdropColor,
+    mask: "url(#spotlight-mask)"
+  }));
+};
+
 var calculatePosition = function calculatePosition(_ref) {
   var placement = _ref.placement,
     position = _ref.position,
@@ -9582,92 +9604,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,
@@ -9684,27 +9675,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;
       }
   }
 };
@@ -9715,23 +9706,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 = React.useRef(null);
+  var isControlled = controlledVisible !== undefined;
   var _React$useState = React__namespace.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__namespace.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__namespace.default.useState({
       width: 0,
       height: 0
@@ -9742,23 +9737,36 @@ var AppCue = function AppCue(_ref) {
   var doMeasure = React.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 = React.useCallback(function () {
+    if (!isControlled) {
+      doMeasure(function () {
+        return setInternalVisible(true);
+      });
+    }
+  }, [isControlled, doMeasure]);
+  var handleDismiss = React.useCallback(function () {
+    if (!isControlled) {
+      setInternalVisible(false);
+    }
+    onDismiss === null || onDismiss === void 0 || onDismiss();
+  }, [isControlled, onDismiss]);
   React.useLayoutEffect(function () {
     doMeasure();
   }, [doMeasure]);
+  React.useEffect(function () {
+    if (open) {
+      doMeasure();
+    }
+  }, [open, doMeasure]);
   var enhancedTarget = /*#__PURE__*/React__namespace.default.cloneElement(target, {
     onPress: function onPress() {
       var _target$props, _target$props$onPress;
@@ -9775,14 +9783,14 @@ var AppCue = function AppCue(_ref) {
   var _useWindowDimensions = reactNative.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
@@ -9805,26 +9813,24 @@ var AppCue = function AppCue(_ref) {
     }
   }, enhancedTarget)), /*#__PURE__*/React__namespace.default.createElement(reactNative.Modal, {
     animationType: "fade",
-    visible: visible,
-    onDismiss: function onDismiss() {
-      return setVisible(false);
-    },
+    visible: open,
+    onDismiss: handleDismiss,
     transparent: true,
     presentationStyle: "overFullScreen",
     statusBarTranslucent: true
   }, /*#__PURE__*/React__namespace.default.createElement(reactNative.TouchableWithoutFeedback, {
     testID: testID && "".concat(testID, "-backdrop"),
-    onPress: function onPress() {
-      return setVisible(false);
-    }
-  }, /*#__PURE__*/React__namespace.default.createElement(StyledContainer$a, null, /*#__PURE__*/React__namespace.default.createElement(reactNative.View, {
-    style: reactNative.StyleSheet.flatten([{
-      position: 'absolute',
+    onPress: handleDismiss
+  }, /*#__PURE__*/React__namespace.default.createElement(StyledModalContainer, null, /*#__PURE__*/React__namespace.default.createElement(SpotlightBackdrop, {
+    bounds: bounds,
+    testID: testID
+  }), /*#__PURE__*/React__namespace.default.createElement(StyledContentPositioner, {
+    style: [{
       top: pos.top,
       left: pos.left,
       bottom: pos.bottom,
       right: pos.right
-    }, style]),
+    }, style],
     onLayout: measureContent,
     testID: testID
   }, /*#__PURE__*/React__namespace.default.createElement(StyledContent$1, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hero-design/rn",
-  "version": "8.132.0",
+  "version": "8.133.0",
   "license": "MIT",
   "main": "lib/index.js",
   "module": "es/index.js",

package/src/components/AppCue/SpotlightBackdrop.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import { useWindowDimensions } from 'react-native';
+import Svg, { Defs, Mask, Rect } from 'react-native-svg';
+import { useTheme } from '../../theme';
+
+interface SpotlightBackdropProps {
+  bounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  testID?: string;
+}
+
+const SpotlightBackdrop = ({ bounds, testID }: SpotlightBackdropProps) => {
+  const theme = useTheme();
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
+
+  const { spotlight: maxSpotlightRadius } = theme.__hd__.appCue.radii;
+  const { backdropColor } = theme.__hd__.appCue.colors;
+
+  const resolvedRadius = Math.min(
+    bounds.height / 2,
+    bounds.width / 2,
+    maxSpotlightRadius
+  );
+
+  return (
+    <Svg
+      width={windowWidth}
+      height={windowHeight}
+      style={{ position: 'absolute', top: 0, left: 0 }}
+    >
+      <Defs>
+        <Mask id="spotlight-mask">
+          <Rect width={windowWidth} height={windowHeight} fill="white" />
+          <Rect
+            x={bounds.x}
+            y={bounds.y}
+            width={bounds.width}
+            height={bounds.height}
+            rx={resolvedRadius}
+            ry={resolvedRadius}
+            fill="black"
+            testID={testID && `${testID}-spotlight`}
+          />
+        </Mask>
+      </Defs>
+      <Rect
+        width={windowWidth}
+        height={windowHeight}
+        fill={backdropColor}
+        mask="url(#spotlight-mask)"
+      />
+    </Svg>
+  );
+};
+
+export default SpotlightBackdrop;

package/src/components/AppCue/StyledAppCue.tsx

@@ -18,11 +18,14 @@ export const StyledContent = styled(View)(({ theme }) => ({
   alignSelf: 'center',
 }));
 
-export const StyledContainer = styled(View)(({ theme }) => ({
+export const StyledModalContainer = styled(View)({
   width: '100%',
   height: '100%',
-  backgroundColor: theme.__hd__.appCue.colors.backdropColor,
-}));
+});
+
+export const StyledContentPositioner = styled(View)({
+  position: 'absolute',
+});
 
 export const StyledIconContainer = styled(Animated.View)<{
   themePlacement: Placement;

package/src/components/AppCue/index.tsx

@@ -1,20 +1,22 @@
-import React, { useCallback, useLayoutEffect, useRef } from 'react';
+import React, { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
 import type { LayoutChangeEvent, StyleProp, ViewStyle } from 'react-native';
 import {
   Modal,
   View,
   TouchableWithoutFeedback,
-  StyleSheet,
   useWindowDimensions,
 } from 'react-native';
 import type { Placement } from './StyledAppCue';
 import {
-  StyledContainer,
   StyledContent,
+  StyledContentPositioner,
   StyledIconContainer,
+  StyledModalContainer,
 } from './StyledAppCue';
+import SpotlightBackdrop from './SpotlightBackdrop';
 import Typography from '../Typography';
 import Icon from '../Icon';
+
 import { useTheme } from '../../theme';
 import { calculatePosition, calulateContentMaxWidth } from './utils';
 
@@ -43,6 +45,16 @@ export interface AppCueProps {
    * Testing ID of the component.
    */
   testID?: string;
+  /**
+   * Controls visibility externally. When provided, the component becomes controlled
+   * and will not toggle open/closed on target press.
+   */
+  visible?: boolean;
+  /**
+   * Called when the backdrop is pressed. Use this in controlled mode to update
+   * the `visible` prop.
+   */
+  onDismiss?: () => void;
 }
 
 const AppCue = ({
@@ -51,18 +63,22 @@ const AppCue = ({
   placement = 'top',
   style,
   testID,
+  visible: controlledVisible,
+  onDismiss,
 }: AppCueProps) => {
   const targetContainerRef = useRef<View>(null);
 
-  const [visible, setVisible] = React.useState(false);
+  const isControlled = controlledVisible !== undefined;
+  const [internalVisible, setInternalVisible] = React.useState(false);
+  const open = isControlled ? controlledVisible : internalVisible;
 
   const theme = useTheme();
 
   const { offset } = theme.__hd__.appCue.space;
 
-  const [position, setPosition] = React.useState({
-    pageX: 0,
-    pageY: 0,
+  const [bounds, setBounds] = React.useState({
+    x: 0,
+    y: 0,
     width: 0,
     height: 0,
   });
@@ -75,20 +91,35 @@ const AppCue = ({
   const doMeasure = useCallback((cb?: () => void) => {
     targetContainerRef.current?.measure(
       (_, __, width, height, pageX, pageY) => {
-        setPosition({ pageX, pageY, width, height });
+        setBounds({ x: pageX, y: pageY, width, height });
         cb?.();
       }
     );
   }, []);
 
-  const handleOpen = () => {
-    doMeasure(() => setVisible(true));
-  };
+  const handleOpen = useCallback(() => {
+    if (!isControlled) {
+      doMeasure(() => setInternalVisible(true));
+    }
+  }, [isControlled, doMeasure]);
+
+  const handleDismiss = useCallback(() => {
+    if (!isControlled) {
+      setInternalVisible(false);
+    }
+    onDismiss?.();
+  }, [isControlled, onDismiss]);
 
   useLayoutEffect(() => {
     doMeasure();
   }, [doMeasure]);
 
+  useEffect(() => {
+    if (open) {
+      doMeasure();
+    }
+  }, [open, doMeasure]);
+
   const enhancedTarget = React.cloneElement(
     target,
     {
@@ -110,7 +141,7 @@ const AppCue = ({
   const { width: windowWidth } = useWindowDimensions();
 
   const pos = calculatePosition({
-    position,
+    position: bounds,
     contentSize,
     placement,
     offset,
@@ -118,7 +149,7 @@ const AppCue = ({
   });
 
   const maxWidth = calulateContentMaxWidth({
-    position,
+    position: bounds,
     offset,
     placement,
     windowWidth,
@@ -144,28 +175,28 @@ const AppCue = ({
       </TouchableWithoutFeedback>
       <Modal
         animationType="fade"
-        visible={visible}
-        onDismiss={() => setVisible(false)}
+        visible={open}
+        onDismiss={handleDismiss}
         transparent
         presentationStyle="overFullScreen"
         statusBarTranslucent
       >
         <TouchableWithoutFeedback
           testID={testID && `${testID}-backdrop`}
-          onPress={() => setVisible(false)}
+          onPress={handleDismiss}
         >
-          <StyledContainer>
-            <View
-              style={StyleSheet.flatten([
+          <StyledModalContainer>
+            <SpotlightBackdrop bounds={bounds} testID={testID} />
+            <StyledContentPositioner
+              style={[
                 {
-                  position: 'absolute',
                   top: pos.top,
                   left: pos.left,
                   bottom: pos.bottom,
                   right: pos.right,
                 },
                 style,
-              ])}
+              ]}
               onLayout={measureContent}
               testID={testID}
             >
@@ -181,8 +212,8 @@ const AppCue = ({
               >
                 <Icon icon="caret-down" size="small" />
               </StyledIconContainer>
-            </View>
-          </StyledContainer>
+            </StyledContentPositioner>
+          </StyledModalContainer>
         </TouchableWithoutFeedback>
       </Modal>
     </>