🎇 Placeholder for iFrame (#1609)

.changeset/cool-suits-repair.md

@@ -0,0 +1,7 @@
+---
+"myst-directives": patch
+"myst-spec-ext": patch
+"myst-to-typst": patch
+---
+
+Allow for iframe to have a placeholder

packages/myst-directives/src/iframe.ts

@@ -1,4 +1,4 @@
-import type { Iframe } from 'myst-spec-ext';
+import type { Iframe, Image } from 'myst-spec-ext';
 import type { DirectiveSpec, DirectiveData, GenericNode } from 'myst-common';
 import { addCommonDirectiveOptions, commonDirectiveOptions } from './utils.js';
 
@@ -23,6 +23,10 @@ export const iframeDirective: DirectiveSpec = {
       type: String,
       doc: 'The alignment of the iframe in the page. Choose one of `left`, `center` or `right`',
     },
+    placeholder: {
+      type: String,
+      doc: 'A placeholder image for the iframe in static exports.',
+    },
   },
   body: { type: 'myst', doc: 'If provided, this will be the iframe caption.' },
   run(data: DirectiveData): GenericNode[] {
@@ -32,6 +36,19 @@ export const iframeDirective: DirectiveSpec = {
       width: data.options?.width as string,
       align: data.options?.align as Iframe['align'],
     };
+    if (data.options?.placeholder) {
+      iframe.children = [
+        {
+          type: 'image',
+          placeholder: true,
+          url: data.options.placeholder as string,
+          alt: data.options?.alt as string,
+          width: data.options?.width as string,
+          height: data.options?.height as string,
+          align: data.options?.align as Image['align'],
+        } as Image,
+      ];
+    }
     if (!data.body) {
       iframe.class = data.options?.class as string;
       addCommonDirectiveOptions(data, iframe);

packages/myst-spec-ext/src/types.ts

@@ -125,6 +125,7 @@ export type Iframe = Target & {
   width?: string;
   align?: Image['align'];
   class?: Image['class'];
+  children?: Image[];
 };
 
 export type Admonition = SpecAdmonition & {

packages/myst-to-typst/src/index.ts

@@ -309,6 +309,19 @@ const handlers: Record<string, Handler> = {
     }
     state.write(')\n\n');
   },
+  iframe(node, state) {
+    const image = node.children?.[0];
+    if (!image || image.placeholder !== true) return;
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { width: nodeWidth, url: nodeSrc, align } = image;
+    const src = nodeSrc;
+    const width = getLatexImageWidth(nodeWidth);
+    state.write(`#image("${src}"`);
+    if (!state.data.isInTable) {
+      state.write(`, width: ${width}`);
+    }
+    state.write(')\n\n');
+  },
   container: containerHandler,
   caption: captionHandler,
   legend: captionHandler,