# Vue

Das Mate Design System stellt eine Vue-Komponentenbibliothek bereit, die auf Web Components basiert und vollständig in Vue-3-Projekte integriert werden kann. Die Komponenten folgen den Designprinzipien des Mate Design Systems und sind so konzipiert, dass sie konsistent, zugänglich und wiederverwendbar sind.

## Voraussetzungen

Bevor du mit der Integration beginnst, stelle sicher, dass folgende Voraussetzungen erfüllt sind:

- Node.js in einer aktuellen LTS-Version
- Ein bestehendes Vue-3-Projekt oder die Bereitschaft, eines anzulegen
- Npm-Konfiguration mit Zugriff auf das interne Package Registry

Falls du den Source Code sehen oder das Design System via Contribution mitgestalten möchtest und noch keinen Zugang zum GitLab hast, wende dich an das Entwicklungsteam oder tritt der Usergroup bei.

## Installation

Konfiguriere zunächst den Zugang zum internen Package Registry. Füge dazu die Vue-Registry in deine `.npmrc`-Datei im Projektstamm ein und installiere anschließend das Vue-Paket des Mate Design Systems. Wie das genau funktioniert, erfährst du in [Installation](../installation.md) im Vue-Beispiel.

## Schnellstart mit Getting-Started-Template

Die schnellste Möglichkeit, mit MATE Vue zu beginnen, ist die Verwendung des offiziellen Getting-Started-Templates:

```bash
npm create @mate-vue/init@latest
```

Der Generator fragt nach dem Projektnamen. Gib z. B. `mein-projekt` ein oder bestätige mit Enter, um den Standardnamen `mate-vue-app` zu übernehmen. Direkt danach fragt er, ob er die Abhängigkeiten gleich selbst installieren soll (`npm install`). Anschließend:

```bash
cd mein-projekt
npm install   # nur nötig, wenn du die Installation im Generator abgelehnt hast
npm run dev
```

Dieser Befehl erstellt ein vollständiges Beispielprojekt mit:

- Einer funktionsfähigen Event-Management-Anwendung
- Beispielen für Dashboard, Kalender, Teilnehmerverwaltung und mehr
- Korrekt konfiguriertem MATE-Theme
- Mock-Backend mit Express
- Best-Practice-Projektstruktur

Das Template dient als Referenz und Ausgangspunkt für eigene Projekte. Nach dem Erstellen kannst du die Beispielkomponenten nach Bedarf anpassen oder entfernen.

## Erste Schritte (manuell)

Falls du MATE Vue in ein bestehendes Projekt integrieren möchtest, muss das Stylesheet des Design Systems in deinen Einstiegspunkt importiert werden. Füge den Import am Anfang deiner `main.ts` ein. Siehe dazu das Vue-Beispiel in [Theme](../theme.md).

Anschließend stehen alle Mate-Komponenten global in deinen Templates zur Verfügung:

```vue
<template>
  <MateFormLayout>
    <MateTextField label="Benutzername" />
    <MateTextField label="Passwort" type="password" />
    <MateButton variant="primary" @click="login">Anmelden</MateButton>
  </MateFormLayout>
</template>

<script setup lang="ts">
function login() {
  // Anmeldelogik
}
</script>
```

Das war es im Wesentlichen. Sobald das Plugin und das Stylesheet eingebunden sind, verhält sich jede Komponente wie erwartet – du musst kein weiteres Setup durchführen.

## Internationalization (i18n)

Um die Barrierefreiheit gewährleisten zu können, sollte überall, wo möglich das i18n Property gesetzt werden. Um standardmäßig Deutsche Texte zu erhalten, wird empfohlen den Einstiegspunkt der App wie folg zu konfigurieren:

```javascript
import '@mate/i18n/src/apply-all';
```

## Arbeiten mit dem Design System

Die Vue-Komponenten des Mate Design Systems sind Wrapper um die zugrundeliegenden Web Components, die sich nahtlos in Vues Reaktivitätssystem integrieren. Props werden als reguläre Vue-Props übergeben, Events folgen der Vue-Konvention mit `@`-Bindungen.

### Events und v-model

Für Eingabekomponenten steht `v-model` zur Verfügung, sofern die Komponente das entsprechende Emitter-Interface implementiert:

```vue
<template>
  <MateTextField label="Suche" v-model="query" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const query = ref('');
</script>
```

Falls `v-model` für eine Komponente nicht unterstützt wird, kannst du den Event manuell binden:

```vue
<template>
  <MateCombobox
    label="Kategorie"
    :value="selected"
    @value-changed="onValueChanged"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const selected = ref('');

function onValueChanged(event: CustomEvent) {
  selected.value = event.detail.value;
}
</script>
```

Beachte, dass Web Component Events in Vue typischerweise in Kebab-Case angegeben werden, also `@value-changed` statt `@valueChanged`.

