pagyra-js 0.0.1

package/src/layout/utils/content-measurer.ts

@@ -0,0 +1,117 @@
+import { LayoutNode } from "../../dom/node.js";
+import { Display } from "../../css/enums.js";
+import { resolveLength } from "../../css/length.js";
+import { inFlow } from "./node-math.js";
+
+type LayoutDebug = (...args: unknown[]) => void;
+
+/**
+ * Handles measurement and adjustment of intrinsic content width for layout nodes.
+ * 
+ * This class is responsible for:
+ * - Measuring the actual width used by in-flow children
+ * - Calculating offsets for content alignment
+ * - Shifting children horizontally when needed
+ * 
+ * Primarily used for inline-block sizing where the content width
+ * needs to shrink-to-fit based on children's actual space usage.
+ */
+export class ContentMeasurer {
+    constructor(private readonly layoutDebug: LayoutDebug) {}
+    /**
+     * Measures the intrinsic width of in-flow content within a node.
+     * 
+     * Calculates the minimum and maximum horizontal extents of all in-flow
+     * children, taking into account their margins, borders, and padding.
+     * 
+     * @param node - The parent node whose content width to measure
+     * @param referenceWidth - The reference width for percentage calculations
+     * @param contentStartX - The X coordinate where content area begins
+     * @returns Object containing the measured width and any left offset
+     */
+    measureInFlowWidth(
+        node: LayoutNode,
+        referenceWidth: number,
+        contentStartX: number,
+    ): { width: number; leftOffset: number } {
+        let minStart = Number.POSITIVE_INFINITY;
+        let maxEnd = Number.NEGATIVE_INFINITY;
+        let hasContent = false;
+
+        for (const child of node.children) {
+            if (!inFlow(child)) {
+                continue;
+            }
+            if (child.style.display === Display.None) {
+                continue;
+            }
+
+            const marginLeft =
+                child.box.usedMarginLeft !== undefined
+                    ? child.box.usedMarginLeft
+                    : resolveLength(child.style.marginLeft, referenceWidth, { auto: "zero" });
+            const marginRight =
+                child.box.usedMarginRight !== undefined
+                    ? child.box.usedMarginRight
+                    : resolveLength(child.style.marginRight, referenceWidth, { auto: "zero" });
+            const borderLeft = resolveLength(child.style.borderLeft, referenceWidth, { auto: "zero" });
+            const borderRight = resolveLength(child.style.borderRight, referenceWidth, { auto: "zero" });
+            const paddingLeft = resolveLength(child.style.paddingLeft, referenceWidth, { auto: "zero" });
+            const paddingRight = resolveLength(child.style.paddingRight, referenceWidth, { auto: "zero" });
+
+            const borderBoxWidth = child.box.borderBoxWidth || Math.max(0, child.box.contentWidth + paddingLeft + paddingRight + borderLeft + borderRight);
+            const marginBoxWidth = borderBoxWidth + marginLeft + marginRight;
+            const marginStart = child.box.x - paddingLeft - borderLeft - marginLeft;
+            const relativeStart = marginStart - contentStartX;
+            const relativeEnd = relativeStart + marginBoxWidth;
+
+            this.layoutDebug(
+                `[measureInFlowContentWidth] parent=${node.tagName ?? "(anonymous)"} child=${child.tagName ?? "(anonymous)"} marginStart=${marginStart} relativeStart=${relativeStart} marginBoxWidth=${marginBoxWidth} borderBoxWidth=${borderBoxWidth} child.box.x=${child.box.x} contentStartX=${contentStartX}`,
+            );
+
+            minStart = Math.min(minStart, relativeStart);
+            maxEnd = Math.max(maxEnd, relativeEnd);
+            hasContent = true;
+        }
+
+        if (!hasContent) {
+            return { width: 0, leftOffset: 0 };
+        }
+
+        if (!Number.isFinite(minStart)) {
+            minStart = 0;
+        }
+        if (!Number.isFinite(maxEnd)) {
+            maxEnd = minStart;
+        }
+
+        const width = Math.max(0, maxEnd - minStart);
+        const leftOffset = minStart > 0 ? minStart : 0;
+        return { width, leftOffset };
+    }
+
+    /**
+     * Shifts all in-flow children horizontally by the specified amount.
+     * 
+     * This is used to adjust child positions when the parent's content width
+     * changes (e.g., for inline-block shrink-to-fit).
+     * 
+     * @param node - The parent node whose children to shift
+     * @param deltaX - The horizontal offset to apply (negative shifts left)
+     */
+    shiftInFlowChildrenX(node: LayoutNode, deltaX: number): void {
+        if (deltaX === 0) {
+            return;
+        }
+        for (const child of node.children) {
+            if (!inFlow(child)) {
+                continue;
+            }
+            if (child.style.display === Display.None) {
+                continue;
+            }
+            // Shift the child and all its descendants
+            child.shift(-deltaX, 0);
+        }
+    }
+}

package/src/layout/utils/display-utils.ts

@@ -0,0 +1,24 @@
+import { LayoutNode } from "../../dom/node.js";
+import { Display } from "../../css/enums.js";
+
+/**
+ * Determines if a layout node has an inline-level display mode.
+ * 
+ * Inline-level elements participate in inline formatting contexts
+ * and can be laid out on the same line with text and other inline elements.
+ * 
+ * @param node - The layout node to check
+ * @returns true if the node has an inline-level display mode
+ */
+export function isInlineLevel(node: LayoutNode): boolean {
+    switch (node.style.display) {
+        case Display.Inline:
+        case Display.InlineBlock:
+        case Display.InlineFlex:
+        case Display.InlineGrid:
+        case Display.InlineTable:
+            return true;
+        default:
+            return false;
+    }
+}

package/src/layout/utils/floats.ts

@@ -0,0 +1,98 @@
+import { LayoutNode } from "../../dom/node.js";
+import { ClearMode, FloatMode } from "../../css/enums.js";
+import { resolveLength } from "../../css/length.js";
+import { FloatContext } from "../context/float-context.js";
+import type { LayoutContext } from "../pipeline/strategy.js";
+
+interface FloatPlacementOptions {
+  node: LayoutNode;
+  floatContext: FloatContext;
+  context: LayoutContext;
+  contentX: number;
+  contentWidth: number;
+  startY: number;
+}
+
+export function clearForBlock(node: LayoutNode, floatContext: FloatContext, yCursor: number): number {
+  const { clear } = node.style;
+  let y = yCursor;
+  if (clear === ClearMode.Left || clear === ClearMode.Both || clear === ClearMode.InlineStart) {
+    y = Math.max(y, floatContext.bottom("left"));
+  }
+  if (clear === ClearMode.Right || clear === ClearMode.Both || clear === ClearMode.InlineEnd) {
+    y = Math.max(y, floatContext.bottom("right"));
+  }
+  return y;
+}
+
+export function placeFloat(options: FloatPlacementOptions): number {
+  const { node, floatContext, context, contentX, contentWidth } = options;
+
+  context.layoutChild(node);
+
+  const marginLeft = resolveLength(node.style.marginLeft, contentWidth, { auto: "zero" });
+  const marginRight = resolveLength(node.style.marginRight, contentWidth, { auto: "zero" });
+  const marginTop = resolveLength(node.style.marginTop, contentWidth, { auto: "zero" });
+  const marginBottom = resolveLength(node.style.marginBottom, contentWidth, { auto: "zero" });
+
+  const borderLeft = resolveLength(node.style.borderLeft, contentWidth, { auto: "zero" });
+  const borderRight = resolveLength(node.style.borderRight, contentWidth, { auto: "zero" });
+  const borderTop = resolveLength(node.style.borderTop, contentWidth, { auto: "zero" });
+  const borderBottom = resolveLength(node.style.borderBottom, contentWidth, { auto: "zero" });
+
+  const paddingLeft = resolveLength(node.style.paddingLeft, contentWidth, { auto: "zero" });
+  const paddingRight = resolveLength(node.style.paddingRight, contentWidth, { auto: "zero" });
+  const paddingTop = resolveLength(node.style.paddingTop, contentWidth, { auto: "zero" });
+  const paddingBottom = resolveLength(node.style.paddingBottom, contentWidth, { auto: "zero" });
+
+  const borderBoxWidth = node.box.contentWidth + paddingLeft + paddingRight + borderLeft + borderRight;
+  const borderBoxHeight = node.box.contentHeight + paddingTop + paddingBottom + borderTop + borderBottom;
+
+  node.box.borderBoxWidth = borderBoxWidth;
+  node.box.borderBoxHeight = borderBoxHeight;
+  node.box.marginBoxWidth = borderBoxWidth + marginLeft + marginRight;
+  node.box.marginBoxHeight = borderBoxHeight + marginTop + marginBottom;
+
+  const outerWidth = node.box.marginBoxWidth;
+  const outerHeight = node.box.marginBoxHeight;
+
+  let y = options.startY;
+  let attempts = 0;
+  while (true) {
+    if (attempts > 1000) {
+      break;
+    }
+    const offsets = floatContext.inlineOffsets(y, y + outerHeight, contentWidth);
+    const availableWidth = Math.max(0, offsets.end - offsets.start);
+    if (outerWidth <= availableWidth) {
+      const marginBoxStart =
+        node.style.float === FloatMode.Left
+          ? contentX + offsets.start
+          : contentX + offsets.end - outerWidth;
+
+      const contentXPosition = marginBoxStart + marginLeft + borderLeft + paddingLeft;
+      const contentYPosition = y + marginTop + borderTop + paddingTop;
+
+      node.box.x = contentXPosition;
+      node.box.y = contentYPosition;
+      node.box.scrollWidth = node.box.contentWidth;
+      node.box.scrollHeight = node.box.contentHeight;
+
+      floatContext.register(node.style.float === FloatMode.Left ? "left" : "right", {
+        top: y,
+        bottom: y + outerHeight,
+        inlineStart: marginBoxStart - contentX,
+        inlineEnd: marginBoxStart - contentX + outerWidth,
+      });
+      return y + outerHeight;
+    }
+    const nextY = floatContext.nextUnblockedY(y, y + outerHeight);
+    if (nextY === null || nextY <= y) {
+      y += 1;
+    } else {
+      y = nextY;
+    }
+    attempts += 1;
+  }
+  return y + outerHeight;
+}

package/src/layout/utils/gap-calculator.ts

@@ -0,0 +1,167 @@
+/**
+ * Gap calculation utilities for layout strategies.
+ * Provides SOLID gap handling for grid, flex, and other layout modes.
+ * 
+ * This module follows the Single Responsibility Principle by focusing
+ * solely on gap-related calculations, making it reusable across different
+ * layout strategies.
+ */
+
+export interface GapConfig {
+    /** Gap between rows (in pixels) */
+    rowGap: number;
+
+    /** Gap between columns (in pixels) */
+    columnGap: number;
+}
+
+/**
+ * Calculate total gap space for a given number of items in one direction.
+ * 
+ * Formula: gap × (itemCount - 1)
+ * 
+ * @param gap - Gap value in pixels
+ * @param itemCount - Number of items
+ * @returns Total gap space consumed (0 if itemCount <= 1 or gap <= 0)
+ * 
+ * @example
+ * calculateTotalGap(10, 3) // returns 20 (2 gaps between 3 items)
+ * calculateTotalGap(10, 1) // returns 0 (no gaps for single item)
+ */
+export function calculateTotalGap(gap: number, itemCount: number): number {
+    if (itemCount <= 1 || gap <= 0) {
+        return 0;
+    }
+    return gap * (itemCount - 1);
+}
+
+/**
+ * Calculate available space after accounting for gaps.
+ * 
+ * @param totalSpace - Total available space in pixels
+ * @param gap - Gap between items in pixels
+ * @param itemCount - Number of items
+ * @returns Available space for content (clamped to 0 minimum)
+ * 
+ * @example
+ * calculateAvailableSpace(100, 10, 3) // returns 80 (100 - 20 gap)
+ */
+export function calculateAvailableSpace(
+    totalSpace: number,
+    gap: number,
+    itemCount: number
+): number {
+    const totalGap = calculateTotalGap(gap, itemCount);
+    return Math.max(0, totalSpace - totalGap);
+}
+
+/**
+ * Calculate offsets for items with gaps in a single axis.
+ * 
+ * Returns the starting position of each item, accounting for gaps.
+ * 
+ * @param itemSizes - Array of item sizes in pixels
+ * @param gap - Gap between items in pixels
+ * @returns Array of offsets for each item
+ * 
+ * @example
+ * calculateItemOffsets([50, 30, 40], 10)
+ * // returns [0, 60, 100] (item1 at 0, item2 at 50+10, item3 at 50+10+30+10)
+ */
+export function calculateItemOffsets(
+    itemSizes: number[],
+    gap: number
+): number[] {
+    const offsets: number[] = [];
+    let offset = 0;
+
+    for (let i = 0; i < itemSizes.length; i++) {
+        offsets.push(offset);
+        offset += itemSizes[i];
+
+        // Add gap after all items except the last
+        if (i < itemSizes.length - 1) {
+            offset += gap;
+        }
+    }
+
+    return offsets;
+}
+
+/**
+ * Calculate grid track offsets with gaps.
+ * 
+ * This is an alias for calculateItemOffsets with clearer naming for grid context.
+ * 
+ * @param trackSizes - Array of track sizes in pixels
+ * @param gap - Gap between tracks in pixels
+ * @returns Array of offsets for each track
+ */
+export function calculateTrackOffsets(
+    trackSizes: number[],
+    gap: number
+): number[] {
+    return calculateItemOffsets(trackSizes, gap);
+}
+
+/**
+ * Gap calculator service for layout strategies.
+ * 
+ * This class provides a convenient interface for gap calculations
+ * with awareness of layout direction (row vs column).
+ * 
+ * Follows the Dependency Inversion Principle - layout strategies
+ * depend on this abstraction rather than implementing gap logic themselves.
+ */
+export class GapCalculator {
+    constructor(private config: GapConfig) { }
+
+    /**
+     * Get gap for main axis based on direction.
+     * 
+     * @param isRow - True if main axis is horizontal (row), false for vertical (column)
+     * @returns Gap value in pixels
+     */
+    getMainAxisGap(isRow: boolean): number {
+        return isRow ? this.config.columnGap : this.config.rowGap;
+    }
+
+    /**
+     * Get gap for cross axis based on direction.
+     * 
+     * @param isRow - True if main axis is horizontal (row), false for vertical (column)
+     * @returns Gap value in pixels
+     */
+    getCrossAxisGap(isRow: boolean): number {
+        return isRow ? this.config.rowGap : this.config.columnGap;
+    }
+
+    /**
+     * Calculate total gap for main axis.
+     * 
+     * @param isRow - True if main axis is horizontal (row)
+     * @param itemCount - Number of items in main axis
+     * @returns Total gap space consumed in pixels
+     */
+    calculateMainAxisTotalGap(isRow: boolean, itemCount: number): number {
+        const gap = this.getMainAxisGap(isRow);
+        return calculateTotalGap(gap, itemCount);
+    }
+
+    /**
+     * Calculate available space in main axis after gaps.
+     * 
+     * @param isRow - True if main axis is horizontal (row)
+     * @param totalSpace - Total available space in pixels
+     * @param itemCount - Number of items in main axis
+     * @returns Available space for content in pixels
+     */
+    calculateMainAxisAvailableSpace(
+        isRow: boolean,
+        totalSpace: number,
+        itemCount: number
+    ): number {
+        const gap = this.getMainAxisGap(isRow);
+        return calculateAvailableSpace(totalSpace, gap, itemCount);
+    }
+}

package/src/layout/utils/inline-formatter.ts

@@ -0,0 +1,31 @@
+import { FloatContext } from "../context/float-context.js";
+import type { LayoutContext } from "../pipeline/strategy.js";
+import type { LayoutNode } from "../../dom/node.js";
+import { layoutInlineFormattingContext, type InlineLayoutResult } from "./inline-formatting.js";
+
+export interface InlineFormattingRequest {
+  container: LayoutNode;
+  inlineNodes: LayoutNode[];
+  context: LayoutContext;
+  floatContext?: FloatContext;
+  contentX: number;
+  contentWidth: number;
+  startY: number;
+}
+
+export class InlineFormatter {
+  layout(request: InlineFormattingRequest): InlineLayoutResult {
+    const floatContext = request.floatContext ?? new FloatContext();
+    return layoutInlineFormattingContext({
+      container: request.container,
+      inlineNodes: request.inlineNodes,
+      context: request.context,
+      floatContext,
+      contentX: request.contentX,
+      contentWidth: request.contentWidth,
+      startY: request.startY,
+    });
+  }
+}
+
+export const defaultInlineFormatter = new InlineFormatter();

package/src/layout/utils/inline-formatting.ts

@@ -0,0 +1,9 @@
+export {
+  layoutInlineFormattingContext,
+} from "../inline/layout.js";
+
+export type {
+  InlineLayoutOptions,
+  InlineLayoutResult,
+  InlineMetrics,
+} from "../inline/types.js";

package/src/layout/utils/margin.ts

