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

### StatusBadge

A standardized badge component with consistent color schemes across all microfrontends.

```tsx
import { StatusBadge, UserRoleBadge, RuntimeBadge } from '@skybridge/web-components';

// Generic usage
<StatusBadge value="active" variant="status" />

// Context-specific usage
<UserRoleBadge value="admin" />
<RuntimeBadge value="nodejs18" />

// Variants: 'status', 'role', 'runtime', 'type', 'severity', 'execution'
```

### EmptyState

A comprehensive empty state component for consistent empty data handling.

```tsx
import { EmptyState, NoUsersState, NoSearchResults } from '@skybridge/web-components';

// Generic empty state
<EmptyState
  variant="no-data"
  context="users"
  onAdd={() => handleAddUser()}
  onRefresh={() => handleRefresh()}
/>

// Convenience components
<NoUsersState onAddUser={handleAddUser} />
<NoSearchResults onClearFilters={handleClear} onRefresh={handleRefresh} />
```

### Sidebar

A flexible base sidebar component for consistent slide-out panels.

```tsx
import { Sidebar, DetailsSidebar, useSidebar } from '@skybridge/web-components';

const MySidebar = () => {
  const { opened, open, close } = useSidebar();
  
  return (
    <Sidebar
      opened={opened}
      onClose={close}
      title="My Panel"
      width={400}
    >
      <p>Content goes here</p>
    </Sidebar>
  );
};

// For item details
<DetailsSidebar
  opened={opened}
  onClose={close}
  itemName="John Doe"
  itemType="User"
  status={<StatusBadge value="active" />}
  editButton={<Button onClick={handleEdit}>Edit</Button>}
>
  <UserDetails user={selectedUser} />
</DetailsSidebar>
```

### ActionMenu

A standardized action menu component for table rows and items.

```tsx
import { ActionMenu, getUserActions, createEditAction } from '@skybridge/web-components';

// Using pre-built action sets
<ActionMenu
  item={user}
  actions={getUserActions(handleEdit, handleDelete, handleViewDetails)}
/>

// Custom actions
<ActionMenu
  item={item}
  actions={[
    createEditAction(handleEdit),
    createDeleteAction(handleDelete, 'user'),
    {
      key: 'custom',
      label: 'Custom Action',
      icon: IconSettings,
      onClick: handleCustomAction,
    }
  ]}
/>
```

### LoadingState

Comprehensive loading states for different scenarios.

```tsx
import { 
  LoadingState, 
  TableLoadingState, 
  PageLoadingState,
  useLoadingState 
} from '@skybridge/web-components';

// Different loading variants
<LoadingState variant="spinner" message="Loading data..." />
<LoadingState variant="progress" progress={75} progressLabel="3/4 complete" />
<LoadingState variant="skeleton-table" rows={5} columns={3} />

// Convenience components
<TableLoadingState rows={10} />
<PageLoadingState message="Loading application..." />

// Hook for loading state management
const { loading, startLoading, stopLoading, updateProgress } = useLoadingState();
```

### 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 deep analysis of the existing microfrontends, this library extracts these common patterns:

1. **Status Display**: Standardized color schemes and formatting for status badges across all apps
2. **Empty States**: Consistent empty data handling with contextual actions and messaging
3. **Sidebar Components**: All microfrontends use similar slide-out forms and detail panels
4. **Action Menus**: Standardized table actions with confirmation dialogs and consistent UX
5. **Loading States**: Multiple loading variants (spinners, progress, skeletons) for different scenarios
6. **Form Handling**: Reusable form sidebars with validation and error handling
7. **Data Tables**: Consistent table layouts with actions, filtering, and pagination
8. **API Integration**: Standard CRUD operations with error handling and state management
9. **Validation**: Common validation rules and patterns with consistent error messages
10. **Notifications**: Standardized success/error messaging and CRUD operation feedback

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