react-cheminfo 0.4.0 → 0.6.0

package/lib/seo/core/noscript.js

@@ -0,0 +1,93 @@
+/**
+ * A readable page for a visitor, or a crawler, with no JavaScript.
+ *
+ * The body of our sites is an empty root element, so this is the only crawl
+ * path through them that costs nothing to render — and it is honest: it says
+ * the tool needs JavaScript, and links the addresses it answers.
+ */
+import { siteById, siteDisplayName } from "../../ecosystem/core/lookup.js";
+import { ECOSYSTEM_SITES, siteUrl } from "../../ecosystem/core/sites.js";
+import { joinBasePath } from "../../router/core/basePath.js";
+import { escapeAttribute, escapeText } from "../../share/core/escape.js";
+import { mountPathOf, resolveSite } from "./siteFiles.js";
+/**
+ * The `noscript` block, ready to put in the body.
+ *
+ * An absolute address is written under the mount the deployment named, so a
+ * build published as one tool among several on a shared host links its own
+ * pages rather than the root of the host it shares.
+ * @param options - The site, the pages it links, and the prose that opens the
+ * block.
+ * @returns The block.
+ * @throws {Error} When the deployment named an origin that is not an absolute
+ * address.
+ */
+export function noscriptIndex(options) {
+    const site = resolveSite(options.site);
+    const hrefs = options.hrefs ?? 'absolute';
+    const mount = hrefs === 'absolute' ? mountPathOf(options) : '';
+    const heading = escapeText(options.heading ?? siteDisplayName(site));
+    const intro = escapeText(options.intro ??
+        `${site.tagline} This tool needs JavaScript; these are the pages it offers:`);
+    return `<noscript>
+  <h1>${heading}</h1>
+  <p>${intro}</p>${pageList(options.routes, mount, hrefs, '  ')}${familyList(site.id, options.ecosystem)}
+</noscript>`;
+}
+function pageList(routes, mount, hrefs, indent) {
+    // A list with no item is not a list: `<ul>` holds at least one `<li>`.
+    if (routes.length === 0)
+        return '';
+    const items = routes
+        .map((route) => pageItem(route, mount, hrefs, `${indent}  `))
+        .join('\n');
+    return `\n${indent}<ul>\n${items}\n${indent}</ul>`;
+}
+function pageItem(route, mount, hrefs, indent) {
+    const href = escapeAttribute(pageHref(route.path, mount, hrefs));
+    const label = escapeText(labelOf(route));
+    const note = route.note === undefined || route.note.trim() === ''
+        ? ''
+        : ` — ${escapeText(route.note)}`;
+    const children = route.children ?? [];
+    const link = `<a href="${href}">${label}</a>${note}`;
+    if (children.length === 0)
+        return `${indent}<li>${link}</li>`;
+    return `${indent}<li>${link}${pageList(children, mount, hrefs, `${indent}  `)}
+${indent}</li>`;
+}
+function pageHref(path, mount, hrefs) {
+    if (hrefs === 'absolute')
+        return joinBasePath(mount, path);
+    return `./${path.startsWith('/') ? path.slice(1) : path}`;
+}
+function labelOf(route) {
+    const short = route.short;
+    return short !== undefined && short.trim() !== '' ? short : route.title;
+}
+function familyList(current, ecosystem) {
+    if (ecosystem === undefined || ecosystem === false)
+        return '';
+    const listed = ecosystem === true ? {} : ecosystem;
+    const taglines = listed.taglines ?? true;
+    const items = [];
+    for (const site of familySites(listed.sites)) {
+        if (site.id === current)
+            continue;
+        const tagline = taglines ? ` — ${escapeText(site.tagline)}` : '';
+        items.push(`    <li><a href="${escapeAttribute(siteUrl(site))}">${escapeText(site.host)}</a>${tagline}</li>`);
+    }
+    if (items.length === 0)
+        return '';
+    return `
+  <h2>Our other tools</h2>
+  <ul>
+${items.join('\n')}
+  </ul>`;
+}
+function familySites(sites) {
+    if (sites === undefined)
+        return [...ECOSYSTEM_SITES];
+    return sites.map((id) => siteById(id));
+}
+//# sourceMappingURL=noscript.js.map

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

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

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

