@nowline/layout 0.8.5 → 0.9.0

package/dist/phases/date-window.js

@@ -0,0 +1,130 @@
+// Phase 1, the date window (specs/layout-phases.md §3.2): the roadmap's
+// scope (theme, locale, style context, `default roadmap` style) and the
+// natural date window, a projection of the day schedule
+// (specs/scheduler-unification.md §3.3). Nothing here knows about pixels.
+import { findProp } from '@nowline/core/internal';
+import { daysBetween, literalToDays } from '../calendar.js';
+import { resolveWorkingCalendar } from '../calendar-resolver.js';
+import { propValue } from '../dsl-utils.js';
+import { resolveLocale } from '../i18n.js';
+import { isNonWorkingDisplay } from '../non-working-display.js';
+import { resolveStyle } from '../style-resolution.js';
+import { themes } from '../themes/index.js';
+import { resolveScale, tickBoundaryAtOrAfter } from '../view-preset.js';
+import { daysPerUnit } from '../working-calendar.js';
+export function resolveScope(file, resolved, options) {
+    const themeName = options.theme ?? 'light';
+    const theme = themes[themeName];
+    const locale = resolveLocale(options.locale, directiveLocale(file));
+    const styleCtx = {
+        theme,
+        styles: resolved.config.styles,
+        defaults: resolved.config.defaults,
+        labels: resolved.content.labels,
+    };
+    // Raw style props (including `timeline-position` and `minor-grid`) are
+    // banned on the roadmap declaration itself, so the values come from the
+    // level-2 `default roadmap` line in config.
+    const roadmapStyle = resolveStyle('roadmap', file.roadmapDecl?.properties ?? [], styleCtx);
+    return { themeName, theme, locale, styleCtx, roadmapStyle };
+}
+export function resolveDateWindow(file, resolved, options, scope, schedule) {
+    // The working calendar maps dates to working-day indices for the
+    // window, the axis and every placement (specs/working-calendar.md
+    // §5, §7.1).
+    const { config: cal, working: calendar } = resolveWorkingCalendar(file, resolved);
+    const preset = resolveScale(file, resolved.config.scale);
+    // Window is content-aware: when `length:` is omitted we derive the end
+    // day from the latest dated/sequenced entity (item, anchor, milestone,
+    // today's now-line) instead of defaulting to a 180-day desert.
+    const { startDate, endDate } = computeDateWindow(file, schedule, options.today, preset);
+    // How non-working days are drawn: the surface option, then the file's
+    // `default roadmap non-working:` key (resolved to `hide` when absent).
+    // It reaches every placement through the time scale.
+    const nonWorking = isNonWorkingDisplay(options.nonWorking)
+        ? options.nonWorking
+        : scope.roadmapStyle.nonWorking;
+    // `TimeScale.showsNonWorking`, needed here to size the scale's range.
+    const showsNonWorking = nonWorking === 'show' && calendar.hasNonWorkingDays;
+    const spanDays = Math.max(1, calendar.workingIndexOf(startDate, endDate));
+    // Under `show` every calendar day takes a pixel width of its own, so
+    // the chart widens by the non-working days in the window.
+    const timelineDays = showsNonWorking ? Math.max(1, daysBetween(startDate, endDate)) : spanDays;
+    return {
+        cal,
+        calendar,
+        preset,
+        schedule,
+        startDate,
+        naturalEndDate: endDate,
+        spanDays,
+        timelineDays,
+        nonWorking,
+    };
+}
+// Compute a sensible [startDate, endDate] window from the roadmap's day
+// schedule (`scheduleRoadmap`, specs/scheduler-unification.md §3.3).
+//
+// Precedence:
+//   1. An explicit `length:` is a minimum span; content (including wave
+//      barriers E_n and every S_k) past it grows the window to the next
+//      tick boundary.
+//   2. Otherwise we derive the end day from the actual content extent
+//      (`schedule.extent.contentEndDay`: latest lane cursor, anchor date,
+//      milestone date/after, wave edge) and today's now-line if it falls
+//      past the content. This keeps the rendered chart from defaulting to
+//      a 180-day desert when the content only spans a few weeks.
+//   3. As a last resort (no content + no length), fall back to a small
+//      4-week placeholder so an empty roadmap still draws a sensible axis.
+//
+// The start is `schedule.startDate`: the roadmap's `start:`, else `today`
+// (see `scheduleRoadmap`). Every day count is a working-day index from the
+// start (specs/working-calendar.md §5) under the schedule's calendar. A
+// calendar with no non-working day keeps calendar-day arithmetic.
+//
+// Exported for tests; not part of the package surface.
+export function computeDateWindow(file, schedule, today, scale) {
+    const props = file.roadmapDecl?.properties ?? [];
+    const { config: cal, working: calendar } = schedule.calendar;
+    const { startDate } = schedule;
+    const lengthRaw = propValue(props, 'length');
+    let minDays = 0;
+    if (lengthRaw) {
+        const days = literalToDays(lengthRaw, cal);
+        if (days > 0) {
+            minDays = days;
+        }
+    }
+    // An explicit `length:` bounds the now-line: a far-future `today` must
+    // not stretch a deliberately-sized roadmap (that case stays out of range
+    // and surfaces as an NL.W1000 insight). Content overflow — items,
+    // anchors, milestones — still grows the window below via `padded`, with
+    // `length:` acting purely as the floor. Without `length:`, `today`
+    // extends the window so the now-line is always in range.
+    let contentDays = schedule.extent.contentEndDay;
+    if (today && !(minDays > 0)) {
+        const t = calendar.workingIndexOf(startDate, today);
+        if (t > 0)
+            contentDays = Math.max(contentDays, t);
+    }
+    const tickDays = daysPerUnit(scale.unit, cal);
+    // Round up to the smallest tick boundary that is `>= contentDays`. When
+    // the latest content lands exactly on a tick boundary the chart ends
+    // exactly there (no extra trailing tick); otherwise we extend to the
+    // next tick so the right edge always sits on a labelled column. For
+    // month / quarter / year scales the boundary is a real month /
+    // quarter / year start, not a multiple of `days-per-month` etc.
+    const padded = tickBoundaryAtOrAfter(startDate, contentDays > 0 ? contentDays : 4 * cal.daysPerWeek, scale.unit, tickDays, calendar);
+    const finalDays = Math.max(minDays, padded);
+    return {
+        startDate,
+        endDate: calendar.dateAtWorkingIndex(startDate, Math.max(1, finalDays)),
+    };
+}
+// Read the optional `locale:` property from the file's `nowline` directive.
+// Layout receives an already-parsed AST, so this is a cheap lookup with no
+// validation work — that's the validator's job in `@nowline/core`.
+function directiveLocale(file) {
+    return findProp(file.directive?.properties ?? [], 'locale')?.value;
+}
+//# sourceMappingURL=date-window.js.map

