docx-kit 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,3 +1,4 @@
1
+ import { AlignmentType, Document } from "docx";
1
2
  import { EChartsOption } from "echarts";
2
3
 
3
4
  //#region src/types/utility.d.ts
@@ -67,6 +68,8 @@ interface DocxStyleRule {
67
68
  borderRight?: BorderRule;
68
69
  /** Top border override. */
69
70
  borderTop?: BorderRule;
71
+ /** Character spacing (letter-spacing). */
72
+ characterSpacing?: number;
70
73
  /** Text / foreground color. */
71
74
  color?: string | HexColor;
72
75
  /**
@@ -84,6 +87,12 @@ interface DocxStyleRule {
84
87
  fontWeight?: FontWeight;
85
88
  /** Element height. */
86
89
  height?: UnitValue;
90
+ /** Text highlight color (background marker). */
91
+ highlight?: HighlightColor;
92
+ /** Keep lines together on same page. */
93
+ keepLines?: boolean;
94
+ /** Keep this paragraph with the next one. */
95
+ keepNext?: boolean;
87
96
  /** Character spacing. */
88
97
  letterSpacing?: UnitValue;
89
98
  /** Line height multiplier or explicit unit value. */
@@ -96,8 +105,16 @@ interface DocxStyleRule {
96
105
  marginRight?: UnitValue;
97
106
  /** Top margin. */
98
107
  marginTop?: UnitValue;
108
+ /** Force page break before this paragraph. */
109
+ pageBreakBefore?: boolean;
110
+ /** Small caps text variant. */
111
+ smallCaps?: boolean;
99
112
  /** Strikethrough toggle. */
100
113
  strike?: boolean;
114
+ /** Sub-script text. */
115
+ subScript?: boolean;
116
+ /** Super-script text. */
117
+ superScript?: boolean;
101
118
  /** Horizontal text alignment. */
102
119
  textAlign?: TextAlign;
103
120
  /** First-line indent. */
@@ -125,6 +142,8 @@ interface DocxStyleRule {
125
142
  * following the CSS `font-weight` spec.
126
143
  */
127
144
  type FontWeight = 'bold' | 'normal' | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
145
+ /** Text highlight / marker colors (matches Word highlight palette). */
146
+ type HighlightColor = 'black' | 'blue' | 'cyan' | 'darkBlue' | 'darkCyan' | 'darkGray' | 'darkGreen' | 'darkMagenta' | 'darkRed' | 'darkYellow' | 'green' | 'lightGray' | 'magenta' | 'none' | 'red' | 'white' | 'yellow';
128
147
  /**
129
148
  * A map of class name → style rule.
130
149
  *
@@ -161,6 +180,139 @@ type VerticalAlign = 'bottom' | 'middle' | 'top';
161
180
  */
162
181
  declare function defineStyles<const T extends StyleSheet>(styles: T): T;
163
182
  //#endregion
183
+ //#region src/types/document.d.ts
184
+ /**
185
+ * Top-level configuration passed to `createDocx()`.
186
+ *
187
+ * Covers page setup, stylesheet, theme tokens, element defaults,
188
+ * and document metadata.
189
+ *
190
+ * @template TStyles — The user's stylesheet type (inferred from `styles`).
191
+ */
192
+ interface DocxKitConfig<TStyles extends StyleSheet = StyleSheet> {
193
+ /** Page dimensions and margins. */
194
+ page?: PageConfig;
195
+ /** Named style classes (class → style rule map). */
196
+ styles?: TStyles;
197
+ /** Semantic design tokens for theming. */
198
+ theme?: DocxTheme;
199
+ /** Default styles applied as base for each element type. */
200
+ defaults?: {
201
+ /** Default table cell style. */cell?: DocxStyleRule; /** Default image style (applied to the paragraph wrapping the image). */
202
+ image?: DocxStyleRule; /** Default paragraph style. */
203
+ paragraph?: DocxStyleRule; /** Default table style. */
204
+ table?: DocxStyleRule; /** Default text run style. */
205
+ text?: DocxStyleRule;
206
+ };
207
+ /** OOXML core properties (appear in File → Info). */
208
+ metadata?: {
209
+ /** Document author. */creator?: string; /** Document description / summary. */
210
+ description?: string; /** Keywords / tags. */
211
+ keywords?: string[]; /** Last editor. */
212
+ lastModifiedBy?: string; /** Document subject. */
213
+ subject?: string; /** Document title. */
214
+ title?: string;
215
+ };
216
+ }
217
+ /**
218
+ * Theme tokens that can be referenced in styles.
219
+ *
220
+ * Allows defining a single source of truth for colors, fonts,
221
+ * font sizes, and spacing values.
222
+ */
223
+ interface DocxTheme {
224
+ /** Color palette (name → hex). */
225
+ colors?: Record<string, string>;
226
+ /** Font family tokens (name → font family). */
227
+ fontFamily?: Record<string, string>;
228
+ /** Font size tokens (name → value). */
229
+ fontSize?: Record<string, UnitValue>;
230
+ /** Spacing tokens (name → value). */
231
+ spacing?: Record<string, UnitValue>;
232
+ }
233
+ /**
234
+ * Header/footer configuration for a section.
235
+ *
236
+ * Supports standard, first-page, and even-page variants.
237
+ *
238
+ * @example
239
+ * ```ts
240
+ * {
241
+ * default: { children: ['Chapter 1'] },
242
+ * first: { children: ['Title Page'] },
243
+ * }
244
+ * ```
245
+ */
246
+ interface HeaderFooterConfig {
247
+ /** Default header/footer (appears on all pages). */
248
+ default?: HeaderFooterContent;
249
+ /** Even-page header/footer (overrides default on even pages). */
250
+ even?: HeaderFooterContent;
251
+ /** First-page-only header/footer (overrides default on page 1). */
252
+ first?: HeaderFooterContent;
253
+ }
254
+ /**
255
+ * Content for a header or footer — a list of text strings.
256
+ *
257
+ * Each string maps to a `Paragraph` in the compiled .docx output.
258
+ * Future versions may support richer content (tables, images, page numbers).
259
+ *
260
+ * @example
261
+ * ```ts
262
+ * { default: ['Company Name', 'Confidential'] }
263
+ * ```
264
+ */
265
+ interface HeaderFooterContent {
266
+ /** Paragraph text lines. */
267
+ children: string[];
268
+ }
269
+ /** Page orientation. */
270
+ type Orientation = 'landscape' | 'portrait';
271
+ /**
272
+ * Page configuration (size, orientation, margin).
273
+ */
274
+ interface PageConfig {
275
+ /** Page orientation (`"portrait"` default). */
276
+ orientation?: Orientation;
277
+ /** Page size: preset name or explicit dimensions. */
278
+ size?: PageSize | {
279
+ height: UnitValue;
280
+ width: UnitValue;
281
+ };
282
+ /**
283
+ * Page margin.
284
+ *
285
+ * Supports 1-value, 2-value, and 4-value shorthand
286
+ * (e.g. `"20mm"`, `"20mm 15mm"`, `"20mm 15mm 25mm 15mm"`).
287
+ */
288
+ margin?: `${string} ${string}` | `${string} ${string} ${string} ${string}` | UnitValue;
289
+ }
290
+ /** Available page size presets. */
291
+ type PageSize = 'A3' | 'A4' | 'Legal' | 'Letter';
292
+ /**
293
+ * Per-section configuration.
294
+ *
295
+ * Each call to `.section(config)` starts a new document section, which
296
+ * can have its own page setup, headers, and footers independent of other
297
+ * sections.
298
+ *
299
+ * @example
300
+ * ```ts
301
+ * doc.section({
302
+ * page: { size: 'A3', orientation: 'landscape' },
303
+ * header: { default: { children: ['Wide Page'] } },
304
+ * })
305
+ * ```
306
+ */
307
+ interface SectionConfig {
308
+ /** Section footer(s). */
309
+ footer?: HeaderFooterConfig;
310
+ /** Section header(s). */
311
+ header?: HeaderFooterConfig;
312
+ /** Section-specific page dimensions (overrides document-level `page`). */
313
+ page?: PageConfig;
314
+ }
315
+ //#endregion
164
316
  //#region src/dsl/nodes.d.ts
165
317
  /**
166
318
  * Common properties shared by all nodes.
@@ -184,7 +336,34 @@ interface BaseNode<TStyles extends StyleSheet = StyleSheet> {
184
336
  *
185
337
  * @template TStyles — The user's stylesheet type
186
338
  */
187
- type BlockNode<TStyles extends StyleSheet = StyleSheet> = HeadingNode<TStyles> | ImageNode<TStyles> | PageBreakNode | ParagraphNode<TStyles> | PluginNode<string, unknown, TStyles> | TableNode<Record<string, unknown>, TStyles>;
339
+ 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>;
340
+ /**
341
+ * A structured list item (for rich bullet/numbered items).
342
+ *
343
+ * @template TStyles — The user's stylesheet type
344
+ */
345
+ interface BulletItem<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
346
+ /** Item text content. */
347
+ text: string;
348
+ /** Optional inline children override (instead of text). */
349
+ children?: InlineNode<TStyles>[];
350
+ }
351
+ /**
352
+ * A bullet list node.
353
+ *
354
+ * Supports plain string items or structured items with children.
355
+ *
356
+ * @template TStyles — The user's stylesheet type
357
+ */
358
+ interface BulletListNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
359
+ /** List items — strings or structured items. */
360
+ items: (string | BulletItem<TStyles>)[];
361
+ type: 'bulletList';
362
+ /** Bullet character / style. Default: `'•'`. */
363
+ bullet?: string;
364
+ /** Nested list level (0 = top-level). */
365
+ level?: number;
366
+ }
188
367
  /**
189
368
  * Extract valid class name keys from a stylesheet type.
190
369
  *
@@ -203,6 +382,18 @@ interface HeadingNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<
203
382
  text: string;
204
383
  type: 'heading';
205
384
  }
385
+ /**
386
+ * A hyperlink node (inline content that creates a clickable link).
387
+ *
388
+ * @template TStyles — The user's stylesheet type
389
+ */
390
+ interface HyperlinkNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
391
+ /** Display text or inline children. */
392
+ children: (string | TextNode<TStyles>)[];
393
+ type: 'hyperlink';
394
+ /** Link target URL. */
395
+ url: string;
396
+ }
206
397
  /**
207
398
  * An image node.
208
399
  *
@@ -239,7 +430,28 @@ interface ImageNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TS
239
430
  *
240
431
  * @template TStyles — The user's stylesheet type
241
432
  */
