# React SDK

`@keenauth/react` ti offre componenti integrabili per accedere, iscriversi e gestire l'account, insieme agli hook che li sostengono. Il pacchetto si appoggia al core per browser [`@keenauth/js`](/docs/sdk/js), che esegue ogni chiamata di rete, PKCE, DPoP e il cerimoniale WebAuthn; i componenti non chiamano mai direttamente `fetch` o WebCrypto. Il pacchetto non è ancora pubblicato su npm.

Per un accesso con reindirizzamento alla pagina di login ospitata non ti serve questo pacchetto: vedi il [quickstart React](/docs/quickstarts/react), che usa direttamente `@keenauth/js`.

## Configura il provider

Crea il core una sola volta e passalo a `KeenAuthProvider`. Passa al core la classe di errore del pacchetto React, così i componenti riconoscono i problemi lato server:

```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` accetta:

| Prop | Significato |
|---|---|
| `core` | Il client `@keenauth/js` (qualsiasi oggetto che implementa il contratto `KeenAuthCore`) |
| `locale` | Lingua dell'interfaccia (BCP 47); predefinita `en` |
| `appearance` | Personalizzazioni opzionali del tema, vedi [Aspetto](#aspetto) |

I componenti chiamano l'API front (`/fapi/v1`) con i cookie del tuo ambiente e un header CSRF. Il server accetta queste chiamate solo dall'origine di login dell'ambiente stesso, e solo per applicazioni di prima parte.

## Componenti

| Componente | Cosa fa |
|---|---|
| `SignIn` | Accesso che parte dall'identificatore: password, passkey, codice via email o magic link, e secondi fattori |
| `SignUp` | Registrazione con le impostazioni di registrazione dell'ambiente |
| `UserProfile` | Il profilo dell'utente autenticato, le email (con verifica tramite codice), le passkey e le sessioni |

`SignIn` e `SignUp` accettano `transaction`, il corpo che avvia una transazione di accesso:

- nel flusso con reindirizzamento, `{ authorization_request: "azr_…" }` dalla richiesta di autorizzazione;
- senza reindirizzamento, `{ client_id, redirect_uri }` con un URI di reindirizzamento registrato.

`onComplete` viene chiamato quando il core ha terminato la transazione nella pagina; nel flusso con reindirizzamento, invece, la pagina passa altrove. Un passaggio che i componenti non disegnano (per esempio una sfida o la scelta di un'organizzazione) diventa un link per continuare sulla pagina di login ospitata.

`UserProfile` accetta `sections`, un sottoinsieme di `profile`, `emails`, `passkeys` e `sessions` (tutte e quattro per impostazione predefinita). Una scrittura del profilo che entra in conflitto con una modifica fatta altrove mostra un errore e ricarica i valori correnti.

## Hook

| Hook | Restituisce |
|---|---|
| `useKeenAuth()` | Il valore del provider: `core`, `locale`, `appearance` |
| `useEnvironment()` | Le impostazioni di accesso dell'ambiente e una funzione di ricerca testi `t` per la lingua attiva |
| `useTransaction()` | Una macchina a stati della transazione sopra l'API `transactions` del core |
| `useMe()` | Il profilo dell'utente autenticato e l'API dell'account |

## Aspetto

`appearance.variables` sovrascrive i token del tema (per esempio `color.primary`); vengono scritti come proprietà personalizzate `--idp-*` sul nodo radice del componente tramite CSSOM, quindi funziona anche con una Content Security Policy restrittiva senza stili `'unsafe-inline'`. `appearance.elements` aggiunge i tuoi nomi di classe agli elementi dei componenti. Il pacchetto non include alcun foglio di stile: applica gli stili alle classi `idp-*` nel tuo CSS.

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

## Lingue e accessibilità

- I componenti includono testi in inglese, turco, francese, tedesco, coreano, giapponese, italiano e spagnolo. Le personalizzazioni dei testi del tuo ambiente hanno la precedenza; un'altra lingua ricade sull'inglese, con la direzione del testo di quella lingua.
- Ogni campo ha un'etichetta, il riepilogo degli errori riceve il focus, i valori `autocomplete` sono impostati e l'incolla non viene mai bloccata.

## Passkey

Il pulsante passkey compare quando il relying party ID della passkey copre l'host della pagina (oppure l'origine della pagina è un'origine correlata dell'ambiente); altrimenti il componente rimanda alla pagina di login ospitata. Le passkey richiedono un contesto sicuro (`https` o `localhost`).

## Limiti attuali

- I pulsanti di accesso social non sono ancora disegnati; un ambiente che offre l'accesso social riceve un link alla pagina di login ospitata.
- I numeri di telefono non sono ancora disponibili: `UserProfile` non ha una sezione dedicata.
- I componenti per le organizzazioni (un selettore di organizzazione e il profilo) non sono ancora disponibili.