@tollbooth-dpyc/web 1.7.1 → 1.8.1

package/dist/tour/lint.js

@@ -0,0 +1,47 @@
+/**
+ * The voice a tour speaks in, checked.
+ *
+ * A step says what a control is and what to do with it, in one or two short
+ * sentences. It never says what something is not, and never contrasts: "your
+ * npub is your key" and never "your key, not a password". A site's test runs
+ * its tours through this so every site holds the same voice.
+ */
+const CONTRAST = /\b(not|no|never|nothing|instead of|rather than)\b/i;
+export const MAX_SAYS = 180;
+export const MAX_TITLE = 28;
+export const MAX_SENTENCES = 2;
+function sentences(text) {
+    return text.split(/[.!?](\s|$)/).filter((x) => x.trim()).length;
+}
+/** The problems with one step's words, each a sentence; none when it is well said. */
+export function lintStep(s, page = "") {
+    const where = page ? `${page} "${s.title}"` : `"${s.title}"`;
+    const out = [];
+    if (!s.title.trim())
+        out.push(`${where}: has no title`);
+    if (s.title.length > MAX_TITLE)
+        out.push(`${where}: the title runs ${s.title.length} characters`);
+    if (!s.says.trim())
+        out.push(`${where}: says nothing`);
+    if (s.says.length > MAX_SAYS)
+        out.push(`${where}: runs ${s.says.length} characters`);
+    if (sentences(s.says) > MAX_SENTENCES)
+        out.push(`${where}: is more than ${MAX_SENTENCES} sentences`);
+    const m = CONTRAST.exec(s.says) ?? CONTRAST.exec(s.title);
+    if (m)
+        out.push(`${where}: says what something is not ("${m[0]}"): ${s.says}`);
+    return out;
+}
+/** Every problem in a tour's words. */
+export function lintTour(t) {
+    const out = [];
+    if (!t.steps.length)
+        out.push(`${t.page}: has no steps`);
+    for (const s of t.steps)
+        out.push(...lintStep(s, t.page));
+    return out;
+}
+/** Every problem across a site's tours. */
+export function lintTours(tours) {
+    return Object.values(tours).flatMap(lintTour);
+}

package/dist/tour/run.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A tour as driver.js runs it, and the offer that precedes it.
+ *
+ * driver.js draws the popover and the cutout. This adds what it has no idea
+ * of: a page action before a step whose control must be opened first, a tour
+ * that ends when nothing later can be shown, a "Stop the tutorial" link in
+ * every popover, and the centred question a page asks after a quiet while.
+ *
+ * DOM code, so it is untested here as its peers are; the rules it applies
+ * live in `./state.ts` and `./idle.ts`, which are.
+ */
+import type { Tour } from "./types.ts";
+export interface TourRun {
+    start(): void;
+    /** Take the tour down. `silent` is for the page leaving under it. */
+    stop(silent?: boolean): void;
+}
+export interface TourHooks {
+    /** Do what a step asks for before it is pointed at. */
+    run(action: string): void | Promise<void>;
+    /** The tour ended by its last step or its ✕: this page is done. */
+    onEnd(): void;
+    /** "Stop the tutorial": off on every page. */
+    onStop(): void;
+}
+export declare const POPOVER_CLASS = "tb-tour";
+export declare function selector(name: string): string;
+export declare function buildTour(tour: Tour, hooks: TourHooks): TourRun;
+export interface OfferHooks {
+    onYes(): void;
+    /** "No", the ✕, or a tap outside: this page is done being asked. */
+    onNo(): void;
+}
+export interface Offer {
+    show(): void;
+    /** Take the question down without answering it. */
+    dismiss(): void;
+}
+/** The question a page asks after a quiet while, centred, with Yes and No. */
+export declare function offerTour(hooks: OfferHooks, words?: OfferWords): Offer;
+export interface OfferWords {
+    title: string;
+    says: string;
+    yes: string;
+    no: string;
+}
+export declare const OFFER_WORDS: OfferWords;

package/dist/tour/run.js

