skybridge/web-components/INTEGRATION_EXAMPLE.md

# 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.