@nowline/layout 0.2.0

package/src/nodes/anchor-node.ts

@@ -0,0 +1,77 @@
+// AnchorNode — Renderable for a single anchor + a `buildAnchors` loop
+// helper. Each anchor sits in the marker row of the timeline and emits
+// a downward cut line through the chart. Marker-row placement (row +
+// label box + left/right label side) is decided up-front in
+// `roadmap-node.ts` (`packMarkerRow`) so anchors and milestones share
+// the same row stack — see `LayoutContext.markerRowPlacements`.
+
+import type { AnchorDeclaration } from '@nowline/core';
+import { parseDate, propValue } from '../dsl-utils.js';
+import type { LayoutContext } from '../layout-context.js';
+import { resolveStyle } from '../style-resolution.js';
+import type { Point, PositionedAnchor } from '../types.js';
+import {
+    MARKER_DIAMOND_RADIUS_PX,
+    MARKER_LABEL_GAP_PX,
+    MARKER_LABEL_HEIGHT_PX,
+} from './marker-geometry.js';
+
+export class AnchorNode {
+    constructor(
+        public readonly id: string,
+        public readonly anchor: AnchorDeclaration,
+    ) {}
+
+    /**
+     * Returns null when the anchor has no `date:` or its date falls
+     * outside the chart's domain (skipped silently — same as the legacy
+     * `buildAnchors` continue-paths).
+     */
+    place(ctx: LayoutContext, _milestoneXs: Set<number>): PositionedAnchor | null {
+        const dateRaw = propValue(this.anchor.properties, 'date');
+        const date = parseDate(dateRaw);
+        if (!date) return null;
+        const x = ctx.scale.forwardWithinDomain(date);
+        if (x === null) return null;
+        const style = resolveStyle('anchor', this.anchor.properties, ctx.styleCtx);
+        const placement = ctx.markerRowPlacements.get(this.id);
+        const y = placement?.centerY ?? ctx.timeline.markerRow.y;
+        const center: Point = { x, y };
+        const labelBox = placement?.labelBox ?? {
+            x: x + MARKER_DIAMOND_RADIUS_PX + MARKER_LABEL_GAP_PX,
+            y: y - 4,
+            width: 0,
+            height: MARKER_LABEL_HEIGHT_PX,
+        };
+        const labelSide = placement?.labelSide ?? 'right';
+        ctx.entityLeftEdges.set(this.id, x);
+        ctx.entityRightEdges.set(this.id, x);
+        ctx.entityMidpoints.set(this.id, center);
+        return {
+            id: this.id,
+            title: this.anchor.title ?? this.id,
+            center,
+            radius: MARKER_DIAMOND_RADIUS_PX,
+            style,
+            predecessorPoints: [],
+            cutTopY: ctx.chartTopY,
+            cutBottomY: ctx.swimlaneBottomY,
+            bumpedUp: (placement?.rowIndex ?? 0) > 0,
+            labelBox,
+            labelSide,
+        };
+    }
+}
+
+export function buildAnchors(
+    anchors: Map<string, AnchorDeclaration>,
+    ctx: LayoutContext,
+    milestoneXs: Set<number>,
+): PositionedAnchor[] {
+    const out: PositionedAnchor[] = [];
+    for (const [id, a] of anchors) {
+        const positioned = new AnchorNode(id, a).place(ctx, milestoneXs);
+        if (positioned) out.push(positioned);
+    }
+    return out;
+}

package/src/nodes/footnote-node.ts

@@ -0,0 +1,60 @@
+// FootnoteNode + buildFootnotes — footnote area at the bottom of the
+// chart. Each footnote gets a stable index (1-based, sorted by id) and
+// records its `on:` host references so item / swimlane sequencing can
+// emit the matching superscript indicators. The panel grows to fit:
+// 28 px header + (entries × FOOTNOTE_ROW_HEIGHT) + 16 px padding.
+
+import type { FootnoteDeclaration } from '@nowline/core';
+import { propValues } from '../dsl-utils.js';
+import type { LayoutContext } from '../layout-context.js';
+import { resolveStyle } from '../style-resolution.js';
+import {
+    FOOTNOTE_HEADER_HEIGHT_PX,
+    FOOTNOTE_PANEL_PADDING_PX,
+    FOOTNOTE_ROW_HEIGHT,
+} from '../themes/shared.js';
+import type { BoundingBox, PositionedFootnoteArea, PositionedFootnoteEntry } from '../types.js';
+
+export interface BuiltFootnotes {
+    area: PositionedFootnoteArea;
+    index: Map<string, number>;
+    hosts: Map<string, string[]>;
+}
+
+export function buildFootnotes(
+    footnotes: Map<string, FootnoteDeclaration>,
+    ctx: LayoutContext,
+    chartBottomY: number,
+): BuiltFootnotes {
+    const entries: PositionedFootnoteEntry[] = [];
+    const index = new Map<string, number>();
+    const hosts = new Map<string, string[]>();
+    const ordered = [...footnotes.entries()].sort(([a], [b]) => a.localeCompare(b));
+    ordered.forEach(([id, f], i) => {
+        const n = i + 1;
+        index.set(id, n);
+        hosts.set(id, propValues(f.properties, 'on'));
+        entries.push({
+            number: n,
+            title: f.title ?? id,
+            description: f.description?.text,
+            style: resolveStyle('footnote', f.properties, ctx.styleCtx),
+        });
+    });
+    const box: BoundingBox = {
+        x: FOOTNOTE_PANEL_PADDING_PX,
+        y: chartBottomY + FOOTNOTE_PANEL_PADDING_PX,
+        width: ctx.chartRightX - 2 * FOOTNOTE_PANEL_PADDING_PX,
+        height:
+            entries.length === 0
+                ? 0
+                : FOOTNOTE_HEADER_HEIGHT_PX +
+                  entries.length * FOOTNOTE_ROW_HEIGHT +
+                  FOOTNOTE_PANEL_PADDING_PX,
+    };
+    return {
+        area: { box, entries },
+        index,
+        hosts,
+    };
+}

package/src/nodes/group-node.ts

@@ -0,0 +1,252 @@
+// GroupNode — Renderable for a `group { ... }` block. Sequences
+// children inside the group's content area using the same row-pack
+// engine `SwimlaneNode` uses, so an item whose desired start collides
+// with a sibling's `rightEdge`, caption `spillX`, or a slack-arrow
+// corridor bumps to a new row inside the group. The group's reported
+// `box.height` grows with the row stack so parent containers stack
+// against the actual painted extent.
+//
+// Filled-style groups paint a title chiclet flush in the upper-left
+// corner of the box; the layout reserves vertical top padding equal
+// to the chiclet height plus a small gutter before the first inner
+// row begins.
+
+import type { EntityProperty, GroupBlock, ItemDeclaration, ParallelBlock } from '@nowline/core';
+import { isItemDeclaration } from '@nowline/core';
+import { deriveItemDurationDays } from '../calendar.js';
+import type { LayoutContext, TrackCursor } from '../layout-context.js';
+import { RowPacker } from '../row-packer.js';
+import { resolveStyle } from '../style-resolution.js';
+import {
+    GROUP_BOTTOM_PAD_PX,
+    GROUP_BRACKET_LABEL_OVERHANG_PX,
+    GROUP_TITLE_TAB_GUTTER_PX,
+    GROUP_TITLE_TAB_HEIGHT_PX,
+    ITEM_INSET_PX,
+    MIN_ITEM_WIDTH,
+    TRACK_BLOCK_TAIL_GUTTER_PX,
+} from '../themes/shared.js';
+import type {
+    BoundingBox,
+    PositionedGroup,
+    PositionedItem,
+    PositionedTrackChild,
+} from '../types.js';
+
+export interface GroupNodeDeps {
+    sequenceItem: (
+        child: ItemDeclaration,
+        cursor: TrackCursor,
+        ctx: LayoutContext,
+        ownerOverride?: string,
+    ) => PositionedItem;
+    sequenceOne: (
+        child: ItemDeclaration | GroupBlock | ParallelBlock,
+        cursor: TrackCursor,
+        ctx: LayoutContext,
+    ) => PositionedTrackChild;
+    resolveChildStart: (
+        props: EntityProperty[],
+        seqDefault: number,
+        laneLeftX: number,
+        ctx: LayoutContext,
+    ) => number;
+    newCursor: (x: number, y: number) => TrackCursor;
+    estimateTextWidth: (text: string, fontSize: number) => number;
+    /** Predict the extra vertical height an item's wrapped label-chip
+     *  rows will add to its bar; used to size the row-packer's row
+     *  pitch ahead of the call to `sequenceItem`. */
+    predictItemChipExtraHeight: (item: ItemDeclaration, ctx: LayoutContext) => number;
+}
+
+export class GroupNode {
+    constructor(
+        public readonly node: GroupBlock,
+        // biome-ignore lint/correctness/noUnusedPrivateClassMembers: accessed via `const { deps } = this` destructuring inside methods, which the analyzer does not detect.
+        private readonly deps: GroupNodeDeps,
+    ) {}
+
+    get id(): string {
+        return this.node.name ?? '';
+    }
+
+    /**
+     * Sequence children inside the group's content area, advance the
+     * parent `cursor` past the group's right edge plus
+     * `TRACK_BLOCK_TAIL_GUTTER_PX` of breathing room, and return a
+     * `PositionedGroup` whose `box.height` covers the chiclet pad,
+     * every row-packed child row, and the bottom pad.
+     */
+    place(cursor: TrackCursor, ctx: LayoutContext): PositionedGroup {
+        const { node } = this;
+        const { deps } = this;
+        const style = resolveStyle('group', node.properties, ctx.styleCtx);
+        const startX = cursor.x;
+        const title = node.title ?? node.name;
+
+        // Group children chain in time inside the group, so they
+        // form one sub-flow under the parent's flow path. See
+        // `LayoutContext.currentFlowKey`.
+        const previousFlowKey = ctx.currentFlowKey;
+        ctx.currentFlowKey = `${previousFlowKey}/group:${node.name ?? 'g'}`;
+        // Mirrors `renderGroup`'s `hasFill` decision so the painted box
+        // and the layout's reservation agree on whether a chiclet exists.
+        const hasChiclet = style.bg !== 'none' && style.bg !== '#ffffff' && Boolean(title);
+        const topPad = hasChiclet ? GROUP_TITLE_TAB_HEIGHT_PX + GROUP_TITLE_TAB_GUTTER_PX : 0;
+        const bottomPad = hasChiclet ? GROUP_BOTTOM_PAD_PX : 0;
+        // Bracket-style groups paint their label at `box.y - 2`, so the
+        // label glyph overhangs ABOVE box.y. Without an explicit
+        // reservation, two bracket-titled groups stacked in a parallel
+        // collide: the previous sibling's bracket-foot ends at its
+        // box.bottom, and the next sibling's label visual top sits just
+        // above box.y — they touch in the gap. Shift `box.y` down by
+        // the overhang amount so the glyph lands in space we own.
+        const bracketLabelOverhang = !hasChiclet && title ? GROUP_BRACKET_LABEL_OVERHANG_PX : 0;
+        const startY = cursor.y + bracketLabelOverhang;
+
+        const step = ctx.bandScale.step();
+        const groupContentLeftX = startX;
+        const packer = new RowPacker({
+            laneLeftX: groupContentLeftX,
+            originY: startY + topPad,
+            minRowHeight: step,
+            slackCorridors: ctx.slackCorridors,
+        });
+        let timeCursorX = groupContentLeftX;
+
+        const children: PositionedTrackChild[] = [];
+        for (const child of node.content) {
+            if (child.$type === 'DescriptionDirective') continue;
+
+            if (!isItemDeclaration(child)) {
+                const blockProps = (child as ParallelBlock | GroupBlock).properties ?? [];
+                const blockStart = deps.resolveChildStart(
+                    blockProps,
+                    timeCursorX,
+                    groupContentLeftX,
+                    ctx,
+                );
+                const { rowIndex, y: blockY } = packer.placeBlock();
+                const innerCursor = deps.newCursor(blockStart, blockY);
+                const positioned = deps.sequenceOne(
+                    child as ItemDeclaration | GroupBlock | ParallelBlock,
+                    innerCursor,
+                    ctx,
+                );
+                children.push(positioned);
+                const blockEnd = positioned.box.x + positioned.box.width;
+                const blockHeight = Math.max(step, innerCursor.height);
+                packer.commitBlock({
+                    rowIndex,
+                    placed: positioned,
+                    blockHeight,
+                    blockEnd,
+                });
+                timeCursorX = Math.max(timeCursorX, blockEnd);
+                continue;
+            }
+
+            const props = (child as ItemDeclaration).properties;
+            const desiredStart = deps.resolveChildStart(props, timeCursorX, groupContentLeftX, ctx);
+            // Predict logical extent so the row-packer can bump on
+            // collision before we hand off to `sequenceItem`. Mirrors
+            // SwimlaneNode's pre-flight width math.
+            const durationDays = deriveItemDurationDays(props, ctx.sizes, ctx.cal);
+            const naturalWidth = Math.max(MIN_ITEM_WIDTH, durationDays * ctx.timeline.pixelsPerDay);
+            const desiredEnd = desiredStart + naturalWidth;
+            const childId = (child as ItemDeclaration).name ?? '';
+
+            const chipExtra = deps.predictItemChipExtraHeight(child as ItemDeclaration, ctx);
+            const predictedHeight = step + chipExtra;
+            const { rowIndex, y: rowY } = packer.placeItem({
+                childId,
+                desiredStart,
+                desiredEnd,
+                // Row pitch = `step()` + extra chip-row height. Keeps
+                // the inter-row visible gap (= step - bandwidth) intact
+                // when an item's labels wrap and grow the bar.
+                predictedHeight,
+            });
+
+            const innerCursor = deps.newCursor(desiredStart, rowY);
+            const positioned = deps.sequenceItem(child as ItemDeclaration, innerCursor, ctx);
+            children.push(positioned);
+
+            const itemLogicalEnd = positioned.box.x + positioned.box.width + ITEM_INSET_PX;
+            timeCursorX = Math.max(timeCursorX, itemLogicalEnd);
+
+            let spillReservation: number | null = null;
+            const hasAnySpill =
+                positioned.textSpills ||
+                positioned.chipsOutside ||
+                positioned.dotSpills ||
+                positioned.iconSpills ||
+                positioned.footnoteSpills;
+            if (hasAnySpill) {
+                const farRight = Math.max(
+                    positioned.decorationsRightX,
+                    positioned.chipsOutside ? positioned.chipsRightX : 0,
+                );
+                spillReservation = farRight + 6;
+            }
+
+            packer.commitItem({
+                rowIndex,
+                placed: positioned,
+                logicalEnd: itemLogicalEnd,
+                spillReservation,
+                rowHeight: predictedHeight,
+            });
+        }
+
+        const innerHeight = Math.max(step, packer.usedHeight());
+        // The group's painted box hugs everything its children put on
+        // screen, including caption text that spills past a bar's right
+        // edge. `usedRightX` is the rightmost extent any row reached —
+        // either a bar's logical right or a caption's reserved spill —
+        // so the orange tint visually "owns" the spilled title/meta.
+        //
+        // The cursor channel (`cursor.x` / `cursor.maxX`) stays on the
+        // COMPACT `timeCursorX` (bar logical ends only). Bubbling the
+        // wide `visualRightX` upward would propagate through
+        // `ParallelNode.maxRight → parallel.box.width → swimlane
+        // blockEnd → timeCursorX`, pushing every subsequent sibling
+        // right by the spill width — including siblings on entirely
+        // different rows of the parent swimlane. The painted box and
+        // the logical cursor advance are intentionally decoupled here.
+        const visualRightX = Math.max(timeCursorX, packer.usedRightX());
+        const box: BoundingBox = {
+            x: startX,
+            y: startY,
+            width: visualRightX - startX,
+            height: topPad + innerHeight + bottomPad,
+        };
+        cursor.x = timeCursorX + TRACK_BLOCK_TAIL_GUTTER_PX;
+        cursor.maxX = Math.max(cursor.maxX, cursor.x);
+        // The painted `box.height` is the group's tight visual
+        // footprint (chiclet + content + bottomPad). The cursor
+        // advance, however, must include one inter-row gap
+        // (`step - bandwidth`) so a sibling stacked below in a
+        // `parallel` (or any track-pack consumer) doesn't butt
+        // right up against the group's bottom edge. Items naturally
+        // include that gap because they report `cursor.height = step`
+        // (bandwidth + gap); groups need to add it explicitly since
+        // their painted height is gap-less.
+        const interRowGap = ctx.bandScale.step() - ctx.bandScale.bandwidth();
+        cursor.height = Math.max(cursor.height, bracketLabelOverhang + box.height + interRowGap);
+        const id = node.name;
+        if (id) {
+            ctx.entityLeftEdges.set(id, box.x);
+            ctx.entityRightEdges.set(id, box.x + box.width);
+        }
+        ctx.currentFlowKey = previousFlowKey;
+        return {
+            kind: 'group',
+            id,
+            title,
+            box,
+            children,
+            style,
+        };
+    }
+}

