prefer-create-el: iframe contentDocument has no Obsidian DOM helper equivalent

[zsviczian]

I agree with prefer-create-el as the default recommendation for ordinary plugin UI. Using Obsidian's DOM helpers generally produces clearer and more consistent plugin code.

There are, however, cases where native Document.createElement() is intentional and the target Document is part of the required semantics.

In Obsidian Excalidraw I have several such cases:

• detached <canvas> elements used for rendering, cropping and image export;
• detached <img> elements;
• <style> elements that must belong to an iframe's contentDocument;
• elements that must belong to a popout view's ownerDocument;
• detached containers used for parsing or offscreen rendering.

For example, this is intentionally document-scoped:

const style = iframe.contentDocument.createElement("style");
const canvas = ownerDocument.createElement("canvas");

Creating the element in another document and then moving it is not necessarily equivalent, and a global plugin stylesheet cannot style an isolated iframe document.

The current rule is therefore excellent guidance for:

document.createElement("div")

when constructing ordinary Obsidian UI, but it is overly broad for operations whose purpose is specifically to create an element owned by another Document, or to create a detached rendering object.

Possible ways to focus the rule:

1. Treat explicit ownerDocument.createElement(...) and contentDocument.createElement(...) differently from generic global-document UI creation.
2. Recognize common detached rendering elements such as canvas and img.
3. Document a supported Obsidian API for creating an element in an explicitly supplied Document, if one exists.
4. Otherwise allow the normal narrowly-scoped ESLint suppression mechanism to represent these intentional cases without producing a Community Plugin scorecard warning.

[saberzero1]

I believe we already had this discussion. Does CSSStyleSheet work for your CSS case and DocumentFragment for your detached DOM cases?

[zsviczian]

Thanks — I looked at these cases again.

DocumentFragment does not itself replace the detached rendering elements I need. For example the image/canvas paths use APIs specific to those elements:

image.src = objectUrl;
await image.decode();

const context = canvas.getContext("2d");
canvas.toBlob(...);

That said, after reviewing one of my detached crop helpers more critically, I agree that its canvas/img probably do not actually need to belong to the view's ownerDocument. They are never attached to the DOM, so an Obsidian helper creating detached elements should be sufficient there. I'll simplify those cases where document ownership is not semantically required.

The iframe case is different and is the stronger example behind this issue:

const style = iframe.contentDocument.createElement("style");
iframe.contentDocument.head.appendChild(style);

Here the target Document is intentional: the style must belong to and affect the iframe document. A plugin stylesheet in the main Obsidian document cannot cross that document boundary.

CSSStyleSheet looks useful for some of these cases and I'll use it where it is equivalent. It does not appear to cover all of them, though: constructable/adopted stylesheets have runtime compatibility considerations, and replace() / replaceSync() are not fully equivalent for arbitrary CSS containing constructs such as @import.

So I think your suggestions can remove some of my current native DOM uses, which is helpful. What I am still trying to resolve is the narrower case where creation in a specific secondary Document is actually required.

Is there an Obsidian-supported pattern you recommend for creating an element specifically in an iframe's contentDocument?

[saberzero1]

Just so I understand the scope of your issue: your non-iframe cases can be handled via DocumentFragment?

Handling iframe is a bit iffy regardless, because it is both an entire separate document scope, but also itself a child element of another document. I'll have do some digging in how we want to approach this, as we generally do not want to encourage iframe usage if not strictly necessary.

[zsviczian]

Thanks. I audited the current native element-creation sites more carefully to answer the scope question.

I don't think all of the non-iframe cases can be handled by DocumentFragment. They currently fall into roughly four categories:

1. iframe-owned elements, mainly <style> elements that must belong to the iframe's contentDocument.
2. Document-scoped dynamic styles outside iframes. These are deliberate cases where a static plugin stylesheet is not equivalent:

• Excalidraw's local font can be changed dynamically by the user, so the corresponding font CSS has to be generated/updated at runtime.
• In Excalidraw Extras, PDF export temporarily injects print-specific CSS containing per-export values and rules that must apply only while Electron is rendering the PDF, then removes it afterwards.

This styling category may deserve separate treatment from the detached-DOM question.

3. Detached rendering primitives, mainly <canvas> and <img> for image processing/export. A DocumentFragment can contain these elements, but it doesn't replace them: the code needs the specialized element APIs themselves:

   image.src = objectUrl;
   await image.decode();
   
   const context = canvas.getContext("2d");
   canvas.toBlob(...);

   So I would still need an HTMLImageElement / HTMLCanvasElement; putting it inside a fragment does not eliminate the need to create that element.

4. Detached HTML serialization containers. I found at least two cases where a temporary <div> exists specifically because I need innerHTML.

   One is exporting declarative setting descriptions to Markdown so the user can feed the super large Excalidraw settings definitions to an LLM and search it:

   const container = document.createElement("div");
   container.appendChild(value.cloneNode(true));
   return htmlToMarkdown(container.innerHTML).trim();