@@ -0,0 +1,76 @@
+/**
+ * The head of the page a crawler is handed.
+ *
+ * Googlebot renders JavaScript, but Bing, a Slack unfurl, an LMS preview and
+ * every academic indexer read the HTML that came off the wire — so the title,
+ * the description and the canonical of a page must already be in it. A site
+ * with a server writes them per request; a static one writes one file per
+ * address at build time. Both call this, which is pure string work: no
+ * `window`, no `node:fs`.
+ *
+ * The page it is given is the template, which declares where its head goes and
+ * carries none of its own, so this only ever writes — see `./template.ts`.
+ */
+import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
+import type { DocumentMeta } from './documentMeta.ts';
+import type { RouteMeta } from './routes.ts';
+/** Which site is being served, and what it answers. */
+export interface PageMetaOptions {
+    /** The site, named or passed. */
+    site: EcosystemSite | SiteId;
+    /** Every address it answers, each with its title and description. */
+    routes: readonly RouteMeta[];
+    /**
+     * The address being written, query string included: a path, or the absolute
+     * address an app reads off the page it is on.
+     */
+    url: string;
+    /**
+     * Where the site is served, mount path included, e.g.
+     * `https://learn.cheminfo.org/surge`. A server passes the one the request
+     * arrived on; a build leaves it out and the site's own host is used. Every
+     * address written here is composed on it, so the mount is carried by the
+     * origin rather than applied a second time. It is an absolute address, or it
+     * is refused.
+     * @default `https://<the site's host>`
+     */
+    origin?: string;
+    /**
+     * The card a link to the page unfurls into, as an absolute address or a path.
+     * @default '/og.png'
+     */
+    image?: string;
+}
+/**
+ * Give a page the title, the description and the canonical address of the route
+ * it answers, plus the card a link to it unfurls into.
+ * @param html - The built template.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The page, with its head written for that route.
+ * @throws {Error} When the page carries no `<!--cheminfo:head-->`, when the
+ * site answers no route, or when it names an origin that is not an absolute
+ * address.
+ */
+export declare function injectPageMeta(html: string, options: PageMetaOptions): string;
+/**
+ * The head a route is indexed and shared under, for a caller writing more into
+ * the same place — a structured-data block, a tracking snippet.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The tags, one per line.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export declare function pageHeadTags(options: PageMetaOptions): string;
+/**
+ * What the page on screen is called and where it is indexed, for the app to
+ * write after an in-app move.
+ *
+ * The same title and canonical the build wrote into the file it served, so a
+ * click that changes the page cannot disagree with the page a crawler fetched.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The title, the description and the canonical of that address.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export declare function pageDocumentMeta(options: PageMetaOptions): Required<DocumentMeta>;
+//# sourceMappingURL=pageMeta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pageMeta.d.ts","sourceRoot":"","sources":["../../../src/seo/core/pageMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAG3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAK7C,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IAC7B,qEAAqE;IACrE,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7B;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAmB7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,eAAe,GACvB,QAAQ,CAAC,YAAY,CAAC,CAQxB"}

package/lib/seo/core/pageMeta.js

@@ -0,0 +1,88 @@
+/**
+ * The head of the page a crawler is handed.
+ *
+ * Googlebot renders JavaScript, but Bing, a Slack unfurl, an LMS preview and
+ * every academic indexer read the HTML that came off the wire — so the title,
+ * the description and the canonical of a page must already be in it. A site
+ * with a server writes them per request; a static one writes one file per
+ * address at build time. Both call this, which is pure string work: no
+ * `window`, no `node:fs`.
+ *
+ * The page it is given is the template, which declares where its head goes and
+ * carries none of its own, so this only ever writes — see `./template.ts`.
+ */
+import { siteDisplayName } from "../../ecosystem/core/lookup.js";
+import { escapeAttribute, escapeText } from "../../share/core/escape.js";
+import { pageMetaFor } from "./routes.js";
+import { mountPathOf, originOf, resolveSite } from "./siteFiles.js";
+import { PAGE_HEAD_MARKER, fill } from "./template.js";
+/**
+ * Give a page the title, the description and the canonical address of the route
+ * it answers, plus the card a link to it unfurls into.
+ * @param html - The built template.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The page, with its head written for that route.
+ * @throws {Error} When the page carries no `<!--cheminfo:head-->`, when the
+ * site answers no route, or when it names an origin that is not an absolute
+ * address.
+ */
+export function injectPageMeta(html, options) {
+    return fill(html, PAGE_HEAD_MARKER, pageHeadTags(options));
+}
+/**
+ * The head a route is indexed and shared under, for a caller writing more into
+ * the same place — a structured-data block, a tracking snippet.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The tags, one per line.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export function pageHeadTags(options) {
+    const name = siteDisplayName(resolveSite(options.site));
+    const description = routeMetaOf(options).description;
+    const origin = originOf(options);
+    const { title, canonical } = pageDocumentMeta(options);
+    const image = absolute(options.image ?? '/og.png', origin);
+    return [
+        `<title>${escapeText(title)}</title>`,
+        `<meta name="description" content="${escapeAttribute(description)}" />`,
+        `<link rel="canonical" href="${escapeAttribute(canonical)}" />`,
+        '<meta property="og:type" content="website" />',
+        `<meta property="og:site_name" content="${escapeAttribute(name)}" />`,
+        `<meta property="og:title" content="${escapeAttribute(title)}" />`,
+        `<meta property="og:description" content="${escapeAttribute(description)}" />`,
+        `<meta property="og:url" content="${escapeAttribute(canonical)}" />`,
+        `<meta property="og:image" content="${escapeAttribute(image)}" />`,
+        '<meta name="twitter:card" content="summary_large_image" />',
+    ].join('\n');
+}
+/**
+ * What the page on screen is called and where it is indexed, for the app to
+ * write after an in-app move.
+ *
+ * The same title and canonical the build wrote into the file it served, so a
+ * click that changes the page cannot disagree with the page a crawler fetched.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The title, the description and the canonical of that address.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export function pageDocumentMeta(options) {
+    const site = resolveSite(options.site);
+    const meta = routeMetaOf(options);
+    return {
+        title: `${meta.title} — ${siteDisplayName(site)}`,
+        description: meta.description,
+        canonical: `${originOf(options)}${meta.path}`,
+    };
+}
+// A server behind a mount is handed the address the browser asked for, and the
+// route table is written from the site's own root, so the mount the origin
+// carries is taken off it before the table is read.
+function routeMetaOf(options) {
+    return pageMetaFor(options.routes, options.url, mountPathOf(options));
+}
+function absolute(target, origin) {
+    return target.startsWith('/') ? `${origin}${target}` : target;
+}
+//# sourceMappingURL=pageMeta.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pageMeta.js","sourceRoot":"","sources":["../../../src/seo/core/pageMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAIzE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AA8BvD;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,OAAwB;IACnE,OAAO,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,OAAwB;IACnD,MAAM,IAAI,GAAG,eAAe,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxD,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC;IACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,IAAI,SAAS,EAAE,MAAM,CAAC,CAAC;IAE3D,OAAO;QACL,UAAU,UAAU,CAAC,KAAK,CAAC,UAAU;QACrC,qCAAqC,eAAe,CAAC,WAAW,CAAC,MAAM;QACvE,+BAA+B,eAAe,CAAC,SAAS,CAAC,MAAM;QAC/D,+CAA+C;QAC/C,0CAA0C,eAAe,CAAC,IAAI,CAAC,MAAM;QACrE,sCAAsC,eAAe,CAAC,KAAK,CAAC,MAAM;QAClE,4CAA4C,eAAe,CAAC,WAAW,CAAC,MAAM;QAC9E,oCAAoC,eAAe,CAAC,SAAS,CAAC,MAAM;QACpE,sCAAsC,eAAe,CAAC,KAAK,CAAC,MAAM;QAClE,4DAA4D;KAC7D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAwB;IAExB,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAClC,OAAO;QACL,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,MAAM,eAAe,CAAC,IAAI,CAAC,EAAE;QACjD,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE;KAC9C,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,2EAA2E;AAC3E,oDAAoD;AACpD,SAAS,WAAW,CAAC,OAAwB;IAC3C,OAAO,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,QAAQ,CAAC,MAAc,EAAE,MAAc;IAC9C,OAAO,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAChE,CAAC"}

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

@@ -0,0 +1,55 @@
+/**
+ * The crawl policy.
+ *
+ * Our tools are meant to be found, so only the endpoints are kept out of the
+ * index — an API prefix and its documentation are not pages — and each one may
+ * say in a comment why, because a policy nobody can read is a policy nobody
+ * maintains.
+ *
+ * Every line of this file is a directive, so nothing an author writes may
+ * become one they did not: a path is a single line that says something, and
+ * carries no fragment, or it is refused; and a comment is folded onto the one
+ * line it is written as.
+ */
+import type { SiteFilesOptions } from './siteFiles.ts';
+/** One address kept out of the index, and why. */
+export interface RobotsDisallow {
+    /**
+     * The address prefix, from the site's own root, e.g. `/v1/`. It is a path,
+     * on one line, saying something, carrying no `#`, and padded by nothing: a
+     * blank one would read as `Disallow: /` and keep the whole site out of the
+     * index — RFC 9309 eats the trailing whitespace of a line, so `"   "` is read
+     * as nothing at all — one carrying a line break would write whatever follows
+     * it as a directive of its own, everything from a `#` onwards is read as a
+     * comment, which truncates the path silently, and a padded one is not the
+     * address it looks like: `" /v1/"` does not start at the site root, so it is
+     * written `Disallow: / /v1/` and matches no address at all, leaving the
+     * endpoint crawled by the very line meant to keep it out.
+     */
+    path: string;
+    /**
+     * One sentence written as a `#` line above the directive. The `#` is added
+     * when it is not already there, every run of whitespace is folded to a single
+     * space so the sentence stays on its own line, and a blank one is written as
+     * no line at all.
+     * @default undefined — the directive is written on its own
+     */
+    comment?: string;
+}
+/**
+ * The crawl policy of the address the site is served at.
+ *
+ * Every path is written under the mount, so a build published as one tool among
+ * several on a shared host allows what it actually answers rather than claiming
+ * the whole host. The sitemap is named only because this module also writes it:
+ * a `Sitemap:` line pointing at a 404 is reported as an error on every fetch.
+ * @param options - The site, its routes, and where it is served.
+ * @param disallow - Addresses to keep out of the index, each optionally with
+ * the sentence saying why.
+ * @returns The `robots.txt` document.
+ * @throws {Error} When a disallowed address is blank, spans more than one line,
+ * carries a `#` or is padded with whitespace, or when the deployment named an
+ * origin that is not an absolute address.
+ */
+export declare function robotsTxt(options: SiteFilesOptions, disallow?: ReadonlyArray<string | RobotsDisallow>): string;
+//# sourceMappingURL=robots.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"robots.d.ts","sourceRoot":"","sources":["../../../src/seo/core/robots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;OAWG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,gBAAgB,EACzB,QAAQ,GAAE,aAAa,CAAC,MAAM,GAAG,cAAc,CAAM,GACpD,MAAM,CAcR"}

