react-cheminfo 0.4.0 → 0.6.0

package/lib/seo/core/routes.js

@@ -0,0 +1,188 @@
+/**
+ * The addresses a site answers, each with the name and the sentence it is
+ * indexed under.
+ *
+ * One table per site, read by three things: the build, which writes an HTML
+ * file per entry and the sitemap listing them; the head injector; and the
+ * running app, which retitles the tab after an in-app move. A page missing from
+ * the table is a page a search engine only ever sees as the home page.
+ */
+import { stripBasePath } from "../../router/core/basePath.js";
+const QUERY_OR_FRAGMENT = /[?#]/;
+const TRAILING_SLASHES = /\/+$/;
+// A scheme and an authority: what `location.href` hands out, and the one shape
+// that cannot be confused with a path. `//host/path` is left as a path, because
+// a route table is free to name one.
+const ABSOLUTE_URL = /^[a-z][\d+.a-z-]*:\/\//i;
+/**
+ * The route an address names.
+ *
+ * An address a route claims exactly always wins over one that claims it as a
+ * subtree, and between two subtrees the longer claim wins, so `/molecules/HEM`
+ * is a molecule rather than whatever `/` answers.
+ * @param routes - Every address the site answers.
+ * @param path - Absolute path, without a query string.
+ * @returns Its entry, or `undefined` when the site does not know the address.
+ */
+export function routeFor(routes, path) {
+    return exactRoute(routes, path) ?? prefixRoute(routes, path);
+}
+/**
+ * The page an address opens.
+ *
+ * An address the site does not know is described as the home page rather than
+ * invented on the fly, which is what the router does with it too. The query
+ * string never reaches the answer: the structure being drawn and the
+ * configuration a shared link carries are not pages of their own. An absolute
+ * address is read for its path, so an app handing over `location.href` after an
+ * in-app move is answered rather than silently described as the home page.
+ *
+ * The route table is written from the site's own root, and a server behind a
+ * mount is handed the address the browser asked for — `/surge/exercises` for a
+ * table that names `/exercises`. So the address is read at the site's own root
+ * first, and the four lookups run in this order:
+ *
+ * 1. the mount taken off, claimed exactly;
+ * 2. the address as written, claimed exactly;
+ * 3. the mount taken off, claimed as a subtree;
+ * 4. the address as written, claimed as a subtree.
+ *
+ * Exact before subtree, or a `prefix` route — a home page answering everything
+ * beneath it above all — would claim every mounted address and the mount would
+ * never come off. Stripped before as-written, or the mount itself would open
+ * whichever page happens to carry the mount's own name rather than the site's
+ * front page. Taking the address as written second is what leaves an unmounted
+ * caller answering exactly as before, and lets a table whose own paths start
+ * with the mount's name still be read.
+ * @param routes - Every address the site answers.
+ * @param url - The address, query string and fragment included, either as a
+ * path or as an absolute `scheme://host/path` address.
+ * @param basePath - The path the site is mounted at, when the address carries
+ * it, written `surge`, `/surge` or `/surge/`.
+ * @default '' — the address is already written from the site's own root
+ * @returns The route it is indexed as.
+ * @throws {Error} When the table is empty, so there is no page to fall back to.
+ */
+export function pageMetaFor(routes, url, basePath = '') {
+    const home = homeRoute(routes);
+    const path = pathOf(url);
+    const own = stripBasePath(basePath, path);
+    return (exactRoute(routes, own) ??
+        exactRoute(routes, path) ??
+        prefixRoute(routes, own) ??
+        prefixRoute(routes, path) ??
+        home);
+}
+/**
+ * The page an unknown address falls back to.
+ * @param routes - Every address the site answers.
+ * @returns The `/` entry, or the first one when the table names no root.
+ * @throws {Error} When the table is empty.
+ */
+export function homeRoute(routes) {
+    const first = routes[0];
+    if (first === undefined)
+        throw new Error('a site answers at least one route');
+    return exactRoute(routes, '/') ?? first;
+}
+/**
+ * Check a route table before a build reads it as a set of file names.
+ *
+ * An address written twice ships two sitemap entries and two links to a page
+ * only the first entry describes, and one carrying a `..` segment writes its
+ * file outside the build output — a real build asked for `/../escaped` and got
+ * a sibling of `dist`. Two addresses that differ only in an empty segment or in
+ * case are the same defect wearing a disguise: `//x` and `/x` both write
+ * `dist/x/index.html`, and so do `/About` and `/about` on the case-insensitive
+ * filesystem macOS and Windows ship by default — one file, two sitemap entries,
+ * and only one of the two descriptions survives. All of it is author
+ * configuration read at build time, so it is refused where it is written rather
+ * than repaired where it lands.
+ * @param routes - Every address the site answers.
+ * @throws {Error} When the table is empty, names one address twice — under any
+ * of those spellings — or carries a path that is not one.
+ */
+export function assertRoutes(routes) {
+    if (routes.length === 0)
+        throw new Error('a site answers at least one route');
+    const claimed = new Set();
+    const folded = new Map();
+    for (const route of routes) {
+        const written = JSON.stringify(route.path);
+        assertPath(route.path, written);
+        const address = trimTrailingSlash(route.path) || '/';
+        if (address.includes('//')) {
+            throw new Error(`a route path names no empty segment: ${written}`);
+        }
+        if (claimed.has(address)) {
+            throw new Error(`a route path is written once: ${written}`);
+        }
+        const first = folded.get(address.toLowerCase());
+        if (first !== undefined) {
+            throw new Error(`two route paths name one file on a case-insensitive disk: ${first} and ${written}`);
+        }
+        claimed.add(address);
+        folded.set(address.toLowerCase(), written);
+    }
+}
+/**
+ * Drop the trailing slashes, so `/about/` and `/about` are one page and an
+ * origin written `https://host/surge//` composes one address rather than one
+ * with an empty segment in it.
+ * @param value - A path or an origin.
+ * @returns It, without the trailing slashes `/` itself keeps.
+ */
+export function trimTrailingSlash(value) {
+    const trimmed = value.replace(TRAILING_SLASHES, '');
+    return trimmed === '' && value !== '' ? '/' : trimmed;
+}
+function assertPath(path, written) {
+    if (!path.startsWith('/')) {
+        throw new Error(`a route path starts at the site root: ${written}`);
+    }
+    if (QUERY_OR_FRAGMENT.test(path)) {
+        throw new Error(`a route path carries no query string and no fragment: ${written}`);
+    }
+    if (path.split('/').includes('..')) {
+        throw new Error(`a route path stays inside the site: ${written}`);
+    }
+}
+// The path half of whatever the caller had at hand: an absolute address, or a
+// path already, with the query string and the fragment cut off either way.
+function pathOf(url) {
+    if (ABSOLUTE_URL.test(url) && URL.canParse(url))
+        return new URL(url).pathname;
+    const cut = url.search(QUERY_OR_FRAGMENT);
+    return cut === -1 ? url : url.slice(0, cut);
+}
+function exactRoute(routes, path) {
+    const wanted = trimTrailingSlash(path) || '/';
+    for (const route of routes) {
+        if ((trimTrailingSlash(route.path) || '/') === wanted)
+            return route;
+    }
+    return undefined;
+}
+function prefixRoute(routes, path) {
+    const wanted = trimTrailingSlash(path) || '/';
+    let claimed;
+    let claimedLength = -1;
+    for (const route of routes) {
+        if (route.prefix !== true)
+            continue;
+        const routePath = trimTrailingSlash(route.path) || '/';
+        if (!isUnder(routePath, wanted))
+            continue;
+        if (routePath.length > claimedLength) {
+            claimed = route;
+            claimedLength = routePath.length;
+        }
+    }
+    return claimed;
+}
+function isUnder(routePath, path) {
+    // `/surgeon` is not a page of `/surge`, so a claim only holds when what
+    // follows it is a path of its own.
+    return routePath === '/' || path.startsWith(`${routePath}/`);
+}
+//# sourceMappingURL=routes.js.map

package/lib/seo/core/routes.js.map

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

package/lib/seo/core/siteFiles.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The sitemap, and what every other file a crawler fetches on its own is
+ * derived from: which site is being written, where it is served, and the path
+ * it is mounted at.
+ *
+ * A deployment names where it serves the site in full — origin and mount path
+ * in one value — because the origin is what a canonical link and a sitemap
+ * entry need. The mount is read back out of it here, so the addresses these
+ * files hand out start where the site actually answers.
+ */
+import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
+import type { RouteMeta } from './routes.ts';
+/** What a crawler is told about the site as a whole. */
+export interface SiteFilesOptions {
+    /** The site, named or passed. */
+    site: EcosystemSite | SiteId;
+    /** Every address it answers. */
+    routes: readonly RouteMeta[];
+    /**
+     * Where the site is served, mount path included, e.g.
+     * `https://learn.cheminfo.org/surge`. Every absolute address is built on it,
+     * and every path one of these files writes starts at its mount.
+     * @default `https://<the site's host>`
+     */
+    origin?: string;
+}
+/**
+ * Every routed address, as the sitemap lists them.
+ *
+ * A sitemap names at least one address: `<url>` is required by the sitemaps.org
+ * schema, and `robots.txt` advertises the file, so an empty one is reported as
+ * an error on every fetch rather than read as a site with nothing to index.
+ * @param options - The site and its routes.
+ * @returns The `sitemap.xml` document.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export declare function sitemapXml(options: SiteFilesOptions): string;
+/**
+ * The site these files are being written for.
+ * @param site - The site, named or passed.
+ * @returns Its record.
+ */
+export declare function resolveSite(site: EcosystemSite | SiteId): EcosystemSite;
+/**
+ * Where the site is served, as an absolute address without a trailing slash.
+ *
+ * It is an absolute `http` or `https` address or it is refused: a canonical
+ * link, an `og:url` and a sitemap entry are addresses a crawler resolves on its
+ * own, and one written from an origin missing its scheme is resolved against
+ * whatever directory the page was fetched from — pointing every page of the
+ * site at a sibling of itself. A dev or staging origin written `localhost:3000`
+ * is refused for the same reason: it parses, but as a path under a `localhost:`
+ * scheme, so the mount read back off it would be `/3000`.
+ * @param options - The site and where it is served.
+ * @returns The origin, mount path included when the deployment named one.
+ * @throws {Error} When the deployment named something that is not an absolute
+ * `http` or `https` address.
+ */
+export declare function originOf(options: SiteFilesOptions): string;
+/**
+ * The path the deployment is mounted at, read off the address it named.
+ * @param options - The site and where it is served.
+ * @returns `''` for a site owning its host, `/surge` for one mounted under it.
+ * @throws {Error} When the deployment named something that is not an absolute
+ * address, so there is no path to read off it.
+ */
+export declare function mountPathOf(options: SiteFilesOptions): string;
+//# sourceMappingURL=siteFiles.d.ts.map

package/lib/seo/core/siteFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"siteFiles.d.ts","sourceRoot":"","sources":["../../../src/seo/core/siteFiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAI3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAQ7C,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IAC7B,gCAAgC;IAChC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAgB5D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,aAAa,CAEvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAQ1D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAE7D"}

package/lib/seo/core/siteFiles.js

@@ -0,0 +1,84 @@
+/**
+ * The sitemap, and what every other file a crawler fetches on its own is
+ * derived from: which site is being written, where it is served, and the path
+ * it is mounted at.
+ *
+ * A deployment names where it serves the site in full — origin and mount path
+ * in one value — because the origin is what a canonical link and a sitemap
+ * entry need. The mount is read back out of it here, so the addresses these
+ * files hand out start where the site actually answers.
+ */
+import { siteById } from "../../ecosystem/core/lookup.js";
+import { basePathOf } from "../../router/core/basePath.js";
+import { escapeText } from "../../share/core/escape.js";
+import { trimTrailingSlash } from "./routes.js";
+// A crawler fetches what it is given over HTTP, so an origin is written in one
+// of the two schemes it speaks. Parsing alone does not say that: `localhost:3000`
+// parses, with `localhost:` as its scheme and `3000` as its path.
+const HTTP_ORIGIN = /^https?:\/\//i;
+/**
+ * Every routed address, as the sitemap lists them.
+ *
+ * A sitemap names at least one address: `<url>` is required by the sitemaps.org
+ * schema, and `robots.txt` advertises the file, so an empty one is reported as
+ * an error on every fetch rather than read as a site with nothing to index.
+ * @param options - The site and its routes.
+ * @returns The `sitemap.xml` document.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export function sitemapXml(options) {
+    const origin = originOf(options);
+    if (options.routes.length === 0) {
+        throw new Error('a sitemap lists at least one address');
+    }
+    const entries = options.routes
+        .map((route) => `  <url><loc>${escapeText(`${origin}${route.path}`)}</loc></url>`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries}
+</urlset>
+`;
+}
+/**
+ * The site these files are being written for.
+ * @param site - The site, named or passed.
+ * @returns Its record.
+ */
+export function resolveSite(site) {
+    return typeof site === 'string' ? siteById(site) : site;
+}
+/**
+ * Where the site is served, as an absolute address without a trailing slash.
+ *
+ * It is an absolute `http` or `https` address or it is refused: a canonical
+ * link, an `og:url` and a sitemap entry are addresses a crawler resolves on its
+ * own, and one written from an origin missing its scheme is resolved against
+ * whatever directory the page was fetched from — pointing every page of the
+ * site at a sibling of itself. A dev or staging origin written `localhost:3000`
+ * is refused for the same reason: it parses, but as a path under a `localhost:`
+ * scheme, so the mount read back off it would be `/3000`.
+ * @param options - The site and where it is served.
+ * @returns The origin, mount path included when the deployment named one.
+ * @throws {Error} When the deployment named something that is not an absolute
+ * `http` or `https` address.
+ */
+export function originOf(options) {
+    const origin = options.origin ?? `https://${resolveSite(options.site).host}`;
+    if (!HTTP_ORIGIN.test(origin) || !URL.canParse(origin)) {
+        throw new Error(`an origin is an absolute address, e.g. https://surge.cheminfo.org: ${JSON.stringify(origin)}`);
+    }
+    return trimTrailingSlash(origin);
+}
+/**
+ * The path the deployment is mounted at, read off the address it named.
+ * @param options - The site and where it is served.
+ * @returns `''` for a site owning its host, `/surge` for one mounted under it.
+ * @throws {Error} When the deployment named something that is not an absolute
+ * address, so there is no path to read off it.
+ */
+export function mountPathOf(options) {
+    return basePathOf(originOf(options));
+}
+//# sourceMappingURL=siteFiles.js.map

package/lib/seo/core/siteFiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"siteFiles.js","sourceRoot":"","sources":["../../../src/seo/core/siteFiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAGxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,+EAA+E;AAC/E,kFAAkF;AAClF,kEAAkE;AAClE,MAAM,WAAW,GAAG,eAAe,CAAC;AAiBpC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,OAAyB;IAClD,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM;SAC3B,GAAG,CACF,CAAC,KAAK,EAAE,EAAE,CACR,eAAe,UAAU,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,cAAc,CACpE;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO;;EAEP,OAAO;;CAER,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAA4B;IACtD,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAyB;IAChD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,WAAW,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7E,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,sEAAsE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,OAAyB;IACnD,OAAO,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/lib/seo/core/startDocumentMeta.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Keep the tab and the canonical link in step with the page on screen.
+ *
+ * The server, or the build that wrote one file per address, already titled the
+ * page it handed out; this is what a move inside the app changes, and what a
+ * crawler that renders the page reads afterwards. Every site did the same three
+ * things around it — read the address it is on, look it up in its route table,
+ * write the head — so all three live here, and a site says only where its
+ * address is read and how a change to it is noticed.
+ */
+import type { PageMetaOptions } from './pageMeta.ts';
+/** Where a site's address is read, and how a change to it is noticed. */
+export interface StartDocumentMetaOptions extends Omit<PageMetaOptions, 'url' | 'image'> {
+    /**
+     * The address on screen, query string included: a path, or the absolute
+     * address read off the page. It is read again on every write, so a `follow`
+     * that tracks what it reads — a signals `effect` — notices the next page.
+     */
+    url: () => string;
+    /**
+     * How a change of page is noticed: `effect` from `@preact/signals-react`
+     * follows whichever signals `url` reads and hands back the function that
+     * stops it. Left out, the head is written once, which is what a site calling
+     * this from its own `popstate` handler wants.
+     * @default undefined — the head is written once
+     */
+    follow?: (write: () => void) => () => void;
+}
+/**
+ * Write the head of the page on screen, and keep it in step as the page
+ * changes.
+ *
+ * Nothing happens where there is no document — a prerender script, a unit test
+ * of the route table — so this is safe to call from a module either of them
+ * imports.
+ * @param options - The site, its routes, where its address is read and how a
+ * change to it is noticed.
+ * @returns The function that stops following, which does nothing when nothing
+ * was followed.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export declare function startDocumentMeta(options: StartDocumentMetaOptions): () => void;
+//# sourceMappingURL=startDocumentMeta.d.ts.map

package/lib/seo/core/startDocumentMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startDocumentMeta.d.ts","sourceRoot":"","sources":["../../../src/seo/core/startDocumentMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,yEAAyE;AACzE,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,eAAe,EACf,KAAK,GAAG,OAAO,CAChB;IACC;;;;OAIG;IACH,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,MAAM,IAAI,CAeZ"}

package/lib/seo/core/startDocumentMeta.js

@@ -0,0 +1,47 @@
+/**
+ * Keep the tab and the canonical link in step with the page on screen.
+ *
+ * The server, or the build that wrote one file per address, already titled the
+ * page it handed out; this is what a move inside the app changes, and what a
+ * crawler that renders the page reads afterwards. Every site did the same three
+ * things around it — read the address it is on, look it up in its route table,
+ * write the head — so all three live here, and a site says only where its
+ * address is read and how a change to it is noticed.
+ */
+import { writeDocumentMeta } from "./documentMeta.js";
+import { pageDocumentMeta } from "./pageMeta.js";
+/**
+ * Write the head of the page on screen, and keep it in step as the page
+ * changes.
+ *
+ * Nothing happens where there is no document — a prerender script, a unit test
+ * of the route table — so this is safe to call from a module either of them
+ * imports.
+ * @param options - The site, its routes, where its address is read and how a
+ * change to it is noticed.
+ * @returns The function that stops following, which does nothing when nothing
+ * was followed.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export function startDocumentMeta(options) {
+    if (typeof document === 'undefined')
+        return stopNothing;
+    const write = () => {
+        writeDocumentMeta(pageDocumentMeta({
+            site: options.site,
+            routes: options.routes,
+            url: options.url(),
+            origin: options.origin,
+        }));
+    };
+    return (options.follow ?? writeOnce)(write);
+}
+function writeOnce(write) {
+    write();
+    return stopNothing;
+}
+function stopNothing() {
+    // Nothing was followed, so there is nothing to stop.
+}
+//# sourceMappingURL=startDocumentMeta.js.map

package/lib/seo/core/startDocumentMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startDocumentMeta.js","sourceRoot":"","sources":["../../../src/seo/core/startDocumentMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAuBjD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAiC;IAEjC,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAO,WAAW,CAAC;IAExD,MAAM,KAAK,GAAG,GAAS,EAAE;QACvB,iBAAiB,CACf,gBAAgB,CAAC;YACf,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;YAClB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CACH,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO,CAAC,OAAO,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,SAAS,CAAC,KAAiB;IAClC,KAAK,EAAE,CAAC;IACR,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,SAAS,WAAW;IAClB,qDAAqD;AACvD,CAAC"}

package/lib/seo/core/structuredData.d.ts

@@ -0,0 +1,48 @@
+/**
+ * One `application/ld+json` block describing the tool.
+ *
+ * It is the same on every page of a site — what varies per page is the head —
+ * so it is written into the built page once rather than per route.
+ */
+import type { SiteFilesOptions } from './siteFiles.ts';
+/** What the structured-data block says the tool is. */
+export interface StructuredDataOptions extends SiteFilesOptions {
+    /**
+     * The schema.org application category.
+     * @default 'EducationalApplication'
+     */
+    category?: string;
+    /**
+     * What the tool needs to run.
+     * @default 'Any modern browser'
+     */
+    operatingSystem?: string;
+    /**
+     * What the tool does, in the words a search result is read in. A site whose
+     * indexed sentence says more than the line its tile in the family menu
+     * carries writes it here.
+     * @default the site's tagline
+     */
+    description?: string;
+    /**
+     * What a browser has to offer for the tool to run. Ours run in the page.
+     * @default 'Requires JavaScript'
+     */
+    browserRequirements?: string;
+    /**
+     * The currency the price is quoted in. The price is zero either way, but the
+     * pair has to agree with the audience the site is read by.
+     * @default 'EUR'
+     */
+    currency?: string;
+}
+/**
+ * The structured-data block, ready to put in the head.
+ *
+ * It always says the tool is free: the price is zero, and a block that leaves
+ * that implicit is one a rich result declines to show.
+ * @param options - The site, and what kind of application it is.
+ * @returns The script tag.
+ */
+export declare function structuredDataScript(options: StructuredDataOptions): string;
+//# sourceMappingURL=structuredData.d.ts.map

package/lib/seo/core/structuredData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuredData.d.ts","sourceRoot":"","sources":["../../../src/seo/core/structuredData.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAMvD,uDAAuD;AACvD,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAwB3E"}

package/lib/seo/core/structuredData.js

@@ -0,0 +1,41 @@
+/**
+ * One `application/ld+json` block describing the tool.
+ *
+ * It is the same on every page of a site — what varies per page is the head —
+ * so it is written into the built page once rather than per route.
+ */
+import { siteDisplayName } from "../../ecosystem/core/lookup.js";
+import { originOf, resolveSite } from "./siteFiles.js";
+/** The sequence that must not appear raw inside a script element. */
+const SCRIPT_SAFE_LESS_THAN = String.raw `\u003c`;
+/**
+ * The structured-data block, ready to put in the head.
+ *
+ * It always says the tool is free: the price is zero, and a block that leaves
+ * that implicit is one a rich result declines to show.
+ * @param options - The site, and what kind of application it is.
+ * @returns The script tag.
+ */
+export function structuredDataScript(options) {
+    const site = resolveSite(options.site);
+    const data = {
+        '@context': 'https://schema.org',
+        '@type': 'WebApplication',
+        name: siteDisplayName(site),
+        url: `${originOf(options)}/`,
+        description: options.description ?? site.tagline,
+        applicationCategory: options.category ?? 'EducationalApplication',
+        operatingSystem: options.operatingSystem ?? 'Any modern browser',
+        browserRequirements: options.browserRequirements ?? 'Requires JavaScript',
+        offers: {
+            '@type': 'Offer',
+            price: '0',
+            priceCurrency: options.currency ?? 'EUR',
+        },
+        isAccessibleForFree: true,
+        publisher: { '@type': 'Organization', name: 'cheminfo' },
+    };
+    const json = JSON.stringify(data, null, 2).replaceAll('<', SCRIPT_SAFE_LESS_THAN);
+    return `<script type="application/ld+json">\n${json}\n</script>`;
+}
+//# sourceMappingURL=structuredData.js.map

package/lib/seo/core/structuredData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuredData.js","sourceRoot":"","sources":["../../../src/seo/core/structuredData.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGjE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEvD,qEAAqE;AACrE,MAAM,qBAAqB,GAAG,MAAM,CAAC,GAAG,CAAA,QAAQ,CAAC;AAkCjD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG;QACX,UAAU,EAAE,oBAAoB;QAChC,OAAO,EAAE,gBAAgB;QACzB,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC;QAC3B,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG;QAC5B,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC,OAAO;QAChD,mBAAmB,EAAE,OAAO,CAAC,QAAQ,IAAI,wBAAwB;QACjE,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,oBAAoB;QAChE,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,qBAAqB;QACzE,MAAM,EAAE;YACN,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,GAAG;YACV,aAAa,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK;SACzC;QACD,mBAAmB,EAAE,IAAI;QACzB,SAAS,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,EAAE;KACzD,CAAC;IACF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,UAAU,CACnD,GAAG,EACH,qBAAqB,CACtB,CAAC;IACF,OAAO,wCAAwC,IAAI,aAAa,CAAC;AACnE,CAAC"}

package/lib/seo/core/template.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where a built page lets its head and its body be written.
+ *
+ * Every address of a site needs its own title, description, canonical and card,
+ * and a static build ships one `index.html`. Rather than look for the tags a
+ * page already carries and operate on them, the template says where they go:
+ * two comments, replaced by what the build or the server writes for the address
+ * being answered.
+ *
+ * ```html
+ * <head>
+ *   <meta charset="utf-8" />
+ *   <link rel="icon" href="%BASE_URL%favicon.svg" />
+ *   <!--cheminfo:head-->
+ * </head>
+ * <body>
+ *   <div id="root"></div>
+ *   <!--cheminfo:body-->
+ * </body>
+ * ```
+ *
+ * The template carries no title and no description of its own, so nothing can
+ * be duplicated and nothing has to be taken back out. Nothing is parsed and
+ * nothing is searched for but the marker, so what the rest of the page holds — a
+ * byte order mark, an implicit head, a `</head>` its prose displays or a script
+ * quotes, an unterminated comment — cannot reach the result.
+ */
+/** Where the head a crawler reads is written. */
+export declare const PAGE_HEAD_MARKER = "<!--cheminfo:head-->";
+/** Where the crawl path a visitor with no JavaScript reads is written. */
+export declare const PAGE_BODY_MARKER = "<!--cheminfo:body-->";
+/**
+ * Write content in the place the template kept for it.
+ *
+ * The marker is consumed, so a page is always filled from the template and
+ * never from a filled page: applying this twice throws rather than writing a
+ * second head, which is why idempotence is not something the caller has to
+ * defend.
+ * @param html - The template.
+ * @param marker - {@link PAGE_HEAD_MARKER} or {@link PAGE_BODY_MARKER}.
+ * @param content - The markup to write, taken as written: no `$&`, `$1` or
+ * `$<name>` is expanded.
+ * @returns The page.
+ * @throws {Error} When the template carries no such marker, rather than
+ * silently shipping a page with no head.
+ */
+export declare function fill(html: string, marker: string, content: string): string;
+//# sourceMappingURL=template.d.ts.map

package/lib/seo/core/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../src/seo/core/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAEvD,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAI1E"}