@tollbooth-dpyc/web 0.3.0 → 0.4.0

package/README.md

@@ -10,7 +10,7 @@ features. It is the peer of the `tollbooth-dpyc` Python wheel.
 - **MCP client** — one shared connection to the operator, typed wrappers for
   the standard tools (balance, top-up, statement, price, profile)
 - **React components** — `NpubGate`, `NostrProfilePanel`, `SessionKeyClaim`, `WalletCard`,
-  `AvatarPicker`, `DebugPanel`, `useSession`, `useDebugLog`
+  `AvatarPicker`, `DebugPanel`, `QuoteScroller`, `useSession`, `useDebugLog`
 - **Debug log** — every call, result and error from `callTool`, scrubbed of
   nsecs, hex keys, tokens and proofs before it is stored
 - **Pages proxy** — the `/mcp` Cloudflare Pages Function
@@ -61,6 +61,27 @@ configureDebugLog({ persist: true });   // optional: outlive a reload; max defau
 A site's own `debugPush` lines are scrubbed the same way. Stamps follow the
 zone the site stores under `<prefix>:timezone`, if any.
 
+### Quote scroller
+
+Something to read while a page loads. The quotes are the site's own; the
+package only scrolls them. Name a remote corpus to edit the set without a
+redeploy — it is fetched once per page and replaces the inline set when it
+arrives, or never, if it cannot be had:
+
+```tsx
+import { QuoteScroller } from "@tollbooth-dpyc/web/react";
+import type { Quote } from "@tollbooth-dpyc/web";
+
+const QUOTES: Quote[] = [{ text: "Observe the seasons.", author: "Hesiod" }];
+
+<QuoteScroller
+  quotes={QUOTES}
+  source="https://raw.githubusercontent.com/lonniev/dpyc-community/main/quotes-agrarian.json"
+  heading="Reading the ledger…"
+  spinner
+/>
+```
+
 ### Styling
 
 Components use Tailwind classes coloured only through CSS variables. Tell

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export { canSignFor, isProven, type Claim } from "./signedIn.ts";
 export { readSignInFailure, type Situation } from "./signInSituation.ts";
 export { canSignProfile, fetchProfile, publishProfile } from "./nostrProfile.ts";
 export * from "./avatar.ts";
+export { loadQuotes, peekQuotes, shuffle, validQuotes, type Quote } from "./quotes.ts";
 export { captureGlobalErrors, clearDebug, configureDebugLog, debugEntries, debugLogText, debugPush, debugSeverity, onDebug, redact, type DebugEntry, type DebugLogOptions, type DebugSeverity, } from "./debugLog.ts";

package/dist/index.js

@@ -10,4 +10,5 @@ export { canSignFor, isProven } from "./signedIn.js";
 export { readSignInFailure } from "./signInSituation.js";
 export { canSignProfile, fetchProfile, publishProfile } from "./nostrProfile.js";
 export * from "./avatar.js";
+export { loadQuotes, peekQuotes, shuffle, validQuotes } from "./quotes.js";
 export { captureGlobalErrors, clearDebug, configureDebugLog, debugEntries, debugLogText, debugPush, debugSeverity, onDebug, redact, } from "./debugLog.js";

package/dist/quotes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Quotations for a wait: something to read while a page loads, instead of a
+ * frozen "Loading…".
+ *
+ * Each site keeps its own set — agrarian for a farm, copywriters for a posting
+ * tool — and may name a remote corpus (a `{ quotes: [{ text, author }] }` JSON
+ * file) that supersedes it once it loads, so the set can be edited without a
+ * redeploy. The remote file is fetched at most once per page per URL; two
+ * sites or two corpora never share a cache entry. Anything that goes wrong —
+ * offline, a 404, a malformed file, an empty list — leaves the site's own set
+ * on screen.
+ */
+export interface Quote {
+    text: string;
+    author: string;
+}
+/** Keep only well-formed rows: both fields present as non-blank strings. */
+export declare function validQuotes(rows: unknown): Quote[];
+/** A shuffled copy (Fisher–Yates); the input is left alone. */
+export declare function shuffle<T>(items: ReadonlyArray<T>, random?: () => number): T[];
+/** The remote list already loaded for `source` this page, if there is one. */
+export declare function peekQuotes(source: string): Quote[] | undefined;
+/**
+ * The quotes at `source`, or `fallback` when they cannot be had. Fetched once
+ * per page per URL; a failure is remembered too, so a broken corpus costs one
+ * request, not one per spinner.
+ */
+export declare function loadQuotes(source: string, fallback: ReadonlyArray<Quote>, fetchImpl?: typeof fetch): Promise<Quote[]>;

