@nowline/layout 0.0.0-dev.20260601071750.g04bdff9

package/src/lane-utilization.ts

@@ -0,0 +1,259 @@
+// Lane utilization computation per specs/rendering.md § Lane utilization
+// underline.
+//
+// Walks a positioned lane's children (items, plus the items inside parallel
+// and group blocks), collects each contributor's pixel span and capacity load,
+// then sweeps the timeline to produce a list of half-open segments
+// classified `green | yellow | red` against the lane's resolved capacity and
+// thresholds. Adjacent same-classification segments coalesce so the renderer
+// paints one rectangle per color band rather than per event boundary.
+//
+// Pure data in / pure data out — no AST, no theme, no side effects. Lives
+// next to `capacity.ts` (the other capacity-helper module) and is tested in
+// isolation.
+
+import type { DefaultDeclaration, SwimlaneDeclaration } from '@nowline/core';
+import { propValue } from './dsl-utils.js';
+import type {
+    PositionedItem,
+    PositionedLaneUtilization,
+    PositionedTrackChild,
+    PositionedUtilizationSegment,
+    UtilizationClassification,
+} from './types.js';
+
+/**
+ * Built-in defaults used when neither the lane nor its `default swimlane`
+ * declares a threshold. Mirrors specs/dsl.md rule 17d.
+ */
+export const DEFAULT_UTILIZATION_WARN_FRACTION = 0.8; // 80%
+export const DEFAULT_UTILIZATION_OVER_FRACTION = 1.0; // 100%
+
+/**
+ * One contributor to a lane's load function: a single positioned item with
+ * its visual horizontal span and the load it contributes during that span.
+ * Children inside `parallel` / `group` blocks contribute individually so
+ * concurrent load reads correctly (the parallel block itself spans the union
+ * of its children's bars but does not itself add load — only the items do).
+ */
+interface LoadContributor {
+    startX: number;
+    endX: number;
+    load: number;
+}
+
+/**
+ * Walk the lane's positioned children and return one `LoadContributor` per
+ * item that contributes load. Items inside `parallel` and `group` blocks are
+ * descended into recursively; the block envelopes themselves contribute
+ * nothing (they are pure containers).
+ *
+ * `inferItemLoad` mirrors the spec's "Default capacity" table:
+ *   - Explicit `capacity:N` → that value.
+ *   - Sized item without explicit `capacity:` → 1 (the default for sized
+ *     items, matching the duration-derivation default).
+ *   - Duration-literal item without `capacity:` → 0 (the bar paints normally
+ *     but does not contribute load — this is the legacy "uncounted" item
+ *     family from before the size system existed).
+ */
+export function collectLoadContributors(children: PositionedTrackChild[]): LoadContributor[] {
+    const out: LoadContributor[] = [];
+    walk(children, out);
+    return out;
+}
+
+function walk(children: PositionedTrackChild[], out: LoadContributor[]): void {
+    for (const child of children) {
+        if (child.kind === 'item') {
+            const load = inferItemLoad(child);
+            if (load > 0 && child.box.width > 0) {
+                out.push({
+                    startX: child.box.x,
+                    endX: child.box.x + child.box.width,
+                    load,
+                });
+            }
+        } else if (child.kind === 'parallel' || child.kind === 'group') {
+            walk(child.children, out);
+        }
+    }
+}
+
+function inferItemLoad(item: PositionedItem): number {
+    if (item.capacity) return item.capacity.value;
+    if (item.size) return 1;
+    return 0;
+}
+
+/**
+ * Compute a lane's utilization model. Returns `null` when there is no
+ * meaningful underline to paint:
+ *   - Lane has no `capacity:` (no denominator → undefined utilization).
+ *   - Lane has no items contributing load (collectLoadContributors returns
+ *     an empty list).
+ *   - Both thresholds resolve to `none` (caller has opted out of every
+ *     color band; nothing to paint).
+ *
+ * The returned `PositionedLaneUtilization` carries the resolved thresholds
+ * (in fraction form, or `null` for opt-out) alongside the segments so the
+ * renderer can render legends / tooltips without re-resolving anything.
+ */
+export function computeLaneUtilization(opts: {
+    children: PositionedTrackChild[];
+    capacityValue: number;
+    warnFraction: number | null;
+    overFraction: number | null;
+}): PositionedLaneUtilization | null {
+    if (opts.capacityValue <= 0) return null;
+    if (opts.warnFraction === null && opts.overFraction === null) return null;
+
+    const contributors = collectLoadContributors(opts.children);
+    if (contributors.length === 0) return null;
+
+    // Build sorted unique x coordinates from every event boundary.
+    const xSet = new Set<number>();
+    for (const c of contributors) {
+        xSet.add(c.startX);
+        xSet.add(c.endX);
+    }
+    const xs = Array.from(xSet).sort((a, b) => a - b);
+    if (xs.length < 2) return null;
+
+    // Per half-open interval [xs[j], xs[j+1]) compute the active load by
+    // summing every contributor whose span covers the interval midpoint.
+    // O(n²) but n is small (typically <20 items per lane); avoids the
+    // bookkeeping of an event-stream sweep without a measurable cost.
+    const raw: PositionedUtilizationSegment[] = [];
+    for (let j = 0; j < xs.length - 1; j++) {
+        const a = xs[j];
+        const b = xs[j + 1];
+        const mid = (a + b) / 2;
+        let load = 0;
+        for (const c of contributors) {
+            if (c.startX <= mid && mid < c.endX) load += c.load;
+        }
+        raw.push({
+            startX: a,
+            endX: b,
+            load,
+            classification: classifyLoad(
+                load,
+                opts.capacityValue,
+                opts.warnFraction,
+                opts.overFraction,
+            ),
+        });
+    }
+
+    // Coalesce adjacent same-classification segments so the renderer paints
+    // one rectangle per visible color band rather than per event boundary.
+    const segments: PositionedUtilizationSegment[] = [];
+    for (const s of raw) {
+        const last = segments[segments.length - 1];
+        if (last && last.classification === s.classification && last.endX === s.startX) {
+            last.endX = s.endX;
+            // Keep the first interval's `load` as a representative; the
+            // coalesced span may have varying load within a single color
+            // band but renderers paint by class, not by exact load.
+        } else {
+            segments.push({ ...s });
+        }
+    }
+
+    return {
+        segments,
+        capacityValue: opts.capacityValue,
+        warnFraction: opts.warnFraction,
+        overFraction: opts.overFraction,
+    };
+}
+
+/**
+ * Classify a single load value against the lane's resolved capacity and
+ * thresholds. Spec § "Load function and segmentation":
+ *   - `u < warn-at` → green (healthy; includes `u = 0` so the underline
+ *     stays continuous).
+ *   - `warn-at ≤ u < over-at` → yellow.
+ *   - `u ≥ over-at` → red.
+ *
+ * `null` thresholds disable that color band: a `null` warnFraction collapses
+ * to a binary green / red indicator; a `null` overFraction collapses to
+ * green / yellow; both `null` is unreachable here (caller short-circuits
+ * upstream).
+ */
+export function classifyLoad(
+    load: number,
+    capacity: number,
+    warnFraction: number | null,
+    overFraction: number | null,
+): UtilizationClassification {
+    const u = load / capacity;
+    if (overFraction !== null && u >= overFraction) return 'red';
+    if (warnFraction !== null && u >= warnFraction) return 'yellow';
+    return 'green';
+}
+
+/**
+ * Resolve the lane's effective utilization thresholds, applying the spec's
+ * resolution order:
+ *
+ *   1. Lane's own `utilization-warn-at:` / `utilization-over-at:` properties.
+ *   2. The applicable `default swimlane` declaration's properties.
+ *   3. Built-in defaults (`warn-at:80%`, `over-at:100%`).
+ *
+ * Each side resolves independently — a lane can pin only one threshold and
+ * inherit the other from defaults / built-ins. The returned `null` means
+ * "opted out via `none`" and disables that color band downstream.
+ *
+ * Malformed values (already reported by the validator) are treated as
+ * "unset" — the resolver falls through to the next layer rather than
+ * double-reporting.
+ */
+export function resolveLaneUtilizationThresholds(
+    lane: SwimlaneDeclaration,
+    defaults: Map<string, DefaultDeclaration>,
+): { warn: number | null; over: number | null } {
+    const dflt = defaults.get('swimlane');
+    const warn = resolveThreshold(
+        propValue(lane.properties, 'utilization-warn-at'),
+        dflt ? propValue(dflt.properties, 'utilization-warn-at') : undefined,
+        DEFAULT_UTILIZATION_WARN_FRACTION,
+    );
+    const over = resolveThreshold(
+        propValue(lane.properties, 'utilization-over-at'),
+        dflt ? propValue(dflt.properties, 'utilization-over-at') : undefined,
+        DEFAULT_UTILIZATION_OVER_FRACTION,
+    );
+    return { warn, over };
+}
+
+function resolveThreshold(
+    laneVal: string | undefined,
+    defaultVal: string | undefined,
+    builtinFraction: number,
+): number | null {
+    const raw = laneVal ?? defaultVal;
+    const parsed = parseThresholdRaw(raw);
+    if (parsed.kind === 'unset') return builtinFraction;
+    if (parsed.kind === 'none') return null;
+    return parsed.value;
+}
+
+type ParsedThreshold = { kind: 'unset' } | { kind: 'none' } | { kind: 'number'; value: number };
+
+const PERCENT_RE = /^\d+(?:\.\d+)?%$/;
+const DECIMAL_FRACTION_RE = /^\d+\.\d+$/;
+
+function parseThresholdRaw(val: string | undefined): ParsedThreshold {
+    if (val === undefined) return { kind: 'unset' };
+    if (val === 'none') return { kind: 'none' };
+    if (PERCENT_RE.test(val)) {
+        const n = parseFloat(val) / 100;
+        return Number.isFinite(n) && n > 0 ? { kind: 'number', value: n } : { kind: 'unset' };
+    }
+    if (DECIMAL_FRACTION_RE.test(val)) {
+        const n = parseFloat(val);
+        return Number.isFinite(n) && n > 0 ? { kind: 'number', value: n } : { kind: 'unset' };
+    }
+    return { kind: 'unset' };
+}

