@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/components/menu/SelectionToolbar.svelte

@@ -0,0 +1,380 @@
+<script lang="ts">
+	/**
+	 * The editor's own formatting popover over a selection: a row of marks, then labelled rows
+	 * for what acts on the whole selection. Built only on the public API a host's toolbar would
+	 * use (`selectionChange`, the rect API, `runCommand`), so the consumer-guide recipe matches it.
+	 */
+	import type { EditorInstance } from '../../editor-props';
+	import type { EditorSelection } from '../../selection/primitives';
+	import { normalize as normalizeSelection } from '../../selection/primitives';
+	import { SELECTION_END } from '../../block-component';
+	import { TOOLBAR_COMMANDS } from '../../schema/commands';
+	import { SELECTION_TOOLBAR_LABEL } from '../../a11y-strings';
+	import { keepFlyoutOnScreen } from './flyout-placement';
+	import { runClipboardAction } from './clipboard-actions';
+	import MenuIcon from './MenuIcon.svelte';
+	import type { MenuIconName } from '../../menu-icons';
+
+	type ToolbarEditor = Pick<
+		EditorInstance,
+		| 'getSelection'
+		| 'getRects'
+		| 'getBlockKindAt'
+		| 'runCommand'
+		| 'canRunCommand'
+		| 'isCommandActive'
+		| 'getEvents'
+	>;
+
+	// The bar: the three marks and the link. Beneath it, as rows: the heading picker, inline code
+	// and copy. The bar sets the card's width.
+	const MARKS: readonly { icon: MenuIconName; title: string; command: string; size: number }[] = [
+		{ icon: 'bold', title: 'Bold (Ctrl/Cmd+B)', command: TOOLBAR_COMMANDS.toggleStrong, size: 16 },
+		{
+			icon: 'italic',
+			title: 'Italic (Ctrl/Cmd+I)',
+			command: TOOLBAR_COMMANDS.toggleEmphasis,
+			size: 16
+		},
+		{
+			icon: 'strikethrough',
+			title: 'Strikethrough (Ctrl/Cmd+Shift+X)',
+			command: TOOLBAR_COMMANDS.toggleStrikethrough,
+			size: 16
+		},
+		{ icon: 'link', title: 'Edit link (Ctrl/Cmd+K)', command: TOOLBAR_COMMANDS.editLink, size: 10 }
+	];
+	const ROWS: readonly { icon: MenuIconName; label: string; command: string }[] = [
+		{ icon: 'code', label: 'Inline code', command: TOOLBAR_COMMANDS.toggleCode }
+	];
+	const TURN_INTO_COMMAND = TOOLBAR_COMMANDS.setHeading;
+	const TURN_INTO: readonly { label: string; level: number }[] = [
+		{ label: 'Normal text', level: 0 },
+		{ label: 'Heading 1', level: 1 },
+		{ label: 'Heading 2', level: 2 },
+		{ label: 'Heading 3', level: 3 }
+	];
+	const BUTTONS = [...MARKS, ...ROWS, { command: TURN_INTO_COMMAND }];
+	const BAR_GAP = 6;
+
+	let { editor, root }: { editor: ToolbarEditor; root: HTMLElement | undefined } = $props();
+
+	let turnIntoOpen = $state(false);
+	let blockKind = $state<string | null>(null);
+	let placement = $state<Placement | null>(null);
+	let declined = $state<ReadonlySet<string>>(new Set());
+	let active = $state<ReadonlySet<string>>(new Set());
+	let current: EditorSelection | null = null;
+	let barEl: HTMLDivElement | undefined = $state();
+
+	// A labelled row the editor refuses is dropped, where a mark only dims: the icons keep the
+	// bar's shape, while a row that does nothing is noise over a selection it cannot act on.
+	const rows = $derived(ROWS.filter((row) => !declined.has(row.command)));
+	const offersHeading = $derived(!declined.has(TURN_INTO_COMMAND));
+
+	interface Placement {
+		x: number;
+		y: number;
+		/** The selection's first rectangle, used when the bar has to go above it instead. */
+		flipY: number;
+	}
+
+	// The editor root's top is the line the bar may not cross: whatever the host draws above
+	// the editor ends where the root begins.
+	function topInset(): number {
+		return Math.max(0, root?.getBoundingClientRect().top ?? 0);
+	}
+
+	// The document's own copy, so a cross-block range lands as the Markdown Ctrl+C would write.
+	function copySelection(): void {
+		void runClipboardAction('copy', null);
+		placement = null;
+	}
+
+	// The bar's own size, measured once it is in the DOM, so the placement can keep it on screen:
+	// pushed left at the right edge, moved above the selection when there is no room below.
+	let size = $state<{ w: number; h: number } | null>(null);
+	$effect(() => {
+		if (!barEl || !placement) return;
+		const rect = barEl.getBoundingClientRect();
+		size = { w: rect.width, h: rect.height };
+	});
+	const shown = $derived.by(() => {
+		if (!placement) return null;
+		if (!size) return { x: placement.x, y: placement.y };
+		const margin = 8;
+		let { x, y } = placement;
+		if (x + size.w > window.innerWidth - margin)
+			x = Math.max(margin, window.innerWidth - margin - size.w);
+		if (y + size.h > window.innerHeight - margin)
+			y = Math.max(topInset() + 4, placement.flipY - size.h - BAR_GAP);
+		return { x, y };
+	});
+
+	$effect(() => editor.getEvents().on('selectionChange', update));
+
+	// Shown only once the drag is over, since a bar moving under the pointer is in the way;
+	// watched at the document, where the drag can end anywhere.
+	let pointerHeld = false;
+	$effect(() => {
+		// A pointer-down on the bar itself is a button, not a drag: watching for its release
+		// would re-place the bar, and close its flyout, under the click that follows.
+		const down = (e: PointerEvent) => {
+			if (e.button === 0 && !barEl?.contains(e.target as Node)) pointerHeld = true;
+		};
+		// Placed from the range the editor last reported; a release that still moves the range
+		// reports again through `selectionChange`, which re-places.
+		const up = () => {
+			if (!pointerHeld) return;
+			pointerHeld = false;
+			if (current) update(current);
+		};
+		document.addEventListener('pointerdown', down, true);
+		document.addEventListener('pointerup', up, true);
+		document.addEventListener('pointercancel', up, true);
+		return () => {
+			document.removeEventListener('pointerdown', down, true);
+			document.removeEventListener('pointerup', up, true);
+			document.removeEventListener('pointercancel', up, true);
+		};
+	});
+
+	// The editor's own right-click menu takes the selection's spot; two panels over one range read
+	// as a glitch, so the bar hides while it is open and comes back where the selection still is.
+	let menuOpen = false;
+	$effect(() =>
+		editor.getEvents().on('menuChange', (open) => {
+			menuOpen = open;
+			if (open) placement = null;
+			else if (current) update(current);
+		})
+	);
+
+	// Sticky with the text: the rects are viewport coordinates, so a scroll or resize moves the
+	// selection under the bar and the bar re-measures. Scroll already arrives once per frame.
+	$effect(() => {
+		const reanchor = () => {
+			// Same gates as a selection change: a scroll mid-drag (autoscroll included) must not
+			// bring the bar out before the release does.
+			if (current) placement = shownOver(current);
+		};
+		window.addEventListener('scroll', reanchor, { capture: true, passive: true });
+		window.addEventListener('resize', reanchor, { passive: true });
+		return () => {
+			window.removeEventListener('scroll', reanchor, { capture: true });
+			window.removeEventListener('resize', reanchor);
+		};
+	});
+
+	function update(selection: EditorSelection | null): void {
+		current = selection;
+		turnIntoOpen = false;
+		blockKind = selection ? editor.getBlockKindAt(normalizeSelection(selection).start.path) : null;
+		// Asked per selection change, not per render: the answers are snapshots of this selection.
+		declined = new Set(
+			BUTTONS.filter((b) => !editor.canRunCommand(b.command)).map((b) => b.command)
+		);
+		active = new Set(
+			BUTTONS.filter((b) => editor.isCommandActive(b.command)).map((b) => b.command)
+		);
+		placement = selection ? shownOver(selection) : null;
+	}
+
+	// The editor decides where the bar belongs: over a code fence or an equation's source it
+	// refuses every mark, and a bar of greyed-out buttons is worse than none.
+	function shownOver(selection: EditorSelection): Placement | null {
+		if (menuOpen || pointerHeld) return null;
+		if (MARKS.every((mark) => declined.has(mark.command))) return null;
+		return place(selection);
+	}
+
+	function place(selection: EditorSelection): Placement | null {
+		const { start, end } = normalizeSelection(selection);
+		const sameBlock = start.path.join('.') === end.path.join('.');
+		if (!sameBlock) {
+			// The bar hangs off where the selection ends; the start block's remaining range, then
+			// its whole box, are the fallbacks when the end block yields no rectangle.
+			const rects = editor.getRects();
+			const endRects =
+				editor.getBlockKindAt(end.path) !== 'table' && end.offset > 0
+					? rects.rangeRects(end.path, 0, end.offset)
+					: [];
+			const anchored = endRects.length
+				? endRects
+				: rects.rangeRects(start.path, start.offset, SELECTION_END);
+			const measured = anchored.length ? anchored : rects.rangeRects(start.path, 0, SELECTION_END);
+			return measured.length ? belowRight(measured) : null;
+		}
+		// A rectangle inside one table shares the table's path and holds cell indices on endpoints
+		// the cross-block flag need not set, so the kind is what rules it out, not the flag.
+		if (editor.getBlockKindAt(start.path) === 'table') return null;
+		if (start.offset === end.offset) return null;
+		const rects = editor.getRects().rangeRects(start.path, start.offset, end.offset);
+		return rects.length ? belowRight(rects) : null;
+	}
+
+	/** Below the selection's last line and right of where it ends, never over the text; the
+	 *  clamp above moves it left or above when there is no room. */
+	function belowRight(rects: DOMRect[]): Placement | null {
+		const first = rects[0];
+		const last = rects[rects.length - 1];
+		// Scrolled out from under whatever the host draws above, or off the bottom: nowhere to go.
+		if (last.bottom < topInset() || first.top > window.innerHeight) return null;
+		return { x: last.right + BAR_GAP, y: last.bottom + BAR_GAP, flipY: first.top };
+	}
+
+	// The command id, not a made-up keystroke: a host rebind moves the shortcut and leaves the
+	// button. A refused run means what the bar assumed has changed, so the bar hides.
+	function fire(command: string, arg?: unknown): void {
+		turnIntoOpen = false;
+		if (!editor.runCommand(command, arg)) placement = null;
+	}
+</script>
+
+{#if shown}
+	<div
+		bind:this={barEl}
+		class="md-menu selection-toolbar"
+		data-testid="selection-toolbar"
+		style:left="{shown.x}px"
+		style:top="{shown.y}px"
+		role="toolbar"
+		aria-label={SELECTION_TOOLBAR_LABEL}
+		tabindex="-1"
+		onpointerleave={() => (turnIntoOpen = false)}
+	>
+		<div class="selection-toolbar-marks">
+			{#each MARKS as button (button.command)}
+				<button
+					type="button"
+					class="md-menu-item selection-toolbar-mark"
+					data-testid="toolbar-{button.command}"
+					title={button.title}
+					disabled={declined.has(button.command)}
+					aria-pressed={active.has(button.command)}
+					onmousedown={(e) => e.preventDefault()}
+					onclick={() => fire(button.command)}
+				>
+					<MenuIcon name={button.icon} size={button.size} />
+				</button>
+			{/each}
+		</div>
+		<div class="md-menu-divider" aria-hidden="true"></div>
+		{#if offersHeading}
+			<div
+				class="selection-toolbar-row"
+				role="presentation"
+				onpointerenter={() => (turnIntoOpen = true)}
+			>
+				<button
+					type="button"
+					class="md-menu-item"
+					data-testid="toolbar-set-heading"
+					aria-haspopup="menu"
+					aria-expanded={turnIntoOpen}
+					onmousedown={(e) => e.preventDefault()}
+					onclick={() => (turnIntoOpen = !turnIntoOpen)}
+				>
+					<span class="md-menu-icon"><MenuIcon name="heading" size={14} /></span>
+					<span class="selection-toolbar-label">Set heading</span>
+					<span class="md-menu-icon"><MenuIcon name="chevron-right" size={13} /></span>
+				</button>
+				{#if turnIntoOpen}
+					<div class="md-menu selection-toolbar-flyout" role="menu" {@attach keepFlyoutOnScreen}>
+						{#each TURN_INTO as option (option.level)}
+							{@const chosen = option.level === 0 ? blockKind === 'paragraph' : false}
+							<button
+								type="button"
+								class="md-menu-item"
+								role="menuitemradio"
+								data-testid="toolbar-set-heading-{option.level}"
+								aria-checked={chosen}
+								onmousedown={(e) => e.preventDefault()}
+								onclick={() => fire(TURN_INTO_COMMAND, option.level)}
+							>
+								<span class="selection-toolbar-label">{option.label}</span>
+								{#if chosen}<span class="md-menu-icon"><MenuIcon name="check" size={13} /></span
+									>{/if}
+							</button>
+						{/each}
+					</div>
+				{/if}
+			</div>
+		{/if}
+		{#each rows as row (row.command)}
+			<button
+				type="button"
+				class="md-menu-item"
+				data-testid="toolbar-{row.command}"
+				aria-pressed={active.has(row.command)}
+				onmousedown={(e) => e.preventDefault()}
+				onclick={() => fire(row.command)}
+			>
+				<span class="md-menu-icon"><MenuIcon name={row.icon} size={14} /></span>
+				<span class="selection-toolbar-label">{row.label}</span>
+				{#if active.has(row.command)}<span class="md-menu-icon"
+						><MenuIcon name="check" size={13} /></span
+					>{/if}
+			</button>
+		{/each}
+		<button
+			type="button"
+			class="md-menu-item"
+			data-testid="toolbar-copy"
+			onmousedown={(e) => e.preventDefault()}
+			onclick={copySelection}
+		>
+			<span class="md-menu-icon"><MenuIcon name="copy" size={14} /></span>
+			<span>Copy</span>
+		</button>
+	</div>
+{/if}
+
+<style>
+	/* The panel and its rows are the shared `.md-menu` family (editor.css); only the marks row
+	   and where the flyout hangs are this popover's own. */
+	.selection-toolbar {
+		z-index: 100;
+		min-width: 0;
+		width: calc(4 * 34px + 3 * 2px + 2 * 6px);
+		white-space: nowrap;
+	}
+	.selection-toolbar-marks {
+		display: flex;
+		align-items: center;
+		gap: 2px;
+		padding: 2px;
+	}
+	.selection-toolbar-mark {
+		flex: 0 0 34px;
+		justify-content: center;
+		width: 34px;
+		height: 30px;
+		padding: 0;
+		color: var(--color-ui-muted, #93938d);
+	}
+	.selection-toolbar-mark:hover:not(:disabled),
+	.selection-toolbar-mark[aria-pressed='true'] {
+		color: var(--color-text-primary, #e8e8e5);
+	}
+	/* The marks are serif letters; a Lucide outline beside them needs a heavier stroke to weigh
+	   the same. */
+	.selection-toolbar-mark :global(svg) {
+		stroke-width: 2.2;
+	}
+	.selection-toolbar-row {
+		position: relative;
+	}
+	.selection-toolbar-label {
+		flex: 1;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+	.selection-toolbar-flyout {
+		position: absolute;
+		left: 100%;
+		top: -4px;
+		margin-left: 4px;
+		min-width: 150px;
+	}
+</style>

package/dist/components/menu/SelectionToolbar.svelte.d.ts

@@ -0,0 +1,14 @@
+/**
+     * The editor's own formatting popover over a selection: a row of marks, then labelled rows
+     * for what acts on the whole selection. Built only on the public API a host's toolbar would
+     * use (`selectionChange`, the rect API, `runCommand`), so the consumer-guide recipe matches it.
+     */
+import type { EditorInstance } from '../../editor-props';
+type ToolbarEditor = Pick<EditorInstance, 'getSelection' | 'getRects' | 'getBlockKindAt' | 'runCommand' | 'canRunCommand' | 'isCommandActive' | 'getEvents'>;
+type $$ComponentProps = {
+    editor: ToolbarEditor;
+    root: HTMLElement | undefined;
+};
+declare const SelectionToolbar: import("svelte").Component<$$ComponentProps, {}, "">;
+type SelectionToolbar = ReturnType<typeof SelectionToolbar>;
+export default SelectionToolbar;

package/dist/components/menu/clipboard-actions.d.ts

@@ -1,8 +1,7 @@
 /**
- * The clipboard rows a menu offers where Ctrl+X/C/V would go: cut and copy through the
- * document's own command (so the editor's copy handlers write what they always write), paste by
- * handing the clipboard's text to the focused surface as a paste event — the same road a real
- * Ctrl+V takes — either as it is, or escaped so Markdown syntax in it lands as literal text.
+ * The clipboard rows a menu offers: cut and copy through the document's own command, so the
+ * editor's copy handlers run as usual, and paste as a paste event on the focused editable,
+ * as is or escaped so Markdown syntax arrives as literal text.
  */
 export type ClipboardAction = 'cut' | 'copy' | 'paste' | 'paste-plain';
 /** Markdown-significant bytes, escaped so pasted text reads back exactly as pasted. */

package/dist/components/menu/clipboard-actions.js

@@ -1,8 +1,7 @@
 /**
- * The clipboard rows a menu offers where Ctrl+X/C/V would go: cut and copy through the
- * document's own command (so the editor's copy handlers write what they always write), paste by
- * handing the clipboard's text to the focused surface as a paste event — the same road a real
- * Ctrl+V takes — either as it is, or escaped so Markdown syntax in it lands as literal text.
+ * The clipboard rows a menu offers: cut and copy through the document's own command, so the
+ * editor's copy handlers run as usual, and paste as a paste event on the focused editable,
+ * as is or escaped so Markdown syntax arrives as literal text.
  */
 /** Markdown-significant bytes, escaped so pasted text reads back exactly as pasted. */
 export function escapeMarkdownLiteral(text) {

package/dist/components/menu/default-context-actions.d.ts

@@ -1,15 +1,6 @@
-/**
- * What every non-prose block's context menu offers after the kind's own rows: copy it (its
- * Markdown), replace it with the clipboard, remove it — each named for what the block is
- * ("Remove code block", "Copy image"). Plain, not red: every one is a Ctrl+Z away. Prose blocks
- * are the page's background and keep the browser's own menu (`Editor.svelte`).
- */
 import type { NodeView } from '../../core/node-views';
-/** The noun the menu uses for a block: a paragraph holding nothing but an image is "image". */
-export declare function blockNoun(node: NodeView): string;
-/** Prose is the page's background: it takes no block menu of its own. An image alone in a
- *  paragraph is a block, not prose. */
-export declare function isProseBackground(node: NodeView): boolean;
-/** Test-only. */
-export declare function __resetDefaultContextActionsForTests(): void;
+import type { InlineReading } from '../../core/inline/inline-cache';
+/** The noun the menu uses for a block: its kind's name mid-sentence, and "image" or "images"
+ *  for a paragraph holding nothing but images. */
+export declare function blockNoun(node: NodeView, reading: InlineReading): string;
 export declare function registerDefaultContextActions(): void;

package/dist/components/menu/default-context-actions.js

@@ -1,76 +1,58 @@
-import { EVERY_KIND, registerBlockContextActions } from '../../schema/context-actions';
-import { applyPasteTransforms } from '../../tree-operations/paste/paste-transforms';
-const KIND_NAMES = {
-    paragraph: 'paragraph',
-    heading: 'heading',
-    setextHeading: 'heading',
-    fencedCode: 'code block',
-    indentedCode: 'code block',
-    mathBlock: 'math block',
-    mathFence: 'math block',
-    table: 'table',
-    blockquote: 'quote',
-    list: 'list',
-    thematicBreak: 'divider',
-    html: 'HTML block',
-    linkReferenceDefinition: 'link definition'
-};
-const IMAGE_ONLY = /^\s*!\[[^\]]*\]\([^)]*\)\s*$/;
-const PROSE_KINDS = new Set(['paragraph', 'heading', 'setextHeading']);
-/** The noun the menu uses for a block: a paragraph holding nothing but an image is "image". */
-export function blockNoun(node) {
-    if (node.kind === 'paragraph' && IMAGE_ONLY.test(node.raw))
-        return 'image';
-    return KIND_NAMES[node.kind] ?? 'block';
-}
-/** Prose is the page's background: it takes no block menu of its own. An image alone in a
- *  paragraph is a block, not prose. */
-export function isProseBackground(node) {
-    return PROSE_KINDS.has(node.kind) && blockNoun(node) !== 'image';
+/**
+ * What every non-prose block's context menu offers after the kind's own rows: copy it (its
+ * Markdown), replace it with the clipboard, remove it, each named for what the block is
+ * ("Remove code block", "Copy image"). Plain, not red: every one is a Ctrl+Z away. Prose blocks
+ * are the page's background and take the clipboard rows instead (`editor-root-menus.ts`).
+ */
+import { blockKindLabel } from '../../a11y-strings';
+import { pictureImageCount } from '../../core/inline/picture';
+import { EVERY_KIND, registerBuiltinBlockContextActions } from '../../schema/context-actions';
+/** The noun the menu uses for a block: its kind's name mid-sentence, and "image" or "images"
+ *  for a paragraph holding nothing but images. */
+export function blockNoun(node, reading) {
+    const images = pictureImageCount(node, reading);
+    if (images > 0)
+        return images === 1 ? 'image' : 'images';
+    const label = blockKindLabel(node.kind);
+    // An initialism keeps its capitals: "HTML block", not "hTML block".
+    return /^.[A-Z]/.test(label) ? label : label.charAt(0).toLowerCase() + label.slice(1);
 }
 let registered = false;
-/** Test-only. */
-export function __resetDefaultContextActionsForTests() {
-    registered = false;
-}
 export function registerDefaultContextActions() {
     if (registered)
         return;
     registered = true;
-    registerBlockContextActions(EVERY_KIND, (node) => {
-        const noun = blockNoun(node);
-        return [
-            {
-                id: 'block.copy',
-                label: `Copy ${noun}`,
-                icon: 'copy',
-                run: () => navigator.clipboard.writeText(node.raw)
-            },
-            {
-                id: 'block.replace',
-                label: 'Replace with clipboard',
-                icon: 'clipboard',
-                run: async (ctx) => {
-                    let text;
-                    try {
-                        text = await navigator.clipboard.readText();
-                    }
-                    catch {
-                        return;
-                    }
-                    if (text.trim() === '')
-                        return;
-                    // The paste transforms first, as any paste gets, so a plugin's rewrite applies.
-                    const md = applyPasteTransforms(text);
-                    await ctx.replaceRaw(md.endsWith('\n') ? md : md + '\n');
+    registerBuiltinBlockContextActions(EVERY_KIND, 'block', (node, _path, noun) => [
+        {
+            id: 'block.copy',
+            label: `Copy ${noun}`,
+            icon: 'copy',
+            run: () => navigator.clipboard.writeText(node.raw)
+        },
+        {
+            id: 'block.replace',
+            label: 'Replace with clipboard',
+            icon: 'clipboard',
+            run: async (ctx) => {
+                let text;
+                try {
+                    text = await navigator.clipboard.readText();
+                }
+                catch {
+                    return;
                 }
-            },
-            {
-                id: 'block.remove',
-                label: `Remove ${noun}`,
-                icon: 'trash',
-                run: (ctx) => ctx.deleteBlock()
+                if (text.trim() === '')
+                    return;
+                // The paste transforms first, as any paste gets, so a plugin's rewrite applies.
+                const md = ctx.transformPaste(text);
+                await ctx.replaceRaw(md.endsWith('\n') ? md : md + '\n');
             }
-        ];
-    });
+        },
+        {
+            id: 'block.remove',
+            label: `Remove ${noun}`,
+            icon: 'trash',
+            run: (ctx) => ctx.deleteBlock()
+        }
+    ]);
 }

package/dist/components/menu/flyout-placement.d.ts

@@ -1,6 +1,6 @@
 /**
- * Svelte attachment for a menu flyout: measures the surface once it is in the DOM and moves it
- * to stay inside the viewport (`flyoutPlacement`). The element's own CSS hangs it off the row's
+ * Svelte attachment for a menu flyout: measures the panel once it is in the DOM and moves it to
+ * stay inside the viewport (`flyoutPlacement`). The element's own CSS hangs it off the row's
  * right edge; this writes the correction inline, so the rule lives in one place for every menu.
  */
 export declare function keepFlyoutOnScreen(node: HTMLElement): void;

package/dist/components/menu/flyout-placement.js

@@ -1,6 +1,6 @@
 /**
- * Svelte attachment for a menu flyout: measures the surface once it is in the DOM and moves it
- * to stay inside the viewport (`flyoutPlacement`). The element's own CSS hangs it off the row's
+ * Svelte attachment for a menu flyout: measures the panel once it is in the DOM and moves it to
+ * stay inside the viewport (`flyoutPlacement`). The element's own CSS hangs it off the row's
  * right edge; this writes the correction inline, so the rule lives in one place for every menu.
  */
 import { flyoutPlacement } from '../blocks/table/table-menu-model';

package/dist/components/menu/menu-presence.svelte.d.ts

@@ -0,0 +1,12 @@
+/**
+ * How many editor menus are showing, which is what `menuChange` reports. Every menu attaches
+ * `track` to its root element, so a menu reads open for exactly as long as it is mounted,
+ * whichever way it closes. A count, so two menus overlapping still read as one open.
+ */
+import type { Attachment } from 'svelte/attachments';
+export interface MenuPresence {
+    /** A getter, so a reader re-runs when a menu opens or closes. */
+    readonly isOpen: boolean;
+    track: Attachment;
+}
+export declare function createMenuPresence(): MenuPresence;

package/dist/components/menu/menu-presence.svelte.js

@@ -0,0 +1,19 @@
+/**
+ * How many editor menus are showing, which is what `menuChange` reports. Every menu attaches
+ * `track` to its root element, so a menu reads open for exactly as long as it is mounted,
+ * whichever way it closes. A count, so two menus overlapping still read as one open.
+ */
+import { untrack } from 'svelte';
+export function createMenuPresence() {
+    let open = $state(0);
+    return {
+        get isOpen() {
+            return open > 0;
+        },
+        track() {
+            // Untracked, or the attachment would depend on the count it writes and rerun forever.
+            untrack(() => open++);
+            return () => untrack(() => open--);
+        }
+    };
+}

package/dist/components/paste-image-arm.d.ts

@@ -1,15 +1,13 @@
 /**
- * The host image-import arm of a paste, shared by the editable-surface clipboard skeleton and the
- * editor-root fallback. It ends at "here is the markdown nobody claimed"; each caller owns what
- * happens next. Two ordering rules: files are read before the first await (`clipboardData` is not
- * dependably live afterwards), and a multi-block selection reaches the delete only after the hook
- * answers, so a failed import destroys nothing.
+ * Hands a paste's images to the host's import hook, for the blocks' clipboard code and the
+ * editor-root fallback alike. Files are read before the first await, since `clipboardData` may
+ * not stay live, and a multi-block selection is deleted only after the hook answers.
  */
 import type { PasteImageHook } from '../editor-keys';
 import { type EditorEvents } from '../editor-events';
 import type { CrossBlockHandlers } from '../selection/cross-block/dispatch';
 export interface ImagePasteArmDeps {
-    /** Undefined leaves an image-bearing paste on the text/plain path — `filesOf`
+    /** Undefined leaves a paste carrying images on the text/plain path: `filesOf`
      *  then reports none. */
     onPasteImage: PasteImageHook | undefined;
     /** A failed import reports here rather than vanishing. */
@@ -19,11 +17,8 @@ export interface ImagePasteArmDeps {
 export interface ImagePasteArm {
     /** Call before the handler's first await; empty when no hook is installed. */
     filesOf(data: DataTransfer | null): File[];
-    /**
-     * Import `files` in clipboard order, then offer the markdown to the cross-block
-     * seam. Null means the arm is finished (nothing imported, or a multi-block
-     * selection took the insertion); markdown means no selection claimed it.
-     */
+    /** Imports `files` in clipboard order and offers the markdown to the cross-block paste; null
+     *  when nothing is left to do, the markdown when no selection took it. */
     run(e: ClipboardEvent, files: File[]): Promise<string | null>;
 }
 export declare function createImagePasteArm(deps: ImagePasteArmDeps): ImagePasteArm;