@diagrammo/dgmo 0.8.16 → 0.8.18

package/src/gantt/parser.ts

@@ -17,7 +17,7 @@ import {
   MULTIPLE_PIPE_ERROR,
   parseFirstLine,
 } from '../utils/parsing';
-import { parseOffset } from '../utils/duration';
+import { parseOffset, parseDuration } from '../utils/duration';
 import type { PaletteColors } from '../palettes';
 import { getSeriesColors } from '../palettes';
 import type {
@@ -35,14 +35,14 @@ import type {
 // ── Regexes ─────────────────────────────────────────────────
 
 /** Duration task: `30d Label`, `1.5w Label`, `10bd? Label`, `2h Label`, `90min Label` */
-const DURATION_RE = /^(\d+(?:\.\d+)?)(min|bd|d|w|m|q|y|h)(\?)?\s+(.+)$/;
+const DURATION_RE = /^(\d+(?:\.\d+)?)(min|bd|d|w|m|q|y|h|s)(\?)?\s+(.+)$/;
 
 /** Explicit date task: `2024-01-15 Label` or `2024-01-15 14:30 Label` */
 const EXPLICIT_DATE_RE = /^(\d{4}-\d{2}-\d{2}(?: \d{2}:\d{2})?)\s+(.+)$/;
 
 /** Timeline migration syntax: `2024-01-15 -> 30d Label` or `2024-01-15 14:30 -> 2h Label` */
 const TIMELINE_DURATION_RE =
-  /^(\d{4}-\d{2}-\d{2}(?: \d{2}:\d{2})?)\s*(?:->|\u2013>)\s*(\d+(?:\.\d+)?)(min|bd|d|w|m|q|y|h)(\?)?\s+(.+)$/;
+  /^(\d{4}-\d{2}-\d{2}(?: \d{2}:\d{2})?)\s*(?:->|\u2013>)\s*(\d+(?:\.\d+)?)(min|bd|d|w|m|q|y|h|s)(\?)?\s+(.+)$/;
 
 /** Group container: `[GroupName]` with optional pipe metadata */
 const GROUP_RE = /^\[(.+?)\]\s*(.*)$/;
@@ -138,6 +138,10 @@ export function parseGantt(
       activeTag: null,
       optionLineNumbers: {},
       holidaysLineNumber: null,
+      sprintLength: null,
+      sprintNumber: null,
+      sprintStart: null,
+      sprintMode: null,
     },
     diagnostics,
     error: null,
@@ -650,6 +654,57 @@ export function parseGantt(
         case 'active-tag':
           result.options.activeTag = value;
           break;
+        case 'sprint-length': {
+          const dur = parseDuration(value);
+          if (!dur) {
+            warn(
+              lineNumber,
+              `Invalid sprint-length value: "${value}". Expected a duration like "2w" or "10d".`
+            );
+          } else if (dur.unit !== 'd' && dur.unit !== 'w') {
+            warn(
+              lineNumber,
+              `sprint-length only accepts "d" or "w" units, got "${dur.unit}".`
+            );
+          } else if (dur.amount <= 0) {
+            warn(lineNumber, `sprint-length must be greater than 0.`);
+          } else if (
+            !Number.isInteger(dur.amount * (dur.unit === 'w' ? 7 : 1))
+          ) {
+            warn(
+              lineNumber,
+              `sprint-length must resolve to a whole number of days.`
+            );
+          } else {
+            result.options.sprintLength = dur;
+          }
+          break;
+        }
+        case 'sprint-number': {
+          const n = Number(value);
+          if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+            warn(
+              lineNumber,
+              `sprint-number must be a positive integer, got "${value}".`
+            );
+          } else {
+            result.options.sprintNumber = n;
+          }
+          break;
+        }
+        case 'sprint-start': {
+          if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+            warn(
+              lineNumber,
+              `sprint-start requires a full date (YYYY-MM-DD), got "${value}".`
+            );
+          } else if (Number.isNaN(new Date(value + 'T00:00:00').getTime())) {
+            warn(lineNumber, `sprint-start is not a valid date: "${value}".`);
+          } else {
+            result.options.sprintStart = value;
+          }
+          break;
+        }
       }
       continue;
     }
