@plannotator/ui 0.30.0 → 0.32.0

package/components/MarkdownEditor/embedPicker.ts

@@ -0,0 +1,349 @@
+import {
+  pickedCompletion,
+  startCompletion,
+  type Completion,
+  type CompletionSource,
+} from '@codemirror/autocomplete';
+import {
+  EditorState,
+  MapMode,
+  StateEffect,
+  StateField,
+  type Extension,
+  type StateEffectType,
+} from '@codemirror/state';
+import type { EditorView } from '@codemirror/view';
+import type { SlashCommandItem } from '@plannotator/atomic-editor';
+import { planEmbedInsert } from '@plannotator/core/embed-insert';
+
+/** What an embed can point at. The union grows as new media kinds ship. */
+export type EmbedKind = 'html';
+
+/** One embeddable target supplied by the host. */
+export interface EmbedTarget {
+  /** Media kind represented by this target. */
+  readonly kind: EmbedKind;
+  /** Host-meaningful target identifier or path. */
+  readonly path: string;
+  /** Display title. Blank and absent titles fall back to {@link path}. */
+  readonly title?: string | null;
+}
+
+/** Per-editor host callbacks for the `/embed` picker. */
+export interface EmbedPickerConfig {
+  /** Live read of embeddable targets. Dynamic data belongs behind this callback. */
+  readonly getTargets: () => readonly EmbedTarget[];
+  /** Build the exact host-owned embed line for a picked target. */
+  readonly buildInsertLine: (target: EmbedTarget) => string;
+  /**
+   * Optionally upload a target. Resolve with a target to insert it, or `null`
+   * when the user cancels. The host owns error presentation.
+   */
+  readonly uploadTarget?: (kind: EmbedKind) => Promise<EmbedTarget | null>;
+  /** Return an optional informational row for the current document text. */
+  readonly getNotice?: (docBody: string) => string | null;
+}
+
+type IconCompletion = Completion & {
+  readonly slashCommandIcon?: string;
+};
+
+type UploadAnchor = {
+  readonly from: number;
+  readonly to: number;
+  readonly text: string;
+};
+
+type UploadState =
+  | { readonly _tag: 'idle' }
+  | { readonly _tag: 'uploading'; readonly anchor: UploadAnchor | null };
+
+type UploadStateEffect =
+  | { readonly _tag: 'start'; readonly anchor: UploadAnchor }
+  | { readonly _tag: 'finish' };
+
+type UploadStateEffectType = StateEffectType<UploadStateEffect>;
+
+const IDLE_UPLOAD_STATE: UploadState = { _tag: 'idle' };
+const EMBED_PREFIX = '/embed ';
+const HTML_KIND: EmbedKind = 'html';
+
+// Framed `</>` for an HTML document rendered in place. This follows the
+// editor package convention: 16x16 viewBox, currentColor, 1.5 stroke.
+const EMBED_ICON =
+  '<svg viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="12" height="10" rx="1.5"/><path d="M6.4 6 4.4 8l2 2"/><path d="M9.6 6 11.6 8l-2 2"/></svg>';
+
+// A document with an upward arrow. `slashCommands()` owns the shared menu's
+// icon renderer; its completion metadata lets this picker use the same gutter.
+const UPLOAD_ICON =
+  '<svg viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3 8.5V13h10V8.5"/><path d="M8 11V3M5 6l3-3 3 3"/></svg>';
+
+/**
+ * Build the static slash-menu item that hands completion to the `/embed` picker.
+ *
+ * @returns A slash command that rewrites the typed query to `/embed ` and
+ * immediately reopens completion.
+ */
+export function embedSlashItem(): SlashCommandItem {
+  return {
+    label: 'Embed HTML',
+    detail: 'live preview',
+    icon: EMBED_ICON,
+    apply: (view, completion, from, to) => {
+      view.dispatch({
+        changes: { from, to, insert: EMBED_PREFIX },
+        selection: { anchor: from + EMBED_PREFIX.length },
+        annotations: pickedCompletion.of(completion),
+      });
+      startCompletion(view);
+    },
+  };
+}
+
+/**
+ * Build the `/embed` target picker extension for one editor mount.
+ *
+ * The editor captures extensions once per document mount. Keep the returned
+ * extension stable and feed changing target data through the config callbacks.
+ *
+ * @param config - Host target, serialization, upload, and notice callbacks.
+ * @returns A CodeMirror extension that composes with `slashCommands()`.
+ */
+export function embedPicker(config: EmbedPickerConfig): Extension {
+  const uploadStateEffect = StateEffect.define<UploadStateEffect>();
+  const uploadStateField = StateField.define<UploadState>({
+    create: () => IDLE_UPLOAD_STATE,
+    update: (current, transaction) => {
+      let next = current;
+      if (next._tag === 'uploading' && next.anchor !== null && transaction.docChanged) {
+        const mappedFrom = transaction.changes.mapPos(next.anchor.from, 1, MapMode.TrackAfter);
+        const mappedTo = transaction.changes.mapPos(next.anchor.to, -1, MapMode.TrackBefore);
+        next = {
+          _tag: 'uploading',
+          anchor:
+            mappedFrom === null || mappedTo === null || mappedFrom > mappedTo
+              ? null
+              : { ...next.anchor, from: mappedFrom, to: mappedTo },
+        };
+      }
+
+      for (const effect of transaction.effects) {
+        if (!effect.is(uploadStateEffect)) continue;
+        next =
+          effect.value._tag === 'start'
+            ? { _tag: 'uploading', anchor: effect.value.anchor }
+            : IDLE_UPLOAD_STATE;
+      }
+      return next;
+    },
+  });
+
+  const source = createEmbedPickerSource(config, uploadStateField, uploadStateEffect);
+  return [uploadStateField, EditorState.languageData.of(() => [{ autocomplete: source }])];
+}
+
+function createEmbedPickerSource(
+  config: EmbedPickerConfig,
+  uploadStateField: StateField<UploadState>,
+  uploadStateEffect: UploadStateEffectType,
+): CompletionSource {
+  return (context) => {
+    const match = context.matchBefore(/\/embed +[^\n]*$/);
+    if (match === null) return null;
+
+    // Like the package slash source, the trigger must open its line. An embed
+    // is a block insertion and belongs in its own paragraph.
+    const line = context.state.doc.lineAt(match.from);
+    if (!/^\s*$/.test(line.text.slice(0, match.from - line.from))) return null;
+
+    const query = match.text.replace(/^\/embed +/, '');
+    const targets = config.getTargets().filter((target) => target.kind === HTML_KIND);
+    const matches = filterTargets(targets, query);
+    const options: IconCompletion[] = [];
+    const notice = config.getNotice?.(context.state.doc.toString()) ?? null;
+    if (notice !== null) {
+      options.push({
+        label: notice,
+        apply: () => {
+          // Informational row: selection closes the menu and leaves the typed
+          // command in place so the author can keep deciding.
+        },
+      });
+    }
+
+    if (matches.length === 0) {
+      options.push({
+        label:
+          targets.length === 0
+            ? 'No HTML files in this workspace'
+            : `No HTML files match “${query.trim()}”`,
+        apply: (view, completion, _from, to) => {
+          view.dispatch({
+            changes: { from: line.from, to, insert: '' },
+            annotations: pickedCompletion.of(completion),
+          });
+        },
+      });
+    } else {
+      for (const target of matches) {
+        options.push({
+          label: targetLabel(target),
+          detail: target.path,
+          apply: (view, completion, from, to) => {
+            applyTargetInsert(view, completion, from, to, target, config.buildInsertLine);
+          },
+        });
+      }
+    }
+
+    const uploadTarget = config.uploadTarget;
+    if (uploadTarget !== undefined) {
+      const uploadState = context.state.field(uploadStateField);
+      options.push(
+        uploadState._tag === 'uploading'
+          ? {
+              label: 'Uploading...',
+              slashCommandIcon: UPLOAD_ICON,
+              apply: () => {
+                // Inert while the existing host callback is still pending.
+              },
+            }
+          : {
+              label: 'Upload HTML...',
+              slashCommandIcon: UPLOAD_ICON,
+              apply: (view, completion, from, to) => {
+                startUpload(
+                  view,
+                  completion,
+                  from,
+                  to,
+                  config,
+                  uploadTarget,
+                  uploadStateField,
+                  uploadStateEffect,
+                );
+              },
+            },
+      );
+    }
+
+    return {
+      // The entire `/embed query` is the completion range. Our case-insensitive
+      // substring matcher owns filtering because CM's fuzzy matcher closes a
+      // completion session when a title query contains spaces.
+      from: match.from,
+      options,
+      filter: false,
+    };
+  };
+}
+
+function filterTargets(targets: readonly EmbedTarget[], query: string): readonly EmbedTarget[] {
+  const needle = query.trim().toLowerCase();
+  if (needle === '') return targets;
+  return targets.filter((target) => {
+    const title = (target.title ?? '').toLowerCase();
+    return title.includes(needle) || target.path.toLowerCase().includes(needle);
+  });
+}
+
+function targetLabel(target: EmbedTarget): string {
+  const title = target.title ?? '';
+  return title.trim() === '' ? target.path : title;
+}
+
+function applyTargetInsert(
+  view: EditorView,
+  completion: Completion,
+  from: number,
+  to: number,
+  target: EmbedTarget,
+  buildInsertLine: EmbedPickerConfig['buildInsertLine'],
+): void {
+  const body = view.state.doc.toString();
+  const plan = planEmbedInsert(body, from, to, buildInsertLine(target));
+  view.dispatch({
+    changes: { from: plan.from, to: plan.to, insert: plan.insert },
+    selection: { anchor: plan.cursor },
+    scrollIntoView: true,
+    annotations: pickedCompletion.of(completion),
+  });
+}
+
+function startUpload(
+  view: EditorView,
+  completion: Completion,
+  from: number,
+  to: number,
+  config: EmbedPickerConfig,
+  uploadTarget: NonNullable<EmbedPickerConfig['uploadTarget']>,
+  uploadStateField: StateField<UploadState>,
+  uploadStateEffect: UploadStateEffectType,
+): void {
+  const uploadState = view.state.field(uploadStateField, false);
+  if (uploadState?._tag === 'uploading') return;
+
+  const anchor: UploadAnchor = {
+    from,
+    to,
+    text: view.state.doc.sliceString(from, to),
+  };
+  view.dispatch({
+    effects: uploadStateEffect.of({ _tag: 'start', anchor }),
+    annotations: pickedCompletion.of(completion),
+  });
+
+  void (async () => {
+    try {
+      const target = await uploadTarget(HTML_KIND);
+      finishUpload(view, completion, target, config, uploadStateField, uploadStateEffect);
+    } catch {
+      clearUpload(view, uploadStateField, uploadStateEffect);
+    }
+  })();
+}
+
+function finishUpload(
+  view: EditorView,
+  completion: Completion,
+  target: EmbedTarget | null,
+  config: EmbedPickerConfig,
+  uploadStateField: StateField<UploadState>,
+  uploadStateEffect: UploadStateEffectType,
+): void {
+  const uploadState = view.state.field(uploadStateField, false);
+  if (uploadState?._tag !== 'uploading') return;
+
+  const anchor = uploadState.anchor;
+  if (target === null || anchor === null || !isLiveAnchor(view, anchor)) {
+    clearUpload(view, uploadStateField, uploadStateEffect);
+    return;
+  }
+
+  const body = view.state.doc.toString();
+  const plan = planEmbedInsert(body, anchor.from, anchor.to, config.buildInsertLine(target));
+  view.dispatch({
+    changes: { from: plan.from, to: plan.to, insert: plan.insert },
+    selection: { anchor: plan.cursor },
+    scrollIntoView: true,
+    effects: uploadStateEffect.of({ _tag: 'finish' }),
+    annotations: pickedCompletion.of(completion),
+  });
+}
+
+function isLiveAnchor(view: EditorView, anchor: UploadAnchor): boolean {
+  if (anchor.from > anchor.to || anchor.to > view.state.doc.length) return false;
+  if (view.state.doc.sliceString(anchor.from, anchor.to) !== anchor.text) return false;
+  const line = view.state.doc.lineAt(anchor.from);
+  return /^\s*$/.test(line.text.slice(0, anchor.from - line.from));
+}
+
+function clearUpload(
+  view: EditorView,
+  uploadStateField: StateField<UploadState>,
+  uploadStateEffect: UploadStateEffectType,
+): void {
+  const uploadState = view.state.field(uploadStateField, false);
+  if (uploadState?._tag !== 'uploading') return;
+  view.dispatch({ effects: uploadStateEffect.of({ _tag: 'finish' }) });
+}

