react-cheminfo 0.11.0 → 0.12.0

package/src/share/core/preferences.ts

@@ -0,0 +1,211 @@
+import { EMBED_PARAM, HIDE_PARAM } from './config.ts';
+import type { ShareParamCodec } from './params.ts';
+import type { QueryEntry } from './query.ts';
+import { firstValues, parseQuery, serializeQuery } from './query.ts';
+
+/**
+ * One persisted user choice mirrored in the address bar: how it is read from
+ * and written to a link, and how the site reads and stores it.
+ */
+export interface UrlPreference<Value> {
+  /** How the value is read from a link and written back; its default is never written. */
+  codec: ShareParamCodec<Value>;
+  /**
+   * The value in force.
+   * @returns The current value.
+   */
+  get(): Value;
+  /**
+   * Store a value a link carries, which makes it the visitor's saved preference.
+   * @param value - The value to store.
+   */
+  set(value: Value): void;
+}
+
+/** The preferences a site mirrors, keyed by their URL parameter name. */
+export type UrlPreferences = Readonly<Record<string, UrlPreference<unknown>>>;
+
+/** The minimal part of `window.location` the sync reads. */
+export interface PreferenceLocation {
+  /** The path of the address. */
+  readonly pathname: string;
+  /** The query string, with its leading `?` or empty. */
+  readonly search: string;
+  /** The fragment, with its leading `#` or empty. */
+  readonly hash: string;
+}
+
+/** The minimal part of `window.history` the sync writes through. */
+export interface PreferenceHistory {
+  /** The state of the current entry, kept as it is. */
+  readonly state: unknown;
+  /**
+   * Rewrite the current entry without adding one.
+   * @param data - The state to keep.
+   * @param unused - Ignored by browsers.
+   * @param url - The new address.
+   */
+  replaceState(data: unknown, unused: string, url: string): void;
+}
+
+/** What {@link syncPreferencesWithUrl} is given. */
+export interface SyncPreferencesOptions {
+  /** The preferences to mirror, keyed by their URL parameter name. */
+  preferences: UrlPreferences;
+  /** Call the listener whenever any preference changes, and answer a function that stops calling it. */
+  subscribe: (listener: () => void) => () => void;
+  /**
+   * The address to read and keep up to date.
+   * @default globalThis.location
+   */
+  location?: PreferenceLocation;
+  /**
+   * The history to rewrite.
+   * @default globalThis.history
+   */
+  history?: PreferenceHistory;
+}
+
+/**
+ * Store the preferences a link carries. Only the keys present are set: a key
+ * the link omits leaves the saved preference as it is. A malformed value falls
+ * back to the codec's default.
+ * @param search - The query string, with or without its leading `?`.
+ * @param preferences - The preferences, keyed by their URL parameter name.
+ * @returns The names of the preferences that were set, in declaration order.
+ */
+export function applyPreferencesFromSearch(
+  search: string,
+  preferences: UrlPreferences,
+): string[] {
+  assertPreferenceNames(preferences);
+  const values = firstValues(parseQuery(search));
+  const applied: string[] = [];
+  for (const [name, preference] of Object.entries(preferences)) {
+    const raw = values.get(name);
+    if (raw === undefined) continue;
+    preference.set(preference.codec.parse(raw));
+    applied.push(name);
+  }
+  return applied;
+}
+
+/**
+ * Write the preferences into a query string. A preference already in the
+ * address keeps its place, a new one is appended, one at its default is
+ * deleted; every other key keeps its value and its order.
+ * @param search - The query string, with or without its leading `?`.
+ * @param preferences - The preferences, keyed by their URL parameter name.
+ * @returns The new query string, without its leading `?`.
+ */
+export function writePreferencesToSearch(
+  search: string,
+  preferences: UrlPreferences,
+): string {
+  assertPreferenceNames(preferences);
+  const written = new Map<string, string | null>();
+  for (const [name, preference] of Object.entries(preferences)) {
+    written.set(name, preference.codec.serialize(preference.get()));
+  }
+  const entries: QueryEntry[] = [];
+  const placed = new Set<string>();
+  for (const entry of parseQuery(search)) {
+    const [key] = entry;
+    if (!written.has(key)) {
+      entries.push(entry);
+      continue;
+    }
+    if (placed.has(key)) continue;
+    placed.add(key);
+    const raw = written.get(key);
+    if (raw !== null && raw !== undefined) entries.push([key, raw]);
+  }
+  for (const [name, raw] of written) {
+    if (!placed.has(name) && raw !== null) entries.push([name, raw]);
+  }
+  return serializeQuery(entries);
+}
+
+/**
+ * Mirror a site's preferences in the address bar. The preferences the current
+ * address carries are applied once, then the address is rewritten with
+ * `history.replaceState` — never a new history entry — every time one changes.
+ * The path, the hash and every other query key are kept, and the address is
+ * left alone when nothing in it would change.
+ *
+ * A site using signals subscribes with an effect reading every value:
+ *
+ * ```ts
+ * const stop = syncPreferencesWithUrl({
+ *   preferences: {
+ *     strategy: {
+ *       codec: enumParam(['greedy', 'exhaustive'] as const, 'greedy'),
+ *       get: () => state.preferences.strategy.value,
+ *       set: (value) => (state.preferences.strategy.value = value),
+ *     },
+ *   },
+ *   subscribe: (listener) =>
+ *     effect(() => {
+ *       void state.preferences.strategy.value;
+ *       listener();
+ *     }),
+ * });
+ * ```
+ * @param options - The preferences, how to watch them, and the address.
+ * @returns A function that stops rewriting the address.
+ */
+export function syncPreferencesWithUrl(
+  options: SyncPreferencesOptions,
+): () => void {
+  const {
+    preferences,
+    subscribe,
+    location = globalThis.location,
+    history = globalThis.history,
+  } = options;
+  assertPreferenceNames(preferences);
+  applyPreferencesFromSearch(location.search, preferences);
+  let active = true;
+  function write(): void {
+    if (!active) return;
+    const current = location.search;
+    const next = writePreferencesToSearch(current, preferences);
+    if (sameQuery(current, next)) return;
+    const query = next === '' ? '' : `?${next}`;
+    history.replaceState(
+      history.state,
+      '',
+      `${location.pathname}${query}${location.hash}`,
+    );
+  }
+  const unsubscribe = subscribe(write);
+  write();
+  return () => {
+    active = false;
+    unsubscribe();
+  };
+}
+
+const RESERVED_NAMES = new Set([EMBED_PARAM, HIDE_PARAM]);
+
+function assertPreferenceNames(preferences: UrlPreferences): void {
+  for (const name of Object.keys(preferences)) {
+    if (RESERVED_NAMES.has(name)) {
+      throw new Error(
+        `preference "${name}" collides with a reserved share parameter`,
+      );
+    }
+  }
+}
+
+function sameQuery(current: string, next: string): boolean {
+  const before = parseQuery(current);
+  const after = parseQuery(next);
+  if (before.length !== after.length) return false;
+  for (let index = 0; index < before.length; index++) {
+    const left = before[index];
+    const right = after[index];
+    if (left?.[0] !== right?.[0] || left?.[1] !== right?.[1]) return false;
+  }
+  return true;
+}