242
- type InlineNode<TStyles extends StyleSheet = StyleSheet> = ImageNode<TStyles> | TextNode<TStyles>;
433
+ type InlineNode<TStyles extends StyleSheet = StyleSheet> = HyperlinkNode<TStyles> | ImageNode<TStyles> | TextNode<TStyles>;
434
+ /**
435
+ * A numbered / ordered list node.
436
+ *
437
+ * @template TStyles — The user's stylesheet type
438
+ */
439
+ interface NumberedListNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
440
+ /** List items. */
441
+ items: (string | BulletItem<TStyles>)[];
442
+ type: 'numberedList';
443
+ /** Nested list level (0 = top-level). */
444
+ level?: number;
445
+ /** Starting number (default: 1). */
446
+ start?: number;
447
+ /**
448
+ * Numbering format.
449
+ *
450
+ * {@link `LevelFormat.DECIMAL`} by default.
451
+ * e.g. `'decimal'`, `'upperRoman'`, `'lowerLetter'`
452
+ */
453
+ numberingFormat?: 'decimal' | 'lowerLetter' | 'lowerRoman' | 'upperLetter' | 'upperRoman';
454
+ }
243
455
  /**
244
456
  * A forced page break.
245
457
  */
@@ -274,6 +486,20 @@ interface PluginNode<TName extends string = string, TOptions = unknown, TStyles
274
486
  options: TOptions;
275
487
  type: 'plugin';
276
488
  }
489
+ /**
490
+ * Internal marker node that represents a section boundary.
491
+ *
492
+ * Created automatically by {@link DocxBuilder.section} — users should
493
+ * not create this node directly.
494
+ *
495
+ * When the compiler encounters this marker, it starts a new section
496
+ * with the provided configuration.
497
+ */
498
+ interface SectionBreakNode {
499
+ type: 'sectionBreak';
500
+ /** Optional per-section page/header/footer overrides. */
501
+ config?: SectionConfig;
502
+ }
277
503
  /**
278
504
  * A column definition for a table.
279
505
  *
@@ -286,6 +512,19 @@ interface TableColumn<TData extends Record<string, unknown> = Record<string, unk
286
512
  title: string;
287
513
  /** Cell text alignment. */
288
514
  align?: 'center' | 'left' | 'right';
515
+ /**
516
+ * Span multiple columns horizontally.
517
+ *
518
+ * Applied to all cells in this column.
519
+ */
520
+ colSpan?: number;
521
+ /**
522
+ * Span multiple rows vertically (per-cell via data hints).
523
+ *
524
+ * Set `rowSpan` on individual data objects using `_rowSpan: N` or keep it
525
+ * as a static column default.
526
+ */
527
+ rowSpan?: number;
289
528
  /** Column width. Supports percentage strings (e.g. `"30%"`). */
290
529
  width?: UnitValue;
