@nowline/layout 0.0.0-dev.20260601071750.g04bdff9

package/dist/lane-utilization.js

@@ -0,0 +1,206 @@
+// 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 { propValue } from './dsl-utils.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%
+/**
+ * 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) {
+    const out = [];
+    walk(children, out);
+    return out;
+}
+function walk(children, out) {
+    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) {
+    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) {
+    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();
+    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 = [];
+    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 = [];
+    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, capacity, warnFraction, overFraction) {
+    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, defaults) {
+    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, defaultVal, builtinFraction) {
+    const raw = laneVal ?? defaultVal;
+    const parsed = parseThresholdRaw(raw);
+    if (parsed.kind === 'unset')
+        return builtinFraction;
+    if (parsed.kind === 'none')
+        return null;
+    return parsed.value;
+}
+const PERCENT_RE = /^\d+(?:\.\d+)?%$/;
+const DECIMAL_FRACTION_RE = /^\d+\.\d+$/;
+function parseThresholdRaw(val) {
+    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' };
+}
+//# sourceMappingURL=lane-utilization.js.map

package/dist/lane-utilization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lane-utilization.js","sourceRoot":"","sources":["../src/lane-utilization.ts"],"names":[],"mappings":"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"}

package/dist/layout-context.d.ts

@@ -0,0 +1,143 @@
+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 declare function newCursor(x: number, y: number): TrackCursor;
+/**
+ * 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;
+}
+//# sourceMappingURL=layout-context.d.ts.map

package/dist/layout-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-context.d.ts","sourceRoot":"","sources":["../src/layout-context.ts"],"names":[],"mappings":"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"}

package/dist/layout-context.js

@@ -0,0 +1,8 @@
+// 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`.
+export function newCursor(x, y) {
+    return { x, y, height: 0, maxX: x };
+}
+//# sourceMappingURL=layout-context.js.map

package/dist/layout-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-context.js","sourceRoot":"","sources":["../src/layout-context.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,iEAAiE;AACjE,uEAAuE;AACvE,4DAA4D;AAqC5D,MAAM,UAAU,SAAS,CAAC,CAAS,EAAE,CAAS;IAC1C,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACxC,CAAC"}

package/dist/layout.d.ts

@@ -0,0 +1,18 @@
+import type { NowlineFile, ResolveResult } from '@nowline/core';
+import type { ThemeName } from './themes/index.js';
+import type { PositionedRoadmap } from './types.js';
+export interface LayoutOptions {
+    theme?: ThemeName;
+    today?: Date;
+    width?: number;
+    /**
+     * BCP-47 tag controlling axis labels, the now-pill string, and the
+     * quarter prefix. Resolved by the caller (CLI flag → env vars). When
+     * undefined, layout falls back to the file's `nowline v1 locale:` and
+     * then to `en-US`. See `specs/localization.md`.
+     */
+    locale?: string;
+}
+export type LayoutResult = PositionedRoadmap;
+export declare function layoutRoadmap(file: NowlineFile, resolved: ResolveResult, options?: LayoutOptions): LayoutResult;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKR,WAAW,EAEX,aAAa,EAEhB,MAAM,eAAe,CAAC;AA2DvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAanD,OAAO,KAAK,EAYR,iBAAiB,EAIpB,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,aAAa;IAC1B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,iBAAiB,CAAC;AAq3C7C,wBAAgB,aAAa,CACzB,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE,aAAkB,GAC5B,YAAY,CAcd"}