@design.estate/dees-catalog 3.97.1 → 3.98.0

package/dist_ts_web/elements/00group-simple/dees-simple-login/dees-simple-login.d.ts

@@ -1,17 +1,263 @@
 import { DeesElement, type TemplateResult } from '@design.estate/dees-element';
 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 {
         'dees-simple-login': DeesSimpleLogin;
     }
 }
+/**
+ * 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>;
+/**
+ * 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.
+ */
 export declare class DeesSimpleLogin extends DeesElement {
     static demo: () => TemplateResult<1>;
     static demoGroups: string[];
+    /** application name, interpolated into the default subheading */
     accessor name: string;
+    /**
+     * 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.
+     */
+    accessor passkey: boolean;
+    /** which passkey affordances to render, in this order */
+    accessor passkeyIntents: TDeesLoginPasskeyIntent[];
+    /**
+     * overrides browser capability detection. `undefined` detects automatically; set it when
+     * the server already knows whether passkeys are configured for this deployment.
+     */
+    accessor passkeyAvailable: boolean | 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.
+     */
+    accessor passkeyAutofill: boolean;
+    /** identity providers to offer. Empty means the provider method is not configured. */
+    accessor providers: IDeesLoginProvider[];
+    /** offer the username/password form. On by default — set `.password=${false}` to drop it. */
+    accessor password: boolean;
+    /**
+     * 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.
+     */
+    accessor methodOrder: TDeesLoginMethod[];
+    /** copy overrides */
+    accessor labels: IDeesLoginLabels;
+    /** drives the passkey sign-in ceremony — see "Who owns the WebAuthn ceremony" */
+    accessor passkeyLoginHandler: TDeesLoginPasskeyHandler | undefined;
+    /** drives the passkey enrollment ceremony */
+    accessor passkeyRegisterHandler: TDeesLoginPasskeyHandler | undefined;
+    /** drives a provider sign-in (redirect or popup) */
+    accessor providerLoginHandler: TDeesLoginProviderHandler | undefined;
+    /** drives a credential sign-in. The legacy `login` event fires regardless. */
+    accessor passwordLoginHandler: TDeesLoginPasswordHandler | undefined;
+    private accessor detectedPasskeySupport;
+    private accessor busyKeys;
+    private accessor errorMap;
+    private ceremonyControllers;
+    private autofillController;
+    private autofillStarted;
+    private interactivityObserver;
     static styles: import("@design.estate/dees-element").CSSResult[];
+    /** resolved browser capability, with `passkeyAvailable` applied */
+    get passkeySupport(): IDeesLoginPasskeySupport;
+    /** the methods that are configured, in render order */
+    get resolvedMethods(): TDeesLoginMethod[];
+    private isConfigured;
+    private get resolvedPasskeyIntents();
+    /**
+     * 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();
+    private get shouldOfferPasskeyAutofill();
+    private copy;
+    private static targetKey;
+    /** true while a ceremony for this target is running */
+    isBusy(targetArg: IDeesLoginTarget | TDeesLoginMethod): boolean;
+    /** marks a target busy — for consumers driving a ceremony from an intent event */
+    setBusy(targetArg: IDeesLoginTarget | TDeesLoginMethod, busyArg: boolean): void;
+    /** the error currently shown for a target, if any */
+    getError(targetArg: IDeesLoginTarget | TDeesLoginMethod): string | undefined;
+    /**
+     * shows an error next to one method without touching the others — a failed passkey
+     * attempt must never blank the password form.
+     */
+    reportError(targetArg: IDeesLoginTarget | TDeesLoginMethod, messageArg: string): void;
+    /** clears one target's error, or every error when called without a target */
+    clearError(targetArg?: IDeesLoginTarget | TDeesLoginMethod): void;
+    /** clears every busy and error state and resets the password form */
+    reset(): void;
     render(): TemplateResult;
+    private renderMethods;
+    private renderMethod;
+    private renderPasskeyMethod;
+    /**
+     * 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();
+    private renderProviderMethod;
+    private renderPasswordMethod;
+    private renderError;
+    connectedCallback(): Promise<void>;
     firstUpdated(_changedProperties: Map<string | number | symbol, unknown>): Promise<void>;
+    updated(_changedProperties: Map<string | number | symbol, unknown>): void;
+    disconnectedCallback(): Promise<void>;
+    private detectPasskeySupportSync;
+    private detectPasskeySupportAsync;
+    private handleFormData;
+    private handlePasskey;
+    private handleProvider;
+    private runCeremony;
+    /**
+     * 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 maybeStartPasskeyAutofill;
+    private abortAutofill;
+    private abortCeremonies;
+    private readUsername;
+    private static isAbortError;
+    private static toErrorMessage;
+    /**
+     * 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;
+    private observeContainerInteractivity;
     /**
      * allows switching to slotted content
      */