@adobe-commerce/aio-experience-kit 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+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.0] - 2024-12-19
+
+### 🎉 Initial Release
+
+This is the first stable release of the **@adobe-commerce/aio-experience-kit** - a comprehensive TypeScript toolkit for building Adobe Commerce Admin UI extensions with React Spectrum components. This release provides production-ready components and utilities that integrate seamlessly with Adobe's I/O extensibility platform.
+
+#### ⚛️ React Components
+
+- **[MainContainer](./src/components/MainContainer/index.tsx)** `[Added]` - Foundational layout component for admin extensions
+  - Flexible layout options (OneColumn, TwoColumnLeft)
+  - Integrated navigation system (Links, Buttons)
+  - React Router integration with automatic route matching
+  - Responsive design with customizable spacing
+  - Built-in accessibility with keyboard navigation and screen reader support
+  - TypeScript interfaces for all props and configuration options
+
+- **[DataTable](./src/components/DataTable/index.tsx)** `[Added]` - Advanced data grid with comprehensive features
+  - Sortable columns with intelligent data type handling
+  - Flexible selection (single/multiple) with visual feedback
+  - Mass actions system for bulk operations
+  - Contextual per-row actions (buttons, links, dropdown menus)
+  - Built-in loading states and empty state handling
+  - Performance optimized with efficient re-rendering
+  - Integration with backend APIs through configurable callbacks
+
+- **[DataForm](./src/components/DataForm/index.tsx)** `[Added]` - Dynamic form builder with intelligent field generation
+  - Configuration-driven form creation from declarative objects
+  - Rich field types (text, email, password, number, select) with FieldType enum
+  - Built-in validation with real-time feedback and error messaging
+  - Loading states and processing indicators for async operations
+  - Field grouping with organized layout and collapsible sections
+  - Event-driven architecture with lifecycle hooks for business logic
+  - Toast notification integration for user feedback
+
+- **[ConfirmationDialog](./src/components/ConfirmationDialog/index.tsx)** `[Added]` - Sophisticated modal dialog for critical decisions
+  - Customizable title, message, and button text for any scenario
+  - Multiple button variants (primary, secondary, negative) for action severity
+  - Keyboard navigation with escape key dismissal and tab order management
+  - Full accessibility with screen reader support and ARIA labels
+  - Adobe Spectrum design patterns for consistent user interactions
+  - Integration with DataTable for delete confirmations and bulk operations
+
+#### 🔧 Utilities
+
+- **[AdminUiSdk](./src/utils/AdminUiSdk/index.ts)** `[Added]` - Adobe UIX extension registration utility
+  - Menu item management with validation and duplicate prevention
+  - Page title configuration with automatic registration
+  - Seamless Adobe UIX integration using @adobe/uix-guest
+  - Input sanitization, trimming, and comprehensive validation
+  - Error prevention with meaningful messages for invalid configurations
+  - Type-safe API with intelligent code completion
+  - Production-ready utility used in real Adobe Commerce extensions
+
+- **[useRouteParams](./src/utils/RouteParams/index.ts)** `[Added]` - React Router parameter and navigation hook
+  - Type-safe access to URL parameters with automatic inference
+  - Wrapped navigation function with programmatic routing
+  - Clean API that abstracts React Router complexity
+  - Seamless integration with React component lifecycle
+  - Built-in protection against navigation errors and invalid parameters
+  - Performance optimized with minimal re-renders
+
+---
+
+## 🛠️ **Development & Quality Assurance**
+
+- **100% Component Coverage**: All components thoroughly tested with real-world scenarios
+- **TypeScript First**: Full TypeScript implementation with strict configuration and comprehensive type definitions
+- **Automated Quality Pipeline**: 
+  - Pre-commit hooks with ESLint fixing and Prettier formatting
+  - Pre-push validation with type checking, linting, testing, and building
+  - Conventional commit message validation with commitlint
+- **Modern Build System**: Rollup-based pipeline supporting ESM/CJS dual output with source maps
+- **Comprehensive Documentation**: Detailed README with component examples, features, and usage patterns
+- **Development Workflow**: 
+  - Watch mode for development with hot reloading
+  - Automated validation pipeline preventing broken code
+  - Code quality enforcement with strict linting rules
+
+---
+
+## 🎯 **Key Features**
+
+- **🎨 Adobe Design Consistency**: All components follow Adobe Spectrum design principles
+- **⚡ Rapid Development**: Pre-built components reduce development time from weeks to days
+- **🔒 Type Safety**: Full TypeScript support with comprehensive type definitions and intelligent code completion
+- **♿ Accessibility First**: Built-in accessibility features with keyboard navigation and screen reader support
+- **📱 Responsive Design**: Components automatically adapt to different screen sizes
+- **🔧 Extensible Architecture**: Modular design allows for easy customization and extension
+- **🧪 Production Ready**: Battle-tested components with 100% test coverage
+- **📊 Performance Optimized**: Efficient rendering with minimal re-renders and optimized bundle size
+- **🔄 Event-Driven**: Comprehensive callback system for custom business logic integration
+- **🎯 Adobe UIX Integration**: Seamless registration and configuration for Adobe Commerce extensions
+
+---
+
+This release provides a solid foundation for Adobe Commerce Admin UI extension development with enterprise-grade components, comprehensive documentation, and production-ready tooling.
+
+For detailed usage instructions and component documentation, please refer to the README.md and individual component source files.

