refactor: centralizing anchored graphic placement

packages/layout-engine/contracts/src/graphic-placement.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest';
+import { resolveAnchoredGraphicY, resolveAnchoredGraphicX } from './graphic-placement.js';
+
+const yBase = {
+  objectHeight: 100,
+  contentTop: 72,
+  contentBottom: 720,
+  pageBottomMargin: 72,
+};
+
+const columns = { width: 200, gap: 20, count: 2 };
+const margins = { left: 72, right: 72 };
+const pageWidth = 600;
+const objectWidth = 80;
+
+describe('resolveAnchoredGraphicY', () => {
+  it('positions margin-relative top with offset', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...yBase,
+        anchor: { vRelativeFrom: 'margin', alignV: 'top', offsetV: 10 },
+      }),
+    ).toBe(82);
+  });
+
+  it('positions page-relative bottom with page margin', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...yBase,
+        anchor: { vRelativeFrom: 'page', alignV: 'bottom', offsetV: 5 },
+      }),
+    ).toBe(720 + 72 - 100 + 5);
+  });
+
+  it('positions paragraph-relative center on first line', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...yBase,
+        anchor: { vRelativeFrom: 'paragraph', alignV: 'center', offsetV: 0 },
+        anchorParagraphY: 200,
+        firstLineHeight: 24,
+      }),
+    ).toBe(200 + (24 - 100) / 2);
+  });
+
+  it('uses pre-registered fallback when vRelativeFrom is paragraph without paragraph context', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...yBase,
+        anchor: { vRelativeFrom: 'paragraph', offsetV: 20 },
+        preRegisteredFallbackToContentTop: true,
+      }),
+    ).toBe(92);
+  });
+
+  it('ignores paragraph alignV when pre-registered fallback has no paragraph context', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...yBase,
+        anchor: { vRelativeFrom: 'paragraph', alignV: 'center', offsetV: 0 },
+        preRegisteredFallbackToContentTop: true,
+      }),
+    ).toBe(72);
+    expect(
+      resolveAnchoredGraphicY({
+        ...yBase,
+        objectHeight: 50,
+        anchor: { vRelativeFrom: 'paragraph', alignV: 'bottom', offsetV: 10 },
+        preRegisteredFallbackToContentTop: true,
+      }),
+    ).toBe(82);
+  });
+
+  it('legacy undefined vRelativeFrom uses anchor paragraph Y plus offsetV', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...yBase,
+        anchor: { offsetV: 15 },
+        anchorParagraphY: 300,
+      }),
+    ).toBe(315);
+  });
+
+  it('legacy undefined vRelativeFrom with preRegisteredFallbackToContentTop uses contentTop', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...yBase,
+        anchor: { alignV: 'center', offsetV: 20 },
+        anchorParagraphY: 300,
+        preRegisteredFallbackToContentTop: true,
+      }),
+    ).toBe(92);
+  });
+
+  it('legacy undefined vRelativeFrom does not use paragraph alignV without vRelativeFrom paragraph', () => {
+    expect(
+      resolveAnchoredGraphicY({
+        ...yBase,
+        anchor: { alignV: 'bottom', offsetV: 0 },
+        anchorParagraphY: 200,
+        firstLineHeight: 24,
+      }),
+    ).toBe(200);
+  });
+});
+
+describe('resolveAnchoredGraphicX', () => {
+  const columnIndex = 1;
+  const columnLeft = margins.left + columnIndex * (columns.width + columns.gap);
+
+  describe('column-relative (default)', () => {
+    it.each([
+      { alignH: 'left' as const, offsetH: 10, expected: columnLeft + 10 },
+      { alignH: 'center' as const, offsetH: 5, expected: columnLeft + (columns.width - objectWidth) / 2 + 5 },
+      { alignH: 'right' as const, offsetH: 3, expected: columnLeft + columns.width - objectWidth - 3 },
+    ])('alignH=$alignH offsetH=$offsetH', ({ alignH, offsetH, expected }) => {
+      expect(resolveAnchoredGraphicX({ alignH, offsetH }, columnIndex, columns, objectWidth, margins, pageWidth)).toBe(
+        expected,
+      );
+    });
+  });
+
+  describe('margin-relative', () => {
+    const baseX = margins.left;
+    const availableWidth = pageWidth - margins.left - margins.right;
+
+    it.each([
+      { alignH: 'left' as const, offsetH: 10, expected: baseX + 10 },
+      { alignH: 'center' as const, offsetH: 5, expected: baseX + (availableWidth - objectWidth) / 2 + 5 },
+      { alignH: 'right' as const, offsetH: 3, expected: baseX + availableWidth - objectWidth - 3 },
+    ])('alignH=$alignH offsetH=$offsetH', ({ alignH, offsetH, expected }) => {
+      expect(
+        resolveAnchoredGraphicX(
+          { hRelativeFrom: 'margin', alignH, offsetH },
+          columnIndex,
+          columns,
+          objectWidth,
+          margins,
+          pageWidth,
+        ),
+      ).toBe(expected);
+    });
+  });
+
+  describe('page-relative', () => {
+    const baseX = 0;
+    const availableWidth = pageWidth;
+
+    it.each([
+      { alignH: 'left' as const, offsetH: 10, expected: baseX + 10 },
+      { alignH: 'center' as const, offsetH: 5, expected: baseX + (availableWidth - objectWidth) / 2 + 5 },
+      { alignH: 'right' as const, offsetH: 3, expected: baseX + availableWidth - objectWidth - 3 },
+    ])('alignH=$alignH offsetH=$offsetH', ({ alignH, offsetH, expected }) => {
+      expect(
+        resolveAnchoredGraphicX(
+          { hRelativeFrom: 'page', alignH, offsetH },
+          columnIndex,
+          columns,
+          objectWidth,
+          margins,
+          pageWidth,
+        ),
+      ).toBe(expected);
+    });
+  });
+
+  it('defaults alignH to left and offsetH to zero', () => {
+    expect(resolveAnchoredGraphicX({}, 0, columns, objectWidth, margins, pageWidth)).toBe(margins.left);
+  });
+});

