# LLM-UI - React Component Library

**Status**: Development  
**Stack**: React 18, TypeScript, Tailwind CSS, Jest  
**Purpose**: UI components for LLM Platform applications with Drupal integration

## Overview

React component library providing UI components for LLM Platform applications. Includes form components, layout utilities, and accessibility features.

## Architecture

```
Component System:
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Core React    │───▶│   Styled with   │───▶│   Accessibility │
│   Components    │    │   Tailwind CSS  │    │   Features      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ TypeScript      │    │  Testing with   │    │ Drupal Bridge   │
│ Type Safety     │    │     Jest        │    │   Components    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## Components

### Form Components
- Input, Select, Checkbox, Radio, TextArea
- Form validation and error handling
- Controlled and uncontrolled patterns

### Layout Components
- Grid, Container, Stack, Dashboard
- Responsive design utilities
- Flexbox and CSS Grid layouts

### UI Elements
- Button, Card, Modal, Toast, Alert
- Loading states and progress indicators
- Icon components

### Typography
- Heading, Text, Link
- Font scaling and responsive typography
- Semantic markup

### Data Display
- Table, Charts, Pagination
- Data visualization components
- Sorting and filtering

### Navigation
- Tabs, Breadcrumbs, Menu, Accordion
- Responsive navigation patterns
- Keyboard accessibility

## Features

- TypeScript type definitions
- Jest test coverage
- Tailwind CSS integration
- WCAG 2.1 accessibility compliance
- Drupal integration adapters

## Installation

```bash
npm install @llm-platform/llm-ui
```

## Usage

### Basic Components

```tsx
import { Button, Input, Card } from '@llm-platform/llm-ui';

function MyComponent() {
  return (
    <Card>
      <Input 
        label="Email" 
        type="email" 
        required 
        onChange={handleChange}
      />
      <Button type="submit" variant="primary">
        Submit
      </Button>
    </Card>
  );
}
```

### Form Handling

```tsx
import { Form, FormField, Button } from '@llm-platform/llm-ui';

function ContactForm() {
  const [values, setValues] = useState({});
  
  return (
    <Form onSubmit={handleSubmit}>
      <FormField 
        name="name"
        label="Full Name"
        required
        value={values.name}
        onChange={handleChange}
      />
      <FormField
        name="email"
        label="Email"
        type="email"
        required
        value={values.email}
        onChange={handleChange}
      />
      <Button type="submit">Send Message</Button>
    </Form>
  );
}
```

### Layout

```tsx
import { Container, Grid, Stack } from '@llm-platform/llm-ui';

function Layout() {
  return (
    <Container maxWidth="lg">
      <Grid cols={2} gap={4}>
        <Stack space={3}>
          <h2>Content Area</h2>
          <p>Main content goes here</p>
        </Stack>
        <Stack space={3}>
          <h3>Sidebar</h3>
          <p>Sidebar content</p>
        </Stack>
      </Grid>
    </Container>
  );
}
```

## Configuration

### Tailwind CSS Setup

```javascript
// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@llm-platform/llm-ui/**/*.{js,ts,jsx,tsx}'
  ],
  theme: {
    extend: {
      // Custom theme extensions
    }
  },
  plugins: []
};
```

### TypeScript Configuration

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true
  }
}
```

## Drupal Integration

### Bridge Components

```tsx
import { DrupalForm, DrupalField } from '@llm-platform/llm-ui/drupal';

function DrupalIntegration() {
  return (
    <DrupalForm entityType="node" bundle="article">
      <DrupalField name="title" />
      <DrupalField name="body" />
      <DrupalField name="field_tags" />
    </DrupalForm>
  );
}
```

### API Integration

```tsx
import { useDrupalEntity } from '@llm-platform/llm-ui/hooks';

function NodeDisplay({ nid }) {
  const { data: node, loading, error } = useDrupalEntity('node', nid);
  
  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage error={error} />;
  
  return (
    <Card>
      <h2>{node.title}</h2>
      <div dangerouslySetInnerHTML={{ __html: node.body }} />
    </Card>
  );
}
```

## Theming

### Custom Theme

```tsx
import { ThemeProvider } from '@llm-platform/llm-ui';

const customTheme = {
  colors: {
    primary: '#007bff',
    secondary: '#6c757d'
  },
  spacing: {
    xs: '0.25rem',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
    xl: '2rem'
  }
};

function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <MyApplication />
    </ThemeProvider>
  );
}
```

## Testing

### Component Tests

```tsx
import { render, screen } from '@testing-library/react';
import { Button } from '@llm-platform/llm-ui';

test('renders button with text', () => {
  render(<Button>Click me</Button>);
  expect(screen.getByText('Click me')).toBeInTheDocument();
});

test('calls onClick handler', () => {
  const handleClick = jest.fn();
  render(<Button onClick={handleClick}>Click me</Button>);
  
  screen.getByText('Click me').click();
  expect(handleClick).toHaveBeenCalledTimes(1);
});
```

### Accessibility Tests

```tsx
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('should not have accessibility violations', async () => {
  const { container } = render(<MyComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});
```

## Development

### Setup

```bash
# Clone repository
git clone [repository-url]
cd llm-ui

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test
```

### Scripts

```bash
npm run dev          # Start Storybook development server
npm run build        # Build for production
npm run test         # Run tests
npm run test:watch   # Run tests in watch mode
npm run lint         # Check code style
npm run typecheck    # Check TypeScript types
npm run storybook    # Start Storybook
```

### Storybook

Components are documented and tested with Storybook:

```bash
npm run storybook
```

Access Storybook at `http://localhost:6006`

## API Reference

### Component Props

#### Button

```tsx
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  onClick?: (event: MouseEvent) => void;
  children: ReactNode;
}
```

#### Input

```tsx
interface InputProps {
  label?: string;
  placeholder?: string;
  type?: 'text' | 'email' | 'password' | 'number';
  required?: boolean;
  disabled?: boolean;
  error?: string;
  value?: string;
  onChange?: (value: string) => void;
}
```

#### Card

```tsx
interface CardProps {
  title?: string;
  subtitle?: string;
  actions?: ReactNode;
  padding?: 'none' | 'sm' | 'md' | 'lg';
  children: ReactNode;
}
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new components
5. Update Storybook documentation
6. Ensure all tests pass
7. Submit a merge request

## MACH Alliance Compliance

This component library embodies MACH Alliance principles for modern frontend architecture:

- **Microservices** ✅ - Independent UI component library that integrates with any backend service
- **API-first** ✅ - Components consume REST/GraphQL APIs without tight coupling to backend systems
- **Cloud-native** ✅ - Framework-agnostic components deployable in any cloud environment
- **Headless** ✅ - Pure UI components that work with any headless CMS or API backend

### MACH Certification Features

```tsx
// API-first component design
import { useAPI } from '@llm-platform/llm-ui/hooks';

function AIAssistantWidget() {
  const { data, loading } = useAPI('/api/ai/chat', {
    method: 'POST',
    body: { message: 'Hello AI' }
  });

  return (
    <Card>
      {loading ? <LoadingSpinner /> : <ChatMessage data={data} />}
    </Card>
  );
}

// Headless integration with any backend
const config = {
  apiEndpoint: 'https://your-api.com',
  authentication: 'bearer-token',
  provider: 'custom' // Works with any provider
};
```

This component library provides production-ready UI components that work seamlessly with any microservice architecture while maintaining complete backend independence. For complete MACH compliance strategy, see [MACH_ALLIANCE_STRATEGY.md](../MACH_ALLIANCE_STRATEGY.md).

## Repository

- GitLab: Internal project repository

## License

MIT