@nowline/layout 0.8.5 → 0.9.0

package/src/nodes/anchor-node.ts

@@ -2,11 +2,11 @@
 // 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
+// `marker-band.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 { formatIsoDate, parseIsoDate, 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';
@@ -29,7 +29,7 @@ export class AnchorNode {
      */
     place(ctx: LayoutContext, _milestoneXs: Set<number>): PositionedAnchor | null {
         const dateRaw = propValue(this.anchor.properties, 'date');
-        const date = parseDate(dateRaw);
+        const date = parseIsoDate(dateRaw);
         if (!date) return null;
         const x = ctx.scale.forwardWithinDomain(date);
         if (x === null) return null;
@@ -47,7 +47,7 @@ export class AnchorNode {
         ctx.entityLeftEdges.set(this.id, x);
         ctx.entityRightEdges.set(this.id, x);
         ctx.entityMidpoints.set(this.id, center);
-        return {
+        const positioned: PositionedAnchor = {
             id: this.id,
             title: this.anchor.title ?? this.id,
             center,
@@ -60,6 +60,13 @@ export class AnchorNode {
             labelBox,
             labelSide,
         };
+        // A date the axis hides keeps its own day as a tooltip
+        // (specs/working-calendar.md §7.4). Under `show` the day is drawn,
+        // and the anchor sits on it.
+        if (!ctx.scale.showsNonWorking && !ctx.calendar.isWorkingDay(date)) {
+            positioned.hiddenDate = formatIsoDate(date);
+        }
+        return positioned;
     }
 }
 

package/src/nodes/content-extent.ts

@@ -0,0 +1,107 @@
+// content-extent — shared helpers that measure how far right placed
+// content reaches. `maxLeafItemRightX` measures the rightmost edge
+// reached by leaf item bars inside a set of swimlanes, recursing
+// through nested swimlanes and group/parallel `children`;
+// `trackChildPaintedRightX` measures everything one track child paints,
+// spilled captions included.
+//
+// A `PositionedItem.box` is always the bar itself, never a spilled
+// caption (see `PositionedItem.textSpills`), so the leaf walk is immune
+// to caption spill by construction. That makes it a stricter measure
+// than `RowPacker.usedRightX()` / `SwimlaneNode`'s `usedRightX`,
+// which both fold in `spillX` (the caption's reserved column).
+//
+// Used by:
+//   - Finalize's timeline extension (`extendTimeline`, f2), which
+//     grows the date window to cover overflowing content boxes
+//     without letting overhanging captions drag it out too.
+//   - `buildIncludeRegions`, to size the dashed include bracket to
+//     its nested content's bars rather than a spilled caption.
+//
+// `maxSpilledCaptionRightX` is the other half of f2: a spilled caption
+// past the axis end grows the axis by the one column it was capped to.
+
+import { containerHeaderRightX } from '../container-header-geometry.js';
+import type { PositionedSwimlane, PositionedTrackChild } from '../types.js';
+
+/**
+ * Rightmost x anything in a placed track child paints: an item's bar, its
+ * spilled caption, decorations and chips; a group's or parallel's box, its
+ * header (a title may run past the bracket's end) and, recursively, its
+ * children. A container's box spans only its dates, so a caption one of its
+ * children spills past that edge shows up here and nowhere else. The row
+ * track feeds it to the packer so the canvas grows to it.
+ */
+export function trackChildPaintedRightX(child: PositionedTrackChild): number {
+    if (child.kind === 'item') {
+        // `decorationsRightX` leads the spill column even when nothing
+        // spills, so it counts only when something does.
+        const spills =
+            child.textSpills || child.dotSpills || child.iconSpills || child.footnoteSpills;
+        return Math.max(
+            child.box.x + child.box.width,
+            spills ? child.decorationsRightX : Number.NEGATIVE_INFINITY,
+            child.chipsOutside ? child.chipsRightX : Number.NEGATIVE_INFINITY,
+        );
+    }
+    let right = Math.max(child.box.x + child.box.width, containerHeaderRightX(child));
+    for (const sub of child.children) right = Math.max(right, trackChildPaintedRightX(sub));
+    return right;
+}
+
+/** Rightmost x reached by any leaf item bar across `swimlanes`, recursing
+ *  into nested swimlanes and group/parallel children. Returns 0 when the
+ *  set contains no items — callers combine this with another baseline
+ *  (e.g. `originX` or a chrome-derived minimum) via `Math.max`. */
+export function maxLeafItemRightX(swimlanes: PositionedSwimlane[]): number {
+    let max = 0;
+    for (const lane of swimlanes) {
+        max = Math.max(max, maxTrackChildRightX(lane.children));
+        if (lane.nested.length > 0) {
+            max = Math.max(max, maxLeafItemRightX(lane.nested));
+        }
+    }
+    return max;
+}
+
+function maxTrackChildRightX(children: PositionedTrackChild[]): number {
+    let max = 0;
+    for (const child of children) {
+        if (child.kind === 'item') {
+            max = Math.max(max, child.box.x + child.box.width);
+        } else {
+            max = Math.max(max, maxTrackChildRightX(child.children));
+        }
+    }
+    return max;
+}
+
+/**
+ * Rightmost x a spilled item caption reaches across `swimlanes` (its spill
+ * column: icon, caption, footnotes, dot), recursing like
+ * `maxLeafItemRightX`; 0 when no caption spills. Finalize f2 grows the
+ * axis by one column for a caption that ends past it (specs/rendering.md
+ * § "Caption cap at the chart's end").
+ */
+export function maxSpilledCaptionRightX(swimlanes: PositionedSwimlane[]): number {
+    let max = 0;
+    for (const lane of swimlanes) {
+        max = Math.max(max, maxTrackChildCaptionRightX(lane.children));
+        if (lane.nested.length > 0) {
+            max = Math.max(max, maxSpilledCaptionRightX(lane.nested));
+        }
+    }
+    return max;
+}
+
+function maxTrackChildCaptionRightX(children: PositionedTrackChild[]): number {
+    let max = 0;
+    for (const child of children) {
+        if (child.kind === 'item') {
+            if (child.textSpills) max = Math.max(max, child.decorationsRightX);
+        } else {
+            max = Math.max(max, maxTrackChildCaptionRightX(child.children));
+        }
+    }
+    return max;
+}

package/src/nodes/dependency-edges.ts

@@ -0,0 +1,171 @@
+// Dependency edges (finalize step f11): every `after:` reference of a
+// placed item becomes an arrow on the dates (specs/true-width-layout.md
+// §3.4), its ends read off the final model. The host chart and each
+// isolated region route their own, among their own lanes.
+
+import type { ItemDeclaration, SwimlaneDeclaration } from '@nowline/core';
+import { isItemDeclaration } from '@nowline/core';
+import { trackNodes } from '@nowline/core/internal';
+import { containerHeaderRightX } from '../container-header-geometry.js';
+import { propValues } from '../dsl-utils.js';
+import {
+    type ArrowEnd,
+    arrowHead,
+    type DependencyRouteRequest,
+    type RouteObstacles,
+    routeDependencies,
+} from '../edge-routing.js';
+import { containerArrowEnd, itemArrowEnd } from '../item-port-geometry.js';
+import type { LayoutContext } from '../layout-context.js';
+import { resolveStyle } from '../style-resolution.js';
+import type {
+    PositionedDependencyEdge,
+    PositionedGroup,
+    PositionedIncludeRegion,
+    PositionedParallel,
+    PositionedSwimlane,
+    PositionedTrackChild,
+} from '../types.js';
+import { trackChildPaintedRightX } from './content-extent.js';
+import { syntheticItemKey } from './sequence-item.js';
+
+// Every item under the lanes, keyed by id. Title-only items register under a
+// synthetic, non-referenceable handle so they still appear as dependency-edge
+// targets.
+export function collectItems(swimlanes: SwimlaneDeclaration[]): Map<string, ItemDeclaration> {
+    const out = new Map<string, ItemDeclaration>();
+    for (const node of trackNodes(swimlanes)) {
+        if (isItemDeclaration(node)) out.set(node.name ?? syntheticItemKey(node), node);
+    }
+    return out;
+}
+
+/** A target that starts within this of a marker's date touches its line. */
+const ON_LINE_PX = 0.01;
+
+/**
+ * What the router must route around, and every group and parallel by id
+ * (the containers an `after:` may name), from the lanes it routes among.
+ * Include regions in `includes` count as obstacles only: their own arrows
+ * are routed separately.
+ */
+function collectRouting(
+    swimlanes: PositionedSwimlane[],
+    includes: PositionedIncludeRegion[],
+): { obstacles: RouteObstacles; containers: Map<string, PositionedGroup | PositionedParallel> } {
+    const obstacles: RouteObstacles = { blocks: [], edges: [] };
+    const containers = new Map<string, PositionedGroup | PositionedParallel>();
+    const line = (x: number, width: number, y: number): void => {
+        obstacles.blocks.push({ x, y, width, height: 0 });
+    };
+    const visitChild = (child: PositionedTrackChild, register: boolean): void => {
+        const { box } = child;
+        if (child.kind === 'item') {
+            // The bar with whatever it spills right of itself (caption,
+            // decorations, chips), so a horizontal leg stays out of the text.
+            obstacles.blocks.push({ ...box, width: trackChildPaintedRightX(child) - box.x });
+            obstacles.edges.push(
+                { x: box.x, top: box.y, bottom: box.y + box.height },
+                { x: box.x + box.width, top: box.y, bottom: box.y + box.height },
+            );
+            return;
+        }
+        if (register && child.id) containers.set(child.id, child);
+        if (!(child.kind === 'group' && child.waveOnly)) {
+            if (child.headerHeight > 0) {
+                obstacles.blocks.push({
+                    x: box.x,
+                    y: box.y,
+                    width: Math.max(box.width, containerHeaderRightX(child) - box.x),
+                    height: child.headerHeight,
+                });
+            }
+            // Nor along the body's bottom edge.
+            line(box.x, box.width, box.y + box.height);
+            obstacles.edges.push(
+                { x: box.x, top: box.y, bottom: box.y + box.height },
+                { x: box.x + box.width, top: box.y, bottom: box.y + box.height },
+            );
+        }
+        for (const sub of child.children) visitChild(sub, register);
+    };
+    const visitLane = (lane: PositionedSwimlane, register: boolean): void => {
+        // A leg never runs along a lane's edge.
+        line(lane.box.x, lane.box.width, lane.box.y);
+        line(lane.box.x, lane.box.width, lane.box.y + lane.box.height);
+        for (const child of lane.children) visitChild(child, register);
+        for (const nested of lane.nested) visitLane(nested, register);
+    };
+    for (const lane of swimlanes) visitLane(lane, true);
+    // A region's containers are not referenceable from the host.
+    for (const region of includes) {
+        line(region.box.x, region.box.width, region.box.y);
+        line(region.box.x, region.box.width, region.box.y + region.box.height);
+        for (const lane of region.nestedSwimlanes) visitLane(lane, false);
+    }
+    return { obstacles, containers };
+}
+
+export function buildDependencies(
+    items: Map<string, ItemDeclaration>,
+    swimlanes: PositionedSwimlane[],
+    includes: PositionedIncludeRegion[],
+    ctx: LayoutContext,
+): PositionedDependencyEdge[] {
+    const { obstacles, containers } = collectRouting(swimlanes, includes);
+    const bandwidth = ctx.bandScale.bandwidth();
+    const style = resolveStyle('item', [], ctx.styleCtx);
+    // Each slot keeps the arrow's place in `after:` order, whichever way it
+    // is built, so the model lists arrows as the file declares them.
+    const slots: Array<PositionedDependencyEdge | DependencyRouteRequest | null> = [];
+
+    for (const [id, item] of items) {
+        const placed = ctx.placedItems.get(id);
+        if (!placed) continue;
+        const target = itemArrowEnd(placed, bandwidth);
+        for (const pred of propValues(item.properties, 'after')) {
+            const predItem = ctx.placedItems.get(pred);
+            const predContainer = predItem ? undefined : containers.get(pred);
+            let source: ArrowEnd | undefined;
+            if (predItem) source = itemArrowEnd(predItem, bandwidth);
+            else if (predContainer) source = containerArrowEnd(predContainer);
+            if (source) {
+                slots.push({ fromId: pred, toId: id, source, target });
+                continue;
+            }
+            // An anchor or milestone: its cut line is the stem. An item that
+            // starts on it touches the line and needs no arrow; one that
+            // starts later gets a dotted stub from the line to its start
+            // (specs/true-width-layout.md §3.5).
+            const marker = ctx.entityMidpoints.get(pred);
+            if (!marker || target.startX - marker.x <= ON_LINE_PX) continue;
+            const y = target.rowY ?? target.top;
+            slots.push({
+                fromId: pred,
+                toId: id,
+                waypoints: [
+                    { x: marker.x, y },
+                    { x: target.paintedX, y },
+                ],
+                slack: true,
+                ...arrowHead(target.bottom - target.top),
+                style,
+            });
+        }
+    }
+
+    const requests = slots.filter((s): s is DependencyRouteRequest => s !== null && 'source' in s);
+    const routed = routeDependencies(requests, obstacles, ctx.scale.pixelsPerDay);
+    const byRequest = new Map(requests.map((r, i) => [r, routed[i]]));
+    const out: PositionedDependencyEdge[] = [];
+    for (const slot of slots) {
+        if (!slot) continue;
+        if (!('source' in slot)) {
+            out.push(slot);
+            continue;
+        }
+        const r = byRequest.get(slot);
+        if (r) out.push({ ...r, style });
+    }
+    return out;
+}

package/src/nodes/footnote-node.ts

@@ -1,60 +1,200 @@
-// FootnoteNode + buildFootnotes — footnote area at the bottom of the
-// chart. Each footnote gets a stable index (1-based, sorted by id) and
+// FootnoteNode + indexFootnotes / buildFootnotePanel — footnote area at the bottom of the
+// chart. Each footnote gets a stable index (1-based, in document order) 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.
+// emit the matching superscript indicators. An isolated region's
+// footnotes continue the numbering after the host's, in include order,
+// and share the one panel under a heading row with the region's title.
+// An entry whose text does not fit the panel's width wraps onto more
+// rows at the title's x. The panel grows to fit: 28 px header + (entry
+// rows and region headings × 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 { estimateTextWidth, wrapText } from '../text-measure.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';
+import type {
+    BoundingBox,
+    PositionedFootnoteArea,
+    PositionedFootnoteEntry,
+    PositionedFootnoteLine,
+} from '../types.js';
 
-export interface BuiltFootnotes {
-    area: PositionedFootnoteArea;
+/** Each footnote's 1-based number (in document order) and its `on:` host ids. */
+export interface FootnoteIndex {
     index: Map<string, number>;
     hosts: Map<string, string[]>;
 }
 
-export function buildFootnotes(
+/**
+ * Pure: depends only on the footnote declarations. Numbers start after
+ * `precedingCount` (an isolated region continues after the host and the
+ * regions before it). The map's order is document order: the resolver
+ * inserts a file's own footnotes as declared, then each merged include's.
+ */
+export function indexFootnotes(
     footnotes: Map<string, FootnoteDeclaration>,
-    ctx: LayoutContext,
-    chartBottomY: number,
-): BuiltFootnotes {
-    const entries: PositionedFootnoteEntry[] = [];
+    precedingCount = 0,
+): FootnoteIndex {
     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);
+    [...footnotes.entries()].forEach(([id, f], i) => {
+        index.set(id, precedingCount + i + 1);
         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),
-        });
     });
+    return { index, hosts };
+}
+
+/** An isolated region's footnotes, numbered and styled by its own context. */
+export interface RegionFootnotes {
+    /** The region's title, as on its label tab. */
+    title: string;
+    footnotes: Map<string, FootnoteDeclaration>;
+    ctx: LayoutContext;
+}
+
+/** Font sizes (px) of an entry's title and description. */
+const FOOTNOTE_TEXT_FONT_SIZE_PX = 11;
+/** The description column never starts closer than this to the title's x. */
+const FOOTNOTE_DESCRIPTION_MIN_OFFSET_PX = 120;
+/** Per-character advance the description column is placed by. */
+const FOOTNOTE_TITLE_CHAR_ADVANCE_PX = 6;
+const DESCRIPTION_LEAD = '— ';
+
+/**
+ * The panel below the chart, spanning the final canvas (`chartRightX`):
+ * the host's footnotes, then each region's under its title, each in
+ * document order. The canvas does not grow for the panel: an entry whose
+ * title or description runs past the panel's inner right edge wraps onto
+ * more rows, which start at the title's x and use the whole width.
+ */
+export function buildFootnotePanel(
+    footnotes: Map<string, FootnoteDeclaration>,
+    ctx: LayoutContext,
+    chartBottomY: number,
+    chartRightX: number,
+    regions: readonly RegionFootnotes[] = [],
+): PositionedFootnoteArea {
+    const boxX = FOOTNOTE_PANEL_PADDING_PX;
+    const boxY = chartBottomY + FOOTNOTE_PANEL_PADDING_PX;
+    const boxWidth = chartRightX - 2 * FOOTNOTE_PANEL_PADDING_PX;
+    const titleX = boxX + 2 * FOOTNOTE_PANEL_PADDING_PX;
+    const textRightX = boxX + boxWidth - FOOTNOTE_PANEL_PADDING_PX;
+    const firstRowY = boxY + FOOTNOTE_HEADER_HEIGHT_PX + FOOTNOTE_PANEL_PADDING_PX;
+    const entries: PositionedFootnoteEntry[] = [];
+    let row = 0;
+    const add = (
+        decls: Map<string, FootnoteDeclaration>,
+        source: LayoutContext,
+        region?: string,
+    ): void => {
+        for (const [id, f] of decls) {
+            const title = f.title ?? id;
+            const description = f.description?.text;
+            const lines = entryLines(title, description, titleX, textRightX);
+            const y = firstRowY + row * FOOTNOTE_ROW_HEIGHT;
+            const at = (l: { x: number; row: number; text: string }): PositionedFootnoteLine => ({
+                x: l.x,
+                y: y + l.row * FOOTNOTE_ROW_HEIGHT,
+                text: l.text,
+            });
+            const entry: PositionedFootnoteEntry = {
+                number: source.footnoteIndex.get(id) ?? entries.length + 1,
+                y,
+                title,
+                titleLines: lines.title.map(at),
+                description,
+                style: resolveStyle('footnote', f.properties, source.styleCtx),
+            };
+            if (lines.description.length > 0) entry.descriptionLines = lines.description.map(at);
+            if (region !== undefined) entry.region = region;
+            entries.push(entry);
+            row += lines.rows;
+        }
+    };
+    add(footnotes, ctx);
+    for (const r of regions) {
+        if (r.footnotes.size === 0) continue;
+        // The region's heading takes a row of its own above its entries.
+        const headingY = firstRowY + row * FOOTNOTE_ROW_HEIGHT;
+        row += 1;
+        const first = entries.length;
+        add(r.footnotes, r.ctx, r.title);
+        entries[first].regionHeadingY = headingY;
+    }
     const box: BoundingBox = {
-        x: FOOTNOTE_PANEL_PADDING_PX,
-        y: chartBottomY + FOOTNOTE_PANEL_PADDING_PX,
-        width: ctx.chartRightX - 2 * FOOTNOTE_PANEL_PADDING_PX,
+        x: boxX,
+        y: boxY,
+        width: boxWidth,
         height:
             entries.length === 0
                 ? 0
-                : FOOTNOTE_HEADER_HEIGHT_PX +
-                  entries.length * FOOTNOTE_ROW_HEIGHT +
-                  FOOTNOTE_PANEL_PADDING_PX,
+                : FOOTNOTE_HEADER_HEIGHT_PX + row * FOOTNOTE_ROW_HEIGHT + FOOTNOTE_PANEL_PADDING_PX,
     };
+    return { box, entries };
+}
+
+interface EntryLine {
+    x: number;
+    /** Rows below the entry's first row. */
+    row: number;
+    text: string;
+}
+
+/**
+ * Wrap one entry into rows. The title starts at `titleX`; the description
+ * follows on the title's row at the description column (`— ` first) and
+ * wraps at `titleX`. A wrapped title, or a description whose first word
+ * does not fit beside the title, starts the description on a row of its
+ * own. A single word wider than the panel stays whole on its row, as
+ * `wrapText` never splits a word.
+ */
+function entryLines(
+    title: string,
+    description: string | undefined,
+    titleX: number,
+    textRightX: number,
+): { title: EntryLine[]; description: EntryLine[]; rows: number } {
+    const fullWidth = textRightX - titleX;
+    const titleRows = fitsOrWraps(title, fullWidth, fullWidth);
+    const titleLines = titleRows.map((text, row) => ({ x: titleX, row, text }));
+    if (!description) return { title: titleLines, description: [], rows: titleRows.length };
+
+    const leadWidth = estimateTextWidth(DESCRIPTION_LEAD, FOOTNOTE_TEXT_FONT_SIZE_PX);
+    const firstWord = description.trim().split(/\s+/)[0] ?? '';
+    const columnX =
+        titleX +
+        Math.max(FOOTNOTE_DESCRIPTION_MIN_OFFSET_PX, title.length * FOOTNOTE_TITLE_CHAR_ADVANCE_PX);
+    const besideTitle =
+        titleRows.length === 1 &&
+        leadWidth + estimateTextWidth(firstWord, FOOTNOTE_TEXT_FONT_SIZE_PX) <=
+            textRightX - columnX;
+    const firstX = besideTitle ? columnX : titleX;
+    const firstRow = besideTitle ? titleRows.length - 1 : titleRows.length;
+    const rows = fitsOrWraps(description, fullWidth, textRightX - firstX - leadWidth);
+    const descriptionLines = rows.map((text, i) => ({
+        x: i === 0 ? firstX : titleX,
+        row: firstRow + i,
+        text: i === 0 ? `${DESCRIPTION_LEAD}${text}` : text,
+    }));
     return {
-        area: { box, entries },
-        index,
-        hosts,
+        title: titleLines,
+        description: descriptionLines,
+        rows: firstRow + rows.length,
     };
 }
+
+/**
+ * `text` as is when it fits `firstWidth`, else wrapped (`wrapText`, which
+ * collapses whitespace), so an entry that fits keeps its exact text.
+ */
+function fitsOrWraps(text: string, width: number, firstWidth: number): string[] {
+    if (estimateTextWidth(text, FOOTNOTE_TEXT_FONT_SIZE_PX) <= firstWidth) return [text];
+    const rows = wrapText(text, width, FOOTNOTE_TEXT_FONT_SIZE_PX, firstWidth);
+    return rows.length > 0 ? rows : [text];
+}