@widergy/mobile-ui 1.47.0 → 1.48.0

package/lib/components/UTSelect/versions/V0/README.md

@@ -0,0 +1,216 @@
+# UTSelect V0
+
+> **⚠️ 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 customizable select/dropdown component with support for single and multiple selection modes. Features autocomplete functionality, custom styling, and comprehensive test ID support.
+
+## Props
+
+| NAME             | TYPE   | REQUIRED | DESCRIPTION                                                                               |
+| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
+| options          | array  | Yes      | Array of option objects. Each option must have `id`, `label`, and `value` properties.     |
+| value            | any    | No       | Selected value(s). For single select: option value. For multiple: array of values.        |
+| onChange         | func   | No       | Callback function called when selection changes. Receives the selected value(s).          |
+| label            | string | No       | Label text for the input field.                                                           |
+| error            | string | No       | Error message to display.                                                                 |
+| disabled         | bool   | No       | Whether the select is disabled.                                                           |
+| variant          | string | No       | Visual variant for the text input.                                                        |
+| isMultiple       | bool   | No       | Enables multiple selection mode with checkboxes.                                          |
+| title            | string | No       | Title text displayed above the select.                                                    |
+| titleProps       | object | No       | Additional props to pass to the title Label component.                                    |
+| changeOnClose    | bool   | No       | When true, onChange is only called when the menu closes, not on each selection.           |
+| verticalOffset   | number | No       | Vertical offset for the dropdown menu positioning. Default: 5.                            |
+| UTMenuProps      | object | No       | Additional props to pass to the underlying UTMenu component.                              |
+| UTTextInputProps | object | No       | Additional props to pass to the underlying UTTextInput component.                         |
+| styles           | object | No       | Custom styles for the container.                                                          |
+| 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,                 // Value to be passed to onChange when selected
+  action?: function          // Optional custom action function
+}
+```
+
+## Usage Examples
+
+### Basic Single Select
+
+```jsx
+import React, { useState } from 'react';
+import UTSelect from '@widergy/mobile-ui/lib/components/UTSelect/versions/V0';
+
+const BasicExample = () => {
+  const [selectedValue, setSelectedValue] = useState(null);
+
+  const options = [
+    { id: '1', label: 'Option 1', value: 'value1' },
+    { id: '2', label: 'Option 2', value: 'value2' },
+    { id: '3', label: 'Option 3', value: 'value3' }
+  ];
+
+  return (
+    <UTSelect options={options} value={selectedValue} onChange={setSelectedValue} label="Choose an option" />
+  );
+};
+```
+
+### Multiple Select with Title
+
+```jsx
+const MultipleSelectExample = () => {
+  const [selectedValues, setSelectedValues] = useState([]);
+
+  const options = [
+    { id: 'red', label: 'Red', value: 'red' },
+    { id: 'green', label: 'Green', value: 'green' },
+    { id: 'blue', label: 'Blue', value: 'blue' }
+  ];
+
+  return (
+    <UTSelect
+      options={options}
+      value={selectedValues}
+      onChange={setSelectedValues}
+      label="Select colors"
+      title="Color Selection"
+      isMultiple
+    />
+  );
+};
+```
+
+### With Error State
+
+```jsx
+const ValidationExample = () => {
+  const [value, setValue] = useState(null);
+  const [error, setError] = useState('');
+
+  const handleChange = newValue => {
+    setValue(newValue);
+    if (newValue) {
+      setError('');
+    } else {
+      setError('Please select an option');
+    }
+  };
+
+  return (
+    <UTSelect options={options} value={value} onChange={handleChange} label="Required Field" error={error} />
+  );
+};
+```
+
+## Testing
+
+The `UTSelect` 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                                          |
+| ----------------------- | ------------------------ | ------------------------------------------------------- |
+| Text input field        | `provided.testId`        | Always (when dataTestId is provided)                    |
+| Title text              | `provided.testId.title`  | When title prop is provided                             |
+| Menu (all sub-elements) | `provided.testId.menu.*` | When menu is open - inherits UTMenu's test ID structure |
+
+**Note:**
+
+- The text input field test ID (`provided.testId`) creates additional hierarchical test IDs based on the UTTextInput component's own test ID structure.
+- The menu test ID (`provided.testId.menu`) creates a hierarchical structure based on UTMenu's streamlined test ID implementation, including:
+  - `provided.testId.menu.anchor` (menu trigger)
+  - `provided.testId.menu.modal` (when open)
+  - `provided.testId.menu.searchInput` (when autocomplete is enabled)
+  - `provided.testId.menu.list` (options container)
+  - `provided.testId.menu.list.option.{index}` (each option by index)
+  - `provided.testId.menu.list.option.{index}.label` (each option label)
+  - For multiple selection: each checkbox inherits the option's test ID structure
+
+### Test ID Examples
+
+```jsx
+// Basic single select with test IDs
+<UTSelect
+  dataTestId="countrySelect"
+  options={countries}
+  value={selectedCountry}
+  onChange={setSelectedCountry}
+  label="Select Country"
+/>
+
+// Creates test IDs:
+// - countrySelect (text input field and its sub-elements)
+// - countrySelect.menu.anchor (menu trigger - same as text input area)
+// - countrySelect.menu.modal (when menu is open)
+// - countrySelect.menu.list (options container when open)
+// - countrySelect.menu.list.option.0 (first option when open)
+// - countrySelect.menu.list.option.0.label (first option label when open)
+// - countrySelect.menu.list.option.1 (second option when open)
+// - countrySelect.menu.list.option.1.label (second option label when open)
+// ... etc for each option
+
+// Multiple select with title and test IDs
+<UTSelect
+  dataTestId="skillsSelect"
+  options={skillOptions}
+  value={selectedSkills}
+  onChange={setSelectedSkills}
+  title="Technical Skills"
+  label="Choose your skills"
+  isMultiple
+/>
+
+// Creates test IDs:
+// - skillsSelect (text input field and its sub-elements)
+// - skillsSelect.title (title label)
+// - skillsSelect.menu.anchor (menu trigger)
+// - skillsSelect.menu.modal (when menu is open)
+// - skillsSelect.menu.list (options container when open)
+// - skillsSelect.menu.list.option.0 (first checkbox option when open)
+// - skillsSelect.menu.list.option.0.label (first option label when open)
+// - skillsSelect.menu.list.option.1 (second checkbox option when open)
+// - skillsSelect.menu.list.option.1.label (second option label when open)
+// - skillsSelect.menu.list.option.2 (third checkbox option when open)
+// - skillsSelect.menu.list.option.2.label (third option label when open)
+// ... etc for each option
+
+// Complex example with searchable menu
+const options = [
+  { id: 'beginner', label: 'Beginner Level', value: 'beginner' },
+  { id: 'intermediate', label: 'Intermediate Level', value: 'intermediate' },
+  { id: 'advanced', label: 'Advanced Level', value: 'advanced' }
+];
+
+<UTSelect
+  dataTestId="userLevel"
+  options={options}
+  value={userLevel}
+  onChange={setUserLevel}
+  title="Experience Level"
+  label="Select your level"
+  UTMenuProps={{ withAutocomplete: true, autoCompletePlaceholder: "Search levels..." }}
+/>
+
+// Creates test IDs:
+// - userLevel (text input field and its sub-elements)
+// - userLevel.title (title label)
+// - userLevel.menu.anchor (menu trigger)
+// - userLevel.menu.modal (when menu is open)
+// - userLevel.menu.searchInput (search input when menu is open)
+// - userLevel.menu.list (options container when open)
+// - userLevel.menu.list.option.0 (first option when open)
+// - userLevel.menu.list.option.0.label (first option label when open)
+// - userLevel.menu.list.option.1 (second option when open)
+// - userLevel.menu.list.option.1.label (second option label when open)
+// - userLevel.menu.list.option.2 (third option when open)
+// - userLevel.menu.list.option.2.label (third option label when open)
+```

package/lib/components/UTSelect/versions/V0/componentes/MultipleItem/index.js

@@ -6,12 +6,13 @@ import Checkbox from '../../../../../Checkbox';
 
 import styles from './styles';
 
-const MultipleItem = ({ onPress, label, selected, checkboxProps, item }) => (
+const MultipleItem = ({ onPress, label, selected, checkboxProps, item, dataTestId }) => (
   <Checkbox
     label={label}
     onPress={() => onPress(item)}
     checked={selected}
     style={styles.checkbox}
+    dataTestId={dataTestId}
     {...checkboxProps}
   />
 );
@@ -21,7 +22,8 @@ MultipleItem.propTypes = {
   label: string,
   selected: bool,
   checkboxProps: shape(any),
-  item: shape(any)
+  item: shape(any),
+  dataTestId: string
 };
 
 export default memo(MultipleItem);

package/lib/components/UTSelect/versions/V0/index.js

@@ -25,7 +25,8 @@ const UTSelect = ({
   verticalOffset = 5,
   title,
   titleProps,
-  changeOnClose
+  changeOnClose,
+  dataTestId
 }) => {
   const [focused, setFocused] = useState(false);
 
@@ -63,7 +64,7 @@ const UTSelect = ({
   return (
     <View style={[styles.container, propStyles]}>
       {title && (
-        <Label medium primary {...titleProps}>
+        <Label medium primary {...titleProps} dataTestId={dataTestId ? `${dataTestId}.title` : undefined}>
           {title}
         </Label>
       )}
@@ -79,6 +80,7 @@ const UTSelect = ({
         withoutOpacity
         MenuOptionComponent={isMultiple && MultipleItem}
         isMultiple={isMultiple}
+        dataTestId={dataTestId ? `${dataTestId}.menu` : undefined}
         {...UTMenuProps}
       >
         <UTTextInput
@@ -91,6 +93,7 @@ const UTSelect = ({
           disabled={disabled}
           version="V0"
           RightIcon={{ type: 'font-awesome', name: 'caret-down' }}
+          dataTestId={dataTestId}
           {...UTTextInputProps}
         />
       </UTMenu>

package/lib/components/UTSelect/versions/V0/proptypes.js

@@ -18,5 +18,6 @@ export default {
   variant: string,
   UTMenuProps: any,
   value: any,
-  isMultiple: bool
+  isMultiple: bool,
+  dataTestId: string
 };

package/lib/components/UTSelect/versions/V1/README.md

@@ -9,6 +9,7 @@
 | action                | shape                      |         | Action object containing `Icon`, `onPress`, and `size` for the action button.                                           |
 | alwaysShowPlaceholder | bool                       | true    | Determines if the placeholder should always be shown.                                                                   |
 | clearable             | bool                       | false   | Determines whether a button to clear the current selection should be shown.                                             |
+| dataTestId            | string                     |         | Test ID for automated testing. Enables hierarchical test ID structure.                                                  |
 | helpText              | string                     |         | Help text displayed below the input field.                                                                              |
 | title                 | string                     |         | Title for the select field.                                                                                             |
 | multiple              | bool                       | false   | Allows multiple selection if true.                                                                                      |
@@ -27,6 +28,47 @@
 | value                 | oneOfType([string, array]) | null    | The value of the input field. It can be a string for single selection or an array for multiple selection.               |
 | withAutoReset         | bool                       | true    | Determines whether the select should automatically reset when the selected value is no longer available in the options. |
 
+## Test IDs
+
+When `dataTestId` is provided, the component creates a hierarchical test ID structure:
+
+| Element            | Test ID                          | Condition                         |
+| ------------------ | -------------------------------- | --------------------------------- |
+| Select trigger     | `${dataTestId}`                  | Always when `dataTestId` provided |
+| Title              | `${dataTestId}.title`            | When `title` prop is provided     |
+| Input field        | `${dataTestId}.input`            | Always when `dataTestId` provided |
+| Help text          | `${dataTestId}.helpText`         | When `helpText` prop is provided  |
+| Validation         | `${dataTestId}.validation`       | When `error` prop is provided     |
+| Bottom sheet       | `${dataTestId}.bottomSheet`      | When bottom sheet is open         |
+| Search field       | `${dataTestId}.searchField`      | When bottom sheet is open         |
+| No options message | `${dataTestId}.noOptionsMessage` | When no options to display        |
+| Options list       | `${dataTestId}.optionsList`      | When options are available        |
+
+### Child Component Test IDs
+
+UTSelect V1 uses several child components that have their own test ID hierarchies:
+
+- **UTBaseInputField**: Creates test IDs for input field and adornments (badge, prefix, suffix, clear action, chevron icon)
+- **UTBottomSheet**: Creates test IDs for modal, title, description, close button, and action buttons
+- **UTSearchField**: Creates test IDs for search input, search icon, and clear button
+- **UTCheckList**: Creates test IDs for checkboxes, labels, and select all functionality
+
+### Test ID Structure Details
+
+```
+${dataTestId}                        // Select trigger (Pressable)
+${dataTestId}.title                  // Title label
+${dataTestId}.input                  // Input field (+ UTBaseInputField hierarchy)
+${dataTestId}.input.left             // Badge (when multiple selection has values)
+${dataTestId}.input.right            // Clear action, chevron icon, custom action
+${dataTestId}.helpText               // Help text
+${dataTestId}.validation             // Validation message
+${dataTestId}.bottomSheet            // Bottom sheet (+ UTBottomSheet hierarchy)
+${dataTestId}.searchField            // Search field (+ UTSearchField hierarchy)
+${dataTestId}.noOptionsMessage       // No options message
+${dataTestId}.optionsList            // Options list (+ UTCheckList hierarchy)
+```
+
 ### Option Object
 
 The `options` prop is an array of objects, each representing an option:
@@ -42,6 +84,8 @@ The `options` prop is an array of objects, each representing an option:
 
 ## Usage
 
+### Basic Example
+
 ```jsx
 import React, { useState } from 'react';
 import { View, Text } from 'react-native';
