@owlmeans/web-auth-email 0.0.0-stage → 0.1.19

package/src/components/panel.tsx

@@ -0,0 +1,299 @@
+import { useId, useState, type FC, type FormEvent } from 'react'
+import { Loader2 } from 'lucide-react'
+import { EMAIL_PASSWORD_MAX_LENGTH, EMAIL_PIN_LENGTH } from '@owlmeans/auth-email'
+import { Button } from '../@/components/ui/button.js'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../@/components/ui/card.js'
+import { Label } from '../@/components/ui/label.js'
+import { cn } from '../@/lib/utils.js'
+import { passwordPanelHelper } from '../password.js'
+import { textUtils } from '../utils/text.js'
+import type { EmailPasswordAction } from '../password/types.js'
+import type { EmailRefusal } from '../refusal/types.js'
+import type { Translate } from '../types.js'
+import { PasswordInput, PinInput, RefusalAlert, SubmitButton } from './fields.js'
+import type { PasswordPanelProps } from './types.js'
+
+const english: Translate = (_key, defaultValue) => defaultValue
+
+/** A record's moment in the reader's language, or null when it has none worth showing. */
+const dateOf = (value: string | undefined, locale?: string): string | null => {
+  if (value == null) {
+    return null
+  }
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) {
+    return null
+  }
+  try {
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(date)
+  } catch {
+    return date.toISOString().slice(0, 10)
+  }
+}
+
+/**
+ * The account's password: off on this deployment (a short notice), none yet (Set), or one (Change,
+ * Remove). Every action is confirmed by a PIN mailed to the account's own address: "Send code",
+ * then the code (and the new password, twice, for set and change), then Confirm.
+ *
+ * Presentational by contract — it performs no I/O, renders what it is given and reports what was
+ * pressed. `ConnectedPasswordPanel` is this panel wired to `usePassword`.
+ */
+export const PasswordPanel: FC<PasswordPanelProps> = ({
+  status, loading = false, busy = false, pending = null, refusal = null, done = null,
+  onSendPin, onConfirm, onCancel, onReload, title, description, translate, locale, className,
+}) => {
+  const t = translate ?? english
+  const id = useId()
+  const [action, setAction] = useState<EmailPasswordAction | null>(null)
+  const [pin, setPin] = useState('')
+  const [password, setPassword] = useState('')
+  const [repeat, setRepeat] = useState('')
+  const [reveal, setReveal] = useState(false)
+  const [local, setLocal] = useState<EmailRefusal | null>(null)
+
+  const state = passwordPanelHelper.stateOf(status, loading)
+  const actions = passwordPanelHelper.actionsOf(status)
+  const sent = action != null && pending === passwordPanelHelper.purposeOf(action)
+  const withPassword = action != null && passwordPanelHelper.needsPassword(action)
+  const shown = local ?? refusal
+
+  const reset = (): void => {
+    setAction(null)
+    setPin('')
+    setPassword('')
+    setRepeat('')
+    setReveal(false)
+    setLocal(null)
+  }
+
+  const open = (next: EmailPasswordAction): void => {
+    reset()
+    setAction(next)
+    if (pending != null) {
+      onCancel()
+    }
+  }
+
+  const close = (): void => {
+    reset()
+    onCancel()
+  }
+
+  const send = async (): Promise<void> => {
+    if (action == null || busy) {
+      return
+    }
+    setLocal(null)
+    setPin('')
+    await onSendPin(passwordPanelHelper.purposeOf(action))
+  }
+
+  const submit = async (event: FormEvent): Promise<void> => {
+    event.preventDefault()
+    if (action == null || busy) {
+      return
+    }
+    if (!sent) {
+      await send()
+      return
+    }
+    const block = passwordPanelHelper.confirmBlock(action, { pin, password, repeat })
+    if (block != null) {
+      setLocal(block)
+      return
+    }
+    setLocal(null)
+    if (await onConfirm(action, withPassword ? { pin, password } : { pin })) {
+      reset()
+    }
+  }
+
+  const updated = state === 'set' ? dateOf(status?.updatedAt, locale) : null
+  const control = 'h-11 text-base'
+
+  const summary = (() => {
+    switch (state) {
+      case 'loading':
+        return <p role="status" className="flex items-center gap-2 text-sm text-muted-foreground">
+          <Loader2 className="size-4 animate-spin" aria-hidden />
+          {t('password.loading', 'Loading…')}
+        </p>
+      case 'unreadable':
+        return <div className="flex flex-col items-start gap-1 text-sm">
+          <p className="text-destructive">{t('password.unreadable', "We couldn't load your password settings.")}</p>
+          {onReload != null && <Button
+            type="button" variant="link" data-email-password-retry className="h-11 px-0"
+            onClick={() => void onReload()}
+          >
+            {t('password.retry', 'Try again')}
+          </Button>}
+        </div>
+      case 'off':
+        return <p data-email-password-notice className="text-sm text-muted-foreground">
+          {t('password.off', 'Password sign-in is not available here. Sign in with a code sent to your email.')}
+        </p>
+      case 'unset':
+        return <p className="text-sm">
+          {t('password.unset', "You don't have a password yet. You sign in with a code sent to your email.")}
+        </p>
+      default:
+        return <p className="text-sm">
+          {t('password.set', 'You have a password.')}
+          {updated != null && <> {textUtils.fill(t('password.updated', 'Last changed {{date}}.'), { date: updated })}</>}
+        </p>
+    }
+  })()
+
+  return <Card data-email-password-panel data-state={state} className={className}>
+    <CardHeader>
+      <CardTitle>{title ?? t('password.title', 'Password')}</CardTitle>
+      <CardDescription>
+        {description ?? t('password.description', 'Sign in with your email and a password instead of a code.')}
+      </CardDescription>
+    </CardHeader>
+
+    <CardContent className="flex flex-col gap-4">
+      {summary}
+
+      {done != null && action == null && <p role="status" data-email-password-success={done} className="text-sm">
+        {done === 'remove'
+          ? t('password.done.remove', 'Your password has been removed.')
+          : done === 'change'
+            ? t('password.done.change', 'Your password has been changed.')
+            : t('password.done.set', 'Your password has been set.')}
+        {' '}
+        {t('password.devices', 'Other devices will need a code the next time they sign in.')}
+      </p>}
+
+      {action == null && actions.length > 0 && <div className="flex flex-col gap-2 sm:flex-row">
+        {actions.map(next => <Button
+          key={next}
+          type="button"
+          variant="outline"
+          data-email-password-action={next}
+          className={cn(control, next === 'remove' && 'text-destructive hover:text-destructive')}
+          onClick={() => open(next)}
+        >
+          {next === 'remove'
+            ? t('password.action.remove', 'Remove password')
+            : next === 'change'
+              ? t('password.action.change', 'Change password')
+              : t('password.action.set', 'Set a password')}
+        </Button>)}
+      </div>}
+
+      {action != null && <form
+        noValidate
+        data-email-password-form={action}
+        data-sent={sent ? 'true' : undefined}
+        className="flex flex-col gap-4"
+        onSubmit={event => void submit(event)}
+      >
+        <p className="text-sm text-muted-foreground">
+          {action === 'remove'
+            ? t('password.explain.remove', "Without a password you sign in with a code sent to your email. We'll email you a code to confirm.")
+            : action === 'change'
+              ? t('password.explain.change', "To change your password, confirm it's you with a code we'll email you.")
+              : t('password.explain.set', "To set a password, confirm it's you with a code we'll email you.")}
+        </p>
+
+        {sent && <>
+          <p role="status" data-email-password-sent className="text-sm">
+            {t('password.sent', 'We sent a code to your email.')}
+          </p>
+          <div className="flex flex-col gap-2">
+            <Label htmlFor={`${id}-pin`}>{t('password.pin-label', 'Code from the email')}</Label>
+            <PinInput
+              id={`${id}-pin`}
+              name="pin"
+              data-email-password-pin
+              length={EMAIL_PIN_LENGTH}
+              value={pin}
+              readOnly={busy}
+              autoFocus
+              aria-invalid={shown?.kind === 'code' || shown?.kind === 'pin-format' || undefined}
+              className="max-w-60"
+              onChange={event => { setPin(event.target.value.replace(/\D/g, '').slice(0, EMAIL_PIN_LENGTH)); setLocal(null) }}
+            />
+          </div>
+          {withPassword && <>
+            <div className="flex flex-col gap-2">
+              <Label htmlFor={`${id}-new`}>{t('password.new-label', 'New password')}</Label>
+              <PasswordInput
+                id={`${id}-new`}
+                name="new-password"
+                data-email-password-new
+                autoComplete="new-password"
+                maxLength={EMAIL_PASSWORD_MAX_LENGTH}
+                value={password}
+                readOnly={busy}
+                aria-invalid={shown?.kind === 'weak' || shown?.kind === 'password-empty' || undefined}
+                reveal={reveal}
+                onReveal={setReveal}
+                showLabel={t('login.show-password', 'Show password')}
+                hideLabel={t('login.hide-password', 'Hide password')}
+                toggleProps={{ 'data-email-password-toggle': '' }}
+                onChange={event => { setPassword(event.target.value); setLocal(null) }}
+              />
+            </div>
+            <div className="flex flex-col gap-2">
+              <Label htmlFor={`${id}-repeat`}>{t('password.repeat-label', 'Repeat the password')}</Label>
+              <PasswordInput
+                id={`${id}-repeat`}
+                name="repeat-password"
+                data-email-password-repeat
+                autoComplete="new-password"
+                maxLength={EMAIL_PASSWORD_MAX_LENGTH}
+                value={repeat}
+                readOnly={busy}
+                aria-invalid={shown?.kind === 'mismatch' || undefined}
+                reveal={reveal}
+                onReveal={setReveal}
+                showLabel={t('login.show-password', 'Show password')}
+                hideLabel={t('login.hide-password', 'Hide password')}
+                onChange={event => { setRepeat(event.target.value); setLocal(null) }}
+              />
+            </div>
+          </>}
+        </>}
+
+        <RefusalAlert refusal={shown} t={t} locale={locale} marker="data-email-password-error" className="text-left" />
+
+        <div className="flex flex-col gap-2 sm:flex-row">
+          {sent
+            ? <SubmitButton
+              data-email-password-confirm
+              busy={busy}
+              blocked={passwordPanelHelper.confirmBlock(action, { pin, password, repeat }) != null}
+              className="sm:w-auto"
+            >
+              {busy ? t('password.confirming', 'Saving…') : t('password.confirm', 'Confirm')}
+            </SubmitButton>
+            : <SubmitButton data-email-password-send busy={busy} className="sm:w-auto">
+              {busy ? t('password.sending', 'Sending…') : t('password.send', 'Send code')}
+            </SubmitButton>}
+          {sent && <Button
+            type="button"
+            variant="link"
+            data-email-password-resend
+            aria-disabled={busy || undefined}
+            className={control}
+            onClick={() => void send()}
+          >
+            {t('password.resend', 'Send a new code')}
+          </Button>}
+          <Button
+            type="button"
+            variant="ghost"
+            data-email-password-cancel
+            className={control}
+            onClick={close}
+          >
+            {t('password.cancel', 'Cancel')}
+          </Button>
+        </div>
+      </form>}
+    </CardContent>
+  </Card>
+}