package/components/MarkdownEditor.tsx

@@ -34,6 +34,18 @@ export type { SlashCommandItem, SlashCommandsConfig } from '@plannotator/atomic-
 export { selectionToolbar } from '@plannotator/atomic-editor';
 export type { SelectionToolbarConfig, InlineFormat } from '@plannotator/atomic-editor';
 
+/* Host-configured embed media authoring. The picker is per editor mount so its
+   callbacks can close over live route state; nothing enters configurePlannotatorUI.
+   The package owns paragraph-safe splicing while the host owns embed grammar. */
+export { embedPicker, embedSlashItem } from './MarkdownEditor/embedPicker';
+export type {
+  EmbedKind,
+  EmbedPickerConfig,
+  EmbedTarget,
+} from './MarkdownEditor/embedPicker';
+export { planEmbedInsert } from '@plannotator/core/embed-insert';
+export type { EmbedInsertPlan } from '@plannotator/core/embed-insert';
+
 /* Grid-mode card utilities stay here (not in the package): they're Plannotator
    design-system Tailwind classes, and this file is @source-scanned. */
 const GRID_CARD_CLASSES = 'px-5 md:px-8 lg:px-10 xl:px-12 shadow-xl border border-border/50';

package/components/MermaidBlock.tsx

@@ -1,33 +1,26 @@
 import React, { useRef, useState, useEffect, useCallback } from 'react';
 import { createPortal } from 'react-dom';
