react-cheminfo 0.7.0 → 0.9.0

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 === '_'
+  );
+}

package/src/tokens/core/index.ts

@@ -0,0 +1,6 @@
+export type {
+  CheckTokensOptions,
+  TokenViolation,
+  TokenViolationKind,
+} from './checkTokens.ts';
+export { findTokenViolations } from './checkTokens.ts';

package/src/tokens/core/rules.ts

@@ -0,0 +1,103 @@
+// tokens-ok: file — the colours a site may not write are listed here.
+import type { TokenViolationKind } from './checkTokens.ts';
+
+/** What a colour a site may not write should have been. */
+export interface ColorRule {
+  /** Which kind of violation writing it raises. */
+  kind: TokenViolationKind;
+  /** The token to write instead, in one line. */
+  hint: string;
+}
+
+/**
+ * The colours a site may not write, keyed by their six lowercase hex digits.
+ *
+ * Two things land here. Blueprint's own neutrals and intent blue, which arrive
+ * by reading a value off a component and pasting it: they are near the
+ * family's greys without being them, which is what makes two of our sites
+ * opened side by side read as two products. And the family's own token values
+ * re-typed as literals, which pins the page to the colour the token held on
+ * the day it was copied — a retune then moves everything except it.
+ *
+ * `#ffffff` is deliberately absent: `--surface` is white, and so are a hundred
+ * legitimate whites in a shadow, a gradient or a `color-mix`.
+ */
+export const BANNED_COLORS: ReadonlyMap<string, ColorRule> = new Map<
+  string,
+  ColorRule
+>([
+  [
+    'f6f7f9',
+    {
+      kind: 'blueprint-grey',
+      hint: "Blueprint's page grey — the family's page is var(--surface-sunken).",
+    },
+  ],
+  [
+    'd3d8de',
+    {
+      kind: 'blueprint-grey',
+      hint: "Blueprint's light grey — the family's line is var(--border).",
+    },
+  ],
+  [
+    '5f6b7c',
+    {
+      kind: 'blueprint-grey',
+      hint: "Blueprint's muted text — use var(--text-muted).",
+    },
+  ],
+  [
+    '2d72d2',
+    {
+      kind: 'blueprint-blue',
+      hint: "Blueprint's intent blue — the site's own colour is var(--accent).",
+    },
+  ],
+  [
+    '137cbd',
+    {
+      kind: 'blueprint-blue',
+      hint: "Blueprint's older intent blue — the site's own colour is var(--accent).",
+    },
+  ],
+  [
+    'f5f7fa',
+    {
+      kind: 'retyped-token',
+      hint: 'the value of --surface-sunken — use var(--surface-sunken).',
+    },
+  ],
+  [
+    'dfe3e8',
+    {
+      kind: 'retyped-token',
+      hint: 'the value of --border — use var(--border).',
+    },
+  ],
+  [
+    'c3cad3',
+    {
+      kind: 'retyped-token',
+      hint: 'the value of --border-strong — use var(--border-strong).',
+    },
+  ],
+  [
+    '16202c',
+    { kind: 'retyped-token', hint: 'the value of --text — use var(--text).' },
+  ],
+  [
+    '5b6875',
+    {
+      kind: 'retyped-token',
+      hint: 'the value of --text-muted — use var(--text-muted).',
+    },
+  ],
+  [
+    '8a96a3',
+    {
+      kind: 'retyped-token',
+      hint: 'the value of --text-faint — use var(--text-faint).',
+    },
+  ],
+]);

package/src/ui.ts

@@ -1,3 +1,4 @@
+export * from './about/ui/index.ts';
 export * from './capsule/ui/index.ts';
 export * from './chrome/ui/index.ts';
 export * from './citation/ui/index.ts';

package/src/vite.ts

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

package/styles/chrome.css

@@ -1,3 +1,4 @@
+/* tokens-ok: file — this is where the family's tokens are declared. */
 /*
  * The chrome every *.cheminfo.org site carries: the neutrals, the geometry and
  * the type the family shares, then the bar, the menu and the footer drawn from