react-cheminfo 0.3.0 → 0.4.1

package/lib/router/core/query.d.ts

@@ -0,0 +1,41 @@
+/** How a query string is read and written. */
+export interface QueryStringOptions {
+    /**
+     * Keep a `+` in a value as the character it is, rather than reading it as
+     * the space `URLSearchParams` decodes it to. A SMILES carries `+` for a
+     * charged atom, and `CC[N+](C)(C)C` handed out in a link has to survive.
+     * @default true
+     */
+    literalPlus?: boolean;
+    /**
+     * Write a parameter carrying nothing back as the bare key, so a hand-typed
+     * flag such as `?embed` survives the round trip. Left off, an empty value is
+     * dropped and an unconfigured link stays clean.
+     * @default false
+     */
+    keepEmptyValues?: boolean;
+}
+/**
+ * Read a query string.
+ *
+ * Forgiving by design, because the address is hand-editable and arrives from
+ * bookmarks, course pages and lecture slides: a repeated key keeps its last
+ * value, a key carrying nothing is kept as an empty value so a bare `?embed`
+ * reads as present, and an escape that does not decode is taken literally.
+ * @param search - The query string, with or without its leading `?`.
+ * @param options - How the values are decoded.
+ * @returns One entry per key, decoded.
+ */
+export declare function parseQueryString(search: string, options?: QueryStringOptions): Record<string, string>;
+/**
+ * Write a query string.
+ *
+ * A parameter left at nothing is dropped unless `keepEmptyValues` asks for it,
+ * and `undefined` or `null` removes a parameter outright, so a page can hand
+ * its whole state to this function and get back only what it actually carries.
+ * @param params - The parameters, in the order they should be written.
+ * @param options - How the values are encoded.
+ * @returns The query string, without its leading `?`, empty when nothing is carried.
+ */
+export declare function formatQueryString(params: Readonly<Record<string, string | undefined | null>>, options?: QueryStringOptions): string;
+//# sourceMappingURL=query.d.ts.map

package/lib/router/core/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/router/core/query.ts"],"names":[],"mappings":"AAEA,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAcxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC,EAC3D,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAYR"}

package/lib/router/core/query.js

@@ -0,0 +1,64 @@
+import { safeDecode } from "./address.js";
+/**
+ * Read a query string.
+ *
+ * Forgiving by design, because the address is hand-editable and arrives from
+ * bookmarks, course pages and lecture slides: a repeated key keeps its last
+ * value, a key carrying nothing is kept as an empty value so a bare `?embed`
+ * reads as present, and an escape that does not decode is taken literally.
+ * @param search - The query string, with or without its leading `?`.
+ * @param options - How the values are decoded.
+ * @returns One entry per key, decoded.
+ */
+export function parseQueryString(search, options = {}) {
+    const literalPlus = options.literalPlus ?? true;
+    const query = {};
+    const text = search.startsWith('?') ? search.slice(1) : search;
+    for (const part of text.split('&')) {
+        if (part === '')
+            continue;
+        const index = part.indexOf('=');
+        const rawKey = index === -1 ? part : part.slice(0, index);
+        const rawValue = index === -1 ? '' : part.slice(index + 1);
+        const key = decodeValue(rawKey, literalPlus);
+        if (key === '')
+            continue;
+        query[key] = decodeValue(rawValue, literalPlus);
+    }
+    return query;
+}
+/**
+ * Write a query string.
+ *
+ * A parameter left at nothing is dropped unless `keepEmptyValues` asks for it,
+ * and `undefined` or `null` removes a parameter outright, so a page can hand
+ * its whole state to this function and get back only what it actually carries.
+ * @param params - The parameters, in the order they should be written.
+ * @param options - How the values are encoded.
+ * @returns The query string, without its leading `?`, empty when nothing is carried.
+ */
+export function formatQueryString(params, options = {}) {
+    const keepEmptyValues = options.keepEmptyValues ?? false;
+    const parts = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (key === '' || value === undefined || value === null)
+            continue;
+        if (value === '') {
+            if (keepEmptyValues)
+                parts.push(encodeValue(key));
+            continue;
+        }
+        parts.push(`${encodeValue(key)}=${encodeValue(value)}`);
+    }
+    return parts.join('&');
+}
+// A comma is legal in a query value and is what separates the keys of `hide`
+// and the formulas of a list; escaped to `%2C` a link stops being one a teacher
+// can read out loud.
+function encodeValue(value) {
+    return encodeURIComponent(value).replaceAll('%2C', ',');
+}
+function decodeValue(value, literalPlus) {
+    return safeDecode(literalPlus ? value : value.replaceAll('+', ' '));
+}
+//# sourceMappingURL=query.js.map