package/src/components/route.tsx

@@ -0,0 +1,20 @@
+import type { FC } from 'react'
+import { useContext } from '@owlmeans/client'
+import type { AuthenticationRendererProps } from '@owlmeans/client-auth/manager'
+import { EMAIL_LOGIN_SERVICE } from '@owlmeans/auth-email'
+import type { EmailLoginClientService } from '../types.js'
+import { LocalizedEmailLoginScreen } from './screen.js'
+
+/**
+ * What the e-mail method's authentication route renders: the screen registered for this context
+ * (`appendEmailLogin({ screen })`, or a replacement from `registerEmailLoginScreen`), else the
+ * package's own.
+ */
+export const EmailLoginRoute: FC<Partial<AuthenticationRendererProps>> = () => {
+  const ctx = useContext()
+  const Screen = ctx.hasService(EMAIL_LOGIN_SERVICE)
+    ? ctx.service<EmailLoginClientService>(EMAIL_LOGIN_SERVICE).screen() ?? LocalizedEmailLoginScreen
+    : LocalizedEmailLoginScreen
+
+  return <Screen />
+}

package/src/components/screen.tsx

@@ -0,0 +1,253 @@
+import { isValidElement, useId, type FC, type FormEvent } from 'react'
+import { Loader2 } from 'lucide-react'
+import { useLanguage } from '@owlmeans/client-i18n'
+import { EMAIL_ADDRESS_MAX_LENGTH } from '@owlmeans/auth-email'
+import { Button } from '../@/components/ui/button.js'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../@/components/ui/card.js'
+import { Input } from '../@/components/ui/input.js'
+import { Label } from '../@/components/ui/label.js'
+import { cn } from '../@/lib/utils.js'
+import { useEmailLogin } from '../hooks/use-email-login.js'
+import { useEmailAuthTranslate } from '../hooks/use-translate.js'
+import { emailLoginStateHelper } from '../state.js'
+import { textUtils } from '../utils/text.js'
+import type { EmailLoginScreenProps, Translate } from '../types.js'
+import { CaptchaNotice, PasswordInput, PinInput, RefusalAlert, SubmitButton } from './fields.js'
+import { EmailLoginCredit } from './credit.js'
+
+const english: Translate = (_key, defaultValue) => defaultValue
+
+/**
+ * The e-mail sign-in card — the chooser card's twin (`@owlmeans/web-panel`'s `LoginScreen`): the
+ * same centred card, logo, title, subtitle and footer slot, the same inline viewport height.
+ *
+ * Three steps share it: the address ("Receive authentication PIN code"), the mailed PIN, and — only
+ * where the deployment offers passwords — the address with a password. Enter submits the step on
+ * screen. Nothing on it is ever natively `disabled`.
+ *
+ * Pure with respect to i18n: `translate` is a prop (English without it), `locale` too.
+ * `LocalizedEmailLoginScreen` binds both to the application's own.
+ */
+export const EmailLoginScreen: FC<EmailLoginScreenProps> = props => {
+  const t = props.translate ?? english
+  const model = useEmailLogin({ locale: props.locale })
+  const { state } = model
+  const id = useId()
+  const busy = state.busy != null
+  const Logo = props.Logo
+
+  const onSubmit = (event: FormEvent): void => {
+    event.preventDefault()
+    void model.submit()
+  }
+
+  const subtitle = props.subtitle ?? (state.step === 'password'
+    ? t('login.password-subtitle', 'Sign in with your email and password.')
+    : state.step === 'pin'
+      ? t('login.pin-subtitle', 'Check your inbox for the code.')
+      : t('login.subtitle', "We'll email you a code to sign in. New here? The same code creates your account."))
+
+  const emailField = (autoFocus: boolean) => <div className="flex flex-col gap-2 text-left">
+    <Label htmlFor={`${id}-email`}>{t('login.email-label', 'Email')}</Label>
+    <Input
+      id={`${id}-email`}
+      name="email"
+      data-email-login-email
+      type="email"
+      inputMode="email"
+      autoComplete="username"
+      autoCapitalize="none"
+      autoCorrect="off"
+      spellCheck={false}
+      maxLength={EMAIL_ADDRESS_MAX_LENGTH}
+      placeholder={t('login.email-placeholder', 'you@example.com')}
+      value={state.email}
+      readOnly={busy}
+      autoFocus={autoFocus}
+      aria-invalid={state.refusal?.kind === 'email' || undefined}
+      className="h-11 text-base"
+      onChange={event => model.setEmail(event.target.value)}
+    />
+  </div>
+
+  const link = 'h-11 px-2 text-sm'
+  // A tertiary button: no fill and no visible border until hovered, the primary text colour kept.
+  const tertiary = 'h-11 px-3 text-sm text-primary border border-transparent hover:border-border hover:text-primary'
+
+  const step = (() => {
+    switch (state.step) {
+      case 'pin':
+        return <form noValidate onSubmit={onSubmit} data-email-login-form="pin" className="flex flex-col gap-4">
+          <p role="status" data-email-login-notice={state.notice ?? 'sent'} className="text-center text-sm">
+            {state.notice === 'device'
+              ? t('login.device', "We don't recognise this device. Enter the code we sent to your email.")
+              : textUtils.fill(t('login.sent', 'We sent a sign-in code to {{email}}.'), {
+                email: emailLoginStateHelper.normalizeEmail(state.email),
+              })}
+          </p>
+          <div className="flex flex-col gap-2 text-left">
+            <Label htmlFor={`${id}-pin`}>{t('login.pin-label', 'Code from the email')}</Label>
+            <PinInput
+              id={`${id}-pin`}
+              name="pin"
+              data-email-login-pin
+              length={model.pinLength}
+              value={state.pin}
+              readOnly={busy}
+              autoFocus
+              aria-invalid={state.refusal?.kind === 'code' || state.refusal?.kind === 'pin-format' || undefined}
+              onChange={event => model.setPin(event.target.value)}
+            />
+          </div>
+          <SubmitButton
+            data-email-login-submit
+            data-mode="pin"
+            busy={state.busy === 'sign-in'}
+            blocked={emailLoginStateHelper.verifyBlock(state) != null}
+          >
+            {state.busy === 'sign-in' ? t('login.verifying', 'Signing in…') : t('login.verify', 'Sign in')}
+          </SubmitButton>
+          <div className="flex flex-col items-center justify-center gap-1 sm:flex-row sm:gap-4">
+            <Button
+              type="button"
+              variant="link"
+              data-email-login-resend
+              aria-busy={state.busy === 'send' || undefined}
+              className={link}
+              onClick={() => void model.send()}
+            >
+              {state.busy === 'send' ? t('login.sending', 'Sending…') : t('login.resend', 'Send a new code')}
+            </Button>
+            <Button type="button" variant="link" data-email-login-change className={link} onClick={model.changeEmail}>
+              {t('login.change-email', 'Change email')}
+            </Button>
+          </div>
+        </form>
+
+      case 'password':
+        return <form noValidate onSubmit={onSubmit} data-email-login-form="password" className="flex flex-col gap-4">
+          {emailField(false)}
+          <div className="flex flex-col gap-2 text-left">
+            <Label htmlFor={`${id}-password`}>{t('login.password-label', 'Password')}</Label>
+            <PasswordInput
+              id={`${id}-password`}
+              name="password"
+              data-email-login-password
+              autoComplete="current-password"
+              value={state.password}
+              readOnly={busy}
+              autoFocus
+              aria-invalid={state.refusal?.kind === 'credentials' || state.refusal?.kind === 'password-empty'
+                || undefined}
+              reveal={state.reveal}
+              onReveal={model.setReveal}
+              showLabel={t('login.show-password', 'Show password')}
+              hideLabel={t('login.hide-password', 'Hide password')}
+              toggleProps={{ 'data-email-login-password-toggle': '' }}
+              onChange={event => model.setPassword(event.target.value)}
+            />
+          </div>
+          <SubmitButton
+            data-email-login-submit
+            data-mode="password"
+            busy={state.busy === 'sign-in'}
+            blocked={emailLoginStateHelper.signInBlock(state) != null}
+          >
+            {state.busy === 'sign-in' ? t('login.verifying', 'Signing in…') : t('login.password-submit', 'Sign in')}
+          </SubmitButton>
+          <Button type="button" variant="link" data-email-login-use-pin className={link} onClick={model.choosePin}>
+            {t('login.use-pin', 'Sign in with a code instead')}
+          </Button>
+        </form>
+
+      case 'done':
+        return <p role="status" data-email-login-done className="flex items-center justify-center gap-2 text-sm">
+          <Loader2 className="size-4 animate-spin" aria-hidden />
+          {t('login.done', 'Signing you in…')}
+        </p>
+
+      default:
+        return <form noValidate onSubmit={onSubmit} data-email-login-form="email" className="flex flex-col gap-4">
+          {emailField(true)}
+          <SubmitButton
+            data-email-login-send
+            busy={state.busy === 'send'}
+            blocked={emailLoginStateHelper.sendBlock(state) != null}
+          >
+            {state.busy === 'send' ? t('login.sending', 'Sending…') : t('login.send', 'Receive authentication PIN code')}
+          </SubmitButton>
+          {model.passwordOffered && <Button
+            type="button"
+            variant="ghost"
+            data-email-login-use-password
+            className={tertiary}
+            onClick={model.choosePassword}
+          >
+            {t('login.use-password', 'Already set a password? Use it')}
+          </Button>}
+        </form>
+    }
+  })()
+
+  const card = <Card data-email-login-card className={cn('w-full max-w-sm', props.containerClassName)}>
+    <CardHeader className="items-center gap-2 text-center">
+      {Logo != null && <div className="flex justify-center pb-2">
+        {isValidElement(Logo) ? Logo : typeof Logo === 'function' ? <Logo className="h-10 w-auto" /> : Logo}
+      </div>}
+      <CardTitle className="text-xl">{props.title ?? t('login.title', 'Sign in with email')}</CardTitle>
+      <CardDescription>{subtitle}</CardDescription>
+    </CardHeader>
+
+    <CardContent className="flex flex-col gap-4">
+      {step}
+
+      <RefusalAlert refusal={state.refusal} t={t} locale={props.locale} marker="data-email-login-error" />
+
+      {state.optionsFailed && state.options == null && state.refusal == null
+        && <div data-email-login-options-error className="flex flex-col items-center gap-1 text-center text-sm">
+          <p role="alert" className="text-destructive">
+            {t('login.options-failed', "We couldn't load the sign-in settings.")}
+          </p>
+          <Button type="button" variant="link" data-email-login-retry className={link} onClick={() => void model.retryOptions()}>
+            {t('login.retry', 'Try again')}
+          </Button>
+        </div>}
+
+      {model.captcha && state.step !== 'pin' && state.step !== 'done' && <CaptchaNotice t={t} />}
+
+      {model.otherOptions != null && state.step !== 'done' && <a
+        href={model.otherOptions.href}
+        data-email-login-other
+        className="inline-flex h-11 items-center justify-center text-sm text-muted-foreground underline-offset-4 hover:text-foreground hover:underline"
+        onClick={model.otherOptions.go}
+      >
+        {t('login.other', 'Other sign-in options')}
+      </a>}
+    </CardContent>
+
+    <div className="px-6">
+      {props.footer ?? <EmailLoginCredit t={t} />}
+    </div>
+  </Card>
+
+  // The viewport height is INLINE, like the chooser's: this screen is rendered straight out of the
+  // authentication route into a chain that carries no height, and a utility class new to the
+  // consumer's stylesheet is exactly what a stale `@source` scan drops. `props.style` still wins.
+  return <div
+    data-email-login-screen
+    data-step={state.step}
+    data-busy={state.busy ?? undefined}
+    style={{ minHeight: '100dvh', ...props.style }}
+    className={cn('flex w-full items-center justify-center p-4', props.className)}
+  >
+    {card}
+  </div>
+}
+
+/** {@link EmailLoginScreen} bound to the application's own translations and language. */
+export const LocalizedEmailLoginScreen: FC<EmailLoginScreenProps> = props => {
+  const t = useEmailAuthTranslate()
+  const [lng] = useLanguage()
+
+  return <EmailLoginScreen {...props} translate={props.translate ?? t} locale={props.locale ?? lng} />
+}

