ts-visio 1.2.0 → 1.4.0

package/README.md

@@ -8,8 +8,6 @@
 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 (zipped XML).
@@ -18,13 +16,17 @@ Built using specific schema-level abstractions to handle the complex internal st
 - **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.
+- **Create Shapes**: Rectangles, ellipses, diamonds, rounded rectangles, triangles, parallelograms.
+- **Connect Shapes**: Dynamic connectors with arrow styles, line styling, and routing (straight / orthogonal / curved).
 - **Text Styling**: Font size, font family, bold, color, horizontal/vertical alignment.
 - **Shape Transformations**: Rotate, flip (X/Y), and resize shapes via a fluent API.
 - **Deletion**: Remove shapes and pages cleanly (including orphaned connectors and relationships).
 - **Lookup API**: Find shapes by ID, predicate, or look up pages by name.
 - **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()`.
+
+Feature gaps are being tracked in [FEATURES.md](./FEATURES.md).
 
 ## Installation
 
@@ -418,6 +420,107 @@ const links = shape.getHyperlinks();
 const indices = shape.getLayerIndices(); // e.g. [0, 2]
 ```
 
+#### 23. Non-Rectangular Geometry
+Use the `geometry` prop on `addShape()` to create common flowchart primitives without touching XML.
+
+```typescript
+// Ellipse / circle
+await page.addShape({ text: "Start", x: 1, y: 5, width: 2, height: 2, geometry: 'ellipse' });
+
+// Decision diamond
+await page.addShape({ text: "Yes?", x: 4, y: 5, width: 2, height: 2, geometry: 'diamond' });
+
+// Rounded rectangle (optional corner radius in inches)
+await page.addShape({ text: "Process", x: 7, y: 5, width: 3, height: 2,
+    geometry: 'rounded-rectangle', cornerRadius: 0.2 });
+
+// Right-pointing triangle
+await page.addShape({ text: "Extract", x: 1, y: 2, width: 2, height: 2, geometry: 'triangle' });
+
+// Parallelogram (Data / IO shape)
+await page.addShape({ text: "Input", x: 4, y: 2, width: 3, height: 1.5, geometry: 'parallelogram' });
+```
+
+Supported values: `'rectangle'` (default), `'ellipse'`, `'diamond'`, `'rounded-rectangle'`, `'triangle'`, `'parallelogram'`.
+
+#### 24. Connector Styling
+Control line appearance and routing algorithm on any connector.
+
+```typescript
+import { ArrowHeads } from 'ts-visio/utils/StyleHelpers';
+
+// Styled connector with crow's foot arrow and custom line
+await shape1.connectTo(shape2, ArrowHeads.One, ArrowHeads.CrowsFoot, {
+    lineColor: '#cc0000',   // Hex stroke color
+    lineWeight: 1.5,        // Stroke width in points
+    linePattern: 2,         // 1=solid, 2=dash, 3=dot, 4=dash-dot
+    routing: 'curved',      // 'straight' | 'orthogonal' (default) | 'curved'
+});
+
+// Via page.connectShapes()
+await page.connectShapes(a, b, undefined, undefined, { routing: 'straight' });
+```
+
+#### 25. Page Size & Orientation
+Control the canvas dimensions using named paper sizes or raw inch values.
+
+```typescript
+import { PageSizes } from 'ts-visio';
+
+// Use a named paper size (portrait by default)
+page.setNamedSize('A4');                     // 8.268" × 11.693"
+page.setNamedSize('Letter', 'landscape');   // 11" × 8.5"
+
+// Set arbitrary dimensions in inches
+page.setSize(13.33, 7.5);    // 13.33" × 7.5" widescreen
+
+// Rotate the existing canvas without changing the paper size
+page.setOrientation('landscape');  // swaps width and height if needed
+page.setOrientation('portrait');
+
+// Read current dimensions
+console.log(page.pageWidth);    // e.g. 11
+console.log(page.pageHeight);   // e.g. 8.5
+console.log(page.orientation);  // 'landscape' | 'portrait'
+
+// All size methods are chainable
+page.setNamedSize('A3').setOrientation('landscape');
+```
+
+Available named sizes in `PageSizes`: `Letter`, `Legal`, `Tabloid`, `A3`, `A4`, `A5`.
+
+---
+
+#### 26. Document Metadata
+Set and read document-level properties that appear in Visio's Document Properties dialog.
+
+```typescript
+// Write metadata (only supplied fields are changed)
+doc.setMetadata({
+    title:          'Network Topology',
+    author:         'Alice',
+    description:    'Data-centre interconnect diagram',
+    keywords:       'network datacenter cloud',
+    lastModifiedBy: 'CI pipeline',
+    company:        'ACME Corp',
+    manager:        'Bob',
+    created:        new Date('2025-01-01T00:00:00Z'),
+    modified:       new Date(),
+});
+
+// Read back all metadata fields
+const meta = doc.getMetadata();
+console.log(meta.title);    // 'Network Topology'
+console.log(meta.author);   // 'Alice'
+console.log(meta.company);  // 'ACME Corp'
+console.log(meta.created);  // Date object
+```
+
+Fields map to OPC parts: `title`, `author`, `description`, `keywords`, `lastModifiedBy`,
+`created`, `modified` → `docProps/core.xml`; `company`, `manager` → `docProps/app.xml`.
+
+---
+
 ## Examples
 
 Check out the [examples](./examples) directory for complete scripts.

package/dist/Page.d.ts

@@ -1,4 +1,4 @@
-import { VisioPage } from './types/VisioTypes';
+import { VisioPage, ConnectorStyle, PageOrientation, PageSizeName } from './types/VisioTypes';
 import { VisioPackage } from './VisioPackage';
 import { ShapeModifier } from './ShapeModifier';
 import { NewShapeProps } from './types/VisioTypes';
