react-cheminfo 0.64.0 → 0.65.0

package/lib/router/core/history.js

@@ -8,6 +8,7 @@
  * script can import a module that uses it.
  */
 import { EMBED_PARAM, HIDE_PARAM } from "../../share/core/config.js";
+import { stripBasePath } from "./basePath.js";
 import { pageHistory, pageLocation } from "./pageAddress.js";
 import { formatQueryEntries } from "./query.js";
 /**
@@ -20,13 +21,17 @@ export const ROUTE_CHANGE_EVENT = 'cheminfo:routechange';
  *
  * A link written before the site routed by path — `/#/tutorial/3` — is replaced
  * in place, once, by the address the router writes for it, when the router
- * adopts such links.
+ * adopts such links. So is a `?lang=` a sibling site handed the language over
+ * in, on a router given `languages`: the language moves into the path, so one
+ * reader's bookmark and the next one's are the same address. The language of a
+ * prefixed address never changes: `/fr/tutorial?lang=de` stays French.
  * @param router - The site's router.
  * @returns The route of the address on screen, or of `/` where there is no browser.
  */
 export function readRoute(router) {
     const address = currentAddress();
-    const adopted = router.legacyAddress(address);
+    const legacy = router.legacyAddress(address);
+    const adopted = router.languageAddress?.(legacy ?? address) ?? legacy;
     if (adopted === null)
         return router.parse(address);
     const history = pageHistory();
@@ -34,14 +39,45 @@ export function readRoute(router) {
     globalThis.dispatchEvent?.(new Event(ROUTE_CHANGE_EVENT));
     return router.parse(adopted);
 }
+/**
+ * Read the route the site opens on, the reader's own language applied to a
+ * bare root.
+ *
+ * A bare `/` — no page, no query, no fragment — names no language, so the one
+ * the reader last chose may decide which front page opens, and the address is
+ * rewritten in place to say it. Nothing else is steered: a deep link opens what
+ * it names for everybody, so `/tutorial` handed out in a course is English and
+ * `/fr/tutorial` French, whatever either reader last read.
+ * @param router - The site's router, given `languages`.
+ * @param preferred - The language the reader last chose; `undefined`, or one
+ * the router does not write, steers nothing.
+ * @returns The route to open on.
+ */
+export function openingRoute(router, preferred) {
+    const bare = isBareRoot(router);
+    const route = readRoute(router);
+    const steered = bare &&
+        preferred !== undefined &&
+        preferred !== route.language &&
+        router.languages?.includes(preferred) === true;
+    if (!steered)
+        return route;
+    const address = router.format({ ...route, language: preferred });
+    const history = pageHistory();
+    history?.replaceState(history.state, '', address);
+    globalThis.dispatchEvent?.(new Event(ROUTE_CHANGE_EVENT));
+    return router.parse(address);
+}
 /**
  * Point the browser at a route.
  *
  * The share parameters of the address on screen, and the preference names in
  * `keep`, survive the move, so an embedded page stays embedded after its first
  * click. A parameter the route names itself — even as `null` or `undefined`, to
- * remove it — is the route's. Writing the address already on screen does
- * nothing, so echoing state back into the address cannot loop.
+ * remove it — is the route's. On a router given `languages`, a route naming no
+ * language keeps the one on screen, and changing language counts as changing
+ * tab. Writing the address already on screen does nothing, so echoing state
+ * back into the address cannot loop.
  * @param router - The site's router.
  * @param route - Where to go.
  * @param options - How the move is recorded and which parameters survive it.
@@ -60,7 +96,9 @@ export function writeRoute(router, route, options = {}) {
     if (shown === address)
         return address;
     const mode = options.history ?? 'auto';
-    const sameTab = router.parse(current).tab === router.parse(address).tab;
+    const from = router.parse(current);
+    const to = router.parse(address);
+    const sameTab = from.tab === to.tab && from.language === to.language;
     if (mode === 'replace' || (mode === 'auto' && sameTab)) {
         history.replaceState(history.state, '', address);
     }
@@ -99,9 +137,11 @@ export function currentAddress() {
     return `${location.pathname}${location.search}${location.hash}`;
 }
 function withKeptParams(router, route, current, keep) {
-    const target = router.format(route);
+    const onScreen = router.parse(current);
+    const language = route.language ?? onScreen.language;
+    const target = router.format(language === undefined ? route : { ...route, language });
     const named = route.params ?? {};
-    const shown = router.parse(current).params;
+    const shown = onScreen.params;
     const kept = [];
     for (const key of new Set([EMBED_PARAM, HIDE_PARAM, ...keep])) {
         if (Object.hasOwn(named, key))
@@ -115,4 +155,12 @@ function withKeptParams(router, route, current, keep) {
     const separator = target.includes('?') ? '&' : '?';
     return `${target}${separator}${formatQueryEntries(kept)}`;
 }
+function isBareRoot(router) {
+    const location = pageLocation();
+    if (location === undefined)
+        return false;
+    if (location.search !== '' || location.hash !== '')
+        return false;
+    return stripBasePath(router.basePath ?? '', location.pathname) === '/';
+}
 //# sourceMappingURL=history.js.map

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

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

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

@@ -1,7 +1,7 @@
 export { trimTrailingSlash } from './address.ts';
 export { basePathOf, joinBasePath, normalizeBasePath, readMountPath, stripBasePath, } from './basePath.ts';
 export type { WriteRouteOptions } from './history.ts';
-export { ROUTE_CHANGE_EVENT, readRoute, subscribeToRoute, writeRoute, } from './history.ts';
+export { ROUTE_CHANGE_EVENT, openingRoute, readRoute, subscribeToRoute, writeRoute, } from './history.ts';
 export type { AdoptLegacyHashOptions, LegacyHashOptions, } from './legacyHash.ts';
 export { adoptLegacyHashAddress, pathFromLegacyHash } from './legacyHash.ts';
 export type { PageHistory, PageLocation } from './pageAddress.ts';
@@ -9,7 +9,7 @@ export { holdPageAddress, isPageAddressHeld, pageHistory, pageLocation, releaseP
 export type { QueryEntry, QueryStringOptions } from './query.ts';
 export { firstQueryValues, formatQueryEntries, formatQueryString, parseQueryEntries, parseQueryString, } from './query.ts';
 export type { SiteAddresses, SiteAddressesOptions } from './siteAddresses.ts';
-export { createSiteAddresses } from './siteAddresses.ts';
-export type { TabDefinition, TabRoute, TabRouteInput, TabRouter, TabRouterOptions, } from './tabRouter.ts';
+export { anchorHref, createSiteAddresses } from './siteAddresses.ts';
+export type { TabDefinition, TabRoute, TabRouteInput, TabRouter, TabRouterOptions, } from './tabRouterTypes.ts';
 export { createTabRouter } from './tabRouter.ts';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/router/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EACV,aAAa,EACb,QAAQ,EACR,aAAa,EACb,SAAS,EACT,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/router/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACrE,YAAY,EACV,aAAa,EACb,QAAQ,EACR,aAAa,EACb,SAAS,EACT,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/lib/router/core/index.js

@@ -1,9 +1,9 @@
 export { trimTrailingSlash } from "./address.js";
 export { basePathOf, joinBasePath, normalizeBasePath, readMountPath, stripBasePath, } from "./basePath.js";
-export { ROUTE_CHANGE_EVENT, readRoute, subscribeToRoute, writeRoute, } from "./history.js";
+export { ROUTE_CHANGE_EVENT, openingRoute, readRoute, subscribeToRoute, writeRoute, } from "./history.js";
 export { adoptLegacyHashAddress, pathFromLegacyHash } from "./legacyHash.js";
 export { holdPageAddress, isPageAddressHeld, pageHistory, pageLocation, releasePageAddress, } from "./pageAddress.js";
 export { firstQueryValues, formatQueryEntries, formatQueryString, parseQueryEntries, parseQueryString, } from "./query.js";
-export { createSiteAddresses } from "./siteAddresses.js";
+export { anchorHref, createSiteAddresses } from "./siteAddresses.js";
 export { createTabRouter } from "./tabRouter.js";
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/router/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,UAAU,GACX,MAAM,cAAc,CAAC;AAKtB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAQzD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/router/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,UAAU,GACX,MAAM,cAAc,CAAC;AAKtB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAQrE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1,61 @@
+/**
+ * The language half of a translated site's routes: the prefix a page is
+ * written under, and the `?lang=` a sibling site hands the language over in.
+ *
+ * Inside a translated site the language is the path — `/fr/tutorial` — so each
+ * language is an address of its own a crawler indexes and a course hands out.
+ * Between sites it travels as a parameter, because the site being linked to
+ * may not speak it, and a parameter it does not know is ignored where a prefix
+ * it does not have is a 404. So a route reads the parameter only where the
+ * prefix says nothing, and the prefix always wins: `/fr/tutorial?lang=de` is
+ * the French tutorial for everybody.
+ */
+import type { Language } from '../../i18n/core/languages.ts';
+import type { QueryStringOptions } from './query.ts';
+/** The language a route is read in, and what is left of its address. */
+export interface RouteLanguage {
+    /** The language the page is read in. */
+    language: Language;
+    /** The path from the site's own root, the prefix taken off. */
+    path: string;
+    /** The parameters, without a `lang` that names a language of the site. */
+    params: Record<string, string>;
+}
+/**
+ * Read the language of a route off its path and its parameters.
+ * @param path - The path from the site's own root, the mount already off.
+ * @param params - The decoded query parameters.
+ * @param languages - The languages the site is written in.
+ * @returns The language, the path without its prefix, and the parameters.
+ */
+export declare function readRouteLanguage(path: string, params: Record<string, string>, languages: readonly Language[]): RouteLanguage;
+/**
+ * Write a path from the site's own root under a language's prefix.
+ * @param language - The language asked for, if any.
+ * @param path - The path from the site's own root.
+ * @param languages - The languages the site is written in.
+ * @returns The path under the prefix; a language the site does not speak is
+ * written as the default one, with no prefix.
+ */
+export declare function writeRouteLanguage(language: Language | undefined, path: string, languages: readonly Language[]): string;
+/** How {@link adoptLanguageParam} reads an address. */
+export interface AdoptLanguageOptions {
+    /** The mount path, normalised. */
+    basePath: string;
+    /** The languages the site is written in. */
+    languages: readonly Language[];
+    /** How the query string is read and written back. */
+    queryOptions: QueryStringOptions;
+}
+/**
+ * The address to put in place of one carrying a `?lang=` the site speaks.
+ *
+ * Only the language moves: the page named stays the page written, whether the
+ * router knows it or not, and every other parameter and the fragment are kept.
+ * @param address - A browser address: mount, prefix, page, query and fragment.
+ * @param options - The mount, the languages and how the query is read.
+ * @returns The address with the language in its path, or `null` when the
+ * address names no language of the site in its query.
+ */
+export declare function adoptLanguageParam(address: string, options: AdoptLanguageOptions): string | null;
+//# sourceMappingURL=languageRoute.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"languageRoute.d.ts","sourceRoot":"","sources":["../../../src/router/core/languageRoute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAU7D,OAAO,KAAK,EAAc,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGjE,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,QAAQ,EAAE,QAAQ,CAAC;IACnB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,aAAa,CAUf;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,MAAM,CAMR;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/B,qDAAqD;IACrD,YAAY,EAAE,kBAAkB,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,GAC5B,MAAM,GAAG,IAAI,CAsBf"}

package/lib/router/core/languageRoute.js

@@ -0,0 +1,96 @@
+/**
+ * The language half of a translated site's routes: the prefix a page is
+ * written under, and the `?lang=` a sibling site hands the language over in.
+ *
+ * Inside a translated site the language is the path — `/fr/tutorial` — so each
+ * language is an address of its own a crawler indexes and a course hands out.
+ * Between sites it travels as a parameter, because the site being linked to
+ * may not speak it, and a parameter it does not know is ignored where a prefix
+ * it does not have is a 404. So a route reads the parameter only where the
+ * prefix says nothing, and the prefix always wins: `/fr/tutorial?lang=de` is
+ * the French tutorial for everybody.
+ */
+import { DEFAULT_LANGUAGE } from "../../i18n/core/languages.js";
+import { LANGUAGE_PARAM } from "../../language/core/languageParam.js";
+import { readLanguagePath, withLanguagePath, } from "../../language/core/languagePath.js";
+import { splitAddress } from "./address.js";
+import { joinBasePath, stripBasePath } from "./basePath.js";
+import { formatQueryEntries, parseQueryEntries } from "./query.js";
+/**
+ * Read the language of a route off its path and its parameters.
+ * @param path - The path from the site's own root, the mount already off.
+ * @param params - The decoded query parameters.
+ * @param languages - The languages the site is written in.
+ * @returns The language, the path without its prefix, and the parameters.
+ */
+export function readRouteLanguage(path, params, languages) {
+    const read = readLanguagePath(path, languages);
+    const named = siteLanguage(params[LANGUAGE_PARAM], languages);
+    if (named === undefined)
+        return { ...read, params };
+    const kept = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (key !== LANGUAGE_PARAM)
+            kept[key] = value;
+    }
+    const language = read.language === DEFAULT_LANGUAGE ? named : read.language;
+    return { language, path: read.path, params: kept };
+}
+/**
+ * Write a path from the site's own root under a language's prefix.
+ * @param language - The language asked for, if any.
+ * @param path - The path from the site's own root.
+ * @param languages - The languages the site is written in.
+ * @returns The path under the prefix; a language the site does not speak is
+ * written as the default one, with no prefix.
+ */
+export function writeRouteLanguage(language, path, languages) {
+    const written = language !== undefined && languages.includes(language)
+        ? language
+        : DEFAULT_LANGUAGE;
+    return withLanguagePath(written, path);
+}
+/**
+ * The address to put in place of one carrying a `?lang=` the site speaks.
+ *
+ * Only the language moves: the page named stays the page written, whether the
+ * router knows it or not, and every other parameter and the fragment are kept.
+ * @param address - A browser address: mount, prefix, page, query and fragment.
+ * @param options - The mount, the languages and how the query is read.
+ * @returns The address with the language in its path, or `null` when the
+ * address names no language of the site in its query.
+ */
+export function adoptLanguageParam(address, options) {
+    const { basePath, languages, queryOptions } = options;
+    const { path, search, fragment } = splitAddress(address);
+    const entries = parseQueryEntries(search, queryOptions);
+    let named;
+    const kept = [];
+    for (const entry of entries) {
+        const language = entry[0] === LANGUAGE_PARAM
+            ? siteLanguage(entry[1], languages)
+            : undefined;
+        if (language === undefined)
+            kept.push(entry);
+        else
+            named ??= language;
+    }
+    if (named === undefined)
+        return null;
+    const read = readLanguagePath(stripBasePath(basePath, path), languages);
+    const language = read.language === DEFAULT_LANGUAGE ? named : read.language;
+    const opened = joinBasePath(basePath, withLanguagePath(language, read.path));
+    const query = formatQueryEntries(kept);
+    const withQuery = query === '' ? opened : `${opened}?${query}`;
+    return fragment === '' ? withQuery : `${withQuery}#${fragment}`;
+}
+function siteLanguage(value, languages) {
+    if (value === undefined)
+        return undefined;
+    for (const language of languages) {
+        if (language === value)
+            return language;
+    }
+    return undefined;
+}
+//# sourceMappingURL=languageRoute.js.map

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

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

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

