@adobe-commerce/aio-experience-kit 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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.1] - 2025-10-14
+
+### ✨ Added
+
+- **[ShippingCarrierForm](./src/components/ShippingCarrierForm/index.tsx)** - New specialized form component for shipping carrier configuration
+  - Pre-configured fields for common shipping carrier attributes (code, title, active status)
+  - Multi-select support for stores and countries with scrollable option lists
+  - Toggle fields for tracking and shipping labels availability
+  - Built on top of DataForm with consistent validation and user experience
+  - Async-friendly API with loading states and lifecycle callbacks
+  - Type-safe props with comprehensive TypeScript interfaces
+
+### 🐛 Fixed
+
+- **FormBuilder**: Resolved race condition when handling multiple toggle fields simultaneously
+- **ESLint**: Resolved React hooks linting warnings across components
+
+### 🔧 Changed
+
+- **[DataForm](./src/components/DataForm/index.tsx)** - Enhanced with new field types for richer form capabilities
+  - Added MULTISELECT field type with React Spectrum CheckboxGroup implementation
+  - Added TOGGLE field type with React Spectrum Switch component
+  - Array value handling for MULTISELECT with proper storage and retrieval
+  - Automatic '1'/'0' value handling for TOGGLE fields with backend compatibility
+  - Scrollable containers for multi-select options with automatic overflow handling
+  - Enhanced styling with proper spacing and visual hierarchy for new field types
+  - Full accessibility support with keyboard navigation for all field types
+  - Environment variable mode support for TOGGLE fields
+
+- **[AdminUiSdk](./src/utils/AdminUiSdk/index.ts)** - Refactored to use registration-based approach for improved flexibility
+- **ESLint**: Migrated to ESLint 9 flat config format for modern JavaScript tooling
+- **FieldBuilder**: Improved import formatting and code spacing for better readability
+
+### 📚 Documentation
+
+- Added comprehensive documentation for MULTISELECT and TOGGLE field types
+- Updated README with ShippingCarrierForm component usage examples
+- Enhanced field type documentation with code examples and use cases
+
+---
+
 ## [1.0.0] - 2024-12-19
 
 ### 🎉 Initial Release

package/README.md

@@ -287,6 +287,46 @@ class EntityModel {
                   label: 'Disabled'
                 }
               ]
+            },
+            {
+              label: 'Categories',
+              code: 'categories',
+              db_field: 'categories',
+              type: FieldType.MULTISELECT,
+              required: false,
+              options: [
+                {
+                  value: 'electronics',
+                  label: 'Electronics'
+                },
+                {
+                  value: 'clothing',
+                  label: 'Clothing'
+                },
+                {
+                  value: 'books',
+                  label: 'Books'
+                },
+                {
+                  value: 'home',
+                  label: 'Home & Garden'
+                }
+              ]
+            },
+            {
+              label: 'Featured Product',
+              code: 'featured',
+              db_field: 'featured',
+              type: FieldType.TOGGLE,
+              required: false
+            },
+            {
+              label: 'Notifications',
+              code: 'notifications',
+              db_field: 'notifications',
+              type: FieldType.TOGGLE,
+              required: false,
+              use_env_var: true
             }
           ]
         }
