react-cheminfo 0.2.0 → 0.4.0

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

@@ -0,0 +1,45 @@
+/** How a legacy hash link is turned into the path it means. */
+export interface LegacyHashOptions {
+    /**
+     * Carry the query string of the address over to the path. The share
+     * configuration lives there, so an embed stays configured across the move.
+     * A query written inside the fragment itself always wins over it.
+     * @default true
+     */
+    keepSearch?: boolean;
+}
+/** How an address is read when adopting the path a legacy hash link meant. */
+export interface AdoptLegacyHashOptions extends LegacyHashOptions {
+    /**
+     * The path the site is mounted at, so a legacy link to a tool served under
+     * one is recognised as sitting on its root.
+     * @default ''
+     */
+    basePath?: string;
+}
+/**
+ * The path a link written before the site routed by path points at.
+ *
+ * Those links are in course pages, in bookmarks and inside other people's
+ * iframes, so they are answered rather than dropped. Only a fragment shaped
+ * like a path is one: an anchor such as `#results` names a place inside a page
+ * and comes back `null`.
+ * @param address - A full address, or the fragment on its own, e.g. `/#/tutorial/3`.
+ * @param options - Whether the query string is carried over.
+ * @returns The path form of the address, or `null` when it names no page.
+ */
+export declare function pathFromLegacyHash(address: string, options?: LegacyHashOptions): string | null;
+/**
+ * The address to put in the bar in place of a legacy hash link, before anything
+ * reads it.
+ *
+ * Called once at startup with `location.pathname + location.search +
+ * location.hash`, so nothing downstream has to know the site ever routed by the
+ * hash. Only a visitor sitting on the site's root is moved: a fragment on a
+ * real page is an anchor of that page, not an address of its own.
+ * @param address - The address the browser is on.
+ * @param options - Whether the query is carried over, and the site's mount path.
+ * @returns The address to replace it with, or `null` when there is nothing to adopt.
+ */
+export declare function adoptLegacyHashAddress(address: string, options?: AdoptLegacyHashOptions): string | null;
+//# sourceMappingURL=legacyHash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"legacyHash.d.ts","sourceRoot":"","sources":["../../../src/router/core/legacyHash.ts"],"names":[],"mappings":"AAGA,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,MAAM,GAAG,IAAI,CAWf"}

package/lib/router/core/legacyHash.js

@@ -0,0 +1,50 @@
+import { splitAddress } from "./address.js";
+import { normalizeBasePath, stripBasePath } from "./basePath.js";
+/**
+ * The path a link written before the site routed by path points at.
+ *
+ * Those links are in course pages, in bookmarks and inside other people's
+ * iframes, so they are answered rather than dropped. Only a fragment shaped
+ * like a path is one: an anchor such as `#results` names a place inside a page
+ * and comes back `null`.
+ * @param address - A full address, or the fragment on its own, e.g. `/#/tutorial/3`.
+ * @param options - Whether the query string is carried over.
+ * @returns The path form of the address, or `null` when it names no page.
+ */
+export function pathFromLegacyHash(address, options = {}) {
+    const outer = splitAddress(address);
+    if (outer.fragment === '' || !outer.fragment.startsWith('/'))
+        return null;
+    const inner = splitAddress(outer.fragment);
+    if (inner.path === '/')
+        return null;
+    const keepSearch = options.keepSearch ?? true;
+    const search = inner.search || (keepSearch ? outer.search : '');
+    return search === '' ? inner.path : `${inner.path}?${search}`;
+}
+/**
+ * The address to put in the bar in place of a legacy hash link, before anything
+ * reads it.
+ *
+ * Called once at startup with `location.pathname + location.search +
+ * location.hash`, so nothing downstream has to know the site ever routed by the
+ * hash. Only a visitor sitting on the site's root is moved: a fragment on a
+ * real page is an anchor of that page, not an address of its own.
+ * @param address - The address the browser is on.
+ * @param options - Whether the query is carried over, and the site's mount path.
+ * @returns The address to replace it with, or `null` when there is nothing to adopt.
+ */
+export function adoptLegacyHashAddress(address, options = {}) {
+    const basePath = normalizeBasePath(options.basePath ?? '');
+    if (stripBasePath(basePath, splitAddress(address).path) !== '/')
+        return null;
+    const path = pathFromLegacyHash(address, options);
+    if (path === null)
+        return null;
+    if (basePath === '')
+        return path;
+    const { path: adopted, search } = splitAddress(path);
+    const mounted = `${basePath}${adopted}`;
+    return search === '' ? mounted : `${mounted}?${search}`;
+}
+//# sourceMappingURL=legacyHash.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"legacyHash.js","sourceRoot":"","sources":["../../../src/router/core/legacyHash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAuBjE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,UAA6B,EAAE;IAE/B,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,QAAQ,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAE1E,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAEpC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;IAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAChE,OAAO,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,MAAM,EAAE,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAe,EACf,UAAkC,EAAE;IAEpC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC3D,IAAI,aAAa,CAAC,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAE7E,MAAM,IAAI,GAAG,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAClD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAEjC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,GAAG,QAAQ,GAAG,OAAO,EAAE,CAAC;IACxC,OAAO,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,MAAM,EAAE,CAAC;AAC1D,CAAC"}

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

