@hero-design/rn 8.132.1 → 8.133.0

package/src/components/AppCue/utils.ts

@@ -1,24 +1,5 @@
 import type { Placement } from './StyledAppCue';
 
-/**
- * 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.
- */
 export const calculatePosition = ({
   placement,
   position,
@@ -27,8 +8,8 @@ export const calculatePosition = ({
   windowWidth,
 }: {
   position: {
-    pageX: number;
-    pageY: number;
+    x: number;
+    y: number;
     width: number;
     height: number;
   };
@@ -48,86 +29,55 @@ export const calculatePosition = ({
   switch (placement) {
     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.
- */
 export const calulateContentMaxWidth = ({
   position,
   offset,
@@ -135,8 +85,8 @@ export const calulateContentMaxWidth = ({
   windowWidth,
 }: {
   position: {
-    pageX: number;
-    pageY: number;
+    x: number;
+    y: number;
     width: number;
     height: number;
   };
@@ -152,22 +102,22 @@ export const calulateContentMaxWidth = ({
       return undefined;
     }
     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;
     }
   }
 };

package/src/theme/components/appCue.ts

@@ -14,6 +14,7 @@ const getAppCueTheme = (theme: GlobalTheme) => {
 
   const radii = {
     container: theme.radii.large,
+    spotlight: theme.radii['5xlarge'],
   };
 
   return { colors, space, radii };

package/types/components/AppCue/SpotlightBackdrop.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+interface SpotlightBackdropProps {
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    testID?: string;
+}
+declare const SpotlightBackdrop: ({ bounds, testID }: SpotlightBackdropProps) => React.JSX.Element;
+export default SpotlightBackdrop;

package/types/components/AppCue/StyledAppCue.d.ts

@@ -6,7 +6,13 @@ export declare const StyledContent: import("@emotion/native").StyledComponent<im
 }, {}, {
     ref?: import("react").Ref<View> | undefined;
 }>;
-export declare const StyledContainer: import("@emotion/native").StyledComponent<import("react-native").ViewProps & {
+export declare const StyledModalContainer: import("@emotion/native").StyledComponent<import("react-native").ViewProps & {
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, {}, {
+    ref?: import("react").Ref<View> | undefined;
+}>;
+export declare const StyledContentPositioner: import("@emotion/native").StyledComponent<import("react-native").ViewProps & {
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;
 }, {}, {

package/types/components/AppCue/index.d.ts

@@ -19,6 +19,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;
 }
-declare const AppCue: ({ target, content, placement, style, testID, }: AppCueProps) => React.JSX.Element;
+declare const AppCue: ({ target, content, placement, style, testID, visible: controlledVisible, onDismiss, }: AppCueProps) => React.JSX.Element;
 export default AppCue;

package/types/components/AppCue/utils.d.ts

@@ -1,27 +1,8 @@
 import type { Placement } from './StyledAppCue';
-/**
- * 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.
- */
 export declare const calculatePosition: ({ placement, position, contentSize, offset, windowWidth, }: {
     position: {
-        pageX: number;
-        pageY: number;
+        x: number;
+        y: number;
         width: number;
         height: number;
     };
@@ -38,25 +19,10 @@ export declare const calculatePosition: ({ placement, position, contentSize, off
     bottom?: number;
     right?: number;
 };
-/**
- * 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.
- */
 export declare const calulateContentMaxWidth: ({ position, offset, placement, windowWidth, }: {
     position: {
-        pageX: number;
-        pageY: number;
+        x: number;
+        y: number;
         width: number;
         height: number;
     };

package/types/theme/components/appCue.d.ts

@@ -11,6 +11,7 @@ declare const getAppCueTheme: (theme: GlobalTheme) => {
     };
     radii: {
         container: number;
+        spotlight: number;
     };
 };
 export default getAppCueTheme;