@docxkit/plugin-barcode 0.4.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,16 @@
+# @docxkit/plugin-barcode
+
+Linear barcode generation plugin for docx-kit.
+
+## Usage
+
+```ts
+import { barcodePlugin } from '@docxkit/plugin-barcode'
+
+const doc = createDocx()
+  .use(barcodePlugin())
+  .plugin('barcode', {
+    format: 'code128',
+    text: 'DOCX-KIT-2026',
+  })
+```

package/dist/index.d.ts

@@ -0,0 +1,1107 @@
+import { LiteralUnion } from "@docxkit/core";
+//#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$1<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;
+  /** Line width (bare number treated as pt). */
+  width?: UnitValue;
+}
+/** Available border line styles. */
+type BorderStyle = '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;
+  /** Outline level used by Word navigation and table-of-contents fields (0–9). */
+  outlineLevel?: number;
+  /** Force page break before this paragraph. */
+  pageBreakBefore?: boolean;
+  /** Custom tab stops for this paragraph. */
+  tabStops?: TabStopRule[];
+  /** Horizontal text alignment. */
+  textAlign?: TextAlign;
+  /** First-line indent. */
+  textIndent?: UnitValue;
+  /** Prevent isolated first or last lines across page boundaries. */
+  widowControl?: boolean;
+  /**
+   * 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[];
+}
+/** A paragraph tab stop. */
+interface TabStopRule {
+  /** Position from the paragraph's left edge. */
+  position: UnitValue;
+  /** Optional leader characters before the tab stop. */
+  leader?: 'dot' | 'hyphen' | 'middleDot' | 'none' | 'underscore';
+  /** Tab alignment. */
+  type: 'bar' | 'center' | 'clear' | 'decimal' | 'end' | 'left' | 'num' | 'right' | 'start';
+}
+/** 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;
+  /** Raw OOXML character spacing in twips. Prefer `letterSpacing` for CSS units. */
+  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>;
+  /** Double strikethrough toggle. */
+  doubleStrike?: boolean;
+  /** Embossed text effect. */
+  emboss?: boolean;
+  /**
+   * Font family name (e.g. `"Arial"`, or theme token like `"$fonts.heading"`).
+   */
+  fontFamily?: StyleToken<LiteralUnion$1<'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;
+  /** Imprinted (engraved) text effect. */
+  imprint?: boolean;
+  /**
+   * Convenience boolean: `true` maps to `fontStyle: 'italic'`.
+   * Takes precedence over `fontStyle` when both are set.
+   */
+  italic?: boolean;
+  /** CSS-like character spacing with unit conversion. */
+  letterSpacing?: UnitValue;
+  /** Right-to-left run direction. */
+  rightToLeft?: boolean;
+  /** 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> = BookmarkNode<TStyles> | BulletListNode<TStyles> | CheckboxNode<TStyles> | ColumnBreakNode | CommentNode<TStyles> | FootnoteNode<TStyles> | HeadingNode<TStyles> | HyperlinkNode<TStyles> | ImageNode<TStyles> | MathNode | NumberedListNode<TStyles> | PageBreakNode | ParagraphNode<TStyles> | PluginNode<string, unknown, TStyles> | RevisionNode<TStyles> | SectionBreakNode | TableNode<Record<string, unknown>, TStyles> | TextBoxNode<TStyles> | ThematicBreakNode<TStyles>;
+/**
+ * A named bookmark that can be targeted by an internal hyperlink.
+ */
+interface BookmarkNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Text or styled text runs contained by the bookmark. */
+  children: (string | TextNode<TStyles>)[];
+  /** Stable bookmark name. */
+  name: string;
+  type: 'bookmark';
+}
+/**
+ * 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> {
+  /** Optional inline children override (instead of text). */
+  children?: InlineNode<TStyles>[];
+  /** Per-item nested list level (0–8). Overrides the list-level default. */
+  level?: number;
+  /** Item text content, used when `children` is absent. */
+  text?: string;
+}
+/**
+ * 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;
+}
+/**
+ * A Word checkbox content control.
+ */
+interface CheckboxNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  type: 'checkbox';
+  /** Accessible alias for the checkbox control. */
+  alias?: string;
+  /** Whether the checkbox is checked. */
+  checked?: boolean;
+  /** Checked-state glyph and font. */
+  checkedState?: CheckboxSymbol;
+  /** Optional label rendered after the checkbox. */
+  label?: string;
+  /** Unchecked-state glyph and font. */
+  uncheckedState?: CheckboxSymbol;
+}
+/** Checkbox glyph customization. */
+interface CheckboxSymbol {
+  /** Font containing the glyph. */
+  font?: string;
+  /** Unicode code point expressed as a hexadecimal string. */
+  value?: string;
+}
+/**
+ * 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 forced column break.
+ */
+interface ColumnBreakNode {
+  type: 'columnBreak';
+}
+/**
+ * An annotated content range backed by a Word comment.
+ */
+interface CommentNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Comment author. */
+  author: string;
+  /** Annotated inline content. */
+  children: InlineNode<TStyles>[];
+  /** Comment body paragraphs or plain text. */
+  comment: (string | ParagraphNode<TStyles>)[];
+  type: 'comment';
+  /** ISO-8601 creation timestamp. */
+  date?: string;
+  /** Author initials. */
+  initials?: string;
+}
+/**
+ * A footnote reference and its document-level footnote content.
+ */
+interface FootnoteNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Footnote body paragraphs or plain text. */
+  content: (string | ParagraphNode<TStyles>)[];
+  type: 'footnote';
+}
+/**
+ * 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';
+  /** Internal bookmark target (used instead of `url`). */
+  anchor?: string;
+  /** External 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> = BookmarkNode<TStyles> | CheckboxNode<TStyles> | CommentNode<TStyles> | FootnoteNode<TStyles> | HyperlinkNode<TStyles> | ImageNode<TStyles> | MathNode | RevisionNode<TStyles> | TextNode<TStyles>;
+/**
+ * A recursive expression used by {@link MathNode}.
+ */
+type MathExpression = MathFractionExpression | MathFunctionExpression | MathIntegralExpression | MathRadicalExpression | MathScriptExpression | MathSumExpression | MathTextExpression;
+/** A mathematical fraction. */
+interface MathFractionExpression {
+  denominator: MathExpression[];
+  numerator: MathExpression[];
+  type: 'fraction';
+}
+/** A named mathematical function. */
+interface MathFunctionExpression {
+  arguments: MathExpression[];
+  name: MathExpression[];
+  type: 'function';
+}
+/** A mathematical integral. */
+interface MathIntegralExpression {
+  children: MathExpression[];
+  type: 'integral';
+  subScript?: MathExpression[];
+  superScript?: MathExpression[];
+}
+/**
+ * An Office Math (OMML) expression.
+ */
+interface MathNode {
+  /** Structured mathematical expression tree. */
+  children: MathExpression[];
+  type: 'math';
+}
+/** A mathematical radical with an optional degree. */
+interface MathRadicalExpression {
+  children: MathExpression[];
+  type: 'radical';
+  degree?: MathExpression[];
+}
+/** Subscript, superscript, or combined script. */
+interface MathScriptExpression {
+  children: MathExpression[];
+  type: 'script';
+  subScript?: MathExpression[];
+  superScript?: MathExpression[];
+}
+/** A mathematical sum. */
+interface MathSumExpression {
+  children: MathExpression[];
+  type: 'sum';
+  subScript?: MathExpression[];
+  superScript?: MathExpression[];
+}
+/** Plain text inside a mathematical expression. */
+interface MathTextExpression {
+  text: string;
+  type: 'text';
+}
+/**
+ * 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';
+}
+/**
+ * An inserted or deleted text revision.
+ */
+interface RevisionNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Revision author. */
+  author: string;
+  /** Text or styled text runs in the revision. */
+  children: (string | TextNode<TStyles>)[];
+  /** ISO-8601 revision timestamp. */
+  date: string;
+  /** Document-unique revision identifier. */
+  revisionId: number;
+  /** Revision kind. */
+  type: 'deletedText' | 'insertedText';
+}
+/**
+ * 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;
+}
+/** Table-level border configuration. */
+interface TableBordersConfig {
+  bottom?: BorderRule;
+  insideHorizontal?: BorderRule;
+  insideVertical?: BorderRule;
+  left?: BorderRule;
+  right?: BorderRule;
+  top?: BorderRule;
+}
+/** Per-cell style resolver. */
+type TableCellStyleResolver<TData extends Record<string, unknown> = Record<string, unknown>> = (value: TData[keyof TData], row: TData, rowIndex: number, column: TableColumn<TData>) => DocxStyleRule;
+/**
+ * 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';
+  /** Per-column data cell style or resolver. */
+  cellStyle?: DocxStyleRule | TableCellStyleResolver<TData>;
+  /**
+   * Span multiple columns horizontally.
+   *
+   * Applied to all cells in this column.
+   */
+  colSpan?: number;
+  /** Per-column header cell style. */
+  headerCellStyle?: DocxStyleRule;
+  /**
+   * Span multiple rows vertically (per-cell via data hints).
+   *
+   * Set a keyed `_${key}_rowSpan: N` hint on an individual data object,
+   * use `_rowSpan: N` for every cell in that row, or keep this 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[];
+}
+/** Floating table positioning. */
+interface TableFloatingOptions {
+  /** Bottom distance from surrounding text. */
+  bottomFromText?: UnitValue;
+  /** Horizontal anchor. */
+  horizontalAnchor?: 'margin' | 'page' | 'text';
+  /** Left distance from surrounding text. */
+  leftFromText?: UnitValue;
+  /** Whether the table may overlap other floating objects. */
+  overlap?: boolean;
+  /** Right distance from surrounding text. */
+  rightFromText?: UnitValue;
+  /** Top distance from surrounding text. */
+  topFromText?: UnitValue;
+  /** Vertical anchor. */
+  verticalAnchor?: 'margin' | 'page' | 'text';
+  /** Absolute horizontal offset. */
+  x?: UnitValue;
+  /** Absolute vertical offset. */
+  y?: UnitValue;
+  /** Relative horizontal placement. */
+  relativeHorizontalPosition?: 'center' | 'inside' | 'left' | 'outside' | 'right';
+  /** Relative vertical placement. */
+  relativeVerticalPosition?: 'bottom' | 'center' | 'inline' | 'inside' | 'outside' | 'top';
+}
+/** Native Word table-look flags. */
+interface TableLookOptions {
+  firstColumn?: boolean;
+  firstRow?: boolean;
+  lastColumn?: boolean;
+  lastRow?: boolean;
+  noHBand?: boolean;
+  noVBand?: boolean;
+}
+/**
+ * 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';
+  /** Horizontal table alignment. */
+  alignment?: 'center' | 'left' | 'right';
+  /** Show table borders. */
+  bordered?: boolean;
+  /** Explicit outer and inner table borders. */
+  borders?: TableBordersConfig;
+  /** Default data cell style or per-cell resolver. */
+  cellStyle?: DocxStyleRule | TableCellStyleResolver<TData>;
+  /** Floating table positioning. Enables side-by-side layouts. */
+  floating?: TableFloatingOptions;
+  /** Show header row (default: `true`). */
+  header?: boolean;
+  /** Style for header cells. */
+  headerCellStyle?: DocxStyleRule;
+  /** Word table layout algorithm. */
+  layout?: 'autofit' | 'fixed';
+  /** Alternate row shading. */
+  striped?: boolean;
+  /** Native Word table style ID. */
+  styleName?: string;
+  /** Native Word table-look flags. */
+  tableLook?: TableLookOptions;
+  /** Render the table grid from right to left. */
+  visuallyRightToLeft?: boolean;
+  /** Overall table width. */
+  width?: UnitValue;
+}
+/**
+ * A legacy Word text box positioned as a block-level shape.
+ */
+interface TextBoxNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  /** Text box dimensions and positioning. */
+  box: TextBoxOptions;
+  type: 'textBox';
+  /** Inline children (used instead of `text`). */
+  children?: InlineNode<TStyles>[];
+  /** Plain text content. */
+  text?: string;
+}
+/** Text box dimensions and positioning. */
+interface TextBoxOptions {
+  /** Text box width. */
+  width: UnitValue;
+  /** Text box height. */
+  height?: UnitValue;
+  /** Horizontal offset. */
+  left?: UnitValue;
+  /** Shape positioning mode. */
+  position?: 'absolute' | 'relative' | 'static';
+  /** Vertical offset. */
+  top?: UnitValue;
+  /** Text wrapping behavior. */
+  wrap?: 'none' | 'square';
+}
+/**
+ * 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';
+}
+/**
+ * A horizontal thematic break rendered as a paragraph border.
+ */
+interface ThematicBreakNode<TStyles extends StyleSheet = StyleSheet> extends BaseNode<TStyles> {
+  type: 'thematicBreak';
+}
+//#endregion
+//#region ../../packages/types/dist/document.d.ts
+/** OOXML document properties shown in Word's File → Info panel. */
+interface DocumentMetadata {
+  /** Document author. */
+  creator?: string;
+  /** Application-specific string properties. */
+  customProperties?: Record<string, string>;
+  /** Document description / summary. */
+  description?: string;
+  /** Keywords / tags. */
+  keywords?: string[];
+  /** Last editor. */
+  lastModifiedBy?: string;
+  /** Document subject. */
+  subject?: string;
+  /** Document title. */
+  title?: string;
+}
+/**
+ * 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> {
+  /** Font files embedded into the generated DOCX package. */
+  fonts?: EmbeddedFont[];
+  /** OOXML core properties (appear in File → Info). */
+  metadata?: DocumentMetadata;
+  /** 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;
+  };
+  /** Document-level Word feature switches. */
+  features?: {
+    /** Enable tracked revision display and behavior. */
+    trackRevisions?: boolean;
+    /** Ask Word to update fields when the document opens. */
+    updateFields?: boolean;
+  };
+}
+/**
+ * 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;
+}
+/** A TrueType/OpenType font embedded into the DOCX package. */
+interface EmbeddedFont {
+  /** Raw font-file bytes. */
+  data: Uint8Array;
+  /** Font family name written to the OOXML font table. */
+  name: string;
+}
+/**
+ * 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 border configuration. */
+interface PageBorderConfig {
+  /** Bottom page border. */
+  bottom?: BorderRule;
+  /** Pages that display the border. */
+  display?: 'allPages' | 'firstPage' | 'notFirstPage';
+  /** Left page border. */
+  left?: BorderRule;
+  /** Measure border offsets from the page edge or text area. */
+  offsetFrom?: 'page' | 'text';
+  /** Right page border. */
+  right?: BorderRule;
+  /** Top page border. */
+  top?: BorderRule;
+  /** Render the border behind or in front of document content. */
+  zOrder?: 'back' | 'front';
+}
+/**
+ * Page configuration (size, orientation, margin).
+ */
+interface PageConfig {
+  /** Page border configuration. */
+  borders?: PageBorderConfig;
+  /** Distance between the footer and the page edge. */
+  footerDistance?: UnitValue;
+  /** Extra gutter width for binding. */
+  gutter?: UnitValue;
+  /** Distance between the header and the page edge. */
+  headerDistance?: UnitValue;
+  /** Page orientation (`"portrait"` default). */
+  orientation?: Orientation;
+  /** Page-number sequence configuration for this section. */
+  pageNumber?: PageNumberConfig;
+  /** 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;
+}
+/** Per-section page-number sequence configuration. */
+interface PageNumberConfig {
+  /** First page number in the section. */
+  start?: number;
+  /** Page number format. */
+  format?: 'decimal' | 'lowerLetter' | 'lowerRoman' | 'upperLetter' | 'upperRoman';
+}
+/** Available page size presets. */
+type PageSize = 'A3' | 'A4' | 'Legal' | 'Letter';
+/** An explicitly sized section column. */
+interface SectionColumn {
+  /** Column width. */
+  width: UnitValue;
+  /** Space after this column. */
+  spacing?: UnitValue;
+}
+/** Multi-column layout for a section. */
+interface SectionColumnsConfig {
+  /** Explicit column widths for unequal-width layouts. */
+  columns?: SectionColumn[];
+  /** Number of equal-width columns. */
+  count?: number;
+  /** Whether Word should keep columns equally sized. */
+  equalWidth?: boolean;
+  /** Draw a separator line between columns. */
+  separator?: boolean;
+  /** Default spacing between columns. */
+  spacing?: UnitValue;
+}
+/**
+ * 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 {
+  /** Multi-column layout. */
+  columns?: SectionColumnsConfig;
+  /** Section footer(s). */
+  footer?: HeaderFooterConfig;
+  /** Section header(s). */
+  header?: HeaderFooterConfig;
+  /** Line numbering. */
+  lineNumbers?: SectionLineNumberConfig;
+  /** Section-specific page dimensions (overrides document-level `page`). */
+  page?: PageConfig;
+  /** Section break behavior. */
+  type?: SectionType;
+}
+/** Line-numbering configuration for a section. */
+interface SectionLineNumberConfig {
+  /** Number every Nth line. */
+  countBy?: number;
+  /** Distance between line numbers and text. */
+  distance?: UnitValue;
+  /** When line numbering restarts. */
+  restart?: 'continuous' | 'newPage' | 'newSection';
+  /** Starting line number. */
+  start?: number;
+}
+/** Section break behavior. */
+type SectionType = 'continuous' | 'evenPage' | 'nextColumn' | 'nextPage' | 'oddPage';
+/**
+ * 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
+/** Common linear barcode formats, while retaining the full bwip-js catalog. */
+type BarcodeFormat = LiteralUnion<'code128' | 'code39' | 'code93' | 'ean13' | 'ean8' | 'interleaved2of5' | 'isbn' | 'itf14' | 'upca' | 'upce'>;
+/** Options for the barcode plugin. */
+interface BarcodeOptions {
+  /** Value encoded by the barcode. */
+  text: string;
+  /** Paragraph alignment. @default "center" */
+  alignment?: 'center' | 'left' | 'right';
+  /** Background color as a hex string. @default "#FFFFFF" */
+  backgroundColor?: string;
+  /** Bar color as a hex string. @default "#000000" */
+  barColor?: string;
+  /** Bar height in millimeters. @default 12 */
+  barHeight?: number;
+  /** Optional caption below the barcode. */
+  caption?: string;
+  /** Barcode symbology. @default "code128" */
+  format?: BarcodeFormat;
+  /** Include the human-readable value below the bars. @default true */
+  includeText?: boolean;
+  /** Barcode rotation. @default "N" */
+  rotate?: 'I' | 'L' | 'N' | 'R';
+  /** Rasterization scale. @default 3 */
+  scale?: number;
+  /** Human-readable text color as a hex string. */
+  textColor?: string;
+  /** Display width in pixels. Defaults to the natural width, capped at 320. */
+  width?: number;
+}
+/**
+ * Create a barcode plugin instance.
+ *
+ * @returns A configured plugin for the `barcode` node name
+ */
+declare function barcodePlugin(): DocxPlugin<"barcode", BarcodeOptions, unknown>;
+//#endregion
+export { BarcodeFormat, BarcodeOptions, barcodePlugin };

package/dist/index.js

@@ -0,0 +1,100 @@
+import { createImageRun, dataUrlToUint8Array, definePlugin } from "@docxkit/core";
+import { AlignmentType, Paragraph } from "docx";
+//#region src/index.ts
+/**
+* Barcode plugin — embeds a linear barcode image in the document.
+*
+* Uses the optional `bwip-js` peer dependency and selects its Node.js or
+* browser PNG renderer at runtime.
+*
+* @module plugins/barcode
+*/
+/**
+* Create a barcode plugin instance.
+*
+* @returns A configured plugin for the `barcode` node name
+*/
+function barcodePlugin() {
+	return definePlugin({
+		name: "barcode",
+		async render(options) {
+			const rendered = await renderBarcode(options);
+			const width = options.width ?? Math.min(rendered.width, 320);
+			const height = Math.max(1, Math.round(rendered.height * (width / rendered.width)));
+			const alignment = toAlignment(options.alignment);
+			const paragraphs = [new Paragraph({
+				alignment,
+				children: [createImageRun({
+					data: rendered.data,
+					height,
+					type: "png",
+					width
+				})]
+			})];
+			if (options.caption) paragraphs.push(new Paragraph({
+				alignment,
+				text: options.caption
+			}));
+			return paragraphs;
+		}
+	});
+}
+async function loadBarcodeRenderer() {
+	try {
+		const module = await import("bwip-js");
+		return module.default ?? module;
+	} catch (err) {
+		throw new Error("The barcode plugin requires the optional \"bwip-js\" package. Install it before rendering barcodes.", { cause: err });
+	}
+}
+function normalizeColor(color) {
+	return color.replace(/^#/, "");
+}
+function readPngDimensions(data) {
+	if (!(data.length >= 24 && data[0] === 137 && data[1] === 80 && data[2] === 78 && data[3] === 71)) throw new Error("bwip-js did not return a valid PNG barcode image.");
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	return {
+		height: view.getUint32(20),
+		width: view.getUint32(16)
+	};
+}
+async function renderBarcode(options) {
+	const renderer = await loadBarcodeRenderer();
+	const renderOptions = {
+		backgroundcolor: normalizeColor(options.backgroundColor ?? "#FFFFFF"),
+		barcolor: normalizeColor(options.barColor ?? "#000000"),
+		bcid: options.format ?? "code128",
+		height: options.barHeight ?? 12,
+		includetext: options.includeText ?? true,
+		rotate: options.rotate ?? "N",
+		scale: options.scale ?? 3,
+		text: options.text,
+		textxalign: "center",
+		...options.textColor ? { textcolor: normalizeColor(options.textColor) } : {}
+	};
+	if (renderer.toBuffer) {
+		const data = new Uint8Array(await renderer.toBuffer(renderOptions));
+		return {
+			data,
+			...readPngDimensions(data)
+		};
+	}
+	if (renderer.toCanvas && typeof document !== "undefined") {
+		const canvas = renderer.toCanvas(document.createElement("canvas"), renderOptions);
+		return {
+			data: await dataUrlToUint8Array(canvas.toDataURL("image/png")),
+			height: canvas.height,
+			width: canvas.width
+		};
+	}
+	throw new Error("No compatible bwip-js PNG renderer is available.");
+}
+function toAlignment(alignment) {
+	switch (alignment) {
+		case "left": return AlignmentType.LEFT;
+		case "right": return AlignmentType.RIGHT;
+		default: return AlignmentType.CENTER;
+	}
+}
+//#endregion
+export { barcodePlugin };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@docxkit/plugin-barcode",
+  "type": "module",
+  "version": "0.4.0",
+  "description": "Linear barcode generation — docx-kit plugin",
+  "keywords": [
+    "barcode",
+    "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/barcode"
+  },
+  "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": {
+    "bwip-js": ">=4.10.0",
+    "docx": "^9.7.1",
+    "@docxkit/core": "0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "bwip-js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "jszip": "^3.10.1",
+    "@docxkit/pdk": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch"
+  }
+}