package/lib/router/core/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../src/router/core/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAoB1C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,UAA8B,EAAE;IAEhC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC;IAChD,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC/D,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,IAAI,KAAK,EAAE;YAAE,SAAS;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC1D,MAAM,QAAQ,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC3D,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAC7C,IAAI,GAAG,KAAK,EAAE;YAAE,SAAS;QACzB,KAAK,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA2D,EAC3D,UAA8B,EAAE;IAEhC,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,KAAK,CAAC;IACzD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,GAAG,KAAK,EAAE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAClE,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACjB,IAAI,eAAe;gBAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YAClD,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,6EAA6E;AAC7E,gFAAgF;AAChF,qBAAqB;AACrB,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,WAAW,CAAC,KAAa,EAAE,WAAoB;IACtD,OAAO,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/lib/router/core/tabRouter.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The two directions between an address and the page it names.
+ *
+ * Both functions are pure: they take and return strings, never touch
+ * `location`, and know none of the parameter names the tool carries — the share
+ * configuration owns those. That is what makes the round trip unit-testable
+ * without a DOM, and usable from a prerender script under Node.
+ * @param options - The tabs of the site and how their addresses are written.
+ * @returns The parser, the serialiser, and the test for a known tab.
+ */
+export declare function createTabRouter<Tab extends string>(options: TabRouterOptions<Tab>): TabRouter<Tab>;
+/** A tab whose address carries more than the tab's own name. */
+export interface TabDefinition<Tab extends string = string> {
+    /** Identifier of the tab, as the state and the components name it. */
+    id: Tab;
+    /**
+     * The address of the tab, from the site's own root. The home tab is always
+     * written as `/`, whatever it declares here, so the site has one address for
+     * it instead of two holding the same thing.
+     * @default `/${id}`
+     */
+    path?: string;
+    /**
+     * Whether the tab addresses one of its items in a second path segment — a
+     * tutorial step, an exercise, an element — so a lecturer can hand out a deep
+     * link and a crawler indexes each item as a page of its own.
+     * @default false
+     */
+    takesId?: boolean;
+}
+/** How the addresses of a site's tabs are read and written. */
+export interface TabRouterOptions<Tab extends string> {
+    /** Every tab of the site, named on its own or described in full. */
+    tabs: ReadonlyArray<Tab | TabDefinition<Tab>>;
+    /**
+     * The tab living at the root, and the one an address the site does not know
+     * opens — a link written before a rename still lands somewhere.
+     */
+    home: Tab;
+    /**
+     * Whether the address is the path or the fragment. A public tool must use
+     * `'path'`: a `#` is dropped by half the tools that pass links around, the
+     * server never sees it, and a crawler indexes the whole site as one page.
+     * `'hash'` exists only so a site already routing that way can adopt this
+     * router before it moves.
+     * @default 'path'
+     */
+    mode?: 'path' | 'hash';
+    /**
+     * The path the site is served under: nothing on a host of its own, `/surge`
+     * as one tool among several on a shared one.
+     * @default ''
+     */
+    basePath?: string;
+    /**
+     * Read a `+` in a value as the character it is rather than as a space.
+     * Without it a shared SMILES breaks.
+     * @default true
+     */
+    literalPlus?: boolean;
+    /**
+     * Write a parameter carrying nothing back as the bare key, so a hand-typed
+     * `?embed` survives the round trip.
+     * @default false
+     */
+    keepEmptyValues?: boolean;
+    /**
+     * Also read an address whose page is named by an old `#/tab/item` fragment,
+     * so links handed out before the site routed by path keep working.
+     * @default false
+     */
+    adoptLegacyHash?: boolean;
+}
+/** Where the app is: which tab, what it has open, and how it is set up. */
+export interface TabRoute<Tab extends string = string> {
+    /** The tab the address opens. */
+    tab: Tab;
+    /** The item its second segment names, `null` on a tab that takes none. */
+    id: string | null;
+    /** Decoded query parameters, the tool's own and the share configuration's. */
+    params: Record<string, string>;
+}
+/** A route as a caller writes it, the parts it does not carry left out. */
+export interface TabRouteInput<Tab extends string = string> {
+    /** The tab to open; one the router does not know falls back to the home tab. */
+    tab: Tab;
+    /**
+     * The item the tab has open, ignored by a tab that addresses none.
+     * @default null
+     */
+    id?: string | null;
+    /**
+     * Query parameters to carry; an empty, `undefined` or `null` value is left out.
+     * @default {}
+     */
+    params?: Record<string, string | undefined | null>;
+}
+/** The string ↔ route mapping of a site. */
+export interface TabRouter<Tab extends string = string> {
+    /**
+     * The route an address denotes. An unknown tab, a trailing slash, an empty
+     * address and an escape that does not decode all resolve to something
+     * sensible rather than throwing.
+     */
+    parse: (address: string) => TabRoute<Tab>;
+    /** The address a route is reachable at, mount path and query included. */
+    format: (route: TabRouteInput<Tab>) => string;
+    /** Whether a string read out of an address names one of the site's tabs. */
+    isTab: (value: string) => value is Tab;
+}
+//# sourceMappingURL=tabRouter.d.ts.map

package/lib/router/core/tabRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabRouter.d.ts","sourceRoot":"","sources":["../../../src/router/core/tabRouter.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,SAAS,MAAM,EAChD,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAC7B,SAAS,CAAC,GAAG,CAAC,CAyDhB;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM;IACxD,sEAAsE;IACtE,EAAE,EAAE,GAAG,CAAC;IACR;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB,CAAC,GAAG,SAAS,MAAM;IAClD,oEAAoE;IACpE,IAAI,EAAE,aAAa,CAAC,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C;;;OAGG;IACH,IAAI,EAAE,GAAG,CAAC;IACV;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,WAAW,QAAQ,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM;IACnD,iCAAiC;IACjC,GAAG,EAAE,GAAG,CAAC;IACT,0EAA0E;IAC1E,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM;IACxD,gFAAgF;IAChF,GAAG,EAAE,GAAG,CAAC;IACT;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;CACpD;AAED,4CAA4C;AAC5C,MAAM,WAAW,SAAS,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM;IACpD;;;;OAIG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,MAAM,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC;IAC9C,4EAA4E;IAC5E,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC;CACxC"}

package/lib/router/core/tabRouter.js

@@ -0,0 +1,87 @@
+import { splitAddress, splitPath } from "./address.js";
+import { joinBasePath, normalizeBasePath, stripBasePath } from "./basePath.js";
+import { pathFromLegacyHash } from "./legacyHash.js";
+import { formatQueryString, parseQueryString } from "./query.js";
+/**
+ * The two directions between an address and the page it names.
+ *
+ * Both functions are pure: they take and return strings, never touch
+ * `location`, and know none of the parameter names the tool carries — the share
+ * configuration owns those. That is what makes the round trip unit-testable
+ * without a DOM, and usable from a prerender script under Node.
+ * @param options - The tabs of the site and how their addresses are written.
+ * @returns The parser, the serialiser, and the test for a known tab.
+ */
+export function createTabRouter(options) {
+    const mode = options.mode ?? 'path';
+    const basePath = normalizeBasePath(options.basePath ?? '');
+    const adoptLegacyHash = options.adoptLegacyHash ?? false;
+    const queryOptions = {
+        literalPlus: options.literalPlus ?? true,
+        keepEmptyValues: options.keepEmptyValues ?? false,
+    };
+    const definitions = new Map();
+    for (const tab of options.tabs) {
+        const definition = typeof tab === 'string' ? { id: tab } : tab;
+        definitions.set(definition.id, {
+            path: normalizeTabPath(definition.path ?? `/${definition.id}`),
+            takesId: definition.takesId ?? false,
+        });
+    }
+    definitions.set(options.home, definitions.get(options.home) ?? { path: '/', takesId: false });
+    const tabBySegment = new Map();
+    for (const [id, definition] of definitions) {
+        const segment = definition.path.slice(1);
+        if (segment !== '')
+            tabBySegment.set(segment, id);
+    }
+    function isTab(value) {
+        return definitions.has(value);
+    }
+    function parse(address) {
+        const parts = readAddress(address, mode, basePath, adoptLegacyHash);
+        const params = parseQueryString(parts.search, queryOptions);
+        const segments = splitPath(parts.path);
+        const first = segments[0];
+        const tab = first === undefined ? undefined : tabBySegment.get(first);
+        if (tab === undefined)
+            return { tab: options.home, id: null, params };
+        const second = segments[1];
+        const takesId = definitions.get(tab)?.takesId ?? false;
+        return { tab, id: takesId && second !== undefined ? second : null, params };
+    }
+    function format(route) {
+        const tab = definitions.has(route.tab) ? route.tab : options.home;
+        const definition = definitions.get(tab);
+        const base = tab === options.home ? '/' : (definition?.path ?? '/');
+        const id = definition?.takesId === true ? (route.id ?? null) : null;
+        const path = id === null || base === '/' ? base : `${base}/${encodeURIComponent(id)}`;
+        const search = formatQueryString(route.params ?? {}, queryOptions);
+        const address = mode === 'hash' ? `#${path}` : joinBasePath(basePath, path);
+        return search === '' ? address : `${address}?${search}`;
+    }
+    return { parse, format, isTab };
+}
+function readAddress(address, mode, basePath, adoptLegacyHash) {
+    if (mode === 'hash') {
+        const fragment = address.includes('#')
+            ? splitAddress(address).fragment
+            : address;
+        const { path, search } = splitAddress(fragment);
+        return { path, search };
+    }
+    const outer = splitAddress(address);
+    const path = stripBasePath(basePath, outer.path);
+    if (adoptLegacyHash && path === '/') {
+        const legacy = pathFromLegacyHash(address);
+        if (legacy !== null)
+            return splitAddress(legacy);
+    }
+    return { path, search: outer.search };
+}
+function normalizeTabPath(path) {
+    const opened = path.startsWith('/') ? path : `/${path}`;
+    const closed = opened.replace(/\/+$/, '');
+    return closed === '' ? '/' : closed;
+}
+//# sourceMappingURL=tabRouter.js.map

