@docxkit/plugin-cover-page 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT ntnyq <https://github.com/ntnyq>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,12 @@
+# @docxkit/plugin-cover-page
+
+Cover page plugin for docx-kit.
+
+## Usage
+
+```ts
+import { coverPagePlugin } from '@docxkit/plugin-cover-page'
+
+builder.use(coverPagePlugin)
+builder.coverPage({ title: 'Annual Report', subtitle: '2026' })
+```

package/dist/index.d.ts

@@ -0,0 +1,748 @@
+import { AlignmentType } from "docx";
+
+//#region ../../packages/types/dist/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;
+/**
+ * Augments a base value type with theme token references.
+ *
+ * Lets users write `$colors.primary` in any style field that accepts the
+ * base type — the token is resolved at compile time against the document
+ * theme.
+ */
+type StyleToken<T extends number | string> = T | ThemeToken;
+/** Supported theme token categories (must match {@link resolveSingleToken}). */
+type StyleTokenCategory = '$colors' | '$fonts' | '$fontSize' | '$spacing';
+/**
+ * A `$category.key` reference to a theme token, e.g. `"$colors.primary"`,
+ * `"$fontSize.lg"`, `"$spacing.xl"`. Resolved at compile time by
+ * {@link resolveThemeTokens}.
+ */
+type ThemeToken = `${StyleTokenCategory}.${string}`;
+/**
+ * CSS-like length value.
+ *
+ * Supports bare numbers, explicit unit strings
+ * (`%`, `cm`, `in`, `mm`, `pt`, `px`), and theme token references
+ * (e.g. `"$spacing.lg"`, `"$fontSize.base"`).
+ *
+ * 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 | ThemeToken;
+//#endregion
+//#region ../../packages/types/dist/style.d.ts
+/**
+ * A single border side descriptor.
+ *
+ * Follows the CSS `border` shorthand convention (style, width, color).
+ */
+interface BorderRule {
+  /** Border color (e.g. `"#333"`, named color, or theme token like `"$colors.primary"`). */
+  color?: HexColor | StyleToken<string>;
+  /** Line style. */
+  style?: BorderStyle$1;
+  /** Line width (bare number treated as pt). */
+  width?: UnitValue;
+}
+/** Available border line styles. */
+type BorderStyle$1 = 'dashed' | 'dotted' | 'double' | 'none' | 'single';
+/**
+ * Table-cell level style properties.
+ *
+ * Used by {@link compileCellStyle} for `TableCell` construction.
+ */
+interface CellStyleRule {
+  /** Background / shading color (hex, named, or theme token like `"$colors.info"`). */
+  backgroundColor?: HexColor | StyleToken<string>;
+  /** 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;
+  /** Element height. */
+  height?: UnitValue;
+  /** Bottom margin (cell padding). */
+  marginBottom?: UnitValue;
+  /** Left margin (cell padding). */
+  marginLeft?: UnitValue;
+  /** Right margin (cell padding). */
+  marginRight?: UnitValue;
+  /** Top margin (cell padding). */
+  marginTop?: UnitValue;
+  /** Vertical alignment (mostly for table cells). */
+  verticalAlign?: VerticalAlign;
+  /** Element width. */
+  width?: UnitValue;
+  /**
+   * CSS-like margin shorthand (used as cell padding).
+   */
+  margin?: `${string} ${string}` | `${string} ${string} ${string} ${string}` | UnitValue;
+}
+/**
+ * CSS-like style descriptor for a run, paragraph, cell, or table.
+ *
+ * Combines text, paragraph, and cell-level properties.
+ * This is the user-facing style type — individual compiler functions
+ * narrow to {@link TextStyleRule}, {@link ParagraphStyleRule}, or
+ * {@link CellStyleRule} as appropriate.
+ */
+interface DocxStyleRule extends CellStyleRule, ParagraphStyleRule, TextStyleRule {}
+/**
+ * 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';
+/**
+ * Paragraph-level style properties.
+ *
+ * Used by {@link compileParagraphStyle} for `Paragraph` construction.
+ */
+interface ParagraphStyleRule {
+  /** 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;
+  /** Keep lines together on same page. */
+  keepLines?: boolean;
+  /** Keep this paragraph with the next one. */
+  keepNext?: boolean;
+  /** 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;
+  /** Horizontal text alignment. */
+  textAlign?: TextAlign;
+  /** First-line indent. */
+  textIndent?: 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;
+}
+/**
+ * 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, StyleSheetEntry>;
+/**
+ * A single entry in the stylesheet.
+ *
+ * Extends {@link DocxStyleRule} with an optional `extends` property
+ * that allows style classes to inherit from other classes.
+ *
+ * @example
+ * ```ts
+ * defineStyles({
+ *   baseText: { fontFamily: 'Arial', fontSize: 12, color: '#333' },
+ *   heading:  { extends: 'baseText', fontSize: 20, fontWeight: 'bold' },
+ *   muted:    { extends: 'baseText', color: '#888' },
+ * })
+ * ```
+ */
+interface StyleSheetEntry extends DocxStyleRule {
+  /** Inherit style properties from one or more other style classes. */
+  extends?: string | string[];
+}
+/** Horizontal text alignment. */
+type TextAlign = 'center' | 'justify' | 'left' | 'right';
+/**
+ * Text-level style properties (font, color, size, weight, etc.).
+ *
+ * Used by {@link compileTextStyle} for `TextRun` construction.
+ *
+ * @remarks
+ * Convenience boolean shortcuts `bold` and `italic` are provided
+ * alongside the canonical `fontWeight` / `fontStyle` properties.
+ * When `bold: true` is set, it is equivalent to `fontWeight: 'bold'`.
+ * When `italic: true` is set, it is equivalent to `fontStyle: 'italic'`.
+ */
+interface TextStyleRule {
+  /** Force text to uppercase (small caps-like). */
+  allCaps?: boolean;
+  /** Background / shading color (hex, named, or theme token like `"$colors.info"`). */
+  backgroundColor?: HexColor | StyleToken<string>;
+  /**
+   * Convenience boolean: `true` maps to `fontWeight: 'bold'`.
+   * Takes precedence over `fontWeight` when both are set.
+   */
+  bold?: boolean;
+  /** Character spacing (letter-spacing). */
+  characterSpacing?: number;
+  /** Text / foreground color (hex, named, or theme token like `"$colors.primary"`). */
+  color?: HexColor | StyleToken<string>;
+  /**
+   * 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 (e.g. `"Arial"`, or theme token like `"$fonts.heading"`).
+   */
+  fontFamily?: StyleToken<LiteralUnion<'Arial' | 'Calibri' | 'Times New Roman'>>;
+  /** Font size (bare number = pt). */
+  fontSize?: UnitValue;
+  /** Italic toggle (canonical form). Use `italic?: boolean` for convenience. */
+  fontStyle?: 'italic' | 'normal';
+  /** Font weight: keyword `"bold"` / `"normal"` or numeric 100–900. */
+  fontWeight?: FontWeight;
+  /** Text highlight color (background marker). */
+  highlight?: HighlightColor;
+  /**
+   * Convenience boolean: `true` maps to `fontStyle: 'italic'`.
+   * Takes precedence over `fontStyle` when both are set.
+   */
+  italic?: boolean;
+  /** Character spacing. */
+  letterSpacing?: UnitValue;
+  /** Small caps text variant. */
+  smallCaps?: boolean;
+  /** Strikethrough toggle. */
+  strike?: boolean;
+  /** Sub-script text. */
+  subScript?: boolean;
+  /** Super-script text. */
+  superScript?: boolean;
+  /** Underline style. */
+  underline?: 'double' | 'single' | boolean;
+}
+/** Vertical alignment (for table cells). */
+type VerticalAlign = 'bottom' | 'middle' | 'top';
+//#endregion
+//#region ../../packages/types/dist/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 ../../packages/types/dist/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 via `$category.key` syntax.
+ *
+ * Allows defining a single source of truth for colors, fonts,
+ * font sizes, and spacing values. Token references are resolved
+ * at compile time by {@link resolveThemeTokens}.
+ */
+interface DocxTheme {
+  /** Color palette tokens (name → hex). */
+  colors?: ThemeColors;
+  /** Font family tokens (name → font family string). */
+  fonts?: ThemeFonts;
+  /** Font size tokens (name → value). */
+  fontSize?: Record<string, UnitValue>;
+  /** Spacing tokens (name → value). */
+  spacing?: ThemeSpacing;
+}
+/**
+ * Header/footer configuration for a section.
+ *
+ * Supports standard, first-page, and even-page variants.
+ */
+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.
+ *
+ * Supports both simple text strings (backward compatible, each maps to a `Paragraph`)
+ * and full {@link BlockNode} elements (paragraphs, images, tables, etc.).
+ */
+interface HeaderFooterContent {
+  /** Content items — strings (simple) or BlockNode objects (rich). */
+  children: (string | BlockNode)[];
+}
+/** 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.
+ */
+interface SectionConfig {
+  /** Section footer(s). */
+  footer?: HeaderFooterConfig;
+  /** Section header(s). */
+  header?: HeaderFooterConfig;
+  /** Section-specific page dimensions (overrides document-level `page`). */
+  page?: PageConfig;
+}
+/**
+ * Theme color palette — semantic color tokens referenced by name.
+ */
+interface ThemeColors {
+  [name: string]: string;
+}
+/**
+ * Theme font tokens — semantic font family names.
+ */
+interface ThemeFonts {
+  [name: string]: string;
+}
+/**
+ * Theme spacing tokens — named spacing values.
+ */
+interface ThemeSpacing {
+  [name: string]: UnitValue;
+}
+//#endregion
+//#region ../../packages/types/dist/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
+ * @template TRender — The render output type produced by the plugin
+ */
+interface DocxPlugin<TName extends string = string, TOptions = unknown, TRender = 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<TRender>;
+}
+/**
+ * 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.
+       *
+       * @param blob - The image data as a Blob
+       * @returns A promise that resolves to a Uint8Array of the 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>;
+    };
+  };
+}
+//#endregion
+//#region src/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, unknown>;
+//#endregion
+export { CoverPageOptions, coverPagePlugin };

package/dist/index.js

@@ -0,0 +1,124 @@
+import { definePlugin } from "@docxkit/core";
+import { AlignmentType, BorderStyle, Paragraph, ShadingType, TextRun } from "docx";
+//#region src/index.ts
+/**
+* Cover Page plugin — generates a professional title page.
+*
+* Renders a centered block with title, subtitle, author, date,
+* organization, and an optional decorative horizontal rule.
+*
+* @module plugins/cover-page
+*
+* @example
+* ```ts
+* const doc = createDocx()
+*   .use(coverPagePlugin())
+*   .plugin('coverPage', {
+*     title: 'Q3 运营报告',
+*     subtitle: '数据驱动 · 智能决策',
+*     author: '数据分析部',
+*   })
+*   .save('report.docx')
+* ```
+*/
+/**
+* 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 科技集团',
+*   })
+* ```
+*/
+function coverPagePlugin() {
+	return definePlugin({
+		name: "coverPage",
+		render(options) {
+			const alignment = options.alignment ?? AlignmentType.CENTER;
+			const showRule = options.showRule !== false;
+			const titlePara = new Paragraph({
+				alignment,
+				spacing: { after: 200 },
+				children: [new TextRun({
+					bold: true,
+					font: "Arial",
+					size: 56,
+					text: options.title
+				})],
+				...options.backgroundColor ? { shading: {
+					fill: options.backgroundColor,
+					type: ShadingType.CLEAR
+				} } : {}
+			});
+			return [
+				new Paragraph({
+					children: [],
+					spacing: { before: 2400 }
+				}),
+				titlePara,
+				...options.subtitle ? [new Paragraph({
+					alignment,
+					spacing: { after: 400 },
+					children: [new TextRun({
+						color: "555555",
+						font: "Arial",
+						size: 32,
+						text: options.subtitle
+					})]
+				})] : [],
+				...showRule ? [new Paragraph({
+					alignment,
+					children: [],
+					spacing: { after: 400 },
+					border: { bottom: {
+						color: "4472C4",
+						size: 6,
+						space: 1,
+						style: BorderStyle.SINGLE
+					} }
+				})] : [],
+				...options.author ? [new Paragraph({
+					alignment,
+					spacing: { after: 120 },
+					children: [new TextRun({
+						font: "Arial",
+						size: 28,
+						text: options.author
+					})]
+				})] : [],
+				...options.organization ? [new Paragraph({
+					alignment,
+					spacing: { after: 120 },
+					children: [new TextRun({
+						color: "333333",
+						font: "Arial",
+						size: 24,
+						text: options.organization
+					})]
+				})] : [],
+				...options.date ? [new Paragraph({
+					alignment,
+					spacing: { after: 0 },
+					children: [new TextRun({
+						color: "777777",
+						font: "Arial",
+						size: 24,
+						text: options.date
+					})]
+				})] : []
+			];
+		}
+	});
+}
+//#endregion
+export { coverPagePlugin };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@docxkit/plugin-cover-page",
+  "type": "module",
+  "version": "0.3.0",
+  "description": "Professional cover/title page — docx-kit plugin",
+  "keywords": [
+    "docx",
+    "docx-kit",
+    "docx-kit-plugin"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "ntnyq",
+    "email": "ntnyq13@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ntnyq/docx-kit",
+    "directory": "packages-plugins/cover-page"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "docx": "^9.7.1",
+    "@docxkit/core": "0.3.0"
+  },
+  "devDependencies": {
+    "@docxkit/pdk": "0.3.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch"
+  }
+}