package/dist/quotes.js

@@ -0,0 +1,77 @@
+/**
+ * Quotations for a wait: something to read while a page loads, instead of a
+ * frozen "Loading…".
+ *
+ * Each site keeps its own set — agrarian for a farm, copywriters for a posting
+ * tool — and may name a remote corpus (a `{ quotes: [{ text, author }] }` JSON
+ * file) that supersedes it once it loads, so the set can be edited without a
+ * redeploy. The remote file is fetched at most once per page per URL; two
+ * sites or two corpora never share a cache entry. Anything that goes wrong —
+ * offline, a 404, a malformed file, an empty list — leaves the site's own set
+ * on screen.
+ */
+/** Keep only well-formed rows: both fields present as non-blank strings. */
+export function validQuotes(rows) {
+    if (!Array.isArray(rows))
+        return [];
+    return rows.flatMap((row) => {
+        if (typeof row !== "object" || row === null)
+            return [];
+        const { text, author } = row;
+        if (typeof text !== "string" || typeof author !== "string")
+            return [];
+        if (!text.trim() || !author.trim())
+            return [];
+        return [{ text, author }];
+    });
+}
+/** A shuffled copy (Fisher–Yates); the input is left alone. */
+export function shuffle(items, random = Math.random) {
+    const copy = items.slice();
+    for (let i = copy.length - 1; i > 0; i--) {
+        const j = Math.floor(random() * (i + 1));
+        [copy[i], copy[j]] = [copy[j], copy[i]];
+    }
+    return copy;
+}
+// Per source URL: the validated remote list ([] when the fetch failed), and
+// the one request in flight so concurrent callers share it.
+const loaded = new Map();
+const inflight = new Map();
+/** The remote list already loaded for `source` this page, if there is one. */
+export function peekQuotes(source) {
+    const list = loaded.get(source);
+    return list && list.length ? list : undefined;
+}
+/**
+ * The quotes at `source`, or `fallback` when they cannot be had. Fetched once
+ * per page per URL; a failure is remembered too, so a broken corpus costs one
+ * request, not one per spinner.
+ */
+export async function loadQuotes(source, fallback, fetchImpl = globalThis.fetch) {
+    const pick = (list) => (list.length ? list : fallback.slice());
+    const done = loaded.get(source);
+    if (done)
+        return pick(done);
+    let pending = inflight.get(source);
+    if (!pending) {
+        pending = (async () => {
+            let list = [];
+            try {
+                const res = await fetchImpl(source, { cache: "no-cache" });
+                if (res.ok) {
+                    const body = (await res.json());
+                    list = validQuotes(body?.quotes);
+                }
+            }
+            catch {
+                list = [];
+            }
+            loaded.set(source, list);
+            inflight.delete(source);
+            return list;
+        })();
+        inflight.set(source, pending);
+    }
+    return pick(await pending);
+}

