react-cheminfo 0.2.0 → 0.4.0

package/src/pedagogy/ui/tutorialLevels.ts

@@ -0,0 +1,27 @@
+/**
+ * The two shades each level of the guided tour is painted in.
+ *
+ * Green, amber, pink — the same three the level tags use, in the pale weights a
+ * strip of buttons can sit on. They are shared so a student moving from one of
+ * our tools to the next reads the shape of the course the same way.
+ */
+
+import type { ExerciseLevel } from '../core/types.ts';
+
+/** How one level is painted. */
+export interface TutorialLevelColours {
+  /** Behind the whole strip. */
+  background: string;
+  /** Behind the step that is open, which is the darker of the two. */
+  activeBackground: string;
+}
+
+/** The palette of the three levels. */
+export const TUTORIAL_LEVEL_COLOURS: Record<
+  ExerciseLevel,
+  TutorialLevelColours
+> = {
+  beginner: { background: '#d1fae5', activeBackground: '#6ee7b7' },
+  intermediate: { background: '#fef3c7', activeBackground: '#fcd34d' },
+  advanced: { background: '#fce7f3', activeBackground: '#f9a8d4' },
+};

package/src/router/core/address.ts

@@ -0,0 +1,74 @@
+/** An address cut into the three parts a router reads separately. */
+export interface AddressParts {
+  /** Path of the address, `/` when it carries none. */
+  path: string;
+  /** Query string, without its leading `?`. */
+  search: string;
+  /** Fragment, without its leading `#`. */
+  fragment: string;
+}
+
+/**
+ * Cut an address into its path, its query and its fragment.
+ *
+ * The fragment is taken first, so a `?` inside it — an old hash link of the
+ * shape `#/tutorial/3?step=2` — stays part of the fragment rather than being
+ * read as the query of the page.
+ * @param address - A path, a full address, or a bare query string.
+ * @returns The three parts, each without its separator.
+ */
+export function splitAddress(address: string): AddressParts {
+  const hashIndex = address.indexOf('#');
+  const beforeHash = hashIndex === -1 ? address : address.slice(0, hashIndex);
+  const fragment = hashIndex === -1 ? '' : address.slice(hashIndex + 1);
+  const queryIndex = beforeHash.indexOf('?');
+  if (queryIndex === -1) {
+    return { path: beforeHash === '' ? '/' : beforeHash, search: '', fragment };
+  }
+  const path = beforeHash.slice(0, queryIndex);
+  return {
+    path: path === '' ? '/' : path,
+    search: beforeHash.slice(queryIndex + 1),
+    fragment,
+  };
+}
+
+/**
+ * The decoded, non-empty segments of a path.
+ * @param path - Path of an address, with or without its leading slash.
+ * @returns One entry per segment, `[]` for the root.
+ */
+export function splitPath(path: string): string[] {
+  const segments: string[] = [];
+  for (const raw of path.split('/')) {
+    if (raw !== '') segments.push(safeDecode(raw));
+  }
+  return segments;
+}
+
+/**
+ * A path in the one shape the lookups compare: a leading slash, no trailing
+ * one, its segments decoded, and neither query nor fragment.
+ * @param path - Path of an address.
+ * @returns The same address, normalized.
+ */
+export function normalizePath(path: string): string {
+  const segments = splitPath(splitAddress(path).path);
+  return segments.length === 0 ? '/' : `/${segments.join('/')}`;
+}
+
+/**
+ * Decode one component of an address, tolerating an escape that is not one.
+ *
+ * `decodeURIComponent` throws on a lone `%`, and an address is hand-editable:
+ * the raw text is closer to what its author meant than an error page.
+ * @param value - Raw, percent-encoded text.
+ * @returns The decoded text, or the raw text when it does not decode.
+ */
+export function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}

package/src/router/core/basePath.ts

