react-cheminfo 0.8.0 → 0.10.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/spectra/core/axisEntries.ts

@@ -0,0 +1,107 @@
+import type { FilterCatalogEntry } from './filterEntries.ts';
+import { RANGE_FIELDS, ZONE_FIELDS } from './filterEntries.ts';
+import {
+  booleanField,
+  enumField,
+  formulaField,
+  integerField,
+  numberField,
+} from './filterFields.ts';
+
+export const AXIS_ENTRIES = {
+  xFunction: {
+    label: 'Apply a formula to x',
+    group: 'x-axis',
+    summary:
+      'Rewrites every x through an expression, read the same way as the y one.',
+    fields: [
+      formulaField(
+        'function',
+        'Expression in x',
+        'For instance 10000000/x, which reads nanometres as wavenumbers.',
+      ),
+    ],
+    caution:
+      'Every range below is then read in the new units — including the resampling range, which runs last unless you resample first.',
+  },
+  fromTo: {
+    label: 'Crop',
+    group: 'x-axis',
+    summary: 'Keeps one stretch of the spectrum and drops the rest.',
+    fields: [
+      ...RANGE_FIELDS,
+      integerField('fromIndex', 'From (point)', '0'),
+      integerField('toIndex', 'To (point)', 'the last point'),
+    ],
+    caution:
+      'Give x values or point numbers, not both: a point number silently wins over an x value.',
+  },
+  filterX: {
+    label: 'Keep or drop x zones',
+    group: 'x-axis',
+    summary:
+      'Keeps the points falling in the zones named, without resampling anything.',
+    fields: [...RANGE_FIELDS, ...ZONE_FIELDS],
+  },
+  equallySpaced: {
+    label: 'Resample on a regular grid',
+    group: 'x-axis',
+    summary: 'Interpolates onto evenly spaced x values.',
+    fields: [
+      ...RANGE_FIELDS,
+      integerField('numberOfPoints', 'Number of points', '100'),
+      ...ZONE_FIELDS,
+    ],
+    caution:
+      'The settings above already resample once, so this resamples twice; whichever of the two runs last sets the point count.',
+  },
+  calibrateX: {
+    label: 'Calibrate x on a peak',
+    group: 'x-axis',
+    summary:
+      'Finds the strongest peaks in a stretch and shifts the whole axis so their mean lands on the value asked for.',
+    fields: [
+      ...RANGE_FIELDS,
+      integerField('nbPeaks', 'Peaks to find', '1'),
+      numberField('targetX', 'Move them to', '0'),
+      booleanField('gsd.smoothY', 'Smooth before picking'),
+      booleanField(
+        'gsd.maxCriteria',
+        'Pick maxima',
+        'Off picks minima instead.',
+      ),
+      numberField(
+        'gsd.minMaxRatio',
+        'Smallest peak kept',
+        '0.00025',
+        'As a fraction of the tallest. A step added here starts at 0.1; empty the box and this far lower default takes over.',
+      ),
+      numberField('gsd.noiseLevel', 'Noise level', 'not set'),
+      booleanField('gsd.realTopDetection', 'Refine the summit'),
+      integerField('gsd.sgOptions.windowSize', 'Peak-picking window', '9'),
+      integerField('gsd.sgOptions.polynomial', 'Peak-picking polynomial', '3'),
+      enumField('gsd.peakDetectionAlgorithm', 'Detected on', [
+        { value: 'first', label: 'The first derivative' },
+        { value: 'second', label: 'The second derivative' },
+        { value: 'auto', label: 'Whichever fits' },
+      ]),
+    ],
+    caution:
+      'When fewer peaks are found than asked for, the spectrum is returned untouched and nothing says so.',
+  },
+  ensureGrowing: {
+    label: 'Make x strictly increasing',
+    group: 'utility',
+    summary:
+      'Drops the points that repeat or go backwards, which resampling and cropping both assume never happens.',
+    fields: [],
+  },
+  reverseIfNeeded: {
+    label: 'Reverse a descending x',
+    group: 'utility',
+    summary: 'Turns a descending axis the right way round.',
+    fields: [],
+    caution:
+      'The chain already does this before every step, so adding it here changes nothing.',
+  },
+} as const satisfies Record<string, FilterCatalogEntry>;

package/src/spectra/core/chainProblems.ts

