react-cheminfo 0.21.0 → 0.23.0

package/src/ecosystem/ui/glyphs.tsx

@@ -409,4 +409,55 @@ export const GLYPHS: Record<SiteId, (alt: string) => ReactNode> = {
       />
     </>
   ),
+  // A nucleus with one electron on its orbit. The electron carries the
+  // answering colour because the electron is what every tool here counts.
+  atoms: (alt) => (
+    <>
+      <circle
+        cx="16"
+        cy="16"
+        r="10.5"
+        fill="none"
+        stroke="#ffffff"
+        strokeWidth="2.2"
+      />
+      <circle cx="16" cy="16" r="3.6" fill="#ffffff" />
+      <circle cx="23.42" cy="8.58" r="3.2" fill={alt} />
+    </>
+  ),
+  // A balance still tipped, its two pans holding the two sides of the
+  // calculation. The pan that carries the answer carries the colour.
+  moles: (alt) => (
+    <>
+      <path
+        d="M6.5 11.5 25.5 15.5M16 13.5V24M10.5 24h11"
+        fill="none"
+        stroke="#ffffff"
+        strokeWidth="2.2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <circle cx="6.5" cy="11.5" r="3.2" fill="#ffffff" />
+      <circle cx="25.5" cy="15.5" r="3.2" fill={alt} />
+    </>
+  ),
+  // One cell of an ionic lattice, cations and anions alternating: the shape of
+  // the compounds this site names. The ion being named carries the colour.
+  inorganic: (alt) => (
+    <>
+      <path
+        d="M9.5 9.5h13v13h-13Z"
+        fill="none"
+        stroke="#ffffff"
+        strokeWidth="1.6"
+        opacity="0.55"
+      />
+      <g fill="#ffffff">
+        <circle cx="9.5" cy="9.5" r="4.3" />
+        <circle cx="22.5" cy="9.5" r="2.7" />
+        <circle cx="9.5" cy="22.5" r="2.7" />
+      </g>
+      <circle cx="22.5" cy="22.5" r="4.3" fill={alt} />
+    </>
+  ),
 };

package/src/error/ui/ErrorFallback.tsx

