# XWUIAuthGateway

One sign-in surface that carries both credential styles a product usually needs:
identity plus password, and contact plus one-time code. It renders the forms,
the mode switcher, the validation copy and the two-stage OTP flow - and performs
no authentication itself. Every submission leaves as a DOM event; the host makes
the API call and calls back in with the result.

## When to use

- The sign-in page of a product where some users have passwords and some sign in
  with a code, and you do not want two routes.
- Deployments whose enabled sign-in methods are decided by the server rather
  than by the front end - see the policy section below, which is the main reason
  this component exists.
- Any host that already owns its auth API and needs the form, not the protocol.

For registration, password reset and the other blocks, use the `XWUIAuthBlocks`
family; for the whole authenticated shell, `XWUISuperAuth`.

## The server policy is authoritative

Pass `config.policy` - the public projection of the server's sign-in policy
(`GET /v1/auth/policy`) - and it **overrides** `modes`, `otpContactKind` and the
phone country list. The point is that the form stops asserting a policy it does
not own: if the server has OTP disabled, no OTP tab renders, whatever the
component was configured with.

Two consequences to handle:

- When the policy requires a credential this component cannot render (a passkey,
  today), the rendering is marked unsupported and `policyUnsupportedText` is
  shown instead of a form that could not succeed.
- Some deployments sign in with contact **plus password** in one step and never
  send a code. That is `otpWithPassword`: the contact form collects a password
  and emits it with `otp-request`, with no code stage after it.

Labels, icons and copy always stay the host's. The policy decides what is
possible, not what it is called.

## Events in, feedback out

The gateway dispatches composed, bubbling `CustomEvent`s on its container:

- `xwui-auth-gateway:password-submit` - identity and password.
- `xwui-auth-gateway:otp-request` - the contact (and password, under
  `otpWithPassword`).
- `xwui-auth-gateway:otp-verify` - the entered code.
- `xwui-auth-gateway:otp-resend` - a resend request.

The host answers by calling back into the component: `setError(message)`,
`setSuccess(message)`, `setOtpHint(message)` and the generic
`setFeedback(message, variant)` for inline feedback, and
`showOtpCodeStage(contact)` / `resetOtpStage()` to move between the contact and
code stages. Pass `null` to clear a message.

Never put a secret in the feedback copy, and never decide success in the
component: the only thing that knows whether a credential was accepted is the
server that checked it.

## Configuration surface

Beyond `policy` and `policyUnsupportedText`:

- Mode: `modes`, `defaultMode`, `modeSwitcher` (`tabs` via `XWUINavTabs` or
  `toggle` via `XWUIToggleGroup`), `modeTabsVariant`, `passwordModeLabel`,
  `otpModeLabel`, `passwordModeIcon`, `otpModeIcon`.
- Password form: `passwordIdentityLabel` / `passwordIdentityPlaceholder`,
  `passwordLabel`, `passwordSubmitLabel`, `passwordSubmitIcon`,
  `passwordIdentityLeadingIcon`, `passwordLeadingIcon`, `passwordRequiredText`,
  `passwordFormLabel` (the form's accessible name).
- OTP form: `otpContactKind` (`phone`, `email` or `either`), `otpEmailLabel`,
  `otpPhoneLabel`, `otpPhoneKindLabel` / `otpEmailKindLabel`, `otpLength`,
  `otpSendLabel`, `otpVerifyLabel`, `otpResendLabel`, `otpSubmitIcon`,
  `otpContactInvalidText`, `otpCodeIncompleteText`, `otpRequestFormLabel` /
  `otpVerifyFormLabel`, plus `otpWithPassword`, `otpPasswordLabel` and
  `otpPasswordRequiredText`.
- Phone input: `phoneDefaultCountry`, `phoneAllowedCountries` (set from
  `policy.regions` when a policy is given).
- Footer: `showRegisterLink`, `registerHref`, `registerLinkIcon`,
  `footerLayout` (`inline` or `center`).

`data` carries the visible strings the host owns: `registerLinkPrefix`,
`registerLinkLabel`, `errorText`, `otpHintText`, `otpSentToPrefix`.

## Showcase

Dual password and OTP modes with tab or toggle switchers, single-mode setups,
the OTP contact kinds and code lengths, the inline feedback API, the two-stage
OTP flow, and a live panel printing the events a host listens for.

```example
file: examples/Showcase.ts
html: examples/Showcase.html
title: Showcase
description: Both sign-in modes, the feedback API, and a live event log.
```

```api
```