ts-visio 1.5.0 → 1.6.0

package/README.md

@@ -25,6 +25,7 @@ Built using specific schema-level abstractions to handle the complex internal st
 - **Read-Back API**: Read custom properties, hyperlinks, and layer assignments from existing shapes.
 - **Page Size & Orientation**: Set canvas dimensions with named sizes (`Letter`, `A4`, …) or raw inches; rotate between portrait and landscape.
 - **Document Metadata**: Read and write document properties (title, author, description, keywords, company, dates) via `doc.getMetadata()` / `doc.setMetadata()`.
+- **Named Connection Points**: Define specific ports on shapes (`Top`, `Right`, etc.) and connect to them precisely using `fromPort`/`toPort` on any connector API.
 
 Feature gaps are being tracked in [FEATURES.md](./FEATURES.md).
 
@@ -558,6 +559,57 @@ await shape.setStyle({
 
 ---
 
+#### 28. Named Connection Points
+Define specific ports on shapes and connect to them precisely instead of relying on edge-intersection.
+
+```typescript
+import { StandardConnectionPoints } from 'ts-visio';
+
+// 1. Add connection points at shape-creation time
+const nodeA = await page.addShape({
+    text: 'A', x: 2, y: 3, width: 2, height: 1,
+    connectionPoints: StandardConnectionPoints.cardinal, // Top, Right, Bottom, Left
+});
+
+const nodeB = await page.addShape({
+    text: 'B', x: 6, y: 3, width: 2, height: 1,
+    connectionPoints: StandardConnectionPoints.cardinal,
+});
+
+// 2. Connect using named ports (Right of A → Left of B)
+await page.connectShapes(nodeA, nodeB, undefined, undefined, undefined,
+    { name: 'Right' },   // fromPort
+    { name: 'Left' },    // toPort
+);
+
+// 3. Fluent Shape API
+await nodeA.connectTo(nodeB, undefined, undefined, undefined,
+    { name: 'Right' }, { name: 'Left' });
+
+// 4. Add a point to an existing shape by index
+const ix = nodeA.addConnectionPoint({
+    name: 'Center',
+    xFraction: 0.5, yFraction: 0.5,
+    type: 'both',
+});
+
+// 5. Connect by zero-based index instead of name
+await page.connectShapes(nodeA, nodeB, undefined, undefined, undefined,
+    { index: 1 }, // Right (IX=1 in cardinal preset)
+    { index: 3 }, // Left  (IX=3 in cardinal preset)
+);
+
+// 6. 'center' target (default behaviour) works alongside named ports
+await page.connectShapes(nodeA, nodeB, undefined, undefined, undefined,
+    'center', { name: 'Left' });
+```
+
+`StandardConnectionPoints.cardinal` — 4 points: `Top`, `Right`, `Bottom`, `Left`.
+`StandardConnectionPoints.full` — 8 points: cardinal + `TopLeft`, `TopRight`, `BottomRight`, `BottomLeft`.
+Unknown port names fall back gracefully to edge-intersection routing without throwing.
+
+---
+
 ## Examples
 
 Check out the [examples](./examples) directory for complete scripts.

package/dist/Page.d.ts

@@ -1,4 +1,4 @@
-import { VisioPage, ConnectorStyle, PageOrientation, PageSizeName } from './types/VisioTypes';
+import { VisioPage, ConnectorStyle, PageOrientation, PageSizeName, ConnectionTarget } from './types/VisioTypes';
 import { VisioPackage } from './VisioPackage';
 import { ShapeModifier } from './ShapeModifier';
 import { NewShapeProps } from './types/VisioTypes';
@@ -50,7 +50,7 @@ export declare class Page {
      */
     findShapes(predicate: (shape: Shape) => boolean): Shape[];
     addShape(props: NewShapeProps, parentId?: string): Promise<Shape>;
-    connectShapes(fromShape: Shape, toShape: Shape, beginArrow?: string, endArrow?: string, style?: ConnectorStyle): Promise<void>;
+    connectShapes(fromShape: Shape, toShape: Shape, beginArrow?: string, endArrow?: string, style?: ConnectorStyle, fromPort?: ConnectionTarget, toPort?: ConnectionTarget): Promise<void>;
     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>;

package/dist/Page.js

@@ -124,8 +124,8 @@ class Page {
         });
         return new Shape_1.Shape(internalStub, this.id, this.pkg, this.modifier);
     }
-    async connectShapes(fromShape, toShape, beginArrow, endArrow, style) {
-        await this.modifier.addConnector(this.id, fromShape.id, toShape.id, beginArrow, endArrow, style);
+    async connectShapes(fromShape, toShape, beginArrow, endArrow, style, fromPort, toPort) {
+        await this.modifier.addConnector(this.id, fromShape.id, toShape.id, beginArrow, endArrow, style, fromPort, toPort);
     }
     async addImage(data, name, x, y, width, height) {
         // 1. Upload Media

package/dist/Shape.d.ts

@@ -1,4 +1,4 @@
-import { VisioShape, ConnectorStyle } from './types/VisioTypes';
+import { VisioShape, ConnectorStyle, ConnectionTarget, ConnectionPointDef } from './types/VisioTypes';
 import { VisioPackage } from './VisioPackage';
 import { ShapeModifier, ShapeStyle } from './ShapeModifier';
 import { VisioPropType } from './types/VisioTypes';
@@ -30,7 +30,12 @@ export declare class Shape {
     get x(): number;
     get y(): number;
     delete(): Promise<void>;
-    connectTo(targetShape: Shape, beginArrow?: string, endArrow?: string, style?: ConnectorStyle): Promise<this>;
+    connectTo(targetShape: Shape, beginArrow?: string, endArrow?: string, style?: ConnectorStyle, fromPort?: ConnectionTarget, toPort?: ConnectionTarget): Promise<this>;
+    /**
+     * Add a connection point to this shape.
+     * Returns the zero-based index (IX) of the newly added point.
+     */
+    addConnectionPoint(point: ConnectionPointDef): number;
     setStyle(style: ShapeStyle): Promise<this>;
     placeRightOf(targetShape: Shape, options?: {
         gap: number;

package/dist/Shape.js

@@ -42,10 +42,17 @@ class Shape {
     async delete() {
         await this.modifier.deleteShape(this.pageId, this.id);
     }
-    async connectTo(targetShape, beginArrow, endArrow, style) {
-        await this.modifier.addConnector(this.pageId, this.id, targetShape.id, beginArrow, endArrow, style);
+    async connectTo(targetShape, beginArrow, endArrow, style, fromPort, toPort) {
+        await this.modifier.addConnector(this.pageId, this.id, targetShape.id, beginArrow, endArrow, style, fromPort, toPort);
         return this;
     }
+    /**
+     * Add a connection point to this shape.
+     * Returns the zero-based index (IX) of the newly added point.
+     */
+    addConnectionPoint(point) {
+        return this.modifier.addConnectionPoint(this.pageId, this.id, point);
+    }
     async setStyle(style) {
         await this.modifier.updateShapeStyle(this.pageId, this.id, style);
         return this;

package/dist/ShapeModifier.d.ts

@@ -1,6 +1,6 @@
 import { VisioPackage } from './VisioPackage';
 import { HorzAlign, VertAlign } from './utils/StyleHelpers';
-import { NewShapeProps, ConnectorStyle } from './types/VisioTypes';
+import { NewShapeProps, ConnectorStyle, ConnectionTarget, ConnectionPointDef } from './types/VisioTypes';
 import type { ShapeData, ShapeHyperlink } from './Shape';
 export declare class ShapeModifier {
     private pkg;
@@ -31,7 +31,12 @@ export declare class ShapeModifier {
     private saveParsed;
     private performSave;
     flush(): void;
-    addConnector(pageId: string, fromShapeId: string, toShapeId: string, beginArrow?: string, endArrow?: string, style?: ConnectorStyle): Promise<string>;
+    addConnector(pageId: string, fromShapeId: string, toShapeId: string, beginArrow?: string, endArrow?: string, style?: ConnectorStyle, fromPort?: ConnectionTarget, toPort?: ConnectionTarget): Promise<string>;
+    /**
+     * Add a single connection point to an existing shape.
+     * Returns the zero-based IX (row index) of the newly added point.
+     */
+    addConnectionPoint(pageId: string, shapeId: string, point: ConnectionPointDef): number;
     addShape(pageId: string, props: NewShapeProps, parentId?: string): Promise<string>;
     deleteShape(pageId: string, shapeId: string): Promise<void>;
     private removeShapeFromTree;

package/dist/ShapeModifier.js

@@ -5,6 +5,7 @@ const RelsManager_1 = require("./core/RelsManager");
 const StyleHelpers_1 = require("./utils/StyleHelpers");
 const VisioConstants_1 = require("./core/VisioConstants");
 const VisioTypes_1 = require("./types/VisioTypes");
+const ConnectionPointBuilder_1 = require("./shapes/ConnectionPointBuilder");
 const ForeignShapeBuilder_1 = require("./shapes/ForeignShapeBuilder");
 const ShapeBuilder_1 = require("./shapes/ShapeBuilder");
 const ConnectorBuilder_1 = require("./shapes/ConnectorBuilder");
@@ -184,7 +185,7 @@ class ShapeModifier {
         }
         this.dirtyPages.clear();
     }
-    async addConnector(pageId, fromShapeId, toShapeId, beginArrow, endArrow, style) {
+    async addConnector(pageId, fromShapeId, toShapeId, beginArrow, endArrow, style, fromPort, toPort) {
         const parsed = this.getParsed(pageId);
         // Ensure Shapes collection exists
         if (!parsed.PageContents.Shapes) {
@@ -204,15 +205,45 @@ class ShapeModifier {
                 return '0';
             return val;
         };
-        const layout = ConnectorBuilder_1.ConnectorBuilder.calculateConnectorLayout(fromShapeId, toShapeId, shapeHierarchy);
+        const layout = ConnectorBuilder_1.ConnectorBuilder.calculateConnectorLayout(fromShapeId, toShapeId, shapeHierarchy, fromPort, toPort);
         const connectorShape = ConnectorBuilder_1.ConnectorBuilder.createConnectorShapeObject(newId, layout, validateArrow(beginArrow), validateArrow(endArrow), style);
         const topLevelShapes = parsed.PageContents.Shapes.Shape;
         topLevelShapes.push(connectorShape);
         this.getShapeMap(parsed).set(newId, connectorShape);
-        ConnectorBuilder_1.ConnectorBuilder.addConnectorToConnects(parsed, newId, fromShapeId, toShapeId);
+        ConnectorBuilder_1.ConnectorBuilder.addConnectorToConnects(parsed, newId, fromShapeId, toShapeId, shapeHierarchy, fromPort, toPort);
         this.saveParsed(pageId, parsed);
         return newId;
     }
+    /**
+     * Add a single connection point to an existing shape.
+     * Returns the zero-based IX (row index) of the newly added point.
+     */
+    addConnectionPoint(pageId, shapeId, point) {
+        const parsed = this.getParsed(pageId);
+        const shapeMap = this.getShapeMap(parsed);
+        const shape = shapeMap.get(shapeId);
+        if (!shape)
+            throw new Error(`Shape ${shapeId} not found on page ${pageId}`);
+        // Ensure Section array exists
+        if (!shape.Section)
+            shape.Section = [];
+        if (!Array.isArray(shape.Section))
+            shape.Section = [shape.Section];
+        // Find or create Connection section
+        let connSection = shape.Section.find((s) => s['@_N'] === 'Connection');
+        if (!connSection) {
+            connSection = { '@_N': 'Connection', Row: [] };
+            shape.Section.push(connSection);
+        }
+        if (!connSection.Row)
+            connSection.Row = [];
+        if (!Array.isArray(connSection.Row))
+            connSection.Row = [connSection.Row];
+        const ix = connSection.Row.length;
+        connSection.Row.push(ConnectionPointBuilder_1.ConnectionPointBuilder.buildRow(point, ix));
+        this.saveParsed(pageId, parsed);
+        return ix;
+    }
     async addShape(pageId, props, parentId) {
         const parsed = this.getParsed(pageId);
         // Ensure Shapes container exists

package/dist/shapes/ConnectionPointBuilder.d.ts

@@ -0,0 +1,40 @@
+import { ConnectionPointDef, ConnectionTarget } from '../types/VisioTypes';
+/**
+ * Builds and resolves Visio Connection section XML structures.
+ *
+ * Connection points in Visio are stored as rows in a `<Section N="Connection">` element.
+ * Each row has an IX attribute (0-based) and an optional N (name) attribute.
+ * X and Y cells store fractions via formula: `Width*{xFraction}` / `Height*{yFraction}`.
+ *
+ * When connecting to a named point, the Connect element uses:
+ *   ToPart = 100 + IX   (instead of 3 for shape centre)
+ *   ToCell = "Connections.X{IX+1}"  (1-based)
+ */
+export declare class ConnectionPointBuilder {
+    /** Build the raw XML object for a Connection section from a list of point definitions. */
+    static buildConnectionSection(points: ConnectionPointDef[]): any;
+    /** Build a single Connection row XML object. */
+    static buildRow(point: ConnectionPointDef, ix: number): any;
+    /**
+     * Resolve a `ConnectionTarget` against a raw shape XML object.
+     *
+     * Returns the `ToPart` / `ToCell` strings for the Connect element, plus the
+     * fractional X/Y position of the connection point (undefined when targeting
+     * the shape centre, which falls back to edge-intersection logic).
+     */
+    static resolveTarget(target: ConnectionTarget, shape: any): {
+        toPart: string;
+        toCell: string;
+        xFraction?: number;
+        yFraction?: number;
+    };
+    private static getConnectionSection;
+    private static getRows;
+    private static findIxByName;
+    private static getPointByIx;
+    /**
+     * Extract the numeric multiplier from a formula of the form `Width*0.5` or `Height*1`.
+     * Returns `undefined` if the formula does not match that pattern.
+     */
+    private static parseFraction;
+}

package/dist/shapes/ConnectionPointBuilder.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionPointBuilder = void 0;
+const TYPE_VALUES = {
+    inward: '0',
+    outward: '1',
+    both: '2',
+};
+/**
+ * Builds and resolves Visio Connection section XML structures.
+ *
+ * Connection points in Visio are stored as rows in a `<Section N="Connection">` element.
+ * Each row has an IX attribute (0-based) and an optional N (name) attribute.
+ * X and Y cells store fractions via formula: `Width*{xFraction}` / `Height*{yFraction}`.
+ *
+ * When connecting to a named point, the Connect element uses:
+ *   ToPart = 100 + IX   (instead of 3 for shape centre)
+ *   ToCell = "Connections.X{IX+1}"  (1-based)
+ */
+class ConnectionPointBuilder {
+    /** Build the raw XML object for a Connection section from a list of point definitions. */
+    static buildConnectionSection(points) {
+        return {
+            '@_N': 'Connection',
+            Row: points.map((pt, ix) => this.buildRow(pt, ix)),
+        };
+    }
+    /** Build a single Connection row XML object. */
+    static buildRow(point, ix) {
+        const row = {
+            '@_IX': ix.toString(),
+            Cell: [
+                { '@_N': 'X', '@_V': '0', '@_F': `Width*${point.xFraction}` },
+                { '@_N': 'Y', '@_V': '0', '@_F': `Height*${point.yFraction}` },
+                { '@_N': 'DirX', '@_V': point.direction ? point.direction.x.toString() : '0' },
+                { '@_N': 'DirY', '@_V': point.direction ? point.direction.y.toString() : '0' },
+                { '@_N': 'Type', '@_V': point.type ? TYPE_VALUES[point.type] : '0' },
+                { '@_N': 'AutoGen', '@_V': '0' },
+            ],
+        };
+        if (point.name)
+            row['@_N'] = point.name;
+        if (point.prompt)
+            row.Cell.push({ '@_N': 'Prompt', '@_V': point.prompt });
+        return row;
+    }
+    /**
+     * Resolve a `ConnectionTarget` against a raw shape XML object.
+     *
+     * Returns the `ToPart` / `ToCell` strings for the Connect element, plus the
+     * fractional X/Y position of the connection point (undefined when targeting
+     * the shape centre, which falls back to edge-intersection logic).
+     */
+    static resolveTarget(target, shape) {
+        if (target === 'center') {
+            return { toPart: '3', toCell: 'PinX' };
+        }
+        if ('index' in target) {
+            const ix = target.index;
+            const pt = this.getPointByIx(shape, ix);
+            return {
+                toPart: (100 + ix).toString(),
+                toCell: `Connections.X${ix + 1}`,
+                xFraction: pt?.xFraction,
+                yFraction: pt?.yFraction,
+            };
+        }
+        // name lookup
+        const ix = this.findIxByName(shape, target.name);
+        if (ix === -1) {
+            // Named point not found — fall back to centre
+            return { toPart: '3', toCell: 'PinX' };
+        }
+        const pt = this.getPointByIx(shape, ix);
+        return {
+            toPart: (100 + ix).toString(),
+            toCell: `Connections.X${ix + 1}`,
+            xFraction: pt?.xFraction,
+            yFraction: pt?.yFraction,
+        };
+    }
+    // ── private helpers ────────────────────────────────────────────────────────
+    static getConnectionSection(shape) {
+        const sections = shape?.Section;
+        if (!sections)
+            return null;
+        const arr = Array.isArray(sections) ? sections : [sections];
+        return arr.find((s) => s['@_N'] === 'Connection') ?? null;
+    }
+    static getRows(section) {
+        if (!section?.Row)
+            return [];
+        return Array.isArray(section.Row) ? section.Row : [section.Row];
+    }
+    static findIxByName(shape, name) {
+        const section = this.getConnectionSection(shape);
+        if (!section)
+            return -1;
+        const row = this.getRows(section).find((r) => r['@_N'] === name);
+        if (!row)
+            return -1;
+        return parseInt(row['@_IX'], 10);
+    }
+    static getPointByIx(shape, ix) {
+        const section = this.getConnectionSection(shape);
+        if (!section)
+            return undefined;
+        const row = this.getRows(section).find((r) => parseInt(r['@_IX'], 10) === ix);
+        if (!row)
+            return undefined;
+        const cells = Array.isArray(row.Cell) ? row.Cell : row.Cell ? [row.Cell] : [];
+        const xCell = cells.find((c) => c['@_N'] === 'X');
+        const yCell = cells.find((c) => c['@_N'] === 'Y');
+        // Prefer formula parsing (works for both freshly-created and loaded shapes).
+        // Fall back to @_V if no formula is present.
+        const xFraction = this.parseFraction(xCell?.['@_F']) ?? parseFloat(xCell?.['@_V'] ?? '0');
+        const yFraction = this.parseFraction(yCell?.['@_F']) ?? parseFloat(yCell?.['@_V'] ?? '0');
+        return { xFraction, yFraction };
+    }
+    /**
+     * Extract the numeric multiplier from a formula of the form `Width*0.5` or `Height*1`.
+     * Returns `undefined` if the formula does not match that pattern.
+     */
+    static parseFraction(formula) {
+        if (!formula)
+            return undefined;
+        const m = formula.match(/^(?:Width|Height)\*([0-9.]+)$/);
+        return m ? parseFloat(m[1]) : undefined;
+    }
+}
+exports.ConnectionPointBuilder = ConnectionPointBuilder;

package/dist/shapes/ConnectorBuilder.d.ts

@@ -1,4 +1,4 @@
-import { ConnectorStyle } from '../types/VisioTypes';
+import { ConnectorStyle, ConnectionTarget } from '../types/VisioTypes';
 export declare class ConnectorBuilder {
     private static getCellVal;
     private static getAbsolutePos;
@@ -10,7 +10,7 @@ export declare class ConnectorBuilder {
     static calculateConnectorLayout(fromShapeId: string, toShapeId: string, shapeHierarchy: Map<string, {
         shape: any;
         parent: any;
-    }>): {
+    }>, fromPort?: ConnectionTarget, toPort?: ConnectionTarget): {
         beginX: number;
         beginY: number;
         endX: number;
@@ -18,6 +18,12 @@ export declare class ConnectorBuilder {
         width: number;
         angle: number;
     };
+    /**
+     * Resolve a ConnectionTarget to an absolute page position using the shape hierarchy.
+     * Returns null when the target is 'center' or the named/indexed point is not found,
+     * signalling the caller to fall back to edge-intersection logic.
+     */
+    private static resolveConnectionPointPos;
     static createConnectorShapeObject(id: string, layout: any, beginArrow?: string, endArrow?: string, style?: ConnectorStyle): {
         '@_ID': string;
         '@_NameU': string;
@@ -34,5 +40,8 @@ export declare class ConnectorBuilder {
         })[];
         Section: import("../utils/StyleHelpers").VisioSection[];
     };
-    static addConnectorToConnects(parsed: any, connectorId: string, fromShapeId: string, toShapeId: string): void;
+    static addConnectorToConnects(parsed: any, connectorId: string, fromShapeId: string, toShapeId: string, shapeHierarchy?: Map<string, {
+        shape: any;
+        parent: any;
+    }>, fromPort?: ConnectionTarget, toPort?: ConnectionTarget): void;
 }

package/dist/shapes/ConnectorBuilder.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectorBuilder = void 0;
 const StyleHelpers_1 = require("../utils/StyleHelpers");
+const ConnectionPointBuilder_1 = require("./ConnectionPointBuilder");
 const ROUTING_VALUES = {
     straight: '2',
     orthogonal: '1',
@@ -65,7 +66,7 @@ class ConnectorBuilder {
         mapHierarchy(topShapes, null);
         return shapeHierarchy;
     }
-    static calculateConnectorLayout(fromShapeId, toShapeId, shapeHierarchy) {
+    static calculateConnectorLayout(fromShapeId, toShapeId, shapeHierarchy, fromPort, toPort) {
         let beginX = 0, beginY = 0, endX = 0, endY = 0;
         let sourceGeom = null;
         let targetGeom = null;
@@ -88,12 +89,32 @@ class ConnectorBuilder {
             endY = abs.y;
         }
         if (sourceGeom && targetGeom) {
-            const startNode = this.getEdgePoint(sourceGeom.x, sourceGeom.y, sourceGeom.w, sourceGeom.h, targetGeom.x, targetGeom.y);
-            const endNode = this.getEdgePoint(targetGeom.x, targetGeom.y, targetGeom.w, targetGeom.h, sourceGeom.x, sourceGeom.y);
-            beginX = startNode.x;
-            beginY = startNode.y;
-            endX = endNode.x;
-            endY = endNode.y;
+            // Compute begin (from-side) endpoint
+            const beginPt = fromPort && fromPort !== 'center'
+                ? this.resolveConnectionPointPos(fromShapeId, fromPort, shapeHierarchy, sourceGeom)
+                : null;
+            if (beginPt) {
+                beginX = beginPt.x;
+                beginY = beginPt.y;
+            }
+            else {
+                const sp = this.getEdgePoint(sourceGeom.x, sourceGeom.y, sourceGeom.w, sourceGeom.h, targetGeom.x, targetGeom.y);
+                beginX = sp.x;
+                beginY = sp.y;
+            }
+            // Compute end (to-side) endpoint
+            const endPt = toPort && toPort !== 'center'
+                ? this.resolveConnectionPointPos(toShapeId, toPort, shapeHierarchy, targetGeom)
+                : null;
+            if (endPt) {
+                endX = endPt.x;
+                endY = endPt.y;
+            }
+            else {
+                const ep = this.getEdgePoint(targetGeom.x, targetGeom.y, targetGeom.w, targetGeom.h, sourceGeom.x, sourceGeom.y);
+                endX = ep.x;
+                endY = ep.y;
+            }
         }
         const dx = endX - beginX;
         const dy = endY - beginY;
@@ -101,6 +122,26 @@ class ConnectorBuilder {
         const angle = Math.atan2(dy, dx);
         return { beginX, beginY, endX, endY, width, angle };
     }
+    /**
+     * Resolve a ConnectionTarget to an absolute page position using the shape hierarchy.
+     * Returns null when the target is 'center' or the named/indexed point is not found,
+     * signalling the caller to fall back to edge-intersection logic.
+     */
+    static resolveConnectionPointPos(shapeId, target, shapeHierarchy, geom) {
+        const entry = shapeHierarchy.get(shapeId);
+        if (!entry)
+            return null;
+        const resolved = ConnectionPointBuilder_1.ConnectionPointBuilder.resolveTarget(target, entry.shape);
+        if (resolved.xFraction === undefined || resolved.yFraction === undefined)
+            return null;
+        const locPinX = parseFloat(this.getCellVal(entry.shape, 'LocPinX'));
+        const locPinY = parseFloat(this.getCellVal(entry.shape, 'LocPinY'));
+        const abs = this.getAbsolutePos(shapeId, shapeHierarchy);
+        return {
+            x: (abs.x - locPinX) + geom.w * resolved.xFraction,
+            y: (abs.y - locPinY) + geom.h * resolved.yFraction,
+        };
+    }
     static createConnectorShapeObject(id, layout, beginArrow, endArrow, style) {
         const { beginX, beginY, endX, endY, width, angle } = layout;
         const routeStyle = style?.routing ? (ROUTING_VALUES[style.routing] ?? '1') : '1';
@@ -151,7 +192,7 @@ class ConnectorBuilder {
             ]
         };
     }
-    static addConnectorToConnects(parsed, connectorId, fromShapeId, toShapeId) {
+    static addConnectorToConnects(parsed, connectorId, fromShapeId, toShapeId, shapeHierarchy, fromPort, toPort) {
         if (!parsed.PageContents.Connects) {
             parsed.PageContents.Connects = { Connect: [] };
         }
@@ -161,21 +202,43 @@ class ConnectorBuilder {
             connectCollection = connectCollection ? [connectCollection] : [];
             parsed.PageContents.Connects.Connect = connectCollection;
         }
+        // Resolve from-side ToPart/ToCell
+        let fromToCell = 'PinX';
+        let fromToPart = '3';
+        if (fromPort && fromPort !== 'center' && shapeHierarchy) {
+            const fromEntry = shapeHierarchy.get(fromShapeId);
+            if (fromEntry) {
+                const r = ConnectionPointBuilder_1.ConnectionPointBuilder.resolveTarget(fromPort, fromEntry.shape);
+                fromToCell = r.toCell;
+                fromToPart = r.toPart;
+            }
+        }
+        // Resolve to-side ToPart/ToCell
+        let toToCell = 'PinX';
+        let toToPart = '3';
+        if (toPort && toPort !== 'center' && shapeHierarchy) {
+            const toEntry = shapeHierarchy.get(toShapeId);
+            if (toEntry) {
+                const r = ConnectionPointBuilder_1.ConnectionPointBuilder.resolveTarget(toPort, toEntry.shape);
+                toToCell = r.toCell;
+                toToPart = r.toPart;
+            }
+        }
         connectCollection.push({
             '@_FromSheet': connectorId,
             '@_FromCell': 'BeginX',
             '@_FromPart': '9',
             '@_ToSheet': fromShapeId,
-            '@_ToCell': 'PinX',
-            '@_ToPart': '3'
+            '@_ToCell': fromToCell,
+            '@_ToPart': fromToPart,
         });
         connectCollection.push({
             '@_FromSheet': connectorId,
             '@_FromCell': 'EndX',
             '@_FromPart': '12',
             '@_ToSheet': toShapeId,
-            '@_ToCell': 'PinX',
-            '@_ToPart': '3'
+            '@_ToCell': toToCell,
+            '@_ToPart': toToPart,
         });
     }
 }

package/dist/shapes/ShapeBuilder.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShapeBuilder = void 0;
 const StyleHelpers_1 = require("../utils/StyleHelpers");
 const GeometryBuilder_1 = require("./GeometryBuilder");
+const ConnectionPointBuilder_1 = require("./ConnectionPointBuilder");
 class ShapeBuilder {
     static createStandardShape(id, props) {
         // Validate dimensions
@@ -82,6 +83,10 @@ class ShapeBuilder {
         if (props.verticalAlign !== undefined) {
             shape.Cell.push({ '@_N': 'VerticalAlign', '@_V': (0, StyleHelpers_1.vertAlignValue)(props.verticalAlign) });
         }
+        // Connection points
+        if (props.connectionPoints && props.connectionPoints.length > 0) {
+            shape.Section.push(ConnectionPointBuilder_1.ConnectionPointBuilder.buildConnectionSection(props.connectionPoints));
+        }
         // Add Geometry
         // Only if NOT a Group AND NOT a Master Instance
         if (props.type !== 'Group' && !props.masterId) {

package/dist/types/VisioTypes.d.ts

@@ -146,6 +146,48 @@ export interface ConnectorStyle {
 }
 /** Non-rectangular geometry variants supported by ShapeBuilder. */
 export type ShapeGeometry = 'rectangle' | 'ellipse' | 'diamond' | 'rounded-rectangle' | 'triangle' | 'parallelogram';
+/** Whether a connection point accepts incoming glue, outgoing glue, or both. */
+export type ConnectionPointType = 'inward' | 'outward' | 'both';
+/**
+ * Definition of a single connection point on a shape.
+ * Positions are expressed as fractions of the shape's width/height
+ * (0.0 = left/bottom, 1.0 = right/top in Visio's coordinate system).
+ */
+export interface ConnectionPointDef {
+    /** Optional display name (e.g. `'Top'`, `'Right'`). Referenced when connecting by name. */
+    name?: string;
+    /** Horizontal position as a fraction of shape width. 0 = left edge, 1 = right edge. */
+    xFraction: number;
+    /** Vertical position as a fraction of shape height. 0 = bottom edge, 1 = top edge. */
+    yFraction: number;
+    /** Glue direction vector. Defaults to `{ x: 0, y: 0 }` (no preferred direction). */
+    direction?: {
+        x: number;
+        y: number;
+    };
+    /** Connection point type. Defaults to `'inward'`. */
+    type?: ConnectionPointType;
+    /** Optional tooltip shown in the Visio UI. */
+    prompt?: string;
+}
+/**
+ * Specifies which connection point to use when attaching a connector endpoint.
+ * - `'center'`       → shape centre (default behaviour, `ToPart=3`)
+ * - `{ name }`       → named connection point (e.g. `{ name: 'Top' }`)
+ * - `{ index }`      → connection point by zero-based row index
+ */
+export type ConnectionTarget = 'center' | {
+    name: string;
+} | {
+    index: number;
+};
+/** Ready-made connection-point presets. */
+export declare const StandardConnectionPoints: {
+    /** Four cardinal points: Top, Right, Bottom, Left. */
+    cardinal: ConnectionPointDef[];
+    /** Eight points: four cardinal + four corners. */
+    full: ConnectionPointDef[];
+};
 export interface NewShapeProps {
     text: string;
     x: number;
@@ -192,4 +234,10 @@ export interface NewShapeProps {
     textMarginLeft?: number;
     /** Right text margin in inches. */
     textMarginRight?: number;
+    /**
+     * Connection points to add to the shape.
+     * Use `StandardConnectionPoints.cardinal` for the four cardinal points,
+     * or `StandardConnectionPoints.full` for eight points.
+     */
+    connectionPoints?: ConnectionPointDef[];
 }

package/dist/types/VisioTypes.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PageSizes = exports.VisioPropType = void 0;
+exports.StandardConnectionPoints = exports.PageSizes = exports.VisioPropType = void 0;
 var VisioPropType;
 (function (VisioPropType) {
     VisioPropType[VisioPropType["String"] = 0] = "String";
@@ -21,3 +21,22 @@ exports.PageSizes = {
     A4: { width: 8.268, height: 11.693 },
     A5: { width: 5.827, height: 8.268 },
 };
+/** Ready-made connection-point presets. */
+exports.StandardConnectionPoints = {
+    cardinal: [
+        { name: 'Top', xFraction: 0.5, yFraction: 1.0, direction: { x: 0, y: 1 } },
+        { name: 'Right', xFraction: 1.0, yFraction: 0.5, direction: { x: 1, y: 0 } },
+        { name: 'Bottom', xFraction: 0.5, yFraction: 0.0, direction: { x: 0, y: -1 } },
+        { name: 'Left', xFraction: 0.0, yFraction: 0.5, direction: { x: -1, y: 0 } },
+    ],
+    full: [
+        { name: 'Top', xFraction: 0.5, yFraction: 1.0, direction: { x: 0, y: 1 } },
+        { name: 'Right', xFraction: 1.0, yFraction: 0.5, direction: { x: 1, y: 0 } },
+        { name: 'Bottom', xFraction: 0.5, yFraction: 0.0, direction: { x: 0, y: -1 } },
+        { name: 'Left', xFraction: 0.0, yFraction: 0.5, direction: { x: -1, y: 0 } },
+        { name: 'TopLeft', xFraction: 0.0, yFraction: 1.0, direction: { x: -1, y: 1 } },
+        { name: 'TopRight', xFraction: 1.0, yFraction: 1.0, direction: { x: 1, y: 1 } },
+        { name: 'BottomRight', xFraction: 1.0, yFraction: 0.0, direction: { x: 1, y: -1 } },
+        { name: 'BottomLeft', xFraction: 0.0, yFraction: 0.0, direction: { x: -1, y: -1 } },
+    ],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-visio",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {