react-cheminfo 0.4.1 → 0.6.0

package/src/orbital/ui/AtomicOrbitalViewer.tsx

@@ -56,6 +56,11 @@ export interface AtomicOrbitalViewerProps {
    * @default false
    */
   spinning?: boolean;
+  /**
+   * How fast it turns, in molstar's own spin unit. Lower is slower.
+   * @default 0.3
+   */
+  spinSpeed?: number;
   /**
    * How the field is produced. Supply a worker-backed sampler to keep the main
    * thread free; the default runs in process.

package/src/orbital/ui/axesGeometry.ts

@@ -0,0 +1,91 @@
+/**
+ * The geometry of the cartesian frame: three rods through the origin and the
+ * three letters that name them.
+ *
+ * It is arithmetic over positions, which is why it is here rather than in
+ * `renderAxes.ts` — that module is about representations, exactly as
+ * `volumeField.ts` is to `renderVolume.ts`.
+ */
+
+import { addCylinder } from 'molstar/lib/mol-geo/geometry/mesh/builder/cylinder.js';
+import { MeshBuilder } from 'molstar/lib/mol-geo/geometry/mesh/mesh-builder.js';
+import type { Mesh } from 'molstar/lib/mol-geo/geometry/mesh/mesh.js';
+import { TextBuilder } from 'molstar/lib/mol-geo/geometry/text/text-builder.js';
+import type { Text } from 'molstar/lib/mol-geo/geometry/text/text.js';
+import { Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+
+/** How far a rod, and a label, sit from the origin as fractions of the reach. */
+export const ROD_LENGTH = 1.06;
+export const LABEL_SIZE = 0.1;
+
+/** Rod radius, as a fraction of the reach. */
+const ROD_RADIUS = 0.006;
+
+/** Arrowhead length as a fraction of the rod's half-length. */
+const HEAD_LENGTH = 0.06;
+
+/** Arrowhead radius as a multiple of the rod's. */
+const HEAD_FLARE = 4;
+
+/** x, y and z, in the order their labels are given in. */
+const AXIS_DIRECTIONS = [
+  Vec3.create(1, 0, 0),
+  Vec3.create(0, 1, 0),
+  Vec3.create(0, 0, 1),
+] as const;
+
+/**
+ * Three rods through the origin, each with an arrowhead on its positive end.
+ * @param reach - How far the orbital reaches, in scene units.
+ * @returns The mesh, one group per axis.
+ */
+export function buildAxisRods(reach: number): Mesh {
+  const state = MeshBuilder.createState(1024, 512);
+  const length = reach * ROD_LENGTH;
+  const radius = reach * ROD_RADIUS;
+  const head = length * HEAD_LENGTH;
+  for (const [axis, direction] of AXIS_DIRECTIONS.entries()) {
+    state.currentGroup = axis;
+    const start = Vec3.scale(Vec3.zero(), direction, -length);
+    const neck = Vec3.scale(Vec3.zero(), direction, length - head);
+    const tip = Vec3.scale(Vec3.zero(), direction, length);
+    addCylinder(state, start, neck, 1, {
+      radiusTop: radius,
+      radiusBottom: radius,
+      topCap: true,
+      bottomCap: true,
+      radialSegments: 12,
+    });
+    addCylinder(state, neck, tip, 1, {
+      radiusTop: 0,
+      radiusBottom: radius * HEAD_FLARE,
+      topCap: true,
+      bottomCap: true,
+      radialSegments: 16,
+    });
+  }
+  return MeshBuilder.getMesh(state);
+}
+
+/**
+ * One label just beyond each arrowhead.
+ * @param at - Distance from the origin the labels sit at, in scene units.
+ * @param labels - What the axes are called, in x, y, z order.
+ * @returns The text geometry, one group per axis.
+ */
+export function buildAxisLabels(at: number, labels: readonly string[]): Text {
+  const builder = TextBuilder.create({}, 3, 3);
+  for (const [axis, direction] of AXIS_DIRECTIONS.entries()) {
+    const position = Vec3.scale(Vec3.zero(), direction, at);
+    builder.add(
+      labels[axis] ?? '',
+      position[0] as number,
+      position[1] as number,
+      position[2] as number,
+      0,
+      1,
+      axis,
+    );
+  }
+  return builder.getText();
+}

package/src/orbital/ui/camera.ts

@@ -10,6 +10,14 @@ import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
 /** Transition length used when the caller does not pick one, milliseconds. */
 export const DEFAULT_CAMERA_DURATION = 250;
 
+/**
+ * Turn rate used when the caller does not pick one, in molstar's own spin unit.
+ *
+ * A lobe has to stay in one place long enough to be read; molstar's own 1 turns
+ * an orbital fast enough that the phases blur into each other.
+ */
+export const DEFAULT_SPIN_SPEED = 0.3;
+
 /**
  * Fraction of the bounding sphere kept as breathing room around the orbital.
  *
@@ -113,7 +121,7 @@ export function frameOrbital(
 export function setSpin(
   plugin: PluginContext,
   spinning: boolean,
-  speed = 1,
+  speed = DEFAULT_SPIN_SPEED,
 ): void {
   plugin.canvas3d?.setProps({
     trackball: {

package/src/orbital/ui/renderAxes.ts

@@ -0,0 +1,190 @@
+/**
+ * The cartesian frame an atomic orbital is read against.
+ *
+ * A `3d_xz` is only `3d_xz` because of where its lobes sit relative to x and
+ * z, and a lone isosurface on a blank canvas says nothing about that: the
+ * student is looking at four identical lobes and has to take the label's word
+ * for it. Three labelled axes through the nucleus are what turn the picture
+ * back into the diagram their textbook draws.
+ *
+ * The axes are neutral grey on purpose. The phase palette already owns colour
+ * here — blue against red, or blue against amber — so the usual red/green/blue
+ * axis convention would compete with the one thing the surface is saying, and
+ * the labels tell the three apart anyway.
+ *
+ * Like the isosurfaces, the representations live outside the state tree and
+ * are tracked per plugin.
+ */
+
+import { Mesh } from 'molstar/lib/mol-geo/geometry/mesh/mesh.js';
+import { Text } from 'molstar/lib/mol-geo/geometry/text/text.js';
+import { Shape } from 'molstar/lib/mol-model/shape.js';
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+import type { Representation } from 'molstar/lib/mol-repr/representation.js';
+// Lowercased on import: it is a factory, not a constructor.
+import { ShapeRepresentation as shapeRepresentation } from 'molstar/lib/mol-repr/shape/representation.js';
+import { Color } from 'molstar/lib/mol-util/color/color.js';
+
+import {
+  LABEL_SIZE,
+  ROD_LENGTH,
+  buildAxisLabels,
+  buildAxisRods,
+} from './axesGeometry.ts';
+
+/** How the cartesian frame is drawn. */
+export interface AxesStyle {
+  /**
+   * Colour of the three rods, as `#rrggbb`.
+   * @default '#64748b'
+   */
+  colour?: string;
+  /**
+   * Colour of the three labels, as `#rrggbb`.
+   * @default '#334155'
+   */
+  labelColour?: string;
+  /**
+   * What the axes are called, in x, y, z order.
+   * @default ['x', 'y', 'z']
+   */
+  labels?: readonly [string, string, string];
+}
+
+/**
+ * Draw a labelled x, y, z frame through the origin, replacing any previous one.
+ * @param plugin - The molstar context.
+ * @param reach - How far the orbital reaches, in scene units — what
+ * `renderSampledVolume` returned.
+ * @param style - See {@link AxesStyle}.
+ * @returns How far the frame reaches, labels included, in scene units: what a
+ * camera has to frame for the whole of it to be on screen.
+ * @throws {Error} When the canvas is not ready.
+ */
+export async function renderOrbitalAxes(
+  plugin: PluginContext,
+  reach: number,
+  style: AxesStyle = {},
+): Promise<number> {
+  const canvas3d = plugin.canvas3d;
+  if (canvas3d === undefined) {
+    throw new Error('renderOrbitalAxes: the molstar canvas is not ready.');
+  }
+  const {
+    colour = '#64748b',
+    labelColour = '#334155',
+    labels = ['x', 'y', 'z'],
+  } = style;
+  clearOrbitalAxes(plugin);
+  if (reach <= 0) return 0;
+
+  const labelSize = reach * LABEL_SIZE;
+  const labelAt = reach * ROD_LENGTH + labelSize;
+  const drawn = await Promise.all([
+    createRods(plugin, buildAxisRods(reach), colour),
+    createLabels(
+      plugin,
+      buildAxisLabels(labelAt, labels),
+      labelColour,
+      labelSize,
+    ),
+  ]);
+  representations.set(plugin, drawn);
+  for (const representation of drawn) canvas3d.add(representation);
+  // add() only queues; nothing appears until the queue is committed.
+  canvas3d.commit();
+  return labelAt + labelSize / 2;
+}
+
+/**
+ * Remove the frame, leaving anything else on the canvas.
+ * @param plugin - The molstar context.
+ */
+export function clearOrbitalAxes(plugin: PluginContext): void {
+  const previous = representations.get(plugin);
+  if (previous === undefined) return;
+  representations.delete(plugin);
+  for (const representation of previous) {
+    plugin.canvas3d?.remove(representation);
+  }
+  plugin.canvas3d?.commit();
+}
+
+/**
+ * The rods, as a representation the canvas can hold.
+ * @param plugin - The molstar context.
+ * @param mesh - The rod mesh.
+ * @param colour - Rod colour, as `#rrggbb`.
+ * @returns The representation.
+ */
+async function createRods(
+  plugin: PluginContext,
+  mesh: Mesh,
+  colour: string,
+): Promise<Representation.Any> {
+  const value = Color.fromHexStyle(colour);
+  const representation = shapeRepresentation(
+    (_ctx, data: Mesh) =>
+      Shape.create(
+        'orbital axes',
+        {},
+        data,
+        () => value,
+        () => 1,
+        () => 'axis',
+      ),
+    Mesh.Utils,
+  );
+  await plugin.runTask(
+    // Unlit: a shaded rod reads as a cylinder in front of the surface, while a
+    // flat one reads as the axis line a textbook draws.
+    representation.createOrUpdate({ alpha: 1, ignoreLight: true }, mesh),
+  );
+  representation.setState({ pickable: false });
+  return representation;
+}
+
+/**
+ * The labels, as a representation the canvas can hold.
+ * @param plugin - The molstar context.
+ * @param text - The label geometry.
+ * @param colour - Label colour, as `#rrggbb`.
+ * @param size - Label height, in scene units.
+ * @returns The representation.
+ */
+async function createLabels(
+  plugin: PluginContext,
+  text: Text,
+  colour: string,
+  size: number,
+): Promise<Representation.Any> {
+  const value = Color.fromHexStyle(colour);
+  const representation = shapeRepresentation(
+    (_ctx, data: Text) =>
+      Shape.create(
+        'orbital axis labels',
+        {},
+        data,
+        () => value,
+        () => 1,
+        () => 'axis label',
+      ),
+    Text.Utils,
+  );
+  await plugin.runTask(
+    representation.createOrUpdate(
+      {
+        sizeFactor: size,
+        background: false,
+        attachment: 'middle-center',
+        fontWeight: 'bold',
+      },
+      text,
+    ),
+  );
+  representation.setState({ pickable: false });
+  return representation;
+}
+
+/** One frame per plugin, outside the state tree like the isosurfaces. */
+const representations = new WeakMap<PluginContext, Representation.Any[]>();

package/src/orbital/ui/viewer.ts

@@ -22,7 +22,14 @@ import { Color } from 'molstar/lib/mol-util/color/color.js';
 import type { OrbitalGrid } from '../core/grid.ts';
 import type { OrbitalContour } from '../core/isovalue.ts';
 
-import { DEFAULT_CAMERA_DURATION, frameOrbital, setSpin } from './camera.ts';
+import {
+  DEFAULT_CAMERA_DURATION,
+  DEFAULT_SPIN_SPEED,
+  frameOrbital,
+  setSpin,
+} from './camera.ts';
+import type { AxesStyle } from './renderAxes.ts';
+import { clearOrbitalAxes, renderOrbitalAxes } from './renderAxes.ts';
 import type { VolumeStyle } from './renderVolume.ts';
 import { clearSampledVolume, renderSampledVolume } from './renderVolume.ts';
 
@@ -105,6 +112,29 @@ export class OrbitalViewer {
     );
   }
 
+  /**
+   * Draw the labelled x, y, z frame through the origin, replacing any previous
+   * one.
+   * @param reach - How far the orbital reaches, in scene units, as
+   * `showOrbital` returned it.
+   * @param style - See {@link AxesStyle}.
+   * @returns How far the frame reaches, labels included, for the camera to
+   * frame; `undefined` once the viewer has been disposed.
+   */
+  showAxes(reach: number, style?: AxesStyle): Promise<number | undefined> {
+    return this.#run((plugin) => renderOrbitalAxes(plugin, reach, style));
+  }
+
+  /**
+   * Remove the frame.
+   * @returns Nothing, once the axes are gone.
+   */
+  hideAxes(): Promise<void> {
+    return this.#run((plugin) => {
+      clearOrbitalAxes(plugin);
+    });
+  }
+
   /**
    * Remove the isosurface pair.
    * @returns Nothing, once the surfaces are gone.
@@ -138,7 +168,7 @@ export class OrbitalViewer {
    * @param speed - molstar's own spin unit.
    * @returns Nothing, once the spin has been switched.
    */