The declarative settings API itself still supports DocumentFragment descriptions; this code is for Excalidraw's separate Markdown export of the settings definitions. DocumentFragment does not expose innerHTML, so replacing the <div> with a fragment does not provide the serialization needed by htmlToMarkdown().

There is a similar case in the settings content-search/export code, where selected DOM nodes are cloned into a detached container, its innerHTML is transformed, and the result is converted to Markdown.

So DocumentFragment does help narrow the question, but I don't think it is an equivalent replacement for all non-iframe cases.

The iframe case remains the clearest case where the specific target Document is intrinsic to the operation. The dynamic-style cases may be a separate rule/policy discussion, while the canvas/image and HTML-serialization cases are more about whether native creation of detached specialized elements should have a legitimate path.

If there is an Obsidian-supported pattern I'm overlooking for either creating these specialized detached elements or serializing a DocumentFragment to HTML without introducing an otherwise unnecessary wrapper element, I'm happy to use it.

[saberzero1]

Thanks. I audited the current native element-creation sites more carefully to answer the scope question.

I don't think all of the non-iframe cases can be handled by DocumentFragment. They currently fall into roughly four categories:

1. iframe-owned elements, mainly <style> elements that must belong to the iframe's contentDocument.
2. Document-scoped dynamic styles outside iframes. These are deliberate cases where a static plugin stylesheet is not equivalent:

• Excalidraw's local font can be changed dynamically by the user, so the corresponding font CSS has to be generated/updated at runtime.
• In Excalidraw Extras, PDF export temporarily injects print-specific CSS containing per-export values and rules that must apply only while Electron is rendering the PDF, then removes it afterwards.

This styling category may deserve separate treatment from the detached-DOM question.

3. Detached rendering primitives, mainly <canvas> and <img> for image processing/export. A DocumentFragment can contain these elements, but it doesn't replace them: the code needs the specialized element APIs themselves:

   image.src = objectUrl;
   await image.decode();
   
   const context = canvas.getContext("2d");
   canvas.toBlob(...);

   So I would still need an HTMLImageElement / HTMLCanvasElement; putting it inside a fragment does not eliminate the need to create that element.

4. Detached HTML serialization containers. I found at least two cases where a temporary <div> exists specifically because I need innerHTML.

   One is exporting declarative setting descriptions to Markdown so the user can feed the super large Excalidraw settings definitions to an LLM and search it:

   const container = document.createElement("div");
   container.appendChild(value.cloneNode(true));
   return htmlToMarkdown(container.innerHTML).trim();

The declarative settings API itself still supports DocumentFragment descriptions; this code is for Excalidraw's separate Markdown export of the settings definitions. DocumentFragment does not expose innerHTML, so replacing the <div> with a fragment does not provide the serialization needed by htmlToMarkdown().

There is a similar case in the settings content-search/export code, where selected DOM nodes are cloned into a detached container, its innerHTML is transformed, and the result is converted to Markdown.

So DocumentFragment does help narrow the question, but I don't think it is an equivalent replacement for all non-iframe cases.

The iframe case remains the clearest case where the specific target Document is intrinsic to the operation. The dynamic-style cases may be a separate rule/policy discussion, while the canvas/image and HTML-serialization cases are more about whether native creation of detached specialized elements should have a legitimate path.

If there is an Obsidian-supported pattern I'm overlooking for either creating these specialized detached elements or serializing a DocumentFragment to HTML without introducing an otherwise unnecessary wrapper element, I'm happy to use it.

1. iframe. Already discussed.
2. There are dedicated functions for this in, such as setProperty, as well as Obsidian API functions such as setCssProps() and setCssStyles().
3. You should still be able to attach them via createEl() and then assign them via one of the child functions to get the correct reference. I don't understand why that won't work.
4. Use XMLSerializer to stringify a DOM tree. Use DOMParser to parse it back to a DOM tree.

[zsviczian]

Thanks, this discussion was useful. I went back through all 20 related lint findings in Excalidraw and implemented the suggestions where they were equivalent to the existing behavior.

The resulting changes are in zsviczian/obsidian-excalidraw-plugin#2921:

• 5 detached <canvas> / <img> creations now use createFragment().createEl(...);
• 2 temporary serialization wrappers were removed by working with DocumentFragment directly;
• the dynamic @font-face stylesheet in FontManager was replaced with document-scoped FontFace registration, preserving unicodeRange metadata and cleanup.

That removes 8 of the original 20 native element-creation cases. All 12 remaining calls create <style> elements.

Of those, 7 are non-iframe dynamic stylesheet cases. I think that is a separate concern from prefer-create-el, so I opened #197 to discuss those specifically.

The remaining 5 are styles that belong to an iframe's contentDocument. Since you mentioned that iframe handling needs separate investigation, I am renaming this issue to focus specifically on that unresolved case.

Thanks again, your suggestions here already resulted in cleaner code, and narrowing the issue this way should make the remaining question more precise.