react-cheminfo 0.3.0 → 0.4.0

package/src/share/ui/ShareDialog.tsx

@@ -0,0 +1,114 @@
+import { Dialog } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import type {
+  ShareConfig,
+  ShareParamCodecs,
+  ShareParamValues,
+  ShareVocabulary,
+} from '../core/index.ts';
+
+import { ShareDialogContent } from './ShareDialogContent.tsx';
+
+const DIALOG_STYLE: CSSProperties = { width: 'min(680px, 94vw)' };
+
+/**
+ * The configuration the dialog is holding, handed to a tool-specific section so
+ * it can read it and change it.
+ */
+export interface ShareDraft<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> {
+  /** What the link would say if it were handed out now. */
+  config: ShareConfig<Codecs>;
+  /** Frame the page, or give it its chrome back. */
+  setEmbed: (embed: boolean) => void;
+  /** Switch one part of the page off, or on again. */
+  setPartHidden: (part: string, hidden: boolean) => void;
+  /** Give one of the tool's own parameters a new value. */
+  setParam: <Key extends keyof ShareParamValues<Codecs>>(
+    key: Key,
+    value: ShareParamValues<Codecs>[Key],
+  ) => void;
+}
+
+export interface ShareDialogProps<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> {
+  /** Whether the dialog is on screen. */
+  isOpen: boolean;
+  /** Called when the dialog is dismissed. */
+  onClose: () => void;
+  /** What this site's links can say: the hideable parts, and the tool's own parameters. */
+  vocabulary: ShareVocabulary<Codecs>;
+  /** How the open page is named in the dialog, and in the frame. */
+  title: string;
+  /**
+   * Where the page is served from — origin and path. Anything from the first
+   * `?` or `#` is dropped, so an address can be handed over as it is.
+   * @default the address of the page
+   */
+  baseUrl?: string;
+  /**
+   * The address as it stands, so the tool's own inputs travel with the link and
+   * a page already running a configuration opens on that one.
+   * @default the query string of the page
+   */
+  search?: string;
+  /**
+   * What a screen reader announces the frame as. A frame in someone else's page
+   * is usually named after the site as well as the page.
+   * @default the title
+   */
+  frameTitle?: string;
+  /**
+   * Height of the frame, in pixels.
+   * @default 700
+   */
+  frameHeight?: number;
+  /**
+   * Whether the dialog is rendered through a portal on `document.body`.
+   * @default true
+   */
+  usePortal?: boolean;
+  /**
+   * An extra section for what only this tool can configure — a series length, a
+   * difficulty, a seed. A function is handed the draft, so such a section can
+   * write the tool's own parameters into the link.
+   * @default undefined — the dialog shows the sections every site shares
+   */
+  children?: ReactNode | ((draft: ShareDraft<Codecs>) => ReactNode);
+}
+
+/**
+ * Hand the open page out as a link, or as the iframe that frames it in someone
+ * else's site.
+ *
+ * The dialog opens on the link one actually hands out: framed, and with the
+ * parts a host page has no use for already switched off. A page that is itself
+ * running a configuration shows that one instead.
+ * @param props - Whether the dialog is open, what the site's links can say, and how the page is named.
+ * @returns The dialog.
+ */
+export function ShareDialog<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(props: ShareDialogProps<Codecs>): ReactElement {
+  const { isOpen, onClose, usePortal = true, ...rest } = props;
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      onClose={onClose}
+      usePortal={usePortal}
+      title="Share or embed"
+      icon="share"
+      className="share-dialog"
+      style={DIALOG_STYLE}
+    >
+      {/* The draft is mounted with the body, so a dialog a page leaves mounted
+          still opens on the link it would hand out rather than on whatever was
+          left in it. */}
+      {isOpen ? <ShareDialogContent {...rest} onClose={onClose} /> : null}
+    </Dialog>
+  );
+}

package/src/share/ui/ShareDialogContent.tsx