package/lib/router/core/tabRouter.js.map

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

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

@@ -0,0 +1,45 @@
+/**
+ * Keep the head in step with the page on screen after an in-app move.
+ *
+ * The server, or the build that wrote one file per address, already titled the
+ * page it handed out; this is what a click inside the app changes, and what a
+ * crawler that renders the page reads afterwards. Every access to the document
+ * is guarded, so a prerender script importing this under Node does nothing
+ * rather than throwing.
+ * @param meta - What the page on screen is called and where it is indexed.
+ */
+export declare function writeDocumentMeta(meta: DocumentMeta): void;
+/**
+ * Name the browser tab.
+ * @param title - The title of the page, site name included.
+ */
+export declare function documentTitle(title: string): void;
+/**
+ * Point the canonical link at the address the page is indexed under, creating
+ * the tag when the served page carries none.
+ *
+ * The query string is dropped, and so is any fragment: the structure being
+ * edited and the configuration a shared link carries are not pages of their
+ * own, and indexing them as such splits one result into hundreds.
+ * @param href - The address of the page, absolute so a crawler can resolve it.
+ */
+export declare function canonicalLink(href: string): void;
+/** What a page is called and where it is indexed. */
+export interface DocumentMeta {
+    /** The title of the tab, the search result and the shared card. */
+    title: string;
+    /**
+     * One sentence describing this page, in the words someone would search for.
+     * Left out, the description the page was served with stays as it is — which
+     * is what every crawler but a rendering one has already read.
+     * @default undefined
+     */
+    description?: string;
+    /**
+     * The absolute address the page is indexed under. Left out, the canonical
+     * link the page was served with stays as it is.
+     * @default undefined
+     */
+    canonical?: string;
+}
+//# sourceMappingURL=documentMeta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documentMeta.d.ts","sourceRoot":"","sources":["../../../src/seo/core/documentMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAK1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAiBhD;AAED,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/lib/seo/core/documentMeta.js