@@ -296,9 +336,74 @@ class EntityModel {
 }
 ```
 
+##### Field Types
+
+The DataForm component supports various field types for different input scenarios:
+
+**Basic Input Fields:**
+- `FieldType.TEXT` - Standard text input
+- `FieldType.EMAIL` - Email input with validation
+- `FieldType.PASSWORD` - Password input with masking
+- `FieldType.NUMBER` - Numeric input with validation
+- `FieldType.URL` - URL input with validation
+- `FieldType.TEL` - Telephone number input
+- `FieldType.SEARCH` - Search input with appropriate styling
+
+**Selection Fields:**
+- `FieldType.SELECT` - Single selection dropdown with options
+- `FieldType.MULTISELECT` - Multiple selection with checkboxes in a scrollable container
+- `FieldType.TOGGLE` - Boolean toggle switch with '1'/'0' values
+
+**Display Fields:**
+- `FieldType.LABEL` - Read-only display field for showing values
+
+**Field Configuration Examples:**
+
+```javascript
+// MULTISELECT field with scrollable options
+{
+  label: 'Product Categories',
+  code: 'categories',
+  db_field: 'categories',
+  type: FieldType.MULTISELECT,
+  required: false,
+  options: [
+    { value: 'electronics', label: 'Electronics' },
+    { value: 'clothing', label: 'Clothing' },
+    { value: 'books', label: 'Books' },
+    { value: 'home', label: 'Home & Garden' },
+    // ... more options (automatically scrollable when many)
+  ]
+}
+
+// TOGGLE field with automatic default value
+{
+  label: 'Enable Feature',
+  code: 'feature_enabled',
+  db_field: 'feature_enabled',
+  type: FieldType.TOGGLE,
+  required: false
+  // Automatically defaults to '0' if no value provided
+  // Returns '1' when enabled, '0' when disabled
+}
+
+// Field with environment variable support
+{
+  label: 'API Endpoint',
+  code: 'api_endpoint',
+  db_field: 'api_endpoint',
+  type: FieldType.TEXT,
+  required: true,
+  use_env_var: true  // Adds checkbox to use as environment variable
+}
+```
+
 **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, and specialized input types
+- **Rich Field Types**: Support for text, email, password, number, select, multiselect, toggle, and specialized input 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)
 - **Intelligent Validation**: Built-in validation with custom rules, real-time feedback, and error messaging
 - **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
@@ -386,42 +491,197 @@ class EntityModel {
 - **Accessibility Excellence**: Full screen reader support, proper ARIA labels, and focus trap implementation
 - **Design Consistency**: Follows Adobe Spectrum design patterns for familiar user interactions
 
+#### `ShippingCarrierForm`
+
+A specialized form component pre-configured for shipping carrier management. Built on top of DataForm, it provides a ready-to-use form with all the necessary fields for shipping carrier configuration.
+
+```javascript
+import React, { useState } from 'react';
+import { ShippingCarrierForm, useRouteParams } from '@adobe-commerce/aio-experience-kit';
+import { ToastQueue } from '@react-spectrum/toast';
+
+const CarrierForm = ({ actionCallHeaders, id = undefined }) => {
+  const { getNavigate } = useRouteParams();
+  const navigate = getNavigate();
+  const [isLoading, setLoading] = useState(false);
+  const [carrierData, setCarrierData] = useState({});
+
+  const carrierModel = new CarrierModel(actionCallHeaders);
+
+  const storeOptions = [
+    { value: '1', label: 'Main Store' },
+    { value: '2', label: 'EU Store' },
+    { value: '3', label: 'Asia Store' }
+  ];
+
+  const countryOptions = [
+    { value: 'US', label: 'United States' },
+    { value: 'CA', label: 'Canada' },
+    { value: 'GB', label: 'United Kingdom' },
+    { value: 'DE', label: 'Germany' },
+    { value: 'FR', label: 'France' }
+  ];
+
+  return (
+    <ShippingCarrierForm
+      countryOptions={countryOptions}
+      storeOptions={storeOptions}
+      defaults={carrierData}
+      isLoading={isLoading}
+      onFormSubmit={async (values) => {
+        try {
+          await carrierModel.save(values);
+          ToastQueue.positive('Carrier saved successfully', { timeout: 5000 });
+        } catch (e) {
+          ToastQueue.negative(e.message, { timeout: 5000 });
+        }
+      }}
+      onPostFormSubmit={async () => {
+        navigate('/carrier/grid');
+      }}
+      onBackPress={() => {
+        navigate('/carrier/grid');
+      }}
+    />
+  );
+};
+
+// Carrier Model
+class CarrierModel {
+  constructor(actionCallHeaders) {
+    this.actionCallHeaders = actionCallHeaders;
+  }
+
+  async save(formValues) {
+    // Save carrier using API
+    return {};
+  }
+}
+```
+
+**Pre-configured Fields:**
+
+The component includes the following built-in fields:
+- **Active** (TOGGLE) - Enable/disable the shipping carrier
+- **Code** (TEXT) - Unique identifier for the carrier
+- **Title** (TEXT) - Display name of the carrier
+- **Stores** (MULTISELECT) - Select which stores the carrier is available for
+- **Countries** (MULTISELECT) - Select which countries the carrier ships to
+- **Sort Order** (NUMBER) - Display order in the shipping methods list
+- **Is Tracking Available?** (TOGGLE) - Whether tracking is supported
+- **Is Shipping Labels Available?** (TOGGLE) - Whether shipping label generation is supported
+
+**Features:**
+- **Ready-to-Use**: Pre-configured form eliminates boilerplate code for common shipping carrier scenarios
+- **Flexible Options**: Pass custom store and country options based on your store configuration
+- **Data Persistence**: Support for loading existing carrier data via `defaults` prop
+- **Loading States**: Built-in loading indicator while fetching carrier data
+- **Type Safety**: Full TypeScript support with `ShippingCarrierFormProps` and `SelectOption` types
+- **Workflow Integration**: Lifecycle callbacks for form submission, navigation, and error handling
+- **Consistent UX**: Leverages DataForm for validation, error messaging, and user experience
+
 ### 🔧 Utils
 
 Utility functions and classes that simplify common tasks in Adobe Commerce extension development.
 
 #### `AdminUiSdk`
 
-A comprehensive utility class for registering Adobe Admin UI extensions with the Adobe UIX registry, managing menu items and page configurations.
+A comprehensive utility class for registering Adobe Admin UI extensions with the Adobe UIX registry, managing menu items, page configurations, and credentials.
+
+##### Building Registration Configuration
+
+Create menu structure and page configuration for your extension:
 
 ```typescript
 import { AdminUiSdk } from '@adobe-commerce/aio-experience-kit';
 
