officeparser 7.6.2 → 7.8.0

package/dist/types.d.ts

@@ -413,6 +413,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
@@ -909,6 +921,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.
@@ -1065,6 +1086,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
@@ -1076,25 +1140,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. */
@@ -1104,6 +1203,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
@@ -1120,10 +1226,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
@@ -1630,6 +1748,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.
@@ -1708,6 +1832,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).
@@ -1725,10 +1851,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`).
@@ -1791,6 +1920,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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "officeparser",
-  "version": "7.6.2",
+  "version": "7.8.0",
   "description": "A robust, strictly-typed Node.js and Browser library for parsing office files (.docx, .pptx, .xlsx, .odt, .odp, .ods, .pdf, .rtf, .csv, .md, .html, .epub) and generating high-fidelity outputs in Markdown, HTML, CSV, RTF, PDF, EPUB, and RAG-focused chunks.",
   "funding": "https://github.com/sponsors/harshankur",
   "main": "dist/index.js",