@qrauth/web-components 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# @qrauth/web-components
+
+## 0.3.0
+
+- `<qrauth-2fa>`: mobile-aware pending state. Primary CTA opens the hosted approval page (`/a/:token`) in a new tab; QR demoted to a "Use another device" expander. Polling in the original tab continues to fire `qrauth:verified` on approval. Adds `force-mode` and `mobile-fallback-only` attributes.
+- `<qrauth-ephemeral>`: adds `force-mode` and `mobile-fallback-only` attributes for forward compatibility. No default mobile UI change — the ephemeral flow is a QR meant to be scanned by another device, so QR-first remains correct on all viewports.
+
+## 0.2.0 — 2026-04-18
+
+### Minor
+
+- **`<qrauth-login>` — mobile-aware pending state.** Mobile-aware pending state: primary CTA opens the hosted approval page (`/a/:token`) in a new tab. QR demoted to a "Use another device" expander. Polling in the original tab continues to fire `qrauth:authenticated` on approval.
+- **New attribute `force-mode="mobile" | "desktop" | "auto"`** — overrides the automatic detection. Useful for demos, screenshots, and host sites that know their audience's form factor.
+- **New attribute `mobile-fallback-only`** — when present, disables the mobile-aware UI entirely and keeps the QR-first body on every device. Intended for host sites that already provide a same-device login path around the component; the QRAuth modal is then purely the cross-device scan option.
+- **Shared `isMobileLike()` detector on `QRAuthElement`** — base-class helper so `<qrauth-2fa>` and `<qrauth-ephemeral>` can adopt the same branch without refactor when they grow analogous mobile-aware modes.
+- **`MOBILE_MEDIA_QUERY` export** — `'(pointer: coarse) and (hover: none)'`, for documentation and test mocks.
+
+### Internal
+
+- Added `vitest` + `happy-dom` test harness (`npm test` runs the new `tests/login.mobile.test.ts`).
+- Added Playwright spec `packages/e2e/tests/qrauth-login-mobile.spec.ts` under an iPhone 13 viewport (chromium-emulated).
+- Bundle size: 10.4 KB gzipped IIFE / 10.2 KB gzipped ESM (target was <12 KB).
+
+### Non-breaking
+
+- Event surface (`qrauth:authenticated`, `qrauth:scanned`, `qrauth:expired`, `qrauth:denied`, `qrauth:error`) unchanged.
+- Desktop pending body markup unchanged.
+- Polling / SSE path unchanged — APPROVED transitions still fire `qrauth:authenticated` regardless of whether approval completed on the hosted page or via a scanned QR.
+
+## 0.1.0
+
+- Initial release: `<qrauth-login>`, `<qrauth-2fa>`, `<qrauth-ephemeral>` Shadow DOM custom elements.

package/README.md

