/** * DOCX Module - Enhanced DrawingML Shape Builder * * Provides a comprehensive API for creating DrawingML shapes beyond the * basic shape type. Includes support for: * - All 187 preset geometry types * - Gradient and pattern fills * - Shadow, glow, reflection effects * - 3D rotation and bevel * - Shape connectors and groups * - Custom geometry paths * - Text body formatting within shapes */ import type { DrawingShape, Paragraph, HexColor, Emu, HorizontalPositionRelative, VerticalPositionRelative, WrapStyle, WrapTextSide } from "../types.js"; /** All standard OOXML preset shape types. */ export type StandardShapeType = "rect" | "roundRect" | "snip1Rect" | "snip2SameRect" | "snip2DiagRect" | "snipRoundRect" | "round1Rect" | "round2SameRect" | "round2DiagRect" | "ellipse" | "triangle" | "rtTriangle" | "parallelogram" | "trapezoid" | "diamond" | "pentagon" | "hexagon" | "heptagon" | "octagon" | "decagon" | "dodecagon" | "pie" | "chord" | "teardrop" | "frame" | "halfFrame" | "corner" | "diagStripe" | "plus" | "cross" | "cube" | "can" | "foldedCorner" | "smileyFace" | "heart" | "lightningBolt" | "sun" | "moon" | "cloud" | "arc" | "bracketPair" | "bracePair" | "plaque" | "donut" | "noSmoking" | "blockArc" | "gear6" | "gear9" | "rightArrow" | "leftArrow" | "upArrow" | "downArrow" | "leftRightArrow" | "upDownArrow" | "quadArrow" | "leftRightUpArrow" | "bentArrow" | "uturnArrow" | "leftUpArrow" | "bentUpArrow" | "curvedRightArrow" | "curvedLeftArrow" | "curvedUpArrow" | "curvedDownArrow" | "stripedRightArrow" | "notchedRightArrow" | "homePlate" | "chevron" | "rightArrowCallout" | "downArrowCallout" | "leftArrowCallout" | "upArrowCallout" | "leftRightArrowCallout" | "quadArrowCallout" | "circularArrow" | "flowChartProcess" | "flowChartAlternateProcess" | "flowChartDecision" | "flowChartInputOutput" | "flowChartPredefinedProcess" | "flowChartInternalStorage" | "flowChartDocument" | "flowChartMultidocument" | "flowChartTerminator" | "flowChartPreparation" | "flowChartManualInput" | "flowChartManualOperation" | "flowChartConnector" | "flowChartOffpageConnector" | "flowChartPunchedCard" | "flowChartPunchedTape" | "flowChartSummingJunction" | "flowChartOr" | "flowChartCollate" | "flowChartSort" | "flowChartExtract" | "flowChartMerge" | "flowChartOnlineStorage" | "flowChartDelay" | "flowChartMagneticTape" | "flowChartMagneticDisk" | "flowChartMagneticDrum" | "flowChartDisplay" | "wedgeRectCallout" | "wedgeRoundRectCallout" | "wedgeEllipseCallout" | "cloudCallout" | "borderCallout1" | "borderCallout2" | "borderCallout3" | "accentCallout1" | "accentCallout2" | "accentCallout3" | "callout1" | "callout2" | "callout3" | "accentBorderCallout1" | "accentBorderCallout2" | "accentBorderCallout3" | "irregularSeal1" | "irregularSeal2" | "star4" | "star5" | "star6" | "star7" | "star8" | "star10" | "star12" | "star16" | "star24" | "star32" | "ribbon" | "ribbon2" | "ellipseRibbon" | "ellipseRibbon2" | "verticalScroll" | "horizontalScroll" | "wave" | "doubleWave" | "mathPlus" | "mathMinus" | "mathMultiply" | "mathDivide" | "mathEqual" | "mathNotEqual" | "line" | "straightConnector1" | "bentConnector2" | "bentConnector3" | "bentConnector4" | "bentConnector5" | "curvedConnector2" | "curvedConnector3" | "curvedConnector4" | "curvedConnector5" | "actionButtonBlank" | "actionButtonHome" | "actionButtonHelp" | "actionButtonInformation" | "actionButtonBackPrevious" | "actionButtonForwardNext" | "actionButtonBeginning" | "actionButtonEnd" | "actionButtonReturn" | "actionButtonDocument" | "actionButtonSound" | "actionButtonMovie"; /** Solid fill. */ export interface SolidFill { readonly type: "solid"; readonly color: HexColor; /** Transparency (0-100, percent). */ readonly transparency?: number; } /** Gradient stop. */ export interface GradientStop { readonly position: number; readonly color: HexColor; readonly transparency?: number; } /** Gradient fill. */ export interface GradientFill { readonly type: "gradient"; readonly stops: readonly GradientStop[]; /** Angle in 60,000ths of a degree. 0 = left-to-right. */ readonly angle?: number; /** Gradient type: linear or radial (path). */ readonly gradientType?: "linear" | "radial"; } /** Pattern fill. */ export interface PatternFill { readonly type: "pattern"; /** Pattern preset (e.g. "pct10", "dkHorz", "ltVert", "dnDiag"). */ readonly preset: string; readonly foregroundColor: HexColor; readonly backgroundColor: HexColor; } /** No fill (transparent). */ export interface NoFill { readonly type: "none"; } /** Shape fill specification. */ export type ShapeFill = SolidFill | GradientFill | PatternFill | NoFill; /** Line dash style. */ export type LineDash = "solid" | "dot" | "dash" | "lgDash" | "dashDot" | "lgDashDot" | "lgDashDotDot" | "sysDot" | "sysDash" | "sysDashDot" | "sysDashDotDot"; /** Line end type (arrow head). */ export type LineEndType = "none" | "triangle" | "stealth" | "diamond" | "oval" | "arrow"; /** Line end size. */ export type LineEndSize = "sm" | "med" | "lg"; /** Line/outline specification. */ export interface ShapeOutline { /** Width in EMU. */ readonly width?: Emu; /** Color. */ readonly color?: HexColor; /** Dash style. */ readonly dash?: LineDash; /** Join type. */ readonly join?: "round" | "bevel" | "miter"; /** Head end (start of line). */ readonly headEnd?: { type: LineEndType; width?: LineEndSize; length?: LineEndSize; }; /** Tail end (end of line). */ readonly tailEnd?: { type: LineEndType; width?: LineEndSize; length?: LineEndSize; }; /** No outline. */ readonly noLine?: boolean; } /** Shadow effect. */ export interface ShadowEffect { readonly type: "outer" | "inner"; readonly color: HexColor; readonly transparency?: number; /** Blur radius in EMU. */ readonly blurRadius?: Emu; /** Distance in EMU. */ readonly distance?: Emu; /** Direction in 60,000ths of a degree. */ readonly direction?: number; } /** Glow effect. */ export interface GlowEffect { readonly color: HexColor; readonly transparency?: number; /** Radius in EMU. */ readonly radius: Emu; } /** Reflection effect. */ export interface ReflectionEffect { /** Blur radius in EMU. */ readonly blurRadius?: Emu; /** Start transparency (0-100). */ readonly startOpacity?: number; /** End transparency (0-100). */ readonly endOpacity?: number; /** Distance in EMU. */ readonly distance?: Emu; /** Direction in 60,000ths of a degree. */ readonly direction?: number; /** Fade direction. */ readonly fadeDirection?: number; } /** 3D effect. */ export interface Effect3D { /** Rotation on X/Y/Z axes (in 60,000ths of a degree). */ readonly rotX?: number; readonly rotY?: number; readonly rotZ?: number; /** Camera preset. */ readonly camera?: "orthographicFront" | "perspectiveFront" | "isometricTopDown" | "obliqueTopLeft"; /** Bevel top. */ readonly bevelTop?: { width: Emu; height: Emu; preset?: string; }; /** Bevel bottom. */ readonly bevelBottom?: { width: Emu; height: Emu; preset?: string; }; /** Extrusion depth in EMU. */ readonly extrusionDepth?: Emu; /** Extrusion color. */ readonly extrusionColor?: HexColor; } /** Shape effects. */ export interface ShapeEffects { readonly shadow?: ShadowEffect; readonly glow?: GlowEffect; readonly reflection?: ReflectionEffect; readonly effect3d?: Effect3D; /** Soft edges radius in EMU. */ readonly softEdges?: Emu; } /** Vertical text anchor. */ export type TextVerticalAnchor = "t" | "ctr" | "b"; /** Text wrapping type within shape. */ export type TextWrap = "none" | "square"; /** Text body configuration for shapes. */ export interface ShapeTextBody { /** Content paragraphs. */ readonly paragraphs: readonly Paragraph[]; /** Vertical alignment. */ readonly anchor?: TextVerticalAnchor; /** Wrap text within shape. */ readonly wrap?: TextWrap; /** Internal margins (EMU). */ readonly margins?: { readonly top?: Emu; readonly bottom?: Emu; readonly left?: Emu; readonly right?: Emu; }; /** Auto-fit text. */ readonly autoFit?: "none" | "normal" | "shrink"; /** Vertical text (for CJK). */ readonly vertical?: boolean; /** Number of columns. */ readonly columns?: number; /** Column spacing in EMU. */ readonly columnSpacing?: Emu; } /** Complete shape creation options. */ export interface CreateShapeOptions { /** Shape type (preset geometry). */ readonly shapeType: string; /** Width in EMU. */ readonly width: Emu; /** Height in EMU. */ readonly height: Emu; /** Fill specification. */ readonly fill?: ShapeFill; /** Outline specification. */ readonly outline?: ShapeOutline; /** Effects (shadow, glow, etc.). */ readonly effects?: ShapeEffects; /** Text content. */ readonly textBody?: ShapeTextBody; /** Alternative text (accessibility). */ readonly altText?: string; /** Shape name. */ readonly name?: string; /** Rotation in 60,000ths of a degree. */ readonly rotation?: number; /** Flip horizontally. */ readonly flipH?: boolean; /** Flip vertically. */ readonly flipV?: boolean; /** Horizontal position. */ readonly horizontalPosition?: { readonly relativeTo?: HorizontalPositionRelative; readonly offset?: Emu; readonly align?: "left" | "center" | "right"; }; /** Vertical position. */ readonly verticalPosition?: { readonly relativeTo?: VerticalPositionRelative; readonly offset?: Emu; readonly align?: "top" | "center" | "bottom"; }; /** Text wrapping. */ readonly wrap?: { readonly style: WrapStyle; readonly side?: WrapTextSide; }; /** Behind document text. */ readonly behindDoc?: boolean; } /** * Create an enhanced DrawingML shape with full styling options. * * Basic properties (solid fill, outline color/width, text paragraphs, positioning) * are mapped directly to the `DrawingShape` interface fields. Advanced properties * (gradient/pattern fills, effects, line details, text body formatting) are * serialized into the `rawXml` field for preservation during packaging. * * @param options - Complete shape creation options. * @returns A DrawingShape element for the document body. */ export declare function createShape(options: CreateShapeOptions): DrawingShape; /** * Create a simple rectangle shape. */ export declare function createRect(width: Emu, height: Emu, options?: Partial>): DrawingShape; /** * Create a rounded rectangle shape. */ export declare function createRoundRect(width: Emu, height: Emu, options?: Partial>): DrawingShape; /** * Create an ellipse/circle shape. */ export declare function createEllipse(width: Emu, height: Emu, options?: Partial>): DrawingShape; /** * Create a line connector. */ export declare function createLine(width: Emu, height: Emu, options?: Partial>): DrawingShape; /** * Create an arrow shape. */ export declare function createArrow(direction: "right" | "left" | "up" | "down", width: Emu, height: Emu, options?: Partial>): DrawingShape; /** * Create a flowchart shape. */ export declare function createFlowchartShape(kind: "process" | "decision" | "terminator" | "document" | "data" | "connector" | "preparation", width: Emu, height: Emu, options?: Partial>): DrawingShape; /** * Create a callout shape. */ export declare function createCallout(style: "rect" | "roundRect" | "ellipse" | "cloud", width: Emu, height: Emu, options?: Partial>): DrawingShape; /** * Create a star shape. */ export declare function createStar(points: 4 | 5 | 6 | 7 | 8 | 10 | 12 | 16 | 24 | 32, width: Emu, height: Emu, options?: Partial>): DrawingShape;