@nowline/renderer 0.8.6 → 0.10.0

package/src/stage.ts

@@ -0,0 +1,191 @@
+// One staging function for every render surface (specs/surface-options.md
+// §3.3): parse and validate, resolve includes, apply the include-error
+// precedence, load the logo, build the wave plan and the day schedule, lay
+// out. Rendering, diagnostics formatting,
+// `strict` and layout insights stay with each caller, which maps the result
+// to its own shape.
+
+import {
+    buildWavePlan,
+    collectDocumentDiagnostics,
+    isRoutedResolveDiagnostic,
+    type NowlineFile,
+    type NowlineServices,
+    type RawDiagnostic,
+    type ResolveDiagnostic,
+    type ResolveResult,
+    resolveIncludes,
+    type WavePlan,
+} from '@nowline/core';
+import {
+    type LayoutOptions,
+    layoutRoadmap,
+    type PositionedRoadmap,
+    type RoadmapSchedule,
+    roadmapLogoRef,
+    scheduleRoadmap,
+} from '@nowline/layout';
+import { type LangiumDocument, type LangiumSharedCoreServices, URI } from 'langium';
+import { type LoadedLogo, loadLogo } from './logo.js';
+import type { AssetResolver } from './svg/render.js';
+
+/** The layout options a stage reads; a staged roadmap records the values it used. */
+export type StageLayout = Pick<
+    LayoutOptions,
+    'theme' | 'today' | 'width' | 'locale' | 'nonWorking'
+>;
+
+/** Langium's `DiagnosticSeverity.Error`. */
+const SEVERITY_ERROR = 1;
+
+export interface StageInputs {
+    source: string;
+    /** Absolute path: base for includes and assets. */
+    sourcePath: string;
+    /** The caller's Langium services (each pipeline keeps its own instance). */
+    services: { shared: LangiumSharedCoreServices; Nowline: NowlineServices };
+    readSource: (absPath: string) => Promise<string>;
+    /** Omitted: no asset access (the embed), so a `logo:` lays out as if absent. */
+    assetResolver?: AssetResolver;
+    /** A document the caller already parsed and validated from `source`. */
+    document?: LangiumDocument<NowlineFile>;
+    layout: StageLayout;
+    /**
+     * An include error the caller tolerates, such as the browser's
+     * single-file mode skipping every include: it takes no part in the
+     * include-error precedence and stays in `resolved.diagnostics` for the
+     * caller to report. Omitted: every include error counts.
+     */
+    isToleratedIncludeError?: (diagnostic: ResolveDiagnostic) => boolean;
+}
+
+export type StageResult =
+    | {
+          kind: 'invalid';
+          document: LangiumDocument<NowlineFile>;
+          /** Lexer, parser and validator diagnostics with errors among them. */
+          diagnostics: RawDiagnostic[];
+      }
+    | {
+          kind: 'include-error';
+          document: LangiumDocument<NowlineFile>;
+          /** The first uncoded include error, when one exists: it wins (waves.md §6.1). */
+          legacy?: ResolveDiagnostic;
+          /** Routed (wave-rule) diagnostics, errors and warnings; empty when `legacy` is set. */
+          routed: ResolveDiagnostic[];
+          /** Every resolver diagnostic in order, for callers that report more than the winner. */
+          resolved: ResolveResult;
+      }
+    | {
+          kind: 'staged';
+          document: LangiumDocument<NowlineFile>;
+          ast: NowlineFile;
+          resolved: ResolveResult;
+          /** Routed warnings (no errors). */
+          routed: ResolveDiagnostic[];
+          /** The loaded logo: size for layout, bytes for `RenderOptions.logo`. */
+          logo?: LoadedLogo;
+          /** Asset warnings (missing or unreadable logo); the caller applies `strict`. */
+          warnings: string[];
+          /** The wave plan (`buildWavePlan`); `null` when the roadmap declares no waves. */
+          plan: WavePlan | null;
+          /**
+           * The day schedule `model` was laid out with (`scheduleRoadmap`,
+           * `plan` included as `schedule.plan`); exporters reuse it through
+           * `ExportInputs.schedule` (specs/scheduler-unification.md §3.6).
+           */
+          schedule: RoadmapSchedule;
+          model: PositionedRoadmap;
+          /** The layout options `model` was laid out with, picked from `StageInputs.layout`. */
+          layout: StageLayout;
+      };
+
+/** A roadmap that staged without errors, ready to render or export. */
+export type StagedRoadmap = Extract<StageResult, { kind: 'staged' }>;
+
+let documentCounter = 0;
+
+function freshUri(): URI {
+    // A fresh URI per stage: reusing one lets Langium mutate the prior
+    // document in place.
+    return URI.parse(`memory:///stage-${++documentCounter}.nowline`);
+}
+
+async function buildDocument(inputs: StageInputs): Promise<LangiumDocument<NowlineFile>> {
+    if (inputs.document) return inputs.document;
+    const { workspace } = inputs.services.shared;
+    const document = workspace.LangiumDocumentFactory.fromString<NowlineFile>(
+        inputs.source,
+        freshUri(),
+    );
+    await workspace.DocumentBuilder.build([document], { validation: true });
+    return document;
+}
+
+function isErrorDiagnostic(raw: RawDiagnostic): boolean {
+    return raw.origin !== 'validation' || raw.diagnostic.severity === SEVERITY_ERROR;
+}
+
+/**
+ * Parse, validate, resolve includes, load the logo, schedule and lay out `source`.
+ * Returns `invalid` on a lexer, parser or validator error, `include-error`
+ * on a resolver error, and `staged` with the positioned model otherwise.
+ */
+export async function stageRoadmap(inputs: StageInputs): Promise<StageResult> {
+    const document = await buildDocument(inputs);
+    const diagnostics = collectDocumentDiagnostics(document);
+    if (diagnostics.some(isErrorDiagnostic)) {
+        return { kind: 'invalid', document, diagnostics };
+    }
+
+    const ast = document.parseResult.value;
+    const resolved = await resolveIncludes(ast, inputs.sourcePath, {
+        services: inputs.services.Nowline,
+        readFile: inputs.readSource,
+    });
+
+    // An uncoded include error is more fundamental than the wave-rule
+    // errors: the first one wins and hides the routed diagnostics.
+    const isTolerated = inputs.isToleratedIncludeError ?? (() => false);
+    const errors = resolved.diagnostics.filter((d) => d.severity === 'error' && !isTolerated(d));
+    const routed = resolved.diagnostics.filter(isRoutedResolveDiagnostic);
+    const legacy = errors.find((d) => !isRoutedResolveDiagnostic(d));
+    if (legacy) {
+        return { kind: 'include-error', document, legacy, routed: [], resolved };
+    }
+    if (errors.length > 0) {
+        return { kind: 'include-error', document, routed, resolved };
+    }
+
+    // A failed logo load warns and lays out as if no logo were declared.
+    const warnings: string[] = [];
+    const logo = await loadLogo(roadmapLogoRef(ast), inputs.assetResolver, (message) =>
+        warnings.push(message),
+    );
+    // Named keys, not a spread: a caller may pass a wider options object.
+    const { theme, today, width, locale, nonWorking } = inputs.layout;
+    const layout: StageLayout = { theme, today, width, locale, nonWorking };
+    // One wave plan and one day schedule per staging: layout reuses the
+    // schedule and the exporters read it from `ExportInputs`
+    // (specs/scheduler-unification.md §3.6).
+    const plan = buildWavePlan(resolved) ?? null;
+    const schedule = scheduleRoadmap(ast, resolved, { today, plan });
+    const model = layoutRoadmap(ast, resolved, {
+        ...layout,
+        schedule,
+        logo: logo?.dimensions,
+    });
+    return {
+        kind: 'staged',
+        document,
+        ast,
+        resolved,
+        routed,
+        logo,
+        warnings,
+        plan,
+        schedule,
+        model,
+        layout,
+    };
+}

