officeparser 7.7.0 → 7.8.0

package/dist/officeparser.browser.slim.d.ts

@@ -415,6 +415,18 @@ export interface HtmlParserConfig {
 	 * Defaults to false.
 	 */
 	preserveIframes?: boolean | string[];
+	/**
+	 * Import ambiguous "folk" embed forms in Markdown as embeds: a standalone Obsidian-style image
+	 * whose URL is a YouTube link (`![](https://youtube.com/watch?v=ID)`), and the clickable
+	 * thumbnail-link (`[![alt](https://img.youtube.com/vi/ID/…)](watch-url)`). Both become a
+	 * `embedType: 'youtube'` embed (rendered from the validated id, so it is safe). Off by default:
+	 * auto-upgrading an image/link to an embed is a heuristic that could mangle a genuinely-intended
+	 * image link, so a consumer opts in. The unambiguous forms (`<div data-youtube-video>`, a bare
+	 * YouTube `<iframe>`, the `::youtube` directive) are always recognized, independent of this flag.
+	 *
+	 * Defaults to false.
+	 */
+	embedFolkForms?: boolean;
 }
 /**
  * Maps an input format string to its corresponding format-specific parser configuration, mirroring
@@ -883,6 +895,15 @@ export interface HtmlGeneratorConfig {
 	 * `HtmlParser` reads every shape this emits, so output stays self-round-trippable.
 	 */
 	sourceAttributes?: boolean;
+	/**
+	 * Emit a generic (non-YouTube) iframe embed as a gated placeholder,
+	 * `<div data-embed-gated data-embed-src="…" …>`, instead of a live `<iframe>`. The gated shape
+	 * never auto-loads its src: an editor renders a click-to-load placeholder from it, and
+	 * `HtmlParser` reads it back to the same `embed` node. The src is scheme-checked (`sanitizeUrl`)
+	 * on emit. Off by default; the default output (a live `<iframe>`) is unchanged. YouTube embeds
+	 * are unaffected (they already render from a validated id).
+	 */
+	gatedEmbeds?: boolean;
 }
 /**
  * Configuration options for PDF generation.
@@ -1056,6 +1077,20 @@ export type CitationSyntax = "at" | "none";
 export type WikilinkSyntax = "double-bracket" | "none";
 /** `{width=50%}` attribute lists (`'brace'`), or `'none'`. */
 export type AttributeListSyntax = "brace" | "none";
+/**
+ * How an `embed` node is written to Markdown:
+ * - `'html'` (default): the single-line `<div data-youtube-video="ID">` / `<iframe src=...>` block
+ *   this library has always emitted. Round-trips through officeParser, but renders as an invisible
+ *   empty box on GitHub.
+ * - `'directive'`: a remark-directive leaf, `::youtube[Label]{id=... width=... align=...}` /
+ *   `::embed[Label]{src=... width=... height=... align=...}`. Round-trips within an editor that
+ *   understands it; renders verbatim (not just the label) on GitHub, so it is an editor format, not
+ *   a GitHub-interop one.
+ * - `'link'`: a plain `[YouTube](url)` / `[Embed](url)`.
+ * - `'thumbnail'`: a YouTube-only clickable thumbnail `[![Label](.../vi/ID/hqdefault.jpg)](watch)`,
+ *   the best GitHub degrade; a non-YouTube embed falls back to `'link'`.
+ */
+export type EmbedSyntax = "html" | "directive" | "link" | "thumbnail";
 /**
  * @deprecated Legacy flavor names for `MarkdownDialectConfig.admonitions`. Use the syntax names
  * instead: `'github'` -> `'blockquote'`, `'gitlab'` -> `'fence'`, `'pandoc'` -> `'fence-attribute'`.
@@ -1142,6 +1177,13 @@ export interface MarkdownDialectConfig {
 	/** Table syntax: native GFM pipe tables, or forced HTML `<table>` (required for strict
 	 *  CommonMark, which has no table syntax of its own). */
 	tables?: "native" | "html";
+	/**
+	 * How an `embed` node is written to Markdown (`'html'` | `'directive'` | `'link'` |
+	 * `'thumbnail'`; see `EmbedSyntax`). This is the authority for embed form. When omitted, the
+	 * deprecated `fallbackToHtml.embeds` boolean is honored (`true`/unset maps to `'html'`, `false`
+	 * to `'link'`), then the default `'html'`.
+	 */
+	embeds?: EmbedSyntax;
 }
 /**
  * Granular control over when the Markdown generator falls back to raw HTML tags for features
@@ -1158,7 +1200,12 @@ export interface FallbackToHtmlConfig {
 	anchors?: boolean;
 	/** Nested-table and merged-cell (colspan/rowspan) HTML `<table>` fallback. */
 	tables?: boolean;
-	/** YouTube embed `<div data-youtube-video>` vs. a plain link. */
+	/**
+	 * YouTube embed `<div data-youtube-video>` vs. a plain link.
+	 * @deprecated Use `mdConfig.dialect.embeds` (`EmbedSyntax`) instead, which also selects the
+	 * `'directive'` and `'thumbnail'` forms. When `dialect.embeds` is unset this boolean is still
+	 * honored (`true` maps to `'html'`, `false` to `'link'`); it will be removed in the next major.
+	 */
 	embeds?: boolean;
 	/** Multi-line table cell content joined with `<br>` instead of a space. */
 	cellLineBreaks?: boolean;
@@ -1778,10 +1825,13 @@ export interface EmbedMetadata {
 	url?: string;
 	/** Display width, as a CSS length or percentage. */
 	width?: string;
-	/** Display height, as a CSS length or percentage (generic iframes). */
+	/** Display height, as a CSS length or percentage. */
 	height?: string;
 	/** Layout alignment of the embed. */
 	align?: "left" | "center" | "right";
+	/** Human-readable label for the embed (e.g. the `[Label]` of a `::youtube[Label]{...}` leaf
+	 *  directive, or a gated embed's caption). Purely descriptive; never a trust or render input. */
+	label?: string;
 }
 /**
  * Metadata for an admonition/alert node (e.g. GitHub's `> [!NOTE]` or GLFM's `:::note`).