@@ -0,0 +1,140 @@
+import { LayoutNode } from "../../dom/node.js";
+import { Display } from "../../css/enums.js";
+import { resolveLength } from "../../css/length.js";
+import { establishesBFC, inFlow, resolveWidthBlock } from "./node-math.js";
+
+const EPSILON = 1e-7;
+
+function isApproximatelyZero(value: number): boolean {
+  return Math.abs(value) < EPSILON;
+}
+
+function isBlockLevel(node: LayoutNode): boolean {
+  switch (node.style.display) {
+    case Display.Block:
+    case Display.ListItem:
+      return true;
+    default:
+      return false;
+  }
+}
+
+function isMarginCollapsibleChild(node: LayoutNode): boolean {
+  return node.style.display !== Display.None && inFlow(node) && isBlockLevel(node) && !establishesBFC(node);
+}
+
+export function collapseMarginSet(margins: readonly number[]): number {
+  const positives: number[] = [];
+  const negatives: number[] = [];
+  for (const margin of margins) {
+    if (margin > 0) {
+      positives.push(margin);
+    } else if (margin < 0) {
+      negatives.push(margin);
+    }
+  }
+
+  if (negatives.length === 0) {
+    return positives.length > 0 ? Math.max(...positives) : 0;
+  }
+  if (positives.length === 0) {
+    return Math.min(...negatives);
+  }
+  return Math.max(...positives) + Math.min(...negatives);
+}
+
+export function collapsedGapBetween(
+  prevBottomMargin: number,
+  nextTopMargin: number,
+  parentEstablishesBfc: boolean,
+): number {
+  if (parentEstablishesBfc) {
+    return prevBottomMargin + nextTopMargin;
+  }
+  return collapseMarginSet([prevBottomMargin, nextTopMargin]);
+}
+
+export function findFirstMarginCollapsibleChild(node: LayoutNode): LayoutNode | undefined {
+  for (const child of node.children) {
+    if (!inFlow(child) || child.style.display === Display.None) {
+      continue;
+    }
+    if (isMarginCollapsibleChild(child)) {
+      return child;
+    }
+    break;
+  }
+  return undefined;
+}
+
+export function findLastMarginCollapsibleChild(node: LayoutNode): LayoutNode | undefined {
+  for (let i = node.children.length - 1; i >= 0; i -= 1) {
+    const child = node.children[i];
+    if (!inFlow(child) || child.style.display === Display.None) {
+      continue;
+    }
+    if (isMarginCollapsibleChild(child)) {
+      return child;
+    }
+    break;
+  }
+  return undefined;
+}
+
+export function canCollapseMarginStart(node: LayoutNode, containingBlockWidth: number): boolean {
+  if (!isBlockLevel(node) || establishesBFC(node)) {
+    return false;
+  }
+  const paddingTop = resolveLength(node.style.paddingTop, containingBlockWidth, { auto: "zero" });
+  const borderTop = resolveLength(node.style.borderTop, containingBlockWidth, { auto: "zero" });
+  if (!isApproximatelyZero(paddingTop) || !isApproximatelyZero(borderTop)) {
+    return false;
+  }
+  return findFirstMarginCollapsibleChild(node) !== undefined;
+}
+
+export function canCollapseMarginEnd(node: LayoutNode, containingBlockWidth: number): boolean {
+  if (!isBlockLevel(node) || establishesBFC(node)) {
+    return false;
+  }
+  const paddingBottom = resolveLength(node.style.paddingBottom, containingBlockWidth, { auto: "zero" });
+  const borderBottom = resolveLength(node.style.borderBottom, containingBlockWidth, { auto: "zero" });
+  if (!isApproximatelyZero(paddingBottom) || !isApproximatelyZero(borderBottom)) {
+    return false;
+  }
+  return findLastMarginCollapsibleChild(node) !== undefined;
+}
+
+export function effectiveMarginTop(node: LayoutNode, containingBlockWidth: number): number {
+  const ownMargin = resolveLength(node.style.marginTop, containingBlockWidth, { auto: "zero" });
+  if (!isBlockLevel(node)) {
+    return ownMargin;
+  }
+  if (!canCollapseMarginStart(node, containingBlockWidth)) {
+    return ownMargin;
+  }
+  const firstChild = findFirstMarginCollapsibleChild(node);
+  if (!firstChild) {
+    return ownMargin;
+  }
+  const childContainingWidth = resolveWidthBlock(node, containingBlockWidth);
+  const childMargin = effectiveMarginTop(firstChild, childContainingWidth);
+  return collapseMarginSet([ownMargin, childMargin]);
+}
+
+export function effectiveMarginBottom(node: LayoutNode, containingBlockWidth: number): number {
+  const ownMargin = resolveLength(node.style.marginBottom, containingBlockWidth, { auto: "zero" });
+  if (!isBlockLevel(node)) {
+    return ownMargin;
+  }
+  if (!canCollapseMarginEnd(node, containingBlockWidth)) {
+    return ownMargin;
+  }
+  const lastChild = findLastMarginCollapsibleChild(node);
+  if (!lastChild) {
+    return ownMargin;
+  }
+  const childContainingWidth = resolveWidthBlock(node, containingBlockWidth);
+  const childMargin = effectiveMarginBottom(lastChild, childContainingWidth);
+  return collapseMarginSet([ownMargin, childMargin]);
+}