react-cheminfo 0.14.0 → 0.15.0

package/src/about/ui/AboutBuild.tsx

@@ -0,0 +1,83 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import type { BuildInfo } from '../../build/core/buildInfo.ts';
+import { formatBuiltAt, shortCommit } from '../../build/core/buildInfo.ts';
+
+export interface AboutBuildProps {
+  /** What the build published about itself. */
+  build: BuildInfo;
+  /** Where the sources live, which is what the version and commit link into. */
+  repository: string;
+}
+
+/**
+ * The one line that says which build of the site a visitor has open.
+ *
+ * A report of something going wrong is worth answering only when we know what
+ * was running, and a visitor cannot read that off the page otherwise. The
+ * version and the commit link into the repository, so the change that caused a
+ * problem is one click from the page that shows it.
+ * @param props - See {@link AboutBuildProps}.
+ * @returns The line.
+ */
+export function AboutBuild(props: AboutBuildProps): ReactElement {
+  const { build, repository } = props;
+  const sources = repository.endsWith('/')
+    ? repository.slice(0, -1)
+    : repository;
+  const onGitHub = sources.startsWith(GITHUB);
+
+  return (
+    <p style={PARAGRAPH_STYLE}>
+      Running version{' '}
+      <Reference
+        href={
+          onGitHub ? `${sources}/releases/tag/v${build.version}` : undefined
+        }
+      >
+        {build.version}
+      </Reference>
+      , built {formatBuiltAt(build.builtAt)}
+      {build.commit === undefined ? null : (
+        <>
+          {' from commit '}
+          <Reference
+            href={onGitHub ? `${sources}/commit/${build.commit}` : undefined}
+          >
+            {shortCommit(build.commit)}
+          </Reference>
+        </>
+      )}
+      .
+    </p>
+  );
+}
+
+function Reference(props: {
+  href: string | undefined;
+  children: ReactNode;
+}): ReactElement {
+  const { href, children } = props;
+  if (href === undefined) return <code style={CODE_STYLE}>{children}</code>;
+
+  return (
+    <a href={href} target="_blank" rel="noopener noreferrer" style={LINK_STYLE}>
+      <code style={CODE_STYLE}>{children}</code>
+    </a>
+  );
+}
+
+const GITHUB = 'https://github.com/';
+
+const PARAGRAPH_STYLE = {
+  margin: '8px 0 0',
+  color: 'var(--text-muted)',
+  fontSize: 13,
+} as const satisfies CSSProperties;
+
+const CODE_STYLE = {
+  fontFamily: 'var(--font-mono, ui-monospace, monospace)',
+  fontSize: 13,
+} as const satisfies CSSProperties;
+
+const LINK_STYLE = { color: 'var(--accent)' } as const satisfies CSSProperties;

package/src/about/ui/AboutPage.tsx

@@ -6,6 +6,7 @@ import { SiteMark } from '../../ecosystem/ui/marks.tsx';
 import type { AboutContent } from '../core/about.ts';
 import { resolveAbout } from '../core/about.ts';
 
+import { AboutBuild } from './AboutBuild.tsx';
 import { AboutCitations } from './AboutCitations.tsx';
 import { AboutProvidedBy } from './AboutProvidedBy.tsx';
 import { AboutSection } from './AboutSection.tsx';
