@graph-knowledge/api 0.2.0 → 0.3.2

package/README.md

@@ -92,6 +92,7 @@ new GraphKnowledgeAPI(config: ApiConfig)
 | `signOut()` | Signs out the current user |
 | `waitForAuthInit()` | Waits for Firebase Auth to initialize |
 | `measureText(text, options?)` | Measures text dimensions (static method, no auth required) |
+| `fitTextToShape(text, bounds, options?)` | Fits text into a shape's bounds (static method, no auth required) |
 
 #### Properties
 
@@ -185,6 +186,11 @@ const rect = await api.elements.create(documentId, nodeId, {
 });
 
 // Create text
+// If you omit both `width` and `maxWidth`, the API will auto-measure the text
+// and use a tight single-line bounding box. This is convenient for simple labels.
+// For predictable wrapping or alignment in more complex layouts, explicitly set
+// `width` or `maxWidth`. You can use measureText() to choose a width, or
+// fitTextToShape() for text inside shapes.
 await api.elements.create(documentId, nodeId, {
     type: "text",
     x: 100,
@@ -219,6 +225,18 @@ await api.elements.create(documentId, nodeId, {
 });
 // Note: height is auto-calculated based on the number of lines and lineHeight
 
+// Create text with auto-wrapping
+// maxWidth sets the wrap boundary — text will wrap at word boundaries
+await api.elements.create(documentId, nodeId, {
+    type: "text",
+    x: 100,
+    y: 300,
+    text: "This is a long paragraph that will automatically wrap within the specified width boundary.",
+    maxWidth: 400,  // Text wraps at 400px
+    fontSize: 18
+});
+// Note: height is auto-calculated based on wrapped lines
+
 // Create a connector
 await api.elements.create(documentId, nodeId, {
     type: "connector",
@@ -450,6 +468,106 @@ npm install canvas
 Without it, the API uses character-based estimation (less accurate).
 The `canvas` package requires native compilation - see [node-canvas requirements](https://github.com/Automattic/node-canvas#compiling).
 
+### Text Width Behavior
+
+When you create a text element via the API without `width` or `maxWidth`, the API **auto-measures** the text and sets the width to fit the content. This prevents the legacy 100px default that caused unexpected wrapping.
+
+For predictable wrapping or text inside shapes, explicitly set `width` or `maxWidth`:
+
+```typescript
+// Auto-measured — convenient for simple labels
+await api.elements.create(docId, nodeId, {
+    type: "text", x: 100, y: 100,
+    text: "My Long Title",
+    fontSize: 24
+});
+
+// Explicit width — for controlled wrapping
+const m = GraphKnowledgeAPI.measureText("My Long Title", { fontSize: 24 });
+await api.elements.create(docId, nodeId, {
+    type: "text", x: 100, y: 100, width: m.width,
+    text: "My Long Title",
+    fontSize: 24
+});
+
+// fitTextToShape — for text inside shapes (sets maxWidth automatically)
+const fit = GraphKnowledgeAPI.fitTextToShape("My Long Title", shapeBounds);
+await api.elements.create(docId, nodeId, { type: "text", ...fit.textInput });
+```
+
+## Layout Helpers
+
+Fit text into shapes with automatic wrapping, shrinking, or both. Returns a ready-to-use `textInput` for element creation.
+
+```typescript
+import { GraphKnowledgeAPI } from "@graph-knowledge/api";
+
+// Fit text into a rectangle (default: wrap strategy)
+const result = GraphKnowledgeAPI.fitTextToShape("Hello World", {
+    x: 100, y: 100, width: 200, height: 100
+});
+console.log(result.fits);      // true if text fits within bounds
+console.log(result.fontSize);  // final font size used
+
+// Create the text element directly
+await api.elements.create(docId, nodeId, { type: "text", ...result.textInput });
+```
+
+### Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `"wrap"` (default) | Wraps text at word boundaries. Reports `fits: false` if height overflows. |
+| `"shrink"` | Reduces font size (down to `minFontSize`) until text fits in one line. |
+| `"auto"` | Tries wrapping first. If height overflows, shrinks font size with wrapping. |
+
+```typescript
+// Shrink: reduce font size to fit in one line
+const shrunk = GraphKnowledgeAPI.fitTextToShape("A very long title", bounds, {
+    strategy: "shrink",
+    fontSize: 24,
+    minFontSize: 8
+});
+
+// Auto: wrap first, shrink if needed
+const auto = GraphKnowledgeAPI.fitTextToShape("Long paragraph text...", bounds, {
+    strategy: "auto"
+});
+```
+
+### FitTextOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `fontSize` | `number` | `16` | Starting font size in pixels |
+| `fontFamily` | `string` | `"Arial, sans-serif"` | Font family |
+| `fontWeight` | `number` | `400` | Font weight (100-900) |
+| `fillColor` | `string` | `"#000000"` | Text fill color |
+| `textAlign` | `"left" \| "center" \| "right"` | `"center"` | Text alignment |
+| `lineHeight` | `number` | `1.2` | Line height multiplier |
+| `padding` | `number` | `8` | Padding between shape edge and text |
+| `strategy` | `"wrap" \| "shrink" \| "auto"` | `"wrap"` | Fitting strategy |
+| `minFontSize` | `number` | `8` | Minimum font size for shrink/auto |
+
+### Creating Documents with AI
+
+Combine shapes and fitted text for programmatic document creation:
+
+```typescript
+// Create a labeled rectangle
+const rect = await api.elements.create(docId, nodeId, {
+    type: "rectangle",
+    x: 100, y: 100, width: 200, height: 80,
+    fillColor: "#E3F2FD"
+});
+
+const label = GraphKnowledgeAPI.fitTextToShape("User Service", {
+    x: 100, y: 100, width: 200, height: 80
+}, { fontSize: 18, strategy: "auto" });
+
+await api.elements.create(docId, nodeId, { type: "text", ...label.textInput });
+```
+
 ## Error Handling
 
 The API throws typed errors for different failure cases:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graph-knowledge/api",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "Headless Document API for Graph Knowledge - programmatic access to documents, nodes, and elements",
   "license": "MIT",
   "author": "Graph Knowledge Team",

package/src/index.d.ts

@@ -17,5 +17,7 @@ export { LinkLevelManager } from "./lib/utils/link-level-manager";
 export type { LevelChange, LinkState } from "./lib/utils/link-level-manager";
 export type { MeasureTextOptions, TextMetrics } from "./lib/types/text-measurement-types";
 export { TextMeasurementService } from "./lib/utils/text-measurement/text-measurement-service";
+export { LayoutHelper } from "./lib/utils/layout/layout-helper";
+export type { FitTextOptions, FitTextResult, FitTextStrategy, ShapeBounds } from "./lib/types/layout-types";
 export { MockAuthClient } from "./lib/testing/mock-auth-client";
 export { MockFirestoreClient } from "./lib/testing/mock-firestore-client";

package/src/index.js

@@ -3,7 +3,7 @@
 // Graph Knowledge Headless Document API
 // =============================================================================
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MockFirestoreClient = exports.MockAuthClient = exports.TextMeasurementService = exports.LinkLevelManager = exports.CURRENT_DOCUMENT_SCHEMA_VERSION = exports.PermissionError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.GraphKnowledgeAPIError = exports.GraphKnowledgeAPI = void 0;
+exports.MockFirestoreClient = exports.MockAuthClient = exports.LayoutHelper = exports.TextMeasurementService = exports.LinkLevelManager = exports.CURRENT_DOCUMENT_SCHEMA_VERSION = exports.PermissionError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.GraphKnowledgeAPIError = exports.GraphKnowledgeAPI = void 0;
 // Main API Class
 var graph_knowledge_api_1 = require("./lib/graph-knowledge-api");
 Object.defineProperty(exports, "GraphKnowledgeAPI", { enumerable: true, get: function () { return graph_knowledge_api_1.GraphKnowledgeAPI; } });
@@ -25,6 +25,9 @@ var link_level_manager_1 = require("./lib/utils/link-level-manager");
 Object.defineProperty(exports, "LinkLevelManager", { enumerable: true, get: function () { return link_level_manager_1.LinkLevelManager; } });
 var text_measurement_service_1 = require("./lib/utils/text-measurement/text-measurement-service");
 Object.defineProperty(exports, "TextMeasurementService", { enumerable: true, get: function () { return text_measurement_service_1.TextMeasurementService; } });
+// Layout
+var layout_helper_1 = require("./lib/utils/layout/layout-helper");
+Object.defineProperty(exports, "LayoutHelper", { enumerable: true, get: function () { return layout_helper_1.LayoutHelper; } });
 // =============================================================================
 // Testing Utilities
 // =============================================================================

package/src/lib/graph-knowledge-api.d.ts

@@ -6,6 +6,7 @@ import { IElementOperations } from "./interfaces/element-operations.interface";
 import { IBatchOperations } from "./interfaces/batch-operations.interface";
 import { ITemplateOperations } from "./interfaces/template-operations.interface";
 import { MeasureTextOptions, TextMetrics } from "./types/text-measurement-types";
+import { FitTextOptions, FitTextResult, ShapeBounds } from "./types/layout-types";
 /**
  * Main entry point for the Graph Knowledge Headless API.
  *
@@ -55,6 +56,10 @@ export declare class GraphKnowledgeAPI {
      * Shared text measurement service for static and instance methods.
      */
     private static _textMeasurementService;
+    /**
+     * Shared layout helper for static and instance methods.
+     */
+    private static _layoutHelper;
     /**
      * Creates a new GraphKnowledgeAPI instance.
      * @param config Configuration including Firebase credentials
@@ -146,4 +151,32 @@ export declare class GraphKnowledgeAPI {
      * ```
      */
     measureText(text: string, options?: MeasureTextOptions): TextMetrics;
+    /**
+     * Fits text into a shape's bounding box, returning a ready-to-use TextInput.
+     * No authentication required.
+     *
+     * @param text The text to fit
+     * @param bounds The shape's bounding box (x, y, width, height)
+     * @param options Fitting options (strategy, font, padding, etc.)
+     * @returns FitTextResult with textInput ready for element creation
+     *
+     * @example
+     * ```typescript
+     * const result = GraphKnowledgeAPI.fitTextToShape("Hello World", {
+     *     x: 100, y: 100, width: 200, height: 100
+     * });
+     * await api.elements.create(docId, nodeId, { type: "text", ...result.textInput });
+     * ```
+     */
+    static fitTextToShape(text: string, bounds: ShapeBounds, options?: FitTextOptions): FitTextResult;
+    /**
+     * Fits text into a shape's bounding box, returning a ready-to-use TextInput.
+     * Instance method that delegates to the static method.
+     *
+     * @param text The text to fit
+     * @param bounds The shape's bounding box (x, y, width, height)
+     * @param options Fitting options (strategy, font, padding, etc.)
+     * @returns FitTextResult with textInput ready for element creation
+     */
+    fitTextToShape(text: string, bounds: ShapeBounds, options?: FitTextOptions): FitTextResult;
 }

package/src/lib/graph-knowledge-api.js

@@ -16,6 +16,7 @@ const node_validator_1 = require("./validators/node-validator");
 const element_validator_registry_1 = require("./validators/element-validator-registry");
 const template_validator_1 = require("./validators/template-validator");
 const text_measurement_service_1 = require("./utils/text-measurement/text-measurement-service");
+const layout_helper_1 = require("./utils/layout/layout-helper");
 /**
  * Main entry point for the Graph Knowledge Headless API.
  *
@@ -65,6 +66,10 @@ class GraphKnowledgeAPI {
      * Shared text measurement service for static and instance methods.
      */
     static _textMeasurementService = null;
+    /**
+     * Shared layout helper for static and instance methods.
+     */
+    static _layoutHelper = null;
     /**
      * Creates a new GraphKnowledgeAPI instance.
      * @param config Configuration including Firebase credentials
@@ -211,5 +216,46 @@ class GraphKnowledgeAPI {
     measureText(text, options = {}) {
         return GraphKnowledgeAPI.measureText(text, options);
     }
+    // =========================================================================
+    // Layout Helpers (static and instance methods)
+    // =========================================================================
+    /**
+     * Fits text into a shape's bounding box, returning a ready-to-use TextInput.
+     * No authentication required.
+     *
+     * @param text The text to fit
+     * @param bounds The shape's bounding box (x, y, width, height)
+     * @param options Fitting options (strategy, font, padding, etc.)
+     * @returns FitTextResult with textInput ready for element creation
+     *
+     * @example
+     * ```typescript
+     * const result = GraphKnowledgeAPI.fitTextToShape("Hello World", {
+     *     x: 100, y: 100, width: 200, height: 100
+     * });
+     * await api.elements.create(docId, nodeId, { type: "text", ...result.textInput });
+     * ```
+     */
+    static fitTextToShape(text, bounds, options) {
+        if (!GraphKnowledgeAPI._layoutHelper) {
+            if (!GraphKnowledgeAPI._textMeasurementService) {
+                GraphKnowledgeAPI._textMeasurementService = new text_measurement_service_1.TextMeasurementService();
+            }
+            GraphKnowledgeAPI._layoutHelper = new layout_helper_1.LayoutHelper(GraphKnowledgeAPI._textMeasurementService.provider);
+        }
+        return GraphKnowledgeAPI._layoutHelper.fitTextToShape(text, bounds, options);
+    }
+    /**
+     * Fits text into a shape's bounding box, returning a ready-to-use TextInput.
+     * Instance method that delegates to the static method.
+     *
+     * @param text The text to fit
+     * @param bounds The shape's bounding box (x, y, width, height)
+     * @param options Fitting options (strategy, font, padding, etc.)
+     * @returns FitTextResult with textInput ready for element creation
+     */
+    fitTextToShape(text, bounds, options) {
+        return GraphKnowledgeAPI.fitTextToShape(text, bounds, options);
+    }
 }
 exports.GraphKnowledgeAPI = GraphKnowledgeAPI;

package/src/lib/operations/element-operations.d.ts

@@ -25,6 +25,12 @@ export declare class ElementOperations implements IElementOperations {
      * Normalizes rotation to integer in range [0, 360).
      */
     private normalizeRotation;
+    /**
+     * Auto-measures text width for text elements created without explicit width/maxWidth.
+     * Uses a lazily-initialized TextMeasurementService singleton.
+     */
+    private measureTextWidth;
+    private static _textMeasurementService;
     /**
      * Builds properties object from element input.
      * Extracts type-specific properties, excluding common fields.

package/src/lib/operations/element-operations.js

@@ -4,6 +4,7 @@ exports.ElementOperations = void 0;
 const uuid_1 = require("../utils/uuid");
 const api_errors_1 = require("../errors/api-errors");
 const element_defaults_1 = require("../constants/element-defaults");
+const text_measurement_service_1 = require("../utils/text-measurement/text-measurement-service");
 /**
  * Implementation of element CRUD operations.
  */
@@ -54,12 +55,25 @@ class ElementOperations {
         // Connectors have optional x/y since their position is derived from connected elements
         const x = input.x ?? 0;
         const y = input.y ?? 0;
+        // For text elements, maxWidth is a convenience alias for width (the wrap boundary)
+        let resolvedWidth = input.width;
+        if (input.type === "text" && resolvedWidth === undefined) {
+            const textInput = input;
+            if (textInput.maxWidth !== undefined) {
+                resolvedWidth = textInput.maxWidth;
+            }
+            else {
+                // Auto-measure text width to avoid the 100px default which causes
+                // unexpected wrapping in the editor.
+                resolvedWidth = this.measureTextWidth(textInput);
+            }
+        }
         const element = {
             id: (0, uuid_1.generateUuid)(),
             elementType: input.type,
             x,
             y,
-            width: input.width ?? defaults.width,
+            width: resolvedWidth ?? defaults.width,
             height: input.height ?? defaults.height,
             rotation: this.normalizeRotation(input.rotation ?? 0),
             properties: this.buildProperties(input)
@@ -149,6 +163,24 @@ class ElementOperations {
         }
         return Math.round(normalized);
     }
+    /**
+     * Auto-measures text width for text elements created without explicit width/maxWidth.
+     * Uses a lazily-initialized TextMeasurementService singleton.
+     */
+    measureTextWidth(input) {
+        if (!ElementOperations._textMeasurementService) {
+            ElementOperations._textMeasurementService = new text_measurement_service_1.TextMeasurementService();
+        }
+        const metrics = ElementOperations._textMeasurementService.measureText(input.text, {
+            fontSize: input.fontSize,
+            fontFamily: input.fontFamily,
+            fontWeight: input.fontWeight,
+            textAlign: input.textAlign,
+            lineHeight: input.lineHeight
+        });
+        return Math.ceil(metrics.width);
+    }
+    static _textMeasurementService = null;
     /**
      * Builds properties object from element input.
      * Extracts type-specific properties, excluding common fields.
@@ -157,7 +189,7 @@ class ElementOperations {
         const props = {
             __schemaVersion: 1
         };
-        // Exclude common fields, copy the rest as properties
+        // Exclude common fields and convenience aliases, copy the rest as properties
         const commonFields = new Set([
             "type",
             "x",
@@ -166,27 +198,22 @@ class ElementOperations {
             "height",
             "rotation",
             "isLink",
-            "linkTarget"
+            "linkTarget",
+            "maxWidth"
         ]);
         for (const [key, value] of Object.entries(input)) {
             if (!commonFields.has(key) && value !== undefined) {
                 props[key] = value;
             }
         }
-        // For text elements with an explicitly specified width, set __usesTopLeft: true
-        // so the app's normalization knows that x/y is the bounding box top-left
-        // (not the text anchor point). Without this, the app would incorrectly adjust
-        // x/y based on textAlign, causing centered text to be positioned in negative
-        // coordinates.
-        //
-        // However, when width is omitted, a default width is applied elsewhere. In that
-        // case we DO NOT set __usesTopLeft, so the text plugin can treat the element as
-        // auto-sized text instead of preserving the default container width.
+        // For text elements, set __usesTopLeft: true so the app's normalization
+        // knows that x/y is the bounding box top-left (not the text anchor point).
+        // Without this, the app would incorrectly adjust x/y based on textAlign,
+        // causing centered text to be positioned in negative coordinates.
+        // Since we now always resolve a proper width for text (via explicit width,
+        // maxWidth, or auto-measurement), we always set this flag.
         if (input.type === "text") {
-            const hasExplicitWidth = Object.prototype.hasOwnProperty.call(input, "width");
-            if (hasExplicitWidth) {
-                props["__usesTopLeft"] = true;
-            }
+            props["__usesTopLeft"] = true;
         }
         return props;
     }

package/src/lib/operations/template-operations.js

@@ -229,19 +229,13 @@ class TemplateOperations {
         const clonedProperties = { ...element.properties };
         // Update connector endpoint references if this is a connector
         if (element.elementType === "connector" && clonedProperties) {
-            if (clonedProperties["startAnchor"]?.elementId &&
-                idMapping.has(clonedProperties["startAnchor"].elementId)) {
-                clonedProperties["startAnchor"] = {
-                    ...clonedProperties["startAnchor"],
-                    elementId: idMapping.get(clonedProperties["startAnchor"].elementId)
-                };
+            if (clonedProperties["startElementId"] &&
+                idMapping.has(clonedProperties["startElementId"])) {
+                clonedProperties["startElementId"] = idMapping.get(clonedProperties["startElementId"]);
             }
-            if (clonedProperties["endAnchor"]?.elementId &&
-                idMapping.has(clonedProperties["endAnchor"].elementId)) {
-                clonedProperties["endAnchor"] = {
-                    ...clonedProperties["endAnchor"],
-                    elementId: idMapping.get(clonedProperties["endAnchor"].elementId)
-                };
+            if (clonedProperties["endElementId"] &&
+                idMapping.has(clonedProperties["endElementId"])) {
+                clonedProperties["endElementId"] = idMapping.get(clonedProperties["endElementId"]);
             }
         }
         const clonedElement = {

package/src/lib/types/element-input-types.d.ts

@@ -50,6 +50,8 @@ export interface TextInput extends BaseElementInput {
     textAlign?: "left" | "center" | "right";
     /** Line height multiplier */
     lineHeight?: number;
+    /** Maximum width for text wrapping. Text will auto-wrap at word boundaries within this width. */
+    maxWidth?: number;
 }
 /**
  * Anchor points for connectors.

package/src/lib/types/layout-types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Strategy for fitting text within a shape.
+ *
+ * - `wrap`: Wrap text at word boundaries within the shape width (default)
+ * - `shrink`: Reduce font size until text fits in a single line
+ * - `auto`: Try wrapping first; if height overflows, shrink font size with wrapping
+ */
+export type FitTextStrategy = "wrap" | "shrink" | "auto";
+/**
+ * Bounding box of a shape to fit text into.
+ */
+export interface ShapeBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Options for fitting text into a shape.
+ * All properties are optional and have sensible defaults.
+ */
+export interface FitTextOptions {
+    /** Font family. @default "Arial, sans-serif" */
+    fontFamily?: string;
+    /** Font size in pixels. @default 16 */
+    fontSize?: number;
+    /** Font weight (100-900). @default 400 */
+    fontWeight?: number;
+    /** Fill color for the text. @default "#000000" */
+    fillColor?: string;
+    /** Text alignment within the shape. @default "center" */
+    textAlign?: "left" | "center" | "right";
+    /** Line height multiplier. @default 1.2 */
+    lineHeight?: number;
+    /** Padding in pixels between shape edge and text. @default 8 */
+    padding?: number;
+    /** Strategy for fitting text. @default "wrap" */
+    strategy?: FitTextStrategy;
+    /** Minimum font size for shrink/auto strategies. @default 8 */
+    minFontSize?: number;
+}
+/**
+ * Result of fitting text into a shape.
+ */
+export interface FitTextResult {
+    /**
+     * Ready to spread into api.elements.create(docId, nodeId, { type: "text", ...textInput }).
+     */
+    textInput: {
+        x: number;
+        y: number;
+        text: string;
+        maxWidth?: number;
+        fontSize: number;
+        fontFamily: string;
+        fontWeight: number;
+        fillColor: string;
+        textAlign: "left" | "center" | "right";
+        lineHeight: number;
+    };
+    /** Final font size used (may differ from input if shrunk). */
+    fontSize: number;
+    /** Number of lines after fitting. */
+    lines: number;
+    /** Width of the measured text. */
+    textWidth: number;
+    /** Height of the measured text. */
+    textHeight: number;
+    /** False if text overflows the shape even after applying the strategy. */
+    fits: boolean;
+}

package/src/lib/types/layout-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/lib/utils/layout/layout-helper.d.ts

@@ -0,0 +1,37 @@
+import { ITextMeasurementProvider } from "../../interfaces/text-measurement.interface";
+import { FitTextOptions, FitTextResult, ShapeBounds } from "../../types/layout-types";
+/**
+ * Pure layout utility for fitting text into shapes.
+ * No Firestore/Auth dependencies — only requires a text measurement provider.
+ */
+export declare class LayoutHelper {
+    private readonly _measurementProvider;
+    constructor(_measurementProvider: ITextMeasurementProvider);
+    /**
+     * Fits text into a shape's bounding box, returning a ready-to-use TextInput.
+     *
+     * @param text The text to fit
+     * @param bounds The shape's bounding box
+     * @param options Fitting options (strategy, font, padding, etc.)
+     * @returns FitTextResult with textInput ready for element creation
+     */
+    fitTextToShape(text: string, bounds: ShapeBounds, options?: FitTextOptions): FitTextResult;
+    /**
+     * Wrap strategy: set maxWidth and measure. Report fits: false if height overflows.
+     */
+    private _fitWrap;
+    /**
+     * Shrink strategy: binary search font size until single-line text fits width.
+     */
+    private _fitShrink;
+    /**
+     * Auto strategy: try wrap first. If height overflows, binary search font size with wrapping.
+     */
+    private _fitAuto;
+    /** Measure without wrapping. */
+    private _measure;
+    /** Measure with wrapping at maxWidth. */
+    private _measureWrapped;
+    /** Build the final FitTextResult with centered positioning. */
+    private _buildResult;
+}

package/src/lib/utils/layout/layout-helper.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LayoutHelper = void 0;
+const FIT_TEXT_DEFAULTS = {
+    fontFamily: "Arial, sans-serif",
+    fontSize: 16,
+    fontWeight: 400,
+    fillColor: "#000000",
+    textAlign: "center",
+    lineHeight: 1.2,
+    padding: 8,
+    strategy: "wrap",
+    minFontSize: 8
+};
+/**
+ * Pure layout utility for fitting text into shapes.
+ * No Firestore/Auth dependencies — only requires a text measurement provider.
+ */
+class LayoutHelper {
+    _measurementProvider;
+    constructor(_measurementProvider) {
+        this._measurementProvider = _measurementProvider;
+    }
+    /**
+     * Fits text into a shape's bounding box, returning a ready-to-use TextInput.
+     *
+     * @param text The text to fit
+     * @param bounds The shape's bounding box
+     * @param options Fitting options (strategy, font, padding, etc.)
+     * @returns FitTextResult with textInput ready for element creation
+     */
+    fitTextToShape(text, bounds, options) {
+        const opts = { ...FIT_TEXT_DEFAULTS, ...options };
+        const contentWidth = Math.max(0, bounds.width - 2 * opts.padding);
+        const contentHeight = Math.max(0, bounds.height - 2 * opts.padding);
+        if (!text) {
+            return this._buildResult(text, bounds, opts, 0, 0, 0, opts.fontSize, true);
+        }
+        switch (opts.strategy) {
+            case "shrink":
+                return this._fitShrink(text, bounds, opts, contentWidth, contentHeight);
+            case "auto":
+                return this._fitAuto(text, bounds, opts, contentWidth, contentHeight);
+            case "wrap":
+            default:
+                return this._fitWrap(text, bounds, opts, contentWidth, contentHeight);
+        }
+    }
+    /**
+     * Wrap strategy: set maxWidth and measure. Report fits: false if height overflows.
+     */
+    _fitWrap(text, bounds, opts, contentWidth, contentHeight) {
+        const metrics = this._measurementProvider.measureText(text, {
+            fontSize: opts.fontSize,
+            fontFamily: opts.fontFamily,
+            fontWeight: opts.fontWeight,
+            textAlign: opts.textAlign,
+            lineHeight: opts.lineHeight,
+            maxWidth: contentWidth
+        });
+        const fits = metrics.height <= contentHeight;
+        return this._buildResult(text, bounds, opts, metrics.width, metrics.height, metrics.lines, opts.fontSize, fits);
+    }
+    /**
+     * Shrink strategy: binary search font size until single-line text fits width.
+     */
+    _fitShrink(text, bounds, opts, contentWidth, contentHeight) {
+        let lo = opts.minFontSize;
+        let hi = opts.fontSize;
+        let bestSize = lo;
+        // If text fits at full size, no need to shrink
+        const fullMetrics = this._measure(text, hi, opts);
+        if (fullMetrics.width <= contentWidth && fullMetrics.height <= contentHeight) {
+            return this._buildResult(text, bounds, opts, fullMetrics.width, fullMetrics.height, fullMetrics.lines, hi, true);
+        }
+        // Binary search for largest font size that fits
+        while (hi - lo > 0.5) {
+            const mid = (lo + hi) / 2;
+            const metrics = this._measure(text, mid, opts);
+            if (metrics.width <= contentWidth && metrics.height <= contentHeight) {
+                bestSize = mid;
+                lo = mid;
+            }
+            else {
+                hi = mid;
+            }
+        }
+        const finalSize = Math.floor(bestSize);
+        const finalMetrics = this._measure(text, finalSize, opts);
+        const fits = finalMetrics.width <= contentWidth && finalMetrics.height <= contentHeight;
+        return this._buildResult(text, bounds, opts, finalMetrics.width, finalMetrics.height, finalMetrics.lines, finalSize, fits);
+    }
+    /**
+     * Auto strategy: try wrap first. If height overflows, binary search font size with wrapping.
+     */
+    _fitAuto(text, bounds, opts, contentWidth, contentHeight) {
+        // Try wrapping at current font size
+        const wrapMetrics = this._measureWrapped(text, opts.fontSize, opts, contentWidth);
+        if (wrapMetrics.height <= contentHeight) {
+            return this._buildResult(text, bounds, opts, wrapMetrics.width, wrapMetrics.height, wrapMetrics.lines, opts.fontSize, true);
+        }
+        // Binary search font size with wrapping
+        let lo = opts.minFontSize;
+        let hi = opts.fontSize;
+        let bestSize = lo;
+        while (hi - lo > 0.5) {
+            const mid = (lo + hi) / 2;
+            const metrics = this._measureWrapped(text, mid, opts, contentWidth);
+            if (metrics.height <= contentHeight) {
+                bestSize = mid;
+                lo = mid;
+            }
+            else {
+                hi = mid;
+            }
+        }
+        const finalSize = Math.floor(bestSize);
+        const finalMetrics = this._measureWrapped(text, finalSize, opts, contentWidth);
+        const fits = finalMetrics.height <= contentHeight;
+        return this._buildResult(text, bounds, opts, finalMetrics.width, finalMetrics.height, finalMetrics.lines, finalSize, fits);
+    }
+    /** Measure without wrapping. */
+    _measure(text, fontSize, opts) {
+        return this._measurementProvider.measureText(text, {
+            fontSize,
+            fontFamily: opts.fontFamily,
+            fontWeight: opts.fontWeight,
+            textAlign: opts.textAlign,
+            lineHeight: opts.lineHeight
+        });
+    }
+    /** Measure with wrapping at maxWidth. */
+    _measureWrapped(text, fontSize, opts, maxWidth) {
+        return this._measurementProvider.measureText(text, {
+            fontSize,
+            fontFamily: opts.fontFamily,
+            fontWeight: opts.fontWeight,
+            textAlign: opts.textAlign,
+            lineHeight: opts.lineHeight,
+            maxWidth
+        });
+    }
+    /** Build the final FitTextResult with centered positioning. */
+    _buildResult(text, bounds, opts, textWidth, textHeight, lines, fontSize, fits) {
+        const contentWidth = Math.max(0, bounds.width - 2 * opts.padding);
+        const contentHeight = Math.max(0, bounds.height - 2 * opts.padding);
+        const x = bounds.x + opts.padding;
+        const y = bounds.y + opts.padding + (contentHeight - textHeight) / 2;
+        const textInput = {
+            x,
+            y,
+            text,
+            fontSize,
+            fontFamily: opts.fontFamily,
+            fontWeight: opts.fontWeight,
+            fillColor: opts.fillColor,
+            textAlign: opts.textAlign,
+            lineHeight: opts.lineHeight
+        };
+        if (contentWidth > 0) {
+            textInput.maxWidth = contentWidth;
+        }
+        return {
+            textInput,
+            fontSize,
+            lines,
+            textWidth,
+            textHeight,
+            fits
+        };
+    }
+}
+exports.LayoutHelper = LayoutHelper;

package/src/lib/validators/element-type-validators/text-validator.d.ts

@@ -11,4 +11,5 @@ export declare class TextValidator extends BaseElementValidator implements IElem
     private validateFontWeight;
     private validateTextAlign;
     private validateLineHeight;
+    private validateMaxWidth;
 }

package/src/lib/validators/element-type-validators/text-validator.js

@@ -28,6 +28,7 @@ class TextValidator extends base_element_validator_1.BaseElementValidator {
         this.validateFontWeight(textInput.fontWeight);
         this.validateTextAlign(textInput.textAlign);
         this.validateLineHeight(textInput.lineHeight);
+        this.validateMaxWidth(textInput.maxWidth);
     }
     validateFontSize(value) {
         if (value === undefined)
@@ -66,5 +67,15 @@ class TextValidator extends base_element_validator_1.BaseElementValidator {
             throw new api_errors_1.ValidationError("lineHeight must be positive", "lineHeight");
         }
     }
+    validateMaxWidth(value) {
+        if (value === undefined)
+            return;
+        if (typeof value !== "number" || isNaN(value)) {
+            throw new api_errors_1.ValidationError("maxWidth must be a valid number", "maxWidth");
+        }
+        if (value <= 0) {
+            throw new api_errors_1.ValidationError("maxWidth must be positive", "maxWidth");
+        }
+    }
 }
 exports.TextValidator = TextValidator;