package/src/components/types.ts

@@ -0,0 +1,85 @@
+import type { ComponentProps, ReactNode } from 'react'
+import type { EmailPasswordPurpose, EmailPasswordStatusView } from '@owlmeans/auth-email'
+import type { EmailRefusal } from '../refusal/types.js'
+import type { EmailPasswordAction } from '../password/types.js'
+import type { EmailPasswordAliases, Translate } from '../types.js'
+
+/** A password field with a show/hide toggle; every other prop goes to the `<input>`. */
+export interface PasswordInputProps extends Omit<ComponentProps<'input'>, 'type'> {
+  reveal: boolean
+  onReveal: (value: boolean) => void
+  /** The toggle's accessible name while the password is hidden. */
+  showLabel: string
+  /** The toggle's accessible name while the password is shown. */
+  hideLabel: string
+  /** `data-*` hooks for the toggle button. */
+  toggleProps?: Record<`data-${string}`, string>
+}
+
+/** A PIN field: digits only, the one-time-code autofill, as many characters as the PIN has. */
+export interface PinInputProps extends Omit<ComponentProps<'input'>, 'type' | 'inputMode' | 'autoComplete' | 'maxLength'> {
+  length: number
+}
+
+/** A primary submit button that is never natively `disabled` — see the screen. */
+export interface SubmitButtonProps extends ComponentProps<'button'> {
+  busy: boolean
+  /** The action cannot go yet; pressing it says why (`aria-disabled`, never `disabled`). */
+  blocked?: boolean
+}
+
+export interface RefusalAlertProps {
+  refusal: EmailRefusal | null
+  t: Translate
+  locale?: string
+  /** The `data-*` attribute that marks this alert for tests (`data-email-login-error`, …). */
+  marker: `data-${string}`
+  className?: string
+}
+
+export interface CaptchaNoticeProps {
+  t: Translate
+  className?: string
+}
+
+export interface EmailLoginCreditProps {
+  t: Translate
+  className?: string
+}
+
+/**
+ * The password surface, as a function of what it is given — no I/O: it renders what it is handed
+ * and reports what was pressed. `ConnectedPasswordPanel` is this panel wired to `usePassword`.
+ */
+export interface PasswordPanelProps {
+  status: EmailPasswordStatusView | null
+  loading?: boolean
+  /** A PIN request or a confirmation is in flight. */
+  busy?: boolean
+  /** The purpose a confirmation PIN was mailed for; the panel shows the PIN step while it is set. */
+  pending?: EmailPasswordPurpose | null
+  refusal?: EmailRefusal | null
+  /** The last action that went through. */
+  done?: EmailPasswordAction | null
+  /** Mail a confirmation PIN. Resolves whether it was sent. */
+  onSendPin: (purpose: EmailPasswordPurpose) => Promise<boolean>
+  /** Confirm the open action. Resolves whether it went through; the panel closes the action then. */
+  onConfirm: (action: EmailPasswordAction, input: { pin: string, password?: string }) => Promise<boolean>
+  /** The open action was abandoned. */
+  onCancel: () => void
+  /** Read the status again after it could not be read. */
+  onReload?: () => Promise<void> | void
+  /** Already-translated header copy; the package's own by default. */
+  title?: ReactNode
+  description?: ReactNode
+  translate?: Translate
+  locale?: string
+  className?: string
+}
+
+export interface ConnectedPasswordPanelProps extends Pick<PasswordPanelProps, 'title' | 'description' | 'className'> {
+  /** Where the password routes are mounted; see `EmailPasswordAliases`. */
+  aliases?: EmailPasswordAliases
+  /** Overrides the package's own translator. */
+  translate?: Translate
+}