package/src/layout-context.ts

@@ -0,0 +1,182 @@
+// 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`.
+
+import type {
+    EntityProperty,
+    GroupBlock,
+    ItemDeclaration,
+    LabelDeclaration,
+    ParallelBlock,
+    SymbolDeclaration,
+} from '@nowline/core';
+import type { BandScale } from './band-scale.js';
+import type { resolveCalendar } from './calendar.js';
+import type { StyleContext } from './style-resolution.js';
+import type { TimeScale } from './time-scale.js';
+import type {
+    MarkerRowPlacement,
+    Point,
+    PositionedItem,
+    PositionedTimelineScale,
+    PositionedTrackChild,
+    ResolvedSize,
+    SlackCorridor,
+} from './types.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. */
+    x: 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 };
+}
+
+/**
+ * Shared layout state passed through the per-entity sequencers and
+ * Renderable nodes. Owns the resolved calendar/timeline/style scope plus
+ * the running entity-edge maps that `after:` / `before:` references read.
+ */
+export interface LayoutContext {
+    cal: ReturnType<typeof resolveCalendar>;
+    styleCtx: StyleContext;
+    sizes: Map<string, ResolvedSize>;
+    labels: Map<string, LabelDeclaration>;
+    teams: Map<string, import('@nowline/core').TeamDeclaration>;
+    persons: Map<string, import('@nowline/core').PersonDeclaration>;
+    /**
+     * Custom `symbol` declarations from `ResolvedConfig.symbols`. Used by
+     * `resolveCapacityIcon` (in `capacity.ts`) to dereference custom symbol
+     * ids like `capacity-icon:budget` to the symbol's `unicode:` payload.
+     * Empty when the file declares no symbols.
+     */
+    symbols: Map<string, SymbolDeclaration>;
+    footnoteIndex: Map<string, number>;
+    /** For each footnote id, the list of `on:` host ids it references. */
+    footnoteHosts: Map<string, string[]>;
+    timeline: PositionedTimelineScale;
+    scale: TimeScale;
+    calendar: WorkingCalendar;
+    bandScale: BandScale;
+    entityLeftEdges: Map<string, number>;
+    entityRightEdges: Map<string, number>;
+    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`.
+     */
+    entityVisualLeftX: Map<string, number>;
+    entityVisualRightX: Map<string, number>;
+    /**
+     * 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.
+     */
+    itemArrowSource: Map<string, Point>;
+    /**
+     * Flow key for each item, used to dedupe milestone slack arrows.
+     * A "flow" is the deepest enclosing single-track container —
+     * swimlane root, sequential group, or one parallel sub-track.
+     * Two items share a flowKey iff they share that container path
+     * (file order already encodes their ordering, so only the
+     * latest predecessor in each flow contributes a slack arrow).
+     */
+    itemFlowKey: Map<string, string>;
+    /**
+     * The flow key currently being built by the swimlane walk.
+     * Container nodes (`SwimlaneNode`, `GroupNode`, `ParallelNode`)
+     * push their own segment onto this string before recursing into
+     * children and restore it afterward. `sequenceItem` reads this
+     * 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
+     * pass's milestones and consulted on the second pass so the binding
+     * predecessor (and any unrelated overlapping item) drops to a row
+     * whose Y does not match the corridor.
+     */
+    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.
+     */
+    markerRowPlacements: Map<string, MarkerRowPlacement>;
+    chartTopY: number;
+    chartBottomY: number;
+    /**
+     * Y coordinate at the bottom of the last swimlane / include region.
+     * Distinct from `chartBottomY`, which extends through any mirrored
+     * bottom timeline tick panel. Marker cut-lines (anchors, milestones)
+     * stop here so they never invade the bottom date strip; the now-line
+     * uses the wider `chartBottomY` (or the bottom panel's bottom edge)
+     * to thread the entire timeline strip.
+     */
+    swimlaneBottomY: number;
+    chartRightX: number;
+}
+
+/**
+ * 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.
+ */
+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;
+}