@mlightcad/mtext-renderer 0.10.13 → 0.10.14

package/lib/renderer/mtext.d.ts

@@ -109,20 +109,86 @@ export declare class MText extends THREE.Object3D {
      */
     private createMTextGroup;
     /**
-     * Calculates the anchor point for text positioning based on alignment and flow direction.
-     * @param width - The width of the text
-     * @param height - The height of the text
-     * @param attachmentPoint - The attachment point for text alignment
-     * @param flowDirection - The text flow direction
-     * @returns The calculated anchor point coordinates
+     * Measures the logical text frame used by attachment-point anchoring.
+     *
+     * @remarks
+     * Line-layout boxes include inter-line leading that is useful for hit testing, but
+     * that leading must not become extra padding above the first rendered line when
+     * aligning to top/middle/bottom attachment points. This method therefore prefers the
+     * visible geometry height from `geometryBox` when it is non-empty, and only falls
+     * back to `layoutHeight` when there are no measurable glyphs (e.g. empty or
+     * whitespace-only runs).
+     *
+     * @param object - Root group produced by layout; traversed for {@link LineLayout}
+     *   metadata to locate the first line baseline.
+     * @param width - Column width used for horizontal anchoring when finite and
+     *   positive; if not, horizontal extents are taken from `geometryBox`.
+     * @param layoutHeight - Total laid-out height from {@link MTextProcessor} when
+     *   geometry height is unavailable or zero.
+     * @param geometryBox - Axis-aligned bounds of rendered primitives under `object`,
+     *   typically from {@link THREE.Box3.setFromObject}.
+     * @param flowDirection - Optional flow; when {@link MTextFlowDirection.BOTTOM_TO_TOP},
+     *   the vertical frame is anchored from the geometry minimum upward.
+     * @returns Metrics consumed by {@link MText.calculateAnchorPoint}.
+     */
+    private measureAnchorMetrics;
+    /**
+     * Computes the 2D translation that maps the logical frame described by `metrics`
+     * so that the chosen AutoCAD-style attachment point coincides with the insertion
+     * origin (before rotation/insertion-point transforms applied later in
+     * {@link MText.loadMText}).
+     *
+     * @remarks
+     * The returned vector is **added** to vertex positions and char-box metadata via
+     * `geometry.translate` / `CharBox.box.translate` / line `y` offsets. For `undefined`
+     * attachment, behavior matches {@link MTextAttachmentPoint.TopLeft}.
+     *
+     * @param metrics - Pre-anchoring frame from {@link MText.measureAnchorMetrics}.
+     * @param attachmentPoint - DWG attachment constant; determines which corner, edge
+     *   center, or baseline of the frame is pinned to `(0,0)` in anchored space.
+     * @returns Translation `(x, y)` in drawing units applied uniformly to the laid-out
+     *   group and its layout sidecars.
      */
     private calculateAnchorPoint;
     /**
-     * Recursively calculates bounding boxes for an object and its children.
-     * @param object - The Three.js object to process
-     * @param boxes - Array to store the calculated bounding boxes
+     * Walks a laid-out MText subgraph and accumulates world-space character hit boxes and
+     * soft line rectangles for {@link MText.createLayoutData} (raycasting, cursors, debug).
+     *
+     * @remarks
+     * - When `userData.layout.chars` is present, entries are transformed with
+     *   {@link buildCharBoxesFromObject} and appended to `chars`, then recursion stops
+     *   for that branch (char metadata is authoritative).
+     * - When only mesh/line geometry exists, a single synthetic {@link CharBox} wrapping
+     *   the geometry AABB may be emitted.
+     * - `userData.lineLayouts` rows are converted to world-space center `y` and height.
+     *
+     * @param object - Node to traverse (typically the root group from {@link MText.loadMText}).
+     * @param chars - Output collection; receives merged {@link CharBox} entries in world space.
+     * @param lines - Output collection; receives {@link LineLayout} summaries per line break.
      */
     private getLayout;
+    /**
+     * Depth-first union of this MText’s {@link MText.box} from layout metadata and mesh
+     * geometry, while optionally tracking coarse line AABB in `lineBounds`.
+     *
+     * @remarks
+     * Priority order per node:
+     * 1. If `userData.logicalBounds` exists (set in {@link MText.loadMText}), union that
+     *    axis-aligned rectangle transformed by `matrixWorld` — this reflects anchored
+     *    logical extents even when individual glyphs are expensive to union.
+     * 2. Else if `userData.lineLayouts` exists, expand `lineBounds` from the world-space
+     *    top/bottom of each line strip (used as a fallback when no logical bounds were
+     *    written, e.g. legacy paths).
+     * 3. Else if `userData.layout.chars` exists, union each transformed char AABB.
+     * 4. Else for mesh/line primitives, union non-decoration geometry bounds.
+     * 5. Always recurse into children.
+     *
+     * @param object - Current scene graph node.
+     * @param lineBounds - Mutable accumulator: `hasLine`/`min*`/`max*` track the union of
+     *   line-layout strips in world space; `hasLogicalBounds` flips true when any child
+     *   contributed `logicalBounds` so {@link MText.syncDraw} can avoid double-counting
+     *   vertical extent from line strips alone.
+     */
     private updateBoxFromObject;
     /**
      * Remove the specified object from its parent and release geometry and material resource used
@@ -130,5 +196,12 @@ export declare class MText extends THREE.Object3D {
      * @param obj - Input object to dispose
      */
     private disposeThreeObject;
+    /**
+     * Normalizes a font file reference to the lowercase stem used by
+     * {@link FontManager.loadFontsByNames} (strip extension).
+     *
+     * @param fontFileName - Style font path such as `arial.ttf` or extension-less name.
+     * @returns Lowercase name without the last extension segment, or `undefined` if empty.
+     */
     private getFontName;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlightcad/mtext-renderer",
-  "version": "0.10.13",
+  "version": "0.10.14",
   "description": "AutoCAD MText renderer based on Three.js",
   "license": "MIT",
   "author": "MLight Lee <mlight.lee@outlook.com>",