@@ -0,0 +1,189 @@
+import {
+  AnchorButton,
+  Button,
+  Checkbox,
+  DialogBody,
+  DialogFooter,
+  H6,
+} from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { useState } from 'react';
+
+import { CodeBlock, CopyButton } from '../../clipboard/ui/index.ts';
+import type {
+  ShareConfig,
+  ShareParamCodecs,
+  ShareParamValues,
+  ShareVocabulary,
+} from '../core/index.ts';
+import {
+  buildEmbedCode,
+  buildShareUrl,
+  isShareConfigured,
+  parseShareConfig,
+  suggestedShareConfig,
+} from '../core/index.ts';
+
+import type { ShareDialogProps, ShareDraft } from './ShareDialog.tsx';
+import { SharePartOptions } from './SharePartOptions.tsx';
+import { withPart } from './draft.ts';
+
+const LEAD_STYLE: CSSProperties = { marginTop: 0, color: '#5b6875' };
+const SECTION_STYLE: CSSProperties = { marginBottom: 18 };
+const ACTIONS_STYLE: CSSProperties = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: 8,
+  marginTop: 8,
+};
+const HINT_STYLE: CSSProperties = {
+  display: 'block',
+  marginLeft: 26,
+  color: '#5b6875',
+  fontSize: 12,
+};
+
+/** Everything the dialog holds, minus what only its shell is concerned with. */
+export type ShareDialogContentProps<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> = Omit<ShareDialogProps<Codecs>, 'isOpen' | 'usePortal'>;
+
+/**
+ * The sections of the share dialog: what the link says, what it hands out, and
+ * the markup that frames it.
+ * @param props - What the site's links can say, how the page is named, and the extra section.
+ * @returns The body and the footer of the dialog.
+ */
+export function ShareDialogContent<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(props: ShareDialogContentProps<Codecs>): ReactElement {
+  const {
+    onClose,
+    vocabulary,
+    title,
+    baseUrl,
+    search,
+    frameTitle,
+    frameHeight,
+    children,
+  } = props;
+
+  const address = globalThis.location;
+  const base = baseUrl ?? address?.href ?? '';
+  const query = search ?? address?.search ?? '';
+  const [config, setConfig] = useState<ShareConfig<Codecs>>(() =>
+    initialDraft(query, vocabulary),
+  );
+
+  function setEmbed(embed: boolean): void {
+    setConfig((previous) => ({ ...previous, embed }));
+  }
+
+  function setPartHidden(part: string, hidden: boolean): void {
+    setConfig((previous) => ({
+      ...previous,
+      hidden: withPart(previous.hidden, part, hidden),
+    }));
+  }
+
+  function setParam<Key extends keyof ShareParamValues<Codecs>>(
+    key: Key,
+    value: ShareParamValues<Codecs>[Key],
+  ): void {
+    setConfig((previous) => ({
+      ...previous,
+      params: { ...previous.params, [key]: value },
+    }));
+  }
+
+  const draft: ShareDraft<Codecs> = {
+    config,
+    setEmbed,
+    setPartHidden,
+    setParam,
+  };
+  const url = buildShareUrl({ base, search: query, config, vocabulary });
+  const frame = buildEmbedCode({
+    url,
+    title: frameTitle ?? title,
+    height: frameHeight,
+  });
+
+  return (
+    <>
+      <DialogBody>
+        <p style={LEAD_STYLE}>
+          A link to <b>{title}</b> as you have it set up now.
+        </p>
+
+        <section className="share-section" style={SECTION_STYLE}>
+          <H6>Layout</H6>
+          <Checkbox
+            checked={config.embed}
+            label="Embed in another page"
+            onChange={(event) => {
+              setEmbed(event.currentTarget.checked);
+            }}
+          />
+          <span style={HINT_STYLE}>
+            Drops the site header and its navigation, so the page sits inside a
+            page of your own.
+          </span>
+        </section>
+
+        {vocabulary.parts.length > 0 ? (
+          <section className="share-section" style={SECTION_STYLE}>
+            <H6>Show on the page</H6>
+            <SharePartOptions
+              parts={vocabulary.parts}
+              hidden={config.hidden}
+              onChange={setPartHidden}
+            />
+          </section>
+        ) : null}
+
+        {children === undefined ? null : (
+          <section className="share-section" style={SECTION_STYLE}>
+            {typeof children === 'function' ? children(draft) : children}
+          </section>
+        )}
+
+        <section className="share-section" style={SECTION_STYLE}>
+          <H6>Link</H6>
+          <CodeBlock code={url} tone="muted" />
+          <div style={ACTIONS_STYLE}>
+            <CopyButton content={url} label="Copy the link" />
+            <AnchorButton
+              icon="share"
+              text="Open in a new tab"
+              href={url}
+              target="_blank"
+              rel="noopener noreferrer"
+            />
+          </div>
+        </section>
+
+        <section className="share-section" style={SECTION_STYLE}>
+          <H6>Iframe</H6>
+          <CodeBlock code={frame} tone="muted" />
+          <div style={ACTIONS_STYLE}>
+            <CopyButton content={frame} label="Copy the iframe" />
+          </div>
+        </section>
+      </DialogBody>
+      <DialogFooter
+        actions={<Button intent="primary" text="Done" onClick={onClose} />}
+      />
+    </>
+  );
+}
+
+function initialDraft<Codecs extends ShareParamCodecs>(
+  search: string,
+  vocabulary: ShareVocabulary<Codecs>,
+): ShareConfig<Codecs> {
+  const current = parseShareConfig(search, vocabulary);
+  return isShareConfigured(current, vocabulary)
+    ? current
+    : suggestedShareConfig(vocabulary);
+}