package/dist/react/QuoteScroller.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Something worth reading while a page loads — rotating quotations instead of
+ * a frozen "Loading…". First written for optionality-mcp as a port of the
+ * Pricing Studio app's LoadingQuoteView, then copied across the fleet; this is
+ * the one copy.
+ *
+ * The site brings its own quotes (`quotes`), so the scroller always has
+ * something to show without the network. `source` may name a remote corpus
+ * that supersedes them once it loads (see `loadQuotes`).
+ *
+ * The order is shuffled and then walked, so nothing repeats until every quote
+ * has shown. It cross-fades (instantly under reduced motion), stops while the
+ * tab is hidden, and reserves the height of its longest quote so the page
+ * does not jump as quotes change. Coloured only through `--tb-*` tokens.
+ */
+import { type Quote } from "../quotes.ts";
+export interface QuoteScrollerProps {
+    /** The site's own quotes: shown at once, and kept if `source` fails. Pass a
+     *  module constant. */
+    quotes: ReadonlyArray<Quote>;
+    /** URL of a `{ quotes: [{ text, author }] }` JSON file that supersedes
+     *  `quotes` once it loads. */
+    source?: string;
+    /** A status line above the quotes ("Reading the ledger…"). */
+    heading?: string;
+    /** Show a spinner beside the heading. Default false. */
+    spinner?: boolean;
+    /** How long each quote stays, in ms. Default 3500. */
+    intervalMs?: number;
+    /** Classes for the outer box (padding, placement). */
+    className?: string;
+}
+export default function QuoteScroller({ quotes, source, heading, spinner, intervalMs, className, }: QuoteScrollerProps): import("react").JSX.Element;

package/dist/react/QuoteScroller.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Something worth reading while a page loads — rotating quotations instead of
+ * a frozen "Loading…". First written for optionality-mcp as a port of the
+ * Pricing Studio app's LoadingQuoteView, then copied across the fleet; this is
+ * the one copy.
+ *
+ * The site brings its own quotes (`quotes`), so the scroller always has
+ * something to show without the network. `source` may name a remote corpus
+ * that supersedes them once it loads (see `loadQuotes`).
+ *
+ * The order is shuffled and then walked, so nothing repeats until every quote
+ * has shown. It cross-fades (instantly under reduced motion), stops while the
+ * tab is hidden, and reserves the height of its longest quote so the page
+ * does not jump as quotes change. Coloured only through `--tb-*` tokens.
+ */
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Loader2 } from "lucide-react";
+import { loadQuotes, peekQuotes, shuffle } from "../quotes.js";
+const FADE_MS = 450;
+function useReducedMotion() {
+    const query = "(prefers-reduced-motion: reduce)";
+    const [reduced, setReduced] = useState(() => typeof window !== "undefined" && !!window.matchMedia?.(query).matches);
+    useEffect(() => {
+        const mq = window.matchMedia?.(query);
+        if (!mq)
+            return;
+        const on = () => setReduced(mq.matches);
+        mq.addEventListener("change", on);
+        return () => mq.removeEventListener("change", on);
+    }, []);
+    return reduced;
+}
+function usePageVisible() {
+    const [shown, setShown] = useState(() => typeof document === "undefined" || document.visibilityState !== "hidden");
+    useEffect(() => {
+        const on = () => setShown(document.visibilityState !== "hidden");
+        document.addEventListener("visibilitychange", on);
+        return () => document.removeEventListener("visibilitychange", on);
+    }, []);
+    return shown;
+}
+export default function QuoteScroller({ quotes, source, heading, spinner = false, intervalMs = 3500, className = "", }) {
+    const reduced = useReducedMotion();
+    const pageVisible = usePageVisible();
+    // Content, not identity: a site that passes an inline array still gets one
+    // shuffle, not one per render.
+    const signature = quotes.map((q) => `${q.text}\u0000${q.author}`).join("\u0001");
+    const [list, setList] = useState(() => shuffle((source && peekQuotes(source)) || quotes));
+    const [index, setIndex] = useState(0);
+    const [shown, setShown] = useState(false);
+    const key = `${source ?? ""}\u0002${signature}`;
+    const first = useRef(key);
+    useEffect(() => {
+        if (first.current !== key) {
+            first.current = key;
+            setList(shuffle((source && peekQuotes(source)) || quotes));
+            setIndex(0);
+        }
+        if (!source || peekQuotes(source))
+            return; // nothing to fetch, or already showing it
+        let alive = true;
+        void loadQuotes(source, quotes).then((loaded) => {
+            if (!alive || !peekQuotes(source))
+                return; // the site's own set is already up
+            setList(shuffle(loaded));
+            setIndex(0);
+        });
+        return () => {
+            alive = false;
+        };
+        // `key` stands for `quotes` and `source`, by content.
+    }, [key]);
+    // Fade the first quote in.
+    useEffect(() => {
+        const id = window.setTimeout(() => setShown(true), 30);
+        return () => window.clearTimeout(id);
+    }, []);
+    useEffect(() => {
+        if (list.length <= 1 || !pageVisible)
+            return;
+        const fade = reduced ? 0 : FADE_MS;
+        let swap;
+        const tick = window.setInterval(() => {
+            setShown(false);
+            swap = window.setTimeout(() => {
+                setIndex((i) => (i + 1) % list.length);
+                setShown(true);
+            }, fade);
+        }, intervalMs);
+        return () => {
+            window.clearInterval(tick);
+            window.clearTimeout(swap);
+            setShown(true);
+        };
+    }, [list, intervalMs, reduced, pageVisible]);
+    const longest = useMemo(() => list.reduce((a, q) => (!a || q.text.length + q.author.length > a.text.length + a.author.length ? q : a), undefined), [list]);
+    const q = list[index % Math.max(list.length, 1)];
+    return (_jsxs("div", { className: `px-4 py-6 text-center ${className}`, children: [heading && (_jsxs("div", { className: "mb-5 flex items-center justify-center gap-2 font-mono text-[11px] uppercase tracking-[0.3em] text-[var(--tb-accent)]", children: [spinner && _jsx(Loader2, { "aria-hidden": true, className: "h-3.5 w-3.5 motion-safe:animate-spin" }), heading] })), q && longest && (_jsxs("div", { className: "mx-auto grid max-w-xl", children: [_jsx(QuoteText, { quote: longest, className: "invisible [grid-area:1/1]", hidden: true }), _jsx(QuoteText, { quote: q, className: "[grid-area:1/1]", style: {
+                            opacity: shown ? 1 : 0,
+                            transition: reduced ? "none" : `opacity ${FADE_MS}ms ease`,
+                        }, live: true })] }))] }));
+}
+function QuoteText({ quote, className, style, hidden = false, live = false, }) {
+    return (_jsxs("figure", { className: `m-0 flex flex-col justify-center gap-3 ${className}`, style: style, "aria-hidden": hidden || undefined, "aria-live": live ? "polite" : undefined, "aria-atomic": live || undefined, children: [_jsxs("blockquote", { className: "m-0 font-serif text-[17px] italic leading-relaxed text-[var(--tb-ink)]", children: [_jsx("span", { className: "not-italic text-[var(--tb-accent)]", children: "\u201C" }), quote.text, _jsx("span", { className: "not-italic text-[var(--tb-accent)]", children: "\u201D" })] }), _jsx("figcaption", { className: "font-mono text-[10.5px] uppercase tracking-[0.22em] text-[var(--tb-muted)]", children: quote.author })] }));
+}