packages/layout-engine/contracts/src/graphic-placement.ts

@@ -0,0 +1,155 @@
+type AnchorVRelative = 'paragraph' | 'page' | 'margin';
+type AnchorHRelative = 'column' | 'page' | 'margin';
+type AnchorAlignH = 'left' | 'center' | 'right';
+type AnchorAlignV = 'top' | 'center' | 'bottom';
+
+export type ColumnLayoutForAnchor = {
+  width: number;
+  gap: number;
+  count: number;
+};
+
+/**
+ * Inputs for resolving the paint Y of an anchored image, drawing, or floating table.
+ * `offsetV` is applied inside this function; callers must pass the resolved value to
+ * text-wrap registration without adding `offsetV` again.
+ */
+export type ResolveAnchoredGraphicYInput = {
+  anchor?: {
+    vRelativeFrom?: AnchorVRelative;
+    alignV?: AnchorAlignV;
+    offsetV?: number;
+  };
+  objectHeight: number;
+  contentTop: number;
+  contentBottom: number;
+  /** Bottom page margin in px (used when vRelativeFrom is `page`). */
+  pageBottomMargin?: number;
+  /**
+   * Anchor paragraph top Y (body cursor when laying out the anchor paragraph).
+   * Used for `paragraph` and legacy (undefined vRelativeFrom) positioning.
+   */
+  anchorParagraphY?: number;
+  /** First line height of the anchor paragraph (paragraph-relative alignV). */
+  firstLineHeight?: number;
+  /**
+   * When true, anchor has no host paragraph (pre-registered / paragraphless layout).
+   * For `vRelativeFrom: 'paragraph'`, use `contentTop + offsetV` instead of alignV on a
+   * synthetic paragraph (defaults would wrongly center/bottom against contentTop).
+   */
+  preRegisteredFallbackToContentTop?: boolean;
+};
+
+/**
+ * Resolve the vertical paint position for an anchored graphic (image, drawing, or table).
+ */
+export function resolveAnchoredGraphicY(input: ResolveAnchoredGraphicYInput): number {
+  const {
+    anchor,
+    objectHeight,
+    contentTop,
+    contentBottom,
+    pageBottomMargin = 0,
+    anchorParagraphY = contentTop,
+    firstLineHeight = 0,
+    preRegisteredFallbackToContentTop = false,
+  } = input;
+
+  const offsetV = anchor?.offsetV ?? 0;
+  const vRelativeFrom = anchor?.vRelativeFrom;
+  const alignV = anchor?.alignV;
+  const contentHeight = Math.max(0, contentBottom - contentTop);
+
+  if (vRelativeFrom === 'margin') {
+    if (alignV === 'bottom') {
+      return contentBottom - objectHeight + offsetV;
+    }
+    if (alignV === 'center') {
+      return contentTop + (contentHeight - objectHeight) / 2 + offsetV;
+    }
+    return contentTop + offsetV;
+  }
+
+  if (vRelativeFrom === 'page') {
+    const pageHeight = contentBottom + pageBottomMargin;
+    if (alignV === 'bottom') {
+      return pageHeight - objectHeight + offsetV;
+    }
+    if (alignV === 'center') {
+      return (pageHeight - objectHeight) / 2 + offsetV;
+    }
+    return offsetV;
+  }
+
+  if (vRelativeFrom === 'paragraph') {
+    if (preRegisteredFallbackToContentTop) {
+      return contentTop + offsetV;
+    }
+    const baseAnchorY = anchorParagraphY;
+    if (alignV === 'bottom') {
+      return baseAnchorY + firstLineHeight - objectHeight + offsetV;
+    }
+    if (alignV === 'center') {
+      return baseAnchorY + (firstLineHeight - objectHeight) / 2 + offsetV;
+    }
+    return baseAnchorY + offsetV;
+  }
+
+  if (preRegisteredFallbackToContentTop) {
+    return contentTop + offsetV;
+  }
+
+  return anchorParagraphY + offsetV;
+}
+
+/**
+ * Resolve horizontal paint position for an anchored graphic.
+ */
+export function resolveAnchoredGraphicX(
+  anchor: {
+    hRelativeFrom?: AnchorHRelative;
+    alignH?: AnchorAlignH;
+    offsetH?: number;
+  },
+  columnIndex: number,
+  columns: ColumnLayoutForAnchor,
+  objectWidth: number,
+  margins?: { left?: number; right?: number },
+  pageWidth?: number,
+): number {
+  const alignH = anchor.alignH ?? 'left';
+  const offsetH = anchor.offsetH ?? 0;
+
+  const marginLeft = Math.max(0, margins?.left ?? 0);
+  const marginRight = Math.max(0, margins?.right ?? 0);
+  const contentWidth = pageWidth != null ? Math.max(1, pageWidth - (marginLeft + marginRight)) : columns.width;
+
+  const contentLeft = marginLeft;
+  const columnLeft = contentLeft + columnIndex * (columns.width + columns.gap);
+
+  const relativeFrom = anchor.hRelativeFrom ?? 'column';
+
+  let baseX: number;
+  let availableWidth: number;
+  if (relativeFrom === 'page') {
+    baseX = 0;
+    availableWidth = pageWidth != null ? pageWidth : contentWidth + marginLeft + marginRight;
+  } else if (relativeFrom === 'margin') {
+    baseX = contentLeft;
+    availableWidth = contentWidth;
+  } else {
+    baseX = columnLeft;
+    availableWidth = columns.width;
+  }
+
+  if (alignH === 'left') {
+    return baseX + offsetH;
+  }
+  if (alignH === 'right') {
+    return baseX + availableWidth - objectWidth - offsetH;
+  }
+  if (alignH === 'center') {
+    return baseX + (availableWidth - objectWidth) / 2 + offsetH;
+  }
+  return baseX;
+}

packages/layout-engine/contracts/src/index.ts

@@ -92,6 +92,13 @@ export {
 
 export { computeFragmentPmRange, computeLinePmRange, type LinePmRange } from './pm-range.js';
 
+export {
+  resolveAnchoredGraphicY,
+  resolveAnchoredGraphicX,
+  type ColumnLayoutForAnchor,
+  type ResolveAnchoredGraphicYInput,
+} from './graphic-placement.js';
+
 // Editor-neutral layout identity primitives (prep-001).
 // Additive only — `pmStart`/`pmEnd` and PM-shaped fields remain available
 // alongside these on every fragment/run.