ts-visio 1.13.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).
@@ -30,6 +32,7 @@ Built using specific schema-level abstractions to handle the complex internal st
 - **Color Palette**: Register named colors in the document's color table via `doc.addColor()` and look them up by index or hex value with `doc.getColors()` / `doc.getColorIndex()`.
 - **Read Layers Back**: Enumerate existing layers from loaded files via `page.getLayers()`; delete a layer with `layer.delete()`, rename with `layer.rename()`, and read `layer.visible` / `layer.locked` state.
 - **Group Traversal**: Access nested child shapes via `shape.getChildren()`, check `shape.isGroup`, and read `shape.type`.
+- **Drawing Scale**: Set a real-world unit mapping on any page (`page.setDrawingScale()`), read it back (`page.getDrawingScale()`), or reset to 1:1 (`page.clearDrawingScale()`). Supports all common imperial and metric units.
 
 Feature gaps are being tracked in [FEATURES.md](./FEATURES.md).
 
@@ -201,26 +204,53 @@ Save the modified document back to disk.
 await doc.save('updated_diagram.vsdx');
 ```
 
-#### 10. Using Stencils (Masters)
-Load a template that already contains stencils (like "Network" or "Flowchart") and drop shapes by their Master ID.
+#### 10. Masters & Stencils
+
+**Create a master from scratch** — define a reusable shape with a built-in geometry, then stamp instances onto any page:
 
 ```typescript
-// 1. Load a template with stencils
-const doc = await VisioDocument.load('template_with_masters.vsdx');
+const doc = await VisioDocument.create();
 const page = doc.pages[0];
 