-  setSpin(spinning: boolean, speed = 1): Promise<void> {
+  setSpin(spinning: boolean, speed = DEFAULT_SPIN_SPEED): Promise<void> {
     return this.#run((plugin) => {
       setSpin(plugin, spinning, speed);
     });

package/src/seo/core/documentMeta.ts

@@ -10,9 +10,9 @@
  */
 export function writeDocumentMeta(meta: DocumentMeta): void {
   if (typeof document === 'undefined') return;
-  documentTitle(meta.title);
-  if (meta.description !== undefined) metaDescription(meta.description);
-  if (meta.canonical !== undefined) canonicalLink(meta.canonical);
+  if (meta.title) documentTitle(meta.title);
+  if (meta.description) metaDescription(meta.description);
+  if (meta.canonical) canonicalLink(meta.canonical);
 }
 
 /**
@@ -58,8 +58,8 @@ export interface DocumentMeta {
   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.
+   * Left out or empty, 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;

package/src/seo/core/index.ts

@@ -4,23 +4,30 @@ export {
   documentTitle,
   writeDocumentMeta,
 } from './documentMeta.ts';
+export type {
+  NoscriptEcosystem,
+  NoscriptHrefs,
+  NoscriptOptions,
+  NoscriptRoute,
+  NoscriptText,
+} from './noscript.ts';
+export { noscriptIndex } from './noscript.ts';
 export type { PageMetaOptions } from './pageMeta.ts';
-export {
-  injectPageMeta,
-  insertBeforeHeadEnd,
-  pageDocumentMeta,
-} from './pageMeta.ts';
+export { injectPageMeta, pageDocumentMeta, pageHeadTags } from './pageMeta.ts';
+export type { RobotsDisallow } from './robots.ts';
+export { robotsTxt } from './robots.ts';
 export type { RouteMeta } from './routes.ts';
 export {
+  assertRoutes,
   homeRoute,
   pageMetaFor,
   routeFor,
   trimTrailingSlash,
 } from './routes.ts';
-export type { SiteFilesOptions, StructuredDataOptions } from './siteFiles.ts';
-export {
-  noscriptIndex,
-  robotsTxt,
-  sitemapXml,
-  structuredDataScript,
-} from './siteFiles.ts';
+export type { SiteFilesOptions } from './siteFiles.ts';
+export { sitemapXml } from './siteFiles.ts';
+export type { StartDocumentMetaOptions } from './startDocumentMeta.ts';
+export { startDocumentMeta } from './startDocumentMeta.ts';
+export type { StructuredDataOptions } from './structuredData.ts';
+export { structuredDataScript } from './structuredData.ts';
+export { PAGE_BODY_MARKER, PAGE_HEAD_MARKER, fill } from './template.ts';

package/src/seo/core/noscript.ts

@@ -0,0 +1,195 @@
+/**
+ * A readable page for a visitor, or a crawler, with no JavaScript.
+ *
+ * The body of our sites is an empty root element, so this is the only crawl
+ * path through them that costs nothing to render — and it is honest: it says
+ * the tool needs JavaScript, and links the addresses it answers.
+ */
+
+import { siteById, siteDisplayName } from '../../ecosystem/core/lookup.ts';
+import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
+import { ECOSYSTEM_SITES, siteUrl } from '../../ecosystem/core/sites.ts';
+import { joinBasePath } from '../../router/core/basePath.ts';
+import { escapeAttribute, escapeText } from '../../share/core/escape.ts';
+
+import type { RouteMeta } from './routes.ts';
+import type { SiteFilesOptions } from './siteFiles.ts';
+import { mountPathOf, resolveSite } from './siteFiles.ts';
+
+/** How the addresses of the site's own pages are written. */
+export type NoscriptHrefs = 'absolute' | 'relative';
+
+/** A page the block links, and the pages listed under it. */
+export interface NoscriptRoute extends RouteMeta {
+  /**
+   * Pages listed under this one, as a list nested in its item — the sections of
+   * an exercise set under the set itself.
+   * @default undefined — the item carries no list
+   */
+  children?: readonly NoscriptRoute[];
+}
+
+/** Which of the family's other sites are listed, and how. */
+export interface NoscriptEcosystem {
+  /**
+   * The sites listed, in the order they are named. The site writing the block
+   * is never one of them, whether or not it is named: the list is headed *Our
+   * other tools*.
+   * @default every other site in the family, in the family's own order
+   */
+  sites?: readonly SiteId[];
+  /**
+   * Whether each host is followed by ` — ` and the site's one-line tagline.
+   * @default true
+   */
+  taglines?: boolean;
+}
+
+/** The prose of the block, where the site says more than its record does. */
+export interface NoscriptText {
+  /**
+   * The heading the block opens with.
+   * @default the site's display name
+   */
+  heading?: string;
+  /**
+   * The paragraph under it, taken as written. It is the one place a reader with
+   * no JavaScript is told what the tool is, so it may say more than the tagline
+   * — but it still has to say that the tool needs JavaScript.
+   * @default the tagline, followed by the sentence naming the requirement
+   */
+  intro?: string;
+  /**
+   * Whether the family's other sites are listed under the site's own pages, and
+   * which of them. A crawler that runs no script has no other path from one of
+   * our tools to the next, so a site that lists none leaves it with none.
+   * `true` lists every other site with its tagline; an object names the sites,
+   * or drops the taglines, or both.
+   * @default false
+   */
+  ecosystem?: boolean | NoscriptEcosystem;
+  /**
+   * How the site's own addresses are written. `'absolute'` writes them from the
+   * root of the host, under the mount the origin names. `'relative'` writes
+   * `./exercises` and `./`, which the page resolves against its own `<base>` —
+   * the only shape that works for an image whose mount is chosen at container
+   * startup, because it bakes no mount into the build at all. The `<base>` such
+   * a deployment stamps in ends with a slash, or a relative address resolves
+   * one directory too high.
+   * @default 'absolute'
+   */
+  hrefs?: NoscriptHrefs;
+  /**
+   * The pages the block links, when they are not the site's whole route table.
+   * A crawl path is a menu: a site whose table carries an entry per tutorial
+   * step lists the tutorial, not its hundred and thirty-seven steps.
+   * @default every route the site answers
+   */
+  routes?: readonly NoscriptRoute[];
+}
+
+/** What the block says, and which addresses it links. */
+export interface NoscriptOptions
+  extends Omit<SiteFilesOptions, 'routes'>, Omit<NoscriptText, 'routes'> {
+  /** The addresses it links, each with the label it is linked under. */
+  routes: readonly NoscriptRoute[];
+}
+
+/**
+ * The `noscript` block, ready to put in the body.
+ *
+ * An absolute address is written under the mount the deployment named, so a
+ * build published as one tool among several on a shared host links its own
+ * pages rather than the root of the host it shares.
+ * @param options - The site, the pages it links, and the prose that opens the
+ * block.
+ * @returns The block.
+ * @throws {Error} When the deployment named an origin that is not an absolute
+ * address.
+ */
+export function noscriptIndex(options: NoscriptOptions): string {
+  const site = resolveSite(options.site);
+  const hrefs = options.hrefs ?? 'absolute';
+  const mount = hrefs === 'absolute' ? mountPathOf(options) : '';
+  const heading = escapeText(options.heading ?? siteDisplayName(site));
+  const intro = escapeText(
+    options.intro ??
+      `${site.tagline} This tool needs JavaScript; these are the pages it offers:`,
+  );
+
+  return `<noscript>
+  <h1>${heading}</h1>
+  <p>${intro}</p>${pageList(options.routes, mount, hrefs, '  ')}${familyList(site.id, options.ecosystem)}
+</noscript>`;
+}
+
+function pageList(
+  routes: readonly NoscriptRoute[],
+  mount: string,
+  hrefs: NoscriptHrefs,
+  indent: string,
+): string {
+  // A list with no item is not a list: `<ul>` holds at least one `<li>`.
+  if (routes.length === 0) return '';
+  const items = routes
+    .map((route) => pageItem(route, mount, hrefs, `${indent}  `))
+    .join('\n');
+  return `\n${indent}<ul>\n${items}\n${indent}</ul>`;
+}
+
+function pageItem(
+  route: NoscriptRoute,
+  mount: string,
+  hrefs: NoscriptHrefs,
+  indent: string,
+): string {
+  const href = escapeAttribute(pageHref(route.path, mount, hrefs));
+  const label = escapeText(labelOf(route));
+  const note =
+    route.note === undefined || route.note.trim() === ''
+      ? ''
+      : ` — ${escapeText(route.note)}`;
+  const children = route.children ?? [];
+  const link = `<a href="${href}">${label}</a>${note}`;
+  if (children.length === 0) return `${indent}<li>${link}</li>`;
+  return `${indent}<li>${link}${pageList(children, mount, hrefs, `${indent}  `)}
+${indent}</li>`;
+}
+
+function pageHref(path: string, mount: string, hrefs: NoscriptHrefs): string {
+  if (hrefs === 'absolute') return joinBasePath(mount, path);
+  return `./${path.startsWith('/') ? path.slice(1) : path}`;
+}
+
+function labelOf(route: NoscriptRoute): string {
+  const short = route.short;
+  return short !== undefined && short.trim() !== '' ? short : route.title;
+}
+
+function familyList(
+  current: SiteId,
+  ecosystem: boolean | NoscriptEcosystem | undefined,
+): string {
+  if (ecosystem === undefined || ecosystem === false) return '';
+  const listed = ecosystem === true ? {} : ecosystem;
+  const taglines = listed.taglines ?? true;
+  const items: string[] = [];
+  for (const site of familySites(listed.sites)) {
+    if (site.id === current) continue;
+    const tagline = taglines ? ` — ${escapeText(site.tagline)}` : '';
+    items.push(
+      `    <li><a href="${escapeAttribute(siteUrl(site))}">${escapeText(site.host)}</a>${tagline}</li>`,
+    );
+  }
+  if (items.length === 0) return '';
+  return `
+  <h2>Our other tools</h2>
+  <ul>
+${items.join('\n')}
+  </ul>`;
+}
+
+function familySites(sites: readonly SiteId[] | undefined): EcosystemSite[] {
+  if (sites === undefined) return [...ECOSYSTEM_SITES];
+  return sites.map((id) => siteById(id));
+}