ts-visio 1.15.0 → 1.16.0

package/README.md

@@ -1,5 +1,7 @@
 # ts-visio
 
+[![API Docs](https://img.shields.io/badge/API%20Docs-TypeDoc-blue?style=flat-square)](https://zimmermanw84.github.io/ts-visio/)
+
 > [!WARNING]
 > **Under Construction**
 > This library is currently being developed with heavy assistance from AI and is primarily an experimental project. Use with caution.
@@ -14,7 +16,7 @@ Built using specific schema-level abstractions to handle the complex internal st
 - **Strict Typing**: Interact with `VisioPage`, `VisioShape`, and `VisioConnect` objects.
 - **ShapeSheet Access**: Read `Cells`, `Rows`, and `Sections` directly.
 - **Connections**: Analyze connectivity between shapes.
-- **Modular Architecture**: Use specialized components for loading, page management, shape reading, and modification.
+- **Modular Architecture**: Clean layered architecture — `VisioDocument` → `Page` → `Shape` is the full public surface; XML and OPC internals stay encapsulated.
 - **Modify Content**: Update text content of shapes.
 - **Create Shapes**: Rectangles, ellipses, diamonds, rounded rectangles, triangles, parallelograms.
 - **Connect Shapes**: Dynamic connectors with arrow styles, line styling, and routing (straight / orthogonal / curved).
@@ -710,6 +712,16 @@ const styles = doc.getStyles();
 `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.
 
+The alignment and style types are exported for use in typed consumers:
+
+```typescript
+import type { HorzAlign, VertAlign, ShapeStyle } from 'ts-visio';
+
+const style: ShapeStyle = { horzAlign: 'center', verticalAlign: 'middle', bold: true };
+const align: HorzAlign  = 'justify';   // 'left' | 'center' | 'right' | 'justify'
+const valign: VertAlign = 'bottom';    // 'top' | 'middle' | 'bottom'
+```
+
 #### 30. Reading Connectors Back
 Enumerate connectors on a page — including those loaded from an existing `.vsdx` file — and inspect or delete them.
 

package/dist/Layer.d.ts

@@ -1,5 +1,19 @@
 import { VisioPackage } from './VisioPackage';
 import { ShapeModifier } from './ShapeModifier';
+/**
+ * A named display layer on a Visio page.
+ *
+ * Layers control the visibility and printability of groups of shapes.
+ * Obtain instances via `page.getLayers()` or `page.addLayer()`.
+ *
+ * @example
+ * ```typescript
+ * const annotations = await page.addLayer('Annotations');
+ * ann.setVisible(false);  // hide all shapes on this layer
+ * ```
+ *
+ * @category Layers
+ */
 export declare class Layer {
     name: string;
     index: number;

package/dist/Layer.js

@@ -2,6 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Layer = void 0;
 const ShapeModifier_1 = require("./ShapeModifier");
+/**
+ * A named display layer on a Visio page.
+ *
+ * Layers control the visibility and printability of groups of shapes.
+ * Obtain instances via `page.getLayers()` or `page.addLayer()`.
+ *
+ * @example
+ * ```typescript
+ * const annotations = await page.addLayer('Annotations');
+ * ann.setVisible(false);  // hide all shapes on this layer
+ * ```
+ *
+ * @category Layers
+ */
 class Layer {
     constructor(name, index, pageId, pkg, modifier, _visible = true, _locked = false) {
         this.name = name;

package/dist/Page.d.ts

@@ -7,6 +7,21 @@ import { Shape } from './Shape';
 import { MediaManager } from './core/MediaManager';
 import { RelsManager } from './core/RelsManager';
 import { Layer } from './Layer';
+/**
+ * Represents a single page (tab) inside a Visio document.
+ *
+ * Obtain a `Page` instance from {@link VisioDocument.pages},
+ * {@link VisioDocument.addPage}, or {@link VisioDocument.getPage}.
+ *
+ * @example
+ * ```typescript
+ * const doc  = await VisioDocument.create();
+ * const page = doc.pages[0];
+ * await page.addShape({ text: 'Hello', x: 1, y: 1, width: 2, height: 1 });
+ * ```
+ *
+ * @category Pages
+ */
 export declare class Page {
     private internalPage;
     private pkg;
@@ -39,6 +54,10 @@ export declare class Page {
      * Swaps width and height when the current orientation does not match the requested one.
      */
     setOrientation(orientation: PageOrientation): this;
+    /**
+     * Return all top-level shapes on the page.
+     * Group children are not included; use {@link findShapes} to search the entire shape tree.
+     */
     getShapes(): Shape[];
     /**
      * Find a shape by its ID anywhere on the page, including shapes nested inside groups.
@@ -50,6 +69,29 @@ export declare class Page {
      * the predicate. Equivalent to getAllShapes().filter(predicate).
      */
     findShapes(predicate: (shape: Shape) => boolean): Shape[];
+    /**
+     * Add a new shape to the page and return a {@link Shape} handle to it.
+     *
+     * @param props    Visual and text properties for the new shape.
+     *                 All geometry fields (`x`, `y`, `width`, `height`) are in inches.
+     * @param parentId Optional ID of an existing group shape to nest the new shape inside.
+     *
+     * @example
+     * ```typescript
+     * // Plain rectangle
+     * const box = await page.addShape({ text: 'Server', x: 2, y: 3, width: 2, height: 1 });
+     *
+     * // Ellipse with styling
+     * await page.addShape({
+     *     text: 'Start', x: 1, y: 1, width: 1.5, height: 1.5,
+     *     geometry: 'ellipse', fillColor: '#4472C4', fontColor: '#ffffff',
+     * });
+     *
+     * // Master instance (shape defined by a reusable master)
+     * const m = doc.createMaster('Router', 'ellipse');
+     * await page.addShape({ text: '', x: 4, y: 2, width: 1, height: 1, masterId: m.id });
+     * ```
+     */
     addShape(props: NewShapeProps, parentId?: string): Promise<Shape>;
     /**
      * Return all connector shapes on the page.
@@ -57,19 +99,50 @@ export declare class Page {
      * and a `delete()` method to remove the connector.
      */
     getConnectors(): Connector[];
+    /**
+     * Draw a connector (line/arrow) between two shapes on this page.
+     *
+     * @param fromShape   Source shape.
+     * @param toShape     Target shape.
+     * @param beginArrow  Arrow head at the source end (use {@link ArrowHeads} constants).
+     * @param endArrow    Arrow head at the target end (use {@link ArrowHeads} constants).
+     * @param style       Line color, weight, pattern, and routing style.
+     * @param fromPort    Named connection point on the source shape (e.g. `'Right'`).
+     * @param toPort      Named connection point on the target shape (e.g. `'Left'`).
+     *
+     * @example
+     * ```typescript
+     * import { ArrowHeads } from 'ts-visio';
+     * const a = await page.addShape({ text: 'A', x: 1, y: 1, width: 1, height: 1 });
+     * const b = await page.addShape({ text: 'B', x: 4, y: 1, width: 1, height: 1 });
+     * await page.connectShapes(a, b, ArrowHeads.None, ArrowHeads.OpenArrow,
+     *     { lineColor: '#333333', routing: 'orthogonal' });
+     * ```
+     */
     connectShapes(fromShape: Shape, toShape: Shape, beginArrow?: string, endArrow?: string, style?: ConnectorStyle, fromPort?: ConnectionTarget, toPort?: ConnectionTarget): Promise<void>;
+    /**
+     * Embed an image on the page and return the resulting Foreign shape.
+     *
+     * @param data   Raw image bytes (PNG, JPEG, GIF, BMP, or TIFF).
+     * @param name   Filename used to store the image inside the archive (e.g. `'logo.png'`).
+     * @param x      Horizontal pin position in inches.
+     * @param y      Vertical pin position in inches.
+     * @param width  Display width in inches.
+     * @param height Display height in inches.
+     *
+     * @example
+     * ```typescript
+     * import fs from 'fs';
+     * const imgBuffer = fs.readFileSync('./logo.png');
+     * await page.addImage(imgBuffer, 'logo.png', 1, 1, 2, 1);
+     * ```
+     */
     addImage(data: Buffer, name: string, x: number, y: number, width: number, height: number): Promise<Shape>;
     addContainer(props: NewShapeProps): Promise<Shape>;
     addList(props: NewShapeProps, direction?: 'vertical' | 'horizontal'): Promise<Shape>;
-    /**
-     * Creates a Swimlane Pool (which is technically a Vertical List of Containers).
-     * @param props Visual properties
-     */
+    /** Creates a Swimlane Pool (a vertical List of Containers). */
     addSwimlanePool(props: NewShapeProps): Promise<Shape>;
-    /**
-     * Creates a Swimlane Lane (which is technically a Container).
-     * @param props Visual properties
-     */
+    /** Creates a Swimlane Lane (a Container inside a pool). */
     addSwimlaneLane(props: NewShapeProps): Promise<Shape>;
     addTable(x: number, y: number, title: string, columns: string[]): Promise<Shape>;
     addLayer(name: string, options?: {

package/dist/Page.js

@@ -10,6 +10,23 @@ const MediaManager_1 = require("./core/MediaManager");
 const RelsManager_1 = require("./core/RelsManager");
 const StubHelpers_1 = require("./utils/StubHelpers");
 const Layer_1 = require("./Layer");
+const TablePattern_1 = require("./diagrams/TablePattern");
+const SwimlanePattern_1 = require("./diagrams/SwimlanePattern");
+/**
+ * Represents a single page (tab) inside a Visio document.
+ *
+ * Obtain a `Page` instance from {@link VisioDocument.pages},
+ * {@link VisioDocument.addPage}, or {@link VisioDocument.getPage}.
+ *
+ * @example
+ * ```typescript
+ * const doc  = await VisioDocument.create();
+ * const page = doc.pages[0];
+ * await page.addShape({ text: 'Hello', x: 1, y: 1, width: 2, height: 1 });
+ * ```
+ *
+ * @category Pages
+ */
 class Page {
     constructor(internalPage, pkg, media, rels, modifier) {
         this.internalPage = internalPage;
@@ -73,6 +90,10 @@ class Page {
         }
         return this;
     }
+    /**
+     * Return all top-level shapes on the page.
+     * Group children are not included; use {@link findShapes} to search the entire shape tree.
+     */
     getShapes() {
         const reader = new ShapeReader_1.ShapeReader(this.pkg);
         try {
@@ -106,6 +127,29 @@ class Page {
             .map(s => new Shape_1.Shape(s, this.id, this.pkg, this.modifier))
             .filter(predicate);
     }
+    /**
+     * Add a new shape to the page and return a {@link Shape} handle to it.
+     *
+     * @param props    Visual and text properties for the new shape.
+     *                 All geometry fields (`x`, `y`, `width`, `height`) are in inches.
+     * @param parentId Optional ID of an existing group shape to nest the new shape inside.
+     *
+     * @example
+     * ```typescript
+     * // Plain rectangle
+     * const box = await page.addShape({ text: 'Server', x: 2, y: 3, width: 2, height: 1 });
+     *
+     * // Ellipse with styling
+     * await page.addShape({
+     *     text: 'Start', x: 1, y: 1, width: 1.5, height: 1.5,
+     *     geometry: 'ellipse', fillColor: '#4472C4', fontColor: '#ffffff',
+     * });
+     *
+     * // Master instance (shape defined by a reusable master)
+     * const m = doc.createMaster('Router', 'ellipse');
+     * await page.addShape({ text: '', x: 4, y: 2, width: 1, height: 1, masterId: m.id });
+     * ```
+     */
     async addShape(props, parentId) {
         const newId = await this.modifier.addShape(this.id, props, parentId);
         // Return a fresh Shape object representing the new shape
@@ -142,9 +186,46 @@ class Page {
             return [];
         }
     }
+    /**
+     * Draw a connector (line/arrow) between two shapes on this page.
+     *
+     * @param fromShape   Source shape.
+     * @param toShape     Target shape.
+     * @param beginArrow  Arrow head at the source end (use {@link ArrowHeads} constants).
+     * @param endArrow    Arrow head at the target end (use {@link ArrowHeads} constants).
+     * @param style       Line color, weight, pattern, and routing style.
+     * @param fromPort    Named connection point on the source shape (e.g. `'Right'`).
+     * @param toPort      Named connection point on the target shape (e.g. `'Left'`).
+     *
+     * @example
+     * ```typescript
+     * import { ArrowHeads } from 'ts-visio';
+     * const a = await page.addShape({ text: 'A', x: 1, y: 1, width: 1, height: 1 });
+     * const b = await page.addShape({ text: 'B', x: 4, y: 1, width: 1, height: 1 });
+     * await page.connectShapes(a, b, ArrowHeads.None, ArrowHeads.OpenArrow,
+     *     { lineColor: '#333333', routing: 'orthogonal' });
+     * ```
+     */
     async connectShapes(fromShape, toShape, beginArrow, endArrow, style, fromPort, toPort) {
         await this.modifier.addConnector(this.id, fromShape.id, toShape.id, beginArrow, endArrow, style, fromPort, toPort);
     }
+    /**
+     * Embed an image on the page and return the resulting Foreign shape.
+     *
+     * @param data   Raw image bytes (PNG, JPEG, GIF, BMP, or TIFF).
+     * @param name   Filename used to store the image inside the archive (e.g. `'logo.png'`).
+     * @param x      Horizontal pin position in inches.
+     * @param y      Vertical pin position in inches.
+     * @param width  Display width in inches.
+     * @param height Display height in inches.
+     *
+     * @example
+     * ```typescript
+     * import fs from 'fs';
+     * const imgBuffer = fs.readFileSync('./logo.png');
+     * await page.addImage(imgBuffer, 'logo.png', 1, 1, 2, 1);
+     * ```
+     */
     async addImage(data, name, x, y, width, height) {
         const mediaPath = this.media.addMedia(name, data);
         const rId = await this.rels.addImageRelationship(this.pagePath, mediaPath);
@@ -194,51 +275,16 @@ class Page {
         });
         return new Shape_1.Shape(internalStub, this.id, this.pkg, this.modifier);
     }
-    /**
-     * Creates a Swimlane Pool (which is technically a Vertical List of Containers).
-     * @param props Visual properties
-     */
+    /** Creates a Swimlane Pool (a vertical List of Containers). */
     async addSwimlanePool(props) {
-        return this.addList(props, 'vertical');
+        return SwimlanePattern_1.SwimlanePattern.addPool(this, props);
     }
-    /**
-     * Creates a Swimlane Lane (which is technically a Container).
-     * @param props Visual properties
-     */
+    /** Creates a Swimlane Lane (a Container inside a pool). */
     async addSwimlaneLane(props) {
-        return this.addContainer(props);
+        return SwimlanePattern_1.SwimlanePattern.addLane(this, props);
     }
     async addTable(x, y, title, columns) {
-        const width = 3;
-        const headerHeight = 0.5;
-        const lineItemHeight = 0.25;
-        const bodyHeight = Math.max(0.5, columns.length * lineItemHeight + 0.1);
-        const totalHeight = headerHeight + bodyHeight;
-        // Group contains a header row and a body row; child coords are relative to the group origin.
-        const groupShape = await this.addShape({
-            text: '',
-            x, y, width, height: totalHeight,
-            type: 'Group'
-        });
-        const headerCenterY = bodyHeight + (headerHeight / 2);
-        await this.addShape({
-            text: title,
-            x: width / 2,
-            y: headerCenterY,
-            width, height: headerHeight,
-            fillColor: '#DDDDDD',
-            bold: true
-        }, groupShape.id);
-        const bodyCenterY = bodyHeight / 2;
-        await this.addShape({
-            text: columns.join('\n'),
-            x: width / 2,
-            y: bodyCenterY,
-            width, height: bodyHeight,
-            fillColor: '#FFFFFF',
-            fontColor: '#000000'
-        }, groupShape.id);
-        return groupShape;
+        return TablePattern_1.TablePattern.add(this, x, y, title, columns);
     }
     async addLayer(name, options) {
         const info = await this.modifier.addLayer(this.id, name, options);

package/dist/Shape.d.ts

@@ -15,6 +15,21 @@ export interface ShapeHyperlink {
     description?: string;
     newWindow: boolean;
 }
+/**
+ * A handle to a single shape on a Visio page.
+ *
+ * Obtain instances via {@link Page.addShape}, {@link Page.getShapes},
+ * {@link Page.getShapeById}, or {@link Page.findShapes}.
+ *
+ * @example
+ * ```typescript
+ * const shape = await page.addShape({ text: 'Box', x: 1, y: 1, width: 2, height: 1 });
+ * await shape.setStyle({ fillColor: '#4472C4', fontColor: '#ffffff', bold: true });
+ * console.log(shape.id, shape.x, shape.y);
+ * ```
+ *
+ * @category Shapes
+ */
 export declare class Shape {
     private internalShape;
     private pageId;

package/dist/Shape.js

@@ -8,6 +8,21 @@ const VisioConstants_1 = require("./core/VisioConstants");
 function fmtCoord(n) {
     return parseFloat(n.toFixed(10)).toString();
 }
+/**
+ * A handle to a single shape on a Visio page.
+ *
+ * Obtain instances via {@link Page.addShape}, {@link Page.getShapes},
+ * {@link Page.getShapeById}, or {@link Page.findShapes}.
+ *
+ * @example
+ * ```typescript
+ * const shape = await page.addShape({ text: 'Box', x: 1, y: 1, width: 2, height: 1 });
+ * await shape.setStyle({ fillColor: '#4472C4', fontColor: '#ffffff', bold: true });
+ * console.log(shape.id, shape.x, shape.y);
+ * ```
+ *
+ * @category Shapes
+ */
 class Shape {
     constructor(internalShape, pageId, pkg, modifier) {
         this.internalShape = internalShape;

package/dist/VisioDocument.d.ts

@@ -1,5 +1,23 @@
 import { Page } from './Page';
 import { DocumentMetadata, StyleProps, StyleRecord, ColorEntry, MasterRecord, ShapeGeometry } from './types/VisioTypes';
+/**
+ * The root object for reading and writing Visio (`.vsdx`) files.
+ *
+ * Create a blank document with {@link VisioDocument.create} or load an existing
+ * file with {@link VisioDocument.load}.  Call {@link VisioDocument.save} when done.
+ *
+ * @example
+ * ```typescript
+ * import { VisioDocument } from 'ts-visio';
+ *
+ * const doc  = await VisioDocument.create();
+ * const page = doc.pages[0];
+ * await page.addShape({ text: 'Hello, Visio!', x: 1, y: 1, width: 3, height: 1 });
+ * await doc.save('output.vsdx');
+ * ```
+ *
+ * @category Documents
+ */
 export declare class VisioDocument {
     private pkg;
     private pageManager;

package/dist/VisioDocument.js

@@ -42,6 +42,24 @@ const MediaManager_1 = require("./core/MediaManager");
 const MetadataManager_1 = require("./core/MetadataManager");
 const StyleSheetManager_1 = require("./core/StyleSheetManager");
 const ColorManager_1 = require("./core/ColorManager");
+/**
+ * The root object for reading and writing Visio (`.vsdx`) files.
+ *
+ * Create a blank document with {@link VisioDocument.create} or load an existing
+ * file with {@link VisioDocument.load}.  Call {@link VisioDocument.save} when done.
+ *
+ * @example
+ * ```typescript
+ * import { VisioDocument } from 'ts-visio';
+ *
+ * const doc  = await VisioDocument.create();
+ * const page = doc.pages[0];
+ * await page.addShape({ text: 'Hello, Visio!', x: 1, y: 1, width: 3, height: 1 });
+ * await doc.save('output.vsdx');
+ * ```
+ *
+ * @category Documents
+ */
 class VisioDocument {
     constructor(pkg) {
         this.pkg = pkg;

package/dist/core/PageManager.d.ts

@@ -17,10 +17,9 @@ export declare class PageManager {
     constructor(pkg: VisioPackage);
     load(force?: boolean): PageEntry[];
     createPage(name: string): Promise<string>;
-    /**
-     * Create a background page
-     */
+    /** Create a background page. */
     createBackgroundPage(name: string): Promise<string>;
+    private createPageInternal;
     /**
      * Delete a page and clean up all associated XML entries.
      * Removes the page file, its .rels file, the entry in pages.xml,

package/dist/core/PageManager.js

@@ -79,63 +79,13 @@ class PageManager {
         return this.pages;
     }
     async createPage(name) {
-        this.load();
-        let maxId = 0;
-        for (const p of this.pages) {
-            if (p.id > maxId)
-                maxId = p.id;
-        }
-        const newId = maxId + 1;
-        const fileName = `page${newId}.xml`;
-        const relativePath = `visio/pages/${fileName}`;
-        const pageContent = `<PageContents xmlns="${VisioConstants_1.XML_NAMESPACES.VISIO_MAIN}" xmlns:r="${VisioConstants_1.XML_NAMESPACES.RELATIONSHIPS_OFFICE}" xml:space="preserve">
-    <PageSheet LineStyle="0" FillStyle="0" TextStyle="0">
-        <Cell N="PageWidth" V="8.5"/>
-        <Cell N="PageHeight" V="11"/>
-        <Cell N="PageScale" V="1" Unit="MSG"/>
-        <Cell N="DrawingScale" V="1" Unit="MSG"/>
-        <Cell N="DrawingSizeType" V="0"/>
-        <Cell N="DrawingScaleType" V="0"/>
-        <Cell N="Inhibited" V="0"/>
-        <Cell N="UIVisibility" V="0"/>
-        <Cell N="PageDrawSizeType" V="0"/>
-    </PageSheet>
-    <Shapes/>
-    <Connects/>
-</PageContents>`;
-        this.pkg.updateFile(relativePath, pageContent);
-        const ctPath = '[Content_Types].xml';
-        const parsedCt = this.parser.parse(this.pkg.getFileText(ctPath));
-        if (!parsedCt.Types.Override)
-            parsedCt.Types.Override = [];
-        if (!Array.isArray(parsedCt.Types.Override))
-            parsedCt.Types.Override = [parsedCt.Types.Override];
-        parsedCt.Types.Override.push({
-            '@_PartName': `/${relativePath}`,
-            '@_ContentType': VisioConstants_1.CONTENT_TYPES.VISIO_PAGE
-        });
-        this.pkg.updateFile(ctPath, (0, XmlHelper_1.buildXml)(this.builder, parsedCt));
-        const rId = await this.relsManager.ensureRelationship('visio/pages/pages.xml', fileName, VisioConstants_1.RELATIONSHIP_TYPES.PAGE);
-        const pagesPath = 'visio/pages/pages.xml';
-        const parsedPages = this.parser.parse(this.pkg.getFileText(pagesPath));
-        if (!parsedPages.Pages.Page)
-            parsedPages.Pages.Page = [];
-        if (!Array.isArray(parsedPages.Pages.Page))
-            parsedPages.Pages.Page = [parsedPages.Pages.Page];
-        parsedPages.Pages.Page.push({
-            '@_ID': newId.toString(),
-            '@_Name': name,
-            '@_NameU': name,
-            'Rel': { '@_r:id': rId }
-        });
-        this.pkg.updateFile(pagesPath, (0, XmlHelper_1.buildXml)(this.builder, parsedPages));
-        this.load(true);
-        return newId.toString();
+        return this.createPageInternal(name, false);
     }
-    /**
-     * Create a background page
-     */
+    /** Create a background page. */
     async createBackgroundPage(name) {
+        return this.createPageInternal(name, true);
+    }
+    async createPageInternal(name, isBackground) {
         this.load();
         let maxId = 0;
         for (const p of this.pages) {
@@ -179,13 +129,15 @@ class PageManager {
             parsedPages.Pages.Page = [];
         if (!Array.isArray(parsedPages.Pages.Page))
             parsedPages.Pages.Page = [parsedPages.Pages.Page];
-        parsedPages.Pages.Page.push({
+        const entry = {
             '@_ID': newId.toString(),
             '@_Name': name,
             '@_NameU': name,
-            '@_Background': '1',
-            'Rel': { '@_r:id': rId }
-        });
+        };
+        if (isBackground)
+            entry['@_Background'] = '1';
+        entry['Rel'] = { '@_r:id': rId };
+        parsedPages.Pages.Page.push(entry);
         this.pkg.updateFile(pagesPath, (0, XmlHelper_1.buildXml)(this.builder, parsedPages));
         this.load(true);
         return newId.toString();

package/dist/diagrams/SchemaDiagram.d.ts

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

package/dist/diagrams/SchemaDiagram.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaDiagram = void 0;
+class SchemaDiagram {
+    constructor(page) {
+        this.page = page;
+    }
+    /**
+     * Adds a table entity to the diagram.
+     * @param tableName Name of the table
+     * @param columns List of column names (e.g., "id: int")
+     * @param x X coordinate
+     * @param y Y coordinate
+     */
+    async addTable(tableName, columns, x = 0, y = 0) {
+        return this.page.addTable(x, y, tableName, columns);
+    }
+    /**
+     * Connects two tables with a specific relationship type.
+     * @param fromTable Source table shape
+     * @param toTable Target table shape
+     * @param type Relationship type ('1:1' or '1:N')
+     */
+    async addRelation(fromTable, toTable, type) {
+        let beginArrow = '0'; // No arrow at start
+        let endArrow = '1'; // Default standard arrow
+        if (type === '1:1') {
+            endArrow = '1'; // Standard Arrow
+        }
+        else if (type === '1:N') {
+            endArrow = '29'; // Crow's Foot
+        }
+        await this.page.connectShapes(fromTable, toTable, beginArrow, endArrow);
+    }
+}
+exports.SchemaDiagram = SchemaDiagram;

package/dist/diagrams/SwimlanePattern.d.ts

@@ -0,0 +1,14 @@
+import type { Page } from '../Page';
+import type { Shape } from '../Shape';
+import type { NewShapeProps } from '../types/VisioTypes';
+/**
+ * Swimlane composition helpers.
+ *
+ * A swimlane diagram is modelled as a vertical List (the pool) containing
+ * one or more Containers (the lanes). Used by `page.addSwimlanePool()` and
+ * `page.addSwimlaneLane()`.
+ */
+export declare class SwimlanePattern {
+    static addPool(page: Page, props: NewShapeProps): Promise<Shape>;
+    static addLane(page: Page, props: NewShapeProps): Promise<Shape>;
+}

package/dist/diagrams/SwimlanePattern.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwimlanePattern = void 0;
+/**
+ * Swimlane composition helpers.
+ *
+ * A swimlane diagram is modelled as a vertical List (the pool) containing
+ * one or more Containers (the lanes). Used by `page.addSwimlanePool()` and
+ * `page.addSwimlaneLane()`.
+ */
+class SwimlanePattern {
+    static async addPool(page, props) {
+        return page.addList(props, 'vertical');
+    }
+    static async addLane(page, props) {
+        return page.addContainer(props);
+    }
+}
+exports.SwimlanePattern = SwimlanePattern;

package/dist/diagrams/TablePattern.d.ts

@@ -0,0 +1,11 @@
+import type { Page } from '../Page';
+import type { Shape } from '../Shape';
+/**
+ * High-level table composition: a group shape containing a shaded header row
+ * and a body row whose text lists the column names.
+ *
+ * Used by `page.addTable()` and `SchemaDiagram.addTable()`.
+ */
+export declare class TablePattern {
+    static add(page: Page, x: number, y: number, title: string, columns: string[]): Promise<Shape>;
+}

package/dist/diagrams/TablePattern.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TablePattern = void 0;
+/**
+ * High-level table composition: a group shape containing a shaded header row
+ * and a body row whose text lists the column names.
+ *
+ * Used by `page.addTable()` and `SchemaDiagram.addTable()`.
+ */
+class TablePattern {
+    static async add(page, x, y, title, columns) {
+        const width = 3;
+        const headerHeight = 0.5;
+        const lineItemHeight = 0.25;
+        const bodyHeight = Math.max(0.5, columns.length * lineItemHeight + 0.1);
+        const totalHeight = headerHeight + bodyHeight;
+        // Group contains a header row and a body row; child coords are relative to the group origin.
+        const groupShape = await page.addShape({
+            text: '',
+            x, y, width, height: totalHeight,
+            type: 'Group',
+        });
+        const headerCenterY = bodyHeight + (headerHeight / 2);
+        await page.addShape({
+            text: title,
+            x: width / 2,
+            y: headerCenterY,
+            width, height: headerHeight,
+            fillColor: '#DDDDDD',
+            bold: true,
+        }, groupShape.id);
+        const bodyCenterY = bodyHeight / 2;
+        await page.addShape({
+            text: columns.join('\n'),
+            x: width / 2,
+            y: bodyCenterY,
+            width, height: bodyHeight,
+            fillColor: '#FFFFFF',
+            fontColor: '#000000',
+        }, groupShape.id);
+        return groupShape;
+    }
+}
+exports.TablePattern = TablePattern;

package/dist/index.d.ts

@@ -5,7 +5,9 @@ export { Connector } from './Connector';
 export type { ConnectorData } from './Connector';
 export type { ShapeData, ShapeHyperlink } from './Shape';
 export { Layer } from './Layer';
-export { SchemaDiagram } from './SchemaDiagram';
+export { SchemaDiagram } from './diagrams/SchemaDiagram';
+export { TablePattern } from './diagrams/TablePattern';
+export { SwimlanePattern } from './diagrams/SwimlanePattern';
 export { VisioValidator } from './core/VisioValidator';
 export * from './types/VisioTypes';
 export { ArrowHeads, hexToRgb } from './utils/StyleHelpers';

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.hexToRgb = exports.ArrowHeads = exports.VisioValidator = exports.SchemaDiagram = exports.Layer = exports.Connector = exports.Shape = exports.Page = exports.VisioDocument = void 0;
+exports.hexToRgb = exports.ArrowHeads = exports.VisioValidator = exports.SwimlanePattern = exports.TablePattern = exports.SchemaDiagram = exports.Layer = exports.Connector = exports.Shape = exports.Page = exports.VisioDocument = void 0;
 var VisioDocument_1 = require("./VisioDocument");
 Object.defineProperty(exports, "VisioDocument", { enumerable: true, get: function () { return VisioDocument_1.VisioDocument; } });
 var Page_1 = require("./Page");
@@ -25,8 +25,12 @@ 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");
+var SchemaDiagram_1 = require("./diagrams/SchemaDiagram");
 Object.defineProperty(exports, "SchemaDiagram", { enumerable: true, get: function () { return SchemaDiagram_1.SchemaDiagram; } });
+var TablePattern_1 = require("./diagrams/TablePattern");
+Object.defineProperty(exports, "TablePattern", { enumerable: true, get: function () { return TablePattern_1.TablePattern; } });
+var SwimlanePattern_1 = require("./diagrams/SwimlanePattern");
+Object.defineProperty(exports, "SwimlanePattern", { enumerable: true, get: function () { return SwimlanePattern_1.SwimlanePattern; } });
 var VisioValidator_1 = require("./core/VisioValidator");
 Object.defineProperty(exports, "VisioValidator", { enumerable: true, get: function () { return VisioValidator_1.VisioValidator; } });
 __exportStar(require("./types/VisioTypes"), exports);

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "ts-visio",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "test": "vitest",
     "build": "tsc",
+    "docs:generate": "typedoc",
     "prepublishOnly": "npm run build"
   },
   "files": [
@@ -26,6 +27,7 @@
   "devDependencies": {
     "@types/node": "^25.0.9",
     "tsx": "^4.21.0",
+    "typedoc": "^0.28.17",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
   }