ts-visio 1.0.1 → 1.1.0

package/README.md

@@ -321,6 +321,30 @@ await annotations.show();  // Show again
 await wireframe.setLocked(true);
 ```
 
+#### 18. Cross-Functional Flowcharts (Swimlanes)
+Create structured Swimlane diagrams involving Pools and Lanes.
+
+```typescript
+// 1. Create a Pool (Vertical List)
+const pool = await page.addSwimlanePool({
+    text: "User Registration",
+    x: 5, y: 5, width: 10, height: 6
+});
+
+// 2. Create Lanes (Containers)
+const lane1 = await page.addSwimlaneLane({ text: "Client", width: 10, height: 2 });
+const lane2 = await page.addSwimlaneLane({ text: "Server", width: 10, height: 2 });
+
+// 3. Add Lanes to Pool (Order matters)
+await pool.addListItem(lane1);
+await pool.addListItem(lane2);
+
+// 4. Group Shapes into Lanes
+// This binds their movement so they stay inside the lane
+await lane1.addMember(startShape);
+await lane2.addMember(serverShape);
+```
+
 ## Examples
 
 Check out the [examples](./examples) directory for complete scripts.
@@ -332,6 +356,7 @@ Check out the [examples](./examples) directory for complete scripts.
 - **[Hyperlinks Demo](./examples/hyperlinks_demo.ts)**: Demonstrates Internal and External navigation.
 - **[Layers Demo](./examples/layers_demo.ts)**: Shows how to create layers and toggle visibility.
 - **[Image Embedding Demo](./examples/images_demo.ts)**: Demonstrates how to embed PNG or JPEG images into a diagram.
+- **[Swimlane Demo](./examples/swimlane_demo.ts)**: Demonstrates creating Cross-Functional Flowcharts with Pools and Lanes.
 
 ## Development
 

package/dist/Layer.d.ts

@@ -1,10 +1,12 @@
 import { VisioPackage } from './VisioPackage';
+import { ShapeModifier } from './ShapeModifier';
 export declare class Layer {
     name: string;
     index: number;
     private pageId?;
     private pkg?;
-    constructor(name: string, index: number, pageId?: string | undefined, pkg?: VisioPackage | undefined);
+    private modifier;
+    constructor(name: string, index: number, pageId?: string | undefined, pkg?: VisioPackage | undefined, modifier?: ShapeModifier);
     setVisible(visible: boolean): Promise<this>;
     setLocked(locked: boolean): Promise<this>;
     hide(): Promise<this>;

package/dist/Layer.js

@@ -3,26 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Layer = void 0;
 const ShapeModifier_1 = require("./ShapeModifier");
 class Layer {
-    constructor(name, index, pageId, pkg) {
+    constructor(name, index, pageId, pkg, modifier) {
         this.name = name;
         this.index = index;
         this.pageId = pageId;
         this.pkg = pkg;
+        this.modifier = modifier ?? (pkg ? new ShapeModifier_1.ShapeModifier(pkg) : null);
     }
     async setVisible(visible) {
-        if (!this.pageId || !this.pkg) {
+        if (!this.pageId || !this.modifier) {
             throw new Error('Layer was not created with page context. Cannot update properties.');
         }
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.updateLayerProperty(this.pageId, this.index, 'Visible', visible ? '1' : '0');
+        await this.modifier.updateLayerProperty(this.pageId, this.index, 'Visible', visible ? '1' : '0');
         return this;
     }
     async setLocked(locked) {
-        if (!this.pageId || !this.pkg) {
+        if (!this.pageId || !this.modifier) {
             throw new Error('Layer was not created with page context. Cannot update properties.');
         }
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.updateLayerProperty(this.pageId, this.index, 'Lock', locked ? '1' : '0');
+        await this.modifier.updateLayerProperty(this.pageId, this.index, 'Lock', locked ? '1' : '0');
         return this;
     }
     async hide() {

package/dist/Page.d.ts

@@ -12,6 +12,8 @@ export declare class Page {
     private media;
     private rels;
     private modifier;
+    /** Resolved OPC part path for this page's XML file. */
+    private pagePath;
     constructor(internalPage: VisioPage, pkg: VisioPackage, media?: MediaManager, rels?: RelsManager, modifier?: ShapeModifier);
     get id(): string;
     get name(): string;
@@ -21,6 +23,16 @@ export declare class Page {
     addImage(data: Buffer, name: string, x: number, y: number, width: number, height: number): Promise<Shape>;
     addContainer(props: NewShapeProps): Promise<Shape>;
     addList(props: NewShapeProps, direction?: 'vertical' | 'horizontal'): Promise<Shape>;
+    /**
+     * Creates a Swimlane Pool (which is technically a Vertical List of Containers).
+     * @param props Visual properties
+     */
+    addSwimlanePool(props: NewShapeProps): Promise<Shape>;
+    /**
+     * Creates a Swimlane Lane (which is technically a Container).
+     * @param props Visual properties
+     */
+    addSwimlaneLane(props: NewShapeProps): Promise<Shape>;
     addTable(x: number, y: number, title: string, columns: string[]): Promise<Shape>;
     addLayer(name: string, options?: {
         visible?: boolean;

package/dist/Page.js

@@ -12,9 +12,13 @@ class Page {
     constructor(internalPage, pkg, media, rels, modifier) {
         this.internalPage = internalPage;
         this.pkg = pkg;
+        // Prefer the relationship-resolved path over the ID-derived fallback so
+        // that loaded files with non-sequential page filenames work correctly.
+        this.pagePath = internalPage.xmlPath ?? `visio/pages/page${internalPage.ID}.xml`;
         this.media = media || new MediaManager_1.MediaManager(pkg);
         this.rels = rels || new RelsManager_1.RelsManager(pkg);
         this.modifier = modifier || new ShapeModifier_1.ShapeModifier(pkg);
+        this.modifier.registerPage(internalPage.ID, this.pagePath);
     }
     get id() {
         return this.internalPage.ID;
@@ -24,11 +28,9 @@ class Page {
     }
     getShapes() {
         const reader = new ShapeReader_1.ShapeReader(this.pkg);
-        // Assuming standard path mapping for now
-        const pagePath = `visio/pages/page${this.id}.xml`;
         try {
-            const internalShapes = reader.readShapes(pagePath);
-            return internalShapes.map(s => new Shape_1.Shape(s, this.id, this.pkg));
+            const internalShapes = reader.readShapes(this.pagePath);
+            return internalShapes.map(s => new Shape_1.Shape(s, this.id, this.pkg, this.modifier));
         }
         catch (e) {
             // If page file doesn't exist or is empty, return empty array
@@ -53,7 +55,7 @@ class Page {
                 'LocPinY': props.height / 2
             }
         });
-        return new Shape_1.Shape(internalStub, this.id, this.pkg);
+        return new Shape_1.Shape(internalStub, this.id, this.pkg, this.modifier);
     }
     async connectShapes(fromShape, toShape, beginArrow, endArrow) {
         await this.modifier.addConnector(this.id, fromShape.id, toShape.id, beginArrow, endArrow);
@@ -61,8 +63,8 @@ class Page {
     async addImage(data, name, x, y, width, height) {
         // 1. Upload Media
         const mediaPath = this.media.addMedia(name, data);
-        // 2. Link Page to Media
-        const rId = await this.rels.addPageImageRel(this.id, mediaPath);
+        // 2. Link Page to Media (use resolved path so loaded files work correctly)
+        const rId = await this.rels.addImageRelationship(this.pagePath, mediaPath);
         // 3. Create Shape
         const newId = await this.modifier.addShape(this.id, {
             text: '',
@@ -80,7 +82,7 @@ class Page {
                 'PinY': y
             }
         });
-        return new Shape_1.Shape(internalStub, this.id, this.pkg);
+        return new Shape_1.Shape(internalStub, this.id, this.pkg, this.modifier);
     }
     async addContainer(props) {
         const newId = await this.modifier.addContainer(this.id, props);
@@ -94,7 +96,7 @@ class Page {
                 'PinY': props.y
             }
         });
-        return new Shape_1.Shape(internalStub, this.id, this.pkg);
+        return new Shape_1.Shape(internalStub, this.id, this.pkg, this.modifier);
     }
     async addList(props, direction = 'vertical') {
         const newId = await this.modifier.addList(this.id, props, direction);
@@ -108,7 +110,23 @@ class Page {
                 'PinY': props.y
             }
         });
-        return new Shape_1.Shape(internalStub, this.id, this.pkg);
+        return new Shape_1.Shape(internalStub, this.id, this.pkg, this.modifier);
+    }
+    /**
+     * Creates a Swimlane Pool (which is technically a Vertical List of Containers).
+     * @param props Visual properties
+     */
+    async addSwimlanePool(props) {
+        // A Pool is just a vertical list
+        return this.addList(props, 'vertical');
+    }
+    /**
+     * Creates a Swimlane Lane (which is technically a Container).
+     * @param props Visual properties
+     */
+    async addSwimlaneLane(props) {
+        // A Lane is just a container
+        return this.addContainer(props);
     }
     async addTable(x, y, title, columns) {
         // ... (previous implementation)
@@ -163,7 +181,7 @@ class Page {
     }
     async addLayer(name, options) {
         const info = await this.modifier.addLayer(this.id, name, options);
-        return new Layer_1.Layer(info.name, info.index, this.id, this.pkg);
+        return new Layer_1.Layer(info.name, info.index, this.id, this.pkg, this.modifier);
     }
 }
 exports.Page = Page;

package/dist/Shape.d.ts

@@ -1,6 +1,6 @@
 import { VisioShape } from './types/VisioTypes';
 import { VisioPackage } from './VisioPackage';
-import { ShapeStyle } from './ShapeModifier';
+import { ShapeModifier, ShapeStyle } from './ShapeModifier';
 import { VisioPropType } from './types/VisioTypes';
 import { Layer } from './Layer';
 export interface ShapeData {
@@ -13,7 +13,8 @@ export declare class Shape {
     private internalShape;
     private pageId;
     private pkg;
-    constructor(internalShape: VisioShape, pageId: string, pkg: VisioPackage);
+    private modifier;
+    constructor(internalShape: VisioShape, pageId: string, pkg: VisioPackage, modifier?: ShapeModifier);
     get id(): string;
     get name(): string;
     get text(): string;
@@ -65,4 +66,5 @@ export declare class Shape {
      * Alias for assignLayer. Adds this shape to a layer.
      */
     addToLayer(layer: Layer | number): Promise<this>;
+    private setLocalCoord;
 }

package/dist/Shape.js

@@ -3,11 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Shape = void 0;
 const ShapeModifier_1 = require("./ShapeModifier");
 const VisioTypes_1 = require("./types/VisioTypes");
+/** Round a coordinate to 10 decimal places to prevent float-to-string-to-float precision drift. */
+function fmtCoord(n) {
+    return parseFloat(n.toFixed(10)).toString();
+}
 class Shape {
-    constructor(internalShape, pageId, pkg) {
+    constructor(internalShape, pageId, pkg, modifier) {
         this.internalShape = internalShape;
         this.pageId = pageId;
         this.pkg = pkg;
+        this.modifier = modifier ?? new ShapeModifier_1.ShapeModifier(pkg);
     }
     get id() {
         return this.internalShape.ID;
@@ -19,9 +24,7 @@ class Shape {
         return this.internalShape.Text || '';
     }
     async setText(newText) {
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.updateShapeText(this.pageId, this.id, newText);
-        // Update local state to reflect change
+        await this.modifier.updateShapeText(this.pageId, this.id, newText);
         this.internalShape.Text = newText;
     }
     get width() {
@@ -37,64 +40,43 @@ class Shape {
         return this.internalShape.Cells['PinY'] ? Number(this.internalShape.Cells['PinY'].V) : 0;
     }
     async connectTo(targetShape, beginArrow, endArrow) {
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.addConnector(this.pageId, this.id, targetShape.id, beginArrow, endArrow);
+        await this.modifier.addConnector(this.pageId, this.id, targetShape.id, beginArrow, endArrow);
         return this;
     }
     async setStyle(style) {
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.updateShapeStyle(this.pageId, this.id, style);
-        // Minimal local state update to reflect changes if necessary
-        // For now, valid XML is the priority.
+        await this.modifier.updateShapeStyle(this.pageId, this.id, style);
         return this;
     }
     async placeRightOf(targetShape, options = { gap: 1 }) {
-        const newX = targetShape.x + targetShape.width + options.gap;
-        const newY = targetShape.y; // Keep same Y (per instructions, aligns center-to-center if PinY is center)
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.updateShapePosition(this.pageId, this.id, newX, newY);
-        // Update local state is crucial for chaining successive placements
-        if (this.internalShape.Cells['PinX'])
-            this.internalShape.Cells['PinX'].V = newX.toString();
-        else
-            this.internalShape.Cells['PinX'] = { V: newX.toString(), N: 'PinX' };
-        if (this.internalShape.Cells['PinY'])
-            this.internalShape.Cells['PinY'].V = newY.toString();
-        else
-            this.internalShape.Cells['PinY'] = { V: newY.toString(), N: 'PinY' };
+        // PinX is the shape centre, so right edge of target = target.x + target.width/2;
+        // left edge of this = newX - this.width/2. Set left edge = right edge of target + gap.
+        const newX = targetShape.x + (targetShape.width / 2) + options.gap + (this.width / 2);
+        const newY = targetShape.y; // Align centres vertically
+        await this.modifier.updateShapePosition(this.pageId, this.id, newX, newY);
+        // Update local state — rounded to avoid float precision drift in chained placements
+        this.setLocalCoord('PinX', newX);
+        this.setLocalCoord('PinY', newY);
         return this;
     }
     async placeBelow(targetShape, options = { gap: 1 }) {
-        const newX = targetShape.x; // Align Centers
-        // Target Bottom = target.y - target.height / 2
-        // My Top = Target Bottom - gap
-        // My Center = My Top - my.height / 2
-        // My Center = target.y - target.height/2 - gap - my.height/2
+        const newX = targetShape.x; // Align centres horizontally
+        // Target bottom edge = target.y - target.height/2
+        // This centre = target bottom - gap - this.height/2
         const newY = targetShape.y - (targetShape.height + this.height) / 2 - options.gap;
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.updateShapePosition(this.pageId, this.id, newX, newY);
-        if (this.internalShape.Cells['PinX'])
-            this.internalShape.Cells['PinX'].V = newX.toString();
-        else
-            this.internalShape.Cells['PinX'] = { V: newX.toString(), N: 'PinX' };
-        if (this.internalShape.Cells['PinY'])
-            this.internalShape.Cells['PinY'].V = newY.toString();
-        else
-            this.internalShape.Cells['PinY'] = { V: newY.toString(), N: 'PinY' };
+        await this.modifier.updateShapePosition(this.pageId, this.id, newX, newY);
+        this.setLocalCoord('PinX', newX);
+        this.setLocalCoord('PinY', newY);
         return this;
     }
     addPropertyDefinition(name, type, options = {}) {
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        modifier.addPropertyDefinition(this.pageId, this.id, name, type, options);
+        this.modifier.addPropertyDefinition(this.pageId, this.id, name, type, options);
         return this;
     }
     setPropertyValue(name, value) {
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        modifier.setPropertyValue(this.pageId, this.id, name, value);
+        this.modifier.setPropertyValue(this.pageId, this.id, name, value);
         return this;
     }
     addData(key, data) {
-        // Auto-detect type if not provided
         let type = data.type;
         if (type === undefined) {
             if (data.value instanceof Date) {
@@ -110,59 +92,37 @@ class Shape {
                 type = VisioTypes_1.VisioPropType.String;
             }
         }
-        // 1. Define Property
-        this.addPropertyDefinition(key, type, {
-            label: data.label,
-            invisible: data.hidden
-        });
-        // 2. Set Value
+        this.addPropertyDefinition(key, type, { label: data.label, invisible: data.hidden });
         this.setPropertyValue(key, data.value);
         return this;
     }
     async addMember(memberShape) {
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        // Type="Container" is the standard for Container relationships
-        await modifier.addRelationship(this.pageId, this.id, memberShape.id, 'Container');
+        await this.modifier.addRelationship(this.pageId, this.id, memberShape.id, 'Container');
         return this;
     }
     async addListItem(item) {
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.addListItem(this.pageId, this.id, item.id);
-        // Refresh local state after modifer updates (resizeToFit called internally)
+        await this.modifier.addListItem(this.pageId, this.id, item.id);
         await this.refreshLocalState();
         return this;
     }
     async resizeToFit(padding = 0.25) {
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.resizeContainerToFit(this.pageId, this.id, padding);
+        await this.modifier.resizeContainerToFit(this.pageId, this.id, padding);
         await this.refreshLocalState();
         return this;
     }
     async refreshLocalState() {
-        // Reloads internal Cells from modifier's fresh XML
-        // This is a bit expensive but ensures consistency
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        const geo = modifier.getShapeGeometry(this.pageId, this.id);
-        const update = (n, v) => {
-            if (this.internalShape.Cells[n])
-                this.internalShape.Cells[n].V = v;
-            else
-                this.internalShape.Cells[n] = { V: v, N: n };
-        };
-        update('PinX', geo.x.toString());
-        update('PinY', geo.y.toString());
-        update('Width', geo.width.toString());
-        update('Height', geo.height.toString());
+        const geo = this.modifier.getShapeGeometry(this.pageId, this.id);
+        this.setLocalCoord('PinX', geo.x);
+        this.setLocalCoord('PinY', geo.y);
+        this.setLocalCoord('Width', geo.width);
+        this.setLocalCoord('Height', geo.height);
     }
     async addHyperlink(address, description) {
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.addHyperlink(this.pageId, this.id, { address, description });
+        await this.modifier.addHyperlink(this.pageId, this.id, { address, description });
         return this;
     }
     async linkToPage(targetPage, description) {
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        // Internal links use SubAddress='PageName' and empty Address
-        await modifier.addHyperlink(this.pageId, this.id, {
+        await this.modifier.addHyperlink(this.pageId, this.id, {
             address: '',
             subAddress: targetPage.name,
             description
@@ -189,8 +149,7 @@ class Shape {
     }
     async assignLayer(layer) {
         const index = typeof layer === 'number' ? layer : layer.index;
-        const modifier = new ShapeModifier_1.ShapeModifier(this.pkg);
-        await modifier.assignLayer(this.pageId, this.id, index);
+        await this.modifier.assignLayer(this.pageId, this.id, index);
         return this;
     }
     /**
@@ -199,5 +158,12 @@ class Shape {
     async addToLayer(layer) {
         return this.assignLayer(layer);
     }
+    setLocalCoord(name, value) {
+        const v = fmtCoord(value);
+        if (this.internalShape.Cells[name])
+            this.internalShape.Cells[name].V = v;
+        else
+            this.internalShape.Cells[name] = { V: v, N: name };
+    }
 }
 exports.Shape = Shape;

package/dist/ShapeModifier.d.ts

@@ -9,9 +9,18 @@ export declare class ShapeModifier {
     private relsManager;
     private pageCache;
     private dirtyPages;
+    private shapeCache;
+    private pagePathRegistry;
     autoSave: boolean;
+    /**
+     * Register the resolved OPC part path for a page ID.
+     * Must be called before any operation on a loaded file to ensure the
+     * correct file is targeted rather than the ID-derived fallback name.
+     */
+    registerPage(pageId: string, xmlPath: string): void;
     constructor(pkg: VisioPackage);
     private getPagePath;
+    private getShapeMap;
     private getAllShapes;
     private getNextId;
     private ensurePageSheet;