package/src/nodes/include-node.ts

@@ -0,0 +1,168 @@
+// IncludeNode + buildIncludeRegions — render isolated `include {}`
+// regions stacked under the main swimlanes. Each region runs its own
+// SwimlaneNode pass against the parent's TimeScale so dates align
+// vertically with the tick row above the region. The label tab is
+// reserved 18 px above the first region; subsequent regions are
+// separated by GAP_BETWEEN_REGIONS px.
+
+import type {
+    EntityProperty,
+    GroupBlock,
+    IsolatedRegion,
+    ItemDeclaration,
+    ParallelBlock,
+} from '@nowline/core';
+import { resolveSizes } from '../calendar.js';
+import { includeChromeGeometry } from '../include-chrome-geometry.js';
+import type { LayoutContext, TrackCursor } from '../layout-context.js';
+import { resolveStyle } from '../style-resolution.js';
+import type {
+    BoundingBox,
+    PositionedIncludeRegion,
+    PositionedItem,
+    PositionedSwimlane,
+    PositionedTrackChild,
+} from '../types.js';
+import { SwimlaneNode } from './swimlane-node.js';
+
+const TAB_RESERVE = 18;
+const REGION_INSET_TOP = 14;
+const REGION_INSET_BOTTOM = 14;
+const GAP_BETWEEN_REGIONS = 16;
+
+// Visual breathing room added past the rightmost element when sizing
+// the include's bounding box. Keeps the dashed bracket from butting up
+// against an item's right edge while still trimming the wide
+// chart-width whitespace left over from full-width sizing.
+const INCLUDE_CONTENT_RIGHT_PAD_PX = 32;
+
+export interface IncludeNodeDeps {
+    sequenceItem: (
+        child: ItemDeclaration,
+        cursor: TrackCursor,
+        ctx: LayoutContext,
+        ownerOverride?: string,
+    ) => PositionedItem;
+    sequenceOne: (
+        child: ItemDeclaration | GroupBlock | ParallelBlock,
+        cursor: TrackCursor,
+        ctx: LayoutContext,
+    ) => PositionedTrackChild;
+    resolveChildStart: (
+        props: EntityProperty[],
+        seqDefault: number,
+        laneLeftX: number,
+        ctx: LayoutContext,
+    ) => number;
+    newCursor: (x: number, y: number) => TrackCursor;
+    estimateTextWidth: (text: string, fontSize: number) => number;
+    predictItemChipExtraHeight: (item: ItemDeclaration, ctx: LayoutContext) => number;
+}
+
+export function buildIncludeRegions(
+    regions: IsolatedRegion[],
+    ctx: LayoutContext,
+    startY: number,
+    deps: IncludeNodeDeps,
+): { regions: PositionedIncludeRegion[]; endY: number } {
+    let y = startY + TAB_RESERVE;
+    const out: PositionedIncludeRegion[] = [];
+    let isFirst = true;
+    for (const region of regions) {
+        if (!isFirst) y += GAP_BETWEEN_REGIONS;
+        isFirst = false;
+        const label = region.content.roadmap?.title ?? region.sourcePath;
+        const innerStartY = y + REGION_INSET_TOP;
+        const childCtx: LayoutContext = {
+            cal: ctx.cal,
+            styleCtx: {
+                theme: ctx.styleCtx.theme,
+                styles: region.config.styles,
+                defaults: region.config.defaults,
+                labels: region.content.labels,
+            },
+            // Each include region declares its own sizes; resolve them under
+            // the parent's calendar so child sized items render at the same
+            // pixels-per-day scale as the host roadmap.
+            sizes: resolveSizes(region.content.sizes, ctx.cal),
+            labels: region.content.labels,
+            teams: region.content.teams,
+            persons: region.content.persons,
+            symbols: region.config.symbols,
+            footnoteIndex: new Map(),
+            footnoteHosts: new Map(),
+            timeline: ctx.timeline,
+            scale: ctx.scale,
+            calendar: ctx.calendar,
+            bandScale: ctx.bandScale,
+            entityLeftEdges: new Map(),
+            entityRightEdges: new Map(),
+            entityMidpoints: new Map(),
+            entityVisualLeftX: new Map(),
+            entityVisualRightX: new Map(),
+            itemArrowSource: new Map(),
+            itemFlowKey: new Map(),
+            currentFlowKey: '',
+            itemSlackAttachY: new Map(),
+            slackCorridors: [],
+            markerRowPlacements: new Map(),
+            chartTopY: innerStartY,
+            chartBottomY: innerStartY,
+            swimlaneBottomY: innerStartY,
+            chartRightX: ctx.chartRightX,
+        };
+        const nestedSwimlanes: PositionedSwimlane[] = [];
+        let cursorY = innerStartY;
+        let bandIndex = 0;
+        let nestedContentRightX = childCtx.timeline.originX;
+        for (const lane of region.content.swimlanes.values()) {
+            const { positioned, usedHeight, usedRightX } = new SwimlaneNode(
+                { lane, bandIndex },
+                deps,
+            ).place({ x: childCtx.timeline.originX, y: cursorY }, childCtx);
+            nestedSwimlanes.push(positioned);
+            cursorY += usedHeight;
+            bandIndex++;
+            if (usedRightX > nestedContentRightX) nestedContentRightX = usedRightX;
+        }
+        const innerEndY = cursorY;
+        // Floor the region height to one row's bandwidth so an empty or
+        // tiny include still presents as a visible band — `bandwidth()`
+        // tracks whatever the host theme uses for swimlane row height.
+        const regionHeight = Math.max(
+            ctx.bandScale.bandwidth(),
+            innerEndY - y + REGION_INSET_BOTTOM,
+        );
+        // Shrink-wrap the include's bounding box to fit chrome + content
+        // (with a small right pad) instead of stretching to the full
+        // chart width. An include that reaches past the timeline still
+        // gets clamped to the chart's natural right edge so it never
+        // extends into the attribution / right-margin area.
+        const boxX = 0;
+        const { chromeRightX } = includeChromeGeometry(boxX, label, region.sourcePath);
+        const naturalRightX =
+            Math.max(chromeRightX, nestedContentRightX) + INCLUDE_CONTENT_RIGHT_PAD_PX;
+        const boxWidth = Math.min(ctx.chartRightX - boxX, naturalRightX - boxX);
+        const box: BoundingBox = {
+            x: boxX,
+            y,
+            width: boxWidth,
+            height: regionHeight,
+        };
+        // Mirror the shrunk width onto each nested swimlane band so the
+        // tinted background fits inside the dashed bracket instead of
+        // bleeding past it on the right.
+        for (const lane of nestedSwimlanes) {
+            lane.box.width = boxWidth;
+        }
+        out.push({
+            sourcePath: region.sourcePath,
+            label,
+            box,
+            nestedSwimlanes,
+            style: resolveStyle('swimlane', [], ctx.styleCtx),
+        });
+        y += regionHeight;
+    }
+    return { regions: out, endY: y };
+}