@@ -0,0 +1,76 @@
+/**
+ * Where a site is mounted, read off the page rather than off the build.
+ *
+ * The build is mount-agnostic — vite is given a relative base, so the same
+ * `dist` serves `https://surge.cheminfo.org/` and
+ * `https://www.cheminfo.org/surge/`. What tells the two apart is the `<base>`
+ * the deployment stamps into the page it hands out, and `document.baseURI`
+ * resolves it against the address actually opened. So this answers correctly
+ * whether or not a slash closes the address, and on an address the SPA
+ * fallback answered.
+ * @returns The mount path, in the shape {@link normalizeBasePath} returns.
+ */
+export function readMountPath(): string {
+  const baseUri = globalThis.document?.baseURI;
+  if (!baseUri) return '';
+  return normalizeBasePath(new URL(baseUri).pathname);
+}
+
+/**
+ * The path half of a site's address, as a mount path.
+ *
+ * A deployment names where it serves the site in full — origin and path in one
+ * value — because the origin is what the canonical link and the sitemap need.
+ * This is the other half of it.
+ * @param siteUrl - The absolute address the site is served at.
+ * @returns The mount path, in the shape {@link normalizeBasePath} returns.
+ */
+export function basePathOf(siteUrl: string): string {
+  return normalizeBasePath(new URL(siteUrl).pathname);
+}
+
+/**
+ * A mount path in the shape the other helpers assume: the empty string when the
+ * site owns the root of its host, `/surge` when it is one tool among several on
+ * a shared one.
+ * @param basePath - The mount path however it was written: `surge`, `/surge`, `/surge/`.
+ * @returns The normalized mount path, without a trailing slash.
+ */
+export function normalizeBasePath(basePath: string): string {
+  const trimmed = basePath.trim();
+  if (trimmed === '' || trimmed === '/') return '';
+  const opened = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  return opened.replace(/\/+$/, '');
+}
+
+/**
+ * Move one of the site's own addresses under the path it is mounted at.
+ * @param basePath - The mount path, in any of the shapes {@link normalizeBasePath} accepts.
+ * @param path - An address from the site's own root, e.g. `/exercises`.
+ * @returns The address the browser and the server see, e.g. `/surge/exercises`.
+ */
+export function joinBasePath(basePath: string, path: string): string {
+  const base = normalizeBasePath(basePath);
+  const opened = path === '' || !path.startsWith('/') ? `/${path}` : path;
+  if (base === '') return opened;
+  return opened === '/' ? `${base}/` : `${base}${opened}`;
+}
+
+/**
+ * Read one of the site's own addresses back out of a browser path.
+ *
+ * A path that does not sit under the mount is handed back untouched, so a
+ * deployment served from somewhere else than the build was told still routes.
+ * @param basePath - The mount path, in any of the shapes {@link normalizeBasePath} accepts.
+ * @param pathname - The path the browser is on, e.g. `/surge/exercises`.
+ * @returns The address from the site's own root, `/` for the mount itself.
+ */
+export function stripBasePath(basePath: string, pathname: string): string {
+  const base = normalizeBasePath(basePath);
+  const path = pathname === '' ? '/' : pathname;
+  if (base === '') return path;
+  if (path === base || path === `${base}/`) return '/';
+  // `/surgeon` is not a page of a site mounted at `/surge`, so the mount only
+  // matches when what follows it is a path of its own.
+  return path.startsWith(`${base}/`) ? path.slice(base.length) : path;
+}

package/src/router/core/index.ts

@@ -0,0 +1,26 @@
+export {
+  basePathOf,
+  joinBasePath,
+  normalizeBasePath,
+  readMountPath,
+  stripBasePath,
+} from './basePath.ts';
+export type {
+  AdoptLegacyHashOptions,
+  LegacyHashOptions,
+} from './legacyHash.ts';
+export { adoptLegacyHashAddress, pathFromLegacyHash } from './legacyHash.ts';
+export type {
+  PageAddresses,
+  PageAddressesOptions,
+  PageWithPath,
+} from './pageAddresses.ts';
+export { createPageAddresses } from './pageAddresses.ts';
+export type {
+  TabDefinition,
+  TabRoute,
+  TabRouteInput,
+  TabRouter,
+  TabRouterOptions,
+} from './tabRouter.ts';
+export { createTabRouter } from './tabRouter.ts';

package/src/router/core/legacyHash.ts

