@glw907/cairn-cms 0.38.0 → 0.41.0

package/src/lib/components/EditorToolbar.svelte

@@ -1,35 +1,62 @@
 <!--
 @component
-The editor's formatting toolbar: bold, italic, heading, link, bulleted list, quote, code. Each button
-asks the host to apply a markdown transform to the current selection. Carta supplied this row before;
-cairn owns it now so the edit surface stays swappable. The glyphs are stroke SVG icons in the admin's
-house style (24x24 viewBox, `currentColor`, round caps), so the row matches the rest of the surface.
+The editor card's instrument strip. Three button groups divided by hairlines (Text, Structure with a
+More overflow menu, then the host's Insert controls) and the Write/Preview segmented control pinned
+right. Format buttons ask the host to transform the editor's current selection; the host supplies the
+Insert group through the `insertControls` snippet so the strip stays free of picker wiring. The glyphs
+are stroke SVG icons in the admin's house style (24x24 viewBox, `currentColor`, round caps).
 -->
 <script lang="ts">
+  import type { Snippet } from 'svelte';
   import type { FormatKind } from './markdown-format.js';
 
   interface Props {
     /** Apply a markdown transform to the editor's current selection. */
     format: (kind: FormatKind) => void;
+    /** Which pane the editor card shows; the segmented control reflects it. */
+    mode: 'write' | 'preview';
+    /** Ask the host to switch panes. */
+    onMode: (m: 'write' | 'preview') => void;
+    /** The host's Insert controls (link picker, component insert, image), rendered in the Insert group. */
+    insertControls?: Snippet;
   }
 
-  let { format }: Props = $props();
+  let { format, mode, onMode, insertControls }: Props = $props();
 
   // Each icon is a set of stroke `<path>` d-strings rendered into the shared 24x24 svg below, so the
   // markup stays declarative (no per-icon raw html). Paths follow the house outline style.
-  const buttons: { kind: FormatKind; label: string; paths: string[] }[] = [
-    { kind: 'bold', label: 'Bold', paths: ['M6 12h9a4 4 0 0 1 0 8H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h7a4 4 0 0 1 0 8'] },
-    { kind: 'italic', label: 'Italic', paths: ['M19 4h-9', 'M14 20H5', 'M15 4 9 20'] },
-    { kind: 'heading', label: 'Heading', paths: ['M6 4v16', 'M18 4v16', 'M6 12h12'] },
+  type ToolButton = { kind: FormatKind; label: string; paths: string[] };
+
+  // Labels carry the shortcut where one exists. "Ctrl" is written literally for macOS readers
+  // too; detecting the platform buys little for what it costs.
+  const textButtons: ToolButton[] = [
+    { kind: 'bold', label: 'Bold (Ctrl+B)', paths: ['M6 12h9a4 4 0 0 1 0 8H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h7a4 4 0 0 1 0 8'] },
+    { kind: 'italic', label: 'Italic (Ctrl+I)', paths: ['M19 4h-9', 'M14 20H5', 'M15 4 9 20'] },
+  ];
+
+  const structureButtons: ToolButton[] = [
+    {
+      kind: 'h2',
+      label: 'Heading',
+      paths: ['M4 12h8', 'M4 18V6', 'M12 18V6', 'M21 18h-4c0-4 4-3 4-6 0-1.5-2-2.5-4-1'],
+    },
     {
-      kind: 'link',
-      label: 'Link',
+      kind: 'h3',
+      label: 'Smaller heading',
       paths: [
-        'M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71',
-        'M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71',
+        'M4 12h8',
+        'M4 18V6',
+        'M12 18V6',
+        'M17.5 10.5c1.7-1 3.5 0 3.5 1.5a2 2 0 0 1-2 2',
+        'M17 17.5c2 1.5 4 .3 4-1.5a2 2 0 0 0-2-2',
       ],
     },
     { kind: 'ul', label: 'Bulleted list', paths: ['M8 6h13', 'M8 12h13', 'M8 18h13', 'M3 6h.01', 'M3 12h.01', 'M3 18h.01'] },
+    {
+      kind: 'ol',
+      label: 'Numbered list',
+      paths: ['M10 12h11', 'M10 18h11', 'M10 6h11', 'M4 10h2', 'M4 6h1v4', 'M6 18H4c0-1 2-2 2-3s-1-1.5-2-1'],
+    },
     {
       kind: 'quote',
       label: 'Quote',
@@ -38,24 +65,174 @@ house style (24x24 viewBox, `currentColor`, round caps), so the row matches the
         'M5 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1 1 1 0 0 0 1 1 4 4 0 0 0 4-4V5a2 2 0 0 0-2-2z',
       ],
     },
-    { kind: 'code', label: 'Code', paths: ['M16 18l6-6-6-6', 'M8 6l-6 6 6 6'] },
   ];