@@ -14,6 +14,18 @@ import type { SiteId } from '../../ecosystem/core/sites.ts';
  * @throws {Error} When no site of the family carries that identifier.
  */
 export declare function createSiteAddresses(siteId: SiteId, options?: SiteAddressesOptions): SiteAddresses;
+/**
+ * A link to an anchor on the page being read.
+ *
+ * Every page of ours carries a `<base>`, so a bare `#id` resolves against the
+ * mount rather than against the address open, and clicking it leaves the page
+ * instead of scrolling down it. The link names the page's own address and its
+ * query instead — the browser's, since that is the document a click scrolls.
+ * @param id - The `id` of the element to jump to.
+ * @returns The address of that anchor on the page on screen, or `#id` where
+ * there is no page.
+ */
+export declare function anchorHref(id: string): string;
 /** How {@link createSiteAddresses} reads the mount. */
 export interface SiteAddressesOptions {
     /**
@@ -45,5 +57,16 @@ export interface SiteAddresses {
      * it says something, the site's own address otherwise.
      */
     configuredSiteUrl: () => string;
+    /** A link to an anchor on the page on screen; see {@link anchorHref}. */
+    anchorHref: (id: string) => string;
+    /**
+     * The address of something a backend stored and the page shows — an
+     * uploaded picture — as this deployment serves it. A backend names those
+     * from its own root, `/uploads/<name>`, because a proxy mounting the site
+     * under a path strips the path before the request reaches it; so a
+     * root-relative address is put under the mount, and one carrying its own
+     * scheme or origin, or relative already, is handed back untouched.
+     */
+    storedAssetSrc: (url: string) => string;
 }
 //# sourceMappingURL=siteAddresses.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"siteAddresses.d.ts","sourceRoot":"","sources":["../../../src/router/core/siteAddresses.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAU5D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB,GACjC,aAAa,CAmCf;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,iEAAiE;IACjE,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C;;;OAGG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC;;;OAGG;IACH,iBAAiB,EAAE,MAAM,MAAM,CAAC;CACjC"}
+{"version":3,"file":"siteAddresses.d.ts","sourceRoot":"","sources":["../../../src/router/core/siteAddresses.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAU5D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB,GACjC,aAAa,CA0Cf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAI7C;AAKD,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,iEAAiE;IACjE,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C;;;OAGG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC;;;OAGG;IACH,iBAAiB,EAAE,MAAM,MAAM,CAAC;IAChC,yEAAyE;IACzE,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC;;;;;;;OAOG;IACH,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CACzC"}

package/lib/router/core/siteAddresses.js

@@ -34,6 +34,11 @@ export function createSiteAddresses(siteId, options = {}) {
         const environment = globalThis.process?.env?.SITE_URL;
         return environment || ownUrl;
     }
+    function storedAssetSrc(url) {
+        if (OWN_ORIGIN.test(url) || url.startsWith('//'))
+            return url;
+        return url.startsWith('/') ? withBase(url) : url;
+    }
     return {
         basePath,
         siteName: siteDisplayName(site),
@@ -42,6 +47,27 @@ export function createSiteAddresses(siteId, options = {}) {
         pathWithoutBase,
         absoluteUrl,
         configuredSiteUrl,
+        anchorHref,
+        storedAssetSrc,
     };
 }
+/**
+ * A link to an anchor on the page being read.
+ *
+ * Every page of ours carries a `<base>`, so a bare `#id` resolves against the
+ * mount rather than against the address open, and clicking it leaves the page
+ * instead of scrolling down it. The link names the page's own address and its
+ * query instead — the browser's, since that is the document a click scrolls.
+ * @param id - The `id` of the element to jump to.
+ * @returns The address of that anchor on the page on screen, or `#id` where
+ * there is no page.
+ */
+export function anchorHref(id) {
+    const location = globalThis.location;
+    if (location === undefined)
+        return `#${id}`;
+    return `${location.pathname}${location.search}#${id}`;
+}
+// A scheme names its own origin: `https:`, `data:`, `blob:`.
+const OWN_ORIGIN = /^[a-z][\w+.-]*:/i;
 //# sourceMappingURL=siteAddresses.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"siteAddresses.js","sourceRoot":"","sources":["../../../src/router/core/siteAddresses.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAExD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,UAAgC,EAAE;IAElC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,QAAQ,IAAI,aAAa,EAAE,CAAC,CAAC;IAExE,SAAS,QAAQ,CAAC,IAAY;QAC5B,OAAO,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,SAAS,eAAe,CAAC,QAAgB;QACvC,OAAO,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,SAAS,WAAW,CAAC,IAAY;QAC/B,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAgC,CAAC;QAC7D,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;QAC1D,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACtC,CAAC;IAED,SAAS,iBAAiB;QACxB,MAAM,WAAW,GACf,UACD,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC;QACzB,OAAO,WAAW,IAAI,MAAM,CAAC;IAC/B,CAAC;IAED,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE,eAAe,CAAC,IAAI,CAAC;QAC/B,OAAO,EAAE,MAAM;QACf,QAAQ;QACR,eAAe;QACf,WAAW;QACX,iBAAiB;KAClB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"siteAddresses.js","sourceRoot":"","sources":["../../../src/router/core/siteAddresses.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAExD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,UAAgC,EAAE;IAElC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,QAAQ,IAAI,aAAa,EAAE,CAAC,CAAC;IAExE,SAAS,QAAQ,CAAC,IAAY;QAC5B,OAAO,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,SAAS,eAAe,CAAC,QAAgB;QACvC,OAAO,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,SAAS,WAAW,CAAC,IAAY;QAC/B,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAgC,CAAC;QAC7D,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;QAC1D,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACtC,CAAC;IAED,SAAS,iBAAiB;QACxB,MAAM,WAAW,GACf,UACD,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC;QACzB,OAAO,WAAW,IAAI,MAAM,CAAC;IAC/B,CAAC;IAED,SAAS,cAAc,CAAC,GAAW;QACjC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,GAAG,CAAC;QAC7D,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACnD,CAAC;IAED,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE,eAAe,CAAC,IAAI,CAAC;QAC/B,OAAO,EAAE,MAAM;QACf,QAAQ;QACR,eAAe;QACf,WAAW;QACX,iBAAiB;QACjB,UAAU;QACV,cAAc;KACf,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAgC,CAAC;IAC7D,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,EAAE,EAAE,CAAC;IAC5C,OAAO,GAAG,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;AACxD,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,GAAG,kBAAkB,CAAC"}

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

@@ -1,3 +1,5 @@
+import type { TabRouter, TabRouterOptions } from './tabRouterTypes.ts';
+export type { TabDefinition, TabRoute, TabRouteInput, TabRouter, TabRouterOptions, } from './tabRouterTypes.ts';
 /**
  * The two directions between an address and the page it names.
  *
@@ -9,112 +11,4 @@
  * @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> {
-    /** Whether the route lives in the path or in the fragment. */
-    mode: 'path' | 'hash';
-    /**
-     * 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;
-    /**
-     * The address to put in the bar in place of a link written before the site
-     * routed by path: the page it names as this router writes it, with the query
-     * string kept as it was. `null` when the address is no such link, or when the
-     * router does not adopt them.
-     */
-    legacyAddress: (address: string) => string | null;
-}
 //# sourceMappingURL=tabRouter.d.ts.map

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

@@ -1 +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,CAmEhB;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,8DAA8D;IAC9D,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB;;;;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;IACvC;;;;;OAKG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACnD"}
+{"version":3,"file":"tabRouter.d.ts","sourceRoot":"","sources":["../../../src/router/core/tabRouter.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAGV,SAAS,EACT,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,aAAa,EACb,QAAQ,EACR,aAAa,EACb,SAAS,EACT,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,SAAS,MAAM,EAChD,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAC7B,SAAS,CAAC,GAAG,CAAC,CAuGhB"}