@@ -0,0 +1,163 @@
+/**
+ * A tour as driver.js runs it, and the offer that precedes it.
+ *
+ * driver.js draws the popover and the cutout. This adds what it has no idea
+ * of: a page action before a step whose control must be opened first, a tour
+ * that ends when nothing later can be shown, a "Stop the tutorial" link in
+ * every popover, and the centred question a page asks after a quiet while.
+ *
+ * DOM code, so it is untested here as its peers are; the rules it applies
+ * live in `./state.ts` and `./idle.ts`, which are.
+ */
+import { driver } from "driver.js";
+/** How long to wait for a control that a page action is still opening. */
+const WAIT_MS = 1500;
+export const POPOVER_CLASS = "tb-tour";
+export function selector(name) {
+    return `[data-tour="${name}"]`;
+}
+/** Whether a step's control is on the page right now. */
+function present(s) {
+    return typeof s.target === "string" ? !!document.querySelector(selector(s.target)) : !!s.target();
+}
+export function buildTour(tour, hooks) {
+    let silent = false;
+    // The step at or after `from` that can be shown: its control is on the
+    // page, or its page action will put it there. driver.js's own skipping of
+    // a missing element loses its place when the FIRST steps are missing, so
+    // the tour moves by index and decides for itself.
+    const showable = (from) => tour.steps.findIndex((s, j) => j >= from && (Boolean(s.before) || present(s)));
+    const showableBack = (from) => {
+        for (let j = from; j >= 0; j--)
+            if (present(tour.steps[j]))
+                return j;
+        return -1;
+    };
+    const steps = tour.steps.map((s) => ({
+        // driver.js types a finder as returning an Element; one that finds
+        // nothing returns null, which it treats as a missing element and skips.
+        element: typeof s.target === "string" ? selector(s.target) : s.target,
+        popover: {
+            title: s.title,
+            description: s.says,
+            side: s.side ?? "bottom",
+            align: s.align ?? "start",
+        },
+    }));
+    const d = driver({
+        steps,
+        popoverClass: POPOVER_CLASS,
+        showProgress: true,
+        progressText: "{{current}} of {{total}}",
+        nextBtnText: "Next",
+        prevBtnText: "Back",
+        doneBtnText: "Done",
+        allowClose: true,
+        overlayOpacity: 0.45,
+        stagePadding: 6,
+        stageRadius: 8,
+        smoothScroll: true,
+        skipMissingElement: true,
+        waitForElement: WAIT_MS,
+        onPopoverRender(popover) {
+            const stop = document.createElement("button");
+            stop.type = "button";
+            stop.className = "tb-tour-stop";
+            stop.textContent = "Stop the tutorial";
+            stop.addEventListener("click", () => { silent = true; hooks.onStop(); d.destroy(); });
+            popover.wrapper.appendChild(stop);
+        },
+        async onNextClick() {
+            // With no showable step left the tour is over.
+            const i = d.getActiveIndex() ?? 0;
+            const n = showable(i + 1);
+            if (n < 0) {
+                d.destroy();
+                return;
+            }
+            const next = tour.steps[n];
+            if (next.before)
+                await hooks.run(next.before);
+            d.moveTo(n);
+        },
+        onPrevClick() {
+            const i = d.getActiveIndex() ?? 0;
+            const b = showableBack(i - 1);
+            if (b >= 0)
+                d.moveTo(b);
+        },
+        onDestroyed() {
+            if (!silent)
+                hooks.onEnd();
+        },
+    });
+    return {
+        start() {
+            const i = showable(0);
+            if (i < 0) {
+                hooks.onEnd();
+                return;
+            }
+            const first = tour.steps[i];
+            if (first.before)
+                void Promise.resolve(hooks.run(first.before)).then(() => d.drive(i));
+            else
+                d.drive(i);
+        },
+        stop(quiet = true) {
+            silent = quiet;
+            if (d.isActive())
+                d.destroy();
+        },
+    };
+}
+/** The question a page asks after a quiet while, centred, with Yes and No. */
+export function offerTour(hooks, words = OFFER_WORDS) {
+    let answered = false;
+    let quiet = false;
+    const d = driver({
+        popoverClass: `${POPOVER_CLASS} tb-tour-offer`,
+        showButtons: [],
+        allowClose: true,
+        overlayOpacity: 0.3,
+        onPopoverRender(popover) {
+            const row = document.createElement("div");
+            row.className = "tb-tour-answer";
+            const no = document.createElement("button");
+            no.type = "button";
+            no.className = "tb-tour-no";
+            no.textContent = words.no;
+            no.addEventListener("click", () => { answered = true; d.destroy(); hooks.onNo(); });
+            const yes = document.createElement("button");
+            yes.type = "button";
+            yes.className = "tb-tour-yes";
+            yes.textContent = words.yes;
+            // The tour starts on the next tick. Started inside this click, the
+            // click would go on to the new tour's outside-click listener and close
+            // it before it was seen.
+            yes.addEventListener("click", () => { answered = true; d.destroy(); window.setTimeout(hooks.onYes, 0); });
+            row.append(no, yes);
+            popover.wrapper.appendChild(row);
+        },
+        onDestroyed() {
+            if (!answered && !quiet)
+                hooks.onNo();
+        },
+    });
+    return {
+        show() {
+            d.highlight({ popover: { title: words.title, description: words.says } });
+        },
+        dismiss() {
+            quiet = true;
+            if (d.isActive())
+                d.destroy();
+        },
+    };
+}
+export const OFFER_WORDS = {
+    title: "A tour?",
+    says: "Would you like a tour of this page? It points at each control and says what it is for.",
+    yes: "Yes",
+    no: "No",
+};

