@design.estate/dees-catalog 3.97.1 → 3.98.0

package/ts_web/elements/00group-simple/dees-simple-login/dees-simple-login.ts

@@ -5,12 +5,18 @@ import {
   html,
   DeesElement,
   property,
+  state,
   type TemplateResult,
   cssManager,
   css,
 } from '@design.estate/dees-element';
 import { themeDefaultStyles } from '../../00theme.js';
 import '../../00group-layout/dees-tile/dees-tile.js';
+import '../../00group-button/dees-button/dees-button.js';
+import '../../00group-form/dees-form/dees-form.js';
+import '../../00group-form/dees-form-submit/dees-form-submit.js';
+import '../../00group-input/dees-input-text/dees-input-text.js';
+import '../../00group-utility/dees-icon/dees-icon.js';
 
 declare global {
   interface HTMLElementTagNameMap {
@@ -18,16 +24,234 @@ declare global {
   }
 }
 
+/**
+ * The authentication methods this component can offer.
+ * A method is offered when it is configured — see `passkey`, `providers` and `password`.
+ */
+export type TDeesLoginMethod = 'passkey' | 'provider' | 'password';
+
+/**
+ * Passkey ceremonies are two different things and need two different affordances:
+ * `authenticate` signs in with an existing credential, `register` enrolls a new one.
+ */
+export type TDeesLoginPasskeyIntent = 'authenticate' | 'register';
+
+/**
+ * `optional` is a user-initiated ceremony (an explicit button press).
+ * `conditional` is the browser's passkey autofill, started silently on mount.
+ */
+export type TDeesLoginMediation = 'optional' | 'conditional';
+
+/**
+ * One "sign in with …" button.
+ * Icons are consumer-supplied on purpose: the catalog carries no third-party brand assets.
+ */
+export interface IDeesLoginProvider {
+  /** stable identifier handed back to the consumer, e.g. an OIDC provider id */
+  id: string;
+  /** display name, rendered as "<providerPrefix> <label>" */
+  label: string;
+  /** dees-icon name — Lucide only, e.g. 'lucide:keyRound'. The `fa:` prefix is unsupported. */
+  icon?: string;
+  /** optional second line under the label */
+  description?: string;
+  /** disables this single provider without removing it */
+  disabled?: boolean;
+}
+
+/**
+ * Addresses one interactive affordance for busy/error purposes.
+ * A bare `TDeesLoginMethod` is accepted wherever a target is expected.
+ */
+export interface IDeesLoginTarget {
+  method: TDeesLoginMethod;
+  /** passkey only — defaults to 'authenticate' */
+  intent?: TDeesLoginPasskeyIntent;
+  /** provider only — omit to address the provider group as a whole */
+  providerId?: string;
+}
+
+/** Copy overrides. Every field falls back to the built-in default. */
+export interface IDeesLoginLabels {
+  heading?: string;
+  subheading?: string;
+  passkeyAuthenticate?: string;
+  passkeyRegister?: string;
+  /** prefixed to every provider label; set to '' to render bare provider labels */
+  providerPrefix?: string;
+  credentialsHeading?: string;
+  passwordSubmit?: string;
+  usernameLabel?: string;
+  passwordLabel?: string;
+  divider?: string;
+  unavailable?: string;
+}
+
+/** Resolved browser capability for passkeys. */
+export interface IDeesLoginPasskeySupport {
+  /** WebAuthn is usable at all — secure context plus PublicKeyCredential */
+  available: boolean;
+  /** browser can run `navigator.credentials.get({ mediation: 'conditional' })` */
+  conditionalMediation: boolean;
+  /** a user-verifying platform authenticator exists (informational — never a gate) */
+  platformAuthenticator: boolean;
+}
+
+export interface IDeesLoginPasskeyContext {
+  intent: TDeesLoginPasskeyIntent;
+  /** current value of the username field, when the password method renders one */
+  username: string | undefined;
+  mediation: TDeesLoginMediation;
+  /** aborted when the element disconnects or another ceremony supersedes this one */
+  signal: AbortSignal;
+}
+
+export interface IDeesLoginProviderContext {
+  providerId: string;
+  provider: IDeesLoginProvider;
+}
+
+export interface IDeesLoginPasswordContext {
+  data: Record<string, unknown>;
+}
+
+export type TDeesLoginPasskeyHandler = (
+  contextArg: IDeesLoginPasskeyContext,
+) => unknown | Promise<unknown>;
+
+export type TDeesLoginProviderHandler = (
+  contextArg: IDeesLoginProviderContext,
+) => unknown | Promise<unknown>;
+
+export type TDeesLoginPasswordHandler = (
+  contextArg: IDeesLoginPasswordContext,
+) => unknown | Promise<unknown>;
+
+const canonicalMethodOrder: TDeesLoginMethod[] = ['passkey', 'provider', 'password'];
+
+/**
+ * dees-simple-login — the login surface for an application shell.
+ *
+ * Offers up to three authentication methods in one card: passkeys, identity providers
+ * ("sign in with …") and a username/password form. A method is offered only when it is
+ * configured, so the zero-configuration default is the password form alone.
+ *
+ * ## Who owns the WebAuthn ceremony
+ *
+ * Not this component. A passkey ceremony needs server-issued options and server-side
+ * verification, so the catalog deliberately carries no WebAuthn dependency and no
+ * knowledge of any wire protocol. There are two ways to plug a ceremony in, and exactly
+ * one of them is active per interaction:
+ *
+ * 1. **Event mode** (no handler set) — the component dispatches `passkey-login`,
+ *    `passkey-register` or `provider-login` and stops. The consumer drives everything and
+ *    reports progress back through `setBusy()` / `reportError()`.
+ * 2. **Handler mode** (handler property set) — the component awaits the handler, owns the
+ *    per-method busy state and turns a rejection into that method's error message. The
+ *    request event is *not* dispatched, so a ceremony can never be started twice.
+ *
+ * The legacy `login` event is a notification rather than a request and always fires, even
+ * when `passwordLoginHandler` is set. Do not both listen to `login` and set that handler.
+ *
+ * ## Shadow DOM contract
+ *
+ * Consumers reach into this shadow root: `.loginContainer`, `.login` and `.slotContainer`
+ * carry the post-login transition, and `shadowRoot.querySelector('dees-form')` is expected
+ * to be the password form. Those are load-bearing and must not be renamed, and no second
+ * `dees-form` may precede the password form.
+ */
 @customElement('dees-simple-login')
 export class DeesSimpleLogin extends DeesElement {
   // STATIC
   public static demo = demoFunc;
   public static demoGroups = ['Simple'];
+
   // INSTANCE
 
+  /** application name, interpolated into the default subheading */
   @property()
   accessor name: string = 'Application';
 
+  /**
+   * offer a passkey affordance. Silently drops out when the browser cannot do WebAuthn,
+   * unless it is the only configured method — then the card explains itself instead of
+   * rendering empty.
+   */
+  @property({ type: Boolean })
+  accessor passkey: boolean = false;
+
+  /** which passkey affordances to render, in this order */
+  @property({ attribute: false })
+  accessor passkeyIntents: TDeesLoginPasskeyIntent[] = ['authenticate'];
+
+  /**
+   * overrides browser capability detection. `undefined` detects automatically; set it when
+   * the server already knows whether passkeys are configured for this deployment.
+   */
+  @property({ attribute: false })
+  accessor passkeyAvailable: boolean | undefined = undefined;
+
+  /**
+   * opt into WebAuthn conditional mediation (passkey autofill). Requires
+   * `passkeyLoginHandler` and a rendered password method — the username field is what the
+   * browser attaches its passkey picker to. Silently inert when either is missing.
+   */
+  @property({ type: Boolean })
+  accessor passkeyAutofill: boolean = false;
+
+  /** identity providers to offer. Empty means the provider method is not configured. */
+  @property({ attribute: false })
+  accessor providers: IDeesLoginProvider[] = [];
+
+  /** offer the username/password form. On by default — set `.password=${false}` to drop it. */
+  @property({ type: Boolean })
+  accessor password: boolean = true;
+
+  /**
+   * reorders the configured methods. Configured methods missing from this list are appended
+   * in canonical order, so an incomplete list can never silently hide a method.
+   */
+  @property({ attribute: false })
+  accessor methodOrder: TDeesLoginMethod[] = ['passkey', 'provider', 'password'];
+
+  /** copy overrides */
+  @property({ attribute: false })
+  accessor labels: IDeesLoginLabels = {};
+
+  /** drives the passkey sign-in ceremony — see "Who owns the WebAuthn ceremony" */
+  @property({ attribute: false })
+  accessor passkeyLoginHandler: TDeesLoginPasskeyHandler | undefined = undefined;
+
+  /** drives the passkey enrollment ceremony */
+  @property({ attribute: false })
+  accessor passkeyRegisterHandler: TDeesLoginPasskeyHandler | undefined = undefined;
+
+  /** drives a provider sign-in (redirect or popup) */
+  @property({ attribute: false })
+  accessor providerLoginHandler: TDeesLoginProviderHandler | undefined = undefined;
+
+  /** drives a credential sign-in. The legacy `login` event fires regardless. */
+  @property({ attribute: false })
+  accessor passwordLoginHandler: TDeesLoginPasswordHandler | undefined = undefined;
+
+  @state()
+  private accessor detectedPasskeySupport: IDeesLoginPasskeySupport = {
+    available: false,
+    conditionalMediation: false,
+    platformAuthenticator: false,
+  };
+
+  @state()
+  private accessor busyKeys: string[] = [];
+
+  @state()
+  private accessor errorMap: Record<string, string> = {};
+
+  private ceremonyControllers = new Map<string, AbortController>();
+  private autofillController: AbortController | undefined = undefined;
+  private autofillStarted = false;
+  private interactivityObserver: MutationObserver | undefined = undefined;
+
   public static styles = [
     themeDefaultStyles,
     cssManager.defaultStyles,
@@ -50,6 +274,11 @@ export class DeesSimpleLogin extends DeesElement {
         height: 100%;
         top: 0;
         left: 0;
+        box-sizing: border-box;
+        /* a card with passkey + several providers + credentials can outgrow a short
+           viewport, so the container scrolls instead of clipping */
+        padding: var(--dees-spacing-xl);
+        overflow-y: auto;
         background: var(--dees-color-bg-primary);
       }
 
@@ -87,8 +316,117 @@ export class DeesSimpleLogin extends DeesElement {
       }
 
       .subheader {
+        font-size: var(--dees-font-control-size);
+        /* secondary rather than muted: the tertiary label token is a 0.30 alpha and drops
+           under 2:1 against both backgrounds */
+        color: var(--dees-color-text-secondary);
+      }
+
+      .methods {
+        display: flex;
+        flex-direction: column;
+        gap: var(--dees-spacing-lg);
+      }
+
+      .method {
+        display: flex;
+        flex-direction: column;
+        gap: var(--dees-spacing-sm);
+      }
+
+      .methodActions {
+        display: flex;
+        flex-direction: column;
+        gap: var(--dees-spacing-sm);
+      }
+
+      /* Four or more providers would turn the card into a tower, so they pair up. The
+         labels lose their prefix at the same time — see denseProviders. */
+      .methodActions.dense {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+      }
+
+      /* an odd trailing provider spans the row instead of leaving a ragged half cell */
+      .methodActions.dense > :last-child:nth-child(odd) {
+        grid-column: 1 / -1;
+      }
+
+      /* dees-button's default pending face is a 20% accent tint with accent-coloured text,
+         which lands under 2:1 on a dark canvas. Each group therefore states a busy face in
+         its own emphasis instead: the primary action keeps its solid accent, and a provider
+         keeps its secondary surface so only the spinner changes. */
+      .passkeyActions dees-button {
+        --button-pending-bg: var(--dees-color-accent-primary);
+        --button-pending-fg: var(--dees-color-on-accent);
+        --dees-spinner-color: var(--dees-color-on-accent);
+      }
+
+      .providerActions dees-button {
+        --button-pending-bg: var(--dees-color-fill-secondary);
+        --button-pending-fg: var(--dees-color-text-primary);
+        --dees-spinner-color: var(--dees-color-text-primary);
+      }
+
+      .divider {
+        display: flex;
+        align-items: center;
+        gap: var(--dees-spacing-md);
+        font-size: var(--dees-font-control-size-sm);
+        color: var(--dees-color-text-secondary);
+        text-transform: lowercase;
+      }
+
+      .divider::before,
+      .divider::after {
+        content: '';
+        flex: 1;
+        height: 1px;
+        background: var(--dees-color-border-subtle);
+      }
+
+      .methodError {
+        display: flex;
+        align-items: flex-start;
+        gap: var(--dees-spacing-xs);
+        font-size: var(--dees-font-control-size-sm);
+        line-height: 1.4;
+        color: var(--dees-color-text-error);
+        user-select: text;
+      }
+
+      .methodError dees-icon {
+        flex-shrink: 0;
+        margin-top: 1px;
+      }
+
+      .unavailable {
+        padding: var(--dees-spacing-lg);
+        border: 1px solid var(--dees-color-border-subtle);
+        border-radius: var(--dees-radius-xl);
+        corner-shape: var(--dees-corner-shape);
+        background: var(--dees-color-bg-secondary);
         font-size: var(--dees-font-control-size);
         color: var(--dees-color-text-muted);
+        text-align: center;
+      }
+
+      /* The bare credentials block, used whenever the card already offers another method.
+         A nested tile there would inset the fields 24px against full-width buttons above
+         it and add a second frame inside the card. */
+      .credentials {
+        display: flex;
+        flex-direction: column;
+        gap: var(--dees-spacing-lg);
+      }
+
+      .credentials dees-input-text {
+        width: 100%;
+      }
+
+      .credentials dees-form-submit {
+        margin-top: var(--dees-spacing-sm);
+        width: 100%;
       }
 
       dees-tile {
@@ -116,21 +454,171 @@ export class DeesSimpleLogin extends DeesElement {
     `,
   ];
 
+  // ------------------------------------------------------------------------------------
+  // resolution
+  // ------------------------------------------------------------------------------------
+
+  /** resolved browser capability, with `passkeyAvailable` applied */
+  public get passkeySupport(): IDeesLoginPasskeySupport {
+    if (this.passkeyAvailable === undefined) {
+      return this.detectedPasskeySupport;
+    }
+    return { ...this.detectedPasskeySupport, available: this.passkeyAvailable };
+  }
+
+  /** the methods that are configured, in render order */
+  public get resolvedMethods(): TDeesLoginMethod[] {
+    const configured = canonicalMethodOrder.filter((methodArg) => this.isConfigured(methodArg));
+    const ordered: TDeesLoginMethod[] = [];
+    for (const methodArg of this.methodOrder || []) {
+      if (configured.includes(methodArg) && !ordered.includes(methodArg)) {
+        ordered.push(methodArg);
+      }
+    }
+    for (const methodArg of configured) {
+      if (!ordered.includes(methodArg)) {
+        ordered.push(methodArg);
+      }
+    }
+    return ordered;
+  }
+
+  private isConfigured(methodArg: TDeesLoginMethod): boolean {
+    switch (methodArg) {
+      case 'passkey':
+        return this.passkey && this.passkeySupport.available && this.resolvedPasskeyIntents.length > 0;
+      case 'provider':
+        return this.providers.length > 0;
+      case 'password':
+        return this.password;
+      default:
+        return false;
+    }
+  }
+
+  private get resolvedPasskeyIntents(): TDeesLoginPasskeyIntent[] {
+    const intents = (this.passkeyIntents || []).filter(
+      (intentArg, index, all) => all.indexOf(intentArg) === index,
+    );
+    return intents.length > 0 ? intents : ['authenticate'];
+  }
+
+  /**
+   * true when nothing at all is offered — typically a passkey-only card in a browser that
+   * cannot do WebAuthn. Silent degradation would leave an empty card, so this case gets a
+   * message instead.
+   */
+  private get isUnavailable(): boolean {
+    return this.resolvedMethods.length === 0;
+  }
+
+  private get shouldOfferPasskeyAutofill(): boolean {
+    const methods = this.resolvedMethods;
+    return (
+      this.passkeyAutofill &&
+      Boolean(this.passkeyLoginHandler) &&
+      this.passkeySupport.conditionalMediation &&
+      methods.includes('passkey') &&
+      methods.includes('password')
+    );
+  }
+
+  private copy<K extends keyof IDeesLoginLabels>(keyArg: K, fallbackArg: string): string {
+    const value = (this.labels || {})[keyArg];
+    return value === undefined ? fallbackArg : value;
+  }
+
+  // ------------------------------------------------------------------------------------
+  // per-method state
+  // ------------------------------------------------------------------------------------
+
+  private static targetKey(targetArg: IDeesLoginTarget | TDeesLoginMethod): string {
+    const target: IDeesLoginTarget =
+      typeof targetArg === 'string' ? { method: targetArg } : targetArg;
+    if (target.method === 'passkey') {
+      return `passkey:${target.intent || 'authenticate'}`;
+    }
+    if (target.method === 'provider') {
+      return `provider:${target.providerId || ''}`;
+    }
+    return 'password';
+  }
+
+  /** true while a ceremony for this target is running */
+  public isBusy(targetArg: IDeesLoginTarget | TDeesLoginMethod): boolean {
+    return this.busyKeys.includes(DeesSimpleLogin.targetKey(targetArg));
+  }
+
+  /** marks a target busy — for consumers driving a ceremony from an intent event */
+  public setBusy(targetArg: IDeesLoginTarget | TDeesLoginMethod, busyArg: boolean): void {
+    const key = DeesSimpleLogin.targetKey(targetArg);
+    const isBusy = this.busyKeys.includes(key);
+    if (busyArg === isBusy) {
+      return;
+    }
+    this.busyKeys = busyArg
+      ? [...this.busyKeys, key]
+      : this.busyKeys.filter((busyKey) => busyKey !== key);
+  }
+
+  /** the error currently shown for a target, if any */
+  public getError(targetArg: IDeesLoginTarget | TDeesLoginMethod): string | undefined {
+    return this.errorMap[DeesSimpleLogin.targetKey(targetArg)];
+  }
+
+  /**
+   * shows an error next to one method without touching the others — a failed passkey
+   * attempt must never blank the password form.
+   */
+  public reportError(targetArg: IDeesLoginTarget | TDeesLoginMethod, messageArg: string): void {
+    const key = DeesSimpleLogin.targetKey(targetArg);
+    if (this.errorMap[key] === messageArg) {
+      return;
+    }
+    this.errorMap = { ...this.errorMap, [key]: messageArg };
+  }
+
+  /** clears one target's error, or every error when called without a target */
+  public clearError(targetArg?: IDeesLoginTarget | TDeesLoginMethod): void {
+    if (targetArg === undefined) {
+      if (Object.keys(this.errorMap).length > 0) {
+        this.errorMap = {};
+      }
+      return;
+    }
+    const key = DeesSimpleLogin.targetKey(targetArg);
+    if (this.errorMap[key] === undefined) {
+      return;
+    }
+    const nextMap = { ...this.errorMap };
+    delete nextMap[key];
+    this.errorMap = nextMap;
+  }
+
+  /** clears every busy and error state and resets the password form */
+  public reset(): void {
+    this.abortCeremonies();
+    this.busyKeys = [];
+    this.errorMap = {};
+    const form = this.shadowRoot?.querySelector('dees-form');
+    form?.reset();
+  }
+
+  // ------------------------------------------------------------------------------------
+  // render
+  // ------------------------------------------------------------------------------------
+
   public render(): TemplateResult {
     return html`
       <div class="loginContainer">
         <div class="login">
           <div class="login-header">
-            <div class="header">Sign in</div>
-            <div class="subheader">Enter your credentials to access ${this.name}</div>
+            <div class="header">${this.copy('heading', 'Sign in')}</div>
+            <div class="subheader">
+              ${this.copy('subheading', `Enter your credentials to access ${this.name}`)}
+            </div>
           </div>
-          <dees-tile .heading=${'Credentials'}>
-            <dees-form>
-              <dees-input-text key="username" label="Username" required></dees-input-text>
-              <dees-input-text key="password" label="Password" isPasswordBool required></dees-input-text>
-              <dees-form-submit>Sign in</dees-form-submit>
-            </dees-form>
-          </dees-tile>
+          ${this.renderMethods()}
         </div>
       </div>
       <div class="slotContainer">
@@ -139,19 +627,480 @@ export class DeesSimpleLogin extends DeesElement {
     `;
   }
 
-  public async firstUpdated(_changedProperties: Map<string | number | symbol, unknown>): Promise<void> {
+  private renderMethods(): TemplateResult {
+    if (this.isUnavailable) {
+      return html`
+        <div class="methods">
+          <div class="unavailable">
+            ${this.copy('unavailable', 'No sign-in method is available in this browser.')}
+          </div>
+        </div>
+      `;
+    }
+    const methods = this.resolvedMethods;
+    return html`
+      <div class="methods">
+        ${methods.map(
+          (methodArg, index) => html`
+            ${index === 0
+              ? ''
+              : html`<div class="divider">${this.copy('divider', 'or')}</div>`}
+            ${this.renderMethod(methodArg)}
+          `,
+        )}
+      </div>
+    `;
+  }
+
+  private renderMethod(methodArg: TDeesLoginMethod): TemplateResult {
+    if (methodArg === 'passkey') {
+      return this.renderPasskeyMethod();
+    }
+    if (methodArg === 'provider') {
+      return this.renderProviderMethod();
+    }
+    return this.renderPasswordMethod();
+  }
+
+  private renderPasskeyMethod(): TemplateResult {
+    const intents = this.resolvedPasskeyIntents;
+    // Concurrent WebAuthn calls reject each other, so a running ceremony locks the *other*
+    // passkey intent — providers and the password form stay usable. The busy button itself
+    // is never marked disabled: dees-button dims a disabled face to 50% opacity, which
+    // would wash out the pending spinner. handlePasskey() guards the re-entry instead.
+    const anyPasskeyBusy = intents.some((intentArg) =>
+      this.isBusy({ method: 'passkey', intent: intentArg }),
+    );
+    return html`
+      <div class="method">
+        <div class="methodActions passkeyActions">
+          ${intents.map((intentArg) => {
+            const busy = this.isBusy({ method: 'passkey', intent: intentArg });
+            const isRegister = intentArg === 'register';
+            return html`
+              <dees-button
+                full-width
+                .type=${isRegister ? 'outline' : 'accent'}
+                .icon=${busy ? '' : isRegister ? 'lucide:keyRound' : 'lucide:fingerprint'}
+                .text=${isRegister
+                  ? this.copy('passkeyRegister', 'Create a passkey')
+                  : this.copy('passkeyAuthenticate', 'Sign in with a passkey')}
+                .status=${busy ? 'pending' : 'normal'}
+                .disabled=${anyPasskeyBusy && !busy}
+                @clicked=${() => this.handlePasskey(intentArg)}
+              ></dees-button>
+            `;
+          })}
+        </div>
+        ${intents.map((intentArg) =>
+          this.renderError(this.getError({ method: 'passkey', intent: intentArg })),
+        )}
+      </div>
+    `;
+  }
+
+  /**
+   * Past three providers the buttons pair up into two columns, and the "Continue with"
+   * prefix is dropped so a bare provider name still fits its half-width button.
+   */
+  private get denseProviders(): boolean {
+    return this.providers.length >= 4;
+  }
+
+  private renderProviderMethod(): TemplateResult {
+    const dense = this.denseProviders;
+    // Half-width buttons cannot carry "Continue with …", so the prefix is dropped when the
+    // grid kicks in — unless the consumer stated one explicitly, which always wins.
+    const prefix = this.copy('providerPrefix', dense ? '' : 'Continue with');
+    return html`
+      <div class="method">
+        <div class="methodActions providerActions ${dense ? 'dense' : ''}">
+          ${this.providers.map((providerArg) => {
+            const busy = this.isBusy({ method: 'provider', providerId: providerArg.id });
+            return html`
+              <dees-button
+                full-width
+                title=${dense ? providerArg.label : ''}
+                .type=${'secondary'}
+                .icon=${busy ? '' : providerArg.icon || ''}
+                .text=${prefix ? `${prefix} ${providerArg.label}` : providerArg.label}
+                .status=${busy ? 'pending' : 'normal'}
+                .disabled=${Boolean(providerArg.disabled)}
+                @clicked=${() => this.handleProvider(providerArg)}
+              ></dees-button>
+            `;
+          })}
+        </div>
+        ${this.renderError(this.getError({ method: 'provider' }))}
+        ${this.providers.map((providerArg) => {
+          const message = this.getError({ method: 'provider', providerId: providerArg.id });
+          if (!message) {
+            return '';
+          }
+          return this.renderError(
+            this.providers.length > 1 ? `${providerArg.label}: ${message}` : message,
+          );
+        })}
+      </div>
+    `;
+  }
+
+  private renderPasswordMethod(): TemplateResult {
+    // The submit label is slotted, not bound: consumers call dees-form.setStatus(), which
+    // writes dees-form-submit.text imperatively. A property binding here would clobber
+    // their status text on the next render.
+    const form = html`
+      <dees-form @formData=${this.handleFormData}>
+        <dees-input-text
+          key="username"
+          .label=${this.copy('usernameLabel', 'Username')}
+          .autocomplete=${this.shouldOfferPasskeyAutofill ? 'username webauthn' : 'username'}
+          required
+        ></dees-input-text>
+        <dees-input-text
+          key="password"
+          .label=${this.copy('passwordLabel', 'Password')}
+          .autocomplete=${'current-password'}
+          isPasswordBool
+          required
+        ></dees-input-text>
+        <dees-form-submit full-width>${this.copy('passwordSubmit', 'Sign in')}</dees-form-submit>
+      </dees-form>
+    `;
+    // The tile is what gives a lone credentials form its card. Once the column holds other
+    // methods the column *is* the card, and a second frame around only the fields reads as
+    // a stray box — so the form joins the column bare and keeps the same 360px edge.
+    return html`
+      <div class="method">
+        ${this.resolvedMethods.length === 1
+          ? html`
+              <dees-tile .heading=${this.copy('credentialsHeading', 'Credentials')}>
+                ${form}
+              </dees-tile>
+            `
+          : html`<div class="credentials">${form}</div>`}
+        ${this.renderError(this.getError('password'))}
+      </div>
+    `;
+  }
+
+  private renderError(messageArg: string | undefined): TemplateResult | string {
+    if (!messageArg) {
+      return '';
+    }
+    return html`
+      <div class="methodError" role="alert">
+        <dees-icon .icon=${'lucide:circleAlert'} .iconSize=${14}></dees-icon>
+        <span>${messageArg}</span>
+      </div>
+    `;
+  }
+
+  // ------------------------------------------------------------------------------------
+  // lifecycle
+  // ------------------------------------------------------------------------------------
+
+  public async connectedCallback(): Promise<void> {
+    await super.connectedCallback();
+    this.detectPasskeySupportSync();
+    void this.detectPasskeySupportAsync();
+  }
+
+  public async firstUpdated(
+    _changedProperties: Map<string | number | symbol, unknown>,
+  ): Promise<void> {
     super.firstUpdated(_changedProperties);
-    
-    const form = this.shadowRoot!.querySelector('dees-form') as any;
-    if (form) {
-      form.addEventListener('formData', ((event: CustomEvent) => {
-        this.dispatchEvent(new CustomEvent('login', { 
-          detail: event.detail, 
-          bubbles: true, 
-          composed: true 
-        }));
-      }) as EventListener);
+    this.observeContainerInteractivity();
+    void this.maybeStartPasskeyAutofill();
+  }
+
+  public updated(_changedProperties: Map<string | number | symbol, unknown>): void {
+    super.updated(_changedProperties);
+    // Only take over the submit button's visual state when this component actually owns
+    // the credential ceremony. Legacy consumers drive it through dees-form.setStatus().
+    if (this.passwordLoginHandler) {
+      const submitButton = this.shadowRoot?.querySelector('dees-form-submit');
+      if (submitButton) {
+        submitButton.status = this.isBusy('password') ? 'pending' : 'normal';
+      }
+    }
+    void this.maybeStartPasskeyAutofill();
+  }
+
+  public async disconnectedCallback(): Promise<void> {
+    await super.disconnectedCallback();
+    this.abortCeremonies();
+    this.interactivityObserver?.disconnect();
+    this.interactivityObserver = undefined;
+    // re-arm autofill if this element is attached again
+    this.autofillStarted = false;
+  }
+
+  private detectPasskeySupportSync(): void {
+    const available =
+      typeof window !== 'undefined' &&
+      window.isSecureContext === true &&
+      typeof (window as unknown as { PublicKeyCredential?: unknown }).PublicKeyCredential ===
+        'function' &&
+      typeof navigator !== 'undefined' &&
+      typeof navigator.credentials?.get === 'function';
+    if (this.detectedPasskeySupport.available !== available) {
+      this.detectedPasskeySupport = { ...this.detectedPasskeySupport, available };
+    }
+  }
+
+  private async detectPasskeySupportAsync(): Promise<void> {
+    if (!this.detectedPasskeySupport.available) {
+      return;
+    }
+    const publicKeyCredential = (
+      window as unknown as {
+        PublicKeyCredential: {
+          isConditionalMediationAvailable?: () => Promise<boolean>;
+          isUserVerifyingPlatformAuthenticatorAvailable?: () => Promise<boolean>;
+        };
+      }
+    ).PublicKeyCredential;
+    const probe = async (probeArg?: () => Promise<boolean>): Promise<boolean> => {
+      if (typeof probeArg !== 'function') {
+        return false;
+      }
+      try {
+        return (await probeArg.call(publicKeyCredential)) === true;
+      } catch {
+        return false;
+      }
+    };
+    const [conditionalMediation, platformAuthenticator] = await Promise.all([
+      probe(publicKeyCredential.isConditionalMediationAvailable),
+      probe(publicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable),
+    ]);
+    this.detectedPasskeySupport = {
+      available: true,
+      conditionalMediation,
+      platformAuthenticator,
+    };
+  }
+
+  // ------------------------------------------------------------------------------------
+  // interactions
+  // ------------------------------------------------------------------------------------
+
+  private handleFormData = async (eventArg: Event): Promise<void> => {
+    const detail = (eventArg as CustomEvent).detail;
+    if (this.isBusy('password')) {
+      return;
+    }
+    this.clearError('password');
+    // Unchanged legacy contract: `login` carries dees-form's detail verbatim.
+    this.dispatchEvent(
+      new CustomEvent('login', {
+        detail,
+        bubbles: true,
+        composed: true,
+      }),
+    );
+    if (!this.passwordLoginHandler) {
+      return;
+    }
+    const handler = this.passwordLoginHandler;
+    await this.runCeremony({ method: 'password' }, () =>
+      handler({ data: (detail?.data as Record<string, unknown>) || {} }),
+    );
+  };
+
+  private handlePasskey = async (intentArg: TDeesLoginPasskeyIntent): Promise<void> => {
+    const target: IDeesLoginTarget = { method: 'passkey', intent: intentArg };
+    if (this.resolvedPasskeyIntents.some((candidate) =>
+      this.isBusy({ method: 'passkey', intent: candidate }),
+    )) {
+      return;
+    }
+    // An explicit ceremony supersedes a silent autofill request; leaving both in flight
+    // makes the browser reject one of them.
+    this.abortAutofill();
+    this.clearError(target);
+    const handler =
+      intentArg === 'register' ? this.passkeyRegisterHandler : this.passkeyLoginHandler;
+    if (!handler) {
+      this.dispatchEvent(
+        new CustomEvent(intentArg === 'register' ? 'passkey-register' : 'passkey-login', {
+          detail: { intent: intentArg, username: this.readUsername() },
+          bubbles: true,
+          composed: true,
+        }),
+      );
+      return;
+    }
+    const key = DeesSimpleLogin.targetKey(target);
+    const controller = new AbortController();
+    this.ceremonyControllers.set(key, controller);
+    try {
+      await this.runCeremony(target, () =>
+        handler({
+          intent: intentArg,
+          username: this.readUsername(),
+          mediation: 'optional',
+          signal: controller.signal,
+        }),
+      );
+    } finally {
+      if (this.ceremonyControllers.get(key) === controller) {
+        this.ceremonyControllers.delete(key);
+      }
+    }
+  };
+
+  private handleProvider = async (providerArg: IDeesLoginProvider): Promise<void> => {
+    const target: IDeesLoginTarget = { method: 'provider', providerId: providerArg.id };
+    if (providerArg.disabled || this.isBusy(target)) {
+      return;
+    }
+    this.clearError(target);
+    if (!this.providerLoginHandler) {
+      this.dispatchEvent(
+        new CustomEvent('provider-login', {
+          detail: { providerId: providerArg.id, provider: providerArg },
+          bubbles: true,
+          composed: true,
+        }),
+      );
+      return;
+    }
+    const handler = this.providerLoginHandler;
+    await this.runCeremony(target, () =>
+      handler({ providerId: providerArg.id, provider: providerArg }),
+    );
+  };
+
+  private async runCeremony(
+    targetArg: IDeesLoginTarget,
+    ceremonyArg: () => unknown | Promise<unknown>,
+  ): Promise<void> {
+    this.setBusy(targetArg, true);
+    try {
+      await ceremonyArg();
+    } catch (error) {
+      if (!DeesSimpleLogin.isAbortError(error)) {
+        this.reportError(targetArg, DeesSimpleLogin.toErrorMessage(error));
+      }
+    } finally {
+      this.setBusy(targetArg, false);
+    }
+  }
+
+  /**
+   * Starts the browser's passkey autofill. Conditional mediation has to be requested
+   * before the user touches anything, and it must stay silent — a background ceremony that
+   * finds no credential is not an error the user should see.
+   */
+  private async maybeStartPasskeyAutofill(): Promise<void> {
+    if (this.autofillStarted || !this.shouldOfferPasskeyAutofill) {
+      return;
+    }
+    const handler = this.passkeyLoginHandler;
+    if (!handler) {
+      return;
+    }
+    this.autofillStarted = true;
+    const controller = new AbortController();
+    this.autofillController = controller;
+    try {
+      await handler({
+        intent: 'authenticate',
+        username: undefined,
+        mediation: 'conditional',
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (!DeesSimpleLogin.isAbortError(error)) {
+        console.warn('dees-simple-login: passkey autofill ceremony failed', error);
+      }
+    } finally {
+      if (this.autofillController === controller) {
+        this.autofillController = undefined;
+      }
+      // deliberately not reset: one silent attempt per connection, so a rejecting handler
+      // can never be retried in a render loop
+    }
+  }
+
+  private abortAutofill(): void {
+    this.autofillController?.abort();
+    this.autofillController = undefined;
+  }
+
+  private abortCeremonies(): void {
+    this.abortAutofill();
+    for (const controller of this.ceremonyControllers.values()) {
+      controller.abort();
+    }
+    this.ceremonyControllers.clear();
+  }
+
+  private readUsername(): string | undefined {
+    const input = this.shadowRoot?.querySelector('dees-input-text[key="username"]') as
+      | { value?: unknown }
+      | null;
+    const value = input?.value;
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+  }
+
+  private static isAbortError(errorArg: unknown): boolean {
+    return Boolean(errorArg) && (errorArg as { name?: string }).name === 'AbortError';
+  }
+
+  private static toErrorMessage(errorArg: unknown): string {
+    if (errorArg instanceof Error) {
+      return errorArg.message;
+    }
+    return String(errorArg);
+  }
+
+  /**
+   * The login card and the slotted app are both permanently in the DOM, stacked and
+   * cross-faded with opacity plus `pointer-events`. That was enough while nothing inside
+   * either half could hold focus — but `dees-button` faces are focusable now, and
+   * `pointer-events: none` does not remove anything from the tab order. Without this, a
+   * keyboard user could Tab out of the password form straight into the invisible app shell,
+   * and after signing in could Tab back into the invisible login card and start a passkey
+   * ceremony there. `inert` is what actually takes a hidden subtree out of focus and the
+   * accessibility tree.
+   *
+   * Inertness is derived from each container's effective `pointer-events` rather than from
+   * an internal flag, because consumers reverse this transition by hand — cloudly's
+   * `switchToLoginContent()` writes these inline styles directly and knows nothing about
+   * `inert`. Keying off a flag they cannot reset would leave their login card permanently
+   * inert. A MutationObserver on the inline styles keeps both directions correct no matter
+   * who wrote them.
+   */
+  private syncContainerInertness = (): void => {
+    for (const selector of ['.loginContainer', '.slotContainer']) {
+      const container = this.shadowRoot?.querySelector(selector);
+      if (!(container instanceof HTMLElement)) {
+        continue;
+      }
+      container.inert = getComputedStyle(container).pointerEvents === 'none';
+    }
+  };
+
+  private observeContainerInteractivity(): void {
+    if (this.interactivityObserver) {
+      return;
+    }
+    this.interactivityObserver = new MutationObserver(() => this.syncContainerInertness());
+    for (const selector of ['.loginContainer', '.slotContainer']) {
+      const container = this.shadowRoot?.querySelector(selector);
+      if (container) {
+        // only the inline style matters; `inert` reflects to an attribute of its own and
+        // must not re-trigger this observer
+        this.interactivityObserver.observe(container, {
+          attributes: true,
+          attributeFilter: ['style'],
+        });
+      }
     }
+    this.syncContainerInertness();
   }
 
   /**