@widergy/mobile-ui 1.47.0 → 1.48.1

package/lib/components/UTLabel/README.md

@@ -9,6 +9,7 @@
 | Name           | Type   | Default   | Description                                                                                                                                                                                   |
 | -------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | colorTheme     | string | 'dark'    | Color theme to style the `UTLabel`. It must be defined in the project theme. [Example](#colortheme).                                                                                          |
+| dataTestId     | string |           | Test ID for automated testing.                                                                                                                                                                |
 | field          | any    | {}        | Field configuration for advanced customization.                                                                                                                                               |
 | markdownStyles | object | {}        | Custom styles for rendering markdown content. This allows overriding default markdown styles like lists, links, etc.                                                                          |
 | numberOfLines  | number |           | Limits the number of lines displayed in the label. When set, `ellipsizeMode` is automatically set to 'tail'.                                                                                  |
@@ -20,6 +21,20 @@
 | weight         | string | 'regular' | Defines the font weight to be used. For a list of available options, check [here](#weights).                                                                                                  |
 | withMarkdown   | bool   | false     | Indicates whether or not to render text inside as markdown.                                                                                                                                   |
 
+## Test IDs
+
+When `dataTestId` is provided, the component applies the test ID to its element:
+
+| Element | Test ID         | Condition                         |
+| ------- | --------------- | --------------------------------- |
+| Label   | `${dataTestId}` | Always when `dataTestId` provided |
+
+### Test ID Details
+
+- **Label**: The main text element that displays the content
+
+The UTLabel component applies the test ID directly to its root text element, making it easy to identify and interact with in automated tests.
+
 ## Color Themes
 
 The `color` prop must be one of these values:
@@ -97,3 +112,14 @@ For all others: `shade05`
 ```jsx
 <UTLabel withMarkdown>{`This is **bold** and this is *italic* text.`}</UTLabel>
 ```
+
+### Example with Test IDs
+
+```jsx
+<UTLabel dataTestId="userWelcome" variant="title2" colorTheme="accent">
+  Welcome back, John!
+</UTLabel>
+
+// Generated test IDs:
+// userWelcome (label element)
+```

package/lib/components/UTLabel/constants.js

@@ -35,13 +35,3 @@ export const WEIGHTS = {
   extrabold: 800,
   black: 900
 };
-
-export const MARKDOWN_FORMATTING = {
-  BR_SEQUENCE_REGEX: /(<br\s*\/?>)+/gi,
-  BR_TAG_REGEX: /<br\s*\/?>/gi,
-  CARRIAGE_RETURN_REGEX: /\r\n|\r/g,
-  HR_TAG_REGEX: /<\s*hr\s*\/?>/gi,
-  LINE_BREAK_MARK: '\n\u200b',
-  LINE_BREAKS_REGEX: /\n+/g,
-  NORMALIZED_HR: '\n\n---'
-};

package/lib/components/UTLabel/index.js

@@ -11,6 +11,7 @@ import { DEFAULT_PROPS, propTypes } from './proptypes';
 const UTLabel = ({
   children,
   colorTheme,
+  dataTestId,
   field,
   markdownStyles,
   numberOfLines,
@@ -38,6 +39,7 @@ const UTLabel = ({
       {...additionalProps}
       onLinkPress={onLinkPress}
       onTextLayout={onTextLayout}
+      testID={dataTestId}
       style={
         withMarkdown
           ? { ...markdownStyles, body: labelStyles, paragraph: { marginTop: 0, marginBottom: 0 } }

package/lib/components/UTLabel/proptypes.js

@@ -14,6 +14,7 @@ export const DEFAULT_PROPS = {
 
 export const propTypes = {
   colorTheme: string,
+  dataTestId: string,
   // eslint-disable-next-line react/forbid-prop-types
   field: any,
   markdownStyles: object,

package/lib/components/UTLabel/utils.js

@@ -1,23 +1,5 @@
-import { MARKDOWN_FORMATTING } from './constants';
-
-const {
-  BR_SEQUENCE_REGEX,
-  BR_TAG_REGEX,
-  CARRIAGE_RETURN_REGEX,
-  HR_TAG_REGEX,
-  LINE_BREAK_MARK,
-  LINE_BREAKS_REGEX,
-  NORMALIZED_HR
-} = MARKDOWN_FORMATTING;
-
-export const markdownFormat = content => {
-  return content
+export const markdownFormat = content =>
+  content
     ?.toString()
-    .replace(CARRIAGE_RETURN_REGEX, '\n')
-    .replace(LINE_BREAKS_REGEX, match => LINE_BREAK_MARK.repeat(match.length))
-    .replace(BR_SEQUENCE_REGEX, match => {
-      const count = match.match(BR_TAG_REGEX)?.length || 0;
-      return LINE_BREAK_MARK.repeat(count);
-    })
-    .replace(HR_TAG_REGEX, NORMALIZED_HR);
-};
+    .replace(/(<\s*br\s*\/?>|\n)/gi, '\n\n')
+    .replace(/(<\s*hr\s*\/?>)/gi, '\n\n---') || null;

package/lib/components/UTMenu/README.md

@@ -0,0 +1,275 @@
+# UTMenu
+
+> **⚠️ AI-Generated Documentation Disclaimer**  
+> This documentation has been generated with AI assistance and has not been thoroughly reviewed by a developer. Please verify implementation details and usage examples before relying on them in production code.
+
+A flexible dropdown menu component that provides a modal overlay with selectable options. Features customizable positioning, search functionality, Google attribution support, and comprehensive test ID support.
+
+## Props
+
+| NAME                    | TYPE      | REQUIRED | DESCRIPTION                                                                                                |
+| ----------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| options                 | array     | Yes      | Array of option objects. Each option must have `id`, `label`, and optionally `value`, `action` properties. |
+| children                | node      | Yes      | The trigger element that will open the menu when pressed.                                                  |
+| onPress                 | func      | No       | Callback function called when an option is selected. Receives the selected option.                         |
+| selectedOption          | object    | No       | Currently selected option object (for single selection) or array of values (for multiple).                 |
+| onOpen                  | func      | No       | Callback function called when the menu opens.                                                              |
+| onClose                 | func      | No       | Callback function called when the menu closes.                                                             |
+| disabled                | bool      | No       | Whether the menu trigger is disabled.                                                                      |
+| fullWidth               | bool      | No       | Whether the menu should match the width of the trigger element.                                            |
+| verticalOffset          | number    | No       | Vertical offset for menu positioning relative to trigger. Default: 0.                                      |
+| horizontalOffset        | number    | No       | Horizontal offset for menu positioning relative to trigger. Default: 0.                                    |
+| avoidOverlappingAnchor  | bool      | No       | Whether to avoid overlapping the trigger element. Default: true.                                           |
+| withoutOpacity          | bool      | No       | Whether to disable opacity change on trigger press.                                                        |
+| isMultiple              | bool      | No       | Enables multiple selection mode.                                                                           |
+| maxHeight               | number    | No       | Maximum height for the options list.                                                                       |
+| withAutocomplete        | bool      | No       | Enables search/filter functionality with text input.                                                       |
+| autoCompletePlaceholder | string    | No       | Placeholder text for the search input.                                                                     |
+| onQueryChange           | func      | No       | Callback function called when search query changes.                                                        |
+| filterOptions           | bool      | No       | Whether to filter options based on search query. Default: true.                                            |
+| MenuOptionComponent     | component | No       | Custom component to render menu options. Default: MenuOption.                                              |
+| ItemSeparatorComponent  | component | No       | Component to render between menu options.                                                                  |
+| ListEmptyComponent      | component | No       | Component to render when no options are available.                                                         |
+| withGoogleAttribution   | bool      | No       | Whether to show Google attribution (for location services). Default: false.                                |
+| styles                  | object    | No       | Custom styles for menu components.                                                                         |
+| dataTestId              | string    | No       | Unique identifier for testing purposes. Creates hierarchical test IDs for child elements.                  |
+
+## Option Object Structure
+
+Each option in the `options` array should have the following structure:
+
+```js
+{
+  id: string | number,        // Unique identifier for the option
+  label: string,              // Display text for the option
+  value?: any,                // Optional value (defaults to id if not provided)
+  action?: function          // Optional custom action function
+}
+```
+
+## Usage Examples
+
+### Basic Menu
+
+```jsx
+import React, { useState } from 'react';
+import { Text, View } from 'react-native';
+import UTMenu from '@widergy/mobile-ui/lib/components/UTMenu';
+
+const BasicExample = () => {
+  const [selectedOption, setSelectedOption] = useState(null);
+
+  const options = [
+    { id: '1', label: 'Option 1' },
+    { id: '2', label: 'Option 2' },
+    { id: '3', label: 'Option 3' }
+  ];
+
+  return (
+    <UTMenu options={options} onPress={setSelectedOption} selectedOption={selectedOption?.id}>
+      <View style={{ padding: 10, backgroundColor: '#f0f0f0' }}>
+        <Text>{selectedOption?.label || 'Select an option'}</Text>
+      </View>
+    </UTMenu>
+  );
+};
+```
+
+### Menu with Search
+
+```jsx
+const SearchableMenu = () => {
+  const [selected, setSelected] = useState(null);
+  const [query, setQuery] = useState('');
+
+  const options = [
+    { id: 'apple', label: 'Apple' },
+    { id: 'banana', label: 'Banana' },
+    { id: 'cherry', label: 'Cherry' },
+    { id: 'date', label: 'Date' },
+    { id: 'elderberry', label: 'Elderberry' }
+  ];
+
+  return (
+    <UTMenu
+      options={options}
+      onPress={setSelected}
+      selectedOption={selected?.id}
+      withAutocomplete
+      autoCompletePlaceholder="Search fruits..."
+      onQueryChange={setQuery}
+    >
+      <View style={{ padding: 12, borderWidth: 1, borderColor: '#ccc' }}>
+        <Text>{selected?.label || 'Choose a fruit'}</Text>
+      </View>
+    </UTMenu>
+  );
+};
+```
+
+### Multiple Selection Menu
+
+```jsx
+const MultipleSelectionMenu = () => {
+  const [selectedValues, setSelectedValues] = useState([]);
+
+  const skillOptions = [
+    { id: 'react', label: 'React', value: 'react' },
+    { id: 'vue', label: 'Vue.js', value: 'vue' },
+    { id: 'angular', label: 'Angular', value: 'angular' },
+    { id: 'svelte', label: 'Svelte', value: 'svelte' }
+  ];
+
+  return (
+    <UTMenu
+      options={skillOptions}
+      onPress={option => {
+        const isSelected = selectedValues.includes(option.value);
+        if (isSelected) {
+          setSelectedValues(prev => prev.filter(val => val !== option.value));
+        } else {
+          setSelectedValues(prev => [...prev, option.value]);
+        }
+      }}
+      selectedOption={selectedValues}
+      isMultiple
+    >
+      <View style={{ padding: 12, borderWidth: 1 }}>
+        <Text>{selectedValues.length > 0 ? `Selected: ${selectedValues.join(', ')}` : 'Select skills'}</Text>
+      </View>
+    </UTMenu>
+  );
+};
+```
+
+### Custom Positioning
+
+```jsx
+const CustomPositionMenu = () => {
+  return (
+    <UTMenu
+      options={options}
+      onPress={handlePress}
+      verticalOffset={-5}
+      horizontalOffset={10}
+      fullWidth={false}
+      avoidOverlappingAnchor={false}
+    >
+      <YourTriggerComponent />
+    </UTMenu>
+  );
+};
+```
+
+## Testing
+
+The `UTMenu` component supports comprehensive test ID assignment through the `dataTestId` prop. When provided, it creates a hierarchical structure of test IDs for all interactive and meaningful elements.
+
+### Test ID Structure
+
+When you provide `dataTestId="provided.testId"`, the following test IDs are automatically generated:
+
+| Element             | Test ID                                     | When Available                       |
+| ------------------- | ------------------------------------------- | ------------------------------------ |
+| Menu anchor/trigger | `provided.testId.anchor`                    | Always (when dataTestId is provided) |
+| Modal overlay       | `provided.testId.modal`                     | When menu is open                    |
+| Search input        | `provided.testId.searchInput`               | When withAutocomplete is true        |
+| Options list        | `provided.testId.list`                      | When menu is open                    |
+| Individual option   | `provided.testId.list.option.{index}`       | For each option when menu is open    |
+| Option label        | `provided.testId.list.option.{index}.label` | For each option when menu is open    |
+| Attribution text    | `provided.testId.attribution.text`          | When withGoogleAttribution is true   |
+| Attribution logo    | `provided.testId.attribution.logo`          | When withGoogleAttribution is true   |
+
+**Note:** The search input test ID (`provided.testId.searchInput`) creates additional hierarchical test IDs based on the UTTextInput component's own test ID structure.
+
+### Test ID Examples
+
+```jsx
+// Basic menu with test IDs
+<UTMenu
+  dataTestId="actionMenu"
+  options={actionOptions}
+  onPress={handleAction}
+>
+  <ActionButton />
+</UTMenu>
+
+// Creates test IDs:
+// - actionMenu.anchor (trigger button)
+// - actionMenu.modal (when open)
+// - actionMenu.list (options container when open)
+// - actionMenu.list.option.0 (first option when open)
+// - actionMenu.list.option.0.label (first option text when open)
+// - actionMenu.list.option.1 (second option when open)
+// - actionMenu.list.option.1.label (second option text when open)
+
+// Searchable menu with test IDs
+<UTMenu
+  dataTestId="fruitSelector"
+  options={fruitOptions}
+  onPress={handleFruitSelection}
+  withAutocomplete
+  autoCompletePlaceholder="Search fruits..."
+>
+  <FruitSelectorTrigger />
+</UTMenu>
+
+// Creates test IDs:
+// - fruitSelector.anchor (trigger)
+// - fruitSelector.modal (when open)
+// - fruitSelector.searchInput (search input + UTTextInput sub-elements)
+// - fruitSelector.list (options container)
+// - fruitSelector.list.option.0 (first fruit option)
+// - fruitSelector.list.option.0.label (first fruit option text)
+// - fruitSelector.list.option.1 (second fruit option)
+// - fruitSelector.list.option.1.label (second fruit option text)
+
+// Menu with Google attribution and test IDs
+<UTMenu
+  dataTestId="locationMenu"
+  options={locationOptions}
+  onPress={handleLocationSelect}
+  withGoogleAttribution
+>
+  <LocationTrigger />
+</UTMenu>
+
+// Creates test IDs:
+// - locationMenu.anchor (trigger)
+// - locationMenu.modal (when open)
+// - locationMenu.list (options container)
+// - locationMenu.list.option.0 (first location option)
+// - locationMenu.list.option.1 (second location option)
+// - locationMenu.attribution.text (attribution text)
+// - locationMenu.attribution.logo (Google logo)
+```
+
+## Custom Menu Option Components
+
+You can provide a custom `MenuOptionComponent` that will receive the following props:
+
+```jsx
+const CustomMenuOption = ({ onPress, label, selected, item, styles, dataTestId }) => {
+  return (
+    <TouchableOpacity
+      onPress={() => onPress(item)}
+      style={[customStyles.option, selected && customStyles.selected]}
+      testID={dataTestId}
+    >
+      <Text testID={dataTestId ? `${dataTestId}.label` : undefined}>{label}</Text>
+    </TouchableOpacity>
+  );
+};
+
+// Usage
+<UTMenu
+  MenuOptionComponent={CustomMenuOption}
+  options={options}
+  onPress={handlePress}
+  dataTestId="customMenu"
+>
+  <TriggerComponent />
+</UTMenu>;
+```
+
+**Note:** When implementing custom menu option components, make sure to handle the `dataTestId` prop properly to maintain the hierarchical test ID structure.

package/lib/components/UTMenu/components/ListView/index.js

@@ -31,8 +31,8 @@ class ListView extends PureComponent {
     return handleOptionPress(item.action || (() => onPress(item)), item?.value);
   };
 
-  renderItem = ({ item }) => {
-    const { MenuOptionComponent, propStyles } = this.props;
+  renderItem = ({ item, index }) => {
+    const { MenuOptionComponent, propStyles, dataTestId } = this.props;
 
     return (
       <MenuOptionComponent
@@ -41,12 +41,13 @@ class ListView extends PureComponent {
         onPress={this.handleOnPress}
         styles={propStyles}
         item={item}
+        dataTestId={dataTestId ? `${dataTestId}.option.${index}` : undefined}
       />
     );
   };
 
   render() {
-    const { filteredOptions, ItemSeparatorComponent, ListEmptyComponent } = this.props;
+    const { filteredOptions, ItemSeparatorComponent, ListEmptyComponent, dataTestId } = this.props;
     const { style } = this.state;
 
     return (
@@ -58,6 +59,7 @@ class ListView extends PureComponent {
         renderItem={this.renderItem}
         ItemSeparatorComponent={ItemSeparatorComponent}
         ListEmptyComponent={ListEmptyComponent}
+        testID={dataTestId}
       />
     );
   }

package/lib/components/UTMenu/components/ListView/proptypes.js

@@ -12,5 +12,6 @@ export default {
   maxHeight: number,
   windowHeight: number,
   usableWindowHeight: number,
-  ItemSeparatorComponent: any
+  ItemSeparatorComponent: any,
+  dataTestId: string
 };

package/lib/components/UTMenu/components/MenuOption/index.js

@@ -5,7 +5,7 @@ import { TouchableOpacity, Text } from 'react-native';
 
 import styles from './styles';
 
-const MenuOption = ({ onPress, label, selected, styles: propStyles, item }) => (
+const MenuOption = ({ onPress, label, selected, styles: propStyles, item, dataTestId }) => (
   <TouchableOpacity
     onPress={() => onPress(item)}
     style={[
@@ -14,8 +14,9 @@ const MenuOption = ({ onPress, label, selected, styles: propStyles, item }) => (
       selected && styles.selected,
       selected && propStyles?.menuOptionSelected
     ]}
+    testID={dataTestId}
   >
-    <Text>{label}</Text>
+    <Text testID={dataTestId ? `${dataTestId}.label` : undefined}>{label}</Text>
   </TouchableOpacity>
 );
 
@@ -25,7 +26,8 @@ MenuOption.propTypes = {
   selected: bool,
   styles: ViewPropTypes.style,
   // eslint-disable-next-line react/forbid-prop-types
-  item: shape(any)
+  item: shape(any),
+  dataTestId: string
 };
 
 export default memo(MenuOption);

package/lib/components/UTMenu/index.js

@@ -13,6 +13,7 @@ import useKeyboardHeight from '../../hooks/useKeyboardHeight';
 import UTTextInput from '../UTTextInput';
 import UTLabel from '../UTLabel';
 import Surface from '../Surface';
+import { TEST_ID_CONSTANTS } from '../../constants/testIds';
 
 import MenuOption from './components/MenuOption';
 import ListView from './components/ListView';
@@ -21,6 +22,8 @@ import styles from './styles';
 import GoogleLogo from './assets/google_on_white.png';
 import { ATTRIBUTION } from './constants';
 
+const { anchor, modal, searchInput, list, attribution, text, logo } = TEST_ID_CONSTANTS;
+
 const UTMenu = ({
   autoCompletePlaceholder,
   avoidOverlappingAnchor = true,
@@ -44,7 +47,8 @@ const UTMenu = ({
   verticalOffset = 0,
   withAutocomplete,
   withoutOpacity,
-  withGoogleAttribution = false
+  withGoogleAttribution = false,
+  dataTestId
 }) => {
   const [isOpen, setIsOpen] = useState(false);
   const anchorRef = useRef(null);
@@ -138,6 +142,7 @@ const UTMenu = ({
         activeOpacity={withoutOpacity && 1}
         disabled={disabled}
         onPress={isOpen ? closeMenu : openMenu}
+        testID={dataTestId ? `${dataTestId}.${anchor}` : undefined}
       >
         <View onLayout={handleAnchorLayout} pointerEvents="box-only" ref={anchorRef}>
           {children}
@@ -149,6 +154,7 @@ const UTMenu = ({
         onShow={focusSearchInput}
         transparent
         visible={isOpen}
+        testID={dataTestId ? `${dataTestId}.${modal}` : undefined}
       >
         <TouchableOpacity onPress={closeMenu} style={styles.overlayTouchable}>
           <View style={styles.overlay} />
@@ -170,6 +176,7 @@ const UTMenu = ({
                     }
                     placeholder={autoCompletePlaceholder}
                     value={query}
+                    dataTestId={dataTestId ? `${dataTestId}.${searchInput}` : undefined}
                   />
                 </View>
               )}
@@ -187,13 +194,21 @@ const UTMenu = ({
                 selectedOption={selectedOption}
                 usableWindowHeight={usableWindowHeight}
                 windowHeight={windowHeight}
+                dataTestId={dataTestId ? `${dataTestId}.${list}` : undefined}
               />
               {withGoogleAttribution && (
                 <View style={styles.attribution}>
-                  <UTLabel colorTheme="gray" variant="small">
+                  <UTLabel
+                    colorTheme="gray"
+                    variant="small"
+                    dataTestId={dataTestId ? `${dataTestId}.${attribution}.${text}` : undefined}
+                  >
                     {ATTRIBUTION}
                   </UTLabel>
-                  <Image source={GoogleLogo} />
+                  <Image
+                    source={GoogleLogo}
+                    testID={dataTestId ? `${dataTestId}.${attribution}.${logo}` : undefined}
+                  />
                 </View>
               )}
             </KeyboardAvoidingView>

package/lib/components/UTMenu/proptypes.js

@@ -17,5 +17,6 @@ export default {
   horizontalOffset: number,
   onPress: func,
   disabled: bool,
-  withoutOpacity: bool
+  withoutOpacity: bool,
+  dataTestId: string
 };