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:

npm install @skybridge/web-components

Components

StatusBadge

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

2. Import and use components:

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