docxmlater 10.1.3 → 10.1.5

package/src/elements/Shape.ts

@@ -1,873 +1,884 @@
-/**
- * Shape - Represents a drawing shape in a Word document
- *
- * Shapes use DrawingML (a:) and WordprocessingML Drawing (wp:) namespaces,
- * plus WordprocessingShape (wps:) namespace for Word 2010+ shape features.
- *
- * Per ECMA-376 Part 4 (Transitional) and Office Open XML extensions,
- * shapes in Word documents use the wps:wsp element structure.
- */
-
-import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
-import { inchesToEmus, pointsToHalfPoints } from '../utils/units';
-import { RunFormatting } from './Run';
-import {
-  ImagePosition,
-  ImageAnchor,
-  PositionAnchor,
-  HorizontalAlignment,
-  VerticalAlignment
-} from './Image';
-
-/**
- * Preset shape types available in DrawingML
- * Based on ECMA-376 Part 1 §20.1.10.56 ST_ShapeType
- */
-export type ShapeType =
-  | 'rect'              // Rectangle
-  | 'ellipse'           // Circle/Ellipse
-  | 'rightArrow'        // Right arrow
-  | 'leftArrow'         // Left arrow
-  | 'upArrow'           // Up arrow
-  | 'downArrow'         // Down arrow
-  | 'straightConnector1' // Straight line
-  | 'roundRect'         // Rounded rectangle
-  | 'triangle'          // Triangle
-  | 'diamond';          // Diamond
-
-/**
- * Shape fill configuration
- */
-export interface ShapeFill {
-  /** Fill color in hex (e.g., 'FF0000' for red) */
-  color: string;
-  /** Transparency percentage (0-100, where 100 is fully transparent) */
-  transparency?: number;
-}
-
-/**
- * Shape outline/border configuration
- */
-export interface ShapeOutline {
-  /** Outline color in hex */
-  color: string;
-  /** Outline width in EMUs */
-  width: number;
-  /** Line dash style */
-  style?: 'solid' | 'dash' | 'dot' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'sysDash' | 'sysDot' | 'sysDashDot' | 'sysDashDotDot';
-  /** Line cap style (ECMA-376 §20.1.10.31) */
-  cap?: 'flat' | 'rnd' | 'sq';
-  /** Line join style (ECMA-376 §20.1.10.32) */
-  join?: 'bevel' | 'miter' | 'round';
-  /** Compound line type (ECMA-376 §20.1.10.15) */
-  compound?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri';
-}
-
-/**
- * Shape properties
- */
-export interface ShapeProperties {
-  /** Shape type (preset geometry) */
-  shapeType: ShapeType;
-  /** Width in EMUs */
-  width: number;
-  /** Height in EMUs */
-  height: number;
-  /** Fill color and transparency */
-  fill?: ShapeFill;
-  /** Outline/border properties */
-  outline?: ShapeOutline;
-  /** Position configuration (reuses Image position types) */
-  position?: ImagePosition;
-  /** Anchor configuration (reuses Image anchor types) */
-  anchor?: ImageAnchor;
-  /** Rotation angle in degrees (0-360) */
-  rotation?: number;
-  /** Text content within the shape */
-  text?: string;
-  /** Text formatting */
-  textFormatting?: RunFormatting;
-  /** Shape name/title */
-  name?: string;
-  /** Shape description (for accessibility) */
-  description?: string;
-}
-
-/**
- * Represents a drawing shape
- */
-export class Shape {
-  private shapeType: ShapeType;
-  private width: number;
-  private height: number;
-  private fill?: ShapeFill;
-  private outline?: ShapeOutline;
-  private position?: ImagePosition;
-  private anchor?: ImageAnchor;
-  private rotation = 0;
-  private text?: string;
-  private textFormatting?: RunFormatting;
-  private name: string;
-  private description: string;
-  private docPrId = 1;
-
-  /**
-   * Creates a new shape
-   * @param properties Shape properties
-   * @private Use static factory methods instead (create, createRectangle, etc.)
-   */
-  private constructor(properties: ShapeProperties) {
-    this.shapeType = properties.shapeType;
-    this.width = properties.width;
-    this.height = properties.height;
-    this.fill = properties.fill;
-    this.outline = properties.outline;
-    this.position = properties.position;
-    this.anchor = properties.anchor;
-    this.rotation = properties.rotation || 0;
-    this.text = properties.text;
-    this.textFormatting = properties.textFormatting;
-    this.name = properties.name || 'Shape';
-    this.description = properties.description || '';
-  }
-
-  /**
-   * Factory method for creating a shape
-   * @param shapeType Shape type
-   * @param width Width in EMUs (or use inchesToEmus)
-   * @param height Height in EMUs (or use inchesToEmus)
-   * @returns New Shape instance
-   * @example
-   * const rect = Shape.create('rect', inchesToEmus(2), inchesToEmus(1));
-   */
-  static create(shapeType: ShapeType, width: number, height: number): Shape {
-    return new Shape({ shapeType, width, height });
-  }
-
-  /**
-   * Creates a rectangle shape
-   * @param width Width in EMUs
-   * @param height Height in EMUs
-   * @returns New Shape instance
-   */
-  static createRectangle(width: number, height: number): Shape {
-    return Shape.create('rect', width, height);
-  }
-
-  /**
-   * Creates a circle shape
-   * @param diameter Diameter in EMUs
-   * @returns New Shape instance
-   */
-  static createCircle(diameter: number): Shape {
-    return Shape.create('ellipse', diameter, diameter);
-  }
-
-  /**
-   * Creates an ellipse shape
-   * @param width Width in EMUs
-   * @param height Height in EMUs
-   * @returns New Shape instance
-   */
-  static createEllipse(width: number, height: number): Shape {
-    return Shape.create('ellipse', width, height);
-  }
-
-  /**
-   * Creates an arrow shape
-   * @param direction Arrow direction
-   * @param width Width in EMUs
-   * @param height Height in EMUs
-   * @returns New Shape instance
-   */
-  static createArrow(
-    direction: 'right' | 'left' | 'up' | 'down',
-    width: number,
-    height: number
-  ): Shape {
-    const shapeType = `${direction}Arrow` as ShapeType;
-    return Shape.create(shapeType, width, height);
-  }
-
-  /**
-   * Creates a line shape
-   * @param width Line width in EMUs
-   * @returns New Shape instance
-   */
-  static createLine(width: number): Shape {
-    // Lines are typically very thin in height
-    return Shape.create('straightConnector1', width, 12700); // 12700 EMU ≈ 1pt height
-  }
-
-  /**
-   * Gets the shape type
-   * @returns Shape type
-   */
-  getShapeType(): ShapeType {
-    return this.shapeType;
-  }
-
-  /**
-   * Gets the shape width in EMUs
-   * @returns Width
-   */
-  getWidth(): number {
-    return this.width;
-  }
-
-  /**
-   * Gets the shape height in EMUs
-   * @returns Height
-   */
-  getHeight(): number {
-    return this.height;
-  }
-
-  /**
-   * Sets the shape fill color
-   * @param color Fill color in hex (e.g., 'FF0000')
-   * @param transparency Optional transparency percentage (0-100)
-   * @returns This shape for chaining
-   */
-  setFill(color: string, transparency?: number): this {
-    this.fill = { color, transparency };
-    return this;
-  }
-
-  /**
-   * Gets the fill configuration
-   * @returns Fill or undefined
-   */
-  getFill(): ShapeFill | undefined {
-    return this.fill;
-  }
-
-  /**
-   * Sets the shape outline
-   * @param color Outline color in hex
-   * @param width Outline width in EMUs
-   * @param style Line style
-   * @returns This shape for chaining
-   */
-  setOutline(color: string, width: number, style?: 'solid' | 'dash' | 'dot' | 'dashDot'): this {
-    this.outline = { color, width, style: style || 'solid' };
-    return this;
-  }
-
-  /**
-   * Gets the outline configuration
-   * @returns Outline or undefined
-   */
-  getOutline(): ShapeOutline | undefined {
-    return this.outline;
-  }
-
-  /**
-   * Sets shape position (for floating shapes)
-   * @param horizontal Horizontal positioning configuration
-   * @param vertical Vertical positioning configuration
-   * @returns This shape for chaining
-   */
-  setPosition(
-    horizontal: { anchor: PositionAnchor; offset?: number; alignment?: HorizontalAlignment },
-    vertical: { anchor: PositionAnchor; offset?: number; alignment?: VerticalAlignment }
-  ): this {
-    this.position = { horizontal, vertical };
-    return this;
-  }
-
-  /**
-   * Gets the position configuration
-   * @returns Position or undefined
-   */
-  getPosition(): ImagePosition | undefined {
-    return this.position;
-  }
-
-  /**
-   * Sets anchor configuration (converts shape to floating)
-   * @param options Anchor configuration
-   * @returns This shape for chaining
-   */
-  setAnchor(options: ImageAnchor): this {
-    this.anchor = options;
-    return this;
-  }
-
-  /**
-   * Gets the anchor configuration
-   * @returns Anchor configuration or undefined
-   */
-  getAnchor(): ImageAnchor | undefined {
-    return this.anchor;
-  }
-
-  /**
-   * Sets the rotation angle
-   * @param degrees Rotation in degrees (0-360)
-   * @returns This shape for chaining
-   */
-  setRotation(degrees: number): this {
-    this.rotation = ((degrees % 360) + 360) % 360;
-    return this;
-  }
-
-  /**
-   * Gets the rotation angle
-   * @returns Rotation in degrees
-   */
-  getRotation(): number {
-    return this.rotation;
-  }
-
-  /**
-   * Sets text content within the shape
-   * @param text Text content
-   * @param formatting Optional text formatting
-   * @returns This shape for chaining
-   */
-  setText(text: string, formatting?: RunFormatting): this {
-    this.text = text;
-    if (formatting) {
-      this.textFormatting = formatting;
-    }
-    return this;
-  }
-
-  /**
-   * Gets the text content
-   * @returns Text or undefined
-   */
-  getText(): string | undefined {
-    return this.text;
-  }
-
-  /**
-   * Sets the shape name
-   * @param name Shape name
-   * @returns This shape for chaining
-   */
-  setName(name: string): this {
-    this.name = name;
-    return this;
-  }
-
-  /**
-   * Gets the shape name
-   * @returns Shape name
-   */
-  getName(): string {
-    return this.name;
-  }
-
-  /**
-   * Sets the shape description (for accessibility)
-   * @param description Shape description
-   * @returns This shape for chaining
-   */
-  setDescription(description: string): this {
-    this.description = description;
-    return this;
-  }
-
-  /**
-   * Gets the shape description
-   * @returns Shape description
-   */
-  getDescription(): string {
-    return this.description;
-  }
-
-  /**
-   * Sets the docPr ID (drawing object ID)
-   * @param id Document property ID
-   * @returns This shape for chaining
-   */
-  setDocPrId(id: number): this {
-    this.docPrId = id;
-    return this;
-  }
-
-  /**
-   * Checks if this shape is floating (has anchor or position configuration)
-   * @returns True if floating, false if inline
-   */
-  isFloating(): boolean {
-    return this.anchor !== undefined || this.position !== undefined;
-  }
-
-  /**
-   * Generates DrawingML XML for the shape
-   * Creates either inline or floating (anchor) shape based on configuration
-   * @returns XML element representing the shape
-   */
-  toXML(): XMLElement {
-    // Choose between inline and anchor based on configuration
-    const shapeElement = this.isFloating() ? this.createAnchor() : this.createInline();
-
-    // Create the drawing structure
-    return XMLBuilder.w('drawing', undefined, [shapeElement]);
-  }
-
-  /**
-   * Creates the wp:inline element for inline shapes
-   * @private
-   */
-  private createInline(): XMLElement {
-    const children: XMLElement[] = [];
-
-    // Extent (size)
-    children.push({
-      name: 'wp:extent',
-      attributes: {
-        cx: this.width.toString(),
-        cy: this.height.toString(),
-      },
-      selfClosing: true,
-    });
-
-    // Effect extent (set to 0 for shapes)
-    children.push({
-      name: 'wp:effectExtent',
-      attributes: {
-        l: '0',
-        t: '0',
-        r: '0',
-        b: '0',
-      },
-      selfClosing: true,
-    });
-
-    // Document properties
-    children.push({
-      name: 'wp:docPr',
-      attributes: {
-        id: this.docPrId.toString(),
-        name: this.name,
-        descr: this.description,
-      },
-      selfClosing: true,
-    });
-
-    // Non-visual graphic frame properties
-    children.push({
-      name: 'wp:cNvGraphicFramePr',
-      selfClosing: true,
-    });
-
-    // Graphic data (the actual shape)
-    children.push(this.createGraphic());
-
-    return {
-      name: 'wp:inline',
-      attributes: {
-        distT: '0',
-        distB: '0',
-        distL: '0',
-        distR: '0',
-      },
-      children,
-    };
-  }
-
-  /**
-   * Creates the wp:anchor element for floating shapes
-   * @private
-   */
-  private createAnchor(): XMLElement {
-    const children: XMLElement[] = [];
-
-    const anchorConfig = this.anchor || {
-      behindDoc: false,
-      locked: false,
-      layoutInCell: true,
-      allowOverlap: false,
-      relativeHeight: 251658240,
-    };
-
-    // simplePos (required first child per CT_Anchor)
-    children.push({
-      name: 'wp:simplePos',
-      attributes: { x: '0', y: '0' },
-      selfClosing: true,
-    });
-
-    // Position H (horizontal)
-    if (this.position) {
-      const posH = this.position.horizontal;
-      const posHChildren: XMLElement[] = [];
-
-      if (posH.offset !== undefined) {
-        posHChildren.push({
-          name: 'wp:posOffset',
-          children: [posH.offset.toString()],
-        });
-      } else if (posH.alignment) {
-        posHChildren.push({
-          name: 'wp:align',
-          children: [posH.alignment],
-        });
-      }
-
-      children.push({
-        name: 'wp:positionH',
-        attributes: {
-          relativeFrom: posH.anchor,
-        },
-        children: posHChildren,
-      });
-    }
-
-    // Position V (vertical)
-    if (this.position) {
-      const posV = this.position.vertical;
-      const posVChildren: XMLElement[] = [];
-
-      if (posV.offset !== undefined) {
-        posVChildren.push({
-          name: 'wp:posOffset',
-          children: [posV.offset.toString()],
-        });
-      } else if (posV.alignment) {
-        posVChildren.push({
-          name: 'wp:align',
-          children: [posV.alignment],
-        });
-      }
-
-      children.push({
-        name: 'wp:positionV',
-        attributes: {
-          relativeFrom: posV.anchor,
-        },
-        children: posVChildren,
-      });
-    }
-
-    // Extent (size)
-    children.push({
-      name: 'wp:extent',
-      attributes: {
-        cx: this.width.toString(),
-        cy: this.height.toString(),
-      },
-      selfClosing: true,
-    });
-
-    // Effect extent
-    children.push({
-      name: 'wp:effectExtent',
-      attributes: {
-        l: '0',
-        t: '0',
-        r: '0',
-        b: '0',
-      },
-      selfClosing: true,
-    });
-
-    // Wrap square (default for shapes)
-    children.push({
-      name: 'wp:wrapSquare',
-      attributes: {
-        wrapText: 'bothSides',
-      },
-      selfClosing: true,
-    });
-
-    // Document properties
-    children.push({
-      name: 'wp:docPr',
-      attributes: {
-        id: this.docPrId.toString(),
-        name: this.name,
-        descr: this.description,
-      },
-      selfClosing: true,
-    });
-
-    // Non-visual graphic frame properties
-    children.push({
-      name: 'wp:cNvGraphicFramePr',
-      selfClosing: true,
-    });
-
-    // Graphic data (the actual shape)
-    children.push(this.createGraphic());
-
-    return {
-      name: 'wp:anchor',
-      attributes: {
-        distT: '0',
-        distB: '0',
-        distL: '0',
-        distR: '0',
-        simplePos: '0',
-        relativeHeight: anchorConfig.relativeHeight.toString(),
-        behindDoc: anchorConfig.behindDoc ? '1' : '0',
-        locked: anchorConfig.locked ? '1' : '0',
-        layoutInCell: anchorConfig.layoutInCell ? '1' : '0',
-        allowOverlap: anchorConfig.allowOverlap ? '1' : '0',
-      },
-      children,
-    };
-  }
-
-  /**
-   * Creates the a:graphic element containing the shape
-   * @private
-   */
-  private createGraphic(): XMLElement {
-    return {
-      name: 'a:graphic',
-      attributes: {
-        'xmlns:a': 'http://schemas.openxmlformats.org/drawingml/2006/main',
-      },
-      children: [
-        {
-          name: 'a:graphicData',
-          attributes: {
-            uri: 'http://schemas.microsoft.com/office/word/2010/wordprocessingShape',
-          },
-          children: [this.createWps()],
-        },
-      ],
-    };
-  }
-
-  /**
-   * Creates the wps:wsp element (WordprocessingShape)
-   * @private
-   */
-  private createWps(): XMLElement {
-    const children: XMLElement[] = [];
-
-    // Non-visual shape properties
-    children.push({
-      name: 'wps:cNvSpPr',
-      attributes: {
-        'xmlns:wps': 'http://schemas.microsoft.com/office/word/2010/wordprocessingShape',
-      },
-      selfClosing: true,
-    });
-
-    // Shape properties (geometry, fill, outline)
-    children.push(this.createSpPr());
-
-    // Text box (if text is present)
-    if (this.text) {
-      children.push(this.createTextBox());
-    }
-
-    // Body properties (required per CT_WordprocessingShape)
-    children.push({
-      name: 'wps:bodyPr',
-      attributes: {
-        rot: '0',
-        vert: 'horz',
-        wrap: 'square',
-        lIns: '91440',
-        tIns: '45720',
-        rIns: '91440',
-        bIns: '45720',
-        anchor: 't',
-        anchorCtr: '0',
-        upright: '1',
-      },
-      selfClosing: true,
-    });
-
-    return {
-      name: 'wps:wsp',
-      attributes: {
-        'xmlns:wps': 'http://schemas.microsoft.com/office/word/2010/wordprocessingShape',
-      },
-      children,
-    };
-  }
-
-  /**
-   * Creates the wps:spPr element (shape properties)
-   * @private
-   */
-  private createSpPr(): XMLElement {
-    const children: XMLElement[] = [];
-
-    // Transform (position and size)
-    const xfrmAttrs = this.rotation > 0 ? { rot: (this.rotation * 60000).toString() } : undefined;
-    children.push({
-      name: 'a:xfrm',
-      attributes: xfrmAttrs,
-      children: [
-        {
-          name: 'a:off',
-          attributes: { x: '0', y: '0' },
-          selfClosing: true,
-        },
-        {
-          name: 'a:ext',
-          attributes: {
-            cx: this.width.toString(),
-            cy: this.height.toString(),
-          },
-          selfClosing: true,
-        },
-      ],
-    });
-
-    // Preset geometry (shape type)
-    children.push({
-      name: 'a:prstGeom',
-      attributes: {
-        prst: this.shapeType,
-      },
-      children: [
-        {
-          name: 'a:avLst',
-          selfClosing: true,
-        },
-      ],
-    });
-
-    // Fill
-    if (this.fill) {
-      const fillChildren: XMLElement[] = [];
-
-      // Color
-      const colorAttrs: Record<string, string> = {
-        val: this.fill.color.toUpperCase(),
-      };
-
-      // Transparency (alpha percentage)
-      if (this.fill.transparency !== undefined) {
-        // Convert 0-100 to 0-100000 (percentage * 1000)
-        const alpha = 100 - this.fill.transparency; // Invert (0=transparent, 100=opaque)
-        fillChildren.push({
-          name: 'a:alpha',
-          attributes: {
-            val: Math.round(alpha * 1000).toString(),
-          },
-          selfClosing: true,
-        });
-      }
-
-      children.push({
-        name: 'a:solidFill',
-        children: [
-          {
-            name: 'a:srgbClr',
-            attributes: colorAttrs,
-            ...(fillChildren.length > 0 ? { children: fillChildren } : { selfClosing: true }),
-          },
-        ],
-      });
-    }
-
-    // Outline
-    if (this.outline) {
-      const lnAttrs: Record<string, string> = {
-        w: this.outline.width.toString(),
-      };
-      if (this.outline.cap) lnAttrs.cap = this.outline.cap;
-      if (this.outline.compound) lnAttrs.cmpd = this.outline.compound;
-
-      const lnChildren: XMLElement[] = [];
-
-      // Outline color
-      lnChildren.push({
-        name: 'a:solidFill',
-        children: [
-          {
-            name: 'a:srgbClr',
-            attributes: {
-              val: this.outline.color.toUpperCase(),
-            },
-            selfClosing: true,
-          },
-        ],
-      });
-
-      // Line style (prstDash)
-      if (this.outline.style && this.outline.style !== 'solid') {
-        lnChildren.push({
-          name: 'a:prstDash',
-          attributes: {
-            val: this.outline.style,
-          },
-          selfClosing: true,
-        });
-      }
-
-      // Line join style
-      if (this.outline.join) {
-        const joinNames = { bevel: 'a:bevel', miter: 'a:miter', round: 'a:round' } as const;
-        const joinName = joinNames[this.outline.join];
-        if (joinName) {
-          lnChildren.push({
-            name: joinName,
-            selfClosing: true,
-          });
-        }
-      }
-
-      children.push({
-        name: 'a:ln',
-        attributes: lnAttrs,
-        children: lnChildren,
-      });
-    }
-
-    return {
-      name: 'wps:spPr',
-      children,
-    };
-  }
-
-  /**
-   * Creates the wps:txbx element (text box within shape)
-   * @private
-   */
-  private createTextBox(): XMLElement {
-    if (!this.text) {
-      return { name: 'wps:txbx', selfClosing: true };
-    }
-
-    // Build run properties
-    const rPrChildren: XMLElement[] = [];
-    if (this.textFormatting) {
-      if (this.textFormatting.bold) {
-        rPrChildren.push(XMLBuilder.wSelf('b'));
-      }
-      if (this.textFormatting.italic) {
-        rPrChildren.push(XMLBuilder.wSelf('i'));
-      }
-      if (this.textFormatting.color) {
-        rPrChildren.push(XMLBuilder.wSelf('color', { 'w:val': this.textFormatting.color }));
-      }
-      if (this.textFormatting.size) {
-        const halfPoints = pointsToHalfPoints(this.textFormatting.size);
-        rPrChildren.push(XMLBuilder.wSelf('sz', { 'w:val': halfPoints }));
-        rPrChildren.push(XMLBuilder.wSelf('szCs', { 'w:val': halfPoints }));
-      }
-    }
-
-    // Build paragraph with run
-    const runChildren: XMLElement[] = [];
-    if (rPrChildren.length > 0) {
-      runChildren.push(XMLBuilder.w('rPr', undefined, rPrChildren));
-    }
-    runChildren.push(XMLBuilder.w('t', { 'xml:space': 'preserve' }, [this.text]));
-
-    const paragraph = XMLBuilder.w('p', undefined, [XMLBuilder.w('r', undefined, runChildren)]);
-
-    return {
-      name: 'wps:txbx',
-      children: [
-        {
-          name: 'w:txbxContent',
-          children: [paragraph],
-        },
-      ],
-    };
-  }
-}
+/**
+ * Shape - Represents a drawing shape in a Word document
+ *
+ * Shapes use DrawingML (a:) and WordprocessingML Drawing (wp:) namespaces,
+ * plus WordprocessingShape (wps:) namespace for Word 2010+ shape features.
+ *
+ * Per ECMA-376 Part 4 (Transitional) and Office Open XML extensions,
+ * shapes in Word documents use the wps:wsp element structure.
+ */
+
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
+import { inchesToEmus, pointsToHalfPoints } from '../utils/units';
+import { RunFormatting } from './Run';
+import {
+  ImagePosition,
+  ImageAnchor,
+  PositionAnchor,
+  HorizontalAlignment,
+  VerticalAlignment,
+} from './Image';
+
+/**
+ * Preset shape types available in DrawingML
+ * Based on ECMA-376 Part 1 §20.1.10.56 ST_ShapeType
+ */
+export type ShapeType =
+  | 'rect' // Rectangle
+  | 'ellipse' // Circle/Ellipse
+  | 'rightArrow' // Right arrow
+  | 'leftArrow' // Left arrow
+  | 'upArrow' // Up arrow
+  | 'downArrow' // Down arrow
+  | 'straightConnector1' // Straight line
+  | 'roundRect' // Rounded rectangle
+  | 'triangle' // Triangle
+  | 'diamond'; // Diamond
+
+/**
+ * Shape fill configuration
+ */
+export interface ShapeFill {
+  /** Fill color in hex (e.g., 'FF0000' for red) */
+  color: string;
+  /** Transparency percentage (0-100, where 100 is fully transparent) */
+  transparency?: number;
+}
+
+/**
+ * Shape outline/border configuration
+ */
+export interface ShapeOutline {
+  /** Outline color in hex */
+  color: string;
+  /** Outline width in EMUs */
+  width: number;
+  /** Line dash style */
+  style?:
+    | 'solid'
+    | 'dash'
+    | 'dot'
+    | 'dashDot'
+    | 'lgDash'
+    | 'lgDashDot'
+    | 'lgDashDotDot'
+    | 'sysDash'
+    | 'sysDot'
+    | 'sysDashDot'
+    | 'sysDashDotDot';
+  /** Line cap style (ECMA-376 §20.1.10.31) */
+  cap?: 'flat' | 'rnd' | 'sq';
+  /** Line join style (ECMA-376 §20.1.10.32) */
+  join?: 'bevel' | 'miter' | 'round';
+  /** Compound line type (ECMA-376 §20.1.10.15) */
+  compound?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri';
+}
+
+/**
+ * Shape properties
+ */
+export interface ShapeProperties {
+  /** Shape type (preset geometry) */
+  shapeType: ShapeType;
+  /** Width in EMUs */
+  width: number;
+  /** Height in EMUs */
+  height: number;
+  /** Fill color and transparency */
+  fill?: ShapeFill;
+  /** Outline/border properties */
+  outline?: ShapeOutline;
+  /** Position configuration (reuses Image position types) */
+  position?: ImagePosition;
+  /** Anchor configuration (reuses Image anchor types) */
+  anchor?: ImageAnchor;
+  /** Rotation angle in degrees (0-360) */
+  rotation?: number;
+  /** Text content within the shape */
+  text?: string;
+  /** Text formatting */
+  textFormatting?: RunFormatting;
+  /** Shape name/title */
+  name?: string;
+  /** Shape description (for accessibility) */
+  description?: string;
+}
+
+/**
+ * Represents a drawing shape
+ */
+export class Shape {
+  private shapeType: ShapeType;
+  private width: number;
+  private height: number;
+  private fill?: ShapeFill;
+  private outline?: ShapeOutline;
+  private position?: ImagePosition;
+  private anchor?: ImageAnchor;
+  private rotation = 0;
+  private text?: string;
+  private textFormatting?: RunFormatting;
+  private name: string;
+  private description: string;
+  private docPrId = 1;
+
+  /**
+   * Creates a new shape
+   * @param properties Shape properties
+   * @private Use static factory methods instead (create, createRectangle, etc.)
+   */
+  private constructor(properties: ShapeProperties) {
+    this.shapeType = properties.shapeType;
+    this.width = properties.width;
+    this.height = properties.height;
+    this.fill = properties.fill;
+    this.outline = properties.outline;
+    this.position = properties.position;
+    this.anchor = properties.anchor;
+    this.rotation = properties.rotation || 0;
+    this.text = properties.text;
+    this.textFormatting = properties.textFormatting;
+    this.name = properties.name || 'Shape';
+    this.description = properties.description || '';
+  }
+
+  /**
+   * Factory method for creating a shape
+   * @param shapeType Shape type
+   * @param width Width in EMUs (or use inchesToEmus)
+   * @param height Height in EMUs (or use inchesToEmus)
+   * @returns New Shape instance
+   * @example
+   * const rect = Shape.create('rect', inchesToEmus(2), inchesToEmus(1));
+   */
+  static create(shapeType: ShapeType, width: number, height: number): Shape {
+    return new Shape({ shapeType, width, height });
+  }
+
+  /**
+   * Creates a rectangle shape
+   * @param width Width in EMUs
+   * @param height Height in EMUs
+   * @returns New Shape instance
+   */
+  static createRectangle(width: number, height: number): Shape {
+    return Shape.create('rect', width, height);
+  }
+
+  /**
+   * Creates a circle shape
+   * @param diameter Diameter in EMUs
+   * @returns New Shape instance
+   */
+  static createCircle(diameter: number): Shape {
+    return Shape.create('ellipse', diameter, diameter);
+  }
+
+  /**
+   * Creates an ellipse shape
+   * @param width Width in EMUs
+   * @param height Height in EMUs
+   * @returns New Shape instance
+   */
+  static createEllipse(width: number, height: number): Shape {
+    return Shape.create('ellipse', width, height);
+  }
+
+  /**
+   * Creates an arrow shape
+   * @param direction Arrow direction
+   * @param width Width in EMUs
+   * @param height Height in EMUs
+   * @returns New Shape instance
+   */
+  static createArrow(
+    direction: 'right' | 'left' | 'up' | 'down',
+    width: number,
+    height: number
+  ): Shape {
+    const shapeType = `${direction}Arrow` as ShapeType;
+    return Shape.create(shapeType, width, height);
+  }
+
+  /**
+   * Creates a line shape
+   * @param width Line width in EMUs
+   * @returns New Shape instance
+   */
+  static createLine(width: number): Shape {
+    // Lines are typically very thin in height
+    return Shape.create('straightConnector1', width, 12700); // 12700 EMU ≈ 1pt height
+  }
+
+  /**
+   * Gets the shape type
+   * @returns Shape type
+   */
+  getShapeType(): ShapeType {
+    return this.shapeType;
+  }
+
+  /**
+   * Gets the shape width in EMUs
+   * @returns Width
+   */
+  getWidth(): number {
+    return this.width;
+  }
+
+  /**
+   * Gets the shape height in EMUs
+   * @returns Height
+   */
+  getHeight(): number {
+    return this.height;
+  }
+
+  /**
+   * Sets the shape fill color
+   * @param color Fill color in hex (e.g., 'FF0000')
+   * @param transparency Optional transparency percentage (0-100)
+   * @returns This shape for chaining
+   */
+  setFill(color: string, transparency?: number): this {
+    this.fill = { color, transparency };
+    return this;
+  }
+
+  /**
+   * Gets the fill configuration
+   * @returns Fill or undefined
+   */
+  getFill(): ShapeFill | undefined {
+    return this.fill;
+  }
+
+  /**
+   * Sets the shape outline
+   * @param color Outline color in hex
+   * @param width Outline width in EMUs
+   * @param style Line style
+   * @returns This shape for chaining
+   */
+  setOutline(color: string, width: number, style?: 'solid' | 'dash' | 'dot' | 'dashDot'): this {
+    this.outline = { color, width, style: style || 'solid' };
+    return this;
+  }
+
+  /**
+   * Gets the outline configuration
+   * @returns Outline or undefined
+   */
+  getOutline(): ShapeOutline | undefined {
+    return this.outline;
+  }
+
+  /**
+   * Sets shape position (for floating shapes)
+   * @param horizontal Horizontal positioning configuration
+   * @param vertical Vertical positioning configuration
+   * @returns This shape for chaining
+   */
+  setPosition(
+    horizontal: { anchor: PositionAnchor; offset?: number; alignment?: HorizontalAlignment },
+    vertical: { anchor: PositionAnchor; offset?: number; alignment?: VerticalAlignment }
+  ): this {
+    this.position = { horizontal, vertical };
+    return this;
+  }
+
+  /**
+   * Gets the position configuration
+   * @returns Position or undefined
+   */
+  getPosition(): ImagePosition | undefined {
+    return this.position;
+  }
+
+  /**
+   * Sets anchor configuration (converts shape to floating)
+   * @param options Anchor configuration
+   * @returns This shape for chaining
+   */
+  setAnchor(options: ImageAnchor): this {
+    this.anchor = options;
+    return this;
+  }
+
+  /**
+   * Gets the anchor configuration
+   * @returns Anchor configuration or undefined
+   */
+  getAnchor(): ImageAnchor | undefined {
+    return this.anchor;
+  }
+
+  /**
+   * Sets the rotation angle
+   * @param degrees Rotation in degrees (0-360)
+   * @returns This shape for chaining
+   */
+  setRotation(degrees: number): this {
+    this.rotation = ((degrees % 360) + 360) % 360;
+    return this;
+  }
+
+  /**
+   * Gets the rotation angle
+   * @returns Rotation in degrees
+   */
+  getRotation(): number {
+    return this.rotation;
+  }
+
+  /**
+   * Sets text content within the shape
+   * @param text Text content
+   * @param formatting Optional text formatting
+   * @returns This shape for chaining
+   */
+  setText(text: string, formatting?: RunFormatting): this {
+    this.text = text;
+    if (formatting) {
+      this.textFormatting = formatting;
+    }
+    return this;
+  }
+
+  /**
+   * Gets the text content
+   * @returns Text or undefined
+   */
+  getText(): string | undefined {
+    return this.text;
+  }
+
+  /**
+   * Sets the shape name
+   * @param name Shape name
+   * @returns This shape for chaining
+   */
+  setName(name: string): this {
+    this.name = name;
+    return this;
+  }
+
+  /**
+   * Gets the shape name
+   * @returns Shape name
+   */
+  getName(): string {
+    return this.name;
+  }
+
+  /**
+   * Sets the shape description (for accessibility)
+   * @param description Shape description
+   * @returns This shape for chaining
+   */
+  setDescription(description: string): this {
+    this.description = description;
+    return this;
+  }
+
+  /**
+   * Gets the shape description
+   * @returns Shape description
+   */
+  getDescription(): string {
+    return this.description;
+  }
+
+  /**
+   * Sets the docPr ID (drawing object ID)
+   * @param id Document property ID
+   * @returns This shape for chaining
+   */
+  setDocPrId(id: number): this {
+    this.docPrId = id;
+    return this;
+  }
+
+  /**
+   * Checks if this shape is floating (has anchor or position configuration)
+   * @returns True if floating, false if inline
+   */
+  isFloating(): boolean {
+    return this.anchor !== undefined || this.position !== undefined;
+  }
+
+  /**
+   * Generates DrawingML XML for the shape
+   * Creates either inline or floating (anchor) shape based on configuration
+   * @returns XML element representing the shape
+   */
+  toXML(): XMLElement {
+    // Choose between inline and anchor based on configuration
+    const shapeElement = this.isFloating() ? this.createAnchor() : this.createInline();
+
+    // Create the drawing structure
+    return XMLBuilder.w('drawing', undefined, [shapeElement]);
+  }
+
+  /**
+   * Creates the wp:inline element for inline shapes
+   * @private
+   */
+  private createInline(): XMLElement {
+    const children: XMLElement[] = [];
+
+    // Extent (size)
+    children.push({
+      name: 'wp:extent',
+      attributes: {
+        cx: this.width.toString(),
+        cy: this.height.toString(),
+      },
+      selfClosing: true,
+    });
+
+    // Effect extent (set to 0 for shapes)
+    children.push({
+      name: 'wp:effectExtent',
+      attributes: {
+        l: '0',
+        t: '0',
+        r: '0',
+        b: '0',
+      },
+      selfClosing: true,
+    });
+
+    // Document properties
+    children.push({
+      name: 'wp:docPr',
+      attributes: {
+        id: this.docPrId.toString(),
+        name: this.name,
+        descr: this.description,
+      },
+      selfClosing: true,
+    });
+
+    // Non-visual graphic frame properties
+    children.push({
+      name: 'wp:cNvGraphicFramePr',
+      selfClosing: true,
+    });
+
+    // Graphic data (the actual shape)
+    children.push(this.createGraphic());
+
+    return {
+      name: 'wp:inline',
+      attributes: {
+        distT: '0',
+        distB: '0',
+        distL: '0',
+        distR: '0',
+      },
+      children,
+    };
+  }
+
+  /**
+   * Creates the wp:anchor element for floating shapes
+   * @private
+   */
+  private createAnchor(): XMLElement {
+    const children: XMLElement[] = [];
+
+    const anchorConfig = this.anchor || {
+      behindDoc: false,
+      locked: false,
+      layoutInCell: true,
+      allowOverlap: false,
+      relativeHeight: 251658240,
+    };
+
+    // simplePos (required first child per CT_Anchor)
+    children.push({
+      name: 'wp:simplePos',
+      attributes: { x: '0', y: '0' },
+      selfClosing: true,
+    });
+
+    // Position H (horizontal)
+    if (this.position) {
+      const posH = this.position.horizontal;
+      const posHChildren: XMLElement[] = [];
+
+      if (posH.offset !== undefined) {
+        posHChildren.push({
+          name: 'wp:posOffset',
+          children: [posH.offset.toString()],
+        });
+      } else if (posH.alignment) {
+        posHChildren.push({
+          name: 'wp:align',
+          children: [posH.alignment],
+        });
+      }
+
+      children.push({
+        name: 'wp:positionH',
+        attributes: {
+          relativeFrom: posH.anchor,
+        },
+        children: posHChildren,
+      });
+    }
+
+    // Position V (vertical)
+    if (this.position) {
+      const posV = this.position.vertical;
+      const posVChildren: XMLElement[] = [];
+
+      if (posV.offset !== undefined) {
+        posVChildren.push({
+          name: 'wp:posOffset',
+          children: [posV.offset.toString()],
+        });
+      } else if (posV.alignment) {
+        posVChildren.push({
+          name: 'wp:align',
+          children: [posV.alignment],
+        });
+      }
+
+      children.push({
+        name: 'wp:positionV',
+        attributes: {
+          relativeFrom: posV.anchor,
+        },
+        children: posVChildren,
+      });
+    }
+
+    // Extent (size)
+    children.push({
+      name: 'wp:extent',
+      attributes: {
+        cx: this.width.toString(),
+        cy: this.height.toString(),
+      },
+      selfClosing: true,
+    });
+
+    // Effect extent
+    children.push({
+      name: 'wp:effectExtent',
+      attributes: {
+        l: '0',
+        t: '0',
+        r: '0',
+        b: '0',
+      },
+      selfClosing: true,
+    });
+
+    // Wrap square (default for shapes)
+    children.push({
+      name: 'wp:wrapSquare',
+      attributes: {
+        wrapText: 'bothSides',
+      },
+      selfClosing: true,
+    });
+
+    // Document properties
+    children.push({
+      name: 'wp:docPr',
+      attributes: {
+        id: this.docPrId.toString(),
+        name: this.name,
+        descr: this.description,
+      },
+      selfClosing: true,
+    });
+
+    // Non-visual graphic frame properties
+    children.push({
+      name: 'wp:cNvGraphicFramePr',
+      selfClosing: true,
+    });
+
+    // Graphic data (the actual shape)
+    children.push(this.createGraphic());
+
+    return {
+      name: 'wp:anchor',
+      attributes: {
+        distT: '0',
+        distB: '0',
+        distL: '0',
+        distR: '0',
+        simplePos: '0',
+        relativeHeight: anchorConfig.relativeHeight.toString(),
+        behindDoc: anchorConfig.behindDoc ? '1' : '0',
+        locked: anchorConfig.locked ? '1' : '0',
+        layoutInCell: anchorConfig.layoutInCell ? '1' : '0',
+        allowOverlap: anchorConfig.allowOverlap ? '1' : '0',
+      },
+      children,
+    };
+  }
+
+  /**
+   * Creates the a:graphic element containing the shape
+   * @private
+   */
+  private createGraphic(): XMLElement {
+    return {
+      name: 'a:graphic',
+      attributes: {
+        'xmlns:a': 'http://schemas.openxmlformats.org/drawingml/2006/main',
+      },
+      children: [
+        {
+          name: 'a:graphicData',
+          attributes: {
+            uri: 'http://schemas.microsoft.com/office/word/2010/wordprocessingShape',
+          },
+          children: [this.createWps()],
+        },
+      ],
+    };
+  }
+
+  /**
+   * Creates the wps:wsp element (WordprocessingShape)
+   * @private
+   */
+  private createWps(): XMLElement {
+    const children: XMLElement[] = [];
+
+    // Non-visual shape properties
+    children.push({
+      name: 'wps:cNvSpPr',
+      attributes: {
+        'xmlns:wps': 'http://schemas.microsoft.com/office/word/2010/wordprocessingShape',
+      },
+      selfClosing: true,
+    });
+
+    // Shape properties (geometry, fill, outline)
+    children.push(this.createSpPr());
+
+    // Text box (if text is present)
+    if (this.text) {
+      children.push(this.createTextBox());
+    }
+
+    // Body properties (required per CT_WordprocessingShape)
+    children.push({
+      name: 'wps:bodyPr',
+      attributes: {
+        rot: '0',
+        vert: 'horz',
+        wrap: 'square',
+        lIns: '91440',
+        tIns: '45720',
+        rIns: '91440',
+        bIns: '45720',
+        anchor: 't',
+        anchorCtr: '0',
+        upright: '1',
+      },
+      selfClosing: true,
+    });
+
+    return {
+      name: 'wps:wsp',
+      attributes: {
+        'xmlns:wps': 'http://schemas.microsoft.com/office/word/2010/wordprocessingShape',
+      },
+      children,
+    };
+  }
+
+  /**
+   * Creates the wps:spPr element (shape properties)
+   * @private
+   */
+  private createSpPr(): XMLElement {
+    const children: XMLElement[] = [];
+
+    // Transform (position and size)
+    const xfrmAttrs = this.rotation > 0 ? { rot: (this.rotation * 60000).toString() } : undefined;
+    children.push({
+      name: 'a:xfrm',
+      attributes: xfrmAttrs,
+      children: [
+        {
+          name: 'a:off',
+          attributes: { x: '0', y: '0' },
+          selfClosing: true,
+        },
+        {
+          name: 'a:ext',
+          attributes: {
+            cx: this.width.toString(),
+            cy: this.height.toString(),
+          },
+          selfClosing: true,
+        },
+      ],
+    });
+
+    // Preset geometry (shape type)
+    children.push({
+      name: 'a:prstGeom',
+      attributes: {
+        prst: this.shapeType,
+      },
+      children: [
+        {
+          name: 'a:avLst',
+          selfClosing: true,
+        },
+      ],
+    });
+
+    // Fill
+    if (this.fill) {
+      const fillChildren: XMLElement[] = [];
+
+      // Color
+      const colorAttrs: Record<string, string> = {
+        val: this.fill.color.toUpperCase(),
+      };
+
+      // Transparency (alpha percentage)
+      if (this.fill.transparency !== undefined) {
+        // Convert 0-100 to 0-100000 (percentage * 1000)
+        const alpha = 100 - this.fill.transparency; // Invert (0=transparent, 100=opaque)
+        fillChildren.push({
+          name: 'a:alpha',
+          attributes: {
+            val: Math.round(alpha * 1000).toString(),
+          },
+          selfClosing: true,
+        });
+      }
+
+      children.push({
+        name: 'a:solidFill',
+        children: [
+          {
+            name: 'a:srgbClr',
+            attributes: colorAttrs,
+            ...(fillChildren.length > 0 ? { children: fillChildren } : { selfClosing: true }),
+          },
+        ],
+      });
+    }
+
+    // Outline
+    if (this.outline) {
+      const lnAttrs: Record<string, string> = {
+        w: this.outline.width.toString(),
+      };
+      if (this.outline.cap) lnAttrs.cap = this.outline.cap;
+      if (this.outline.compound) lnAttrs.cmpd = this.outline.compound;
+
+      const lnChildren: XMLElement[] = [];
+
+      // Outline color
+      lnChildren.push({
+        name: 'a:solidFill',
+        children: [
+          {
+            name: 'a:srgbClr',
+            attributes: {
+              val: this.outline.color.toUpperCase(),
+            },
+            selfClosing: true,
+          },
+        ],
+      });
+
+      // Line style (prstDash)
+      if (this.outline.style && this.outline.style !== 'solid') {
+        lnChildren.push({
+          name: 'a:prstDash',
+          attributes: {
+            val: this.outline.style,
+          },
+          selfClosing: true,
+        });
+      }
+
+      // Line join style
+      if (this.outline.join) {
+        const joinNames = { bevel: 'a:bevel', miter: 'a:miter', round: 'a:round' } as const;
+        const joinName = joinNames[this.outline.join];
+        if (joinName) {
+          lnChildren.push({
+            name: joinName,
+            selfClosing: true,
+          });
+        }
+      }
+
+      children.push({
+        name: 'a:ln',
+        attributes: lnAttrs,
+        children: lnChildren,
+      });
+    }
+
+    return {
+      name: 'wps:spPr',
+      children,
+    };
+  }
+
+  /**
+   * Creates the wps:txbx element (text box within shape)
+   * @private
+   */
+  private createTextBox(): XMLElement {
+    if (!this.text) {
+      return { name: 'wps:txbx', selfClosing: true };
+    }
+
+    // Build run properties
+    const rPrChildren: XMLElement[] = [];
+    if (this.textFormatting) {
+      if (this.textFormatting.bold) {
+        rPrChildren.push(XMLBuilder.wSelf('b'));
+      }
+      if (this.textFormatting.italic) {
+        rPrChildren.push(XMLBuilder.wSelf('i'));
+      }
+      if (this.textFormatting.color) {
+        rPrChildren.push(XMLBuilder.wSelf('color', { 'w:val': this.textFormatting.color }));
+      }
+      if (this.textFormatting.size) {
+        const halfPoints = pointsToHalfPoints(this.textFormatting.size);
+        rPrChildren.push(XMLBuilder.wSelf('sz', { 'w:val': halfPoints }));
+        rPrChildren.push(XMLBuilder.wSelf('szCs', { 'w:val': halfPoints }));
+      }
+    }
+
+    // Build paragraph with run
+    const runChildren: XMLElement[] = [];
+    if (rPrChildren.length > 0) {
+      runChildren.push(XMLBuilder.w('rPr', undefined, rPrChildren));
+    }
+    runChildren.push(XMLBuilder.w('t', { 'xml:space': 'preserve' }, [this.text]));
+
+    const paragraph = XMLBuilder.w('p', undefined, [XMLBuilder.w('r', undefined, runChildren)]);
+
+    return {
+      name: 'wps:txbx',
+      children: [
+        {
+          name: 'w:txbxContent',
+          children: [paragraph],
+        },
+      ],
+    };
+  }
+}