package/src/svg/edges.ts

@@ -0,0 +1,154 @@
+// The dependency-edge layer: the arrows that join one item to another, their
+// solid and dotted slack legs, and the rounded orthogonal paths they follow.
+
+import type { Point, PositionedDependencyEdge, Theme } from '@nowline/layout';
+import { ARROW_HEAD_LENGTH_PX, ARROW_HEAD_WIDTH_PX, EDGE_CORNER_RADIUS } from '@nowline/layout';
+import { num, tag } from './xml.js';
+
+/** Dash pattern of a dependency's slack leg: the dotted look of milestone slack lines. */
+const SLACK_DASH = '3 3';
+
+// A dependency arrow (specs/true-width-layout.md §3.4). It paints behind
+// the bars (see `renderRoadmap`), so a leg that crosses a bar passes behind
+// it. Vertical legs are solid; the horizontal leg is dotted when the target
+// waits. The head is drawn, not a marker, so it can shrink to a narrow
+// target and become a dot (§8 O6).
+export function renderEdge(e: PositionedDependencyEdge, palette: Theme): string {
+    const points = e.waypoints;
+    if (points.length < 2) return '';
+    const color = palette.dependency.edgeStroke;
+    const tip = points[points.length - 1];
+    const prev = points[points.length - 2];
+    const len = Math.hypot(tip.x - prev.x, tip.y - prev.y);
+    if (len === 0) return '';
+    const ux = (tip.x - prev.x) / len;
+    const uy = (tip.y - prev.y) / len;
+    const half = e.headWidth / 2;
+    // The leg stops where the head starts, so a dotted leg never shows
+    // through it.
+    const headLength =
+        e.head === 'dot' ? half : (e.headWidth * ARROW_HEAD_LENGTH_PX) / ARROW_HEAD_WIDTH_PX;
+    // A last leg no longer than the head is all head.
+    const leg =
+        len > headLength
+            ? [...points.slice(0, -1), { x: tip.x - ux * headLength, y: tip.y - uy * headLength }]
+            : points.slice(0, -1);
+    const parts = [legPaths(leg, e.slack, color)];
+    const headFill = palette.arrowhead.neutral;
+    if (e.head === 'dot') {
+        parts.push(
+            tag('circle', {
+                cx: num(tip.x - ux * half),
+                cy: num(tip.y - uy * half),
+                r: num(half),
+                fill: headFill,
+            }),
+        );
+    } else {
+        const bx = tip.x - ux * headLength;
+        const by = tip.y - uy * headLength;
+        parts.push(
+            tag('path', {
+                d:
+                    `M${num(bx - uy * half)} ${num(by + ux * half)} ` +
+                    `L${num(tip.x)} ${num(tip.y)} ` +
+                    `L${num(bx + uy * half)} ${num(by - ux * half)} z`,
+                fill: headFill,
+            }),
+        );
+    }
+    return tag('g', { 'data-layer': 'dependency' }, parts.join(''));
+}
+
+// An arrow's legs: one rounded path, or for a slack arrow its solid
+// vertical legs and its dotted horizontal ones. Empty when the head is all
+// there is (a leg no longer than the head).
+function legPaths(leg: Point[], slack: boolean, color: string): string {
+    if (leg.length < 2) return '';
+    const stroke = { fill: 'none', stroke: color, 'stroke-width': 1.1, 'stroke-linejoin': 'round' };
+    if (!slack)
+        return tag('path', { d: roundedOrthogonalPath(leg, EDGE_CORNER_RADIUS), ...stroke });
+    const { solid, dotted } = splitSlackPath(leg, EDGE_CORNER_RADIUS);
+    return (
+        (solid ? tag('path', { d: solid, ...stroke }) : '') +
+        (dotted
+            ? tag('path', {
+                  d: dotted,
+                  ...stroke,
+                  'stroke-dasharray': SLACK_DASH,
+                  'stroke-linecap': 'round',
+              })
+            : '')
+    );
+}
+
+// A slack arrow's path in two parts: its vertical legs with the rounded
+// corners (solid) and its horizontal legs (dotted), so the dash pattern
+// marks the wait alone.
+function splitSlackPath(points: Point[], radius: number): { solid: string; dotted: string } {
+    const n = points.length;
+    const before: Point[] = [];
+    const after: Point[] = [];
+    const solid: string[] = [];
+    for (let i = 1; i < n - 1; i++) {
+        const prev = points[i - 1];
+        const cur = points[i];
+        const next = points[i + 1];
+        const inLen = Math.hypot(cur.x - prev.x, cur.y - prev.y);
+        const outLen = Math.hypot(next.x - cur.x, next.y - cur.y);
+        const r = Math.min(radius, inLen / 2, outLen / 2);
+        const dIn = { x: Math.sign(cur.x - prev.x), y: Math.sign(cur.y - prev.y) };
+        const dOut = { x: Math.sign(next.x - cur.x), y: Math.sign(next.y - cur.y) };
+        before[i] = { x: cur.x - dIn.x * r, y: cur.y - dIn.y * r };
+        after[i] = { x: cur.x + dOut.x * r, y: cur.y + dOut.y * r };
+        if (r > 0) {
+            solid.push(
+                `M${num(before[i].x)} ${num(before[i].y)} ` +
+                    `Q${num(cur.x)} ${num(cur.y)} ${num(after[i].x)} ${num(after[i].y)}`,
+            );
+        }
+    }
+    const dotted: string[] = [];
+    for (let i = 0; i < n - 1; i++) {
+        const a = i === 0 ? points[0] : after[i];
+        const b = i === n - 2 ? points[n - 1] : before[i + 1];
+        const piece = `M${num(a.x)} ${num(a.y)} L${num(b.x)} ${num(b.y)}`;
+        if (Math.abs(points[i + 1].y - points[i].y) < 1e-9) dotted.push(piece);
+        else solid.push(piece);
+    }
+    return { solid: solid.join(' '), dotted: dotted.join(' ') };
+}
+
+// Build an SVG path for a sequence of orthogonal waypoints, inserting a
+// quarter-arc at every interior bend. Falls back to straight segments when
+// adjacent points aren't axis-aligned (defensive — the layout always emits
+// orthogonal segments).
+function roundedOrthogonalPath(points: Point[], radius: number): string {
+    if (points.length < 2) return '';
+    const parts: string[] = [`M${num(points[0].x)} ${num(points[0].y)}`];
+    for (let i = 1; i < points.length; i++) {
+        const prev = points[i - 1];
+        const cur = points[i];
+        if (i === points.length - 1) {
+            parts.push(`L${num(cur.x)} ${num(cur.y)}`);
+            continue;
+        }
+        const next = points[i + 1];
+        const dxIn = Math.sign(cur.x - prev.x);
+        const dyIn = Math.sign(cur.y - prev.y);
+        const dxOut = Math.sign(next.x - cur.x);
+        const dyOut = Math.sign(next.y - cur.y);
+        const inLen = Math.hypot(cur.x - prev.x, cur.y - prev.y);
+        const outLen = Math.hypot(next.x - cur.x, next.y - cur.y);
+        const r = Math.min(radius, inLen / 2, outLen / 2);
+        if (r <= 0 || (dxIn !== 0 && dxOut !== 0) || (dyIn !== 0 && dyOut !== 0)) {
+            parts.push(`L${num(cur.x)} ${num(cur.y)}`);
+            continue;
+        }
+        const beforeBend = { x: cur.x - dxIn * r, y: cur.y - dyIn * r };
+        const afterBend = { x: cur.x + dxOut * r, y: cur.y + dyOut * r };
+        parts.push(`L${num(beforeBend.x)} ${num(beforeBend.y)}`);
+        parts.push(`Q${num(cur.x)} ${num(cur.y)} ${num(afterBend.x)} ${num(afterBend.y)}`);
+    }
+    return parts.join(' ');
+}