291
530
  /**
@@ -330,79 +569,6 @@ interface TextNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TSt
330
569
  type: 'text';
331
570
  }
332
571
  //#endregion
333
- //#region src/types/document.d.ts
334
- /**
335
- * Top-level configuration passed to `createDocx()`.
336
- *
337
- * Covers page setup, stylesheet, theme tokens, element defaults,
338
- * and document metadata.
339
- *
340
- * @template TStyles — The user's stylesheet type (inferred from `styles`).
341
- */
342
- interface DocxKitConfig<TStyles extends StyleSheet = StyleSheet> {
343
- /** Page dimensions and margins. */
344
- page?: PageConfig;
345
- /** Named style classes (class → style rule map). */
346
- styles?: TStyles;
347
- /** Semantic design tokens for theming. */
348
- theme?: DocxTheme;
349
- /** Default styles applied as base for each element type. */
350
- defaults?: {
351
- /** Default table cell style. */cell?: DocxStyleRule; /** Default paragraph style. */
352
- paragraph?: DocxStyleRule; /** Default table style. */
353
- table?: DocxStyleRule; /** Default text run style. */
354
- text?: DocxStyleRule;
355
- };
356
- /** OOXML core properties (appear in File → Info). */
357
- metadata?: {
358
- /** Document author. */creator?: string; /** Document description / summary. */
359
- description?: string; /** Keywords / tags. */
360
- keywords?: string[]; /** Last editor. */
361
- lastModifiedBy?: string; /** Document subject. */
362
- subject?: string; /** Document title. */
363
- title?: string;
364
- };
365
- }
366
- /**
367
- * Theme tokens that can be referenced in styles.
368
- *
369
- * Allows defining a single source of truth for colors, fonts,
370
- * font sizes, and spacing values.
371
- */
372
- interface DocxTheme {
373
- /** Color palette (name → hex). */
374
- colors?: Record<string, string>;
375
- /** Font family tokens (name → font family). */
376
- fontFamily?: Record<string, string>;
377
- /** Font size tokens (name → value). */
378
- fontSize?: Record<string, UnitValue>;
379
- /** Spacing tokens (name → value). */
380
- spacing?: Record<string, UnitValue>;
381
- }
382
- /** Page orientation. */
383
- type Orientation = 'landscape' | 'portrait';
384
- /**
385
- * Page configuration (size, orientation, margin).
386
- */
387
- interface PageConfig {
388
- /** Page orientation (`"portrait"` default). */
389
- orientation?: Orientation;
390
- /** Page size: preset name or explicit dimensions. */
391
- size?: PageSize | {
392
- height: UnitValue;
393
- width: UnitValue;
394
- };
395
- /**
396
- * Page margin.
397
- *
398
- * Supports 1-value, 2-value, and 4-value shorthand
399
- * (e.g. `"20mm"`, `"20mm 15mm"`, `"20mm 15mm 25mm 15mm"`).
400
- */
401
- margin?: `${string} ${string}` | `${string} ${string} ${string} ${string}` | UnitValue;
402
- }
403
- /** Available page size presets. */
404
- type PageSize = 'A3' | 'A4' | 'Legal' | 'Letter';
405
- //#endregion
406
572
  //#region src/types/plugin.d.ts
407
573
  /**
408
574
  * A docx-kit plugin.
@@ -476,6 +642,137 @@ interface PluginRenderContext {
476
642
  */
477
643
  declare function definePlugin<const TName extends string, TOptions>(plugin: DocxPlugin<TName, TOptions>): DocxPlugin<TName, TOptions>;
478
644
  //#endregion
645
+ //#region src/plugins/qrcode/index.d.ts
646
+ /**
647
+ * QR Code plugin — embeds a QR code image in the document.
648
+ *
649
+ * Uses the `qrcode` package (peer dependency) to generate
650
+ * a QR code PNG and renders it as an inline `ImageRun`.
651
+ *
652
+ * @module plugins/qrcode
653
+ *
654
+ * @example
655
+ * ```ts
656
+ * const doc = createDocx()
657
+ * .use(qrcodePlugin())
658
+ * .h1('Scan Me')
659
+ * .plugin('qrcode', { text: 'https://example.com', caption: 'Visit us' })
660
+ * .save('qrcode.docx')
661
+ * ```
662
+ */
663
+ /**
664
+ * Options for the QRCode plugin.
665
+ */
666
+ interface QRCodePluginOptions {
667
+ /** The text / URL to encode. */
668
+ text: string;
669
+ /** Optional caption text displayed below the QR code. */
670
+ caption?: string;
671
+ /**
672
+ * QR error correction level.
673
+ *
674
+ * - `"L"` — ~7% recovery
675
+ * - `"M"` — ~15% recovery
676
+ * - `"Q"` — ~25% recovery
677
+ * - `"H"` — ~30% recovery
678
+ *
679
+ * @default "M"
680
+ */
681
+ errorCorrectionLevel?: 'H' | 'L' | 'M' | 'Q';
682
+ /** QR code margin (in modules). @default 1 */
683
+ margin?: number;
684
+ /** QR code image size in pixels. @default 128 */
685
+ size?: number;
686
+ }
687
+ /**
688
+ * Create a QRCode plugin instance.
689
+ *
690
+ * The plugin dynamically imports the `qrcode` package at render time,
691
+ * keeping it an optional peer dependency of docx-kit core.
692
+ *
693
+ * @returns A configured DocxPlugin for `'qrcode'`
694
+ *
695
+ * @example
696
+ * ```ts
697
+ * import { createDocx, qrcodePlugin } from 'docx-kit'
698
+ *
699
+ * const doc = createDocx()
700
+ * .use(qrcodePlugin())
701
+ * .plugin('qrcode', {
702
+ * text: 'https://example.com',
703
+ * size: 256,
704
+ * errorCorrectionLevel: 'H',
705
+ * caption: 'Scan to visit',
706
+ * })
707
+ * ```
708
+ */
709
+ declare function qrcodePlugin(): DocxPlugin<"qrcode", QRCodePluginOptions>;
710
+ //#endregion
711
+ //#region src/plugins/callout/index.d.ts
712
+ /**
713
+ * Callout plugin — colored info / warning / success / danger boxes.
714
+ *
715
+ * Renders a single `Paragraph` with a prominent left border, a tinted
716
+ * background, an emoji icon, an optional bold title, and body text.
717
+ *
718
+ * @module plugins/callout
719
+ *
720
+ * @example
721
+ * ```ts
722
+ * const doc = createDocx()
723
+ * .use(calloutPlugin())
724
+ * .plugin('callout', {
725
+ * type: 'warning',
726
+ * title: '注意',
727
+ * content: '此操作不可撤销,请确认后再提交。',
728
+ * })
729
+ * .save('callout.docx')
730
+ * ```
731
+ */
732
+ /** Options for the Callout plugin. */
733
+ interface CalloutOptions {
734
+ /** Body text of the callout. */
735
+ content: string;
736
+ /** Callout style — controls icon, color, and tone. */
737
+ type: 'danger' | 'info' | 'success' | 'warning';
738
+ /** Optional bold title line placed before the content. */
739
+ title?: string;
740
+ }
741
+ /**
742
+ * Create a Callout plugin instance.
743
+ *
744
+ * @returns A configured DocxPlugin for `'callout'`
745
+ *
746
+ * @example
747
+ * ```ts
748
+ * import { createDocx, calloutPlugin } from 'docx-kit'
749
+ *
750
+ * const doc = createDocx()
751
+ * .use(calloutPlugin())
752
+ * .plugin('callout', { type: 'info', content: '系统将在今晚 22:00 升级。' })
753
+ * ```
754
+ */
755
+ declare function calloutPlugin(): DocxPlugin<"callout", CalloutOptions>;
756
+ //#endregion
757
+ //#region src/plugins/echarts/index.d.ts
758
+ /**
759
+ * Options for the ECharts plugin.
760
+ */
761
+ interface EChartsPluginOptions {
762
+ /** Full ECharts option object (series, axes, title, etc.). */
763
+ option: EChartsOption;
764
+ /** Optional caption text displayed below the chart. */
765
+ caption?: string;
766
+ /** Chart height in pixels. @default 360 */
767
+ height?: number;
768
+ /** Output image format. @default "png" */
769
+ imageType?: 'png' | 'svg';
770
+ /** ECharts rendering engine. @default "canvas" */
771
+ renderer?: 'canvas' | 'svg';
772
+ /** Chart width in pixels. @default 640 */
773
+ width?: number;
774
+ }
775
+ //#endregion
479
776
  //#region src/builder/DocxBuilder.d.ts
