react-cheminfo 0.8.0 → 0.10.0

package/src/spectra/ui/problemsAbout.ts

@@ -0,0 +1,21 @@
+import type { SettingsProblem } from '../core/problems.ts';
+
+/**
+ * The problems whose `where` is, or starts with, one of the given words.
+ *
+ * The `where` strings are what `settingsProblems` writes, so a part of the
+ * panel asks for its own by naming the same words it is headed with — which
+ * keeps a problem next to the field that causes it rather than in one list at
+ * the top, far from anything the reader can act on.
+ * @param problems - Every problem the settings have.
+ * @param prefixes - The `where` strings the part answers for.
+ * @returns Only those problems, in the order they were found.
+ */
+export function problemsAbout(
+  problems: readonly SettingsProblem[],
+  ...prefixes: readonly string[]
+): SettingsProblem[] {
+  return problems.filter((entry) =>
+    prefixes.some((prefix) => entry.where.startsWith(prefix)),
+  );
+}

package/src/spectra/ui/rowKeys.ts

@@ -0,0 +1,47 @@
+/**
+ * A key no row is using yet.
+ *
+ * A row of the settings — a zone, a matrix step, a range — carries no identity
+ * of its own, so one is kept beside the list. Without it React reuses a removed
+ * row's box for the row that slides up, and the half-typed number in it goes
+ * with the wrong entry.
+ * @param keys - The keys in force.
+ * @returns The next free one.
+ */
+export function nextKey(keys: readonly number[]): number {
+  let highest = -1;
+  for (const key of keys) {
+    if (key > highest) highest = key;
+  }
+  return highest + 1;
+}
+
+/**
+ * The keys brought back in step with a list that changed from outside.
+ * @param keys - The keys in force.
+ * @param length - How many rows there now are.
+ * @returns One key per row.
+ */
+export function fitKeys(keys: readonly number[], length: number): number[] {
+  const fitted = keys.slice(0, length);
+  while (fitted.length < length) fitted.push(nextKey(fitted));
+  return fitted;
+}
+
+/**
+ * A list with one entry moved to another position.
+ * @param list - What to reorder.
+ * @param index - Which entry to move.
+ * @param target - Where it lands.
+ * @returns A new list.
+ */
+export function reorder<T>(
+  list: readonly T[],
+  index: number,
+  target: number,
+): T[] {
+  const moved = [...list];
+  const [entry] = moved.splice(index, 1);
+  if (entry !== undefined) moved.splice(target, 0, entry);
+  return moved;
+}

package/src/spectra/ui/scaleOptions.ts

@@ -0,0 +1,116 @@
+import type { ScaleSettings } from '../core/settings.ts';
+import { SCALE_METHODS } from '../core/settingsProblems.ts';
+
+/** The stretch of x a scaling is measured over. */
+export type ScaleRange = NonNullable<ScaleSettings['range']>;
+
+/** What each scaling is called, in the order the processor's switch lists them. */
+const METHOD_LABELS: Readonly<Record<string, string>> = {
+  min: 'Smallest value',
+  max: 'Largest value',
+  minmax: 'Both ends',
+  integration: 'Integral',
+};
+
+/** The method menu: leaving the spectra alone, then the only four that run. */
+export const SCALE_METHOD_OPTIONS: ReadonlyArray<{
+  value: string;
+  label: string;
+}> = [
+  { value: '', label: 'None — every spectrum is left as it is' },
+  ...SCALE_METHODS.map((method) => ({
+    value: method,
+    label: METHOD_LABELS[method] ?? method,
+  })),
+];
+
+/**
+ * The method menu with whatever the settings actually hold in it.
+ *
+ * A menu that does not carry the held value draws the first option instead, so
+ * a settings object saying `MAX` — or saying something the processor throws on
+ * — would be shown as `None` while meaning nothing of the sort. The held
+ * spelling is added rather than corrected, because the panel reports what the
+ * settings say and never quietly rewrites them.
+ * @param method - What the settings hold.
+ * @returns The None prompt and the four scalings, plus the held one when the
+ * menu lacks it.
+ */
+export function scaleMethodOptions(
+  method: string | undefined,
+): ReadonlyArray<{ value: string; label: string }> {
+  if (method === undefined || method === '') return SCALE_METHOD_OPTIONS;
+  for (const option of SCALE_METHOD_OPTIONS) {
+    if (option.value === method) return SCALE_METHOD_OPTIONS;
+  }
+  const known = METHOD_LABELS[method.toLowerCase()];
+  return [
+    ...SCALE_METHOD_OPTIONS,
+    {
+      value: method,
+      label:
+        known === undefined
+          ? `${method} — not a scaling the processor knows`
+          : `${method} — ${known}`,
+    },
+  ];
+}
+
+/**
+ * The scaling with another method, or with none when `None` is picked.
+ *
+ * A picked `None` drops the key rather than writing an empty string, because
+ * the processor reads any falsy method as "do not scale" and a key that is
+ * there but empty reads, to anyone looking at the settings, as a mistake.
+ * @param value - How every spectrum is scaled.
+ * @param method - What was picked.
+ * @returns A new scaling.
+ */
+export function withScaleMethod(
+  value: ScaleSettings,
+  method: string,
+): ScaleSettings {
+  const next: ScaleSettings = { ...value };
+  if (method === '') delete next.method;
+  else next.method = method;
+  return next;
+}
+
+/**
+ * The scaling with another reference, or with none when the box was emptied.
+ * @param value - How every spectrum is scaled.
+ * @param targetID - What was picked or typed.
+ * @returns A new scaling.
+ */
+export function withScaleTarget(
+  value: ScaleSettings,
+  targetID: string,
+): ScaleSettings {
+  const next: ScaleSettings = { ...value };
+  if (targetID === '') delete next.targetID;
+  else next.targetID = targetID;
+  return next;
+}
+
+/**
+ * The scaling measured over another window, dropping what is not set.
+ * @param value - How every spectrum is scaled.
+ * @param patch - The bounds that changed.
+ * @returns A new scaling, without a window at all once every bound is cleared.
+ */
+export function withScaleRange(
+  value: ScaleSettings,
+  patch: ScaleRange,
+): ScaleSettings {
+  const merged: ScaleRange = { ...value.range, ...patch };
+  const range: ScaleRange = {};
+  if (merged.from !== undefined) range.from = merged.from;
+  if (merged.to !== undefined) range.to = merged.to;
+  if (merged.fromIndex !== undefined) range.fromIndex = merged.fromIndex;
+  if (merged.toIndex !== undefined) range.toIndex = merged.toIndex;
+
+  const next: ScaleSettings = { ...value };
+  if (Object.keys(range).length === 0) delete next.range;
+  else next.range = range;
+  return next;
+}

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

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).',
+    },
+  ],
+]);