@@ -0,0 +1,165 @@
+import { filterStepLabel, findFilterEntry } from './filterCatalog.ts';
+import type { SettingsProblem } from './problems.ts';
+import { problem } from './problems.ts';
+import type { SpectrumFilter, SpectrumFilterName } from './settings.ts';
+import { stepProblems } from './stepProblems.ts';
+
+/** The steps that all say "make the y scale comparable"; only the last survives. */
+const SCALING_STEPS: ReadonlySet<SpectrumFilterName> = new Set([
+  'divideBySD',
+  'normed',
+  'paretoNormalization',
+  'rescale',
+]);
+
+/** The steps that hand on plain arrays, whatever they were given. */
+const UNTYPES_X: ReadonlySet<SpectrumFilterName> = new Set([
+  'equallySpaced',
+  'filterX',
+]);
+
+/** The steps that read x as a typed array and throw on a plain one. */
+const NEEDS_TYPED_X: ReadonlySet<SpectrumFilterName> = new Set([
+  'calibrateX',
+  'fromTo',
+]);
+
+/**
+ * Everything wrong, or probably wrong, with one chain.
+ *
+ * The order of a chain is its meaning — scaling measured before a baseline is
+ * removed measures an offset that is about to change — so the advice below is
+ * as much about where a step sits as about what it is set to.
+ * @param chain - The steps, in the order they run.
+ * @param resampleFirst - Whether the settings resample before the chain runs.
+ * @returns Every problem found, errors and advice together.
+ */
+export function chainProblems(
+  chain: readonly SpectrumFilter[],
+  resampleFirst: boolean,
+): SettingsProblem[] {
+  const problems: SettingsProblem[] = [];
+  let baselines = 0;
+  let scalings = 0;
+  let firstScaling: number | undefined;
+  let plainX = resampleFirst;
+  let mayBePlainX = resampleFirst;
+
+  for (const [index, step] of chain.entries()) {
+    const where = filterStepLabel(step.name, index);
+    const entry = findFilterEntry(step.name);
+    problems.push(...stepProblems(step, where));
+
+    if (entry === undefined) {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          `${step.name} is not one of the steps this editor knows, so its options are left as they are. The processor throws on a name it cannot dispatch.`,
+        ),
+      );
+      continue;
+    }
+
+    if (NEEDS_TYPED_X.has(step.name)) {
+      if (plainX) {
+        problems.push(problem('error', where, TYPED_X_MESSAGE));
+      } else if (mayBePlainX) {
+        problems.push(problem('warning', where, MAY_BE_PLAIN_MESSAGE));
+      }
+    }
+    if (UNTYPES_X.has(step.name)) {
+      plainX = true;
+      mayBePlainX = true;
+    }
+    if (step.name === 'ensureGrowing') mayBePlainX = true;
+
+    const { group } = entry;
+    if (group === 'baseline') {
+      baselines++;
+      if (firstScaling !== undefined) {
+        problems.push(
+          problem(
+            'warning',
+            where,
+            `Step ${String(firstScaling + 1)} scales the signal before this levels it, so the scaling is measured against an offset that then changes. Level first.`,
+          ),
+        );
+        firstScaling = undefined;
+      }
+    }
+    if (SCALING_STEPS.has(step.name)) {
+      scalings++;
+      firstScaling ??= index;
+    }
+    if (step.name === 'reverseIfNeeded') {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          'The chain already turns a descending axis round before every step, so this one does nothing.',
+        ),
+      );
+    }
+    if (step.name === 'equallySpaced') {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          resampleFirst
+            ? 'The settings resample before the chain runs, so this resamples a second time and the point count set here is the one the matrix ends up with.'
+            : 'The settings resample after the chain runs, so this resamples a second time and the point count set above is the one the matrix ends up with.',
+        ),
+      );
+    }
+    if (
+      !resampleFirst &&
+      (step.name === 'xFunction' || step.name === 'calibrateX')
+    ) {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          'This changes the x axis before the resampling runs, so the range and the exclusions above are read in the new units.',
+        ),
+      );
+    }
+    if (resampleFirst && step.name === 'filterX') {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          'Cropping after the resampling can leave each spectrum on its own grid, and the matrix then lines up rows that do not match. Pin the range above, or turn resampling back to last.',
+        ),
+      );
+    }
+  }
+
+  if (baselines > 1) {
+    problems.push(
+      problem(
+        'warning',
+        'The chain',
+        `${String(baselines)} baselines are subtracted one after another, each estimated from what the last one left.`,
+      ),
+    );
+  }
+  if (scalings > 1) {
+    problems.push(
+      problem(
+        'warning',
+        'The chain',
+        `${String(scalings)} steps set the y scale; only the last of them still shows in the result.`,
+      ),
+    );
+  }
+  return problems;
+}
+
+/** What a step reading x as a typed array is told when it cannot be one. */
+const TYPED_X_MESSAGE =
+  'This step reads x as a typed array, and resampling or cropping has already turned it into a plain one, so the processor throws. Move it before them, or turn resampling back to last.';
+
+/** The same, when only the data can settle whether x was untyped. */
+const MAY_BE_PLAIN_MESSAGE =
+  'This step reads x as a typed array. An earlier step turns x into a plain one whenever it has points to drop, and the processor then throws on this step.';