+
+  const ellipsisPaths = ['M5 12h.01', 'M12 12h.01', 'M19 12h.01'];
+
+  const moreItems: { kind: FormatKind; label: string }[] = [
+    { kind: 'strike', label: 'Strikethrough' },
+    { kind: 'code', label: 'Inline code' },
+    { kind: 'codeblock', label: 'Code block' },
+    { kind: 'table', label: 'Table' },
+    { kind: 'hr', label: 'Horizontal rule' },
+    { kind: 'task', label: 'Task list' },
+  ];
+
+  // The More menu's popover element and its open state, mirrored from the toggle event into
+  // aria-expanded on the trigger.
+  let moreMenu = $state<HTMLUListElement | null>(null);
+  let moreOpen = $state(false);
+
+  function pickMore(kind: FormatKind) {
+    format(kind);
+    // Picking dismisses the menu; hiding returns focus to the trigger, keeping the roving order.
+    if (moreMenu?.matches(':popover-open')) moreMenu.hidePopover();
+  }
+
+  let toolbarEl = $state<HTMLDivElement | null>(null);
+  // The roving tab stop's position among the strip's enabled top-level controls. The Write/Preview
+  // tabs join the toolbar's roving order instead of managing their own arrow keys: the ARIA toolbar
+  // pattern allows either, and one arrow model over the whole strip is the simpler of the two.
+  let roving = $state(0);
+
+  /** The strip's top-level controls in DOM order: every enabled button outside the More menu's
+   *  popover and outside the insert controls' dialogs. The host's insertControls render their own
+   *  buttons, so the set is queried, not declared. */
+  function rovingControls(): HTMLElement[] {
+    if (!toolbarEl) return [];
+    return Array.from(toolbarEl.querySelectorAll<HTMLElement>('button')).filter(
+      (el) => !el.hasAttribute('disabled') && !el.closest('[popover]') && !el.closest('dialog'),
+    );
+  }
+
+  // Keep exactly one tab stop. Runs on mount (the snippet's buttons render synchronously, so the
+  // first pass sees them) and again whenever the stop moves or a mode switch changes which
+  // controls are enabled.
+  $effect(() => {
+    void mode;
+    const items = rovingControls();
+    if (items.length === 0) return;
+    const stop = Math.min(roving, items.length - 1);
+    // Write the clamp back so the stored stop never drifts from the displayed one across a
+    // Preview round trip. The effect reads roving, so the guarded write re-runs it once and
+    // converges (the second pass computes the same stop and writes nothing).
+    if (stop !== roving) roving = stop;
+    for (const [i, el] of items.entries()) el.setAttribute('tabindex', i === stop ? '0' : '-1');
+  });
+
+  function onToolbarKeydown(e: KeyboardEvent) {
+    if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return;
+    // Leave the keys alone inside the open More menu; its items are not part of the roving order.
+    if ((e.target as HTMLElement | null)?.closest('[popover]')) return;
+    const items = rovingControls();
+    if (items.length === 0) return;
+    const current = items.indexOf(document.activeElement as HTMLElement);
+    const base = current >= 0 ? current : Math.min(roving, items.length - 1);
+    roving = (base + (e.key === 'ArrowRight' ? 1 : -1) + items.length) % items.length;
+    items[roving].focus();
+    e.preventDefault();
+  }
 </script>
 