480
777
  /**
481
778
  * Fluent document builder.
@@ -506,6 +803,23 @@ declare class DocxBuilder<TStyles extends StyleSheet = StyleSheet, TPlugins exte
506
803
  * ```
507
804
  */
508
805
  add(node: BlockNode<TStyles>): this;
806
+ /**
807
+ * Add a bullet (unordered) list.
808
+ *
809
+ * @param items - — List items (strings or structured items)
810
+ * @param options - — Optional bullet character, className, style, level
811
+ * @returns The builder (for chaining)
812
+ *
813
+ * @example
814
+ * ```ts
815
+ * doc.bulletList(['Item 1', 'Item 2', 'Item 3'])
816
+ * doc.bulletList([
817
+ * 'Simple item',
818
+ * { text: 'Rich item', className: 'highlight' },
819
+ * ], { bullet: '\u25CB' })
820
+ * ```
821
+ */
822
+ bulletList(items: (string | BulletItem<TStyles>)[], options?: Omit<Partial<BulletListNode<TStyles>>, 'items' | 'type'>): this;
509
823
  /**
510
824
  * Add a level-1 heading.
511
825
  *
@@ -559,6 +873,20 @@ declare class DocxBuilder<TStyles extends StyleSheet = StyleSheet, TPlugins exte
559
873
  * @returns The builder (for chaining)
560
874
  */
561
875
  h6(text: string, options?: Omit<Partial<HeadingNode<TStyles>>, 'level' | 'text' | 'type'>): this;
876
+ /**
877
+ * Add a hyperlink.
878
+ *
879
+ * @param url - — Target URL
880
+ * @param text - — Display text
881
+ * @param options - — Optional style overrides
882
+ * @returns The builder (for chaining)
883
+ *
884
+ * @example
885
+ * ```ts
886
+ * doc.hyperlink('https://example.com', 'Click here')
887
+ * ```
888
+ */
889
+ hyperlink(url: string, text: string, options?: Omit<Partial<HyperlinkNode<TStyles>>, 'children' | 'type' | 'url'>): this;
562
890
  /**
563
891
  * Add an image node.
564
892
  *
@@ -571,6 +899,23 @@ declare class DocxBuilder<TStyles extends StyleSheet = StyleSheet, TPlugins exte
571
899
  * ```
572
900
  */
573
901
  image(options: Omit<ImageNode<TStyles>, 'type'>): this;
902
+ /**
903
+ * Add a numbered (ordered) list.
904
+ *
905
+ * @param items - — List items
906
+ * @param options - — Optional numbering format, start, className, style, level
907
+ * @returns The builder (for chaining)
908
+ *
909
+ * @example
910
+ * ```ts
911
+ * doc.numberedList(['First', 'Second', 'Third'])
912
+ * doc.numberedList(
913
+ * [{ text: 'Intro' }, { text: 'Body' }],
914
+ * { numberingFormat: 'upperRoman', start: 1 },
915
+ * )
916
+ * ```
917
+ */
918
+ numberedList(items: (string | BulletItem<TStyles>)[], options?: Omit<Partial<NumberedListNode<TStyles>>, 'items' | 'type'>): this;
574
919
  /**
575
920
  * Add a paragraph.
576
921
  *
@@ -615,14 +960,42 @@ declare class DocxBuilder<TStyles extends StyleSheet = StyleSheet, TPlugins exte
615
960
  * **⚠️ Not available in browser environments.**
616
961
  * Use {@link toBlob} and trigger a download instead.
617
962
  *
618
- * @param filename - — Output file path (e.g. `"report.docx"`)
963
+ * @param filename - — Output file path (e.g. `"report.docx"`)
964
+ *
965
+ * @example
966
+ * ```ts
967
+ * await doc.save('output.docx')
968
+ * ```
969
+ */
970
+ save(filename: string): Promise<void>;
971
+ /**
972
+ * Start a new document section.
973
+ *
974
+ * Each section can have its own page size, orientation, margins,
975
+ * headers, and footers. Content added after this call belongs to
976
+ * the new section.
977
+ *
978
+ * @param config - — Optional section-level page/header/footer overrides
979
+ * @returns The builder (for chaining)
619
980
  *
620
981
  * @example
621
982
  * ```ts
622
- * await doc.save('output.docx')
983
+ * // Simple section break
984
+ * doc.p('Section 1 content').section().p('Section 2 content')
985
+ *
986
+ * // Section with custom page setup
987
+ * doc.section({ page: { size: 'A3', orientation: 'landscape' } })
988
+ * .h1('Wide table')
989
+ * .table({ columns: [...], data: [...] })
990
+ *
991
+ * // Section with header and footer
992
+ * doc.section({
993
+ * header: { default: { children: ['Chapter 2', 'Confidential'] } },
994
+ * footer: { default: { children: ['Page 2'] } },
995
+ * })
623
996
  * ```
624
997
  */
625
- save(filename: string): Promise<void>;
998
+ section(config?: SectionConfig): this;
626
999
  /**
627
1000
  * Add a table.
628
1001
  *
@@ -704,6 +1077,7 @@ declare class DocxBuilder<TStyles extends StyleSheet = StyleSheet, TPlugins exte
704
1077
  theme?: DocxTheme;
705
1078
  defaults?: {
706
1079
  cell?: DocxStyleRule;
1080
+ image?: DocxStyleRule;
707
1081
  paragraph?: DocxStyleRule;
708
1082
  table?: DocxStyleRule;
709
1083
  text?: DocxStyleRule;
@@ -751,6 +1125,79 @@ declare class DocxBuilder<TStyles extends StyleSheet = StyleSheet, TPlugins exte
751
1125
  use<TName extends string, TOptions>(plugin: DocxPlugin<TName, TOptions>): DocxBuilder<TStyles, Record<TName, TOptions> & TPlugins>;
752
1126
  }
753
1127
  //#endregion
1128
+ //#region src/plugins/timeline/index.d.ts
1129
+ /**
1130
+ * Timeline plugin — renders a chronological timeline as a styled table.
1131
+ *
1132
+ * Each event occupies one table row: a date cell, a visual connector
1133
+ * cell, and a content cell (title + optional description).
1134
+ *
1135
+ * @module plugins/timeline
1136
+ *
1137
+ * @example
1138
+ * ```ts
1139
+ * const doc = createDocx()
1140
+ * .use(timelinePlugin())
1141
+ * .plugin('timeline', {
1142
+ * events: [
1143
+ * { date: '2026-01', title: '项目立项', description: '完成需求评审' },
1144
+ * { date: '2026-03', title: 'MVP 发布', description: '核心功能上线' },
1145
+ * ],
1146
+ * })
1147
+ * .save('timeline.docx')
1148
+ * ```
1149
+ */
1150
+ /** A single timeline event. */
1151
+ interface TimelineEvent {
1152
+ /** Date / time label (e.g. "2026-06" or "Q3"). */
1153
+ date: string;
1154
+ /** Short event title. */
1155
+ title: string;
1156
+ /** Optional longer description. */
1157
+ description?: string;
1158
+ }
1159
+ /** Options for the Timeline plugin. */
1160
+ interface TimelineOptions {
1161
+ /** Array of timeline events in chronological order. */
1162
+ events: TimelineEvent[];
1163
+ /**
1164
+ * Accent color for the connector line and date highlight.
1165
+ * @default '4472C4'
1166
+ */
1167
+ accentColor?: string;
1168
+ /**
1169
+ * Layout style.
1170
+ *
1171
+ * - `'alternating'` — dates alternate left / right (default)
1172
+ * - `'left'` — all dates on the left, content on the right
1173
+ * - `'right'` — all content on the left, dates on the right
1174
+ *
1175
+ * @default 'alternating'
1176
+ */
1177
+ layout?: 'alternating' | 'left' | 'right';
1178
+ }
1179
+ /**
1180
+ * Create a Timeline plugin instance.
1181
+ *
1182
+ * @returns A configured DocxPlugin for `'timeline'`
1183
+ *
1184
+ * @example
1185
+ * ```ts
1186
+ * import { createDocx, timelinePlugin } from 'docx-kit'
1187
+ *
1188
+ * const doc = createDocx()
1189
+ * .use(timelinePlugin())
1190
+ * .plugin('timeline', {
1191
+ * events: [
1192
+ * { date: '2026-01', title: '项目启动', description: '团队组建完成' },
1193
+ * { date: '2026-04', title: 'Beta 测试', description: '收集用户反馈' },
1194
+ * { date: '2026-06', title: '正式发布' },
1195
+ * ],
1196
+ * })
1197
+ * ```
1198
+ */
1199
+ declare function timelinePlugin(): DocxPlugin<"timeline", TimelineOptions>;
1200
+ //#endregion
754
1201
  //#region src/errors.d.ts
