@nowline/layout 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nowline/layout",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Nowline layout engine — AST → positioned model for rendering",
   "license": "Apache-2.0",
   "engines": {
@@ -24,7 +24,7 @@
   "dependencies": {
     "d3-scale": "^4.0.2",
     "d3-time": "^3.1.0",
-    "@nowline/core": "0.5.1"
+    "@nowline/core": "0.6.0"
   },
   "devDependencies": {
     "@types/d3-scale": "^4.0.9",

package/src/index.ts

@@ -65,6 +65,16 @@ export {
 } from './item-bar-geometry.js';
 export type { LayoutOptions, LayoutResult } from './layout.js';
 export { layoutRoadmap } from './layout.js';
+export {
+    civilDateInZone,
+    type NormalizedZone,
+    normalizeZone,
+    type ResolveTodayOptions,
+    resolveToday,
+    TimezoneError,
+} from './resolve-today.js';
+export type { RoadmapSchedule, ScheduledItem, ScheduleOptions } from './schedule.js';
+export { scheduleRoadmap } from './schedule.js';
 export {
     darkTheme,
     grayscaleTheme,

package/src/layout-context.ts

@@ -145,6 +145,14 @@ export interface LayoutContext {
      */
     swimlaneBottomY: number;
     chartRightX: number;
+    /**
+     * Monotonic counters for id-less `parallel` / `group` blocks. Each
+     * swimlane-loop pass resets both to zero; blocks without an explicit
+     * `name` receive internal flow-key handles (`parallel-1`, `group-1`, …).
+     * These handles are not referenceable from `after:` / `before:` / `on:`.
+     */
+    nextParallelId: number;
+    nextGroupId: number;
 }
 
 /**

package/src/layout.ts

@@ -674,55 +674,60 @@ function sequenceItem(
     const decorationsRightX = Math.max(itemBox.x + itemBox.width, spillCursor);
 
     const id = node.name;
+    // Reference-target edges resolve `after:` / `before:` lookups, so only
+    // EXPLICIT ids register here — an id-less item never becomes a
+    // referenceable target. Entity edges live in LOGICAL space so chained
+    // items / `after:` references sit on the column boundary, not on the
+    // visually inset bar edge. The visible 12 px gutter between bars then
+    // becomes a clean attach corridor.
     if (id) {
-        // Entity edges live in LOGICAL space so chained items / `after:`
-        // references / dependency-arrow attach points sit on the column
-        // boundary, not on the visually inset bar edge. The visible 12 px
-        // gutter between bars then becomes a clean attach corridor.
         ctx.entityLeftEdges.set(id, logicalLeft);
         ctx.entityRightEdges.set(id, logicalRight);
-        ctx.entityMidpoints.set(id, {
-            x: (logicalLeft + logicalRight) / 2,
-            y: itemBox.y + itemBox.height / 2,
-        });
-        // Visual edges — where dependency arrows actually attach. These
-        // sit ITEM_INSET_PX inside the column boundaries so the arrows
-        // emerge from the painted bar edge instead of the inter-column
-        // gutter. See LayoutContext.entityVisualLeftX/RightX.
-        ctx.entityVisualLeftX.set(id, itemBox.x);
-        ctx.entityVisualRightX.set(id, itemBox.x + itemBox.width);
-        // Dependency-arrow source point. Default = the bar's right
-        // edge at row midpoint. When the caption spills past the
-        // bar's right edge (`textSpills`), the spilled title /
-        // meta occupy the area immediately right of the bar at
-        // row midline. Keep X on the bar's right edge so the
-        // arrow visually leaves the bar's side, but drop Y to the
-        // vertical center of the bottom progress strip so the
-        // arrow runs UNDERNEATH the spilled text rather than
-        // through it. Mirrors the slack-arrow attach below.
-        const arrowSource: Point = textSpills
-            ? {
-                  x: itemBox.x + itemBox.width,
-                  y: itemBox.y + itemBox.height - PROGRESS_STRIP_HEIGHT_PX / 2,
-              }
-            : {
-                  x: itemBox.x + itemBox.width,
-                  y: itemBox.y + itemBox.height / 2,
-              };
-        ctx.itemArrowSource.set(id, arrowSource);
-        ctx.itemFlowKey.set(id, ctx.currentFlowKey);
-        // Slack-arrow attach Y. Defaults to the bar's row midpoint; when
-        // the caption spills past the bar's right edge, drop to the
-        // progress-strip's vertical center so the arrow aligns with the
-        // bottom-edge progress bar instead of running through the
-        // adjacent title/meta text. The `/ 2` keeps the attach point on
-        // the strip's vertical center if `PROGRESS_STRIP_HEIGHT_PX` is
-        // ever bumped.
-        const slackAttachY = textSpills
-            ? itemBox.y + itemBox.height - PROGRESS_STRIP_HEIGHT_PX / 2
-            : itemBox.y + itemBox.height / 2;
-        ctx.itemSlackAttachY.set(id, slackAttachY);
     }
+    // Drawing / flow maps key on a registration handle EVERY item has: the
+    // explicit id when present, else a synthetic, non-referenceable handle
+    // (see `syntheticItemKey`). This lets a title-only item register its own
+    // dependency-arrow target geometry and join flow-key dedup without
+    // entering the human-referenceable namespace above.
+    const drawKey = id ?? syntheticItemKey(node);
+    ctx.entityMidpoints.set(drawKey, {
+        x: (logicalLeft + logicalRight) / 2,
+        y: itemBox.y + itemBox.height / 2,
+    });
+    // Visual edges — where dependency arrows actually attach. These sit
+    // ITEM_INSET_PX inside the column boundaries so the arrows emerge from
+    // the painted bar edge instead of the inter-column gutter. See
+    // LayoutContext.entityVisualLeftX/RightX.
+    ctx.entityVisualLeftX.set(drawKey, itemBox.x);
+    ctx.entityVisualRightX.set(drawKey, itemBox.x + itemBox.width);
+    // Dependency-arrow source point. Default = the bar's right edge at row
+    // midpoint. When the caption spills past the bar's right edge
+    // (`textSpills`), the spilled title / meta occupy the area immediately
+    // right of the bar at row midline. Keep X on the bar's right edge so the
+    // arrow visually leaves the bar's side, but drop Y to the vertical center
+    // of the bottom progress strip so the arrow runs UNDERNEATH the spilled
+    // text rather than through it. Mirrors the slack-arrow attach below.
+    const arrowSource: Point = textSpills
+        ? {
+              x: itemBox.x + itemBox.width,
+              y: itemBox.y + itemBox.height - PROGRESS_STRIP_HEIGHT_PX / 2,
+          }
+        : {
+              x: itemBox.x + itemBox.width,
+              y: itemBox.y + itemBox.height / 2,
+          };
+    ctx.itemArrowSource.set(drawKey, arrowSource);
+    ctx.itemFlowKey.set(drawKey, ctx.currentFlowKey);
+    // Slack-arrow attach Y. Defaults to the bar's row midpoint; when the
+    // caption spills past the bar's right edge, drop to the progress-strip's
+    // vertical center so the arrow aligns with the bottom-edge progress bar
+    // instead of running through the adjacent title/meta text. The `/ 2`
+    // keeps the attach point on the strip's vertical center if
+    // `PROGRESS_STRIP_HEIGHT_PX` is ever bumped.
+    const slackAttachY = textSpills
+        ? itemBox.y + itemBox.height - PROGRESS_STRIP_HEIGHT_PX / 2
+        : itemBox.y + itemBox.height / 2;
+    ctx.itemSlackAttachY.set(drawKey, slackAttachY);
 
     cursor.x = logicalRight;
     cursor.maxX = Math.max(cursor.maxX, cursor.x);
@@ -816,6 +821,22 @@ function estimateTextWidth(text: string, fontSize: number): number {
     return text.length * fontSize * 0.58;
 }
 
+/**
+ * Internal drawing handle for an id-less item. Title-only items have no
+ * `node.name`, yet they still need a stable key to register their own
+ * dependency-arrow target geometry and join flow-key dedup. The handle is
+ * derived from the item's source position so it is deterministic and
+ * byte-stable, and the `#item@line:col` form cannot be produced by the
+ * grammar's id rule — so `after:` / `before:` / `on:` can never resolve to it
+ * (an id-less item stays non-referenceable; declare an explicit id to
+ * reference it). Distinct items always start at distinct positions, so the
+ * handle is unique within a file.
+ */
+function syntheticItemKey(node: ItemDeclaration): string {
+    const start = node.$cstNode?.range.start;
+    return `#item@${start ? start.line + 1 : 0}:${start ? start.character + 1 : 0}`;
+}
+
 /**
  * Compute the extra vertical px the bar grows when its spilled chip
  * column would otherwise extend below the (single-row) bottom. The
@@ -1482,7 +1503,9 @@ function collectItems(swimlanes: SwimlaneDeclaration[]): Map<string, ItemDeclara
     const out = new Map<string, ItemDeclaration>();
     const walk = (node: ItemDeclaration | GroupBlock | ParallelBlock): void => {
         if (isItemDeclaration(node)) {
-            if (node.name) out.set(node.name, node);
+            // Title-only items register under a synthetic, non-referenceable
+            // handle so they still appear as dependency-edge targets.
+            out.set(node.name ?? syntheticItemKey(node), node);
             return;
         }
         if (isParallelBlock(node)) {

package/src/nodes/group-node.ts

@@ -90,7 +90,8 @@ export class GroupNode {
         // form one sub-flow under the parent's flow path. See
         // `LayoutContext.currentFlowKey`.
         const previousFlowKey = ctx.currentFlowKey;
-        ctx.currentFlowKey = `${previousFlowKey}/group:${node.name ?? 'g'}`;
+        ctx.nextGroupId += 1;
+        ctx.currentFlowKey = `${previousFlowKey}/group:${node.name ?? `group-${ctx.nextGroupId}`}`;
         // Mirrors `renderGroup`'s `hasFill` decision so the painted box
         // and the layout's reservation agree on whether a chiclet exists.
         const hasChiclet = style.bg !== 'none' && style.bg !== '#ffffff' && Boolean(title);

package/src/nodes/include-node.ts

@@ -110,12 +110,16 @@ export function buildIncludeRegions(
             chartBottomY: innerStartY,
             swimlaneBottomY: innerStartY,
             chartRightX: ctx.chartRightX,
+            nextParallelId: 0,
+            nextGroupId: 0,
         };
         const nestedSwimlanes: PositionedSwimlane[] = [];
         let cursorY = innerStartY;
         let bandIndex = 0;
         let nestedContentRightX = childCtx.timeline.originX;
         for (const lane of region.content.swimlanes.values()) {
+            childCtx.nextParallelId = 0;
+            childCtx.nextGroupId = 0;
             const { positioned, usedHeight, usedRightX } = new SwimlaneNode(
                 { lane, bandIndex },
                 deps,

package/src/nodes/parallel-node.ts

@@ -55,7 +55,8 @@ export class ParallelNode {
         // sub-tracks therefore stay in different flows for milestone
         // slack-arrow dedupe.
         const previousFlowKey = ctx.currentFlowKey;
-        const parId = node.name ?? 'p';
+        ctx.nextParallelId += 1;
+        const parId = node.name ?? `parallel-${ctx.nextParallelId}`;
 
         let childIndex = 0;
         for (const child of node.content) {

package/src/nodes/roadmap-node.ts

@@ -381,6 +381,8 @@ export class RoadmapNode {
             chartBottomY: 0,
             swimlaneBottomY: 0,
             chartRightX: finalChartRightX,
+            nextParallelId: 0,
+            nextGroupId: 0,
         };
 
         // Seed the entity-edge maps from the date-pinned pack so item
@@ -426,6 +428,8 @@ export class RoadmapNode {
             nextY: number;
             maxRightX: number;
         } => {
+            ctx.nextParallelId = 0;
+            ctx.nextGroupId = 0;
             const out: PositionedSwimlane[] = [];
             let cursorY = ctx.chartTopY;
             let bIndex = 0;

package/src/resolve-today.ts

@@ -0,0 +1,266 @@
+// resolveToday — shared timezone-aware now-line date resolver.
+//
+// Every surface (CLI, VS Code extension, embed, browser SPA) calls this helper
+// to decide which civil calendar date to mark as "now" on the chart. Layout
+// itself stays a pure function of its inputs and never calls this — callers
+// resolve the date first, then pass `today: Date` into `layoutRoadmap`.
+//
+// Design contract (see plan: timezone-aware now-line resolution):
+//
+//  - "Today" is the viewer's local civil date by default. UTC is opt-in via
+//    --timezone UTC. This matches iCalendar floating-date semantics: authored
+//    dates in .nowline files are already floating (zone-free); the only thing
+//    that benefits from a timezone is the clock-based "today" default.
+//
+//  - Dates on the axis, item bars, milestones, and anchors are floating and
+//    are NEVER affected by --timezone. Only the now-line moves.
+//
+//  - An explicit --now value always wins over --timezone. When --now carries
+//    an embedded ISO 8601 offset/Z, that offset determines the civil day; the
+//    --timezone is ignored. --timezone only governs the clock-based default
+//    (when --now is omitted).
+
+// ---- Types and errors -------------------------------------------------------
+
+/**
+ * Structured representation of a normalised --timezone / timezone option.
+ * Produced by {@link normalizeZone}; consumed by {@link civilDateInZone}.
+ */
+export type NormalizedZone =
+    | { kind: 'local' }
+    | { kind: 'utc' }
+    | { kind: 'offset'; ms: number }
+    | { kind: 'iana'; name: string };
+
+/**
+ * Thrown by {@link normalizeZone} when the raw timezone string is not
+ * recognised. CLI surfaces catch this and re-throw as `CliError`.
+ */
+export class TimezoneError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'TimezoneError';
+    }
+}
+
+// ---- Zone normalisation -----------------------------------------------------
+
+/**
+ * Normalise a raw --timezone / timezone option string into a {@link NormalizedZone}.
+ *
+ * Accepted forms (case-insensitive for keywords):
+ *   - empty / `'local'`                      → host/viewer local zone (default)
+ *   - `'UTC'`                                → UTC
+ *   - ISO 8601 offset: `Z`, `±HH`, `±HH:MM`, `±HHMM`  → fixed offset (DST-naive)
+ *   - IANA name e.g. `'America/Los_Angeles'` → validated via Intl
+ *
+ * Throws {@link TimezoneError} for strings not recognised by `Intl.DateTimeFormat`.
+ * Ambiguous abbreviations (`PST`, `IST`, …) are rejected on platforms where `Intl`
+ * rejects them (Linux ICU typically rejects them); on macOS Node 26 they may be
+ * accepted and silently mapped to a platform-specific IANA zone — a known platform
+ * caveat. Use explicit IANA names for portable results.
+ * and any unrecognised string. (`GMT` and `Etc/GMT±N` are accepted by `Intl`
+ * but are undocumented; `Etc/GMT±N` has an inverted sign convention.)
+ */
+export function normalizeZone(raw: string | undefined): NormalizedZone {
+    if (!raw || raw.toLowerCase() === 'local') return { kind: 'local' };
+    if (raw.toUpperCase() === 'UTC') return { kind: 'utc' };
+
+    // ISO 8601 offset shorthand: Z, ±HH, ±HH:MM, ±HHMM
+    if (raw === 'Z') return { kind: 'offset', ms: 0 };
+    const offsetMatch = /^([+-])(\d{2})(?::?(\d{2}))?$/.exec(raw);
+    if (offsetMatch) {
+        const sign = offsetMatch[1] === '+' ? 1 : -1;
+        const hours = parseInt(offsetMatch[2], 10);
+        const minutes = offsetMatch[3] !== undefined ? parseInt(offsetMatch[3], 10) : 0;
+        if (hours > 23 || minutes > 59) {
+            throw new TimezoneError(
+                `nowline: invalid timezone offset "${raw}". Hours must be 0–23 and minutes 0–59.`,
+            );
+        }
+        return { kind: 'offset', ms: sign * (hours * 60 + minutes) * 60_000 };
+    }
+
+    // IANA name — validate with Intl; ambiguous abbreviations (PST, IST, …)
+    // are not valid IANA names and will throw here.
+    try {
+        const canonical = Intl.DateTimeFormat(undefined, { timeZone: raw }).resolvedOptions()
+            .timeZone;
+        return { kind: 'iana', name: canonical };
+    } catch {
+        throw new TimezoneError(
+            `nowline: unrecognised timezone "${raw}". ` +
+                `Use "local", "UTC", an ISO 8601 offset (e.g. "+05:30", "-07:00", "Z"), ` +
+                `or an IANA timezone name (e.g. "America/Los_Angeles", "Asia/Kolkata").`,
+        );
+    }
+}
+
+// ---- Civil-date extraction --------------------------------------------------
+
+/**
+ * Extract the civil `YYYY-MM-DD` date of `instant` in the given zone and
+ * return it as a UTC-midnight `Date` (matching the layout engine's convention
+ * for authored dates).
+ */
+export function civilDateInZone(instant: Date, zone: NormalizedZone): Date {
+    switch (zone.kind) {
+        case 'local': {
+            // JS local time — getFullYear/Month/Date already reflect the host zone.
+            return new Date(Date.UTC(instant.getFullYear(), instant.getMonth(), instant.getDate()));
+        }
+        case 'utc': {
+            return new Date(
+                Date.UTC(instant.getUTCFullYear(), instant.getUTCMonth(), instant.getUTCDate()),
+            );
+        }
+        case 'offset': {
+            // Shift the instant by the fixed offset, then read UTC components.
+            // No Intl dependency — portable to older embed browsers.
+            const shifted = new Date(instant.getTime() + zone.ms);
+            return new Date(
+                Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), shifted.getUTCDate()),
+            );
+        }
+        case 'iana': {
+            // Use en-CA locale so formatToParts gives YYYY-MM-DD numeric fields.
+            const parts = new Intl.DateTimeFormat('en-CA', {
+                timeZone: zone.name,
+                year: 'numeric',
+                month: '2-digit',
+                day: '2-digit',
+            }).formatToParts(instant);
+            let y = 0;
+            let m = 0;
+            let d = 0;
+            for (const p of parts) {
+                if (p.type === 'year') y = parseInt(p.value, 10);
+                else if (p.type === 'month') m = parseInt(p.value, 10) - 1;
+                else if (p.type === 'day') d = parseInt(p.value, 10);
+            }
+            return new Date(Date.UTC(y, m, d));
+        }
+    }
+}
+
+// ---- Now-value parsing ------------------------------------------------------
+
+// Bare YYYY-MM-DD (floating date, zone-independent)
+const BARE_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+// ISO 8601 instant with explicit Z or ±HH / ±HH:MM / ±HHMM offset.
+// Captures: [1] datetime part, [2] sign or Z, [3] hours, [4] minutes (optional)
+const ISO_WITH_OFFSET_RE =
+    /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?)(Z|([+-])(\d{2})(?::?(\d{2}))?)$/;
+
+// ISO 8601 with time but no offset (floating local date-time).
+// Captures: [1] year, [2] month, [3] day
+const ISO_FLOATING_RE = /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}:\d{2}(?:\.\d+)?$/;
+
+// ---- Public API -------------------------------------------------------------
+
+export interface ResolveTodayOptions {
+    /**
+     * Raw now value: the CLI's `--now` string, a pre-resolved `Date`, `null`
+     * to suppress the now-line, or `undefined` to use the clock default.
+     *
+     * String forms accepted:
+     *  - `'-'`                   → suppress (same as `null`)
+     *  - `'YYYY-MM-DD'`          → floating date; zone ignored
+     *  - ISO 8601 + Z/offset     → embedded offset wins; zone ignored
+     *  - ISO 8601 without offset → floating; written date part used; zone ignored
+     */
+    now?: string | Date | null;
+    /**
+     * Effective timezone for the clock-based default. Produced by
+     * {@link normalizeZone}. Defaults to `{ kind: 'local' }` (host/viewer zone).
+     * Only consulted when `now` is omitted.
+     */
+    zone?: NormalizedZone;
+    /**
+     * Clock factory — injected for tests; defaults to `() => new Date()`.
+     * Only called when `now` is omitted.
+     */
+    clock?: () => Date;
+}
+
+/**
+ * Resolve the now-line anchor date.
+ *
+ * Returns a UTC-midnight `Date` (the civil day at which to draw the red
+ * now-line), or `undefined` to suppress the now-line entirely.
+ *
+ * Precedence (from highest to lowest):
+ *  1. `now === '-'` / `null`       → `undefined` (suppress)
+ *  2. `now` is a `Date` object     → returned as-is (caller must supply UTC midnight)
+ *  3. `now` bare `YYYY-MM-DD`      → floating; `Date.UTC(y, m, d)` regardless of zone
+ *  4. `now` ISO 8601 + Z/offset    → embedded offset wins; zone ignored
+ *  5. `now` ISO 8601 without offset→ floating; written date part; zone ignored
+ *  6. `now` omitted                → civil date of `clock()` in effective `zone`
+ *
+ * The `zone` is ONLY consulted for case 6 (clock-based default). Authored
+ * dates — item bars, milestones, anchors, the axis ticks — are floating and
+ * are never affected by this function.
+ */
+export function resolveToday(opts: ResolveTodayOptions = {}): Date | undefined {
+    const zone: NormalizedZone = opts.zone ?? { kind: 'local' };
+    const clock = opts.clock ?? (() => new Date());
+    const now = opts.now;
+
+    // 1. Suppress sentinel
+    if (now === '-' || now === null) return undefined;
+
+    // 2. Pre-resolved Date — pass through as-is
+    if (now instanceof Date) return now;
+
+    if (now !== undefined) {
+        // 3. Bare YYYY-MM-DD — floating; zone ignored
+        const bareMatch = BARE_DATE_RE.exec(now);
+        if (bareMatch) {
+            return new Date(
+                Date.UTC(
+                    parseInt(bareMatch[1], 10),
+                    parseInt(bareMatch[2], 10) - 1,
+                    parseInt(bareMatch[3], 10),
+                ),
+            );
+        }
+
+        // 4. ISO 8601 instant with explicit Z or offset — embedded offset WINS
+        const withOffset = ISO_WITH_OFFSET_RE.exec(now);
+        if (withOffset) {
+            const instant = new Date(now);
+            if (!Number.isNaN(instant.getTime())) {
+                const suffix = withOffset[2]; // 'Z' or '±HH:MM'
+                if (suffix === 'Z') {
+                    return civilDateInZone(instant, { kind: 'utc' });
+                }
+                // Fixed offset embedded in the string
+                const sign = withOffset[3] === '+' ? 1 : -1;
+                const hh = parseInt(withOffset[4], 10);
+                const mm = withOffset[5] !== undefined ? parseInt(withOffset[5], 10) : 0;
+                const offsetMs = sign * (hh * 60 + mm) * 60_000;
+                return civilDateInZone(instant, { kind: 'offset', ms: offsetMs });
+            }
+        }
+
+        // 5. ISO 8601 without offset — floating; use written date part; zone ignored
+        const floating = ISO_FLOATING_RE.exec(now);
+        if (floating) {
+            return new Date(
+                Date.UTC(
+                    parseInt(floating[1], 10),
+                    parseInt(floating[2], 10) - 1,
+                    parseInt(floating[3], 10),
+                ),
+            );
+        }
+
+        // Unrecognised string — caller should have validated before calling.
+        // Return undefined so a bad value doesn't crash the render pipeline.
+        return undefined;
+    }
+
+    // 6. No now given — civil date of clock() in the effective zone
+    return civilDateInZone(clock(), zone);
+}