@trymellon/js 1.7.6 → 2.0.0

package/dist/ui/index.d.ts

@@ -0,0 +1,514 @@
+/**
+ * FSM constants. Single source for initial state.
+ */
+/** Initial FSM state (pre-attach). */
+declare const INITIAL_UI_STATE: "IDLE";
+
+/** UI FSM types — presentation layer. No DOM/core deps (types only). Aligned to 01-arquitectura §4. */
+
+/** UI state machine states. */
+type UIState = 'IDLE' | 'EVALUATING_ENV' | 'READY' | 'READY_REGISTER' | 'READY_LOGIN' | 'AUTHENTICATING' | 'SUCCESS' | 'ERROR' | 'FALLBACK' | 'FALLBACK_EMAIL' | 'FALLBACK_QR';
+/** Component mode (mode attribute). */
+type UIMode = 'login' | 'register' | 'auto';
+/** Client status in UI layer (port/adapter map from core). */
+type UIClientStatus = {
+    isPasskeySupported: boolean;
+    platformAuthenticatorAvailable: boolean;
+    recommendedFlow: 'passkey' | 'fallback';
+};
+/** getClientStatus result for EVALUATING_ENV → READY* transition. */
+type EnvResolvedPayload = {
+    recommendedFlow: 'passkey' | 'fallback';
+    mode: UIMode;
+    /** When recommendedFlow === 'fallback', available fallback channel. */
+    fallbackType?: 'email' | 'qr';
+};
+/** Modal tab (register | login). */
+type TabKind = 'register' | 'login';
+/** Events that trigger FSM transitions. */
+type FSMEvent = {
+    type: 'ENV_EVAL_START';
+} | {
+    type: 'ENV_RESOLVED';
+    payload: EnvResolvedPayload;
+} | {
+    type: 'ENV_DETACH';
+} | {
+    type: 'ENV_ERROR';
+} | {
+    type: 'RESET';
+} | {
+    type: 'TAB_CHANGE';
+    payload: {
+        tab: TabKind;
+    };
+} | {
+    type: 'START_AUTH';
+} | {
+    type: 'AUTH_SUCCESS';
+} | {
+    type: 'AUTH_ERROR';
+} | {
+    type: 'AUTH_FALLBACK';
+} | {
+    type: 'AUTH_FALLBACK_EMAIL';
+} | {
+    type: 'AUTH_FALLBACK_QR';
+};
+
+/**
+ * Port: client environment evaluation (passkey/fallback). Contract only; implementation in adapters.
+ */
+
+/** Contract to get client capability status (browser/device). */
+interface EnvStatusPort {
+    getClientStatus(): Promise<UIClientStatus>;
+}
+
+/**
+ * Use case: evaluate environment (getClientStatus) and return next FSM state. Validates params and port response at boundary; domain + EnvStatusPort only. No DOM.
+ */
+
+type RunEnvEvalParams = {
+    envStatusPort: EnvStatusPort;
+    currentState: UIState;
+    mode: UIMode;
+    isMobileOverride?: boolean;
+    /** When recommendedFlow is fallback, allows fixing FALLBACK_EMAIL vs FALLBACK_QR (e.g. modal). */
+    fallbackType?: 'email' | 'qr';
+};
+
+/**
+ * Type contracts for parsed UI attributes. Types only; no DOM/core. Parsing lives in adapters.
+ */
+
+/** Presentation theme (theme attribute). */
+type ThemeKind = 'light' | 'dark';
+/** Button action: direct-auth (ceremony only) or open-modal (emit open-request / show modal). */
+type ButtonAction = 'direct-auth' | 'open-modal';
+/** Button presentation variant: default (inline icon+text) or pill (landing: circle + label, touch ≥48px). */
+type ButtonVariant = 'default' | 'pill';
+/** Modal presentation variant: default (standard panel/tabs) or minimal (landing: rounded-2xl, border-2, light tabs). */
+type ModalVariant = 'default' | 'minimal';
+/** Parsed and normalized host attributes (trymellon-auth). */
+type ParsedAttributes = {
+    appId: string;
+    publishableKey: string;
+    mode: UIMode;
+    externalUserId: string | null;
+    theme: ThemeKind;
+    action: ButtonAction;
+    triggerOnly: boolean;
+    buttonVariant: ButtonVariant;
+};
+/** Modal display mode: overlay vs inline. */
+type ModalDisplayMode = 'modal' | 'inline';
+/** Active modal tab: register | login. */
+type ModalTabKind = 'register' | 'login';
+/** Tab labels for register/login. */
+type TabLabels = {
+    register: string;
+    login: string;
+};
+/** Fallback type when recommendedFlow is fallback (fallback-type attribute). */
+type FallbackTypeKind = 'email' | 'qr';
+/** Parsed and normalized modal attributes (trymellon-auth-modal). */
+type ParsedModalAttributes = {
+    open: boolean;
+    mode: ModalDisplayMode;
+    tab: ModalTabKind;
+    tabLabels: TabLabels;
+    theme: ThemeKind;
+    sessionId: string | null;
+    onboardingUrl: string | null;
+    isMobileOverride: boolean | null;
+    fallbackType?: FallbackTypeKind;
+    appId: string;
+    publishableKey: string;
+    /** Optional app name shown in dialog title (e.g. "My App — Sign in or register"). */
+    appName: string | null;
+    /** Optional full dialog title; overrides default/app-name title when set. */
+    dialogTitle: string | null;
+    /** Optional dialog description; overrides default copy when set. */
+    dialogDescription: string | null;
+    /** Optional external user id for register; when missing, SDK uses a generated UUID (no external UI needed). */
+    externalUserId: string | null;
+    modalVariant: ModalVariant;
+};
+
+/**
+ * Port: UI rendering onto a surface. Contract only; implementation in adapters. Imports from ../domain only.
+ */
+
+/** Render options (theme, mode, pre-ceremony signal for register, button variant, labels). */
+type RenderOptions = {
+    theme?: ThemeKind;
+    mode?: UIMode;
+    /** When false and state is READY_REGISTER, show "Preparing…" instead of button (session-id missing or empty). */
+    registerSessionReady?: boolean;
+    /** Button presentation variant. Default: default. */
+    buttonVariant?: ButtonVariant;
+    /** Primary button label (e.g. trigger "TryMellon", inside modal "Try Passkey"). Omit = "TryMellon". */
+    primaryButtonLabel?: string;
+    /** Primary button aria-label. Omit = derived from primaryButtonLabel or default. */
+    primaryButtonAriaLabel?: string;
+};
+
+/**
+ * Port: core event subscription and re-emission on host. Source of truth for modal WC event contract (names, detail types).
+ * Contract only; implementation in adapters. No import from ../core.
+ */
+
+/** Public auth operation for host (login | register). */
+type AuthOperation = TabKind;
+/** Optional user info in mellon:success; minimal shape for host without coupling to core. */
+type MellonSuccessUserInfo = {
+    userId: string;
+    externalUserId?: string;
+    email?: string;
+    metadata?: Record<string, unknown>;
+};
+/** mellon:success detail. Token required; token only in this event. Sensitive: backend only, validate server-side. */
+type MellonSuccessDetail = {
+    operation: AuthOperation;
+    token: string;
+    nonce?: string;
+    user?: MellonSuccessUserInfo;
+    /** Redirect URL after login when core provides it. */
+    redirectUrl?: string;
+};
+/** mellon:error detail (code, message, operation, optional nonce). bubbles: true, composed: true. */
+type MellonErrorDetail = {
+    operation: AuthOperation;
+    code: string;
+    message: string;
+    nonce?: string;
+};
+/** mellon:start and mellon:cancelled detail (operation, optional nonce for ceremony correlation). */
+type MellonOperationDetail = {
+    operation: AuthOperation;
+    nonce?: string;
+};
+/** mellon:open detail (optional source, timestamp for observability). */
+type MellonOpenDetail = Record<string, never> | {
+    source?: 'user' | 'api';
+    timestamp?: number;
+};
+/** mellon:close detail (optional reason, timestamp for observability). */
+type MellonCloseDetail = Record<string, never> | {
+    reason: 'user' | 'success' | 'error' | 'cancel';
+    timestamp?: number;
+};
+/** mellon:fallback detail (channel chosen in UI). */
+type MellonFallbackDetail = {
+    operation?: AuthOperation;
+    fallbackType?: 'email' | 'qr';
+};
+/** Minimal core contract for event subscription (on → unsubscribe). */
+interface CoreWithEvents {
+    on(event: string, handler: (...args: unknown[]) => void): () => void;
+}
+/** Contract to subscribe core to host and re-emit as CustomEvents. Returns unsubscribe. */
+interface CoreEventsPort {
+    subscribe(core: CoreWithEvents, host: HTMLElement): () => void;
+}
+/** Minimal core surface for UI: start auth and subscribe to events. */
+interface CoreAuthPort extends CoreWithEvents {
+    authenticate(options?: CoreAuthOptions): void;
+    register(options?: CoreAuthOptions): void;
+}
+/** Options when starting auth from UI. */
+interface CoreAuthOptions {
+    externalUserId?: string | null;
+}
+
+interface CoreConfig {
+    appId: string;
+    publishableKey: string;
+}
+
+type PendingAuthOperation = 'register' | 'authenticate';
+declare class AuthController {
+    private _currentState;
+    private _lastRenderedState;
+    private _renderDirty;
+    private _pendingOperation;
+    private _currentNonce;
+    private _envEvalRequestId;
+    get currentState(): UIState;
+    setState(next: UIState): void;
+    invalidateRender(): void;
+    /**
+     * Decides if a render is needed based on state/dirty flag.
+     * Returns true when the caller should render and marks state as clean.
+     */
+    consumeRenderDecision(): boolean;
+    setPendingOperationFromTab(tab: TabKind): void;
+    get pendingOperation(): PendingAuthOperation;
+    setNonce(nonce: string | undefined): void;
+    consumeCancelledDetailIfAuthenticating(): MellonOperationDetail | null;
+    handleAuthSuccess(): void;
+    handleAuthError(): void;
+    onStartEvent(detail: MellonOperationDetail | undefined): void;
+    startAuthFromClick(core: CoreAuthPort | null, tab: TabKind, options?: CoreAuthOptions): void;
+    runEnvEval(params: Omit<RunEnvEvalParams, 'currentState'>): Promise<UIState | null>;
+    reset(): void;
+    setStateForRender(state: UIState): void;
+}
+
+/**
+ * Abstract base for <trymellon-auth> and <trymellon-auth-modal>. Shared lifecycle: teardown, host/fallback listeners, Mellon handlers, env eval.
+ * AuthController encapsulates FSM/env-eval; this base wires it to HTMLElement and DOM events.
+ */
+
+/**
+ * Abstract base: FSM, core, event bridge, env eval, fallback/shadow click.
+ * Subclasses define observedAttributes, parsing, _render() and (modal only) open/tab.
+ * Render flow: setState / invalidateRender → scheduleRenderIfNeeded → _render (single path).
+ */
+declare abstract class AuthElementBase extends HTMLElement {
+    protected _controller: AuthController;
+    protected _unsubscribeBridge: (() => void) | null;
+    protected _core: CoreAuthPort | null;
+    protected _lastCoreConfig: CoreConfig | null;
+    /** Encapsulates state assignment and schedules render. Single canonical way to change _currentState and trigger _render. */
+    protected setState(next: UIState): void;
+    /** Marks that a re-render is needed even if FSM state did not change (e.g. theme or props). */
+    protected invalidateRender(): void;
+    /** Compares current state with last render; if changed or dirty, calls _render and updates cache. */
+    protected scheduleRenderIfNeeded(): void;
+    /** If state was AUTHENTICATING: build detail, dispatch mellon:cancelled, clear nonce; return true. Else false. */
+    protected _emitCancelledIfAuthenticating(): boolean;
+    /**
+     * Injects auth core and starts env eval. Pass null to detach and transition to IDLE.
+     * Multi-write safe: teardown existing core before attaching new one. Host must call reset() before re-open if WC stays in DOM.
+     * @param core - CoreAuthPort-compatible instance, or null to detach.
+     */
+    attachCore(core: unknown): void;
+    protected _teardownCore(): void;
+    protected _attachHostListeners(): void;
+    protected _onMellonSuccess: () => void;
+    protected _onMellonError: () => void;
+    protected _onMellonStart: (e: Event) => void;
+    /**
+     * Semantic logic for "click on primary auth button". Subclasses register DOM delegation
+     * (e.g. adapters/interactions/dom.adapter) and call this method from the callback.
+     */
+    protected startAuthFromClick(): void;
+    /**
+     * Emits mellon:fallback. With type = email|qr sets detail.fallbackType; without type (generic "Continue") does not set fallbackType.
+     */
+    protected dispatchFallback(type?: 'email' | 'qr'): void;
+    protected _runEnvEval(): Promise<void>;
+    protected _maybeAutoCreateCoreAndRunEnvEval(): void;
+    /** Single path: compare config with last, attach or detach core. No per-call special cases. */
+    protected _reconcileCoreFromConfig(): void;
+    disconnectedCallback(): void;
+    /** Current FSM state (read-only). */
+    get currentState(): UIState;
+    /**
+     * Transitions FSM to IDLE, clears in-flight ceremony, re-renders. If state was AUTHENTICATING, emits mellon:cancelled first.
+     * Host must call reset() before re-open if WC remains in DOM after close.
+     */
+    reset(): void;
+    /** Tests only: set state and re-render without FSM transition. */
+    setStateForRender(state: UIState): void;
+    protected abstract getTabKind(): TabKind;
+    protected abstract getCoreAuthOptions(): {
+        externalUserId?: string | null;
+    };
+    protected abstract canStartAuth(): boolean;
+    protected abstract getEnvEvalParams(): Omit<RunEnvEvalParams, 'envStatusPort' | 'currentState'>;
+    protected abstract getCoreConfig(): {
+        appId: string;
+        publishableKey: string;
+    } | null;
+    protected abstract getFallbackDetail(): MellonFallbackDetail;
+    protected abstract _render(): void;
+}
+
+/**
+ * Web Component <trymellon-auth>. Shadow DOM open + attributes + render by state.
+ * Option A (default): action=open-modal without trigger-only → emits mellon:open-request and shows internal modal.
+ * Option B (escape hatch): trigger-only="true" → only emits mellon:open-request; host mounts <trymellon-auth-modal> separately.
+ */
+
+declare class TryMellonAuthElement extends AuthElementBase {
+    static get observedAttributes(): string[];
+    protected _parsed: ParsedAttributes;
+    private _internalModal;
+    /** Element that opened the modal; single source for focus restore on close. */
+    private _focusRestoreTarget;
+    private _unregisterInteractions;
+    private _onInternalModalClose;
+    private _restoreFocusToTrigger;
+    connectedCallback(): void;
+    private _registerInteractions;
+    attributeChangedCallback(name: string, _oldValue: string | null, _newValue: string | null): void;
+    private _onPrimaryClick;
+    protected getTabKind(): TabKind;
+    protected getCoreAuthOptions(): {
+        externalUserId?: string | null;
+    };
+    protected canStartAuth(): boolean;
+    protected getEnvEvalParams(): Omit<RunEnvEvalParams, 'envStatusPort' | 'currentState'>;
+    protected getCoreConfig(): {
+        appId: string;
+        publishableKey: string;
+    } | null;
+    protected getFallbackDetail(): MellonFallbackDetail;
+    protected _render(): void;
+    private _syncThemeAttribute;
+    private _syncInternalModalAttributes;
+    private _ensureInternalModal;
+    disconnectedCallback(): void;
+}
+
+/**
+ * Web Component <trymellon-auth-modal>. Public API per 01-limites-api-publica.md.
+ * Extends AuthElementBase; attributes, parsing, modal structure, open/tab and _render only.
+ */
+
+declare class TryMellonAuthModalElement extends AuthElementBase {
+    static get observedAttributes(): string[];
+    protected _parsed: ParsedModalAttributes;
+    private _focusTrap;
+    private _unregisterInteractions;
+    /** When external-user-id is not set, register uses this UUID so backend can notify client without external UI. */
+    private _generatedExternalUserId;
+    private _qrLoadTimeoutId;
+    private _qrSlotChangeBound;
+    /** Escape closes modal via same path as open=false → _transitionToIdle. */
+    private _boundEscapeKeydown;
+    connectedCallback(): void;
+    private _registerInteractions;
+    attributeChangedCallback(name: string, oldValue: string | null, _newValue: string | null): void;
+    private _startQrLoadWait;
+    private _clearQrLoadWait;
+    /** Single path to IDLE: close event, cancelled if needed, reset FSM, structure, render, visibility. Called from open→false and reset(). */
+    private _transitionToIdle;
+    get open(): boolean;
+    set open(value: boolean);
+    get mode(): 'modal' | 'inline';
+    set mode(value: 'modal' | 'inline');
+    get tab(): 'register' | 'login';
+    set tab(value: 'register' | 'login');
+    get tabLabels(): string;
+    set tabLabels(value: string | undefined);
+    get theme(): 'light' | 'dark';
+    set theme(value: 'light' | 'dark');
+    get sessionId(): string | null;
+    set sessionId(value: string | null);
+    get onboardingUrl(): string | null;
+    set onboardingUrl(value: string | null);
+    get isMobileOverride(): boolean | null;
+    set isMobileOverride(value: boolean | null);
+    get fallbackType(): 'email' | 'qr' | undefined;
+    set fallbackType(value: 'email' | 'qr' | undefined);
+    get appId(): string;
+    set appId(value: string);
+    get publishableKey(): string;
+    set publishableKey(value: string);
+    get appName(): string | null;
+    set appName(value: string | null);
+    get dialogTitle(): string | null;
+    set dialogTitle(value: string | null);
+    get dialogDescription(): string | null;
+    set dialogDescription(value: string | null);
+    get externalUserId(): string | null;
+    set externalUserId(value: string | null);
+    /**
+     * Reset override: transitions to IDLE, clears ceremony and emits `mellon:cancelled` if was AUTHENTICATING.
+     * Also emits `mellon:close` with the reason for the current state (success | cancel | error | user).
+     * Host must call `reset()` before reopening if the WC stays in the DOM for a clean state.
+     */
+    disconnectedCallback(): void;
+    reset(): void;
+    protected getTabKind(): TabKind;
+    protected getCoreAuthOptions(): {
+        externalUserId?: string | null;
+    };
+    /** Single path: explicit attr > generated UUID for register > none. No special-case branches in getCoreAuthOptions. */
+    private _resolveExternalUserId;
+    /** Passkey register is always allowed (external user id optional; SDK uses UUID when not set). */
+    protected canStartAuth(): boolean;
+    protected getEnvEvalParams(): Omit<RunEnvEvalParams, 'envStatusPort' | 'currentState'>;
+    protected getCoreConfig(): {
+        appId: string;
+        publishableKey: string;
+    } | null;
+    protected getFallbackDetail(): MellonFallbackDetail;
+    /** Reflects open/mode in DOM (wrapper/overlay hidden). Syncs focus trap: activate when open, deactivate restores focus on close. */
+    private _applyModalVisibility;
+    protected _render(): void;
+}
+
+/**
+ * Pure UI FSM — no DOM, no I/O. (currentState, event) → nextState.
+ * Transitions per 02-fsm-estado-modal.
+ */
+
+/**
+ * Next FSM state from current state and event. RESET from any state → IDLE.
+ * Undefined transitions leave state unchanged (idempotent).
+ */
+declare function getNextState(currentState: UIState, event: FSMEvent): UIState;
+
+/**
+ * WC styles. Injected via adoptedStyleSheets or <style> + textContent. No innerHTML.
+ * Constructable Stylesheet when supported; <style> fallback (e.g. Safari <16.4).
+ */
+/**
+ * Host overrides via CSS custom properties. Delegation: --mellon-* fallback to MDS-like tokens
+ * (--surface-elevated, --text-strong, etc.) so the host can drive look without coupling.
+ * Default: white-label minimal TryMellon — neutral with a cool tint (220°), WCAG AA.
+ * Theming and accessibility are configurable via WC attributes and host CSS.
+ */
+declare const BASE_STYLES: string;
+/** Returns CSSStyleSheet for adoptedStyleSheets when supported; null otherwise (use <style> + textContent). */
+declare function createConstructableStylesheet(): CSSStyleSheet | null;
+/** Returns CSS string for <style> textContent (fallback). */
+declare function getStylesFallback(): string;
+
+/**
+ * Centralized constants for the infra layer (event bridge).
+ * CustomEvent names for core → host communication.
+ */
+/** Event name when modal opens (WC lifecycle). */
+declare const MELLON_OPEN = "mellon:open";
+/** Event name when button/host requests modal open. bubbles: true, composed: true; detail empty or minimal. */
+declare const MELLON_OPEN_REQUEST = "mellon:open-request";
+/** Event name when modal closes (WC lifecycle). */
+declare const MELLON_CLOSE = "mellon:close";
+/** Event name when auth completes (core → host). bubbles: false, composed: true; listener on WC element. */
+declare const MELLON_SUCCESS = "mellon:success";
+/** Event name when auth fails (core → host). bubbles: true, composed: true. */
+declare const MELLON_ERROR = "mellon:error";
+/** Event name when ceremony starts (core → host). */
+declare const MELLON_START = "mellon:start";
+/** Event name when ceremony is cancelled (host close or reset from AUTHENTICATING). bubbles: true, composed: true. */
+declare const MELLON_CANCELLED = "mellon:cancelled";
+/** Fired on fallback UI click inside WC (no external navigation). */
+declare const MELLON_FALLBACK = "mellon:fallback";
+/** Event name when tab changes (register ↔ login) in the modal. */
+declare const MELLON_TAB_CHANGE = "mellon:tab-change";
+
+/**
+ * Event bridge: Core EventEmitter → DOM CustomEvents on the WC host element.
+ * Token only in mellon:success; bubbles:false, composed:true. At most once success per ceremony; no error after success.
+ * Payload as unknown; narrow with type guards to port types. P1-B: nonce in detail when present; no public API to dispatch success with arbitrary detail.
+ * Constants: infra/constants.ts.
+ */
+
+/** Event-bridge adapter: CoreEventsPort (core → CustomEvents on host). */
+declare const eventBridgeAdapter: CoreEventsPort;
+
+/** @trymellon/js/ui — Web Component entry. */
+
+declare const UI_VERSION = "0.1.0";
+/** Canonical tag: button + internal modal (Option A) or trigger only (Option B with trigger-only). */
+declare const TRYMELLON_AUTH_TAG = "trymellon-auth";
+/** Modal tag; used internally by <trymellon-auth> (Option A) or by host (Option B). */
+declare const TRYMELLON_AUTH_MODAL_TAG = "trymellon-auth-modal";
+
+export { BASE_STYLES, type CoreEventsPort, type CoreWithEvents, type EnvResolvedPayload, type FSMEvent, INITIAL_UI_STATE, MELLON_CANCELLED, MELLON_CLOSE, MELLON_ERROR, MELLON_FALLBACK, MELLON_OPEN, MELLON_OPEN_REQUEST, MELLON_START, MELLON_SUCCESS, MELLON_TAB_CHANGE, type MellonCloseDetail, type MellonErrorDetail, type MellonFallbackDetail, type MellonOpenDetail, type MellonOperationDetail, type MellonSuccessDetail, type ParsedAttributes, type RenderOptions, TRYMELLON_AUTH_MODAL_TAG, TRYMELLON_AUTH_TAG, type TabKind, type ThemeKind, TryMellonAuthElement, TryMellonAuthModalElement, type UIMode, type UIState, UI_VERSION, createConstructableStylesheet, eventBridgeAdapter, getNextState, getStylesFallback };