@nowline/layout 0.8.6 → 0.10.0

package/src/wave-barrier.ts

@@ -0,0 +1,242 @@
+// Wave barriers (specs/waves.md §5.1, §8.2-§8.5).
+//
+// One unit-agnostic driver serves both schedulers: engine A (pixel layout)
+// and engine C (`scheduleRoadmap`, days). Each wraps its lane walk in a
+// `runPass(S, E)` callback that floors starts by the barrier and reports the
+// latest member end per wave; the driver iterates to the least fixpoint.
+//
+// Arrays are **0-based** throughout this module: wave k (1-based, as in
+// `WavePlan` and the spec's `w_1 … w_n`) lives at index `k - 1` of `S`, `E`,
+// `floors` and `memberEnd`.
+
+import type { GroupBlock, ItemDeclaration, ParallelBlock, WavePlan } from '@nowline/core';
+import { waveFloorDates } from './start-terms.js';
+import type { WorkingCalendar } from './working-calendar.js';
+
+/** A node the walkers floor: a leaf item or a container. */
+export type WaveNode = ItemDeclaration | GroupBlock | ParallelBlock;
+
+/** What one pass reports back to the driver. */
+export interface WavePassResult {
+    /** Latest member end per wave (0-based); `-Infinity` when the wave has no member. */
+    memberEnd: readonly number[];
+}
+
+export interface WaveBarrierResult {
+    /** Wave starts `S_k` at index `k - 1`. */
+    S: number[];
+    /** Wave ends `E_k` at index `k - 1`. */
+    E: number[];
+    /** Passes the solve ran (at most `n + 1`). */
+    passes: number;
+    /** True when the solve hit the `n + 1` cap without settling (invalid input). */
+    capped: boolean;
+}
+
+/** A warm start for `solveWaveBarriers`: estimates of `S_k` / `E_k` from below (0-based, null: none). */
+export interface WaveBarrierSeed {
+    S: ReadonlyArray<number | null>;
+    E: ReadonlyArray<number | null>;
+}
+
+/**
+ * Solve the barrier recurrence (§8.2). `floors[k - 1]` is `A_k` in the
+ * caller's units, or null for no floor; `origin` is the axis origin (0 days,
+ * or the timeline's origin x).
+ *
+ * `runPass` must be pure in `(S, E)`: the caller resets its entity maps every
+ * pass. On convergence the last `runPass` call ran with the returned `S`/`E`,
+ * so the caller can keep that pass's placements. When the cap is hit, the
+ * driver calls `runPass` once more with the returned `S`/`E` for the same
+ * reason; that extra call is not counted in `passes`.
+ *
+ * `tolerance` is how far a floor must pass the prior edge (`E_{k-1}`, or
+ * the origin for `S_1`) to set `S_k`; a floor within it is a tie and the
+ * prior edge wins. The day engines use 0 (exact `max`). Engine A passes its
+ * sub-pixel edge tolerance: its floors are `origin + days * ppd` while
+ * `E_{k-1}` is a sum of item widths, so a same-day floor can exceed the
+ * prior end by an ulp and would otherwise open a phantom gap.
+ *
+ * `seed` warm-starts the solve (specs/scheduler-unification.md §5, F4):
+ * `seed.S[k - 1]` and `seed.E[k - 1]` are an estimate of `S_k` and `E_k`
+ * from below (engine A passes engine C's, projected), or null for none. The
+ * first pass starts each `S_k` (k > 1) and `E_k` at no less than its seed
+ * instead of at the floor chain alone, so the passes settle sooner on the
+ * same fixpoint: Kleene iteration from any lower bound of the least
+ * fixpoint reaches it, and for valid input (WV10) the fixpoint is unique
+ * (`S_1` is fixed, and each `E_k` then follows from `S_1..S_k` and
+ * `E_1..E_{k-1}`), so a pass can only confirm the right one. `S_1` is never
+ * seeded: the driver keeps the first pass's `S_1` to the end.
+ */
+export function solveWaveBarriers(
+    n: number,
+    origin: number,
+    floors: ReadonlyArray<number | null>,
+    runPass: (S: readonly number[], E: readonly number[]) => WavePassResult,
+    tolerance = 0,
+    seed?: WaveBarrierSeed,
+): WaveBarrierResult {
+    const A = floors.map((f) => f ?? -Infinity);
+    let S: number[] = [];
+    for (let i = 0; i < n; i++) {
+        const chained = floorPast(i === 0 ? origin : S[i - 1], A[i], tolerance);
+        S.push(i === 0 ? chained : Math.max(chained, seed?.S[i] ?? -Infinity));
+    }
+    let E = S.map((s, i) => Math.max(s, seed?.E[i] ?? -Infinity));
+    for (let pass = 1; pass <= n + 1; pass++) {
+        const m = runPass(S, E).memberEnd;
+        const S2: number[] = [];
+        const E2: number[] = [];
+        for (let i = 0; i < n; i++) {
+            S2.push(i === 0 ? S[0] : floorPast(E2[i - 1], A[i], tolerance));
+            E2.push(Math.max(S2[i], m[i] ?? -Infinity));
+        }
+        if (sameArray(S, S2) && sameArray(E, E2)) {
+            return { S, E, passes: pass, capped: false };
+        }
+        S = S2;
+        E = E2;
+    }
+    runPass(S, E);
+    return { S, E, passes: n + 1, capped: true };
+}
+
+/** `max(prior, floor)`, except a floor within `tolerance` of `prior` is a tie: `prior`. */
+function floorPast(prior: number, floor: number, tolerance: number): number {
+    return floor - prior > tolerance ? floor : prior;
+}
+
+function sameArray(a: readonly number[], b: readonly number[]): boolean {
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) return false;
+    }
+    return true;
+}
+
+/**
+ * Floor offsets `A_k` in working days from `startDate`, from the plan's
+ * unclamped declaration dates (§5.1). A floor on a non-working day counts
+ * as the next working day. A floor before the start yields a negative
+ * offset; `S_1 = max(0, A_1)` absorbs it.
+ */
+export function waveFloorDays(
+    plan: WavePlan,
+    startDate: Date,
+    calendar: WorkingCalendar,
+): Array<number | null> {
+    return waveFloorDates(plan).map((d) => (d ? calendar.workingIndexOf(startDate, d) : null));
+}
+
+/**
+ * Per-pass wave state, in the caller's units (days for engine C, px for engine
+ * A): the floor of a node and the member-end accumulator. One instance per pass.
+ */
+export class WavePass {
+    /** Latest member end per wave (0-based); `-Infinity` when the wave has no member. */
+    readonly memberEnd: number[];
+    /** The member that set `memberEnd` (latest end; ties keep the first placed). */
+    readonly binding: Array<ItemDeclaration | undefined>;
+    /** Members placed per wave. */
+    readonly memberCount: number[];
+
+    constructor(
+        readonly plan: WavePlan,
+        readonly S: readonly number[],
+    ) {
+        const n = plan.waves.length;
+        this.memberEnd = new Array<number>(n).fill(-Infinity);
+        this.binding = new Array<ItemDeclaration | undefined>(n).fill(undefined);
+        this.memberCount = new Array<number>(n).fill(0);
+    }
+
+    /**
+     * The barrier floor of `node`: `S[ew]` for an item, and
+     * `max(S[ew(C)], S[lw(C)])` for a container (§5.1 start rule). Undefined
+     * for background work with no lead wave.
+     */
+    floor(node: WaveNode): number | undefined {
+        const ew = this.plan.waveOf.get(node);
+        const lw = node.$type === 'ItemDeclaration' ? undefined : this.plan.leadOf.get(node);
+        let f: number | undefined;
+        if (ew !== undefined) f = this.S[ew - 1];
+        if (lw !== undefined) f = Math.max(f ?? -Infinity, this.S[lw - 1]);
+        return f;
+    }
+
+    /** `max(start, floor(node))`, or `start` unchanged when there is no floor. */
+    apply(node: WaveNode, start: number): number {
+        const f = this.floor(node);
+        return f === undefined ? start : Math.max(start, f);
+    }
+
+    /** Record a placed item's end; a no-op for background work. */
+    accumulate(item: ItemDeclaration, end: number): void {
+        const k = this.plan.memberWave(item);
+        if (k === undefined) return;
+        this.memberCount[k - 1]++;
+        if (end > this.memberEnd[k - 1]) {
+            this.memberEnd[k - 1] = end;
+            this.binding[k - 1] = item;
+        }
+    }
+}
+
+/** One wave's solved span, in the caller's units. */
+export interface WaveSpan {
+    id: string;
+    /** 1-based declaration order. */
+    index: number;
+    start: number;
+    end: number;
+    memberCount: number;
+    /** The binding member's id ?? title; omitted when no member sets `E_k > S_k`. */
+    heldBy?: string;
+    /** The `after:` element that set `S_k`, when it beat `E_{k-1}` (or the origin). */
+    floorRef?: string;
+}
+
+/**
+ * Summarise the solved waves from the driver's result and the final pass
+ * (the pass that ran with `result.S` / `result.E`). `tolerance` must be
+ * the one the solve ran with, so `floorRef` is set exactly when the floor
+ * set `S_k`.
+ */
+export function summarizeWaves(
+    plan: WavePlan,
+    result: WaveBarrierResult,
+    finalPass: WavePass,
+    origin: number,
+    floors: ReadonlyArray<number | null>,
+    tolerance = 0,
+): WaveSpan[] {
+    return plan.waves.map((w, i) => {
+        const span: WaveSpan = {
+            id: w.name as string,
+            index: i + 1,
+            start: result.S[i],
+            end: result.E[i],
+            memberCount: finalPass.memberCount[i],
+        };
+        const binding = finalPass.binding[i];
+        if (
+            binding !== undefined &&
+            finalPass.memberEnd[i] === result.E[i] &&
+            result.E[i] > result.S[i]
+        ) {
+            const label = binding.name ?? binding.title;
+            if (label !== undefined) span.heldBy = label;
+        }
+        const floor = floors[i];
+        const floorRef = plan.floors[i]?.ref;
+        const prior = i === 0 ? origin : result.E[i - 1];
+        if (
+            floor !== null &&
+            floor !== undefined &&
+            floorRef !== undefined &&
+            floor - prior > tolerance
+        ) {
+            span.floorRef = floorRef;
+        }
+        return span;
+    });
+}

