@nowline/layout 0.2.0

package/src/row-packer.ts

@@ -0,0 +1,271 @@
+// RowPacker — the topmost-fit row-pack engine shared by `SwimlaneNode`
+// and `GroupNode`. Tracks rows of variable height (each row's height is
+// the max of its placed children's heights, with a per-packer minimum)
+// and bumps a child to a new row when it would collide with a sibling's
+// `rightEdge`, caption `spillX`, or a slack-arrow corridor.
+//
+// Two-phase API per child:
+//   1) `placeItem(...)` / `placeBlock(...)` decides which row the child
+//      lands on. The caller then sequences the child at the returned
+//      `(rowIndex, y)`, producing a fully positioned subtree.
+//   2) `commitItem(...)` / `commitBlock(...)` records the placed child
+//      back into the packer so the row's `rightEdge` / `spillX` advance
+//      and the row's height grows to accommodate the new child.
+//
+// When a row's height grows after later rows already exist, the packer
+// shifts every subsequent row (and every positioned child placed in it)
+// downward by the delta. Items keep their row-anchored top edge; the
+// row simply gets taller. This keeps the contract "all children in a
+// row share that row's top y" intact while letting individual children
+// grow vertically (e.g. wrapped label-chiclet stacks in m3).
+
+import type { PositionedItem, PositionedTrackChild, SlackCorridor } from './types.js';
+
+export interface PackedRow {
+    /** Top-y of the row in canvas px. */
+    y: number;
+    /** Visible height of the row. Grows with the tallest committed child. */
+    height: number;
+    /** Logical x of the rightmost extent reached by a committed child. */
+    rightEdge: number;
+    /** Reserved x for caption spill. Items whose `desiredStart < spillX`
+     *  bump to a new row even if `rightEdge` would let them in. */
+    spillX: number;
+    /** Children placed in this row. Used when the row's height grows
+     *  after later rows exist — every child in every later row shifts
+     *  down by the delta. */
+    placedChildren: PositionedTrackChild[];
+}
+
+export interface RowPackerOptions {
+    /** Logical left x of the track this packer owns (lane left edge or
+     *  group's content left). New rows reset their `rightEdge` /
+     *  `spillX` to this value. */
+    laneLeftX: number;
+    /** Top-y of the first row. */
+    originY: number;
+    /** Minimum height of any row. Typically `bandScale.step()`. */
+    minRowHeight: number;
+    /** Slack-arrow corridors to avoid. Items whose vertical band
+     *  intersects a corridor at the candidate row bump to a new row. */
+    slackCorridors: SlackCorridor[];
+}
+
+/** Item placement query — passed to `placeItem` BEFORE sequencing. */
+export interface ItemPlacementInput {
+    /** Item id; corridor-bumping is skipped for the corridor's own
+     *  predecessor (the slack arrow's source item is exempt). */
+    childId: string;
+    /** Logical left x where the item wants to start. */
+    desiredStart: number;
+    /** Logical right x of the item's natural extent. */
+    desiredEnd: number;
+    /** Predicted intrinsic height of the item. Used to set the row's
+     *  initial height when this is the first item in a fresh row, or
+     *  to grow the row when a taller item lands in an existing row. */
+    predictedHeight: number;
+}
+
+/** Result of a `placeItem` query. */
+export interface ItemPlacement {
+    rowIndex: number;
+    y: number;
+}
+
+/** Item-commit payload — passed to `commitItem` AFTER sequencing. */
+export interface ItemCommitInput {
+    rowIndex: number;
+    placed: PositionedItem;
+    /** Logical right edge of the placed item. Includes the trailing
+     *  `ITEM_INSET_PX` so the next chained item butts edge-to-edge in
+     *  logical space (with a 2 × ITEM_INSET_PX visible gutter between
+     *  bars). */
+    logicalEnd: number;
+    /** Reserved spill x for captions that overflow the bar's right
+     *  edge. `null` resets the row's spill reservation to `laneLeftX`. */
+    spillReservation: number | null;
+    /** Total vertical reservation the placed item needs (e.g. bar
+     *  height plus a multi-row spilled chip column hanging below the
+     *  bar). When omitted, the row only grows to `placed.box.height`,
+     *  which is fine for items whose entire content fits inside the
+     *  bar. Set this to `predictedHeight` from `placeItem(...)` when
+     *  the item has a chip overhang so the row grows even if it
+     *  landed in an EXISTING row (where the placement step ignores
+     *  `predictedHeight`). */
+    rowHeight?: number;
+}
+
+/** Result of a `placeBlock` query (parallel/group as a child). */
+export interface BlockPlacement {
+    rowIndex: number;
+    y: number;
+}
+
+/** Block-commit payload — passed to `commitBlock` AFTER sequencing. */
+export interface BlockCommitInput {
+    rowIndex: number;
+    placed: PositionedTrackChild;
+    /** Total vertical extent the block occupies (the block's reported
+     *  `box.height`). The row this block landed on grows to at least
+     *  this height. */
+    blockHeight: number;
+    /** Logical right edge of the block. */
+    blockEnd: number;
+}
+
+export class RowPacker {
+    public readonly rows: PackedRow[];
+    private readonly opts: RowPackerOptions;
+
+    constructor(opts: RowPackerOptions) {
+        this.opts = opts;
+        this.rows = [
+            {
+                y: opts.originY,
+                height: opts.minRowHeight,
+                rightEdge: opts.laneLeftX,
+                spillX: opts.laneLeftX,
+                placedChildren: [],
+            },
+        ];
+    }
+
+    /**
+     * Find the topmost row where the item's natural extent fits without
+     * colliding with sibling content or a slack corridor; appending a
+     * fresh row at the bottom when none of the existing rows fit.
+     */
+    placeItem(input: ItemPlacementInput): ItemPlacement {
+        for (let i = 0; i < this.rows.length; i += 1) {
+            const r = this.rows[i];
+            if (input.desiredStart < r.rightEdge) continue;
+            if (input.desiredStart < r.spillX) continue;
+            if (this.rowIntersectsCorridor(r, input)) continue;
+            return { rowIndex: i, y: r.y };
+        }
+        const fresh = this.appendRow(Math.max(this.opts.minRowHeight, input.predictedHeight));
+        return { rowIndex: this.rows.length - 1, y: fresh.y };
+    }
+
+    /**
+     * Blocks (parallel / group) always claim a fresh row at the bottom
+     * of the stack so their inner sub-tracks have contiguous rows to
+     * expand into. If the bottom row is empty, we reuse it; otherwise
+     * we append.
+     */
+    placeBlock(): BlockPlacement {
+        const last = this.rows[this.rows.length - 1];
+        if (last.rightEdge > this.opts.laneLeftX) {
+            const fresh = this.appendRow(this.opts.minRowHeight);
+            return { rowIndex: this.rows.length - 1, y: fresh.y };
+        }
+        return { rowIndex: this.rows.length - 1, y: last.y };
+    }
+
+    /**
+     * Record a placed item back into its row. Grows the row's height to
+     * fit the item, advances `rightEdge`, sets the caption spill, and
+     * shifts later rows down if this row got taller.
+     */
+    commitItem(input: ItemCommitInput): void {
+        const row = this.rows[input.rowIndex];
+        const target = Math.max(input.placed.box.height, input.rowHeight ?? 0);
+        this.growRowHeight(input.rowIndex, target);
+        row.rightEdge = input.logicalEnd;
+        row.spillX = input.spillReservation ?? this.opts.laneLeftX;
+        row.placedChildren.push(input.placed);
+    }
+
+    /**
+     * Record a placed block. Sets the row's height to the block's full
+     * height (blocks own their row, no other child shares it).
+     */
+    commitBlock(input: BlockCommitInput): void {
+        const row = this.rows[input.rowIndex];
+        this.growRowHeight(input.rowIndex, input.blockHeight);
+        row.rightEdge = input.blockEnd;
+        row.spillX = this.opts.laneLeftX;
+        row.placedChildren.push(input.placed);
+    }
+
+    /** Total vertical extent reached (last row's bottom - originY). */
+    usedHeight(): number {
+        const last = this.rows[this.rows.length - 1];
+        return last.y + last.height - this.opts.originY;
+    }
+
+    /** Rightmost extent reached — bar logical end OR caption spill,
+     *  whichever is wider, across every row. Empty rows contribute
+     *  `laneLeftX`. */
+    usedRightX(): number {
+        let x = this.opts.laneLeftX;
+        for (const r of this.rows) {
+            if (r.rightEdge > x) x = r.rightEdge;
+            if (r.spillX > x) x = r.spillX;
+        }
+        return x;
+    }
+
+    private rowIntersectsCorridor(r: PackedRow, p: ItemPlacementInput): boolean {
+        return this.opts.slackCorridors.some(
+            (c) =>
+                c.y >= r.y &&
+                c.y < r.y + r.height &&
+                p.desiredStart < c.xEnd &&
+                p.desiredEnd > c.xStart &&
+                c.slackPredId !== p.childId,
+        );
+    }
+
+    private appendRow(height: number): PackedRow {
+        const last = this.rows[this.rows.length - 1];
+        const r: PackedRow = {
+            y: last.y + last.height,
+            height,
+            rightEdge: this.opts.laneLeftX,
+            spillX: this.opts.laneLeftX,
+            placedChildren: [],
+        };
+        this.rows.push(r);
+        return r;
+    }
+
+    private growRowHeight(rowIndex: number, newHeight: number): void {
+        const row = this.rows[rowIndex];
+        const delta = newHeight - row.height;
+        if (delta <= 0) return;
+        row.height = newHeight;
+        for (let i = rowIndex + 1; i < this.rows.length; i += 1) {
+            const r = this.rows[i];
+            r.y += delta;
+            for (const child of r.placedChildren) {
+                shiftPositionedY(child, delta);
+            }
+        }
+    }
+}
+
+/**
+ * Walk a positioned subtree and shift every absolute y by `dy`. Used
+ * when an earlier row in the packer grows, retroactively pushing every
+ * later row (and its placed subtrees) down to keep them clear.
+ *
+ * Items: shift the bar box plus label chips and any overflow box.
+ * Groups / parallels: shift the container box and recurse into
+ * children. The caller's `box.y` already moved with the parent.
+ */
+function shiftPositionedY(p: PositionedTrackChild, dy: number): void {
+    p.box.y += dy;
+    if (p.kind === 'item') {
+        for (const chip of p.labelChips) {
+            chip.box.y += dy;
+        }
+        if (p.overflowBox) {
+            p.overflowBox.y += dy;
+        }
+        return;
+    }
+    for (const child of p.children) {
+        shiftPositionedY(child, dy);
+    }
+}

package/src/style-resolution.ts

@@ -0,0 +1,243 @@
+import type {
+    DefaultDeclaration,
+    EntityProperty,
+    LabelDeclaration,
+    StyleDeclaration,
+    StyleProperty,
+} from '@nowline/core';
+import { resolveColor } from './themes/index.js';
+import type { EntityStyle, Theme } from './themes/shape.js';
+import type { ResolvedStyle, SizeBucket } from './types.js';
+
+type EntityTypeKey =
+    | 'roadmap'
+    | 'swimlane'
+    | 'item'
+    | 'parallel'
+    | 'group'
+    | 'anchor'
+    | 'milestone'
+    | 'footnote'
+    | 'label';
+
+export interface StyleContext {
+    theme: Theme;
+    // Map of style id → StyleDeclaration (from resolveIncludes().config.styles
+    // or a fallback scan of the parent file).
+    styles: Map<string, StyleDeclaration>;
+    // Map of `default <entity>` per entity type. May be missing entries.
+    defaults: Map<string, DefaultDeclaration>;
+    // Map of label id → LabelDeclaration for resolving label styles.
+    labels: Map<string, LabelDeclaration>;
+}
+
+function propKey(prop: { key: string }): string {
+    return prop.key.endsWith(':') ? prop.key.slice(0, -1) : prop.key;
+}
+
+function entityStyleToResolved(e: EntityStyle, theme: Theme): ResolvedStyle {
+    return {
+        bg: resolveColor(e.bg, theme),
+        fg: resolveColor(e.fg, theme),
+        text: resolveColor(e.text, theme),
+        border: e.border,
+        icon: e.icon,
+        shadow: e.shadow,
+        font: e.font,
+        weight: e.weight,
+        italic: e.italic,
+        textSize: e.textSize,
+        padding: e.padding,
+        spacing: e.spacing,
+        headerHeight: e.headerHeight,
+        cornerRadius: e.cornerRadius,
+        bracket: e.bracket,
+        // DSL does not expose header-position on non-roadmap entities; system
+        // default `beside` applies. Roadmap entity's resolve step lifts this
+        // from the 5-level chain.
+        headerPosition: 'beside',
+        capacityIcon: e.capacityIcon,
+        // Roadmap-only readability knobs. Defaults preserve the existing
+        // single-top-strip layout and keep the major-ticks-only grid.
+        timelinePosition: 'top',
+        minorGrid: false,
+    };
+}
+
+// Apply a single style property (from `style` blocks, `default` blocks, or
+// label styles) onto an accumulating ResolvedStyle.
+function applyProp(target: ResolvedStyle, key: string, value: string, theme: Theme): void {
+    switch (key) {
+        case 'bg':
+            target.bg = resolveColor(value, theme);
+            break;
+        case 'fg':
+            target.fg = resolveColor(value, theme);
+            break;
+        case 'text':
+            target.text = resolveColor(value, theme);
+            break;
+        case 'border':
+            if (value === 'solid' || value === 'dashed' || value === 'dotted')
+                target.border = value;
+            break;
+        case 'icon':
+            target.icon = value;
+            break;
+        case 'shadow':
+            if (value === 'none' || value === 'subtle' || value === 'soft' || value === 'hard') {
+                target.shadow = value;
+            }
+            break;
+        case 'font':
+            if (value === 'sans' || value === 'serif' || value === 'mono') target.font = value;
+            break;
+        case 'weight':
+            if (value === 'thin' || value === 'light' || value === 'normal' || value === 'bold') {
+                target.weight = value;
+            }
+            break;
+        case 'italic':
+            target.italic = value === 'true';
+            break;
+        case 'text-size':
+            target.textSize = coerceSize(value, 'xl') as ResolvedStyle['textSize'];
+            break;
+        case 'padding':
+            target.padding = coerceSize(value, 'xl') as ResolvedStyle['padding'];
+            break;
+        case 'spacing':
+            target.spacing = coerceSize(value, 'xl') as ResolvedStyle['spacing'];
+            break;
+        case 'header-height':
+            target.headerHeight = coerceSize(value, 'xl') as ResolvedStyle['headerHeight'];
+            break;
+        case 'corner-radius':
+            target.cornerRadius = coerceSize(value, 'full') as ResolvedStyle['cornerRadius'];
+            break;
+        case 'bracket':
+            if (value === 'none' || value === 'solid' || value === 'dashed') target.bracket = value;
+            break;
+        case 'header-position':
+            if (value === 'beside' || value === 'above') target.headerPosition = value;
+            break;
+        case 'capacity-icon':
+            // Validator (rule 17e + checkSymbolReferences) has already verified
+            // the value is a built-in name, a declared symbol id, or an inline
+            // Unicode literal. Pass it through verbatim — interpretation
+            // happens in the renderer where we have access to ResolvedConfig.symbols.
+            target.capacityIcon = value;
+            break;
+        case 'timeline-position':
+            if (value === 'top' || value === 'bottom' || value === 'both') {
+                target.timelinePosition = value;
+            }
+            break;
+        case 'minor-grid':
+            target.minorGrid = value === 'true';
+            break;
+        default:
+            break;
+    }
+}
+
+function coerceSize(value: string, max: SizeBucket): SizeBucket {
+    const order: SizeBucket[] = ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'full'];
+    const cap = order.indexOf(max);
+    const idx = order.indexOf(value as SizeBucket);
+    if (idx < 0) return 'md';
+    if (idx > cap) return order[cap];
+    return order[idx];
+}
+
+function applyStyleDecl(
+    target: ResolvedStyle,
+    decl: StyleDeclaration | undefined,
+    theme: Theme,
+): void {
+    if (!decl) return;
+    for (const p of decl.properties as StyleProperty[]) {
+        applyProp(target, propKey(p), p.value, theme);
+    }
+}
+
+function applyProperties(target: ResolvedStyle, props: EntityProperty[], theme: Theme): void {
+    for (const p of props) {
+        const key = propKey(p);
+        if (p.value !== undefined) {
+            applyProp(target, key, p.value, theme);
+        }
+    }
+}
+
+function applyLabelStyleRefs(
+    target: ResolvedStyle,
+    props: EntityProperty[],
+    ctx: StyleContext,
+): void {
+    const labelsProp = props.find((p) => propKey(p) === 'labels');
+    if (!labelsProp) return;
+    const names: string[] = labelsProp.value ? [labelsProp.value] : labelsProp.values;
+    for (const name of names) {
+        const label = ctx.labels.get(name);
+        if (!label) continue;
+        // Label's `style:` ref gets applied.
+        const styleRef = label.properties.find((p) => propKey(p) === 'style');
+        if (styleRef?.value) {
+            applyStyleDecl(target, ctx.styles.get(styleRef.value), ctx.theme);
+        }
+    }
+}
+
+function applyEntityStyleRef(
+    target: ResolvedStyle,
+    props: EntityProperty[],
+    ctx: StyleContext,
+): void {
+    const styleProp = props.find((p) => propKey(p) === 'style');
+    if (!styleProp?.value) return;
+    applyStyleDecl(target, ctx.styles.get(styleProp.value), ctx.theme);
+}
+
+// Five-level precedence chain from specs/rendering.md § Style Precedence:
+// 1. system default (theme's EntityStyle for this type)
+// 2. config `default <entity>` properties
+// 3. label `style:` refs (per applied label)
+// 4. entity's own `style:` ref
+// 5. inline style properties on the entity (banned by validator for roadmap
+//    entities; still supported for declared styles / defaults)
+export function resolveStyle(
+    entityType: EntityTypeKey,
+    props: EntityProperty[],
+    ctx: StyleContext,
+): ResolvedStyle {
+    const baseEntity = ctx.theme.entities[entityType];
+    const out = entityStyleToResolved(baseEntity, ctx.theme);
+
+    // Level 2: config defaults
+    const defaultDecl = ctx.defaults.get(entityType);
+    if (defaultDecl) {
+        for (const p of defaultDecl.properties) {
+            if (p.value !== undefined) {
+                applyProp(out, propKey(p), p.value, ctx.theme);
+            }
+        }
+    }
+
+    // Level 3: label styles (labels on this entity, each label's `style:` ref)
+    applyLabelStyleRefs(out, props, ctx);
+
+    // Level 4: entity's own `style:` ref
+    applyEntityStyleRef(out, props, ctx);
+
+    // Level 5: inline props on the entity
+    applyProperties(out, props, ctx.theme);
+
+    return out;
+}
+
+// Resolve a label's *display* style (bg/fg/text + bracket etc.) as used on
+// label chips rendered on items. The chip uses the label entity type.
+export function resolveLabelChipStyle(label: LabelDeclaration, ctx: StyleContext): ResolvedStyle {
+    return resolveStyle('label', label.properties, ctx);
+}