package/dist/tour/state.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Who sees a tour, and when it stops.
+ *
+ * Three facts, kept per site and per device: whether the live tutorial is on,
+ * which pages have had their tour, and a page asked to replay once from its
+ * guide. A new device starts with the tutorial on. A device that already
+ * holds a patron npub but no tour preference has been here since before the
+ * tour existed, and starts with it off — a patron who has used the site for a
+ * season is shown nothing until they ask.
+ */
+export interface TourPrefs {
+    on: boolean;
+    toured: Record<string, true>;
+    /** A page asked to show its tour once more, whatever the switch says. */
+    replay: string | null;
+}
+export declare const TOUR_DEFAULTS: TourPrefs;
+/** Should this page's tour be offered now? */
+export declare function shouldRun(p: TourPrefs, page: string): boolean;
+/** The page's tour ended — by its last step, its ✕, or a "No". Done for this device. */
+export declare function markToured<P extends TourPrefs>(p: P, page: string): P;
+/** "Stop the tutorial", from any popover: off on every page. */
+export declare function stopAll<P extends TourPrefs>(p: P): P;
+/** The switch turned on in the profile: every page offers its tour again. */
+export declare function replayAll<P extends TourPrefs>(p: P): P;
+/** "Show me on the page", from a guide: that page once more, and only it. */
+export declare function replayPage<P extends TourPrefs>(p: P, page: string): P;
+/**
+ * The preference as stored, read back. `raw` is the parsed JSON or null when
+ * nothing is stored; `oldHand` says whether this device already held a patron
+ * npub, which is what makes a device with no preference an old hand rather
+ * than a newcomer.
+ */
+export declare function fromStored(raw: unknown, oldHand: boolean): TourPrefs;

package/dist/tour/state.js