package/dist/react/index.d.ts

@@ -3,6 +3,7 @@ export { default as AvatarPicker } from "./AvatarPicker.tsx";
 export { default as DebugPanel, type DebugPanelProps } from "./DebugPanel.tsx";
 export { default as NpubGate } from "./NpubGate.tsx";
 export { default as NostrProfilePanel } from "./NostrProfilePanel.tsx";
+export { default as QuoteScroller, type QuoteScrollerProps } from "./QuoteScroller.tsx";
 export { default as SessionKeyClaim } from "./SessionKeyClaim.tsx";
 export { default as WalletCard } from "./WalletCard.tsx";
 export { useSession, type Session } from "./useSession.ts";

package/dist/react/index.js

@@ -3,6 +3,7 @@ export { default as AvatarPicker } from "./AvatarPicker.js";
 export { default as DebugPanel } from "./DebugPanel.js";
 export { default as NpubGate } from "./NpubGate.js";
 export { default as NostrProfilePanel } from "./NostrProfilePanel.js";
+export { default as QuoteScroller } from "./QuoteScroller.js";
 export { default as SessionKeyClaim } from "./SessionKeyClaim.js";
 export { default as WalletCard } from "./WalletCard.js";
 export { useSession } from "./useSession.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tollbooth-dpyc/web",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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",