package/lib/seo/core/robots.js

@@ -0,0 +1,70 @@
+/**
+ * The crawl policy.
+ *
+ * Our tools are meant to be found, so only the endpoints are kept out of the
+ * index — an API prefix and its documentation are not pages — and each one may
+ * say in a comment why, because a policy nobody can read is a policy nobody
+ * maintains.
+ *
+ * Every line of this file is a directive, so nothing an author writes may
+ * become one they did not: a path is a single line that says something, and
+ * carries no fragment, or it is refused; and a comment is folded onto the one
+ * line it is written as.
+ */
+import { joinBasePath } from "../../router/core/basePath.js";
+import { mountPathOf, originOf } from "./siteFiles.js";
+const NEWLINE = /[\n\r]/;
+const WHITESPACE = /\s+/g;
+/**
+ * The crawl policy of the address the site is served at.
+ *
+ * Every path is written under the mount, so a build published as one tool among
+ * several on a shared host allows what it actually answers rather than claiming
+ * the whole host. The sitemap is named only because this module also writes it:
+ * a `Sitemap:` line pointing at a 404 is reported as an error on every fetch.
+ * @param options - The site, its routes, and where it is served.
+ * @param disallow - Addresses to keep out of the index, each optionally with
+ * the sentence saying why.
+ * @returns The `robots.txt` document.
+ * @throws {Error} When a disallowed address is blank, spans more than one line,
+ * carries a `#` or is padded with whitespace, or when the deployment named an
+ * origin that is not an absolute address.
+ */
+export function robotsTxt(options, disallow = []) {
+    const mount = mountPathOf(options);
+    const lines = ['User-agent: *', `Allow: ${joinBasePath(mount, '/')}`];
+    for (const entry of disallow) {
+        const rule = typeof entry === 'string' ? { path: entry } : entry;
+        const comment = rule.comment === undefined ? undefined : commentLine(rule.comment);
+        if (comment !== undefined)
+            lines.push(comment);
+        lines.push(`Disallow: ${joinBasePath(mount, disallowPath(rule.path))}`);
+    }
+    lines.push('', `Sitemap: ${originOf(options)}/sitemap.xml`, '');
+    return lines.join('\n');
+}
+function disallowPath(path) {
+    if (path === '') {
+        throw new Error('a disallowed address is a path, never the empty string');
+    }
+    if (path.trim() === '') {
+        throw new Error(`a disallowed address is a path, never blank: ${JSON.stringify(path)}`);
+    }
+    if (NEWLINE.test(path)) {
+        throw new Error(`a disallowed address is written on one line: ${JSON.stringify(path)}`);
+    }
+    if (path.includes('#')) {
+        throw new Error(`a disallowed address carries no fragment: ${JSON.stringify(path)}`);
+    }
+    if (path !== path.trim()) {
+        throw new Error(`a disallowed address is written without padding: ${JSON.stringify(path)}`);
+    }
+    return path;
+}
+function commentLine(comment) {
+    const text = comment.replaceAll(WHITESPACE, ' ').trim();
+    if (text === '')
+        return undefined;
+    return text.startsWith('#') ? text : `# ${text}`;
+}
+//# sourceMappingURL=robots.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"robots.js","sourceRoot":"","sources":["../../../src/seo/core/robots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AA2BvD,MAAM,OAAO,GAAG,QAAQ,CAAC;AAEzB,MAAM,UAAU,GAAG,MAAM,CAAC;AAE1B;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CACvB,OAAyB,EACzB,WAAmD,EAAE;IAErD,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,CAAC,eAAe,EAAE,UAAU,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAEtE,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QACjE,MAAM,OAAO,GACX,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrE,IAAI,OAAO,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/C,KAAK,CAAC,IAAI,CAAC,aAAa,YAAY,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,YAAY,QAAQ,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IAChE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CACvE,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CACvE,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,6CAA6C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CACpE,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,oDAAoD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAC3E,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,OAAe;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAClC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;AACnD,CAAC"}

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

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ */
+/** A page, as a crawler and a shared card see it. */
+export interface RouteMeta {
+    /** Absolute path, without a trailing slash and without a query string. */
+    path: string;
+    /** Under ~60 characters: the site name is appended to it. */
+    title: string;
+    /** One sentence, in the words someone would search for. */
+    description: string;
+    /**
+     * The label the page is linked under where a title written for a search
+     * result is too long to read as a menu entry — the `noscript` index.
+     * @default the route's own title
+     */
+    short?: string;
+    /**
+     * What the page is for, written after an em dash next to its link in the
+     * `noscript` index.
+     * @default undefined — the link stands on its own
+     */
+    note?: string;
+    /**
+     * Whether the route also answers every address beneath it, so a section
+     * carrying more pages than a table can hold — an entry per structure, per
+     * ligand, per identifier — is indexed under the section rather than under the
+     * home page. Those addresses are canonical to the section itself.
+     * @default false
+     */
+    prefix?: boolean;
+}
+/**
+ * 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 declare function routeFor(routes: readonly RouteMeta[], path: string): RouteMeta | undefined;
+/**
+ * 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 declare function pageMetaFor(routes: readonly RouteMeta[], url: string, basePath?: string): RouteMeta;
+/**
+ * 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 declare function homeRoute(routes: readonly RouteMeta[]): RouteMeta;
+/**
+ * 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 declare function assertRoutes(routes: readonly RouteMeta[]): void;
+/**
+ * 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 declare function trimTrailingSlash(value: string): string;
+//# sourceMappingURL=routes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/seo/core/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,IAAI,EAAE,MAAM,GACX,SAAS,GAAG,SAAS,CAEvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,SAAK,GACZ,SAAS,CAWX;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,CAIjE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,CAwB/D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGvD"}