package/src/wave-hatch.ts

@@ -0,0 +1,25 @@
+// Wave hatch kind: which of the theme's two hatch strokes marks background
+// work on a bar (specs/waves.md §9.3), picked by the bar fill's luminance.
+// Moved from the SVG renderer (R5) so each background item and the legend's
+// hatch swatch carry their kind and the renderer only draws the pattern.
+
+import { fillLuminance } from './status-dot.js';
+import type { ResolvedStyle, WaveHatchKind } from './types.js';
+
+/**
+ * Bar-fill luminance at or above which background work gets the dark hatch
+ * (`wave.hatch`); below it, the light one (`wave.hatchOnDark`). The same
+ * crossover the status dot picks its palette by (`pickStatusDotPalette`), so
+ * the hatch and the dot agree on which bars read as dark.
+ */
+const WAVE_HATCH_LIGHT_FILL_MIN_LUMINANCE = 0.24;
+
+/** The painted fill of a bar, as the renderer's `rectFrame` paints it. */
+function barFill(bg: ResolvedStyle['bg']): string {
+    return bg === 'none' ? 'transparent' : bg;
+}
+
+/** The hatch kind for a bar (or legend swatch) whose resolved `bg` is `bg`. */
+export function waveHatchKind(bg: ResolvedStyle['bg']): WaveHatchKind {
+    return fillLuminance(barFill(bg)) >= WAVE_HATCH_LIGHT_FILL_MIN_LUMINANCE ? 'dark' : 'light';
+}

package/src/wave-layout.ts

@@ -0,0 +1,203 @@
+// Engine A (pixel layout) wave state: specs/waves.md §8.4.
+//
+// The place phase (`phases/place.ts`) runs its lane loop (plus a region pass) inside the
+// unit-agnostic barrier driver (`solveWaveBarriers`). Every pass floors
+// starts with the pass's `S` (in px) and accumulates member ends; this
+// module holds that state and the small helpers the sequencers and
+// container nodes call. Without waves `LayoutContext.waves` is undefined
+// and every helper here is a no-op, so wave-free output is unchanged.
+
+import type { ItemDeclaration, WavePlan } from '@nowline/core';
+import { addDays } from './calendar.js';
+import type { LayoutContext } from './layout-context.js';
+import { waveFloorDates } from './start-terms.js';
+import type { TimeScale } from './time-scale.js';
+import type { PositionedItem } from './types.js';
+import { type WaveBarrierResult, type WaveNode, WavePass } from './wave-barrier.js';
+import { spanEndDate } from './working-calendar.js';
+
+/**
+ * Sub-pixel tolerance for wave edges: a milestone whose center is closer
+ * than this to a boundary sits on it (specs/waves.md §9.2), a wave must
+ * move past a date by at least this much to count as an overrun, and an
+ * item must start this close to its `after:` date for that date to have
+ * set its start (NL.I1008). Pixel ends are float sums, so exact
+ * comparisons would flip on rounding noise.
+ */
+export const WAVE_EDGE_TOLERANCE_PX = 0.5;
+
+/** Engine A's barrier state, shared by the main lanes and the regions. */
+export interface WaveLayoutState {
+    readonly plan: WavePlan;
+    /** Wave ids in declaration order (wave k at index `k - 1`). */
+    readonly ids: readonly string[];
+    /** The axis origin in px (`S_1 >= origin`). */
+    readonly origin: number;
+    /**
+     * `A_k` in px from the unclamped `scale.forward` of each floor date
+     * (never `forwardWithinDomain` or the edge maps), or null: no floor.
+     */
+    readonly floors: ReadonlyArray<number | null>;
+    /** `S_k` / `E_k` in px (0-based) that the current pass floors with and seeds. */
+    S: readonly number[];
+    E: readonly number[];
+    /** The current pass: floors from `S`, plus the member-end accumulator. */
+    pass: WavePass;
+    /**
+     * Set once the driver settles: `S`/`E` are the solved values, `pass` is
+     * the pass that ran with them, and later placements (the slack rerun,
+     * the final region placement) floor without accumulating. The spans
+     * then come from `summarizeWaves(plan, solve, pass, origin, floors)`.
+     */
+    frozen: boolean;
+    /** The driver's result, set with `frozen`. */
+    solve?: WaveBarrierResult;
+    /**
+     * The localized hover line of a background item
+     * (`PositionedItem.waveTooltip`), set where the item is placed: the
+     * renderer has no locale table (specs/waves.md §9.3).
+     */
+    readonly backgroundTooltip: string;
+    /**
+     * Some wave has a member (`hasVisibleWaves`). When none does, the
+     * barrier still runs but nothing is drawn: no item is background work.
+     */
+    readonly visible: boolean;
+}
+
+/**
+ * Fresh state for a roadmap with waves; `scale` maps the floor dates,
+ * `backgroundTooltip` is the locale's background-item line, and `visible`
+ * says whether any wave has a member.
+ */
+export function createWaveLayoutState(
+    plan: WavePlan,
+    scale: TimeScale,
+    origin: number,
+    backgroundTooltip: string,
+    visible: boolean,
+): WaveLayoutState {
+    const S = plan.waves.map(() => origin);
+    return {
+        plan,
+        ids: plan.waves.map((w) => w.name as string),
+        origin,
+        floors: waveFloorDates(plan).map((d) => (d ? scale.forward(d) : null)),
+        S,
+        E: S,
+        pass: new WavePass(plan, S),
+        frozen: false,
+        backgroundTooltip,
+        visible,
+    };
+}
+
+/** Start a barrier pass with the driver's `S`/`E`. */
+export function beginWavePass(
+    state: WaveLayoutState,
+    S: readonly number[],
+    E: readonly number[],
+): void {
+    state.S = S;
+    state.E = E;
+    state.pass = new WavePass(state.plan, S);
+}
+
+/**
+ * Freeze the state on the driver's result. The last pass the driver ran
+ * used exactly `result.S` / `result.E` (on convergence and when capped),
+ * so `state.pass` already floors with the solved starts.
+ */
+export function freezeWaves(state: WaveLayoutState, result: WaveBarrierResult): void {
+    state.S = result.S;
+    state.E = result.E;
+    state.frozen = true;
+    state.solve = result;
+}
+
+/**
+ * Seed the wave edges into a pair of entity-edge maps (specs/waves.md
+ * §8.4): `entityRightEdges[w_k] = E_k`, `entityLeftEdges[w_k] = S_k`, so
+ * `after:<wave>`, `before:<wave>` and a floating `milestone after:<wave>`
+ * resolve through the existing lookups. Wave ids get no midpoint, so a
+ * wave reference draws no dependency arrow.
+ */
+export function seedWaveEdges(
+    state: WaveLayoutState,
+    left: Map<string, number>,
+    right: Map<string, number>,
+): void {
+    state.ids.forEach((id, i) => {
+        left.set(id, state.S[i]);
+        right.set(id, state.E[i]);
+    });
+}
+
+/**
+ * The barrier floor applied to a start: `max(x, S[ew(node)], S[lw(node)])`
+ * (specs/waves.md §5.1 start rule). `x` unchanged without waves and for
+ * background work with no lead wave.
+ */
+export function waveFloorX(node: WaveNode, x: number, ctx: LayoutContext): number {
+    return ctx.waves ? ctx.waves.pass.apply(node, x) : x;
+}
+
+/** Record a placed item's logical end (members only; never while frozen). */
+export function accumulateWaveMember(
+    node: ItemDeclaration,
+    logicalEnd: number,
+    ctx: LayoutContext,
+): void {
+    if (ctx.waves && !ctx.waves.frozen) ctx.waves.pass.accumulate(node, logicalEnd);
+}
+
+/** `PositionedItem.waveRole`, or undefined when the roadmap draws no waves. */
+export function waveRoleOf(node: ItemDeclaration, ctx: LayoutContext): PositionedItem['waveRole'] {
+    if (!ctx.waves?.visible) return undefined;
+    return ctx.waves.plan.memberWave(node) !== undefined ? 'member' : 'background';
+}
+
+/** True when `x` sits on a wave boundary: any `S_k` or `E_k` except the origin. */
+export function isOnWaveBoundary(state: WaveLayoutState, x: number): boolean {
+    for (const b of [...state.S, ...state.E]) {
+        if (Math.abs(b - state.origin) < WAVE_EDGE_TOLERANCE_PX) continue;
+        if (Math.abs(x - b) < WAVE_EDGE_TOLERANCE_PX) return true;
+    }
+    return false;
+}
+
+/**
+ * The whole working-day index nearest to `x` on the timeline. Under `show`
+ * x is linear in calendar days, so the nearest calendar day is read first
+ * and then counted in working days (a non-working day counts as the next
+ * working day), which keeps the dates engine A reports equal to engine C's.
+ */
+function dayAtX(x: number, ctx: LayoutContext): number {
+    const days = Math.round((x - ctx.timeline.originX) / ctx.timeline.pixelsPerDay);
+    if (!ctx.scale.showsNonWorking) return days;
+    const start = ctx.timeline.startDate;
+    return ctx.calendar.workingIndexOf(start, addDays(start, days));
+}
+
+/**
+ * The working day whose start is nearest `x` on the timeline: a point,
+ * such as a start (UTC midnight). Extent growth never moves the origin or
+ * the pixels-per-day, so this is stable across it.
+ */
+export function dateAtX(x: number, ctx: LayoutContext): Date {
+    return ctx.calendar.dateAtWorkingIndex(ctx.timeline.startDate, dayAtX(x, ctx));
+}
+
+/**
+ * The exclusive end date of the span [startX, endX] on the timeline
+ * (`spanEndDate` over the nearest whole working days): a Mon–Fri span
+ * ends on Saturday.
+ */
+export function spanEndDateAtX(startX: number, endX: number, ctx: LayoutContext): Date {
+    return spanEndDate(
+        ctx.calendar,
+        ctx.timeline.startDate,
+        dayAtX(startX, ctx),
+        dayAtX(endX, ctx),
+    );
+}