package/src/share/ui/SharePartOptions.tsx

@@ -0,0 +1,51 @@
+import { Checkbox } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { HideablePart } from '../core/index.ts';
+
+const OPTION_STYLE: CSSProperties = { marginBottom: 8 };
+
+const DESCRIPTION_STYLE: CSSProperties = {
+  display: 'block',
+  marginLeft: 26,
+  color: '#5b6875',
+  fontSize: 12,
+};
+
+export interface SharePartOptionsProps {
+  /** The parts this page can switch off, in the order the vocabulary lists them. */
+  parts: readonly HideablePart[];
+  /** The parts the draft currently switches off. */
+  hidden: readonly string[];
+  /** Called with the part and whether the link should switch it off. */
+  onChange: (part: string, hidden: boolean) => void;
+}
+
+/**
+ * One box per part of the page, worded positively: a ticked box is a part the
+ * link keeps, which is how somebody building a course tile thinks about it.
+ * @param props - The parts, what is switched off, and how to change it.
+ * @returns The list of boxes.
+ */
+export function SharePartOptions(props: SharePartOptionsProps): ReactElement {
+  const { parts, hidden, onChange } = props;
+
+  return (
+    <>
+      {parts.map((part) => (
+        <div key={part.key} style={OPTION_STYLE} className="share-part">
+          <Checkbox
+            checked={!hidden.includes(part.key)}
+            label={part.label}
+            onChange={(event) => {
+              onChange(part.key, !event.currentTarget.checked);
+            }}
+          />
+          <span style={DESCRIPTION_STYLE} className="share-part-description">
+            {part.description}
+          </span>
+        </div>
+      ))}
+    </>
+  );
+}

package/src/share/ui/draft.ts

@@ -0,0 +1,19 @@
+/**
+ * Switch one part of the page off, or on again, in the draft the dialog holds.
+ *
+ * A part is named once however many times it is ticked, and the order the
+ * vocabulary gives is restored when the link is written, so two people who
+ * ticked the same boxes hand out the same link.
+ * @param hidden - The parts the draft switches off.
+ * @param part - The part being ticked.
+ * @param off - Whether the link should switch it off.
+ * @returns The parts the draft switches off after the change.
+ */
+export function withPart(
+  hidden: readonly string[],
+  part: string,
+  off: boolean,
+): readonly string[] {
+  const rest = hidden.filter((entry) => entry !== part);
+  return off ? [...rest, part] : rest;
+}

package/src/share/ui/hiddenParts.ts

@@ -0,0 +1,22 @@
+import { createContext, useCallback, useContext } from 'react';
+
+/**
+ * The parts the link switched off, so a component that can be left out of an
+ * embedded page reads the configuration instead of taking it as a prop.
+ *
+ * A page with no provider above it hides nothing, which is what a site that
+ * hands out no links wants.
+ */
+export const HiddenPartsContext = createContext<ReadonlySet<string>>(new Set());
+
+/**
+ * Ask whether the link the page was opened with switches a part 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.
+ * @returns A predicate over the part keys of the site's vocabulary.
+ */
+export function useIsHidden(): (part: string) => boolean {
+  const hidden = useContext(HiddenPartsContext);
+  return useCallback((part: string) => hidden.has(part), [hidden]);
+}

package/src/share/ui/index.ts

