@vyaz/core 0.0.4 → 0.0.5

package/src/layout/PositioningEngine.ts

@@ -16,10 +16,13 @@
  *   without mutating ClusterData.advance)
  */
 
-import type { ParagraphStyle } from '../types/Document.js';
+import type { ParagraphStyle, ListStyle, NumberFormat } from '../types/Document.js';
 import type { FontMetrics } from '../types/FontTypes.js';
 import type { Line, Span, SpanFontMetrics } from '../types/LayoutTypes.js';
 import type { PreparedRichInlineItem } from '../compile/DocumentCompiler.js';
+import type { MeasureFn } from './estimateWidth.js';
+import { resolveFragmentWidths } from './estimateWidth.js';
+import { formatListNumber, defaultBulletChar } from '../utils/list.js';
 
 // ── Helper types for pretext ───────────────────────────────────────────
 
@@ -38,6 +41,48 @@ interface PretextLine {
   end: { segmentIndex: number; graphemeIndex: number };
 }
 
+// ── List marker helpers ─────────────────────────────────────────────────
+
+/**
+ * Resolve the marker text for a list item.
+ */
+function getMarkerText(listStyle: ListStyle, listIndex: number): string {
+  if (listStyle.type === 'bullet') {
+    return listStyle.bulletChar ?? defaultBulletChar(listStyle.level ?? 0);
+  }
+  if (listStyle.type === 'number') {
+    const fmt = listStyle.numberFormat ?? 'decimal';
+    return formatListNumber(listIndex, fmt) + '.';
+  }
+  return '';
+}
+
+/**
+ * Resolve the paragraph-level font size for marker sizing.
+ * Uses the first child run's fontSize, or DEFAULT_TEXT_STYLE.fontSize.
+ */
+function getParagraphFontSize(items: PreparedRichInlineItem[]): number {
+  if (items.length === 0) return 12;
+  return items[0].metadata.style.fontSize ?? 12;
+}
+
+/**
+ * Resolve the effective bulletIndent for a paragraph.
+ * Uses listStyle.indents[level] if available, otherwise default * (level + 1).
+ */
+function resolveBulletIndent(
+  listStyle: ListStyle,
+  paraFontSize: number,
+): number {
+  const level = listStyle.level ?? 0;
+  const indents = listStyle.indents;
+  if (indents && indents[level] !== undefined) {
+    return indents[level];
+  }
+  const defaultIndent = listStyle.bulletIndent ?? (paraFontSize * 1.5);
+  return defaultIndent * (level + 1);
+}
+
 // ── PositioningEngine ─────────────────────────────────────────────────
 
 /**
@@ -50,6 +95,14 @@ interface PretextLine {
  * @param maxWidth — available container width
  * @param startY — initial Y position
  * @param mode — metric mode ('browser' | 'office'), affects line height calculation
+ * @param tag — optional tag for debugging
+ * @param measureText — function to measure text width accurately via fontkit.
+ *   The function accepts (text, fontSize, fontFamily, fontWeight, fontStyle)
+ *   and returns width in px. Throws FontNotFoundError if font not registered.
+ * @param listStyle — optional list configuration (bullet / numbered)
+ * @param listIndex — current index in the list (for numbered lists). 1-based.
+ * @param listMarkerWidth — pre-computed width of the widest marker in the list group.
+ *   When provided, bulletIndent is expanded to this value if needed.
  * @returns { lines: Line[], contentWidth: number }
  */
 export function positionLines(
@@ -60,7 +113,11 @@ export function positionLines(
   maxWidth: number,
   startY: number = 0,
   mode: 'browser' | 'office' = 'browser',
-  paragraphId?: string,
+  measureText: (text: string, fontSize: number, fontFamily?: string, fontWeight?: string, fontStyle?: string) => number,
+  tag?: string,
+  listStyle?: ListStyle,
+  listIndex?: number,
+  listMarkerWidth?: number,
 ): { lines: Line[]; contentWidth: number } {
   const lines: Line[] = [];
   let currentY = startY + style.spaceBefore;
@@ -68,6 +125,41 @@ export function positionLines(
   let isFirstLine = true;
   let contentWidth = 0;
 
+  // ── Pre-compute marker-related values ──────────────────────────
+  const isListItem = listStyle && listStyle.type !== 'none' && listIndex !== undefined;
+  let markerText = '';
+  let markerWidth = 0;
+  let bulletZoneIndent = 0;
+  let effectiveLeftIndent = style.leftIndent ?? 0;
+
+  if (isListItem) {
+    markerText = getMarkerText(listStyle!, listIndex!);
+    const paraFontSize = getParagraphFontSize(items);
+    bulletZoneIndent = resolveBulletIndent(listStyle!, paraFontSize);
+
+    // Expand bulletIndent to fit the widest marker in the list group
+    if (listMarkerWidth !== undefined && listMarkerWidth > bulletZoneIndent) {
+      bulletZoneIndent = listMarkerWidth;
+    }
+
+    // Measure marker width using paragraph's first run font
+    const firstRunFontFamily = items[0]?.metadata.style.fontFamily ?? 'Arial';
+    const firstRunFontWeight = String(items[0]?.metadata.style.fontWeight ?? 400);
+    const firstRunFontStyle = items[0]?.metadata.style.fontStyle ?? 'normal';
+
+    // Marker font-size: same as paragraph font size for numbered,
+    // slightly smaller (0.9x) for bullets (PowerPoint convention)
+    const markerFontSize = listStyle!.type === 'bullet'
+      ? paraFontSize * 0.9
+      : paraFontSize;
+    markerWidth = measureText(markerText, markerFontSize, firstRunFontFamily, firstRunFontWeight, firstRunFontStyle);
+
+    // For 'outside': text block is shifted right by bulletZoneIndent
+    if (listStyle!.position !== 'inside') {
+      effectiveLeftIndent += bulletZoneIndent;
+    }
+  }
+
   for (let lineIdx = 0; lineIdx < pretextLines.length; lineIdx++) {
     const ptLine = pretextLines[lineIdx];
 
@@ -82,8 +174,12 @@ export function positionLines(
       if (!item) continue;
 
       const metrics = fontMetricsFn(item);
-      const effectiveAscent = metrics.ascent + (item.metadata.baselineOffset || 0);
-      const effectiveDescent = metrics.descent - (item.metadata.baselineOffset || 0);
+      // baselineOffset: superscript → negative (glyph moves up).
+      // ascent must increase (glyph above baseline), descent must decrease (less overhang below).
+      // subscript → positive (glyph moves down).
+      // ascent must decrease, descent must increase.
+      const effectiveAscent = metrics.ascent - (item.metadata.baselineOffset || 0);
+      const effectiveDescent = metrics.descent + (item.metadata.baselineOffset || 0);
 
       maxAscent = Math.max(maxAscent, effectiveAscent);
       maxDescent = Math.max(maxDescent, effectiveDescent);
@@ -109,7 +205,8 @@ export function positionLines(
           width: gapWidth,
           text: ' ',
           itemIndex: frag.itemIndex,
-          paragraphId,
+          pIdx: 0,
+          tag,
           fontMetrics: baseFontMetrics,
           style: item.metadata.style,
           inlineWidget: item.metadata.inlineWidget,
@@ -122,7 +219,6 @@ export function positionLines(
       const text = frag.text;
       const leadingMatch = text.match(/^(\s+)/);
 
-      const totalChars = text.length;
       let remainingText = text;
       let leadingSpaceChars = 0;
       let trailingSpaceChars = 0;
@@ -139,18 +235,37 @@ export function positionLines(
         }
       }
 
-      const computePartialWidth = (charCount: number) => {
-        return totalChars > 0 ? (charCount / totalChars) * textWidth : 0;
-      };
+      // Resolve widths via resolveFragmentWidths:
+      //   exact measurement (measureText) when available,
+      //   weight-based fallback otherwise,
+      //   then correctToSumInvariant to preserve line-breaking invariant.
+      const fragments: string[] = [];
+      if (leadingSpaceChars > 0) fragments.push(text.slice(0, leadingSpaceChars));
+      if (remainingText.length > 0) fragments.push(remainingText);
+      if (trailingSpaceChars > 0) fragments.push(text.slice(leadingSpaceChars + remainingText.length));
+
+      // Build measure function with font parameters baked in
+      const { fontFamily, fontWeight, fontStyle } = item.metadata.style;
+      const fsWeight = String(fontWeight || 400);
+      const fsStyle = fontStyle || 'normal';
+      const fragmentMeasureFn: MeasureFn = (t: string) => measureText(t, baseFontMetrics.fontSize, fontFamily, fsWeight, fsStyle);
+
+      const resolvedWidths = resolveFragmentWidths(fragments, text, textWidth, fragmentMeasureFn);
+      let resolvedIdx = 0;
+      const leadingWidth = leadingSpaceChars > 0 ? resolvedWidths[resolvedIdx++] : 0;
+      const trimmedWidth = remainingText.length > 0 ? resolvedWidths[resolvedIdx++] : 0;
+      const trailingWidthVal = trailingSpaceChars > 0 ? resolvedWidths[resolvedIdx++] : 0;
 
       // Leading space span
       if (leadingSpaceChars > 0) {
+        const leadingText = text.slice(0, leadingSpaceChars);
         spans.push({
           x: 0,
-          width: computePartialWidth(leadingSpaceChars),
-          text: text.slice(0, leadingSpaceChars),
+          width: leadingWidth,
+          text: leadingText,
           itemIndex: frag.itemIndex,
-          paragraphId,
+          pIdx: 0,
+          tag,
           fontMetrics: baseFontMetrics,
           style: item.metadata.style,
           inlineWidget: item.metadata.inlineWidget,
@@ -160,40 +275,32 @@ export function positionLines(
 
       // Text span (trimmed)
       if (remainingText.length > 0) {
-        const textWidth = computePartialWidth(remainingText.length);
-        // Compute per-glyph advances by distributing textWidth equally across glyphs.
-        // For monospace fonts this is exact; for proportional it's a linear approximation.
-        // The FontMetricsProvider can later supply real glyph advances when available.
-        const glyphAdvances: number[] = [];
-        if (remainingText.length > 1) {
-          const perGlyph = textWidth / remainingText.length;
-          for (let i = 0; i < remainingText.length; i++) {
-            glyphAdvances.push(perGlyph);
-          }
-        }
+        const actualTextWidth = trimmedWidth;
         spans.push({
           x: 0,
-          width: textWidth,
+          width: actualTextWidth,
           text: remainingText,
           itemIndex: frag.itemIndex,
-          paragraphId,
+          pIdx: 0,
+          tag,
           fontMetrics: baseFontMetrics,
           style: item.metadata.style,
           inlineWidget: item.metadata.inlineWidget,
           type: 'text',
-          glyphAdvances: glyphAdvances.length > 0 ? glyphAdvances : undefined,
         });
       }
 
       // Trailing space span
       if (trailingSpaceChars > 0) {
         const trailingStart = leadingSpaceChars + remainingText.length;
+        const trailingText = text.slice(trailingStart, trailingStart + trailingSpaceChars);
         spans.push({
           x: 0,
-          width: computePartialWidth(trailingSpaceChars),
-          text: text.slice(trailingStart, trailingStart + trailingSpaceChars),
+          width: trailingWidthVal,
+          text: trailingText,
           itemIndex: frag.itemIndex,
-          paragraphId,
+          pIdx: 0,
+          tag,
           fontMetrics: baseFontMetrics,
           style: item.metadata.style,
           inlineWidget: item.metadata.inlineWidget,
@@ -211,6 +318,80 @@ export function positionLines(
       }
     }
 
+    // ── Prepare marker data (only on first line) ──────────────────
+    // For 'inside': marker is inserted into the span flow before X positioning.
+    // For 'outside': marker is added after X positioning with a custom x in the bullet zone.
+    let outsideMarkerSpan: Span | null = null;
+
+    if (isListItem && isFirstLine) {
+      const paraFontSize = getParagraphFontSize(items);
+      const firstRun = items[0];
+      const markerFontSize = listStyle!.type === 'bullet' ? paraFontSize * 0.9 : paraFontSize;
+      const markerAscent = markerFontSize * 0.8; // approximate ascent for marker
+      const markerDescent = markerFontSize * 0.2;
+
+      maxAscent = Math.max(maxAscent, markerAscent);
+      maxDescent = Math.max(maxDescent, markerDescent);
+      maxLineHeightBase = Math.max(maxLineHeightBase, markerAscent + markerDescent);
+
+      // Create a style object for the marker span
+      const markerStyle = {
+        ...(firstRun?.metadata.style ?? {
+          fontFamily: 'Arial',
+          fontSize: markerFontSize,
+          fontWeight: 400,
+          fontStyle: 'normal' as const,
+          color: '#000000',
+          type: 'text' as const,
+          text: markerText,
+        }),
+        fontSize: markerFontSize,
+        text: markerText,
+      };
+
+      const markerSpanBase: Span = {
+        x: 0,
+        width: markerWidth,
+        text: markerText,
+        itemIndex: 0,
+        pIdx: 0,
+        tag,
+        fontMetrics: {
+          ascent: markerAscent,
+          descent: markerDescent,
+          fontSize: markerFontSize,
+        },
+        style: markerStyle,
+        type: 'marker',
+      };
+
+      // For 'inside': marker is part of text flow — insert at beginning of spans
+      // For 'outside': store for later (after X positioning)
+      if (listStyle!.position === 'inside') {
+        spans.unshift(markerSpanBase);
+        // Add a small gap after the marker (0.5em)
+        const gapWidth = markerFontSize * 0.5;
+        spans.splice(1, 0, {
+          x: 0,
+          width: gapWidth,
+          text: ' ',
+          itemIndex: 0,
+          pIdx: 0,
+          tag,
+          fontMetrics: {
+            ascent: 0,
+            descent: 0,
+            fontSize: markerFontSize,
+          },
+          style: markerStyle,
+          type: 'space',
+        });
+      } else {
+        // 'outside' (default): marker sits in the bullet zone, left of text
+        outsideMarkerSpan = markerSpanBase;
+      }
+    }
+
     // ── Mark trailing whitespace spans ───────────────────
     // CSS Text §4.1.3: end-of-line spaces have zero measure for line-advance calculations.
     // Parley: LineItemData.has_trailing_whitespace → trailing whitespace is excluded from advance.
@@ -242,8 +423,8 @@ export function positionLines(
 
     // ── X positioning ───────────────────────────────
     const indent = isFirstLine
-      ? (style.leftIndent || 0) + (style.indent || 0)
-      : (style.leftIndent || 0);
+      ? effectiveLeftIndent + (style.indent || 0)
+      : effectiveLeftIndent;
     const rightIndent = style.rightIndent || 0;
     const availableWidth = maxWidth - indent - rightIndent;
 
@@ -293,8 +474,37 @@ export function positionLines(
       runX += frag.width;
     }
 
-    const lineWidth = runX - xOffset;
-    contentWidth = Math.max(contentWidth, lineWidth);
+    // ── Outside marker: place in the bullet zone (left of text) ──
+    // Marker is right-aligned within the bullet zone so multi-digit
+    // numbers ("9." vs "10.") share the same right edge.
+    // CSS list-style-position: outside — marker is outside the principal box.
+    // OOXML a:buFont / a:buChar — bullet sits in the indent zone.
+    if (outsideMarkerSpan) {
+      // Right edge of the bullet zone = xOffset (start of text)
+      // Marker right-aligned: x = xOffset - markerWidth - small gap
+      const gap = outsideMarkerSpan.fontMetrics.fontSize * 0.25; // 0.25em gap
+      outsideMarkerSpan.x = Math.round((xOffset - outsideMarkerSpan.width - gap) * 100) / 100;
+      // Prepend so it appears first in the spans array
+      spans.unshift(outsideMarkerSpan);
+    }
+
+    // Line box must cover ALL spans, including outside markers that sit
+    // left of the principal text box. Otherwise contentWidth / computeBBox
+    // miss the marker and content sizing clips it.
+    let lineX = xOffset;
+    let lineWidth = runX - xOffset;
+    if (spans.length > 0) {
+      const minSpanX = Math.min(...spans.map(s => s.x));
+      const maxSpanRight = Math.max(...spans.map(s => s.x + s.width));
+      lineX = minSpanX;
+      lineWidth = maxSpanRight - minSpanX;
+    }
+    // contentWidth is the absolute right edge of content (not just line.width).
+    // When line.x > 0 (outside marker, indent, center/right), consumers that
+    // size the canvas as contentWidth with viewBox origin 0 need this value.
+    contentWidth = Math.max(contentWidth, lineX + lineWidth);
+
+
 
     // ── Y positioning ───────────────────────────────
     // Line height algorithm depends on mode:
@@ -356,7 +566,10 @@ export function positionLines(
     // Count characters in line (for INDEX_CONSIST)
     let lineCharCount = 0;
     for (const frag of spans) {
-      lineCharCount += frag.text.length;
+      // Marker spans don't count toward the paragraph's character index
+      if (frag.type !== 'marker') {
+        lineCharCount += frag.text.length;
+      }
     }
     const endIdx = startIdx + lineCharCount;
     charIndex = endIdx;
@@ -377,7 +590,7 @@ export function positionLines(
     }
 
     lines.push({
-      x: Math.round(xOffset * 100) / 100,
+      x: Math.round(lineX * 100) / 100,
       y: Math.round(currentY * 100) / 100,
       width: Math.round(lineWidth * 100) / 100,
       height: Math.round(lineBoxHeight * 100) / 100,
@@ -390,6 +603,7 @@ export function positionLines(
       spans,
     });
 
+
     currentY += lineBoxHeight;
     isFirstLine = false;
   }