package/src/share/core/presets.ts

@@ -0,0 +1,89 @@
+import type { ShareConfig } from './config.ts';
+import { applyShareConfig } from './config.ts';
+import type {
+  ShareParamCodecs,
+  ShareParamValues,
+  ShareVocabulary,
+} from './vocabulary.ts';
+
+/**
+ * A ready-made link the share dialog offers as one tab: the handful of
+ * configurations a site knows people actually hand out, so building one is a
+ * click rather than six boxes.
+ */
+export interface SharePreset<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> {
+  /** Names the preset among the others of the dialog. */
+  key: string;
+  /** The tab label, a few words. */
+  label: string;
+  /** One sentence saying what the link shows, for the person building it. */
+  description: string;
+  /**
+   * Whether the link drops the site chrome.
+   * @default true
+   */
+  embed?: boolean;
+  /**
+   * The parts the link switches off. A key the vocabulary does not list is
+   * ignored.
+   * @default []
+   */
+  hidden?: readonly string[];
+  /**
+   * The tool's own parameters the preset pins. A parameter it does not name
+   * keeps the value the draft holds.
+   * @default {}
+   */
+  params?: Partial<ShareParamValues<Codecs>>;
+}
+
+/**
+ * The configuration a preset turns a draft into.
+ * @param config - The draft as it stands.
+ * @param preset - The preset to apply.
+ * @param vocabulary - What this site's links can say.
+ * @returns The draft with the preset's layout, parts and parameters.
+ */
+export function applySharePreset<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(
+  config: ShareConfig<Codecs>,
+  preset: SharePreset<Codecs>,
+  vocabulary: ShareVocabulary<Codecs>,
+): ShareConfig<Codecs> {
+  const asked = new Set(preset.hidden);
+  const hidden: string[] = [];
+  for (const part of vocabulary.parts) {
+    if (asked.has(part.key)) hidden.push(part.key);
+  }
+  return {
+    embed: preset.embed ?? true,
+    hidden,
+    params: { ...config.params, ...preset.params },
+  };
+}
+
+/**
+ * The preset a draft already is, judged by the link both would write, so a
+ * part the layout makes meaningless does not tell them apart.
+ * @param config - The draft to recognise.
+ * @param presets - The presets the dialog offers.
+ * @param vocabulary - What this site's links can say.
+ * @returns The first preset writing the same link, or `undefined`.
+ */
+export function findSharePreset<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(
+  config: ShareConfig<Codecs>,
+  presets: ReadonlyArray<SharePreset<Codecs>>,
+  vocabulary: ShareVocabulary<Codecs>,
+): SharePreset<Codecs> | undefined {
+  const link = applyShareConfig('', config, vocabulary);
+  for (const preset of presets) {
+    const presetConfig = applySharePreset(config, preset, vocabulary);
+    if (applyShareConfig('', presetConfig, vocabulary) === link) return preset;
+  }
+  return undefined;
+}