### Formulare und Validierung

Mate-Eingabekomponenten lassen sich gut mit Formular-Bibliotheken wie VeeValidate kombinieren. Da die Komponenten als reguläre HTML-Elemente im DOM erscheinen, greifen die meisten Validierungsansätze ohne zusätzliche Konfiguration.

### Zugänglichkeit

Die Komponenten des Mate Design Systems bringen eine solide Basis für barrierefreie Anwendungen mit: ARIA-Rollen, Tastaturnavigation und Screenreader-Unterstützung sind in die Komponenten eingebaut. Das bedeutet aber nicht, dass eine Anwendung automatisch barrierefrei ist – das hängt entscheidend davon ab, wie die Komponenten verwendet werden.

Konkret: Ein Button ohne lesbaren Text, ein Eingabefeld ohne Label oder eine Pflichtangabe, die nicht als solche markiert ist, sind auch mit Mate-Komponenten nicht zugänglich. Nutze die bereitgestellten Props – `label`, `required`, `error-message`, `helper-text` – konsequent und mit aussagekräftigen Inhalten.

Darüber hinaus gibt es Aspekte der Barrierefreiheit, die grundsätzlich kontextabhängig sind und nicht von einer Komponentenbibliothek gelöst werden können: Fokus-Management nach Seitenübergängen, Live-Regionen für dynamisch aktualisierte Inhalte oder die Reihenfolge von Überschriften im Dokumentenbaum. Diese liegen in der Verantwortung der Anwendungsentwicklung.

## Best Practices

**Komponentengrenzen respektieren.** Mate-Komponenten sind so entworfen, dass sie eigenständige Einheiten sind. Versuche nicht, interne DOM-Strukturen der Web Components direkt zu manipulieren – nutze immer die offiziell dokumentierten Props und Slots.

**Konsistenz durch das Design System sicherstellen.** Verwende ausschließlich Mate-Komponenten für UI-Elemente, die im Design System definiert sind. Eigenentwicklungen für Buttons, Eingabefelder oder Dialoge führen zu Inkonsistenzen und erhöhen den Wartungsaufwand.

**Typen nutzen.** Das Paket liefert TypeScript-Definitionen mit. Nutze diese konsequent, um Fehler frühzeitig zu erkennen und die Autovervollständigung in deinem Editor zu verbessern.

**Keine Inline-Styles auf Mate-Komponenten.** Das Design System definiert alle visuellen Aspekte über Design Tokens. Inline-Styles überschreiben diese und führen zu unerwünschten Abweichungen. Falls du Abstände oder Layouts anpassen musst, tue das auf der umgebenden Wrapper-Ebene.

**Updates im Blick behalten.** Das Design System entwickelt sich weiter. Abonniere den Release-Kanal oder halte Ausschau nach Changelog-Einträgen, wenn du das Paket aktualisierst – Breaking Changes werden dort kommuniziert.

## Troubleshooting

**Komponenten werden unstyled dargestellt.**
Überprüfe, ob der CSS-Import in deiner `main.ts` vorhanden und korrekt ist. Ohne das Stylesheet werden die Web Components zwar gerendert, aber ohne die Mate-Styles.

**Vue gibt Warnungen zu unbekannten Komponenten aus.**
Stelle sicher, dass `app.use(MatePlugin)` vor `app.mount()` aufgerufen wird. Falls Komponenten trotzdem nicht erkannt werden, prüfe, ob du die korrekte Plugin-Instanz importierst.

**`v-model` funktioniert nicht wie erwartet.**
Nicht alle Komponenten implementieren das `v-model`-Interface. Wechsle in diesem Fall auf die explizite `:value`-Bindung kombiniert mit einem `@value-changed`-Handler.

**Events kommen nicht an.**
Prüfe den Eventnamen in der Komponentendokumentation. Web Component Events können in Vue sowohl in camelCase als auch in Kebab-Case gebunden werden – bei Problemen beide Varianten ausprobieren.

**Das Paket wird nicht gefunden.**
Überprüfe deine `.npmrc`-Konfiguration und stelle sicher, dass die @mate und @mate-vue Registry richtig ist. Die Pakete benötigen normalerweise kein extra Token.

## Weitere Informationen

- [Installationsübersicht](../installation) – Allgemeine Hinweise zum Zugang und zur Registry-Konfiguration
- [Komponentendokumentation](../../../components) – Übersicht aller verfügbaren Komponenten mit Props und Beispielen
- [Design-Grundlagen](../../../foundations) – Farben, Typografie, Spacing und weitere Designprinzipien
- [Dev & UX/UI Prozess](../dev-and-ux-ui-process) – Wie Entwicklung und Design im Mate-Ökosystem zusammenarbeiten