@@ -0,0 +1,54 @@
+/**
+ * Who sees a tour, and when it stops.
+ *
+ * Three facts, kept per site and per device: whether the live tutorial is on,
+ * which pages have had their tour, and a page asked to replay once from its
+ * guide. A new device starts with the tutorial on. A device that already
+ * holds a patron npub but no tour preference has been here since before the
+ * tour existed, and starts with it off — a patron who has used the site for a
+ * season is shown nothing until they ask.
+ */
+export const TOUR_DEFAULTS = { on: true, toured: {}, replay: null };
+/** Should this page's tour be offered now? */
+export function shouldRun(p, page) {
+    if (p.replay === page)
+        return true;
+    return p.on && !p.toured[page];
+}
+/** The page's tour ended — by its last step, its ✕, or a "No". Done for this device. */
+export function markToured(p, page) {
+    return { ...p, toured: { ...p.toured, [page]: true }, replay: p.replay === page ? null : p.replay };
+}
+/** "Stop the tutorial", from any popover: off on every page. */
+export function stopAll(p) {
+    return { ...p, on: false, replay: null };
+}
+/** The switch turned on in the profile: every page offers its tour again. */
+export function replayAll(p) {
+    return { ...p, on: true, toured: {}, replay: null };
+}
+/** "Show me on the page", from a guide: that page once more, and only it. */
+export function replayPage(p, page) {
+    const toured = { ...p.toured };
+    delete toured[page];
+    return { ...p, toured, replay: page };
+}
+/**
+ * The preference as stored, read back. `raw` is the parsed JSON or null when
+ * nothing is stored; `oldHand` says whether this device already held a patron
+ * npub, which is what makes a device with no preference an old hand rather
+ * than a newcomer.
+ */
+export function fromStored(raw, oldHand) {
+    if (raw == null || typeof raw !== "object")
+        return { ...TOUR_DEFAULTS, on: !oldHand };
+    const r = raw;
+    const toured = r.toured && typeof r.toured === "object"
+        ? Object.fromEntries(Object.entries(r.toured).filter(([, v]) => v === true))
+        : {};
+    return {
+        on: typeof r.on === "boolean" ? r.on : !oldHand,
+        toured,
+        replay: typeof r.replay === "string" ? r.replay : null,
+    };
+}

package/dist/tour/tours.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The two tours every site shares, because the pages are the package's: the
+ * sign-in gate, and the account page's panels. A site puts them in its tour
+ * map beside its own, and adds its own steps after the panels' for whatever
+ * else its account page holds.
+ *
+ * The copy says what each thing is, in the words the network uses — Patron,
+ * npub, MCP tool, api_sats — in a sentence or two.
+ */
+import type { Tour, TourStep } from "./types.ts";
+/** The `data-tour` names the package's own markup carries. */
+export declare const TB_TARGETS: {
+    readonly gateNpub: "tb.gate.npub";
+    readonly gateLinks: "tb.gate.links";
+    readonly gateSend: "tb.gate.send";
+    readonly gateSteps: "tb.gate.steps";
+    readonly gateVerify: "tb.gate.verify";
+    readonly accountProfile: "tb.account.profile";
+    readonly accountUsage: "tb.account.usage";
+    readonly accountCoupons: "tb.account.coupons";
+    readonly accountSessionKey: "tb.account.sessionKey";
+};
+/** The sign-in gate, from the field to the moment of being in. */
+export declare function signInTour(page?: string): Tour;
+/** The account page's package panels: the usage table, the persona, coupons, the session key. */
+export declare function accountPanelsSteps(): TourStep[];
+/** The account page as the package knows it; a site appends its own steps. */
+export declare function accountTour(page?: string, own?: TourStep[]): Tour;

package/dist/tour/tours.js

