@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/cjs/modules/word/advanced/drawing-shapes.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createShape = createShape;
+exports.createRect = createRect;
+exports.createRoundRect = createRoundRect;
+exports.createEllipse = createEllipse;
+exports.createLine = createLine;
+exports.createArrow = createArrow;
+exports.createFlowchartShape = createFlowchartShape;
+exports.createCallout = createCallout;
+exports.createStar = createStar;
+const encode_1 = require("../../xml/encode.js");
+// =============================================================================
+// Shape Builder Functions
+// =============================================================================
+/**
+ * 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.
+ */
+function createShape(options) {
+    // Convert fill to simple properties for the DrawingShape interface
+    let fillColor;
+    let noFill = false;
+    if (options.fill) {
+        if (options.fill.type === "solid") {
+            fillColor = options.fill.color;
+        }
+        else if (options.fill.type === "none") {
+            noFill = true;
+        }
+    }
+    let outlineColor;
+    let outlineWidth;
+    let noOutline = false;
+    if (options.outline) {
+        outlineColor = options.outline.color;
+        outlineWidth = options.outline.width;
+        noOutline = options.outline.noLine ?? false;
+    }
+    // Serialize advanced properties that DrawingShape can't represent directly.
+    // The writer needs them split because the OOXML schema requires fill
+    // fragments to precede a:ln while effect/3D fragments must follow it.
+    const advanced = serializeAdvancedProperties(options);
+    const rawXml = (advanced.fillXml ?? "") + (advanced.effectsXml ?? "");
+    return {
+        type: "drawingShape",
+        shapeType: options.shapeType,
+        width: options.width,
+        height: options.height,
+        fillColor,
+        noFill,
+        outlineColor,
+        outlineWidth,
+        noOutline,
+        textContent: options.textBody?.paragraphs,
+        altText: options.altText,
+        name: options.name,
+        horizontalPosition: options.horizontalPosition,
+        verticalPosition: options.verticalPosition,
+        wrap: options.wrap,
+        behindDoc: options.behindDoc,
+        rotation: options.rotation,
+        rawXml: rawXml.length > 0 ? rawXml : undefined,
+        _advancedFillXml: advanced.fillXml,
+        _advancedEffectsXml: advanced.effectsXml
+    };
+}
+/**
+ * Serialize advanced shape properties into XML fragments suitable for
+ * insertion inside `wps:spPr`. Returns them split into the two slots the
+ * OOXML schema cares about:
+ *  - `fillXml` is inserted between `a:prstGeom` and `a:ln`
+ *  - `effectsXml` is inserted after `a:ln` (effectLst → scene3d → sp3d)
+ */
+function serializeAdvancedProperties(options) {
+    const fillParts = [];
+    const effectParts = [];
+    // Gradient fill
+    if (options.fill && options.fill.type === "gradient") {
+        const gf = options.fill;
+        const stops = gf.stops
+            .map(s => `<a:gs pos="${s.position}"><a:srgbClr val="${(0, encode_1.xmlEncodeAttr)(s.color)}"${s.transparency ? ` alpha="${Math.round((100 - s.transparency) * 1000)}"` : ""}/></a:gs>`)
+            .join("");
+        const angle = gf.angle !== undefined ? ` ang="${gf.angle}"` : "";
+        fillParts.push(`<a:gradFill><a:gsLst>${stops}</a:gsLst><a:lin${angle} scaled="1"/></a:gradFill>`);
+    }
+    // Pattern fill
+    if (options.fill && options.fill.type === "pattern") {
+        const pf = options.fill;
+        fillParts.push(`<a:pattFill prst="${(0, encode_1.xmlEncodeAttr)(pf.preset)}"><a:fgClr><a:srgbClr val="${(0, encode_1.xmlEncodeAttr)(pf.foregroundColor)}"/></a:fgClr><a:bgClr><a:srgbClr val="${(0, encode_1.xmlEncodeAttr)(pf.backgroundColor)}"/></a:bgClr></a:pattFill>`);
+    }
+    // Effects: shadow / glow / reflection / softEdges must live inside
+    // <a:effectLst>. Collect all of them then emit a single wrapper.
+    const effectChildren = [];
+    if (options.effects?.shadow) {
+        const s = options.effects.shadow;
+        const attrs = [];
+        if (s.blurRadius) {
+            attrs.push(`blurRad="${s.blurRadius}"`);
+        }
+        if (s.distance) {
+            attrs.push(`dist="${s.distance}"`);
+        }
+        if (s.direction !== undefined) {
+            attrs.push(`dir="${s.direction}"`);
+        }
+        const alpha = s.transparency !== undefined
+            ? ` <a:alpha val="${Math.round((100 - s.transparency) * 1000)}"/>`
+            : "";
+        const tag = s.type === "inner" ? "a:innerShdw" : "a:outerShdw";
+        effectChildren.push(`<${tag} ${attrs.join(" ")}><a:srgbClr val="${(0, encode_1.xmlEncodeAttr)(s.color)}">${alpha}</a:srgbClr></${tag}>`);
+    }
+    if (options.effects?.glow) {
+        const g = options.effects.glow;
+        const alpha = g.transparency !== undefined
+            ? `<a:alpha val="${Math.round((100 - g.transparency) * 1000)}"/>`
+            : "";
+        effectChildren.push(`<a:glow rad="${g.radius}"><a:srgbClr val="${(0, encode_1.xmlEncodeAttr)(g.color)}">${alpha}</a:srgbClr></a:glow>`);
+    }
+    if (options.effects?.reflection) {
+        const r = options.effects.reflection;
+        const attrs = [];
+        if (r.blurRadius) {
+            attrs.push(`blurRad="${r.blurRadius}"`);
+        }
+        if (r.startOpacity !== undefined) {
+            attrs.push(`stA="${Math.round(r.startOpacity * 1000)}"`);
+        }
+        if (r.endOpacity !== undefined) {
+            attrs.push(`endA="${Math.round(r.endOpacity * 1000)}"`);
+        }
+        if (r.distance) {
+            attrs.push(`dist="${r.distance}"`);
+        }
+        if (r.direction !== undefined) {
+            attrs.push(`dir="${r.direction}"`);
+        }
+        if (r.fadeDirection !== undefined) {
+            attrs.push(`fadeDir="${r.fadeDirection}"`);
+        }
+        effectChildren.push(`<a:reflection ${attrs.join(" ")}/>`);
+    }
+    if (options.effects?.softEdges) {
+        effectChildren.push(`<a:softEdge rad="${options.effects.softEdges}"/>`);
+    }
+    if (effectChildren.length > 0) {
+        effectParts.push(`<a:effectLst>${effectChildren.join("")}</a:effectLst>`);
+    }
+    // 3D effect (scene3d + sp3d) — both follow effectLst.
+    if (options.effects?.effect3d) {
+        const e = options.effects.effect3d;
+        const camera = e.camera ?? "orthographicFront";
+        const rotAttrs = [];
+        if (e.rotX !== undefined) {
+            rotAttrs.push(`lat="${e.rotX}"`);
+        }
+        if (e.rotY !== undefined) {
+            rotAttrs.push(`lon="${e.rotY}"`);
+        }
+        if (e.rotZ !== undefined) {
+            rotAttrs.push(`rev="${e.rotZ}"`);
+        }
+        const rot = rotAttrs.length > 0 ? `<a:rot ${rotAttrs.join(" ")}/>` : "";
+        effectParts.push(`<a:scene3d><a:camera prst="${(0, encode_1.xmlEncodeAttr)(camera)}">${rot}</a:camera><a:lightRig rig="threePt" dir="t"/></a:scene3d>`);
+        const sp3dChildren = [];
+        if (e.bevelTop) {
+            const preset = e.bevelTop.preset ? ` prst="${(0, encode_1.xmlEncodeAttr)(e.bevelTop.preset)}"` : "";
+            sp3dChildren.push(`<a:bevelT w="${e.bevelTop.width}" h="${e.bevelTop.height}"${preset}/>`);
+        }
+        if (e.bevelBottom) {
+            const preset = e.bevelBottom.preset ? ` prst="${(0, encode_1.xmlEncodeAttr)(e.bevelBottom.preset)}"` : "";
+            sp3dChildren.push(`<a:bevelB w="${e.bevelBottom.width}" h="${e.bevelBottom.height}"${preset}/>`);
+        }
+        if (e.extrusionColor) {
+            sp3dChildren.push(`<a:extrusionClr><a:srgbClr val="${(0, encode_1.xmlEncodeAttr)(e.extrusionColor)}"/></a:extrusionClr>`);
+        }
+        const extDepth = e.extrusionDepth ? ` extrusionH="${e.extrusionDepth}"` : "";
+        effectParts.push(`<a:sp3d${extDepth}>${sp3dChildren.join("")}</a:sp3d>`);
+    }
+    return {
+        fillXml: fillParts.length > 0 ? fillParts.join("") : undefined,
+        effectsXml: effectParts.length > 0 ? effectParts.join("") : undefined
+    };
+}
+/**
+ * Create a simple rectangle shape.
+ */
+function createRect(width, height, options) {
+    return createShape({ shapeType: "rect", width, height, ...options });
+}
+/**
+ * Create a rounded rectangle shape.
+ */
+function createRoundRect(width, height, options) {
+    return createShape({ shapeType: "roundRect", width, height, ...options });
+}
+/**
+ * Create an ellipse/circle shape.
+ */
+function createEllipse(width, height, options) {
+    return createShape({ shapeType: "ellipse", width, height, ...options });
+}
+/**
+ * Create a line connector.
+ */
+function createLine(width, height, options) {
+    return createShape({
+        shapeType: "line",
+        width,
+        height,
+        fill: { type: "none" },
+        ...options
+    });
+}
+/**
+ * Create an arrow shape.
+ */
+function createArrow(direction, width, height, options) {
+    const shapeMap = {
+        right: "rightArrow",
+        left: "leftArrow",
+        up: "upArrow",
+        down: "downArrow"
+    };
+    return createShape({ shapeType: shapeMap[direction], width, height, ...options });
+}
+/**
+ * Create a flowchart shape.
+ */
+function createFlowchartShape(kind, width, height, options) {
+    const shapeMap = {
+        process: "flowChartProcess",
+        decision: "flowChartDecision",
+        terminator: "flowChartTerminator",
+        document: "flowChartDocument",
+        data: "flowChartInputOutput",
+        connector: "flowChartConnector",
+        preparation: "flowChartPreparation"
+    };
+    return createShape({ shapeType: shapeMap[kind], width, height, ...options });
+}
+/**
+ * Create a callout shape.
+ */
+function createCallout(style, width, height, options) {
+    const shapeMap = {
+        rect: "wedgeRectCallout",
+        roundRect: "wedgeRoundRectCallout",
+        ellipse: "wedgeEllipseCallout",
+        cloud: "cloudCallout"
+    };
+    return createShape({ shapeType: shapeMap[style], width, height, ...options });
+}
+/**
+ * Create a star shape.
+ */
+function createStar(points, width, height, options) {
+    return createShape({ shapeType: `star${points}`, width, height, ...options });
+}