@connextar/house 0.17.0 → 0.19.0

package/dist/admin/view-as.js

@@ -0,0 +1,251 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { AdminRefusalError, adminRefusal } from "./access.js";
+import { emitSafely, viewAsStarted, viewAsStopped, } from "./audit.js";
+const DEFAULT_MINUTES = 60;
+const MAX_COOKIE = 1024;
+const b64 = (value) => Buffer.from(value).toString("base64url");
+export function viewAs(options) {
+    const { cookieName, secret, access } = options;
+    const minutes = options.minutes ?? DEFAULT_MINUTES;
+    const now = options.now ?? Date.now;
+    const logger = options.logger ?? console;
+    const standing = options.standing ?? "admin";
+    if (!cookieName || !/^[\w.-]+$/.test(cookieName)) {
+        throw new Error(`[admin] viewAs cookieName must be a plain cookie name, got "${cookieName}".`);
+    }
+    if (typeof secret !== "string" || secret.length < 32) {
+        throw new Error("[admin] viewAs needs a secret of at least 32 characters to sign its cookie.");
+    }
+    if (!Number.isFinite(minutes) || minutes <= 0 || minutes > 24 * 60) {
+        throw new Error(`[admin] viewAs minutes must be between 0 and a day, got ${String(minutes)}.`);
+    }
+    const sign = (payload) => createHmac("sha256", secret).update(`view-as:${cookieName}:${payload}`).digest();
+    function encode(view) {
+        const payload = b64(JSON.stringify({ v: 1, t: view.targetId, a: view.adminId, e: view.expiresAt.getTime() }));
+        return `${payload}.${b64(sign(payload))}`;
+    }
+    /** The signed view in the cookie, whoever it belongs to and whether or not it has lapsed. */
+    function decode(raw) {
+        if (!raw || raw.length > MAX_COOKIE)
+            return null;
+        const [payload, signature, extra] = raw.split(".");
+        if (!payload || !signature || extra !== undefined)
+            return null;
+        const given = Buffer.from(signature, "base64url");
+        const expected = sign(payload);
+        if (given.length !== expected.length || !timingSafeEqual(given, expected))
+            return null;
+        try {
+            const data = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+            if (data.v !== 1 || typeof data.t !== "string" || typeof data.a !== "string" || typeof data.e !== "number") {
+                return null;
+            }
+            if (!data.t || !data.a || !Number.isFinite(data.e))
+                return null;
+            return { targetId: data.t, adminId: data.a, expiresAt: new Date(data.e) };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The view in the cookie if it is this administrator's and has not lapsed — the binding, before any lookup. */
+    async function bound(adminId) {
+        const jar = await options.cookies();
+        const view = decode(jar.get(cookieName)?.value);
+        if (!view || view.adminId !== adminId || view.targetId === adminId)
+            return null;
+        if (view.expiresAt.getTime() <= now())
+            return null;
+        return view;
+    }
+    async function nameOf(id, given) {
+        if (given)
+            return given;
+        try {
+            return (await options.names?.(id)) || id;
+        }
+        catch {
+            return id;
+        }
+    }
+    return {
+        cookieName,
+        minutes,
+        async start(admin, target, meta = {}) {
+            const targetRef = typeof target === "string" ? { id: target } : target;
+            if (!targetRef.id || targetRef.id === admin.id) {
+                return { ok: false, reason: "self", status: 400, message: options.words?.self ?? "You are already yourself." };
+            }
+            const decision = await access.check(admin, { viewingAs: false });
+            if (!decision.ok)
+                return decision;
+            if (await access.isAdmin(targetRef.id)) {
+                return {
+                    ok: false,
+                    reason: "target-is-admin",
+                    status: 400,
+                    message: options.words?.targetIsAdmin ?? "Viewing as another administrator is not allowed — their view is this one.",
+                };
+            }
+            const view = {
+                targetId: targetRef.id,
+                adminId: admin.id,
+                expiresAt: new Date(now() + minutes * 60_000),
+            };
+            const jar = await options.cookies();
+            jar.set(cookieName, encode(view), {
+                httpOnly: true,
+                sameSite: "lax",
+                secure: options.secure ?? process.env.NODE_ENV === "production",
+                path: options.path ?? "/",
+                maxAge: minutes * 60,
+            });
+            await emitSafely(options.audit, viewAsStarted({
+                actor: { id: admin.id, name: await nameOf(admin.id, admin.name), standing },
+                target: { id: view.targetId, name: await nameOf(view.targetId, "name" in targetRef ? targetRef.name : null) },
+                expiresAt: view.expiresAt,
+                ...(options.scope ? { scope: options.scope } : {}),
+                ...meta,
+            }), logger);
+            return { ok: true, view, minutes };
+        },
+        async stop(realAdmin, meta = {}) {
+            const view = realAdmin ? await bound(realAdmin.id) : null;
+            const jar = await options.cookies();
+            jar.delete(cookieName);
+            if (view && realAdmin) {
+                await emitSafely(options.audit, viewAsStopped({
+                    actor: { id: realAdmin.id, name: await nameOf(realAdmin.id, realAdmin.name), standing },
+                    target: { id: view.targetId, name: await nameOf(view.targetId) },
+                    ...(options.scope ? { scope: options.scope } : {}),
+                    ...meta,
+                }), logger);
+            }
+            return { stopped: view };
+        },
+        async read(realAdmin) {
+            if (!realAdmin?.id || !realAdmin.sessionId)
+                return null;
+            const view = await bound(realAdmin.id);
+            if (!view)
+                return null;
+            // Checked on every request rather than when the cookie was set: a demotion, a revoked session or a sign-in
+            // without the second factor has to end the view immediately.
+            if (!(await access.check(realAdmin, { viewingAs: false })).ok)
+                return null;
+            if (await access.isAdmin(view.targetId))
+                return null;
+            return view;
+        },
+    };
+}
+/** The sentence a refusal under "view as" says. */
+export function viewingAsMessage(name, what) {
+    return `You’re viewing as ${name || "somebody else"}. Stop viewing as them before ${what}.`;
+}
+/**
+ * Refuse, under "view as", a request that acts for the viewed account where the write guard cannot see it: a Stripe
+ * call, an email, a rate-limit bucket. Call it first in the route, before anything is spent.
+ */
+export function refuseWhileViewingAs(user, what, options = {}) {
+    if (!user || (!user.impersonatedBy && !user.viewingAs))
+        return;
+    const name = typeof user.viewingAs === "object" && user.viewingAs?.name ? user.viewingAs.name : user.name;
+    const message = viewingAsMessage(name, what);
+    if (options.makeError)
+        throw options.makeError(message);
+    throw new AdminRefusalError(adminRefusal("viewing-as", { "viewing-as": { message } }));
+}
+/**
+ * The fail-closed default for what reaches outside the database: call `assertNotViewingAs` once inside the app's own
+ * `sendEmail`, `sendSms`, Stripe, GoCardless, Xero and AI wrappers, and every route that uses them is covered —
+ * including the next one written. Quickie had to add `refuseWhileViewingAs` to thirty handlers by hand.
+ *
+ * It reads the app's request-scoped actor rather than keeping a store of its own. An `AsyncLocalStorage` set where the
+ * view is resolved — inside `getCurrentUser`, an awaited callee — does not reach the route's later calls: a store
+ * entered in a callee after its first await (the session read) never propagates back to the caller's continuation
+ * (`view-as.test.ts` pins it), and wrapping
+ * every handler in `withViewingAs(…, fn)` is the per-route step this exists to remove. Quickie's and AltEd's actor
+ * is keyed on the request itself (Next's `headers()` object), which every call in the request shares.
+ */
+export function viewingAsGate(options) {
+    async function lookup() {
+        return options.getViewing();
+    }
+    return {
+        async isViewingAs() {
+            return !!(await lookup());
+        },
+        async assertNotViewingAs(what) {
+            let viewing;
+            try {
+                viewing = await lookup();
+            }
+            catch (error) {
+                const message = `Could not tell whether this request is a “view as”, so ${what} was refused.`;
+                if (options.makeError)
+                    throw options.makeError(message);
+                throw new AdminRefusalError(adminRefusal("viewing-as", { "viewing-as": { message } }), { cause: error });
+            }
+            if (!viewing)
+                return;
+            const message = viewingAsMessage(typeof viewing === "object" ? viewing.name : null, what);
+            if (options.makeError)
+                throw options.makeError(message);
+            throw new AdminRefusalError(adminRefusal("viewing-as", { "viewing-as": { message } }));
+        },
+    };
+}
+/** Every Prisma write operation. A read is never refused — that is the whole point of a view. */
+export const PRISMA_WRITE_OPERATIONS = new Set([
+    "create",
+    "createMany",
+    "createManyAndReturn",
+    "update",
+    "updateMany",
+    "updateManyAndReturn",
+    "upsert",
+    "delete",
+    "deleteMany",
+]);
+/** `allow` from a map of model → operations: `allowWhileViewing({ Session: ["update", "updateMany"] })`. */
+export function allowWhileViewing(list) {
+    const sets = new Map(Object.entries(list).map(([model, operations]) => [model, new Set(operations)]));
+    return (model, operation) => !!model && !!sets.get(model)?.has(operation);
+}
+/**
+ * Make "view as" read-only at the client: `prisma.$extends(viewAsWriteGuard({ … }))`. Every write that arrives while
+ * the request is viewing as somebody is refused, whichever handler made it, unless it is on the allow-list.
+ *
+ * The rule is inverted from "block what is audited", which AltEd learnt by running it: deleting an account ran
+ * `session.deleteMany` and `passkey.deleteMany` before it touched the user row, so the deletion was refused —
+ * correctly — after signing the family out of every device. So everything is refused except what is allowed.
+ *
+ * Typed structurally, so this package imports no Prisma. If an app's Prisma types object to it, wrap it:
+ * `Prisma.defineExtension(viewAsWriteGuard({ … }))`.
+ */
+export function viewAsWriteGuard(options) {
+    const isWrite = options.isWrite ?? ((operation) => PRISMA_WRITE_OPERATIONS.has(operation));
+    return {
+        name: options.name ?? "view-as-write-guard",
+        query: {
+            $allModels: {
+                async $allOperations({ model, operation, args, query }) {
+                    if (isWrite(operation) && !options.allow(model, operation)) {
+                        // Fail-closed: a `getViewing` that throws fails the write, rather than letting it through unchecked.
+                        const viewing = await options.getViewing();
+                        if (viewing) {
+                            const name = typeof viewing === "object" ? viewing.name : null;
+                            const message = viewingAsMessage(name, "changing anything");
+                            if (options.makeError)
+                                throw options.makeError(message);
+                            throw new AdminRefusalError(adminRefusal("viewing-as", { "viewing-as": { message } }));
+                        }
+                    }
+                    return query(args);
+                },
+            },
+        },
+    };
+}
+//# sourceMappingURL=view-as.js.map

package/dist/admin/view-as.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-as.js","sourceRoot":"","sources":["../../src/admin/view-as.ts"],"names":[],"mappings":"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"}

package/dist/guides/guide-article.d.ts

@@ -1,4 +1,6 @@
+import type { GuideFigures } from "../markdown/figures.js";
 import { type GuideClassNames } from "../markdown/guide.js";
+import type { GuideZoomClassNames } from "./guide-figure-zoom.js";
 import { type GuidesLabels } from "./library.js";
 export interface GuideArticleProps {
     /** The guide as `parseGuideFrontmatter` splits it. */
@@ -15,13 +17,22 @@ export interface GuideArticleProps {
     category?: string;
     labels?: Partial<GuidesLabels>;
     classNames?: Partial<GuideClassNames>;
+    /**
+     * The pictures this app's guides may show (`![alt](/guide-images/x.webp "Caption")` and
+     * `![alt](diagram:name)` on a line of their own). Unregistered ones are left out.
+     */
+    figures?: GuideFigures;
+    /** Open a picture full-size on a click, Enter or Space. Default: on. */
+    zoom?: boolean;
+    zoomClassNames?: Partial<GuideZoomClassNames>;
 }
 /**
  * One guide, laid out for reading inside `GuidesShell`: a way back to all guides, the category,
  * the title and lede, the article drawn by `GuideMarkdown`, and "On this page" — a rail that
  * follows the reader on wide screens, a collapsible list above the article on narrow ones. The
  * contents use the same heading ids the renderer gives, so `#<heading id>` links land.
- * Server-safe; the contents are the only client part.
+ * Registered pictures are drawn where the guide names them, each opening full-size.
+ * Server-safe; the contents and the zoom are the only client parts.
  */
-export declare function GuideArticle({ guide, guidesPath, indexSlug, category, labels, classNames }: GuideArticleProps): import("react").JSX.Element;
+export declare function GuideArticle({ guide, guidesPath, indexSlug, category, labels, classNames, figures, zoom, zoomClassNames, }: GuideArticleProps): import("react").JSX.Element;
 //# sourceMappingURL=guide-article.d.ts.map

package/dist/guides/guide-article.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guide-article.d.ts","sourceRoot":"","sources":["../../src/guides/guide-article.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAkC,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5F,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,iBAAiB,+BA0B7G"}
+{"version":3,"file":"guide-article.d.ts","sourceRoot":"","sources":["../../src/guides/guide-article.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAkC,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,wEAAwE;IACxE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,cAAc,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,UAAU,EACV,SAAS,EACT,QAAQ,EACR,MAAM,EACN,UAAU,EACV,OAAO,EACP,IAAI,EACJ,cAAc,GACf,EAAE,iBAAiB,+BA0CnB"}

package/dist/guides/guide-article.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ChevronLeft } from "lucide-react";
 import { Link } from "../internal/next-link.js";
 import { extractHeadings, GuideMarkdown } from "../markdown/guide.js";
+import { GuideFigure } from "./guide-figure.js";
 import { GuideToc } from "./guide-toc.js";
 import { GUIDES_LABELS } from "./library.js";
 /**
@@ -9,11 +10,12 @@ import { GUIDES_LABELS } from "./library.js";
  * the title and lede, the article drawn by `GuideMarkdown`, and "On this page" — a rail that
  * follows the reader on wide screens, a collapsible list above the article on narrow ones. The
  * contents use the same heading ids the renderer gives, so `#<heading id>` links land.
- * Server-safe; the contents are the only client part.
+ * Registered pictures are drawn where the guide names them, each opening full-size.
+ * Server-safe; the contents and the zoom are the only client parts.
  */
-export function GuideArticle({ guide, guidesPath, indexSlug, category, labels, classNames }) {
+export function GuideArticle({ guide, guidesPath, indexSlug, category, labels, classNames, figures, zoom, zoomClassNames, }) {
     const text = { ...GUIDES_LABELS, ...labels };
     const headings = extractHeadings(guide.body);
-    return (_jsxs("div", { className: "xl:grid xl:grid-cols-[minmax(0,1fr)_13rem] xl:gap-12", children: [_jsxs("article", { className: "max-w-3xl min-w-0", children: [_jsxs(Link, { href: guidesPath, className: "inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground", children: [_jsx(ChevronLeft, { className: "size-4", "aria-hidden": true }), " ", text.allGuides] }), category ? (_jsx("p", { className: "mt-5 text-xs font-bold tracking-[0.14em] text-primary uppercase", children: category })) : null, _jsx("h1", { className: "mt-2 text-3xl font-bold tracking-tight text-foreground sm:text-4xl", children: guide.title }), guide.lede ? _jsx("p", { className: "mt-3 text-lg text-muted-foreground", children: guide.lede }) : null, _jsx("div", { className: "mt-8", children: _jsx(GuideToc, { headings: headings, variant: "inline", labels: labels }) }), _jsx(GuideMarkdown, { content: guide.body, guidesPath: guidesPath, indexSlug: indexSlug, classNames: classNames })] }), _jsx(GuideToc, { headings: headings, variant: "rail", labels: labels })] }));
+    return (_jsxs("div", { className: "xl:grid xl:grid-cols-[minmax(0,1fr)_13rem] xl:gap-12", children: [_jsxs("article", { className: "max-w-3xl min-w-0", children: [_jsxs(Link, { href: guidesPath, className: "inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground", children: [_jsx(ChevronLeft, { className: "size-4", "aria-hidden": true }), " ", text.allGuides] }), category ? (_jsx("p", { className: "mt-5 text-xs font-bold tracking-[0.14em] text-primary uppercase", children: category })) : null, _jsx("h1", { className: "mt-2 text-3xl font-bold tracking-tight text-foreground sm:text-4xl", children: guide.title }), guide.lede ? _jsx("p", { className: "mt-3 text-lg text-muted-foreground", children: guide.lede }) : null, _jsx("div", { className: "mt-8", children: _jsx(GuideToc, { headings: headings, variant: "inline", labels: labels }) }), _jsx(GuideMarkdown, { content: guide.body, guidesPath: guidesPath, indexSlug: indexSlug, classNames: classNames, figures: figures, renderFigure: (figure) => (_jsx(GuideFigure, { figure: figure, figures: figures, zoom: zoom, labels: labels, classNames: classNames?.figure, zoomClassNames: zoomClassNames })) })] }), _jsx(GuideToc, { headings: headings, variant: "rail", labels: labels })] }));
 }
 //# sourceMappingURL=guide-article.js.map

package/dist/guides/guide-article.js.map

@@ -1 +1 @@
-{"version":3,"file":"guide-article.js","sourceRoot":"","sources":["../../src/guides/guide-article.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAwB,MAAM,sBAAsB,CAAC;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAqB,MAAM,cAAc,CAAC;AAehE;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAqB;IAC5G,MAAM,IAAI,GAAG,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAE7C,OAAO,CACL,eAAK,SAAS,EAAC,sDAAsD,aACnE,mBAAS,SAAS,EAAC,mBAAmB,aACpC,MAAC,IAAI,IACH,IAAI,EAAE,UAAU,EAChB,SAAS,EAAC,oFAAoF,aAE9F,KAAC,WAAW,IAAC,SAAS,EAAC,QAAQ,wBAAe,OAAE,IAAI,CAAC,SAAS,IACzD,EACN,QAAQ,CAAC,CAAC,CAAC,CACV,YAAG,SAAS,EAAC,iEAAiE,YAAE,QAAQ,GAAK,CAC9F,CAAC,CAAC,CAAC,IAAI,EACR,aAAI,SAAS,EAAC,oEAAoE,YAAE,KAAK,CAAC,KAAK,GAAM,EACpG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,YAAG,SAAS,EAAC,oCAAoC,YAAE,KAAK,CAAC,IAAI,GAAK,CAAC,CAAC,CAAC,IAAI,EACvF,cAAK,SAAS,EAAC,MAAM,YACnB,KAAC,QAAQ,IAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAC,QAAQ,EAAC,MAAM,EAAE,MAAM,GAAI,GAC7D,EACN,KAAC,aAAa,IAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,GAAI,IACpG,EACV,KAAC,QAAQ,IAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAC,MAAM,EAAC,MAAM,EAAE,MAAM,GAAI,IAC3D,CACP,CAAC;AACJ,CAAC"}
+{"version":3,"file":"guide-article.js","sourceRoot":"","sources":["../../src/guides/guide-article.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAwB,MAAM,sBAAsB,CAAC;AAC5F,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAqB,MAAM,cAAc,CAAC;AAuBhE;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,EAC3B,KAAK,EACL,UAAU,EACV,SAAS,EACT,QAAQ,EACR,MAAM,EACN,UAAU,EACV,OAAO,EACP,IAAI,EACJ,cAAc,GACI;IAClB,MAAM,IAAI,GAAG,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAE7C,OAAO,CACL,eAAK,SAAS,EAAC,sDAAsD,aACnE,mBAAS,SAAS,EAAC,mBAAmB,aACpC,MAAC,IAAI,IACH,IAAI,EAAE,UAAU,EAChB,SAAS,EAAC,oFAAoF,aAE9F,KAAC,WAAW,IAAC,SAAS,EAAC,QAAQ,wBAAe,OAAE,IAAI,CAAC,SAAS,IACzD,EACN,QAAQ,CAAC,CAAC,CAAC,CACV,YAAG,SAAS,EAAC,iEAAiE,YAAE,QAAQ,GAAK,CAC9F,CAAC,CAAC,CAAC,IAAI,EACR,aAAI,SAAS,EAAC,oEAAoE,YAAE,KAAK,CAAC,KAAK,GAAM,EACpG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,YAAG,SAAS,EAAC,oCAAoC,YAAE,KAAK,CAAC,IAAI,GAAK,CAAC,CAAC,CAAC,IAAI,EACvF,cAAK,SAAS,EAAC,MAAM,YACnB,KAAC,QAAQ,IAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAC,QAAQ,EAAC,MAAM,EAAE,MAAM,GAAI,GAC7D,EACN,KAAC,aAAa,IACZ,OAAO,EAAE,KAAK,CAAC,IAAI,EACnB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CACxB,KAAC,WAAW,IACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EAAE,MAAM,EAC9B,cAAc,EAAE,cAAc,GAC9B,CACH,GACD,IACM,EACV,KAAC,QAAQ,IAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAC,MAAM,EAAC,MAAM,EAAE,MAAM,GAAI,IAC3D,CACP,CAAC;AACJ,CAAC"}

package/dist/guides/guide-figure-zoom.d.ts

@@ -0,0 +1,73 @@
+import { type ReactNode } from "react";
+import { type GuidesLabels } from "./library.js";
+/**
+ * Every element the zoom draws. Each value replaces the default for that element. A part added after
+ * 0.18.0 is optional, so an app that writes out a whole `GuideZoomClassNames` keeps typechecking.
+ */
+export interface GuideZoomClassNames {
+    /** The button around the picture in the article. */
+    trigger: string;
+    /**
+     * The row under the picture with "Click to enlarge" (or "Tap to enlarge"): under it rather than over
+     * its corner, so it never covers part of a small diagram on a phone.
+     */
+    hint: string;
+    /** The words shown where the pointer is a mouse or a trackpad. Optional: a later addition. */
+    hintPointer?: string;
+    /** The words shown on a touch screen (`@media (pointer: coarse)`). Optional: a later addition. */
+    hintTouch?: string;
+    overlay: string;
+    /** The dialog: the whole screen on a phone, inset on wider ones. */
+    content: string;
+    toolbar: string;
+    instructions: string;
+    button: string;
+    /** The zoom level, a button that switches between fit and full size. */
+    level: string;
+    /** The area the picture is zoomed and dragged in. */
+    stage: string;
+    /** Under the picture: the caption and the alt text. */
+    footer: string;
+    caption: string;
+    alt: string;
+}
+export declare const GUIDE_ZOOM_CLASS_NAMES: Required<GuideZoomClassNames>;
+export interface GuideFigureZoomProps {
+    /** The picture as the article draws it: the button's content. */
+    children: ReactNode;
+    /** What the dialog shows, laid out at the natural size and scaled. Default: `children` again. */
+    full?: ReactNode;
+    /**
+     * The picture's natural size in CSS pixels — a screenshot's registered size, so "full size"
+     * is one image pixel to one CSS pixel. Left out (a diagram), it is measured from the article's
+     * picture when the dialog opens, and full size is twice the fit.
+     */
+    width?: number;
+    height?: number;
+    alt: string;
+    caption?: string;
+    labels?: Partial<GuidesLabels>;
+    classNames?: Partial<GuideZoomClassNames>;
+}
+interface Size {
+    w: number;
+    h: number;
+}
+/** Each button press or key multiplies or divides the zoom by this. */
+export declare const ZOOM_STEP = 1.25;
+/** The scale that fits `natural` inside `stage`, never past full size for a picture with a natural size. */
+export declare function fitScale(natural: Size, stage: Size, capAtFull: boolean): number;
+/**
+ * A guide's picture, opened full-size: a button around the article's picture (with a "Click to
+ * enlarge" hint under it, "Tap to enlarge" on a touch screen) that opens a dialog fitting it to
+ * the screen. In there it zooms with the buttons, `+` and `−`, ⌘/Ctrl + scroll (a trackpad
+ * pinch) and a touch pinch; drags to pan when it is bigger than the screen (and scrolls, and
+ * moves with the arrow keys); a double-click or double-tap switches between fit and full size,
+ * and `0` fits again. Escape closes it and focus goes back to the picture. The caption and alt
+ * text are shown under it.
+ *
+ * Zooming eases unless the reader prefers reduced motion; dragging and pinching never do.
+ */
+export declare function GuideFigureZoom({ children, full, width, height, alt, caption, labels, classNames, }: GuideFigureZoomProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=guide-figure-zoom.d.ts.map

package/dist/guides/guide-figure-zoom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-figure-zoom.d.ts","sourceRoot":"","sources":["../../src/guides/guide-figure-zoom.tsx"],"names":[],"mappings":"AAIA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,mBAAmB,CAqBhE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,QAAQ,EAAE,SAAS,CAAC;IACpB,iGAAiG;IACjG,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC3C;AAED,UAAU,IAAI;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAMD,uEAAuE;AACvE,eAAO,MAAM,SAAS,OAAO,CAAC;AAS9B,4GAA4G;AAC5G,wBAAgB,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAM/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,MAAM,EACN,GAAG,EACH,OAAO,EACP,MAAM,EACN,UAAU,GACX,EAAE,oBAAoB,+BA0VtB"}