ts-visio 1.6.0 → 1.9.0

package/README.md

@@ -26,6 +26,7 @@ Built using specific schema-level abstractions to handle the complex internal st
 - **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.
+- **StyleSheets**: Create document-level named styles with fill, line, and text properties via `doc.createStyle()` and apply them to shapes at creation time (`styleId`) or post-creation (`shape.applyStyle()`).
 
 Feature gaps are being tracked in [FEATURES.md](./FEATURES.md).
 
@@ -610,6 +611,89 @@ Unknown port names fall back gracefully to edge-intersection routing without thr
 
 ---
 
+#### 29. StyleSheets (Document-Level Styles)
+Define reusable named styles at the document level and apply them to shapes so they inherit line, fill, and text properties without repeating the same values on every shape.
+
+```typescript
+// 1. Create a document-level style
+const headerStyle = doc.createStyle('Header', {
+    fillColor:    '#4472C4',          // Blue fill
+    lineColor:    '#2F5597',          // Dark-blue border
+    lineWeight:   1.5,                // 1.5 pt stroke
+    fontColor:    '#FFFFFF',          // White text
+    fontSize:     14,                 // 14 pt
+    bold:         true,
+    fontFamily:   'Calibri',
+    horzAlign:    'center',
+    verticalAlign: 'middle',
+});
+
+const bodyStyle = doc.createStyle('Body', {
+    fillColor:  '#DEEAF1',
+    lineColor:  '#2F5597',
+    fontSize:   11,
+    horzAlign:  'left',
+});
+
+// 2. Apply at shape-creation time
+const title = await page.addShape({
+    text: 'System Architecture',
+    x: 1, y: 8, width: 8, height: 1,
+    styleId: headerStyle.id,          // sets LineStyle, FillStyle, TextStyle
+});
+
+// Fine-grained: apply only the fill from one style, line from another
+const hybrid = await page.addShape({
+    text: 'Hybrid',
+    x: 1, y: 6, width: 3, height: 1,
+    fillStyleId: headerStyle.id,
+    lineStyleId: bodyStyle.id,
+});
+
+// 3. Apply (or change) style post-creation
+const box = await page.addShape({ text: 'Server', x: 4, y: 4, width: 2, height: 1 });
+box.applyStyle(bodyStyle.id);                // all three categories
+box.applyStyle(headerStyle.id, 'fill');      // fill only — leaves line & text unchanged
+box.applyStyle(headerStyle.id, 'text');      // text only
+
+// 4. List all styles in the document
+const styles = doc.getStyles();
+// [ { id: 0, name: 'No Style' }, { id: 1, name: 'Normal' }, { id: 2, name: 'Header' }, … ]
+```
+
+`StyleProps` supports: `fillColor`, `lineColor`, `lineWeight` (pt), `linePattern`, `fontColor`, `fontSize` (pt), `bold`, `italic`, `underline`, `strikethrough`, `fontFamily`, `horzAlign`, `verticalAlign`, `spaceBefore`, `spaceAfter`, `lineSpacing`, `textMarginTop/Bottom/Left/Right` (in).
+Local shape properties always override inherited stylesheet values.
+
+#### 30. Reading Connectors Back
+Enumerate connectors on a page — including those loaded from an existing `.vsdx` file — and inspect or delete them.
+
+```typescript
+import { VisioDocument } from 'ts-visio';
+
+const doc  = await VisioDocument.load(buffer);   // or VisioDocument.create()
+const page = doc.pages[0];
+
+// Read all connector shapes
+const connectors = page.getConnectors();
+
+for (const conn of connectors) {
+    console.log(`Connector ${conn.id}: ${conn.fromShapeId} → ${conn.toShapeId}`);
+    console.log('  fromPort:', conn.fromPort);     // 'center' | { name } | { index }
+    console.log('  toPort:',   conn.toPort);
+    console.log('  style:',    conn.style);        // lineColor, lineWeight, linePattern, routing
+    console.log('  arrows:',   conn.beginArrow, conn.endArrow);
+}
+
+// Delete a specific connector
+await connectors[0].delete();
+
+// After delete the connector is gone but the shapes remain
+console.log(page.getConnectors().length);  // 0
+console.log(page.getShapes().length);      // shapes still exist
+```
+
+---
+
 ## Examples
 
 Check out the [examples](./examples) directory for complete scripts.

package/dist/Connector.d.ts

@@ -0,0 +1,53 @@
+import { ConnectorStyle, ConnectionTarget } from './types/VisioTypes';
+import { ShapeModifier } from './ShapeModifier';
+/**
+ * Raw data extracted from the page XML for a single connector shape.
+ * Returned by `ShapeReader.readConnectors()` and wrapped by the `Connector` class.
+ */
+export interface ConnectorData {
+    /** Visio shape ID of the connector (1D shape). */
+    id: string;
+    /** ID of the shape at the connector's begin-point (BeginX). */
+    fromShapeId: string;
+    /** ID of the shape at the connector's end-point (EndX). */
+    toShapeId: string;
+    /** Connection point used on the from-shape. */
+    fromPort: ConnectionTarget;
+    /** Connection point used on the to-shape. */
+    toPort: ConnectionTarget;
+    /** Line style extracted from the connector's Line section. */
+    style: ConnectorStyle;
+    /** Begin-arrow head value (Visio ArrowHeads integer string). */
+    beginArrow: string;
+    /** End-arrow head value (Visio ArrowHeads integer string). */
+    endArrow: string;
+}
+/**
+ * A read/delete wrapper around a connector shape found on a page.
+ * Obtain instances via `page.getConnectors()`.
+ */
+export declare class Connector {
+    private readonly pageId;
+    private readonly modifier;
+    /** Visio shape ID of this connector. */
+    readonly id: string;
+    /** ID of the shape this connector starts from. */
+    readonly fromShapeId: string;
+    /** ID of the shape this connector ends at. */
+    readonly toShapeId: string;
+    /** Connection point used on the from-shape ('center', `{ name }`, or `{ index }`). */
+    readonly fromPort: ConnectionTarget;
+    /** Connection point used on the to-shape ('center', `{ name }`, or `{ index }`). */
+    readonly toPort: ConnectionTarget;
+    /** Line style (color, weight, pattern, routing) for this connector. */
+    readonly style: ConnectorStyle;
+    /** Begin-arrow head value string (e.g. `'0'` = none, `'1'` = standard). */
+    readonly beginArrow: string;
+    /** End-arrow head value string (e.g. `'0'` = none, `'1'` = standard). */
+    readonly endArrow: string;
+    constructor(data: ConnectorData, pageId: string, modifier: ShapeModifier);
+    /**
+     * Delete this connector from the page (removes the shape and its Connect entries).
+     */
+    delete(): Promise<void>;
+}

