react-cheminfo 0.38.0 → 0.39.0

package/src/share/ui/SharePresetTabs.tsx

@@ -1,15 +1,9 @@
 import { Tab, Tabs } from '@blueprintjs/core';
-import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import type { ReactElement } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
 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-';
 
@@ -22,51 +16,50 @@ export interface SharePresetTabsProps<
   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.
+ * One tab per ready-made link, then a last Custom tab for building any other
+ * one.
+ *
+ * The strip runs the width of the dialog rather than sitting in the column of
+ * options, because the choice governs the preview as much as the switches: in
+ * a third of the width, four tabs wrap onto a second row and the last of them
+ * — the one holding every switch — reads as an afterthought.
+ * @param props - The presets, and which one is open.
+ * @returns The tab strip.
  */
 export function SharePresetTabs<
   Codecs extends ShareParamCodecs = Record<string, never>,
 >(props: SharePresetTabsProps<Codecs>): ReactElement {
-  const { presets, selected, onSelect, custom } = props;
+  const { presets, selected, onSelect } = props;
   const t = useChromeT();
 
   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={t('share.custom')} panel={<>{custom}</>} />
-      </Tabs>
-    </section>
+    <Tabs
+      id="share-presets"
+      className="share-presets"
+      animate={false}
+      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}
+        />
+      ))}
+      <Tab id={CUSTOM_TAB} title={t('share.custom')} />
+    </Tabs>
   );
 }

package/src/share/ui/SharePreview.tsx