-import mermaid from 'mermaid';
+import type { Mermaid } from 'mermaid';
 import type { Block } from '../types';
 import { normalizeMermaidSvgMarkup } from './mermaidSvg';
+import {
+  MERMAID_CONFIG,
+  getMermaidRetryDelayMs,
+  loadMermaidRuntime,
+  __setMermaidRuntimeLoaderForTests,
+} from '../utils/mermaid';
 
-mermaid.initialize({
-  startOnLoad: false,
-  securityLevel: 'strict',
-  theme: 'dark',
-  themeVariables: {
-    primaryColor: '#3b82f6',
-    primaryTextColor: '#f8fafc',
-    primaryBorderColor: '#475569',
-    lineColor: '#64748b',
-    secondaryColor: '#1e293b',
-    tertiaryColor: '#0f172a',
-    background: '#1e293b',
-    mainBkg: '#1e293b',
-    nodeBorder: '#475569',
-    clusterBkg: '#1e293b',
-    clusterBorder: '#475569',
-    titleColor: '#f8fafc',
-    edgeLabelBackground: '#1e293b',
-  },
-  flowchart: {
-    htmlLabels: true,
-    curve: 'basis',
-  },
-});
+// Re-exported: the config pin test and the lazy-retry test import them from here.
+export { MERMAID_CONFIG, __setMermaidRuntimeLoaderForTests };
+
+/**
+ * The runtime comes from the slot in utils/mermaid: filled eagerly by
+ * Plannotator (utils/mermaid-eager, imported by the editor App), loaded
+ * lazily otherwise. See that module for the retry contract.
+ */
+const getMermaid = loadMermaidRuntime;
+
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
 
 interface ViewBox {
   x: number;
@@ -133,6 +126,11 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
   const expandedOverlayRef = useRef<HTMLDivElement>(null);
   const [svg, setSvg] = useState('');
   const [error, setError] = useState<string | null>(null);
+  // True when the failure was the runtime import itself (a chunking host's
+  // fetch), which is the only failure a Retry can change; a diagram syntax
+  // error keeps the panel exactly as it always was.
+  const [runtimeUnavailable, setRuntimeUnavailable] = useState(false);
+  const [retryToken, setRetryToken] = useState(0);
   const [showSource, setShowSource] = useState(false);
   const [isExpanded, setIsExpanded] = useState(false);
 
@@ -188,6 +186,27 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
 
     // Render mermaid diagram
     const renderDiagram = async () => {
+      let mermaid: Mermaid;
+      try {
+        try {
+          mermaid = await getMermaid();
+        } catch {
+          // Transient chunk failure on a chunking host: one automatic
+          // re-attempt with a fresh import() after a short delay. In a
+          // single-file build the first await never rejects, so this branch
+          // is unreachable there and the success path is unchanged.
+          await wait(getMermaidRetryDelayMs());
+          if (cancelled) return;
+          mermaid = await getMermaid();
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : 'Failed to render diagram');
+          setRuntimeUnavailable(true);
+          setSvg('');
+        }
+        return;
+      }
       try {
         const id = `mermaid-${block.id}`;
         const { svg: renderedSvg } = await mermaid.render(id, block.content);
@@ -196,10 +215,12 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
           naturalBoundsRef.current = parseViewBoxFromMarkup(normalizedSvg);
           setSvg(normalizedSvg);
           setError(null);
+          setRuntimeUnavailable(false);
         }
       } catch (err) {
         if (!cancelled) {
           setError(err instanceof Error ? err.message : 'Failed to render diagram');
+          setRuntimeUnavailable(false);
           setSvg('');
         }
       }
