skybridge/web-components/README.md

# Skybridge Web Components

A shared component library for Skybridge microfrontends, providing consistent UI components, hooks, and utilities across all applications.

## Installation

Since this is a monorepo package, install it as a workspace dependency:

```bash
npm install @skybridge/web-components
```

## Components

### FormSidebar

A reusable sidebar form component that handles create/edit operations with validation.

```tsx
import { FormSidebar, FormField } from '@skybridge/web-components';

const fields: FormField[] = [
  {
    name: 'name',
    label: 'Name',
    type: 'text',
    required: true,
    placeholder: 'Enter name',
  },
  {
    name: 'email',
    label: 'Email',
    type: 'email',
    required: true,
    validation: { email: true },
  },
  {
    name: 'role',
    label: 'Role',
    type: 'select',
    options: [
      { value: 'admin', label: 'Admin' },
      { value: 'user', label: 'User' },
    ],
  },
];

const MyComponent = () => {
  const [opened, setOpened] = useState(false);
  const [editItem, setEditItem] = useState(null);

  const handleSubmit = async (values) => {
    // Handle create/update logic
    await apiService.create(values);
  };

  return (
    <FormSidebar
      opened={opened}
      onClose={() => setOpened(false)}
      onSuccess={() => {
        setOpened(false);
        // Refresh data
      }}
      title="User"
      editMode={!!editItem}
      editItem={editItem}
      fields={fields}
      onSubmit={handleSubmit}
    />
  );
};
```

### DataTable

A feature-rich data table component with filtering, pagination, and actions.

```tsx
import { DataTable, TableColumn } from '@skybridge/web-components';

const columns: TableColumn[] = [
  { key: 'name', label: 'Name', sortable: true },
  { key: 'email', label: 'Email', sortable: true },
  { 
    key: 'status', 
    label: 'Status',
    render: (value) => (
      <Badge color={value === 'active' ? 'green' : 'gray'}>
        {value}
      </Badge>
    )
  },
];

const MyTable = () => {
  const [data, setData] = useState([]);
  const [page, setPage] = useState(1);
  
  return (
    <DataTable
      data={data}
      columns={columns}
      title="Users"
      searchable
      page={page}
      onPageChange={setPage}
      onAdd={() => {/* Handle add */}}
      onEdit={(item) => {/* Handle edit */}}
      onDelete={async (item) => {/* Handle delete */}}
    />
  );
};
```

## Hooks

### useApiService

A comprehensive API service hook with CRUD operations and state management.

```tsx
import { useApiService } from '@skybridge/web-components';

const MyComponent = () => {
  const {
    data,
    loading,
    error,
    getAll,
    create,
    update,
    delete: deleteItem,
    refresh,
  } = useApiService({
    baseURL: 'http://localhost:8080/api',
    defaultHeaders: { 'X-User-Email': 'admin@example.com' },
  }, 'users');

  useEffect(() => {
    getAll();
  }, [getAll]);

  const handleCreate = async (userData) => {
    await create(userData);
  };

  return (
    // Your component JSX
  );
};
```

### useDataFilter

Client-side filtering and search functionality.

```tsx
import { useDataFilter } from '@skybridge/web-components';

const MyComponent = () => {
  const [rawData, setRawData] = useState([]);
  
  const {
    filteredData,
    filters,
    setFilter,
    searchTerm,
    setSearchTerm,
    clearFilters,
  } = useDataFilter(rawData, {
    searchFields: ['name', 'email', 'description'],
  });

  return (
    <div>
      <input
        value={searchTerm}
        onChange={(e) => setSearchTerm(e.target.value)}
        placeholder="Search..."
      />
      {/* Render filteredData */}
    </div>
  );
};
```

## Utilities

### Notifications

Standardized notification helpers.

```tsx
import {
  showSuccessNotification,
  showErrorNotification,
  showCrudNotification,
  NotificationMessages,
} from '@skybridge/web-components';

// Simple notifications
showSuccessNotification('Operation completed!');
showErrorNotification('Something went wrong');

// CRUD operation notifications
showCrudNotification.success('create', 'User');
showCrudNotification.error('update', 'User', 'Custom error message');

// Pre-defined messages
showSuccessNotification(NotificationMessages.userCreated);
```

### Validation

Common validation functions and patterns.

```tsx
import {
  validateRequired,
  validateEmail,
  validateDuration,
  combineValidators,
  ValidationPatterns,
  parseDuration,
} from '@skybridge/web-components';

// Single validators
const emailError = validateEmail('invalid-email'); // Returns error message or null

// Combined validators
const validateName = combineValidators(
  validateRequired,
  (value) => validateMinLength(value, 2, 'Name')
);

// Duration parsing (common in KMS/FaaS)
const seconds = parseDuration('24h'); // Returns 86400
```

## Development

### Building

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Watch mode for development
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint
```

### Usage in Microfrontends

1. Add as a dependency in your microfrontend's `package.json`:

```json
{
  "dependencies": {
    "@skybridge/web-components": "workspace:*"
  }
}
```

2. Import and use components:

```tsx
import { FormSidebar, DataTable, useApiService } from '@skybridge/web-components';
```

## Architecture

The component library is designed to:

- **Standardize UI**: Consistent components across all microfrontends
- **Reduce Duplication**: Shared business logic and utilities
- **Improve Maintainability**: Single source of truth for common patterns
- **Ensure Consistency**: Unified validation, notifications, and API handling

## Common Patterns Extracted

Based on analysis of the existing microfrontends, this library extracts these common patterns:

1. **Sidebar Forms**: All microfrontends use similar slide-out forms
2. **Data Tables**: Consistent table layouts with actions and filtering
3. **API Integration**: Standard CRUD operations with error handling
4. **Validation**: Common validation rules and patterns
5. **Notifications**: Standardized success/error messaging
6. **Filtering**: Client-side search and filter functionality

## Compatibility

- React 18+
- TypeScript 5+
- Mantine 7.0+
- Works with all existing Skybridge microfrontends (web, kms, user, faas)

## Contributing

When adding new components or utilities:

1. Follow existing patterns and naming conventions
2. Add TypeScript types for all props and return values
3. Include documentation and usage examples
4. Test with all microfrontends before committing
5. Update this README with new features