@nowline/layout 0.8.6 → 0.9.0

package/src/nodes/wave-node.ts

@@ -0,0 +1,609 @@
+// Positioned waves (specs/waves.md §8.7, §9.1-§9.5): the solved spans engine
+// A's barrier driver settled on, in declaration order, plus everything the
+// renderer draws for them: strip cells (label fit chain, tooltip, empty-wave
+// diamonds, gap labels, the all-empty placeholder), styled colours, boundary
+// lines, crossings over background bars, and the legend.
+//
+// Built from the frozen `WaveLayoutState` after the post-layout extent growth
+// and the marker-row `deltaY` shift, so the dates read the final scale and
+// every y is final. Growth only extends the domain end (origin and
+// pixels-per-day are unchanged), so the spans' x never move.
+
+import type { StyleProperty } from '@nowline/core';
+import { propKey } from '@nowline/core/internal';
+import { propValue } from '../dsl-utils.js';
+import type { LocaleStrings } from '../i18n.js';
+import { pickInlineDate } from '../inline-date-pin-geometry.js';
+import {
+    INLINE_DATE_GLYPH_GAP_PX,
+    INLINE_DATE_GLYPH_INSET_LEFT_PX,
+    INLINE_DATE_GLYPH_TILE_SIZE_PX,
+    ITEM_FOOTNOTE_INDICATOR_STEP_PX,
+} from '../item-bar-geometry.js';
+import type { LayoutContext } from '../layout-context.js';
+import { estimateTextWidth } from '../text-measure.js';
+import { contrastRatio, hexToRgb } from '../themes/contrast.js';
+import { resolveColor } from '../themes/index.js';
+import type { Theme } from '../themes/shape.js';
+import {
+    WAVE_CELL_INSET_PX,
+    WAVE_LABEL_HALO_INSET_Y_PX,
+    WAVE_LABEL_HALO_PAD_PX,
+    WAVE_LEGEND_BASELINE_OFFSET_PX,
+    WAVE_LEGEND_LINE_PX,
+    WAVE_LEGEND_SWATCH_GAP_PX,
+    WAVE_LEGEND_SWATCH_HEIGHT_PX,
+    WAVE_LEGEND_SWATCH_WIDTH_PX,
+    WAVE_STRIP_LABEL_FONT_SIZE_PX,
+    WAVE_STRIP_LABEL_PAD_PX,
+    WAVE_STYLED_STRIP_MIX_OPACITY,
+} from '../themes/shared.js';
+import type {
+    BoundingBox,
+    InlineDatePin,
+    PositionedIncludeRegion,
+    PositionedItem,
+    PositionedSwimlane,
+    PositionedTrackChild,
+    PositionedWave,
+    PositionedWaveBoundary,
+    PositionedWaveCrossing,
+    PositionedWaveLegend,
+    PositionedWaveStyle,
+    WaveLegendEntry,
+} from '../types.js';
+import { summarizeWaves } from '../wave-barrier.js';
+import { waveHatchKind } from '../wave-hatch.js';
+import {
+    dateAtX,
+    spanEndDateAtX,
+    WAVE_EDGE_TOLERANCE_PX,
+    type WaveLayoutState,
+} from '../wave-layout.js';
+import { MARKER_BOLD_WIDTH_FACTOR } from './marker-geometry.js';
+
+/** WCAG AA floor for the strip label against its composited cell fill. */
+const WAVE_LABEL_MIN_CONTRAST = 4.5;
+
+/** Everything `buildWaves` produces; the caller attaches it to the model. */
+export interface BuiltWaves {
+    waves: PositionedWave[];
+    /** Boundary lines, left to right (empty when every wave is empty). */
+    boundaries: PositionedWaveBoundary[];
+    /** Crossings over the main lanes' background bars. */
+    crossings: PositionedWaveCrossing[];
+    /** Crossings over each isolated region's background bars, parallel to `includes`. */
+    regionCrossings: PositionedWaveCrossing[][];
+    /** True when any placed item (main lanes or regions) is background work. */
+    hasBackground: boolean;
+}
+
+/**
+ * Build the positioned waves, boundaries and crossings. `state` must be
+ * frozen: its `pass` is the pass that ran with the solved `S`/`E`, so its
+ * member counts cover the main lanes and the first-level regions exactly
+ * once (later placements never accumulate). `ctx.timeline.waveStrip` is
+ * set whenever some wave has items; when none does, nothing is drawn and the
+ * waves carry their spans only (specs/waves.md §9.1).
+ */
+export function buildWaves(
+    state: WaveLayoutState,
+    ctx: LayoutContext,
+    strings: LocaleStrings,
+    swimlanes: PositionedSwimlane[],
+    includes: PositionedIncludeRegion[],
+): BuiltWaves {
+    if (!state.frozen || !state.solve) {
+        throw new Error('buildWaves: the wave barrier has not settled');
+    }
+    const spans = summarizeWaves(
+        state.plan,
+        state.solve,
+        state.pass,
+        state.origin,
+        state.floors,
+        WAVE_EDGE_TOLERANCE_PX,
+    );
+    const allEmpty = spans.every((s) => s.memberCount === 0);
+    // With every wave empty the roadmap draws no strip: the waves keep a
+    // zero-height one under the tick panel, for their boxes only.
+    const strip = ctx.timeline.waveStrip ?? {
+        y: ctx.timeline.tickPanelY + ctx.timeline.tickPanelHeight,
+        height: 0,
+    };
+    if (!ctx.timeline.waveStrip && !allEmpty) {
+        throw new Error('buildWaves: the timeline has no wave strip');
+    }
+    // The visible part of a span is its overlap with the timeline.
+    const visLeft = ctx.timeline.box.x;
+    const visRight = visLeft + ctx.timeline.box.width;
+    // Every strip halo spans the strip less a vertical inset.
+    const haloY = strip.y + WAVE_LABEL_HALO_INSET_Y_PX;
+    const haloHeight = strip.height - 2 * WAVE_LABEL_HALO_INSET_Y_PX;
+    let ordinal = 0;
+
+    const waves = spans.map((span, i): PositionedWave => {
+        const decl = state.plan.waves[i];
+        const title = decl.title ?? span.id;
+        const empty = span.memberCount === 0;
+        const startDate = dateAtX(span.start, ctx);
+        const endDate = spanEndDateAtX(span.start, span.end, ctx);
+        const visibleOrdinal = empty ? undefined : ordinal++;
+        const footnoteIndicators = waveFootnoteIndicators(span.id, ctx);
+        const style = waveStyle(decl.properties, visibleOrdinal, ctx);
+
+        const cellLeft = Math.max(span.start, visLeft);
+        const cellRight = Math.min(span.end, visRight);
+        const visibleWidth = Math.max(0, cellRight - cellLeft);
+
+        // A declared date floor (`after:2026-11-02`) puts a calendar glyph at
+        // the cell's left, whether or not the floor opened a gap (§9.1); the
+        // label clears it like it clears the superscripts.
+        const floorDate = pickInlineDate(
+            state.plan.floors[i]?.ref !== undefined ? [state.plan.floors[i].ref as string] : [],
+        );
+        const glyphFits =
+            floorDate !== undefined &&
+            visibleWidth >=
+                INLINE_DATE_GLYPH_INSET_LEFT_PX +
+                    INLINE_DATE_GLYPH_TILE_SIZE_PX +
+                    WAVE_STRIP_LABEL_PAD_PX;
+        const glyphReserve = glyphFits
+            ? INLINE_DATE_GLYPH_TILE_SIZE_PX + INLINE_DATE_GLYPH_GAP_PX
+            : 0;
+
+        // Fit chain (§9.1): try every candidate beside the footnote
+        // superscripts; when none fits with them, the superscripts move
+        // to the legend and the chain runs again on the label alone.
+        let fit: LabelFit | undefined;
+        let footnotesShown = false;
+        if (!empty) {
+            if (footnoteIndicators.length > 0) {
+                const superscriptWidth =
+                    footnoteIndicators.length * ITEM_FOOTNOTE_INDICATOR_STEP_PX;
+                fit = fitStripLabel(
+                    title,
+                    span.id,
+                    i + 1,
+                    visibleWidth,
+                    superscriptWidth + glyphReserve,
+                );
+                footnotesShown = fit !== undefined;
+            }
+            fit ??= fitStripLabel(title, span.id, i + 1, visibleWidth, glyphReserve);
+        }
+
+        // An empty wave is not drawn (§9.1); the NL.I1006 insight names it.
+        const labelX = empty ? span.start : (cellLeft + cellRight) / 2;
+
+        const range = empty ? isoDay(startDate) : `${isoDay(startDate)} – ${isoDay(endDate)}`;
+        const tooltipParts = [title, range];
+        if (empty) tooltipParts.push(strings.waveNoItems);
+        else if (span.heldBy !== undefined) {
+            tooltipParts.push(`${strings.waveHeldBy} ${span.heldBy}`);
+        }
+
+        // A gap (S_k > E_{k-1}) shows the floor reference that opened it.
+        let gapLabel: PositionedWave['strip']['gapLabel'];
+        const prior = spans[i - 1];
+        if (
+            !allEmpty &&
+            prior !== undefined &&
+            span.floorRef !== undefined &&
+            span.start - prior.end > WAVE_EDGE_TOLERANCE_PX
+        ) {
+            const gapLeft = Math.max(prior.end, visLeft);
+            const gapRight = Math.min(span.start, visRight);
+            const textWidth = estimateTextWidth(span.floorRef, WAVE_STRIP_LABEL_FONT_SIZE_PX);
+            if (textWidth + 2 * WAVE_STRIP_LABEL_PAD_PX <= gapRight - gapLeft) {
+                const x = (gapLeft + gapRight) / 2;
+                const haloWidth = textWidth + 2 * WAVE_LABEL_HALO_PAD_PX;
+                gapLabel = {
+                    text: span.floorRef,
+                    x,
+                    halo: { x: x - haloWidth / 2, y: haloY, width: haloWidth, height: haloHeight },
+                };
+            }
+        }
+
+        // The painted cell, and in it the label and superscript halos
+        // (§9.1): the superscripts right-aligned, the label centred on the
+        // visible span but never under them.
+        const stripBox: BoundingBox = {
+            x: span.start,
+            y: strip.y,
+            width: span.end - span.start,
+            height: strip.height,
+        };
+        const cell = empty ? undefined : stripCellBox(stripBox, ctx.timeline.box);
+        let labelDraw: PositionedWave['strip']['labelDraw'];
+        let superscripts: PositionedWave['strip']['superscripts'];
+        let inlineDatePin: InlineDatePin | undefined;
+        if (cell) {
+            if (glyphFits && floorDate !== undefined) {
+                inlineDatePin = {
+                    side: 'after',
+                    isoDate: floorDate,
+                    glyphTopLeft: {
+                        x: cell.x + INLINE_DATE_GLYPH_INSET_LEFT_PX,
+                        y: strip.y + (strip.height - INLINE_DATE_GLYPH_TILE_SIZE_PX) / 2,
+                    },
+                    glyphSize: INLINE_DATE_GLYPH_TILE_SIZE_PX,
+                    spilled: false,
+                };
+            }
+            const paintedRight = cell.x + cell.width;
+            const superscriptWidth = footnotesShown
+                ? footnoteIndicators.length * ITEM_FOOTNOTE_INDICATOR_STEP_PX
+                : 0;
+            if (superscriptWidth) {
+                const right = paintedRight - WAVE_STRIP_LABEL_PAD_PX + WAVE_LABEL_HALO_PAD_PX;
+                const left =
+                    paintedRight -
+                    WAVE_STRIP_LABEL_PAD_PX -
+                    superscriptWidth -
+                    WAVE_LABEL_HALO_PAD_PX;
+                superscripts = {
+                    rightX: paintedRight - WAVE_STRIP_LABEL_PAD_PX,
+                    halo: { x: left, y: haloY, width: right - left, height: haloHeight },
+                };
+            }
+            if (fit) {
+                const textWidth = stripLabelWidth(fit.label);
+                const rightBound = superscriptWidth
+                    ? Math.min(
+                          labelX,
+                          paintedRight - WAVE_STRIP_LABEL_PAD_PX - superscriptWidth - textWidth / 2,
+                      )
+                    : labelX;
+                const x = inlineDatePin
+                    ? Math.max(
+                          rightBound,
+                          inlineDatePin.glyphTopLeft.x +
+                              INLINE_DATE_GLYPH_TILE_SIZE_PX +
+                              INLINE_DATE_GLYPH_GAP_PX +
+                              textWidth / 2,
+                      )
+                    : rightBound;
+                const haloWidth = textWidth + 2 * WAVE_LABEL_HALO_PAD_PX;
+                labelDraw = {
+                    x,
+                    halo: { x: x - haloWidth / 2, y: haloY, width: haloWidth, height: haloHeight },
+                };
+            }
+        }
+
+        return {
+            id: span.id,
+            title,
+            index: i,
+            ...(visibleOrdinal !== undefined ? { visibleOrdinal } : {}),
+            startX: span.start,
+            endX: span.end,
+            startDate,
+            endDate,
+            memberCount: span.memberCount,
+            empty,
+            ...(span.heldBy !== undefined ? { heldBy: span.heldBy } : {}),
+            ...(span.floorRef !== undefined ? { floorRef: span.floorRef } : {}),
+            columnBox: {
+                x: span.start,
+                y: ctx.chartTopY,
+                width: span.end - span.start,
+                height: ctx.swimlaneBottomY - ctx.chartTopY,
+            },
+            strip: {
+                box: {
+                    x: span.start,
+                    y: strip.y,
+                    width: span.end - span.start,
+                    height: strip.height,
+                },
+                ...(fit ? { label: fit.label } : {}),
+                labelKind: fit?.kind ?? 'none',
+                labelX,
+                ...(cell ? { cell } : {}),
+                ...(labelDraw ? { labelDraw } : {}),
+                ...(inlineDatePin ? { inlineDatePin } : {}),
+                ...(superscripts ? { superscripts } : {}),
+                tooltip: tooltipParts.join(' · '),
+                footnotesShown,
+                ...(gapLabel ? { gapLabel } : {}),
+            },
+            style,
+            footnoteIndicators,
+        };
+    });
+
+    const boundaries = allEmpty ? [] : buildBoundaries(waves, state.origin, strip.y, ctx);
+    const mainBackground = backgroundItems(swimlanes);
+    // Background items already carry their tooltip: `sequenceItem` sets it
+    // where it places them.
+    const regionBackground = includes.map((inc) => backgroundItems(inc.nestedSwimlanes));
+    const built: BuiltWaves = {
+        waves,
+        boundaries,
+        crossings: crossingsOver(mainBackground, boundaries),
+        regionCrossings: regionBackground.map((items) => crossingsOver(items, boundaries)),
+        hasBackground: mainBackground.length + regionBackground.flat().length > 0,
+    };
+    return built;
+}
+
+/**
+ * A strip cell's painted box: the wave's strip box clipped to the timeline's
+ * backing panel, inset by half the panel's 1 px stroke so the cell never
+ * covers it. Undefined when the two do not overlap (an off-screen wave).
+ */
+function stripCellBox(box: BoundingBox, timelineBox: BoundingBox): BoundingBox | undefined {
+    const inset = WAVE_CELL_INSET_PX;
+    const a: BoundingBox = {
+        x: box.x,
+        y: box.y + inset,
+        width: box.width,
+        height: box.height - 2 * inset,
+    };
+    const b: BoundingBox = {
+        x: timelineBox.x + inset,
+        y: box.y,
+        width: timelineBox.width - 2 * inset,
+        height: box.height,
+    };
+    const x1 = Math.max(a.x, b.x);
+    const y1 = Math.max(a.y, b.y);
+    const x2 = Math.min(a.x + a.width, b.x + b.width);
+    const y2 = Math.min(a.y + a.height, b.y + b.height);
+    if (x2 <= x1 || y2 <= y1) return undefined;
+    return { x: x1, y: y1, width: x2 - x1, height: y2 - y1 };
+}
+
+interface LabelFit {
+    kind: 'title' | 'id' | 'ellipsis' | 'ordinal';
+    label: string;
+}
+
+/** A strip label's estimated width: 10 px text, widened for its bold weight. */
+function stripLabelWidth(text: string): number {
+    return estimateTextWidth(text, WAVE_STRIP_LABEL_FONT_SIZE_PX) * MARKER_BOLD_WIDTH_FACTOR;
+}
+
+/**
+ * The first strip label candidate that fits (§9.1): the title, the id, the
+ * title ellipsized to 3 or more characters plus "…", then the 1-based
+ * `#k`. The test is the bold 10 px width estimate plus `extraWidth` (the
+ * footnote superscripts) plus 6 px padding on each side. Undefined: no
+ * label.
+ */
+export function fitStripLabel(
+    title: string,
+    id: string,
+    ordinal: number,
+    visibleWidth: number,
+    extraWidth: number,
+): LabelFit | undefined {
+    const fits = (text: string): boolean =>
+        stripLabelWidth(text) + extraWidth + 2 * WAVE_STRIP_LABEL_PAD_PX <= visibleWidth;
+    if (fits(title)) return { kind: 'title', label: title };
+    if (id !== title && fits(id)) return { kind: 'id', label: id };
+    for (let n = title.length - 1; n >= 3; n--) {
+        const prefix = title.slice(0, n).trimEnd();
+        if (prefix.length < 3) break;
+        const text = `${prefix}…`;
+        if (fits(text)) return { kind: 'ellipsis', label: text };
+    }
+    const hash = `#${ordinal}`;
+    if (fits(hash)) return { kind: 'ordinal', label: hash };
+    return undefined;
+}
+
+/** Footnotes whose `on:` names the wave, as 1-based numbers, ascending. */
+function waveFootnoteIndicators(id: string, ctx: LayoutContext): number[] {
+    const out: number[] = [];
+    for (const [fid, hosts] of ctx.footnoteHosts.entries()) {
+        if (!hosts.includes(id)) continue;
+        const n = ctx.footnoteIndex.get(fid);
+        if (n !== undefined) out.push(n);
+    }
+    return out.sort((a, b) => a - b);
+}
+
+/**
+ * A wave's colours (§9.4). Only the named `style:` applies (there is no
+ * `default wave`), and of it only `bg`, `fg`, `text` and `border`. The
+ * style is read raw.
+ */
+function waveStyle(
+    properties: Parameters<typeof propValue>[0],
+    visibleOrdinal: number | undefined,
+    ctx: LayoutContext,
+): PositionedWaveStyle {
+    const theme = ctx.styleCtx.theme;
+    const raw = new Map<string, string>();
+    const styleId = propValue(properties, 'style');
+    const decl = styleId ? ctx.styleCtx.styles.get(styleId) : undefined;
+    for (const p of (decl?.properties ?? []) as StyleProperty[]) {
+        raw.set(propKey(p), p.value);
+    }
+    const color = (key: string): string | undefined => {
+        const v = raw.get(key);
+        if (v === undefined) return undefined;
+        const c = resolveColor(v, theme);
+        return c === 'none' ? undefined : c;
+    };
+    const tint = color('bg');
+    const stripFill =
+        visibleOrdinal !== undefined && visibleOrdinal % 2 === 1
+            ? theme.wave.stripFillAlt
+            : theme.wave.stripFill;
+    // The cell the label sits on: the strip fill under the tint overlay.
+    const cellFill = tint
+        ? (mixHex(stripFill, tint, WAVE_STYLED_STRIP_MIX_OPACITY) ?? stripFill)
+        : stripFill;
+    const border = raw.get('border');
+    return {
+        ...(tint ? { tint } : {}),
+        stripFill,
+        text: color('text') ?? readableLabelText(theme.wave, cellFill),
+        boundary: color('fg') ?? theme.wave.boundary,
+        boundaryDash: border === 'dashed' ? '4 2' : border === 'dotted' ? '1 2' : null,
+    };
+}
+
+const HEX_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+
+/** `top` composited over `base` at `alpha`, as `#rrggbb`; undefined unless both are hex. */
+function mixHex(base: string, top: string, alpha: number): string | undefined {
+    if (!HEX_RE.test(base) || !HEX_RE.test(top)) return undefined;
+    const b = hexToRgb(base);
+    const t = hexToRgb(top);
+    return `#${b
+        .map((v, i) =>
+            Math.round(v * (1 - alpha) + t[i] * alpha)
+                .toString(16)
+                .padStart(2, '0'),
+        )
+        .join('')}`;
+}
+
+/**
+ * `wave.labelText` when it reaches 4.5:1 against `fill` (or either colour is
+ * not hex), else whichever of the theme's dark (`hatch`) and light
+ * (`hatchOnDark`) strokes contrasts more.
+ */
+export function readableLabelText(
+    wave: Pick<Theme['wave'], 'labelText' | 'hatch' | 'hatchOnDark'>,
+    fill: string,
+): string {
+    const preferred = wave.labelText;
+    if (!HEX_RE.test(preferred) || !HEX_RE.test(fill)) return preferred;
+    if (contrastRatio(preferred, fill) >= WAVE_LABEL_MIN_CONTRAST) return preferred;
+    return contrastRatio(wave.hatch, fill) >= contrastRatio(wave.hatchOnDark, fill)
+        ? wave.hatch
+        : wave.hatchOnDark;
+}
+
+/**
+ * One line at every distinct x in `{S_k} ∪ {E_k}` of the non-empty waves,
+ * except the origin (§9.2): contiguous waves share a line, a gap gives two,
+ * and an empty wave adds none of its own. A wave's opening line uses its
+ * own style; a closing line that opens nothing (a gap, or `E_n`) uses the
+ * closing wave's.
+ */
+function buildBoundaries(
+    waves: PositionedWave[],
+    origin: number,
+    topY: number,
+    ctx: LayoutContext,
+): PositionedWaveBoundary[] {
+    const edges: Array<{ x: number; wave: PositionedWave; opening: boolean }> = [];
+    for (const w of waves) {
+        if (w.empty) continue;
+        edges.push({ x: w.startX, wave: w, opening: true });
+        edges.push({ x: w.endX, wave: w, opening: false });
+    }
+    edges.sort((a, b) => a.x - b.x);
+    const out: PositionedWaveBoundary[] = [];
+    let i = 0;
+    while (i < edges.length) {
+        let j = i;
+        while (j < edges.length && edges[j].x - edges[i].x < WAVE_EDGE_TOLERANCE_PX) j++;
+        const group = edges.slice(i, j);
+        i = j;
+        const x = group[0].x;
+        if (Math.abs(x - origin) < WAVE_EDGE_TOLERANCE_PX) continue;
+        const owner = (group.find((e) => e.opening) ?? group[0]).wave;
+        out.push({
+            x,
+            topY,
+            bottomY: ctx.swimlaneBottomY,
+            stroke: owner.style.boundary,
+            dash: owner.style.boundaryDash,
+        });
+    }
+    return out;
+}
+
+/** Background items (`waveRole: 'background'`) in lane and document order. */
+function backgroundItems(lanes: PositionedSwimlane[]): PositionedItem[] {
+    const out: PositionedItem[] = [];
+    const walk = (children: PositionedTrackChild[]): void => {
+        for (const child of children) {
+            if (child.kind === 'item') {
+                if (child.waveRole === 'background') out.push(child);
+            } else {
+                walk(child.children);
+            }
+        }
+    };
+    for (const lane of lanes) {
+        walk(lane.children);
+        out.push(...backgroundItems(lane.nested));
+    }
+    return out;
+}
+
+/**
+ * A crossing for every boundary strictly inside a background bar's visual
+ * extent (§9.3). Item boxes are visual (inset from the logical edges), so a
+ * boundary at a bar's logical edge falls in the inset and gets none.
+ */
+function crossingsOver(
+    items: PositionedItem[],
+    boundaries: PositionedWaveBoundary[],
+): PositionedWaveCrossing[] {
+    const out: PositionedWaveCrossing[] = [];
+    for (const item of items) {
+        const left = item.box.x;
+        const right = item.box.x + item.box.width;
+        for (const b of boundaries) {
+            if (left < b.x && b.x < right) {
+                out.push({
+                    x: b.x,
+                    topY: item.box.y,
+                    bottomY: item.box.y + item.box.height,
+                    stroke: b.stroke,
+                });
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * The wave legend (§9.5), or undefined without background work (which there
+ * is only when some wave is drawn): one hatch swatch, `Background work (not
+ * in a wave)`, `WAVE_LEGEND_LINE_PX` high from `topY` at the chart origin.
+ */
+export function buildWaveLegend(
+    built: BuiltWaves,
+    ctx: LayoutContext,
+    strings: LocaleStrings,
+    topY: number,
+): PositionedWaveLegend | undefined {
+    if (!built.hasBackground) return undefined;
+    const left = ctx.timeline.originX;
+    const text = strings.waveLegendBackground;
+    const textX0 = WAVE_LEGEND_SWATCH_WIDTH_PX + WAVE_LEGEND_SWATCH_GAP_PX;
+    const width = textX0 + estimateTextWidth(text, WAVE_STRIP_LABEL_FONT_SIZE_PX);
+    const entry: WaveLegendEntry = {
+        kind: 'background',
+        text,
+        swatch: {
+            x: left,
+            y: topY + (WAVE_LEGEND_LINE_PX - WAVE_LEGEND_SWATCH_HEIGHT_PX) / 2,
+            width: WAVE_LEGEND_SWATCH_WIDTH_PX,
+            height: WAVE_LEGEND_SWATCH_HEIGHT_PX,
+        },
+        // The hatched swatch is a default item bar.
+        hatch: waveHatchKind(ctx.styleCtx.theme.entities.item.bg),
+        runs: [{ text, x: left + textX0, y: topY + WAVE_LEGEND_BASELINE_OFFSET_PX }],
+    };
+    return {
+        box: { x: left, y: topY, width, height: WAVE_LEGEND_LINE_PX },
+        entries: [entry],
+    };
+}
+
+function isoDay(d: Date): string {
+    return d.toISOString().slice(0, 10);
+}

package/src/non-working-display.ts

@@ -0,0 +1,32 @@
+// How the chart shows a calendar's non-working days (specs/working-
+// calendar.md §4.2): `hide` collapses them to zero width (the default),
+// `show` draws them at full width as shaded bands. One shared definition
+// for the layout and every surface that takes a render-time option, so the
+// accepted spellings cannot drift between them. The table itself lives in
+// core (`value-tables.ts`), which the validator and the editor completions
+// read too; the GitHub Action still has its own copy, though it bundles
+// layout's theme parser.
+
+import { NON_WORKING_DISPLAYS, type NonWorkingDisplay } from '@nowline/core/internal';
+
+/** A non-working display value. */
+export type { NonWorkingDisplay };
+
+/** Every display value, in documentation order. */
+export { NON_WORKING_DISPLAYS };
+
+/** True when `value` is a display value. */
+export function isNonWorkingDisplay(value: unknown): value is NonWorkingDisplay {
+    return value === 'hide' || value === 'show';
+}
+
+/**
+ * Parse a raw surface option. Empty or missing input is "unset" and returns
+ * undefined, so the file's `default roadmap non-working:` key still applies;
+ * anything other than `hide` or `show` throws a `RangeError`.
+ */
+export function parseNonWorkingDisplay(raw: string | undefined): NonWorkingDisplay | undefined {
+    if (raw === undefined || raw === '') return undefined;
+    if (isNonWorkingDisplay(raw)) return raw;
+    throw new RangeError(`Invalid non-working display "${raw}". Expected hide or show.`);
+}