-// 2. Drop a shape using a Master ID
-// (You can find IDs in visio/masters/masters.xml of the template)
-await page.addShape({
-    text: "Router 1",
-    x: 2,
-    y: 2,
-    width: 1,
-    height: 1,
-    masterId: "5" // ID of the 'Router' master in the template
+// Define masters (geometries: 'rectangle' | 'ellipse' | 'diamond' |
+//   'rounded-rectangle' | 'triangle' | 'parallelogram')
+const boxMaster     = doc.createMaster('Box');
+const processMaster = doc.createMaster('Process', 'ellipse');
+const decisionMaster = doc.createMaster('Decision', 'diamond');
+
+// Stamp instances — geometry + styling come from the master definition
+await page.addShape({ text: 'Start',    x: 1, y: 1, width: 2, height: 1, masterId: processMaster.id });
+await page.addShape({ text: 'Step 1',   x: 4, y: 1, width: 2, height: 1, masterId: boxMaster.id });
+await page.addShape({ text: 'Branch?',  x: 7, y: 1, width: 2, height: 1, masterId: decisionMaster.id });
+```
+
+**Import masters from a `.vssx` stencil file** — bring in an entire stencil and use any of its masters:
+
+```typescript
+const doc = await VisioDocument.create();
+
+// Path to a .vssx file, or pass a Buffer / ArrayBuffer directly
+const stencilMasters = await doc.importMastersFromStencil('./Network_Shapes.vssx');
+const router = stencilMasters.find(m => m.name === 'Router')!;
+
+await doc.pages[0].addShape({
+    text: 'Router 1', x: 2, y: 2, width: 1, height: 1,
+    masterId: router.id,
 });
+```
 
-// The library automatically handles the relationships so the file stays valid.
+**List masters already in the document** — useful after loading a `.vsdx` that was created in Visio:
+
+```typescript
+const doc = await VisioDocument.load('existing_diagram.vsdx');
+const masters = doc.getMasters();
+// [{ id: '1', name: 'Box', nameU: 'Box', xmlPath: 'visio/masters/master1.xml' }, ...]
+
+// Find and reuse a master by name
+const routerMaster = masters.find(m => m.name === 'Router');
+if (routerMaster) {
+    await doc.pages[0].addShape({ text: 'Router 2', x: 5, y: 5, width: 1, height: 1, masterId: routerMaster.id });
+}
 ```
 
 #### 11. Multi-Page Documents
@@ -682,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.
 
@@ -789,6 +829,47 @@ for (const g of groups) {
 
 `getChildren()` returns `[]` for non-group shapes. Children are full `Shape` instances — all existing methods (`setStyle()`, `getProperties()`, `delete()`, etc.) work on them.
 
+#### 33. Drawing Scale
+Map page coordinates to real-world units. One `pageScale` `pageUnit` on the paper equals `drawingScale` `drawingUnit` in reality. Visio uses this to display rulers, grids, and shape dimensions in real-world terms.
+
+```typescript
+import type { LengthUnit, DrawingScaleInfo } from 'ts-visio';
+
+// 1 inch on paper = 10 feet in the real world (architectural)
+page.setDrawingScale(1, 'in', 10, 'ft');
+
+// 1:100 metric (1 cm on paper = 100 cm = 1 m in reality)
+page.setDrawingScale(1, 'cm', 100, 'cm');
+
+// Engineering: 1 inch = 20 feet
+page.setDrawingScale(1, 'in', 20, 'ft');
+
+// Read the current scale back
+const scale: DrawingScaleInfo | null = page.getDrawingScale();
+if (scale) {
+    console.log(`${scale.pageScale} ${scale.pageUnit} = ${scale.drawingScale} ${scale.drawingUnit}`);
+    // → "1 in = 10 ft"
+}
+
+// Returns null when no custom scale is set
+const freshPage = doc.pages[0];
+console.log(freshPage.getDrawingScale()); // null
+
+// Reset to 1:1 (no scale)
+page.clearDrawingScale();
+console.log(page.getDrawingScale()); // null
+
+// All methods are chainable
+page.setDrawingScale(1, 'mm', 1000, 'mm')
+    .setNamedSize('A1');  // combine with page size changes
+```
+
+Supported `LengthUnit` values:
+- Imperial: `'in'` (inches), `'ft'` (feet), `'yd'` (yards), `'mi'` (miles)
+- Metric: `'mm'`, `'cm'`, `'m'`, `'km'`
+
+The drawing scale does not affect the internal coordinate system — shape positions and sizes are still specified in page-inches. The scale is purely a display/annotation mapping applied by Visio's ruler and grid.
+
 ---
 
 ## Examples

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

@@ -1,4 +1,4 @@
-import { VisioPage, ConnectorStyle, PageOrientation, PageSizeName, ConnectionTarget } from './types/VisioTypes';
+import { VisioPage, ConnectorStyle, PageOrientation, PageSizeName, ConnectionTarget, DrawingScaleInfo, LengthUnit } from './types/VisioTypes';
 import { Connector } from './Connector';
 import { VisioPackage } from './VisioPackage';
 import { ShapeModifier } from './ShapeModifier';
@@ -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?: {
@@ -86,6 +159,30 @@ export declare class Page {
      * // [{ name: 'Background', index: 0, visible: true, locked: false }, ...]
      */
     getLayers(): Layer[];
+    /**
+     * Return the current drawing scale, or `null` if no custom scale is set (1:1).
+     *
+     * @example
+     * const scale = page.getDrawingScale();
+     * // { pageScale: 1, pageUnit: 'in', drawingScale: 10, drawingUnit: 'ft' }
+     */
+    getDrawingScale(): DrawingScaleInfo | null;
+    /**
+     * Set a custom drawing scale for the page.
+     * One `pageScale` `pageUnit` on paper equals `drawingScale` `drawingUnit` in the real world.
+     *
+     * @example
+     * // 1 inch on paper = 10 feet in the real world
+     * page.setDrawingScale(1, 'in', 10, 'ft');
+     *
+     * // 1:100 metric
+     * page.setDrawingScale(1, 'cm', 100, 'cm');
+     */
+    setDrawingScale(pageScale: number, pageUnit: LengthUnit, drawingScale: number, drawingUnit: LengthUnit): this;
+    /**
+     * Remove any custom drawing scale, reverting the page to a 1:1 ratio.
+     */
+    clearDrawingScale(): this;
     /** @internal Used by VisioDocument.renamePage() to keep in-memory state in sync. */
     _updateName(newName: string): void;
 }

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,15 +186,49 @@ 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) {
-        // 1. Upload Media
         const mediaPath = this.media.addMedia(name, data);
-        // 2. Link Page to Media (use resolved path so loaded files work correctly)
         const rId = await this.rels.addImageRelationship(this.pagePath, mediaPath);
-        // 3. Create Shape
         const newId = await this.modifier.addShape(this.id, {
             text: '',
             x, y, width, height,
@@ -197,72 +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) {
-        // A Pool is just a vertical list
-        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) {
-        // A Lane is just a container
-        return this.addContainer(props);
+        return SwimlanePattern_1.SwimlanePattern.addLane(this, props);
     }
     async addTable(x, y, title, columns) {
-        // ... (previous implementation)
-        // Dimensions
-        const width = 3;
-        const headerHeight = 0.5;
-        const lineItemHeight = 0.25;
-        const bodyHeight = Math.max(0.5, columns.length * lineItemHeight + 0.1); // Min height
-        const totalHeight = headerHeight + bodyHeight;
-        // 1. Create Main Group Shape (Transparent container)
-        // Group Logic:
-        // Positioned at (x, y) on the Page.
-        // Size encapsulates both header and body.
-        const groupShape = await this.addShape({
-            text: '', // No text on container
-            x: x,
-            y: y,
-            width: width,
-            height: totalHeight,
-            type: 'Group'
-        });
-        // 2. Header Shape (Inside Group)
-        // Coords relative to Group (Bottom-Left is 0,0)
-        // Header is at top. Center X is Width/2.
-        // Center Y = BodyHeight + (HeaderHeight/2)
-        const headerCenterY = bodyHeight + (headerHeight / 2);
-        await this.addShape({
-            text: title,
-            x: width / 2, // Relative PinX
-            y: headerCenterY, // Relative PinY
-            width: width,
-            height: headerHeight,
-            fillColor: '#DDDDDD',
-            bold: true
-        }, groupShape.id);
-        // 3. Body Shape (Inside Group)
-        // Bottom part. Center X is Width/2.
-        // Center Y = BodyHeight/2
-        const bodyCenterY = bodyHeight / 2;
-        const bodyText = columns.join('\n');
-        await this.addShape({
-            text: bodyText,
-            x: width / 2, // Relative PinX
-            y: bodyCenterY, // Relative PinY
-            width: width,
-            height: bodyHeight,
-            fillColor: '#FFFFFF',
-            fontColor: '#000000'
-        }, groupShape.id);
-        // Return the Group Shape
-        return groupShape;
+        return TablePattern_1.TablePattern.add(this, x, y, title, columns);
     }
     async addLayer(name, options) {
         const info = await this.modifier.addLayer(this.id, name, options);
@@ -280,6 +302,38 @@ class Page {
         const infos = this.modifier.getPageLayers(this.id);
         return infos.map(l => new Layer_1.Layer(l.name, l.index, this.id, this.pkg, this.modifier, l.visible, l.locked));
     }
+    /**
+     * Return the current drawing scale, or `null` if no custom scale is set (1:1).
+     *
+     * @example
+     * const scale = page.getDrawingScale();
+     * // { pageScale: 1, pageUnit: 'in', drawingScale: 10, drawingUnit: 'ft' }
+     */
+    getDrawingScale() {
+        return this.modifier.getDrawingScale(this.id);
+    }
+    /**
+     * Set a custom drawing scale for the page.
+     * One `pageScale` `pageUnit` on paper equals `drawingScale` `drawingUnit` in the real world.
+     *
+     * @example
+     * // 1 inch on paper = 10 feet in the real world
+     * page.setDrawingScale(1, 'in', 10, 'ft');
+     *
+     * // 1:100 metric
+     * page.setDrawingScale(1, 'cm', 100, 'cm');
+     */
+    setDrawingScale(pageScale, pageUnit, drawingScale, drawingUnit) {
+        this.modifier.setDrawingScale(this.id, pageScale, pageUnit, drawingScale, drawingUnit);
+        return this;
+    }
+    /**
+     * Remove any custom drawing scale, reverting the page to a 1:1 ratio.
+     */
+    clearDrawingScale() {
+        this.modifier.clearDrawingScale(this.id);
+        return this;
+    }
     /** @internal Used by VisioDocument.renamePage() to keep in-memory state in sync. */
     _updateName(newName) {
         this.internalPage.Name = newName;

package/dist/Shape.d.ts

@@ -1,6 +1,6 @@
-import { VisioShape, ConnectorStyle, ConnectionTarget, ConnectionPointDef } from './types/VisioTypes';
+import { VisioShape, ConnectorStyle, ConnectionTarget, ConnectionPointDef, ShapeStyle } from './types/VisioTypes';
 import { VisioPackage } from './VisioPackage';
-import { ShapeModifier, ShapeStyle } from './ShapeModifier';
+import { ShapeModifier } from './ShapeModifier';
 import { VisioPropType } from './types/VisioTypes';
 import { Layer } from './Layer';
 export interface ShapeData {
@@ -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;