ts-visio 1.1.0 → 1.2.0

package/README.md

@@ -12,7 +12,7 @@ Built using specific schema-level abstractions to handle the complex internal st
 
 ## Features
 
-- **Read VSDX**: Open and parse `.vsdx` files (zippped XML).
+- **Read VSDX**: Open and parse `.vsdx` files (zipped XML).
 - **Strict Typing**: Interact with `VisioPage`, `VisioShape`, and `VisioConnect` objects.
 - **ShapeSheet Access**: Read `Cells`, `Rows`, and `Sections` directly.
 - **Connections**: Analyze connectivity between shapes.
@@ -20,6 +20,11 @@ Built using specific schema-level abstractions to handle the complex internal st
 - **Modify Content**: Update text content of shapes.
 - **Create Shapes**: Add new rectangular shapes with text to pages.
 - **Connect Shapes**: Create dynamic connectors between shapes.
+- **Text Styling**: Font size, font family, bold, color, horizontal/vertical alignment.
+- **Shape Transformations**: Rotate, flip (X/Y), and resize shapes via a fluent API.
+- **Deletion**: Remove shapes and pages cleanly (including orphaned connectors and relationships).
+- **Lookup API**: Find shapes by ID, predicate, or look up pages by name.
+- **Read-Back API**: Read custom properties, hyperlinks, and layer assignments from existing shapes.
 
 ## Installation
 
@@ -63,9 +68,13 @@ const shape = await page.addShape({
     y: 1,
     width: 3,
     height: 1,
-    fillColor: "#ff0000", // Option hexadecimal fill color
+    fillColor: "#ff0000",   // Hex fill color
     fontColor: "#ffffff",
-    bold: true
+    bold: true,
+    fontSize: 14,           // Points
+    fontFamily: "Segoe UI",
+    horzAlign: "center",    // "left" | "center" | "right" | "justify"
+    verticalAlign: "middle" // "top" | "middle" | "bottom"
 });
 
 // Modify text
