@stocksharp/diagram 0.4.1 → 0.6.0

package/src/canvas-renderer.ts

@@ -1,3 +1,5 @@
+import type { DrawSurface } from './draw-surface.js';
+import { SvgSurface } from './svg-surface.js';
 // Internal dependency-free canvas renderer used by StockSharpDiagram.
 //
 // Dependency-free, pure 2D canvas. Demonstrates the hard parts: typed
@@ -507,7 +509,9 @@ function colorLuminance(color: string | undefined): number {
 export class Diagram {
     private readonly host: HTMLElement;
     private readonly canvas: HTMLCanvasElement;
-    private ctx: CanvasRenderingContext2D;
+    // Typed as the surface, not the context: the on-screen path still passes the browser's own
+    // 2D context (it satisfies the interface structurally), while export can hand in an SVG one.
+    private ctx: DrawSurface;
     private readonly opts: DiagramOptions;
 
     private nodes: NodeModel[] = [];
@@ -1332,6 +1336,65 @@ export class Diagram {
             return copy;
         }
 
+        const layout = this.exportLayout(scope, options);
+        const { pixelRatio, exportScale, padding, bounds, width, height, pixelWidth, pixelHeight } = layout;
+
+        const output = document.createElement('canvas');
+        output.width = pixelWidth;
+        output.height = pixelHeight;
+        output.style.width = `${width}px`;
+        output.style.height = `${height}px`;
+        const outputContext = output.getContext('2d');
+        if (outputContext === null) throw new Error('ssdiagram: screenshot 2d context unavailable');
+
+        const previous = {
+            ctx: this.ctx,
+            width: this.width,
+            height: this.height,
+            dpr: this.dpr,
+            scale: this.scale,
+            offX: this.offX,
+            offY: this.offY,
+            overviewVisible: this.overviewVisible,
+            background: this.opts.background,
+        };
+        try {
+            this.ctx = outputContext;
+            this.width = width;
+            this.height = height;
+            this.dpr = pixelRatio;
+            this.scale = exportScale;
+            this.offX = scope === 'content' && bounds !== null ? padding - bounds.minX * exportScale : previous.offX;
+            this.offY = scope === 'content' && bounds !== null ? padding - bounds.minY * exportScale : previous.offY;
+            this.overviewVisible = options.includeOverview ?? (scope === 'viewport' && previous.overviewVisible);
+            if (options.background !== undefined) this.opts.background = options.background;
+            outputContext.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
+            this.draw({
+                grid: options.includeGrid ?? true,
+                overview: this.overviewVisible,
+                selection: options.includeSelection ?? scope === 'viewport',
+                runtime: options.includeRuntimeState ?? true,
+                transient: false,
+            });
+        } finally {
+            this.ctx = previous.ctx;
+            this.width = previous.width;
+            this.height = previous.height;
+            this.dpr = previous.dpr;
+            this.scale = previous.scale;
+            this.offX = previous.offX;
+            this.offY = previous.offY;
+            this.overviewVisible = previous.overviewVisible;
+            this.opts.background = previous.background;
+        }
+        return output;
+    }
+
+    // Everything an export needs to know about size and placement, for either output. Shared on
+    // purpose: a raster and a vector export of the same scope must frame the picture identically,
+    // and two copies of this arithmetic would eventually disagree about padding or where the origin
+    // sits. A block comment here would be lifted onto the next public member in the .d.ts.
+    private exportLayout(scope: DiagramScreenshotScope, options: DiagramScreenshotOptions) {
         const pixelRatio = this.positiveScreenshotNumber(options.pixelRatio ?? this.dpr, 'pixelRatio');
         const exportScale = scope === 'content'
             ? this.positiveScreenshotNumber(options.scale ?? 1, 'scale')
@@ -1348,17 +1411,41 @@ export class Diagram {
             : this.height;
         const pixelWidth = Math.ceil(width * pixelRatio);
         const pixelHeight = Math.ceil(height * pixelRatio);
+
         if (pixelWidth > 16384 || pixelHeight > 16384 || pixelWidth * pixelHeight > 268_435_456) {
             throw new RangeError(`ssdiagram: screenshot is too large (${pixelWidth}x${pixelHeight})`);
         }
 
-        const output = document.createElement('canvas');
-        output.width = pixelWidth;
-        output.height = pixelHeight;
-        output.style.width = `${width}px`;
-        output.style.height = `${height}px`;
-        const outputContext = output.getContext('2d');
-        if (outputContext === null) throw new Error('ssdiagram: screenshot 2d context unavailable');
+        return { pixelRatio, exportScale, padding, bounds, width, height, pixelWidth, pixelHeight };
+    }
+
+    /**
+     * The same picture takeScreenshot produces, as SVG.
+     *
+     * It is the renderer that draws it -- the surface underneath simply records instead of paints --
+     * so the vector output cannot drift from what the screen and the raster export show. Text keeps
+     * the on-screen metrics by measuring through a real 2D context.
+     *
+     * Scale and pixelRatio still frame the picture (they decide the viewBox), but nothing is
+     * resampled: the result is resolution-independent, which is the point of asking for it.
+     */
+    takeSvg(options: DiagramScreenshotOptions = {}): string {
+        if (this.destroyed) throw new Error('ssdiagram: cannot export a destroyed diagram');
+
+        const scope = options.scope ?? 'viewport';
+        if (scope !== 'viewport' && scope !== 'content') {
+            throw new RangeError(`ssdiagram: unsupported screenshot scope "${String(scope)}"`);
+        }
+
+        const { exportScale, padding, bounds, width, height } = this.exportLayout(scope, options);
+
+        const metrics = this.canvas.getContext('2d');
+        const surface = new SvgSurface({
+            width,
+            height,
+            background: options.background ?? this.opts.background ?? '#1b1b1f',
+            metrics: metrics ?? undefined,
+        });
 
         const previous = {
             ctx: this.ctx,
@@ -1369,19 +1456,19 @@ export class Diagram {
             offX: this.offX,
             offY: this.offY,
             overviewVisible: this.overviewVisible,
-            background: this.opts.background,
         };
+
         try {
-            this.ctx = outputContext;
+            this.ctx = surface;
             this.width = width;
             this.height = height;
-            this.dpr = pixelRatio;
+            // 1: an SVG has no device pixels to multiply by, and the viewBox carries the size.
+            this.dpr = 1;
             this.scale = exportScale;
             this.offX = scope === 'content' && bounds !== null ? padding - bounds.minX * exportScale : previous.offX;
             this.offY = scope === 'content' && bounds !== null ? padding - bounds.minY * exportScale : previous.offY;
             this.overviewVisible = options.includeOverview ?? (scope === 'viewport' && previous.overviewVisible);
-            if (options.background !== undefined) this.opts.background = options.background;
-            outputContext.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
+
             this.draw({
                 grid: options.includeGrid ?? true,
                 overview: this.overviewVisible,
@@ -1398,9 +1485,9 @@ export class Diagram {
             this.offX = previous.offX;
             this.offY = previous.offY;
             this.overviewVisible = previous.overviewVisible;
-            this.opts.background = previous.background;
         }
-        return output;
+
+        return surface.toSvg();
     }
 
     private positiveScreenshotNumber(value: number, name: string): number {
@@ -1999,6 +2086,18 @@ export class Diagram {
     }
 
     // ---- input ------------------------------------------------------
+    // Ends hover and everything hanging off it: highlight, cursor and the delayed tooltip.
+    private clearHover(): void {
+        if (this.hoverPort !== null) this.emit('portHover', { node: this.hoverPort.node, port: this.hoverPort.port, hovering: false });
+        if (this.hoverNode !== null) this.emit('nodeHover', { node: this.hoverNode, hovering: false });
+        if (this.hoveredLink !== null) this.emit('linkHover', { link: this.hoveredLink, hovering: false });
+        this.hoverPort = null; this.hoverNode = null; this.hoveredLink = null;
+        this.tipTarget = null; this.tipShow = false;
+        if (this.tipTimer !== null) { clearTimeout(this.tipTimer); this.tipTimer = null; }
+        this.canvas.style.cursor = 'default';
+        this.scheduleDraw();
+    }
+
     private cancelLongPress(): void {
         if (this.lpTimer !== null) { clearTimeout(this.lpTimer); this.lpTimer = null; }
         this.lpStart = null;
@@ -2024,7 +2123,10 @@ export class Diagram {
         }
         this.dragNode = null; this.dragStart = []; this.rubber = null;
         this.panning = false; this.linking = null; this.relinking = null; this.relinkCandidate = null; this.linkSnap = null;
-        this.scheduleDraw();
+        // A menu is about to cover this spot, and it opens under a cursor that has not moved --
+        // which fires no boundary event, so nothing else would end the hover. Without this the
+        // tooltip armed by the last pointermove appears 400ms later, through the open menu.
+        this.clearHover();
         this.emit('contextMenu', { x: pageX, y: pageY, link, node, port });
     }
 
@@ -2381,16 +2483,7 @@ export class Diagram {
             this.emitViewChanged(true);
             this.scheduleDraw();
         }, { passive: false });
-        this.listen(this.canvas, 'pointerleave', () => {
-            if (this.hoverPort !== null) this.emit('portHover', { node: this.hoverPort.node, port: this.hoverPort.port, hovering: false });
-            if (this.hoverNode !== null) this.emit('nodeHover', { node: this.hoverNode, hovering: false });
-            if (this.hoveredLink !== null) this.emit('linkHover', { link: this.hoveredLink, hovering: false });
-            this.hoverPort = null; this.hoverNode = null; this.hoveredLink = null;
-            this.tipTarget = null; this.tipShow = false;
-            if (this.tipTimer !== null) { clearTimeout(this.tipTimer); this.tipTimer = null; }
-            this.canvas.style.cursor = 'default';
-            this.scheduleDraw();
-        });
+        this.listen(this.canvas, 'pointerleave', () => this.clearHover());
         this.listen(this.canvas, 'dblclick', (e) => {
             const [sx, sy] = localXY(e);
             const [wx, wy] = this.toWorld(sx, sy);
@@ -3072,7 +3165,7 @@ export class Diagram {
     }
 }
 
-function roundRect(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, r: number): void {
+function roundRect(ctx: DrawSurface, x: number, y: number, w: number, h: number, r: number): void {
     const rr = Math.min(r, w / 2, h / 2);
     ctx.beginPath();
     ctx.moveTo(x + rr, y);

package/src/diagram/api.ts

@@ -18,6 +18,12 @@ export interface DiagramOptions {
     catalog: import('./catalog.js').StockSharpCatalog;
     /** Show the built-in top-right fullscreen request button. Defaults to true. */
     showFullscreenButton?: boolean;
+    /**
+     * Show the built-in context menu on right-click. Defaults to true, because the control
+     * suppresses the browser's own menu regardless. Turn it off to draw your own from
+     * `contextMenuRequested`, which is emitted either way.
+     */
+    showContextMenu?: boolean;
     /** Tooltip/aria text for that button. Defaults to English. */
     fullscreenLabels?: DiagramFullscreenLabels;
     overviewContainer?: HTMLElement | null;
@@ -112,7 +118,19 @@ export interface FullscreenRequestedPayload {
     fullscreen: boolean;
 }
 
-export type ContextCommand = 'undo' | 'redo' | 'cut' | 'copy' | 'paste' | 'open' | 'delete' | 'properties' | 'help';
+export type ContextCommand =
+    | 'undo' | 'redo'
+    | 'cut' | 'copy' | 'paste'
+    | 'open' | 'delete'
+    | 'exportDocument' | 'exportPng' | 'exportSvg'
+    | 'overview'
+    | 'properties' | 'help';
+
+/**
+ * Names a submenu rather than something to run. Deliberately outside ContextCommand:
+ * `executeContextCommand` takes commands, and a submenu label has nothing to execute.
+ */
+export type ContextCommandGroup = 'export';
 
 export interface ContextCommandPayload {
     command: ContextCommand;
@@ -123,6 +141,38 @@ export interface ContextCommandPayload {
 export interface ContextCommandState {
     command: ContextCommand;
     enabled: boolean;
+    /**
+     * Present only on commands that toggle something, and then it is the current state --
+     * `overview` is the one today. A menu draws these with a tick rather than as two separate
+     * show/hide entries, which would leave one of them dead at all times.
+     */
+    checked?: boolean;
+}
+
+/** A submenu: its own enabled state, plus the items to show when it opens. */
+export interface ContextCommandGroupState {
+    group: ContextCommandGroup;
+    enabled: boolean;
+    commands: ContextCommandState[];
+}
+
+/**
+ * One entry of the menu, in the order it should be drawn. Discriminate on `group`:
+ * an entry that has it is a submenu, an entry that does not is a command.
+ */
+export type ContextMenuItemState = ContextCommandState | ContextCommandGroupState;
+
+/** What an export request asks the host to produce. */
+export type ExportFormat = 'document' | 'png' | 'svg';
+
+/**
+ * The user picked something from the export submenu. Like `nodeProperties`, this is a
+ * request and nothing more: the control does not write files or open dialogs, so the
+ * host fulfils it with `saveDocument()`, `takeScreenshot()` or `takeSvg()` and its own
+ * options for scope, padding and background.
+ */
+export interface ExportRequestedPayload {
+    format: ExportFormat;
 }
 
 export interface ContextMenuRequestedPayload {
@@ -132,7 +182,7 @@ export interface ContextMenuRequestedPayload {
     link: Link | null;
     port: Port | null;
     portDirection: PortDirection | null;
-    commands: ContextCommandState[];
+    commands: ContextMenuItemState[];
 }
 
 export interface NodeSelectedPayload {
@@ -251,6 +301,7 @@ export interface DiagramEvents {
     loadFinished: LoadFinishedPayload;
     contextCommand: ContextCommandPayload;
     contextMenuRequested: ContextMenuRequestedPayload;
+    exportRequested: ExportRequestedPayload;
     undoRequested: NodeChangePayload & LinkChangePayload;
     redoRequested: NodeChangePayload & LinkChangePayload;
     nodeEdit: NodeChangePayload;

package/src/diagram/context-menu.ts

@@ -0,0 +1,363 @@
+import { t } from '../i18n.js';
+import type { ContextCommand, ContextCommandGroup, ContextMenuItemState } from './api.js';
+
+/**
+ * The control's own context menu.
+ *
+ * It exists because right-click already suppresses the browser's menu whether or not anyone
+ * is listening. A control that takes the native menu away owes one back, so this is on by
+ * default; a host with its own menu turns it off (`showContextMenu: false`) and keeps using
+ * `contextMenuRequested`, which is emitted either way.
+ *
+ * Styling follows the fullscreen button: inline styles driven by `--ssdiagram-*` custom
+ * properties with sensible fallbacks, so the menu is usable with no stylesheet at all and
+ * retintable without one. Class names are stable for hosts that would rather use CSS.
+ */
+
+const ROOT_CLASS = 'ssdiagram-context-menu';
+const ITEM_CLASS = 'ssdiagram-context-menu-item';
+const SUBMENU_CLASS = 'ssdiagram-context-menu-submenu';
+const SEPARATOR_CLASS = 'ssdiagram-context-menu-separator';
+const LABEL_CLASS = 'ssdiagram-context-menu-label';
+const ARROW_CLASS = 'ssdiagram-context-menu-arrow';
+const CHECK_CLASS = 'ssdiagram-context-menu-check';
+
+/** A rule below these entries, so related commands read as blocks rather than one long list. */
+const SEPARATE_AFTER: ReadonlySet<string> = new Set(['redo', 'paste', 'delete', 'overview']);
+
+function label(id: ContextCommand | ContextCommandGroup): string {
+    switch (id) {
+        case 'undo': return t('undo', 'Undo');
+        case 'redo': return t('redo', 'Redo');
+        case 'cut': return t('cut', 'Cut');
+        case 'copy': return t('copy', 'Copy');
+        case 'paste': return t('paste', 'Paste');
+        case 'open': return t('ctxOpen', 'Open');
+        case 'delete': return t('ctxDelete', 'Delete');
+        case 'export': return t('ctxExportAs', 'Export as');
+        case 'exportDocument': return t('ctxExportDocument', 'Scheme');
+        case 'exportPng': return t('ctxExportPng', 'PNG image');
+        case 'exportSvg': return t('ctxExportSvg', 'SVG image');
+        case 'overview': return t('ctxOverview', 'Overview');
+        case 'properties': return t('properties', 'Properties');
+        case 'help': return t('ctxHelp', 'Help');
+    }
+}
+
+const PANEL_STYLE: Partial<CSSStyleDeclaration> = {
+    position: 'fixed',
+    zIndex: '2147483000',
+    minWidth: '176px',
+    // Translations run longer than English -- German and Russian routinely half again. Without
+    // a cap the panel just grows, and on a narrow viewport it leaves the screen entirely, which
+    // no amount of repositioning can recover.
+    maxWidth: 'min(320px, calc(100vw - 16px))',
+    padding: '4px',
+    border: '1px solid var(--ssdiagram-menu-border, var(--ssdiagram-control-border, var(--t-border, #3a4250)))',
+    borderRadius: '7px',
+    background: 'var(--ssdiagram-menu-background, var(--ssdiagram-control-background, var(--t-panel, #181a20)))',
+    color: 'var(--ssdiagram-menu-color, var(--ssdiagram-control-color, var(--t-text, #eaecef)))',
+    boxShadow: '0 12px 32px rgba(0, 0, 0, 0.45)',
+    font: 'var(--ssdiagram-menu-font, 12.5px/1.35 system-ui, -apple-system, "Segoe UI", sans-serif)',
+    boxSizing: 'border-box',
+    userSelect: 'none',
+};
+
+const ITEM_STYLE: Partial<CSSStyleDeclaration> = {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '10px',
+    width: '100%',
+    padding: '6px 10px',
+    border: '0',
+    borderRadius: '4px',
+    background: 'transparent',
+    color: 'inherit',
+    font: 'inherit',
+    // Logical, not physical: on an RTL page these follow the writing direction instead of
+    // pinning the text left and truncating from the wrong end.
+    textAlign: 'start',
+    overflowWrap: 'anywhere',
+    cursor: 'pointer',
+    boxSizing: 'border-box',
+};
+
+const HOVER_BACKGROUND = 'var(--ssdiagram-menu-hover, var(--t-hover, rgba(255, 255, 255, 0.08)))';
+const DISABLED_COLOR = 'var(--ssdiagram-menu-disabled-color, var(--t-text-dim, #848e9c))';
+
+export interface ContextMenuViewOptions {
+    /** Where the menu is appended. The diagram mount point, so it survives a fullscreened panel. */
+    container: HTMLElement;
+    /** Runs the picked command. The same entry point a host menu would use. */
+    execute: (command: ContextCommand) => void;
+}
+
+export class ContextMenuView {
+    private readonly container: HTMLElement;
+    private readonly execute: (command: ContextCommand) => void;
+    private root: HTMLElement | null = null;
+    private submenu: HTMLElement | null = null;
+    private readonly submenuTriggers = new Map<HTMLElement, HTMLElement>();
+    private readonly detach: Array<() => void> = [];
+
+    constructor(options: ContextMenuViewOptions) {
+        this.container = options.container;
+        this.execute = options.execute;
+    }
+
+    get isOpen(): boolean {
+        return this.root !== null;
+    }
+
+    show(x: number, y: number, items: readonly ContextMenuItemState[]): void {
+        this.hide();
+        const owner = this.container.ownerDocument ?? document;
+        const root = this.panel(owner);
+        root.className = ROOT_CLASS;
+        root.setAttribute('role', 'menu');
+
+        const gutter = items.some((item) => !('group' in item) && item.checked !== undefined);
+        items.forEach((item, index) => {
+            if ('group' in item) root.appendChild(this.groupEntry(owner, item, gutter));
+            else root.appendChild(this.commandEntry(owner, item.command, item.enabled, true, item.checked, gutter));
+            const id = 'group' in item ? item.group : item.command;
+            if (SEPARATE_AFTER.has(id) && index < items.length - 1) root.appendChild(this.separator(owner));
+        });
+
+        this.container.appendChild(root);
+        this.root = root;
+        this.place(root, x, y);
+        this.watchForDismissal(owner);
+    }
+
+    hide(): void {
+        for (const dispose of this.detach.splice(0)) dispose();
+        this.submenu = null;
+        this.submenuTriggers.clear();
+        this.root?.remove();
+        this.root = null;
+    }
+
+    destroy(): void {
+        this.hide();
+    }
+
+    private panel(owner: Document): HTMLElement {
+        const panel = owner.createElement('div');
+        Object.assign(panel.style, PANEL_STYLE);
+        return panel;
+    }
+
+    private separator(owner: Document): HTMLElement {
+        const rule = owner.createElement('div');
+        rule.className = SEPARATOR_CLASS;
+        Object.assign(rule.style, {
+            height: '1px',
+            margin: '4px 6px',
+            background: 'var(--ssdiagram-menu-border, var(--t-border, #3a4250))',
+        });
+        return rule;
+    }
+
+    private item(
+        owner: Document,
+        text: string,
+        enabled: boolean,
+        arrow: boolean,
+        checked: boolean | undefined,
+        gutter: boolean,
+    ): HTMLButtonElement {
+        const button = owner.createElement('button');
+        button.type = 'button';
+        button.className = ITEM_CLASS;
+        button.setAttribute('role', checked === undefined ? 'menuitem' : 'menuitemcheckbox');
+        if (checked !== undefined) button.setAttribute('aria-checked', String(checked));
+        Object.assign(button.style, ITEM_STYLE);
+        if (!enabled) {
+            button.disabled = true;
+            button.style.color = DISABLED_COLOR;
+            button.style.cursor = 'default';
+        }
+
+        // Every item in a panel that has a checkable entry gets the same gutter, so the
+        // captions stay on one line rather than one row sitting further in than the rest.
+        if (gutter) {
+            const tick = owner.createElement('span');
+            tick.className = CHECK_CLASS;
+            tick.textContent = checked === true ? '✓' : '';
+            tick.setAttribute('aria-hidden', 'true');
+            Object.assign(tick.style, { flex: 'none', width: '12px', textAlign: 'center' });
+            button.appendChild(tick);
+        }
+
+        const caption = owner.createElement('span');
+        caption.className = LABEL_CLASS;
+        caption.textContent = text;
+        caption.style.flex = '1';
+        button.appendChild(caption);
+
+        if (arrow) {
+            const chevron = owner.createElement('span');
+            chevron.className = ARROW_CLASS;
+            // Points the way the submenu actually opens, which on an RTL page is the other way.
+            chevron.textContent = this.rtl() ? '‹' : '›';
+            chevron.setAttribute('aria-hidden', 'true');
+            Object.assign(chevron.style, { flex: 'none', opacity: '0.7', fontSize: '14px' });
+            button.appendChild(chevron);
+        }
+        return button;
+    }
+
+    // `closesSubmenu` separates the two places an item can live. A top-level item shuts any
+    // open submenu when the pointer arrives, the way menus everywhere behave. An item inside
+    // the submenu must not: reaching it means the pointer has entered that very panel, and
+    // closing it there would pull it out from under the pointer and drop the click on the
+    // canvas behind.
+    private commandEntry(
+        owner: Document,
+        command: ContextCommand,
+        enabled: boolean,
+        closesSubmenu: boolean,
+        checked: boolean | undefined,
+        gutter: boolean,
+    ): HTMLElement {
+        const button = this.item(owner, label(command), enabled, false, checked, gutter);
+        this.on(button, 'pointerenter', () => {
+            if (closesSubmenu) this.closeSubmenu();
+            if (enabled) button.style.background = HOVER_BACKGROUND;
+        });
+        this.on(button, 'pointerleave', () => { button.style.background = 'transparent'; });
+        this.on(button, 'click', () => {
+            if (!enabled) return;
+            // Hide first: a command may open a dialog, and a menu left on top of it looks stuck.
+            this.hide();
+            this.execute(command);
+        });
+        return button;
+    }
+
+    private groupEntry(
+        owner: Document,
+        group: { group: ContextCommandGroup; enabled: boolean; commands: readonly { command: ContextCommand; enabled: boolean; checked?: boolean }[] },
+        gutter: boolean,
+    ): HTMLElement {
+        const host = owner.createElement('div');
+        host.style.position = 'relative';
+
+        const button = this.item(owner, label(group.group), group.enabled, true, undefined, gutter);
+        button.setAttribute('aria-haspopup', 'menu');
+        button.setAttribute('aria-expanded', 'false');
+        host.appendChild(button);
+
+        const panel = this.panel(owner);
+        panel.className = SUBMENU_CLASS;
+        panel.setAttribute('role', 'menu');
+        panel.setAttribute('aria-label', label(group.group));
+        // insetInlineStart, not left: the submenu opens towards the end of the line, which
+        // is the right on an LTR page and the left on an RTL one.
+        Object.assign(panel.style, { position: 'absolute', insetInlineStart: '100%', top: '-5px', display: 'none' });
+        const childGutter = group.commands.some((child) => child.checked !== undefined);
+        for (const child of group.commands) {
+            panel.appendChild(this.commandEntry(owner, child.command, child.enabled, false, child.checked, childGutter));
+        }
+        host.appendChild(panel);
+
+        const open = (): void => {
+            if (!group.enabled) return;
+            button.style.background = HOVER_BACKGROUND;
+            button.setAttribute('aria-expanded', 'true');
+            panel.style.display = 'block';
+            this.submenu = panel;
+            this.keepOnScreen(panel);
+        };
+        this.on(button, 'pointerenter', open);
+        // Tap opens it too: a touch device never sends pointerenter on its own.
+        this.on(button, 'click', open);
+        this.on(host, 'pointerleave', () => {
+            if (this.submenu !== panel) return;
+            button.style.background = 'transparent';
+            button.setAttribute('aria-expanded', 'false');
+            panel.style.display = 'none';
+            this.submenu = null;
+        });
+        this.submenuTriggers.set(panel, button);
+        return host;
+    }
+
+    private closeSubmenu(): void {
+        if (this.submenu === null) return;
+        this.submenu.style.display = 'none';
+        this.submenuTriggers.get(this.submenu)?.setAttribute('aria-expanded', 'false');
+        this.submenu = null;
+    }
+
+    // Reads the resolved writing direction so the submenu's side and its arrow agree with it.
+    private rtl(): boolean {
+        if (typeof getComputedStyle !== 'function') return false;
+        try {
+            return getComputedStyle(this.container).direction === 'rtl';
+        } catch {
+            // A detached or fake container has no computed style; left-to-right is the safe read.
+            return false;
+        }
+    }
+
+    /** Keeps the panel inside the viewport, flipping it left when it would run off the edge. */
+    private keepOnScreen(panel: HTMLElement): void {
+        if (typeof panel.getBoundingClientRect !== 'function' || typeof window === 'undefined') return;
+        const box = panel.getBoundingClientRect();
+        if (box.right > window.innerWidth - 4 || box.left < 4) {
+            panel.style.insetInlineStart = 'auto';
+            panel.style.insetInlineEnd = '100%';
+        }
+        if (box.bottom > window.innerHeight - 4) {
+            panel.style.top = 'auto';
+            panel.style.bottom = '-5px';
+        }
+    }
+
+    private place(root: HTMLElement, x: number, y: number): void {
+        root.style.left = `${x}px`;
+        root.style.top = `${y}px`;
+        if (typeof root.getBoundingClientRect !== 'function' || typeof window === 'undefined') return;
+        const box = root.getBoundingClientRect();
+        // Flip rather than clamp: a menu shoved back onto the screen would cover the very
+        // thing that was right-clicked.
+        if (box.right > window.innerWidth - 4) root.style.left = `${Math.max(4, x - box.width)}px`;
+        if (box.bottom > window.innerHeight - 4) root.style.top = `${Math.max(4, y - box.height)}px`;
+    }
+
+    private watchForDismissal(owner: Document): void {
+        const dismiss = (): void => this.hide();
+        const outside = (event: Event): void => {
+            // Duck-typed rather than `target instanceof Node`: this runs in whatever document
+            // the host mounted us in, and a cross-document Node fails that check.
+            const root = this.root;
+            const target = event.target as Node | null;
+            if (root !== null && target !== null && typeof root.contains === 'function' && root.contains(target)) return;
+            this.hide();
+        };
+        this.on(owner, 'pointerdown', outside, true);
+        this.on(owner, 'keydown', (event: Event) => {
+            if ((event as KeyboardEvent).key === 'Escape') this.hide();
+        });
+        if (typeof window !== 'undefined') {
+            // Scroll and resize move the diagram out from under the menu, which would otherwise
+            // hang in place pointing at nothing.
+            this.on(window, 'blur', dismiss);
+            this.on(window, 'resize', dismiss);
+            this.on(window, 'scroll', dismiss, true);
+        }
+    }
+
+    private on(
+        target: { addEventListener?: (type: string, listener: EventListener, options?: boolean) => void; removeEventListener?: (type: string, listener: EventListener, options?: boolean) => void },
+        type: string,
+        listener: EventListener,
+        capture = false,
+    ): void {
+        if (typeof target.addEventListener !== 'function') return;
+        target.addEventListener(type, listener, capture);
+        this.detach.push(() => target.removeEventListener?.(type, listener, capture));
+    }
+}