react-cheminfo 0.2.0 → 0.4.0

package/src/seo/core/documentMeta.ts

@@ -0,0 +1,92 @@
+/**
+ * Keep the head in step with the page on screen after an in-app move.
+ *
+ * The server, or the build that wrote one file per address, already titled the
+ * page it handed out; this is what a click inside the app changes, and what a
+ * crawler that renders the page reads afterwards. Every access to the document
+ * is guarded, so a prerender script importing this under Node does nothing
+ * rather than throwing.
+ * @param meta - What the page on screen is called and where it is indexed.
+ */
+export function writeDocumentMeta(meta: DocumentMeta): void {
+  if (typeof document === 'undefined') return;
+  documentTitle(meta.title);
+  if (meta.description !== undefined) metaDescription(meta.description);
+  if (meta.canonical !== undefined) canonicalLink(meta.canonical);
+}
+
+/**
+ * Name the browser tab.
+ * @param title - The title of the page, site name included.
+ */
+export function documentTitle(title: string): void {
+  if (typeof document === 'undefined') return;
+  document.title = title;
+}
+
+/**
+ * Point the canonical link at the address the page is indexed under, creating
+ * the tag when the served page carries none.
+ *
+ * The query string is dropped, and so is any fragment: the structure being
+ * edited and the configuration a shared link carries are not pages of their
+ * own, and indexing them as such splits one result into hundreds.
+ * @param href - The address of the page, absolute so a crawler can resolve it.
+ */
+export function canonicalLink(href: string): void {
+  if (typeof document === 'undefined') return;
+  const address = withoutQuery(href);
+  if (address === '') return;
+
+  const existing = document.querySelector<HTMLLinkElement>(
+    'link[rel="canonical"]',
+  );
+  if (existing) {
+    existing.href = address;
+    return;
+  }
+
+  const link = document.createElement('link');
+  link.rel = 'canonical';
+  document.head.append(link);
+  link.href = address;
+}
+
+/** What a page is called and where it is indexed. */
+export interface DocumentMeta {
+  /** The title of the tab, the search result and the shared card. */
+  title: string;
+  /**
+   * One sentence describing this page, in the words someone would search for.
+   * Left out, the description the page was served with stays as it is — which
+   * is what every crawler but a rendering one has already read.
+   * @default undefined
+   */
+  description?: string;
+  /**
+   * The absolute address the page is indexed under. Left out, the canonical
+   * link the page was served with stays as it is.
+   * @default undefined
+   */
+  canonical?: string;
+}
+
+function metaDescription(content: string): void {
+  const existing = document.querySelector<HTMLMetaElement>(
+    'meta[name="description"]',
+  );
+  if (existing) {
+    existing.content = content;
+    return;
+  }
+
+  const meta = document.createElement('meta');
+  meta.name = 'description';
+  document.head.append(meta);
+  meta.content = content;
+}
+
+function withoutQuery(href: string): string {
+  const cut = href.search(/[?#]/);
+  return cut === -1 ? href : href.slice(0, cut);
+}

package/src/seo/core/index.ts

@@ -0,0 +1,6 @@
+export type { DocumentMeta } from './documentMeta.ts';
+export {
+  canonicalLink,
+  documentTitle,
+  writeDocumentMeta,
+} from './documentMeta.ts';

package/src/share/core/config.ts

@@ -0,0 +1,165 @@
+import type { QueryEntry } from './query.ts';
+import { firstValues, parseQuery, serializeQuery } from './query.ts';
+import type {
+  HideablePart,
+  ShareParamCodecs,
+  ShareParamValues,
+  ShareVocabulary,
+} from './vocabulary.ts';
+
+/** The parameter that drops the site chrome. */
+export const EMBED_PARAM = 'embed';
+
+/** The parameter listing the parts a link switches off. */
+export const HIDE_PARAM = 'hide';
+
+/** What one link says about the page it opens, beyond the tool's own inputs. */
+export interface ShareConfig<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> {
+  /** Drop the site chrome, so the page can be framed in someone else's site. */
+  embed: boolean;
+  /** The parts switched off, in the order the vocabulary lists them. */
+  hidden: readonly string[];
+  /** The tool's own parameters, each at the value the link carries or its default. */
+  params: ShareParamValues<Codecs>;
+}
+
+/**
+ * Read the configuration a link carries.
+ *
+ * Everything here is untrusted: a `hide` key the vocabulary does not list is
+ * ignored, a malformed number falls back to its default, and every number is
+ * clamped to what the tool can serve, so a link written two years ago still
+ * opens.
+ * @param search - The query string, with or without its leading `?`.
+ * @param vocabulary - What this site's links can say.
+ * @returns The configuration in force.
+ */
+export function parseShareConfig<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(search: string, vocabulary: ShareVocabulary<Codecs>): ShareConfig<Codecs> {
+  const values = firstValues(parseQuery(search));
+  const embed = values.get(EMBED_PARAM);
+  return {
+    embed: embed !== undefined && embed !== '0',
+    hidden: orderHidden(splitHidden(values.get(HIDE_PARAM)), vocabulary.parts),
+    params: readParams(values, vocabulary.params) as ShareParamValues<Codecs>,
+  };
+}
+
+/**
+ * Write a configuration into an address, leaving the tool's own inputs as they
+ * were. A parameter left at its default is deleted rather than written, so an
+ * unconfigured link stays a plain link.
+ * @param search - The address as it stands, with or without its leading `?`.
+ * @param config - The configuration to write.
+ * @param vocabulary - What this site's links can say.
+ * @returns The new query string, without its leading `?`.
+ */
+export function applyShareConfig<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(
+  search: string,
+  config: ShareConfig<Codecs>,
+  vocabulary: ShareVocabulary<Codecs>,
+): string {
+  const codecs: ShareParamCodecs = vocabulary.params ?? {};
+  const owned = new Set<string>([
+    EMBED_PARAM,
+    HIDE_PARAM,
+    ...Object.keys(codecs),
+  ]);
+  const entries: QueryEntry[] = [];
+  for (const entry of parseQuery(search)) {
+    if (!owned.has(entry[0])) entries.push(entry);
+  }
+  if (config.embed) entries.push([EMBED_PARAM, '1']);
+  const hidden = orderHidden(new Set(config.hidden), vocabulary.parts);
+  if (hidden.length > 0) entries.push([HIDE_PARAM, hidden.join(',')]);
+  const values = config.params as Readonly<Record<string, unknown>>;
+  for (const [key, codec] of Object.entries(codecs)) {
+    const raw = codec.serialize(values[key]);
+    if (raw !== null) entries.push([key, raw]);
+  }
+  return serializeQuery(entries);
+}
+
+/**
+ * Whether the link switches a part of the page off.
+ *
+ * Hidden means hidden, not disabled: the value a hidden control carries still
+ * applies, so an embedder can preset what a visitor may not change.
+ * @param config - The configuration in force.
+ * @param key - The part to test.
+ * @returns True when the part must not be rendered.
+ */
+export function isHidden(
+  config: Pick<ShareConfig, 'hidden'>,
+  key: string,
+): boolean {
+  return config.hidden.includes(key);
+}
+
+/**
+ * Whether a configuration differs from an unconfigured link.
+ * @param config - The configuration to test.
+ * @param vocabulary - What this site's links can say.
+ * @returns True when the link configures anything at all.
+ */
+export function isShareConfigured<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(config: ShareConfig<Codecs>, vocabulary: ShareVocabulary<Codecs>): boolean {
+  return applyShareConfig('', config, vocabulary) !== '';
+}
+
+/**
+ * The configuration a share dialog opens on: framed, with the parts a host
+ * page has no use for already switched off. Someone who wants the whole site
+ * is one click away; someone building a course tile should not have to tick
+ * five boxes every time.
+ * @param vocabulary - What this site's links can say.
+ * @returns The configuration to start from.
+ */
+export function suggestedShareConfig<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(vocabulary: ShareVocabulary<Codecs>): ShareConfig<Codecs> {
+  const hidden: string[] = [];
+  for (const part of vocabulary.parts) {
+    if (part.hiddenByDefault === true) hidden.push(part.key);
+  }
+  return { ...parseShareConfig('', vocabulary), embed: true, hidden };
+}
+
+function splitHidden(raw: string | undefined): ReadonlySet<string> {
+  const asked = new Set<string>();
+  if (raw === undefined) return asked;
+  for (const entry of raw.split(',')) {
+    const key = entry.trim();
+    if (key !== '') asked.add(key);
+  }
+  return asked;
+}
+
+function orderHidden(
+  asked: ReadonlySet<string>,
+  parts: readonly HideablePart[],
+): readonly string[] {
+  const hidden: string[] = [];
+  for (const part of parts) {
+    if (asked.has(part.key)) hidden.push(part.key);
+  }
+  return hidden;
+}
+
+function readParams(
+  values: ReadonlyMap<string, string>,
+  codecs: ShareParamCodecs | undefined,
+): Record<string, unknown> {
+  const params: Record<string, unknown> = {};
+  if (codecs === undefined) return params;
+  for (const [key, codec] of Object.entries(codecs)) {
+    params[key] = codec.parse(values.get(key) ?? null);
+  }
+  return params;
+}

package/src/share/core/escape.ts

@@ -0,0 +1,22 @@
+/**
+ * Escape a value written into HTML text, so a formula, a title or an address
+ * a link carries cannot close the element it sits in.
+ * @param value - The untrusted value.
+ * @returns The value with `&`, `<` and `>` replaced by their entities.
+ */
+export function escapeText(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+/**
+ * Escape a value written into a double-quoted HTML attribute, so an address
+ * carrying an ampersand or a quote cannot break out of it.
+ * @param value - The untrusted value.
+ * @returns The value with `&`, `<`, `>` and `"` replaced by their entities.
+ */
+export function escapeAttribute(value: string): string {
+  return escapeText(value).replaceAll('"', '&quot;');
+}

package/src/share/core/index.ts

@@ -0,0 +1,31 @@
+export type { ShareConfig } from './config.ts';
+export {
+  EMBED_PARAM,
+  HIDE_PARAM,
+  applyShareConfig,
+  isHidden,
+  isShareConfigured,
+  parseShareConfig,
+  suggestedShareConfig,
+} from './config.ts';
+export { escapeAttribute, escapeText } from './escape.ts';
+export type {
+  BooleanParamOptions,
+  IntegerParamOptions,
+  ShareParamCodec,
+  StringParamOptions,
+} from './params.ts';
+export {
+  booleanParam,
+  enumParam,
+  integerParam,
+  stringParam,
+} from './params.ts';
+export type { EmbedCodeOptions, ShareUrlOptions } from './url.ts';
+export { buildEmbedCode, buildShareUrl } from './url.ts';
+export type {
+  HideablePart,
+  ShareParamCodecs,
+  ShareParamValues,
+  ShareVocabulary,
+} from './vocabulary.ts';

package/src/share/core/params.ts

@@ -0,0 +1,176 @@
+/**
+ * Reads one of a tool's own parameters out of a link and writes it back.
+ *
+ * `parse` is handed the raw value, or `null` when the link does not carry the
+ * key at all, and always answers: anything absent or malformed falls back to
+ * the default. `serialize` answers `null` for a value that is already the
+ * default, which deletes the key rather than writing it, so an unconfigured
+ * link stays a plain link.
+ */
+export interface ShareParamCodec<Value> {
+  /**
+   * Read the value a link carries.
+   * @param raw - The raw parameter, `null` when the link omits it.
+   * @returns The value, or the default when it is absent or malformed.
+   */
+  parse(raw: string | null): Value;
+  /**
+   * Write the value into a link.
+   * @param value - The value to write.
+   * @returns The raw parameter, or `null` to delete the key.
+   */
+  serialize(value: Value): string | null;
+}
+
+/** What {@link booleanParam} is configured with. */
+export interface BooleanParamOptions {
+  /**
+   * The value an absent parameter reads as, and the one deleted rather than
+   * written.
+   * @default false
+   */
+  default?: boolean;
+}
+
+/**
+ * A flag a link switches on by naming it. `?flag`, `?flag=` and `?flag=1` all
+ * read as on, because these addresses are retyped by hand out of a course
+ * page; only `0` and `false` read as off.
+ * @param options - The value the flag takes when the link says nothing.
+ * @returns The codec.
+ */
+export function booleanParam(
+  options: BooleanParamOptions = {},
+): ShareParamCodec<boolean> {
+  const { default: fallback = false } = options;
+  return {
+    parse(raw) {
+      if (raw === null) return fallback;
+      const text = raw.trim().toLowerCase();
+      return text !== '0' && text !== 'false';
+    },
+    serialize(value) {
+      if (value === fallback) return null;
+      return value ? '1' : '0';
+    },
+  };
+}
+
+/** What {@link integerParam} is configured with. */
+export interface IntegerParamOptions<Fallback extends number | null> {
+  /** The smallest value a link may ask for. */
+  min: number;
+  /** The largest value a link may ask for, so a link cannot hang the page. */
+  max: number;
+  /**
+   * The value an absent or malformed parameter falls back to, and the one
+   * deleted rather than written. `null` means the tool has no value of its own
+   * until a link names one.
+   */
+  default: Fallback;
+}
+
+/**
+ * A whole number a link carries, rounded and clamped to the range the tool can
+ * actually serve. A value outside the range is brought back inside it rather
+ * than rejected: a link written when the maximum was higher must still open.
+ * @param options - The range and the default.
+ * @returns The codec.
+ */
+export function integerParam<Fallback extends number | null>(
+  options: IntegerParamOptions<Fallback>,
+): ShareParamCodec<number | Fallback> {
+  const { min, max, default: fallback } = options;
+  return {
+    parse(raw) {
+      if (raw === null) return fallback;
+      const text = raw.trim();
+      if (text === '') return fallback;
+      const parsed = Number(text);
+      if (Number.isNaN(parsed)) return fallback;
+      return clamp(parsed, min, max);
+    },
+    serialize(value) {
+      if (typeof value !== 'number' || value === fallback) return null;
+      return String(clamp(value, min, max));
+    },
+  };
+}
+
+/** What {@link stringParam} is configured with. */
+export interface StringParamOptions {
+  /**
+   * The value an absent parameter reads as, and the one deleted rather than
+   * written.
+   * @default ''
+   */
+  default?: string;
+  /**
+   * The longest value accepted; anything beyond it is cut, so a link cannot
+   * hand the tool a megabyte of text.
+   * @default undefined
+   */
+  maxLength?: number;
+}
+
+/**
+ * A free-text parameter, taken as written. The value is not trimmed: a
+ * leading space can be part of what the tool is showing.
+ * @param options - The default and the length limit.
+ * @returns The codec.
+ */
+export function stringParam(
+  options: StringParamOptions = {},
+): ShareParamCodec<string> {
+  const { default: fallback = '', maxLength } = options;
+  return {
+    parse(raw) {
+      if (raw === null) return fallback;
+      return cut(raw, maxLength);
+    },
+    serialize(value) {
+      const text = cut(value, maxLength);
+      return text === fallback ? null : text;
+    },
+  };
+}
+
+/**
+ * One of a fixed set of names — a difficulty, a display mode, a format.
+ * A name the tool does not know falls back rather than throwing, so a link
+ * written before the set changed still opens.
+ * @param values - Every name the tool understands.
+ * @param fallback - The name an absent or unknown parameter reads as.
+ * @returns The codec.
+ */
+export function enumParam<Value extends string>(
+  values: readonly Value[],
+  fallback: Value,
+): ShareParamCodec<Value> {
+  return {
+    parse(raw) {
+      if (raw === null) return fallback;
+      const text = raw.trim();
+      for (const value of values) {
+        if (value === text) return value;
+      }
+      return fallback;
+    },
+    serialize(value) {
+      if (value === fallback) return null;
+      for (const candidate of values) {
+        if (candidate === value) return value;
+      }
+      return null;
+    },
+  };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, Math.round(value)));
+}
+
+function cut(value: string, maxLength: number | undefined): string {
+  if (maxLength === undefined || value.length <= maxLength) return value;
+  return value.slice(0, maxLength);
+}

package/src/share/core/query.ts

@@ -0,0 +1,72 @@
+/** One `key=value` pair of a query string, already decoded. */
+export type QueryEntry = readonly [key: string, value: string];
+
+/**
+ * Read a query string into its pairs, in the order it wrote them.
+ *
+ * A `+` is a plus, not a space: a link carries structures such as
+ * `CC[N+](C)(C)C`, and the form-urlencoded reading of `+` would turn one into
+ * a different molecule without anything failing. A malformed escape is kept as
+ * written rather than throwing, so a link somebody retyped still opens.
+ * @param search - The query string, with or without its leading `?`, and without a fragment.
+ * @returns The pairs, decoded.
+ */
+export function parseQuery(search: string): QueryEntry[] {
+  const text = search.startsWith('?') ? search.slice(1) : search;
+  const entries: QueryEntry[] = [];
+  if (text === '') return entries;
+  for (const chunk of text.split('&')) {
+    if (chunk === '') continue;
+    const separator = chunk.indexOf('=');
+    const key = separator === -1 ? chunk : chunk.slice(0, separator);
+    const value = separator === -1 ? '' : chunk.slice(separator + 1);
+    entries.push([decodeComponent(key), decodeComponent(value)]);
+  }
+  return entries;
+}
+
+/**
+ * Write pairs back into a query string, keeping the two characters a reader
+ * of these links cares about legible: a comma stays a comma rather than
+ * `%2C`, and a plus stays a plus rather than `%2B`. Both parse back
+ * identically through {@link parseQuery}.
+ * @param entries - The pairs to write, in the order they should appear.
+ * @returns The query string, without its leading `?`.
+ */
+export function serializeQuery(entries: readonly QueryEntry[]): string {
+  const chunks: string[] = [];
+  for (const [key, value] of entries) {
+    chunks.push(`${encodeComponent(key)}=${encodeComponent(value)}`);
+  }
+  return chunks.join('&');
+}
+
+/**
+ * The first value each key carries, which is what a link means when it names
+ * the same parameter twice.
+ * @param entries - The pairs of a query string.
+ * @returns One value per key.
+ */
+export function firstValues(
+  entries: readonly QueryEntry[],
+): ReadonlyMap<string, string> {
+  const values = new Map<string, string>();
+  for (const [key, value] of entries) {
+    if (!values.has(key)) values.set(key, value);
+  }
+  return values;
+}
+
+function decodeComponent(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function encodeComponent(value: string): string {
+  return encodeURIComponent(value)
+    .replaceAll('%2C', ',')
+    .replaceAll('%2B', '+');
+}

package/src/share/core/url.ts

@@ -0,0 +1,105 @@
+import type { ShareConfig } from './config.ts';
+import { applyShareConfig } from './config.ts';
+import { escapeAttribute } from './escape.ts';
+import type { ShareParamCodecs, ShareVocabulary } from './vocabulary.ts';
+
+/** What {@link buildShareUrl} needs to write a link. */
+export interface ShareUrlOptions<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> {
+  /**
+   * Where the page is served from — origin and path. Anything from the first
+   * `?` or `#` is dropped, so the current address can be handed over as it is.
+   */
+  base: string;
+  /**
+   * The address as it stands, so the tool's own inputs travel with the link.
+   * @default ''
+   */
+  search?: string;
+  /** The configuration the link carries. */
+  config: ShareConfig<Codecs>;
+  /** What this site's links can say. */
+  vocabulary: ShareVocabulary<Codecs>;
+}
+
+/**
+ * The absolute link the share dialog hands out: the page, the tool's own
+ * inputs, and the configuration written over whatever the address carried.
+ * @param options - Where the page is, what it is showing, and how it is configured.
+ * @returns An absolute URL.
+ */
+export function buildShareUrl<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(options: ShareUrlOptions<Codecs>): string {
+  const { base, search = '', config, vocabulary } = options;
+  const query = applyShareConfig(search, config, vocabulary);
+  const address = trimAddress(base);
+  return query === '' ? address : `${address}?${query}`;
+}
+
+/** What {@link buildEmbedCode} needs to write the snippet. */
+export interface EmbedCodeOptions {
+  /** The link the frame loads. */
+  url: string;
+  /** What a screen reader announces the frame as; a frame without one is unreadable. */
+  title: string;
+  /**
+   * Height of the frame, in pixels.
+   * @default 700
+   */
+  height?: number;
+  /**
+   * Width of the frame; a number is taken as pixels.
+   * @default '100%'
+   */
+  width?: number | string;
+  /**
+   * The CSS border the frame is drawn with.
+   * @default '1px solid #ddd'
+   */
+  border?: string;
+}
+
+/**
+ * The snippet to paste into a course page: one iframe loading the shared link.
+ * Every value is escaped, so an address carrying an ampersand or a title
+ * carrying a quote cannot break out of its attribute.
+ * @param options - The link, its accessible name and the frame's dimensions.
+ * @returns One line of HTML.
+ */
+export function buildEmbedCode(options: EmbedCodeOptions): string {
+  const {
+    url,
+    title,
+    height = DEFAULT_HEIGHT,
+    width = '100%',
+    border = '1px solid #ddd',
+  } = options;
+  const style = `border: ${border}; border-radius: 8px`;
+  return [
+    `<iframe src="${escapeAttribute(url)}"`,
+    `title="${escapeAttribute(title)}"`,
+    `width="${escapeAttribute(formatWidth(width))}"`,
+    `height="${formatHeight(height)}"`,
+    `style="${escapeAttribute(style)}"`,
+    'loading="lazy"></iframe>',
+  ].join(' ');
+}
+
+const DEFAULT_HEIGHT = 700;
+
+function trimAddress(base: string): string {
+  const cut = base.search(/[#?]/);
+  return cut === -1 ? base : base.slice(0, cut);
+}
+
+function formatWidth(width: number | string): string {
+  if (typeof width !== 'number') return width;
+  return String(Math.max(1, Math.round(width)));
+}
+
+function formatHeight(height: number): string {
+  if (!Number.isFinite(height)) return String(DEFAULT_HEIGHT);
+  return String(Math.max(1, Math.round(height)));
+}