@@ -0,0 +1,50 @@
+/**
+ * The table of everything the site answers, read by the three things that must
+ * agree on it: the build, which writes one HTML file per entry and the sitemap
+ * listing them; the server or the entrypoint, which titles the page it hands
+ * out; and the running app, which retitles the tab after an in-app move.
+ *
+ * Pure and DOM-free, so the prerender script imports the same table under Node
+ * that the browser imports at run time. A page missing from it is a page a
+ * search engine only ever sees as the home page.
+ * @param options - The pages, in the order the site presents them.
+ * @returns The three lookups the build and the app share.
+ */
+export declare function createPageAddresses<Page extends PageWithPath>(options: PageAddressesOptions<Page>): PageAddresses<Page>;
+/** The one thing a page must carry: the address it is reachable at. */
+export interface PageWithPath {
+    /** Address from the site's own root, e.g. `/exercises`. */
+    path: string;
+}
+/** How a site's pages are turned into addresses. */
+export interface PageAddressesOptions<Page extends PageWithPath> {
+    /**
+     * Every page, deep addresses included. The first is the home page, and is
+     * what an address the site does not know opens.
+     */
+    pages: readonly Page[];
+    /**
+     * 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;
+}
+/** The lookups a site's pages answer. */
+export interface PageAddresses<Page extends PageWithPath> {
+    /** Every page, in the order given: what the sitemap lists and the build writes. */
+    everyPage: () => readonly Page[];
+    /**
+     * The address a page is indexed under, mount path included and query string
+     * dropped — a structure being edited and a share configuration are not pages.
+     */
+    canonicalPathOf: (page: Page) => string;
+    /**
+     * The page an address opens. An address below a page it does not list is that
+     * page — a link written before an exercise was renamed still opens, and is
+     * indexed as the exercises — and an address it knows nothing about is the
+     * home page.
+     */
+    pageAt: (address: string) => Page;
+}
+//# sourceMappingURL=pageAddresses.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pageAddresses.d.ts","sourceRoot":"","sources":["../../../src/router/core/pageAddresses.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,YAAY,EAC3D,OAAO,EAAE,oBAAoB,CAAC,IAAI,CAAC,GAClC,aAAa,CAAC,IAAI,CAAC,CAgCrB;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,YAAY;IAC7D;;;OAGG;IACH,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa,CAAC,IAAI,SAAS,YAAY;IACtD,mFAAmF;IACnF,SAAS,EAAE,MAAM,SAAS,IAAI,EAAE,CAAC;IACjC;;;OAGG;IACH,eAAe,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;IACxC;;;;;OAKG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC"}

package/lib/router/core/pageAddresses.js

@@ -0,0 +1,56 @@
+import { normalizePath, splitAddress } from "./address.js";
+import { joinBasePath, normalizeBasePath, stripBasePath } from "./basePath.js";
+/**
+ * The table of everything the site answers, read by the three things that must
+ * agree on it: the build, which writes one HTML file per entry and the sitemap
+ * listing them; the server or the entrypoint, which titles the page it hands
+ * out; and the running app, which retitles the tab after an in-app move.
+ *
+ * Pure and DOM-free, so the prerender script imports the same table under Node
+ * that the browser imports at run time. A page missing from it is a page a
+ * search engine only ever sees as the home page.
+ * @param options - The pages, in the order the site presents them.
+ * @returns The three lookups the build and the app share.
+ */
+export function createPageAddresses(options) {
+    const pages = options.pages;
+    const first = pages[0];
+    if (first === undefined) {
+        throw new Error('createPageAddresses needs at least one page');
+    }
+    const home = first;
+    const basePath = normalizeBasePath(options.basePath ?? '');
+    const byPath = new Map();
+    for (const page of pages) {
+        byPath.set(normalizePath(page.path), page);
+    }
+    function everyPage() {
+        return pages;
+    }
+    function canonicalPathOf(page) {
+        return joinBasePath(basePath, normalizePath(page.path));
+    }
+    function pageAt(address) {
+        const path = normalizePath(stripBasePath(basePath, splitAddress(address).path));
+        const exact = byPath.get(path);
+        if (exact !== undefined)
+            return exact;
+        return deepestPageUnder(pages, path) ?? home;
+    }
+    return { everyPage, canonicalPathOf, pageAt };
+}
+function deepestPageUnder(pages, path) {
+    let deepest;
+    let depth = 0;
+    for (const page of pages) {
+        const candidate = normalizePath(page.path);
+        if (candidate === '/' || candidate.length <= depth)
+            continue;
+        if (path.startsWith(`${candidate}/`)) {
+            deepest = page;
+            depth = candidate.length;
+        }
+    }
+    return deepest;
+}
+//# sourceMappingURL=pageAddresses.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pageAddresses.js","sourceRoot":"","sources":["../../../src/router/core/pageAddresses.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAmC;IAEnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,IAAI,GAAS,KAAK,CAAC;IACzB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAE3D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAgB,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED,SAAS,SAAS;QAChB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,SAAS,eAAe,CAAC,IAAU;QACjC,OAAO,YAAY,CAAC,QAAQ,EAAE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,SAAS,MAAM,CAAC,OAAe;QAC7B,MAAM,IAAI,GAAG,aAAa,CACxB,aAAa,CAAC,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CACpD,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACtC,OAAO,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC;IAC/C,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC;AAChD,CAAC;AAyCD,SAAS,gBAAgB,CACvB,KAAsB,EACtB,IAAY;IAEZ,IAAI,OAAyB,CAAC;IAC9B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,SAAS,KAAK,GAAG,IAAI,SAAS,CAAC,MAAM,IAAI,KAAK;YAAE,SAAS;QAC7D,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,SAAS,GAAG,CAAC,EAAE,CAAC;YACrC,OAAO,GAAG,IAAI,CAAC;YACf,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

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"}