package/src/svg/footnotes.ts

@@ -0,0 +1,115 @@
+// The footnotes layer: the panel at the bottom of the chart that lists each
+// footnote's number, title and description, drawn only when the roadmap has
+// footnotes.
+
+import type { PositionedFootnoteArea, Theme } from '@nowline/layout';
+import { FOOTNOTE_HEADER_BASELINE_OFFSET_PX, FOOTNOTE_PANEL_PADDING_PX } from '@nowline/layout';
+import type { FontFamilies } from './render.js';
+import { num, tag, textTag } from './xml.js';
+
+export function renderFootnotes(
+    f: PositionedFootnoteArea,
+    idPrefix: string,
+    palette: Theme,
+    fonts: FontFamilies,
+): string {
+    if (f.entries.length === 0) return '';
+    const panelFill = palette.footnotePanel.fill;
+    const borderColor = palette.footnotePanel.border;
+    const headerColor = palette.footnotePanel.header;
+    const titleColor = palette.footnotePanel.title;
+    const descColor = palette.footnotePanel.description;
+    const numberColor = palette.footnotePanel.number;
+    const parts: string[] = [];
+    parts.push(
+        tag('rect', {
+            x: num(f.box.x),
+            y: num(f.box.y),
+            width: num(f.box.width),
+            height: num(f.box.height),
+            rx: 6,
+            ry: 6,
+            fill: panelFill,
+            stroke: borderColor,
+            'stroke-width': 1,
+            filter: `url(#${idPrefix}-shadow-subtle)`,
+        }),
+    );
+    parts.push(
+        textTag(
+            {
+                x: num(f.box.x + FOOTNOTE_PANEL_PADDING_PX),
+                y: num(f.box.y + FOOTNOTE_HEADER_BASELINE_OFFSET_PX),
+                'font-family': fonts.sans,
+                'font-size': 12,
+                'font-weight': 700,
+                fill: headerColor,
+            },
+            'Footnotes',
+        ),
+    );
+    // Layout places every row: the entry's number on its first row, the
+    // title and description lines (wrapped ones included) at their own
+    // baselines, and a region's heading row above its first entry.
+    const numberX = f.box.x + FOOTNOTE_PANEL_PADDING_PX;
+    for (const e of f.entries) {
+        if (e.region !== undefined && e.regionHeadingY !== undefined) {
+            parts.push(
+                textTag(
+                    {
+                        x: num(numberX),
+                        y: num(e.regionHeadingY),
+                        'font-family': fonts.sans,
+                        'font-size': 10,
+                        'font-weight': 700,
+                        fill: headerColor,
+                    },
+                    e.region,
+                ),
+            );
+        }
+        parts.push(
+            textTag(
+                {
+                    x: num(numberX),
+                    y: num(e.y),
+                    'font-family': fonts.sans,
+                    'font-size': 10,
+                    'font-weight': 700,
+                    fill: numberColor,
+                },
+                String(e.number),
+            ),
+        );
+        for (const line of e.titleLines) {
+            parts.push(
+                textTag(
+                    {
+                        x: num(line.x),
+                        y: num(line.y),
+                        'font-family': fonts.sans,
+                        'font-size': 11,
+                        'font-weight': 600,
+                        fill: titleColor,
+                    },
+                    line.text,
+                ),
+            );
+        }
+        for (const line of e.descriptionLines ?? []) {
+            parts.push(
+                textTag(
+                    {
+                        x: num(line.x),
+                        y: num(line.y),
+                        'font-family': fonts.sans,
+                        'font-size': 11,
+                        fill: descColor,
+                    },
+                    line.text,
+                ),
+            );
+        }
+    }
+    return tag('g', { 'data-layer': 'footnotes' }, parts.join(''));
+}