react-cheminfo 0.7.0 → 0.9.0

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/citation/core/index.ts

@@ -21,6 +21,7 @@ export type {
   CitationStyleId,
 } from './segments.ts';
 export { CITATION_STYLES, citationSegments } from './segments.ts';
+export { TEACHING_PAPER, TEACHING_WORK } from './teachingPaper.ts';
 export type { CitedWork } from './works.ts';
 export {
   citationsFilename,

package/src/citation/core/teachingPaper.ts

@@ -0,0 +1,36 @@
+import type { Reference } from './reference.ts';
+import type { CitedWork } from './works.ts';
+
+/**
+ * The twenty years of online teaching the pedagogic sites of the family come
+ * out of: the tutorials, the exercises and the marking are the web-based tools
+ * it describes. One record holds it, so no site can name a different version
+ * of it.
+ */
+export const TEACHING_PAPER: Reference = {
+  authors: [
+    { given: 'R.', family: 'Turin' },
+    { given: 'L.', family: 'Patiny' },
+  ],
+  title:
+    'Two Decades of Online Teaching: Trends, Challenges, and Future Directions',
+  journal: 'CHIMIA',
+  journalAbbreviation: 'Chimia',
+  year: 2023,
+  volume: '77',
+  issue: '10',
+  firstPage: '683',
+  lastPage: '687',
+  doi: '10.2533/chimia.2023.683',
+  publisher: 'Swiss Chemical Society',
+};
+
+/**
+ * The teaching paper as one of the works a site that teaches asks to be cited,
+ * beside `PLATFORM_WORK` and the work the tool itself implements.
+ */
+export const TEACHING_WORK: CitedWork = {
+  reference: TEACHING_PAPER,
+  what: 'Teaching chemistry online',
+  note: 'Cite it for the exercises, which are the web-based teaching it describes.',
+};

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;

package/src/delimited/ui/DelimitedTextPanel.tsx

@@ -143,7 +143,7 @@ const CONTROLS_STYLE = {
 } as const satisfies CSSProperties;
 
 const LABEL_STYLE = {
-  color: '#5f6b7c',
+  color: 'var(--text-muted, #5f6b7c)',
   fontSize: 12,
 } as const satisfies CSSProperties;
 

package/src/ecosystem/core/sites.ts

@@ -1,5 +1,7 @@
+// tokens-ok: file — every site's two colours are declared here.
 /** The sites the menu links to, in the order they are listed. */
 export type SiteId =
+  | 'learn'
   | 'inchi'
   | 'vcl'
   | 'smiles'
@@ -70,6 +72,16 @@ export interface SiteMarkColors {
  * go with them live in `marks.tsx`.
  */
 export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
+  {
+    id: 'learn',
+    name: { lead: 'learn', alt: 'cheminfo', dot: true },
+    host: 'learn.cheminfo.org',
+    repository: 'https://github.com/cheminfo/learn.cheminfo.org',
+    tagline: 'Arrange the tools into a course and hand out its link.',
+    brand: '#0d9488',
+    brandAlt: '#b45309',
+    mark: { plate: '#0d9488', accent: '#f59e0b' },
+  },
   {
     id: 'inchi',
     name: { lead: 'inchi', alt: 'cheminfo', dot: true },

package/src/ecosystem/core/tokens.ts

@@ -1,3 +1,4 @@
+// tokens-ok: file — the block a site renders is written here.
 import { siteById } from './lookup.ts';
 import type { EcosystemSite, SiteId } from './sites.ts';
 

package/src/ecosystem/ui/EcosystemLinks.tsx

@@ -17,7 +17,7 @@ const SECTION_STYLE: CSSProperties = {
 };
 const HEADING_STYLE: CSSProperties = {
   margin: 0,
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: '0.75rem',
   fontWeight: 600,
 };
@@ -40,7 +40,7 @@ const LINK_STYLE: CSSProperties = {
 };
 const CURRENT_STYLE: CSSProperties = {
   ...LINK_STYLE,
-  color: '#8a96a3',
+  color: 'var(--text-faint, #8a96a3)',
   cursor: 'default',
 };
 

package/src/ecosystem/ui/EcosystemMenu.tsx

@@ -14,7 +14,7 @@ const PANEL_STYLE: CSSProperties = {
   gap: 8,
 };
 const HEADING_STYLE: CSSProperties = {
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: '0.75rem',
   fontWeight: 600,
 };

package/src/ecosystem/ui/SiteTile.tsx

@@ -11,7 +11,7 @@ const TILE_STYLE: CSSProperties = {
   padding: '7px 8px',
   border: '1px solid transparent',
   borderRadius: 10,
-  color: '#16202c',
+  color: 'var(--text, #16202c)',
   gap: 10,
   textDecoration: 'none',
   transition: 'background 120ms, border-color 120ms, transform 120ms',
@@ -37,7 +37,7 @@ const HERE_STYLE: CSSProperties = {
   textTransform: 'uppercase',
 };
 const TAGLINE_STYLE: CSSProperties = {
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: '0.75rem',
   lineHeight: 1.35,
 };
@@ -91,7 +91,9 @@ export function SiteTile(props: SiteTileProps): ReactElement {
         <div style={NAME_STYLE}>
           <span>
             <span style={{ color: site.brand }}>{site.name.lead}</span>
-            {site.name.dot ? <span style={{ color: '#8a96a3' }}>.</span> : null}
+            {site.name.dot ? (
+              <span style={{ color: 'var(--text-faint, #8a96a3)' }}>.</span>
+            ) : null}
             <span style={{ color: site.brandAlt }}>{site.name.alt}</span>
           </span>
           {isCurrent ? (
@@ -134,7 +136,7 @@ export function SiteTile(props: SiteTileProps): ReactElement {
 // A tile lights up in the colour of the site it opens, never in ours: the
 // pointer moving down the grid is what makes the pairs of colours read.
 function tint(site: EcosystemSite, isCurrent: boolean, lit: boolean): string {
-  if (isCurrent) return '#f5f7fa';
+  if (isCurrent) return 'var(--surface-sunken, #f5f7fa)';
   return lit ? `color-mix(in oklab, ${site.brand} 9%, white)` : 'transparent';
 }
 
@@ -143,6 +145,6 @@ function borderOf(
   isCurrent: boolean,
   lit: boolean,
 ): string {
-  if (isCurrent) return '#dfe3e8';
+  if (isCurrent) return 'var(--border, #dfe3e8)';
   return lit ? `color-mix(in oklab, ${site.brand} 32%, white)` : 'transparent';
 }

package/src/ecosystem/ui/glyphs.tsx

@@ -16,6 +16,46 @@ import type { SiteId } from '../core/sites.ts';
 
 /** Every mark, keyed by site, drawn on top of its plate. */
 export const GLYPHS: Record<SiteId, (alt: string) => ReactNode> = {
+  // Six tiles standing where the six atoms of a benzene ring stand: the
+  // arrangement of tiles is the product and the ring is the subject.
+  learn: (alt) => (
+    <g>
+      <rect x="12.85" y="4.15" width="6.3" height="6.3" rx="1.9" fill={alt} />
+      <rect
+        x="20.39"
+        y="8.5"
+        width="6.3"
+        height="6.3"
+        rx="1.9"
+        fill="#ffffff"
+      />
+      <rect
+        x="20.39"
+        y="17.2"
+        width="6.3"
+        height="6.3"
+        rx="1.9"
+        fill="#ffffff"
+      />
+      <rect
+        x="12.85"
+        y="21.55"
+        width="6.3"
+        height="6.3"
+        rx="1.9"
+        fill="#ffffff"
+      />
+      <rect
+        x="5.31"
+        y="17.2"
+        width="6.3"
+        height="6.3"
+        rx="1.9"
+        fill="#ffffff"
+      />
+      <rect x="5.31" y="8.5" width="6.3" height="6.3" rx="1.9" fill="#ffffff" />
+    </g>
+  ),
   // A hexagon with a tail: the structure, and the string it hashes into.
   inchi: (alt) => (
     <g

package/src/orbital/core/index.ts

@@ -1,5 +1,8 @@
 export type { ResolutionLimits } from './atomicGrid.ts';
-export { atomicGridResolution } from './atomicGrid.ts';
+export {
+  atomicGridResolution,
+  createAtomicOrbitalEvaluator,
+} from './atomicGrid.ts';
 export type { AtomicOrbital, AtomicOrbitalOptions } from './atomicOrbitals.ts';
 export {
   atomicOrbitalsOf,

package/src/orbital/core/realHarmonics.ts

@@ -32,8 +32,11 @@ export interface RealHarmonic {
    * @param y - Offset from the nucleus along y, ångström.
    * @param z - Offset from the nucleus along z, ångström.
    * @param radius - Length of `(x, y, z)`, passed in because the caller has
-   * already computed it for the radial part.
-   * @returns The dimensionless amplitude; 0 at the nucleus for ℓ > 0.
+   * already computed it for the radial part. Never 0: a harmonic names a
+   * direction and the nucleus has none, so every ℓ > 0 divides by it. Build
+   * `ψ` with `createAtomicOrbitalEvaluator`, which answers that one point
+   * itself rather than paying for a branch on every sample.
+   * @returns The dimensionless amplitude.
    */
   evaluate: (x: number, y: number, z: number, radius: number) => number;
 }