@@ -0,0 +1,9 @@
+export type { HiddenPartsProviderProps } from './HiddenPartsProvider.tsx';
+export { HiddenPartsProvider } from './HiddenPartsProvider.tsx';
+export { useIsHidden } from './hiddenParts.ts';
+export type { PagePartProps } from './PagePart.tsx';
+export { PagePart } from './PagePart.tsx';
+export type { ShareButtonProps, ShareButtonVariant } from './ShareButton.tsx';
+export { ShareButton } from './ShareButton.tsx';
+export type { ShareDialogProps } from './ShareDialog.tsx';
+export { ShareDialog } from './ShareDialog.tsx';

package/src/shared/ui/index.ts

@@ -1 +1,2 @@
-export type { HeaderButtonProps } from './MenuButton.tsx';
+export type { HeaderButtonProps, MenuButtonProps } from './MenuButton.tsx';
+export { MenuButton } from './MenuButton.tsx';

package/src/state/ui/index.ts

@@ -0,0 +1,6 @@
+export type {
+  BucketRead,
+  PersistBucketOptions,
+  PersistedBucket,
+} from './persistBucket.ts';
+export { persistBucket } from './persistBucket.ts';

package/src/state/ui/mergeStored.ts

@@ -0,0 +1,87 @@
+/**
+ * Merge what came out of storage over the defaults it was stored against.
+ *
+ * A field the defaults name and the payload does not keeps its default, so a
+ * field added after the last save lands as its default rather than as
+ * `undefined`. A field whose stored value no longer has the shape of its
+ * default — a number where a string is expected, an object where an array is —
+ * is discarded, because a payload written by an older version of a page must
+ * never reach the interface as the wrong type. A key the defaults do not name
+ * is kept, so a bucket whose default is an empty dictionary keeps everything
+ * that was ever put in it.
+ *
+ * The result shares no object and no array with `defaults`, so a caller may
+ * write into it.
+ * @param defaults - What every missing or unusable field falls back to.
+ * @param stored - Whatever `JSON.parse` gave back, trusted for nothing.
+ * @returns The defaults, with whatever was stored and is usable on top.
+ */
+export function mergeStored<T extends object>(defaults: T, stored: unknown): T {
+  const source = isPlainRecord(stored) ? stored : {};
+  return mergeRecord(defaults as Record<string, unknown>, source) as T;
+}
+
+/**
+ * Whether a value is a plain object — the shape the JSON payload of a bucket
+ * takes — rather than an array, a primitive or null.
+ * @param value - Value to inspect.
+ * @returns True for a plain object.
+ */
+export function isPlainRecord(
+  value: unknown,
+): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function mergeRecord(
+  defaults: Record<string, unknown>,
+  stored: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(defaults)) {
+    merged[name] = cloneValue(value);
+  }
+  for (const [name, value] of Object.entries(stored)) {
+    if (value === undefined) continue;
+    merged[name] = Object.hasOwn(defaults, name)
+      ? mergeValue(defaults[name], value)
+      : value;
+  }
+  return merged;
+}
+
+function mergeValue(defaultValue: unknown, storedValue: unknown): unknown {
+  if (isPlainRecord(defaultValue) && isPlainRecord(storedValue)) {
+    return mergeRecord(defaultValue, storedValue);
+  }
+  return hasSameShape(defaultValue, storedValue)
+    ? storedValue
+    : cloneValue(defaultValue);
+}
+
+// A default that is `null` or absent accepts anything, since it names no shape
+// of its own.
+function hasSameShape(defaultValue: unknown, storedValue: unknown): boolean {
+  if (defaultValue === null || defaultValue === undefined) return true;
+  if (storedValue === null) return false;
+  if (Array.isArray(defaultValue) !== Array.isArray(storedValue)) return false;
+  return typeof defaultValue === typeof storedValue;
+}
+
+function cloneValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    const copy = new Array<unknown>(value.length);
+    for (let index = 0; index < value.length; index++) {
+      copy[index] = cloneValue(value[index]);
+    }
+    return copy;
+  }
+  if (isPlainRecord(value)) {
+    const copy: Record<string, unknown> = {};
+    for (const [name, item] of Object.entries(value)) {
+      copy[name] = cloneValue(item);
+    }
+    return copy;
+  }
+  return value;
+}

package/src/state/ui/persistBucket.ts

