# React SDK

`@keenauth/react` stellt einbettbare Komponenten für Anmeldung, Registrierung und Konto bereit, dazu die Hooks darunter. Es läuft auf dem Browser-Kern [`@keenauth/js`](/docs/sdk/js), der jeden Netzwerkaufruf, PKCE, DPoP und jeden WebAuthn-Ablauf übernimmt; die Komponenten rufen `fetch` oder WebCrypto selbst nie auf. Das Paket ist noch nicht auf npm veröffentlicht.

Für eine Weiterleitung zur gehosteten Anmeldeseite benötigen Sie dieses Paket nicht. Siehe dazu den [React-Schnellstart](/docs/quickstarts/react), der `@keenauth/js` direkt verwendet.

## Provider einrichten

Erstellen Sie den Kern einmalig und übergeben Sie ihn an `KeenAuthProvider`. Übergeben Sie die Fehlerklasse des React-Pakets an den Kern, damit die Komponenten Serverprobleme erkennen:

```tsx
import { KeenAuth } from "@keenauth/js";
import { KeenAuthProblemError, KeenAuthProvider, SignIn } from "@keenauth/react";

const core = new KeenAuth({
  issuer: "https://acme.eu.keenauth.app",
  clientId: "app_01j9zzzzzzzzzzzzzzzzzzzz",
  redirectUri: "https://login.acme.example/callback",
  createProblemError: (problem) => new KeenAuthProblemError(problem),
});

export function App() {
  return (
    <KeenAuthProvider core={core} locale="en">
      <SignIn transaction={{ client_id: "app_01j9zzzzzzzzzzzzzzzzzzzz", redirect_uri: "https://login.acme.example/callback" }} />
    </KeenAuthProvider>
  );
}
```

`KeenAuthProvider` akzeptiert:

| Prop | Bedeutung |
|---|---|
| `core` | Der `@keenauth/js`-Client (jedes Objekt, das den `KeenAuthCore`-Vertrag implementiert) |
| `locale` | UI-Sprache (BCP 47); Standard `en` |
| `appearance` | Optionale Theme-Überschreibungen, siehe [Erscheinungsbild](#erscheinungsbild) |

Die Komponenten rufen die Front-API (`/fapi/v1`) mit den Cookies Ihrer Umgebung und einem CSRF-Header auf. Der Server akzeptiert diese Aufrufe nur von der eigenen Anmeldeseite der Umgebung und nur für First-Party-Anwendungen.

## Komponenten

| Komponente | Funktion |
|---|---|
| `SignIn` | Identifier-first-Anmeldung: Passwort, Passkey, E-Mail-Code oder Magic Link sowie zweite Faktoren |
| `SignUp` | Registrierung mit den Registrierungseinstellungen der Umgebung |
| `UserProfile` | Das Profil des angemeldeten Benutzers, E-Mail-Adressen (mit Bestätigungscode), Passkeys und Sitzungen |

`SignIn` und `SignUp` akzeptieren `transaction`, den Body, der eine Anmeldetransaktion startet:

- im Weiterleitungsablauf `{ authorization_request: "azr_…" }` aus der Autorisierungsanfrage;
- ohne Weiterleitung `{ client_id, redirect_uri }` mit einer registrierten Redirect-URI.

`onComplete` wird aufgerufen, wenn der Kern die Transaktion auf der Seite abgeschlossen hat. Im Weiterleitungsablauf navigiert die Seite stattdessen weg. Ein Schritt, den die Komponenten nicht darstellen (zum Beispiel eine Challenge oder eine Organisationsauswahl), wird zu einem Link, mit dem Sie auf der gehosteten Anmeldeseite fortfahren.

`UserProfile` akzeptiert `sections`, eine Teilmenge von `profile`, `emails`, `passkeys` und `sessions` (standardmäßig alle vier). Ein Profil-Schreibvorgang, der mit einer anderswo vorgenommenen Änderung kollidiert, zeigt einen Fehler an und lädt die aktuellen Werte neu.

## Hooks

| Hook | Liefert |
|---|---|
| `useKeenAuth()` | Den Provider-Wert: `core`, `locale`, `appearance` |
| `useEnvironment()` | Die Anmeldeeinstellungen der Umgebung und eine Textsuche `t` für die aktive Sprache |
| `useTransaction()` | Eine Transaktions-Zustandsmaschine über der `transactions`-API des Kerns |
| `useMe()` | Das Profil des angemeldeten Benutzers und die Konto-API |

## Erscheinungsbild

`appearance.variables` überschreibt Theme-Tokens (zum Beispiel `color.primary`). Sie werden über das CSSOM als `--idp-*`-Custom-Properties am Komponenten-Root geschrieben, sodass auch eine strikte Content Security Policy ohne `'unsafe-inline'`-Styles funktioniert. `appearance.elements` fügt Ihre Klassennamen den Elementen der Komponenten hinzu. Das Paket liefert kein Stylesheet mit: Gestalten Sie die `idp-*`-Klassen in Ihrem eigenen CSS.

```tsx
<KeenAuthProvider core={core} appearance={{ variables: { "color.primary": "#1f6feb" }, elements: { buttonPrimary: "acme-button" } }}>
```

## Sprachen und Barrierefreiheit

- Die Komponenten enthalten Texte auf Englisch, Türkisch, Französisch, Deutsch, Koreanisch, Japanisch, Italienisch und Spanisch. Die Textüberschreibungen Ihrer Umgebung haben Vorrang. Eine andere Sprache fällt auf Englisch zurück, mit der Textrichtung dieser Sprache.
- Jedes Eingabefeld hat eine Beschriftung, die Fehlerzusammenfassung erhält den Fokus, `autocomplete`-Werte sind gesetzt, und Einfügen wird nie blockiert.

## Passkeys

Die Passkey-Schaltfläche erscheint, wenn die Relying-Party-ID des Passkeys den Host der Seite abdeckt (oder der Ursprung der Seite ein verwandter Ursprung der Umgebung ist). Andernfalls verlinkt die Komponente auf die gehostete Anmeldeseite. Passkeys benötigen einen sicheren Kontext (`https` oder `localhost`).

## Aktuelle Einschränkungen

- Schaltflächen für Social Sign-in werden noch nicht dargestellt. Eine Umgebung, die Social Sign-in anbietet, erhält einen Link zur gehosteten Anmeldeseite.
- Telefonnummern sind noch nicht verfügbar: `UserProfile` hat keinen Telefonabschnitt.
- Organisationskomponenten (ein Organisationsumschalter und ein Organisationsprofil) sind noch nicht verfügbar.