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

package/README.md

@@ -181,13 +181,167 @@ class EntityModel {
 }
 ```
 
+**Vertical Scrolling for Large Datasets (v1.0.3+):**
+
+Control table height with automatic scrolling:
+
+```javascript
+<DataTable
+  columns={columns}
+  data={largeDataset}
+  maxHeight="size-6000" // Spectrum token (480px)
+  // or maxHeight="500px"  // CSS value
+  // or maxHeight="60vh"   // Viewport height
+  onGridLoad={async () => {
+    // Load large dataset
+  }}
+/>
+```
+
+**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
 - **Bulk Operations**: Mass action system for performing operations on multiple selected items
 - **Contextual Actions**: Per-row actions with customizable button layouts, links, or dropdown menus
 - **State Management**: Built-in loading states, empty state handling, and error boundary support
-- **Performance Optimized**: Virtual scrolling for large datasets and efficient re-rendering
+- **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`
@@ -398,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)
@@ -408,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`
 
@@ -528,12 +1080,47 @@ const DocumentUploader = () => {
 };
 ```
 
+**Programmatic Control with Refs (v1.0.3+):**
+
+Reset the component programmatically from parent components:
+
+```javascript
+import React, { useRef } from 'react';
+import { FileUpload, FileUploadHandle } from '@adobe-commerce/aio-experience-kit';
+
+const MyForm = () => {
+  const fileUploadRef = useRef<FileUploadHandle>(null);
+  
+  const handleReset = () => {
+    fileUploadRef.current?.reset(); // Clear all files
+  };
+  
+  const handleGetFiles = () => {
+    const files = fileUploadRef.current?.getFiles(); // Get current files
+    console.log('Current files:', files);
+  };
+  
+  return (
+    <>
+      <FileUpload
+        ref={fileUploadRef}
+        label="Upload Files"
+        onSelect={(files) => console.log('Selected:', files)}
+      />
+      <Button onPress={handleReset}>Reset</Button>
+      <Button onPress={handleGetFiles}>Get Files</Button>
+    </>
+  );
+};
+```
+
 **Features:**
 - **File Selection**: Click to browse files with support for single or multiple file selection
 - **Automatic Content Reading**: Automatically reads file content as text or base64 based on file type
 - **File Type Validation**: Built-in validation for accepted MIME types and file extensions
 - **Built-in Display**: Automatically displays selected files with name, size, and type information
-- **Clear Functionality**: Built-in "Clear Files" link to remove selected files
+- **Clear Functionality**: Built-in "Clear Files" link to remove selected files and programmatic reset via ref
+- **Imperative Handle**: Access reset() and getFiles() methods via React refs for parent control
 - **Loading States**: Shows processing indicator while reading file contents
 - **Error Handling**: Comprehensive error messaging for file reading failures
 - **Accessibility**: Full keyboard navigation, screen reader support, and ARIA labels
@@ -631,6 +1218,7 @@ import type {
   DataFormProps,
   ConfirmationDialogProps,
   FileUploadProps,
+  FileUploadHandle,
   FieldType,
   AdminUiSdkInterface,
   AdminUiSdkCredentials