react-cheminfo 0.10.0 → 0.12.0

package/lib/deploy/core/composeFile.js

@@ -0,0 +1,138 @@
+import { readComposeDocument } from "./composeDocument.js";
+import { carriesMarker } from "./markers.js";
+const OWN_IMAGE = /^\$\{IMAGE_NAME:-(?<name>[^}]+)\}:\$\{IMAGE_TAG:-[^}]+\}$/;
+/**
+ * Report what one compose file gets wrong: whether it parses, its images, its
+ * build contexts, its `env_file` entries and its healthchecks.
+ * @param name - The file, as a report names it.
+ * @param text - Its content.
+ * @param rules - What the file is checked against.
+ * @param problems - Where each problem found is appended, in reading order.
+ */
+export function readComposeFile(name, text, rules, problems) {
+    const document = readComposeDocument(text);
+    if (document.error !== undefined) {
+        problems.push({
+            file: name,
+            line: document.error.line,
+            kind: 'invalid-compose',
+            message: `the file is not valid YAML: ${document.error.message}`,
+            hint: 'fix the YAML; docker compose config reports the same error',
+        });
+        return;
+    }
+    const found = [];
+    const report = (line, problem) => found.push({ file: name, line, ...problem });
+    for (const service of document.services) {
+        const { image, build } = service.value;
+        const own = typeof image === 'string'
+            ? OWN_IMAGE.exec(image)?.groups?.name
+            : undefined;
+        if (typeof image === 'string') {
+            const line = service.lineOf('image');
+            const problem = own === undefined
+                ? foreignImageProblem(image, carriesMarker(document.lines, line - 1, rules.pinMarker), rules)
+                : ownImageProblem(own, rules);
+            if (problem !== undefined)
+                report(line, problem);
+        }
+        if ('env_file' in service.value &&
+            requiresEnvFile(service.value.env_file)) {
+            report(service.lineOf('env_file'), {
+                kind: 'required-env-file',
+                message: 'env_file is required, so compose fails on a checkout that has no .env yet',
+                hint: 'write env_file: [{ path: .env, required: false }]',
+            });
+        }
+        if (own === undefined)
+            continue;
+        if (build === undefined || build === null) {
+            report(service.line, {
+                kind: 'missing-build',
+                message: `service ${service.name} carries no build context, so it cannot be built from the checkout`,
+                hint: 'add build: . next to image:',
+            });
+        }
+        if (rules.requireHealthcheck && !isProbed(service, document.lines, rules)) {
+            report(service.line, {
+                kind: 'missing-healthcheck',
+                message: `service ${service.name} declares no healthcheck, so the deploy script cannot tell a broken container from a good one`,
+                hint: 'add a healthcheck probing the health endpoint',
+            });
+        }
+    }
+    problems.push(...found.toSorted((one, other) => one.line - other.line));
+}
+function ownImageProblem(name, rules) {
+    if (rules.imageName === undefined || name === rules.imageName) {
+        return undefined;
+    }
+    return {
+        kind: 'wrong-image-name',
+        message: `IMAGE_NAME defaults to ${name}, which this repository never publishes`,
+        hint: `default it to ${rules.imageName}`,
+    };
+}
+function foreignImageProblem(value, waived, rules) {
+    // Somebody else builds it and this site tracks it on purpose.
+    if (waived)
+        return undefined;
+    const bare = value.replace(/^docker\.io\/(?:library\/)?/, '');
+    const isForeign = rules.foreignImages.some((prefix) => value.startsWith(prefix) || bare.startsWith(prefix));
+    if (!isForeign) {
+        return {
+            kind: 'unpinned-image',
+            message: `image ${value} gives the deploy script no tag to select`,
+            hint: `write \${IMAGE_NAME:-ghcr.io/<owner>/<repo>}:\${IMAGE_TAG:-latest}`,
+        };
+    }
+    if (value.endsWith(':latest') || !value.includes(':')) {
+        return {
+            kind: 'floating-sidecar',
+            message: `third-party image ${value} is not pinned, so a rebuild is not reproducible`,
+            hint: 'pin the sidecar to an exact version',
+        };
+    }
+    return undefined;
+}
+/**
+ * Whether compose fails when a listed file is absent: a bare path is required,
+ * and so is a `{ path }` entry unless it says `required: false`.
+ * @param value - The service's `env_file`, in its short or long form.
+ * @returns True when any entry is required.
+ */
+function requiresEnvFile(value) {
+    const entries = Array.isArray(value) ? value : [value];
+    for (const entry of entries) {
+        if (typeof entry !== 'object' || entry === null)
+            return true;
+        if (entry.required !== false)
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether Docker will report the service's health: it declares a healthcheck
+ * that is not disabled, or a comment inside it carries the waiver.
+ * @param service - The service.
+ * @param lines - The file, split into lines.
+ * @param rules - The marker that waives the healthcheck.
+ * @returns True when the deploy script has a health to read, or needs none.
+ */
+function isProbed(service, lines, rules) {
+    const [first, last] = service.lines;
+    for (let line = first; line <= last; line++) {
+        if ((lines[line - 1] ?? '').toLowerCase().includes(rules.healthcheckMarker)) {
+            return true;
+        }
+    }
+    const { healthcheck } = service.value;
+    if (typeof healthcheck !== 'object' || healthcheck === null)
+        return false;
+    const { disable, test } = healthcheck;
+    if (disable === true)
+        return false;
+    const command = Array.isArray(test) ? test[0] : test;
+    return command !== 'NONE';
+}
+//# sourceMappingURL=composeFile.js.map

package/lib/deploy/core/composeFile.js.map

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

package/lib/deploy/core/envExample.d.ts

@@ -0,0 +1,10 @@
+import type { DeployProblem } from './types.ts';
+/**
+ * Report what an `.env.example` fails to offer the operator: the two variables
+ * the deploy script rewrites, and one commented `COMPOSE_FILE` line per mode.
+ * @param text - The content of `.env.example`.
+ * @param expected - The compose files the repository is expected to ship.
+ * @param problems - Where each problem found is appended.
+ */
+export declare function readEnvExample(text: string, expected: readonly string[], problems: DeployProblem[]): void;
+//# sourceMappingURL=envExample.d.ts.map

package/lib/deploy/core/envExample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envExample.d.ts","sourceRoot":"","sources":["../../../src/deploy/core/envExample.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,aAAa,EAAE,GACxB,IAAI,CA4BN"}

package/lib/deploy/core/envExample.js

@@ -0,0 +1,36 @@
+/**
+ * Report what an `.env.example` fails to offer the operator: the two variables
+ * the deploy script rewrites, and one commented `COMPOSE_FILE` line per mode.
+ * @param text - The content of `.env.example`.
+ * @param expected - The compose files the repository is expected to ship.
+ * @param problems - Where each problem found is appended.
+ */
+export function readEnvExample(text, expected, problems) {
+    for (const name of ['IMAGE_NAME', 'IMAGE_TAG']) {
+        if (!new RegExp(String.raw `^#?\s*${name}=`, 'm').test(text)) {
+            problems.push({
+                file: '.env.example',
+                line: 0,
+                kind: 'missing-env-example',
+                message: `${name} is not declared, so the operator cannot see what the deploy script sets`,
+                hint: `add a ${name}= line`,
+            });
+        }
+    }
+    for (const name of expected) {
+        const offered = new RegExp(String.raw `^#\s*COMPOSE_FILE=${escapeRegExp(name)}(?:\s|$)`, 'm');
+        if (!offered.test(text)) {
+            problems.push({
+                file: '.env.example',
+                line: 0,
+                kind: 'missing-env-example',
+                message: `no commented COMPOSE_FILE line offers ${name}`,
+                hint: `add a commented COMPOSE_FILE=${name} line`,
+            });
+        }
+    }
+}
+function escapeRegExp(value) {
+    return value.replaceAll(/[$()*+.?[\\\]^{|}]/g, String.raw `\$&`);
+}
+//# sourceMappingURL=envExample.js.map

package/lib/deploy/core/envExample.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envExample.js","sourceRoot":"","sources":["../../../src/deploy/core/envExample.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,QAA2B,EAC3B,QAAyB;IAEzB,KAAK,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,EAAE,CAAC;QAC/C,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAA,SAAS,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5D,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,CAAC;gBACP,IAAI,EAAE,qBAAqB;gBAC3B,OAAO,EAAE,GAAG,IAAI,0EAA0E;gBAC1F,IAAI,EAAE,SAAS,IAAI,QAAQ;aAC5B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,MAAM,CACxB,MAAM,CAAC,GAAG,CAAA,qBAAqB,YAAY,CAAC,IAAI,CAAC,UAAU,EAC3D,GAAG,CACJ,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,CAAC;gBACP,IAAI,EAAE,qBAAqB;gBAC3B,OAAO,EAAE,yCAAyC,IAAI,EAAE;gBACxD,IAAI,EAAE,gCAAgC,IAAI,OAAO;aAClD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK,CAAC,UAAU,CAAC,qBAAqB,EAAE,MAAM,CAAC,GAAG,CAAA,KAAK,CAAC,CAAC;AAClE,CAAC"}

package/lib/deploy/core/index.d.ts

@@ -0,0 +1,4 @@
+export { findDeployProblems } from './checkDeploy.ts';
+export type { CheckDeployOptions, DeployFile, DeployProblem, DeployProblemKind, } from './types.ts';
+export { DEPLOY_COMPOSE_FILES } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/deploy/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/deploy/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EACV,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/lib/deploy/core/index.js

@@ -0,0 +1,3 @@
+export { findDeployProblems } from "./checkDeploy.js";
+export { DEPLOY_COMPOSE_FILES } from "./types.js";
+//# sourceMappingURL=index.js.map

package/lib/deploy/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/deploy/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAOtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/lib/deploy/core/markers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a line, or the comment block written directly above it, carries a
+ * marker — so a waiver can be explained in as many lines as it needs.
+ * @param lines - The file, split into lines.
+ * @param index - The line the marker would apply to.
+ * @param marker - The marker to look for, lowercased.
+ * @returns True when the line or its comment block carries it.
+ */
+export declare function carriesMarker(lines: readonly string[], index: number, marker: string): boolean;
+//# sourceMappingURL=markers.d.ts.map

package/lib/deploy/core/markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.d.ts","sourceRoot":"","sources":["../../../src/deploy/core/markers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAQT"}

package/lib/deploy/core/markers.js

@@ -0,0 +1,21 @@
+/**
+ * Whether a line, or the comment block written directly above it, carries a
+ * marker — so a waiver can be explained in as many lines as it needs.
+ * @param lines - The file, split into lines.
+ * @param index - The line the marker would apply to.
+ * @param marker - The marker to look for, lowercased.
+ * @returns True when the line or its comment block carries it.
+ */
+export function carriesMarker(lines, index, marker) {
+    if ((lines[index] ?? '').toLowerCase().includes(marker))
+        return true;
+    for (let above = index - 1; above >= 0; above--) {
+        const line = lines[above] ?? '';
+        if (!/^\s*#/.test(line))
+            return false;
+        if (line.toLowerCase().includes(marker))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=markers.js.map

package/lib/deploy/core/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../../../src/deploy/core/markers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAwB,EACxB,KAAa,EACb,MAAc;IAEd,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,KAAK,IAAI,KAAK,GAAG,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACtC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;IACvD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/lib/deploy/core/types.d.ts

@@ -0,0 +1,70 @@
+/** What a repository got wrong against the deployment contract. */
+export type DeployProblemKind = 'missing-compose' | 'invalid-compose' | 'unpinned-image' | 'missing-build' | 'wrong-image-name' | 'required-env-file' | 'floating-sidecar' | 'missing-healthcheck' | 'missing-env-example' | 'missing-deploy-ignore';
+/** One way a repository would fail, or silently mis-deploy, on the server. */
+export interface DeployProblem {
+    /** The file it was found in, named as the caller named it. */
+    file: string;
+    /** Which line, counting from 1; 0 when the problem is the file's absence. */
+    line: number;
+    /** What kind of mistake it is. */
+    kind: DeployProblemKind;
+    /** What is wrong, in one line. */
+    message: string;
+    /** What to write instead, in one line. */
+    hint: string;
+}
+/** One file of the repository, with the path a report names it by. */
+export interface DeployFile {
+    /** The path, relative to the repository root. */
+    path: string;
+    /** Its content. */
+    text: string;
+}
+/** What the contract is checked against. */
+export interface CheckDeployOptions {
+    /**
+     * The package this repository's own workflow publishes, without a tag —
+     * `ghcr.io/<owner>/<repo>`, the repository name verbatim. When given, every
+     * compose file must default `IMAGE_NAME` to exactly this.
+     * @default undefined
+     */
+    imageName?: string;
+    /**
+     * Images built elsewhere, matched as a prefix before the tag. They are exempt
+     * from the `IMAGE_NAME`/`IMAGE_TAG` rule but must still carry a pinned tag.
+     * @default []
+     */
+    foreignImages?: readonly string[];
+    /**
+     * Compose files the repository is expected to ship. A site behind fewer
+     * exposures names fewer.
+     * @default DEPLOY_COMPOSE_FILES
+     */
+    composeFiles?: readonly string[];
+    /**
+     * Whether every service must declare a `healthcheck`. The deploy script keeps
+     * a new container only once Docker reports it healthy.
+     * @default true
+     */
+    requireHealthcheck?: boolean;
+    /**
+     * A comment carrying this marker inside a service waives the healthcheck for
+     * it, for a worker with no HTTP surface to probe. The reason is written next
+     * to the marker, where the next reader of the compose file will find it.
+     * @default 'healthcheck-ok'
+     */
+    healthcheckMarker?: string;
+    /**
+     * A comment carrying this marker on, or just above, an `image:` line waives
+     * the tag rules for it — for an image somebody else builds and this site
+     * deliberately tracks. The reason is written next to the marker.
+     * @default 'pin-ok'
+     */
+    pinMarker?: string;
+}
+/**
+ * The compose files every deployed site ships, one per exposure: a published
+ * port, a Traefik reverse proxy, a Cloudflare Tunnel.
+ */
+export declare const DEPLOY_COMPOSE_FILES: readonly string[];
+//# sourceMappingURL=types.d.ts.map

package/lib/deploy/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/deploy/core/types.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,iBAAiB,GACjB,gBAAgB,GAChB,eAAe,GACf,kBAAkB,GAClB,mBAAmB,GACnB,kBAAkB,GAClB,qBAAqB,GACrB,qBAAqB,GACrB,uBAAuB,CAAC;AAE5B,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4CAA4C;AAC5C,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAIjD,CAAC"}

package/lib/deploy/core/types.js

@@ -0,0 +1,10 @@
+/**
+ * The compose files every deployed site ships, one per exposure: a published
+ * port, a Traefik reverse proxy, a Cloudflare Tunnel.
+ */
+export const DEPLOY_COMPOSE_FILES = [
+    'compose.yaml',
+    'compose.traefik.yaml',
+    'compose.cloudflared.yaml',
+];
+//# sourceMappingURL=types.js.map

package/lib/deploy/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/deploy/core/types.ts"],"names":[],"mappings":"AA8EA;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAsB;IACrD,cAAc;IACd,sBAAsB;IACtB,0BAA0B;CAC3B,CAAC"}

package/lib/disclosure/ui/CollapsibleSection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CollapsibleSection.d.ts","sourceRoot":"","sources":["../../../src/disclosure/ui/CollapsibleSection.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,KAAK,EAAiB,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGpE,mDAAmD;AACnD,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,KAAK,EAAE,SAAS,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,uBAAuB,GAC7B,YAAY,CAmDd"}
+{"version":3,"file":"CollapsibleSection.d.ts","sourceRoot":"","sources":["../../../src/disclosure/ui/CollapsibleSection.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,KAAK,EAAiB,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKpE,mDAAmD;AACnD,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,KAAK,EAAE,SAAS,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,uBAAuB,GAC7B,YAAY,CA+Cd"}

package/lib/disclosure/ui/CollapsibleSection.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Collapse, Icon } from '@blueprintjs/core';
 import { useState } from 'react';
+import { joinClassNames } from "../../shared/ui/joinClassNames.js";
 /**
  * A titled block of a page that folds away when its heading is pressed.
  *
@@ -21,9 +22,7 @@ export function CollapsibleSection(props) {
         else
             setOpenState((shown) => !shown);
     }
-    return (_jsxs("section", { id: id, className: className === undefined
-            ? 'collapsible-section'
-            : `collapsible-section ${className}`, children: [_jsxs("div", { style: HEADER_STYLE, children: [_jsxs("button", { type: "button", style: BUTTON_STYLE, "aria-expanded": isOpen, onClick: toggle, children: [_jsx(Icon, { icon: isOpen ? 'chevron-down' : 'chevron-right', size: 14 }), icon === undefined ? null : _jsx(Icon, { icon: icon, size: 14 }), _jsx("span", { style: TITLE_STYLE, children: title })] }), rightElement === undefined ? null : (_jsx("div", { style: RIGHT_STYLE, children: rightElement }))] }), _jsx(Collapse, { isOpen: isOpen, children: _jsx("div", { style: BODY_STYLE, children: children }) })] }));
+    return (_jsxs("section", { id: id, className: joinClassNames('collapsible-section', className), children: [_jsxs("div", { style: HEADER_STYLE, children: [_jsxs("button", { type: "button", style: BUTTON_STYLE, "aria-expanded": isOpen, onClick: toggle, children: [_jsx(Icon, { icon: isOpen ? 'chevron-down' : 'chevron-right', size: 14 }), icon === undefined ? null : _jsx(Icon, { icon: icon, size: 14 }), _jsx("span", { style: TITLE_STYLE, children: title })] }), rightElement === undefined ? null : (_jsx("div", { style: RIGHT_STYLE, children: rightElement }))] }), _jsx(Collapse, { isOpen: isOpen, children: _jsx("div", { style: BODY_STYLE, children: children }) })] }));
 }
 const HEADER_STYLE = {
     display: 'flex',

package/lib/disclosure/ui/CollapsibleSection.js.map

@@ -1 +1 @@
-{"version":3,"file":"CollapsibleSection.js","sourceRoot":"","sources":["../../../src/disclosure/ui/CollapsibleSection.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AA+CjC;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAA8B;IAE9B,MAAM,EACJ,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,WAAW,GAAG,IAAI,EAClB,YAAY,EACZ,MAAM,EAAE,QAAQ,EAChB,QAAQ,EACR,EAAE,EACF,SAAS,GACV,GAAG,KAAK,CAAC;IACV,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;IAExD,MAAM,YAAY,GAAG,QAAQ,KAAK,SAAS,CAAC;IAC5C,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnD,SAAS,MAAM;QACb,IAAI,YAAY;YAAE,QAAQ,EAAE,EAAE,CAAC;;YAC1B,YAAY,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CACL,mBACE,EAAE,EAAE,EAAE,EACN,SAAS,EACP,SAAS,KAAK,SAAS;YACrB,CAAC,CAAC,qBAAqB;YACvB,CAAC,CAAC,uBAAuB,SAAS,EAAE,aAGxC,eAAK,KAAK,EAAE,YAAY,aACtB,kBACE,IAAI,EAAC,QAAQ,EACb,KAAK,EAAE,YAAY,mBACJ,MAAM,EACrB,OAAO,EAAE,MAAM,aAEf,KAAC,IAAI,IAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,EAAE,IAAI,EAAE,EAAE,GAAI,EAClE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAC,IAAI,IAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,GAAI,EAC3D,eAAM,KAAK,EAAE,WAAW,YAAG,KAAK,GAAQ,IACjC,EACR,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CACnC,cAAK,KAAK,EAAE,WAAW,YAAG,YAAY,GAAO,CAC9C,IACG,EACN,KAAC,QAAQ,IAAC,MAAM,EAAE,MAAM,YACtB,cAAK,KAAK,EAAE,UAAU,YAAG,QAAQ,GAAO,GAC/B,IACH,CACX,CAAC;AACJ,CAAC;AAED,MAAM,YAAY,GAAG;IACnB,OAAO,EAAE,MAAM;IACf,UAAU,EAAE,QAAQ;IACpB,GAAG,EAAE,CAAC;CAC0B,CAAC;AAEnC,MAAM,YAAY,GAAG;IACnB,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE,CAAC;IACX,UAAU,EAAE,QAAQ;IACpB,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE,CAAC;IACT,UAAU,EAAE,MAAM;IAClB,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,SAAS;IACf,UAAU,EAAE,GAAG;IACf,GAAG,EAAE,CAAC;IACN,SAAS,EAAE,MAAM;IACjB,MAAM,EAAE,SAAS;CACe,CAAC;AAEnC,MAAM,WAAW,GAAG;IAClB,QAAQ,EAAE,QAAQ;IAClB,YAAY,EAAE,UAAU;IACxB,UAAU,EAAE,QAAQ;CACY,CAAC;AAEnC,MAAM,WAAW,GAAG;IAClB,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,UAAU;IAChB,UAAU,EAAE,QAAQ;IACpB,GAAG,EAAE,CAAC;CAC0B,CAAC;AAEnC,MAAM,UAAU,GAAG,EAAE,UAAU,EAAE,CAAC,EAAmC,CAAC"}
+{"version":3,"file":"CollapsibleSection.js","sourceRoot":"","sources":["../../../src/disclosure/ui/CollapsibleSection.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AA+CnE;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAA8B;IAE9B,MAAM,EACJ,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,WAAW,GAAG,IAAI,EAClB,YAAY,EACZ,MAAM,EAAE,QAAQ,EAChB,QAAQ,EACR,EAAE,EACF,SAAS,GACV,GAAG,KAAK,CAAC;IACV,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;IAExD,MAAM,YAAY,GAAG,QAAQ,KAAK,SAAS,CAAC;IAC5C,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnD,SAAS,MAAM;QACb,IAAI,YAAY;YAAE,QAAQ,EAAE,EAAE,CAAC;;YAC1B,YAAY,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CACL,mBACE,EAAE,EAAE,EAAE,EACN,SAAS,EAAE,cAAc,CAAC,qBAAqB,EAAE,SAAS,CAAC,aAE3D,eAAK,KAAK,EAAE,YAAY,aACtB,kBACE,IAAI,EAAC,QAAQ,EACb,KAAK,EAAE,YAAY,mBACJ,MAAM,EACrB,OAAO,EAAE,MAAM,aAEf,KAAC,IAAI,IAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,EAAE,IAAI,EAAE,EAAE,GAAI,EAClE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAC,IAAI,IAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,GAAI,EAC3D,eAAM,KAAK,EAAE,WAAW,YAAG,KAAK,GAAQ,IACjC,EACR,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CACnC,cAAK,KAAK,EAAE,WAAW,YAAG,YAAY,GAAO,CAC9C,IACG,EACN,KAAC,QAAQ,IAAC,MAAM,EAAE,MAAM,YACtB,cAAK,KAAK,EAAE,UAAU,YAAG,QAAQ,GAAO,GAC/B,IACH,CACX,CAAC;AACJ,CAAC;AAED,MAAM,YAAY,GAAG;IACnB,OAAO,EAAE,MAAM;IACf,UAAU,EAAE,QAAQ;IACpB,GAAG,EAAE,CAAC;CAC0B,CAAC;AAEnC,MAAM,YAAY,GAAG;IACnB,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE,CAAC;IACX,UAAU,EAAE,QAAQ;IACpB,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE,CAAC;IACT,UAAU,EAAE,MAAM;IAClB,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,SAAS;IACf,UAAU,EAAE,GAAG;IACf,GAAG,EAAE,CAAC;IACN,SAAS,EAAE,MAAM;IACjB,MAAM,EAAE,SAAS;CACe,CAAC;AAEnC,MAAM,WAAW,GAAG;IAClB,QAAQ,EAAE,QAAQ;IAClB,YAAY,EAAE,UAAU;IACxB,UAAU,EAAE,QAAQ;CACY,CAAC;AAEnC,MAAM,WAAW,GAAG;IAClB,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,UAAU;IAChB,UAAU,EAAE,QAAQ;IACpB,GAAG,EAAE,CAAC;CAC0B,CAAC;AAEnC,MAAM,UAAU,GAAG,EAAE,UAAU,EAAE,CAAC,EAAmC,CAAC"}

package/lib/download/core/figureLegend.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The key, painted into the file the figure leaves the page as.
+ *
+ * A legend is HTML — it is a filter the reader presses, not a drawing — so it
+ * is inside the chrome the export otherwise leaves behind. But a saved figure
+ * without its key says nothing: a reader looking at three colours has no way
+ * back to the three species. So the card is redrawn, once, in SVG, from the
+ * boxes the browser laid it out in.
+ *
+ * It is redrawn from measurements rather than re-derived from the styles that
+ * made it, so the copy cannot drift from the card on screen: whatever the
+ * browser did with the wrapping, the folding and the type, that is what the
+ * file gets.
+ */
+/** The card the entries sit on. */
+export interface FigureLegendCard {
+    /** Its width, in pixels. */
+    width: number;
+    /** Its height. */
+    height: number;
+    /**
+     * How round its corners are, in pixels.
+     * @default 0
+     */
+    radius?: number;
+    /**
+     * What is painted behind it.
+     * @default undefined — nothing is painted
+     */
+    background?: string;
+    /**
+     * The colour of the line round it.
+     * @default undefined — no line is drawn
+     */
+    border?: string;
+    /**
+     * How heavy that line is, in pixels.
+     * @default 1
+     */
+    borderWidth?: number;
+}
+/** One mark of the key, already an SVG of its own. */
+export interface FigureLegendMark {
+    /** The `<svg>` element as it was serialized, tokens already resolved. */
+    markup: string;
+    /** Its left edge, in pixels from the left of the card. */
+    x: number;
+    /** Its top edge, in pixels from the top of the card. */
+    y: number;
+}
+/** One run of words of the key. */
+export interface FigureLegendText {
+    /** What it says. */
+    text: string;
+    /** Its left edge, in pixels from the left of the card. */
+    x: number;
+    /** The middle of its line, in pixels from the top of the card. */
+    y: number;
+    /**
+     * Its colour.
+     * @default undefined — the document's own
+     */
+    color?: string;
+    /**
+     * Its size, in pixels.
+     * @default undefined — the document's own
+     */
+    fontSize?: number;
+    /**
+     * Its weight.
+     * @default undefined — the document's own
+     */
+    fontWeight?: string;
+}
+/** A key, measured off the page and ready to be painted. */
+export interface FigureLegendPrint {
+    /** The card itself. */
+    card: FigureLegendCard;
+    /** Its marks, in the order they are drawn. */
+    marks: readonly FigureLegendMark[];
+    /** Its words, in the order they are drawn. */
+    texts: readonly FigureLegendText[];
+}
+/**
+ * A key, as the markup that goes into the saved figure.
+ * @param print - The card, its marks and its words. See {@link FigureLegendPrint}.
+ * @returns The markup, in the card's own coordinates: the caller places it.
+ */
+export declare function figureLegendMarkup(print: FigureLegendPrint): string;
+//# sourceMappingURL=figureLegend.d.ts.map

package/lib/download/core/figureLegend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figureLegend.d.ts","sourceRoot":"","sources":["../../../src/download/core/figureLegend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,CAAC,EAAE,MAAM,CAAC;IACV,wDAAwD;IACxD,CAAC,EAAE,MAAM,CAAC;CACX;AAED,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,CAAC,EAAE,MAAM,CAAC;IACV,kEAAkE;IAClE,CAAC,EAAE,MAAM,CAAC;IACV;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,uBAAuB;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,8CAA8C;IAC9C,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnC,8CAA8C;IAC9C,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAYnE"}

package/lib/download/core/figureLegend.js

@@ -0,0 +1,77 @@
+/**
+ * The key, painted into the file the figure leaves the page as.
+ *
+ * A legend is HTML — it is a filter the reader presses, not a drawing — so it
+ * is inside the chrome the export otherwise leaves behind. But a saved figure
+ * without its key says nothing: a reader looking at three colours has no way
+ * back to the three species. So the card is redrawn, once, in SVG, from the
+ * boxes the browser laid it out in.
+ *
+ * It is redrawn from measurements rather than re-derived from the styles that
+ * made it, so the copy cannot drift from the card on screen: whatever the
+ * browser did with the wrapping, the folding and the type, that is what the
+ * file gets.
+ */
+/**
+ * A key, as the markup that goes into the saved figure.
+ * @param print - The card, its marks and its words. See {@link FigureLegendPrint}.
+ * @returns The markup, in the card's own coordinates: the caller places it.
+ */
+export function figureLegendMarkup(print) {
+    const { card, marks, texts } = print;
+    const parts = [groundMarkup(card)];
+    for (const mark of marks) {
+        parts.push(`<g transform="translate(${round(mark.x)} ${round(mark.y)})">${mark.markup}</g>`);
+    }
+    for (const run of texts)
+        parts.push(textMarkup(run));
+    return parts.join('');
+}
+/**
+ * The card the entries are written on.
+ * @param card - Its measurements. See {@link FigureLegendCard}.
+ * @returns Its markup, or nothing when the card has neither ground nor line.
+ */
+function groundMarkup(card) {
+    const { width, height, radius = 0, background, border } = card;
+    if (background === undefined && border === undefined)
+        return '';
+    const borderWidth = card.borderWidth ?? 1;
+    // Drawn inside its own line, which a stroke otherwise straddles: half of it
+    // would fall outside the card and be clipped by the figure's edge.
+    const inset = border === undefined ? 0 : borderWidth / 2;
+    const line = border === undefined
+        ? ''
+        : ` stroke="${attribute(border)}" stroke-width="${round(borderWidth)}"`;
+    return (`<rect x="${round(inset)}" y="${round(inset)}"` +
+        ` width="${round(Math.max(0, width - inset * 2))}"` +
+        ` height="${round(Math.max(0, height - inset * 2))}"` +
+        ` rx="${round(radius)}" fill="${attribute(background ?? 'none')}"${line}/>`);
+}
+/**
+ * One run of words, set on the middle of the line it was laid out on.
+ * @param run - The words and where they sit. See {@link FigureLegendText}.
+ * @returns Its markup, or nothing when it says nothing.
+ */
+function textMarkup(run) {
+    if (run.text === '')
+        return '';
+    const fill = run.color === undefined ? '' : ` fill="${attribute(run.color)}"`;
+    const size = run.fontSize === undefined ? '' : ` font-size="${round(run.fontSize)}px"`;
+    const weight = run.fontWeight === undefined
+        ? ''
+        : ` font-weight="${attribute(run.fontWeight)}"`;
+    return (`<text x="${round(run.x)}" y="${round(run.y)}" dominant-baseline="central"` +
+        `${fill}${size}${weight}>${text(run.text)}</text>`);
+}
+function attribute(value) {
+    return text(value).replaceAll('"', '&quot;');
+}
+function text(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}
+const round = (value) => Math.round(value * 100) / 100;
+//# sourceMappingURL=figureLegend.js.map

package/lib/download/core/figureLegend.js.map

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

package/lib/download/core/figureSvg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figureSvg.d.ts","sourceRoot":"","sources":["../../../src/download/core/figureSvg.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,eAAO,MAAM,eAAe,gCAAgC,CAAC;AAQ7D;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CAgCX"}
+{"version":3,"file":"figureSvg.d.ts","sourceRoot":"","sources":["../../../src/download/core/figureSvg.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,eAAO,MAAM,eAAe,gCAAgC,CAAC;AAQ7D;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CA2CX"}