react-cheminfo 0.8.0 → 0.9.0

package/src/slides/ui/TalkList.tsx

@@ -0,0 +1,146 @@
+import type { ReactElement } from 'react';
+
+import { isModifiedClick } from '../../chrome/ui/navItem.ts';
+import { pluralize } from '../../format/core/index.ts';
+import type { TalkManifest, TalkSummary } from '../core/index.ts';
+
+/** The talks to list, and what opening one means. */
+export interface TalkListProps {
+  /** One manifest per publishing site. */
+  manifests: readonly TalkManifest[];
+  /** Called when a talk is picked. */
+  onOpen: (manifest: TalkManifest, talk: TalkSummary) => void;
+  /**
+   * The address a talk sits at, which keeps the card a real link — a middle
+   * click opens a tab of its own, and a crawler walks the list.
+   * @default undefined — the card is a link with no address
+   */
+  renderHref?: (manifest: TalkManifest, talk: TalkSummary) => string;
+  /**
+   * How a site id is written above its talks.
+   * @default the id itself
+   */
+  siteName?: (site: string) => string;
+  /**
+   * What an empty list says. A list that draws nothing at all reads as a
+   * broken page rather than as a site that has published no deck yet.
+   * @default 'No talk yet.'
+   */
+  emptyNote?: string;
+}
+
+/**
+ * The talks on offer: a site's own, or the whole family's.
+ *
+ * The site heading appears only once there is more than one site to tell
+ * apart, so the same component draws a single site's `/talks` page and the
+ * family-wide listing without either looking like the other one's leftovers.
+ * @param props - See {@link TalkListProps}.
+ * @returns The listing.
+ */
+export function TalkList(props: TalkListProps): ReactElement {
+  const {
+    manifests,
+    onOpen,
+    renderHref,
+    siteName,
+    emptyNote = 'No talk yet.',
+  } = props;
+  const groups = groupBySite(manifests);
+  const showSite = groups.length > 1;
+
+  if (groups.length === 0) {
+    return <p className="talk-list-empty">{emptyNote}</p>;
+  }
+
+  return (
+    <div className="talk-list">
+      {groups.map((group) => (
+        <section key={group.site} className="talk-list-group">
+          {showSite ? (
+            <h2 className="talk-list-site">
+              {siteName === undefined ? group.site : siteName(group.site)}
+            </h2>
+          ) : null}
+          <div className="talk-grid">
+            {group.entries.map(({ manifest, talk }) => (
+              <a
+                key={`${manifest.site}:${talk.id}`}
+                className="talk-card"
+                href={renderHref?.(manifest, talk)}
+                onClick={(event) => {
+                  if (isModifiedClick(event)) return;
+                  event.preventDefault();
+                  onOpen(manifest, talk);
+                }}
+              >
+                <div className="talk-card-title">{talk.title}</div>
+                {talk.subtitle === undefined ? null : (
+                  <div className="talk-card-subtitle">{talk.subtitle}</div>
+                )}
+                <div className="talk-card-meta">{occasion(talk)}</div>
+                <div className="talk-card-count">
+                  {`${talk.slideCount} ${pluralize(talk.slideCount, 'slide')}`}
+                </div>
+              </a>
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  );
+}
+
+/** One talk, together with the manifest that published it. */
+interface TalkEntry {
+  /** The manifest the talk was listed in. */
+  manifest: TalkManifest;
+  /** The talk itself. */
+  talk: TalkSummary;
+}
+
+/** Every talk one site published, most recent first. */
+interface TalkGroup {
+  /** The `ECOSYSTEM_SITES` id of the publishing site. */
+  site: string;
+  /** Its talks. */
+  entries: TalkEntry[];
+}
+
+function groupBySite(manifests: readonly TalkManifest[]): TalkGroup[] {
+  const bySite = new Map<string, TalkEntry[]>();
+  for (const manifest of manifests) {
+    let entries = bySite.get(manifest.site);
+    if (entries === undefined) {
+      entries = [];
+      bySite.set(manifest.site, entries);
+    }
+    for (const talk of manifest.talks) entries.push({ manifest, talk });
+  }
+
+  const groups: TalkGroup[] = [];
+  for (const [site, entries] of bySite) {
+    // A site that has published nothing is not a heading over an empty row.
+    if (entries.length === 0) continue;
+    groups.push({ site, entries: entries.toSorted(byMostRecent) });
+  }
+  return groups;
+}
+
+// The dates are ISO, so they order as text; a talk with no date sorts last
+// rather than ahead of every dated one.
+function byMostRecent(left: TalkEntry, right: TalkEntry): number {
+  const before = left.talk.date ?? '';
+  const after = right.talk.date ?? '';
+  if (before === after) return 0;
+  if (before === '') return 1;
+  if (after === '') return -1;
+  return before > after ? -1 : 1;
+}
+
+function occasion(talk: TalkSummary): string {
+  const parts: string[] = [];
+  if (talk.event !== undefined) parts.push(talk.event);
+  if (talk.date !== undefined) parts.push(talk.date);
+  return parts.join(' · ');
+}

package/src/slides/ui/index.ts

@@ -0,0 +1,18 @@
+export type { BackToSlidesProps } from './BackToSlides.tsx';
+export { BackToSlides } from './BackToSlides.tsx';
+export type { DemoLinkProps, RenderSlideLink } from './DemoLink.tsx';
+export { DemoLink } from './DemoLink.tsx';
+export type { EmbedSlideProps } from './EmbedSlide.tsx';
+export { EmbedSlide } from './EmbedSlide.tsx';
+export type { SectionSlideProps } from './SectionSlide.tsx';
+export { SectionSlide } from './SectionSlide.tsx';
+export type { SlideLayoutProps, SlideViewProps } from './Slide.tsx';
+export { SlideView } from './Slide.tsx';
+export type { SlideBodyProps } from './SlideBody.tsx';
+export { SlideBody } from './SlideBody.tsx';
+export type { SlideshowProps } from './Slideshow.tsx';
+export { Slideshow } from './Slideshow.tsx';
+export type { SlideshowBarProps } from './SlideshowBar.tsx';
+export { SlideshowBar } from './SlideshowBar.tsx';
+export type { TalkListProps } from './TalkList.tsx';
+export { TalkList } from './TalkList.tsx';

package/src/slides/vite/index.ts

@@ -0,0 +1,2 @@
+export type { LoadedTalk, TalksOptions } from './talks.ts';
+export { cheminfoTalks, loadTalksFromDisk } from './talks.ts';

package/src/slides/vite/talks.ts

@@ -0,0 +1,126 @@
+/**
+ * Publish a site's talks so another site can list and play them.
+ *
+ * A deck is Markdown in the repository of the site whose subject it teaches,
+ * which is what keeps a talk reviewable. For learn.cheminfo.org to gather the
+ * family's talks it needs two static files per site and no API: a manifest of
+ * what exists, and the source of each deck. Both are written at build time and
+ * served with permissive CORS, because public teaching material is fetched from
+ * a page that is not ours.
+ */
+
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import type { Plugin } from 'vite';
+
+import { siteById, siteUrl } from '../../ecosystem/core/index.ts';
+import type { SiteId } from '../../ecosystem/core/sites.ts';
+import type { Talk } from '../core/talk.ts';
+import { parseTalk } from '../core/talk.ts';
+import { buildTalkManifest } from '../core/talkManifest.ts';
+
+/** What the build needs to know to publish the decks. */
+export interface TalksOptions {
+  /** The site the talks belong to. */
+  site: SiteId;
+  /**
+   * Where the sources live, relative to the project root.
+   * @default 'src/talks'
+   */
+  dir?: string;
+  /**
+   * Where the site is served, used as the manifest's origin.
+   * @default `https://<the site's host>`
+   */
+  origin?: string;
+}
+
+/** One talk on disk: its id, its source, and what the source parses into. */
+export interface LoadedTalk {
+  /** The file name without extension, or the folder name for `<id>/index.md`. */
+  id: string;
+  /** The Markdown as written, which is what other sites fetch. */
+  source: string;
+  /** The parsed talk, for the manifest. */
+  talk: Talk;
+}
+
+/**
+ * Write `talks.json` and `talks/<id>.md` into the build.
+ * @param options - Which site, and where its decks are.
+ * @returns The Vite plugin.
+ */
+export function cheminfoTalks(options: TalksOptions): Plugin {
+  const { site, dir = 'src/talks' } = options;
+  let root = process.cwd();
+  let outDir = 'dist';
+
+  return {
+    name: 'cheminfo-talks',
+    apply: 'build',
+    configResolved(config) {
+      root = config.root;
+      outDir = config.build.outDir;
+    },
+    closeBundle() {
+      const talks = loadTalksFromDisk(join(root, dir));
+      const origin =
+        options.origin ?? siteUrl(siteById(site)).replace(/\/$/, '');
+      const manifest = buildTalkManifest({
+        site,
+        origin,
+        talks: talks.map((entry) => ({ id: entry.id, ...entry.talk })),
+      });
+
+      const target = resolve(root, outDir);
+      mkdirSync(join(target, 'talks'), { recursive: true });
+      writeFileSync(
+        join(target, 'talks.json'),
+        `${JSON.stringify(manifest, null, 2)}\n`,
+      );
+      for (const entry of talks) {
+        writeFileSync(join(target, 'talks', `${entry.id}.md`), entry.source);
+      }
+    },
+  };
+}
+
+/**
+ * Read every deck of a directory, in either of the two shapes a talk takes.
+ * @param directory - Absolute path of the talks directory.
+ * @returns The talks, sorted by id so a build is reproducible.
+ */
+export function loadTalksFromDisk(directory: string): LoadedTalk[] {
+  const loaded: LoadedTalk[] = [];
+  let entries: string[] = [];
+  try {
+    entries = readdirSync(directory);
+  } catch {
+    // A site with no talks yet still builds; it simply publishes an empty list.
+    return loaded;
+  }
+
+  for (const entry of entries) {
+    const path = join(directory, entry);
+    if (entry.endsWith('.md')) {
+      const source = readFileSync(path, 'utf8');
+      loaded.push({
+        id: entry.slice(0, -3),
+        source,
+        talk: parseTalk(source),
+      });
+      continue;
+    }
+    const index = join(path, 'index.md');
+    let source: string;
+    try {
+      source = readFileSync(index, 'utf8');
+    } catch {
+      continue;
+    }
+    loaded.push({ id: entry, source, talk: parseTalk(source) });
+  }
+
+  return loaded.toSorted((left, right) => left.id.localeCompare(right.id));
+}

package/src/slides.ts

@@ -0,0 +1,2 @@
+export * from './slides/core/index.ts';
+export * from './slides/ui/index.ts';

package/src/structure/ui/StructureEditor.tsx

@@ -179,7 +179,7 @@ const ROOT_STYLE: CSSProperties = {
   position: 'relative',
   overflow: 'hidden',
   boxSizing: 'border-box',
-  border: '1px solid #d3d8de',
+  border: '1px solid var(--border, #d3d8de)',
   borderRadius: 6,
   background: '#fff',
 };
@@ -191,6 +191,6 @@ const LOADING_STYLE: CSSProperties = {
   display: 'flex',
   alignItems: 'center',
   justifyContent: 'center',
-  color: '#8a96a3',
+  color: 'var(--text-faint, #8a96a3)',
   fontSize: 13,
 };

package/src/structure/ui/StructurePlaceholder.tsx

@@ -43,6 +43,6 @@ const PLACEHOLDER_STYLE: CSSProperties = {
   display: 'inline-flex',
   alignItems: 'center',
   justifyContent: 'center',
-  color: '#8a96a3',
+  color: 'var(--text-faint, #8a96a3)',
   fontSize: '0.75rem',
 };

package/src/tokens/core/checkTokens.ts

@@ -0,0 +1,242 @@
+// tokens-ok: file — the checker names the colours it looks for.
+import { normalizeColor, readHexColor, readRgbColor } from './colors.ts';
+import { BANNED_COLORS } from './rules.ts';
+
+/** What a site got wrong where a token was called for. */
+export type TokenViolationKind =
+  'blueprint-grey' | 'blueprint-blue' | 'retyped-token' | 'redeclared-brand';
+
+/** One place a site writes a colour that is not its own to write. */
+export interface TokenViolation {
+  /** The file it is written in, named as the caller named it. */
+  file: string;
+  /** Which line, counting from 1. */
+  line: number;
+  /** Which column, counting from 1. */
+  column: number;
+  /** What kind of mistake it is. */
+  kind: TokenViolationKind;
+  /** The text as written — the hex, the `rgb()` call, the property name. */
+  text: string;
+  /** The token to use instead, in one line. */
+  hint: string;
+}
+
+/** How forgiving a scan is. */
+export interface CheckTokensOptions {
+  /**
+   * Colours the project legitimately owns — a subject-matter palette, a logo
+   * of somebody else.
+   * @default []
+   */
+  allow?: readonly string[];
+  /**
+   * Lines carrying this marker are skipped, for the rare deliberate literal.
+   * @default 'tokens-ok'
+   */
+  ignoreMarker?: string;
+}
+
+/**
+ * Every colour a set of files writes that belongs to the family rather than to
+ * the site.
+ *
+ * The neutrals, the geometry and the type are shared, and the two colours a
+ * site owns come from `<SiteTheme siteId>`; a site that re-types either — a
+ * Blueprint grey because a component used it, `#f5f7fa` because that is what
+ * the token holds today, `--brand` because the palette was declared by hand —
+ * leaves its page unable to follow the family. Both spellings of one colour
+ * are caught, `#5f6b7c` and `rgb(95 107 124)` alike, and reading a token
+ * through `var()` is never a violation.
+ * @param files - The files to read, each with the path a report names it by.
+ * @param options - The colours the project owns, and the marker waiving a line.
+ * @returns Every violation, in file order and then in reading order.
+ */
+export function findTokenViolations(
+  files: ReadonlyArray<{ path: string; text: string }>,
+  options: CheckTokensOptions = {},
+): TokenViolation[] {
+  const marker = (options.ignoreMarker ?? DEFAULT_IGNORE_MARKER).toLowerCase();
+  const allowed = new Set<string>();
+  for (const entry of options.allow ?? []) {
+    const color = normalizeColor(entry);
+    if (color !== null) allowed.add(color);
+  }
+
+  const violations: TokenViolation[] = [];
+  for (const file of files) {
+    // A file whose opening lines carry the marker defines the palette rather
+    // than consuming it — the token block itself, the registry of banned
+    // colours, an image generated outside any page.
+    if (waivesWholeFile(file.text, marker)) continue;
+    const scan = scanFile(file.text, marker);
+    for (const candidate of scan.candidates) {
+      if (scan.markedLines.has(candidate.line)) continue;
+      if (candidate.color !== null && allowed.has(candidate.color)) continue;
+      violations.push({
+        file: file.path,
+        line: candidate.line,
+        column: candidate.column,
+        kind: candidate.kind,
+        text: candidate.text,
+        hint: candidate.hint,
+      });
+    }
+  }
+  return violations;
+}
+
+const DEFAULT_IGNORE_MARKER = 'tokens-ok';
+
+// How far into a file the whole-file waiver may sit: a licence header, an
+// import or two, and the comment saying why this file writes colours.
+const WAIVER_LINES = 6;
+
+function waivesWholeFile(text: string, marker: string): boolean {
+  if (marker.length === 0) return false;
+  const head = text.split('\n', WAIVER_LINES).join('\n').toLowerCase();
+  return head.includes(`${marker}: file`);
+}
+
+// Longest first, so `--brand-alt` is never read as `--brand`.
+const BRAND_PROPERTIES = ['--brand-alt', '--brand', '--accent'] as const;
+
+interface Candidate extends Omit<TokenViolation, 'file'> {
+  /** The colour written, or `null` for a property that should not be declared. */
+  color: string | null;
+}
+
+interface FileScan {
+  candidates: Candidate[];
+  markedLines: Set<number>;
+}
+
+// One pass over the file: the marker, the block structure and every colour are
+// all read from the same walk, so nothing is matched a second time per line.
+function scanFile(text: string, marker: string): FileScan {
+  const lower = text.toLowerCase();
+  const candidates: Candidate[] = [];
+  const markedLines = new Set<number>();
+  const rootBlocks: boolean[] = [];
+  // Which parentheses are open, and whether each is a `var(` past its comma —
+  // a colour there is a fallback for the token named beside it.
+  const parens: Array<{ isVar: boolean; sawComma: boolean }> = [];
+  let selectorStart = 0;
+  let line = 1;
+  let lineStart = 0;
+
+  for (let index = 0; index < lower.length; index++) {
+    const char = lower[index];
+    if (char === '\n') {
+      line++;
+      lineStart = index + 1;
+      continue;
+    }
+    if (
+      marker.length > 0 &&
+      char === marker[0] &&
+      lower.startsWith(marker, index)
+    ) {
+      markedLines.add(line);
+      index += marker.length - 1;
+      continue;
+    }
+    if (char === '(') {
+      parens.push({
+        isVar: lower.startsWith('var(', index - 3),
+        sawComma: false,
+      });
+      continue;
+    }
+    if (char === ')') {
+      parens.pop();
+      continue;
+    }
+    if (char === ',') {
+      const open = parens.at(-1);
+      if (open !== undefined) open.sawComma = true;
+      continue;
+    }
+    if (char === '{') {
+      rootBlocks.push(lower.slice(selectorStart, index).includes(':root'));
+      selectorStart = index + 1;
+      continue;
+    }
+    if (char === '}' || char === ';') {
+      if (char === '}') rootBlocks.pop();
+      selectorStart = index + 1;
+      continue;
+    }
+
+    if (char === '#' || char === 'r') {
+      const match =
+        char === '#' ? readHexColor(lower, index) : readRgbColor(lower, index);
+      if (match === null) continue;
+      const rule = BANNED_COLORS.get(match.color);
+      const open = parens.at(-1);
+      const isFallback = open !== undefined && open.isVar && open.sawComma;
+      if (rule !== undefined && !isFallback) {
+        candidates.push({
+          line,
+          column: index - lineStart + 1,
+          kind: rule.kind,
+          text: text.slice(index, match.end),
+          hint: rule.hint,
+          color: match.color,
+        });
+      }
+      index = match.end - 1;
+      continue;
+    }
+
+    if (char === '-') {
+      const property = readBrandDeclaration(lower, index);
+      if (property === null) continue;
+      if (rootBlocks.includes(true)) {
+        candidates.push({
+          line,
+          column: index - lineStart + 1,
+          kind: 'redeclared-brand',
+          text: property.name,
+          hint: `render <SiteTheme siteId> instead of declaring ${property.name} in :root.`,
+          color: null,
+        });
+      }
+      index = property.end - 1;
+    }
+  }
+  return { candidates, markedLines };
+}
+
+// A declaration of one of the palette properties. Reading one — `var(--brand)`
+// — has no colon after the name, so it never lands here.
+function readBrandDeclaration(
+  lower: string,
+  start: number,
+): { name: string; end: number } | null {
+  for (const name of BRAND_PROPERTIES) {
+    if (!lower.startsWith(name, start)) continue;
+    const after = start + name.length;
+    // `--brand-alt-text` is its own property, not `--brand-alt`.
+    if (isNameChar(lower[after])) return null;
+    let index = after;
+    while (isSpace(lower[index])) index++;
+    if (lower[index] !== ':') return null;
+    return { name, end: after };
+  }
+  return null;
+}
+
+function isNameChar(char: string | undefined): boolean {
+  if (char === undefined) return false;
+  return (
+    (char >= '0' && char <= '9') ||
+    (char >= 'a' && char <= 'z') ||
+    char === '-' ||
+    char === '_'
+  );
+}
+
+function isSpace(char: string | undefined): boolean {
+  return char === ' ' || char === '\t';
+}

package/src/tokens/core/colors.ts

@@ -0,0 +1,122 @@
+// tokens-ok: file — the colour reader is tested against literals.
+/**
+ * Reading a colour out of source text, in both spellings the same value is
+ * written in: `#5f6b7c` and `rgb(95 107 124)`. Both come back as the same six
+ * lowercase hex digits, so a table of banned colours holds one entry per
+ * colour rather than one per way of typing it.
+ */
+
+/** A colour found in the text, and where it ends. */
+export interface ColorMatch {
+  /** The value, as six lowercase hex digits, without its `#`. */
+  color: string;
+  /** The index just past the last character the colour is written with. */
+  end: number;
+}
+
+/**
+ * The colour a hex literal starts at, in `#rgb`, `#rgba`, `#rrggbb` or
+ * `#rrggbbaa` form. The alpha, when there is one, says nothing about the
+ * colour and is dropped.
+ * @param lower - The text being scanned, already lowercased.
+ * @param start - The index of the `#`.
+ * @returns The colour and its end, or `null` when it is not a hex colour.
+ */
+export function readHexColor(lower: string, start: number): ColorMatch | null {
+  let end = start + 1;
+  while (isHexDigit(lower[end])) end++;
+
+  // A run of hex digits running straight into a word is an identifier — a
+  // private field, an anchor — rather than a colour.
+  if (isWordChar(lower[end])) return null;
+
+  const digits = end - start - 1;
+  if (digits === 3 || digits === 4) {
+    const red = lower[start + 1];
+    const green = lower[start + 2];
+    const blue = lower[start + 3];
+    return { color: `${red}${red}${green}${green}${blue}${blue}`, end };
+  }
+  if (digits === 6 || digits === 8) {
+    return { color: lower.slice(start + 1, start + 7), end };
+  }
+  return null;
+}
+
+/**
+ * The colour an `rgb()` or `rgba()` call starts at, in either the comma or the
+ * space separated spelling.
+ *
+ * Only a plain byte triple is read: a percentage, a decimal or a variable
+ * inside the call means the value cannot be compared with a hex literal, and
+ * is left alone rather than guessed at.
+ * @param lower - The text being scanned, already lowercased.
+ * @param start - The index of the `r`.
+ * @returns The colour and its end, or `null` when it is not one.
+ */
+export function readRgbColor(lower: string, start: number): ColorMatch | null {
+  let open = -1;
+  if (lower.startsWith('rgb(', start)) open = start + 3;
+  else if (lower.startsWith('rgba(', start)) open = start + 4;
+  if (open === -1) return null;
+
+  const close = lower.indexOf(')', open);
+  if (close === -1) return null;
+
+  const components: number[] = [];
+  let value = -1;
+  for (let index = open + 1; index < close; index++) {
+    const char = lower[index];
+    if (char !== undefined && char >= '0' && char <= '9') {
+      value = Math.max(value, 0) * 10 + Number(char);
+      continue;
+    }
+    if (value >= 0) {
+      components.push(value);
+      value = -1;
+    }
+    // The alpha of the modern syntax, which the colour does not depend on.
+    if (char === '/') break;
+    if (char !== ' ' && char !== ',' && char !== '\t' && char !== '\n') {
+      return null;
+    }
+  }
+  if (value >= 0) components.push(value);
+  if (components.length < 3) return null;
+
+  let color = '';
+  for (let index = 0; index < 3; index++) {
+    const component = components[index];
+    if (component === undefined || component > 255) return null;
+    color += component.toString(16).padStart(2, '0');
+  }
+  return { color, end: close + 1 };
+}
+
+/**
+ * The `rrggbb` form of a colour written by hand — in an allow list, on a
+ * command line — in any of the spellings the scanner itself reads.
+ * @param value - The colour, with or without its `#`.
+ * @returns The six lowercase hex digits, or `null` when it is not a colour.
+ */
+export function normalizeColor(value: string): string | null {
+  const text = value.trim().toLowerCase();
+  if (text === '') return null;
+  let match: ColorMatch | null = null;
+  if (text.startsWith('#')) match = readHexColor(text, 0);
+  else if (text.startsWith('rgb')) match = readRgbColor(text, 0);
+  else match = readHexColor(`#${text}`, 0);
+  return match === null ? null : match.color;
+}
+
+function isHexDigit(char: string | undefined): boolean {
+  if (char === undefined) return false;
+  return (char >= '0' && char <= '9') || (char >= 'a' && char <= 'f');
+}
+
+function isWordChar(char: string | undefined): boolean {
+  if (char === undefined) return false;
+  return (
+    (char >= '0' && char <= '9') || (char >= 'a' && char <= 'z') || char === '_'
+  );
+}