package/src/share/core/vocabulary.ts

@@ -20,6 +20,14 @@ export interface HideablePart {
    * @default false
    */
   hiddenByDefault?: boolean;
+  /**
+   * Whether the part sits inside the site header, as a tab bar does. An
+   * embedded page has no header, so while `embed` is on the dialog does not
+   * offer the part and a link does not name it in `?hide=`; what the draft
+   * says about it is kept for when `embed` is switched off again.
+   * @default false
+   */
+  inHeader?: boolean;
 }
 
 /**

package/src/share/ui/ShareButton.tsx

@@ -72,13 +72,19 @@ export function ShareButton(props: ShareButtonProps): ReactElement {
   return (
     <button
       type="button"
-      className={className === undefined ? 'nav-link' : `nav-link ${className}`}
+      className={
+        className === undefined
+          ? 'nav-link nav-link--icon'
+          : `nav-link nav-link--icon ${className}`
+      }
       title={title}
       aria-label={label}
       onClick={onClick}
     >
       <Icon icon="share" size={14} />
-      {text}
+      {text === undefined ? null : (
+        <span className="nav-link__label">{text}</span>
+      )}
     </button>
   );
 }

package/src/share/ui/ShareConfigOptions.tsx

@@ -0,0 +1,68 @@
+import { Checkbox, H6 } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { HideablePart } from '../core/index.ts';
+
+import { SharePartOptions } from './SharePartOptions.tsx';
+
+const SECTION_STYLE: CSSProperties = { marginBottom: 18 };
+const HINT_STYLE: CSSProperties = {
+  display: 'block',
+  marginLeft: 26,
+  color: 'var(--text-muted, #5b6875)',
+  fontSize: 12,
+};
+
+export interface ShareConfigOptionsProps {
+  /** Whether the draft drops the site chrome. */
+  embed: boolean;
+  /** The parts that still mean something in this layout, in vocabulary order. */
+  parts: readonly HideablePart[];
+  /** The parts the draft switches off. */
+  hidden: readonly string[];
+  /** Called when the layout is switched. */
+  onEmbedChange: (embed: boolean) => void;
+  /** Called with the part and whether the link should switch it off. */
+  onPartChange: (part: string, hidden: boolean) => void;
+}
+
+/**
+ * The boxes of the share dialog: the layout, then one box per part of the page.
+ * @param props - The draft's layout and parts, and how to change them.
+ * @returns The two sections.
+ */
+export function ShareConfigOptions(
+  props: ShareConfigOptionsProps,
+): ReactElement {
+  const { embed, parts, hidden, onEmbedChange, onPartChange } = props;
+
+  return (
+    <>
+      <section className="share-section" style={SECTION_STYLE}>
+        <H6>Layout</H6>
+        <Checkbox
+          checked={embed}
+          label="Embed in another page"
+          onChange={(event) => {
+            onEmbedChange(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>
+
+      {parts.length > 0 ? (
+        <section className="share-section" style={SECTION_STYLE}>
+          <H6>Show on the page</H6>
+          <SharePartOptions
+            parts={parts}
+            hidden={hidden}
+            onChange={onPartChange}
+          />
+        </section>
+      ) : null}
+    </>
+  );
+}

package/src/share/ui/ShareDialog.tsx

@@ -5,12 +5,16 @@ import type {
   ShareConfig,
   ShareParamCodecs,
   ShareParamValues,
+  SharePreset,
   ShareVocabulary,
 } from '../core/index.ts';
 
 import { ShareDialogContent } from './ShareDialogContent.tsx';
 
-const DIALOG_STYLE: CSSProperties = { width: 'min(680px, 94vw)' };
+const DIALOG_STYLE: CSSProperties = {
+  width: 'min(820px, 94vw)',
+  height: 'min(760px, 90dvh)',
+};
 
 /**
  * The configuration the dialog is holding, handed to a tool-specific section so
@@ -41,6 +45,20 @@ export interface ShareDialogProps<
   onClose: () => void;
   /** What this site's links can say: the hideable parts, and the tool's own parameters. */
   vocabulary: ShareVocabulary<Codecs>;
+  /**
+   * Ready-made links, offered as tabs above a last Custom tab that holds the
+   * boxes. Picking one rewrites the draft; the dialog opens on the preset the
+   * draft already is, or on Custom.
+   * @default [] — no tabs, the boxes alone
+   */
+  presets?: ReadonlyArray<SharePreset<Codecs>>;
+  /**
+   * Key of the preset the dialog opens on when the page is not already running
+   * a configuration of its own — the link a page like this is usually handed
+   * out as. A key no preset has is ignored.
+   * @default undefined — the dialog opens on the suggested configuration
+   */
+  defaultPreset?: string;
   /** How the open page is named in the dialog, and in the frame. */
   title: string;
   /**

package/src/share/ui/ShareDialogContent.tsx

@@ -1,8 +1,7 @@
 import {
   AnchorButton,
   Button,
-  Checkbox,
-  DialogBody,
+  Classes,
   DialogFooter,
   H6,
 } from '@blueprintjs/core';
@@ -14,18 +13,23 @@ import type {
   ShareConfig,
   ShareParamCodecs,
   ShareParamValues,
+  SharePreset,
   ShareVocabulary,
 } from '../core/index.ts';
 import {
+  applySharePreset,
   buildEmbedCode,
   buildShareUrl,
+  findSharePreset,
   isShareConfigured,
   parseShareConfig,
   suggestedShareConfig,
+  visibleShareParts,
 } from '../core/index.ts';
 
+import { ShareConfigOptions } from './ShareConfigOptions.tsx';
 import type { ShareDialogProps, ShareDraft } from './ShareDialog.tsx';
-import { SharePartOptions } from './SharePartOptions.tsx';
+import { SharePresetTabs } from './SharePresetTabs.tsx';
 import { withPart } from './draft.ts';
 
 const LEAD_STYLE: CSSProperties = {
@@ -39,12 +43,13 @@ const ACTIONS_STYLE: CSSProperties = {
   gap: 8,
   marginTop: 8,
 };
-const HINT_STYLE: CSSProperties = {
-  display: 'block',
-  marginLeft: 26,
-  color: 'var(--text-muted, #5b6875)',
-  fontSize: 12,
-};
+
+const NO_PRESETS: readonly never[] = [];
+
+// The dialog has a fixed height so switching preset does not resize it: the
+// body takes what the header and footer leave, and scrolls.
+const BODY_CLASS = `${Classes.DIALOG_BODY} ${Classes.DIALOG_BODY_SCROLL_CONTAINER}`;
+const BODY_STYLE: CSSProperties = { maxHeight: 'none', minHeight: 0 };
 
 /** Everything the dialog holds, minus what only its shell is concerned with. */
 export type ShareDialogContentProps<
@@ -63,6 +68,8 @@ export function ShareDialogContent<
   const {
     onClose,
     vocabulary,
+    presets = NO_PRESETS,
+    defaultPreset,
     title,
     baseUrl,
     search,
@@ -75,7 +82,10 @@ export function ShareDialogContent<
   const base = baseUrl ?? address?.href ?? '';
   const query = search ?? address?.search ?? '';
   const [config, setConfig] = useState<ShareConfig<Codecs>>(() =>
-    initialDraft(query, vocabulary),
+    initialDraft(query, vocabulary, findPreset(presets, defaultPreset ?? null)),
+  );
+  const [presetKey, setPresetKey] = useState<string | null>(
+    () => findSharePreset(config, presets, vocabulary)?.key ?? null,
   );
 
   function setEmbed(embed: boolean): void {
@@ -99,6 +109,13 @@ export function ShareDialogContent<
     }));
   }
 
+  function selectPreset(key: string | null): void {
+    setPresetKey(key);
+    const preset = findPreset(presets, key);
+    if (preset === undefined) return;
+    setConfig((previous) => applySharePreset(previous, preset, vocabulary));
+  }
+
   const draft: ShareDraft<Codecs> = {
     config,
     setEmbed,
@@ -111,39 +128,33 @@ export function ShareDialogContent<
     title: frameTitle ?? title,
     height: frameHeight,
   });
