ts-visio 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Walt Zimmerman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,343 @@
+# ts-visio
+
+> [!WARNING]
+> **Under Construction**
+> This library is currently being developed with heavy assistance from AI and is primarily an experimental project. Use with caution.
+
+
+A Node.js library to strict-type interact with Visio (`.vsdx`) files.
+Built using specific schema-level abstractions to handle the complex internal structure of Visio documents (ShapeSheets, Pages, Masters).
+
+> **Status**: Work In Progress (TDD).
+
+## Features
+
+- **Read VSDX**: Open and parse `.vsdx` files (zippped XML).
+- **Strict Typing**: Interact with `VisioPage`, `VisioShape`, and `VisioConnect` objects.
+- **ShapeSheet Access**: Read `Cells`, `Rows`, and `Sections` directly.
+- **Connections**: Analyze connectivity between shapes.
+- **Modular Architecture**: Use specialized components for loading, page management, shape reading, and modification.
+- **Modify Content**: Update text content of shapes.
+- **Create Shapes**: Add new rectangular shapes with text to pages.
+- **Connect Shapes**: Create dynamic connectors between shapes.
+
+## Installation
+
+```bash
+npm install ts-visio
+```
+
+## Usage
+
+
+
+### 1. Create or Load a Document
+The `VisioDocument` class is the main entry point.
+
+```typescript
+import { VisioDocument } from 'ts-visio';
+
+// Create a new blank document
+const doc = await VisioDocument.create();
+
+// OR Load an existing file
+// const doc = await VisioDocument.load('diagram.vsdx');
+```
+
+#### 2. Access Pages
+Access pages through the `pages` property.
+
+```typescript
+const page = doc.pages[0];
+console.log(`Editing Page: ${page.name}`);
+```
+
+#### 3. Add & Modify Shapes
+Add new shapes or modify existing ones without dealing with XML.
+
+```typescript
+// Add a new rectangle shape
+const shape = await page.addShape({
+    text: "Hello World",
+    x: 1,
+    y: 1,
+    width: 3,
+    height: 1,
+    fillColor: "#ff0000", // Option hexadecimal fill color
+    fontColor: "#ffffff",
+    bold: true
+});
+
+// Modify text
+await shape.setText("Updated Text");
+
+console.log(`Shape ID: ${shape.id}`);
+```
+
+
+
+#### 4. Groups & Nesting
+Create Group shapes and add children to them.
+
+```typescript
+// 1. Create a Group container
+const group = await page.addShape({
+    text: "Group",
+    x: 5,
+    y: 5,
+    width: 4,
+    height: 4,
+    type: 'Group'
+});
+
+// 2. Add child shape directly to the group
+// Coordinates are relative to the Group's bottom-left corner
+await page.addShape({
+    text: "Child",
+    x: 1, // Relative X
+    y: 1, // Relative Y
+    width: 1,
+    height: 1
+}, group.id);
+```
+
+
+#### 6. Automatic Layout
+Easily position shapes relative to each other.
+
+```typescript
+const shape1 = await page.addShape({ text: "Step 1", x: 2, y: 5, width: 2, height: 1 });
+const shape2 = await page.addShape({ text: "Step 2", x: 0, y: 0, width: 2, height: 1 }); // X,Y ignored if we place it next
+
+// Place Shape 2 to the right of Shape 1 with a 1-inch gap
+await shape2.placeRightOf(shape1, { gap: 1 });
+
+// Chain placement
+const shape3 = await page.addShape({ text: "Step 3", x: 0, y: 0, width: 2, height: 1 });
+await shape3.placeRightOf(shape2);
+
+// Vertical stacking
+const shape4 = await page.addShape({ text: "Below", x: 0, y: 0, width: 2, height: 1 });
+await shape4.placeBelow(shape1, { gap: 0.5 });
+```
+
+#### 7. Fluent API & Chaining
+Combine creation, styling, and connection in a clean syntax.
+
+```typescript
+const shape1 = await page.addShape({ text: "Start", x: 2, y: 4, width: 2, height: 1 });
+const shape2 = await page.addShape({ text: "End", x: 6, y: 4, width: 2, height: 1 });
+
+// Fluent Connection
+await shape1.connectTo(shape2);
+
+// Chaining Styles & Connections
+await shape1.setStyle({ fillColor: '#00FF00' })
+            .connectTo(shape2);
+```
+
+#### 5. Advanced Connections
+Use specific arrowheads (Crow's Foot, etc.)
+
+```typescript
+import { ArrowHeads } from 'ts-visio/utils/StyleHelpers';
+
+await page.connectShapes(shape1, shape2, ArrowHeads.One, ArrowHeads.CrowsFoot);
+// OR
+await shape1.connectTo(shape2, ArrowHeads.One, ArrowHeads.CrowsFoot);
+```
+
+#### 6. Database Tables
+Create a compound stacked shape for database tables.
+
+```typescript
+const tableShape = await page.addTable(
+    5,
+    5,
+    "Users",
+    ["ID: int", "Name: varchar", "Email: varchar"]
+);
+console.log(tableShape.id); // Access ID
+```
+
+#### 8. Typed Schema Builder (Facade)
+For ER diagrams, use the `SchemaDiagram` wrapper for simplified semantics.
+
+```typescript
+import { VisioDocument, SchemaDiagram } from 'ts-visio';
+
+const doc = await VisioDocument.create();
+const page = doc.pages[0];
+const schema = new SchemaDiagram(page);
+
+// Add Tables
+const users = await schema.addTable('Users', ['id', 'email'], 0, 0);
+const posts = await schema.addTable('Posts', ['id', 'user_id'], 5, 0);
+
+// Add Relations (1:N maps to Crow's Foot arrow)
+await schema.addRelation(users, posts, '1:N');
+```
+
+#### 9. Save the Document
+Save the modified document back to disk.
+
+```typescript
+await doc.save('updated_diagram.vsdx');
+```
+
+#### 10. Using Stencils (Masters)
+Load a template that already contains stencils (like "Network" or "Flowchart") and drop shapes by their Master ID.
+
+```typescript
+// 1. Load a template with stencils
+const doc = await VisioDocument.load('template_with_masters.vsdx');
+const page = doc.pages[0];
+
+// 2. Drop a shape using a Master ID
+// (You can find IDs in visio/masters/masters.xml of the template)
+await page.addShape({
+    text: "Router 1",
+    x: 2,
+    y: 2,
+    width: 1,
+    height: 1,
+    masterId: "5" // ID of the 'Router' master in the template
+});
+
+// The library automatically handles the relationships so the file stays valid.
+```
+
+#### 11. Multi-Page Documents
+Create multiple pages and organize your diagram across them.
+
+```typescript
+const doc = await VisioDocument.create();
+
+// Page 1 (Default)
+const page1 = doc.pages[0];
+await page1.addShape({ text: "Home", x: 1, y: 1 });
+
+// Page 2 (New)
+const page2 = await doc.addPage("Architecture Diagram");
+await page2.addShape({ text: "Server", x: 4, y: 4 });
+
+await doc.save("multipage.vsdx");
+```
+
+#### 12. Shape Data (Custom Properties)
+Add metadata to shapes, which is crucial for "Smart" diagrams like visual databases or inventories.
+
+```typescript
+const shape = await page.addShape({ text: "Server DB-01", x: 2, y: 2 });
+
+// Synchronous Fluent API
+shape.addData("IP", { value: "192.168.1.10", label: "IP Address" })
+     .addData("Status", { value: "Active" })
+     .addData("LastRefreshed", { value: new Date() }) // Auto-serialized as Visio Date
+     .addData("ConfigID", { value: 1024, hidden: true }); // Invisible to user
+```
+
+#### 13. Image Embedding
+Embed PNG or JPEG images directly into the diagram.
+
+```typescript
+import * as fs from 'fs';
+
+const buffer = fs.readFileSync('logo.png');
+const page = doc.pages[0];
+
+// Add image at (x=2, y=5) with width=3, height=2
+await page.addImage(buffer, 'logo.png', 2, 5, 3, 2);
+```
+
+#### 14. Containers
+Create visual grouping containers (Classic Visio style).
+
+```typescript
+// Create a Container
+const container = await page.addContainer({
+    text: "Network Zone",
+    x: 1, y: 1,
+    width: 6, height: 4
+});
+
+// Add shapes "inside" the container area
+// (Visio treats them as members if they are spatially within)
+const shape = await page.addShape({ text: "Server A", x: 2, y: 2, width: 1, height: 1 });
+
+// Explicitly link the shape to the container (so they move together)
+await container.addMember(shape);
+```
+
+#### 15. Lists (Stacking Containers)
+Create ordered lists that automatically stack items either vertically (Tables) or horizontally (Timelines).
+
+```typescript
+// Vertical List (e.g. Database Table)
+const list = await page.addList({
+    text: "Users",
+    x: 1, y: 10,
+    width: 3, height: 1
+}, 'vertical'); // 'vertical' or 'horizontal'
+
+// Items stack automatically
+await list.addListItem(item1);
+await list.addListItem(item2);
+```
+
+#### 16. Interactivity & Navigation (Hyperlinks)
+Add internal links (drill-downs) or external links (web references). These appear in the right-click menu in Visio.
+
+```typescript
+// 1. External URL
+await shape.toUrl('https://jira.com/123', 'Open Ticket');
+
+// 2. Internal Page Link
+const detailPage = await doc.addPage('Details');
+await shape.toPage(detailPage, 'Go to Details');
+
+// 3. Chainable
+await shape.toUrl('https://google.com')
+           .toPage(detailPage);
+```
+
+#### 17. Layers
+Organize complex diagrams with layers. Control visibility and locking programmatically.
+
+```typescript
+// 1. Define Layers
+const wireframe = await page.addLayer('Wireframe');
+const annotations = await page.addLayer('Annotations');
+
+// 2. Assign Shapes to Layers
+await shape.addToLayer(wireframe);
+await noteBox.addToLayer(annotations);
+
+// 3. Toggle Visibility
+await annotations.hide();  // Hide for presentation
+await annotations.show();  // Show again
+
+// 4. Lock Layer
+await wireframe.setLocked(true);
+```
+
+## Examples
+
+Check out the [examples](./examples) directory for complete scripts.
+
+- **[Simple Schema](./examples/simple-schema.ts)**: Generates a database schema ERD with tables, styling, and Crow's Foot connectors.
+- **[Network Topology](./examples/network-diagram.ts)**: Demonstrates the **Fluent Shape Data API** to build a network map with hidden metadata, typed properties, and connections.
+- **[Containers Demo](./examples/containers_demo.ts)**: Shows how to create Classic Visio containers and place shapes within them.
+- **[Lists Demo](./examples/lists_demo.ts)**: Demonstrates Vertical and Horizontal List stacks.
+- **[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.
+
+## Development
+
+This project uses **Vitest** for testing.
+
+```bash
+npm install
+npm test
+```

package/dist/Layer.d.ts

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

package/dist/Layer.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Layer = void 0;
+const ShapeModifier_1 = require("./ShapeModifier");
+class Layer {
+    constructor(name, index, pageId, pkg) {
+        this.name = name;
+        this.index = index;
+        this.pageId = pageId;
+        this.pkg = pkg;
+    }
+    async setVisible(visible) {
+        if (!this.pageId || !this.pkg) {
+            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');
+        return this;
+    }
+    async setLocked(locked) {
+        if (!this.pageId || !this.pkg) {
+            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');
+        return this;
+    }
+    async hide() {
+        return this.setVisible(false);
+    }
+    async show() {
+        return this.setVisible(true);
+    }
+}
+exports.Layer = Layer;

package/dist/Page.d.ts

@@ -0,0 +1,30 @@
+import { VisioPage } from './types/VisioTypes';
+import { VisioPackage } from './VisioPackage';
+import { ShapeModifier } from './ShapeModifier';
+import { NewShapeProps } from './types/VisioTypes';
+import { Shape } from './Shape';
+import { MediaManager } from './core/MediaManager';
+import { RelsManager } from './core/RelsManager';
+import { Layer } from './Layer';
+export declare class Page {
+    private internalPage;
+    private pkg;
+    private media;
+    private rels;
+    private modifier;
+    constructor(internalPage: VisioPage, pkg: VisioPackage, media?: MediaManager, rels?: RelsManager, modifier?: ShapeModifier);
+    get id(): string;
+    get name(): string;
+    getShapes(): Shape[];
+    addShape(props: NewShapeProps, parentId?: string): Promise<Shape>;
+    connectShapes(fromShape: Shape, toShape: Shape, beginArrow?: string, endArrow?: string): 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>;
+    addTable(x: number, y: number, title: string, columns: string[]): Promise<Shape>;
+    addLayer(name: string, options?: {
+        visible?: boolean;
+        lock?: boolean;
+        print?: boolean;
+    }): Promise<Layer>;
+}

package/dist/Page.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Page = void 0;
+const ShapeReader_1 = require("./ShapeReader");
+const ShapeModifier_1 = require("./ShapeModifier");
+const Shape_1 = require("./Shape");
+const MediaManager_1 = require("./core/MediaManager");
+const RelsManager_1 = require("./core/RelsManager");
+const StubHelpers_1 = require("./utils/StubHelpers");
+const Layer_1 = require("./Layer");
+class Page {
+    constructor(internalPage, pkg, media, rels, modifier) {
+        this.internalPage = internalPage;
+        this.pkg = pkg;
+        this.media = media || new MediaManager_1.MediaManager(pkg);
+        this.rels = rels || new RelsManager_1.RelsManager(pkg);
+        this.modifier = modifier || new ShapeModifier_1.ShapeModifier(pkg);
+    }
+    get id() {
+        return this.internalPage.ID;
+    }
+    get name() {
+        return this.internalPage.Name;
+    }
+    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));
+        }
+        catch (e) {
+            // If page file doesn't exist or is empty, return empty array
+            console.warn(`Could not read shapes for page ${this.id}:`, e);
+            return [];
+        }
+    }
+    async addShape(props, parentId) {
+        const newId = await this.modifier.addShape(this.id, props, parentId);
+        // Return a fresh Shape object representing the new shape
+        // We construct a minimal internal shape to satisfy the wrapper
+        // In a real scenario, we might want to re-read the shape from disk to get full defaults
+        const internalStub = (0, StubHelpers_1.createVisioShapeStub)({
+            ID: newId,
+            Text: props.text,
+            Cells: {
+                'Width': props.width,
+                'Height': props.height,
+                'PinX': props.x,
+                'PinY': props.y,
+                'LocPinX': props.width / 2,
+                'LocPinY': props.height / 2
+            }
+        });
+        return new Shape_1.Shape(internalStub, this.id, this.pkg);
+    }
+    async connectShapes(fromShape, toShape, beginArrow, endArrow) {
+        await this.modifier.addConnector(this.id, fromShape.id, toShape.id, beginArrow, endArrow);
+    }
+    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);
+        // 3. Create Shape
+        const newId = await this.modifier.addShape(this.id, {
+            text: '',
+            x, y, width, height,
+            type: 'Foreign',
+            imgRelId: rId
+        });
+        const internalStub = (0, StubHelpers_1.createVisioShapeStub)({
+            ID: newId,
+            Text: '',
+            Cells: {
+                'Width': width,
+                'Height': height,
+                'PinX': x,
+                'PinY': y
+            }
+        });
+        return new Shape_1.Shape(internalStub, this.id, this.pkg);
+    }
+    async addContainer(props) {
+        const newId = await this.modifier.addContainer(this.id, props);
+        const internalStub = (0, StubHelpers_1.createVisioShapeStub)({
+            ID: newId,
+            Text: props.text,
+            Cells: {
+                'Width': props.width,
+                'Height': props.height,
+                'PinX': props.x,
+                'PinY': props.y
+            }
+        });
+        return new Shape_1.Shape(internalStub, this.id, this.pkg);
+    }
+    async addList(props, direction = 'vertical') {
+        const newId = await this.modifier.addList(this.id, props, direction);
+        const internalStub = (0, StubHelpers_1.createVisioShapeStub)({
+            ID: newId,
+            Text: props.text,
+            Cells: {
+                'Width': props.width,
+                'Height': props.height,
+                'PinX': props.x,
+                'PinY': props.y
+            }
+        });
+        return new Shape_1.Shape(internalStub, this.id, this.pkg);
+    }
+    async addTable(x, y, title, columns) {
+        // ... (previous implementation)
+        // Dimensions
+        const width = 3;
+        const headerHeight = 0.5;
+        const lineItemHeight = 0.25;
+        const bodyHeight = Math.max(0.5, columns.length * lineItemHeight + 0.1); // Min height
+        const totalHeight = headerHeight + bodyHeight;
+        // 1. Create Main Group Shape (Transparent container)
+        // Group Logic:
+        // Positioned at (x, y) on the Page.
+        // Size encapsulates both header and body.
+        const groupShape = await this.addShape({
+            text: '', // No text on container
+            x: x,
+            y: y,
+            width: width,
+            height: totalHeight,
+            type: 'Group'
+        });
+        // 2. Header Shape (Inside Group)
+        // Coords relative to Group (Bottom-Left is 0,0)
+        // Header is at top. Center X is Width/2.
+        // Center Y = BodyHeight + (HeaderHeight/2)
+        const headerCenterY = bodyHeight + (headerHeight / 2);
+        await this.addShape({
+            text: title,
+            x: width / 2, // Relative PinX
+            y: headerCenterY, // Relative PinY
+            width: width,
+            height: headerHeight,
+            fillColor: '#DDDDDD',
+            bold: true
+        }, groupShape.id);
+        // 3. Body Shape (Inside Group)
+        // Bottom part. Center X is Width/2.
+        // Center Y = BodyHeight/2
+        const bodyCenterY = bodyHeight / 2;
+        const bodyText = columns.join('\n');
+        await this.addShape({
+            text: bodyText,
+            x: width / 2, // Relative PinX
+            y: bodyCenterY, // Relative PinY
+            width: width,
+            height: bodyHeight,
+            fillColor: '#FFFFFF',
+            fontColor: '#000000'
+        }, groupShape.id);
+        // Return the Group Shape
+        return groupShape;
+    }
+    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);
+    }
+}
+exports.Page = Page;

