officeparser 7.6.2 → 7.8.0

package/dist/officeparser.browser.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.
@@ -1039,6 +1060,49 @@ export interface CsvGeneratorConfig {
  * historical output exactly (every feature on, GitHub-style admonitions).
  */
 export type MarkdownDialectPreset = "extended" | "github" | "gitlab" | "obsidian" | "pandoc" | "commonmark";
+/** Admonition syntax: `'blockquote'` = GitHub `> [!NOTE]`, `'fence'` = GitLab `:::note`,
+ *  `'fence-attribute'` = Pandoc `::: {.note}`, `'none'` = plain bold-labeled blockquote. */
+export type AdmonitionSyntax = "blockquote" | "fence" | "fence-attribute" | "none";
+/** `==text==` highlight (`'equals'`), or `'none'` to disable. */
+export type HighlightSyntax = "equals" | "none";
+/** GFM `~~text~~` strikethrough (`'tilde'`), or `'none'`. */
+export type StrikethroughSyntax = "tilde" | "none";
+/** `Term`/`: Description` definition lists (`'colon'`), or `'none'`. */
+export type DefinitionListSyntax = "colon" | "none";
+/** `[^id]` footnotes (`'caret'`), or `'none'`. */
+export type FootnoteSyntax = "caret" | "none";
+/** `[@citekey]` citations (`'at'`), or `'none'`. */
+export type CitationSyntax = "at" | "none";
+/** `[[Page]]` wikilinks (`'double-bracket'`), or `'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'`.
+ * These aliases still resolve to the same output and will be removed in the next major version.
+ */
+export type DeprecatedAdmonitionFlavor = "github" | "gitlab" | "pandoc";
+/**
+ * @deprecated Boolean toggles for dialect capability fields are deprecated in favor of the
+ * syntax-name unions: `true` maps to that field's on-value (e.g. `'tilde'`), `false` maps to
+ * `'none'`. Booleans keep working via coercion and will be removed in the next major version.
+ */
+export type DeprecatedDialectToggle = boolean;
 /**
  * Granular control over which native Markdown syntax the generator emits for constructs that
  * differ across real-world dialects (e.g. GitHub's `> [!NOTE]` vs GitLab's `:::note` vs Pandoc's
@@ -1050,25 +1114,60 @@ export type MarkdownDialectPreset = "extended" | "github" | "gitlab" | "obsidian
 export interface MarkdownDialectConfig {
 	/** Base preset any omitted field inherits from. Defaults to 'extended'. */
 	extends?: MarkdownDialectPreset;
-	/** Admonition syntax: GitHub `> [!NOTE]`, GitLab `:::note`, Pandoc `::: {.note}`, or `'none'`
-	 *  to degrade to a plain bold-labeled blockquote with no special marker. */
-	admonitions?: "github" | "gitlab" | "pandoc" | "none";
-	/** Markdown Extra/Pandoc-style `Term\n: Description` definition lists. */
-	definitionLists?: boolean;
-	/** `[^id]` footnote references/definitions. When false, note content is inlined as a
-	 *  parenthetical right at the reference point instead of using footnote syntax. */
-	footnotes?: boolean;
-	/** Pandoc-style `[@citekey]` citations. When false, emits `[citekey]` (brackets, no `@`). */
-	citations?: boolean;
-	/** Obsidian-style `[[Page]]`/`[[Page|Alias]]` wikilinks. When false, falls back to a plain
-	 *  `[text](url)` link using the same target. */
-	wikilinks?: boolean;
-	/** Inline `$...$`/block `$$...$$` math delimiters, or `'none'` for bare LaTeX text. */
+	/**
+	 * Admonition syntax: `'blockquote'` = GitHub `> [!NOTE]`, `'fence'` = GitLab `:::note`,
+	 * `'fence-attribute'` = Pandoc `::: {.note}`, `'none'` = a plain bold-labeled blockquote with no
+	 * special marker. Omit to inherit from the `extends` preset. The legacy flavor names
+	 * `'github'`/`'gitlab'`/`'pandoc'` are accepted as deprecated aliases (see
+	 * `DeprecatedAdmonitionFlavor`) and will be removed in the next major version.
+	 */
+	admonitions?: AdmonitionSyntax | DeprecatedAdmonitionFlavor;
+	/**
+	 * Markdown Extra/Pandoc-style `Term`/`: Description` definition lists (`'colon'`), or `'none'`
+	 * to render terms and descriptions as plain paragraphs. Omit to inherit from `extends`. Passing
+	 * a boolean is deprecated: `true` = `'colon'`, `false` = `'none'` (removed next major).
+	 */
+	definitionLists?: DefinitionListSyntax | DeprecatedDialectToggle;
+	/**
+	 * `[^id]` footnote references/definitions (`'caret'`), or `'none'` to inline note content as a
+	 * parenthetical right at the reference point. Omit to inherit from `extends`. Passing a boolean
+	 * is deprecated: `true` = `'caret'`, `false` = `'none'` (removed next major).
+	 */
+	footnotes?: FootnoteSyntax | DeprecatedDialectToggle;
+	/**
+	 * Pandoc-style `[@citekey]` citations (`'at'`), or `'none'` to emit `[citekey]` (brackets, no
+	 * `@`). Omit to inherit from `extends`. Passing a boolean is deprecated: `true` = `'at'`,
+	 * `false` = `'none'` (removed next major).
+	 */
+	citations?: CitationSyntax | DeprecatedDialectToggle;
+	/**
+	 * Obsidian-style `[[Page]]`/`[[Page|Alias]]` wikilinks (`'double-bracket'`), or `'none'` to fall
+	 * back to a plain `[text](url)` link using the same target. Omit to inherit from `extends`.
+	 * Passing a boolean is deprecated: `true` = `'double-bracket'`, `false` = `'none'` (removed next major).
+	 */
+	wikilinks?: WikilinkSyntax | DeprecatedDialectToggle;
+	/** Inline `$...$`/block `$$...$$` math delimiters (`'dollar'`), or `'none'` for bare LaTeX text. */
 	math?: "dollar" | "none";
-	/** Pandoc-style `{width=50% .centered}` attribute lists after images/tables. */
-	attributeLists?: boolean;
-	/** GFM `~~text~~` strikethrough (not part of base CommonMark). */
-	strikethrough?: boolean;
+	/**
+	 * Pandoc-style `{width=50% .centered}` attribute lists after images/tables (`'brace'`), or
+	 * `'none'`. Omit to inherit from `extends`. Passing a boolean is deprecated: `true` = `'brace'`,
+	 * `false` = `'none'` (removed next major).
+	 */
+	attributeLists?: AttributeListSyntax | DeprecatedDialectToggle;
+	/**
+	 * GFM `~~text~~` strikethrough (`'tilde'`; not part of base CommonMark), or `'none'`. Omit to
+	 * inherit from `extends`. Passing a boolean is deprecated: `true` = `'tilde'`, `false` = `'none'`
+	 * (removed next major).
+	 */
+	strikethrough?: StrikethroughSyntax | DeprecatedDialectToggle;
+	/**
+	 * `==text==` highlight (`'equals'`; Obsidian/extended flavors, NOT GFM or CommonMark where `==`
+	 * is literal text), or `'none'`. When `'equals'`, a highlighted run round-trips as `==text==`
+	 * and `==text==` is read back as a highlight; when `'none'`, a highlight falls back to an HTML
+	 * `<mark>`/`<span>` per `fallbackToHtml.inlineFormatting`, and `==text==` stays literal on parse.
+	 * Omit to inherit from `extends`.
+	 */
+	highlight?: HighlightSyntax;
 	/** Unordered list bullet character. */
 	bulletListMarker?: "-" | "*" | "+";
 	/** Ordered list marker punctuation. */
@@ -1078,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
@@ -1094,10 +1200,22 @@ 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;
+	/**
+	 * Multi-paragraph list-item content (an HTML `<li>` with several `<p>` children) joined with
+	 * `<br>` instead of a space, so it stays on the item's single Markdown line. Block children of
+	 * an item (a code fence or table inside `<li>`) degrade under this join, the same way they do
+	 * inside a table cell under `cellLineBreaks`.
+	 */
+	itemLineBreaks?: boolean;
 	/**
 	 * Inline text color, highlight, and font size via a `<span style="color:...;background-color:...;
 	 * font-size:...">` run, which the Markdown parser reads back. These have no Markdown syntax and
@@ -1604,6 +1722,12 @@ export interface CellMetadata {
 	 * @example 0 for column A, 1 for column B, etc.
 	 */
 	col: number;
+	/**
+	 * Text alignment for this cell's column, from the GFM pipe-table separator row
+	 * (`:---` left, `:---:` center, `---:` right). All cells in a column carry the same value;
+	 * the Markdown generator reads it from the header row to emit the separator.
+	 */
+	align?: "left" | "center" | "right";
 	/**
 	 * The number of rows this cell spans (merges).
 	 * @example 2 if the cell is merged with the one below it.
@@ -1682,6 +1806,8 @@ export interface ImageMetadata {
 	 * @example 'center'
 	 */
 	align?: "left" | "center" | "right";
+	/** Advisory image title (Markdown `![alt](url "title")`, HTML `<img title>`), if any. */
+	title?: string;
 }
 /**
  * Metadata for an embedded external media node (e.g. a YouTube video).
@@ -1699,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`).
@@ -1765,6 +1894,8 @@ export interface TextMetadata {
 	 * officeParser always parses/generates the syntax.
 	 */
 	wikilink?: boolean;
+	/** Advisory link title (Markdown `[text](url "title")`, HTML `<a title>`), if any. */
+	title?: string;
 }
 /**
  * Metadata for note nodes (footnotes/endnotes).