package/src/spectra/core/filterCatalog.ts

@@ -0,0 +1,100 @@
+import { AXIS_ENTRIES } from './axisEntries.ts';
+import type { FilterCatalogEntry } from './filterEntries.ts';
+import { BASELINE_ENTRIES, SIGNAL_ENTRIES } from './filterEntries.ts';
+import type { FilterGroup } from './filterFields.ts';
+import { FILTER_GROUPS } from './filterFields.ts';
+import type { SpectrumFilterName } from './settings.ts';
+
+/**
+ * What the editor knows about every step `filterXY` dispatches.
+ *
+ * Keyed by the name rather than listed, so the day `ml-signal-processing` adds
+ * a filter this object stops compiling and the gap is a build failure instead
+ * of a step nobody can reach.
+ */
+export const FILTER_CATALOG: Readonly<
+  Record<SpectrumFilterName, FilterCatalogEntry>
+> = {
+  ...BASELINE_ENTRIES,
+  ...SIGNAL_ENTRIES,
+  ...AXIS_ENTRIES,
+};
+
+/** Every step name, in the order the menu offers them. */
+export const FILTER_NAMES: readonly SpectrumFilterName[] = Object.keys(
+  FILTER_CATALOG,
+) as SpectrumFilterName[];
+
+/**
+ * What the editor knows about one step.
+ * @param name - The step's name.
+ * @returns Its catalog entry.
+ */
+export function filterEntry(name: SpectrumFilterName): FilterCatalogEntry {
+  return FILTER_CATALOG[name];
+}
+
+/**
+ * What the editor knows about a step whose name it may not recognise.
+ *
+ * The settings the processor accepts are typed `{ name: string }`, and
+ * `filterXY` really does dispatch four more names than the union declares, so a
+ * chain reaching the editor can name a step the catalog has never heard of.
+ * Answering nothing lets the panel say so; throwing would take the whole page
+ * down over one row.
+ * @param name - The step's name, from settings that may come from anywhere.
+ * @returns Its catalog entry, or undefined when the name is not one of the 23.
+ */
+export function findFilterEntry(name: string): FilterCatalogEntry | undefined {
+  return Object.hasOwn(FILTER_CATALOG, name)
+    ? FILTER_CATALOG[name as SpectrumFilterName]
+    : undefined;
+}
+
+/**
+ * How the panel labels one step of a chain, whether or not it knows the step.
+ * @param name - The step's name.
+ * @param position - Where it sits, counting from zero.
+ * @returns The label the row and every problem about it share.
+ */
+export function filterStepLabel(name: string, position: number): string {
+  return `Step ${String(position + 1)} — ${findFilterEntry(name)?.label ?? name}`;
+}
+
+/**
+ * The steps of one group, in menu order.
+ * @param group - Which part of the signal the steps work on.
+ * @returns Their names.
+ */
+export function filterNamesInGroup(
+  group: FilterGroup,
+): readonly SpectrumFilterName[] {
+  const names: SpectrumFilterName[] = [];
+  for (const name of FILTER_NAMES) {
+    if (FILTER_CATALOG[name].group === group) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * The whole menu, group by group, skipping a group that holds nothing.
+ *
+ * The 23 steps are unreadable as one list, and grouping them by what they touch
+ * is the same order a chain is usually built in: level the baseline, smooth,
+ * scale, then move the axis.
+ * @returns Each group with its steps.
+ */
+export function filterMenu(): ReadonlyArray<{
+  group: FilterGroup;
+  names: readonly SpectrumFilterName[];
+}> {
+  const menu: Array<{
+    group: FilterGroup;
+    names: readonly SpectrumFilterName[];
+  }> = [];
+  for (const group of FILTER_GROUPS) {
+    const names = filterNamesInGroup(group);
+    if (names.length > 0) menu.push({ group, names });
+  }
+  return menu;
+}