@@ -345,6 +354,70 @@ await lane1.addMember(startShape);
 await lane2.addMember(serverShape);
 ```
 
+#### 19. Shape Transformations
+Rotate, flip, and resize shapes using a fluent API.
+
+```typescript
+const shape = await page.addShape({ text: "Widget", x: 3, y: 3, width: 2, height: 1 });
+
+// Rotate 45 degrees (clockwise)
+await shape.rotate(45);
+console.log(shape.angle); // 45
+
+// Mirror horizontally or vertically
+await shape.flipX();
+await shape.flipY(false); // un-flip
+
+// Resize (keeps the pin point centred)
+await shape.resize(4, 2);
+console.log(shape.width, shape.height); // 4, 2
+
+// Chainable
+await shape.rotate(90).then(s => s.resize(3, 1));
+```
+
+#### 20. Deleting Shapes and Pages
+Remove shapes or entire pages. Orphaned connectors and relationships are cleaned up automatically.
+
+```typescript
+// Delete a shape
+await shape.delete();
+
+// Delete a page (removes page file, rels, and all back-page references)
+await doc.deletePage(page2);
+```
+
+#### 21. Lookup API
+Find shapes and pages without iterating manually.
+
+```typescript
+// Find a shape by its numeric ID (searches nested groups too)
+const target = await page.getShapeById("42");
+
+// Find all shapes matching a predicate
+const servers = await page.findShapes(s => s.text.startsWith("Server"));
+
+// Look up a page by name (exact, case-sensitive)
+const detailPage = doc.getPage("Architecture Diagram");
+```
+
+#### 22. Reading Shape Data Back
+Retrieve custom properties, hyperlinks, and layer assignments that were previously written.
+
+```typescript
+// Custom properties (shape data)
+const props = shape.getProperties();
+console.log(props["IP"].value);    // "192.168.1.10"
+console.log(props["Port"].type);   // VisioPropType.Number
+
+// Hyperlinks
+const links = shape.getHyperlinks();
+// [ { address: "https://example.com", description: "Docs", newWindow: false } ]
+
+// Layer indices
+const indices = shape.getLayerIndices(); // e.g. [0, 2]
+```
+
 ## Examples
 
 Check out the [examples](./examples) directory for complete scripts.

package/dist/Page.d.ts

@@ -18,6 +18,16 @@ export declare class Page {
     get id(): string;
     get name(): string;
     getShapes(): Shape[];
+    /**
+     * Find a shape by its ID anywhere on the page, including shapes nested inside groups.
+     * Returns undefined if no shape with that ID exists.
+     */
+    getShapeById(id: string): Shape | undefined;
+    /**
+     * Return all shapes on the page (including nested group children) that satisfy
+     * the predicate. Equivalent to getAllShapes().filter(predicate).
+     */
+    findShapes(predicate: (shape: Shape) => boolean): Shape[];
     addShape(props: NewShapeProps, parentId?: string): Promise<Shape>;
     connectShapes(fromShape: Shape, toShape: Shape, beginArrow?: string, endArrow?: string): Promise<void>;
     addImage(data: Buffer, name: string, x: number, y: number, width: number, height: number): Promise<Shape>;

package/dist/Page.js

@@ -33,11 +33,32 @@ class Page {
             return internalShapes.map(s => new Shape_1.Shape(s, this.id, this.pkg, this.modifier));
         }
         catch (e) {
-            // If page file doesn't exist or is empty, return empty array
             console.warn(`Could not read shapes for page ${this.id}:`, e);
             return [];
         }
     }
+    /**
+     * Find a shape by its ID anywhere on the page, including shapes nested inside groups.
+     * Returns undefined if no shape with that ID exists.
+     */
+    getShapeById(id) {
+        const reader = new ShapeReader_1.ShapeReader(this.pkg);
+        const internal = reader.readShapeById(this.pagePath, id);
+        if (!internal)
+            return undefined;
+        return new Shape_1.Shape(internal, this.id, this.pkg, this.modifier);
+    }
+    /**
+     * Return all shapes on the page (including nested group children) that satisfy
+     * the predicate. Equivalent to getAllShapes().filter(predicate).
+     */
+    findShapes(predicate) {
+        const reader = new ShapeReader_1.ShapeReader(this.pkg);
+        const all = reader.readAllShapes(this.pagePath);
+        return all
+            .map(s => new Shape_1.Shape(s, this.id, this.pkg, this.modifier))
+            .filter(predicate);
+    }
     async addShape(props, parentId) {
         const newId = await this.modifier.addShape(this.id, props, parentId);
         // Return a fresh Shape object representing the new shape

package/dist/Shape.d.ts

@@ -9,6 +9,12 @@ export interface ShapeData {
     hidden?: boolean;
     type?: VisioPropType;
 }
+export interface ShapeHyperlink {
+    address?: string;
+    subAddress?: string;
+    description?: string;
+    newWindow: boolean;
+}
 export declare class Shape {
     private internalShape;
     private pageId;
@@ -23,6 +29,7 @@ export declare class Shape {
     get height(): number;
     get x(): number;
     get y(): number;
+    delete(): Promise<void>;
     connectTo(targetShape: Shape, beginArrow?: string, endArrow?: string): Promise<this>;
     setStyle(style: ShapeStyle): Promise<this>;
     placeRightOf(targetShape: Shape, options?: {
@@ -37,6 +44,41 @@ export declare class Shape {
     }): this;
     setPropertyValue(name: string, value: string | number | boolean | Date): this;
     addData(key: string, data: ShapeData): this;
+    /**
+     * Read back all custom property (shape data) entries written to this shape.
+     * Returns a map of property key → ShapeData. Values are coerced to the
+     * declared Visio type (Number, Boolean, Date, or String).
+     */
+    getProperties(): Record<string, ShapeData>;
+    /**
+     * Read back all hyperlinks attached to this shape.
+     */
+    getHyperlinks(): ShapeHyperlink[];
+    /**
+     * Read back the layer indices this shape is assigned to.
+     * Returns an empty array if the shape has no layer assignment.
+     */
+    getLayerIndices(): number[];
+    /** Current rotation angle in degrees (0 if no Angle cell is set). */
+    get angle(): number;
+    /**
+     * Rotate the shape to an absolute angle (degrees, clockwise).
+     * Replaces any existing rotation.
+     */
+    rotate(degrees: number): Promise<this>;
+    /**
+     * Resize the shape to the given width and height (in inches).
+     * Updates LocPinX/LocPinY to keep the centre-pin at width/2, height/2.
+     */
+    resize(width: number, height: number): Promise<this>;
+    /**
+     * Flip the shape horizontally. Pass `false` to un-flip.
+     */
+    flipX(enabled?: boolean): Promise<this>;
+    /**
+     * Flip the shape vertically. Pass `false` to un-flip.
+     */
+    flipY(enabled?: boolean): Promise<this>;
     addMember(memberShape: Shape): Promise<this>;
     addListItem(item: Shape): Promise<this>;
     resizeToFit(padding?: number): Promise<this>;
@@ -67,4 +109,5 @@ export declare class Shape {
      */
     addToLayer(layer: Layer | number): Promise<this>;
     private setLocalCoord;
+    private setLocalRawCell;
 }

package/dist/Shape.js

@@ -39,6 +39,9 @@ class Shape {
     get y() {
         return this.internalShape.Cells['PinY'] ? Number(this.internalShape.Cells['PinY'].V) : 0;
     }
+    async delete() {
+        await this.modifier.deleteShape(this.pageId, this.id);
+    }
     async connectTo(targetShape, beginArrow, endArrow) {
         await this.modifier.addConnector(this.pageId, this.id, targetShape.id, beginArrow, endArrow);
         return this;
@@ -96,6 +99,72 @@ class Shape {
         this.setPropertyValue(key, data.value);
         return this;
     }
+    /**
+     * Read back all custom property (shape data) entries written to this shape.
+     * Returns a map of property key → ShapeData. Values are coerced to the
+     * declared Visio type (Number, Boolean, Date, or String).
+     */
+    getProperties() {
+        return this.modifier.getShapeProperties(this.pageId, this.id);
+    }
+    /**
+     * Read back all hyperlinks attached to this shape.
+     */
+    getHyperlinks() {
+        return this.modifier.getShapeHyperlinks(this.pageId, this.id);
+    }
+    /**
+     * Read back the layer indices this shape is assigned to.
+     * Returns an empty array if the shape has no layer assignment.
+     */
+    getLayerIndices() {
+        return this.modifier.getShapeLayerIndices(this.pageId, this.id);
+    }
+    /** Current rotation angle in degrees (0 if no Angle cell is set). */
+    get angle() {
+        const cell = this.internalShape.Cells['Angle'];
+        return cell ? (parseFloat(cell.V) * 180) / Math.PI : 0;
+    }
+    /**
+     * Rotate the shape to an absolute angle (degrees, clockwise).
+     * Replaces any existing rotation.
+     */
+    async rotate(degrees) {
+        await this.modifier.rotateShape(this.pageId, this.id, degrees);
+        const radians = (degrees * Math.PI) / 180;
+        this.setLocalCoord('Angle', radians);
+        return this;
+    }
+    /**
+     * Resize the shape to the given width and height (in inches).
+     * Updates LocPinX/LocPinY to keep the centre-pin at width/2, height/2.
+     */
+    async resize(width, height) {
+        if (width <= 0 || height <= 0)
+            throw new Error('Shape dimensions must be positive');
+        await this.modifier.resizeShape(this.pageId, this.id, width, height);
+        this.setLocalCoord('Width', width);
+        this.setLocalCoord('Height', height);
+        this.setLocalCoord('LocPinX', width / 2);
+        this.setLocalCoord('LocPinY', height / 2);
+        return this;
+    }
+    /**
+     * Flip the shape horizontally. Pass `false` to un-flip.
+     */
+    async flipX(enabled = true) {
+        this.modifier.setShapeFlip(this.pageId, this.id, 'x', enabled);
+        this.setLocalRawCell('FlipX', enabled ? '1' : '0');
+        return this;
+    }
+    /**
+     * Flip the shape vertically. Pass `false` to un-flip.
+     */
+    async flipY(enabled = true) {
+        this.modifier.setShapeFlip(this.pageId, this.id, 'y', enabled);
+        this.setLocalRawCell('FlipY', enabled ? '1' : '0');
+        return this;
+    }
     async addMember(memberShape) {
         await this.modifier.addRelationship(this.pageId, this.id, memberShape.id, 'Container');
         return this;
@@ -165,5 +234,11 @@ class Shape {
         else
             this.internalShape.Cells[name] = { V: v, N: name };
     }
+    setLocalRawCell(name, value) {
+        if (this.internalShape.Cells[name])
+            this.internalShape.Cells[name].V = value;
+        else
+            this.internalShape.Cells[name] = { V: value, N: name };
+    }
 }
 exports.Shape = Shape;

package/dist/ShapeModifier.d.ts

@@ -1,5 +1,7 @@
 import { VisioPackage } from './VisioPackage';
+import { HorzAlign, VertAlign } from './utils/StyleHelpers';
 import { NewShapeProps } from './types/VisioTypes';
+import type { ShapeData, ShapeHyperlink } from './Shape';
 export declare class ShapeModifier {
     private pkg;
     addContainer(pageId: string, props: NewShapeProps): Promise<string>;
@@ -31,9 +33,28 @@ export declare class ShapeModifier {
     flush(): void;
     addConnector(pageId: string, fromShapeId: string, toShapeId: string, beginArrow?: string, endArrow?: string): Promise<string>;
     addShape(pageId: string, props: NewShapeProps, parentId?: string): Promise<string>;
+    deleteShape(pageId: string, shapeId: string): Promise<void>;
+    private removeShapeFromTree;
     updateShapeText(pageId: string, shapeId: string, newText: string): Promise<void>;
     updateShapeStyle(pageId: string, shapeId: string, style: ShapeStyle): Promise<void>;
     updateShapeDimensions(pageId: string, shapeId: string, w: number, h: number): Promise<void>;
+    /**
+     * Set the rotation angle of a shape. Degrees are converted to radians
+     * for storage in the Angle cell (Visio's native unit).
+     */
+    rotateShape(pageId: string, shapeId: string, degrees: number): Promise<void>;
+    /**
+     * Set the flip state for a shape along the X or Y axis.
+     * FlipX mirrors left-to-right; FlipY mirrors top-to-bottom.
+     */
+    setShapeFlip(pageId: string, shapeId: string, axis: 'x' | 'y', enabled: boolean): void;
+    /**
+     * Resize a shape, keeping it centred on its current PinX/PinY.
+     * Updates Width, Height, LocPinX, LocPinY, and the cached @_V on any
+     * Geometry cells whose @_F formula references Width or Height, so that
+     * non-Visio renderers see consistent values.
+     */
+    resizeShape(pageId: string, shapeId: string, width: number, height: number): Promise<void>;
     updateShapePosition(pageId: string, shapeId: string, x: number, y: number): Promise<void>;
     addPropertyDefinition(pageId: string, shapeId: string, name: string, type: number, options?: {
         label?: string;
@@ -67,9 +88,32 @@ export declare class ShapeModifier {
     }>;
     assignLayer(pageId: string, shapeId: string, layerIndex: number): Promise<void>;
     updateLayerProperty(pageId: string, layerIndex: number, propName: string, value: string): Promise<void>;
+    /**
+     * Read back all custom property (shape data) entries for a shape.
+     * Returns a map of property key → ShapeData, with values coerced to
+     * the declared type (Number, Boolean, Date, or String).
+     */
+    getShapeProperties(pageId: string, shapeId: string): Record<string, ShapeData>;
+    /**
+     * Read back all hyperlinks attached to a shape.
+     */
+    getShapeHyperlinks(pageId: string, shapeId: string): ShapeHyperlink[];
+    /**
+     * Read back the layer indices a shape is assigned to.
+     * Returns an empty array if the shape has no layer assignment.
+     */
+    getShapeLayerIndices(pageId: string, shapeId: string): number[];
 }
 export interface ShapeStyle {
     fillColor?: string;
     fontColor?: string;
     bold?: boolean;
+    /** Font size in points (e.g. 14 for 14pt). */
+    fontSize?: number;
+    /** Font family name (e.g. "Arial"). */
+    fontFamily?: string;
+    /** Horizontal text alignment. */
+    horzAlign?: HorzAlign;
+    /** Vertical text alignment. */
+    verticalAlign?: VertAlign;
 }

package/dist/ShapeModifier.js

@@ -4,6 +4,7 @@ exports.ShapeModifier = void 0;
 const RelsManager_1 = require("./core/RelsManager");
 const StyleHelpers_1 = require("./utils/StyleHelpers");
 const VisioConstants_1 = require("./core/VisioConstants");
+const VisioTypes_1 = require("./types/VisioTypes");
 const ForeignShapeBuilder_1 = require("./shapes/ForeignShapeBuilder");
 const ShapeBuilder_1 = require("./shapes/ShapeBuilder");
 const ConnectorBuilder_1 = require("./shapes/ConnectorBuilder");
@@ -271,6 +272,52 @@ class ShapeModifier {
         this.saveParsed(pageId, parsed);
         return newId;
     }
+    async deleteShape(pageId, shapeId) {
+        const parsed = this.getParsed(pageId);
+        // 1. Remove shape from the shape tree (handles top-level and nested groups)
+        const removed = this.removeShapeFromTree(parsed.PageContents.Shapes, shapeId);
+        if (!removed) {
+            throw new Error(`Shape ${shapeId} not found on page ${pageId}`);
+        }
+        // 2. Remove any Connect elements referencing this shape
+        if (parsed.PageContents.Connects?.Connect) {
+            let connects = parsed.PageContents.Connects.Connect;
+            if (!Array.isArray(connects))
+                connects = [connects];
+            const filtered = connects.filter((c) => c['@_FromSheet'] !== shapeId && c['@_ToSheet'] !== shapeId);
+            parsed.PageContents.Connects.Connect = filtered;
+        }
+        // 3. Remove any Relationship elements referencing this shape (container membership, etc.)
+        if (parsed.PageContents.Relationships?.Relationship) {
+            let rels = parsed.PageContents.Relationships.Relationship;
+            if (!Array.isArray(rels))
+                rels = [rels];
+            parsed.PageContents.Relationships.Relationship = rels.filter((r) => r['@_ShapeID'] !== shapeId && r['@_RelatedShapeID'] !== shapeId);
+        }
+        // 4. Invalidate the shape cache so the map is rebuilt on next access
+        this.shapeCache.delete(parsed);
+        this.saveParsed(pageId, parsed);
+    }
+    removeShapeFromTree(shapesContainer, shapeId) {
+        if (!shapesContainer?.Shape)
+            return false;
+        let shapes = shapesContainer.Shape;
+        if (!Array.isArray(shapes))
+            shapes = [shapes];
+        const idx = shapes.findIndex((s) => s['@_ID'] === shapeId);
+        if (idx !== -1) {
+            shapes.splice(idx, 1);
+            shapesContainer.Shape = shapes;
+            return true;
+        }
+        // Recurse into nested group children
+        for (const shape of shapes) {
+            if (shape.Shapes && this.removeShapeFromTree(shape.Shapes, shapeId)) {
+                return true;
+            }
+        }
+        return false;
+    }
     async updateShapeText(pageId, shapeId, newText) {
         const parsed = this.getParsed(pageId);
         const shape = this.getShapeMap(parsed).get(shapeId);
@@ -302,14 +349,34 @@ class ShapeModifier {
             shape.Section.push((0, StyleHelpers_1.createFillSection)(style.fillColor));
         }
         // Update/Add Character (Font/Text Style)
-        if (style.fontColor || style.bold !== undefined) {
-            // Remove existing Character section if any
+        if (style.fontColor || style.bold !== undefined || style.fontSize !== undefined || style.fontFamily !== undefined) {
             shape.Section = shape.Section.filter((s) => s['@_N'] !== 'Character');
             shape.Section.push((0, StyleHelpers_1.createCharacterSection)({
                 bold: style.bold,
-                color: style.fontColor
+                color: style.fontColor,
+                fontSize: style.fontSize,
+                fontFamily: style.fontFamily,
             }));
         }
+        // Update/Add Paragraph (Horizontal Alignment)
+        if (style.horzAlign !== undefined) {
+            shape.Section = shape.Section.filter((s) => s['@_N'] !== 'Paragraph');
+            shape.Section.push((0, StyleHelpers_1.createParagraphSection)(style.horzAlign));
+        }
+        // Update/Add VerticalAlign (top-level shape Cell)
+        if (style.verticalAlign !== undefined) {
+            if (!shape.Cell)
+                shape.Cell = [];
+            if (!Array.isArray(shape.Cell))
+                shape.Cell = [shape.Cell];
+            const existingCell = shape.Cell.find((c) => c['@_N'] === 'VerticalAlign');
+            if (existingCell) {
+                existingCell['@_V'] = (0, StyleHelpers_1.vertAlignValue)(style.verticalAlign);
+            }
+            else {
+                shape.Cell.push({ '@_N': 'VerticalAlign', '@_V': (0, StyleHelpers_1.vertAlignValue)(style.verticalAlign) });
+            }
+        }
         this.saveParsed(pageId, parsed);
     }
     async updateShapeDimensions(pageId, shapeId, w, h) {
@@ -333,6 +400,97 @@ class ShapeModifier {
         updateCell('Height', h.toString());
         this.saveParsed(pageId, parsed);
     }
+    /**
+     * Set the rotation angle of a shape. Degrees are converted to radians
+     * for storage in the Angle cell (Visio's native unit).
+     */
+    async rotateShape(pageId, shapeId, degrees) {
+        const parsed = this.getParsed(pageId);
+        const shape = this.getShapeMap(parsed).get(shapeId);
+        if (!shape)
+            throw new Error(`Shape ${shapeId} not found on page ${pageId}`);
+        if (!shape.Cell)
+            shape.Cell = [];
+        if (!Array.isArray(shape.Cell))
+            shape.Cell = [shape.Cell];
+        const radians = (degrees * Math.PI) / 180;
+        const existing = shape.Cell.find((c) => c['@_N'] === 'Angle');
+        if (existing)
+            existing['@_V'] = radians.toString();
+        else
+            shape.Cell.push({ '@_N': 'Angle', '@_V': radians.toString() });
+        this.saveParsed(pageId, parsed);
+    }
+    /**
+     * Set the flip state for a shape along the X or Y axis.
+     * FlipX mirrors left-to-right; FlipY mirrors top-to-bottom.
+     */
+    setShapeFlip(pageId, shapeId, axis, enabled) {
+        const parsed = this.getParsed(pageId);
+        const shape = this.getShapeMap(parsed).get(shapeId);
+        if (!shape)
+            throw new Error(`Shape ${shapeId} not found on page ${pageId}`);
+        if (!shape.Cell)
+            shape.Cell = [];
+        if (!Array.isArray(shape.Cell))
+            shape.Cell = [shape.Cell];
+        const cellName = axis === 'x' ? 'FlipX' : 'FlipY';
+        const value = enabled ? '1' : '0';
+        const existing = shape.Cell.find((c) => c['@_N'] === cellName);
+        if (existing)
+            existing['@_V'] = value;
+        else
+            shape.Cell.push({ '@_N': cellName, '@_V': value });
+        this.saveParsed(pageId, parsed);
+    }
+    /**
+     * Resize a shape, keeping it centred on its current PinX/PinY.
+     * Updates Width, Height, LocPinX, LocPinY, and the cached @_V on any
+     * Geometry cells whose @_F formula references Width or Height, so that
+     * non-Visio renderers see consistent values.
+     */
+    async resizeShape(pageId, shapeId, width, height) {
+        const parsed = this.getParsed(pageId);
+        const shape = this.getShapeMap(parsed).get(shapeId);
+        if (!shape)
+            throw new Error(`Shape ${shapeId} not found on page ${pageId}`);
+        if (!shape.Cell)
+            shape.Cell = [];
+        if (!Array.isArray(shape.Cell))
+            shape.Cell = [shape.Cell];
+        const upsert = (name, val) => {
+            const cell = shape.Cell.find((c) => c['@_N'] === name);
+            if (cell)
+                cell['@_V'] = val;
+            else
+                shape.Cell.push({ '@_N': name, '@_V': val });
+        };
+        upsert('Width', width.toString());
+        upsert('Height', height.toString());
+        upsert('LocPinX', (width / 2).toString());
+        upsert('LocPinY', (height / 2).toString());
+        // Keep cached @_V consistent for renderers that don't evaluate formulas
+        if (shape.Section) {
+            const sections = Array.isArray(shape.Section) ? shape.Section : [shape.Section];
+            for (const section of sections) {
+                if (section['@_N'] !== 'Geometry' || !section.Row)
+                    continue;
+                const rows = Array.isArray(section.Row) ? section.Row : [section.Row];
+                for (const row of rows) {
+                    if (!row.Cell)
+                        continue;
+                    const cells = Array.isArray(row.Cell) ? row.Cell : [row.Cell];
+                    for (const cell of cells) {
+                        if (cell['@_F'] === 'Width')
+                            cell['@_V'] = width.toString();
+                        if (cell['@_F'] === 'Height')
+                            cell['@_V'] = height.toString();
+                    }
+                }
+            }
+        }
+        this.saveParsed(pageId, parsed);
+    }
     async updateShapePosition(pageId, shapeId, x, y) {
         const parsed = this.getParsed(pageId);
         const shape = this.getShapeMap(parsed).get(shapeId);
@@ -804,5 +962,112 @@ class ShapeModifier {
         }
         this.saveParsed(pageId, parsed);
     }
+    /**
+     * Read back all custom property (shape data) entries for a shape.
+     * Returns a map of property key → ShapeData, with values coerced to
+     * the declared type (Number, Boolean, Date, or String).
+     */
+    getShapeProperties(pageId, shapeId) {
+        const parsed = this.getParsed(pageId);
+        const shape = this.getShapeMap(parsed).get(shapeId);
+        if (!shape)
+            throw new Error(`Shape ${shapeId} not found on page ${pageId}`);
+        const result = {};
+        if (!shape.Section)
+            return result;
+        const sections = Array.isArray(shape.Section) ? shape.Section : [shape.Section];
+        const propSection = sections.find((s) => s['@_N'] === 'Property');
+        if (!propSection?.Row)
+            return result;
+        const rows = Array.isArray(propSection.Row) ? propSection.Row : [propSection.Row];
+        for (const row of rows) {
+            // Row names are "Prop.KeyName" — strip the prefix to recover the user-facing key
+            const rawKey = row['@_N'] ?? '';
+            const key = rawKey.startsWith('Prop.') ? rawKey.slice(5) : rawKey;
+            if (!key)
+                continue;
+            const cells = Array.isArray(row.Cell) ? row.Cell : (row.Cell ? [row.Cell] : []);
+            const getCell = (name) => cells.find((c) => c['@_N'] === name)?.['@_V'];
+            const rawValue = getCell('Value') ?? '';
+            const type = parseInt(getCell('Type') ?? '0');
+            const label = getCell('Label');
+            const hidden = getCell('Invisible') === '1';
+            let value;
+            switch (type) {
+                case VisioTypes_1.VisioPropType.Number:
+                case VisioTypes_1.VisioPropType.Currency:
+                case VisioTypes_1.VisioPropType.Duration:
+                    value = parseFloat(rawValue) || 0;
+                    break;
+                case VisioTypes_1.VisioPropType.Boolean:
+                    value = rawValue === '1' || rawValue.toLowerCase() === 'true';
+                    break;
+                case VisioTypes_1.VisioPropType.Date:
+                    value = new Date(rawValue);
+                    break;
+                default:
+                    value = rawValue;
+            }
+            result[key] = { value, label, hidden, type };
+        }
+        return result;
+    }
+    /**
+     * Read back all hyperlinks attached to a shape.
+     */
+    getShapeHyperlinks(pageId, shapeId) {
+        const parsed = this.getParsed(pageId);
+        const shape = this.getShapeMap(parsed).get(shapeId);
+        if (!shape)
+            throw new Error(`Shape ${shapeId} not found on page ${pageId}`);
+        const result = [];
+        if (!shape.Section)
+            return result;
+        const sections = Array.isArray(shape.Section) ? shape.Section : [shape.Section];
+        const linkSection = sections.find((s) => s['@_N'] === 'Hyperlink');
+        if (!linkSection?.Row)
+            return result;
+        const rows = Array.isArray(linkSection.Row) ? linkSection.Row : [linkSection.Row];
+        for (const row of rows) {
+            const cells = Array.isArray(row.Cell) ? row.Cell : (row.Cell ? [row.Cell] : []);
+            const getCell = (name) => cells.find((c) => c['@_N'] === name)?.['@_V'];
+            result.push({
+                address: getCell('Address'),
+                subAddress: getCell('SubAddress'),
+                description: getCell('Description'),
+                newWindow: getCell('NewWindow') === '1',
+            });
+        }
+        return result;
+    }
+    /**
+     * Read back the layer indices a shape is assigned to.
+     * Returns an empty array if the shape has no layer assignment.
+     */
+    getShapeLayerIndices(pageId, shapeId) {
+        const parsed = this.getParsed(pageId);
+        const shape = this.getShapeMap(parsed).get(shapeId);
+        if (!shape)
+            throw new Error(`Shape ${shapeId} not found on page ${pageId}`);
+        if (!shape.Section)
+            return [];
+        const sections = Array.isArray(shape.Section) ? shape.Section : [shape.Section];
+        const memSection = sections.find((s) => s['@_N'] === 'LayerMem');
+        if (!memSection?.Row)
+            return [];
+        const rows = Array.isArray(memSection.Row) ? memSection.Row : [memSection.Row];
+        const row = rows[0];
+        if (!row)
+            return [];
+        const cells = Array.isArray(row.Cell) ? row.Cell : (row.Cell ? [row.Cell] : []);
+        const memberCell = cells.find((c) => c['@_N'] === 'LayerMember');
+        if (!memberCell?.['@_V'])
+            return [];
+        return memberCell['@_V']
+            .split(';')
+            .filter((s) => s.length > 0)
+            .map((s) => parseInt(s))
+            .filter((n) => !isNaN(n));
+    }
 }
 exports.ShapeModifier = ShapeModifier;

package/dist/ShapeReader.d.ts

@@ -5,5 +5,17 @@ export declare class ShapeReader {
     private parser;
     constructor(pkg: VisioPackage);
     readShapes(path: string): VisioShape[];
+    /**
+     * Returns every shape on the page flattened into a single array,
+     * including shapes nested inside groups at any depth.
+     */
+    readAllShapes(path: string): VisioShape[];
+    /**
+     * Find a single shape by ID anywhere in the page tree (including nested groups).
+     * Returns undefined if not found.
+     */
+    readShapeById(path: string, shapeId: string): VisioShape | undefined;
+    private gatherShapes;
+    private findShapeById;
     private parseShape;
 }

package/dist/ShapeReader.js

@@ -20,12 +20,68 @@ class ShapeReader {
             return [];
         }
         const parsed = this.parser.parse(content);
-        // Supports PageContents -> Shapes -> Shape or just Shapes -> Shape depending on structure
         const shapesData = parsed.PageContents?.Shapes?.Shape;
         if (!shapesData)
             return [];
-        const shapesArray = (0, VisioParsers_1.asArray)(shapesData);
-        return shapesArray.map(s => this.parseShape(s));
+        return (0, VisioParsers_1.asArray)(shapesData).map(s => this.parseShape(s));
+    }
+    /**
+     * Returns every shape on the page flattened into a single array,
+     * including shapes nested inside groups at any depth.
+     */
+    readAllShapes(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 [];
+        const result = [];
+        this.gatherShapes((0, VisioParsers_1.asArray)(shapesData), result);
+        return result;
+    }
+    /**
+     * Find a single shape by ID anywhere in the page tree (including nested groups).
+     * Returns undefined if not found.
+     */
+    readShapeById(path, shapeId) {
+        let content;
+        try {
+            content = this.pkg.getFileText(path);
+        }
+        catch {
+            return undefined;
+        }
+        const parsed = this.parser.parse(content);
+        const shapesData = parsed.PageContents?.Shapes?.Shape;
+        if (!shapesData)
+            return undefined;
+        return this.findShapeById((0, VisioParsers_1.asArray)(shapesData), shapeId);
+    }
+    gatherShapes(rawShapes, result) {
+        for (const s of rawShapes) {
+            result.push(this.parseShape(s));
+            if (s.Shapes?.Shape) {
+                this.gatherShapes((0, VisioParsers_1.asArray)(s.Shapes.Shape), result);
+            }
+        }
+    }
+    findShapeById(rawShapes, shapeId) {
+        for (const s of rawShapes) {
+            if (s['@_ID'] === shapeId)
+                return this.parseShape(s);
+            if (s.Shapes?.Shape) {
+                const found = this.findShapeById((0, VisioParsers_1.asArray)(s.Shapes.Shape), shapeId);
+                if (found)
+                    return found;
+            }
+        }
+        return undefined;
     }
     parseShape(s) {
         const shape = {

package/dist/VisioDocument.d.ts

@@ -17,5 +17,15 @@ export declare class VisioDocument {
      * Set a background page for a foreground page
      */
     setBackgroundPage(foregroundPage: Page, backgroundPage: Page): Promise<void>;
+    /**
+     * Find a page by name. Returns undefined if no page with that name exists.
+     */
+    getPage(name: string): Page | undefined;
+    /**
+     * Delete a page from the document.
+     * Removes the page XML, its relationships, the Content Types entry,
+     * and any BackPage references from other pages.
+     */
+    deletePage(page: Page): Promise<void>;
     save(filename?: string): Promise<Buffer>;
 }

package/dist/VisioDocument.js

@@ -116,6 +116,21 @@ class VisioDocument {
         await this.pageManager.setBackgroundPage(foregroundPage.id, backgroundPage.id);
         this._pageCache = null;
     }
+    /**
+     * Find a page by name. Returns undefined if no page with that name exists.
+     */
+    getPage(name) {
+        return this.pages.find(p => p.name === name);
+    }
+    /**
+     * Delete a page from the document.
+     * Removes the page XML, its relationships, the Content Types entry,
+     * and any BackPage references from other pages.
+     */
+    async deletePage(page) {
+        await this.pageManager.deletePage(page.id);
+        this._pageCache = null;
+    }
     async save(filename) {
         return this.pkg.save(filename);
     }

package/dist/VisioPackage.d.ts

@@ -6,5 +6,6 @@ export declare class VisioPackage {
     load(buffer: Buffer | ArrayBuffer | Uint8Array): Promise<void>;
     updateFile(path: string, content: string | Buffer): void;
     save(filename?: string): Promise<Buffer>;
+    removeFile(path: string): void;
     getFileText(path: string): string;
 }

package/dist/VisioPackage.js

@@ -98,6 +98,13 @@ class VisioPackage {
         }
         return buffer;
     }
+    removeFile(path) {
+        if (!this.zip) {
+            throw new Error("Package not loaded");
+        }
+        this._files.delete(path);
+        this.zip.remove(path);
+    }
     getFileText(path) {
         const content = this._files.get(path);
         if (content === undefined) {

package/dist/core/PageManager.d.ts

@@ -21,6 +21,13 @@ export declare class PageManager {
      * Create a background page
      */
     createBackgroundPage(name: string): Promise<string>;
+    /**
+     * Delete a page and clean up all associated XML entries.
+     * Removes the page file, its .rels file, the entry in pages.xml,
+     * the relationship in pages.xml.rels, the Content Types override,
+     * and any BackPage references from other pages that pointed to it.
+     */
+    deletePage(pageId: string): Promise<void>;
     /**
      * Set a background page for a foreground page
      */

package/dist/core/PageManager.js

@@ -208,6 +208,69 @@ class PageManager {
         this.load(true);
         return newId.toString();
     }
+    /**
+     * Delete a page and clean up all associated XML entries.
+     * Removes the page file, its .rels file, the entry in pages.xml,
+     * the relationship in pages.xml.rels, the Content Types override,
+     * and any BackPage references from other pages that pointed to it.
+     */
+    async deletePage(pageId) {
+        this.load();
+        const page = this.pages.find(p => p.id.toString() === pageId);
+        if (!page)
+            throw new Error(`Page ${pageId} not found`);
+        const pageFileName = page.xmlPath.split('/').pop(); // e.g. "page2.xml"
+        // 1. Remove the page XML file
+        try {
+            this.pkg.removeFile(page.xmlPath);
+        }
+        catch { /* already gone */ }
+        // 2. Remove the page's .rels file if it exists
+        const pageRelsPath = `visio/pages/_rels/${pageFileName}.rels`;
+        try {
+            this.pkg.removeFile(pageRelsPath);
+        }
+        catch { /* no rels file is fine */ }
+        // 3. Remove entry from pages.xml (and strip BackPage refs pointing to this page)
+        const pagesPath = 'visio/pages/pages.xml';
+        const pagesContent = this.pkg.getFileText(pagesPath);
+        const parsedPages = this.parser.parse(pagesContent);
+        let pageNodes = parsedPages.Pages.Page;
+        if (!Array.isArray(pageNodes))
+            pageNodes = pageNodes ? [pageNodes] : [];
+        // Remove deleted page and clean up BackPage refs on remaining pages
+        parsedPages.Pages.Page = pageNodes
+            .filter((n) => n['@_ID'] !== pageId)
+            .map((n) => {
+            if (n['@_BackPage'] === pageId) {
+                const copy = { ...n };
+                delete copy['@_BackPage'];
+                return copy;
+            }
+            return n;
+        });
+        this.pkg.updateFile(pagesPath, (0, XmlHelper_1.buildXml)(this.builder, parsedPages));
+        // 4. Remove relationship from pages.xml.rels
+        const pagesRelsPath = 'visio/pages/_rels/pages.xml.rels';
+        const pagesRelsContent = this.pkg.getFileText(pagesRelsPath);
+        const parsedPagesRels = this.parser.parse(pagesRelsContent);
+        let rels = parsedPagesRels.Relationships?.Relationship;
+        if (!Array.isArray(rels))
+            rels = rels ? [rels] : [];
+        parsedPagesRels.Relationships.Relationship = rels.filter((r) => r['@_Id'] !== page.relId);
+        this.pkg.updateFile(pagesRelsPath, (0, XmlHelper_1.buildXml)(this.builder, parsedPagesRels));
+        // 5. Remove Content Types override for the page file
+        const ctPath = '[Content_Types].xml';
+        const ctContent = this.pkg.getFileText(ctPath);
+        const parsedCt = this.parser.parse(ctContent);
+        let overrides = parsedCt.Types.Override;
+        if (!Array.isArray(overrides))
+            overrides = overrides ? [overrides] : [];
+        parsedCt.Types.Override = overrides.filter((o) => !o['@_PartName']?.endsWith(pageFileName));
+        this.pkg.updateFile(ctPath, (0, XmlHelper_1.buildXml)(this.builder, parsedCt));
+        // 6. Reload the page list to reflect the deletion
+        this.load(true);
+    }
     /**
      * Set a background page for a foreground page
      */

package/dist/index.d.ts

@@ -6,4 +6,5 @@ export { ShapeModifier } from './ShapeModifier';
 export { VisioDocument } from './VisioDocument';
 export { Page } from './Page';
 export { Shape } from './Shape';
+export type { ShapeData, ShapeHyperlink } from './Shape';
 export * from './types/VisioTypes';

package/dist/shapes/ForeignShapeBuilder.js

@@ -17,8 +17,8 @@ class ForeignShapeBuilder {
                 { '@_N': 'PinY', '@_V': props.y.toString() },
                 { '@_N': 'Width', '@_V': props.width.toString() },
                 { '@_N': 'Height', '@_V': props.height.toString() },
-                { '@_N': 'LocPinX', '@_V': (props.width / 2).toString() },
-                { '@_N': 'LocPinY', '@_V': (props.height / 2).toString() }
+                { '@_N': 'LocPinX', '@_V': (props.width / 2).toString(), '@_F': 'Width*0.5' },
+                { '@_N': 'LocPinY', '@_V': (props.height / 2).toString(), '@_F': 'Height*0.5' }
             ],
             Section: [
                 // Foreign shapes typically have no border (LinePattern=0)

package/dist/shapes/ShapeBuilder.js

@@ -18,8 +18,8 @@ class ShapeBuilder {
                 { '@_N': 'PinY', '@_V': props.y.toString() },
                 { '@_N': 'Width', '@_V': props.width.toString() },
                 { '@_N': 'Height', '@_V': props.height.toString() },
-                { '@_N': 'LocPinX', '@_V': (props.width / 2).toString() },
-                { '@_N': 'LocPinY', '@_V': (props.height / 2).toString() }
+                { '@_N': 'LocPinX', '@_V': (props.width / 2).toString(), '@_F': 'Width*0.5' },
+                { '@_N': 'LocPinY', '@_V': (props.height / 2).toString(), '@_F': 'Height*0.5' }
             ],
             Section: []
             // Text added at end by caller or we can do it here if props.text is final
@@ -36,12 +36,20 @@ class ShapeBuilder {
                 weight: '0.01'
             }));
         }
-        if (props.fontColor || props.bold) {
+        if (props.fontColor || props.bold || props.fontSize !== undefined || props.fontFamily !== undefined) {
             shape.Section.push((0, StyleHelpers_1.createCharacterSection)({
                 bold: props.bold,
-                color: props.fontColor
+                color: props.fontColor,
+                fontSize: props.fontSize,
+                fontFamily: props.fontFamily,
             }));
         }
+        if (props.horzAlign !== undefined) {
+            shape.Section.push((0, StyleHelpers_1.createParagraphSection)(props.horzAlign));
+        }
+        if (props.verticalAlign !== undefined) {
+            shape.Cell.push({ '@_N': 'VerticalAlign', '@_V': (0, StyleHelpers_1.vertAlignValue)(props.verticalAlign) });
+        }
         // Add Geometry
         // Only if NOT a Group AND NOT a Master Instance
         if (props.type !== 'Group' && !props.masterId) {

package/dist/types/VisioTypes.d.ts

@@ -82,6 +82,14 @@ export interface NewShapeProps {
     fillColor?: string;
     fontColor?: string;
     bold?: boolean;
+    /** Font size in points (e.g. 14 for 14pt). */
+    fontSize?: number;
+    /** Font family name (e.g. "Arial", "Times New Roman"). */
+    fontFamily?: string;
+    /** Horizontal text alignment within the shape. */
+    horzAlign?: 'left' | 'center' | 'right' | 'justify';
+    /** Vertical text alignment within the shape. */
+    verticalAlign?: 'top' | 'middle' | 'bottom';
     type?: string;
     masterId?: string;
     imgRelId?: string;

package/dist/utils/StyleHelpers.d.ts

@@ -15,12 +15,33 @@ export declare const ArrowHeads: {
     CrowsFoot: string;
     One: string;
 };
+declare const HORZ_ALIGN_VALUES: {
+    readonly left: "0";
+    readonly center: "1";
+    readonly right: "2";
+    readonly justify: "3";
+};
+declare const VERT_ALIGN_VALUES: {
+    readonly top: "0";
+    readonly middle: "1";
+    readonly bottom: "2";
+};
+export type HorzAlign = keyof typeof HORZ_ALIGN_VALUES;
+export type VertAlign = keyof typeof VERT_ALIGN_VALUES;
+export declare function horzAlignValue(align: HorzAlign): string;
+export declare function vertAlignValue(align: VertAlign): string;
 export declare function createCharacterSection(props: {
     bold?: boolean;
     color?: string;
+    /** Font size in points (e.g. 12 for 12pt). Stored internally as inches (pt / 72). */
+    fontSize?: number;
+    /** Font family name (e.g. "Arial"). Uses FONT() formula for portability. */
+    fontFamily?: string;
 }): VisioSection;
+export declare function createParagraphSection(horzAlign: HorzAlign): VisioSection;
 export declare function createLineSection(props: {
     color?: string;
     pattern?: string;
     weight?: string;
 }): VisioSection;
+export {};

package/dist/utils/StyleHelpers.js

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArrowHeads = void 0;
 exports.createFillSection = createFillSection;
+exports.horzAlignValue = horzAlignValue;
+exports.vertAlignValue = vertAlignValue;
 exports.createCharacterSection = createCharacterSection;
+exports.createParagraphSection = createParagraphSection;
 exports.createLineSection = createLineSection;
 const hexToRgb = (hex) => {
     // Expand shorthand form (e.g. "03F") to full form (e.g. "0033FF")
@@ -35,32 +38,66 @@ exports.ArrowHeads = {
     One: '24', // Visio "One" (Dash) - Approximate, or '26'
     // There are many variants, but 29 is the standard "Fork"
 };
+const HORZ_ALIGN_VALUES = {
+    left: '0',
+    center: '1',
+    right: '2',
+    justify: '3',
+};
+const VERT_ALIGN_VALUES = {
+    top: '0',
+    middle: '1',
+    bottom: '2',
+};
+function horzAlignValue(align) {
+    return HORZ_ALIGN_VALUES[align];
+}
+function vertAlignValue(align) {
+    return VERT_ALIGN_VALUES[align];
+}
 function createCharacterSection(props) {
-    // Visio Character Section
-    // N="Character"
-    // Row T="Character"
-    //   Cell N="Color" V="#FF0000"
-    //   Cell N="Style" V="1" (1=Bold, 2=Italic, 4=Underline) - Bitwise
-    // Visio booleans are often 0 or 1.
-    // Style=1 (Bold)
-    // Default Style is 0 (Normal)
     let styleVal = 0;
     if (props.bold) {
-        styleVal += 1; // Add Bold bit
+        styleVal += 1; // Bold bit
     }
-    // Default Color is usually 0 (Black) or specific hex
     const colorVal = props.color || '#000000';
+    const cells = [
+        { '@_N': 'Color', '@_V': colorVal, '@_F': hexToRgb(colorVal) },
+        { '@_N': 'Style', '@_V': styleVal.toString() },
+    ];
+    if (props.fontSize !== undefined) {
+        // Visio stores size in inches internally; @_U="PT" is a display hint for the ShapeSheet UI
+        const sizeInInches = props.fontSize / 72;
+        cells.push({ '@_N': 'Size', '@_V': sizeInInches.toString(), '@_U': 'PT' });
+    }
+    if (props.fontFamily !== undefined) {
+        // FONT("name") formula lets Visio resolve the font by name at load time.
+        // @_V="0" is a safe placeholder (document default font) used before Visio evaluates the formula.
+        cells.push({ '@_N': 'Font', '@_V': '0', '@_F': `FONT("${props.fontFamily}")` });
+    }
+    else {
+        cells.push({ '@_N': 'Font', '@_V': '1' }); // Default (Calibri)
+    }
     return {
         '@_N': 'Character',
         Row: [
             {
                 '@_T': 'Character',
                 '@_IX': '0',
+                Cell: cells,
+            }
+        ]
+    };
+}
+function createParagraphSection(horzAlign) {
+    return {
+        '@_N': 'Paragraph',
+        Row: [
+            {
+                '@_T': 'Paragraph',
+                '@_IX': '0',
                 Cell: [
-                    { '@_N': 'Color', '@_V': colorVal, '@_F': hexToRgb(colorVal) },
-                    { '@_N': 'Style', '@_V': styleVal.toString() },
-                    // Size, Font, etc could go here
-                    { '@_N': 'Font', '@_V': '1' } // Default font (Calibri usually)
+                    { '@_N': 'HorzAlign', '@_V': HORZ_ALIGN_VALUES[horzAlign] },
                 ]
             }
         ]

package/package.json

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