package/dist/Connector.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Connector = void 0;
+/**
+ * A read/delete wrapper around a connector shape found on a page.
+ * Obtain instances via `page.getConnectors()`.
+ */
+class Connector {
+    constructor(data, pageId, modifier) {
+        this.pageId = pageId;
+        this.modifier = modifier;
+        this.id = data.id;
+        this.fromShapeId = data.fromShapeId;
+        this.toShapeId = data.toShapeId;
+        this.fromPort = data.fromPort;
+        this.toPort = data.toPort;
+        this.style = data.style;
+        this.beginArrow = data.beginArrow;
+        this.endArrow = data.endArrow;
+    }
+    /**
+     * Delete this connector from the page (removes the shape and its Connect entries).
+     */
+    async delete() {
+        await this.modifier.deleteShape(this.pageId, this.id);
+    }
+}
+exports.Connector = Connector;

package/dist/Page.d.ts

@@ -1,4 +1,5 @@
 import { VisioPage, ConnectorStyle, PageOrientation, PageSizeName, ConnectionTarget } from './types/VisioTypes';
+import { Connector } from './Connector';
 import { VisioPackage } from './VisioPackage';
 import { ShapeModifier } from './ShapeModifier';
 import { NewShapeProps } from './types/VisioTypes';
@@ -50,6 +51,12 @@ export declare class Page {
      */
     findShapes(predicate: (shape: Shape) => boolean): Shape[];
     addShape(props: NewShapeProps, parentId?: string): Promise<Shape>;
+    /**
+     * Return all connector shapes on the page.
+     * Each `Connector` exposes the from/to shape IDs, port targets, line style, arrows,
+     * and a `delete()` method to remove the connector.
+     */
+    getConnectors(): Connector[];
     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>;

package/dist/Page.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Page = void 0;
 const VisioTypes_1 = require("./types/VisioTypes");
+const Connector_1 = require("./Connector");
 const ShapeReader_1 = require("./ShapeReader");
 const ShapeModifier_1 = require("./ShapeModifier");
 const Shape_1 = require("./Shape");
@@ -124,6 +125,22 @@ class Page {
         });
         return new Shape_1.Shape(internalStub, this.id, this.pkg, this.modifier);
     }
+    /**
+     * Return all connector shapes on the page.
+     * Each `Connector` exposes the from/to shape IDs, port targets, line style, arrows,
+     * and a `delete()` method to remove the connector.
+     */
+    getConnectors() {
+        const reader = new ShapeReader_1.ShapeReader(this.pkg);
+        try {
+            const data = reader.readConnectors(this.pagePath);
+            return data.map(d => new Connector_1.Connector(d, this.id, this.modifier));
+        }
+        catch (e) {
+            console.warn(`Could not read connectors for page ${this.id}:`, e);
+            return [];
+        }
+    }
     async connectShapes(fromShape, toShape, beginArrow, endArrow, style, fromPort, toPort) {
         await this.modifier.addConnector(this.id, fromShape.id, toShape.id, beginArrow, endArrow, style, fromPort, toPort);
     }

package/dist/Shape.d.ts