-// Initialize the SDK
-const extensionId = 'my_admin_extension';
-const sdk = new AdminUiSdk(extensionId);
+// Initialize the SDK with your extension ID
+const sdk = new AdminUiSdk('my_admin_extension');
+
+// Add a menu section (appears as a parent menu)
+sdk.addMenuSection('products', 'Product Management', 100);
 
-// Add menu items
-sdk.addMenu({
-  id: `${extensionId}::products`,
-  title: 'Product Manager',
-  parent: 'Magento_Catalog::catalog',
-  sortOrder: 10
-});
+// Add menu items under the section
+sdk.addMenuItem('product_list', 'Product List', 1, 'products');
 
-// Set page title
+// Set the page title for your extension
 sdk.addPage('Product Management Dashboard');
 
-// Register with Adobe UIX
-await sdk.register();
+// Get the complete registration configuration
+const registration = sdk.getRegistration();
+console.log(registration);
+// Output: {
+//   registration: {
+//     menuItems: [
+//       {
+//         id: 'my_admin_extension::products',
+//         title: 'Product Management',
+//         sortOrder: 100,
+//         isSection: true
+//       },
+//       {
+//         id: 'my_admin_extension::product_list',
+//         title: 'Product List',
+//         parent: 'my_admin_extension::products',
+//         sortOrder: 1
+//       },
+//     page: {
+//       title: 'Product Management Dashboard'
+//     }
+//   }
+// }
+```
+
+##### Registering Your Extension
+
+Register your extension with Adobe UIX platform:
+
+```typescript
+import { AdminUiSdk } from '@adobe-commerce/aio-experience-kit';
+
+try {
+  const sdk = new AdminUiSdk('my_admin_extension');
+  // Register the extension with Adobe UIX
+  await sdk.registerExtension();
+} catch (error) {
+  console.error('Registration failed:', error.message);
+}
+```
+
+##### Getting Adobe IMS Credentials
+
+Retrieve authentication credentials from the Adobe shared context:
+
+```typescript
+import { AdminUiSdk } from '@adobe-commerce/aio-experience-kit';
+
+try {
+  const sdk = new AdminUiSdk('my_admin_extension');
+
+  const credentials = await sdk.getCredentials();
+  
+  if (credentials.imsToken && credentials.imsOrgId) {
+    // Use credentials for API calls
+    const apiHeaders = {
+      'Authorization': `Bearer ${credentials.imsToken}`,
+      'x-gw-ims-org-id': credentials.imsOrgId
+    };
+    
+    // Make authenticated API requests
+  } else {
+    console.log('Credentials not available');
+  }
+} catch (error) {
+  console.error('Failed to get credentials:', error.message);
+}
 ```
 
 **Features:**
-- **Menu Management**: Add and organize menu items with validation, duplicate prevention, and proper hierarchy
-- **Page Configuration**: Set custom page titles for extension interfaces with automatic registration
+- **Flexible Menu Management**: Create menu sections and items with automatic ID prefixing and validation
+- **Optional Configuration**: Registration works with any combination of menu items and page configuration
+- **Credential Management**: Secure access to Adobe IMS authentication tokens and organization IDs
 - **Adobe UIX Integration**: Seamless registration with Adobe's extensibility platform using official APIs
-- **Input Validation**: Built-in sanitization, trimming, and validation for all configuration parameters
-- **Error Prevention**: Comprehensive error handling with meaningful messages for invalid configurations
+- **Input Validation**: Strict ID validation (alphanumeric + underscores only) and comprehensive error handling
 - **Type Safety**: Full TypeScript support with intelligent code completion and compile-time validation
 - **Production Ready**: Battle-tested utility used in real Adobe Commerce extensions with robust error handling
 
@@ -469,7 +729,12 @@ import type {
   DataTableProps,
   DataFormProps,
   ConfirmationDialogProps,
+  ShippingCarrierFormProps,
+  SelectOption,
+  FieldType,
   AdminUiSdkInterface,
+  AdminUiSdkCredentials,
+  AdminUiSdkRegistration,
   MenuItem
 } from '@adobe-commerce/aio-experience-kit';
 ```