@@ -0,0 +1,54 @@
+/**
+ * The two tours every site shares, because the pages are the package's: the
+ * sign-in gate, and the account page's panels. A site puts them in its tour
+ * map beside its own, and adds its own steps after the panels' for whatever
+ * else its account page holds.
+ *
+ * The copy says what each thing is, in the words the network uses — Patron,
+ * npub, MCP tool, api_sats — in a sentence or two.
+ */
+/** The `data-tour` names the package's own markup carries. */
+export const TB_TARGETS = {
+    gateNpub: "tb.gate.npub",
+    gateLinks: "tb.gate.links",
+    gateSend: "tb.gate.send",
+    gateSteps: "tb.gate.steps",
+    gateVerify: "tb.gate.verify",
+    accountProfile: "tb.account.profile",
+    accountUsage: "tb.account.usage",
+    accountCoupons: "tb.account.coupons",
+    accountSessionKey: "tb.account.sessionKey",
+};
+/** The sign-in gate, from the field to the moment of being in. */
+export function signInTour(page = "signin") {
+    const steps = [
+        { target: TB_TARGETS.gateNpub, title: "Your npub",
+            says: "Paste your npub here. An nsec works too and stays in this browser." },
+        { target: TB_TARGETS.gateLinks, title: "Get a key",
+            says: "Get a free key in 0xchat or Pricing Studio. Either makes one in a minute.", side: "top" },
+        { target: TB_TARGETS.gateSend, title: "Send",
+            says: "We send a message to your Nostr client. Reply to it with any words." },
+        { target: TB_TARGETS.gateSteps, title: "The proof",
+            says: "Your signed reply is the proof. The tiles show where you are.", side: "top" },
+        { target: TB_TARGETS.gateVerify, title: "Verify",
+            says: "Replied? Tap here and you are in." },
+    ];
+    return { page, steps };
+}
+/** The account page's package panels: the usage table, the persona, coupons, the session key. */
+export function accountPanelsSteps() {
+    return [
+        { target: TB_TARGETS.accountUsage, title: "What each tool drew",
+            says: "Every MCP tool you have called, how many times, and the api_sats each cost. The operator sets the prices; this is what was paid.", side: "top" },
+        { target: TB_TARGETS.accountProfile, title: "Your Nostr persona",
+            says: "The name, picture, bio and addresses Nostr shows for your npub. Tap Edit to change them; they publish to your Nostr profile.", side: "top" },
+        { target: TB_TARGETS.accountCoupons, title: "Coupons",
+            says: "A code an operator hands out. Redeem it once here and it discounts your MCP tool fees on its own after that.", side: "top" },
+        { target: TB_TARGETS.accountSessionKey, title: "Your session key",
+            says: "This browser holds a key that signs each call for you. Claim it here to carry it to another device.", side: "top" },
+    ];
+}
+/** The account page as the package knows it; a site appends its own steps. */
+export function accountTour(page = "account", own = []) {
+    return { page, steps: [...accountPanelsSteps(), ...own] };
+}

package/dist/tour/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The shape of a page's guided tour: a handful of steps, each pointing at one
+ * control and saying what it is for.
+ *
+ * Data with no DOM in it, so a site's copy can be tested: every target drawn,
+ * every sentence saying what a thing IS. The mechanics that run it are in
+ * `./run.ts` and `react/useTour.ts`; the words are each site's own, except
+ * for the two pages every site shares (`./tours.ts`).
+ */
+export interface TourStep {
+    /**
+     * A `data-tour` name on the element, or — for markup a site does not own —
+     * a function that finds it. A function that finds nothing skips the step.
+     */
+    target: string | (() => Element | null);
+    title: string;
+    /** One or two short sentences: what the control is, what to do with it. */
+    says: string;
+    side?: "top" | "right" | "bottom" | "left";
+    align?: "start" | "center" | "end";
+    /**
+     * Something the page must do before this step can be pointed at — open the
+     * add form, pick a tag. The page registers the action by this name.
+     */
+    before?: string;
+    /** The guide step this abbreviates, for a site's own test: [group, control]. */
+    guide?: [group: string, control: string];
+}
+export interface Tour {
+    /** The page's key, as the site names its views. */
+    page: string;
+    steps: TourStep[];
+}
+/** What a step may ask the page to do first, by name. */
+export type TourActions = Record<string, () => void | Promise<void>>;

package/dist/tour/types.js

@@ -0,0 +1,10 @@
+/**
+ * The shape of a page's guided tour: a handful of steps, each pointing at one
+ * control and saying what it is for.
+ *
+ * Data with no DOM in it, so a site's copy can be tested: every target drawn,
+ * every sentence saying what a thing IS. The mechanics that run it are in
+ * `./run.ts` and `react/useTour.ts`; the words are each site's own, except
+ * for the two pages every site shares (`./tours.ts`).
+ */
+export {};