-<div class="border-base-300 bg-base-200 flex gap-1 border-b p-1" role="toolbar" aria-label="Formatting">
-  {#each buttons as button (button.kind)}
-    <button
-      type="button"
-      class="btn btn-ghost btn-sm btn-square"
-      aria-label={button.label}
-      title={button.label}
-      onclick={() => format(button.kind)}
-    >
-      <svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
-        {#each button.paths as d (d)}
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d={d} />
-        {/each}
-      </svg>
-    </button>
+{#snippet strokeIcon(paths: string[])}
+  <svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
+    {#each paths as d (d)}
+      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d={d} />
+    {/each}
+  </svg>
+{/snippet}
+
+{#snippet glyphButton(button: ToolButton)}
+  <button
+    type="button"
+    class="btn btn-ghost btn-sm btn-square"
+    aria-label={button.label}
+    title={button.label}
+    disabled={mode === 'preview'}
+    onclick={() => format(button.kind)}
+  >
+    {@render strokeIcon(button.paths)}
+  </button>
+{/snippet}
+
+{#snippet tab(m: 'write' | 'preview', label: string)}
+  <button
+    type="button"
+    role="tab"
+    id={`cairn-tab-${m}`}
+    aria-selected={mode === m}
+    aria-controls={`cairn-pane-${m}`}
+    class="join-item btn btn-sm {mode === m ? 'btn-active' : 'btn-ghost'}"
+    onclick={() => onMode(m)}
+  >
+    {label}
+  </button>
+{/snippet}
+
+<!-- tabindex -1: the container is never a tab stop itself; the roving tabindex on its controls
+     carries keyboard entry, per the ARIA toolbar pattern. -->
+<div
+  bind:this={toolbarEl}
+  class="bg-base-100 flex flex-wrap items-center gap-1 border-b border-[var(--cairn-card-border)] p-1"
+  role="toolbar"
+  aria-label="Formatting"
+  tabindex="-1"
+  onkeydown={onToolbarKeydown}
+>
+  {#each textButtons as button (button.kind)}
+    {@render glyphButton(button)}
+  {/each}
+
+  <div class="w-px self-stretch bg-[var(--cairn-card-border)]" aria-hidden="true"></div>
+
+  {#each structureButtons as button (button.kind)}
+    {@render glyphButton(button)}
   {/each}
+  <!-- The More menu is a DaisyUI v5 popover dropdown: click to open (never focus-in-transit),
+       Escape and light dismiss from the Popover API, and the anchor-name/position-anchor pair
+       places the panel under its trigger. -->
+  <button
+    type="button"
+    class="btn btn-ghost btn-sm btn-square"
+    aria-label="More formatting"
+    title="More formatting"
+    aria-expanded={moreOpen}
+    popovertarget="cairn-more-formatting-menu"
+    style="anchor-name:--cairn-more-formatting"
+    disabled={mode === 'preview'}
+  >
+    {@render strokeIcon(ellipsisPaths)}
+  </button>
+  <ul
+    bind:this={moreMenu}
+    popover="auto"
+    id="cairn-more-formatting-menu"
+    style="position-anchor:--cairn-more-formatting"
+    ontoggle={(e) => (moreOpen = e.newState === 'open')}
+    class="dropdown menu menu-sm bg-base-100 rounded-box w-44 border border-[var(--cairn-card-border)] p-1 shadow-[var(--cairn-shadow)]"
+  >
+    {#each moreItems as item (item.kind)}
+      <li><button type="button" onclick={() => pickMore(item.kind)}>{item.label}</button></li>
+    {/each}
+  </ul>
+
+  {#if insertControls}
+    <div class="w-px self-stretch bg-[var(--cairn-card-border)]" aria-hidden="true"></div>
+    <!-- The host's controls carry their own disabled state in Preview; this wrapper just keeps
+         any stray pointer target in the snippet inert while the pane is read-only. -->
+    <div
+      class="flex items-center gap-1"
+      class:pointer-events-none={mode === 'preview'}
+      class:opacity-50={mode === 'preview'}
+    >
+      {@render insertControls()}
+    </div>
+  {/if}
+
+  <!-- The host renders the matching tabpanels (#cairn-pane-write and #cairn-pane-preview) below
+       the strip inside the same editor card. -->
+  <div class="join ml-auto" role="tablist" aria-label="Editor view">
+    {@render tab('write', 'Write')}
+    {@render tab('preview', 'Preview')}
+  </div>
 </div>

package/src/lib/components/LinkPicker.svelte

@@ -4,7 +4,7 @@ The "Link to page" control and its modal. It lists the site's posts and pages fr
 manifest (the linkTargets the editor receives), grouped by concept with Pages first, each post
 showing its date and each draft marked. Picking a target inserts a cairn: internal link through the
 editor's registerInsertLink seam. Built on a native <dialog>, following the component dialog's a11y
-conventions. The plain-URL link stays the toolbar's link button; this is for an internal target.
+conventions. The plain-URL link is the toolbar's Web link dialog; this is for an internal target.
 -->
 <script lang="ts">
   import type { LinkTarget } from '../content/manifest.js';
@@ -15,9 +15,14 @@ conventions. The plain-URL link stays the toolbar's link button; this is for an
     linkTargets: LinkTarget[];
     /** Insert an inline cairn link at the editor cursor. */
     insert: (href: string, title: string) => void;
+    /** Disable the trigger; the host sets it while Preview shows. */
+    disabled?: boolean;
+    /** Render the built-in Link to page trigger. False mounts only the dialog, for a host that
+     *  supplies its own trigger and opens the dialog through the exported open(). */
+    trigger?: boolean;
   }
 
-  let { linkTargets, insert }: Props = $props();
+  let { linkTargets, insert, disabled = false, trigger = true }: Props = $props();
 
   let dialog = $state<HTMLDialogElement | null>(null);
   let query = $state('');
@@ -48,7 +53,8 @@ conventions. The plain-URL link stays the toolbar's link button; this is for an
       .sort((a, b) => rank(a.concept) - rank(b.concept) || a.heading.localeCompare(b.heading));
   });
 
-  function open() {
+  /** Open the picker programmatically, for a host that drives it without the trigger. */
+  export function open() {
     query = '';
     dialog?.showModal();
   }
@@ -61,9 +67,11 @@ conventions. The plain-URL link stays the toolbar's link button; this is for an
   }
 </script>
 
-<button type="button" class="btn btn-sm btn-ghost" aria-haspopup="dialog" aria-label="Link to page" onclick={open}>
-  Link to page
-</button>
+{#if trigger}
+  <button type="button" class="btn btn-sm btn-ghost" aria-haspopup="dialog" aria-label="Link to page" {disabled} onclick={open}>
+    Link to page
+  </button>
+{/if}
 
 <dialog class="modal" aria-labelledby="cairn-link-dialog-title" bind:this={dialog}>
   <div class="modal-box">

package/src/lib/components/MarkdownEditor.svelte

@@ -1,15 +1,15 @@
 <!--
 @component
 The `MarkdownEditor` seam (spec §6, seam 5): a thin wrapper over CodeMirror 6 exposing a bindable
-value and a cursor-insert callback. CodeMirror is client-only, so it mounts after the component does
+value and cursor-edit callbacks. CodeMirror is client-only, so it mounts after the component does
 through a dynamic import; until then a plain textarea carries the value so the form still submits, and
-the hidden field mirrors the value throughout. The edit surface owns its toolbar; the design-accurate
-preview lives in EditPage through the adapter's render. Swapping the editor stays a one-file change.
+the hidden field mirrors the value throughout. The host owns the toolbar and the card chrome, driving
+selection transforms through the registerFormat seam; the design-accurate preview lives in EditPage
+through the adapter's render. Swapping the editor stays a one-file change.
 -->
 <script lang="ts">
   import { onMount, onDestroy } from 'svelte';
-  import EditorToolbar from './EditorToolbar.svelte';
-  import { applyMarkdownFormat, insertInlineLink, type FormatKind } from './markdown-format.js';
+  import { applyMarkdownFormat, insertInlineLink, type FormatKind, type FormatResult } from './markdown-format.js';
 
   interface Props {
     /** The markdown source; bindable so the parent reads edits back. */
@@ -20,12 +20,24 @@ preview lives in EditPage through the adapter's render. Swapping the editor stay
     registerInsert?: (insert: (text: string) => void) => void;
     /** Receives a `(href, title) => void` that inserts an inline link; the link picker calls it. */
     registerInsertLink?: (insert: (href: string, title: string) => void) => void;
+    /** Receives a `() => string` returning the selected text; the web link dialog reads it. */
+    registerGetSelection?: (get: () => string) => void;
+    /** Receives a `(kind) => void` that transforms the current selection; the host's toolbar calls it. */
+    registerFormat?: (format: (kind: FormatKind) => void) => void;
     /** Generic CodeMirror completion sources wired into the editor; the link autocomplete is one. The
      *  type is referenced inline so no static `@codemirror/*` import sits in this client-only file. */
     completionSources?: import('@codemirror/autocomplete').CompletionSource[];
   }
 
-  let { value = $bindable(), name, registerInsert, registerInsertLink, completionSources = [] }: Props = $props();
+  let {
+    value = $bindable(),
+    name,
+    registerInsert,
+    registerInsertLink,
+    registerGetSelection,
+    registerFormat,
+    completionSources = [],
+  }: Props = $props();
 
   let host = $state<HTMLDivElement | null>(null);
   let mounted = $state(false);
@@ -41,19 +53,47 @@ preview lives in EditPage through the adapter's render. Swapping the editor stay
     const commandsMod = await import('@codemirror/commands');
     const languageMod = await import('@codemirror/language');
     const autocompleteMod = await import('@codemirror/autocomplete');
+    const highlightMod = await import('./editor-highlight.js');
 
     if (!host) return;
 
     const { EditorView, keymap } = viewMod;
+    // Mirror the admin theme into CodeMirror's own dark flag, so its base chrome (the autocomplete
+    // tooltip above all) renders dark-on-dark instead of light-on-dark.
+    const isDark = host.closest('[data-theme]')?.getAttribute('data-theme')?.includes('dark') ?? false;
+    // The directive machinery ink, one rule for the fence, leaf, and inline decorations.
+    const directiveInk = {
+      backgroundColor: 'color-mix(in oklab, var(--color-accent) 8%, transparent)',
+      color: 'var(--color-accent)',
+    };
     const theme = EditorView.theme(
       {
-        '&': { backgroundColor: 'var(--color-base-100)', color: 'var(--color-base-content)', fontSize: '0.875rem' },
-        '.cm-content': { fontFamily: 'ui-monospace, monospace', padding: '0.75rem', lineHeight: '1.7' },
+        '&': { backgroundColor: 'var(--color-base-100)', color: 'var(--color-base-content)', fontSize: '0.9375rem' },
+        // The 50vh floor keeps a short entry reading as a writing surface, and because the
+        // contenteditable content area carries the height, a click in the empty space below the
+        // text still lands in the editor and focuses it.
+        '.cm-content': {
+          fontFamily: 'ui-monospace, monospace',
+          padding: '0.875rem 1.25rem',
+          lineHeight: '1.8',
+          minHeight: '50vh',
+        },
         '.cm-cursor': { borderLeftColor: 'var(--color-primary)' },
-        '&.cm-focused': { outline: '2px solid var(--color-primary)', outlineOffset: '-2px' },
+        // A quiet always-on focus hairline. :focus-visible is no escape here: browsers treat a
+        // focused text-entry surface as keyboard-modal, so a 2px ring would shout through every
+        // typing session. One subtle line keeps focus visible (WCAG 2.4.7) without competing
+        // with the manuscript. The 70% primary mix clears the 3:1 non-text contrast floor
+        // (WCAG 1.4.11) on both themes (3.23:1 light, 3.32:1 dark), where 45% measured near 2:1.
+        '&.cm-focused': {
+          outline: '1px solid color-mix(in oklab, var(--color-primary) 70%, transparent)',
+          outlineOffset: '-1px',
+        },
         '.cm-line': { padding: '0' },
+        '.cm-cairn-directive-fence': directiveInk,
+        '.cm-cairn-directive-leaf': directiveInk,
+        '.cm-cairn-directive-inline': directiveInk,
       },
-      { dark: false },
+      { dark: isDark },
     );
 
     view = new EditorView({
@@ -70,7 +110,9 @@ preview lives in EditPage through the adapter's render. Swapping the editor stay
               [autocompleteMod.autocompletion({ override: completionSources, interactionDelay: 0 })]
             : []),
           EditorView.lineWrapping,
-          languageMod.syntaxHighlighting(languageMod.defaultHighlightStyle, { fallback: true }),
+          languageMod.syntaxHighlighting(highlightMod.cairnHighlightStyle()),
+          highlightMod.cairnDirectivePlugin(),
+          EditorView.contentAttributes.of({ spellcheck: 'true', autocorrect: 'on', autocapitalize: 'sentences' }),
           theme,
           EditorView.updateListener.of((update) => {
             if (update.docChanged) value = update.state.doc.toString();
@@ -81,6 +123,8 @@ preview lives in EditPage through the adapter's render. Swapping the editor stay
 
     registerInsert?.(insertAtCursor);
     registerInsertLink?.(insertLink);
+    registerGetSelection?.(selectedText);
+    registerFormat?.(applyFormat);
     mounted = true;
   });
 
@@ -108,6 +152,20 @@ preview lives in EditPage through the adapter's render. Swapping the editor stay
     view.focus();
   }
 
+  // Run a pure selection transform over the mounted editor: hand it the document and selection,
+  // dispatch the document and selection it returns, and put focus back on the surface.
+  function transformSelection(transform: (doc: string, from: number, to: number) => FormatResult) {
+    if (!view) return;
+    const { from, to } = view.state.selection.main;
+    const doc = view.state.doc.toString();
+    const next = transform(doc, from, to);
+    view.dispatch({
+      changes: { from: 0, to: doc.length, insert: next.doc },
+      selection: { anchor: next.from, head: next.to },
+    });
+    view.focus();
+  }
+
   function insertLink(href: string, title: string) {
     if (!view) {
       // The editor has not mounted yet; append the link to the raw value so a pick is never lost,
@@ -116,35 +174,23 @@ preview lives in EditPage through the adapter's render. Swapping the editor stay
       value = value ? `${value} ${link}` : link;
       return;
     }
+    transformSelection((doc, from, to) => insertInlineLink(doc, from, to, href, title));
+  }
+
+  function selectedText(): string {
+    if (!view) return '';
     const { from, to } = view.state.selection.main;
-    const doc = view.state.doc.toString();
-    const next = insertInlineLink(doc, from, to, href, title);
-    view.dispatch({
-      changes: { from: 0, to: doc.length, insert: next.doc },
-      selection: { anchor: next.from, head: next.to },
-    });
-    view.focus();
+    return view.state.sliceDoc(from, to);
   }
 
   function applyFormat(kind: FormatKind) {
-    if (!view) return;
-    const { from, to } = view.state.selection.main;
-    const doc = view.state.doc.toString();
-    const next = applyMarkdownFormat(doc, from, to, kind);
-    view.dispatch({
-      changes: { from: 0, to: doc.length, insert: next.doc },
-      selection: { anchor: next.from, head: next.to },
-    });
-    view.focus();
+    transformSelection((doc, from, to) => applyMarkdownFormat(doc, from, to, kind));
   }
 </script>
 
 <input type="hidden" {name} {value} />
 
-<div class="border-base-300 overflow-hidden rounded-box border">
-  <EditorToolbar format={applyFormat} />
-  <div bind:this={host}></div>
-  {#if !mounted}
-    <textarea class="textarea min-h-64 w-full font-mono text-sm" bind:value aria-label="Markdown source"></textarea>
-  {/if}
-</div>
+<div bind:this={host}></div>
+{#if !mounted}
+  <textarea class="textarea min-h-[50vh] w-full font-mono text-sm" bind:value aria-label="Markdown source"></textarea>
+{/if}

package/src/lib/components/MarkdownHelpDialog.svelte

@@ -0,0 +1,58 @@
+<!--
+@component
+The Markdown cheat sheet, opened from the edit page's editor footer. A one-screen table pairs
+each piece of syntax with what it makes, and a closing note explains the ::: layout blocks.
+Built on a native <dialog>, the DeleteDialog recipe; the host drives it through the exported
+open(), so the component renders no trigger of its own.
+-->
+<script lang="ts">
+  let dialog = $state<HTMLDialogElement | null>(null);
+
+  /** Open the cheat sheet. The trigger lives in the host (the edit page's editor footer). */
+  export function open() {
+    dialog?.showModal();
+  }
+  function close() {
+    dialog?.close();
+  }
+</script>
+
+<dialog class="modal" aria-labelledby="cairn-markdown-help-title" bind:this={dialog}>
+  <div class="modal-box">
+    <div class="mb-3 flex items-center justify-between">
+      <h2 id="cairn-markdown-help-title" class="text-base font-semibold">Markdown help</h2>
+      <button type="button" class="btn btn-ghost btn-sm" aria-label="Close" onclick={close}>✕</button>
+    </div>
+    <table class="table table-sm">
+      <thead>
+        <tr>
+          <th class="text-[0.6875rem] font-semibold uppercase tracking-[0.08em] text-[var(--color-muted)]">Type this</th>
+          <th class="text-[0.6875rem] font-semibold uppercase tracking-[0.08em] text-[var(--color-muted)]">What it makes</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr><td><code>## Heading</code></td><td>A heading</td></tr>
+        <tr><td><code>### Heading</code></td><td>A smaller heading</td></tr>
+        <tr><td><code>**bold**</code></td><td>Bold text</td></tr>
+        <tr><td><code>*italic*</code></td><td>Italic text</td></tr>
+        <tr><td><code>~~text~~</code></td><td>Crossed-out text</td></tr>
+        <tr><td><code>[text](url)</code></td><td>A link</td></tr>
+        <tr><td><code>[[page-name]]</code></td><td>A link to one of your pages</td></tr>
+        <tr><td><code>- item</code></td><td>A bulleted list</td></tr>
+        <tr><td><code>1. item</code></td><td>A numbered list</td></tr>
+        <tr><td><code>- [ ] item</code></td><td>A checklist</td></tr>
+        <tr><td><code>&gt; quote</code></td><td>A quote</td></tr>
+        <tr><td><code>`code`</code></td><td>Code</td></tr>
+        <tr><td>Table</td><td>The Table button in the toolbar inserts one</td></tr>
+        <tr><td><code>---</code></td><td>A horizontal rule</td></tr>
+      </tbody>
+    </table>
+    <p class="mt-3 text-sm">
+      Lines starting with <code>:::</code> are layout blocks. Edit the text inside them and leave
+      the <code>:::</code> lines alone.
+    </p>
+  </div>
+  <form method="dialog" class="modal-backdrop">
+    <button tabindex="-1" aria-label="Close">close</button>
+  </form>
+</dialog>

package/src/lib/components/RenameDialog.svelte

@@ -17,9 +17,15 @@ DeleteDialog a11y conventions.
     label: string;
     /** The current slug, prefilled into the input. */
     slug: string;
+    /** Render the built-in Change URL trigger. False mounts only the dialog, for a host that
+     *  supplies its own trigger and opens the dialog through the exported open(). */
+    trigger?: boolean;
+    /** Called when the rename form submits, before the document navigates. The edit page uses it
+     *  to stand down its leave guard while the POST is in flight. */
+    onsubmitting?: () => void;
   }
 
-  let { conceptId, id, label, slug }: Props = $props();
+  let { conceptId, id, label, slug, trigger = true, onsubmitting }: Props = $props();
 
   let dialog = $state<HTMLDialogElement | null>(null);
   let slugInput = $state<HTMLInputElement | null>(null);
@@ -27,7 +33,8 @@ DeleteDialog a11y conventions.
   // current slug each time the dialog opens without capturing only the initial prop value.
   let nextSlug = $state('');
 
-  function open() {
+  /** Open the dialog with a fresh prefill. Exported so a trigger={false} host can drive it. */
+  export function open() {
     nextSlug = slug;
     dialog?.showModal();
     // showModal() lands focus on the first focusable element (the header Close button), so move
@@ -43,7 +50,9 @@ DeleteDialog a11y conventions.
   }
 </script>
 
-<button type="button" class="btn btn-sm btn-ghost" aria-haspopup="dialog" onclick={open}>Change URL</button>
+{#if trigger}
+  <button type="button" class="btn btn-sm btn-ghost" aria-haspopup="dialog" onclick={open}>Change URL</button>
+{/if}
 
 <dialog class="modal" aria-labelledby="cairn-rename-dialog-title" bind:this={dialog}>
   <div class="modal-box">
@@ -51,7 +60,7 @@ DeleteDialog a11y conventions.
       <h2 id="cairn-rename-dialog-title" class="text-base font-semibold">Change this {label.toLowerCase()} URL</h2>
       <button type="button" class="btn btn-ghost btn-sm" aria-label="Close" onclick={close}>✕</button>
     </div>
-    <form method="POST" action="?/rename" class="flex flex-col gap-3">
+    <form method="POST" action="?/rename" class="flex flex-col gap-3" onsubmit={() => onsubmitting?.()}>
       <CsrfField />
       <input type="hidden" name="concept" value={conceptId} />
       <input type="hidden" name="id" value={id} />