react-cheminfo 0.11.0 → 0.13.0

package/src/projection/ui/projectionTabInfo.ts

@@ -2,19 +2,18 @@
  * What each tab answers when the reader presses the question mark.
  *
  * The viewer is meant to be embedded in somebody else's page, so the paragraph
- * that used to stand under every figure now waits behind one glyph in the bar:
- * a reader who wants it opens it, and everybody else pays no vertical space
- * for it. Not one word of it was dropped in the move — the sentences are the
- * reason a reader who has never met a component can read the figure at all —
- * so they are built here, where what a tab claims about its own numbers can be
- * checked without rendering a chart.
+ * that explains each figure waits behind one glyph in the bar: a reader who
+ * wants it opens it, and everybody else pays no vertical space for it. It is
+ * written in full — the sentences are the reason a reader who has never met a
+ * component can read the figure at all — and built here, where what a tab
+ * claims about its own numbers can be checked without rendering a chart.
  */
 
 import { chartShare } from '../../chart/core/chartLabels.ts';
 import type { ExplainedShares } from '../core/explainedShares.ts';
+import { fillCopy } from '../core/fillCopy.ts';
 import type { LoadingProfiles } from '../core/loadingProfiles.ts';
 import type { ProjectionCopy } from '../core/projectionCopy.ts';
-import { fillCopy } from '../core/projectionCopy.ts';
 
 import { legendTitle, variablesCaption } from './projectionVariablesWords.ts';
 