755
1202
  /**
756
1203
  * Error handling types and classes for docx-kit.
@@ -803,150 +1250,222 @@ declare class DocxKitError extends Error {
803
1250
  constructor(code: string | ErrorCode, message: string, cause?: unknown);
804
1251
  }
805
1252
  //#endregion
806
- //#region src/plugins/qrcode/index.d.ts
1253
+ //#region src/plugins/watermark/index.d.ts
1254
+ /** Options for the Watermark plugin. */
1255
+ interface WatermarkOptions {
1256
+ /** Watermark text. */
1257
+ text: string;
1258
+ /**
1259
+ * Horizontal alignment.
1260
+ * @default 'center'
1261
+ */
1262
+ alignment?: (typeof AlignmentType)[keyof typeof AlignmentType];
1263
+ /**
1264
+ * Text color in hex RRGGBB.
1265
+ * @default 'BFBFBF'
1266
+ */
1267
+ color?: string;
1268
+ /**
1269
+ * Font size in half-points (20 = 10pt).
1270
+ * @default 48
1271
+ */
1272
+ fontSize?: number;
1273
+ }
807
1274
  /**
808
- * QR Code plugin — embeds a QR code image in the document.
1275
+ * Create a Watermark plugin instance.
809
1276
  *
810
- * Uses the `qrcode` package (peer dependency) to generate
811
- * a QR code PNG and renders it as an inline `ImageRun`.
812
- *
813
- * @module plugins/qrcode
1277
+ * @returns A configured DocxPlugin for `'watermark'`
814
1278
  *
815
1279
  * @example
816
1280
  * ```ts
1281
+ * import { createDocx, watermarkPlugin } from 'docx-kit'
1282
+ *
817
1283
  * const doc = createDocx()
818
- * .use(qrcodePlugin())
819
- * .h1('Scan Me')
820
- * .plugin('qrcode', { text: 'https://example.com', caption: 'Visit us' })
821
- * .save('qrcode.docx')
1284
+ * .use(watermarkPlugin())
1285
+ * .plugin('watermark', { text: 'DRAFT', color: 'FF0000' })
822
1286
  * ```
823
1287
  */
1288
+ declare function watermarkPlugin(): DocxPlugin<"watermark", WatermarkOptions>;
1289
+ //#endregion
1290
+ //#region src/plugins/code-block/index.d.ts
824
1291
  /**
825
- * Options for the QRCode plugin.
1292
+ * Code Block plugin renders source code with monospaced font and
1293
+ * optional line numbers and syntax highlighting.
1294
+ *
1295
+ * Syntax highlighting requires `highlight.js` as an optional peer dependency.
1296
+ * When unavailable (or when `language` is not provided), the plugin falls
1297
+ * back to plain monospaced rendering.
1298
+ *
1299
+ * @module plugins/code-block
1300
+ *
1301
+ * @example
1302
+ * ```ts
1303
+ * const doc = createDocx()
1304
+ * .use(codeBlockPlugin())
1305
+ * .plugin('codeBlock', {
1306
+ * code: `export function hello() {\n return "world"\n}`,
1307
+ * language: 'typescript',
1308
+ * showLineNumbers: true,
1309
+ * })
1310
+ * .save('code.docx')
1311
+ * ```
826
1312
  */