@@ -25,6 +26,13 @@ export interface AboutPageProps {
    * @default undefined
    */
   children?: ReactNode;
+  /**
+   * The site's own mark, for a site the shared glyph set does not hold —
+   * one that is deliberately not listed in `ECOSYSTEM_SITES`. It stands where
+   * `SiteMark` would, and the hero is otherwise unchanged.
+   * @default undefined — the family's mark for that site
+   */
+  mark?: ReactNode;
   /**
    * The site's own drawn lockup, for a site that has one. It stands in the
    * hero in place of the mark and the written name, above the tagline, and
@@ -48,7 +56,7 @@ export interface AboutPageProps {
  * @throws {Error} When the record names a site or a credit that does not exist.
  */
 export function AboutPage(props: AboutPageProps): ReactElement {
-  const { content, className, children, logo } = props;
+  const { content, className, children, logo, mark } = props;
   const about = resolveAbout(content);
   const site = about.site;
 
@@ -63,10 +71,12 @@ export function AboutPage(props: AboutPageProps): ReactElement {
         className="about-hero"
         style={logo === undefined ? HERO_STYLE : LOGO_HERO_STYLE}
       >
-        {logo === undefined ? <SiteMark siteId={site.id} size={56} /> : null}
+        {logo === undefined
+          ? (mark ?? <SiteMark site={site} size={56} />)
+          : null}
         <div>
           <h1 style={logo === undefined ? NAME_STYLE : LOGO_NAME_STYLE}>
-            {logo ?? <Wordmark siteId={site.id} size={26} />}
+            {logo ?? <Wordmark site={site} size={26} />}
           </h1>
           <p style={TAGLINE_STYLE}>{site.tagline}</p>
           <p style={WHAT_STYLE}>{about.what}</p>
@@ -118,10 +128,8 @@ export function AboutPage(props: AboutPageProps): ReactElement {
           piece of it into something else. The sources are at{' '}
           <ExternalLink href={about.repository} />.
         </p>
-        {about.version === undefined ? null : (
-          <p style={PARAGRAPH_STYLE}>
-            This page is running version {about.version}.
-          </p>
+        {about.build === undefined ? null : (
+          <AboutBuild build={about.build} repository={about.repository} />
         )}
       </AboutSection>
 

package/src/about/ui/index.ts

@@ -1,3 +1,5 @@
+export type { AboutBuildProps } from './AboutBuild.tsx';
+export { AboutBuild } from './AboutBuild.tsx';
 export type { AboutCitationsProps } from './AboutCitations.tsx';
 export { AboutCitations } from './AboutCitations.tsx';
 export type { AboutPageProps } from './AboutPage.tsx';

package/src/build/core/buildInfo.ts

@@ -0,0 +1,48 @@
+/**
+ * What a deployed page can say about itself: which release it is, when it was
+ * built, and from which commit.
+ *
+ * A site of ours is a link somebody handed out in a course, so the first
+ * question a report raises is *which one of these is running*. The record is
+ * filled by the build rather than written by hand — a version a human types
+ * into a source file is a version that is wrong by the next release.
+ */
+export interface BuildInfo {
+  /** The released version, from the package.json at the repository root. */
+  version: string;
+  /** When the build ran, as an ISO instant to the second: `2026-09-16T09:41:07Z`. */
+  builtAt: string;
+  /**
+   * The full commit the build was made from.
+   * @default undefined — the build could not see the repository
+   */
+  commit?: string;
+  /**
+   * The version of `react-cheminfo` the site is built against, which is what
+   * says whether a site is running the current chrome.
+   * @default undefined — the build could not read it
+   */
+  reactCheminfo?: string;
+}
+
+/**
+ * The commit as it is written for a reader.
+ * @param commit - The full hash.
+ * @returns Its first seven characters, which is what git itself shows.
+ */
+export function shortCommit(commit: string): string {
+  return commit.slice(0, SHORT_COMMIT_LENGTH);
+}
+
+/**
+ * The build instant as it is read on the page.
+ * @param builtAt - The ISO instant the build wrote.
+ * @returns The day and the time, in UTC, e.g. `2026-09-16 09:41:07 UTC`.
+ */
+export function formatBuiltAt(builtAt: string): string {
+  const seconds = builtAt.slice(0, SECOND_LENGTH).replace('T', ' ');
+  return `${seconds} UTC`;
+}
+
+const SHORT_COMMIT_LENGTH = 7;
+const SECOND_LENGTH = 19;

package/src/build/core/current.ts

@@ -0,0 +1,12 @@
+import type { BuildInfo } from './buildInfo.ts';
+
+/**
+ * Which build of the site is running, or `undefined` when nothing filled it in.
+ *
+ * The module is replaced at build time by `cheminfoBuildInfo`, which is what
+ * puts the real version, instant and commit here. It stays a real module rather
+ * than a virtual one so that a test, a Playwright spec or a backend can import
+ * the About record in plain Node: outside a build there is simply no record,
+ * and the About page leaves the line out.
+ */
+export const BUILD_INFO: BuildInfo | undefined = undefined;

package/src/build/core/index.ts

@@ -0,0 +1,2 @@
+export type { BuildInfo } from './buildInfo.ts';
+export { formatBuiltAt, shortCommit } from './buildInfo.ts';

package/src/build/vite/buildInfo.ts

@@ -0,0 +1,178 @@
+/**
+ * Tell a site which build of itself it is running.
+ *
+ * Every site of the family carries an About page, and the one thing that page
+ * cannot state from a hand-written record is the release it is serving. So the
+ * build states it: the plugin resolves the version, the day and the commit
+ * once, hands them to the page through a virtual module, and writes the same
+ * record to `build-info.json` so the whole family can be asked what it is
+ * running with one request each.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import type { Plugin } from 'vite';
+
+import type { BuildInfo } from '../core/buildInfo.ts';
+
+import { commitFromEnvironment, readGitHead } from './gitHead.ts';
+
+/** The module a site imports its build record from. */
+export const BUILD_INFO_MODULE = 'react-cheminfo/build-info';
+
+/** What the build writes about itself. */
+export interface BuildInfoOptions {
+  /**
+   * Where the record is written in the build, so a deployment can be asked
+   * what it is running. `false` writes none.
+   * @default 'build-info.json'
+   */
+  fileName?: string | false;
+}
+
+/**
+ * Resolve the build's own version, instant and commit, and publish them.
+ *
+ * The site reads them from the module the plugin fills in:
+ *
+ * ```ts
+ * import { BUILD_INFO } from 'react-cheminfo/build-info';
+ * ```
+ *
+ * That module exists on disk and exports `undefined`, so a Playwright spec or
+ * a unit test importing the same About record in plain Node still resolves it —
+ * a virtual specifier does not, and the whole suite dies on the import.
+ * @param options - See {@link BuildInfoOptions}.
+ * @returns The Vite plugin.
+ */
+export function cheminfoBuildInfo(options: BuildInfoOptions = {}): Plugin {
+  const { fileName = 'build-info.json' } = options;
+  let root = process.cwd();
+  let outDir = 'dist';
+  let info: BuildInfo = resolveBuildInfo(root);
+
+  return {
+    name: 'cheminfo-build-info',
+    // Vite's own resolver runs first and would hand back the module on disk,
+    // which exports `undefined`; and the dependency optimizer pre-bundles a
+    // bare specifier without asking a plugin at all.
+    enforce: 'pre',
+    config() {
+      return { optimizeDeps: { exclude: [BUILD_INFO_MODULE] } };
+    },
+    configResolved(config) {
+      root = config.root;
+      outDir = config.build.outDir;
+      info = resolveBuildInfo(root);
+    },
+    resolveId(id) {
+      return id === BUILD_INFO_MODULE ? RESOLVED_MODULE : undefined;
+    },
+    load(id) {
+      if (id !== RESOLVED_MODULE) return undefined;
+      return `export const BUILD_INFO = ${JSON.stringify(info)};\n`;
+    },
+    closeBundle() {
+      if (fileName === false) return;
+      const target = resolve(root, outDir, fileName);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, `${JSON.stringify(info, null, 2)}\n`);
+    },
+  };
+}
+
+/**
+ * What the build knows about itself, read off the checkout it runs in.
+ * @param root - The project Vite is building, which may sit under the
+ *   repository root as `frontend` does.
+ * @returns The record, with whatever it could not resolve left out.
+ */
+export function resolveBuildInfo(root: string): BuildInfo {
+  const repository = findRepositoryRoot(root);
+
+  return {
+    version: readVersion(repository) ?? readVersion(root) ?? UNRELEASED,
+    builtAt: buildInstant(),
+    commit: readGitHead(repository) ?? commitFromEnvironment(),
+    reactCheminfo: readOwnVersion(),
+  };
+}
+
+/**
+ * The topmost directory of the run of ancestors that all hold a `package.json`.
+ *
+ * It is the repository root, and it is where the released version lives:
+ * release-please bumps the root `package.json`, while the `frontend` workspace
+ * of a site that has one keeps the `0.0.0` it was scaffolded with.
+ * @param start - Where to start climbing.
+ * @returns The highest such directory, or `start` when it holds none itself.
+ */
+export function findRepositoryRoot(start: string): string {
+  let directory = resolve(start);
+  let highest = directory;
+
+  for (;;) {
+    if (readPackage(directory) !== undefined) highest = directory;
+    const parent = dirname(directory);
+    // The run has ended: a directory with no package.json is above the project,
+    // and so is everything above it.
+    if (parent === directory || readPackage(parent) === undefined) {
+      return highest;
+    }
+    directory = parent;
+  }
+}
+
+function readVersion(directory: string): string | undefined {
+  const version = readPackage(directory)?.version;
+  return typeof version === 'string' && version.length > 0
+    ? version
+    : undefined;
+}
+
+/**
+ * The version of this package, so a site can be asked which chrome it runs.
+ * @returns The version, or `undefined` when the manifest is out of reach.
+ */
+function readOwnVersion(): string | undefined {
+  let directory = import.meta.dirname;
+
+  for (;;) {
+    const manifest = readPackage(directory);
+    if (manifest?.name === OWN_NAME && typeof manifest.version === 'string') {
+      return manifest.version;
+    }
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+function readPackage(
+  directory: string,
+): { name?: unknown; version?: unknown } | undefined {
+  try {
+    return JSON.parse(
+      readFileSync(join(directory, 'package.json'), 'utf8'),
+    ) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * When the build ran, honouring `SOURCE_DATE_EPOCH` so a reproducible build
+ * stays reproducible.
+ * @returns The instant, to the second, as `2026-09-16T09:41:07Z`.
+ */
+function buildInstant(): string {
+  const epoch = Number(process.env.SOURCE_DATE_EPOCH);
+  const when = Number.isFinite(epoch) && epoch > 0 ? epoch * 1000 : Date.now();
+  return `${new Date(when).toISOString().slice(0, SECOND_LENGTH)}Z`;
+}
+
+const RESOLVED_MODULE = `\0${BUILD_INFO_MODULE}`;
+const OWN_NAME = 'react-cheminfo';
+const UNRELEASED = '0.0.0';
+const SECOND_LENGTH = 19;

package/src/build/vite/gitHead.ts

@@ -0,0 +1,114 @@
+/**
+ * Read the commit a build is made from, without running git.
+ *
+ * The image build cannot run git: `.dockerignore` keeps `.git` out of the
+ * context and `node:alpine` ships no git binary, while the shared
+ * `docker-image` workflow passes no build argument a commit could arrive in.
+ * What a site does instead is let three paths back into the context —
+ * `.git/HEAD`, `.git/refs` and `.git/packed-refs`, a few kilobytes — and those
+ * three are enough to resolve the hash by reading files.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+/**
+ * The commit `HEAD` names, read from the repository above a directory.
+ * @param start - Where to start looking; every ancestor is tried in turn.
+ * @returns The full hash, or `undefined` when the repository is out of reach —
+ *   which is what a build sees when the three paths were not let back in.
+ */
+export function readGitHead(start: string): string | undefined {
+  const gitDir = findGitDir(start);
+  if (gitDir === undefined) return undefined;
+
+  const head = readText(join(gitDir, 'HEAD'));
+  if (head === undefined) return undefined;
+
+  // A checkout made by `actions/checkout` is detached, so `HEAD` is the hash
+  // itself and neither `refs` nor `packed-refs` is read at all.
+  if (!head.startsWith('ref:')) return asCommit(head);
+
+  const ref = head.slice('ref:'.length).trim();
+  const loose = readText(join(gitDir, ref));
+  return (
+    asCommit(loose) ??
+    commitInPackedRefs(readText(join(gitDir, 'packed-refs')), ref)
+  );
+}
+
+/**
+ * The commit named by the environment, for a build that cannot see `.git`.
+ * @returns The hash, or `undefined` when no variable names one.
+ */
+export function commitFromEnvironment(): string | undefined {
+  return (
+    asCommit(process.env.GITHUB_SHA) ??
+    asCommit(process.env.SOURCE_COMMIT) ??
+    asCommit(process.env.GIT_COMMIT)
+  );
+}
+
+/**
+ * The `.git` directory governing a path.
+ * @param start - Where to start looking.
+ * @returns Its absolute path, or `undefined` when there is none above `start`.
+ */
+export function findGitDir(start: string): string | undefined {
+  let directory = resolve(start);
+
+  for (;;) {
+    const candidate = join(directory, '.git');
+    const text = readText(candidate);
+    // A worktree and a submodule write a file naming the real directory; a
+    // plain repository has the directory itself, which reads as `undefined`.
+    if (text?.startsWith('gitdir:')) {
+      const target = text.slice('gitdir:'.length).trim();
+      return isAbsolute(target) ? target : resolve(directory, target);
+    }
+    if (readText(join(candidate, 'HEAD')) !== undefined) return candidate;
+
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+/**
+ * The hash a packed `refs` file gives a ref.
+ * @param packed - The contents of `packed-refs`, when there is one.
+ * @param ref - The ref to look up, e.g. `refs/heads/main`.
+ * @returns The hash, or `undefined` when the file does not carry the ref.
+ */
+function commitInPackedRefs(
+  packed: string | undefined,
+  ref: string,
+): string | undefined {
+  if (packed === undefined) return undefined;
+
+  for (const line of packed.split('\n')) {
+    // `#` is the header and `^` the object a tag points at: neither is a ref.
+    if (line.startsWith('#') || line.startsWith('^')) continue;
+    const space = line.indexOf(' ');
+    if (space === -1 || line.slice(space + 1).trim() !== ref) continue;
+    return asCommit(line.slice(0, space));
+  }
+
+  return undefined;
+}
+
+function asCommit(value: string | undefined): string | undefined {
+  const text = value?.trim();
+  return text !== undefined && COMMIT.test(text) ? text : undefined;
+}
+
+function readText(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf8').trim();
+  } catch {
+    return undefined;
+  }
+}
+
+// Forty hexadecimal characters, or sixty-four in a repository on sha256.
+const COMMIT = /^[\da-f]{40}(?:[\da-f]{24})?$/;

package/src/build/vite/index.ts

@@ -0,0 +1,8 @@
+export type { BuildInfoOptions } from './buildInfo.ts';
+export {
+  BUILD_INFO_MODULE,
+  cheminfoBuildInfo,
+  findRepositoryRoot,
+  resolveBuildInfo,
+} from './buildInfo.ts';
+export { commitFromEnvironment, findGitDir, readGitHead } from './gitHead.ts';

package/src/build-info.ts

@@ -0,0 +1,2 @@
+export type { BuildInfo } from './build/core/buildInfo.ts';
+export { BUILD_INFO } from './build/core/current.ts';

package/src/core.ts

@@ -1,4 +1,5 @@
 export * from './about/core/index.ts';
+export * from './build/core/index.ts';
 export * from './chart/core/index.ts';
 export * from './citation/core/index.ts';
 export * from './clipboard/core/index.ts';

package/src/credits/core/credits.ts

@@ -194,6 +194,27 @@ export const CREDITS = [
     description: 'the dragging that arranges things into an order.',
     license: 'MIT',
   },
+  {
+    id: 'react-roi',
+    name: 'react-roi',
+    href: 'https://github.com/zakodium-oss/react-roi',
+    description: 'the box a region of an image is drawn with.',
+    license: 'MIT',
+  },
+  {
+    id: 'file-collection',
+    name: 'file-collection',
+    href: 'https://github.com/cheminfo/file-collection',
+    description: 'the reader that takes dropped files, folders and archives.',
+    license: 'MIT',
+  },
+  {
+    id: 'zip-js',
+    name: 'zip.js',
+    href: 'https://github.com/gildas-lormeau/zip.js',
+    description: 'the ZIP archives that are read and written in the browser.',
+    license: 'BSD-3-Clause',
+  },
   {
     id: 'preact-signals',
     name: 'Preact Signals',

package/src/ecosystem/ui/Wordmark.tsx

@@ -3,12 +3,22 @@ import type { CSSProperties, ReactElement } from 'react';
 import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 import { siteById } from '../core/lookup.ts';
 import { siteNameColors } from '../core/nameColors.ts';
-import type { SiteId } from '../core/sites.ts';
+import type { EcosystemSite, SiteId } from '../core/sites.ts';
 
 /** What a site's written name needs. */
 export interface WordmarkProps {
-  /** The site whose name is written. */
-  siteId: SiteId;
+  /**
+   * The site whose name is written, passed rather than named — for a site that
+   * is deliberately not one of `ECOSYSTEM_SITES`. One of `site` and `siteId` is
+   * required.
+   * @default undefined
+   */
+  site?: EcosystemSite;
+  /**
+   * The same site, named rather than passed, which is what a header knows.
+   * @default undefined
+   */
+  siteId?: SiteId;
   /**
    * Size of the name, in pixels. The weight comes from the surrounding
    * context, so the same wordmark suits a header bar and a heading.
@@ -32,12 +42,17 @@ export interface WordmarkProps {
  * its address.
  * @param props - The site, the size of the name, and extra class names.
  * @returns The name, as one inline element that never wraps mid-address.
+ * @throws {Error} When neither `site` nor `siteId` is given.
  */
 export function Wordmark(props: WordmarkProps): ReactElement {
-  const { siteId, size = 17, className } = props;
-  const site = siteById(siteId);
-  const { lead, alt, dot } = site.name;
-  const colors = siteNameColors(site);
+  const { site, siteId, size = 17, className } = props;
+  const written = site ?? (siteId === undefined ? undefined : siteById(siteId));
+  if (written === undefined) {
+    throw new Error('Wordmark needs one of its `site` and `siteId` props');
+  }
+
+  const { lead, alt, dot } = written.name;
+  const colors = siteNameColors(written);
 
   return (
     <span

package/src/vite.ts

@@ -1,2 +1,3 @@
+export * from './build/vite/index.ts';
 export * from './seo/vite/index.ts';
 export * from './slides/vite/index.ts';