@@ -75,3 +119,53 @@ const UTSelectExample = () => {
 
 export default UTSelectExample;
 ```
+
+### With Test IDs
+
+```jsx
+import React, { useState } from 'react';
+import { View, Text } from 'react-native';
+import UTSelect from './UTSelect';
+
+const options = [
+  { label: 'React', value: 'react' },
+  { label: 'JavaScript', value: 'javascript' },
+  { label: 'TypeScript', value: 'typescript' },
+  { label: 'Node.js', value: 'nodejs' }
+];
+
+const TestableSelectExample = () => {
+  const [selectedSkills, setSelectedSkills] = useState([]);
+
+  return (
+    <View style={{ padding: 20 }}>
+      <UTSelect
+        dataTestId="skillsSelect"
+        title="Select Skills"
+        helpText="Choose your programming skills"
+        multiple={true}
+        clearable={true}
+        noMatchesText="No skills found"
+        noOptionsText="No skills available"
+        onChange={setSelectedSkills}
+        options={options}
+        placeholder="Choose skills..."
+        searchPlaceholder="Search skills..."
+        selectAllLabel="Select All Skills"
+        showSelectAll={true}
+        value={selectedSkills}
+      />
+      <Text>Selected Skills: {selectedSkills.join(', ')}</Text>
+    </View>
+  );
+};
+
+// Generated test IDs include:
+// skillsSelect (select trigger)
+// skillsSelect.title
+// skillsSelect.input (+ UTBaseInputField hierarchy)
+// skillsSelect.helpText
+// skillsSelect.bottomSheet (when open + UTBottomSheet hierarchy)
+// skillsSelect.searchField (when open + UTSearchField hierarchy)
+// skillsSelect.optionsList (when open + UTCheckList hierarchy)
+```

package/lib/components/UTSelect/versions/V1/index.js

@@ -41,7 +41,8 @@ const UTSelect = ({
   value,
   onChangeSearchTerm,
   disableFilterOptions,
-  withAutoReset
+  withAutoReset,
+  dataTestId
 }) => {
   const [bottomSheetVisible, setBottomSheetVisible] = useState(false);
   const [searchTerm, setSearchTerm] = useState('');
@@ -146,11 +147,15 @@ const UTSelect = ({
     <Fragment>
       <View style={[styles.container, style]}>
         {title && (
-          <UTFieldLabel required={required} variant="body">
+          <UTFieldLabel
+            required={required}
+            variant="body"
+            dataTestId={dataTestId ? `${dataTestId}.title` : undefined}
+          >
             {title}
           </UTFieldLabel>
         )}
-        <Pressable disabled={disabled} onPress={handleOpenBottomSheet}>
+        <Pressable disabled={disabled} onPress={handleOpenBottomSheet} testID={dataTestId}>
           <UTBaseInputField
             alwaysShowPlaceholder={alwaysShowPlaceholder}
             disabled={disabled}
@@ -162,14 +167,24 @@ const UTSelect = ({
             rightAdornments={rightAdornments}
             value={displayValue}
             variant="button"
+            dataTestId={dataTestId ? `${dataTestId}.input` : undefined}
           />
         </Pressable>
         {helpText && (
-          <UTLabel colorTheme="gray" variant="small">
+          <UTLabel
+            colorTheme="gray"
+            variant="small"
+            dataTestId={dataTestId ? `${dataTestId}.helpText` : undefined}
+          >
             {helpText}
           </UTLabel>
         )}
-        {validationData && <UTValidation validationData={validationData} />}
+        {validationData && (
+          <UTValidation
+            validationData={validationData}
+            dataTestId={dataTestId ? `${dataTestId}.validation` : undefined}
+          />
+        )}
       </View>
       <UTBottomSheet
         title={title}
@@ -177,6 +192,7 @@ const UTSelect = ({
         visible={bottomSheetVisible}
         onClose={handleCloseBottomSheet}
         buttonText={closeButtonText}
+        dataTestId={dataTestId ? `${dataTestId}.bottomSheet` : undefined}
       >
         <View style={styles.bottomSheetBodyContainer}>
           <UTSearchField
@@ -184,9 +200,14 @@ const UTSelect = ({
             placeholder={searchPlaceholder}
             value={searchTerm}
             variant="gray"
+            dataTestId={dataTestId ? `${dataTestId}.searchField` : undefined}
           />
           {isEmpty(filteredOptions) ? (
-            <UTLabel colorTheme="gray" style={styles.noMatchesText}>
+            <UTLabel
+              colorTheme="gray"
+              style={styles.noMatchesText}
+              dataTestId={dataTestId ? `${dataTestId}.noOptionsMessage` : undefined}
+            >
               {!searchTerm ? noOptionsText : noMatchesText}
             </UTLabel>
           ) : (
@@ -200,6 +221,7 @@ const UTSelect = ({
                 value={value ? (multiple ? value : [value]) : []}
                 variant="button"
                 style={{ item: { title: styles.checklistTitles } }}
+                dataTestId={dataTestId ? `${dataTestId}.optionsList` : undefined}
               />
             </ScrollView>
           )}

package/lib/components/UTSelect/versions/V1/proptypes.js

@@ -20,6 +20,7 @@ export const propTypes = {
   alwaysShowPlaceholder: bool,
   clearable: bool,
   closeButtonText: string,
+  dataTestId: string,
   disabled: bool,
   error: string,
   helpText: string,

package/lib/components/UTSelectableCard/README.md

@@ -11,9 +11,11 @@
 | `additionalInfo` | `additionalInfoType` | `{}`       | Contains `description` and `title` to display supplementary information in the card.          |
 | `appearance`     | `string`             | `'white'`  | Defines the card's appearance. Supported values: `white`, `gray`.                             |
 | `checkIcon`      | `bool`               | `true`     | Whether to show a check icon when the card is selected.                                       |
+| `dataTestId`     | `string`             |            | Unique identifier for testing purposes. Creates hierarchical test IDs for child elements.     |
 | `description`    | `string`             |            | Secondary text shown below the title.                                                         |
 | `disabled`       | `bool`               | `false`    | Disables the card, preventing interactions and applying a disabled style.                     |
 | `Icon`           | `iconType`           |            | Icon configuration. Supports `url`, `name`, `shade`, `size`, or a custom `Component`.         |
+| `iconDataTestId` | `string`             |            | Override test ID for Icon.Component. If not provided, uses `${dataTestId}.icon`.              |
 | `numberOfLines`  | `number`             |            | Determines the amount of lines the text can span. If the text overflows it will be ellipsized |
 | `onPress`        | `func`               |            | Function triggered when the card is pressed.                                                  |
 | `selected`       | `bool`               | `false`    | Indicates whether the card is selected.                                                       |
@@ -82,6 +84,89 @@ export default Example;
 />
 ```
 
+## Testing
+
+The `UTSelectableCard` 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                              |
+| --------------------------- | -------------------------------------------- | ------------------------------------------- |
+| Card container (touchable)  | `provided.testId`                            | Always (when dataTestId is provided)        |
+| Icon                        | `provided.testId.icon`                       | When Icon prop is provided                  |
+| Title text                  | `provided.testId.titleText`                  | When titleText prop is provided             |
+| Description text            | `provided.testId.description`                | When description prop is provided           |
+| Tooltip                     | `provided.testId.tooltip`                    | When tooltip prop is provided               |
+| Tooltip content             | `provided.testId.tooltip.content`            | When tooltip prop is provided               |
+| Additional info title       | `provided.testId.additionalInfo.title`       | When additionalInfo.title is provided       |
+| Additional info description | `provided.testId.additionalInfo.description` | When additionalInfo.description is provided |
+| Check icon                  | `provided.testId.checkIcon`                  | When selected=true and checkIcon=true       |
+
+**Note:** If `Icon.Component` is used, the `iconDataTestId` prop can be used to override the default `${dataTestId}.icon` test ID. This prop only applies to custom icon components and has no effect when using `Icon.url` or `Icon.name`.
+
+**Children Test IDs:** The `children` prop renders React components directly without wrapping them. If child components need test IDs, it's the responsibility of the developer creating those components to add appropriate `dataTestId` props.
+
+### Example Usage
+
+```jsx
+// Basic test ID usage
+<UTSelectableCard
+  dataTestId="addressCard.1"
+  titleText="Home Address"
+  description="123 Main Street"
+  selected={true}
+  onPress={() => selectAddress(1)}
+/>
+
+// Creates the following test IDs:
+// - addressCard.1 (main container)
+// - addressCard.1.titleText (title text)
+// - addressCard.1.description (description text)
+// - addressCard.1.checkIcon (check icon when selected)
+
+// With all features enabled
+<UTSelectableCard
+  dataTestId="paymentCard.visa"
+  titleText="Visa ****1234"
+  description="Expires 12/25"
+  additionalInfo={{ title: "Primary", description: "Default card" }}
+  Icon={{ name: "IconCreditCard" }}
+  tooltip="Secure payment method"
+  selected={false}
+  onPress={() => selectCard('visa')}
+/>
+
+// Creates test IDs:
+// - paymentCard.visa
+// - paymentCard.visa.icon
+// - paymentCard.visa.titleText
+// - paymentCard.visa.description
+// - paymentCard.visa.tooltip
+// - paymentCard.visa.tooltip.content
+// - paymentCard.visa.additionalInfo.title
+// - paymentCard.visa.additionalInfo.description
+
+// Custom icon test ID override
+<UTSelectableCard
+  dataTestId="productCard.featured"
+  iconDataTestId="customProductIcon.primary"
+  titleText="Premium Product"
+  description="High-quality item"
+  Icon={{ Component: CustomIconComponent }}
+  selected={true}
+  onPress={() => selectProduct('featured')}
+/>
+
+// Creates test IDs:
+// - productCard.featured (main container)
+// - customProductIcon.primary (custom icon test ID)
+// - productCard.featured.titleText
+// - productCard.featured.description
+// - productCard.featured.checkIcon
+```
+
 ## Notes
 
 - Ensure to define custom styles through the `style` prop or the project theme.