react-cheminfo 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "license": "MIT",
   "description": "Assembled React components shared by the cheminfo sites: a Cite button and an ecosystem menu",
   "author": "Luc Patiny",
@@ -14,18 +14,24 @@
   "exports": {
     "./core": "./lib/core.js",
     "./orbital": "./lib/orbital.js",
+    "./slides": "./lib/slides.js",
     "./structure": "./lib/structure.js",
     "./ui": "./lib/ui.js",
     "./vite": "./lib/vite.js",
     "./styles/*.css": "./styles/*.css"
   },
+  "bin": {
+    "cheminfo-check-tokens": "bin/check-tokens.mjs"
+  },
   "files": [
+    "bin",
     "lib",
     "src",
     "styles"
   ],
   "scripts": {
     "build-storybook": "storybook build",
+    "check-tokens": "node bin/check-tokens.mjs styles src",
     "check-types": "tsc --noEmit",
     "clean": "rimraf coverage lib storybook-static",
     "dev": "storybook dev -p 10815",
@@ -34,7 +40,7 @@
     "prepack": "npm run tsc",
     "prettier": "prettier --check .",
     "prettier-write": "prettier --write .",
-    "test": "npm run test-only && npm run check-types && npm run eslint && npm run prettier",
+    "test": "npm run test-only && npm run check-types && npm run check-tokens && npm run eslint && npm run prettier",
     "test-e2e": "playwright test",
     "test-e2e-ui": "playwright test --ui",
     "test-only": "vitest run --coverage",
@@ -42,7 +48,9 @@
     "tsc-build": "tsc --project tsconfig.build.json"
   },
   "dependencies": {
-    "cheminfo-font": "^1.28.0"
+    "cheminfo-font": "^1.28.0",
+    "react-markdown": "^10.1.0",
+    "rehype-raw": "^7.0.0"
   },
   "devDependencies": {
     "@blueprintjs/core": "^6.18.0",
@@ -58,6 +66,9 @@
     "eslint": "^9.39.5",
     "eslint-config-cheminfo-react": "^20.1.0",
     "eslint-config-cheminfo-typescript": "^22.1.0",
+    "ml-dataset-iris": "^1.2.1",
+    "ml-pca": "^4.1.1",
+    "ml-signal-processing": "^2.2.2",
     "molstar": "^5.11.0",
     "openchemlib": "^9.25.0",
     "prettier": "^3.9.6",
@@ -66,6 +77,7 @@
     "react-ocl": "^8.7.2",
     "react-science": "^23.0.0",
     "rimraf": "^6.1.3",
+    "spectra-processor": "^5.0.0",
     "storybook": "^10.5.8",
     "typescript": "^6.0.3",
     "vite": "^8.2.1",
@@ -73,12 +85,15 @@
   },
   "peerDependencies": {
     "@blueprintjs/core": "^6.18.0",
+    "ml-pca": "^4.1.1",
+    "ml-signal-processing": "^2.2.2",
     "molstar": "^5.11.0",
     "openchemlib": "^9.24.0",
     "react": "^18.3.1 || >=19",
     "react-dom": "^18.3.1 || >=19",
     "react-ocl": "^8.7.1",
     "react-science": "^20.6.2 || ^21.0.0 || ^22.0.0 || ^23.0.0",
+    "spectra-processor": "^5.0.0",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "repository": {
@@ -90,6 +105,12 @@
   },
   "homepage": "https://github.com/cheminfo/react-cheminfo#readme",
   "peerDependenciesMeta": {
+    "ml-pca": {
+      "optional": true
+    },
+    "ml-signal-processing": {
+      "optional": true
+    },
     "molstar": {
       "optional": true
     },
@@ -99,6 +120,9 @@
     "react-ocl": {
       "optional": true
     },
+    "spectra-processor": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }

package/src/about/core/about.ts

@@ -0,0 +1,176 @@
+import type { CitedWork } from '../../citation/core/works.ts';
+import type { CreditEntry, CreditId } from '../../credits/core/credits.ts';
+import { credits } from '../../credits/core/credits.ts';
+import { siteById } from '../../ecosystem/core/lookup.ts';
+import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
+
+/**
+ * What a site says about itself: the one page a visitor opens to find out what
+ * the tool is, what it stands on, and who to tell when it breaks.
+ *
+ * Every field is content, never markup. A site writes this record and the page
+ * is drawn from it, which is what keeps fourteen About pages in one order and
+ * one voice — the shape they were in before was fourteen hand-written pages,
+ * each crediting a different half of what it runs on.
+ */
+export interface AboutContent {
+  /** The site the page belongs to. */
+  siteId: SiteId;
+  /** One sentence: what this tool is. */
+  what: string;
+  /**
+   * At most two short paragraphs of context — what the site replaces, where
+   * its numbers come from, what it deliberately does not do.
+   * @default undefined
+   */
+  paragraphs?: readonly string[];
+  /** Three to six one-line entries: what a visitor can do here. */
+  can: readonly string[];
+  /** Ids into the shared credits registry, in display order. */
+  credits: readonly CreditId[];
+  /**
+   * Works to cite, from the citation module.
+   * @default undefined — the site asks for no citation of its own
+   */
+  cite?: readonly CitedWork[];
+  /**
+   * Licence the site itself is published under.
+   * @default 'MIT'
+   */
+  license?: string;
+  /**
+   * Where the sources live.
+   * @default the repository of the ECOSYSTEM_SITES record
+   */
+  repository?: string;
+  /**
+   * The running version, when the site knows it.
+   * @default undefined
+   */
+  version?: string;
+  /**
+   * Where a problem is reported.
+   * @default the repository's /issues
+   */
+  issues?: string;
+}
+
+/**
+ * The same record with nothing left to look up: every default filled in, and
+ * every credit id replaced by the entry it names.
+ */
+export interface ResolvedAbout {
+  /** The site's own record, which carries its name, tagline and colours. */
+  site: EcosystemSite;
+  what: string;
+  /** The context paragraphs, empty when the site writes none. */
+  paragraphs: readonly string[];
+  can: readonly string[];
+  /** The borrowed works themselves, in the order the site names them. */
+  credits: CreditEntry[];
+  /** The works to cite, empty when the site asks for none. */
+  cite: readonly CitedWork[];
+  license: string;
+  repository: string;
+  /** The running version, or `undefined` when the site does not know it. */
+  version: string | undefined;
+  issues: string;
+}
+
+/**
+ * Fill in what a site left to the family, and resolve what it named.
+ * @param content - What the site wrote about itself.
+ * @returns The record the About page is drawn from.
+ * @throws {Error} When the site is not one of the family, or when a credit id
+ *   is not in the registry: an About page that silently drops a borrowed work
+ *   credits nobody.
+ */
+export function resolveAbout(content: AboutContent): ResolvedAbout {
+  const site = siteById(content.siteId);
+  const repository = content.repository ?? site.repository;
+
+  return {
+    site,
+    what: content.what,
+    paragraphs: content.paragraphs ?? [],
+    can: content.can,
+    credits: credits(content.credits),
+    cite: content.cite ?? [],
+    license: content.license ?? DEFAULT_LICENSE,
+    repository,
+    version: content.version,
+    issues: content.issues ?? `${withoutTrailingSlash(repository)}/issues`,
+  };
+}
+
+/**
+ * What is wrong with a record before anyone reads the page it draws.
+ *
+ * Short and efficient prose is the house style, and prose is exactly what no
+ * test, lint rule or type ever checks: a `what` that runs to a paragraph and a
+ * `can` list of a dozen lines both compile. This is where that is caught, so a
+ * site can assert it in its own suite rather than discover it in review.
+ * @param content - What the site wrote about itself.
+ * @returns One line per problem, in reading order; empty when there is none.
+ */
+export function aboutProblems(content: AboutContent): string[] {
+  const problems: string[] = [];
+
+  if (content.what.length > WHAT_LIMIT) {
+    problems.push(
+      `\`what\` is ${content.what.length} characters: one sentence of at most ${WHAT_LIMIT} says what the tool is.`,
+    );
+  }
+
+  const can = content.can;
+  if (can.length < CAN_MIN || can.length > CAN_MAX) {
+    problems.push(
+      `\`can\` lists ${can.length} entries: between ${CAN_MIN} and ${CAN_MAX} is what a visitor reads before deciding to stay.`,
+    );
+  }
+  for (let index = 0; index < can.length; index++) {
+    const line = can[index] ?? '';
+    if (line.length > CAN_LINE_LIMIT) {
+      problems.push(
+        `\`can\` entry ${index + 1} is ${line.length} characters: one line of at most ${CAN_LINE_LIMIT}, not a sentence about it.`,
+      );
+    }
+  }
+
+  const paragraphs = content.paragraphs ?? [];
+  if (paragraphs.length > PARAGRAPH_MAX) {
+    problems.push(
+      `\`paragraphs\` holds ${paragraphs.length}: at most ${PARAGRAPH_MAX} short paragraphs of context, and the rest belongs in the README.`,
+    );
+  }
+  for (let index = 0; index < paragraphs.length; index++) {
+    const paragraph = paragraphs[index] ?? '';
+    if (paragraph.length > PARAGRAPH_LIMIT) {
+      problems.push(
+        `paragraph ${index + 1} is ${paragraph.length} characters: at most ${PARAGRAPH_LIMIT}, or it is documentation rather than context.`,
+      );
+    }
+  }
+
+  if (content.credits.length === 0) {
+    problems.push(
+      '`credits` is empty: every page of ours stands on borrowed work, and naming it is what the section is for.',
+    );
+  }
+
+  return problems;
+}
+
+/** What a site is published under unless it says otherwise. */
+const DEFAULT_LICENSE = 'MIT';
+
+const WHAT_LIMIT = 160;
+const CAN_MIN = 3;
+const CAN_MAX = 6;
+const CAN_LINE_LIMIT = 90;
+const PARAGRAPH_MAX = 2;
+const PARAGRAPH_LIMIT = 400;
+
+function withoutTrailingSlash(url: string): string {
+  return url.endsWith('/') ? url.slice(0, -1) : url;
+}

package/src/about/core/index.ts

@@ -0,0 +1,2 @@
+export type { AboutContent, ResolvedAbout } from './about.ts';
+export { aboutProblems, resolveAbout } from './about.ts';

package/src/about/ui/AboutCitations.tsx

@@ -0,0 +1,79 @@
+import type { CSSProperties, ReactElement } from 'react';
+
+import { DEFAULT_CITATION_STYLE } from '../../citation/core/formats.ts';
+import { doiUrl } from '../../citation/core/reference.ts';
+import type { CitedWork } from '../../citation/core/works.ts';
+import { CitationPreview } from '../../citation/ui/CitationPreview.tsx';
+
+export interface AboutCitationsProps {
+  /** The works the site asks for, in the order it names them. */
+  works: readonly CitedWork[];
+}
+
+/**
+ * What to cite, and what citing each work credits: a reader handed two
+ * references has to be told which is which before they can pick one.
+ * @param props - See {@link AboutCitationsProps}.
+ * @returns The works, each with its reference and its DOI.
+ */
+export function AboutCitations(props: AboutCitationsProps): ReactElement {
+  const { works } = props;
+
+  return (
+    <div className="about-citations" style={LIST_STYLE}>
+      {works.map((work) => (
+        <div key={work.reference.doi} className="about-citation">
+          <div style={WHAT_STYLE}>{work.what}</div>
+          {work.note === undefined ? null : (
+            <p style={NOTE_STYLE}>{work.note}</p>
+          )}
+          <div style={PLATE_STYLE}>
+            <CitationPreview
+              reference={work.reference}
+              format="text"
+              style={DEFAULT_CITATION_STYLE}
+            />
+          </div>
+          <a
+            href={doiUrl(work.reference)}
+            target="_blank"
+            rel="noopener noreferrer"
+            style={DOI_STYLE}
+          >
+            doi:{work.reference.doi}
+          </a>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+const LIST_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 14,
+} as const satisfies CSSProperties;
+
+const WHAT_STYLE = { fontWeight: 600 } as const satisfies CSSProperties;
+
+const NOTE_STYLE = {
+  margin: '2px 0 6px',
+  color: 'var(--text-muted)',
+  fontSize: 13,
+} as const satisfies CSSProperties;
+
+// The preview is set in the light ink of the tooltip it was drawn for, so it
+// is given the dark plate that ink is legible on.
+const PLATE_STYLE = {
+  padding: '8px 10px',
+  borderRadius: 'var(--radius)',
+  background: 'var(--text)',
+  overflow: 'auto',
+} as const satisfies CSSProperties;
+
+const DOI_STYLE = {
+  display: 'inline-block',
+  marginTop: 6,
+  color: 'var(--accent)',
+  fontSize: 12,
+} as const satisfies CSSProperties;

package/src/about/ui/AboutPage.tsx

@@ -0,0 +1,177 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import { CreditsList } from '../../credits/ui/CreditsList.tsx';
+import { Wordmark } from '../../ecosystem/ui/Wordmark.tsx';
+import { SiteMark } from '../../ecosystem/ui/marks.tsx';
+import type { AboutContent } from '../core/about.ts';
+import { resolveAbout } from '../core/about.ts';
+
+import { AboutCitations } from './AboutCitations.tsx';
+import { AboutSection } from './AboutSection.tsx';
+
+export interface AboutPageProps {
+  /** What the site says about itself. */
+  content: AboutContent;
+  /**
+   * Class the page carries, in addition to `about-page`.
+   * @default undefined
+   */
+  className?: string;
+  /**
+   * The one section a site adds of its own — where its numbers come from, the
+   * limitation it wants named. It lands under the context paragraphs, so the
+   * credits, the citation and the licence keep the place a reader expects.
+   * @default undefined
+   */
+  children?: ReactNode;
+}
+
+/**
+ * The About page of a site of the family: what the tool is, what a visitor can
+ * do with it, what it is built on, how to cite it, and where to report a
+ * problem — always in that order.
+ *
+ * The order is the point. A reader who has read one of our About pages knows
+ * where the credits are on the other thirteen, and a site that writes its own
+ * page is a site that will forget one of these sections.
+ * @param props - See {@link AboutPageProps}.
+ * @returns The page.
+ * @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 } = props;
+  const about = resolveAbout(content);
+  const site = about.site;
+
+  return (
+    <div
+      className={
+        className === undefined ? 'about-page' : `about-page ${className}`
+      }
+      style={PAGE_STYLE}
+    >
+      <header className="about-hero" style={HERO_STYLE}>
+        <SiteMark siteId={site.id} size={56} />
+        <div>
+          <h1 style={NAME_STYLE}>
+            <Wordmark siteId={site.id} size={26} />
+          </h1>
+          <p style={TAGLINE_STYLE}>{site.tagline}</p>
+          <p style={WHAT_STYLE}>{about.what}</p>
+        </div>
+      </header>
+
+      <AboutSection title="What you can do here" className="about-can">
+        <ul style={CAN_LIST_STYLE}>
+          {about.can.map((line) => (
+            <li key={line}>{line}</li>
+          ))}
+        </ul>
+      </AboutSection>
+
+      {about.paragraphs.length === 0 ? null : (
+        <AboutSection className="about-context">
+          {about.paragraphs.map((paragraph, index) => (
+            <p
+              key={paragraph}
+              style={index === 0 ? FIRST_PARAGRAPH_STYLE : PARAGRAPH_STYLE}
+            >
+              {paragraph}
+            </p>
+          ))}
+        </AboutSection>
+      )}
+
+      {children}
+
+      <AboutSection title="Built on" className="about-credits">
+        <CreditsList entries={about.credits} />
+      </AboutSection>
+
+      {about.cite.length === 0 ? null : (
+        <AboutSection title="How to cite" className="about-cite">
+          <AboutCitations works={about.cite} />
+        </AboutSection>
+      )}
+
+      <AboutSection title="Licence and source" className="about-licence">
+        <p style={FIRST_PARAGRAPH_STYLE}>
+          {about.license}, © cheminfo. Use it in a course, fork it, or lift a
+          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>
+        )}
+      </AboutSection>
+
+      <AboutSection title="Found a problem?" className="about-issues">
+        <p style={FIRST_PARAGRAPH_STYLE}>
+          Tell us: a report naming what you typed and what came back is the
+          fastest fix there is. <ExternalLink href={about.issues} />.
+        </p>
+      </AboutSection>
+    </div>
+  );
+}
+
+function ExternalLink(props: { href: string }): ReactElement {
+  const { href } = props;
+
+  return (
+    <a href={href} target="_blank" rel="noopener noreferrer" style={LINK_STYLE}>
+      {href.replace(/^https?:\/\//, '')}
+    </a>
+  );
+}
+
+const PAGE_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  maxWidth: 980,
+  // Centred, because the About is read on its own rather than beside a tool.
+  marginInline: 'auto',
+  gap: 10,
+} as const satisfies CSSProperties;
+
+const HERO_STYLE = {
+  display: 'flex',
+  alignItems: 'flex-start',
+  padding: 16,
+  border: '1px solid var(--border)',
+  borderRadius: 'var(--radius)',
+  background: 'var(--surface)',
+  gap: 16,
+  lineHeight: 1.55,
+} as const satisfies CSSProperties;
+
+const NAME_STYLE = {
+  margin: 0,
+  fontSize: 26,
+  fontWeight: 700,
+} as const satisfies CSSProperties;
+
+const TAGLINE_STYLE = {
+  margin: '2px 0 8px',
+  color: 'var(--text-muted)',
+  fontSize: 14,
+} as const satisfies CSSProperties;
+
+const WHAT_STYLE = { margin: 0 } as const satisfies CSSProperties;
+
+const CAN_LIST_STYLE = {
+  margin: 0,
+  paddingLeft: 20,
+} as const satisfies CSSProperties;
+
+const FIRST_PARAGRAPH_STYLE = {
+  margin: 0,
+} as const satisfies CSSProperties;
+
+const PARAGRAPH_STYLE = {
+  margin: '8px 0 0',
+} as const satisfies CSSProperties;
+
+const LINK_STYLE = { color: 'var(--accent)' } as const satisfies CSSProperties;

package/src/about/ui/AboutSection.tsx

@@ -0,0 +1,56 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+export interface AboutSectionProps {
+  /**
+   * What the section is called, written as its heading.
+   * @default undefined — the section carries no heading
+   */
+  title?: string;
+  /**
+   * Class the section carries, in addition to `about-section`.
+   * @default undefined
+   */
+  className?: string;
+  /** What the section holds. */
+  children: ReactNode;
+}
+
+/**
+ * One block of the About page: a heading and what sits under it, on the
+ * family's own surface rather than on a component library's card.
+ * @param props - See {@link AboutSectionProps}.
+ * @returns The section.
+ */
+export function AboutSection(props: AboutSectionProps): ReactElement {
+  const { title, className, children } = props;
+
+  return (
+    <section
+      className={
+        className === undefined ? 'about-section' : `about-section ${className}`
+      }
+      style={SECTION_STYLE}
+    >
+      {title === undefined ? null : <h2 style={TITLE_STYLE}>{title}</h2>}
+      {children}
+    </section>
+  );
+}
+
+const SECTION_STYLE = {
+  padding: 16,
+  border: '1px solid var(--border)',
+  borderRadius: 'var(--radius)',
+  background: 'var(--surface)',
+  // An About page is printed as often as it is read, and a section split over
+  // two pages loses the heading that says what its list is.
+  breakInside: 'avoid',
+  lineHeight: 1.55,
+} as const satisfies CSSProperties;
+
+const TITLE_STYLE = {
+  margin: '0 0 8px',
+  color: 'var(--accent)',
+  fontSize: 16,
+  fontWeight: 600,
+} as const satisfies CSSProperties;

package/src/about/ui/index.ts

@@ -0,0 +1,6 @@
+export type { AboutCitationsProps } from './AboutCitations.tsx';
+export { AboutCitations } from './AboutCitations.tsx';
+export type { AboutPageProps } from './AboutPage.tsx';
+export { AboutPage } from './AboutPage.tsx';
+export type { AboutSectionProps } from './AboutSection.tsx';
+export { AboutSection } from './AboutSection.tsx';