@@ -879,6 +934,31 @@ export function parseGantt(
 
   validateTagGroupNames(result.tagGroups, warn);
 
+  // ── Sprint mode detection ──────────────────────────────
+  const hasSprintOption =
+    result.options.sprintLength !== null ||
+    result.options.sprintNumber !== null ||
+    result.options.sprintStart !== null;
+
+  const hasSprintUnit = hasSprintDurationUnit(result.nodes);
+
+  if (hasSprintOption) {
+    result.options.sprintMode = 'explicit';
+  } else if (hasSprintUnit) {
+    result.options.sprintMode = 'auto';
+  }
+
+  // Apply defaults when sprint mode is active
+  if (result.options.sprintMode) {
+    if (!result.options.sprintLength) {
+      result.options.sprintLength = { amount: 2, unit: 'w' };
+    }
+    if (result.options.sprintNumber === null) {
+      result.options.sprintNumber = 1;
+    }
+    // sprintStart defaults to chart start or today — handled in calculator
+  }
+
   return result;
 
   // ── Helper: create a task ───────────────────────────────
@@ -1041,6 +1121,9 @@ const KNOWN_OPTIONS = new Set([
   'chart',
   'sort',
   'active-tag',
+  'sprint-length',
+  'sprint-number',
+  'sprint-start',
 ]);
 
 /** Boolean options that can appear as bare keywords or with `no-` prefix. */
@@ -1053,3 +1136,15 @@ const KNOWN_BOOLEANS = new Set([
 function isKnownOption(key: string): boolean {
   return KNOWN_OPTIONS.has(key);
 }
+
+/** Check if any task in the tree uses the `s` (sprint) duration unit. */
+function hasSprintDurationUnit(nodes: GanttNode[]): boolean {
+  for (const node of nodes) {
+    if (node.kind === 'task') {
+      if (node.duration?.unit === 's') return true;
+    } else if (node.kind === 'group' || node.kind === 'parallel') {
+      if (hasSprintDurationUnit(node.children)) return true;
+    }
+  }
+  return false;
+}

package/src/gantt/renderer.ts

@@ -272,11 +272,16 @@ export function renderGantt(
   const topDateLabelReserve = 22; // tick (6) + gap (4) + label height (~12)
   const hasOverheadLabels =
     resolved.markers.length > 0 || resolved.eras.length > 0;
-  const markerLabelReserve = hasOverheadLabels ? 18 : 0; // markers/eras extend above date labels
+  const markerLabelReserve = hasOverheadLabels ? 28 : 0; // markers/eras get own row above sprint labels
+  const sprintLabelReserve = resolved.sprints.length > 0 ? 16 : 0; // sprint hover label above date labels
   const CONTENT_TOP_PAD = 16; // breathing room between scale labels and first row
 
   const marginTop =
-    titleHeight + tagLegendReserve + topDateLabelReserve + markerLabelReserve;
+    titleHeight +
+    tagLegendReserve +
+    topDateLabelReserve +
+    markerLabelReserve +
+    sprintLabelReserve;
 
   // Content area
   const contentH = isTagMode
@@ -286,7 +291,10 @@ export function renderGantt(
   const outerHeight = marginTop + innerHeight + BOTTOM_MARGIN;
 
   const containerWidth = exportDims?.width ?? (container.clientWidth || 800);
-  const innerWidth = containerWidth - leftMargin - RIGHT_MARGIN;
+  // Extra right margin when sprints present so hover date labels aren't clipped
+  const sprintRightPad = resolved.sprints.length > 0 ? 50 : 0;
+  const innerWidth =
+    containerWidth - leftMargin - RIGHT_MARGIN - sprintRightPad;
 
   // ── Create SVG ──────────────────────────────────────────
 
@@ -418,6 +426,7 @@ export function renderGantt(
     onClickItem
   );
   renderErasAndMarkers(g, svg, resolved, xScale, innerHeight, palette);
+  renderSprintBands(g, svg, resolved, xScale, innerHeight, palette);
 
   // ── Today marker (line rendered before rows so it paints behind task bars) ──
 
@@ -2192,7 +2201,7 @@ function renderErasAndMarkers(
       .append('text')
       .attr('class', 'gantt-era-label')
       .attr('x', (sx + ex) / 2)
-      .attr('y', -24)
+      .attr('y', -34)
       .attr('text-anchor', 'middle')
       .attr('font-size', '10px')
       .attr('fill', color)
@@ -2257,8 +2266,8 @@ function renderErasAndMarkers(
     const mx = xScale(parseDateToFractionalYear(marker.date));
     const markerDate = parseDateStringToDate(marker.date);
     const diamondSize = 5;
-    const labelY = -24;
-    const diamondY = labelY + 14;
+    const labelY = -34;
+    const diamondY = -2; // below date indicator labels
 
     const markerG = g
       .append('g')
@@ -2374,6 +2383,250 @@ function renderErasAndMarkers(
   }
 }
 
+// ── Sprint band rendering ──────────────────────────────────
+
+const SPRINT_BAND_OPACITY = 0.05;
+const SPRINT_HOVER_OPACITY = 0.12;
+const SPRINT_BOUNDARY_OPACITY = 0.3;
+
+function renderSprintBands(
+  g: d3Selection.Selection<SVGGElement, unknown, null, undefined>,
+  svg: d3Selection.Selection<SVGSVGElement, unknown, null, undefined>,
+  resolved: ResolvedSchedule,
+  xScale: d3Scale.ScaleLinear<number, number>,
+  innerHeight: number,
+  palette: PaletteColors
+): void {
+  if (resolved.sprints.length === 0) return;
+
+  // When both eras and sprints defined, eras win — don't render sprint bands
+  if (resolved.eras.length > 0) return;
+
+  const bandColor = palette.textMuted || palette.text || '#888';
+
+  // Chart content area starts at x=0 in the g coordinate space
+  const chartMinX = 0;
+
+  for (let i = 0; i < resolved.sprints.length; i++) {
+    const sprint = resolved.sprints[i];
+    const rawSx = xScale(dateToFractionalYear(sprint.startDate));
+    const rawEx = xScale(dateToFractionalYear(sprint.endDate));
+    if (rawEx <= rawSx) continue;
+
+    // Clip to chart content area — prevent bands from extending into swimlane margin
+    const sx = Math.max(rawSx, chartMinX);
+    const ex = rawEx;
+    const bandWidth = ex - sx;
+    if (bandWidth <= 0) continue;
+
+    const sprintG = g
+      .append('g')
+      .attr('class', 'gantt-sprint-group')
+      .style('cursor', 'pointer');
+
+    // Alternating shaded bands (consistent by sprint number)
+    const sprintRect = sprintG
+      .append('rect')
+      .attr('class', 'gantt-sprint-band')
+      .attr('x', sx)
+      .attr('y', 0)
+      .attr('width', bandWidth)
+      .attr('height', innerHeight)
+      .attr('fill', bandColor)
+      .attr('opacity', sprint.number % 2 === 0 ? SPRINT_BAND_OPACITY : 0);
+
+    // Invisible hit rect for hover on unshaded bands
+    if (sprint.number % 2 !== 0) {
+      sprintG
+        .append('rect')
+        .attr('x', sx)
+        .attr('y', 0)
+        .attr('width', bandWidth)
+        .attr('height', innerHeight)
+        .attr('fill', 'transparent');
+    }
+
+    // Persistent sprint number label — always visible, turns into "Sprint X" on hover
+    const sprintLabel = sprintG
+      .append('text')
+      .attr('class', 'gantt-sprint-label')
+      .attr('x', (sx + ex) / 2)
+      .attr('y', -22)
+      .attr('text-anchor', 'middle')
+      .attr('font-size', '10px')
+      .attr('font-weight', '600')
+      .attr('fill', bandColor)
+      .attr('opacity', 0.4)
+      .text(String(sprint.number));
+
+    // Dashed boundary line at sprint start (skip for first visible band)
+    if (i > 0 && rawSx >= chartMinX) {
+      sprintG
+        .append('line')
+        .attr('class', 'gantt-sprint-boundary')
+        .attr('x1', sx)
+        .attr('y1', -6)
+        .attr('x2', sx)
+        .attr('y2', innerHeight)
+        .attr('stroke', bandColor)
+        .attr('stroke-width', 1)
+        .attr('stroke-dasharray', '3 3')
+        .attr('opacity', SPRINT_BOUNDARY_OPACITY);
+    }
+
+    // Determine which tasks and groups overlap this sprint (start-inclusive, end-exclusive)
+    const sprintStartMs = sprint.startDate.getTime();
+    const sprintEndMs = sprint.endDate.getTime();
+    const overlappingTaskIds = new Set<string>();
+    for (const rt of resolved.tasks) {
+      const taskStart = rt.startDate.getTime();
+      const taskEnd = rt.endDate.getTime();
+      // Task overlaps sprint if it starts before sprint ends AND ends after sprint starts
+      if (taskStart < sprintEndMs && taskEnd > sprintStartMs) {
+        overlappingTaskIds.add(rt.task.id);
+      }
+      // Milestones (zero duration): include if they fall within [sprintStart, sprintEnd)
+      if (
+        taskStart === taskEnd &&
+        taskStart >= sprintStartMs &&
+        taskStart < sprintEndMs
+      ) {
+        overlappingTaskIds.add(rt.task.id);
+      }
+    }
+    const overlappingGroupNames = new Set<string>();
+    for (const rg of resolved.groups) {
+      const gStart = rg.startDate.getTime();
+      const gEnd = rg.endDate.getTime();
+      if (gStart < sprintEndMs && gEnd > sprintStartMs) {
+        overlappingGroupNames.add(rg.name);
+      }
+    }
+
+    // Hover: highlight band, keep overlapping tasks visible, show dates + sprint label
+    const baseOpacity = sprint.number % 2 === 0 ? SPRINT_BAND_OPACITY : 0;
+    sprintG
+      .on('mouseenter', () => {
+        // Dim tasks NOT in this sprint, keep overlapping ones visible
+        g.selectAll<SVGGElement, unknown>('.gantt-task').each(function () {
+          const el = d3Selection.select(this);
+          const id = el.attr('data-task-id');
+          el.attr(
+            'opacity',
+            id && overlappingTaskIds.has(id) ? 1 : FADE_OPACITY
+          );
+        });
+        g.selectAll<SVGElement, unknown>('.gantt-milestone').each(function () {
+          const el = d3Selection.select(this);
+          const id = el.attr('data-task-id');
+          el.attr(
+            'opacity',
+            id && overlappingTaskIds.has(id) ? 1 : FADE_OPACITY
+          );
+        });
+        svg
+          .selectAll<SVGTextElement, unknown>('.gantt-task-label')
+          .each(function () {
+            const el = d3Selection.select(this);
+            const id = el.attr('data-task-id');
+            el.attr(
+              'opacity',
+              id && overlappingTaskIds.has(id) ? 1 : FADE_OPACITY
+            );
+          });
+        g.selectAll<SVGElement, unknown>(
+          '.gantt-group-bar, .gantt-group-summary'
+        ).each(function () {
+          const el = d3Selection.select(this);
+          const name = el.attr('data-group');
+          el.attr(
+            'opacity',
+            name && overlappingGroupNames.has(name) ? 1 : FADE_OPACITY
+          );
+        });
+        svg
+          .selectAll<SVGGElement, unknown>('.gantt-group-label')
+          .each(function () {
+            const el = d3Selection.select(this);
+            const name = el.attr('data-group');
+            el.attr(
+              'opacity',
+              name && overlappingGroupNames.has(name) ? 1 : FADE_OPACITY
+            );
+          });
+        svg
+          .selectAll<SVGGElement, unknown>('.gantt-lane-header')
+          .attr('opacity', FADE_OPACITY);
+        g.selectAll<SVGElement, unknown>(
+          '.gantt-lane-band, .gantt-lane-accent, .gantt-lane-band-group'
+        ).attr('opacity', FADE_OPACITY);
+        g.selectAll<SVGElement, unknown>(
+          '.gantt-dep-arrow, .gantt-dep-arrowhead'
+        ).attr('opacity', FADE_OPACITY);
+        g.selectAll<SVGElement, unknown>('.gantt-marker-group').attr(
+          'opacity',
+          FADE_OPACITY
+        );
+        sprintRect.attr('opacity', SPRINT_HOVER_OPACITY);
+        // Only show start date indicator if it's within the visible chart area
+        const startVisible = rawSx >= chartMinX;
+        if (startVisible) {
+          showGanttDateIndicators(
+            g,
+            xScale,
+            sprint.startDate,
+            sprint.endDate,
+            innerHeight,
+            bandColor
+          );
+        } else {
+          // Only show end date indicator (start is clipped/off-screen)
+          showGanttDateIndicators(
+            g,
+            xScale,
+            sprint.endDate,
+            null,
+            innerHeight,
+            bandColor
+          );
+        }
+        // Swap persistent label to full "Sprint X" on hover
+        const accentColor = palette.accent || palette.text || bandColor;
+        sprintLabel
+          .text(`Sprint ${sprint.number}`)
+          .attr('font-size', '13px')
+          .attr('font-weight', '700')
+          .attr('fill', accentColor)
+          .attr('opacity', 1);
+      })
+      .on('mouseleave', () => {
+        resetHighlight(g, svg);
+        sprintRect.attr('opacity', baseOpacity);
+        sprintLabel
+          .text(String(sprint.number))
+          .attr('font-size', '10px')
+          .attr('font-weight', '600')
+          .attr('fill', bandColor)
+          .attr('opacity', 0.4);
+        hideGanttDateIndicators(g);
+      });
+  }
+
+  // Boundary line at end of last sprint
+  const lastSprint = resolved.sprints[resolved.sprints.length - 1];
+  const lastEx = xScale(dateToFractionalYear(lastSprint.endDate));
+  g.append('line')
+    .attr('class', 'gantt-sprint-boundary')
+    .attr('x1', lastEx)
+    .attr('y1', -6)
+    .attr('x2', lastEx)
+    .attr('y2', innerHeight)
+    .attr('stroke', bandColor)
+    .attr('stroke-width', 1)
+    .attr('stroke-dasharray', '3 3')
+    .attr('opacity', SPRINT_BOUNDARY_OPACITY);
+}
+
 /**
  * Parse a date string (YYYY, YYYY-MM, YYYY-MM-DD) to a Date object.
  * Used for eras and markers which store dates as strings.

package/src/gantt/types.ts

@@ -7,8 +7,17 @@ import type { TagGroup } from '../utils/tag-groups';
 
 // ── Duration ────────────────────────────────────────────────
 
-/** Calendar units: d (days), w (weeks), m (months), q (quarters), y (years), h (hours), min (minutes). bd = business days. */
-export type DurationUnit = 'd' | 'bd' | 'w' | 'm' | 'q' | 'y' | 'h' | 'min';
+/** Calendar units: d (days), w (weeks), m (months), q (quarters), y (years), h (hours), min (minutes). bd = business days. s = sprints. */
+export type DurationUnit =
+  | 'd'
+  | 'bd'
+  | 'w'
+  | 'm'
+  | 'q'
+  | 'y'
+  | 'h'
+  | 'min'
+  | 's';
 
 export interface Duration {
   amount: number;
@@ -119,6 +128,11 @@ export interface GanttOptions {
   /** Line numbers for option/block keywords — maps key to source line */
   optionLineNumbers: Record<string, number>;
   holidaysLineNumber: number | null;
+  // ── Sprint options ─────────────────────────────────────────
+  sprintLength: Duration | null; // default { amount: 2, unit: 'w' } when sprint mode active
+  sprintNumber: number | null; // which sprint the chart starts at (default 1)
+  sprintStart: string | null; // YYYY-MM-DD — date that sprintNumber begins
+  sprintMode: 'auto' | 'explicit' | null; // auto = activated by `s` unit, explicit = sprint-* option present
 }
 
 // ── Parsed Result ───────────────────────────────────────────
@@ -158,6 +172,12 @@ export interface ResolvedGroup {
   depth: number;
 }
 
+export interface ResolvedSprint {
+  number: number;
+  startDate: Date;
+  endDate: Date;
+}
+
 export interface ResolvedSchedule {
   tasks: ResolvedTask[];
   groups: ResolvedGroup[];
@@ -167,6 +187,7 @@ export interface ResolvedSchedule {
   tagGroups: TagGroup[];
   eras: GanttEra[];
   markers: GanttMarker[];
+  sprints: ResolvedSprint[];
   options: GanttOptions;
   diagnostics: DgmoError[];
   error: string | null;

package/src/sharing.ts

@@ -1,6 +1,7 @@
-import lzString from 'lz-string';
-const { compressToEncodedURIComponent, decompressFromEncodedURIComponent } =
-  lzString;
+import {
+  compressToEncodedURIComponent,
+  decompressFromEncodedURIComponent,
+} from 'lz-string';
 
 const DEFAULT_BASE_URL = 'https://online.diagrammo.app';
 const COMPRESSED_SIZE_LIMIT = 8192; // 8 KB

package/src/utils/duration.ts

@@ -120,7 +120,8 @@ export function addGanttDuration(
   duration: Duration,
   holidays: GanttHolidays,
   holidaySet: Set<string>,
-  direction: 1 | -1 = 1
+  direction: 1 | -1 = 1,
+  opts?: { sprintLength?: Duration }
 ): Date {
   const { amount, unit } = duration;
 
@@ -197,6 +198,19 @@ export function addGanttDuration(
       result.setTime(result.getTime() + amount * 60000 * direction);
       return result;
     }
+
+    case 's': {
+      if (!opts?.sprintLength) {
+        throw new Error(
+          'Sprint duration unit "s" requires sprintLength configuration'
+        );
+      }
+      const sl = opts.sprintLength;
+      const totalDays = amount * sl.amount * (sl.unit === 'w' ? 7 : 1);
+      const result = new Date(startDate);
+      result.setDate(result.getDate() + Math.round(totalDays) * direction);
+      return result;
+    }
   }
 }
 
@@ -204,7 +218,7 @@ export function addGanttDuration(
  * Parse a duration string like "3bd" or "5d".
  */
 export function parseDuration(s: string): Duration | null {
-  const match = s.trim().match(/^(\d+(?:\.\d+)?)(min|bd|d|w|m|q|y|h)$/);
+  const match = s.trim().match(/^(\d+(?:\.\d+)?)(min|bd|d|w|m|q|y|h|s)$/);
   if (!match) return null;
   return { amount: parseFloat(match[1]), unit: match[2] as DurationUnit };
 }

package/src/utils/legend-layout.ts

@@ -107,14 +107,16 @@ function capsuleWidth(
   }
 
   // Multi-row: compute how many entries fit per row
-  const rowWidth = maxCapsuleW - LEGEND_CAPSULE_PAD * 2;
+  // Right boundary leaves one LEGEND_CAPSULE_PAD for right padding;
+  // left padding is already baked into the starting rowX.
+  const rowWidth = maxCapsuleW - LEGEND_CAPSULE_PAD;
   let row = 1;
-  let rowX = pw + 4;
+  let rowX = LEGEND_CAPSULE_PAD + pw + 4 + addonWidth;
   let visible = 0;
 
   for (let i = 0; i < entries.length; i++) {
     const ew2 = entryWidth(entries[i].value);
-    if (rowX + ew2 > rowWidth && rowX > pw + 4) {
+    if (rowX + ew2 > rowWidth && i > 0) {
       row++;
       rowX = 0;
       if (row > LEGEND_MAX_ENTRY_ROWS) {
@@ -323,7 +325,9 @@ function buildCapsuleLayout(
   let ex = LEGEND_CAPSULE_PAD + pw + 4 + addonWidth;
   let ey = 0;
   let rowX = ex;
-  const maxRowW = containerWidth - LEGEND_CAPSULE_PAD * 2;
+  // Right boundary: one LEGEND_CAPSULE_PAD for right padding.
+  // Left padding is already in ex/rowX starting position.
+  const maxRowW = containerWidth - LEGEND_CAPSULE_PAD;
   let currentRow = 0;
 
   for (let i = 0; i < info.visibleEntries; i++) {