decent

web-components/INTEGRATION_EXAMPLE.md

@@ -0,0 +1,282 @@
+# Integration Example
+
+This document shows how to integrate the `@skybridge/web-components` library into existing microfrontends.
+
+## 1. Update Package.json
+
+Add the component library as a dependency:
+
+```json
+{
+  "dependencies": {
+    "@skybridge/web-components": "workspace:*"
+  }
+}
+```
+
+## 2. Example: Refactoring User Management
+
+Here's how to refactor the existing `UserSidebar.tsx` to use the shared components:
+
+### Before (existing code):
+```tsx
+// user/web/src/components/UserSidebar.tsx
+import { Paper, TextInput, Select, Button /* ... */ } from '@mantine/core';
+import { useForm } from '@mantine/form';
+// ... lots of boilerplate form logic
+```
+
+### After (using shared components):
+```tsx
+// user/web/src/components/UserSidebar.tsx
+import React from 'react';
+import { 
+  FormSidebar, 
+  FormField, 
+  validateRequired, 
+  validateEmail,
+  combineValidators 
+} from '@skybridge/web-components';
+import { userService } from '../services/userService';
+
+const UserSidebar: React.FC<UserSidebarProps> = ({
+  opened,
+  onClose,
+  onSuccess,
+  editUser,
+}) => {
+  const fields: FormField[] = [
+    {
+      name: 'first_name',
+      label: 'First Name',
+      type: 'text',
+      required: true,
+      placeholder: 'Enter first name',
+    },
+    {
+      name: 'last_name',
+      label: 'Last Name', 
+      type: 'text',
+      required: true,
+      placeholder: 'Enter last name',
+    },
+    {
+      name: 'email',
+      label: 'Email',
+      type: 'email',
+      required: true,
+      placeholder: 'Enter email address',
+      validation: { email: true },
+    },
+    {
+      name: 'role',
+      label: 'Role',
+      type: 'select',
+      required: true,
+      options: [
+        { value: 'admin', label: 'Admin' },
+        { value: 'moderator', label: 'Moderator' },
+        { value: 'user', label: 'User' },
+        { value: 'viewer', label: 'Viewer' },
+      ],
+      defaultValue: 'user',
+    },
+    {
+      name: 'status',
+      label: 'Status',
+      type: 'select', 
+      required: true,
+      options: [
+        { value: 'active', label: 'Active' },
+        { value: 'inactive', label: 'Inactive' },
+        { value: 'suspended', label: 'Suspended' },
+        { value: 'pending', label: 'Pending' },
+      ],
+      defaultValue: 'pending',
+    },
+  ];
+
+  const handleSubmit = async (values: any) => {
+    if (editUser) {
+      await userService.updateUser(editUser.id, values);
+    } else {
+      await userService.createUser(values);
+    }
+  };
+
+  return (
+    <FormSidebar
+      opened={opened}
+      onClose={onClose}
+      onSuccess={onSuccess}
+      title="User"
+      editMode={!!editUser}
+      editItem={editUser}
+      fields={fields}
+      onSubmit={handleSubmit}
+      width={400}
+    />
+  );
+};
+```
+
+## 3. Example: User Management Table
+
+Replace the existing table with the shared DataTable:
+
+```tsx
+// user/web/src/components/UserManagement.tsx
+import React, { useState, useEffect } from 'react';
+import { 
+  DataTable, 
+  TableColumn, 
+  useApiService,
+  useDataFilter,
+  Badge 
+} from '@skybridge/web-components';
+
+const UserManagement: React.FC = () => {
+  const [sidebarOpened, setSidebarOpened] = useState(false);
+  const [editUser, setEditUser] = useState(null);
+  
+  const {
+    data: users,
+    loading,
+    error,
+    getAll,
+    delete: deleteUser,
+    refresh,
+  } = useApiService({
+    baseURL: 'http://localhost:8090/api',
+    defaultHeaders: { 'X-User-Email': 'admin@example.com' },
+  }, 'users');
+
+  const columns: TableColumn[] = [
+    { 
+      key: 'first_name', 
+      label: 'First Name',
+      sortable: true 
+    },
+    { 
+      key: 'last_name', 
+      label: 'Last Name',
+      sortable: true 
+    },
+    { 
+      key: 'email', 
+      label: 'Email',
+      sortable: true 
+    },
+    { 
+      key: 'role', 
+      label: 'Role',
+      render: (value) => (
+        <Badge color="blue" size="sm">{value}</Badge>
+      )
+    },
+    { 
+      key: 'status', 
+      label: 'Status' 
+      // Uses default status rendering from DataTable
+    },
+  ];
+
+  useEffect(() => {
+    getAll();
+  }, [getAll]);
+
+  const handleAdd = () => {
+    setEditUser(null);
+    setSidebarOpened(true);
+  };
+
+  const handleEdit = (user) => {
+    setEditUser(user);
+    setSidebarOpened(true);
+  };
+
+  const handleSuccess = () => {
+    setSidebarOpened(false);
+    setEditUser(null);
+    refresh();
+  };
+
+  return (
+    <>
+      <DataTable
+        data={users}
+        columns={columns}
+        loading={loading}
+        error={error}
+        title="User Management"
+        searchable
+        onAdd={handleAdd}
+        onEdit={handleEdit}
+        onDelete={deleteUser}
+        onRefresh={refresh}
+        emptyMessage="No users found"
+      />
+      
+      <UserSidebar
+        opened={sidebarOpened}
+        onClose={() => setSidebarOpened(false)}
+        onSuccess={handleSuccess}
+        editUser={editUser}
+      />
+    </>
+  );
+};
+```
+
+## 4. Benefits of Integration
+
+### Code Reduction
+- **UserSidebar.tsx**: Reduced from ~250 lines to ~80 lines
+- **UserManagement.tsx**: Cleaner, more focused on business logic
+- **Removed Duplication**: No more repeated form validation, notification logic
+
+### Consistency
+- All forms look and behave the same across microfrontends
+- Standardized validation messages and error handling
+- Consistent table layouts and interactions
+
+### Maintainability
+- Bug fixes in shared components benefit all microfrontends
+- New features added once, available everywhere
+- Easier to update UI themes and styling
+
+## 5. Installation Steps
+
+1. **Install the component library**:
+   ```bash
+   npm install @skybridge/web-components --workspace=user/web
+   ```
+
+2. **Update imports in existing components**:
+   ```tsx
+   // Replace individual Mantine imports
+   import { FormSidebar, DataTable, useApiService } from '@skybridge/web-components';
+   ```
+
+3. **Refactor components gradually**:
+   - Start with new components
+   - Refactor existing components one at a time
+   - Test thoroughly in each microfrontend
+
+4. **Update build configuration** (if needed):
+   - Ensure the component library is built before microfrontends
+   - Update webpack externals if necessary
+
+## 6. Migration Checklist
+
+- [ ] Add `@skybridge/web-components` to package.json
+- [ ] Refactor sidebar forms to use `FormSidebar`
+- [ ] Replace tables with `DataTable` component  
+- [ ] Use shared validation utilities
+- [ ] Standardize notification handling
+- [ ] Update API service patterns to use `useApiService`
+- [ ] Test all CRUD operations
+- [ ] Verify styling consistency
+- [ ] Update tests if necessary
+
+This integration will significantly reduce code duplication while improving consistency and maintainability across all Skybridge microfrontends.