@@ -52,7 +52,9 @@ export function ErrorFallback(props: ErrorFallbackProps): ReactElement {
       icon="error"
       title={title}
       description={
-        error.message === '' ? 'No message was given.' : error.message
+        <span className="error-fallback__message">
+          {error.message === '' ? 'No message was given.' : error.message}
+        </span>
       }
       action={
         onRetry === undefined ? undefined : (

package/src/overlay/core/index.ts

@@ -11,8 +11,12 @@ export type { EmptiestCornerOptions } from './emptiestCorner.ts';
 export { emptiestCorner } from './emptiestCorner.ts';
 export type { OverlayBarFoldOptions } from './overlayCollapse.ts';
 export { overlayBarFolded, shouldCollapseOverlay } from './overlayCollapse.ts';
-export type { OverlayMarkShape } from './overlayMarks.ts';
-export { OVERLAY_MARK_SHAPES, isFilledMark } from './overlayMarks.ts';
+export type { OverlayMarkShape, OverlaySampleShape } from './overlayMarks.ts';
+export {
+  OVERLAY_MARK_SHAPES,
+  OVERLAY_SAMPLE_SHAPES,
+  isFilledMark,
+} from './overlayMarks.ts';
 export type {
   OverlayDensity,
   OverlayMetrics,

package/src/overlay/core/overlayMarks.ts

@@ -10,25 +10,62 @@
 
 /** Which mark a legend entry, a marker or a series stands for. */
 export type OverlayMarkShape =
-  'dot' | 'ring' | 'square' | 'line' | 'dashed' | 'cross';
+  | 'dot'
+  | 'ring'
+  | 'square'
+  | 'triangle'
+  | 'diamond'
+  | 'triangle-down'
+  | 'line'
+  | 'dashed'
+  | 'cross';
+
+/**
+ * The shapes a sample's own dot can take, which is how a second grouping of
+ * the same samples is drawn while colour keeps the first.
+ */
+export type OverlaySampleShape = Extract<
+  OverlayMarkShape,
+  'dot' | 'square' | 'triangle' | 'diamond' | 'triangle-down'
+>;
 
 /**
  * Every mark, in the order a picker offers them.
  *
- * The first three separate one filled thing from another by colour alone; the
- * last three carry a second meaning on one figure — a line for a component
- * beside dots for the samples — which is what keeps a figure readable when the
- * colours run out or the reader does not separate two of them.
+ * The filled ones come first and separate one thing from another by colour or
+ * by outline alone; the last three carry a second meaning on one figure — a
+ * line for a component beside dots for the samples — which is what keeps a
+ * figure readable when the colours run out or the reader does not separate two
+ * of them.
  */
 export const OVERLAY_MARK_SHAPES: readonly OverlayMarkShape[] = [
   'dot',
   'ring',
   'square',
+  'triangle',
+  'diamond',
+  'triangle-down',
   'line',
   'dashed',
   'cross',
 ];
 
+/**
+ * The shapes a second grouping is given, in the order its groups are listed.
+ *
+ * Five, because that is about where a reader stops telling small shapes apart
+ * at a glance. None of them is a ring or a cross: a ring is a sample placed
+ * into a finished model and a cross is a group's average, and a sample drawn
+ * as either would be read as one of those.
+ */
+export const OVERLAY_SAMPLE_SHAPES: readonly OverlaySampleShape[] = [
+  'dot',
+  'square',
+  'triangle',
+  'diamond',
+  'triangle-down',
+];
+
 /**
  * Whether a mark is drawn as a solid area rather than as a stroke.
  *
@@ -39,5 +76,13 @@ export const OVERLAY_MARK_SHAPES: readonly OverlayMarkShape[] = [
  * @returns `true` for the filled marks, `false` for the drawn ones.
  */
 export function isFilledMark(shape: OverlayMarkShape): boolean {
-  return shape === 'dot' || shape === 'square';
+  return FILLED_MARKS.has(shape);
 }
+
+const FILLED_MARKS: ReadonlySet<OverlayMarkShape> = new Set<OverlayMarkShape>([
+  'dot',
+  'square',
+  'triangle',
+  'diamond',
+  'triangle-down',
+]);

package/src/overlay/ui/OverlayLegendMark.tsx

@@ -73,6 +73,11 @@ const MARK_GEOMETRY: Record<OverlayMarkShape, ReactElement> = {
   dot: <circle cx="6" cy="6" r="4.2" />,
   ring: <circle cx="6" cy="6" r="3.4" strokeWidth="2.2" />,
   square: <rect x="2" y="2" width="8" height="8" rx="1.5" />,
+  // Balanced on the centre of the box, as the dots they name are balanced on
+  // their samples.
+  triangle: <path d="M6 0.8L10.5 8.6L1.5 8.6Z" />,
+  diamond: <path d="M6 1L11 6L6 11L1 6Z" />,
+  'triangle-down': <path d="M1.5 3.4L10.5 3.4L6 11.2Z" />,
   line: <line x1="0.5" y1="6" x2="11.5" y2="6" strokeWidth="2.8" />,
   dashed: (
     <line

package/src/pedagogy/ui/ReferenceSectionBlock.tsx

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactElement } from 'react';
 
+import { ClickToCopy } from '../../clipboard/ui/ClickToCopy.tsx';
 import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 
@@ -108,7 +109,15 @@ function ReferenceRowLine(props: {
   const interactive = row.tooltip !== undefined;
   const line = (
     <span style={interactive ? INTERACTIVE_ROW_STYLE : ROW_STYLE}>
-      <span style={syntaxStyle(width, interactive)}>{row.syntax}</span>
+      <span style={syntaxStyle(width, interactive)}>
+        <ClickToCopy
+          value={row.syntax}
+          label="syntax"
+          title={interactive ? '' : undefined}
+        >
+          {row.syntax}
+        </ClickToCopy>
+      </span>
       <span style={DESCRIPTION_STYLE}>{row.description}</span>
     </span>
   );

package/src/projection/core/index.ts

@@ -35,13 +35,15 @@ export type { ProjectionCopy } from './projectionCopy.ts';
 export { PROJECTION_COPY } from './projectionCopy.ts';
 export type { ProjectionCopyPatch } from './projectionCopyPatch.ts';
 export type {
-  ProjectionColorBy,
   ProjectionOptionId,
   ProjectionOptions,
   ProjectionVariablesView,
 } from './projectionOptions.ts';
 export { mergeProjectionCopy } from './mergeProjectionCopy.ts';
-export { DEFAULT_PROJECTION_OPTIONS } from './projectionOptions.ts';
+export {
+  DEFAULT_PROJECTION_OPTIONS,
+  NO_GROUPING,
+} from './projectionOptions.ts';
 export type {
   ProjectionChoiceWords,
   ProjectionOutlineWords,
@@ -56,10 +58,16 @@ export type {
 } from './projectionResult.ts';
 export type {
   ProjectionField,
+  ProjectionGrouping,
   ProjectionSamples,
   ResolvedProjectionGroups,
+  ResolvedProjectionShapes,
 } from './projectionSamples.ts';
-export { resolveProjectionGroups } from './projectionSamples.ts';
+export {
+  projectionGrouping,
+  resolveProjectionGroups,
+  resolveProjectionShapes,
+} from './projectionGroupings.ts';
 export type {
   ProjectionBarWords,
   ProjectionHelp,

package/src/projection/core/projectionCopy.ts

@@ -86,6 +86,8 @@ export interface ProjectionCopy {
     projected: string;
     /** The title of a key whose colour stands for nothing, so only shape is left. */
     shapes: string;
+    /** What the shape stands for, after what the colour does. Carries `{shapes}`. */
+    shapedBy: string;
   };
   /** The sentences the viewer builds from the data. */
   sentence: {
@@ -208,6 +210,7 @@ export const PROJECTION_COPY: ProjectionCopy = {
     notOutlined: 'Not outlined: too few samples.',
     projected: 'Hollow = added after the map was built',
     shapes: 'Shape = what each mark is.',
+    shapedBy: 'Shape = {shapes}.',
   },
   sentence: {
     sharesFirst:

package/src/projection/core/projectionGroupings.ts

@@ -0,0 +1,174 @@
+/**
+ * How the groupings a page hands in become what a figure draws: the one that
+ * colours the dots, painted from the shared palette, and the one that shapes
+ * them, given one shape per group.
+ *
+ * Both are cut the same way — the page's own order first, then every group in
+ * the order its first row names it — so a group keeps its colour and its shape
+ * however the rows are filtered.
+ */
+
+import {
+  CHART_SERIES_COLORS,
+  chartSeriesColor,
+} from '../../chart/core/chartPalette.ts';
+import { OVERLAY_SAMPLE_SHAPES } from '../../overlay/core/overlayMarks.ts';
+
+import type {
+  ProjectionGrouping,
+  ProjectionSamples,
+  ResolvedProjectionGroups,
+  ResolvedProjectionShapes,
+} from './projectionSamples.ts';
+
+/**
+ * The grouping a set of samples is coloured by, in a shape a legend and a plot
+ * can both read.
+ *
+ * A group named in `order` but held by no row is kept, so a legend does not
+ * reshuffle when a filter empties one; a row naming a group that is not in
+ * `order` is appended in the order it appears.
+ * @param grouping - The grouping, or nothing when the dots are not coloured.
+ * @param count - How many rows there are, which is the score matrix's height.
+ * @returns The resolved groups. No grouping gives no entries at all, and every
+ * row lands at `-1`.
+ */
+export function resolveProjectionGroups(
+  grouping: ProjectionGrouping | undefined,
+  count: number,
+): ResolvedProjectionGroups {
+  const { label, entries, rowOf } = partition(grouping, count);
+  const colored = entries.map((entry) => ({ ...entry, color: '' }));
+  paintGroups(colored, grouping?.colors);
+  return { label, entries: colored, groupOf: rowOf };
+}
+
+/**
+ * The grouping a set of samples is shaped by, one shape per group.
+ *
+ * A grouping of more groups than there are shapes is refused as a whole rather
+ * than drawn with two groups sharing a shape, or with the last ones falling
+ * back to a disc: either would put two groups under one mark, which is the one
+ * thing a key cannot undo.
+ * @param grouping - The grouping, or nothing when the dots are not shaped.
+ * @param count - How many rows there are, which is the score matrix's height.
+ * @returns The resolved shapes, or `null` when there is no grouping or its
+ * groups outnumber the shapes.
+ */
+export function resolveProjectionShapes(
+  grouping: ProjectionGrouping | undefined,
+  count: number,
+): ResolvedProjectionShapes | null {
+  if (grouping === undefined) return null;
+  const { label, entries, rowOf } = partition(grouping, count);
+  if (entries.length > OVERLAY_SAMPLE_SHAPES.length) return null;
+  const shaped = entries.map((entry, index) => ({
+    ...entry,
+    shape: OVERLAY_SAMPLE_SHAPES[index] ?? 'dot',
+  }));
+  return { label, entries: shaped, shapeOf: rowOf };
+}
+
+/**
+ * The grouping carrying an id.
+ * @param samples - Who the rows are.
+ * @param id - The id asked for.
+ * @returns The grouping, or `undefined` when none carries it.
+ */
+export function projectionGrouping(
+  samples: ProjectionSamples,
+  id: string,
+): ProjectionGrouping | undefined {
+  for (const grouping of samples.groupings ?? NO_GROUPINGS) {
+    if (grouping.id === id) return grouping;
+  }
+  return undefined;
+}
+
+const NO_GROUP = -1;
+const DEFAULT_GROUP_LABEL = 'Group';
+const NO_GROUPINGS: readonly ProjectionGrouping[] = [];
+
+interface GroupEntry {
+  id: string;
+  label: string;
+  count: number;
+}
+
+interface ColoredEntry extends GroupEntry {
+  color: string;
+}
+
+function partition(
+  grouping: ProjectionGrouping | undefined,
+  count: number,
+): { label: string; entries: GroupEntry[]; rowOf: Int32Array } {
+  const rowCount = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;
+  const label = grouping?.label ?? DEFAULT_GROUP_LABEL;
+  const rowOf = new Int32Array(rowCount).fill(NO_GROUP);
+  const entries: GroupEntry[] = [];
+  if (grouping === undefined) return { label, entries, rowOf };
+
+  const indexOfGroup = new Map<string, number>();
+  for (const id of grouping.order ?? []) {
+    appendGroup(entries, indexOfGroup, id);
+  }
+  for (let row = 0; row < rowCount; row++) {
+    const id = grouping.groups[row];
+    if (id === undefined) continue;
+    const at = appendGroup(entries, indexOfGroup, id);
+    rowOf[row] = at;
+    const entry = entries[at];
+    if (entry !== undefined) entry.count++;
+  }
+  return { label, entries, rowOf };
+}
+
+function appendGroup(
+  entries: GroupEntry[],
+  indexOfGroup: Map<string, number>,
+  id: string,
+): number {
+  const known = indexOfGroup.get(id);
+  if (known !== undefined) return known;
+  const at = entries.length;
+  indexOfGroup.set(id, at);
+  entries.push({ id, label: id, count: 0 });
+  return at;
+}
+
+function paintGroups(
+  entries: ColoredEntry[],
+  pinned: Readonly<Record<string, string>> | undefined,
+): void {
+  // Every pinned colour is taken out of the palette before any group draws
+  // from it, so pinning the third group's hue onto the first does not leave
+  // two groups wearing it.
+  const taken = new Set<string>();
+  if (pinned !== undefined) {
+    for (const entry of entries) {
+      const color = pinned[entry.id];
+      if (color !== undefined) taken.add(color.toLowerCase());
+    }
+  }
+
+  let cursor = 0;
+  for (const entry of entries) {
+    const own = pinned?.[entry.id];
+    if (own !== undefined) {
+      entry.color = own;
+      continue;
+    }
+    let color = chartSeriesColor(cursor, 'group');
+    while (
+      cursor < CHART_SERIES_COLORS.length &&
+      taken.has(color.toLowerCase())
+    ) {
+      cursor++;
+      color = chartSeriesColor(cursor, 'group');
+    }
+    cursor++;
+    taken.add(color.toLowerCase());
+    entry.color = color;
+  }
+}

package/src/projection/core/projectionOptions.ts

@@ -14,10 +14,10 @@ export type ProjectionVariablesView =
   | 'sample';
 
 /**
- * What decides a dot's colour on the map: `'group'`, `'none'`, or nothing else
- * in this release.
+ * The word for "no grouping" wherever an option names one, which is why no
+ * grouping may be called it.
  */
-export type ProjectionColorBy = 'group' | 'none';
+export const NO_GROUPING = 'none';
 
 /** What the figure is currently showing. Every field is a control in the floating bar. */
 export interface ProjectionOptions {
@@ -43,10 +43,20 @@ export interface ProjectionOptions {
    */
   cloudGesture: CloudGesture;
   /**
-   * What decides a dot's colour.
-   * @default 'group'
+   * Which grouping colours the dots, by its id, or `'none'`. An id no grouping
+   * carries — the empty string, or one saved on other data — takes the first
+   * grouping.
+   * @default ''
    */
-  colorBy: ProjectionColorBy;
+  colorBy: string;
+  /**
+   * Which grouping gives the dots their shapes, by its id, or `'none'`. An id
+   * no grouping carries takes the second grouping — the first when the colour
+   * has taken the second — and a grouping of more groups than there are
+   * shapes is not drawn.
+   * @default ''
+   */
+  shapeBy: string;
   /**
    * How large the group outlines are, or `null` for none.
    * @default { kind: 'coverage', probability: 0.95 }
@@ -134,7 +144,8 @@ export const DEFAULT_PROJECTION_OPTIONS: ProjectionOptions = {
   yAxis: 1,
   zAxis: 2,
   cloudGesture: 'turn',
-  colorBy: 'group',
+  colorBy: '',
+  shapeBy: '',
   ellipse: { kind: 'coverage', probability: 0.95 },
   pointRadius: 3.5,
   showGroupMeans: false,

package/src/projection/core/projectionPanelWords.ts

@@ -44,6 +44,12 @@ export interface ProjectionPanelWords {
 export interface ProjectionReasonWords {
   /** Why the colour cannot be set: the samples carry no groups. */
   noGroups: string;
+  /** Why the shape cannot be set: the samples carry no groups. */
+  noGroupsToShape: string;
+  /** Why a grouping is greyed in the shape picker: the colour already draws it. */
+  shapeIsColour: string;
+  /** Why a grouping is greyed in the shape picker: it has more groups than shapes. */
+  tooManyShapes: string;
   /** Why the map's outlines cannot be set while nothing is coloured. */
   uncolouredOutlines: string;
   /** Why the cloud's shells cannot be set while nothing is coloured. */
@@ -97,6 +103,7 @@ export const PROJECTION_PANEL_WORDS: ProjectionPanelWords = {
     zAxis: 'Into',
     cloudGesture: 'Drag does',
     colorBy: 'Colour by',
+    shapeBy: 'Shape by',
     ellipse: 'Outlines',
     pointRadius: 'Dot size',
     showGroupMeans: 'Averages',
@@ -124,6 +131,9 @@ export const PROJECTION_PANEL_WORDS: ProjectionPanelWords = {
 /** The reasons a greyed control gives when a site overrides nothing. */
 export const PROJECTION_REASON_WORDS: ProjectionReasonWords = {
   noGroups: 'These samples carry no groups to colour by.',
+  noGroupsToShape: 'These samples carry no groups to shape by.',
+  shapeIsColour: 'The colour already stands for these groups.',
+  tooManyShapes: 'More groups than there are shapes to tell apart.',
   uncolouredOutlines:
     'Outlines follow the groups, so colour the map by them first.',
   uncolouredShells: