@nowline/layout 0.2.0

package/src/nodes/item-node.ts

@@ -0,0 +1,171 @@
+// ItemNode — first Renderable entity in the m2.5c port. Owns the
+// geometry of a single item bar: its visual box (insets + height) and
+// its caption x (inside vs. spilled past the bar).
+//
+// Constructed from already-resolved inputs (start/end x, status,
+// remaining, meta text) so this node stays small and pure. The
+// dependency-resolution logic in layout.ts (after/before chains,
+// cursor.x, footnote indexing) remains where it is for now; m2.5c's
+// remaining work is to migrate the rest into sibling node files.
+//
+// `measure(ctx)` returns the bar's intrinsic size. `place(origin,
+// ctx)` returns a `PositionedItem`-shaped fragment with the box, row,
+// and `textX`. The shape is byte-stable with the legacy sequenceItem
+// arithmetic when fed the same inputs.
+
+import { ITEM_LINK_ICON_INSET_PX, ITEM_LINK_ICON_TILE_SIZE_PX } from '../item-bar-geometry.js';
+import type {
+    IntrinsicSize,
+    MeasureContext,
+    PlaceContext,
+    Point,
+    Renderable,
+} from '../renderable.js';
+import { ITEM_INSET_PX, MIN_ITEM_WIDTH } from '../themes/shared.js';
+import type { BoundingBox } from '../types.js';
+
+/**
+ * Inner padding applied on each side of the title text — the bar's
+ * inner-padded text area is `box.width - 2 * TEXT_INSET_PX` wide.
+ * Text spills past the bar when either the title or the meta line
+ * exceeds that area.
+ */
+const TEXT_INSET_PX = 12;
+
+/**
+ * Gap (px) between the bar's right edge and overflow text. Smaller
+ * than `TEXT_INSET_PX` so the text reads as belonging to this bar —
+ * adjacent bars are at least `2 * ITEM_INSET_PX = 12` away, so the
+ * text still has a clear visual home.
+ */
+const TEXT_OUTSIDE_GAP_PX = 4;
+
+const TITLE_FONT_SIZE_PX = 13;
+const META_FONT_SIZE_PX = 11;
+
+export interface ItemNodeInput {
+    id: string;
+    title: string;
+    /** Logical left x of the column the bar lives in. */
+    logicalLeftX: number;
+    /** Logical right x of the column the bar lives in. */
+    logicalRightX: number;
+    /** Caption text shown under the title (e.g. "1w - 50% remaining"). */
+    metaText?: string;
+    /**
+     * Extra horizontal width (px) appended to the meta line for spill
+     * detection — covers content the renderer paints after `metaText` but
+     * that the layout assembles as a structured trailing element rather
+     * than a string (currently: the capacity suffix). The layout adds this
+     * to the meta-line's measured width before deciding whether the
+     * caption block fits inside the bar.
+     *
+     * Defaults to 0. Title spill checks ignore this value (the suffix
+     * never renders on the title line).
+     */
+    metaTrailingWidth?: number;
+    /**
+     * True when the bar shows a link icon in its upper-left corner.
+     * Caption text indents past the icon column so the title doesn't
+     * collide with the icon.
+     */
+    hasLinkIcon?: boolean;
+}
+
+export interface PlacedItemGeometry {
+    id: string;
+    box: BoundingBox;
+    /**
+     * X for the title/meta text. Equal to `box.x + TEXT_INSET_PX`
+     * when text fits inside the bar; otherwise positioned just past
+     * the bar's right edge so the caption reads as belonging to the
+     * item rather than being clipped.
+     */
+    textX: number;
+    /** True when text spills past the bar's right edge. */
+    textSpills: boolean;
+}
+
+/**
+ * Approx. rendered width of `text` at `fontSizePx`. Matches the legacy
+ * `sequenceItem` heuristic (intentionally pessimistic at ~0.58 em/char so
+ * borderline-fitting captions trigger spill rather than clip).
+ */
+function estimateTextWidth(text: string, fontSizePx: number): number {
+    return text.length * fontSizePx * 0.58;
+}
+
+export class ItemNode implements Renderable<PlacedItemGeometry> {
+    constructor(public readonly input: ItemNodeInput) {}
+
+    get id(): string {
+        return this.input.id;
+    }
+
+    measure(ctx: MeasureContext): IntrinsicSize {
+        const naturalWidth = Math.max(
+            MIN_ITEM_WIDTH,
+            this.input.logicalRightX - this.input.logicalLeftX,
+        );
+        return {
+            width: naturalWidth,
+            height: ctx.bands.bandwidth(),
+        };
+    }
+
+    place(origin: Point, ctx: PlaceContext): PlacedItemGeometry {
+        const intrinsic = this.measure(ctx);
+        const visualWidth = Math.max(MIN_ITEM_WIDTH, intrinsic.width - 2 * ITEM_INSET_PX);
+        const boxX = origin.x + ITEM_INSET_PX;
+        const box: BoundingBox = {
+            x: boxX,
+            y: origin.y,
+            width: visualWidth,
+            height: intrinsic.height,
+        };
+
+        // The link icon (when present) lives in the bar's upper-left
+        // and shares the title's vertical band. The caption indents
+        // past the icon so the title doesn't render on top of it.
+        const linkColumn = this.input.hasLinkIcon
+            ? ITEM_LINK_ICON_INSET_PX +
+              ITEM_LINK_ICON_TILE_SIZE_PX +
+              LINK_ICON_TO_CAPTION_GAP_PX -
+              TEXT_INSET_PX
+            : 0;
+        const captionLeftInset = TEXT_INSET_PX + Math.max(0, linkColumn);
+        const innerWidth = Math.max(0, visualWidth - captionLeftInset - TEXT_INSET_PX);
+        const titleStr = this.input.title;
+        const titleWidth = titleStr ? estimateTextWidth(titleStr, TITLE_FONT_SIZE_PX) : 0;
+        const metaTextWidth = this.input.metaText
+            ? estimateTextWidth(this.input.metaText, META_FONT_SIZE_PX)
+            : 0;
+        const trailingWidth = this.input.metaTrailingWidth ?? 0;
+        // Trailing decoration (capacity suffix) renders to the right of
+        // metaText. When metaText is empty the suffix sits at the
+        // caption's leading edge, so its width is the entire meta-line
+        // budget; when both exist the suffix needs a small separator gap
+        // (rendered via `<tspan dx>` later) included in trailingWidth.
+        const metaWidth = metaTextWidth + trailingWidth;
+        const hasMetaContent = this.input.metaText !== undefined || trailingWidth > 0;
+        const textSpills =
+            (titleStr.length > 0 && titleWidth > innerWidth) ||
+            (hasMetaContent && metaWidth > innerWidth);
+        const textX = textSpills
+            ? boxX + visualWidth + TEXT_OUTSIDE_GAP_PX
+            : boxX + captionLeftInset;
+
+        return {
+            id: this.input.id,
+            box,
+            textX,
+            textSpills,
+        };
+    }
+}
+
+/**
+ * Horizontal gap (px) between the link-icon tile's right edge and the
+ * start of the caption text when both render inside the bar.
+ */
+const LINK_ICON_TO_CAPTION_GAP_PX = 4;

package/src/nodes/marker-geometry.ts

@@ -0,0 +1,43 @@
+// Marker-row geometry shared across the marker stack: anchors,
+// milestones, and the roadmap-level row packer all read from here so a
+// font, gap, or row-height change flows from one place.
+//
+// Two row-band types live in this file:
+//
+//   - `MARKER_ROW_PITCH_PX` (26 px): height of a single marker row in
+//     the timeline header. The marker band stacks N rows tall when
+//     anchors and milestones can't fit on a single row without colliding.
+//   - The bare `13` (= PITCH / 2) midpoint that used to sprinkle
+//     `roadmap-node.ts` is derived from this constant — bumping the
+//     pitch automatically re-centers labels.
+//
+// Diamond + label box dimensions are reused by every marker (anchor +
+// milestone), and the `MARKER_BOLD_WIDTH_FACTOR` corrects the
+// pessimistic 0.58 em width estimate for bold milestone labels.
+
+/** Height (px) of a single marker row in the timeline header band. */
+export const MARKER_ROW_PITCH_PX = 26;
+
+/**
+ * Vertical center offset of a marker row from the top of its band.
+ * Always half of `MARKER_ROW_PITCH_PX` — exposed as a derived constant
+ * so call sites read as "row 0 center" instead of magic `13`.
+ */
+export const MARKER_ROW_CENTER_OFFSET_PX = MARKER_ROW_PITCH_PX / 2;
+
+/** Half-width of the diamond glyph drawn at every marker's centerX. */
+export const MARKER_DIAMOND_RADIUS_PX = 6;
+
+/** Horizontal gap between the diamond's edge and its label box. */
+export const MARKER_LABEL_GAP_PX = 6;
+
+/** Height of the label box (one line of marker label text). */
+export const MARKER_LABEL_HEIGHT_PX = 12;
+
+/**
+ * Width-estimate surcharge for bold sans-serif marker labels (milestone
+ * titles). `estimateTextWidth` is intentionally pessimistic at ~0.58
+ * em/char so this small surcharge keeps overlap detection on the safe
+ * side without overshooting layout space.
+ */
+export const MARKER_BOLD_WIDTH_FACTOR = 1.05;

package/src/nodes/milestone-node.ts

@@ -0,0 +1,263 @@
+// MilestoneNode — Renderable for a single milestone + a
+// `buildMilestones` loop helper. Each milestone sits in the marker row
+// and either pins to a fixed `date:` or floats to the rightmost `after:`
+// predecessor. A non-binding (second-latest) predecessor drives the
+// "slack" arrow when present. Date-pinned milestones whose predecessors
+// would push past the date are flagged `isOverrun`.
+//
+// Marker-row placement (row + label box + left/right side) is decided
+// once by `roadmap-node.ts::packMarkerRow`. Date-pinned entities are
+// pre-packed before swimlanes run; after-only milestones get a
+// PROVISIONAL row=0 placement here at build time which the unified
+// re-pack in `RoadmapNode.place` overwrites with the final tick-order
+// bottom-first slot once every centerX is known.
+
+import type { MilestoneDeclaration } from '@nowline/core';
+import { parseDate, propValue, propValues } from '../dsl-utils.js';
+import type { LayoutContext } from '../layout-context.js';
+import { resolveStyle } from '../style-resolution.js';
+import type { BoundingBox, Point, PositionedMilestone } from '../types.js';
+import {
+    MARKER_BOLD_WIDTH_FACTOR,
+    MARKER_DIAMOND_RADIUS_PX,
+    MARKER_LABEL_GAP_PX,
+    MARKER_LABEL_HEIGHT_PX,
+} from './marker-geometry.js';
+
+/**
+ * One predecessor of a milestone with everything the slack-arrow
+ * pipeline needs: its source x (visual right edge for items, marker
+ * centerX for anchors / other milestones), its attach y (bar bottom
+ * strip when text spills, row mid otherwise), and its flow key (used
+ * to dedupe so a chained-flow's siblings collapse to the last entry).
+ */
+export interface MilestonePredecessor {
+    ref: string;
+    x: number;
+    y: number;
+    flowKey: string;
+}
+
+/**
+ * Resolve each `after:` reference into a `MilestonePredecessor`.
+ * Items use their VISUAL right edge as the slack source so the
+ * arrow leaves the painted bar instead of landing in the inter-
+ * column gutter; markers (anchors / other milestones) fall back
+ * to their cut-line centerX. Refs whose target is unknown drop
+ * silently — matches the legacy continue path.
+ */
+export function collectMilestonePredecessors(
+    refs: string[],
+    ctx: LayoutContext,
+): MilestonePredecessor[] {
+    const out: MilestonePredecessor[] = [];
+    for (const ref of refs) {
+        const visualRight = ctx.entityVisualRightX.get(ref);
+        const x = visualRight ?? ctx.entityRightEdges.get(ref);
+        if (x === undefined) continue;
+        const y = ctx.itemSlackAttachY.get(ref) ?? ctx.entityMidpoints.get(ref)?.y ?? 0;
+        // Markers don't share a flow with anything, so use their id
+        // as a unique flow key — every marker stands on its own.
+        const flowKey = ctx.itemFlowKey.get(ref) ?? `marker:${ref}`;
+        out.push({ ref, x, y, flowKey });
+    }
+    return out;
+}
+
+/**
+ * Keep only the rightmost predecessor per flow key. Two
+ * predecessors share a flow when they sit in the same deepest
+ * single-track container (swimlane root, sequential group, or one
+ * sub-track of a parallel) — file order already encodes their
+ * ordering, so only the latest entry contributes a slack arrow.
+ * Predecessors in different flows (e.g. two parallel sub-tracks)
+ * each survive as their flow's last entry.
+ */
+export function lastPredecessorPerFlow(preds: MilestonePredecessor[]): MilestonePredecessor[] {
+    const m = new Map<string, MilestonePredecessor>();
+    for (const p of preds) {
+        const existing = m.get(p.flowKey);
+        if (!existing || p.x > existing.x) m.set(p.flowKey, p);
+    }
+    return Array.from(m.values());
+}
+
+function decideLabelBoxForCanvas(
+    centerX: number,
+    centerY: number,
+    radius: number,
+    title: string,
+    fontSize: number,
+    bold: boolean,
+    chartLeftX: number,
+    chartRightX: number,
+): { box: BoundingBox; side: 'left' | 'right' } {
+    const labelWidth = title.length * fontSize * 0.58 * (bold ? MARKER_BOLD_WIDTH_FACTOR : 1);
+    const naturalRightX = centerX + radius + MARKER_LABEL_GAP_PX;
+    const naturalLeftX = centerX - radius - MARKER_LABEL_GAP_PX - labelWidth;
+    const fitsRight = naturalRightX + labelWidth <= chartRightX;
+    const fitsLeft = naturalLeftX >= chartLeftX;
+    const side: 'left' | 'right' = fitsRight ? 'right' : fitsLeft ? 'left' : 'right';
+    const xLeft = side === 'right' ? naturalRightX : naturalLeftX;
+    return {
+        box: { x: xLeft, y: centerY - 4, width: labelWidth, height: MARKER_LABEL_HEIGHT_PX },
+        side,
+    };
+}
+
+export class MilestoneNode {
+    constructor(
+        public readonly id: string,
+        public readonly milestone: MilestoneDeclaration,
+    ) {}
+
+    /**
+     * Returns null when the milestone is neither date-pinned nor has a
+     * resolvable `after:` predecessor (skipped silently — matches the
+     * legacy `buildMilestones` continue-paths).
+     */
+    place(ctx: LayoutContext): PositionedMilestone | null {
+        const m = this.milestone;
+        const style = resolveStyle('milestone', m.properties, ctx.styleCtx);
+        const dateRaw = propValue(m.properties, 'date');
+        const afterRaw = propValues(m.properties, 'after');
+        const date = parseDate(dateRaw);
+        const inRowY = ctx.timeline.markerRow.y;
+        const radius = MARKER_DIAMOND_RADIUS_PX;
+        const title = m.title ?? this.id;
+
+        let centerX: number | null = null;
+        let centerY: number = inRowY;
+        let labelBox: BoundingBox | null = null;
+        let labelSide: 'left' | 'right' = 'right';
+        let fixed = false;
+        let slackArrows: Array<{ x: number; y: number }> | undefined;
+        let isOverrun = false;
+
+        if (date) {
+            const x = ctx.scale.forwardWithinDomain(date);
+            if (x === null) return null;
+            centerX = x;
+            fixed = true;
+            const placement = ctx.markerRowPlacements.get(this.id);
+            if (placement) {
+                centerY = placement.centerY;
+                labelBox = placement.labelBox;
+                labelSide = placement.labelSide;
+            }
+            // Date-pinned milestones whose `after:` predecessors finish
+            // past the pinned date are flagged `isOverrun`; the latest
+            // last-of-flow predecessor draws a single overrun arrow
+            // pointing back from its visual right edge to the
+            // milestone's column. Flow-dedupe avoids stacking redundant
+            // arrows from sibling items in one chained flow.
+            const preds = collectMilestonePredecessors(afterRaw, ctx);
+            const dedupedPreds = lastPredecessorPerFlow(preds);
+            let maxPred: MilestonePredecessor | null = null;
+            for (const p of dedupedPreds) {
+                if (!maxPred || p.x > maxPred.x) maxPred = p;
+            }
+            if (maxPred && maxPred.x > x) {
+                isOverrun = true;
+                slackArrows = [
+                    {
+                        x: maxPred.x,
+                        y: maxPred.y > 0 ? maxPred.y : centerY,
+                    },
+                ];
+            }
+        } else if (afterRaw.length > 0) {
+            // Float to the rightmost (binding) predecessor; every
+            // last-of-flow predecessor that finishes EARLIER than the
+            // binding contributes one slack arrow. Predecessors in the
+            // same single-track flow (sequential group, swimlane root,
+            // one parallel sub-track) collapse to just their last
+            // entry — file order encodes the dependency chain, so only
+            // the rightmost matters. Predecessors in different flows
+            // (e.g. two parallel sub-tracks) each contribute their own
+            // last-of-flow arrow.
+            const preds = collectMilestonePredecessors(afterRaw, ctx);
+            const dedupedPreds = lastPredecessorPerFlow(preds);
+            dedupedPreds.sort((a, b) => b.x - a.x);
+            const maxEnd = dedupedPreds[0]?.x ?? ctx.timeline.originX;
+            centerX = maxEnd;
+            fixed = false;
+            // Provisional placement — RoadmapNode runs a unified
+            // tick-order pack across all markers (date-pinned anchors,
+            // date-pinned milestones, after-only milestones) once
+            // everyone's centerX is known. That pass overwrites the
+            // rowIndex / centerY / labelBox / labelSide we set here.
+            const provisional = decideLabelBoxForCanvas(
+                centerX,
+                inRowY,
+                radius,
+                title,
+                10,
+                true,
+                ctx.timeline.box.x,
+                ctx.chartRightX,
+            );
+            centerY = inRowY;
+            labelBox = provisional.box;
+            labelSide = provisional.side;
+            ctx.markerRowPlacements.set(this.id, {
+                rowIndex: 0,
+                centerY,
+                labelBox,
+                labelSide,
+            });
+            const arrows: Array<{ x: number; y: number }> = [];
+            for (let i = 1; i < dedupedPreds.length; i++) {
+                const p = dedupedPreds[i];
+                if (p.x < maxEnd && p.y > 0) arrows.push({ x: p.x, y: p.y });
+            }
+            if (arrows.length > 0) slackArrows = arrows;
+        }
+        if (centerX === null) return null;
+        if (!labelBox) {
+            const fallback = decideLabelBoxForCanvas(
+                centerX,
+                centerY,
+                radius,
+                title,
+                10,
+                true,
+                ctx.timeline.box.x,
+                ctx.chartRightX,
+            );
+            labelBox = fallback.box;
+            labelSide = fallback.side;
+        }
+
+        const center: Point = { x: centerX, y: centerY };
+        ctx.entityLeftEdges.set(this.id, center.x);
+        ctx.entityRightEdges.set(this.id, center.x);
+        ctx.entityMidpoints.set(this.id, center);
+        return {
+            id: this.id,
+            title,
+            center,
+            radius,
+            fixed,
+            slackArrows,
+            isOverrun,
+            style,
+            cutTopY: ctx.chartTopY,
+            cutBottomY: ctx.swimlaneBottomY,
+            labelBox,
+            labelSide,
+        };
+    }
+}
+
+export function buildMilestones(
+    milestones: Map<string, MilestoneDeclaration>,
+    ctx: LayoutContext,
+): PositionedMilestone[] {
+    const out: PositionedMilestone[] = [];
+    for (const [id, m] of milestones) {
+        const positioned = new MilestoneNode(id, m).place(ctx);
+        if (positioned) out.push(positioned);
+    }
+    return out;
+}

package/src/nodes/parallel-node.ts

@@ -0,0 +1,101 @@
+// ParallelNode — Renderable for a `parallel { ... }` block. Stacks
+// children top-to-bottom (each child owns a fresh sub-track) and reports
+// the union bounding box. Each child is sequenced via the injected
+// `deps.sequenceOne` callback, which dispatches to the appropriate
+// per-entity Renderable (or, transitionally, the legacy sequencer
+// helpers in `layout.ts`).
+
+import type { GroupBlock, ItemDeclaration, ParallelBlock } from '@nowline/core';
+import type { LayoutContext, TrackCursor } from '../layout-context.js';
+import { resolveStyle } from '../style-resolution.js';
+import { TRACK_BLOCK_TAIL_GUTTER_PX } from '../themes/shared.js';
+import type { BoundingBox, PositionedParallel, PositionedTrackChild } from '../types.js';
+
+export interface ParallelNodeDeps {
+    sequenceOne: (
+        child: ItemDeclaration | GroupBlock | ParallelBlock,
+        cursor: TrackCursor,
+        ctx: LayoutContext,
+    ) => PositionedTrackChild;
+    newCursor: (x: number, y: number) => TrackCursor;
+}
+
+export class ParallelNode {
+    constructor(
+        public readonly node: ParallelBlock,
+        // biome-ignore lint/correctness/noUnusedPrivateClassMembers: accessed via `const { deps } = this` destructuring inside methods, which the analyzer does not detect.
+        private readonly deps: ParallelNodeDeps,
+    ) {}
+
+    get id(): string {
+        return this.node.name ?? '';
+    }
+
+    /**
+     * Sequence children into stacked sub-tracks, advance the parent
+     * `cursor` past the parallel's right edge plus
+     * `TRACK_BLOCK_TAIL_GUTTER_PX` of breathing room, and return a
+     * `PositionedParallel`.
+     */
+    place(cursor: TrackCursor, ctx: LayoutContext): PositionedParallel {
+        const { node } = this;
+        const { deps } = this;
+        const style = resolveStyle('parallel', node.properties, ctx.styleCtx);
+        const startX = cursor.x;
+        const startY = cursor.y;
+        const children: PositionedTrackChild[] = [];
+        let maxRight = startX;
+        let accumulatedHeight = 0;
+
+        // Each child of a parallel block lives on its own sub-track,
+        // so each child starts a fresh flow segment under the parent's
+        // path. Two predecessors that sit on different parallel
+        // sub-tracks therefore stay in different flows for milestone
+        // slack-arrow dedupe.
+        const previousFlowKey = ctx.currentFlowKey;
+        const parId = node.name ?? 'p';
+
+        let childIndex = 0;
+        for (const child of node.content) {
+            if (child.$type === 'DescriptionDirective') continue;
+            ctx.currentFlowKey = `${previousFlowKey}/par:${parId}#${childIndex}`;
+            const subCursor = deps.newCursor(startX, startY + accumulatedHeight);
+            const positioned = deps.sequenceOne(
+                child as ItemDeclaration | GroupBlock,
+                subCursor,
+                ctx,
+            );
+            children.push(positioned);
+            accumulatedHeight += Math.max(ctx.bandScale.step(), subCursor.height);
+            maxRight = Math.max(maxRight, subCursor.maxX);
+            childIndex++;
+        }
+        ctx.currentFlowKey = previousFlowKey;
+
+        const box: BoundingBox = {
+            x: startX,
+            y: startY,
+            width: maxRight - startX,
+            height: accumulatedHeight,
+        };
+
+        cursor.x = maxRight + TRACK_BLOCK_TAIL_GUTTER_PX;
+        cursor.maxX = Math.max(cursor.maxX, cursor.x);
+        cursor.height = Math.max(cursor.height, accumulatedHeight);
+
+        const id = node.name;
+        if (id) {
+            ctx.entityLeftEdges.set(id, box.x);
+            ctx.entityRightEdges.set(id, box.x + box.width);
+        }
+
+        return {
+            kind: 'parallel',
+            id,
+            title: node.title ?? node.name,
+            box,
+            children,
+            style,
+        };
+    }
+}