@@ -0,0 +1,204 @@
+import { H6, Icon } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { useEffect, useRef, useState } from 'react';
+
+import { formatInteger } from '../../format/core/index.ts';
+import type { HelpContent } from '../../help/ui/index.ts';
+import { HelpIcon } from '../../help/ui/index.ts';
+import { useContainerSize } from '../../hooks/ui/useContainerSize.ts';
+import { useDebouncedValue } from '../../hooks/ui/useDebouncedValue.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { SharePreviewDeviceKey, ShareRegion } from '../core/index.ts';
+import {
+  SHARE_REGIONS_REQUEST,
+  readShareRegions,
+  sharePreviewAddress,
+  sharePreviewScale,
+  sharePreviewSize,
+} from '../core/index.ts';
+
+import { SharePreviewDevices } from './SharePreviewDevices.tsx';
+
+/** Room the window's own bar takes, which the page is not scaled into. */
+const CHROME_HEIGHT = 26;
+
+export interface SharePreviewProps {
+  /** The address the frame loads — the link as it stands. */
+  url: string;
+  /** What a screen reader announces the frame as. */
+  title: string;
+  /**
+   * The part the reader is pointing at in the list, drawn on the page so the
+   * name in the list and the thing on the page are the same thing.
+   * @default null — nothing is pointed at
+   */
+  highlight?: { part: string; label: string } | null;
+}
+
+/**
+ * The page as the link hands it out, live, beside the options that write it.
+ *
+ * It is drawn as a window of its own — named above it, with the address it
+ * loads on its own bar — because a page scaled into a pane otherwise reads as
+ * the site itself, and a reader who takes the preview for the tool ticks a box
+ * in it and believes the link now carries it.
+ *
+ * The frame is laid out at the screen the reader picks — their own window, a
+ * phone, a laptop or a large display — and scaled into whatever room the pane
+ * has, so a course tile can be checked at the size a student will meet it.
+ * @param props - The address and the name of the frame.
+ * @returns The preview pane.
+ */
+export function SharePreview(props: SharePreviewProps): ReactElement {
+  const { url, title, highlight = null } = props;
+  const t = useChromeT();
+  const stage = useRef<HTMLDivElement>(null);
+  const frame = useRef<HTMLIFrameElement>(null);
+  const pane = useContainerSize(stage);
+  const [device, setDevice] = useState<SharePreviewDeviceKey>('window');
+  const [regions, setRegions] = useState<readonly ShareRegion[]>(NO_REGIONS);
+  const mark = useRef<HTMLDivElement>(null);
+  // Every box ticked reloads the frame; a number typed into a tool's own field
+  // would otherwise reload it once per keystroke.
+  const src = useDebouncedValue(url, 400);
+
+  const windowSize = {
+    width: globalThis.innerWidth,
+    height: globalThis.innerHeight,
+  };
+  const page = sharePreviewSize(device, windowSize);
+  const scale = sharePreviewScale(
+    { width: pane.width, height: pane.height - CHROME_HEIGHT },
+    page,
+  );
+  const region =
+    highlight === null ? undefined : regionOf(regions, highlight.part);
+  const help: HelpContent = {
+    title: t('share.preview'),
+    body: [t('share.previewWhat'), t('share.previewLive')],
+  };
+
+  useEffect(() => {
+    function onMessage(event: MessageEvent): void {
+      if (event.source !== frame.current?.contentWindow) return;
+      const reported = readShareRegions(event.data);
+      if (reported !== null) setRegions(reported);
+    }
+
+    globalThis.addEventListener('message', onMessage);
+    return () => {
+      globalThis.removeEventListener('message', onMessage);
+    };
+  }, []);
+
+  // A region further down the page than the stage shows is brought into view,
+  // or pointing at a row would mark something the reader cannot see.
+  useEffect(() => {
+    mark.current?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+  }, [highlight?.part]);
+
+  return (
+    <section className="share-preview" aria-label={t('share.preview')}>
+      <header className="share-preview__header">
+        <H6 className="share-preview__label">
+          <Icon icon="eye-open" size={13} />
+          {t('share.preview')}
+          <HelpIcon content={help} />
+        </H6>
+        <SharePreviewDevices
+          value={device}
+          onChange={setDevice}
+          windowSize={windowSize}
+        />
+      </header>
+      <div className="share-preview__stage" ref={stage}>
+        <div
+          className="share-preview__device"
+          style={{ width: page.width * scale }}
+        >
+          <div className="share-preview__chrome">
+            <Icon icon="eye-open" size={11} />
+            <span className="share-preview__address">
+              {sharePreviewAddress(url)}
+            </span>
+            <span className="share-preview__size">
+              {sizeNote(page.width, page.height, scale)}
+            </span>
+          </div>
+          <div
+            className="share-preview__page"
+            style={{ height: page.height * scale }}
+          >
+            <iframe
+              ref={frame}
+              className="share-preview__frame"
+              src={src}
+              title={title}
+              style={frameStyle(page.width, page.height, scale)}
+              onLoad={() => {
+                // What the page before it reported is where its own parts
+                // were, so it is dropped rather than drawn over this one.
+                setRegions(NO_REGIONS);
+                frame.current?.contentWindow?.postMessage(
+                  { type: SHARE_REGIONS_REQUEST },
+                  '*',
+                );
+              }}
+            />
+            {region === undefined || highlight === null ? null : (
+              <div
+                ref={mark}
+                className="share-preview__region"
+                style={regionStyle(region, scale)}
+              >
+                <span className="share-preview__region-name">
+                  {highlight.label}
+                </span>
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+const NO_REGIONS: readonly ShareRegion[] = [];
+
+function regionOf(
+  regions: readonly ShareRegion[],
+  part: string,
+): ShareRegion | undefined {
+  for (const region of regions) {
+    if (region.part === part) return region;
+  }
+  return undefined;
+}
+
+function regionStyle(region: ShareRegion, scale: number): CSSProperties {
+  return {
+    left: region.x * scale,
+    top: region.y * scale,
+    width: region.width * scale,
+    height: region.height * scale,
+  };
+}
+
+function frameStyle(
+  width: number,
+  height: number,
+  scale: number,
+): CSSProperties {
+  return {
+    width,
+    height,
+    border: 0,
+    transform: `scale(${scale})`,
+    transformOrigin: 'top left',
+  };
+}
+
+function sizeNote(width: number, height: number, scale: number): string {
+  const size = `${formatInteger(width)} × ${formatInteger(height)}`;
+  return scale === 1 ? size : `${size} · ${Math.round(scale * 100)}%`;
+}

package/src/share/ui/SharePreviewDevices.tsx

@@ -0,0 +1,70 @@
+import type { IconName } from '@blueprintjs/core';
+import { Button, ButtonGroup } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { SharePreviewDeviceKey, SharePreviewSize } from '../core/index.ts';
+import { SHARE_PREVIEW_DEVICES, sharePreviewSize } from '../core/index.ts';
+
+/**
+ * The glyph each screen is picked by: a window of one's own, a phone, a
+ * monitor, a projected display. The row reads as four screen sizes at a
+ * glance, which four words never did.
+ */
+const DEVICE_ICONS: Record<SharePreviewDeviceKey, IconName> = {
+  window: 'application',
+  mobile: 'mobile-phone',
+  laptop: 'desktop',
+  hd: 'presentation',
+};
+
+export interface SharePreviewDevicesProps {
+  /** The screen the preview is laid out at. */
+  value: SharePreviewDeviceKey;
+  /** Called with the screen picked. */
+  onChange: (value: SharePreviewDeviceKey) => void;
+  /** The reader's own window, which the first screen is measured from. */
+  windowSize: Partial<SharePreviewSize>;
+}
+
+/**
+ * The screens a link can be looked at on, as one row of glyphs.
+ *
+ * Each carries its name and its size, so a pointer resting on one says what it
+ * lays the page out at rather than leaving the reader to guess the icon.
+ * @param props - See {@link SharePreviewDevicesProps}.
+ * @returns The row of screen buttons.
+ */
+export function SharePreviewDevices(
+  props: SharePreviewDevicesProps,
+): ReactElement {
+  const { value, onChange, windowSize } = props;
+  const t = useChromeT();
+
+  return (
+    <ButtonGroup className="share-preview__devices" variant="minimal">
+      {SHARE_PREVIEW_DEVICES.map((key) => {
+        const size = sharePreviewSize(key, windowSize);
+        const name = t(`share.device.${key}`);
+        const label = t('share.deviceSize', {
+          name,
+          width: size.width,
+          height: size.height,
+        });
+
+        return (
+          <Button
+            key={key}
+            icon={DEVICE_ICONS[key]}
+            active={key === value}
+            title={label}
+            aria-label={label}
+            onClick={() => {
+              onChange(key);
+            }}
+          />
+        );
+      })}
+    </ButtonGroup>
+  );
+}

package/src/share/ui/index.ts

@@ -6,4 +6,5 @@ export { PagePart } from './PagePart.tsx';
 export type { ShareButtonProps, ShareButtonVariant } from './ShareButton.tsx';
 export { ShareButton } from './ShareButton.tsx';
 export type { ShareDialogProps } from './ShareDialog.tsx';
+export type { SharePartDescriptions } from './SharePartRow.tsx';
 export { ShareDialog } from './ShareDialog.tsx';

package/src/share/ui/shareMarking.ts

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Whether the page is being looked at through a share dialog's preview, and so
+ * marks each of its parts in the DOM for the dialog to find.
+ *
+ * A page nobody is framing marks nothing: the marker is a wrapper, and a
+ * wrapper changes what a `>` selector in a site's own stylesheet matches.
+ */
+export const ShareMarkingContext = createContext(false);
+
+/**
+ * Whether this page marks its parts for a share dialog looking at it.
+ * @returns Whether the markers are rendered.
+ */
+export function useShareMarking(): boolean {
+  return useContext(ShareMarkingContext);
+}

package/src/share/ui/useShareRegionReports.ts

@@ -0,0 +1,84 @@
+import { useEffect, useState } from 'react';
+
+import type { ShareRegion } from '../core/index.ts';
+import { SHARE_REGIONS_MESSAGE, isShareRegionsRequest } from '../core/index.ts';
+
+/**
+ * Report where each part of this page sits, while a share dialog is looking at
+ * it through its preview.
+ *
+ * Nothing happens on a page nobody frames, and nothing happens in a frame
+ * whose host never asks — a page embedded in a course is framed too, and owes
+ * its host nothing.
+ * @param hidden - The parts the link switches off, so the boxes are measured again when they change.
+ * @returns Whether the page should mark its parts for the dialog to find.
+ */
+export function useShareRegionReports(hidden: ReadonlySet<string>): boolean {
+  const [marking, setMarking] = useState(false);
+
+  useEffect(() => {
+    const host = globalThis.parent;
+    if (host === globalThis.self) return undefined;
+
+    function onMessage(event: MessageEvent): void {
+      if (isShareRegionsRequest(event.data)) setMarking(true);
+    }
+
+    globalThis.addEventListener('message', onMessage);
+    return () => {
+      globalThis.removeEventListener('message', onMessage);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!marking) return undefined;
+    const host = globalThis.parent;
+
+    function report(): void {
+      host.postMessage(
+        { type: SHARE_REGIONS_MESSAGE, regions: measureRegions() },
+        '*',
+      );
+    }
+
+    // A chart, a web font or a structure drawn after mount all move the boxes,
+    // so the page is measured again whenever anything in it resizes rather
+    // than once, on a deadline it would lose.
+    const observer = new ResizeObserver(report);
+    observer.observe(document.documentElement);
+    globalThis.addEventListener('resize', report);
+    report();
+
+    return () => {
+      observer.disconnect();
+      globalThis.removeEventListener('resize', report);
+    };
+  }, [marking, hidden]);
+
+  return marking;
+}
+
+function measureRegions(): ShareRegion[] {
+  const markers = document.querySelectorAll<HTMLElement>('[data-share-part]');
+  const range = document.createRange();
+  const regions: ShareRegion[] = [];
+
+  for (const marker of markers) {
+    const { sharePart: part } = marker.dataset;
+    if (part === undefined) continue;
+    // The marker lays out as `display: contents`, so it has no box of its own.
+    // A range over what it holds has the box its contents occupy.
+    range.selectNodeContents(marker);
+    const box = range.getBoundingClientRect();
+    if (box.width === 0 || box.height === 0) continue;
+    regions.push({
+      part,
+      x: box.x + globalThis.scrollX,
+      y: box.y + globalThis.scrollY,
+      width: box.width,
+      height: box.height,
+    });
+  }
+
+  return regions;
+}

package/src/shared/ui/ActionTooltip.tsx

@@ -0,0 +1,70 @@
+import type { Placement } from '@blueprintjs/core';
+import { Tooltip } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import { useActionTooltip } from './useActionTooltip.ts';
+
+/** What {@link ActionTooltip} explains, and what it steps aside for. */
+export interface ActionTooltipProps {
+  /** What the control is for, read on hover. */
+  content: string | ReactElement;
+  /** The control. */
+  children: ReactElement;
+  /**
+   * Whether what the control opens is on screen. While it is, the tooltip
+   * stays shut.
+   * @default false
+   */
+  opened?: boolean;
+  /**
+   * Which side of the control the tooltip is drawn on.
+   * @default 'bottom'
+   */
+  placement?: Placement;
+  /**
+   * Class the popover carries, for a card that is not the chrome's own.
+   * @default 'help-tooltip'
+   */
+  popoverClassName?: string;
+  /**
+   * How long the pointer rests on the control before the card is drawn, in
+   * milliseconds.
+   * @default 250
+   */
+  delay?: number;
+}
+
+/**
+ * A tooltip on a control that opens something — a dialog, a popover, a menu.
+ *
+ * It is the wrapper form of {@link useActionTooltip}, which is where the whole
+ * argument is written; a tooltip whose target cannot take a wrapping element —
+ * a menu item, a table cell — uses the hook directly.
+ * @param props - See {@link ActionTooltipProps}.
+ * @returns The control, with its tooltip.
+ */
+export function ActionTooltip(props: ActionTooltipProps): ReactElement {
+  const { content, children, opened = false } = props;
+  const { placement = 'bottom', popoverClassName = 'help-tooltip' } = props;
+  const { delay } = props;
+  const { isOpen, target } = useActionTooltip(opened, delay);
+
+  return (
+    <Tooltip
+      content={content}
+      placement={placement}
+      popoverClassName={popoverClassName}
+      isOpen={isOpen}
+    >
+      {/* The pointer is read here rather than on the control, so the control
+          keeps whatever handlers it was given. A box of its own, never
+          `display: contents`, which measures as an empty rectangle and leaves
+          the card positioned in the corner of the window. */}
+      <span style={WRAP_STYLE} {...target}>
+        {children}
+      </span>
+    </Tooltip>
+  );
+}
+
+const WRAP_STYLE = { display: 'inline-flex' } as const satisfies CSSProperties;

package/src/shared/ui/index.ts

@@ -1,2 +1,9 @@
+export type { ActionTooltipProps } from './ActionTooltip.tsx';
+export { ActionTooltip } from './ActionTooltip.tsx';
 export type { HeaderButtonProps, MenuButtonProps } from './MenuButton.tsx';
 export { MenuButton } from './MenuButton.tsx';
+export type {
+  ActionTooltipState,
+  ActionTooltipTarget,
+} from './useActionTooltip.ts';
+export { ACTION_TOOLTIP_DELAY, useActionTooltip } from './useActionTooltip.ts';

package/src/shared/ui/useActionTooltip.ts

@@ -0,0 +1,103 @@
+/**
+ * When a tooltip on a control that is pressed should be on screen.
+ *
+ * Such a control is where a hover tooltip goes wrong, in two ways that look
+ * like one. What it opens lands over the control, so the `mouseleave` that
+ * would close the card is never delivered and the card is left on screen, over
+ * the thing it was explaining. And the open is *scheduled*: a press within the
+ * hover delay cancels nothing, so the card appears after the press, outlives
+ * what was opened, and comes back when it is closed — with the pointer long
+ * gone.
+ *
+ * Blueprint's own hover handling cannot be told either of those, so the state
+ * is held here and Blueprint is told only when to draw.
+ *
+ * The card is a pointer affordance only, and deliberately does not open on
+ * focus: what a control opens hands the focus back as it closes, which would
+ * put the card on screen with the pointer long gone. Nothing is lost by it —
+ * the control carries the same words as its accessible name, which is what a
+ * screen reader reads.
+ */
+
+import { useEffect, useRef, useState } from 'react';
+
+/** The handlers the target carries, which decide when the card is drawn. */
+export interface ActionTooltipTarget {
+  onPointerEnter: () => void;
+  onPointerLeave: () => void;
+  onPointerDownCapture: () => void;
+  onClickCapture: () => void;
+  onBlurCapture: () => void;
+}
+
+/** Whether the card is drawn, and what decides it. */
+export interface ActionTooltipState {
+  /** What to give the tooltip as `isOpen`. */
+  isOpen: boolean;
+  /** What to give the target, or the element wrapping it. */
+  target: ActionTooltipTarget;
+}
+
+/** Long enough that sweeping the pointer across a row of controls opens none. */
+export const ACTION_TOOLTIP_DELAY = 250;
+
+/**
+ * Hold a tooltip's hover, so a press closes it and nothing reopens it until
+ * the pointer leaves the control and comes back.
+ * @param opened - Whether what the control opens is on screen; while it is,
+ * the card stays shut.
+ * @param delay - How long the pointer rests before the card is drawn, in
+ * milliseconds. A card heavier than a line of text asks for longer.
+ * @returns Whether to draw the card, and the handlers that decide it.
+ */
+export function useActionTooltip(
+  opened = false,
+  delay = ACTION_TOOLTIP_DELAY,
+): ActionTooltipState {
+  const [shown, setShown] = useState(false);
+  const waiting = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Set by the press, and cleared only by the pointer actually leaving. It is
+  // what the pointer never leaving looks like: the dialog lands over the
+  // control, and removing it again makes the browser hand the control a fresh
+  // `pointerenter` — with the pointer never having moved. Clearing the latch
+  // there, or on the focus the dialog gives back as it closes, is what made
+  // the card reappear the moment the dialog was dismissed.
+  const pressed = useRef(false);
+
+  function cancel(): void {
+    if (waiting.current !== null) clearTimeout(waiting.current);
+    waiting.current = null;
+  }
+
+  function hide(): void {
+    cancel();
+    setShown(false);
+  }
+
+  function press(): void {
+    pressed.current = true;
+    hide();
+  }
+
+  useEffect(() => cancel, []);
+
+  return {
+    isOpen: shown && !opened,
+    target: {
+      onPointerEnter: () => {
+        if (pressed.current) return;
+        cancel();
+        waiting.current = setTimeout(() => setShown(true), delay);
+      },
+      onPointerLeave: () => {
+        pressed.current = false;
+        hide();
+      },
+      onPointerDownCapture: press,
+      // Enter and Space fire no pointer event, so a control worked from the
+      // keyboard is let go of here instead.
+      onClickCapture: press,
+      onBlurCapture: hide,
+    },
+  };
+}

package/src/structure/core/index.ts

@@ -72,6 +72,11 @@ export type { ReadStructureResult, StructureKind } from './readStructure.ts';
 export { looksLikeSmarts, readStructure } from './readStructure.ts';
 export type { StructureError } from './structureError.ts';
 export { structureError } from './structureError.ts';
+export type {
+  StructurePicture,
+  StructurePictureOptions,
+} from './structurePicture.ts';
+export { STRUCTURE_BOND_LENGTH, structurePicture } from './structurePicture.ts';
 export type {
   StructureSource,
   StructureSourceInput,