@adobe-commerce/aio-experience-kit 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -5,6 +5,97 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.4] - 2025-01-01
+
+### ✨ Added
+
+- **[DataTable - SearchBar](./src/components/DataTable/SearchBar/index.tsx)** - Comprehensive search functionality with filtering capabilities (#33)
+  - Added configurable search bar component integrated into DataTable header
+  - **Two Search Modes**:
+    - Button mode: Search triggered only on button click or Enter key press
+    - Type mode: Real-time search-as-you-type with configurable debouncing
+  - **Search Configuration** via `DataTableSearchConfig` interface with 14 properties:
+    - `enabled` - Enable/disable search bar
+    - `placeholder` - Customizable search input placeholder
+    - `searchButtonLabel` - Button label text (displayed with icon)
+    - `searchOnType` - Toggle between button and type modes
+    - `debounceMs` - Configurable debounce delay (default: 300ms)
+    - `minCharacters` - Minimum character validation
+    - `maxLength` - Maximum input length constraint
+    - `searchableColumns` - Column-specific filtering
+    - `showClearButton` - Clear button visibility
+    - `isSearching` - Loading state with progress indicator
+    - `caseSensitive` - Case sensitivity control
+    - `showResultsCount` - Results count display
+    - `ariaLabel` - Accessibility label customization
+  - **Keyboard Shortcuts**:
+    - Enter: Trigger search (bypasses debounce in type mode)
+    - Escape: Clear search (when clear button enabled)
+  - **Layout**: Right-aligned in header with `justifyContent="space-between"`, maintaining ActionsBuilder and ProgressCircle left alignment
+  - **Accessibility**: Full ARIA label support, keyboard navigation, screen reader compatible, high contrast mode support
+  - **Debouncing**: Smart debounce implementation with timer cleanup on unmount and clear operations
+  - **Use Cases**: Product catalog search, customer lookup, order management, inventory filtering, log/audit trail search, multi-column search
+  - **API Design**: Uncontrolled component with single `onSearch` callback for both button and type modes
+  - **Test Coverage**: 32 unit tests + 12 integration tests, 98.03% statement coverage, 100% function coverage
+  - **Documentation**: Comprehensive README with 5 usage examples, configuration table, keyboard shortcuts, and accessibility features
+
+- **[DataForm - FieldDependency](./src/components/DataForm/FormBuilder/types.ts)** - Conditional field visibility based on other field values (#32)
+  - Added `FieldDependency` interface with field reference and condition configuration
+  - Added `DependencyCondition` type union with 9 condition types:
+    - `equals` - Field value equals specified value
+    - `notEquals` - Field value does not equal specified value
+    - `in` - Field value exists in array of values
+    - `notIn` - Field value not in array of values
+    - `greaterThan` - Numeric field value greater than threshold
+    - `lessThan` - Numeric field value less than threshold
+    - `truthy` - Field value is truthy (for toggle/boolean fields)
+    - `falsy` - Field value is falsy
+    - `custom` - Custom validator function for complex conditions
+  - **Features**:
+    - Dynamic show/hide fields based on dependency conditions
+    - Automatic value clearing for hidden fields (optional via `clearValueOnHide`)
+    - Excluded hidden fields from form validation and submission
+    - Performance optimized with React memoization
+    - Multiple fields can depend on same source field
+  - **Use Cases**: Progressive disclosure, conditional required fields, multi-step forms, dynamic field groups
+  - **Test Coverage**: 18 comprehensive unit tests covering all condition types and edge cases
+  - **Code Coverage**: 98.85% for FormBuilder component
+  - **Documentation**: README updated with examples and configuration options
+
+- **[DataForm - ButtonContainer](./src/components/DataForm/ButtonContainer/index.tsx)** - Configurable form buttons with custom layout control (#34)
+  - Added `ButtonContainer` component for flexible form action button customization
+  - Added `FormButtonConfig` interface with comprehensive button configuration
+  - **Customizable Submit Button**:
+    - Custom label, icon, visibility, and ARIA labels
+    - Default label: "Save" with SaveFloppy icon
+  - **Customizable Back Button**:
+    - Custom label, icon, visibility, and ARIA labels
+    - Default label: "Back" with Back icon
+  - **Secondary Buttons**:
+    - Add multiple custom action buttons
+    - Support async handlers with independent loading states
+    - Button variants: primary, secondary, negative
+    - Custom labels, icons, and ARIA labels
+  - **Layout Configuration**:
+    - Button positioning: before or after form content
+    - Button alignment: start, center, end
+    - Button gap: small (8px), medium (16px), large (24px)
+  - **Features**:
+    - Independent loading states for each secondary button
+    - Automatic disabled state during form submission
+    - Full accessibility with ARIA labels and keyboard navigation
+    - 100% backward compatible (defaults match original behavior)
+  - **Test Coverage**: 37 comprehensive unit tests covering all customization scenarios
+  - **Documentation**: README updated with 10 usage examples for different configurations
+
+### 🐛 Fixed
+
+- **[DataForm - FieldDependency Test](./test/components/DataForm/FieldDependency.test.tsx)** - TypeScript type errors
+  - Added `FormBuilderComponents` import for proper type handling
+  - Used type assertion for intentional invalid test case testing
+  - Removed unused `@ts-expect-error` directive
+  - All 583 tests passing with proper TypeScript compilation
+
 ## [1.0.3] - 2024-11-19
 
 ### ✨ Added

package/README.md

@@ -198,6 +198,141 @@ Control table height with automatic scrolling:
 />
 ```
 
+**Search and Filtering Capabilities:**
+
+Add built-in search functionality to enable users to quickly find and filter records within your DataTable. The search bar is configurable and supports both button-triggered and search-as-you-type modes.
+
+*Example 1: Basic Search (Button Click Mode)*
+
+```javascript
+<DataTable
+  columns={columns}
+  data={data}
+  searchConfig={{
+    enabled: true,
+    placeholder: "Search products...",
+    searchOnType: false, // Only search when button clicked or Enter pressed
+  }}
+  onSearch={async (searchText) => {
+    // Triggered only on button click or Enter key
+    await fetchFilteredData(searchText);
+  }}
+/>
+```
+
+*Example 2: Search-as-you-type with Debounce (Recommended for Client-Side Filtering)*
+
+```javascript
+const [allData, setAllData] = useState(products);
+const [filteredData, setFilteredData] = useState(products);
+
+<DataTable
+  columns={columns}
+  data={filteredData} // Show filtered results
+  searchConfig={{
+    enabled: true,
+    searchOnType: true, // Search while typing
+    debounceMs: 300, // Wait 300ms after user stops typing
+    showClearButton: true,
+    minCharacters: 2, // Only search if 2+ characters entered
+  }}
+  onSearch={async (searchText) => {
+    if (!searchText) {
+      setFilteredData(allData); // Show all if search is empty
+      return;
+    }
+    
+    // Client-side filtering
+    const filtered = allData.filter(item =>
+      Object.values(item).some(val =>
+        String(val).toLowerCase().includes(searchText.toLowerCase())
+      )
+    );
+    setFilteredData(filtered);
+  }}
+/>
+```
+
+*Example 3: Server-Side Search with Loading State*
+
+```javascript
+const [isSearching, setSearching] = useState(false);
+
+<DataTable
+  columns={columns}
+  data={data}
+  searchConfig={{
+    enabled: true,
+    isSearching: isSearching, // Shows spinner in search button
+    placeholder: "Search across 10,000+ records...",
+    searchOnType: true,
+    debounceMs: 800, // Longer debounce for server calls
+  }}
+  onSearch={async (searchText) => {
+    setSearching(true);
+    try {
+      const results = await apiSearchCall(searchText);
+      setData(results);
+    } finally {
+      setSearching(false);
+    }
+  }}
+/>
+```
+
+*Example 4: Column-Specific Search*
+
+```javascript
+<DataTable
+  columns={columns}
+  data={data}
+  searchConfig={{
+    enabled: true,
+    searchableColumns: ['name', 'sku', 'email'], // Only search these columns
+    caseSensitive: false,
+  }}
+  onSearch={async (searchText, searchColumns) => {
+    // searchColumns will be ['name', 'sku', 'email']
+    await searchInColumns(searchText, searchColumns);
+  }}
+/>
+```
+
+**Search Configuration Options:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable/disable search bar |
+| `placeholder` | string | `"Search..."` | Placeholder text for search input |
+| `searchButtonLabel` | string | `"Search"` | Label text displayed on search button (shown with icon) |
+| `clearButtonLabel` | string | `"Clear search"` | Accessible label for clear button |
+| `showClearButton` | boolean | `true` | Show clear button when text exists |
+| `searchOnType` | boolean | `false` | Search while typing vs. button click only |
+| `debounceMs` | number | `300` | Debounce time for search-as-you-type (ms) |
+| `caseSensitive` | boolean | `false` | Case-sensitive search |
+| `searchableColumns` | string[] | `[]` | Specific columns to search (empty = all columns) |
+| `minCharacters` | number | `1` | Minimum characters before search triggers |
+| `maxLength` | number | `100` | Maximum length of search input |
+| `showResultsCount` | boolean | `false` | Show count of filtered results |
+| `isSearching` | boolean | `false` | Show loading state in search button |
+| `ariaLabel` | string | `"Search table"` | ARIA label for search input |
+
+**Search Behavior Modes:**
+
+- **Button Mode** (`searchOnType: false`): Search only triggers when the search button is clicked or Enter key is pressed. Ideal for server-side searches with expensive operations.
+  
+- **Type Mode** (`searchOnType: true`): Search triggers as the user types (with debouncing). Perfect for client-side filtering or real-time search experiences.
+
+**Keyboard Shortcuts:**
+- **Enter**: Triggers search in both modes (bypasses debounce in type mode)
+- **Escape**: Clears search when `showClearButton` is enabled
+
+**Accessibility Features:**
+- Full keyboard navigation support
+- Customizable ARIA labels for screen readers
+- Loading state announcements
+- High contrast mode support
+
 **Features:**
 - **Advanced Data Management**: Sortable columns with intelligent data type handling and custom sort functions
 - **Flexible Selection**: Support for single-row selection or multi-row selection with visual feedback
@@ -206,6 +341,7 @@ Control table height with automatic scrolling:
 - **State Management**: Built-in loading states, empty state handling, and error boundary support
 - **Performance Optimized**: Virtual scrolling for large datasets with efficient re-rendering
 - **Scrollable Tables**: Optional maxHeight prop for vertical scrolling with large datasets (v1.0.3+)
+- **Search & Filter**: Built-in search bar with button and type modes, column-specific filtering
 - **User Experience**: Intuitive interactions with hover states, keyboard navigation, and clear visual hierarchy
 
 #### `DataForm`
@@ -416,9 +552,202 @@ The DataForm component supports various field types for different input scenario
 }
 ```
 
+##### Dependent Field Visibility
+
+The DataForm component supports conditional field visibility based on the values of other fields. This allows you to create dynamic forms that show or hide fields based on user selections.
+
+**Basic Example:**
+
+```javascript
+{
+  groups: [
+    {
+      code: 'settings',
+      label: 'Settings',
+      fields: [
+        {
+          label: 'Enable Feature',
+          code: 'feature_enabled',
+          db_field: 'feature_enabled',
+          type: FieldType.TOGGLE,
+          required: false
+        },
+        {
+          label: 'Feature Configuration',
+          code: 'feature_config',
+          db_field: 'feature_config',
+          type: FieldType.TEXT,
+          required: false,
+          // This field only shows when feature_enabled is truthy
+          dependsOn: {
+            field: 'feature_enabled',
+            condition: { type: 'truthy' }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Dependency Condition Types:**
+
+```javascript
+// Equals - Show field when value matches exactly
+dependsOn: {
+  field: 'status',
+  condition: { type: 'equals', value: 'active' }
+}
+
+// Not Equals - Show field when value doesn't match
+dependsOn: {
+  field: 'status',
+  condition: { type: 'notEquals', value: 'disabled' }
+}
+
+// In - Show field when value is in array
+dependsOn: {
+  field: 'status',
+  condition: { type: 'in', values: ['pending', 'processing'] }
+}
+
+// Not In - Show field when value is not in array
+dependsOn: {
+  field: 'status',
+  condition: { type: 'notIn', values: ['cancelled', 'completed'] }
+}
+
+// Greater Than - Show field when numeric value is greater
+dependsOn: {
+  field: 'quantity',
+  condition: { type: 'greaterThan', value: 10 }
+}
+
+// Less Than - Show field when numeric value is less
+dependsOn: {
+  field: 'stock_level',
+  condition: { type: 'lessThan', value: 5 }
+}
+
+// Truthy - Show field when value is truthy (handles '0' and 'false' as falsy)
+dependsOn: {
+  field: 'enable_feature',
+  condition: { type: 'truthy' }
+}
+
+// Falsy - Show field when value is falsy
+dependsOn: {
+  field: 'enable_feature',
+  condition: { type: 'falsy' }
+}
+
+// Custom - Show field based on custom validation function
+dependsOn: {
+  field: 'username',
+  condition: {
+    type: 'custom',
+    validator: (value, allFormValues) => {
+      return value && value.length > 3;
+    }
+  }
+}
+```
+
+**Advanced Example - Multi-Step Configuration:**
+
+```javascript
+{
+  groups: [
+    {
+      code: 'shipping',
+      label: 'Shipping Configuration',
+      fields: [
+        {
+          label: 'Shipping Method',
+          code: 'shipping_method',
+          db_field: 'shipping_method',
+          type: FieldType.SELECT,
+          required: true,
+          options: [
+            { value: 'standard', label: 'Standard Shipping' },
+            { value: 'express', label: 'Express Shipping' },
+            { value: 'pickup', label: 'Store Pickup' }
+          ]
+        },
+        {
+          label: 'Carrier',
+          code: 'carrier',
+          db_field: 'carrier',
+          type: FieldType.SELECT,
+          required: true,
+          options: [
+            { value: 'ups', label: 'UPS' },
+            { value: 'fedex', label: 'FedEx' },
+            { value: 'usps', label: 'USPS' }
+          ],
+          // Only show carrier selection for standard and express shipping
+          dependsOn: {
+            field: 'shipping_method',
+            condition: { type: 'in', values: ['standard', 'express'] }
+          }
+        },
+        {
+          label: 'Tracking Number',
+          code: 'tracking_number',
+          db_field: 'tracking_number',
+          type: FieldType.TEXT,
+          required: false,
+          // Only show tracking for shipped methods
+          dependsOn: {
+            field: 'shipping_method',
+            condition: { type: 'notEquals', value: 'pickup' }
+          }
+        },
+        {
+          label: 'Store Location',
+          code: 'store_location',
+          db_field: 'store_location',
+          type: FieldType.SELECT,
+          required: true,
+          options: [
+            { value: 'store1', label: 'Main Street Store' },
+            { value: 'store2', label: 'Downtown Store' }
+          ],
+          // Only show store location for pickup
+          dependsOn: {
+            field: 'shipping_method',
+            condition: { type: 'equals', value: 'pickup' }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Dependency Configuration:**
+
+```typescript
+interface FieldDependency {
+  field: string;                    // The code of the field this depends on
+  condition: DependencyCondition;   // The condition to evaluate
+  clearValueOnHide?: boolean;       // Whether to clear field value when hidden (default: false)
+}
+```
+
+**Key Features:**
+- **Dynamic Visibility**: Fields automatically show/hide based on dependency conditions
+- **Multiple Conditions**: Support for equals, notEquals, in, notIn, greaterThan, lessThan, truthy, falsy, and custom validators
+- **Validation Integration**: Hidden fields are excluded from form validation
+- **Value Management**: Optional automatic clearing of hidden field values
+- **Performance Optimized**: Uses React memoization to prevent unnecessary re-renders
+- **Chain Dependencies**: Fields can depend on other dependent fields
+- **Form Submission**: Hidden field values are automatically excluded from submission
+
 **Features:**
 - **Dynamic Form Generation**: Create complex forms from simple configuration objects without manual field creation
 - **Rich Field Types**: Support for text, email, password, number, select, multiselect, toggle, and specialized input types
+- **Conditional Field Visibility**: Show/hide fields dynamically based on other field values with multiple condition types
 - **Multi-Selection Support**: MULTISELECT field type with React Spectrum CheckboxGroup for selecting multiple options with scrollable overflow and accessibility support
 - **Toggle Controls**: TOGGLE field type using React Spectrum Switch component with '1'/'0' value handling and automatic default value initialization
 - **Environment Variable Support**: Built-in support for environment variable checkboxes on compatible field types (TEXT, SELECT, MULTISELECT, TOGGLE)
@@ -426,6 +755,211 @@ The DataForm component supports various field types for different input scenario
 - **Workflow Integration**: Loading states, processing indicators, and navigation controls for multi-step workflows
 - **Organized Layout**: Logical field grouping with collapsible sections and intuitive information hierarchy
 - **Developer Friendly**: Event-driven architecture with lifecycle hooks for custom business logic integration
+- **Configurable Buttons**: Full control over form action buttons with custom labels, icons, visibility, positioning, and alignment
+
+##### Button Configuration
+
+The DataForm component provides extensive button customization through the `buttonConfig` prop:
+
+**Basic Usage:**
+
+```javascript
+<DataForm
+  components={formFields}
+  editItem={editItem}
+  onFormLoad={onFormLoad}
+  onFormSubmit={onFormSubmit}
+  onBackPress={onBackPress}
+  buttonConfig={{
+    submitButton: { label: 'Create Product' },
+    backButton: { label: 'Cancel' },
+  }}
+/>
+```
+
+**Button Configuration Options:**
+
+```typescript
+interface FormButtonConfig {
+  submitButton?: {
+    label?: string;           // Button text (default: "Save")
+    icon?: ReactElement;      // Custom icon (default: SaveFloppy)
+    isHidden?: boolean;       // Hide button (default: false)
+    ariaLabel?: string;       // Custom ARIA label
+  };
+  
+  backButton?: {
+    label?: string;           // Button text (default: "Back")
+    icon?: ReactElement;      // Custom icon (default: Back)
+    isHidden?: boolean;       // Hide button (default: false)
+    ariaLabel?: string;       // Custom ARIA label
+  };
+  
+  secondaryButtons?: Array<{
+    key: string;              // Unique identifier
+    label: string;            // Button text
+    icon?: ReactElement;      // Optional icon
+    onPress: () => Promise<void>; // Click handler
+    variant?: 'primary' | 'secondary' | 'negative'; // Style variant
+    isDisabled?: boolean;     // Disable state
+    type?: 'button' | 'submit'; // Button type (default: 'button')
+    ariaLabel?: string;       // Custom ARIA label
+  }>;
+  
+  position?: 'before' | 'after';  // Button position relative to form (default: 'after')
+  alignment?: 'start' | 'center' | 'end'; // Horizontal alignment (default: 'start')
+  gap?: 'small' | 'medium' | 'large'; // Spacing between buttons (default: 'small')
+}
+```
+
+**Common Use Cases:**
+
+```javascript
+// Example 1: Create vs Edit Forms
+<DataForm
+  buttonConfig={{
+    submitButton: { 
+      label: isEditMode ? 'Update Product' : 'Create Product' 
+    },
+  }}
+/>
+
+// Example 2: Modal Forms (hide back button)
+<DataForm
+  buttonConfig={{
+    submitButton: { label: 'Save Changes' },
+    backButton: { isHidden: true },
+  }}
+/>
+
+// Example 3: Wizard Forms with Navigation
+<DataForm
+  buttonConfig={{
+    submitButton: { label: 'Next Step' },
+    backButton: { label: 'Previous Step' },
+  }}
+/>
+
+// Example 4: Draft Workflow with Secondary Action
+<DataForm
+  buttonConfig={{
+    submitButton: { label: 'Save Draft' },
+    secondaryButtons: [
+      {
+        key: 'publish',
+        label: 'Publish',
+        variant: 'primary',
+        onPress: async () => {
+          await handlePublish();
+        },
+      },
+    ],
+  }}
+/>
+
+// Example 5: Edit Form with Delete Action
+<DataForm
+  buttonConfig={{
+    submitButton: { label: 'Update' },
+    secondaryButtons: [
+      {
+        key: 'delete',
+        label: 'Delete',
+        variant: 'negative',
+        onPress: async () => {
+          const confirmed = await showConfirmDialog();
+          if (confirmed) {
+            await handleDelete();
+            navigate('/products');
+          }
+        },
+      },
+    ],
+  }}
+/>
+
+// Example 6: Top-Aligned Buttons for Long Forms
+<DataForm
+  buttonConfig={{
+    submitButton: { label: 'Save' },
+    position: 'before',
+    alignment: 'end',
+  }}
+/>
+
+// Example 7: Right-Aligned Buttons (Dialog Pattern)
+<DataForm
+  buttonConfig={{
+    submitButton: { label: 'Confirm' },
+    backButton: { label: 'Cancel' },
+    alignment: 'end',
+  }}
+/>
+
+// Example 8: Multi-Action Workflow
+<DataForm
+  buttonConfig={{
+    submitButton: { label: 'Save' },
+    secondaryButtons: [
+      {
+        key: 'save-continue',
+        label: 'Save & Continue',
+        onPress: async () => {
+          await handleSave();
+          navigateToNext();
+        },
+      },
+      {
+        key: 'save-new',
+        label: 'Save & Add New',
+        onPress: async () => {
+          await handleSave();
+          resetForm();
+        },
+      },
+    ],
+  }}
+/>
+
+// Example 9: Custom Icons and ARIA Labels
+import SaveFloppy from '@spectrum-icons/workflow/SaveFloppy';
+import CheckmarkCircle from '@spectrum-icons/workflow/CheckmarkCircle';
+
+<DataForm
+  buttonConfig={{
+    submitButton: {
+      label: 'Approve',
+      icon: <CheckmarkCircle />,
+      ariaLabel: 'Approve and save changes',
+    },
+  }}
+/>
+
+// Example 10: Centered Buttons with Custom Gap
+<DataForm
+  buttonConfig={{
+    submitButton: { label: 'Submit' },
+    backButton: { label: 'Cancel' },
+    alignment: 'center',
+    gap: 'large',
+  }}
+/>
+```
+
+**Button Order and States:**
+
+- **Button Order**: ProgressCircle → Submit → Back → Secondary buttons (in order)
+- **Disabled States**: All buttons are automatically disabled during form submission or when `isProcessing` is true
+- **Loading States**: ProgressCircle shows automatically during submission, secondary buttons can show individual loading states
+- **Accessibility**: All buttons have proper ARIA labels and keyboard navigation support
+
+**Migration Notes:**
+
+For existing implementations without `buttonConfig`, the default behavior is preserved:
+- Submit button labeled "Save" with SaveFloppy icon
+- Back button labeled "Back" with Back icon
+- Buttons positioned after the form with start (left) alignment
+- No breaking changes to existing code
 
 #### `ConfirmationDialog`