@@ -0,0 +1,69 @@
+/**
+ * Keep the head in step with the page on screen after an in-app move.
+ *
+ * The server, or the build that wrote one file per address, already titled the
+ * page it handed out; this is what a click inside the app changes, and what a
+ * crawler that renders the page reads afterwards. Every access to the document
+ * is guarded, so a prerender script importing this under Node does nothing
+ * rather than throwing.
+ * @param meta - What the page on screen is called and where it is indexed.
+ */
+export function writeDocumentMeta(meta) {
+    if (typeof document === 'undefined')
+        return;
+    documentTitle(meta.title);
+    if (meta.description !== undefined)
+        metaDescription(meta.description);
+    if (meta.canonical !== undefined)
+        canonicalLink(meta.canonical);
+}
+/**
+ * Name the browser tab.
+ * @param title - The title of the page, site name included.
+ */
+export function documentTitle(title) {
+    if (typeof document === 'undefined')
+        return;
+    document.title = title;
+}
+/**
+ * Point the canonical link at the address the page is indexed under, creating
+ * the tag when the served page carries none.
+ *
+ * The query string is dropped, and so is any fragment: the structure being
+ * edited and the configuration a shared link carries are not pages of their
+ * own, and indexing them as such splits one result into hundreds.
+ * @param href - The address of the page, absolute so a crawler can resolve it.
+ */
+export function canonicalLink(href) {
+    if (typeof document === 'undefined')
+        return;
+    const address = withoutQuery(href);
+    if (address === '')
+        return;
+    const existing = document.querySelector('link[rel="canonical"]');
+    if (existing) {
+        existing.href = address;
+        return;
+    }
+    const link = document.createElement('link');
+    link.rel = 'canonical';
+    document.head.append(link);
+    link.href = address;
+}
+function metaDescription(content) {
+    const existing = document.querySelector('meta[name="description"]');
+    if (existing) {
+        existing.content = content;
+        return;
+    }
+    const meta = document.createElement('meta');
+    meta.name = 'description';
+    document.head.append(meta);
+    meta.content = content;
+}
+function withoutQuery(href) {
+    const cut = href.search(/[?#]/);
+    return cut === -1 ? href : href.slice(0, cut);
+}
+//# sourceMappingURL=documentMeta.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documentMeta.js","sourceRoot":"","sources":["../../../src/seo/core/documentMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAkB;IAClD,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAO;IAC5C,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS;QAAE,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACtE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAO;IAC5C,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAO;IAC5C,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO;IAE3B,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CACrC,uBAAuB,CACxB,CAAC;IACF,IAAI,QAAQ,EAAE,CAAC;QACb,QAAQ,CAAC,IAAI,GAAG,OAAO,CAAC;QACxB,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,GAAG,GAAG,WAAW,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC;AACtB,CAAC;AAqBD,SAAS,eAAe,CAAC,OAAe;IACtC,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CACrC,0BAA0B,CAC3B,CAAC;IACF,IAAI,QAAQ,EAAE,CAAC;QACb,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC;QAC3B,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;AACzB,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC"}

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

@@ -0,0 +1,9 @@
+export type { DocumentMeta } from './documentMeta.ts';
+export { canonicalLink, documentTitle, writeDocumentMeta, } from './documentMeta.ts';
+export type { PageMetaOptions } from './pageMeta.ts';
+export { injectPageMeta, insertBeforeHeadEnd, pageDocumentMeta, } from './pageMeta.ts';
+export type { RouteMeta } from './routes.ts';
+export { homeRoute, pageMetaFor, routeFor, trimTrailingSlash, } from './routes.ts';
+export type { SiteFilesOptions, StructuredDataOptions } from './siteFiles.ts';
+export { noscriptIndex, robotsTxt, sitemapXml, structuredDataScript, } from './siteFiles.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/seo/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,SAAS,EACT,WAAW,EACX,QAAQ,EACR,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EACL,aAAa,EACb,SAAS,EACT,UAAU,EACV,oBAAoB,GACrB,MAAM,gBAAgB,CAAC"}

package/lib/seo/core/index.js

@@ -0,0 +1,5 @@
+export { canonicalLink, documentTitle, writeDocumentMeta, } from "./documentMeta.js";
+export { injectPageMeta, insertBeforeHeadEnd, pageDocumentMeta, } from "./pageMeta.js";
+export { homeRoute, pageMetaFor, routeFor, trimTrailingSlash, } from "./routes.js";
+export { noscriptIndex, robotsTxt, sitemapXml, structuredDataScript, } from "./siteFiles.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/seo/core/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,EACT,WAAW,EACX,QAAQ,EACR,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,SAAS,EACT,UAAU,EACV,oBAAoB,GACrB,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1,60 @@
+/**
+ * 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 rewrites 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`.
+ */
+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. */
+    url: string;
+    /**
+     * Origin every absolute address is built on. A server passes the one the
+     * request arrived on; a build leaves it out and the site's own host is used.
+     * @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 page.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The page, with its head rewritten for that route.
+ */
+export declare function injectPageMeta(html: string, 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.
+ */
+export declare function pageDocumentMeta(options: PageMetaOptions): Required<DocumentMeta>;
+/**
+ * Put an addition at the end of the head, where a tracking snippet and a
+ * structured-data block both belong.
+ * @param html - The page.
+ * @param addition - The markup to add, taken as written.
+ * @returns The page, with the addition before `</head>`.
+ */
+export declare function insertBeforeHeadEnd(html: string, addition: string): string;
+//# 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;;;;;;;;;GASG;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;AAG7C,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC;IAC7B,qEAAqE;IACrE,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7B,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAuB7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAAC,YAAY,CAAC,CASjF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI1E"}

package/lib/seo/core/pageMeta.js

@@ -0,0 +1,91 @@
+/**
+ * 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 rewrites 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`.
+ */
+import { siteById, siteDisplayName } from "../../ecosystem/core/lookup.js";
+import { escapeAttribute, escapeText } from "../../share/core/escape.js";
+import { pageMetaFor, trimTrailingSlash } from "./routes.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 page.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The page, with its head rewritten for that route.
+ */
+export function injectPageMeta(html, options) {
+    const site = resolveSite(options.site);
+    const meta = pageMetaFor(options.routes, options.url);
+    const name = siteDisplayName(site);
+    const origin = trimTrailingSlash(options.origin ?? `https://${site.host}`);
+    const { title, canonical } = pageDocumentMeta(options);
+    const image = absolute(options.image ?? '/og.png', origin);
+    const head = [
+        `<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(meta.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');
+    return insertBeforeHeadEnd(replaceDescription(replaceTitle(html, title), meta.description), head);
+}
+/**
+ * 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.
+ */
+export function pageDocumentMeta(options) {
+    const site = resolveSite(options.site);
+    const meta = pageMetaFor(options.routes, options.url);
+    const origin = trimTrailingSlash(options.origin ?? `https://${site.host}`);
+    return {
+        title: `${meta.title} — ${siteDisplayName(site)}`,
+        description: meta.description,
+        canonical: `${origin}${meta.path}`,
+    };
+}
+/**
+ * Put an addition at the end of the head, where a tracking snippet and a
+ * structured-data block both belong.
+ * @param html - The page.
+ * @param addition - The markup to add, taken as written.
+ * @returns The page, with the addition before `</head>`.
+ */
+export function insertBeforeHeadEnd(html, addition) {
+    const head = html.lastIndexOf('</head>');
+    if (head === -1)
+        return `${html}\n${addition}\n`;
+    return `${html.slice(0, head)}${addition}\n${html.slice(head)}`;
+}
+function resolveSite(site) {
+    return typeof site === 'string' ? siteById(site) : site;
+}
+function absolute(target, origin) {
+    return target.startsWith('/') ? `${origin}${target}` : target;
+}
+function replaceTitle(html, title) {
+    const replacement = `<title>${escapeText(title)}</title>`;
+    return html.includes('<title>')
+        ? html.replace(/<title>[\s\S]*?<\/title>/, replacement)
+        : insertBeforeHeadEnd(html, replacement);
+}
+function replaceDescription(html, description) {
+    const replacement = `<meta name="description" content="${escapeAttribute(description)}" />`;
+    const existing = /<meta[^>]*name="description"[^>]*>/;
+    return existing.test(html)
+        ? html.replace(existing, replacement)
+        : insertBeforeHeadEnd(html, replacement);
+}
+//# 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":"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"}