@@ -0,0 +1,105 @@
+# @qrauth/web-components
+
+Drop-in Web Components for [QRAuth](https://qrauth.io) — passwordless QR authentication, 2FA, and ephemeral delegated access. Shadow DOM, framework-free, ~10 KB gzipped.
+
+- `<qrauth-login>` — passwordless sign-in, button or inline. Mobile-aware pending state (tap-to-continue CTA with QR demoted under a "Use another device" expander).
+- `<qrauth-2fa>` — drop-in second-factor step with session-token binding.
+- `<qrauth-ephemeral>` — time-limited, device-bound access QRs.
+
+All three components bubble `qrauth:*` events across the Shadow DOM boundary (`composed: true`) so any framework can listen with plain `addEventListener`.
+
+## Install
+
+```bash
+npm install @qrauth/web-components
+```
+
+Or load the CDN IIFE directly in any HTML page:
+
+```html
+<script
+  src="https://cdn.qrauth.io/v1/components.js"
+  integrity="sha384-..."
+  crossorigin="anonymous"
+></script>
+
+<qrauth-login tenant="your-app-id"></qrauth-login>
+```
+
+## Quickstart
+
+```html
+<qrauth-login
+  tenant="qrauth_app_xxx"
+  theme="light"
+  base-url="https://qrauth.io"
+></qrauth-login>
+
+<script>
+  document.querySelector('qrauth-login').addEventListener('qrauth:authenticated', (e) => {
+    const { sessionId, user, signature } = e.detail;
+    // Exchange sessionId + signature server-side for your own session.
+  });
+</script>
+```
+
+## Attributes (login)
+
+| Attribute | Values | Default | Purpose |
+|---|---|---|---|
+| `tenant` | string | — | Your QRAuth App client ID. Required. |
+| `theme` | `light` \| `dark` | `light` | Colour scheme. |
+| `base-url` | URL | `https://qrauth.io` | API host. Override for staging / local dev. |
+| `scopes` | space-separated | `identity` | OAuth-style scopes requested. |
+| `redirect-url` | URL | — | Auto-redirect after success. |
+| `on-auth` | string | — | Name of a global function to invoke on success. |
+| `display` | `button` \| `inline` | `button` | Modal trigger vs. embedded widget. |
+| `animated` | boolean | off | Enables the pulse animation on the QR. |
+| `force-mode` | `mobile` \| `desktop` \| `auto` | `auto` | Override automatic mobile detection. |
+| `mobile-fallback-only` | boolean | off | Keep the QR-first body on every device; disables the mobile CTA path. |
+
+## Events
+
+All events bubble across the Shadow DOM (`composed: true`):
+
+- `qrauth:authenticated` — `detail: { sessionId, user, signature }`
+- `qrauth:scanned` — fired on the PENDING → SCANNED transition (pre-approval)
+- `qrauth:expired` — session timed out
+- `qrauth:denied` — user denied approval on their device
+- `qrauth:error` — `detail: { message }`
+
+## Theming
+
+Override any of the following CSS custom properties on the host page or on the element itself:
+
+```css
+qrauth-login {
+  --qrauth-primary: #00a76f;
+  --qrauth-text: #1a1a2e;
+  --qrauth-bg: #ffffff;
+  --qrauth-surface: #f9fafb;
+  --qrauth-border: #e0e0e0;
+  --qrauth-radius: 12px;
+  --qrauth-btn-bg: #1b2a4a;
+  --qrauth-btn-hover: #263b66;
+  --qrauth-shadow: 0 24px 48px rgba(0, 0, 0, 0.15);
+  --qrauth-font: 'Inter', sans-serif;
+}
+```
+
+Or flip the bundled dark palette via `theme="dark"`.
+
+## Framework integration
+
+The components are framework-free native Custom Elements. They work in React, Vue, Svelte, Angular, plain HTML — wherever the browser exposes `customElements`. For React, wrap event listeners in `useEffect` because React's synthetic event system doesn't observe custom events directly.
+
+## Links
+
+- [Homepage](https://qrauth.io)
+- [Docs](https://docs.qrauth.io)
+- [Signing Architecture](https://docs.qrauth.io/guide/signing-architecture) — cryptographic model behind every approved session
+- [Issues](https://github.com/qrauth-io/qrauth/issues)
+
+## License
+
+MIT.

package/dist/base.d.ts

@@ -3,6 +3,11 @@
  * Provides: Shadow DOM setup, CSS custom property theming, SSE connection management,
  * lifecycle hooks, and event dispatching.
  */
+/**
+ * Media query that identifies mobile-like devices (coarse pointer + no hover).
+ * Exported for documentation and test mocks.
+ */
+export declare const MOBILE_MEDIA_QUERY = "(pointer: coarse) and (hover: none)";
 export declare abstract class QRAuthElement extends HTMLElement {
     protected shadow: ShadowRoot;
     private _sseConnection;
@@ -16,6 +21,22 @@ export declare abstract class QRAuthElement extends HTMLElement {
     disconnectedCallback(): void;
     attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void;
     protected abstract render(): void;
+    /**
+     * Detect whether the component is running on a mobile-like device. Subclasses
+     * may use this to branch UX — e.g. `<qrauth-login>` swaps the big QR for a
+     * "Continue on this device" CTA when isMobileLike() returns true, since the
+     * scan-with-another-device flow is a dead end when the user already IS the
+     * phone. Resolution order:
+     *
+     *   1. `force-mode="mobile"` or `force-mode="desktop"` attribute — wins.
+     *   2. `mobile-fallback-only` attribute — always returns false (keeps the
+     *      component's QR-only behaviour even on phones; consumers opt in here
+     *      when they provide their own alternative flow around the component).
+     *   3. matchMedia on `(pointer: coarse)` + `(hover: none)` (both must match).
+     *   4. UA sniff fallback for environments without matchMedia (headless tests,
+     *      old browsers).
+     */
+    protected isMobileLike(): boolean;
     protected connectSSE(url: string): void;
     protected onSSEEvent(event: string, callback: (data: unknown) => void): void;
     protected disconnectSSE(): void;

package/dist/ephemeral.d.ts

@@ -4,14 +4,25 @@ import { QRAuthElement } from './base.js';
  * and claim status updates.
  *
  * Attributes:
- *   tenant         — Your QRAuth App client ID (required)
- *   theme          — "light" (default) | "dark"
- *   base-url       — API base URL (default: https://qrauth.io)
- *   scopes         — Space-separated scope strings (default: "access")
- *   ttl            — TTL string like "30m", "6h", "1d" (default: "30m")
- *   max-uses       — Maximum number of claims (default: "1")
- *   device-binding — Boolean attribute; present = device binding enabled
- *   display        — "button" | "inline" (default: "inline")
+ *   tenant                — Your QRAuth App client ID (required)
+ *   theme                 — "light" (default) | "dark"
+ *   base-url              — API base URL (default: https://qrauth.io)
+ *   scopes                — Space-separated scope strings (default: "access")
+ *   ttl                   — TTL string like "30m", "6h", "1d" (default: "30m")
+ *   max-uses              — Maximum number of claims (default: "1")
+ *   device-binding        — Boolean attribute; present = device binding enabled
+ *   display               — "button" | "inline" (default: "inline")
+ *   force-mode            — Reserved for future mobile-variant UI; no default
+ *                           behavior change on mobile viewports as of 0.3.0.
+ *                           The ephemeral flow is inherently "generate QR for
+ *                           another device to scan", so QR-first is correct
+ *                           regardless of form factor. Accepted values:
+ *                           "mobile" | "desktop" | "auto" (default "auto").
+ *   mobile-fallback-only  — Reserved for forward compatibility with the
+ *                           pattern used by <qrauth-login> and <qrauth-2fa>.
+ *                           No effect in 0.3.0 — included so consumers can
+ *                           start passing it without breakage when a future
+ *                           mobile-variant UI is added.
  *
  * Events (bubbles + composed, cross shadow-DOM):
  *   qrauth:claimed  — detail: { sessionId, status, scopes, metadata, useCount, maxUses }
@@ -36,6 +47,12 @@ export declare class QRAuthEphemeral extends QRAuthElement {
     get maxUses(): number;
     get deviceBinding(): boolean;
     get display(): string;
+    /**
+     * Reserved attribute — no effect in 0.3.0. See JSDoc header above for why
+     * the ephemeral flow intentionally keeps the QR-first body on mobile.
+     */
+    get forceMode(): 'mobile' | 'desktop' | 'auto';
+    get mobileFallbackOnly(): boolean;
     disconnectedCallback(): void;
     protected render(): void;
     private _renderButton;

package/dist/login.d.ts

@@ -3,14 +3,24 @@ import { QRAuthElement } from './base.js';
  * <qrauth-login> — Drop-in QR authentication button / inline widget.
  *
  * Attributes:
- *   tenant        — Your QRAuth App client ID (required)
- *   theme         — "light" (default) | "dark"
- *   base-url      — API base URL (default: https://qrauth.io)
- *   scopes        — Space-separated scopes (default: "identity")
- *   redirect-url  — Optional redirect after successful auth
- *   on-auth       — Name of a global callback function to call on success
- *   display       — "button" (default) | "inline"
- *   animated      — If present, enables subtle QR pulse animation
+ *   tenant                — Your QRAuth App client ID (required)
+ *   theme                 — "light" (default) | "dark"
+ *   base-url              — API base URL (default: https://qrauth.io)
+ *   scopes                — Space-separated scopes (default: "identity")
+ *   redirect-url          — Optional redirect after successful auth
+ *   on-auth               — Name of a global callback function to call on success
+ *   display               — "button" (default) | "inline"
+ *   animated              — If present, enables subtle QR pulse animation
+ *   force-mode            — "mobile" | "desktop" | "auto" (default "auto").
+ *                           Overrides the automatic mobile-like detection that
+ *                           swaps the QR-first body for a "Continue with
+ *                           QRAuth" CTA + QR expander on phones and tablets.
+ *   mobile-fallback-only  — If present, disables the mobile-aware UI entirely
+ *                           and keeps the QR-first body on every device. Use
+ *                           this when the surrounding page already provides an
+ *                           alternative same-device login path and the
+ *                           component is only there as the cross-device scan
+ *                           option.
  *
  * Events (bubbles + composed, cross shadow-DOM):
  *   qrauth:authenticated  — detail: { sessionId, user, signature }
@@ -25,6 +35,7 @@ import { QRAuthElement } from './base.js';
 export declare class QRAuthLogin extends QRAuthElement {
     static get observedAttributes(): string[];
     private _sessionId;
+    private _sessionToken;
     private _codeVerifier;
     private _status;
     private _expiresAt;
@@ -35,6 +46,8 @@ export declare class QRAuthLogin extends QRAuthElement {
     get onAuth(): string | null;
     get display(): string;
     get animated(): boolean;
+    get forceMode(): 'mobile' | 'desktop' | 'auto';
+    get mobileFallbackOnly(): boolean;
     disconnectedCallback(): void;
     protected render(): void;
     private _renderButton;
@@ -42,10 +55,30 @@ export declare class QRAuthLogin extends QRAuthElement {
     private _inlineIdleContent;
     private _modalContent;
     private _bodyForStatus;
+    /**
+     * Shared QR frame markup used by both the desktop pending body and the
+     * mobile "Use another device" expander. Centralised so the two paths can't
+     * drift.
+     */
+    private _qrFrameHtml;
+    /**
+     * Mobile-aware pending body. Primary CTA opens the hosted approval page
+     * (/a/:token) in a new tab — this same-device path short-circuits the
+     * cross-device QR scan that is a dead end on phones. The QR itself is
+     * demoted to a collapsed expander for the "I have a second device" case.
+     */
+    private _mobilePendingBody;
     private _sharedModalStyles;
     private _bindButtonEvents;
     private _bindInlineEvents;
     private _bindModalButtons;
+    /**
+     * Mobile same-device path: open the hosted approval page in a new tab.
+     * The existing polling loop in _beginPolling picks up SCANNED / APPROVED
+     * transitions from the server once the user completes the flow there,
+     * so qrauth:scanned and qrauth:authenticated fire unchanged.
+     */
+    private _openApprovalPage;
     private _openModal;
     private _closeModal;
     private _startAuth;