@statewalker/httpeers-join 0.1.3

package/dist/widget.js

@@ -0,0 +1,375 @@
+/**
+ * The join widget: one small piece of DOM that renders a `SessionState` and
+ * calls the session's four controls.
+ *
+ * IT HOLDS NO SESSION STATE OF ITS OWN. `PeerSession` already decides every
+ * thing worth deciding -- which phase, which message, which controls make
+ * sense (`SessionState.controls`) -- and the widget only shows it. The page
+ * owns the session and hands each new state to `update()`, because the session
+ * reports changes through one `onChange` callback that the page wires up when
+ * it creates it; the widget cannot subscribe on its own.
+ *
+ * What the widget DOES own is what exists only on screen: the text being
+ * typed, a camera that is running, a button that is waiting on its call, and
+ * the complaint left by a call that rejected.
+ *
+ * NOTHING HAPPENS AT IMPORT. No `document`, no `window`, no stylesheet until
+ * `mountJoinWidget` runs -- `tests/import.test.ts` imports the built entry
+ * under plain Node to hold the package to that, because a page's bundle may
+ * import this module long before it has anything to mount.
+ */
+import { createInvitePanel } from "./invite-panel.js";
+import { defaultQrScanner } from "./qr.js";
+import { injectJoinWidgetStyles } from "./styles.js";
+/** What "Leave this mesh" asks before it forgets the identity. */
+export const LEAVE_CONFIRMATION = "Leave this mesh and forget this browser's identity?\n\n" +
+    "This page becomes a different peer: its current membership is left behind on the hub, and " +
+    "joining again needs a new invitation. The page reloads afterwards.";
+/** `12D3KooW…a1b2c3`: enough to tell two peers apart on screen. The whole id goes in a tooltip. */
+export function shortPeerId(peerId) {
+    return peerId.length <= 18 ? peerId : `${peerId.slice(0, 10)}…${peerId.slice(-6)}`;
+}
+/** The status line's text for a state, for a page that wants it without the widget. */
+export function describePhase(state) {
+    const phase = state?.phase;
+    if (phase == null)
+        return "Starting…";
+    switch (phase.kind) {
+        case "checking":
+            return "Checking this browser's identity…";
+        case "starting":
+            return `Joining… (${phase.peerState})`;
+        case "live":
+            return state?.hubLink == null ? "Connected" : `Connected (${state.hubLink})`;
+        case "needs-invitation":
+            return "Not joined: an invitation is needed";
+        case "disconnected":
+            return "Disconnected";
+        case "blocked":
+            return "Blocked";
+        case "failed":
+            return "Could not join";
+    }
+}
+/**
+ * The phase message, and whether it is news or trouble. A first run asking for
+ * an invitation is instructions (`status`); a hub that no longer knows this
+ * peer, a refused invitation, a duplicate tab or a failure is trouble
+ * (`alert`), and an operator's screen reader should say so.
+ */
+function messageOf(state) {
+    const phase = state?.phase;
+    switch (phase?.kind) {
+        case "live":
+            return phase.note == null ? null : { text: phase.note, role: "status" };
+        case "needs-invitation":
+            return {
+                text: phase.message,
+                role: phase.reason === "no-identity" || phase.reason === "no-mesh" ? "status" : "alert",
+            };
+        case "disconnected":
+            return { text: phase.message, role: "status" };
+        case "blocked":
+        case "failed":
+            return { text: phase.message, role: "alert" };
+        default:
+            return null;
+    }
+}
+let instances = 0;
+/**
+ * Build the widget inside `container` and return its handle.
+ *
+ * Every id is suffixed per instance, so two widgets on one page -- a full one
+ * and a compact one in a header -- never share a label target or a camera
+ * host.
+ */
+export function mountJoinWidget(container, options) {
+    const doc = container.ownerDocument;
+    if (options.injectStyles !== false)
+        injectJoinWidgetStyles(doc);
+    const { session } = options;
+    const scanner = options.scanner === undefined ? defaultQrScanner() : options.scanner;
+    const confirmLeave = options.confirm ?? ((message) => doc.defaultView?.confirm(message) ?? false);
+    const compact = options.compact === true;
+    const n = ++instances;
+    const make = (tag, className, text) => {
+        const node = doc.createElement(tag);
+        node.className = className;
+        if (text != null)
+            node.textContent = text;
+        return node;
+    };
+    const button = (className, label) => {
+        const b = make("button", `hp-join-button ${className}`, label);
+        b.type = "button";
+        return b;
+    };
+    // --- structure ----------------------------------------------------------
+    const root = make("div", compact ? "hp-join hp-join-compact" : "hp-join");
+    const status = make("p", "hp-join-status");
+    status.setAttribute("role", "status");
+    const phaseText = make("span", "hp-join-phase");
+    const peer = make("code", "hp-join-peer");
+    // The compact line leaves the peer id to a tooltip: a header has no room for it.
+    if (compact)
+        status.append(phaseText);
+    else
+        status.append(phaseText, " ", peer);
+    const message = make("p", "hp-join-message");
+    const error = make("p", "hp-join-error");
+    error.setAttribute("role", "alert");
+    error.hidden = true;
+    const disconnectButton = button("hp-join-disconnect", "Disconnect");
+    const reconnectButton = button("hp-join-reconnect", "Reconnect");
+    const resetButton = button("hp-join-reset hp-join-danger", "Leave this mesh…");
+    resetButton.title = "Forget this browser's identity. Joining again needs a new invitation.";
+    const controls = make("div", "hp-join-controls");
+    controls.append(disconnectButton, reconnectButton, resetButton);
+    // The join form: only in the full widget.
+    const form = make("form", "hp-join-form");
+    const input = make("textarea", "hp-join-input");
+    input.id = `hp-join-input-${n}`;
+    input.rows = 3;
+    input.placeholder = "a join link, a join blob, or an invitation id";
+    input.autocomplete = "off";
+    input.spellcheck = false;
+    const label = make("label", "hp-join-label", "Paste an invitation");
+    label.htmlFor = input.id;
+    const submit = make("button", "hp-join-button hp-join-primary hp-join-submit", "Join");
+    submit.type = "submit";
+    const cameraButton = button("hp-join-camera", "Scan a QR code");
+    const fileLabel = make("label", "hp-join-button hp-join-file", "Scan a QR picture");
+    const fileInput = make("input", "hp-join-visually-hidden");
+    fileInput.type = "file";
+    fileInput.accept = "image/*";
+    fileLabel.append(fileInput);
+    const actions = make("div", "hp-join-actions");
+    actions.append(submit, cameraButton, fileLabel);
+    const viewfinder = make("div", "hp-join-viewfinder");
+    viewfinder.id = `hp-join-viewfinder-${n}`;
+    viewfinder.hidden = true;
+    const stopCameraButton = button("hp-join-camera-stop", "Stop camera");
+    stopCameraButton.hidden = true;
+    form.append(label, input, actions, viewfinder, stopCameraButton);
+    const invitePanel = options.invite === false ? null : createInvitePanel(doc, make, n, options.invite ?? {});
+    if (compact) {
+        const menu = make("details", "hp-join-menu");
+        const summary = make("summary", "hp-join-menu-toggle", "Mesh");
+        const panel = make("div", "hp-join-menu-panel");
+        panel.append(message, error, controls);
+        if (invitePanel != null)
+            panel.append(invitePanel.element);
+        menu.append(summary, panel);
+        root.append(status, menu);
+    }
+    else {
+        root.append(status, message, error, form, controls);
+        if (invitePanel != null)
+            root.append(invitePanel.element);
+    }
+    container.append(root);
+    // --- behaviour ----------------------------------------------------------
+    let current = null;
+    let camera = null;
+    /** Set while a camera is being STARTED, so a second click or a stop in between is not lost. */
+    let cameraStarting = false;
+    let destroyed = false;
+    /** The buttons whose call has not settled yet. */
+    const pending = new Set();
+    const showError = (text) => {
+        error.textContent = text ?? "";
+        error.hidden = text == null;
+    };
+    /** Run one session call from a button: disabled until it settles, and a rejection shown rather than lost. */
+    const run = async (from, call) => {
+        if (pending.has(from))
+            return;
+        pending.add(from);
+        from.disabled = true;
+        showError(null);
+        try {
+            await call();
+        }
+        catch (err) {
+            showError(err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            pending.delete(from);
+            if (!destroyed)
+                render();
+        }
+    };
+    const stopCamera = async () => {
+        const running = camera;
+        camera = null;
+        viewfinder.hidden = true;
+        stopCameraButton.hidden = true;
+        viewfinder.replaceChildren();
+        await running?.stop().catch(() => { });
+    };
+    const joinWith = (text) => run(submit, async () => {
+        await session.join(text);
+    });
+    const onScanned = (invitation) => {
+        void stopCamera();
+        if (destroyed)
+            return;
+        input.value = invitation;
+        void joinWith(invitation);
+    };
+    const render = () => {
+        const state = current;
+        const phase = state?.phase;
+        root.dataset.phase = phase?.kind ?? "none";
+        phaseText.textContent = describePhase(state);
+        const id = state?.identity ?? null;
+        peer.hidden = id == null;
+        peer.textContent = id == null ? "" : `peer ${shortPeerId(id)}`;
+        for (const node of compact ? [status] : [peer]) {
+            if (id == null)
+                node.removeAttribute("title");
+            else
+                node.title = `This page's peer id: ${id}`;
+        }
+        const said = messageOf(state);
+        message.hidden = said == null;
+        message.textContent = said?.text ?? "";
+        if (said == null)
+            message.removeAttribute("role");
+        else
+            message.setAttribute("role", said.role);
+        const allowed = state?.controls ?? {
+            join: false,
+            disconnect: false,
+            reconnect: false,
+            reset: false,
+        };
+        disconnectButton.hidden = !allowed.disconnect;
+        reconnectButton.hidden = !allowed.reconnect;
+        // The session offers a reset in every settled phase, but with no identity
+        // yet -- a first run -- there is nothing to forget, and "Leave this mesh"
+        // on a page that never joined one would only confuse.
+        const reset = allowed.reset && id != null;
+        resetButton.hidden = !reset;
+        controls.hidden = !(allowed.disconnect || allowed.reconnect || reset);
+        for (const b of [disconnectButton, reconnectButton, resetButton])
+            b.disabled = pending.has(b);
+        form.hidden = compact || !allowed.join;
+        submit.disabled = pending.has(submit) || input.value.trim() === "";
+        cameraButton.hidden = scanner == null || !scanner.cameraAvailable() || camera != null;
+        fileLabel.hidden = scanner == null;
+        // Invite: only while live, and only toward that link's hub.
+        invitePanel?.setTarget(phase?.kind === "live" ? (state?.handle ?? null) : null);
+        // A camera left running behind a form that has gone -- a join started,
+        // or succeeded -- is a light on the operator's laptop for no reason.
+        if (form.hidden && camera != null)
+            void stopCamera();
+    };
+    form.addEventListener("submit", (event) => {
+        event.preventDefault();
+        const text = input.value.trim();
+        if (text !== "")
+            void joinWith(text);
+    });
+    input.addEventListener("input", () => {
+        submit.disabled = pending.has(submit) || input.value.trim() === "";
+    });
+    disconnectButton.addEventListener("click", () => {
+        void run(disconnectButton, () => session.disconnect());
+    });
+    reconnectButton.addEventListener("click", () => {
+        void run(reconnectButton, () => session.reconnect());
+    });
+    resetButton.addEventListener("click", () => {
+        void run(resetButton, async () => {
+            if (!(await confirmLeave(LEAVE_CONFIRMATION)))
+                return;
+            await stopCamera();
+            await session.resetIdentity();
+        });
+    });
+    cameraButton.addEventListener("click", () => {
+        if (scanner == null || camera != null || cameraStarting)
+            return;
+        cameraStarting = true;
+        showError(null);
+        viewfinder.hidden = false;
+        stopCameraButton.hidden = false;
+        cameraButton.hidden = true;
+        scanner.scanCamera(viewfinder, onScanned).then((started) => {
+            cameraStarting = false;
+            // Stopped, destroyed or already scanned while the camera was starting.
+            if (destroyed || viewfinder.hidden) {
+                void started.stop().catch(() => { });
+                return;
+            }
+            camera = started;
+            render();
+        }, (err) => {
+            cameraStarting = false;
+            viewfinder.hidden = true;
+            stopCameraButton.hidden = true;
+            if (destroyed)
+                return;
+            showError(`Could not start the camera (${err instanceof Error ? err.message : String(err)}). ` +
+                "Choose a picture of the QR code instead, or paste the invitation.");
+            render();
+        });
+    });
+    stopCameraButton.addEventListener("click", () => {
+        void stopCamera().then(() => {
+            if (!destroyed)
+                render();
+        });
+    });
+    fileInput.addEventListener("change", () => {
+        const file = fileInput.files?.[0];
+        // Reset, so choosing the SAME picture again fires `change` a second time.
+        fileInput.value = "";
+        if (file == null || scanner == null)
+            return;
+        showError(null);
+        void scanner.scanFile(file).then((found) => {
+            if (destroyed)
+                return;
+            if (found.ok) {
+                input.value = found.invitation;
+                void joinWith(found.invitation);
+            }
+            else {
+                showError(found.reason === "no-qr"
+                    ? "No QR code found in that picture. Try a sharper or closer one."
+                    : "That QR code is not an invitation.");
+            }
+        }, (err) => {
+            if (!destroyed)
+                showError(`Could not read that picture: ${String(err)}`);
+        });
+    });
+    const update = (state) => {
+        if (destroyed)
+            return;
+        // A join that went through leaves nothing to rejoin with: clear the field
+        // so a later failure does not offer the spent invitation back.
+        if (state?.phase.kind === "live" && current?.phase.kind !== "live")
+            input.value = "";
+        if (state?.phase.kind === "live")
+            showError(null);
+        current = state;
+        render();
+    };
+    update(options.state ?? null);
+    return {
+        element: root,
+        update,
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            void stopCamera();
+            invitePanel?.destroy();
+            root.remove();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@statewalker/httpeers-join",
+  "version": "0.1.3",
+  "type": "module",
+  "description": "The join-the-mesh widget: paste or scan an invitation, see the link to the hub, disconnect, reconnect or leave. Plain DOM, no framework.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/statewalker/httpeers.git",
+    "directory": "packages/httpeers-join"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "html5-qrcode": "^2.3.8",
+    "@statewalker/httpeers-member": "^0.1.4",
+    "@statewalker/httpeers-qr": "^0.1.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@types/node": "^26.6.4",
+    "happy-dom": "^20.14.5",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "pnpm run build && pnpm run typecheck && vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src tests",
+    "lint:check": "biome check src tests"
+  }
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * The join-the-mesh widget: paste or scan an invitation, see the link to the
+ * hub, disconnect, reconnect or leave -- and, for a mesh admin, invite
+ * others as members or admins.
+ *
+ * Plain DOM and no framework. A page mounts it, feeds it every `SessionState`
+ * its `PeerSession` reports, and destroys it when done:
+ *
+ *     const widget = mountJoinWidget(el, { session, state: session.state() });
+ *     // in the session's onChange:
+ *     widget.update(state);
+ *
+ * See the README for the design and for how React pages wrap it.
+ */
+
+export {
+  ADMIN_INVITATION_WARNING,
+  adminHint,
+  type CreatedInvitation,
+  createHubAdminClient,
+  DEFAULT_INVITE_EXPIRY,
+  DEFAULT_INVITE_ROLE,
+  describeExpiry,
+  expiryMs,
+  type HubAdminClient,
+  HubAdminError,
+  type HubTarget,
+  hubAdminBase,
+  INVITE_EXPIRIES,
+  INVITE_ROLES,
+  type InviteExpiryId,
+  type InviteRole,
+  invitationRequestBody,
+  isFinalRefusal,
+  type MeshViewHint,
+  offeredRoles,
+  type PendingInvitation,
+} from "./invite.js";
+export { createInvitePanel, type InvitePanel, type InvitePanelOptions } from "./invite-panel.js";
+export {
+  defaultQrScanner,
+  type QrCameraScan,
+  type QrFileScan,
+  type QrScanner,
+} from "./qr.js";
+export { injectJoinWidgetStyles, JOIN_WIDGET_CSS, JOIN_WIDGET_STYLE_ID } from "./styles.js";
+export {
+  describePhase,
+  type JoinWidget,
+  type JoinWidgetOptions,
+  type JoinWidgetSession,
+  type JoinWidgetState,
+  LEAVE_CONFIRMATION,
+  mountJoinWidget,
+  shortPeerId,
+} from "./widget.js";