827
- interface QRCodePluginOptions {
828
- /** The text / URL to encode. */
829
- text: string;
830
- /** Optional caption text displayed below the QR code. */
831
- caption?: string;
1313
+ /** Options for the CodeBlock plugin. */
1314
+ interface CodeBlockOptions {
1315
+ /** Source code string. */
1316
+ code: string;
832
1317
  /**
833
- * QR error correction level.
834
- *
835
- * - `"L"` — ~7% recovery
836
- * - `"M"` — ~15% recovery
837
- * - `"Q"` — ~25% recovery
838
- * - `"H"` — ~30% recovery
1318
+ * Language identifier for syntax highlighting (optional).
839
1319
  *
840
- * @default "M"
1320
+ * Requires `highlight.js` as a peer dependency. Falls back
1321
+ * to monospaced rendering when the package is not installed.
841
1322
  */
842
- errorCorrectionLevel?: 'H' | 'L' | 'M' | 'Q';
843
- /** QR code margin (in modules). @default 1 */
844
- margin?: number;
845
- /** QR code image size in pixels. @default 128 */
846
- size?: number;
1323
+ language?: string;
1324
+ /** Prepend line numbers. @default false */
1325
+ showLineNumbers?: boolean;
847
1326
  }
848
1327
  /**
849
- * Create a QRCode plugin instance.
1328
+ * Create a CodeBlock plugin instance.
850
1329
  *
851
- * The plugin dynamically imports the `qrcode` package at render time,
852
- * keeping it an optional peer dependency of docx-kit core.
1330
+ * @returns A configured DocxPlugin for `'codeBlock'`
1331
+ */
1332
+ declare function codeBlockPlugin(): DocxPlugin<"codeBlock", CodeBlockOptions>;
1333
+ //#endregion
1334
+ //#region src/plugins/cover-page/index.d.ts
1335
+ /** Options for the Cover Page plugin. */
1336
+ interface CoverPageOptions {
1337
+ /** Main title text (required). */
1338
+ title: string;
1339
+ /** Horizontal text alignment. @default CENTER */
1340
+ alignment?: (typeof AlignmentType)[keyof typeof AlignmentType];
1341
+ /** Author or department name. */
1342
+ author?: string;
1343
+ /** Background color of the cover page in hex RRGGBB. */
1344
+ backgroundColor?: string;
1345
+ /** Date string (e.g. "2026-06-11"). */
1346
+ date?: string;
1347
+ /** Organization / company name. */
1348
+ organization?: string;
1349
+ /**
1350
+ * Show a decorative horizontal rule between title and author.
1351
+ * @default true
1352
+ */
1353
+ showRule?: boolean;
1354
+ /** Sub-title text displayed below the title. */
1355
+ subtitle?: string;
1356
+ }
1357
+ /**
1358
+ * Create a Cover Page plugin instance.
853
1359
  *
854
- * @returns A configured DocxPlugin for `'qrcode'`
1360
+ * @returns A configured DocxPlugin for `'coverPage'`
855
1361
  *
856
1362
  * @example
857
1363
  * ```ts
858
- * import { createDocx, qrcodePlugin } from 'docx-kit'
1364
+ * import { coverPagePlugin, createDocx } from 'docx-kit'
859
1365
  *
860
1366
  * const doc = createDocx()
861
- * .use(qrcodePlugin())
862
- * .plugin('qrcode', {
863
- * text: 'https://example.com',
864
- * size: 256,
865
- * errorCorrectionLevel: 'H',
866
- * caption: 'Scan to visit',
1367
+ * .use(coverPagePlugin())
1368
+ * .plugin('coverPage', {
1369
+ * title: '年度报告',
1370
+ * subtitle: '2026',
1371
+ * author: '战略发展部',
1372
+ * organization: 'XX 科技集团',
867
1373
  * })
868
1374
  * ```
869
1375
  */
870
- declare function qrcodePlugin(): DocxPlugin<"qrcode", QRCodePluginOptions>;
1376
+ declare function coverPagePlugin(): DocxPlugin<"coverPage", CoverPageOptions>;
871
1377
  //#endregion
872
- //#region src/utils/dataUrl.d.ts
873
- /**
874
- * Cross-platform base64 data-URL decoder.
875
- *
876
- * Auto-detects the runtime environment and uses the appropriate
877
- * implementation:
878
- * - **Node.js**: `Buffer.from(base64, 'base64')`
879
- * - **Browser**: `atob(base64)` + manual byte population
880
- *
881
- * This is the internal shared version used by the compiler and
882
- * built-in plugins. For platform-specific direct access, import
883
- * from `'docx-kit/node'` or `'docx-kit/browser'`.
884
- *
885
- * @module utils/dataUrl
886
- */
1378
+ //#region src/plugins/data-table/index.d.ts
887
1379
  /**
888
- * Decode a base64 data-URL to raw bytes (works in both browser & Node.js).
1380
+ * Data Table plugin renders an array of objects as a styled table.
889
1381
  *
890
- * Strips the `"data:*;base64,"` prefix and decodes using the appropriate
891
- * runtime API.
1382
+ * Columns are auto-inferred from the first object’s keys. Column headers
1383
+ * can be localised via `labels`, value formatting is controlled by `format`,
1384
+ * and per-column alignment is controlled by `align`.
892
1385
  *
893
- * @param dataUrl - — A base64 data-URI string (e.g. `"data:image/png;base64,iVBO..."`)
894
- * @returns Raw bytes as `Uint8Array`
1386
+ * @module plugins/data-table
895
1387
  *
896
1388
  * @example
897
1389
  * ```ts
898
- * import { dataUrlToUint8Array } from 'docx-kit'
899
- *
900
- * const bytes = await dataUrlToUint8Array('data:image/png;base64,iVBORw...')
1390
+ * const doc = createDocx()
1391
+ * .use(dataTablePlugin())
1392
+ * .plugin('dataTable', {
1393
+ * data: [
1394
+ * { name: 'Alice', age: 30, salary: 85000 },
1395
+ * { name: 'Bob', age: 25, salary: 62000 },
1396
+ * ],
1397
+ * labels: { name: '姓名', age: '年龄', salary: '薪资' },
1398
+ * format: { salary: 'currency' },
1399
+ * striped: true,
1400
+ * })
1401
+ * .save('table.docx')
901
1402
  * ```
902
1403
  */
903
- declare function dataUrlToUint8Array(dataUrl: string): Promise<Uint8Array>;
904
- //#endregion
905
- //#region src/plugins/echarts/index.d.ts
1404
+ /** Per-column alignment hint. */
1405
+ type ColAlign = 'center' | 'left' | 'right';
1406
+ /** Value formatter identifier. */
1407
+ type ColFormat = 'currency' | 'date' | 'number' | 'percent';
1408
+ /** Options for the DataTable plugin. */
1409
+ interface DataTableOptions {
1410
+ /**
1411
+ * The data to render — each object is one row.
1412
+ *
1413
+ * Column keys are taken from the first object in the array.
1414
+ */
1415
+ data: Record<string, unknown>[];
1416
+ /** Per-column alignment. Auto-detected from value types when omitted. */
1417
+ align?: Record<string, ColAlign>;
1418
+ /** Render visible table borders. @default true */
1419
+ bordered?: boolean;
1420
+ /** Per-column value formatter. */
1421
+ format?: Record<string, ColFormat>;
1422
+ /** Human-readable column labels (e.g. `{ salary: '薪资' }`). */
1423
+ labels?: Record<string, string>;
1424
+ /** Alternate row background shading. @default false */
1425
+ striped?: boolean;
1426
+ }
906
1427
  /**
907
- * Options for the ECharts plugin.
1428
+ * Create a DataTable plugin instance.
1429
+ *
1430
+ * @returns A configured DocxPlugin for `'dataTable'`
908
1431
  */
909
- interface EChartsPluginOptions {
910
- /** Full ECharts option object (series, axes, title, etc.). */
911
- option: EChartsOption;
912
- /** Optional caption text displayed below the chart. */
913
- caption?: string;
914
- /** Chart height in pixels. @default 360 */
915
- height?: number;
916
- /** Output image format. @default "png" */
917
- imageType?: 'png' | 'svg';
918
- /** ECharts rendering engine. @default "canvas" */
919
- renderer?: 'canvas' | 'svg';
920
- /** Chart width in pixels. @default 640 */
921
- width?: number;
1432
+ declare function dataTablePlugin(): DocxPlugin<"dataTable", DataTableOptions>;
1433
+ //#endregion
1434
+ //#region src/plugins/page-number/index.d.ts
1435
+ /** Options for the Page Number plugin. */
1436
+ interface PageNumberOptions {
1437
+ /**
1438
+ * Horizontal alignment of the page number.
1439
+ * @default 'center'
1440
+ */
1441
+ alignment?: (typeof AlignmentType)[keyof typeof AlignmentType];
1442
+ /**
1443
+ * Font size in half-points.
1444
+ * @default 20
1445
+ */
1446
+ fontSize?: number;
1447
+ /**
1448
+ * Show "Page X of Y" instead of just "X".
1449
+ * @default false
1450
+ */
1451
+ showTotal?: boolean;
922
1452
  }
923
1453
  /**
924
- * Create an ECharts plugin instance.
925
- *
926
- * The plugin renders charts using the browser DOM. In Node.js
927
- * environments, it throws an error prompting the user to provide
928
- * a server-side canvas implementation.
1454
+ * Create a Page Number plugin instance.
929
1455
  *
930
- * @returns A configured DocxPlugin for `'echarts'`
1456
+ * @returns A configured DocxPlugin for `'pageNumber'`
931
1457
  *
932
1458
  * @example
933
1459
  * ```ts
934
- * import { createDocx, echartsPlugin } from 'docx-kit'
1460
+ * import { createDocx, pageNumberPlugin } from 'docx-kit'
935
1461
  *
936
1462
  * const doc = createDocx()
937
- * .use(echartsPlugin())
938
- * .plugin('echarts', {
939
- * option: {
940
- * title: { text: 'Revenue' },
941
- * xAxis: { type: 'category', data: ['Q1', 'Q2', 'Q3', 'Q4'] },
942
- * yAxis: { type: 'value' },
943
- * series: [{ data: [820, 932, 901, 1347], type: 'line' }],
944
- * },
945
- * caption: 'Quarterly revenue trend',
946
- * })
1463
+ * .use(pageNumberPlugin())
1464
+ * // Use the page number content in a footer
1465
+ * const pn = doc.plugin('pageNumber', { alignment: 'center' })
947
1466
  * ```
948
1467
  */
949
- declare function echartsPlugin(): DocxPlugin<"echarts", EChartsPluginOptions>;
1468
+ declare function pageNumberPlugin(): DocxPlugin<"pageNumber", PageNumberOptions>;
950
1469
  //#endregion
951
1470
  //#region src/builder/createDocx.d.ts
952
1471
  /**
@@ -1029,4 +1548,270 @@ declare function createDocx<const TStyles extends StyleSheet = StyleSheet>(confi
1029
1548
  */
1030
1549
  declare function renderDocx<const TStyles extends StyleSheet = StyleSheet>(schema: DocxSchema<TStyles>): DocxBuilder<TStyles>;
1031
1550
  //#endregion
1032
- export { type BaseNode, type BlockNode, type BorderRule, type BorderStyle, type ClassName, DocxBuilder, type DocxKitConfig, DocxKitError, type DocxPlugin, type DocxSchema, type DocxStyleRule, type DocxTheme, type EChartsPluginOptions, ERROR_CODES, type ErrorCode, type FontWeight, type HeadingNode, type ImageNode, type InlineNode, type Orientation, type PageBreakNode, type PageConfig, type PageSize, type ParagraphNode, type PluginNode, type PluginRegistry, type PluginRenderContext, type QRCodePluginOptions, type StyleSheet, type TableColumn, type TableNode, type TextAlign, type TextNode, type VerticalAlign, createDocx, dataUrlToUint8Array, definePlugin, defineStyles, echartsPlugin, qrcodePlugin, renderDocx };
1551
+ //#region src/plugins/property-table/index.d.ts
1552
+ /**
1553
+ * Property Table plugin — renders key-value pairs as a styled 2-column table.
1554
+ *
1555
+ * The key column is right-aligned with gray background; the value column
1556
+ * is left-aligned. Ideal for config tables, parameter docs, and spec sheets.
1557
+ *
1558
+ * @module plugins/property-table
1559
+ *
1560
+ * @example
1561
+ * ```ts
1562
+ * const doc = createDocx()
1563
+ * .use(propertyTablePlugin())
1564
+ * .plugin('propertyTable', {
1565
+ * items: [
1566
+ * { key: '项目名称', value: 'XX管理系统' },
1567
+ * { key: '技术栈', value: 'React + Node.js + PostgreSQL' },
1568
+ * ],
1569
+ * keyBold: true,
1570
+ * })
1571
+ * .save('props.docx')
1572
+ * ```
1573
+ */
1574
+ /** A single key-value pair. */
1575
+ interface PropertyItem {
1576
+ key: string;
1577
+ value: string;
1578
+ }
1579
+ /** Options for the PropertyTable plugin. */
1580
+ interface PropertyTableOptions {
1581
+ /** Key-value items to display. */
1582
+ items: PropertyItem[];
1583
+ /**
1584
+ * Whether the key column text is bold. @default true
1585
+ */
1586
+ keyBold?: boolean;
1587
+ /** Alternate row background shading. @default true */
1588
+ striped?: boolean;
1589
+ }
1590
+ /**
1591
+ * Create a PropertyTable plugin instance.
1592
+ *
1593
+ * @returns A configured DocxPlugin for `'propertyTable'`
1594
+ */
1595
+ declare function propertyTablePlugin(): DocxPlugin<"propertyTable", PropertyTableOptions>;
1596
+ //#endregion
1597
+ //#region src/plugins/meeting-minutes/index.d.ts
1598
+ /**
1599
+ * Meeting Minutes plugin — structured meeting notes with header, meta info,
1600
+ * and an agenda table.
1601
+ *
1602
+ * Renders a title paragraph, a date/attendees summary line, and a 4-column
1603
+ * agenda table (Topic | Discussion | Decision | Owner).
1604
+ *
1605
+ * @module plugins/meeting-minutes
1606
+ *
1607
+ * @example
1608
+ * ```ts
1609
+ * const doc = createDocx()
1610
+ * .use(meetingMinutesPlugin())
1611
+ * .plugin('meetingMinutes', {
1612
+ * title: '项目周会纪要',
1613
+ * date: '2026-06-11',
1614
+ * attendees: ['张三', '李四', '王五'],
1615
+ * agenda: [
1616
+ * { topic: '项目进度', discussion: '模块A已完成80%', decision: '下周一上线', owner: '张三' },
1617
+ * { topic: '风险项', discussion: '第三方API不稳定', decision: '增加重试机制', owner: '李四' },
1618
+ * ],
1619
+ * })
1620
+ * .save('minutes.docx')
1621
+ * ```
1622
+ */
1623
+ /** A single agenda item. */
1624
+ interface AgendaItem {
1625
+ /** Discussion notes. */
1626
+ discussion: string;
1627
+ /** Meeting topic. */
1628
+ topic: string;
1629
+ /** Decision made. */
1630
+ decision?: string;
1631
+ /** Responsible person. */
1632
+ owner?: string;
1633
+ }
1634
+ /** Options for the MeetingMinutes plugin. */
1635
+ interface MeetingMinutesOptions {
1636
+ /** Agenda items to render in the table. */
1637
+ agenda: AgendaItem[];
1638
+ /** Attendee names. */
1639
+ attendees: string[];
1640
+ /** Meeting date (e.g. "2026-06-11"). */
1641
+ date: string;
1642
+ /** Meeting title (rendered as Heading 1). */
1643
+ title: string;
1644
+ }
1645
+ /**
1646
+ * Create a MeetingMinutes plugin instance.
1647
+ *
1648
+ * @returns A configured DocxPlugin for `'meetingMinutes'`
1649
+ */
1650
+ declare function meetingMinutesPlugin(): DocxPlugin<"meetingMinutes", MeetingMinutesOptions>;
1651
+ //#endregion
1652
+ //#region src/plugins/signature-block/index.d.ts
1653
+ /**
1654
+ * Signature Block plugin — renders signature lines for contracts and approvals.
1655
+ *
1656
+ * Each party gets a cell in a borderless table with a bold label,
1657
+ * a signature line (underlined placeholder), and an optional date.
1658
+ *
1659
+ * @module plugins/signature-block
1660
+ *
1661
+ * @example
1662
+ * ```ts
1663
+ * const doc = createDocx()
1664
+ * .use(signatureBlockPlugin())
1665
+ * .plugin('signatureBlock', {
1666
+ * parties: [
1667
+ * { label: '甲方(盖章)', date: '2026年 月 日' },
1668
+ * { label: '乙方(盖章)', date: '2026年 月 日' },
1669
+ * ],
1670
+ * columns: 2,
1671
+ * })
1672
+ * .save('signature.docx')
1673
+ * ```
1674
+ */
1675
+ /** Options for the SignatureBlock plugin. */
1676
+ interface SignatureBlockOptions {
1677
+ /** The signing parties. */
1678
+ parties: SignatureParty[];
1679
+ /** Number of columns in the signature grid. @default 2 */
1680
+ columns?: number;
1681
+ }
1682
+ /** A single party in a signature block. */
1683
+ interface SignatureParty {
1684
+ /** Party label (e.g. "甲方(盖章)"). */
1685
+ label: string;
1686
+ /** Pre-filled date (e.g. "2026年 月 日"). */
1687
+ date?: string;
1688
+ /** Pre-filled name (shown underlined when provided). */
1689
+ name?: string;
1690
+ }
1691
+ /**
1692
+ * Create a SignatureBlock plugin instance.
1693
+ *
1694
+ * @returns A configured DocxPlugin for `'signatureBlock'`
1695
+ */
1696
+ declare function signatureBlockPlugin(): DocxPlugin<"signatureBlock", SignatureBlockOptions>;
1697
+ //#endregion
1698
+ //#region src/presets/types.d.ts
1699
+ /**
1700
+ * A named, reusable style preset.
1701
+ *
1702
+ * Each preset provides a `config` object compatible with `DocxKitConfig`.
1703
+ * Spread the config into `createDocx()` to apply the preset, or use the
1704
+ * `usePreset()` helper for lookup by ID.
1705
+ */
1706
+ interface DocxPreset {
1707
+ /** The config fragment to merge into `createDocx()`. */
1708
+ readonly config: DocxKitConfig;
1709
+ /** Short description of the preset's visual character. */
1710
+ readonly description: string;
1711
+ /** Machine-readable identifier (e.g. `"classic"`). */
1712
+ readonly id: string;
1713
+ /** Human-readable display name (e.g. `"Classic"`). */
1714
+ readonly name: string;
1715
+ }
1716
+ //#endregion
1717
+ //#region src/presets/academic.d.ts
1718
+ declare const academicPreset: DocxPreset;
1719
+ //#endregion
1720
+ //#region src/presets/classic.d.ts
1721
+ declare const classicPreset: DocxPreset;
1722
+ //#endregion
1723
+ //#region src/presets/modern.d.ts
1724
+ declare const modernPreset: DocxPreset;
1725
+ //#endregion
1726
+ //#region src/presets/index.d.ts
1727
+ /** Ordered list of built-in presets (for UI selectors). */
1728
+ declare const PRESET_LIST: readonly DocxPreset[];
1729
+ /**
1730
+ * Look up a built-in preset by ID.
1731
+ *
1732
+ * @param id - — Preset identifier (`"classic"`, `"modern"`, or `"academic"`)
1733
+ * @returns The matching preset, or `undefined` if not found
1734
+ *
1735
+ * @example
1736
+ * ```ts
1737
+ * const preset = usePreset('modern')
1738
+ * const doc = createDocx(preset!.config)
1739
+ * ```
1740
+ */
1741
+ declare function usePreset(id: string): DocxPreset | undefined;
1742
+ //#endregion
1743
+ //#region src/node/fs.d.ts
1744
+ /**
1745
+ * Save a compiled document to a file on disk.
1746
+ *
1747
+ * Uses `Packer.toBuffer()` to produce the .docx binary, then
1748
+ * writes via `node:fs/promises`. This function is **Node.js only**.
1749
+ *
1750
+ * @param doc - — A compiled `docx` `Document` instance
1751
+ * @param filename - — Output file path (e.g. `"report.docx"`)
1752
+ *
1753
+ * @example
1754
+ * ```ts
1755
+ * import { saveDocument } from 'docx-kit/node'
1756
+ *
1757
+ * const doc = await compileDocument({ ... })
1758
+ * await saveDocument(doc, 'report.docx')
1759
+ * ```
1760
+ */
1761
+ declare function saveDocument(doc: Document, filename: string): Promise<void>;
1762
+ //#endregion
1763
+ //#region src/node/dataUrl.d.ts
1764
+ /**
1765
+ * Node.js base64 data-URL decoder (uses `Buffer` from `node:buffer`).
1766
+ *
1767
+ * @module node/dataUrl
1768
+ */
1769
+ /**
1770
+ * Decode a base64 data-URL to raw bytes using Node.js `Buffer`.
1771
+ *
1772
+ * Strips the `"data:*;base64,"` prefix and decodes via
1773
+ * `Buffer.from(base64, 'base64')`.
1774
+ *
1775
+ * @param dataUrl - — A base64 data-URI string (e.g. `"data:image/png;base64,iVBO..."`)
1776
+ * @returns Raw bytes as `Uint8Array`
1777
+ *
1778
+ * @example
1779
+ * ```ts
1780
+ * import { dataUrlToUint8Array } from 'docx-kit/node'
1781
+ *
1782
+ * const bytes = await dataUrlToUint8Array('data:image/png;base64,iVBORw...')
1783
+ * ```
1784
+ */
1785
+ declare function dataUrlToUint8Array(dataUrl: string): Promise<Uint8Array>;
1786
+ //#endregion
1787
+ //#region src/node.d.ts
1788
+ /**
1789
+ * ### ❌ `echartsPlugin()` — Not available in Node.js
1790
+ *
1791
+ * The ECharts plugin requires a browser `window` and `document` to
1792
+ * render charts into a DOM container. Node.js has no native DOM.
1793
+ *
1794
+ * **Workarounds:**
1795
+ * - Use a server-side canvas library (e.g. `node-canvas` + `echarts`)
1796
+ * - Pre-render charts on the client and pass the image data to docx-kit
1797
+ *
1798
+ * @deprecated This API is not available in Node.js. See workarounds above.
1799
+ */
1800
+ declare const echartsPlugin: never;
1801
+ /**
1802
+ * ### ❌ `normalizeImageData()` — Not built-in for Node.js
1803
+ *
1804
+ * This utility converts `Blob` instances to `Uint8Array`. While `Blob`
1805
+ * is available in Node.js ≥ 18, it is rarely the carrier for image data
1806
+ * in Node workflows (most users work with `Buffer` or file paths directly).
1807
+ *
1808
+ * If you need Blob→Uint8Array in Node.js, use:
1809
+ * ```ts
1810
+ * const bytes = new Uint8Array(await blob.arrayBuffer())
1811
+ * ```
1812
+ *
1813
+ * @deprecated Use inline `new Uint8Array(await blob.arrayBuffer())` instead.
1814
+ */
1815
+ declare const normalizeImageData: never;
1816
+ //#endregion
1817
+ 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 };