react-cheminfo 0.3.0 → 0.4.0

package/src/pedagogy/ui/TutorialStepStrip.tsx

@@ -0,0 +1,230 @@
+import { Button, Tag, Tooltip } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import type { ExerciseLevel, TutorialStep } from '../core/types.ts';
+
+import { LEVEL_ORDER } from './exerciseMeta.ts';
+import type { TutorialLevelColours } from './tutorialLevels.ts';
+import { TUTORIAL_LEVEL_COLOURS } from './tutorialLevels.ts';
+
+export interface TutorialStepStripProps {
+  /** The whole tour, in teaching order. */
+  steps: readonly TutorialStep[];
+  /**
+   * Which step is open, as its position in `steps`. A position outside the
+   * tour is read as one of its ends, so a hand-edited link still opens.
+   */
+  activeIndex: number;
+  /** Called with the position of the step to open. */
+  onSelect: (index: number) => void;
+  /**
+   * What each strip is called — `Basics`, `π bonds, planarity, conjugation`.
+   * @default undefined — the level names its own strip
+   */
+  levelLabels?: Partial<Record<ExerciseLevel, string>>;
+  /**
+   * Whether Previous and Next sit under the strips. Both exist on purpose: the
+   * strips show the shape of the course and let a lecturer jump into it, the
+   * pager is how a student actually walks through it.
+   * @default true
+   */
+  pager?: boolean;
+  /**
+   * A word after the pager, for a tool whose steps also answer the keyboard.
+   * @default undefined
+   */
+  pagerHint?: ReactNode;
+  /**
+   * Class the strips carry, so a site can reach them from its stylesheet.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The numbered steps of the tour, one coloured strip per level, plus a pager.
+ * @param props - The tour, the open step, and how to move.
+ * @returns The strips and the pager.
+ */
+export function TutorialStepStrip(props: TutorialStepStripProps): ReactElement {
+  const {
+    steps,
+    activeIndex,
+    onSelect,
+    levelLabels,
+    pager = true,
+    pagerHint,
+    className,
+  } = props;
+  const active = clampIndex(activeIndex, steps.length);
+
+  return (
+    <div className={className} style={ROOT_STYLE}>
+      {LEVEL_ORDER.map((level) => {
+        const positions = positionsOfLevel(steps, level);
+        if (positions.length === 0) return null;
+        return (
+          <LevelStrip
+            key={level}
+            steps={steps}
+            positions={positions}
+            colours={TUTORIAL_LEVEL_COLOURS[level]}
+            label={levelLabels?.[level] ?? level}
+            activeIndex={active}
+            onSelect={onSelect}
+          />
+        );
+      })}
+
+      {pager && (
+        <div style={PAGER_STYLE}>
+          <Button
+            size="small"
+            icon="chevron-left"
+            text="Previous"
+            disabled={active === 0}
+            onClick={() => {
+              onSelect(active - 1);
+            }}
+          />
+          <Tag minimal round>
+            {`Step ${active + 1} of ${steps.length}`}
+          </Tag>
+          <Button
+            size="small"
+            endIcon="chevron-right"
+            text="Next"
+            intent="primary"
+            disabled={active >= steps.length - 1}
+            onClick={() => {
+              onSelect(active + 1);
+            }}
+          />
+          {pagerHint !== undefined && (
+            <span style={HINT_STYLE}>{pagerHint}</span>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface LevelStripProps {
+  steps: readonly TutorialStep[];
+  positions: readonly number[];
+  colours: TutorialLevelColours;
+  label: string;
+  activeIndex: number;
+  onSelect: (index: number) => void;
+}
+
+function LevelStrip(props: LevelStripProps): ReactElement {
+  const { steps, positions, colours, label, activeIndex, onSelect } = props;
+  const buttons: ReactNode[] = [];
+  for (const position of positions) {
+    const step = steps[position] as TutorialStep;
+    const active = position === activeIndex;
+    buttons.push(
+      <Tooltip
+        key={step.id}
+        content={step.title}
+        hoverOpenDelay={HOVER_OPEN_DELAY}
+        placement="bottom"
+      >
+        <button
+          type="button"
+          aria-label={`Step ${position + 1}: ${step.title}`}
+          aria-current={active ? 'step' : undefined}
+          style={numberStyle(colours, active)}
+          onClick={() => {
+            onSelect(position);
+          }}
+        >
+          {position + 1}
+        </button>
+      </Tooltip>,
+    );
+  }
+
+  return (
+    <div style={{ ...STRIP_STYLE, background: colours.background }}>
+      <span style={LABEL_STYLE}>{label}</span>
+      {buttons}
+    </div>
+  );
+}
+
+function positionsOfLevel(
+  steps: readonly TutorialStep[],
+  level: ExerciseLevel,
+): number[] {
+  const positions: number[] = [];
+  for (let index = 0; index < steps.length; index++) {
+    if (steps[index]?.level === level) positions.push(index);
+  }
+  return positions;
+}
+
+function clampIndex(index: number, total: number): number {
+  if (!Number.isFinite(index) || index <= 0) return 0;
+  return Math.min(Math.floor(index), Math.max(total - 1, 0));
+}
+
+/**
+ * The open step takes the darker shade of its own level, plus a border.
+ * @param colours - The two shades of the level the step belongs to.
+ * @param active - Whether this is the step on screen.
+ * @returns The style of one numbered button.
+ */
+function numberStyle(
+  colours: TutorialLevelColours,
+  active: boolean,
+): CSSProperties {
+  return {
+    background: active ? colours.activeBackground : '#ffffff',
+    border: active ? '2px solid #1c2127' : '1px solid rgb(17 20 24 / 20%)',
+    borderRadius: 4,
+    color: '#1c2127',
+    cursor: 'pointer',
+    font: 'inherit',
+    fontSize: 12,
+    fontWeight: active ? 700 : 500,
+    lineHeight: 1,
+    minWidth: 26,
+    padding: active ? '5px 6px' : '6px 7px',
+  };
+}
+
+/** Long enough that the pointer can cross the strip without opening a title. */
+const HOVER_OPEN_DELAY = 150;
+
+const ROOT_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+};
+
+const STRIP_STYLE: CSSProperties = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 4,
+  borderRadius: 4,
+  padding: '4px 6px',
+};
+
+const LABEL_STYLE: CSSProperties = {
+  flex: '0 0 220px',
+  fontSize: 12,
+  fontWeight: 600,
+  color: '#1c2127',
+};
+
+const PAGER_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+  paddingTop: 2,
+};
+
+const HINT_STYLE: CSSProperties = { color: '#5b6875', fontSize: 11 };

package/src/pedagogy/ui/exerciseMeta.ts

@@ -0,0 +1,45 @@
+/**
+ * What a level and a status look like, in one place.
+ *
+ * A level means the same thing in the tutorial, in the exercise list and on the
+ * cheatsheet, so it is coloured from here rather than decided again per page.
+ */
+
+import type { IconName, Intent } from '@blueprintjs/core';
+
+import type { ExerciseLevel, ExerciseStatus } from '../core/types.ts';
+
+/** Green for a beginner, amber for an intermediate, red for an advanced one. */
+export const LEVEL_INTENT: Record<ExerciseLevel, Intent> = {
+  beginner: 'success',
+  intermediate: 'warning',
+  advanced: 'danger',
+};
+
+/** The three levels in teaching order, for a page listing all of them. */
+export const LEVEL_ORDER: readonly ExerciseLevel[] = [
+  'beginner',
+  'intermediate',
+  'advanced',
+];
+
+/** An empty circle, a warning sign, a tick: untouched, handed in, right. */
+export const STATUS_ICON: Record<ExerciseStatus, IconName> = {
+  idle: 'circle',
+  attempted: 'warning-sign',
+  solved: 'tick-circle',
+};
+
+/**
+ * Colour per status.
+ *
+ * `idle` is the one uncoloured value in the package: an exercise nobody has
+ * opened has nothing to report, and painting it would make a fresh list read as
+ * a list of mistakes. Every other value keeps its colour wherever it is shown,
+ * including on a tag that is switched off.
+ */
+export const STATUS_INTENT: Record<ExerciseStatus, Intent> = {
+  idle: 'none',
+  attempted: 'warning',
+  solved: 'success',
+};

package/src/pedagogy/ui/glossaryContext.ts

@@ -0,0 +1,23 @@
+/**
+ * Where the terms a site defines are kept while the page is open.
+ *
+ * Prose is rendered deep inside a card, a callout or a tooltip, and threading
+ * the glossary down to each of those as a prop is what makes a site stop
+ * linking its jargon. It is read from the surrounding provider instead.
+ */
+
+import { createContext, useContext } from 'react';
+
+import type { Glossary } from '../core/glossary.ts';
+
+/**
+ * The glossary the surrounding provider holds.
+ * @returns Every term the site defines, and no term at all when nothing wraps
+ * the tree — prose then renders its markers as plain words.
+ */
+export function useGlossary(): Glossary {
+  return useContext(GlossaryContext);
+}
+
+/** Holder of the glossary, written by `GlossaryProvider` and read by prose. */
+export const GlossaryContext = createContext<Glossary>({});

package/src/pedagogy/ui/index.ts

@@ -0,0 +1,37 @@
+export type { ExerciseActionsProps } from './ExerciseActions.tsx';
+export { ExerciseActions } from './ExerciseActions.tsx';
+export type { ExerciseProgressHeaderProps } from './ExerciseProgressHeader.tsx';
+export { ExerciseProgressHeader } from './ExerciseProgressHeader.tsx';
+export type {
+  ExerciseLevelTagProps,
+  ExerciseStatusIconProps,
+} from './ExerciseTags.tsx';
+export { ExerciseLevelTag, ExerciseStatusIcon } from './ExerciseTags.tsx';
+export { LEVEL_INTENT, LEVEL_ORDER, STATUS_ICON } from './exerciseMeta.ts';
+export type { GlossaryProviderProps } from './GlossaryProvider.tsx';
+export { GlossaryProvider } from './GlossaryProvider.tsx';
+export type { GlossaryTextProps } from './GlossaryText.tsx';
+export { GlossaryText } from './GlossaryText.tsx';
+export { useGlossary } from './glossaryContext.ts';
+export type { HintLadderProps } from './HintLadder.tsx';
+export { HintLadder } from './HintLadder.tsx';
+export type { ReferenceGridProps } from './ReferenceGrid.tsx';
+export { ReferenceGrid } from './ReferenceGrid.tsx';
+export type {
+  ReferenceRow,
+  ReferenceSection,
+  ReferenceSectionBlockProps,
+} from './ReferenceSectionBlock.tsx';
+export { ReferenceSectionBlock } from './ReferenceSectionBlock.tsx';
+export type {
+  SyntaxTooltipContent,
+  SyntaxTooltipExample,
+  SyntaxTooltipProps,
+} from './SyntaxTooltip.tsx';
+export { SyntaxTooltip } from './SyntaxTooltip.tsx';
+export type { TestCaseListProps } from './TestCaseList.tsx';
+export { TestCaseList } from './TestCaseList.tsx';
+export type { TutorialStepStripProps } from './TutorialStepStrip.tsx';
+export { TutorialStepStrip } from './TutorialStepStrip.tsx';
+export type { TutorialLevelColours } from './tutorialLevels.ts';
+export { TUTORIAL_LEVEL_COLOURS } from './tutorialLevels.ts';

package/src/pedagogy/ui/tutorialLevels.ts

@@ -0,0 +1,27 @@
+/**
+ * The two shades each level of the guided tour is painted in.
+ *
+ * Green, amber, pink — the same three the level tags use, in the pale weights a
+ * strip of buttons can sit on. They are shared so a student moving from one of
+ * our tools to the next reads the shape of the course the same way.
+ */
+
+import type { ExerciseLevel } from '../core/types.ts';
+
+/** How one level is painted. */
+export interface TutorialLevelColours {
+  /** Behind the whole strip. */
+  background: string;
+  /** Behind the step that is open, which is the darker of the two. */
+  activeBackground: string;
+}
+
+/** The palette of the three levels. */
+export const TUTORIAL_LEVEL_COLOURS: Record<
+  ExerciseLevel,
+  TutorialLevelColours
+> = {
+  beginner: { background: '#d1fae5', activeBackground: '#6ee7b7' },
+  intermediate: { background: '#fef3c7', activeBackground: '#fcd34d' },
+  advanced: { background: '#fce7f3', activeBackground: '#f9a8d4' },
+};

package/src/router/core/address.ts

@@ -0,0 +1,74 @@
+/** An address cut into the three parts a router reads separately. */
+export interface AddressParts {
+  /** Path of the address, `/` when it carries none. */
+  path: string;
+  /** Query string, without its leading `?`. */
+  search: string;
+  /** Fragment, without its leading `#`. */
+  fragment: string;
+}
+
+/**
+ * Cut an address into its path, its query and its fragment.
+ *
+ * The fragment is taken first, so a `?` inside it — an old hash link of the
+ * shape `#/tutorial/3?step=2` — stays part of the fragment rather than being
+ * read as the query of the page.
+ * @param address - A path, a full address, or a bare query string.
+ * @returns The three parts, each without its separator.
+ */
+export function splitAddress(address: string): AddressParts {
+  const hashIndex = address.indexOf('#');
+  const beforeHash = hashIndex === -1 ? address : address.slice(0, hashIndex);
+  const fragment = hashIndex === -1 ? '' : address.slice(hashIndex + 1);
+  const queryIndex = beforeHash.indexOf('?');
+  if (queryIndex === -1) {
+    return { path: beforeHash === '' ? '/' : beforeHash, search: '', fragment };
+  }
+  const path = beforeHash.slice(0, queryIndex);
+  return {
+    path: path === '' ? '/' : path,
+    search: beforeHash.slice(queryIndex + 1),
+    fragment,
+  };
+}
+
+/**
+ * The decoded, non-empty segments of a path.
+ * @param path - Path of an address, with or without its leading slash.
+ * @returns One entry per segment, `[]` for the root.
+ */
+export function splitPath(path: string): string[] {
+  const segments: string[] = [];
+  for (const raw of path.split('/')) {
+    if (raw !== '') segments.push(safeDecode(raw));
+  }
+  return segments;
+}
+
+/**
+ * A path in the one shape the lookups compare: a leading slash, no trailing
+ * one, its segments decoded, and neither query nor fragment.
+ * @param path - Path of an address.
+ * @returns The same address, normalized.
+ */
+export function normalizePath(path: string): string {
+  const segments = splitPath(splitAddress(path).path);
+  return segments.length === 0 ? '/' : `/${segments.join('/')}`;
+}
+
+/**
+ * Decode one component of an address, tolerating an escape that is not one.
+ *
+ * `decodeURIComponent` throws on a lone `%`, and an address is hand-editable:
+ * the raw text is closer to what its author meant than an error page.
+ * @param value - Raw, percent-encoded text.
+ * @returns The decoded text, or the raw text when it does not decode.
+ */
+export function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}

package/src/router/core/basePath.ts

@@ -0,0 +1,76 @@
+/**
+ * Where a site is mounted, read off the page rather than off the build.
+ *
+ * The build is mount-agnostic — vite is given a relative base, so the same
+ * `dist` serves `https://surge.cheminfo.org/` and
+ * `https://www.cheminfo.org/surge/`. What tells the two apart is the `<base>`
+ * the deployment stamps into the page it hands out, and `document.baseURI`
+ * resolves it against the address actually opened. So this answers correctly
+ * whether or not a slash closes the address, and on an address the SPA
+ * fallback answered.
+ * @returns The mount path, in the shape {@link normalizeBasePath} returns.
+ */
+export function readMountPath(): string {
+  const baseUri = globalThis.document?.baseURI;
+  if (!baseUri) return '';
+  return normalizeBasePath(new URL(baseUri).pathname);
+}
+
+/**
+ * The path half of a site's address, as a mount path.
+ *
+ * A deployment names where it serves the site in full — origin and path in one
+ * value — because the origin is what the canonical link and the sitemap need.
+ * This is the other half of it.
+ * @param siteUrl - The absolute address the site is served at.
+ * @returns The mount path, in the shape {@link normalizeBasePath} returns.
+ */
+export function basePathOf(siteUrl: string): string {
+  return normalizeBasePath(new URL(siteUrl).pathname);
+}
+
+/**
+ * A mount path in the shape the other helpers assume: the empty string when the
+ * site owns the root of its host, `/surge` when it is one tool among several on
+ * a shared one.
+ * @param basePath - The mount path however it was written: `surge`, `/surge`, `/surge/`.
+ * @returns The normalized mount path, without a trailing slash.
+ */
+export function normalizeBasePath(basePath: string): string {
+  const trimmed = basePath.trim();
+  if (trimmed === '' || trimmed === '/') return '';
+  const opened = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  return opened.replace(/\/+$/, '');
+}
+
+/**
+ * Move one of the site's own addresses under the path it is mounted at.
+ * @param basePath - The mount path, in any of the shapes {@link normalizeBasePath} accepts.
+ * @param path - An address from the site's own root, e.g. `/exercises`.
+ * @returns The address the browser and the server see, e.g. `/surge/exercises`.
+ */
+export function joinBasePath(basePath: string, path: string): string {
+  const base = normalizeBasePath(basePath);
+  const opened = path === '' || !path.startsWith('/') ? `/${path}` : path;
+  if (base === '') return opened;
+  return opened === '/' ? `${base}/` : `${base}${opened}`;
+}
+
+/**
+ * Read one of the site's own addresses back out of a browser path.
+ *
+ * A path that does not sit under the mount is handed back untouched, so a
+ * deployment served from somewhere else than the build was told still routes.
+ * @param basePath - The mount path, in any of the shapes {@link normalizeBasePath} accepts.
+ * @param pathname - The path the browser is on, e.g. `/surge/exercises`.
+ * @returns The address from the site's own root, `/` for the mount itself.
+ */
+export function stripBasePath(basePath: string, pathname: string): string {
+  const base = normalizeBasePath(basePath);
+  const path = pathname === '' ? '/' : pathname;
+  if (base === '') return path;
+  if (path === base || path === `${base}/`) return '/';
+  // `/surgeon` is not a page of a site mounted at `/surge`, so the mount only
+  // matches when what follows it is a path of its own.
+  return path.startsWith(`${base}/`) ? path.slice(base.length) : path;
+}

package/src/router/core/index.ts

@@ -0,0 +1,26 @@
+export {
+  basePathOf,
+  joinBasePath,
+  normalizeBasePath,
+  readMountPath,
+  stripBasePath,
+} from './basePath.ts';
+export type {
+  AdoptLegacyHashOptions,
+  LegacyHashOptions,
+} from './legacyHash.ts';
+export { adoptLegacyHashAddress, pathFromLegacyHash } from './legacyHash.ts';
+export type {
+  PageAddresses,
+  PageAddressesOptions,
+  PageWithPath,
+} from './pageAddresses.ts';
+export { createPageAddresses } from './pageAddresses.ts';
+export type {
+  TabDefinition,
+  TabRoute,
+  TabRouteInput,
+  TabRouter,
+  TabRouterOptions,
+} from './tabRouter.ts';
+export { createTabRouter } from './tabRouter.ts';

package/src/router/core/legacyHash.ts

@@ -0,0 +1,77 @@
+import { splitAddress } from './address.ts';
+import { normalizeBasePath, stripBasePath } from './basePath.ts';
+
+/** How a legacy hash link is turned into the path it means. */
+export interface LegacyHashOptions {
+  /**
+   * Carry the query string of the address over to the path. The share
+   * configuration lives there, so an embed stays configured across the move.
+   * A query written inside the fragment itself always wins over it.
+   * @default true
+   */
+  keepSearch?: boolean;
+}
+
+/** How an address is read when adopting the path a legacy hash link meant. */
+export interface AdoptLegacyHashOptions extends LegacyHashOptions {
+  /**
+   * The path the site is mounted at, so a legacy link to a tool served under
+   * one is recognised as sitting on its root.
+   * @default ''
+   */
+  basePath?: string;
+}
+
+/**
+ * The path a link written before the site routed by path points at.
+ *
+ * Those links are in course pages, in bookmarks and inside other people's
+ * iframes, so they are answered rather than dropped. Only a fragment shaped
+ * like a path is one: an anchor such as `#results` names a place inside a page
+ * and comes back `null`.
+ * @param address - A full address, or the fragment on its own, e.g. `/#/tutorial/3`.
+ * @param options - Whether the query string is carried over.
+ * @returns The path form of the address, or `null` when it names no page.
+ */
+export function pathFromLegacyHash(
+  address: string,
+  options: LegacyHashOptions = {},
+): string | null {
+  const outer = splitAddress(address);
+  if (outer.fragment === '' || !outer.fragment.startsWith('/')) return null;
+
+  const inner = splitAddress(outer.fragment);
+  if (inner.path === '/') return null;
+
+  const keepSearch = options.keepSearch ?? true;
+  const search = inner.search || (keepSearch ? outer.search : '');
+  return search === '' ? inner.path : `${inner.path}?${search}`;
+}
+
+/**
+ * The address to put in the bar in place of a legacy hash link, before anything
+ * reads it.
+ *
+ * Called once at startup with `location.pathname + location.search +
+ * location.hash`, so nothing downstream has to know the site ever routed by the
+ * hash. Only a visitor sitting on the site's root is moved: a fragment on a
+ * real page is an anchor of that page, not an address of its own.
+ * @param address - The address the browser is on.
+ * @param options - Whether the query is carried over, and the site's mount path.
+ * @returns The address to replace it with, or `null` when there is nothing to adopt.
+ */
+export function adoptLegacyHashAddress(
+  address: string,
+  options: AdoptLegacyHashOptions = {},
+): string | null {
+  const basePath = normalizeBasePath(options.basePath ?? '');
+  if (stripBasePath(basePath, splitAddress(address).path) !== '/') return null;
+
+  const path = pathFromLegacyHash(address, options);
+  if (path === null) return null;
+  if (basePath === '') return path;
+
+  const { path: adopted, search } = splitAddress(path);
+  const mounted = `${basePath}${adopted}`;
+  return search === '' ? mounted : `${mounted}?${search}`;
+}