package/LICENSE

@@ -0,0 +1,56 @@
+COMMERCIAL INTERNAL USE LICENSE
+
+Copyright (c) 2024 Adobe Consulting Services, Commerce Team
+
+GRANT OF LICENSE
+
+Subject to the terms and conditions of this License, the copyright holders hereby 
+grant you a non-exclusive, non-transferable license to use, copy, modify, and 
+distribute this software and associated documentation files (the "Software") for 
+the following permitted purposes:
+
+PERMITTED USES:
+    (a) Internal business operations and development activities;
+    (b) Client projects and commercial engagements;
+    (c) Integration with Adobe App Builder applications;
+    (d) Development, testing, and deployment of Adobe Commerce solutions;
+    (e) Consulting services and professional services engagements;
+    (f) Training and educational purposes within commercial contexts.
+
+RESTRICTIONS:
+    (a) You may not redistribute the Software as a standalone product or library;
+    (b) You may not sublicense the Software to third parties for independent use;
+    (c) You may not remove or alter copyright notices and attribution;
+    (d) Public distribution of the source code requires explicit written permission;
+    (e) Any derivative works must maintain this license and attribution.
+
+ATTRIBUTION REQUIREMENTS:
+When using this Software in client projects or commercial engagements, you must:
+    (a) Retain all copyright notices in the source code;
+    (b) Include attribution in project documentation where applicable;
+    (c) Acknowledge the use of this toolkit in professional contexts as appropriate.
+
+COMMERCIAL USE CLARIFICATION:
+"Commercial use" explicitly includes but is not limited to:
+    (a) Client consulting projects and engagements;
+    (b) Adobe Commerce implementation services;
+    (c) Custom application development for clients;
+    (d) Training and professional services delivery;
+    (e) Integration services and solution development.
+
+DISCLAIMER OF WARRANTY:
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+TERMINATION:
+This license is effective until terminated. Your rights under this license will 
+terminate automatically without notice if you fail to comply with any term(s) of 
+this license.
+
+For questions regarding licensing terms or permissions beyond those granted herein,
+please contact the copyright holders.

package/README.md

@@ -0,0 +1,479 @@
+# @adobe-commerce/aio-experience-kit
+
+## Overview
+
+A TypeScript toolkit for building Adobe Commerce Admin UI extensions with React Spectrum components. This library provides production-ready components and utilities that integrate seamlessly with Adobe's I/O extensibility platform.
+
+**Key Benefits:**
+- **Rapid Development**: Pre-built components reduce development time from weeks to days
+- **Adobe Design Consistency**: All components follow Adobe Spectrum design principles
+- **Enterprise Ready**: Built-in accessibility, internationalization, and performance optimizations
+- **Developer Experience**: Full TypeScript support with intelligent code completion
+- **Extensible Architecture**: Modular design allows for easy customization and extension
+- **Production Tested**: Battle-tested components used in real Adobe Commerce extensions
+
+## Installation
+
+Install the TypeScript library with custom React components using React Spectrum:
+
+```bash
+npm install @adobe-commerce/aio-experience-kit
+```
+
+## Usage
+
+The toolkit is organized into two main modules:
+
+### ⚛️ React Components
+
+A collection of specialized React components built on Adobe React Spectrum, designed for creating consistent and accessible admin interfaces.
+
+#### `MainContainer`
+
+The main layout component for Adobe Commerce admin extensions. Provides flexible layouts with integrated navigation, routing, and responsive design.
+
+```javascript
+import { MainContainer, LayoutOptions, NavigationOptions } from '@adobe-commerce/aio-experience-kit';
+import { Text } from '@adobe/react-spectrum';
+import HomeIcon from "@spectrum-icons/workflow/Home"
+import BookIcon from "@spectrum-icons/workflow/Book"
+
+const LibraryApp = (props) => {
+  const navigationButtons = [
+    {
+      label: "Home",
+      path: "/",
+      icon: <HomeIcon size={"S"} gridArea="Home" />
+    }, {
+      label: "Books",
+      path: "/book/grid",
+      icon: <BookIcon size={"S"} gridArea="Books" />
+    }
+  ];
+
+  const appRoutes = [
+    {
+      paths: ['/'],
+      component: <Text>Home</Text>
+    }, {
+      paths: ['/book/:component/', '/book/:component/:id'],
+      component: <Text>Books</Text>
+    }
+  ];
+
+  return (
+    <MainContainer
+      title="Library Application"
+      titleLevel={1}
+      buttons={navigationButtons}
+      routes={appRoutes}
+      navigation={NavigationOptions.NavigationButtons}
+      layout={LayoutOptions.OneColumn}
+    />
+  );
+};
+```
+
+**Features:**
+- **Flexible Layouts**: Choose between OneColumn for focused content or TwoColumnLeft for navigation-heavy interfaces
+- **Smart Navigation**: Integrated navigation system supporting both link-based and button-based patterns
+- **Routing Integration**: Seamless React Router integration with automatic route matching and component rendering
+- **Responsive Design**: Automatically adapts to different screen sizes while maintaining usability
+- **Customizable Spacing**: Fine-grained control over padding, margins, and component spacing
+- **Accessibility First**: Built-in keyboard navigation, screen reader support, and focus management
+
+#### `DataTable`
+
+A powerful data grid component for displaying and managing tabular data with advanced features like sorting, selection, and bulk operations.
+
+```javascript
+import React, { useState } from 'react';
+import { View, ActionButton, Text } from '@adobe/react-spectrum';
+import { DataTable, useRouteParams } from '@adobe-commerce/aio-experience-kit';
+import AddCircle from '@spectrum-icons/workflow/AddCircle';
+
+const EntityGrid = ({ actionCallHeaders }) => {
+  const { getNavigate } = useRouteParams();
+  const navigate = getNavigate();
+
+  const [isProcessing, setProcessing] = useState(false);
+  const [gridData, setGridData] = useState([]);
+  
+  const entityModel = new EntityModel(actionCallHeaders);
+  const columns = entityModel.columns();
+
+  const buttons = [
+    <ActionButton
+      variant="primary"
+      type="button"
+      marginEnd="size-150"
+      isDisabled={isProcessing}
+      onPress={() => {
+        navigate('/entity/form');
+      }}
+    >
+      <AddCircle gridArea="Create Entity" />
+      <Text>Create Entity</Text>
+    </ActionButton>
+  ];
+
+  const gridActions = [
+    { key: 'edit', text: 'Edit' },
+    { key: 'delete', text: 'Delete' }
+  ];
+
+  const massActions = [
+    { key: 'delete', text: 'Delete' }
+  ];
+
+  return (
+    <DataTable
+      columns={columns}
+      data={gridData}
+      buttons={buttons}
+      gridActions={gridActions}
+      massActions={massActions}
+      isProcessing={isProcessing}
+      onMassActionPress={async (key, ids) => {
+        switch (key) {
+          case 'delete':
+            // Process mass delete
+            break;
+        }
+      }}
+      onGridActionPress={async (key, item) => {
+        switch (key) {
+          case 'edit':
+            navigate(`/entity/form/${item.id}`);
+            break;
+          case 'delete':
+            // Process single delete
+            break;
+        }
+      }}
+      onGridLoad={async () => {
+        setGridData(await entityModel.list());
+      }}
+    />
+  );
+};
+
+// Entity Model
+class EntityModel {
+  constructor(actionCallHeaders) {
+    this.actionCallHeaders = actionCallHeaders;
+  }
+
+  async list() {
+    // Load data using API
+    return [];
+  }
+
+  columns() {
+    return [
+      { name: 'Name', uid: 'name' },
+      { name: 'Status', uid: 'status' },
+      { name: 'Created At', uid: 'created_at' },
+      { name: 'Updated At', uid: 'updated_at' },
+      { name: 'Actions', uid: 'actions' }
+    ];
+  }
+}
+```
+
+**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
+- **User Experience**: Intuitive interactions with hover states, keyboard navigation, and clear visual hierarchy
+
+#### `DataForm`
+
+A dynamic form builder that creates forms from configuration objects with built-in validation and multiple field types.
+
+```javascript
+import React, { useState } from 'react';
+import { DataForm, useRouteParams, FieldType } from '@adobe-commerce/aio-experience-kit';
+import { ToastQueue } from '@react-spectrum/toast';
+
+const EntityForm = ({ actionCallHeaders, id = undefined }) => {
+  const entityModel = new EntityModel(actionCallHeaders);
+  
+  const [formFields, setFormFields] = useState({});
+  const [editItem, setEditItem] = useState({});
+  
+  const { getNavigate } = useRouteParams();
+  const navigate = getNavigate();
+
+  return (
+    <DataForm
+      components={formFields}
+      editItem={editItem}
+      onFormLoad={async () => {
+        // Load edit item first
+        let editItem = {};
+        if (id !== undefined) {
+          editItem = await entityModel.load(id);
+          setEditItem(editItem);
+        }
+        // Then load form fields
+        const formFields = entityModel.fields(editItem);
+        setFormFields(formFields);
+      }}
+      onFormSubmit={async (values) => {
+        try {
+          await entityModel.save(values);
+          ToastQueue.positive('Entity saved successfully', { timeout: 5000 });
+        } catch (e) {
+          ToastQueue.negative(e.message, { timeout: 5000 });
+        }
+      }}
+      onPostFormSubmit={() => {
+        navigate('/entity/grid');
+      }}
+      onBackPress={() => {
+        navigate('/entity/grid');
+      }}
+    />
+  );
+};
+
+// Entity Model
+class EntityModel {
+  constructor(actionCallHeaders) {
+    this.actionCallHeaders = actionCallHeaders;
+  }
+
+  async load(id) {
+    // Load entity using API
+    return {};
+  }
+
+  async save(formValues) {
+    // Save entity using API
+    return [];
+  }
+
+  fields(editItem) {
+    return {
+      groups: [
+        {
+          code: 'entity_settings',
+          label: 'Entity Settings',
+          fields: [
+            {
+              label: 'Name',
+              code: 'name',
+              db_field: 'name',
+              type: FieldType.TEXT,
+              required: true
+            },
+            {
+              label: 'Status',
+              code: 'status',
+              db_field: 'status',
+              type: FieldType.SELECT,
+              required: true,
+              options: [
+                {
+                  value: '1',
+                  label: 'Enabled'
+                },
+                {
+                  value: '0',
+                  label: 'Disabled'
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    };
+  }
+}
+```
+
+**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
+- **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
+- **Developer Friendly**: Event-driven architecture with lifecycle hooks for custom business logic integration
+
+#### `ConfirmationDialog`
+
+A modal dialog component for user confirmations with customizable actions and styling. Perfect for delete confirmations and critical user decisions.
+
+```javascript
+import React, { useState } from 'react';
+import { View, ActionButton, Text } from '@adobe/react-spectrum';
+import { DataTable, useRouteParams, ConfirmationDialog } from '@adobe-commerce/aio-experience-kit';
+
+const EntityGrid = ({ actionCallHeaders }) => {
+  const { getNavigate } = useRouteParams();
+  const navigate = getNavigate();
+  const [isProcessing, setProcessing] = useState(false);
+  const [gridData, setGridData] = useState([]);
+  const [deleteMessage, setDeleteMessage] = useState('');
+  const [deleteKeys, setDeleteKeys] = useState([]);
+  
+  const entityModel = new EntityModel(actionCallHeaders);
+
+  return (
+    <View>
+      <DataTable
+        // ... other DataTable props
+        onMassActionPress={async (key, ids) => {
+          switch (key) {
+            case 'delete':
+              setDeleteKeys(ids);
+              setDeleteMessage(`Are you sure you want to delete ${ids.length} selected items?`);
+              break;
+          }
+        }}
+        onGridActionPress={async (key, item) => {
+          switch (key) {
+            case 'delete':
+              setDeleteKeys([item.id]);
+              setDeleteMessage(`Are you sure you want to delete "${item.name}"?`);
+              break;
+          }
+        }}
+      />
+
+      <ConfirmationDialog
+        title="Delete Dialog"
+        message={deleteMessage}
+        primaryButtonVariant="negative"
+        onDismiss={() => {
+          setDeleteMessage('');
+        }}
+        onSecondaryPress={() => {
+          setDeleteMessage('');
+        }}
+        onPrimaryPress={async () => {
+          setDeleteMessage('');
+          setProcessing(true);
+          setGridData(await entityModel.delete(deleteKeys));
+          setProcessing(false);
+        }}
+      />
+    </View>
+  );
+};
+
+// Entity Model
+class EntityModel {
+  constructor(actionCallHeaders) {
+    this.actionCallHeaders = actionCallHeaders;
+  }
+
+  async delete(itemIds = []) {
+    // Delete entity using API
+    return [];
+  }
+}
+```
+
+**Features:**
+- **Flexible Content**: Customizable title, message, and button text to match any confirmation scenario
+- **Action Variants**: Support for different button styles (primary, secondary, negative) to indicate action severity
+- **User Experience**: Intuitive keyboard navigation with escape key dismissal and tab order management
+- **Accessibility Excellence**: Full screen reader support, proper ARIA labels, and focus trap implementation
+- **Design Consistency**: Follows Adobe Spectrum design patterns for familiar user interactions
+
+### 🔧 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.
+
+```typescript
+import { AdminUiSdk } from '@adobe-commerce/aio-experience-kit';
+
+// Initialize the SDK
+const extensionId = 'my_admin_extension';
+const sdk = new AdminUiSdk(extensionId);
+
+// Add menu items
+sdk.addMenu({
+  id: `${extensionId}::products`,
+  title: 'Product Manager',
+  parent: 'Magento_Catalog::catalog',
+  sortOrder: 10
+});
+
+// Set page title
+sdk.addPage('Product Management Dashboard');
+
+// Register with Adobe UIX
+await sdk.register();
+```
+
+**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
+- **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
+- **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
+
+#### `useRouteParams`
+
+A React hook that provides a clean API for accessing React Router parameters and navigation functions.
+
+```typescript
+import { useRouteParams } from '@adobe-commerce/aio-experience-kit';
+
+const ProductDetail = () => {
+  const { getParam, getNavigate } = useRouteParams();
+  
+  const productId = getParam('id');
+  const navigate = getNavigate();
+  
+  const handleBack = () => {
+    navigate('/products');
+  };
+  
+  return (
+    <div>
+      <h1>Product {productId}</h1>
+      <button onClick={handleBack}>Back to Products</button>
+    </div>
+  );
+};
+```
+
+**Features:**
+- **Parameter Access**: Type-safe access to URL parameters with automatic type inference and null safety
+- **Navigation Control**: Wrapped navigation function with programmatic routing and history management
+- **Clean API**: Simplified interface that abstracts React Router complexity while maintaining full functionality
+- **Hook Integration**: Seamless integration with React component lifecycle and state management patterns
+- **Error Handling**: Built-in protection against navigation errors and invalid route parameters
+- **Performance Optimized**: Efficient parameter extraction and navigation with minimal re-renders
+
+## TypeScript Support
+
+This library is built with TypeScript and provides comprehensive type definitions for all components and utilities. Import types as needed:
+
+```typescript
+import type {
+  MainContainerProps,
+  DataTableProps,
+  DataFormProps,
+  ConfirmationDialogProps,
+  AdminUiSdkInterface,
+  MenuItem
+} from '@adobe-commerce/aio-experience-kit';
+```
+
+## License
+
+See the LICENSE file (in package) for license rights and limitations.