react-cheminfo 0.8.0 → 0.9.0

package/lib/vite.d.ts

@@ -1,2 +1,3 @@
 export * from './seo/vite/index.ts';
+export * from './slides/vite/index.ts';
 //# sourceMappingURL=vite.d.ts.map

package/lib/vite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC"}

package/lib/vite.js

@@ -1,2 +1,3 @@
 export * from "./seo/vite/index.js";
+export * from "./slides/vite/index.js";
 //# sourceMappingURL=vite.js.map

package/lib/vite.js.map

@@ -1 +1 @@
-{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.8.0",
+  "version": "0.9.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",

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';

package/src/chrome/ui/index.ts

@@ -1,4 +1,7 @@
 export type { NavItem } from './navItem.ts';
+// A site drawing its own link needs the same reading of a click the shared nav
+// items use: a middle click or a modified one belongs to the browser.
+export { isModifiedClick } from './navItem.ts';
 export type { NavLinkProps } from './NavLink.tsx';
 export { NavLink } from './NavLink.tsx';
 export type { NavMenuButtonProps } from './NavMenuButton.tsx';

package/src/clipboard/ui/CodeBlock.tsx

@@ -19,7 +19,10 @@ const BASE_PRE_STYLE: CSSProperties = {
 
 const TONE_STYLE: Record<CodeBlockTone, CSSProperties> = {
   default: {},
-  muted: { background: '#f6f7f9', border: '1px solid #d3d8de' },
+  muted: {
+    background: 'var(--surface-sunken, #f6f7f9)',
+    border: '1px solid var(--border, #d3d8de)',
+  },
   dark: {
     background: '#1e293b',
     border: '1px solid #1e293b',

package/src/color/ui/ColorScaleLegend.tsx

@@ -127,7 +127,7 @@ const ROW_STYLE = {
 } as const satisfies CSSProperties;
 
 const LABEL_STYLE = {
-  color: 'rgb(95 107 124)',
+  color: 'var(--text-muted, rgb(95 107 124))',
   fontSize: 12,
 } as const satisfies CSSProperties;
 

package/src/core.ts

@@ -1,3 +1,4 @@
+export * from './about/core/index.ts';
 export * from './citation/core/index.ts';
 export * from './clipboard/core/index.ts';
 export * from './color/core/index.ts';
@@ -12,4 +13,8 @@ export * from './periodic/core/index.ts';
 export * from './router/core/index.ts';
 export * from './seo/core/index.ts';
 export * from './share/core/index.ts';
+// The deck format and its navigation are framework-free, so a backend can read
+// a manifest without loading React: `react-cheminfo/slides` is the player.
+export * from './slides/core/index.ts';
+export * from './tokens/core/index.ts';
 export * from './worker/core/index.ts';

package/src/credits/core/credits.ts

@@ -166,6 +166,48 @@ export const CREDITS = [
     description: 'typesets the mathematics, from LaTeX to what you read.',
     license: 'Apache-2.0',
   },
+  {
+    id: 'lexical',
+    name: 'Lexical',
+    href: 'https://lexical.dev/',
+    description: 'the editor a written page is composed and stored in.',
+    license: 'MIT',
+  },
+  {
+    id: 'katex',
+    name: 'KaTeX',
+    href: 'https://katex.org/',
+    description: 'typesets the mathematics inside a written page.',
+    license: 'MIT',
+  },
+  {
+    id: 'dnd-kit',
+    name: 'dnd kit',
+    href: 'https://dndkit.com/',
+    description: 'the dragging that arranges things into an order.',
+    license: 'MIT',
+  },
+  {
+    id: 'preact-signals',
+    name: 'Preact Signals',
+    href: 'https://preactjs.com/guide/v10/signals/',
+    description: 'the state the pages read, without a store around it.',
+    license: 'MIT',
+  },
+  {
+    id: 'fastify',
+    name: 'Fastify',
+    href: 'https://fastify.dev/',
+    description: 'the server that answers the API and serves the page.',
+    license: 'MIT',
+  },
+  {
+    id: 'sqlite',
+    name: 'SQLite',
+    href: 'https://sqlite.org/',
+    description: 'the database, one file, read through the Node built-in.',
+    license: 'Public domain',
+  },
   {
     id: 'react',
     name: 'React',

package/src/credits/ui/CreditsList.tsx

@@ -76,7 +76,7 @@ const ITEM_STYLE = {
 const NAME_STYLE = { fontWeight: 600 } as const satisfies CSSProperties;
 
 const LICENSE_STYLE = {
-  color: '#5f6b7c',
+  color: 'var(--text-muted, #5f6b7c)',
   fontSize: 11,
   margin: '0 6px',
 } as const satisfies CSSProperties;