@widergy/mobile-ui 1.46.1 → 1.48.0

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
 };

package/lib/components/UTModal/README.md

@@ -0,0 +1,193 @@
+# UTModal
+
+## Description
+
+> ⚠️ **AI-GENERATED DOCUMENTATION**
+> This documentation was entirely generated by an AI assistant and has NOT been reviewed by human developers. The test ID implementation details, patterns, examples, and usage instructions should be thoroughly verified before use in production. Please validate all functionality and testing approaches with your development team.
+
+`UTModal` is a customizable modal component that provides a flexible overlay interface for displaying content, dialogs, and forms. It supports features like background images, loading states, custom buttons, and keyboard handling.
+
+## Props
+
+| Name                  | Type    | Default      | Description                                                               |
+| --------------------- | ------- | ------------ | ------------------------------------------------------------------------- |
+| acceptButton          | object  |              | Configuration for the accept/primary button. See Button Object section.   |
+| backgroundImg         | number  |              | Background image source for the modal.                                    |
+| backgroundStyles      | object  |              | Styles to apply to the background image.                                  |
+| cancelButton          | object  |              | Configuration for the cancel/secondary button. See Button Object section. |
+| children              | node    |              | Content to display inside the modal.                                      |
+| closeButtonColorTheme | string  |              | Color theme for the close button.                                         |
+| dataTestId            | string  | 'modal'      | Test ID for automated testing. Enables hierarchical test ID structure.    |
+| disableTouchable      | bool    | false        | If true, disables the touchable overlay that dismisses the keyboard.      |
+| hideCloseButton       | bool    | false        | If true, hides the close button.                                          |
+| hideSeparatorBar      | bool    | false        | If true, hides the separator bar above buttons.                           |
+| imageComponent        | element |              | Custom image component to display in the modal.                           |
+| imageStyles           | object  |              | Styles to apply to the image component container.                         |
+| loading               | bool    | false        | If true, shows a loading overlay.                                         |
+| loadingText           | string  |              | Text to display during loading state.                                     |
+| modalBackgroundColor  | string  |              | Custom background color for the modal.                                    |
+| modalStyles           | object  |              | Custom styles to apply to the modal container.                            |
+| onRequestClose        | func    | () => {}     | Function called when the modal should be closed.                          |
+| subtitle              | string  |              | Subtitle text to display below the title.                                 |
+| subtitleProps         | object  | {}           | Additional props to pass to the subtitle UTLabel component.               |
+| title                 | string  |              | Title text to display in the modal header.                                |
+| visible               | bool    | **required** | Controls whether the modal is visible.                                    |
+| style                 | object  |              | Custom styles to apply to the modal.                                      |
+
+## Test IDs
+
+When `dataTestId` is provided (defaults to 'modal'), the component creates a hierarchical test ID structure:
+
+| Element       | Test ID                      | Condition                            |
+| ------------- | ---------------------------- | ------------------------------------ |
+| Modal         | `${dataTestId}`              | Always (defaults to 'modal')         |
+| Title         | `${dataTestId}.title`        | When `title` prop is provided        |
+| Subtitle      | `${dataTestId}.subtitle`     | When `subtitle` prop is provided     |
+| Close Button  | `${dataTestId}.closeButton`  | When close button is visible         |
+| Cancel Button | `${dataTestId}.cancelButton` | When `cancelButton` prop is provided |
+| Accept Button | `${dataTestId}.acceptButton` | When `acceptButton` prop is provided |
+
+### Test ID Structure Details
+
+- **Modal**: The main Modal component that controls visibility and overlay behavior
+- **Title**: The main title text displayed in the modal header (handled by UTLabel)
+- **Subtitle**: The subtitle text displayed below the title (handled by UTLabel)
+- **Close Button**: The X button used to close the modal (handled by UTButton)
+- **Cancel Button**: The secondary/cancel button (handled by UTButton)
+- **Accept Button**: The primary/accept button (handled by UTButton)
+
+Each button and label follows their respective component test ID patterns with their own hierarchical structure.
+
+**Default Test ID**: Since only one modal should be visible at a time, the `dataTestId` prop defaults to 'modal'. This ensures that every UTModal instance has a consistent, predictable test ID structure available, while still allowing for custom test IDs when multiple modal types need to be distinguished.
+
+### Button Object
+
+The `acceptButton` and `cancelButton` props are objects with the following structure:
+
+| Name       | Type   | Description                                  |
+| ---------- | ------ | -------------------------------------------- |
+| colorTheme | string | Color theme for the button.                  |
+| disabled   | bool   | Whether the button is disabled.              |
+| onPress    | func   | Function to call when the button is pressed. |
+| text       | string | Text to display on the button.               |
+
+## Usage
+
+### Basic Example
+
+```jsx
+import React from 'react';
+import { UTModal, UTLabel } from '@widergy/mobile-ui';
+
+const Example = () => {
+  const [visible, setVisible] = React.useState(false);
+
+  const handleClose = () => setVisible(false);
+  const handleAccept = () => {
+    // Perform action
+    setVisible(false);
+  };
+
+  return (
+    <UTModal
+      visible={visible}
+      title="Confirm Action"
+      subtitle="Are you sure you want to proceed?"
+      onRequestClose={handleClose}
+      acceptButton={{
+        text: 'Yes, Continue',
+        onPress: handleAccept
+      }}
+      cancelButton={{
+        text: 'Cancel',
+        onPress: handleClose
+      }}
+    >
+      <UTLabel>This action cannot be undone.</UTLabel>
+    </UTModal>
+  );
+};
+
+export default Example;
+```
+
+### With Custom Test ID
+
+```jsx
+import React from 'react';
+import { UTModal, UTLabel } from '@widergy/mobile-ui';
+
+const TestableExample = () => {
+  const [visible, setVisible] = React.useState(false);
+
+  const handleClose = () => setVisible(false);
+  const handleDelete = () => {
+    // Perform delete action
+    setVisible(false);
+  };
+
+  return (
+    <UTModal
+      dataTestId="deleteConfirmModal"
+      visible={visible}
+      title="Delete Item"
+      subtitle="This action cannot be undone"
+      onRequestClose={handleClose}
+      acceptButton={{
+        text: 'Delete',
+        onPress: handleDelete,
+        colorTheme: 'danger'
+      }}
+      cancelButton={{
+        text: 'Cancel',
+        onPress: handleClose
+      }}
+    >
+      <UTLabel>Are you sure you want to delete this item?</UTLabel>
+    </UTModal>
+  );
+};
+
+// Generated test IDs:
+// deleteConfirmModal (main modal)
+// deleteConfirmModal.title (title text)
+// deleteConfirmModal.subtitle (subtitle text)
+// deleteConfirmModal.closeButton (close X button)
+// deleteConfirmModal.cancelButton (cancel button)
+// deleteConfirmModal.acceptButton (delete button)
+
+export default TestableExample;
+```
+
+### With Default Test ID
+
+```jsx
+import React from 'react';
+import { UTModal, UTLabel } from '@widergy/mobile-ui';
+
+const DefaultTestIdExample = () => {
+  const [visible, setVisible] = React.useState(false);
+
+  return (
+    <UTModal
+      visible={visible}
+      title="Default Modal"
+      onRequestClose={() => setVisible(false)}
+      acceptButton={{
+        text: 'OK',
+        onPress: () => setVisible(false)
+      }}
+    >
+      <UTLabel>This modal uses the default test ID 'modal'.</UTLabel>
+    </UTModal>
+  );
+};
+
+// Generated test IDs (using default):
+// modal (main modal)
+// modal.title (title text)
+// modal.closeButton (close X button)
+// modal.acceptButton (OK button)
+
+export default DefaultTestIdExample;
+```