@@ -17,6 +17,27 @@ export declare class Page {
     constructor(internalPage: VisioPage, pkg: VisioPackage, media?: MediaManager, rels?: RelsManager, modifier?: ShapeModifier);
     get id(): string;
     get name(): string;
+    /** Width of the page canvas in inches. */
+    get pageWidth(): number;
+    /** Height of the page canvas in inches. */
+    get pageHeight(): number;
+    /** Current page orientation derived from the canvas dimensions. */
+    get orientation(): PageOrientation;
+    /**
+     * Set the page canvas size in inches.
+     * @example page.setSize(11, 8.5)  // landscape letter
+     */
+    setSize(width: number, height: number): this;
+    /**
+     * Convenience: change the page to a named standard size (portrait by default).
+     * @example page.setNamedSize('A4')
+     */
+    setNamedSize(sizeName: PageSizeName, orientation?: PageOrientation): this;
+    /**
+     * Rotate the canvas between portrait and landscape without changing the paper size.
+     * Swaps width and height when the current orientation does not match the requested one.
+     */
+    setOrientation(orientation: PageOrientation): this;
     getShapes(): Shape[];
     /**
      * Find a shape by its ID anywhere on the page, including shapes nested inside groups.
@@ -29,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): Promise<void>;
+    connectShapes(fromShape: Shape, toShape: Shape, beginArrow?: string, endArrow?: string, style?: ConnectorStyle): 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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Page = void 0;
+const VisioTypes_1 = require("./types/VisioTypes");
 const ShapeReader_1 = require("./ShapeReader");
 const ShapeModifier_1 = require("./ShapeModifier");
 const Shape_1 = require("./Shape");
@@ -26,6 +27,51 @@ class Page {
     get name() {
         return this.internalPage.Name;
     }
+    /** Width of the page canvas in inches. */
+    get pageWidth() {
+        return this.modifier.getPageDimensions(this.id).width;
+    }
+    /** Height of the page canvas in inches. */
+    get pageHeight() {
+        return this.modifier.getPageDimensions(this.id).height;
+    }
+    /** Current page orientation derived from the canvas dimensions. */
+    get orientation() {
+        return this.pageWidth > this.pageHeight ? 'landscape' : 'portrait';
+    }
+    /**
+     * Set the page canvas size in inches.
+     * @example page.setSize(11, 8.5)  // landscape letter
+     */
+    setSize(width, height) {
+        this.modifier.setPageSize(this.id, width, height);
+        return this;
+    }
+    /**
+     * Convenience: change the page to a named standard size (portrait by default).
+     * @example page.setNamedSize('A4')
+     */
+    setNamedSize(sizeName, orientation = 'portrait') {
+        const { width, height } = VisioTypes_1.PageSizes[sizeName];
+        return orientation === 'landscape'
+            ? this.setSize(height, width)
+            : this.setSize(width, height);
+    }
+    /**
+     * Rotate the canvas between portrait and landscape without changing the paper size.
+     * Swaps width and height when the current orientation does not match the requested one.
+     */
+    setOrientation(orientation) {
+        const w = this.pageWidth;
+        const h = this.pageHeight;
+        if (orientation === 'landscape' && h > w) {
+            this.modifier.setPageSize(this.id, h, w);
+        }
+        else if (orientation === 'portrait' && w > h) {
+            this.modifier.setPageSize(this.id, h, w);
+        }
+        return this;
+    }
     getShapes() {
         const reader = new ShapeReader_1.ShapeReader(this.pkg);
         try {
@@ -78,8 +124,8 @@ class Page {
         });
         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);
+    async connectShapes(fromShape, toShape, beginArrow, endArrow, style) {
+        await this.modifier.addConnector(this.id, fromShape.id, toShape.id, beginArrow, endArrow, style);
     }
     async addImage(data, name, x, y, width, height) {
         // 1. Upload Media

package/dist/Shape.d.ts

@@ -1,4 +1,4 @@
-import { VisioShape } from './types/VisioTypes';
+import { VisioShape, ConnectorStyle } from './types/VisioTypes';
 import { VisioPackage } from './VisioPackage';
 import { ShapeModifier, ShapeStyle } from './ShapeModifier';
 import { VisioPropType } from './types/VisioTypes';
@@ -30,7 +30,7 @@ export declare class Shape {
     get x(): number;
     get y(): number;
     delete(): Promise<void>;
-    connectTo(targetShape: Shape, beginArrow?: string, endArrow?: string): Promise<this>;
+    connectTo(targetShape: Shape, beginArrow?: string, endArrow?: string, style?: ConnectorStyle): Promise<this>;
     setStyle(style: ShapeStyle): Promise<this>;
     placeRightOf(targetShape: Shape, options?: {
         gap: number;

package/dist/Shape.js

@@ -42,8 +42,8 @@ class Shape {
     async delete() {
         await this.modifier.deleteShape(this.pageId, this.id);
     }
-    async connectTo(targetShape, beginArrow, endArrow) {
-        await this.modifier.addConnector(this.pageId, this.id, targetShape.id, beginArrow, endArrow);
+    async connectTo(targetShape, beginArrow, endArrow, style) {
+        await this.modifier.addConnector(this.pageId, this.id, targetShape.id, beginArrow, endArrow, style);
         return this;
     }
     async setStyle(style) {

package/dist/ShapeModifier.d.ts

@@ -1,6 +1,6 @@
 import { VisioPackage } from './VisioPackage';
 import { HorzAlign, VertAlign } from './utils/StyleHelpers';
-import { NewShapeProps } from './types/VisioTypes';
+import { NewShapeProps, ConnectorStyle } from './types/VisioTypes';
 import type { ShapeData, ShapeHyperlink } from './Shape';
 export declare class ShapeModifier {
     private pkg;
@@ -31,7 +31,7 @@ export declare class ShapeModifier {
     private saveParsed;
     private performSave;
     flush(): void;
-    addConnector(pageId: string, fromShapeId: string, toShapeId: string, beginArrow?: string, endArrow?: string): Promise<string>;
+    addConnector(pageId: string, fromShapeId: string, toShapeId: string, beginArrow?: string, endArrow?: string, style?: ConnectorStyle): Promise<string>;
     addShape(pageId: string, props: NewShapeProps, parentId?: string): Promise<string>;
     deleteShape(pageId: string, shapeId: string): Promise<void>;
     private removeShapeFromTree;
@@ -94,6 +94,19 @@ export declare class ShapeModifier {
      * the declared type (Number, Boolean, Date, or String).
      */
     getShapeProperties(pageId: string, shapeId: string): Record<string, ShapeData>;
+    /**
+     * Set the page canvas size. Writes PageWidth / PageHeight into the PageSheet
+     * and sets DrawingSizeType=0 (Custom) so Visio does not override the values.
+     */
+    setPageSize(pageId: string, width: number, height: number): void;
+    /**
+     * Read the current page canvas dimensions.
+     * Returns 8.5 × 11 (US Letter) if no PageSheet cells are present.
+     */
+    getPageDimensions(pageId: string): {
+        width: number;
+        height: number;
+    };
     /**
      * Read back all hyperlinks attached to a shape.
      */

package/dist/ShapeModifier.js

@@ -184,7 +184,7 @@ class ShapeModifier {
         }
         this.dirtyPages.clear();
     }
-    async addConnector(pageId, fromShapeId, toShapeId, beginArrow, endArrow) {
+    async addConnector(pageId, fromShapeId, toShapeId, beginArrow, endArrow, style) {
         const parsed = this.getParsed(pageId);
         // Ensure Shapes collection exists
         if (!parsed.PageContents.Shapes) {
@@ -205,7 +205,7 @@ class ShapeModifier {
             return val;
         };
         const layout = ConnectorBuilder_1.ConnectorBuilder.calculateConnectorLayout(fromShapeId, toShapeId, shapeHierarchy);
-        const connectorShape = ConnectorBuilder_1.ConnectorBuilder.createConnectorShapeObject(newId, layout, validateArrow(beginArrow), validateArrow(endArrow));
+        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);
@@ -1012,6 +1012,45 @@ class ShapeModifier {
         }
         return result;
     }
+    /**
+     * Set the page canvas size. Writes PageWidth / PageHeight into the PageSheet
+     * and sets DrawingSizeType=0 (Custom) so Visio does not override the values.
+     */
+    setPageSize(pageId, width, height) {
+        if (width <= 0 || height <= 0)
+            throw new Error('Page dimensions must be positive');
+        const parsed = this.getParsed(pageId);
+        this.ensurePageSheet(parsed);
+        const ps = parsed.PageContents.PageSheet;
+        const upsert = (name, value) => {
+            const existing = ps.Cell.find((c) => c['@_N'] === name);
+            if (existing)
+                existing['@_V'] = value;
+            else
+                ps.Cell.push({ '@_N': name, '@_V': value });
+        };
+        upsert('PageWidth', width.toString());
+        upsert('PageHeight', height.toString());
+        upsert('DrawingSizeType', '0');
+        upsert('PageDrawSizeType', '0');
+        this.saveParsed(pageId, parsed);
+    }
+    /**
+     * Read the current page canvas dimensions.
+     * Returns 8.5 × 11 (US Letter) if no PageSheet cells are present.
+     */
+    getPageDimensions(pageId) {
+        const parsed = this.getParsed(pageId);
+        const ps = parsed.PageContents?.PageSheet;
+        if (!ps?.Cell)
+            return { width: 8.5, height: 11 };
+        const cells = Array.isArray(ps.Cell) ? ps.Cell : [ps.Cell];
+        const getVal = (name, def) => {
+            const c = cells.find((cell) => cell['@_N'] === name);
+            return c ? parseFloat(c['@_V']) : def;
+        };
+        return { width: getVal('PageWidth', 8.5), height: getVal('PageHeight', 11) };
+    }
     /**
      * Read back all hyperlinks attached to a shape.
      */

package/dist/VisioDocument.d.ts

@@ -1,9 +1,11 @@
 import { Page } from './Page';
+import { DocumentMetadata } from './types/VisioTypes';
 export declare class VisioDocument {
     private pkg;
     private pageManager;
     private _pageCache;
     private mediaManager;
+    private metadataManager;
     private constructor();
     static create(): Promise<VisioDocument>;
     static load(pathOrBuffer: string | Buffer | ArrayBuffer | Uint8Array): Promise<VisioDocument>;
@@ -27,5 +29,18 @@ export declare class VisioDocument {
      * and any BackPage references from other pages.
      */
     deletePage(page: Page): Promise<void>;
+    /**
+     * Read document metadata from `docProps/core.xml` and `docProps/app.xml`.
+     * Fields not present in the file are returned as `undefined`.
+     */
+    getMetadata(): DocumentMetadata;
+    /**
+     * Write document metadata. Only the supplied fields are changed;
+     * all other fields keep their existing values.
+     *
+     * @example
+     * doc.setMetadata({ title: 'My Diagram', author: 'Alice', company: 'ACME' });
+     */
+    setMetadata(props: Partial<DocumentMetadata>): void;
     save(filename?: string): Promise<Buffer>;
 }

package/dist/VisioDocument.js

@@ -38,12 +38,14 @@ const VisioPackage_1 = require("./VisioPackage");
 const PageManager_1 = require("./core/PageManager");
 const Page_1 = require("./Page");
 const MediaManager_1 = require("./core/MediaManager");
+const MetadataManager_1 = require("./core/MetadataManager");
 class VisioDocument {
     constructor(pkg) {
         this.pkg = pkg;
         this._pageCache = null;
         this.pageManager = new PageManager_1.PageManager(pkg);
         this.mediaManager = new MediaManager_1.MediaManager(pkg);
+        this.metadataManager = new MetadataManager_1.MetadataManager(pkg);
     }
     static async create() {
         const pkg = await VisioPackage_1.VisioPackage.create();
@@ -131,6 +133,23 @@ class VisioDocument {
         await this.pageManager.deletePage(page.id);
         this._pageCache = null;
     }
+    /**
+     * Read document metadata from `docProps/core.xml` and `docProps/app.xml`.
+     * Fields not present in the file are returned as `undefined`.
+     */
+    getMetadata() {
+        return this.metadataManager.getMetadata();
+    }
+    /**
+     * Write document metadata. Only the supplied fields are changed;
+     * all other fields keep their existing values.
+     *
+     * @example
+     * doc.setMetadata({ title: 'My Diagram', author: 'Alice', company: 'ACME' });
+     */
+    setMetadata(props) {
+        this.metadataManager.setMetadata(props);
+    }
     async save(filename) {
         return this.pkg.save(filename);
     }

package/dist/core/MetadataManager.d.ts

@@ -0,0 +1,22 @@
+import { VisioPackage } from '../VisioPackage';
+import { DocumentMetadata } from '../types/VisioTypes';
+export declare class MetadataManager {
+    private pkg;
+    private parser;
+    private builder;
+    constructor(pkg: VisioPackage);
+    /** Read document metadata from `docProps/core.xml` and `docProps/app.xml`. */
+    getMetadata(): DocumentMetadata;
+    /** Merge the supplied fields into the existing metadata and persist to the package. */
+    setMetadata(props: Partial<DocumentMetadata>): void;
+    /** Extract a string from a parsed XML node (handles plain strings and #text objects). */
+    private str;
+    /** Parse an ISO datetime string into a Date (returns undefined on failure). */
+    private date;
+    private parsedCore;
+    private parsedApp;
+    private writeCore;
+    private writeApp;
+    private blankCoreParsed;
+    private blankAppParsed;
+}

package/dist/core/MetadataManager.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataManager = void 0;
+const VisioConstants_1 = require("./VisioConstants");
+const XmlHelper_1 = require("../utils/XmlHelper");
+class MetadataManager {
+    constructor(pkg) {
+        this.pkg = pkg;
+        this.parser = (0, XmlHelper_1.createXmlParser)();
+        this.builder = (0, XmlHelper_1.createXmlBuilder)();
+    }
+    // ---- public API --------------------------------------------------------
+    /** Read document metadata from `docProps/core.xml` and `docProps/app.xml`. */
+    getMetadata() {
+        const core = this.parsedCore();
+        const app = this.parsedApp();
+        return {
+            title: this.str(core['dc:title']),
+            author: this.str(core['dc:creator']),
+            description: this.str(core['dc:description']),
+            keywords: this.str(core['cp:keywords']),
+            lastModifiedBy: this.str(core['cp:lastModifiedBy']),
+            created: this.date(core['dcterms:created']),
+            modified: this.date(core['dcterms:modified']),
+            company: this.str(app['Company']),
+            manager: this.str(app['Manager']),
+        };
+    }
+    /** Merge the supplied fields into the existing metadata and persist to the package. */
+    setMetadata(props) {
+        const coreKeys = [
+            'title', 'author', 'description', 'keywords', 'lastModifiedBy', 'created', 'modified',
+        ];
+        const appKeys = ['company', 'manager'];
+        if (coreKeys.some(k => k in props))
+            this.writeCore(props);
+        if (appKeys.some(k => k in props))
+            this.writeApp(props);
+    }
+    // ---- private helpers ---------------------------------------------------
+    /** Extract a string from a parsed XML node (handles plain strings and #text objects). */
+    str(val) {
+        if (val === undefined || val === null)
+            return undefined;
+        if (typeof val === 'string')
+            return val || undefined;
+        if (typeof val === 'object' && '#text' in val) {
+            const t = val['#text'];
+            const s = typeof t === 'string' ? t : String(t);
+            return s || undefined;
+        }
+        return undefined;
+    }
+    /** Parse an ISO datetime string into a Date (returns undefined on failure). */
+    date(val) {
+        const text = this.str(val);
+        if (!text)
+            return undefined;
+        const d = new Date(text);
+        return isNaN(d.getTime()) ? undefined : d;
+    }
+    parsedCore() {
+        try {
+            const xml = this.pkg.getFileText('docProps/core.xml');
+            const parsed = this.parser.parse(xml);
+            return parsed['cp:coreProperties'] ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    parsedApp() {
+        try {
+            const xml = this.pkg.getFileText('docProps/app.xml');
+            const parsed = this.parser.parse(xml);
+            return parsed['Properties'] ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    writeCore(props) {
+        let parsed;
+        try {
+            const xml = this.pkg.getFileText('docProps/core.xml');
+            parsed = this.parser.parse(xml);
+        }
+        catch {
+            parsed = this.blankCoreParsed();
+        }
+        const root = parsed['cp:coreProperties'];
+        if ('title' in props)
+            root['dc:title'] = props.title ?? '';
+        if ('author' in props)
+            root['dc:creator'] = props.author ?? '';
+        if ('description' in props)
+            root['dc:description'] = props.description ?? '';
+        if ('keywords' in props)
+            root['cp:keywords'] = props.keywords ?? '';
+        if ('lastModifiedBy' in props)
+            root['cp:lastModifiedBy'] = props.lastModifiedBy ?? '';
+        if ('created' in props && props.created !== undefined) {
+            root['dcterms:created'] = {
+                '@_xsi:type': 'dcterms:W3CDTF',
+                '#text': props.created.toISOString(),
+            };
+        }
+        if ('modified' in props && props.modified !== undefined) {
+            root['dcterms:modified'] = {
+                '@_xsi:type': 'dcterms:W3CDTF',
+                '#text': props.modified.toISOString(),
+            };
+        }
+        this.pkg.updateFile('docProps/core.xml', (0, XmlHelper_1.buildXml)(this.builder, parsed));
+    }
+    writeApp(props) {
+        let parsed;
+        try {
+            const xml = this.pkg.getFileText('docProps/app.xml');
+            parsed = this.parser.parse(xml);
+        }
+        catch {
+            parsed = this.blankAppParsed();
+        }
+        const root = parsed['Properties'];
+        if ('company' in props)
+            root['Company'] = props.company ?? '';
+        if ('manager' in props)
+            root['Manager'] = props.manager ?? '';
+        this.pkg.updateFile('docProps/app.xml', (0, XmlHelper_1.buildXml)(this.builder, parsed));
+    }
+    blankCoreParsed() {
+        return {
+            'cp:coreProperties': {
+                '@_xmlns:cp': VisioConstants_1.XML_NAMESPACES.CORE_PROPERTIES,
+                '@_xmlns:dc': VisioConstants_1.XML_NAMESPACES.DC_ELEMENTS,
+                '@_xmlns:dcterms': VisioConstants_1.XML_NAMESPACES.DC_TERMS,
+                '@_xmlns:dcmitype': VisioConstants_1.XML_NAMESPACES.DC_DCMITYPE,
+                '@_xmlns:xsi': VisioConstants_1.XML_NAMESPACES.XSI,
+            },
+        };
+    }
+    blankAppParsed() {
+        return {
+            'Properties': {
+                '@_xmlns': VisioConstants_1.XML_NAMESPACES.EXTENDED_PROPERTIES,
+                '@_xmlns:vt': VisioConstants_1.XML_NAMESPACES.DOC_PROPS_VTYPES,
+                'Application': 'ts-visio',
+                'Template': 'Basic',
+            },
+        };
+    }
+}
+exports.MetadataManager = MetadataManager;

package/dist/index.d.ts

@@ -7,4 +7,7 @@ export { VisioDocument } from './VisioDocument';
 export { Page } from './Page';
 export { Shape } from './Shape';
 export type { ShapeData, ShapeHyperlink } from './Shape';
+export { Layer } from './Layer';
+export { SchemaDiagram } from './SchemaDiagram';
+export { VisioValidator } from './core/VisioValidator';
 export * from './types/VisioTypes';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Shape = exports.Page = exports.VisioDocument = exports.ShapeModifier = exports.ShapeReader = exports.PageManager = exports.VisioPackage = void 0;
+exports.VisioValidator = exports.SchemaDiagram = exports.Layer = exports.Shape = exports.Page = exports.VisioDocument = exports.ShapeModifier = exports.ShapeReader = exports.PageManager = exports.VisioPackage = void 0;
 var VisioPackage_1 = require("./VisioPackage");
 Object.defineProperty(exports, "VisioPackage", { enumerable: true, get: function () { return VisioPackage_1.VisioPackage; } });
 var PageManager_1 = require("./core/PageManager");
@@ -29,4 +29,10 @@ var Page_1 = require("./Page");
 Object.defineProperty(exports, "Page", { enumerable: true, get: function () { return Page_1.Page; } });
 var Shape_1 = require("./Shape");
 Object.defineProperty(exports, "Shape", { enumerable: true, get: function () { return Shape_1.Shape; } });
+var Layer_1 = require("./Layer");
+Object.defineProperty(exports, "Layer", { enumerable: true, get: function () { return Layer_1.Layer; } });
+var SchemaDiagram_1 = require("./SchemaDiagram");
+Object.defineProperty(exports, "SchemaDiagram", { enumerable: true, get: function () { return SchemaDiagram_1.SchemaDiagram; } });
+var VisioValidator_1 = require("./core/VisioValidator");
+Object.defineProperty(exports, "VisioValidator", { enumerable: true, get: function () { return VisioValidator_1.VisioValidator; } });
 __exportStar(require("./types/VisioTypes"), exports);

package/dist/shapes/ConnectorBuilder.d.ts

@@ -1,3 +1,4 @@
+import { ConnectorStyle } from '../types/VisioTypes';
 export declare class ConnectorBuilder {
     private static getCellVal;
     private static getAbsolutePos;
@@ -17,7 +18,7 @@ export declare class ConnectorBuilder {
         width: number;
         angle: number;
     };
-    static createConnectorShapeObject(id: string, layout: any, beginArrow?: string, endArrow?: string): {
+    static createConnectorShapeObject(id: string, layout: any, beginArrow?: string, endArrow?: string, style?: ConnectorStyle): {
         '@_ID': string;
         '@_NameU': string;
         '@_Name': string;

package/dist/shapes/ConnectorBuilder.js

@@ -2,6 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectorBuilder = void 0;
 const StyleHelpers_1 = require("../utils/StyleHelpers");
+const ROUTING_VALUES = {
+    straight: '2',
+    orthogonal: '1',
+    curved: '16',
+};
 class ConnectorBuilder {
     static getCellVal(shape, name) {
         if (!shape || !shape.Cell)
@@ -96,8 +101,12 @@ class ConnectorBuilder {
         const angle = Math.atan2(dy, dx);
         return { beginX, beginY, endX, endY, width, angle };
     }
-    static createConnectorShapeObject(id, layout, beginArrow, endArrow) {
+    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';
+        const lineWeightIn = style?.lineWeight != null
+            ? (style.lineWeight / 72).toString() // convert pt → inches
+            : '0.01';
         return {
             '@_ID': id,
             '@_NameU': 'Dynamic connector',
@@ -118,7 +127,7 @@ class ConnectorBuilder {
                 { '@_N': 'ObjType', '@_V': '2' },
                 { '@_N': 'ShapePermeableX', '@_V': '0' },
                 { '@_N': 'ShapePermeableY', '@_V': '0' },
-                { '@_N': 'ShapeRouteStyle', '@_V': '1' },
+                { '@_N': 'ShapeRouteStyle', '@_V': routeStyle },
                 { '@_N': 'ConFixedCode', '@_V': '0' },
                 { '@_N': 'BeginArrow', '@_V': beginArrow || '0' },
                 { '@_N': 'BeginArrowSize', '@_V': '2' },
@@ -127,8 +136,9 @@ class ConnectorBuilder {
             ],
             Section: [
                 (0, StyleHelpers_1.createLineSection)({
-                    color: '#000000',
-                    weight: '0.01'
+                    color: style?.lineColor ?? '#000000',
+                    weight: lineWeightIn,
+                    pattern: style?.linePattern != null ? String(style.linePattern) : undefined,
                 }),
                 {
                     '@_N': 'Geometry',

package/dist/shapes/GeometryBuilder.d.ts

@@ -0,0 +1,42 @@
+import { ShapeGeometry } from '../types/VisioTypes';
+export declare class GeometryBuilder {
+    /**
+     * Build a Geometry section object for the given props.
+     * Defaults to 'rectangle' when geometry is omitted.
+     */
+    static build(props: {
+        width: number;
+        height: number;
+        geometry?: ShapeGeometry;
+        cornerRadius?: number;
+        fillColor?: string;
+    }): any;
+    /** Standard rectangle: 4 LineTo rows starting at origin. */
+    static rectangle(W: number, H: number, noFill: string): any;
+    /**
+     * Ellipse: a single Ellipse row. No MoveTo required.
+     * X, Y = centre; A, B = rightmost point; C, D = topmost point.
+     */
+    static ellipse(W: number, H: number, noFill: string): any;
+    /**
+     * Diamond: 4 LineTo rows, starting at top vertex and going clockwise
+     * (top → right → bottom → left → top), matching Visio's built-in Decision shape.
+     */
+    static diamond(W: number, H: number, noFill: string): any;
+    /**
+     * Rounded rectangle with circular corner arcs of radius `r`.
+     * Uses EllipticalArcTo with C=0 (no rotation) and D=1 (circle).
+     * The A, B control cells are the arc midpoints: r*(1-√2/2) inset from each corner.
+     */
+    static roundedRectangle(W: number, H: number, r: number, noFill: string): any;
+    /**
+     * Right-pointing triangle (standard Visio flowchart orientation).
+     * Vertices: bottom-left (0,0), apex-right (W, H/2), top-left (0, H).
+     */
+    static triangle(W: number, H: number, noFill: string): any;
+    /**
+     * Parallelogram with a rightward skew of 20% of the width.
+     * Matches the proportions of Visio's built-in "Data" flowchart shape.
+     */
+    static parallelogram(W: number, H: number, noFill: string): any;
+}

package/dist/shapes/GeometryBuilder.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeometryBuilder = void 0;
+/**
+ * For a 90° circular arc of radius r, the midpoint on the arc sits at 45° from
+ * the corner. Its distance from each endpoint along the arc edge is:
+ *   r * (1 - cos(45°)) = r * (1 - √2/2) ≈ r * 0.29289
+ * This offset is used to compute the A, B control-point cells of EllipticalArcTo.
+ */
+const ARC_OFFSET = 1 - Math.SQRT2 / 2; // ≈ 0.29289321881345254
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function cell(n, value, formula) {
+    const obj = { '@_N': n, '@_V': typeof value === 'number' ? value.toString() : value };
+    if (formula)
+        obj['@_F'] = formula;
+    return obj;
+}
+function moveTo(ix, x, y, xF, yF) {
+    return {
+        '@_T': 'MoveTo',
+        '@_IX': String(ix),
+        Cell: [cell('X', x, xF), cell('Y', y, yF)],
+    };
+}
+function lineTo(ix, x, y, xF, yF) {
+    return {
+        '@_T': 'LineTo',
+        '@_IX': String(ix),
+        Cell: [cell('X', x, xF), cell('Y', y, yF)],
+    };
+}
+function arcTo(ix, endX, endY, midX, midY) {
+    return {
+        '@_T': 'EllipticalArcTo',
+        '@_IX': String(ix),
+        Cell: [
+            cell('X', endX), // arc endpoint X
+            cell('Y', endY), // arc endpoint Y
+            cell('A', midX), // midpoint-on-arc X
+            cell('B', midY), // midpoint-on-arc Y
+            cell('C', '0'), // major-axis angle (0 = no rotation)
+            cell('D', '1'), // eccentricity ratio (1 = circle)
+        ],
+    };
+}
+function section(rows, noFill) {
+    return {
+        '@_N': 'Geometry',
+        '@_IX': '0',
+        Cell: [{ '@_N': 'NoFill', '@_V': noFill }],
+        Row: rows,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public builder
+// ---------------------------------------------------------------------------
+class GeometryBuilder {
+    /**
+     * Build a Geometry section object for the given props.
+     * Defaults to 'rectangle' when geometry is omitted.
+     */
+    static build(props) {
+        const { width: W, height: H, geometry, cornerRadius, fillColor } = props;
+        const noFill = fillColor ? '0' : '1';
+        switch (geometry) {
+            case 'ellipse':
+                return GeometryBuilder.ellipse(W, H, noFill);
+            case 'diamond':
+                return GeometryBuilder.diamond(W, H, noFill);
+            case 'rounded-rectangle': {
+                const r = cornerRadius ?? Math.min(W, H) * 0.1;
+                return GeometryBuilder.roundedRectangle(W, H, r, noFill);
+            }
+            case 'triangle':
+                return GeometryBuilder.triangle(W, H, noFill);
+            case 'parallelogram':
+                return GeometryBuilder.parallelogram(W, H, noFill);
+            case 'rectangle':
+            default:
+                return GeometryBuilder.rectangle(W, H, noFill);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Individual geometry factories (also exported for direct use / testing)
+    // -----------------------------------------------------------------------
+    /** Standard rectangle: 4 LineTo rows starting at origin. */
+    static rectangle(W, H, noFill) {
+        return section([
+            moveTo(1, 0, 0),
+            lineTo(2, W, 0, 'Width'),
+            lineTo(3, W, H, 'Width', 'Height'),
+            lineTo(4, 0, H, undefined, 'Height'),
+            lineTo(5, 0, 0),
+        ], noFill);
+    }
+    /**
+     * Ellipse: a single Ellipse row. No MoveTo required.
+     * X, Y = centre; A, B = rightmost point; C, D = topmost point.
+     */
+    static ellipse(W, H, noFill) {
+        return section([
+            {
+                '@_T': 'Ellipse',
+                '@_IX': '1',
+                Cell: [
+                    cell('X', W / 2, 'Width*0.5'), // centre X
+                    cell('Y', H / 2, 'Height*0.5'), // centre Y
+                    cell('A', W, 'Width'), // right X
+                    cell('B', H / 2, 'Height*0.5'), // right Y
+                    cell('C', W / 2, 'Width*0.5'), // top X
+                    cell('D', H, 'Height'), // top Y
+                ],
+            },
+        ], noFill);
+    }
+    /**
+     * Diamond: 4 LineTo rows, starting at top vertex and going clockwise
+     * (top → right → bottom → left → top), matching Visio's built-in Decision shape.
+     */
+    static diamond(W, H, noFill) {
+        return section([
+            moveTo(1, W / 2, H, 'Width*0.5', 'Height'), // top
+            lineTo(2, W, H / 2, 'Width', 'Height*0.5'), // right
+            lineTo(3, W / 2, 0, 'Width*0.5'), // bottom
+            lineTo(4, 0, H / 2, undefined, 'Height*0.5'), // left
+            lineTo(5, W / 2, H, 'Width*0.5', 'Height'), // close
+        ], noFill);
+    }
+    /**
+     * Rounded rectangle with circular corner arcs of radius `r`.
+     * Uses EllipticalArcTo with C=0 (no rotation) and D=1 (circle).
+     * The A, B control cells are the arc midpoints: r*(1-√2/2) inset from each corner.
+     */
+    static roundedRectangle(W, H, r, noFill) {
+        const k = r * ARC_OFFSET; // midpoint inset ≈ r * 0.2929
+        return section([
+            moveTo(1, r, 0),
+            lineTo(2, W - r, 0),
+            arcTo(3, W, r, W - k, k), // bottom-right corner
+            lineTo(4, W, H - r),
+            arcTo(5, W - r, H, W - k, H - k), // top-right corner
+            lineTo(6, r, H),
+            arcTo(7, 0, H - r, k, H - k), // top-left corner
+            lineTo(8, 0, r),
+            arcTo(9, r, 0, k, k), // bottom-left corner (closes path)
+        ], noFill);
+    }
+    /**
+     * Right-pointing triangle (standard Visio flowchart orientation).
+     * Vertices: bottom-left (0,0), apex-right (W, H/2), top-left (0, H).
+     */
+    static triangle(W, H, noFill) {
+        return section([
+            moveTo(1, 0, 0),
+            lineTo(2, W, H / 2, 'Width', 'Height*0.5'),
+            lineTo(3, 0, H, undefined, 'Height'),
+            lineTo(4, 0, 0),
+        ], noFill);
+    }
+    /**
+     * Parallelogram with a rightward skew of 20% of the width.
+     * Matches the proportions of Visio's built-in "Data" flowchart shape.
+     */
+    static parallelogram(W, H, noFill) {
+        const s = W * 0.2; // horizontal skew offset
+        return section([
+            moveTo(1, s, 0),
+            lineTo(2, W, 0, 'Width'),
+            lineTo(3, W - s, H),
+            lineTo(4, 0, H, undefined, 'Height'),
+            lineTo(5, s, 0),
+        ], noFill);
+    }
+}
+exports.GeometryBuilder = GeometryBuilder;

package/dist/shapes/ShapeBuilder.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShapeBuilder = void 0;
 const StyleHelpers_1 = require("../utils/StyleHelpers");
+const GeometryBuilder_1 = require("./GeometryBuilder");
 class ShapeBuilder {
     static createStandardShape(id, props) {
         // Validate dimensions
@@ -53,18 +54,7 @@ class ShapeBuilder {
         // Add Geometry
         // Only if NOT a Group AND NOT a Master Instance
         if (props.type !== 'Group' && !props.masterId) {
-            shape.Section.push({
-                '@_N': 'Geometry',
-                '@_IX': '0',
-                Cell: [{ '@_N': 'NoFill', '@_V': props.fillColor ? '0' : '1' }],
-                Row: [
-                    { '@_T': 'MoveTo', '@_IX': '1', Cell: [{ '@_N': 'X', '@_V': '0' }, { '@_N': 'Y', '@_V': '0' }] },
-                    { '@_T': 'LineTo', '@_IX': '2', Cell: [{ '@_N': 'X', '@_V': props.width.toString(), '@_F': 'Width' }, { '@_N': 'Y', '@_V': '0' }] },
-                    { '@_T': 'LineTo', '@_IX': '3', Cell: [{ '@_N': 'X', '@_V': props.width.toString(), '@_F': 'Width' }, { '@_N': 'Y', '@_V': props.height.toString(), '@_F': 'Height' }] },
-                    { '@_T': 'LineTo', '@_IX': '4', Cell: [{ '@_N': 'X', '@_V': '0' }, { '@_N': 'Y', '@_V': props.height.toString(), '@_F': 'Height' }] },
-                    { '@_T': 'LineTo', '@_IX': '5', Cell: [{ '@_N': 'X', '@_V': '0' }, { '@_N': 'Y', '@_V': '0' }] }
-                ]
-            });
+            shape.Section.push(GeometryBuilder_1.GeometryBuilder.build(props));
         }
         // Handle Text if provided
         if (props.text !== undefined && props.text !== null) {

package/dist/types/VisioTypes.d.ts

@@ -72,6 +72,80 @@ export declare enum VisioPropType {
     Duration = 6,
     Currency = 7
 }
+/** Document-level metadata that maps to `docProps/core.xml` and `docProps/app.xml`. */
+export interface DocumentMetadata {
+    /** Document title (`dc:title`). */
+    title?: string;
+    /** Author / creator (`dc:creator`). */
+    author?: string;
+    /** Short description (`dc:description`). */
+    description?: string;
+    /** Space-separated keywords (`cp:keywords`). */
+    keywords?: string;
+    /** Last-modified-by user (`cp:lastModifiedBy`). */
+    lastModifiedBy?: string;
+    /** Company name from `app.xml` `<Company>`. */
+    company?: string;
+    /** Manager name from `app.xml` `<Manager>`. */
+    manager?: string;
+    /** Document creation timestamp (`dcterms:created`). */
+    created?: Date;
+    /** Last-modified timestamp (`dcterms:modified`). */
+    modified?: Date;
+}
+export type PageOrientation = 'portrait' | 'landscape';
+/** Common paper sizes in inches (width × height in portrait orientation). */
+export declare const PageSizes: {
+    readonly Letter: {
+        readonly width: 8.5;
+        readonly height: 11;
+    };
+    readonly Legal: {
+        readonly width: 8.5;
+        readonly height: 14;
+    };
+    readonly Tabloid: {
+        readonly width: 11;
+        readonly height: 17;
+    };
+    readonly A3: {
+        readonly width: 11.693;
+        readonly height: 16.535;
+    };
+    readonly A4: {
+        readonly width: 8.268;
+        readonly height: 11.693;
+    };
+    readonly A5: {
+        readonly width: 5.827;
+        readonly height: 8.268;
+    };
+};
+export type PageSizeName = keyof typeof PageSizes;
+/** Connector line-routing algorithm. */
+export type ConnectorRouting = 'straight' | 'orthogonal' | 'curved';
+/**
+ * Style options for a connector (dynamic connector shape).
+ * All fields are optional; omitted fields retain their defaults.
+ */
+export interface ConnectorStyle {
+    /** Line stroke color as a CSS hex string (e.g. `'#ff0000'`). */
+    lineColor?: string;
+    /**
+     * Stroke weight in **points** (e.g. `1` for a 1 pt line).
+     * Converted to inches internally (pt / 72).
+     */
+    lineWeight?: number;
+    /**
+     * Line pattern.  0 = no line, 1 = solid (default), 2 = dashed,
+     * 3 = dotted, 4 = dash-dot, etc.  Matches Visio's LinePattern cell.
+     */
+    linePattern?: number;
+    /** How Visio routes the connector between its endpoints. */
+    routing?: ConnectorRouting;
+}
+/** Non-rectangular geometry variants supported by ShapeBuilder. */
+export type ShapeGeometry = 'rectangle' | 'ellipse' | 'diamond' | 'rounded-rectangle' | 'triangle' | 'parallelogram';
 export interface NewShapeProps {
     text: string;
     x: number;
@@ -90,6 +164,10 @@ export interface NewShapeProps {
     horzAlign?: 'left' | 'center' | 'right' | 'justify';
     /** Vertical text alignment within the shape. */
     verticalAlign?: 'top' | 'middle' | 'bottom';
+    /** Shape geometry. Defaults to 'rectangle'. */
+    geometry?: ShapeGeometry;
+    /** Corner radius in inches for 'rounded-rectangle'. Defaults to 10% of the smaller dimension. */
+    cornerRadius?: number;
     type?: string;
     masterId?: string;
     imgRelId?: string;

package/dist/types/VisioTypes.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VisioPropType = void 0;
+exports.PageSizes = exports.VisioPropType = void 0;
 var VisioPropType;
 (function (VisioPropType) {
     VisioPropType[VisioPropType["String"] = 0] = "String";
@@ -12,3 +12,12 @@ var VisioPropType;
     VisioPropType[VisioPropType["Duration"] = 6] = "Duration";
     VisioPropType[VisioPropType["Currency"] = 7] = "Currency";
 })(VisioPropType || (exports.VisioPropType = VisioPropType = {}));
+/** Common paper sizes in inches (width × height in portrait orientation). */
+exports.PageSizes = {
+    Letter: { width: 8.5, height: 11 },
+    Legal: { width: 8.5, height: 14 },
+    Tabloid: { width: 11, height: 17 },
+    A3: { width: 11.693, height: 16.535 },
+    A4: { width: 8.268, height: 11.693 },
+    A5: { width: 5.827, height: 8.268 },
+};

package/package.json

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