@nowline/layout 0.8.6 → 0.9.0

package/src/layout-context.ts

@@ -1,19 +1,26 @@
-// Layout context — shared internal types used by `layout.ts` and the
-// node files under `nodes/`. Extracted so per-entity nodes (e.g.
-// `swimlane-node.ts`) can type their inputs without forcing a circular
-// import on the production composition root in `layout.ts`.
+// Layout context — shared internal types used by the layout phases
+// (`phases/`) and the node files under `nodes/`. Extracted so per-entity
+// nodes (e.g. `swimlane-node.ts`) can type their inputs without importing
+// the phases that drive them.
 
-import type {
-    EntityProperty,
-    GroupBlock,
-    ItemDeclaration,
-    LabelDeclaration,
-    ParallelBlock,
-    SymbolDeclaration,
+import {
+    type GroupBlock,
+    type ItemDeclaration,
+    isTeamDeclaration,
+    type LabelDeclaration,
+    type ParallelBlock,
+    type ResolvedConfig,
+    type ResolvedContent,
+    type SymbolDeclaration,
+    type TeamDeclaration,
 } from '@nowline/core';
+import type { AxisColumns } from './axis-columns.js';
 import type { BandScale } from './band-scale.js';
-import type { resolveCalendar } from './calendar.js';
+import { type resolveCalendar, resolveSizes } from './calendar.js';
+import type { FootnoteIndex } from './nodes/footnote-node.js';
+import type { RoadmapSchedule } from './schedule.js';
 import type { StyleContext } from './style-resolution.js';
+import type { Theme } from './themes/shape.js';
 import type { TimeScale } from './time-scale.js';
 import type {
     MarkerRowPlacement,
@@ -24,22 +31,49 @@ import type {
     ResolvedSize,
     SlackCorridor,
 } from './types.js';
+import type { WaveLayoutState } from './wave-layout.js';
 import type { WorkingCalendar } from './working-calendar.js';
 
 /** Slim accumulator used while sequencing items into a track. */
 export interface TrackCursor {
-    /** Left edge where the next item begins. */
+    /**
+     * Where the next item begins, in time: the last child's duration end
+     * (a block's latest track end), never a caption spill. A bar spans
+     * exactly its dates, so this is also its painted end
+     * (specs/true-width-layout.md §3.1).
+     */
     x: number;
+    /**
+     * Where the child placed last begins, in time: an item's start date, a
+     * block's earliest child start. A container's bracket and body open
+     * here (specs/true-width-layout.md §3.3).
+     */
+    startX: number;
     /** Top edge of the current row. */
     y: number;
     /** Accumulated height of the track. */
     height: number;
-    /** Rightmost edge reached. */
-    maxX: number;
 }
 
 export function newCursor(x: number, y: number): TrackCursor {
-    return { x, y, height: 0, maxX: x };
+    return { x, startX: x, y, height: 0 };
+}
+
+/**
+ * The working-day duration the day schedule gave `item`. Every item engine A
+ * lays out is in `schedule.byNode` (the main lanes and the first-level
+ * isolated regions it draws), so a miss is an invariant violation, a
+ * schedule built for another roadmap or a walker that skipped a node, and
+ * throws instead of falling back to a second derivation that could drift.
+ */
+export function scheduledItemDays(ctx: LayoutContext, item: ItemDeclaration): number {
+    const scheduled = ctx.schedule.byNode.get(item);
+    if (!scheduled) {
+        throw new Error(
+            `layout: item "${item.name ?? item.title ?? '(unnamed)'}" is not in the day schedule`,
+        );
+    }
+    return scheduled.days;
 }
 
 /**
@@ -49,10 +83,18 @@ export function newCursor(x: number, y: number): TrackCursor {
  */
 export interface LayoutContext {
     cal: ReturnType<typeof resolveCalendar>;
+    /**
+     * The roadmap's day schedule (engine C), shared by the main lanes and
+     * every isolated region's context. Item durations in working days come
+     * from `schedule.byNode` (`scheduledItemDays`), never from re-deriving
+     * them against the sizes (specs/scheduler-unification.md §3.4).
+     */
+    schedule: RoadmapSchedule;
     styleCtx: StyleContext;
     sizes: Map<string, ResolvedSize>;
     labels: Map<string, LabelDeclaration>;
-    teams: Map<string, import('@nowline/core').TeamDeclaration>;
+    /** Every team by id, the ones nested in another team included. */
+    teams: Map<string, TeamDeclaration>;
     persons: Map<string, import('@nowline/core').PersonDeclaration>;
     /**
      * Custom `symbol` declarations from `ResolvedConfig.symbols`. Used by
@@ -67,31 +109,42 @@ export interface LayoutContext {
     timeline: PositionedTimelineScale;
     scale: TimeScale;
     calendar: WorkingCalendar;
+    /**
+     * The natural axis as tick columns, for the caption cap at the chart's
+     * end (`measureItem`). Shared by the main lanes and every isolated
+     * region; omitted by contexts built outside the place phase, which then
+     * cap no caption.
+     */
+    axisColumns?: AxisColumns;
     bandScale: BandScale;
     entityLeftEdges: Map<string, number>;
     entityRightEdges: Map<string, number>;
+    /**
+     * Midpoint per MARKER (anchor or milestone), on the marker row.
+     * Dependency arrows from a marker start on its cut line at this `x`.
+     * Items are not in this map: their attach geometry is derived from
+     * `placedItems`.
+     */
     entityMidpoints: Map<string, Point>;
     /**
-     * Visual edges for items (entries with a painted bar). Differs
-     * from `entityLeftEdges`/`entityRightEdges` (logical column
-     * boundaries) by `ITEM_INSET_PX` on each side so dependency
-     * arrows attach to the painted bar edge instead of landing in
-     * the inter-column gutter. Anchors and milestones are absent —
-     * their attach geometry uses `(center.x, target.row.midY)` on
-     * the cut line, computed inline by `buildDependencies`.
+     * The ids of the anchors and milestones this context's file declares.
+     * A milestone's slack or overrun arrow from one of them starts on its
+     * row in the marker band, which only the final pack knows, so
+     * placement records the marker instead of a y.
      */
-    entityVisualLeftX: Map<string, number>;
-    entityVisualRightX: Map<string, number>;
+    markerIds: ReadonlySet<string>;
     /**
-     * Per-item exit point for `after:` dependency arrows leaving
-     * this entity. Default = `(visualRight, midY)`. When the
-     * caption spills past the bar's right edge (`textSpills`), the
-     * exit drops to `(box.x + box.width / 2, box.y + box.height)`
-     * — the bottom-middle of the progress strip — so the arrow
-     * doesn't visually pierce the spilled title/meta text to the
-     * right of the bar.
+     * Every placed item, keyed by its draw key (the explicit id, or the
+     * synthetic handle of an id-less item; see `syntheticItemKey`). The
+     * value is the same `PositionedItem` object the positioned model
+     * carries, so it always holds the item's FINAL box, however many
+     * times a retroactive row growth or a marker-band growth moved it
+     * down after placement. Dependency-arrow ports and slack-arrow attach
+     * points are derived from that box when the arrows are built (see
+     * `item-port-geometry.ts`), never captured as absolute coordinates
+     * while the item is placed.
      */
-    itemArrowSource: Map<string, Point>;
+    placedItems: Map<string, PositionedItem>;
     /**
      * Flow key for each item, used to dedupe milestone slack arrows.
      * A "flow" is the deepest enclosing single-track container —
@@ -109,15 +162,6 @@ export interface LayoutContext {
      * value to populate `itemFlowKey`.
      */
     currentFlowKey: string;
-    /**
-     * Y coordinate where milestone slack arrows attach for each item id.
-     * Defaults to the item's row midpoint; when an item's caption spills
-     * past the bar's right edge, drops to the progress-strip's vertical
-     * center (`box.y + box.height - PROGRESS_STRIP_HEIGHT_PX / 2`) so the
-     * arrow stays clear of the spilled title/meta line and visually
-     * aligns with the bottom-edge progress bar instead.
-     */
-    itemSlackAttachY: Map<string, number>;
     /**
      * Horizontal arrow corridors that the swimlane row-packer must avoid.
      * Empty during the first layout pass; populated from the first
@@ -127,12 +171,19 @@ export interface LayoutContext {
      */
     slackCorridors: SlackCorridor[];
     /**
-     * Pre-computed marker-row placement (row index + label box + side)
-     * for every anchor and date-pinned milestone. After-only milestones
-     * pack against this map at build time; date-pinned entries are
-     * snapshot upstream so their (Y, label) survives swimlane reflows.
+     * Marker-row placement (row index + label box + side). While lanes
+     * are placed it holds a copy of the measure phase's pre-pack of every
+     * date-pinned anchor and milestone; finalize then replaces it with the
+     * final pack (f5), which adds after-only milestones and the calendar
+     * runs, before milestones are positioned (f6) and anchors built (f10).
      */
     markerRowPlacements: Map<string, MarkerRowPlacement>;
+    /**
+     * The chart's top. Placement lays the chart out in local coordinates,
+     * with the top at 0; finalize translates every placed y once, by the
+     * final top, when the header rows above it stop growing (f7), and
+     * sets this to that top. A region's context keeps its local value.
+     */
     chartTopY: number;
     chartBottomY: number;
     /**
@@ -144,7 +195,6 @@ export interface LayoutContext {
      * to thread the entire timeline strip.
      */
     swimlaneBottomY: number;
-    chartRightX: number;
     /**
      * Monotonic counters for id-less `parallel` / `group` blocks. Each
      * swimlane-loop pass resets both to zero; blocks without an explicit
@@ -153,38 +203,126 @@ export interface LayoutContext {
      */
     nextParallelId: number;
     nextGroupId: number;
+    /**
+     * Wave barrier state (specs/waves.md §8.4), shared by the main lanes
+     * and every isolated region's context. Undefined when the roadmap
+     * declares no waves.
+     */
+    waves?: WaveLayoutState;
 }
 
 /**
- * Bundle of layout-internal helper callbacks injected from `layout.ts`
- * into the per-entity Renderable nodes. Keeping the helpers in
- * `layout.ts` (rather than splitting them across many tiny files) means
- * the nodes stay small and importable without a runtime cycle: they
- * receive the helpers at construction time via this struct.
+ * `teams` plus every team nested in one of them, so an `owner:` naming a
+ * nested team resolves to its title. The resolved content keys only the
+ * file's top-level declarations. A top-level id wins over a nested one.
+ */
+function withNestedTeams(teams: Map<string, TeamDeclaration>): Map<string, TeamDeclaration> {
+    const out = new Map(teams);
+    const visit = (team: TeamDeclaration): void => {
+        for (const member of team.content) {
+            if (!isTeamDeclaration(member)) continue;
+            if (member.name && !out.has(member.name)) out.set(member.name, member);
+            visit(member);
+        }
+    };
+    for (const team of teams.values()) visit(team);
+    return out;
+}
+
+/** The per-file half of a context: the root file, or an isolated region. */
+export interface ContextSource {
+    config: Pick<ResolvedConfig, 'styles' | 'defaults' | 'symbols'>;
+    content: Pick<
+        ResolvedContent,
+        'sizes' | 'labels' | 'teams' | 'persons' | 'anchors' | 'milestones'
+    >;
+}
+
+/**
+ * Build a `LayoutContext` for the root file or for an isolated region.
+ * `chart` passes the chart extents through unchanged: the root sets
+ * `chartTopY` to the local top 0 with both bottoms at 0, a region sets all
+ * three y fields to its inner start. The canvas width is not part of a
+ * context: placement never reads it (finalize owns the `CanvasExtent`).
+ * A region passes its own footnote index, numbered on after the host's,
+ * and no marker placements. The caller seeds
+ * the wave edges.
+ */
+export function createLayoutContext(
+    source: ContextSource,
+    shared: {
+        theme: Theme;
+        cal: ReturnType<typeof resolveCalendar>;
+        schedule: RoadmapSchedule;
+        timeline: PositionedTimelineScale;
+        scale: TimeScale;
+        calendar: WorkingCalendar;
+        axisColumns?: AxisColumns;
+        bandScale: BandScale;
+        waves?: WaveLayoutState;
+    },
+    chart: Pick<LayoutContext, 'chartTopY' | 'chartBottomY' | 'swimlaneBottomY'>,
+    init: {
+        footnotes?: FootnoteIndex;
+        markerRowPlacements?: Map<string, MarkerRowPlacement>;
+    },
+): LayoutContext {
+    return {
+        cal: shared.cal,
+        schedule: shared.schedule,
+        styleCtx: {
+            theme: shared.theme,
+            styles: source.config.styles,
+            defaults: source.config.defaults,
+            labels: source.content.labels,
+        },
+        // Each file declares its own sizes, resolved under the host's
+        // calendar so a region's sized items render at the host's
+        // pixels-per-day scale.
+        sizes: resolveSizes(source.content.sizes, shared.cal),
+        labels: source.content.labels,
+        teams: withNestedTeams(source.content.teams),
+        persons: source.content.persons,
+        symbols: source.config.symbols,
+        footnoteIndex: init.footnotes?.index ?? new Map(),
+        footnoteHosts: init.footnotes?.hosts ?? new Map(),
+        timeline: shared.timeline,
+        scale: shared.scale,
+        calendar: shared.calendar,
+        ...(shared.axisColumns ? { axisColumns: shared.axisColumns } : {}),
+        bandScale: shared.bandScale,
+        entityLeftEdges: new Map(),
+        entityRightEdges: new Map(),
+        entityMidpoints: new Map(),
+        markerIds: new Set([...source.content.anchors.keys(), ...source.content.milestones.keys()]),
+        placedItems: new Map(),
+        itemFlowKey: new Map(),
+        currentFlowKey: '',
+        slackCorridors: [],
+        markerRowPlacements: init.markerRowPlacements ?? new Map(),
+        chartTopY: chart.chartTopY,
+        chartBottomY: chart.chartBottomY,
+        swimlaneBottomY: chart.swimlaneBottomY,
+        nextParallelId: 0,
+        nextGroupId: 0,
+        // Wave floors are dates projected with the unclamped scale
+        // (specs/waves.md §5.1); a region shares the host's wave state
+        // (§8.4) so its lanes are floored and accumulate into the same pass.
+        ...(shared.waves ? { waves: shared.waves } : {}),
+    };
+}
+
+/**
+ * The helpers the place phase injects into the nodes. Everything else a
+ * node needs it imports; `sequenceOne` (`nodes/sequence-one.ts`) stays
+ * injected because it dispatches to `GroupNode` and `ParallelNode`, which
+ * call it for their nested blocks: importing it there would form a cycle
+ * (specs/layout-phases.md §3.8, §8 decision 4).
  */
 export interface LayoutHelpers {
-    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 height an item's wrapped label-chip rows will
-     *  add, so callers can size the row pitch BEFORE handing off to
-     *  `sequenceItem`. Returns 0 when the item's labels all fit on a
-     *  single chip row. */
-    predictItemChipExtraHeight: (item: ItemDeclaration, ctx: LayoutContext) => number;
 }

package/src/layout-insights.ts

@@ -2,7 +2,7 @@
 // model. Informational by default; warnings only when author intent is lost
 // (e.g. now-line outside the date window).
 
-import { type MessageCode, tr } from '@nowline/core';
+import { type I1006Args, type MessageCode, tr } from '@nowline/core';
 import { MIN_BAR_WIDTH_FOR_DOT_PX } from './item-bar-geometry.js';
 import type {
     PositionedItem,
@@ -32,8 +32,17 @@ function formatIsoDate(d: Date): string {
     return d.toISOString().slice(0, 10);
 }
 
+/**
+ * The name an insight echoes for an item: its id, else its title. A title
+ * can carry explicit `\n` line breaks (they paint as separate lines in the
+ * chart), but an insight message is one line of text, so each break run
+ * collapses to a single space.
+ */
 function itemLabel(item: PositionedItem): string {
-    return item.id ?? item.title;
+    if (item.id !== undefined) return item.id;
+    return /[\r\n]/.test(item.title)
+        ? item.title.replace(/\s*[\r\n]+\s*/g, ' ').trim()
+        : item.title;
 }
 
 function walkTrackChildren(
@@ -76,6 +85,27 @@ function collectItemInsights(item: PositionedItem, locale: string, out: LayoutIn
             makeInsight(locale, 'NL.I1003', 'info', { name, anchor: item.overflowAnchorId }, name),
         );
     }
+    collectNonWorkingPinInsight(item, locale, out);
+}
+
+/** NL.I1008 (specs/working-calendar.md §6): an `after:` date on a non-working day set the start. */
+function collectNonWorkingPinInsight(
+    item: PositionedItem,
+    locale: string,
+    out: LayoutInsight[],
+): void {
+    const pin = item.nonWorkingPin;
+    if (!pin) return;
+    const name = itemLabel(item);
+    out.push(
+        makeInsight(
+            locale,
+            'NL.I1008',
+            'info',
+            { name, pin: pin.pin, key: pin.key, start: pin.start },
+            name,
+        ),
+    );
 }
 
 function makeInsight(
@@ -125,6 +155,77 @@ function collectSwimlaneInsights(
     }
 }
 
+/**
+ * Pin insights on the items of an isolated region's lanes. Region items
+ * carry only the non-working pin (NL.I1008) here; the other item and lane
+ * insights stay main-lane only.
+ */
+function collectRegionItemInsights(
+    lane: PositionedSwimlane,
+    locale: string,
+    out: LayoutInsight[],
+): void {
+    walkTrackChildren(lane.children, (item) => {
+        collectNonWorkingPinInsight(item, locale, out);
+    });
+    for (const nested of lane.nested) {
+        collectRegionItemInsights(nested, locale, out);
+    }
+}
+
+/**
+ * Roadmap-level wave insights (specs/waves.md WV16-WV18): the barrier
+ * driver's pass cap, empty waves (once per roadmap), and dated milestones a
+ * wave overruns. No-ops without waves.
+ */
+function collectWaveInsights(
+    layout: PositionedRoadmap,
+    locale: string,
+    out: LayoutInsight[],
+): void {
+    if (layout.waveSolve?.capped) {
+        out.push(makeInsight(locale, 'NL.W1002', 'warning', { passes: layout.waveSolve.passes }));
+    }
+    const waves = layout.waves ?? [];
+    const empty = waves.filter((w) => w.empty).map((w) => w.id);
+    if (empty.length > 0) {
+        // One consolidated message: the empty waves are not drawn (§9.1).
+        const args: I1006Args = { names: empty };
+        out.push(
+            makeInsight(
+                locale,
+                'NL.I1006',
+                'info',
+                args,
+                empty.length === 1 ? empty[0] : undefined,
+            ),
+        );
+    }
+    for (const m of layout.milestones) {
+        // Only dated milestones get `overrunByWave`, and each carries its
+        // own date as `overrunDate`: x cannot give it back, since a hidden
+        // day shares the next working day's x.
+        if (m.overrunByWave === undefined || m.overrunDate === undefined) continue;
+        const wave = waves.find((w) => w.id === m.overrunByWave);
+        if (!wave) continue;
+        const name = m.id ?? m.title;
+        out.push(
+            makeInsight(
+                locale,
+                'NL.I1007',
+                'info',
+                {
+                    name,
+                    date: m.overrunDate,
+                    wave: wave.id,
+                    end: formatIsoDate(wave.endDate),
+                },
+                name,
+            ),
+        );
+    }
+}
+
 /**
  * Collect layout-derived insights from a positioned roadmap. These describe
  * observable reflow consequences (caption spill, lane packing, etc.), not
@@ -140,6 +241,12 @@ export function collectLayoutInsights(
     for (const lane of layout.swimlanes) {
         collectSwimlaneInsights(lane, locale, out);
     }
+    for (const region of layout.includes) {
+        for (const lane of region.nestedSwimlanes) {
+            collectRegionItemInsights(lane, locale, out);
+        }
+    }
+    collectWaveInsights(layout, locale, out);
 
     if (context.today) {
         const today = context.today;