@@ -88,7 +87,7 @@ export function projectionSharesInfo(
  * @param copy - The words the viewer writes.
  * @returns The sentence.
  */
-export function projectionSharesSentence(
+function projectionSharesSentence(
   shares: ExplainedShares,
   copy: ProjectionCopy,
 ): string {

package/src/projection/ui/projectionTabModels.ts

@@ -16,16 +16,19 @@ import type { ExplainedShares } from '../core/explainedShares.ts';
 import { explainedShares } from '../core/explainedShares.ts';
 import type { LoadingProfiles } from '../core/loadingProfiles.ts';
 import { loadingProfiles } from '../core/loadingProfiles.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
 import type { ProjectionOptions } from '../core/projectionOptions.ts';
 import type { ProjectionResult } from '../core/projectionResult.ts';
 import type { ProjectionSamples } from '../core/projectionSamples.ts';
 
 /** What {@link useProjectionModels} needs. */
-export interface ProjectionModelsInput {
+interface ProjectionModelsInput {
   /** What the run produced, whatever produced it. */
   result: ProjectionResult;
   /** Who the rows are, for naming the sample a panel rebuilds. */
   samples: ProjectionSamples;
+  /** The words the viewer writes, whose weight label the weights panels read. */
+  copy: ProjectionCopy;
   /** Every option, already made safe against the result. */
   options: ProjectionOptions;
   /** The selected rows, as indices into the score matrix. */
@@ -57,7 +60,8 @@ export interface ProjectionModels {
 export function useProjectionModels(
   input: ProjectionModelsInput,
 ): ProjectionModels {
-  const { result, samples, options, selected } = input;
+  const { result, samples, copy, options, selected } = input;
+  const weightLabel = copy.words.weight;
   const { loadings, axes, scores } = result;
 
   const one = selected.length === 1 ? (selected[0] ?? -1) : -1;
@@ -72,10 +76,11 @@ export function useProjectionModels(
       spread: options.spread,
       sharedScale: options.sharedScale,
       order: options.variableOrder,
+      weightLabel,
       sampleScores:
         one < 0 ? undefined : rowScores(scores, one, options.variablesCount),
     });
-  }, [loadings, axes, scores, options, one]);
+  }, [loadings, axes, scores, options, one, weightLabel]);
 
   const shares = useMemo(
     () => explainedShares(axes, { target: options.shareTarget }),

package/src/projection/ui/projectionVariablesModel.ts

@@ -7,7 +7,8 @@
  */
 
 import type { ChartSeries } from '../../chart/ui/TrackedLineChart.tsx';
-import type { ChartStickSeries } from '../../chart/ui/TrackedStickChart.tsx';
+import type { ChartStickSeries } from '../../chart/ui/stickChartModel.ts';
+import { formatTrimmed } from '../../format/core/numbers.ts';
 import type {
   LoadingProfile,
   LoadingProfiles,
@@ -30,14 +31,14 @@ export interface ProjectionVariableTrack {
   series: ReadonlyArray<{
     /** Which component, from 0. */
     axis: number;
-    /** What it is called, e.g. `PC 2`. */
+    /** What it is called, e.g. `PC2`. */
     name: string;
     /** The colour it carries on every tab. */
     color: string;
     /** Its value at this measurement, in whatever the current view draws. */
     value: number;
   }>;
-  /** The line the tab writes, e.g. `1650 cm⁻¹ · PC 2 weight +0.081`. */
+  /** The line the tab writes, e.g. `1650 cm⁻¹ · PC2 weight +0.081`. */
   readout: string;
 }
 
@@ -204,7 +205,7 @@ export function ticksOfSlots(built: LoadingProfiles | null): string[] {
  */
 export function writeValue(value: number): string {
   if (!Number.isFinite(value)) return '';
-  return String(Math.round(value * DECIMALS) / DECIMALS);
+  return formatTrimmed(value, READOUT_DECIMALS);
 }
 
 function slotLabels(
@@ -228,4 +229,4 @@ function signed(value: number, format: (value: number) => string): string {
   return `${sign}${format(Math.abs(value))}`;
 }
 
-const DECIMALS = 1000;
+const READOUT_DECIMALS = 3;

package/src/projection/ui/projectionVariablesWords.ts

@@ -9,9 +9,9 @@
  */
 
 import type { OverlayLegendEntry } from '../../overlay/ui/OverlayLegend.tsx';
+import { fillCopy } from '../core/fillCopy.ts';
 import type { LoadingProfiles } from '../core/loadingProfiles.ts';
 import type { ProjectionCopy } from '../core/projectionCopy.ts';
-import { fillCopy } from '../core/projectionCopy.ts';
 import type { VariableAxis } from '../core/variableAxis.ts';
 
 /**

package/src/projection/ui/projectionViewChoices.ts

@@ -36,23 +36,24 @@ export function projectionViewChoices(
 ): ReadonlyArray<OverlayOption<ProjectionVariablesView>> {
   const { canShowEffect, canRescale, canPickSample } = available;
   const { view } = copy.bar;
+  const { reason } = copy;
 
   return [
     {
       value: 'effect',
       label: view.effect,
-      ...whenOff(canShowEffect, NO_AVERAGE),
+      ...whenOff(canShowEffect, reason.noAverage),
     },
     { value: 'weights', label: view.weights },
     {
       value: 'rescaled',
       label: view.rescaled,
-      ...whenOff(canRescale, NO_SCALES),
+      ...whenOff(canRescale, reason.noScales),
     },
     {
       value: 'sample',
       label: view.sample,
-      ...whenOff(canPickSample, NO_SAMPLE),
+      ...whenOff(canPickSample, reason.noSample),
     },
   ];
 }
@@ -69,9 +70,3 @@ function whenOff(
 ): { disabled?: true; title?: string } {
   return available ? {} : { disabled: true, title: reason };
 }
-
-/** Why a view is greyed, written as the thing the reader would have to change. */
-const NO_AVERAGE =
-  'Only when the run reported an average sample to push along the component.';
-const NO_SCALES = 'Only when the model divided each measurement by its spread.';
-const NO_SAMPLE = 'Select exactly one sample on the map first.';

package/src/projection/ui/projectionViewerProps.ts

@@ -13,8 +13,9 @@ import type { ProjectionResult } from '../core/projectionResult.ts';
 import type { ProjectionSamples } from '../core/projectionSamples.ts';
 import type { ProjectionTab } from '../core/projectionTabs.ts';
 
-import type { ProjectionVariableTrack } from './ProjectionVariablesTab.tsx';
+import type { ProjectionViewer } from './ProjectionViewer.tsx';
 import type { ProjectionSelection } from './projectionSelection.ts';
+import type { ProjectionVariableTrack } from './projectionVariablesModel.ts';
 
 /** A sample the reader opened, and where they opened it. */
 export interface ProjectionSampleOpen {

package/src/projection/ui/projectionWordChoices.ts

@@ -0,0 +1,66 @@
+/**
+ * The settings whose choices are a few words, built from the copy.
+ *
+ * One list per setting, read by the value menu on the bar and by the control
+ * in the panel behind the cog, so the two can never offer different words for
+ * the same thing and a site overriding one word sees it in both places.
+ */
+
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type { CloudGesture } from '../../scatter3d/core/cloudGesture.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+
+/**
+ * What a plain drag does to the selection.
+ * @param copy - The words the viewer writes.
+ * @returns The three choices, in the order they are offered.
+ */
+export function projectionSelectModeChoices(
+  copy: ProjectionCopy,
+): ReadonlyArray<OverlayOption<ScatterSelectionMode>> {
+  return wordChoices(copy.choice.selectMode, SELECT_MODES);
+}
+
+/**
+ * What a plain drag over the cloud does.
+ * @param copy - The words the viewer writes.
+ * @returns The two choices, in the order they are offered.
+ */
+export function projectionCloudGestureChoices(
+  copy: ProjectionCopy,
+): ReadonlyArray<OverlayOption<CloudGesture>> {
+  return wordChoices(copy.choice.cloudGesture, CLOUD_GESTURES);
+}
+
+/**
+ * The orders the bars of a "what differs" panel can be drawn in.
+ * @param copy - The words the viewer writes.
+ * @returns The two choices, in the order they are offered.
+ */
+export function projectionVariableOrderChoices(
+  copy: ProjectionCopy,
+): ReadonlyArray<OverlayOption<ProjectionOptions['variableOrder']>> {
+  return wordChoices(copy.choice.variableOrder, VARIABLE_ORDERS);
+}
+
+function wordChoices<TValue extends string>(
+  words: Readonly<Record<TValue, string>>,
+  order: readonly TValue[],
+): Array<OverlayOption<TValue>> {
+  const choices: Array<OverlayOption<TValue>> = [];
+  for (const value of order) choices.push({ value, label: words[value] });
+  return choices;
+}
+
+const SELECT_MODES: readonly ScatterSelectionMode[] = [
+  'replace',
+  'add',
+  'remove',
+];
+const CLOUD_GESTURES: readonly CloudGesture[] = ['turn', 'select'];
+const VARIABLE_ORDERS: ReadonlyArray<ProjectionOptions['variableOrder']> = [
+  'original',
+  'strongest',
+];

package/src/projection/ui/useProjectionState.ts

@@ -3,11 +3,11 @@ import { useCallback, useMemo, useState } from 'react';
 import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
 import type { SelectionChange } from '../../scatter/ui/useScatterSelection.ts';
 import type { ProjectionOptions } from '../core/projectionOptions.ts';
-import { resolveProjectionOptions } from '../core/projectionOptions.ts';
 import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
 import { resolveProjectionGroups } from '../core/projectionSamples.ts';
 import type { ProjectionTab } from '../core/projectionTabs.ts';
 import { projectionTabs } from '../core/projectionTabs.ts';
+import { resolveProjectionOptions } from '../core/resolveProjectionOptions.ts';
 
 import type { ProjectionSelection } from './projectionSelection.ts';
 import {
@@ -25,7 +25,7 @@ import type { ProjectionViewerProps } from './projectionViewerProps.ts';
  * eleven fields, so a default documented on the component is the default the
  * hook actually applies and the two cannot drift apart.
  */
-export type ProjectionStateOptions = Pick<
+type ProjectionStateOptions = Pick<
   ProjectionViewerProps,
   | 'result'
   | 'samples'

package/src/router/core/address.ts

@@ -1,5 +1,5 @@
 /** An address cut into the three parts a router reads separately. */
-export interface AddressParts {
+interface AddressParts {
   /** Path of the address, `/` when it carries none. */
   path: string;
   /** Query string, without its leading `?`. */
@@ -47,14 +47,26 @@ export function splitPath(path: string): string[] {
 }
 
 /**
- * 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.
+ * Drop the trailing slashes, so `/about/` and `/about` are one page and an
+ * origin written `https://host/surge//` composes one address rather than one
+ * with an empty segment in it.
+ * @param value - A path or an origin.
+ * @returns It, without the trailing slashes `/` itself keeps.
  */
-export function normalizePath(path: string): string {
-  const segments = splitPath(splitAddress(path).path);
-  return segments.length === 0 ? '/' : `/${segments.join('/')}`;
+export function trimTrailingSlash(value: string): string {
+  const trimmed = value.replace(TRAILING_SLASHES, '');
+  return trimmed === '' && value !== '' ? '/' : trimmed;
+}
+
+/**
+ * An address cut at its first `?` or `#`, for a lookup or a canonical link that
+ * must not depend on the configuration a link carries.
+ * @param address - A path or an absolute address.
+ * @returns Everything before the query string and the fragment.
+ */
+export function withoutQueryOrFragment(address: string): string {
+  const cut = address.search(QUERY_OR_FRAGMENT);
+  return cut === -1 ? address : address.slice(0, cut);
 }
 
 /**
@@ -72,3 +84,7 @@ export function safeDecode(value: string): string {
     return value;
   }
 }
+
+const TRAILING_SLASHES = /\/+$/;
+
+const QUERY_OR_FRAGMENT = /[?#]/;

package/src/router/core/basePath.ts

@@ -1,3 +1,5 @@
+import { trimTrailingSlash } from './address.ts';
+
 /**
  * Where a site is mounted, read off the page rather than off the build.
  *
@@ -38,9 +40,9 @@ export function basePathOf(siteUrl: string): string {
  */
 export function normalizeBasePath(basePath: string): string {
   const trimmed = basePath.trim();
-  if (trimmed === '' || trimmed === '/') return '';
   const opened = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
-  return opened.replace(/\/+$/, '');
+  const closed = trimTrailingSlash(opened);
+  return closed === '/' ? '' : closed;
 }
 
 /**

package/src/router/core/history.ts

@@ -0,0 +1,160 @@
+/**
+ * The tab router bound to the browser: read the address on screen, write a new
+ * one through the History API, and hear every move.
+ *
+ * The router itself stays pure. Everything here reads `globalThis.location` and
+ * writes `globalThis.history`, and does nothing where neither exists, so a
+ * prerender script can import a module that uses it.
+ */
+
+import { EMBED_PARAM, HIDE_PARAM } from '../../share/core/config.ts';
+
+import type { QueryEntry } from './query.ts';
+import { formatQueryEntries } from './query.ts';
+import type { TabRoute, TabRouteInput, TabRouter } from './tabRouter.ts';
+
+/**
+ * Fired on `globalThis` after {@link writeRoute} changes the address, because
+ * neither `pushState` nor `replaceState` emits an event of its own.
+ */
+export const ROUTE_CHANGE_EVENT = 'cheminfo:routechange';
+
+/**
+ * Read the route the browser is showing.
+ *
+ * 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.
+ * @param router - The site's router.
+ * @returns The route of the address on screen, or of `/` where there is no browser.
+ */
+export function readRoute<Tab extends string>(
+  router: TabRouter<Tab>,
+): TabRoute<Tab> {
+  const address = currentAddress();
+  const adopted = router.legacyAddress(address);
+  if (adopted === null) return router.parse(address);
+  const history = browserHistory();
+  history?.replaceState(history.state, '', adopted);
+  globalThis.dispatchEvent?.(new Event(ROUTE_CHANGE_EVENT));
+  return router.parse(adopted);
+}
+
+/** How {@link writeRoute} records a move. */
+export interface WriteRouteOptions {
+  /**
+   * `push` adds a history entry, `replace` rewrites the current one, and
+   * `auto` pushes when the tab changes and replaces a move inside a tab, so
+   * back walks the tabs rather than every step a visitor clicked through.
+   * @default 'auto'
+   */
+  history?: 'push' | 'replace' | 'auto';
+  /**
+   * Query parameters carried over from the address on screen, besides `embed`
+   * and `hide`, which always are: the names a site mirrors with
+   * `syncPreferencesWithUrl`, typically `Object.keys(preferences)`.
+   * @default []
+   */
+  keep?: readonly string[];
+}
+
+/**
+ * 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.
+ * @param router - The site's router.
+ * @param route - Where to go.
+ * @param options - How the move is recorded and which parameters survive it.
+ * @returns The address written.
+ */
+export function writeRoute<Tab extends string>(
+  router: TabRouter<Tab>,
+  route: TabRouteInput<Tab>,
+  options: WriteRouteOptions = {},
+): string {
+  const current = currentAddress();
+  const address = withKeptParams(router, route, current, options.keep ?? []);
+  const location = browserLocation();
+  const history = browserHistory();
+  if (location === undefined || history === undefined) return address;
+
+  const shown =
+    router.mode === 'hash'
+      ? location.hash
+      : `${location.pathname}${location.search}`;
+  if (shown === address) return address;
+
+  const mode = options.history ?? 'auto';
+  const sameTab = router.parse(current).tab === router.parse(address).tab;
+  if (mode === 'replace' || (mode === 'auto' && sameTab)) {
+    history.replaceState(history.state, '', address);
+  } else {
+    history.pushState(null, '', address);
+  }
+  globalThis.dispatchEvent?.(new Event(ROUTE_CHANGE_EVENT));
+  return address;
+}
+
+/**
+ * Follow every move: the browser's own — back, forward, an edited address — and
+ * the app's, through {@link writeRoute}.
+ * @param router - The site's router.
+ * @param listener - Called with the route after each move.
+ * @returns The function that stops listening.
+ */
+export function subscribeToRoute<Tab extends string>(
+  router: TabRouter<Tab>,
+  listener: (route: TabRoute<Tab>) => void,
+): () => void {
+  function handleChange(): void {
+    listener(readRoute(router));
+  }
+  globalThis.addEventListener?.('popstate', handleChange);
+  globalThis.addEventListener?.(ROUTE_CHANGE_EVENT, handleChange);
+  return () => {
+    globalThis.removeEventListener?.('popstate', handleChange);
+    globalThis.removeEventListener?.(ROUTE_CHANGE_EVENT, handleChange);
+  };
+}
+
+/**
+ * The address on screen: path, query string and fragment.
+ * @returns It, or `/` where there is no browser.
+ */
+export function currentAddress(): string {
+  const location = browserLocation();
+  if (location === undefined) return '/';
+  return `${location.pathname}${location.search}${location.hash}`;
+}
+
+function withKeptParams<Tab extends string>(
+  router: TabRouter<Tab>,
+  route: TabRouteInput<Tab>,
+  current: string,
+  keep: readonly string[],
+): string {
+  const target = router.format(route);
+  const named = route.params ?? {};
+  const shown = router.parse(current).params;
+  const kept: QueryEntry[] = [];
+  for (const key of new Set([EMBED_PARAM, HIDE_PARAM, ...keep])) {
+    if (Object.hasOwn(named, key)) continue;
+    const value = shown[key];
+    if (value !== undefined) kept.push([key, value]);
+  }
+  if (kept.length === 0) return target;
+  const separator = target.includes('?') ? '&' : '?';
+  return `${target}${separator}${formatQueryEntries(kept)}`;
+}
+
+function browserLocation(): Location | undefined {
+  return globalThis.location;
+}
+
+function browserHistory(): History | undefined {
+  return globalThis.history;
+}

package/src/router/core/index.ts

@@ -1,3 +1,4 @@
+export { trimTrailingSlash } from './address.ts';
 export {
   basePathOf,
   joinBasePath,
@@ -5,17 +6,28 @@ export {
   readMountPath,
   stripBasePath,
 } from './basePath.ts';
+export type { WriteRouteOptions } from './history.ts';
+export {
+  ROUTE_CHANGE_EVENT,
+  readRoute,
+  subscribeToRoute,
+  writeRoute,
+} from './history.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 { 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,