package/dist/tourPrefs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The guided tour's preference, stored per site and per device under
+ * `<prefix>:tour:v1`: whether the live tutorial is on, which pages have had
+ * their tour, and a page asked to replay once. The rules are in
+ * `tour/state.ts`; this is their storage, in the shape `timezone.ts` set.
+ */
+import { type TourPrefs } from "./tour/state.ts";
+/** `<prefix>:tour:v1` — for a `storage` event listener. */
+export declare function tourStorageKey(): string;
+export declare function readTourPrefs(): TourPrefs;
+/** Store the preference and tell every listener on the page. */
+export declare function writeTourPrefs(next: TourPrefs): TourPrefs;
+/** Hear every `writeTourPrefs` on this page. Returns an unsubscribe. */
+export declare function onTourChange(fn: (p: TourPrefs) => void): () => void;
+/**
+ * Write the preference down if nothing is stored yet. A newcomer is read as
+ * "on" while they hold no npub; the moment they sign in they would read as
+ * an old hand and the tutorial would go quiet mid-welcome. Settling the
+ * first reading keeps a newcomer a newcomer.
+ */
+export declare function settleTourPrefs(): TourPrefs;

package/dist/tourPrefs.js

@@ -0,0 +1,70 @@
+/**
+ * The guided tour's preference, stored per site and per device under
+ * `<prefix>:tour:v1`: whether the live tutorial is on, which pages have had
+ * their tour, and a page asked to replay once. The rules are in
+ * `tour/state.ts`; this is their storage, in the shape `timezone.ts` set.
+ */
+import { getStoredNpub } from "./identity.js";
+import { key, readStored, writeStored } from "./storage.js";
+import { fromStored } from "./tour/state.js";
+const PREF = "tour:v1";
+/** `<prefix>:tour:v1` — for a `storage` event listener. */
+export function tourStorageKey() {
+    return key(PREF);
+}
+// The last raw value read and what it parsed to. `useSyncExternalStore`
+// wants the same object back while nothing changed; a fresh parse each read
+// would be a new object every time and a render that never settles.
+let lastRaw = null;
+let lastOldHand = false;
+let lastPrefs = null;
+export function readTourPrefs() {
+    const raw = readStored(PREF);
+    // A device that already holds a patron npub but no tour preference has
+    // been here since before the tour existed, and is left in peace. Read each
+    // time: signing in changes it.
+    const oldHand = raw === "" && !!getStoredNpub();
+    if (lastPrefs && raw === lastRaw && oldHand === lastOldHand)
+        return lastPrefs;
+    let parsed = null;
+    if (raw) {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            parsed = null;
+        }
+    }
+    lastPrefs = fromStored(parsed, oldHand);
+    lastRaw = raw;
+    lastOldHand = oldHand;
+    return lastPrefs;
+}
+const listeners = new Set();
+/** Store the preference and tell every listener on the page. */
+export function writeTourPrefs(next) {
+    writeStored(PREF, JSON.stringify(next));
+    lastRaw = null;
+    const stored = readTourPrefs();
+    listeners.forEach((fn) => fn(stored));
+    return stored;
+}
+/** Hear every `writeTourPrefs` on this page. Returns an unsubscribe. */
+export function onTourChange(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}
+/**
+ * Write the preference down if nothing is stored yet. A newcomer is read as
+ * "on" while they hold no npub; the moment they sign in they would read as
+ * an old hand and the tutorial would go quiet mid-welcome. Settling the
+ * first reading keeps a newcomer a newcomer.
+ */
+export function settleTourPrefs() {
+    const current = readTourPrefs();
+    if (readStored(PREF) === "")
+        writeTourPrefs(current);
+    return current;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tollbooth-dpyc/web",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "Shared browser SDK for Tollbooth DPYC operator front ends: npub sign-in, proofs, MCP client, profile and wallet",
   "license": "Apache-2.0",
   "author": "Lonnie VanZandt",
@@ -25,11 +25,13 @@
       "types": "./dist/pagesProxy.d.ts",
       "default": "./dist/pagesProxy.js"
     },
-    "./theme.css": "./theme.css"
+    "./theme.css": "./theme.css",
+    "./tour.css": "./tour.css"
   },
   "files": [
     "dist",
     "theme.css",
+    "tour.css",
     "README.md",
     "LICENSE"
   ],
@@ -55,5 +57,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "driver.js": "1.9.0"
   }
 }