Files
19e5888216 fix: Preserve diagram file format (PNG/SVG) when editing (#11622)
* Initial plan

* Implement format retention for diagram editing

Co-authored-by: tommoor <380914+tommoor@users.noreply.github.com>

* Address code review feedback: improve comments and property order

Co-authored-by: tommoor <380914+tommoor@users.noreply.github.com>

* refactor

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: tommoor <380914+tommoor@users.noreply.github.com>
Co-authored-by: Tom Moor <tom@getoutline.com>
2026-03-02 18:12:52 -05:00

283 lines
8.9 KiB
TypeScript

import type { Command, EditorState } from "prosemirror-state";
import { NodeSelection } from "prosemirror-state";
import type { Node } from "prosemirror-model";
import type { CommandFactory } from "../lib/Extension";
import Extension from "../lib/Extension";
import FileHelper, { ImageSource } from "../lib/FileHelper";
import { IntegrationService } from "../../types";
import type { NodeWithPos } from "../types";
import {
DiagramsNetClient,
EMPTY_DIAGRAM_IMAGE,
} from "../lib/DiagramsNetClient";
import { sanitizeUrl } from "../../utils/urls";
/**
* Tracks the mutable state for a single diagram editing session. Callbacks
* close over a session object so that concurrent or overlapping sessions
* do not interfere with each other.
*/
interface DiagramSession {
/** The current src used to locate the node in the document. Updated after each successful export. */
nodeSrc: string;
/** The format to use for exporting the diagram (xmlsvg or xmlpng). */
format: "xmlsvg" | "xmlpng";
}
/**
* An editor extension that adds commands to insert and edit diagrams using diagrams.net.
*
* This extension provides a command to open the diagrams.net editor for creating
* and editing diagrams. Diagrams are stored as SVG or PNG images with embedded XML data
* that allows them to be re-edited later.
*/
export default class Diagrams extends Extension {
get name() {
return "diagrams";
}
commands(): Record<string, CommandFactory> {
return {
editDiagram: (): Command => (state, dispatch) => {
if (!dispatch) {
return true;
}
const selectedNode = this.getSelectedImageNode(state);
if (!selectedNode) {
this.insertEmptyDiagram(state, dispatch);
}
this.openDiagramEditor(selectedNode);
return true;
},
};
}
/**
* Gets the currently selected image node if it exists.
*
* @param state - the editor state.
* @returns the selected image node or undefined.
*/
private getSelectedImageNode(state: EditorState) {
if (state.selection instanceof NodeSelection) {
const node = state.selection.node;
if (node.type.name === "image") {
return node;
}
}
return;
}
/**
* Inserts an empty diagram placeholder at the current cursor position.
*
* @param state - the editor state.
* @param dispatch - the dispatch function.
*/
private insertEmptyDiagram(
state: EditorState,
dispatch: (tr: ReturnType<EditorState["tr"]["insert"]>) => void
) {
const type = this.editor.schema.nodes.image;
const { tr } = state;
const transaction = tr.insert(
state.selection.from,
type.create({
src: "",
source: ImageSource.DiagramsNet,
})
);
dispatch(transaction);
}
/**
* Opens the diagram editor for creating or editing a diagram.
*
* @param node - the selected image node, if any.
*/
private openDiagramEditor(node?: Node) {
const nodeSrc = node?.attrs.src ?? "";
const sourceUrl = nodeSrc || EMPTY_DIAGRAM_IMAGE;
// Create a per-session object. Async callbacks close over this object so
// that a second editing session does not clobber the first session's state.
// Format defaults to SVG and is updated after fetching the actual content.
const session: DiagramSession = { nodeSrc, format: "xmlsvg" };
// Clean up any existing client
if (this.client) {
this.client.close();
}
this.client = new DiagramsNetClient(
(client) => this.onDiagramReady(client, sourceUrl, session),
(base64Data) => this.onDiagramExported(base64Data, session)
);
this.client.open(this.getDiagramsNetUrl());
}
/**
* Called when the diagram editor is ready to receive commands.
*
* @param client - the DiagramsNetClient that fired the ready event.
* @param sourceUrl - the URL of the diagram to load, or the empty diagram constant.
* @param session - the editing session to update with the detected format.
*/
private async onDiagramReady(
client: DiagramsNetClient,
sourceUrl: string,
session: DiagramSession
) {
let data: string;
if (sourceUrl === EMPTY_DIAGRAM_IMAGE) {
// For empty diagram, send full data URI
data = `data:image/svg+xml;base64,${EMPTY_DIAGRAM_IMAGE}`;
} else {
// For existing diagrams, send the full data URI
data = await FileHelper.urlToBase64(sourceUrl);
}
// Detect format from the data URI now that we have the actual content.
const format = data.startsWith("data:image/png") ? "xmlpng" : "xmlsvg";
session.format = format;
client.format = format;
client.loadDiagram(data);
}
/**
* Called when a diagram has been exported from the editor.
*
* @param base64Data - the exported diagram as base64 encoded SVG or PNG.
* @param session - the editing session that produced this export.
*/
private async onDiagramExported(base64Data: string, session: DiagramSession) {
try {
// Use the format from the session to create the appropriate file
const isPng = session.format === "xmlpng";
const filename = isPng ? "diagram.png" : "diagram.svg";
const mimeType = isPng ? "image/png" : "image/svg+xml";
const file = FileHelper.base64ToFile(base64Data, filename, mimeType);
const dimensions = await FileHelper.getImageDimensions(file);
const uploadedUrl = await this.uploadDiagramFile(file);
// Capture the src we need to search for *before* updating the session,
// then update the document and the session atomically.
const srcToFind = session.nodeSrc;
this.updateDiagramInDocument(uploadedUrl, dimensions || {}, srcToFind);
// Update session so that subsequent saves within the same editing session
// can locate the node by its new uploaded URL.
session.nodeSrc = uploadedUrl;
} catch (error) {
// eslint-disable-next-line no-console
console.error("Failed to export diagram:", error);
}
}
/**
* Uploads the diagram file using the editor's upload handler.
*
* @param file - the diagram file to upload.
* @returns promise resolving to the uploaded file URL.
* @throws Error if no upload handler is configured.
*/
private async uploadDiagramFile(file: File): Promise<string> {
const { uploadFile } = this.editor.props;
if (!uploadFile) {
throw new Error("No upload handler configured");
}
return uploadFile(file);
}
/**
* Updates or inserts the diagram image in the document. Always reads fresh
* editor state at call-time so that positions are accurate even after async
* gaps.
*
* @param uploadedUrl - the URL of the uploaded diagram.
* @param dimensions - the image dimensions.
* @param srcToFind - the src attribute value to search for in the document.
*/
private updateDiagramInDocument(
uploadedUrl: string,
dimensions: { width?: number; height?: number },
srcToFind: string
) {
// Read fresh state at the moment of dispatch to avoid stale positions.
const { state } = this.editor.view;
const { dispatch } = this.editor.view;
const imageType = this.editor.schema.nodes.image;
// Try to find and update the existing node by its current src attribute.
const existingNode = this.findImageNodeBySrc(state, srcToFind);
const attrs = {
...dimensions,
src: uploadedUrl,
source: ImageSource.DiagramsNet,
};
if (existingNode) {
dispatch(
state.tr.setNodeMarkup(existingNode.pos, undefined, {
...existingNode.node.attrs,
...attrs,
})
);
} else {
const imageNode = imageType.create(attrs);
const transaction = state.tr.insert(state.selection.from, imageNode);
dispatch(transaction);
}
}
/**
* Finds an image node in the document by its src attribute.
*
* @param state - the editor state.
* @param src - the image source URL to search for.
* @returns the node and its position, or undefined.
*/
private findImageNodeBySrc(
state: EditorState,
src: string
): NodeWithPos | undefined {
let foundNode: NodeWithPos | undefined;
state.doc.descendants((node, pos) => {
if (node.attrs.src === src && node.type.name === "image") {
foundNode = { node, pos };
return false; // Stop searching
}
return true;
});
return foundNode;
}
/**
* Gets the configured diagrams.net URL or returns the default.
*
* @returns the diagrams.net editor URL.
*/
private getDiagramsNetUrl(): string {
const integration = this.editor.props.embeds?.find(
(integ) => integ.name === IntegrationService.Diagrams
);
const uiTheme = this.editor.props.theme.isDark ? "dark" : "atlas";
return (
sanitizeUrl(
integration?.settings?.diagrams?.url ?? "https://embed.diagrams.net/"
) + `?embed=1&ui=${uiTheme}&spin=1&modified=unsavedChanges&proto=json`
);
}
private client: DiagramsNetClient;
}