docx-kit 0.0.0 → 0.2.0

package/dist/node.d.mts

@@ -0,0 +1,1817 @@
+import { AlignmentType, Document } from "docx";
+import { EChartsOption } from "echarts";
+
+//#region src/types/utility.d.ts
+/** Hexadecimal CSS color string, e.g. `"#ff0000"`. */
+type HexColor = `#${string}`;
+/**
+ * A literal union type that still allows arbitrary string values.
+ * Useful for autocomplete-friendly APIs with extensible values.
+ *
+ * @template T — The literal subtype (e.g. `'Arial' | 'Calibri'`)
+ * @template U — The base type, defaults to `string`
+ */
+type LiteralUnion<T extends U, U = string> = T | (U & {});
+/**
+ * A value that might be synchronous or wrapped in a Promise.
+ *
+ * @template T — The inner value type
+ */
+type MaybePromise<T> = Promise<T> | T;
+/**
+ * CSS-like length value.
+ *
+ * Supports bare numbers, and explicit unit strings:
+ * `%`, `cm`, `in`, `mm`, `pt`, `px`.
+ *
+ * Bare-number conventions vary by context:
+ * - `fontSize` → interpreted as `pt`
+ * - spacing / indent → interpreted as `pt`
+ * - image size → interpreted as `px`
+ */
+type UnitValue = `${number}%` | `${number}cm` | `${number}in` | `${number}mm` | `${number}pt` | `${number}px` | number;
+//#endregion
+//#region src/types/style.d.ts
+/**
+ * A single border side descriptor.
+ *
+ * Follows the CSS `border` shorthand convention (style, width, color).
+ */
+interface BorderRule {
+  /** Border color (e.g. `"#333"` or named color). */
+  color?: string | HexColor;
+  /** Line style. */
+  style?: BorderStyle;
+  /** Line width (bare number treated as pt). */
+  width?: UnitValue;
+}
+/** Available border line styles. */
+type BorderStyle = 'dashed' | 'dotted' | 'double' | 'none' | 'single';
+/**
+ * CSS-like style descriptor for a run, paragraph, cell, or table.
+ *
+ * Keys mirror familiar CSS property names. Unknown properties that don't
+ * map to Word XML are silently ignored.
+ */
+interface DocxStyleRule {
+  /** Force text to uppercase (small caps-like). */
+  allCaps?: boolean;
+  /** Background / shading color. */
+  backgroundColor?: string | HexColor;
+  /** Shorthand border for all four sides. */
+  border?: BorderRule;
+  /** Bottom border override. */
+  borderBottom?: BorderRule;
+  /** Left border override. */
+  borderLeft?: BorderRule;
+  /** Right border override. */
+  borderRight?: BorderRule;
+  /** Top border override. */
+  borderTop?: BorderRule;
+  /** Character spacing (letter-spacing). */
+  characterSpacing?: number;
+  /** Text / foreground color. */
+  color?: string | HexColor;
+  /**
+   * Direct passthrough to the underlying `docx` library constructor options.
+   * Use for properties not yet covered by the CSS-like mapping.
+   */
+  docx?: Record<string, unknown>;
+  /** Font family name. */
+  fontFamily?: LiteralUnion<'Arial' | 'Calibri' | 'Times New Roman'>;
+  /** Font size (bare number = pt). */
+  fontSize?: UnitValue;
+  /** Italic toggle. */
+  fontStyle?: 'italic' | 'normal';
+  /** Font weight: keyword `"bold"` / `"normal"` or numeric 100–900. */
+  fontWeight?: FontWeight;
+  /** Element height. */
+  height?: UnitValue;
+  /** Text highlight color (background marker). */
+  highlight?: HighlightColor;
+  /** Keep lines together on same page. */
+  keepLines?: boolean;
+  /** Keep this paragraph with the next one. */
+  keepNext?: boolean;
+  /** Character spacing. */
+  letterSpacing?: UnitValue;
+  /** Line height multiplier or explicit unit value. */
+  lineHeight?: number | UnitValue;
+  /** Bottom margin. */
+  marginBottom?: UnitValue;
+  /** Left margin. */
+  marginLeft?: UnitValue;
+  /** Right margin. */
+  marginRight?: UnitValue;
+  /** Top margin. */
+  marginTop?: UnitValue;
+  /** Force page break before this paragraph. */
+  pageBreakBefore?: boolean;
+  /** Small caps text variant. */
+  smallCaps?: boolean;
+  /** Strikethrough toggle. */
+  strike?: boolean;
+  /** Sub-script text. */
+  subScript?: boolean;
+  /** Super-script text. */
+  superScript?: boolean;
+  /** Horizontal text alignment. */
+  textAlign?: TextAlign;
+  /** First-line indent. */
+  textIndent?: UnitValue;
+  /** Underline style. */
+  underline?: 'double' | 'single' | boolean;
+  /** Vertical alignment (mostly for table cells). */
+  verticalAlign?: VerticalAlign;
+  /** Element width. */
+  width?: UnitValue;
+  /**
+   * CSS-like margin shorthand.
+   *
+   * Supports 1-value, 2-value, and 4-value string syntax
+   * (e.g. `"10pt"`, `"10pt 20pt"`, `"10pt 20pt 30pt 40pt"`).
+   */
+  margin?: `${string} ${string}` | `${string} ${string} ${string} ${string}` | UnitValue;
+  /**
+   * CSS-like padding shorthand (same syntax as margin).
+   */
+  padding?: `${string} ${string}` | `${string} ${string} ${string} ${string}` | UnitValue;
+}
+/**
+ * Font weight: keyword `"bold"` / `"normal"`, or numeric 100–900
+ * following the CSS `font-weight` spec.
+ */
+type FontWeight = 'bold' | 'normal' | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+/** Text highlight / marker colors (matches Word highlight palette). */
+type HighlightColor = 'black' | 'blue' | 'cyan' | 'darkBlue' | 'darkCyan' | 'darkGray' | 'darkGreen' | 'darkMagenta' | 'darkRed' | 'darkYellow' | 'green' | 'lightGray' | 'magenta' | 'none' | 'red' | 'white' | 'yellow';
+/**
+ * A map of class name → style rule.
+ *
+ * Used to define reusable named styles referenced via `className` on nodes.
+ *
+ * @example
+ * ```ts
+ * const styles = defineStyles({
+ *   red:  { color: '#ff0000' },
+ *   big:  { fontSize: 20 },
+ * })
+ * ```
+ */
+type StyleSheet = Record<string, DocxStyleRule>;
+/** Horizontal text alignment. */
+type TextAlign = 'center' | 'justify' | 'left' | 'right';
+/** Vertical alignment (for table cells). */
+type VerticalAlign = 'bottom' | 'middle' | 'top';
+/**
+ * Define a type-safe stylesheet.
+ *
+ * `fontSize` defaults to pt when passed as a bare number.
+ *
+ * @param styles - — The stylesheet object
+ * @returns The same stylesheet with `const` type inference
+ *
+ * @example
+ * ```ts
+ * const styles = defineStyles({
+ *   title: { fontSize: 28, fontWeight: 'bold' },
+ *   body:  { fontSize: 12, lineHeight: 1.5 },
+ * })
+ * ```
+ */
+declare function defineStyles<const T extends StyleSheet>(styles: T): T;
+//#endregion
+//#region src/types/document.d.ts
+/**
+ * Top-level configuration passed to `createDocx()`.
+ *
+ * Covers page setup, stylesheet, theme tokens, element defaults,
+ * and document metadata.
+ *
+ * @template TStyles — The user's stylesheet type (inferred from `styles`).
+ */
+interface DocxKitConfig<TStyles extends StyleSheet = StyleSheet> {
+  /** Page dimensions and margins. */
+  page?: PageConfig;
+  /** Named style classes (class → style rule map). */
+  styles?: TStyles;
+  /** Semantic design tokens for theming. */
+  theme?: DocxTheme;
+  /** Default styles applied as base for each element type. */
+  defaults?: {
+    /** Default table cell style. */cell?: DocxStyleRule; /** Default image style (applied to the paragraph wrapping the image). */
+    image?: DocxStyleRule; /** Default paragraph style. */
+    paragraph?: DocxStyleRule; /** Default table style. */
+    table?: DocxStyleRule; /** Default text run style. */
+    text?: DocxStyleRule;
+  };
+  /** OOXML core properties (appear in File → Info). */
+  metadata?: {
+    /** Document author. */creator?: string; /** Document description / summary. */
+    description?: string; /** Keywords / tags. */
+    keywords?: string[]; /** Last editor. */
+    lastModifiedBy?: string; /** Document subject. */
+    subject?: string; /** Document title. */
+    title?: string;
+  };
+}
+/**
+ * Theme tokens that can be referenced in styles.
+ *
+ * Allows defining a single source of truth for colors, fonts,
+ * font sizes, and spacing values.
+ */
+interface DocxTheme {
+  /** Color palette (name → hex). */
+  colors?: Record<string, string>;
+  /** Font family tokens (name → font family). */
+  fontFamily?: Record<string, string>;
+  /** Font size tokens (name → value). */
+  fontSize?: Record<string, UnitValue>;
+  /** Spacing tokens (name → value). */
+  spacing?: Record<string, UnitValue>;
+}
+/**
+ * Header/footer configuration for a section.
+ *
+ * Supports standard, first-page, and even-page variants.
+ *
+ * @example
+ * ```ts
+ * {
+ *   default: { children: ['Chapter 1'] },
+ *   first: { children: ['Title Page'] },
+ * }
+ * ```
+ */
+interface HeaderFooterConfig {
+  /** Default header/footer (appears on all pages). */
+  default?: HeaderFooterContent;
+  /** Even-page header/footer (overrides default on even pages). */
+  even?: HeaderFooterContent;
+  /** First-page-only header/footer (overrides default on page 1). */
+  first?: HeaderFooterContent;
+}
+/**
+ * Content for a header or footer — a list of text strings.
+ *
+ * Each string maps to a `Paragraph` in the compiled .docx output.
+ * Future versions may support richer content (tables, images, page numbers).
+ *
+ * @example
+ * ```ts
+ * { default: ['Company Name', 'Confidential'] }
+ * ```
+ */
+interface HeaderFooterContent {
+  /** Paragraph text lines. */
+  children: string[];
+}
+/** Page orientation. */
+type Orientation = 'landscape' | 'portrait';
+/**
+ * Page configuration (size, orientation, margin).
+ */
+interface PageConfig {
+  /** Page orientation (`"portrait"` default). */
+  orientation?: Orientation;
+  /** Page size: preset name or explicit dimensions. */
+  size?: PageSize | {
+    height: UnitValue;
+    width: UnitValue;
+  };
+  /**
+   * Page margin.
+   *
+   * Supports 1-value, 2-value, and 4-value shorthand
+   * (e.g. `"20mm"`, `"20mm 15mm"`, `"20mm 15mm 25mm 15mm"`).
+   */
+  margin?: `${string} ${string}` | `${string} ${string} ${string} ${string}` | UnitValue;
+}
+/** Available page size presets. */
+type PageSize = 'A3' | 'A4' | 'Legal' | 'Letter';
+/**
+ * Per-section configuration.
+ *
+ * Each call to `.section(config)` starts a new document section, which
+ * can have its own page setup, headers, and footers independent of other
+ * sections.
+ *
+ * @example
+ * ```ts
+ * doc.section({
+ *   page: { size: 'A3', orientation: 'landscape' },
+ *   header: { default: { children: ['Wide Page'] } },
+ * })
+ * ```
+ */
+interface SectionConfig {
+  /** Section footer(s). */
+  footer?: HeaderFooterConfig;
+  /** Section header(s). */
+  header?: HeaderFooterConfig;
+  /** Section-specific page dimensions (overrides document-level `page`). */
+  page?: PageConfig;
+}
+//#endregion
+//#region src/dsl/nodes.d.ts
+/**
+ * Common properties shared by all nodes.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface BaseNode<TStyles extends StyleSheet = StyleSheet> {
+  /**
+   * CSS-like class name(s) referencing stylesheet entries.
+   *
+   * Can be a single string, an array, or a space-separated string.
+   */
+  className?: string | ClassName<TStyles> | ClassName<TStyles>[];
+  /** Optional unique identifier (for templating / references). */
+  id?: string;
+  /** Inline style override for this specific node. */
+  style?: DocxStyleRule;
+}
+/**
+ * Union of all top-level content node types.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+type BlockNode<TStyles extends StyleSheet = StyleSheet> = BulletListNode<TStyles> | HeadingNode<TStyles> | HyperlinkNode<TStyles> | ImageNode<TStyles> | NumberedListNode<TStyles> | PageBreakNode | ParagraphNode<TStyles> | PluginNode<string, unknown, TStyles> | SectionBreakNode | TableNode<Record<string, unknown>, TStyles>;
+/**
+ * A structured list item (for rich bullet/numbered items).
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface BulletItem<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Item text content. */
+  text: string;
+  /** Optional inline children override (instead of text). */
+  children?: InlineNode<TStyles>[];
+}
+/**
+ * A bullet list node.
+ *
+ * Supports plain string items or structured items with children.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface BulletListNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** List items — strings or structured items. */
+  items: (string | BulletItem<TStyles>)[];
+  type: 'bulletList';
+  /** Bullet character / style. Default: `'•'`. */
+  bullet?: string;
+  /** Nested list level (0 = top-level). */
+  level?: number;
+}
+/**
+ * Extract valid class name keys from a stylesheet type.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+type ClassName<TStyles extends StyleSheet> = Extract<keyof TStyles, string>;
+/**
+ * A heading node (h1–h6).
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface HeadingNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Heading level (1 = largest, 6 = smallest). */
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Heading text content. */
+  text: string;
+  type: 'heading';
+}
+/**
+ * A hyperlink node (inline content that creates a clickable link).
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface HyperlinkNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Display text or inline children. */
+  children: (string | TextNode<TStyles>)[];
+  type: 'hyperlink';
+  /** Link target URL. */
+  url: string;
+}
+/**
+ * An image node.
+ *
+ * Supports raw bytes (`Uint8Array`, `ArrayBuffer`, `Blob`) or a file path string.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface ImageNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Image data as bytes, blob, or file path. */
+  data: string | ArrayBuffer | Blob | Uint8Array;
+  type: 'image';
+  /** Alt text for accessibility. */
+  alt?: string;
+  /** Display height. */
+  height?: UnitValue;
+  /** Image format hint. Auto-detected if omitted. */
+  imageType?: 'bmp' | 'gif' | 'jpeg' | 'jpg' | 'png';
+  /** Display width. */
+  width?: UnitValue;
+  /**
+   * Floating layout configuration.
+   *
+   * - `true` enables default floating
+   * - Object allows wrap mode and position offsets
+   */
+  floating?: boolean | {
+    /** Text wrap mode. */wrap?: 'square' | 'tight' | 'topAndBottom'; /** Horizontal offset. */
+    x?: UnitValue; /** Vertical offset. */
+    y?: UnitValue;
+  };
+}
+/**
+ * Union of inline content node types (appear inside paragraphs).
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+type InlineNode<TStyles extends StyleSheet = StyleSheet> = HyperlinkNode<TStyles> | ImageNode<TStyles> | TextNode<TStyles>;
+/**
+ * A numbered / ordered list node.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface NumberedListNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** List items. */
+  items: (string | BulletItem<TStyles>)[];
+  type: 'numberedList';
+  /** Nested list level (0 = top-level). */
+  level?: number;
+  /** Starting number (default: 1). */
+  start?: number;
+  /**
+   * Numbering format.
+   *
+   * {@link `LevelFormat.DECIMAL`} by default.
+   * e.g. `'decimal'`, `'upperRoman'`, `'lowerLetter'`
+   */
+  numberingFormat?: 'decimal' | 'lowerLetter' | 'lowerRoman' | 'upperLetter' | 'upperRoman';
+}
+/**
+ * A forced page break.
+ */
+interface PageBreakNode {
+  type: 'pageBreak';
+}
+/**
+ * A paragraph containing text and/or inline children.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface ParagraphNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  type: 'paragraph';
+  /** Inline children (text runs, inline images, etc.). */
+  children?: InlineNode<TStyles>[];
+  /** Plain-text content (used when `children` is not provided). */
+  text?: string;
+}
+/**
+ * A plugin-invocation node.
+ *
+ * Plugins extend the DSL with arbitrary content types.
+ *
+ * @template TName — Plugin name (string literal)
+ * @template TOptions — Plugin-specific options shape
+ * @template TStyles — The user's stylesheet type
+ */
+interface PluginNode<TName extends string = string, TOptions = unknown, TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Registered plugin name. */
+  name: TName;
+  /** Plugin-specific options. */
+  options: TOptions;
+  type: 'plugin';
+}
+/**
+ * Internal marker node that represents a section boundary.
+ *
+ * Created automatically by {@link DocxBuilder.section} — users should
+ * not create this node directly.
+ *
+ * When the compiler encounters this marker, it starts a new section
+ * with the provided configuration.
+ */
+interface SectionBreakNode {
+  type: 'sectionBreak';
+  /** Optional per-section page/header/footer overrides. */
+  config?: SectionConfig;
+}
+/**
+ * A column definition for a table.
+ *
+ * @template TData — The row data type
+ */
+interface TableColumn<TData extends Record<string, unknown> = Record<string, unknown>> {
+  /** Key in the data object this column maps to. */
+  key: Extract<keyof TData, string>;
+  /** Column header text. */
+  title: string;
+  /** Cell text alignment. */
+  align?: 'center' | 'left' | 'right';
+  /**
+   * Span multiple columns horizontally.
+   *
+   * Applied to all cells in this column.
+   */
+  colSpan?: number;
+  /**
+   * Span multiple rows vertically (per-cell via data hints).
+   *
+   * Set `rowSpan` on individual data objects using `_rowSpan: N` or keep it
+   * as a static column default.
+   */
+  rowSpan?: number;
+  /** Column width. Supports percentage strings (e.g. `"30%"`). */
+  width?: UnitValue;
+  /**
+   * Custom cell renderer.
+   *
+   * Receives the raw value, full row data, and row index.
+   * Returns a string or inline nodes.
+   */
+  render?: (value: TData[keyof TData], row: TData, index: number) => string | InlineNode[];
+}
+/**
+ * A table node with column definitions and data rows.
+ *
+ * @template TData — The row data type
+ * @template TStyles — The user's stylesheet type
+ */
+interface TableNode<TData extends Record<string, unknown> = Record<string, unknown>, TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Column definitions. */
+  columns: TableColumn<TData>[];
+  /** Row data objects. */
+  data: TData[];
+  type: 'table';
+  /** Show table borders. */
+  bordered?: boolean;
+  /** Default cell style for data rows. */
+  cellStyle?: DocxStyleRule;
+  /** Show header row (default: `true`). */
+  header?: boolean;
+  /** Style for header cells. */
+  headerCellStyle?: DocxStyleRule;
+  /** Alternate row shading. */
+  striped?: boolean;
+}
+/**
+ * A text run node (inline content).
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface TextNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Text content. */
+  text: string;
+  type: 'text';
+}
+//#endregion
+//#region src/types/plugin.d.ts
+/**
+ * A docx-kit plugin.
+ *
+ * Plugins have a unique `name`, an optional `setup` hook,
+ * and a required `render` function that receives user options
+ * and a rendering context.
+ *
+ * @template TName — The plugin name (string literal type)
+ * @template TOptions — The shape of the user-provided options
+ */
+interface DocxPlugin<TName extends string = string, TOptions = unknown> {
+  /** Unique plugin name, used as the node discriminator. */
+  name: TName;
+  /** One-time setup called when the plugin is registered. */
+  setup?: () => MaybePromise<void>;
+  /**
+   * Render plugin content into one or more `docx` objects
+   * (Paragraph, Table, etc.).
+   *
+   * @param options - — User-provided plugin options
+   * @param context - — Rendering context with helper utilities
+   */
+  render: (options: TOptions, context: PluginRenderContext) => MaybePromise<unknown>;
+}
+/**
+ * Type-level map of plugin name → options type.
+ *
+ * Constructed via `Builder.use()` chaining.
+ */
+type PluginRegistry = Record<string, unknown>;
+/**
+ * Rendering context passed to a plugin's `render()` function.
+ *
+ * Provides access to the document config, image utilities,
+ * and the ability to compile child nodes.
+ */
+interface PluginRenderContext {
+  /** The full document config. */
+  config: DocxKitConfig;
+  /** Compile a child node (useful for nesting). */
+  compileNode: (node: BlockNode) => Promise<unknown>;
+  /** Utility helpers. */
+  utils: {
+    image: {
+      /** Convert a Blob to raw image bytes. */fromBlob: (blob: Blob) => Promise<Uint8Array>;
+      /**
+       * Decode a base64 data-URL to raw image bytes.
+       * Works in both browser and Node.js environments.
+       */
+      fromDataUrl: (dataUrl: string) => MaybePromise<Uint8Array>;
+    };
+  };
+}
+/**
+ * Define a type-safe plugin with full inference.
+ *
+ * @param plugin - — The plugin definition object
+ * @returns The same plugin with `const` type inference
+ *
+ * @example
+ * ```ts
+ * const myPlugin = definePlugin<'badge', { text: string }>({
+ *   name: 'badge',
+ *   render: async (opts, ctx) => {
+ *     // ... render logic
+ *     return new Paragraph({ text: opts.text })
+ *   },
+ * })
+ * ```
+ */
+declare function definePlugin<const TName extends string, TOptions>(plugin: DocxPlugin<TName, TOptions>): DocxPlugin<TName, TOptions>;
+//#endregion
+//#region src/plugins/qrcode/index.d.ts
+/**
+ * QR Code plugin — embeds a QR code image in the document.
+ *
+ * Uses the `qrcode` package (peer dependency) to generate
+ * a QR code PNG and renders it as an inline `ImageRun`.
+ *
+ * @module plugins/qrcode
+ *
+ * @example
+ * ```ts
+ * const doc = createDocx()
+ *   .use(qrcodePlugin())
+ *   .h1('Scan Me')
+ *   .plugin('qrcode', { text: 'https://example.com', caption: 'Visit us' })
+ *   .save('qrcode.docx')
+ * ```
+ */
+/**
+ * Options for the QRCode plugin.
+ */
+interface QRCodePluginOptions {
+  /** The text / URL to encode. */
+  text: string;
+  /** Optional caption text displayed below the QR code. */
+  caption?: string;
+  /**
+   * QR error correction level.
+   *
+   * - `"L"` — ~7% recovery
+   * - `"M"` — ~15% recovery
+   * - `"Q"` — ~25% recovery
+   * - `"H"` — ~30% recovery
+   *
+   * @default "M"
+   */
+  errorCorrectionLevel?: 'H' | 'L' | 'M' | 'Q';
+  /** QR code margin (in modules). @default 1 */
+  margin?: number;
+  /** QR code image size in pixels. @default 128 */
+  size?: number;
+}
+/**
+ * Create a QRCode plugin instance.
+ *
+ * The plugin dynamically imports the `qrcode` package at render time,
+ * keeping it an optional peer dependency of docx-kit core.
+ *
+ * @returns A configured DocxPlugin for `'qrcode'`
+ *
+ * @example
+ * ```ts
+ * import { createDocx, qrcodePlugin } from 'docx-kit'
+ *
+ * const doc = createDocx()
+ *   .use(qrcodePlugin())
+ *   .plugin('qrcode', {
+ *     text: 'https://example.com',
+ *     size: 256,
+ *     errorCorrectionLevel: 'H',
+ *     caption: 'Scan to visit',
+ *   })
+ * ```
+ */
+declare function qrcodePlugin(): DocxPlugin<"qrcode", QRCodePluginOptions>;
+//#endregion
+//#region src/plugins/callout/index.d.ts
+/**
+ * Callout plugin — colored info / warning / success / danger boxes.
+ *
+ * Renders a single `Paragraph` with a prominent left border, a tinted
+ * background, an emoji icon, an optional bold title, and body text.
+ *
+ * @module plugins/callout
+ *
+ * @example
+ * ```ts
+ * const doc = createDocx()
+ *   .use(calloutPlugin())
+ *   .plugin('callout', {
+ *     type: 'warning',
+ *     title: '注意',
+ *     content: '此操作不可撤销，请确认后再提交。',
+ *   })
+ *   .save('callout.docx')
+ * ```
+ */
+/** Options for the Callout plugin. */
+interface CalloutOptions {
+  /** Body text of the callout. */
+  content: string;
+  /** Callout style — controls icon, color, and tone. */
+  type: 'danger' | 'info' | 'success' | 'warning';
+  /** Optional bold title line placed before the content. */
+  title?: string;
+}
+/**
+ * Create a Callout plugin instance.
+ *
+ * @returns A configured DocxPlugin for `'callout'`
+ *
+ * @example
+ * ```ts
+ * import { createDocx, calloutPlugin } from 'docx-kit'
+ *
+ * const doc = createDocx()
+ *   .use(calloutPlugin())
+ *   .plugin('callout', { type: 'info', content: '系统将在今晚 22:00 升级。' })
+ * ```
+ */
+declare function calloutPlugin(): DocxPlugin<"callout", CalloutOptions>;
+//#endregion
+//#region src/plugins/echarts/index.d.ts
+/**
+ * Options for the ECharts plugin.
+ */
+interface EChartsPluginOptions {
+  /** Full ECharts option object (series, axes, title, etc.). */
+  option: EChartsOption;
+  /** Optional caption text displayed below the chart. */
+  caption?: string;
+  /** Chart height in pixels. @default 360 */
+  height?: number;
+  /** Output image format. @default "png" */
+  imageType?: 'png' | 'svg';
+  /** ECharts rendering engine. @default "canvas" */
+  renderer?: 'canvas' | 'svg';
+  /** Chart width in pixels. @default 640 */
+  width?: number;
+}
+//#endregion
+//#region src/builder/DocxBuilder.d.ts
+/**
+ * Fluent document builder.
+ *
+ * Use `createDocx()` to instantiate, then chain `.h1()`, `.p()`, `.table()`,
+ * etc. to build content. Call `.save()`, `.toBlob()`, `.toBuffer()`, or
+ * `.toBase64()` to export the document.
+ *
+ * @template TStyles — Inferred stylesheet type from `config.styles`
+ * @template TPlugins — Accumulated plugin registry (built via `.use()`)
+ */
+declare class DocxBuilder<TStyles extends StyleSheet = StyleSheet, TPlugins extends PluginRegistry = Record<never, never>> {
+  private readonly config;
+  private readonly nodes;
+  private readonly pendingSetups;
+  private readonly pluginMap;
+  constructor(config?: DocxKitConfig<TStyles>);
+  /**
+   * Add a raw DSL node to the document.
+   *
+   * @param node - — Any block-level node
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.add({ type: 'heading', level: 2, text: 'Section' })
+   * doc.add({ type: 'pageBreak' })
+   * ```
+   */
+  add(node: BlockNode<TStyles>): this;
+  /**
+   * Add a bullet (unordered) list.
+   *
+   * @param items - — List items (strings or structured items)
+   * @param options - — Optional bullet character, className, style, level
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.bulletList(['Item 1', 'Item 2', 'Item 3'])
+   * doc.bulletList([
+   *   'Simple item',
+   *   { text: 'Rich item', className: 'highlight' },
+   * ], { bullet: '\u25CB' })
+   * ```
+   */
+  bulletList(items: (string | BulletItem<TStyles>)[], options?: Omit<Partial<BulletListNode<TStyles>>, 'items' | 'type'>): this;
+  /**
+   * Add a level-1 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides (className, id, style)
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.h1('Introduction', { className: 'title' })
+   * ```
+   */
+  h1(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a level-2 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   */
+  h2(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a level-3 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   */
+  h3(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a level-4 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   */
+  h4(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a level-5 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   */
+  h5(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a level-6 heading.
+   *
+   * @param text - — Heading text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   */
+  h6(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
+  /**
+   * Add a hyperlink.
+   *
+   * @param url - — Target URL
+   * @param text - — Display text
+   * @param options - — Optional style overrides
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.hyperlink('https://example.com', 'Click here')
+   * ```
+   */
+  hyperlink(url: string, text: string, options?: Omit<Partial<HyperlinkNode<TStyles>>, 'children' | 'type' | 'url'>): this;
+  /**
+   * Add an image node.
+   *
+   * @param options - — Image node options (data, width, height, etc.)
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.image({ data: imageBytes, width: 400, height: 300 })
+   * ```
+   */
+  image(options: Omit<ImageNode<TStyles>, 'type'>): this;
+  /**
+   * Add a numbered (ordered) list.
+   *
+   * @param items - — List items
+   * @param options - — Optional numbering format, start, className, style, level
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.numberedList(['First', 'Second', 'Third'])
+   * doc.numberedList(
+   *   [{ text: 'Intro' }, { text: 'Body' }],
+   *   { numberingFormat: 'upperRoman', start: 1 },
+   * )
+   * ```
+   */
+  numberedList(items: (string | BulletItem<TStyles>)[], options?: Omit<Partial<NumberedListNode<TStyles>>, 'items' | 'type'>): this;
+  /**
+   * Add a paragraph.
+   *
+   * @param text - — Paragraph text content
+   * @param options - — Optional style overrides (className, id, style)
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.p('Hello world', { className: 'body', style: { textAlign: 'center' } })
+   * ```
+   */
+  p(text: string, options?: Omit<Partial<ParagraphNode<TStyles>>, 'text' | 'type'>): this;
+  /**
+   * Add a forced page break.
+   *
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.h1('Chapter 1').pageBreak().h1('Chapter 2')
+   * ```
+   */
+  pageBreak(): this;
+  /**
+   * Invoke a registered plugin.
+   *
+   * @param name - — Plugin name (must match a previously registered plugin)
+   * @param options - — Plugin-specific options
+   * @param style - — Optional inline style for the plugin's container
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.use(qrcodePlugin()).plugin('qrcode', { text: 'https://example.com' })
+   * ```
+   */
+  plugin<TName extends string & keyof TPlugins>(name: TName, options: TPlugins[TName], style?: DocxStyleRule): this;
+  /**
+   * Save the document to a file (Node.js only).
+   *
+   * **⚠️ Not available in browser environments.**
+   * Use {@link toBlob} and trigger a download instead.
+   *
+   * @param filename - — Output file path (e.g. `"report.docx"`)
+   *
+   * @example
+   * ```ts
+   * await doc.save('output.docx')
+   * ```
+   */
+  save(filename: string): Promise<void>;
+  /**
+   * Start a new document section.
+   *
+   * Each section can have its own page size, orientation, margins,
+   * headers, and footers. Content added after this call belongs to
+   * the new section.
+   *
+   * @param config - — Optional section-level page/header/footer overrides
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * // Simple section break
+   * doc.p('Section 1 content').section().p('Section 2 content')
+   *
+   * // Section with custom page setup
+   * doc.section({ page: { size: 'A3', orientation: 'landscape' } })
+   *    .h1('Wide table')
+   *    .table({ columns: [...], data: [...] })
+   *
+   * // Section with header and footer
+   * doc.section({
+   *   header: { default: { children: ['Chapter 2', 'Confidential'] } },
+   *   footer: { default: { children: ['Page 2'] } },
+   * })
+   * ```
+   */
+  section(config?: SectionConfig): this;
+  /**
+   * Add a table.
+   *
+   * @param options - — Table node options (columns, data, style, etc.)
+   * @returns The builder (for chaining)
+   *
+   * @example
+   * ```ts
+   * doc.table({
+   *   columns: [
+   *     { key: 'name', title: 'Name' },
+   *     { key: 'value', title: 'Value', align: 'right' },
+   *   ],
+   *   data: [{ name: 'Revenue', value: '$1.2M' }],
+   *   headerCellStyle: { fontWeight: 'bold' },
+   * })
+   * ```
+   */
+  table<TData extends Record<string, unknown>>(options: Omit<TableNode<TData, TStyles>, 'type'>): this;
+  /**
+   * Export the document as a base64-encoded string.
+   *
+   * @returns Base64-encoded .docx data
+   *
+   * @example
+   * ```ts
+   * const b64 = await doc.toBase64()
+   * // Send b64 over HTTP or store in a database
+   * ```
+   */
+  toBase64(): Promise<string>;
+  /**
+   * Export the document as a `Blob` (browser-friendly).
+   *
+   * @returns A `Blob` containing the .docx binary
+   *
+   * @example
+   * ```ts
+   * const blob = await doc.toBlob()
+   * const url = URL.createObjectURL(blob)
+   * ```
+   */
+  toBlob(): Promise<Blob>;
+  /**
+   * Export the document as a `Uint8Array` (alias for {@link toUint8Array}).
+   *
+   * **Note:** Despite the name, this returns a standard `Uint8Array`,
+   * not a Node.js `Buffer`. Prefer using {@link toUint8Array} for clarity.
+   *
+   * @returns Raw .docx bytes
+   *
+   * @example
+   * ```ts
+   * const bytes = await doc.toBuffer()
+   * fs.writeFileSync('output.docx', bytes)
+   * ```
+   */
+  toBuffer(): Promise<Uint8Array>;
+  /**
+   * Compile and return the internal `docx` {@link Document} instance.
+   *
+   * Useful if you need to further manipulate the document with the
+   * raw `docx` library before packaging.
+   *
+   * @returns A `docx` `Document` object
+   */
+  toDocument(): Promise<import("docx").Document>;
+  /**
+   * Serialize the builder state to a JSON-friendly object.
+   *
+   * Useful for debugging, serialization, or AI-driven document generation.
+   *
+   * @returns The config + content node array as a plain object
+   */
+  toJSON(): {
+    content: BlockNode<TStyles>[];
+    page?: PageConfig;
+    styles?: TStyles | undefined;
+    theme?: DocxTheme;
+    defaults?: {
+      cell?: DocxStyleRule;
+      image?: DocxStyleRule;
+      paragraph?: DocxStyleRule;
+      table?: DocxStyleRule;
+      text?: DocxStyleRule;
+    };
+    metadata?: {
+      creator?: string;
+      description?: string;
+      keywords?: string[];
+      lastModifiedBy?: string;
+      subject?: string;
+      title?: string;
+    };
+  };
+  /**
+   * Export the document as a `Uint8Array` (browser & Node.js).
+   *
+   * This is the preferred cross-platform export method.
+   *
+   * @returns Raw .docx bytes
+   *
+   * @example
+   * ```ts
+   * const bytes = await doc.toUint8Array()
+   * // In Node.js: import { writeFileSync } from 'node:fs'
+   * // In browser: trigger a download
+   * ```
+   */
+  toUint8Array(): Promise<Uint8Array>;
+  /**
+   * Register a plugin.
+   *
+   * The plugin's name and options type are accumulated into the builder's
+   * type-level plugin registry, enabling type-safe `.plugin()` calls.
+   *
+   * @param plugin - — The plugin definition returned by `definePlugin()`
+   * @returns The builder with the plugin type merged into `TPlugins`
+   *
+   * @example
+   * ```ts
+   * const doc = createDocx()
+   *   .use(qrcodePlugin())
+   *   .plugin('qrcode', { text: 'https://example.com' })
+   * ```
+   */
+  use<TName extends string, TOptions>(plugin: DocxPlugin<TName, TOptions>): DocxBuilder<TStyles, Record<TName, TOptions> & TPlugins>;
+}
+//#endregion
+//#region src/plugins/timeline/index.d.ts
+/**
+ * Timeline plugin — renders a chronological timeline as a styled table.
+ *
+ * Each event occupies one table row: a date cell, a visual connector
+ * cell, and a content cell (title + optional description).
+ *
+ * @module plugins/timeline
+ *
+ * @example
+ * ```ts
+ * const doc = createDocx()
+ *   .use(timelinePlugin())
+ *   .plugin('timeline', {
+ *     events: [
+ *       { date: '2026-01', title: '项目立项', description: '完成需求评审' },
+ *       { date: '2026-03', title: 'MVP 发布', description: '核心功能上线' },
+ *     ],
+ *   })
+ *   .save('timeline.docx')
+ * ```
+ */
+/** A single timeline event. */
+interface TimelineEvent {
+  /** Date / time label (e.g. "2026-06" or "Q3"). */
+  date: string;
+  /** Short event title. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+}
+/** Options for the Timeline plugin. */
+interface TimelineOptions {
+  /** Array of timeline events in chronological order. */
+  events: TimelineEvent[];
+  /**
+   * Accent color for the connector line and date highlight.
+   * @default '4472C4'
+   */
+  accentColor?: string;
+  /**
+   * Layout style.
+   *
+   * - `'alternating'` — dates alternate left / right (default)
+   * - `'left'` — all dates on the left, content on the right
+   * - `'right'` — all content on the left, dates on the right
+   *
+   * @default 'alternating'
+   */
+  layout?: 'alternating' | 'left' | 'right';
+}
+/**
+ * Create a Timeline plugin instance.
+ *
+ * @returns A configured DocxPlugin for `'timeline'`
+ *
+ * @example
+ * ```ts
+ * import { createDocx, timelinePlugin } from 'docx-kit'
+ *
+ * const doc = createDocx()
+ *   .use(timelinePlugin())
+ *   .plugin('timeline', {
+ *     events: [
+ *       { date: '2026-01', title: '项目启动', description: '团队组建完成' },
+ *       { date: '2026-04', title: 'Beta 测试', description: '收集用户反馈' },
+ *       { date: '2026-06', title: '正式发布' },
+ *     ],
+ *   })
+ * ```
+ */
+declare function timelinePlugin(): DocxPlugin<"timeline", TimelineOptions>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error handling types and classes for docx-kit.
+ *
+ * @module errors
+ */
+/**
+ * Well-known error codes used throughout the library.
+ *
+ * Consumers can match against these codes for structured error handling.
+ */
+declare const ERROR_CODES: {
+  /** Document export failed. */readonly EXPORT_FAILED: "EXPORT_FAILED"; /** Image data is empty, corrupt, or unsupported. */
+  readonly IMAGE_INVALID_DATA: "IMAGE_INVALID_DATA"; /** A plugin node referenced an unregistered plugin. */
+  readonly PLUGIN_NOT_REGISTERED: "PLUGIN_NOT_REGISTERED"; /** A plugin's `render()` method threw an error. */
+  readonly PLUGIN_RENDER_FAILED: "PLUGIN_RENDER_FAILED"; /** A `className` referenced a stylesheet key that doesn't exist. */
+  readonly STYLE_UNKNOWN_CLASS: "STYLE_UNKNOWN_CLASS"; /** Table was created with no columns. */
+  readonly TABLE_INVALID_COLUMNS: "TABLE_INVALID_COLUMNS"; /** Encountered a node type that has no registered compiler. */
+  readonly UNKNOWN_NODE_TYPE: "UNKNOWN_NODE_TYPE";
+};
+/** Union type of all known error codes. */
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * Structured error class for docx-kit.
+ *
+ * Carries a machine-readable `code`, a human-readable `message`,
+ * and optionally the underlying `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await doc.save('output.docx')
+ * } catch (err) {
+ *   if (err instanceof DocxKitError && err.code === ERROR_CODES.EXPORT_FAILED) {
+ *     console.error('Export failed:', err.message)
+ *   }
+ * }
+ * ```
+ */
+declare class DocxKitError extends Error {
+  /** The underlying error that caused this failure (if any). */
+  readonly cause: unknown;
+  /** Machine-readable error code. */
+  readonly code: string | ErrorCode;
+  /**
+   * @param code - — Known error code from {@link ERROR_CODES}
+   * @param message - — Human-readable description
+   * @param cause - — Optional underlying error
+   */
+  constructor(code: string | ErrorCode, message: string, cause?: unknown);
+}
+//#endregion
+//#region src/plugins/watermark/index.d.ts
+/** Options for the Watermark plugin. */
+interface WatermarkOptions {
+  /** Watermark text. */
+  text: string;
+  /**
+   * Horizontal alignment.
+   * @default 'center'
+   */
+  alignment?: (typeof AlignmentType)[keyof typeof AlignmentType];
+  /**
+   * Text color in hex RRGGBB.
+   * @default 'BFBFBF'
+   */
+  color?: string;
+  /**
+   * Font size in half-points (20 = 10pt).
+   * @default 48
+   */
+  fontSize?: number;
+}
+/**
+ * Create a Watermark plugin instance.
+ *
+ * @returns A configured DocxPlugin for `'watermark'`
+ *
+ * @example
+ * ```ts
+ * import { createDocx, watermarkPlugin } from 'docx-kit'
+ *
+ * const doc = createDocx()
+ *   .use(watermarkPlugin())
+ *   .plugin('watermark', { text: 'DRAFT', color: 'FF0000' })
+ * ```
+ */
+declare function watermarkPlugin(): DocxPlugin<"watermark", WatermarkOptions>;
+//#endregion
+//#region src/plugins/code-block/index.d.ts
+/**
+ * Code Block plugin — renders source code with monospaced font and
+ * optional line numbers and syntax highlighting.
+ *
+ * Syntax highlighting requires `highlight.js` as an optional peer dependency.
+ * When unavailable (or when `language` is not provided), the plugin falls
+ * back to plain monospaced rendering.
+ *
+ * @module plugins/code-block
+ *
+ * @example
+ * ```ts
+ * const doc = createDocx()
+ *   .use(codeBlockPlugin())
+ *   .plugin('codeBlock', {
+ *     code: `export function hello() {\n  return "world"\n}`,
+ *     language: 'typescript',
+ *     showLineNumbers: true,
+ *   })
+ *   .save('code.docx')
+ * ```
+ */
+/** Options for the CodeBlock plugin. */
+interface CodeBlockOptions {
+  /** Source code string. */
+  code: string;
+  /**
+   * Language identifier for syntax highlighting (optional).
+   *
+   * Requires `highlight.js` as a peer dependency.  Falls back
+   * to monospaced rendering when the package is not installed.
+   */
+  language?: string;
+  /** Prepend line numbers. @default false */
+  showLineNumbers?: boolean;
+}
+/**
+ * Create a CodeBlock plugin instance.
+ *
+ * @returns A configured DocxPlugin for `'codeBlock'`
+ */
+declare function codeBlockPlugin(): DocxPlugin<"codeBlock", CodeBlockOptions>;
+//#endregion
+//#region src/plugins/cover-page/index.d.ts
+/** Options for the Cover Page plugin. */
+interface CoverPageOptions {
+  /** Main title text (required). */
+  title: string;
+  /** Horizontal text alignment. @default CENTER */
+  alignment?: (typeof AlignmentType)[keyof typeof AlignmentType];
+  /** Author or department name. */
+  author?: string;
+  /** Background color of the cover page in hex RRGGBB. */
+  backgroundColor?: string;
+  /** Date string (e.g. "2026-06-11"). */
+  date?: string;
+  /** Organization / company name. */
+  organization?: string;
+  /**
+   * Show a decorative horizontal rule between title and author.
+   * @default true
+   */
+  showRule?: boolean;
+  /** Sub-title text displayed below the title. */
+  subtitle?: string;
+}
+/**
+ * Create a Cover Page plugin instance.
+ *
+ * @returns A configured DocxPlugin for `'coverPage'`
+ *
+ * @example
+ * ```ts
+ * import { coverPagePlugin, createDocx } from 'docx-kit'
+ *
+ * const doc = createDocx()
+ *   .use(coverPagePlugin())
+ *   .plugin('coverPage', {
+ *     title: '年度报告',
+ *     subtitle: '2026',
+ *     author: '战略发展部',
+ *     organization: 'XX 科技集团',
+ *   })
+ * ```
+ */
+declare function coverPagePlugin(): DocxPlugin<"coverPage", CoverPageOptions>;
+//#endregion
+//#region src/plugins/data-table/index.d.ts
+/**
+ * Data Table plugin — renders an array of objects as a styled table.
+ *
+ * Columns are auto-inferred from the first object’s keys.  Column headers
+ * can be localised via `labels`, value formatting is controlled by `format`,
+ * and per-column alignment is controlled by `align`.
+ *
+ * @module plugins/data-table
+ *
+ * @example
+ * ```ts
+ * const doc = createDocx()
+ *   .use(dataTablePlugin())
+ *   .plugin('dataTable', {
+ *     data: [
+ *       { name: 'Alice', age: 30, salary: 85000 },
+ *       { name: 'Bob',   age: 25, salary: 62000 },
+ *     ],
+ *     labels: { name: '姓名', age: '年龄', salary: '薪资' },
+ *     format: { salary: 'currency' },
+ *     striped: true,
+ *   })
+ *   .save('table.docx')
+ * ```
+ */
+/** Per-column alignment hint. */
+type ColAlign = 'center' | 'left' | 'right';
+/** Value formatter identifier. */
+type ColFormat = 'currency' | 'date' | 'number' | 'percent';
+/** Options for the DataTable plugin. */
+interface DataTableOptions {
+  /**
+   * The data to render — each object is one row.
+   *
+   * Column keys are taken from the first object in the array.
+   */
+  data: Record<string, unknown>[];
+  /** Per-column alignment. Auto-detected from value types when omitted. */
+  align?: Record<string, ColAlign>;
+  /** Render visible table borders. @default true */
+  bordered?: boolean;
+  /** Per-column value formatter. */
+  format?: Record<string, ColFormat>;
+  /** Human-readable column labels (e.g. `{ salary: '薪资' }`). */
+  labels?: Record<string, string>;
+  /** Alternate row background shading. @default false */
+  striped?: boolean;
+}
+/**
+ * Create a DataTable plugin instance.
+ *
+ * @returns A configured DocxPlugin for `'dataTable'`
+ */
+declare function dataTablePlugin(): DocxPlugin<"dataTable", DataTableOptions>;
+//#endregion
+//#region src/plugins/page-number/index.d.ts
+/** Options for the Page Number plugin. */
+interface PageNumberOptions {
+  /**
+   * Horizontal alignment of the page number.
+   * @default 'center'
+   */
+  alignment?: (typeof AlignmentType)[keyof typeof AlignmentType];
+  /**
+   * Font size in half-points.
+   * @default 20
+   */
+  fontSize?: number;
+  /**
+   * Show "Page X of Y" instead of just "X".
+   * @default false
+   */
+  showTotal?: boolean;
+}
+/**
+ * Create a Page Number plugin instance.
+ *
+ * @returns A configured DocxPlugin for `'pageNumber'`
+ *
+ * @example
+ * ```ts
+ * import { createDocx, pageNumberPlugin } from 'docx-kit'
+ *
+ * const doc = createDocx()
+ *   .use(pageNumberPlugin())
+ *   // Use the page number content in a footer
+ *   const pn = doc.plugin('pageNumber', { alignment: 'center' })
+ * ```
+ */
+declare function pageNumberPlugin(): DocxPlugin<"pageNumber", PageNumberOptions>;
+//#endregion
+//#region src/builder/createDocx.d.ts
+/**
+ * JSON schema for `renderDocx()`.
+ *
+ * The schema is deliberately simple — a flat config object plus an
+ * ordered array of block nodes. This makes it easy to generate from
+ * AI / LLMs or store as JSON.
+ *
+ * @template TStyles — The user's stylesheet type
+ */
+interface DocxSchema<TStyles extends StyleSheet = StyleSheet> {
+  /** Ordered array of block nodes. */
+  content: BlockNode<TStyles>[];
+  /** Optional page configuration. */
+  page?: DocxKitConfig<TStyles>['page'];
+  /** Named stylesheet entries. */
+  styles?: TStyles;
+}
+/**
+ * Create a new DocxBuilder with optional configuration.
+ *
+ * This is the primary entry point for the fluent builder API.
+ * Chain `.h1()`, `.p()`, `.table()`, etc. and call `.save()`
+ * or `.toBlob()` to export.
+ *
+ * @param config - — Document configuration (page, styles, metadata, theme, defaults)
+ * @returns A new `DocxBuilder` instance
+ *
+ * @example
+ * ```ts
+ * const styles = defineStyles({
+ *   title: { fontSize: 28, fontWeight: 'bold' },
+ *   body:  { fontSize: 12, lineHeight: 1.5 },
+ * })
+ *
+ * const doc = createDocx({
+ *   styles,
+ *   page: { size: 'A4', margin: '20mm' },
+ *   metadata: { title: 'Report', creator: 'docx-kit' },
+ * })
+ *
+ * await doc
+ *   .h1('Annual Report', { className: 'title' })
+ *   .p('Lorem ipsum...', { className: 'body' })
+ *   .save('report.docx')
+ * ```
+ */
+declare function createDocx<const TStyles extends StyleSheet = StyleSheet>(config?: DocxKitConfig<TStyles>): DocxBuilder<TStyles, Record<never, never>>;
+/**
+ * Render a document from a JSON schema (AI-friendly / serializable DSL).
+ *
+ * Unlike `createDocx()`, this accepts a single JSON-serializable object
+ * with `content` (node array), optional `styles`, and optional `page` config.
+ * Ideal for AI-driven document generation or API integrations.
+ *
+ * @param schema - — The `DocxSchema` object
+ * @returns A `DocxBuilder` instance (ready to export)
+ *
+ * @example
+ * ```ts
+ * const blob = await renderDocx({
+ *   page: { size: 'A4', margin: '20mm' },
+ *   styles: {
+ *     h1: { fontSize: 24, fontWeight: 'bold' },
+ *     p:  { fontSize: 12 },
+ *   },
+ *   content: [
+ *     { type: 'heading',  level: 1, text: 'Report', className: 'h1' },
+ *     { type: 'paragraph', text: 'This is a report generated via JSON DSL.', className: 'p' },
+ *     { type: 'pageBreak' },
+ *     {
+ *       type: 'table',
+ *       columns: [{ key: 'name', title: 'Name' }, { key: 'value', title: 'Value' }],
+ *       data: [{ name: 'Revenue', value: '$1.2M' }],
+ *     },
+ *   ],
+ * }).toBlob()
+ * ```
+ */
+declare function renderDocx<const TStyles extends StyleSheet = StyleSheet>(schema: DocxSchema<TStyles>): DocxBuilder<TStyles>;
+//#endregion
+//#region src/plugins/property-table/index.d.ts
+/**
+ * Property Table plugin — renders key-value pairs as a styled 2-column table.
+ *
+ * The key column is right-aligned with gray background; the value column
+ * is left-aligned.  Ideal for config tables, parameter docs, and spec sheets.
+ *
+ * @module plugins/property-table
+ *
+ * @example
+ * ```ts
+ * const doc = createDocx()
+ *   .use(propertyTablePlugin())
+ *   .plugin('propertyTable', {
+ *     items: [
+ *       { key: '项目名称', value: 'XX管理系统' },
+ *       { key: '技术栈',   value: 'React + Node.js + PostgreSQL' },
+ *     ],
+ *     keyBold: true,
+ *   })
+ *   .save('props.docx')
+ * ```
+ */
+/** A single key-value pair. */
+interface PropertyItem {
+  key: string;
+  value: string;
+}
+/** Options for the PropertyTable plugin. */
+interface PropertyTableOptions {
+  /** Key-value items to display. */
+  items: PropertyItem[];
+  /**
+   * Whether the key column text is bold. @default true
+   */
+  keyBold?: boolean;
+  /** Alternate row background shading. @default true */
+  striped?: boolean;
+}
+/**
+ * Create a PropertyTable plugin instance.
+ *
+ * @returns A configured DocxPlugin for `'propertyTable'`
+ */
+declare function propertyTablePlugin(): DocxPlugin<"propertyTable", PropertyTableOptions>;
+//#endregion
+//#region src/plugins/meeting-minutes/index.d.ts
+/**
+ * Meeting Minutes plugin — structured meeting notes with header, meta info,
+ * and an agenda table.
+ *
+ * Renders a title paragraph, a date/attendees summary line, and a 4-column
+ * agenda table (Topic | Discussion | Decision | Owner).
+ *
+ * @module plugins/meeting-minutes
+ *
+ * @example
+ * ```ts
+ * const doc = createDocx()
+ *   .use(meetingMinutesPlugin())
+ *   .plugin('meetingMinutes', {
+ *     title: '项目周会纪要',
+ *     date: '2026-06-11',
+ *     attendees: ['张三', '李四', '王五'],
+ *     agenda: [
+ *       { topic: '项目进度', discussion: '模块A已完成80%', decision: '下周一上线', owner: '张三' },
+ *       { topic: '风险项', discussion: '第三方API不稳定', decision: '增加重试机制', owner: '李四' },
+ *     ],
+ *   })
+ *   .save('minutes.docx')
+ * ```
+ */
+/** A single agenda item. */
+interface AgendaItem {
+  /** Discussion notes. */
+  discussion: string;
+  /** Meeting topic. */
+  topic: string;
+  /** Decision made. */
+  decision?: string;
+  /** Responsible person. */
+  owner?: string;
+}
+/** Options for the MeetingMinutes plugin. */
+interface MeetingMinutesOptions {
+  /** Agenda items to render in the table. */
+  agenda: AgendaItem[];
+  /** Attendee names. */
+  attendees: string[];
+  /** Meeting date (e.g. "2026-06-11"). */
+  date: string;
+  /** Meeting title (rendered as Heading 1). */
+  title: string;
+}
+/**
+ * Create a MeetingMinutes plugin instance.
+ *
+ * @returns A configured DocxPlugin for `'meetingMinutes'`
+ */
+declare function meetingMinutesPlugin(): DocxPlugin<"meetingMinutes", MeetingMinutesOptions>;
+//#endregion
+//#region src/plugins/signature-block/index.d.ts
+/**
+ * Signature Block plugin — renders signature lines for contracts and approvals.
+ *
+ * Each party gets a cell in a borderless table with a bold label,
+ * a signature line (underlined placeholder), and an optional date.
+ *
+ * @module plugins/signature-block
+ *
+ * @example
+ * ```ts
+ * const doc = createDocx()
+ *   .use(signatureBlockPlugin())
+ *   .plugin('signatureBlock', {
+ *     parties: [
+ *       { label: '甲方（盖章）', date: '2026年  月  日' },
+ *       { label: '乙方（盖章）', date: '2026年  月  日' },
+ *     ],
+ *     columns: 2,
+ *   })
+ *   .save('signature.docx')
+ * ```
+ */
+/** Options for the SignatureBlock plugin. */
+interface SignatureBlockOptions {
+  /** The signing parties. */
+  parties: SignatureParty[];
+  /** Number of columns in the signature grid. @default 2 */
+  columns?: number;
+}
+/** A single party in a signature block. */
+interface SignatureParty {
+  /** Party label (e.g. "甲方（盖章）"). */
+  label: string;
+  /** Pre-filled date (e.g. "2026年  月  日"). */
+  date?: string;
+  /** Pre-filled name (shown underlined when provided). */
+  name?: string;
+}
+/**
+ * Create a SignatureBlock plugin instance.
+ *
+ * @returns A configured DocxPlugin for `'signatureBlock'`
+ */
+declare function signatureBlockPlugin(): DocxPlugin<"signatureBlock", SignatureBlockOptions>;
+//#endregion
+//#region src/presets/types.d.ts
+/**
+ * A named, reusable style preset.
+ *
+ * Each preset provides a `config` object compatible with `DocxKitConfig`.
+ * Spread the config into `createDocx()` to apply the preset, or use the
+ * `usePreset()` helper for lookup by ID.
+ */
+interface DocxPreset {
+  /** The config fragment to merge into `createDocx()`. */
+  readonly config: DocxKitConfig;
+  /** Short description of the preset's visual character. */
+  readonly description: string;
+  /** Machine-readable identifier (e.g. `"classic"`). */
+  readonly id: string;
+  /** Human-readable display name (e.g. `"Classic"`). */
+  readonly name: string;
+}
+//#endregion
+//#region src/presets/academic.d.ts
+declare const academicPreset: DocxPreset;
+//#endregion
+//#region src/presets/classic.d.ts
+declare const classicPreset: DocxPreset;
+//#endregion
+//#region src/presets/modern.d.ts
+declare const modernPreset: DocxPreset;
+//#endregion
+//#region src/presets/index.d.ts
+/** Ordered list of built-in presets (for UI selectors). */
+declare const PRESET_LIST: readonly DocxPreset[];
+/**
+ * Look up a built-in preset by ID.
+ *
+ * @param id - — Preset identifier (`"classic"`, `"modern"`, or `"academic"`)
+ * @returns The matching preset, or `undefined` if not found
+ *
+ * @example
+ * ```ts
+ * const preset = usePreset('modern')
+ * const doc = createDocx(preset!.config)
+ * ```
+ */
+declare function usePreset(id: string): DocxPreset | undefined;
+//#endregion
+//#region src/node/fs.d.ts
+/**
+ * Save a compiled document to a file on disk.
+ *
+ * Uses `Packer.toBuffer()` to produce the .docx binary, then
+ * writes via `node:fs/promises`. This function is **Node.js only**.
+ *
+ * @param doc - — A compiled `docx` `Document` instance
+ * @param filename - — Output file path (e.g. `"report.docx"`)
+ *
+ * @example
+ * ```ts
+ * import { saveDocument } from 'docx-kit/node'
+ *
+ * const doc = await compileDocument({ ... })
+ * await saveDocument(doc, 'report.docx')
+ * ```
+ */
+declare function saveDocument(doc: Document, filename: string): Promise<void>;
+//#endregion
+//#region src/node/dataUrl.d.ts
+/**
+ * Node.js base64 data-URL decoder (uses `Buffer` from `node:buffer`).
+ *
+ * @module node/dataUrl
+ */
+/**
+ * Decode a base64 data-URL to raw bytes using Node.js `Buffer`.
+ *
+ * Strips the `"data:*;base64,"` prefix and decodes via
+ * `Buffer.from(base64, 'base64')`.
+ *
+ * @param dataUrl - — A base64 data-URI string (e.g. `"data:image/png;base64,iVBO..."`)
+ * @returns Raw bytes as `Uint8Array`
+ *
+ * @example
+ * ```ts
+ * import { dataUrlToUint8Array } from 'docx-kit/node'
+ *
+ * const bytes = await dataUrlToUint8Array('data:image/png;base64,iVBORw...')
+ * ```
+ */
+declare function dataUrlToUint8Array(dataUrl: string): Promise<Uint8Array>;
+//#endregion
+//#region src/node.d.ts
+/**
+ * ### ❌ `echartsPlugin()` — Not available in Node.js
+ *
+ * The ECharts plugin requires a browser `window` and `document` to
+ * render charts into a DOM container. Node.js has no native DOM.
+ *
+ * **Workarounds:**
+ * - Use a server-side canvas library (e.g. `node-canvas` + `echarts`)
+ * - Pre-render charts on the client and pass the image data to docx-kit
+ *
+ * @deprecated This API is not available in Node.js. See workarounds above.
+ */
+declare const echartsPlugin: never;
+/**
+ * ### ❌ `normalizeImageData()` — Not built-in for Node.js
+ *
+ * This utility converts `Blob` instances to `Uint8Array`. While `Blob`
+ * is available in Node.js ≥ 18, it is rarely the carrier for image data
+ * in Node workflows (most users work with `Buffer` or file paths directly).
+ *
+ * If you need Blob→Uint8Array in Node.js, use:
+ * ```ts
+ * const bytes = new Uint8Array(await blob.arrayBuffer())
+ * ```
+ *
+ * @deprecated Use inline `new Uint8Array(await blob.arrayBuffer())` instead.
+ */
+declare const normalizeImageData: never;
+//#endregion
+export { type AgendaItem, type BaseNode, type BlockNode, type BorderRule, type BorderStyle, type BulletItem, type BulletListNode, type CalloutOptions, type ClassName, type CodeBlockOptions, type ColAlign, type ColFormat, type CoverPageOptions, type DataTableOptions, DocxBuilder, type DocxKitConfig, DocxKitError, type DocxPlugin, type DocxPreset, type DocxSchema, type DocxStyleRule, type DocxTheme, type EChartsPluginOptions, ERROR_CODES, type ErrorCode, type FontWeight, type HeaderFooterConfig, type HeaderFooterContent, type HeadingNode, type HighlightColor, type HyperlinkNode, type ImageNode, type InlineNode, type MeetingMinutesOptions, type NumberedListNode, type Orientation, PRESET_LIST, type PageBreakNode, type PageConfig, type PageNumberOptions, type PageSize, type ParagraphNode, type PluginNode, type PluginRegistry, type PluginRenderContext, type PropertyItem, type PropertyTableOptions, type QRCodePluginOptions, type SectionBreakNode, type SectionConfig, type SignatureBlockOptions, type SignatureParty, type StyleSheet, type TableColumn, type TableNode, type TextAlign, type TextNode, type TimelineEvent, type TimelineOptions, type VerticalAlign, type WatermarkOptions, academicPreset, calloutPlugin, classicPreset, codeBlockPlugin, coverPagePlugin, createDocx, dataTablePlugin, dataUrlToUint8Array, definePlugin, defineStyles, echartsPlugin, meetingMinutesPlugin, modernPreset, normalizeImageData, pageNumberPlugin, propertyTablePlugin, qrcodePlugin, renderDocx, saveDocument, signatureBlockPlugin, timelinePlugin, usePreset, watermarkPlugin };