michaelschiemer/docs/components/README.md

# Component System

Das Component-System ermöglicht wiederverwendbare UI-Komponenten mit konsistenter Syntax und Design-Token-Integration.

## Syntax

Alle Components verwenden die `<x-*>` Syntax:

```html
<x-button variant="primary" size="sm">Click me</x-button>
```

## Verfügbare Components

### Button

Vielseitige Button-Komponente mit verschiedenen Varianten und Größen.

**Syntax:**
```html
<x-button variant="primary|secondary|danger|success|ghost" 
          size="sm|md|lg" 
          href="/url"
          disabled>
    Button Text
</x-button>
```

**Attribute:**
- `variant` (optional): `primary`, `secondary`, `danger`, `success`, `ghost` (Standard: `primary`)
- `size` (optional): `sm`, `md`, `lg` (Standard: `md`)
- `href` (optional): Wenn gesetzt, wird ein `<a>`-Tag statt `<button>` verwendet
- `disabled` (optional): Deaktiviert den Button
- `type` (optional): Button-Typ (`button`, `submit`, `reset`) - nur bei `<button>` relevant
- `full-width` (optional): Button nimmt volle Breite ein
- `icon` (optional): Icon-HTML für Icon-Button

**Beispiele:**

```html
<!-- Primary Button -->
<x-button variant="primary">Save</x-button>

<!-- Secondary Button als Link -->
<x-button variant="secondary" href="/admin">Back</x-button>

<!-- Small Danger Button -->
<x-button variant="danger" size="sm">Delete</x-button>

<!-- Disabled Button -->
<x-button variant="primary" disabled>Processing...</x-button>

<!-- Full Width Button -->
<x-button variant="primary" full-width>Submit Form</x-button>
```

### Card

Card-Komponente für strukturierte Inhaltsblöcke.

**Syntax:**
```html
<x-card variant="default|highlighted|success|warning|error"
        title="Card Title"
        subtitle="Subtitle"
        footer="Footer Content">
    Card content here
</x-card>
```

**Attribute:**
- `variant` (optional): `default`, `highlighted`, `success`, `warning`, `error` (Standard: `default`)
- `title` (optional): Card-Titel
- `subtitle` (optional): Card-Untertitel
- `footer` (optional): Footer-Text
- `image-src` (optional): Bild-URL für Card-Header
- `image-alt` (optional): Alt-Text für Bild

**Beispiele:**

```html
<!-- Einfache Card -->
<x-card>
    <p>Card content</p>
</x-card>

<!-- Card mit Titel -->
<x-card title="Welcome">
    <p>Welcome to our platform!</p>
</x-card>

<!-- Card mit Variante -->
<x-card variant="success" title="Success" subtitle="Operation completed">
    <p>Your changes have been saved.</p>
</x-card>

<!-- Card mit Bild -->
<x-card image-src="/images/hero.jpg" image-alt="Hero Image" title="Featured">
    <p>Featured content here</p>
</x-card>
```

### Badge

Kleine Status-Indikatoren und Labels.

**Syntax:**
```html
<x-badge variant="default|success|warning|error|info"
         size="sm|md|lg"
         pill>
    Badge Text
</x-badge>
```

**Attribute:**
- `variant` (optional): `default`, `success`, `warning`, `error`, `info` (Standard: `default`)
- `size` (optional): `sm`, `md`, `lg` (Standard: `md`)
- `pill` (optional): Rundet die Badge ab (pill-Form)

**Beispiele:**

```html
<!-- Default Badge -->
<x-badge>New</x-badge>

<!-- Success Badge -->
<x-badge variant="success">Active</x-badge>

<!-- Warning Badge -->
<x-badge variant="warning">Pending</x-badge>

<!-- Pill Badge -->
<x-badge variant="info" pill>Beta</x-badge>

<!-- Small Badge -->
<x-badge variant="error" size="sm">Error</x-badge>
```

## Best Practices

### Konsistente Verwendung

1. **Immer Components verwenden**: Verwende `<x-button>` statt `<button class="btn">`
2. **Varianten statt Custom CSS**: Nutze `variant` Attribute statt eigene CSS-Klassen
3. **Design Tokens**: Components nutzen automatisch Design Tokens für konsistente Styles

### Performance

- Components werden server-side gerendert
- Keine JavaScript-Dependencies für statische Components
- Caching für bessere Performance

### Accessibility

- Components generieren semantisch korrektes HTML
- ARIA-Attribute werden automatisch gesetzt wo nötig
- Keyboard-Navigation wird unterstützt

## Migration von alten Templates

### Von direkten CSS-Klassen

```html
<!-- Vorher -->
<button class="btn btn--primary btn--sm">Click</button>

<!-- Nachher -->
<x-button variant="primary" size="sm">Click</x-button>
```

### Von admin-* Klassen

```html
<!-- Vorher -->
<button class="admin-btn admin-btn--secondary">Click</button>

<!-- Nachher -->
<x-button variant="secondary">Click</x-button>
```

### Von <component> Syntax

```html
<!-- Vorher -->
<component name="button" variant="primary">Click</component>

<!-- Nachher -->
<x-button variant="primary">Click</x-button>
```

## Template Linting

Verwende den `design:lint-templates` Command um Templates auf Component-Verwendung zu prüfen:

```bash
php console.php design:lint-templates
```

Der Linter erkennt:
- Direkte CSS-Klassen-Verwendung
- Deprecated `admin-*` Klassen
- Alte `<component>` Syntax

## Modern Web Features

- [Search Component](./search.md) - Semantisches `<search>` Element (Baseline 2023)
- [Popover Component](./popover.md) - Native Popover API (Baseline 2025)

## Weitere Components

Weitere Components werden kontinuierlich hinzugefügt. Siehe die einzelnen Component-Dateien in `src/Framework/View/Components/` für Details.