@@ -0,0 +1,147 @@
+import { isPlainRecord, mergeStored } from './mergeStored.ts';
+
+/**
+ * A bucket of preferences kept in `localStorage` under one versioned key.
+ *
+ * Everything here is best effort. In a page framed by a course, third-party
+ * storage is partitioned in Chrome and blocked in Safari, so a read may find
+ * nothing, a write may be refused, and touching the store may throw before it
+ * is even reached — none of which may ever reach the interface. A visitor whose
+ * quota is full still gets a working site, with their preferences lasting only
+ * as long as the tab.
+ * @param options - See {@link PersistBucketOptions}.
+ * @returns The three ways to use the bucket: read it, write it, forget it.
+ */
+export function persistBucket<T extends object>(
+  options: PersistBucketOptions<T>,
+): PersistedBucket<T> {
+  const { key, version = 1, defaults, onQuotaExceeded } = options;
+  const storageKey = `${key}:v${version}`;
+
+  return {
+    storageKey,
+    read: () => {
+      const stored = readEntry(storageKey);
+      return {
+        value: mergeStored(defaults, stored),
+        firstRun: stored === undefined,
+      };
+    },
+    write: (value: T) => {
+      writeEntry(storageKey, value, onQuotaExceeded);
+    },
+    clear: () => {
+      try {
+        globalThis.localStorage?.removeItem(storageKey);
+      } catch {
+        // An unavailable store has nothing to forget.
+      }
+    },
+  };
+}
+
+/** How a bucket is named, versioned and filled in. */
+export interface PersistBucketOptions<T extends object> {
+  /**
+   * Name of the bucket, namespaced by the site, e.g. `smiles:exercises`. The
+   * version is appended to it, so this never carries one itself.
+   */
+  key: string;
+  /**
+   * Schema version, appended to the key as `:v<version>`. Raise it when a new
+   * shape cannot be reconciled with the old one field by field, and every entry
+   * written by the previous shape is then ignored rather than migrated.
+   * @default 1
+   */
+  version?: number;
+  /**
+   * What a visitor who has stored nothing gets, and what every missing or
+   * unusable field of a stored payload falls back to. Must be JSON
+   * serialisable, since that is how it is stored.
+   */
+  defaults: T;
+  /**
+   * Called when a write was refused because the store is full, with the error
+   * the store threw. The write is swallowed either way; this only exists so a
+   * page can tell its visitor that what they are doing is no longer being kept.
+   * @default undefined
+   */
+  onQuotaExceeded?: (error: unknown) => void;
+}
+
+/** The three ways a page uses its bucket. */
+export interface PersistedBucket<T extends object> {
+  /** The versioned key the bucket occupies, e.g. `smiles:exercises:v1`. */
+  readonly storageKey: string;
+  /** What was stored, merged over the defaults. */
+  read: () => BucketRead<T>;
+  /** Store the bucket as it now stands, replacing what was there. */
+  write: (value: T) => void;
+  /** Forget the bucket, leaving whatever the page holds in memory untouched. */
+  clear: () => void;
+}
+
+/** What one read of a bucket found. */
+export interface BucketRead<T> {
+  /** The stored payload merged over the defaults, ready to be used as is. */
+  value: T;
+  /**
+   * True when nothing usable was there: no entry, an unreadable store, or a
+   * payload that is not an object. It tells a first visit from a visitor who
+   * chose exactly the defaults, which is what decides whether a page opens on
+   * its welcome state or writes the bucket straight back.
+   */
+  firstRun: boolean;
+}
+
+function readEntry(storageKey: string): unknown {
+  let raw: string | null;
+  try {
+    raw = globalThis.localStorage?.getItem(storageKey) ?? null;
+  } catch {
+    return undefined;
+  }
+  if (raw === null) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isPlainRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeEntry(
+  storageKey: string,
+  value: unknown,
+  onQuotaExceeded: ((error: unknown) => void) | undefined,
+): void {
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    // A value that cannot be serialised is a bug in the caller, never a reason
+    // to take the page down with it.
+    return;
+  }
+  try {
+    globalThis.localStorage?.setItem(storageKey, serialized);
+  } catch (error) {
+    if (!isQuotaExceeded(error) || onQuotaExceeded === undefined) return;
+    try {
+      onQuotaExceeded(error);
+    } catch {
+      // A callback that throws must not turn a lost preference into a crash.
+    }
+  }
+}
+
+function isQuotaExceeded(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  const { name, code } = error as { name?: unknown; code?: unknown };
+  return (
+    name === 'QuotaExceededError' ||
+    name === 'NS_ERROR_DOM_QUOTA_REACHED' ||
+    code === 22 ||
+    code === 1014
+  );
+}