+  const options = (
+    <ShareConfigOptions
+      embed={config.embed}
+      parts={visibleShareParts(vocabulary.parts, config.embed)}
+      hidden={config.hidden}
+      onEmbedChange={setEmbed}
+      onPartChange={setPartHidden}
+    />
+  );
 
   return (
     <>
-      <DialogBody>
+      <div className={BODY_CLASS} style={BODY_STYLE}>
         <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);
-            }}
+        {presets.length === 0 ? (
+          options
+        ) : (
+          <SharePresetTabs
+            presets={presets}
+            selected={presetKey}
+            onSelect={selectPreset}
+            custom={options}
           />
-          <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}>
@@ -173,7 +184,7 @@ export function ShareDialogContent<
             <CopyButton content={frame} label="Copy the iframe" />
           </div>
         </section>
-      </DialogBody>
+      </div>
       <DialogFooter
         actions={<Button intent="primary" text="Done" onClick={onClose} />}
       />
@@ -184,9 +195,23 @@ export function ShareDialogContent<
 function initialDraft<Codecs extends ShareParamCodecs>(
   search: string,
   vocabulary: ShareVocabulary<Codecs>,
+  preset: SharePreset<Codecs> | undefined,
 ): ShareConfig<Codecs> {
   const current = parseShareConfig(search, vocabulary);
-  return isShareConfigured(current, vocabulary)
-    ? current
-    : suggestedShareConfig(vocabulary);
+  if (isShareConfigured(current, vocabulary)) return current;
+  const suggested = suggestedShareConfig(vocabulary);
+  return preset === undefined
+    ? suggested
+    : applySharePreset(suggested, preset, vocabulary);
+}
+
+function findPreset<Codecs extends ShareParamCodecs>(
+  presets: ReadonlyArray<SharePreset<Codecs>>,
+  key: string | null,
+): SharePreset<Codecs> | undefined {
+  if (key === null) return undefined;
+  for (const preset of presets) {
+    if (preset.key === key) return preset;
+  }
+  return undefined;
 }

package/src/share/ui/SharePresetTabs.tsx

@@ -0,0 +1,70 @@
+import { Tab, Tabs } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import type { ShareParamCodecs, SharePreset } from '../core/index.ts';
+
+const SECTION_STYLE: CSSProperties = { marginBottom: 18 };
+const DESCRIPTION_STYLE: CSSProperties = {
+  margin: 0,
+  color: 'var(--text-muted, #5b6875)',
+};
+
+const CUSTOM_TAB = 'custom';
+const PRESET_TAB_PREFIX = 'preset-';
+
+export interface SharePresetTabsProps<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> {
+  /** The presets, in the order the tabs list them. */
+  presets: ReadonlyArray<SharePreset<Codecs>>;
+  /** The key of the open preset, `null` for the custom tab. */
+  selected: string | null;
+  /** Called with the key of the preset picked, `null` for the custom tab. */
+  onSelect: (key: string | null) => void;
+  /** What the custom tab holds: the boxes of the draft. */
+  custom: ReactNode;
+}
+
+/**
+ * One tab per preset, then a last Custom tab holding the boxes, which start
+ * from whatever the preset before it set.
+ * @param props - The presets, the open one, and the custom panel.
+ * @returns The tab strip and the open panel.
+ */
+export function SharePresetTabs<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(props: SharePresetTabsProps<Codecs>): ReactElement {
+  const { presets, selected, onSelect, custom } = props;
+
+  return (
+    <section className="share-section" style={SECTION_STYLE}>
+      <Tabs
+        id="share-presets"
+        className="share-presets"
+        animate={false}
+        renderActiveTabPanelOnly
+        selectedTabId={
+          selected === null ? CUSTOM_TAB : `${PRESET_TAB_PREFIX}${selected}`
+        }
+        onChange={(tabId) => {
+          const id = String(tabId);
+          onSelect(
+            id.startsWith(PRESET_TAB_PREFIX)
+              ? id.slice(PRESET_TAB_PREFIX.length)
+              : null,
+          );
+        }}
+      >
+        {presets.map((preset) => (
+          <Tab
+            key={preset.key}
+            id={`${PRESET_TAB_PREFIX}${preset.key}`}
+            title={preset.label}
+            panel={<p style={DESCRIPTION_STYLE}>{preset.description}</p>}
+          />
+        ))}
+        <Tab id={CUSTOM_TAB} title="Custom" panel={<>{custom}</>} />
+      </Tabs>
+    </section>
+  );
+}