@@ -210,7 +231,7 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
     return () => {
       cancelled = true;
     };
-  }, [block.content, block.id]);
+  }, [block.content, block.id, retryToken]);
 
   // Reset zoom and pan when content changes
   useEffect(() => {
@@ -419,6 +440,19 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
             <path strokeLinecap="round" strokeLinejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
           </svg>
           <span className="text-xs text-destructive font-medium">Mermaid Error</span>
+          {runtimeUnavailable && (
+            <button
+              type="button"
+              onClick={() => {
+                setError(null);
+                setRetryToken((token) => token + 1);
+              }}
+              className="ml-auto rounded-md border border-destructive/30 px-2 py-0.5 text-xs text-destructive hover:bg-destructive/10"
+              title="Retry loading the diagram renderer"
+            >
+              Retry
+            </button>
+          )}
         </div>
         <pre className="p-3 text-xs text-destructive/80 overflow-x-auto">{error}</pre>
         <pre className="p-3 text-xs text-muted-foreground bg-muted/30 border-t border-border/30 overflow-x-auto">

package/components/ModeToggle.tsx

@@ -21,8 +21,9 @@ export function ModeToggle() {
     <div className="relative" ref={dropdownRef}>
       <button
         onClick={() => setIsOpen(!isOpen)}
-        className="p-1.5 rounded-md text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
+        className="p-1.5 rounded-md text-muted-foreground hover:text-foreground hover:bg-muted transition-colors relative pointer-coarse:before:absolute pointer-coarse:before:-inset-2 pointer-coarse:before:content-['']"
         title="Toggle theme"
+        aria-label="Toggle theme"
       >
         {/* Sun */}
         <svg

package/components/PermissionModeSetup.tsx

@@ -25,10 +25,29 @@ export const PermissionModeSetup: React.FC<PermissionModeSetupProps> = ({
   };
 
   return createPortal(
-    <div className="fixed inset-0 z-[100] flex items-center justify-center bg-background/90 backdrop-blur-sm p-4">
-      <div className="bg-card border border-border rounded-xl w-full max-w-lg shadow-2xl">
+    // Same bounded shell as the sibling one-time dialogs (see
+    // LookAndFeelAnnouncementDialog): safe-area padding, a card capped to the
+    // visible viewport, and the option list as the only scrolling region. The
+    // hand-rolled unbounded card used to overflow both edges of a short
+    // landscape phone with nothing left to tap.
+    <div
+      className="fixed inset-0 z-[100] flex items-center justify-center overflow-y-auto bg-background/90 backdrop-blur-sm"
+      style={{
+        paddingTop: 'max(1rem, var(--pn-safe-top, 0px))',
+        paddingRight: 'max(1rem, var(--pn-safe-right, 0px))',
+        paddingBottom: 'max(1rem, var(--pn-safe-bottom, 0px))',
+        paddingLeft: 'max(1rem, var(--pn-safe-left, 0px))',
+      }}
+    >
+      <div
+        className="bg-card border border-border rounded-xl w-full max-w-lg shadow-2xl flex flex-col overflow-hidden"
+        style={{
+          maxHeight:
+            'calc(var(--pn-viewport-height, 100vh) - max(1rem, var(--pn-safe-top, 0px)) - max(1rem, var(--pn-safe-bottom, 0px)))',
+        }}
+      >
         {/* Header */}
-        <div className="p-5 border-b border-border">
+        <div className="p-5 border-b border-border flex-shrink-0">
           <div className="flex items-center gap-2 mb-2">
             <div className="p-1.5 rounded-lg bg-primary/15">
               <svg className="w-5 h-5 text-primary" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
@@ -47,7 +66,7 @@ export const PermissionModeSetup: React.FC<PermissionModeSetupProps> = ({
         </div>
 
         {/* Options */}
-        <div className="p-4 space-y-2">
+        <div className="min-h-0 flex-1 overflow-y-auto p-4 space-y-2">
           {PERMISSION_MODE_OPTIONS.map((option) => (
             <label
               key={option.value}
@@ -74,7 +93,7 @@ export const PermissionModeSetup: React.FC<PermissionModeSetupProps> = ({
         </div>
 
         {/* Footer */}
-        <div className="p-4 border-t border-border flex justify-between items-center">
+        <div className="p-4 border-t border-border flex flex-shrink-0 flex-wrap gap-2 justify-between items-center">
           <p className="text-xs text-muted-foreground">
             You can change this later in Settings.
           </p>

package/components/PinpointOverlay.tsx

@@ -1,5 +1,8 @@
 import React, { useLayoutEffect, useState, useRef } from 'react';
-import { useScrollViewport } from '../hooks/useScrollViewport';
+import {
+  addScrollViewportListener,
+  useScrollViewport,
+} from '../hooks/useScrollViewport';
 
 interface PinpointOverlayProps {
   target: { element: HTMLElement; label: string } | null;
@@ -49,15 +52,17 @@ export const PinpointOverlay: React.FC<PinpointOverlayProps> = ({ target, contai
     // delivers its viewport.
     window.addEventListener('resize', handleUpdate, { passive: true });
 
-    // The scroll element is the OverlayScrollArea viewport. Falling back to
-    // <main> or window would attach to the wrong node and the overlay
-    // position would drift silently on scroll.
-    scrollViewport?.addEventListener('scroll', handleUpdate, { passive: true });
+    // The shared viewport is the nested main element on desktop and the page
+    // scroller on compact touch layouts. The helper binds the latter to the
+    // window scroll event so the overlay does not drift as Safari chrome moves.
+    const removeScrollListener = scrollViewport
+      ? addScrollViewportListener(scrollViewport, handleUpdate)
+      : undefined;
 
     return () => {
       cancelAnimationFrame(rafRef.current);
       window.removeEventListener('resize', handleUpdate);
-      scrollViewport?.removeEventListener('scroll', handleUpdate);
+      removeScrollListener?.();
     };
   }, [target, containerRef, scrollViewport]);