@@ -36,6 +36,15 @@ export declare class Shape {
      * Returns the zero-based index (IX) of the newly added point.
      */
     addConnectionPoint(point: ConnectionPointDef): number;
+    /**
+     * Apply a document-level stylesheet to this shape.
+     * Create styles via `doc.createStyle()` and pass the returned `id`.
+     *
+     * @param styleId  The stylesheet ID to apply.
+     * @param which    `'all'` (default) applies to line, fill, and text;
+     *                 `'line'`, `'fill'`, or `'text'` applies to only that category.
+     */
+    applyStyle(styleId: number, which?: 'all' | 'line' | 'fill' | 'text'): this;
     setStyle(style: ShapeStyle): Promise<this>;
     placeRightOf(targetShape: Shape, options?: {
         gap: number;

package/dist/Shape.js

@@ -53,6 +53,18 @@ class Shape {
     addConnectionPoint(point) {
         return this.modifier.addConnectionPoint(this.pageId, this.id, point);
     }
+    /**
+     * Apply a document-level stylesheet to this shape.
+     * Create styles via `doc.createStyle()` and pass the returned `id`.
+     *
+     * @param styleId  The stylesheet ID to apply.
+     * @param which    `'all'` (default) applies to line, fill, and text;
+     *                 `'line'`, `'fill'`, or `'text'` applies to only that category.
+     */
+    applyStyle(styleId, which = 'all') {
+        this.modifier.applyStyle(this.pageId, this.id, styleId, which);
+        return this;
+    }
     async setStyle(style) {
         await this.modifier.updateShapeStyle(this.pageId, this.id, style);
         return this;

package/dist/ShapeModifier.d.ts

@@ -37,6 +37,13 @@ export declare class ShapeModifier {
      * Returns the zero-based IX (row index) of the newly added point.
      */
     addConnectionPoint(pageId: string, shapeId: string, point: ConnectionPointDef): number;
+    /**
+     * Apply a document-level stylesheet to an existing shape by setting its
+     * `LineStyle`, `FillStyle`, and/or `TextStyle` attributes.
+     *
+     * @param which  `'all'` (default) sets all three; `'line'`, `'fill'`, or `'text'` sets only one.
+     */
+    applyStyle(pageId: string, shapeId: string, styleId: number, which?: 'all' | 'line' | 'fill' | 'text'): void;
     addShape(pageId: string, props: NewShapeProps, parentId?: string): Promise<string>;
     deleteShape(pageId: string, shapeId: string): Promise<void>;
     private removeShapeFromTree;
@@ -124,6 +131,12 @@ export declare class ShapeModifier {
 }
 export interface ShapeStyle {
     fillColor?: string;
+    /** Border/stroke colour as a CSS hex string (e.g. `'#cc0000'`). */
+    lineColor?: string;
+    /** Stroke weight in **points**. Stored internally as inches (pt / 72). */
+    lineWeight?: number;
+    /** Line pattern. 0 = none, 1 = solid (default), 2 = dash, 3 = dot, 4 = dash-dot. */
+    linePattern?: number;
     fontColor?: string;
     bold?: boolean;
     /** Italic text. */

package/dist/ShapeModifier.js

@@ -244,6 +244,27 @@ class ShapeModifier {
         this.saveParsed(pageId, parsed);
         return ix;
     }
+    /**
+     * Apply a document-level stylesheet to an existing shape by setting its
+     * `LineStyle`, `FillStyle`, and/or `TextStyle` attributes.
+     *
+     * @param which  `'all'` (default) sets all three; `'line'`, `'fill'`, or `'text'` sets only one.
+     */
+    applyStyle(pageId, shapeId, styleId, which = 'all') {
+        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}`);
+        const sid = styleId.toString();
+        if (which === 'all' || which === 'line')
+            shape['@_LineStyle'] = sid;
+        if (which === 'all' || which === 'fill')
+            shape['@_FillStyle'] = sid;
+        if (which === 'all' || which === 'text')
+            shape['@_TextStyle'] = sid;
+        this.saveParsed(pageId, parsed);
+    }
     async addShape(pageId, props, parentId) {
         const parsed = this.getParsed(pageId);
         // Ensure Shapes container exists
@@ -379,6 +400,18 @@ class ShapeModifier {
             shape.Section = shape.Section.filter((s) => s['@_N'] !== 'Fill');
             shape.Section.push((0, StyleHelpers_1.createFillSection)(style.fillColor));
         }
+        // Update/Add Line
+        const hasLineProps = style.lineColor !== undefined
+            || style.lineWeight !== undefined
+            || style.linePattern !== undefined;
+        if (hasLineProps) {
+            shape.Section = shape.Section.filter((s) => s['@_N'] !== 'Line');
+            shape.Section.push((0, StyleHelpers_1.createLineSection)({
+                color: style.lineColor,
+                weight: style.lineWeight !== undefined ? (style.lineWeight / 72).toString() : undefined,
+                pattern: style.linePattern !== undefined ? style.linePattern.toString() : undefined,
+            }));
+        }
         // Update/Add Character (Font/Text Style)
         const hasCharProps = style.fontColor !== undefined
             || style.bold !== undefined

package/dist/ShapeReader.d.ts

@@ -1,5 +1,6 @@
 import { VisioPackage } from './VisioPackage';
 import { VisioShape } from './types/VisioTypes';
+import { ConnectorData } from './Connector';
 export declare class ShapeReader {
     private pkg;
     private parser;
@@ -15,6 +16,14 @@ export declare class ShapeReader {
      * Returns undefined if not found.
      */
     readShapeById(path: string, shapeId: string): VisioShape | undefined;
+    /**
+     * Read all connector shapes from a page XML file.
+     * A shape is considered a connector if it has `ObjType=2` or a `BeginX` cell,
+     * and is referenced in the page's `<Connects>` section.
+     */
+    readConnectors(path: string): ConnectorData[];
+    /** Decode a Visio ToPart integer string to a ConnectionTarget. */
+    private decodeToPart;
     private gatherShapes;
     private findShapeById;
     private parseShape;

package/dist/ShapeReader.js

@@ -63,6 +63,125 @@ class ShapeReader {
             return undefined;
         return this.findShapeById((0, VisioParsers_1.asArray)(shapesData), shapeId);
     }
+    /**
+     * Read all connector shapes from a page XML file.
+     * A shape is considered a connector if it has `ObjType=2` or a `BeginX` cell,
+     * and is referenced in the page's `<Connects>` section.
+     */
+    readConnectors(path) {
+        let content;
+        try {
+            content = this.pkg.getFileText(path);
+        }
+        catch {
+            return [];
+        }
+        const parsed = this.parser.parse(content);
+        const shapesData = parsed.PageContents?.Shapes?.Shape;
+        if (!shapesData)
+            return [];
+        // Build a flat map of all shapes by ID (including nested)
+        const shapeMap = new Map();
+        const collectShapes = (list) => {
+            for (const s of list) {
+                shapeMap.set(s['@_ID'], s);
+                if (s.Shapes?.Shape)
+                    collectShapes((0, VisioParsers_1.asArray)(s.Shapes.Shape));
+            }
+        };
+        collectShapes((0, VisioParsers_1.asArray)(shapesData));
+        // Identify connector shapes by ObjType=2 or presence of BeginX cell
+        const connectorShapes = [];
+        for (const [, shape] of shapeMap) {
+            const cells = (0, VisioParsers_1.parseCells)(shape);
+            if (cells['ObjType']?.V === '2' || cells['BeginX'] !== undefined) {
+                connectorShapes.push(shape);
+            }
+        }
+        if (connectorShapes.length === 0)
+            return [];
+        // Group <Connect> elements by connector ID (FromSheet)
+        const connectsRaw = parsed.PageContents?.Connects?.Connect;
+        const connects = (0, VisioParsers_1.asArray)(connectsRaw);
+        const connectsByConnector = new Map();
+        for (const c of connects) {
+            const fromSheet = c['@_FromSheet'];
+            const fromCell = c['@_FromCell'];
+            if (!connectsByConnector.has(fromSheet)) {
+                connectsByConnector.set(fromSheet, {});
+            }
+            const entry = connectsByConnector.get(fromSheet);
+            if (fromCell === 'BeginX')
+                entry.beginConnect = c;
+            else if (fromCell === 'EndX')
+                entry.endConnect = c;
+        }
+        const ROUTING_BY_VALUE = {
+            '1': 'orthogonal',
+            '2': 'straight',
+            '16': 'curved',
+        };
+        const result = [];
+        for (const connShape of connectorShapes) {
+            const connId = connShape['@_ID'];
+            const entry = connectsByConnector.get(connId);
+            if (!entry?.beginConnect || !entry?.endConnect)
+                continue;
+            const { beginConnect, endConnect } = entry;
+            const fromShapeId = beginConnect['@_ToSheet'];
+            const toShapeId = endConnect['@_ToSheet'];
+            const fromPort = this.decodeToPart(beginConnect['@_ToPart']);
+            const toPort = this.decodeToPart(endConnect['@_ToPart']);
+            // Extract line style from the connector's Line section
+            const sections = (0, VisioParsers_1.asArray)(connShape.Section);
+            let lineColor;
+            let lineWeight;
+            let linePattern;
+            for (const sec of sections) {
+                if (sec['@_N'] === 'Line') {
+                    const lineCells = (0, VisioParsers_1.parseCells)(sec);
+                    if (lineCells['LineColor']?.V)
+                        lineColor = lineCells['LineColor'].V;
+                    if (lineCells['LineWeight']?.V)
+                        lineWeight = parseFloat(lineCells['LineWeight'].V) * 72; // in→pt
+                    if (lineCells['LinePattern']?.V)
+                        linePattern = parseInt(lineCells['LinePattern'].V, 10);
+                }
+            }
+            const cells = (0, VisioParsers_1.parseCells)(connShape);
+            const routeStyleVal = cells['ShapeRouteStyle']?.V;
+            const routing = routeStyleVal ? ROUTING_BY_VALUE[routeStyleVal] : undefined;
+            const style = {};
+            if (lineColor !== undefined)
+                style.lineColor = lineColor;
+            if (lineWeight !== undefined)
+                style.lineWeight = lineWeight;
+            if (linePattern !== undefined)
+                style.linePattern = linePattern;
+            if (routing !== undefined)
+                style.routing = routing;
+            result.push({
+                id: connId,
+                fromShapeId,
+                toShapeId,
+                fromPort,
+                toPort,
+                style,
+                beginArrow: cells['BeginArrow']?.V ?? '0',
+                endArrow: cells['EndArrow']?.V ?? '0',
+            });
+        }
+        return result;
+    }
+    /** Decode a Visio ToPart integer string to a ConnectionTarget. */
+    decodeToPart(toPart) {
+        const part = toPart !== undefined ? parseInt(toPart, 10) : 3;
+        if (isNaN(part) || part === 3)
+            return 'center';
+        if (part >= 100)
+            return { index: part - 100 };
+        return 'center';
+    }
     gatherShapes(rawShapes, result) {
         for (const s of rawShapes) {
             result.push(this.parseShape(s));

package/dist/VisioDocument.d.ts

@@ -1,11 +1,12 @@
 import { Page } from './Page';
-import { DocumentMetadata } from './types/VisioTypes';
+import { DocumentMetadata, StyleProps, StyleRecord } from './types/VisioTypes';
 export declare class VisioDocument {
     private pkg;
     private pageManager;
     private _pageCache;
     private mediaManager;
     private metadataManager;
+    private styleSheetManager;
     private constructor();
     static create(): Promise<VisioDocument>;
     static load(pathOrBuffer: string | Buffer | ArrayBuffer | Uint8Array): Promise<VisioDocument>;
@@ -42,5 +43,18 @@ export declare class VisioDocument {
      * doc.setMetadata({ title: 'My Diagram', author: 'Alice', company: 'ACME' });
      */
     setMetadata(props: Partial<DocumentMetadata>): void;
+    /**
+     * Create a named document-level stylesheet and return its record.
+     * The returned `id` can be passed to `addShape({ styleId })` or `shape.applyStyle()`.
+     *
+     * @example
+     * const s = doc.createStyle('Header', { fillColor: '#4472C4', fontColor: '#ffffff', bold: true });
+     * const shape = await page.addShape({ text: 'Title', x: 1, y: 1, width: 3, height: 1, styleId: s.id });
+     */
+    createStyle(name: string, props?: StyleProps): StyleRecord;
+    /**
+     * Return all stylesheets defined in the document (including built-in styles).
+     */
+    getStyles(): StyleRecord[];
     save(filename?: string): Promise<Buffer>;
 }

package/dist/VisioDocument.js

@@ -39,6 +39,7 @@ const PageManager_1 = require("./core/PageManager");
 const Page_1 = require("./Page");
 const MediaManager_1 = require("./core/MediaManager");
 const MetadataManager_1 = require("./core/MetadataManager");
+const StyleSheetManager_1 = require("./core/StyleSheetManager");
 class VisioDocument {
     constructor(pkg) {
         this.pkg = pkg;
@@ -46,6 +47,7 @@ class VisioDocument {
         this.pageManager = new PageManager_1.PageManager(pkg);
         this.mediaManager = new MediaManager_1.MediaManager(pkg);
         this.metadataManager = new MetadataManager_1.MetadataManager(pkg);
+        this.styleSheetManager = new StyleSheetManager_1.StyleSheetManager(pkg);
     }
     static async create() {
         const pkg = await VisioPackage_1.VisioPackage.create();
@@ -150,6 +152,23 @@ class VisioDocument {
     setMetadata(props) {
         this.metadataManager.setMetadata(props);
     }
+    /**
+     * Create a named document-level stylesheet and return its record.
+     * The returned `id` can be passed to `addShape({ styleId })` or `shape.applyStyle()`.
+     *
+     * @example
+     * const s = doc.createStyle('Header', { fillColor: '#4472C4', fontColor: '#ffffff', bold: true });
+     * const shape = await page.addShape({ text: 'Title', x: 1, y: 1, width: 3, height: 1, styleId: s.id });
+     */
+    createStyle(name, props = {}) {
+        return this.styleSheetManager.createStyle(name, props);
+    }
+    /**
+     * Return all stylesheets defined in the document (including built-in styles).
+     */
+    getStyles() {
+        return this.styleSheetManager.getStyles();
+    }
     async save(filename) {
         return this.pkg.save(filename);
     }

package/dist/core/StyleSheetManager.d.ts

@@ -0,0 +1,37 @@
+import { VisioPackage } from '../VisioPackage';
+import { StyleProps, StyleRecord } from '../types/VisioTypes';
+/**
+ * Manages document-level stylesheets stored in `visio/document.xml`.
+ *
+ * Stylesheets define reusable sets of line, fill, and text properties that
+ * shapes inherit via the `LineStyle`, `FillStyle`, and `TextStyle` attributes.
+ *
+ * The minimal document template ships with:
+ *   - ID 0  "No Style"  — the inheritance root (all shapes fall back here)
+ *   - ID 1  "Normal"    — empty style inheriting everything from ID 0
+ *
+ * User-created styles receive IDs starting at 2.
+ */
+export declare class StyleSheetManager {
+    private pkg;
+    private parser;
+    private builder;
+    constructor(pkg: VisioPackage);
+    /**
+     * Create a new named document-level stylesheet and return its record.
+     * The returned `id` can be passed to `addShape({ styleId })` or `shape.applyStyle()`.
+     */
+    createStyle(name: string, props?: StyleProps): StyleRecord;
+    /**
+     * Return all stylesheets defined in the document (including the built-in ones).
+     */
+    getStyles(): StyleRecord[];
+    private getParsedDoc;
+    private saveParsedDoc;
+    /** Ensure `<StyleSheets>` contains at least Style 0 and Style 1. */
+    private ensureStyleSheets;
+    private nextId;
+    /** Normalise a fast-xml-parser value that may be undefined, a single object, or an array. */
+    private normalizeArray;
+    private buildStyleSheetXml;
+}

package/dist/core/StyleSheetManager.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StyleSheetManager = void 0;
+const StyleHelpers_1 = require("../utils/StyleHelpers");
+const XmlHelper_1 = require("../utils/XmlHelper");
+const HORZ_ALIGN = {
+    left: '0', center: '1', right: '2', justify: '3',
+};
+const VERT_ALIGN = {
+    top: '0', middle: '1', bottom: '2',
+};
+/**
+ * Manages document-level stylesheets stored in `visio/document.xml`.
+ *
+ * Stylesheets define reusable sets of line, fill, and text properties that
+ * shapes inherit via the `LineStyle`, `FillStyle`, and `TextStyle` attributes.
+ *
+ * The minimal document template ships with:
+ *   - ID 0  "No Style"  — the inheritance root (all shapes fall back here)
+ *   - ID 1  "Normal"    — empty style inheriting everything from ID 0
+ *
+ * User-created styles receive IDs starting at 2.
+ */
+class StyleSheetManager {
+    constructor(pkg) {
+        this.pkg = pkg;
+        this.parser = (0, XmlHelper_1.createXmlParser)();
+        this.builder = (0, XmlHelper_1.createXmlBuilder)();
+    }
+    // ── Public API ────────────────────────────────────────────────────────────
+    /**
+     * Create a new named document-level stylesheet and return its record.
+     * The returned `id` can be passed to `addShape({ styleId })` or `shape.applyStyle()`.
+     */
+    createStyle(name, props = {}) {
+        const parsed = this.getParsedDoc();
+        const doc = parsed['VisioDocument'];
+        this.ensureStyleSheets(doc);
+        const styleSheets = doc['StyleSheets'];
+        const existing = this.normalizeArray(styleSheets['StyleSheet']);
+        const newId = this.nextId(existing);
+        existing.push(this.buildStyleSheetXml(newId, name, props));
+        styleSheets['StyleSheet'] = existing;
+        this.saveParsedDoc(parsed);
+        return { id: newId, name };
+    }
+    /**
+     * Return all stylesheets defined in the document (including the built-in ones).
+     */
+    getStyles() {
+        const parsed = this.getParsedDoc();
+        const doc = parsed['VisioDocument'];
+        const styleSheets = doc?.['StyleSheets'];
+        if (!styleSheets)
+            return [];
+        return this.normalizeArray(styleSheets['StyleSheet']).map((s) => ({
+            id: parseInt(s['@_ID'], 10),
+            name: s['@_Name'] ?? s['@_NameU'] ?? `Style ${s['@_ID']}`,
+        }));
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    getParsedDoc() {
+        const xml = this.pkg.getFileText('visio/document.xml');
+        return this.parser.parse(xml);
+    }
+    saveParsedDoc(parsed) {
+        this.pkg.updateFile('visio/document.xml', (0, XmlHelper_1.buildXml)(this.builder, parsed));
+    }
+    /** Ensure `<StyleSheets>` contains at least Style 0 and Style 1. */
+    ensureStyleSheets(doc) {
+        if (!doc['StyleSheets']) {
+            doc['StyleSheets'] = {};
+        }
+        const ss = doc['StyleSheets'];
+        const existing = this.normalizeArray(ss['StyleSheet']);
+        const hasStyle0 = existing.some((s) => s['@_ID'] === '0');
+        if (!hasStyle0) {
+            existing.unshift({
+                '@_ID': '0',
+                '@_Name': 'No Style',
+                '@_NameU': 'No Style',
+                '@_IsCustomName': '0',
+                '@_IsCustomNameU': '0',
+                Cell: [
+                    { '@_N': 'EnableLineProps', '@_V': '1' },
+                    { '@_N': 'EnableFillProps', '@_V': '1' },
+                    { '@_N': 'EnableTextProps', '@_V': '1' },
+                    { '@_N': 'HideForApply', '@_V': '0' },
+                ],
+            });
+        }
+        const hasStyle1 = existing.some((s) => s['@_ID'] === '1');
+        if (!hasStyle1) {
+            existing.push({
+                '@_ID': '1',
+                '@_Name': 'Normal',
+                '@_NameU': 'Normal',
+                '@_IsCustomName': '0',
+                '@_IsCustomNameU': '0',
+                '@_LineStyle': '0',
+                '@_FillStyle': '0',
+                '@_TextStyle': '0',
+            });
+        }
+        ss['StyleSheet'] = existing;
+    }
+    nextId(existing) {
+        if (existing.length === 0)
+            return 2;
+        const max = existing.reduce((m, s) => {
+            const id = parseInt(s['@_ID'], 10);
+            return isNaN(id) ? m : Math.max(m, id);
+        }, 0);
+        return Math.max(max + 1, 2); // user styles always start at ≥ 2
+    }
+    /** Normalise a fast-xml-parser value that may be undefined, a single object, or an array. */
+    normalizeArray(val) {
+        if (!val)
+            return [];
+        return Array.isArray(val) ? val : [val];
+    }
+    buildStyleSheetXml(id, name, props) {
+        const sheet = {
+            '@_ID': id.toString(),
+            '@_Name': name,
+            '@_NameU': name,
+            '@_IsCustomName': '1',
+            '@_IsCustomNameU': '1',
+            '@_LineStyle': (props.parentLineStyleId ?? 0).toString(),
+            '@_FillStyle': (props.parentFillStyleId ?? 0).toString(),
+            '@_TextStyle': (props.parentTextStyleId ?? 0).toString(),
+        };
+        const cells = [];
+        const sections = [];
+        // ── Fill ────────────────────────────────────────────────────────────
+        if (props.fillColor !== undefined) {
+            cells.push({ '@_N': 'FillForegnd', '@_V': props.fillColor, '@_F': (0, StyleHelpers_1.hexToRgb)(props.fillColor) });
+            cells.push({ '@_N': 'FillPattern', '@_V': '1' });
+        }
+        // ── Line ────────────────────────────────────────────────────────────
+        if (props.lineColor !== undefined) {
+            cells.push({ '@_N': 'LineColor', '@_V': props.lineColor, '@_F': (0, StyleHelpers_1.hexToRgb)(props.lineColor) });
+        }
+        if (props.lineWeight !== undefined) {
+            cells.push({ '@_N': 'LineWeight', '@_V': (props.lineWeight / 72).toString(), '@_U': 'PT' });
+        }
+        if (props.linePattern !== undefined) {
+            cells.push({ '@_N': 'LinePattern', '@_V': props.linePattern.toString() });
+        }
+        // ── TextBlock ───────────────────────────────────────────────────────
+        if (props.verticalAlign !== undefined) {
+            cells.push({ '@_N': 'VerticalAlign', '@_V': VERT_ALIGN[props.verticalAlign] });
+        }
+        if (props.textMarginTop !== undefined)
+            cells.push({ '@_N': 'TopMargin', '@_V': props.textMarginTop.toString(), '@_U': 'IN' });
+        if (props.textMarginBottom !== undefined)
+            cells.push({ '@_N': 'BottomMargin', '@_V': props.textMarginBottom.toString(), '@_U': 'IN' });
+        if (props.textMarginLeft !== undefined)
+            cells.push({ '@_N': 'LeftMargin', '@_V': props.textMarginLeft.toString(), '@_U': 'IN' });
+        if (props.textMarginRight !== undefined)
+            cells.push({ '@_N': 'RightMargin', '@_V': props.textMarginRight.toString(), '@_U': 'IN' });
+        // ── Character section (no @_T on rows — stylesheet convention) ─────
+        const charCells = [];
+        const colorVal = props.fontColor ?? '#000000';
+        if (props.fontColor !== undefined) {
+            charCells.push({ '@_N': 'Color', '@_V': colorVal, '@_F': (0, StyleHelpers_1.hexToRgb)(colorVal) });
+        }
+        let styleVal = 0;
+        if (props.bold)
+            styleVal |= 1;
+        if (props.italic)
+            styleVal |= 2;
+        if (props.underline)
+            styleVal |= 4;
+        if (props.strikethrough)
+            styleVal |= 8;
+        if (styleVal > 0 || props.bold !== undefined || props.italic !== undefined
+            || props.underline !== undefined || props.strikethrough !== undefined) {
+            charCells.push({ '@_N': 'Style', '@_V': styleVal.toString() });
+        }
+        if (props.fontSize !== undefined) {
+            charCells.push({ '@_N': 'Size', '@_V': (props.fontSize / 72).toString(), '@_U': 'PT' });
+        }
+        if (props.fontFamily !== undefined) {
+            charCells.push({ '@_N': 'Font', '@_V': '0', '@_F': `FONT("${props.fontFamily}")` });
+        }
+        if (charCells.length > 0) {
+            sections.push({
+                '@_N': 'Character',
+                Row: { '@_IX': '0', Cell: charCells },
+            });
+        }
+        // ── Paragraph section ───────────────────────────────────────────────
+        const paraCells = [];
+        if (props.horzAlign !== undefined)
+            paraCells.push({ '@_N': 'HorzAlign', '@_V': HORZ_ALIGN[props.horzAlign] });
+        if (props.spaceBefore !== undefined)
+            paraCells.push({ '@_N': 'SpBefore', '@_V': (props.spaceBefore / 72).toString(), '@_U': 'PT' });
+        if (props.spaceAfter !== undefined)
+            paraCells.push({ '@_N': 'SpAfter', '@_V': (props.spaceAfter / 72).toString(), '@_U': 'PT' });
+        if (props.lineSpacing !== undefined)
+            paraCells.push({ '@_N': 'SpLine', '@_V': (-props.lineSpacing).toString() });
+        if (paraCells.length > 0) {
+            sections.push({
+                '@_N': 'Paragraph',
+                Row: { '@_IX': '0', Cell: paraCells },
+            });
+        }
+        if (cells.length > 0)
+            sheet.Cell = cells;
+        if (sections.length > 0)
+            sheet.Section = sections;
+        return sheet;
+    }
+}
+exports.StyleSheetManager = StyleSheetManager;

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { ShapeModifier } from './ShapeModifier';
 export { VisioDocument } from './VisioDocument';
 export { Page } from './Page';
 export { Shape } from './Shape';
+export { Connector } from './Connector';
+export type { ConnectorData } from './Connector';
 export type { ShapeData, ShapeHyperlink } from './Shape';
 export { Layer } from './Layer';
 export { SchemaDiagram } from './SchemaDiagram';

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.VisioValidator = exports.SchemaDiagram = exports.Layer = exports.Shape = exports.Page = exports.VisioDocument = exports.ShapeModifier = exports.ShapeReader = exports.PageManager = exports.VisioPackage = void 0;
+exports.VisioValidator = exports.SchemaDiagram = exports.Layer = exports.Connector = 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,6 +29,8 @@ 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 Connector_1 = require("./Connector");
+Object.defineProperty(exports, "Connector", { enumerable: true, get: function () { return Connector_1.Connector; } });
 var Layer_1 = require("./Layer");
 Object.defineProperty(exports, "Layer", { enumerable: true, get: function () { return Layer_1.Layer; } });
 var SchemaDiagram_1 = require("./SchemaDiagram");

package/dist/shapes/ShapeBuilder.js

@@ -29,6 +29,20 @@ class ShapeBuilder {
         if (props.masterId) {
             shape['@_Master'] = props.masterId;
         }
+        // Apply document-level stylesheet references
+        if (props.styleId !== undefined) {
+            shape['@_LineStyle'] = props.styleId.toString();
+            shape['@_FillStyle'] = props.styleId.toString();
+            shape['@_TextStyle'] = props.styleId.toString();
+        }
+        else {
+            if (props.lineStyleId !== undefined)
+                shape['@_LineStyle'] = props.lineStyleId.toString();
+            if (props.fillStyleId !== undefined)
+                shape['@_FillStyle'] = props.fillStyleId.toString();
+            if (props.textStyleId !== undefined)
+                shape['@_TextStyle'] = props.textStyleId.toString();
+        }
         // Add Styles
         if (props.fillColor) {
             shape.Section.push((0, StyleHelpers_1.createFillSection)(props.fillColor));

package/dist/templates/MinimalVsdx.js

@@ -27,7 +27,15 @@ exports.DOCUMENT_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
         <ColorEntry IX="1" RGB="#FFFFFF"/>
     </Colors>
     <FaceNames/>
-    <StyleSheets/>
+    <StyleSheets>
+        <StyleSheet ID="0" Name="No Style" NameU="No Style" IsCustomName="0" IsCustomNameU="0">
+            <Cell N="EnableLineProps" V="1"/>
+            <Cell N="EnableFillProps" V="1"/>
+            <Cell N="EnableTextProps" V="1"/>
+            <Cell N="HideForApply" V="0"/>
+        </StyleSheet>
+        <StyleSheet ID="1" Name="Normal" NameU="Normal" IsCustomName="0" IsCustomNameU="0" LineStyle="0" FillStyle="0" TextStyle="0"/>
+    </StyleSheets>
 </VisioDocument>`;
 exports.DOCUMENT_RELS_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <Relationships xmlns="${VisioConstants_1.XML_NAMESPACES.RELATIONSHIPS}">

package/dist/types/VisioTypes.d.ts

@@ -146,6 +146,65 @@ export interface ConnectorStyle {
 }
 /** Non-rectangular geometry variants supported by ShapeBuilder. */
 export type ShapeGeometry = 'rectangle' | 'ellipse' | 'diamond' | 'rounded-rectangle' | 'triangle' | 'parallelogram';
+/** A reference to a document-level stylesheet, returned by `doc.createStyle()`. */
+export interface StyleRecord {
+    /** Zero-based integer ID used as `LineStyle` / `FillStyle` / `TextStyle` on shapes. */
+    id: number;
+    /** Human-readable name given to the style. */
+    name: string;
+}
+/**
+ * Visual properties for a document-level stylesheet created via `doc.createStyle()`.
+ * All fields are optional — omitted properties are inherited from the parent style (default: Style 0 "No Style").
+ */
+export interface StyleProps {
+    /** Parent style for line property inheritance. Defaults to 0 ("No Style"). */
+    parentLineStyleId?: number;
+    /** Parent style for fill property inheritance. Defaults to 0 ("No Style"). */
+    parentFillStyleId?: number;
+    /** Parent style for text property inheritance. Defaults to 0 ("No Style"). */
+    parentTextStyleId?: number;
+    /** Stroke colour as a CSS hex string (e.g. `'#cc0000'`). */
+    lineColor?: string;
+    /** Stroke weight in **points**. Stored internally as inches (pt / 72). */
+    lineWeight?: number;
+    /** Line pattern. 0 = none, 1 = solid, 2 = dash, 3 = dot, 4 = dash-dot. */
+    linePattern?: number;
+    /** Background fill colour as a CSS hex string. */
+    fillColor?: string;
+    /** Text colour as a CSS hex string. */
+    fontColor?: string;
+    /** Font size in **points**. */
+    fontSize?: number;
+    /** Bold text. */
+    bold?: boolean;
+    /** Italic text. */
+    italic?: boolean;
+    /** Underline text. */
+    underline?: boolean;
+    /** Strikethrough text. */
+    strikethrough?: boolean;
+    /** Font family name (e.g. `'Calibri'`). */
+    fontFamily?: string;
+    /** Horizontal text alignment within the paragraph. */
+    horzAlign?: 'left' | 'center' | 'right' | 'justify';
+    /** Space before each paragraph in **points**. */
+    spaceBefore?: number;
+    /** Space after each paragraph in **points**. */
+    spaceAfter?: number;
+    /** Line-height multiplier (1.0 = single, 1.5 = 1.5×, 2.0 = double). */
+    lineSpacing?: number;
+    /** Vertical text alignment within the shape. */
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    /** Top text margin in inches. */
+    textMarginTop?: number;
+    /** Bottom text margin in inches. */
+    textMarginBottom?: number;
+    /** Left text margin in inches. */
+    textMarginLeft?: number;
+    /** Right text margin in inches. */
+    textMarginRight?: number;
+}
 /** Whether a connection point accepts incoming glue, outgoing glue, or both. */
 export type ConnectionPointType = 'inward' | 'outward' | 'both';
 /**
@@ -240,4 +299,16 @@ export interface NewShapeProps {
      * or `StandardConnectionPoints.full` for eight points.
      */
     connectionPoints?: ConnectionPointDef[];
+    /**
+     * Apply a document-level stylesheet to this shape (sets `LineStyle`, `FillStyle`,
+     * and `TextStyle` all to the same ID). Create styles via `doc.createStyle()`.
+     * Takes precedence over `lineStyleId`, `fillStyleId`, and `textStyleId`.
+     */
+    styleId?: number;
+    /** Apply a stylesheet only for line properties (`LineStyle` attribute). */
+    lineStyleId?: number;
+    /** Apply a stylesheet only for fill properties (`FillStyle` attribute). */
+    fillStyleId?: number;
+    /** Apply a stylesheet only for text properties (`TextStyle` attribute). */
+    textStyleId?: number;
 }

package/dist/utils/StyleHelpers.d.ts

@@ -4,6 +4,7 @@ export interface VisioSection {
     Row?: any[];
     Cell?: any[];
 }
+export declare const hexToRgb: (hex: string) => string;
 export declare function createFillSection(hexColor: string): VisioSection;
 export declare const ArrowHeads: {
     None: string;

package/dist/utils/StyleHelpers.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArrowHeads = void 0;
+exports.ArrowHeads = exports.hexToRgb = void 0;
 exports.createFillSection = createFillSection;
 exports.horzAlignValue = horzAlignValue;
 exports.vertAlignValue = vertAlignValue;
@@ -15,10 +15,11 @@ const hexToRgb = (hex) => {
     const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
     return result ? `RGB(${parseInt(result[1], 16)},${parseInt(result[2], 16)},${parseInt(result[3], 16)})` : 'RGB(0,0,0)';
 };
+exports.hexToRgb = hexToRgb;
 function createFillSection(hexColor) {
     // Visio uses FillForegnd for the main background color.
     // Ideally we should sanitize hexColor to be #RRGGBB.
-    const rgbFormula = hexToRgb(hexColor);
+    const rgbFormula = (0, exports.hexToRgb)(hexColor);
     return {
         '@_N': 'Fill',
         Cell: [
@@ -68,7 +69,7 @@ function createCharacterSection(props) {
         styleVal |= 8;
     const colorVal = props.color || '#000000';
     const cells = [
-        { '@_N': 'Color', '@_V': colorVal, '@_F': hexToRgb(colorVal) },
+        { '@_N': 'Color', '@_V': colorVal, '@_F': (0, exports.hexToRgb)(colorVal) },
         { '@_N': 'Style', '@_V': styleVal.toString() },
     ];
     if (props.fontSize !== undefined) {
@@ -144,7 +145,7 @@ function createLineSection(props) {
     ];
     // Add RGB Formula for custom colors
     if (props.color) {
-        cells[0]['@_F'] = hexToRgb(props.color);
+        cells[0]['@_F'] = (0, exports.hexToRgb)(props.color);
     }
     return {
         '@_N': 'Line',

package/package.json

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