package/dist/phases/date-window.js.map

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

package/dist/phases/finalize.d.ts

@@ -0,0 +1,198 @@
+import type { NowlineFile, ResolveResult } from '@nowline/core';
+import type { LayoutOptions, LayoutResult } from '../layout.js';
+import type { LayoutContext } from '../layout-context.js';
+import type { PositionedHeaderParts } from '../nodes/header-node.js';
+import { type MarkerBand, type MarkerEntity } from '../nodes/marker-band.js';
+import { type BuiltWaves } from '../nodes/wave-node.js';
+import { TimeScale } from '../time-scale.js';
+import type { BoundingBox, PositionedAnchor, PositionedDependencyEdge, PositionedFootnoteArea, PositionedMilestone, PositionedNowline, PositionedWaveLegend } from '../types.js';
+import type { DateWindow, RoadmapScope } from './date-window.js';
+import { type MeasuredRoadmap } from './measure.js';
+import type { PlacedChart } from './place.js';
+/**
+ * The canvas right edge. `grow` is the single mutator: every artifact that
+ * wants the canvas wider passes the absolute x it must contain, its
+ * breathing room (typically `GUTTER_PX`) included. Today: item caption
+ * spills (f1), the timeline extension (f2) and marker-row labels (f3).
+ * f3 freezes it; `final` reads it only after that.
+ *
+ * The now-pill is intentionally NOT a contributor — when the line lands
+ * close to either edge, `buildNowline` switches the pill to "flag" mode
+ * (squared edge against the line, rounded edge into the chart), so the
+ * pill always fits inside the canvas.
+ */
+export declare class CanvasExtent {
+    private rightX;
+    private frozen;
+    constructor(rightX: number);
+    /** Grow the canvas to contain `x`; returns whether it grew. Throws once frozen. */
+    grow(x: number): boolean;
+    /** The canvas is final from here on. */
+    freeze(): void;
+    /** The right edge so far. Only the step that freezes the canvas (f3) reads it before `final`. */
+    get provisional(): number;
+    /** The final right edge. Throws before `freeze`. */
+    get final(): number;
+}
+/** The pieces of the model the steps produce. Each is set once, by its step. */
+export interface ModelDraft {
+    /** Every marker with its final x, and how many of them are calendar labels (f3). */
+    markerEntries?: {
+        all: MarkerEntity[];
+        calendarCount: number;
+    };
+    milestones?: PositionedMilestone[];
+    waves?: BuiltWaves;
+    anchors?: PositionedAnchor[];
+    edges?: PositionedDependencyEdge[];
+    nowline?: PositionedNowline | null;
+    waveLegend?: PositionedWaveLegend;
+    footnotes?: PositionedFootnoteArea;
+    header?: PositionedHeaderParts;
+    attributionBox?: BoundingBox;
+    /** The canvas height, below the attribution mark. */
+    height?: number;
+}
+/**
+ * The top of the header rows on the final axis. The measure phase reserves
+ * the now-pill row only when `today` falls inside the natural window; when
+ * the axis extension (f2) brings `today` in, the pill row is reserved here
+ * (L2, specs/layout-phases.md §1.3), and the tick panel, wave strip and
+ * marker band below it move down by `shift`.
+ */
+export interface HeaderRowsTop {
+    timelineY: number;
+    pillRowHeight: number;
+    tickPanelY: number;
+    /** The marker band's top, where f5 packs it. */
+    markerRowY: number;
+    /** How far the tick panel, wave strip and marker band move down from the measure. */
+    shift: number;
+}
+/**
+ * Reports whether a finalize step changed something and, for a step that
+ * says (`FinalizeContext.explain`), why; see `setFinalizeTrace`.
+ */
+export type FinalizeTrace = (step: string, changed: boolean, why?: readonly string[]) => void;
+/**
+ * What passed the natural window when f2 grew the axis (specs/layout-phases.md
+ * §9, F3): a leaf item bar (a bug: the schedule's extent and the placement
+ * disagree), a spilled caption (its one capped column), a date-pinned marker
+ * (a dated anchor or milestone on the last day), or an after-only milestone
+ * on the window end (decision 14), in the main chart or in an isolated
+ * region. A diamond sits on its day, so its right half passes a window that
+ * ends on that day.
+ */
+export type TimelineExtensionCause = 'bar' | 'caption' | 'datedMarker' | 'afterMilestone';
+/**
+ * Install (or, with `undefined`, remove) the `FinalizeTrace`. Internal: the
+ * coverage register (`finalize-coverage.test.ts`) records with it which
+ * steps change something on each sample.
+ */
+export declare function setFinalizeTrace(trace: FinalizeTrace | undefined): void;
+export declare class FinalizeContext {
+    readonly file: NowlineFile;
+    readonly resolved: ResolveResult;
+    readonly options: LayoutOptions;
+    readonly scope: RoadmapScope;
+    readonly window: DateWindow;
+    readonly measured: MeasuredRoadmap;
+    readonly chart: PlacedChart;
+    /** The canvas right edge: `grow` until f3 freezes it, `final` only after. */
+    readonly canvas: CanvasExtent;
+    /** Chart top, bottom of the lanes, bottom including the panels below them. */
+    readonly chartY: {
+        top: number;
+        swimlaneBottom: number;
+        bottom: number;
+    };
+    /** Pieces of the model the steps produce. */
+    readonly draft: ModelDraft;
+    private scaleIsFinal;
+    private band;
+    private rowsTop;
+    private rowsBottom;
+    private why;
+    constructor(file: NowlineFile, resolved: ResolveResult, options: LayoutOptions, scope: RoadmapScope, window: DateWindow, measured: MeasuredRoadmap, chart: PlacedChart);
+    /** The placement context of the kept pass. */
+    get ctx(): LayoutContext;
+    /** The axis scale. f2 may replace it; `finalScale()` throws before f2 ran. */
+    get scale(): TimeScale;
+    finalScale(): TimeScale;
+    /** Replace the axis scale with an extended one (f2 only). */
+    extendScale(scale: TimeScale): void;
+    /** The scale is final from here on (f2, whether or not it extended it). */
+    settleScale(): void;
+    /** The final marker pack, set by f5; reading it earlier throws. */
+    markerBand(): MarkerBand;
+    /** Set the final marker pack (f5 only); the context's placements become its. */
+    setMarkerBand(band: MarkerBand): void;
+    /**
+     * The header rows' top on the final axis. It reads the final scale, so
+     * it throws before f2; f5 packs the marker band at it and f7 moves the
+     * rows to it.
+     */
+    headerRowsTop(): HeaderRowsTop;
+    /** The bottom of the grown header rows, set by f7; reading it earlier throws. */
+    headerRowsBottom(): number;
+    /** Set the bottom of the grown header rows (f7 only). */
+    setHeaderRowsBottom(y: number): void;
+    /** Say why the running step changed something; its report carries it. */
+    explain(why: readonly string[]): void;
+    /** Report a step's effect to the trace, when one is installed. */
+    report(step: string, changed: boolean): void;
+}
+/**
+ * The header rows' top once the axis is final. When the measure phase left
+ * the pill row at 0 and `today` lies on the final axis, f2 brought it in:
+ * the rows grow by `NOW_PILL_HEIGHT_PX` above the tick panel, and the
+ * timeline y follows the beside-card rule (`headerRowsTimelineY`), so a
+ * card that already pushed the rows down absorbs some or all of the pill
+ * row instead of the rows growing by its full height.
+ */
+export declare function resolveHeaderRowsTop(measured: MeasuredRoadmap, today: Date | undefined, scale: TimeScale): HeaderRowsTop;
+/**
+ * What a finalize step reads or writes. `placement` is everything place
+ * left (lanes, regions, items, milestone x, the date-pinned markers),
+ * `window` the date window and `headerBands` the measured header rows;
+ * the rest are the slots finalize produces.
+ */
+export type FinalizeSlot = 'placement' | 'window' | 'headerBands' | 'canvas' | 'scale' | 'timeline' | 'calendarRuns' | 'markerEntries' | 'laneWidths' | 'markerBand' | 'milestones' | 'calendarLabels' | 'markerMidpoints' | 'chartTop' | 'rowsBottom' | 'laneBottom' | 'chartBottom' | 'laneY' | 'waves' | 'anchors' | 'edges' | 'nowline' | 'legend' | 'footnotes' | 'header' | 'attribution';
+/**
+ * The rule a slot follows:
+ * - `input`: nothing in finalize writes it.
+ * - `final`: steps up to `finalAfter` may write it, none after; only
+ *   `finalAfter` itself may read it before then.
+ * - `cursor`: only the `advancers` write it (each reads it as it advances
+ *   it); every other reader comes after the last advancer.
+ * - `product`: one step writes it; readers come after that step.
+ */
+export type SlotRule = {
+    kind: 'input';
+} | {
+    kind: 'final';
+    finalAfter: string;
+} | {
+    kind: 'cursor';
+    advancers: readonly string[];
+} | {
+    kind: 'product';
+};
+export declare const SLOT_RULES: Readonly<Record<FinalizeSlot, SlotRule>>;
+export interface FinalizeStep {
+    readonly name: string;
+    readonly reads: readonly FinalizeSlot[];
+    readonly writes: readonly FinalizeSlot[];
+    /** Run the step; returns whether it changed something (for the coverage trace). */
+    run(fx: FinalizeContext): boolean;
+}
+/**
+ * Every way `steps` breaks `rules`, as one message each; empty when the
+ * order holds.
+ */
+export declare function checkFinalizeOrder(steps: readonly FinalizeStep[], rules?: Readonly<Record<FinalizeSlot, SlotRule>>): string[];
+/** The finalize pass, in order (specs/layout-phases.md §3.5). */
+export declare const FINALIZE_STEPS: readonly FinalizeStep[];
+/** Run the finalize pass over `fx` and assemble the positioned model. */
+export declare function finalizeRoadmap(fx: FinalizeContext, steps?: readonly FinalizeStep[]): LayoutResult;
+//# sourceMappingURL=finalize.d.ts.map

package/dist/phases/finalize.d.ts.map

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