package/dist/PageManager.d.ts

@@ -0,0 +1,8 @@
+import { VisioPackage } from './VisioPackage';
+import { VisioPage } from './types/VisioTypes';
+export declare class PageManager {
+    private pkg;
+    private parser;
+    constructor(pkg: VisioPackage);
+    getPages(): VisioPage[];
+}

package/dist/PageManager.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageManager = void 0;
+const fast_xml_parser_1 = require("fast-xml-parser");
+class PageManager {
+    constructor(pkg) {
+        this.pkg = pkg;
+        this.parser = new fast_xml_parser_1.XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: "@_"
+        });
+    }
+    getPages() {
+        let content;
+        try {
+            content = this.pkg.getFileText('visio/pages/pages.xml');
+        }
+        catch {
+            return [];
+        }
+        const parsed = this.parser.parse(content);
+        const pagesData = parsed.Pages?.Page;
+        if (!pagesData)
+            return [];
+        const pagesArray = Array.isArray(pagesData) ? pagesData : [pagesData];
+        return pagesArray.map((p) => ({
+            ID: p['@_ID'],
+            Name: p['@_Name'],
+            NameU: p['@_NameU'],
+            Shapes: [],
+            Connects: []
+        }));
+    }
+}
+exports.PageManager = PageManager;

package/dist/SchemaDiagram.d.ts

@@ -0,0 +1,22 @@
+import { Page } from './Page';
+import { Shape } from './Shape';
+export type RelationType = '1:1' | '1:N';
+export declare class SchemaDiagram {
+    private page;
+    constructor(page: Page);
+    /**
+     * Adds a table entity to the diagram.
+     * @param tableName Name of the table
+     * @param columns List of column names (e.g., "id: int")
+     * @param x X coordinate
+     * @param y Y coordinate
+     */
+    addTable(tableName: string, columns: string[], x?: number, y?: number): Promise<Shape>;
+    /**
+     * Connects two tables with a specific relationship type.
+     * @param fromTable Source table shape
+     * @param toTable Target table shape
+     * @param type Relationship type ('1:1' or '1:N')
+     */
+    addRelation(fromTable: Shape, toTable: Shape, type: RelationType): Promise<void>;
+}