@@ -0,0 +1,77 @@
+import { splitAddress } from './address.ts';
+import { normalizeBasePath, stripBasePath } from './basePath.ts';
+
+/** 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 function pathFromLegacyHash(
+  address: string,
+  options: LegacyHashOptions = {},
+): string | null {
+  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: string,
+  options: AdoptLegacyHashOptions = {},
+): string | null {
+  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}`;
+}

package/src/router/core/pageAddresses.ts

@@ -0,0 +1,106 @@
+import { normalizePath, splitAddress } from './address.ts';
+import { joinBasePath, normalizeBasePath, stripBasePath } from './basePath.ts';
+
+/**
+ * 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<Page extends PageWithPath>(
+  options: PageAddressesOptions<Page>,
+): PageAddresses<Page> {
+  const pages = options.pages;
+  const first = pages[0];
+  if (first === undefined) {
+    throw new Error('createPageAddresses needs at least one page');
+  }
+  const home: Page = first;
+  const basePath = normalizeBasePath(options.basePath ?? '');
+
+  const byPath = new Map<string, Page>();
+  for (const page of pages) {
+    byPath.set(normalizePath(page.path), page);
+  }
+
+  function everyPage(): readonly Page[] {
+    return pages;
+  }
+
+  function canonicalPathOf(page: Page): string {
+    return joinBasePath(basePath, normalizePath(page.path));
+  }
+
+  function pageAt(address: string): Page {
+    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 };
+}
+
+/** 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;
+}
+
+function deepestPageUnder<Page extends PageWithPath>(
+  pages: readonly Page[],
+  path: string,
+): Page | undefined {
+  let deepest: Page | undefined;
+  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;
+}

package/src/router/core/query.ts

@@ -0,0 +1,87 @@
+import { safeDecode } from './address.ts';
+
+/** 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 function parseQueryString(
+  search: string,
+  options: QueryStringOptions = {},
+): Record<string, string> {
+  const literalPlus = options.literalPlus ?? true;
+  const query: Record<string, string> = {};
+  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: Readonly<Record<string, string | undefined | null>>,
+  options: QueryStringOptions = {},
+): string {
+  const keepEmptyValues = options.keepEmptyValues ?? false;
+  const parts: string[] = [];
+  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: string): string {
+  return encodeURIComponent(value).replaceAll('%2C', ',');
+}
+
+function decodeValue(value: string, literalPlus: boolean): string {
+  return safeDecode(literalPlus ? value : value.replaceAll('+', ' '));
+}

package/src/router/core/tabRouter.ts

@@ -0,0 +1,214 @@
+import { splitAddress, splitPath } from './address.ts';
+import { joinBasePath, normalizeBasePath, stripBasePath } from './basePath.ts';
+import { pathFromLegacyHash } from './legacyHash.ts';
+import type { QueryStringOptions } from './query.ts';
+import { formatQueryString, parseQueryString } from './query.ts';
+
+/**
+ * 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<Tab extends string>(
+  options: TabRouterOptions<Tab>,
+): TabRouter<Tab> {
+  const mode = options.mode ?? 'path';
+  const basePath = normalizeBasePath(options.basePath ?? '');
+  const adoptLegacyHash = options.adoptLegacyHash ?? false;
+  const queryOptions: QueryStringOptions = {
+    literalPlus: options.literalPlus ?? true,
+    keepEmptyValues: options.keepEmptyValues ?? false,
+  };
+
+  const definitions = new Map<string, NormalizedTab>();
+  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<string, Tab>();
+  for (const [id, definition] of definitions) {
+    const segment = definition.path.slice(1);
+    if (segment !== '') tabBySegment.set(segment, id as Tab);
+  }
+
+  function isTab(value: string): value is Tab {
+    return definitions.has(value);
+  }
+
+  function parse(address: string): TabRoute<Tab> {
+    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: TabRouteInput<Tab>): string {
+    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 };
+}
+
+/** 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;
+}
+
+interface NormalizedTab {
+  path: string;
+  takesId: boolean;
+}
+
+function readAddress(
+  address: string,
+  mode: 'path' | 'hash',
+  basePath: string,
+  adoptLegacyHash: boolean,
+): { path: string; search: string } {
+  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: string): string {
+  const opened = path.startsWith('/') ? path : `/${path}`;
+  const closed = opened.replace(/\/+$/, '');
+  return closed === '' ? '/' : closed;
+}