@jarenjs/mermaid 0.46.5 → 0.49.2

package/src/layout/gantt.js

@@ -0,0 +1,269 @@
+//@ts-check
+/**
+ * @file Gantt layout: a resolved schedule → a deterministic
+ * `PositionedDiagram` scene. Pure, host-free and vnode-free, so the
+ * geometry can be asserted without rendering anything.
+ *
+ * The time axis is not this file's invention: the domain comes from the
+ * AST, the tick positions come from `@jarenjs/core/dates` — either the
+ * document's own `tickInterval` through `timeTicksEvery`, or the shared
+ * step ladder through `axisTicksTime`, the same one the chart component
+ * draws its time axis with — and the tick labels come from the
+ * document's `axisFormat` compiled once here. A second tick ladder in a
+ * renderer would be a second set of positions.
+ *
+ * Two decisions are made here rather than in the renderer, because both
+ * are geometry:
+ *
+ * - **Tick labels thin out.** `tickInterval 1day` over two years is 730
+ *   ticks; the marks all stay, and labels are kept at the largest
+ *   stride that leaves them from overlapping. The scene says which.
+ * - **Row names elide.** A name wider than the label column is cut with
+ *   an ellipsis at layout time, so the measured width and the drawn text
+ *   are the same string.
+ */
+
+import { textWidth } from '@jarenjs/view/helpers';
+import {
+  compileDateFormat, axisTicksTime, timeTicksEvery, partsFromEpoch,
+} from '@jarenjs/core/dates';
+import { coord as round } from '../utils.js';
+import { strftimeToLdml } from '../parser/gantt-grammar.js';
+import { createExcluder, DAY_MS } from '../gantt-calendar.js';
+
+const FONT_SIZE = 13;
+const MARGIN = 12;
+const TITLE_H = 30;
+const AXIS_H = 26;
+const ROW_H = 24;
+const BAR_H = 15;
+const SECTION_H = 22;
+const LABEL_PAD = 10;
+const LABEL_MAX = 220;
+const PLOT_W = 640;
+const TICK_LABEL_GAP = 12;
+const MILESTONE_R = 7;
+const MIN_BAR_W = 2;
+const LINK_INSET = 6;
+
+/**
+ * @param {any} ast gantt AST (`parser/gantt.js`)
+ * @param {{ dateNames?: import('@jarenjs/core/dates').DateNames }} [options]
+ * @returns {any} PositionedDiagram
+ */
+export function layoutGantt(ast, options = {}) {
+  const rules = ast.rules;
+  const title = ast.meta.title ?? null;
+
+  // --- the label column
+  let labelW = 0;
+  for (const section of ast.sections)
+    for (const task of section.tasks)
+      labelW = Math.max(labelW, textWidth(task.name, FONT_SIZE));
+  labelW = Math.min(LABEL_MAX, Math.ceil(labelW)) + 2 * LABEL_PAD;
+
+  const plotX = MARGIN + labelW;
+  const plotW = PLOT_W;
+  const width = plotX + plotW + MARGIN;
+
+  // --- the shared time domain
+  const domain = ast.domain;
+  const span = domain.end - domain.start || DAY_MS;
+  const xOf = (at) => round(plotX + ((at - domain.start) / span) * plotW);
+
+  // --- rows and sections, top to bottom
+  const top = (title === null ? 0 : TITLE_H) + AXIS_H + MARGIN;
+  const sections = [];
+  const rows = [];
+  /** @type {Map<string, any>} */
+  const byId = new Map();
+  let y = top;
+  let index = 0;
+  for (let si = 0; si < ast.sections.length; si++) {
+    const section = ast.sections[si];
+    const named = section.name !== null && section.name !== '';
+    const sectionTop = y;
+    if (named) y += SECTION_H;
+    for (const task of section.tasks) {
+      const milestone = task.flags.includes('milestone');
+      const barW = milestone ? 0 : Math.max(MIN_BAR_W, xOf(task.end) - xOf(task.start));
+      // a task far shorter than a pixel still has to be visible, and the
+      // minimum width would otherwise push the last bar of a long
+      // schedule past the right edge of its own plot
+      const barX = milestone
+        ? xOf((task.start + task.end) / 2)
+        : Math.min(xOf(task.start), plotX + plotW - barW);
+      const row = {
+        index,
+        id: task.id,
+        name: elide(task.name, labelW - 2 * LABEL_PAD),
+        line: task.line,
+        start: task.start,
+        end: task.end,
+        milestone,
+        flags: task.flags,
+        after: task.after,
+        y,
+        h: ROW_H,
+        labelX: MARGIN + LABEL_PAD,
+        labelY: round(y + ROW_H / 2),
+        x: round(barX),
+        w: round(barW),
+        barY: round(y + (ROW_H - BAR_H) / 2),
+        barH: BAR_H,
+        r: MILESTONE_R,
+        classes: classesFor(task.flags),
+      };
+      rows.push(row);
+      byId.set(task.id, row);
+      y += ROW_H;
+      index++;
+    }
+    sections.push({
+      name: named ? section.name : null,
+      index: si,
+      y: sectionTop,
+      h: y - sectionTop,
+      labelY: round(sectionTop + SECTION_H / 2),
+      band: si % 2 === 1,
+    });
+  }
+  const plotBottom = Math.max(y, top);
+  const height = plotBottom + MARGIN;
+
+  // --- ticks, positions from the core kernel and labels from axisFormat
+  const ticks = planTicks(domain, rules, xOf, options.dateNames);
+  // --- excluded days, as shaded bands clipped to the domain
+  const bands = planBands(domain, rules, xOf);
+  // --- dependency anchors
+  const links = planLinks(rows, byId);
+
+  return {
+    kind: 'gantt',
+    width,
+    height,
+    fontSize: FONT_SIZE,
+    title,
+    domain,
+    plot: { x: plotX, y: top, w: plotW, h: plotBottom - top },
+    axisY: (title === null ? 0 : TITLE_H) + AXIS_H,
+    titleY: title === null ? 0 : 22,
+    labelWidth: labelW,
+    ticks,
+    bands,
+    sections,
+    rows,
+    links,
+  };
+}
+
+/**
+ * Tick positions and the labels that survive collision.
+ * @param {{ start: number, end: number }} domain
+ * @param {any} rules
+ * @param {(at: number) => number} xOf
+ * @param {any} dateNames
+ * @returns {any[]}
+ */
+function planTicks(domain, rules, xOf, dateNames) {
+  const at = rules.tick === null
+    ? axisTicksTime(domain.start, domain.end, Math.max(2, Math.round(PLOT_W / 110)))
+    : timeTicksEvery(domain.start, domain.end, rules.tick.unit, rules.tick.amount,
+      { weekStart: rules.weekStart });
+
+  const adapted = strftimeToLdml(rules.axisFormat);
+  // the parser already refused an unsupported specifier, so this compiles
+  const label = compileDateFormat(adapted.value, dateNames);
+  const parts = at.map((ms) => label(partsFromEpoch(ms)));
+
+  // keep every `stride`-th label, the smallest stride that fits
+  let widest = 0;
+  for (const text of parts) widest = Math.max(widest, textWidth(text, FONT_SIZE - 1));
+  const need = widest + TICK_LABEL_GAP;
+  const step = at.length > 1 ? Math.abs(xOf(at[1]) - xOf(at[0])) : need;
+  const stride = step >= need ? 1 : Math.max(1, Math.ceil(need / Math.max(step, 0.5)));
+
+  return at.map((ms, i) => ({
+    at: ms,
+    x: xOf(ms),
+    label: i % stride === 0 ? parts[i] : null,
+  }));
+}
+
+/**
+ * The excluded days, as bands over the domain. Rebuilt from the AST's
+ * published rules rather than carried through it, because a working
+ * calendar is a closure and the AST is plain JSON.
+ * @param {{ start: number, end: number }} domain
+ * @param {any} rules
+ * @param {(at: number) => number} xOf
+ * @returns {any[]}
+ */
+function planBands(domain, rules, xOf) {
+  const excluder = createExcluder(rules.excludes, rules.weekendStart);
+  if (!excluder.any) return [];
+  const fromDay = Math.floor(domain.start / DAY_MS);
+  const toDay = Math.ceil(domain.end / DAY_MS);
+  // a domain wider than a few years shades nothing: the bands would be
+  // narrower than a hairline and the answer is the axis, not stripes
+  if (toDay - fromDay > 1200) return [];
+  return excluder.intervalsIn(fromDay, toDay).map((span) => {
+    const start = Math.max(span.start, domain.start);
+    const end = Math.min(span.end, domain.end);
+    return { start, end, x: xOf(start), w: round(Math.max(0, xOf(end) - xOf(start))) };
+  }).filter((band) => band.w > 0);
+}
+
+/**
+ * One orthogonal connector per `after` dependency: out of the
+ * predecessor's right edge, across, and into this row's left edge.
+ * @param {any[]} rows
+ * @param {Map<string, any>} byId
+ * @returns {any[]}
+ */
+function planLinks(rows, byId) {
+  const links = [];
+  for (const row of rows) {
+    for (const id of row.after) {
+      const from = byId.get(id);
+      if (from === undefined || from.index >= row.index) continue;
+      const x1 = round(from.milestone ? from.x + from.r : from.x + from.w);
+      const y1 = round(from.y + from.h / 2);
+      const x2 = round(row.milestone ? row.x - row.r : row.x);
+      const y2 = round(row.y + row.h / 2);
+      if (Math.abs(x2 - x1) < 1) {
+        // the successor starts where its predecessor ended: a straight
+        // drop reads as "immediately after", a hook reads as a delay
+        links.push({ from: id, to: row.id, points: [[x1, y1], [x1, y2]] });
+        continue;
+      }
+      const mid = round(Math.max(x1 + LINK_INSET, x2 - LINK_INSET));
+      links.push({ from: id, to: row.id, points: [[x1, y1], [mid, y1], [mid, y2], [x2, y2]] });
+    }
+  }
+  return links;
+}
+
+/**
+ * @param {string[]} flags
+ * @returns {string}
+ */
+function classesFor(flags) {
+  let out = 'mm-gantt-task';
+  for (const flag of flags) out += ` mm-gantt-${flag}`;
+  return out;
+}
+
+/**
+ * Cut a name to the label column, measuring the string that will
+ * actually be drawn.
+ * @param {string} text
+ * @param {number} max
+ * @returns {string}
+ */
+function elide(text, max) {
+  if (textWidth(text, FONT_SIZE) <= max) return text;
+  let cut = text.length;
+  while (cut > 1 && textWidth(text.slice(0, cut) + '…', FONT_SIZE) > max) cut--;
+  return text.slice(0, cut) + '…';
+}

package/src/parser/gantt-grammar.js

@@ -0,0 +1,298 @@
+//@ts-check
+/**
+ * @file The three Gantt token grammars, adapted to the core date
+ * kernel. Mermaid's Gantt header speaks **three different pattern
+ * languages** and none of them is Unicode LDML:
+ *
+ * - `dateFormat` is dayjs' `customParseFormat` vocabulary (moment's
+ *   spelling): `YYYY-MM-DD`, where `YYYY` is the calendar year;
+ * - `axisFormat` is d3-time-format's strftime vocabulary: `%Y-%m-%d`;
+ * - `tickInterval` and a task's duration are two small regular
+ *   grammars of their own (`1week`, `3d`).
+ *
+ * Each gets its own tokenizer here, and each token is mapped
+ * individually onto the LDML token `compileDateFormat`/`compileDateParser`
+ * understand. Handing `YYYY` straight to the core compiler would be a
+ * silent lie — LDML's `YYYY` is the *week-numbering* year, which is
+ * moment's most reported footgun and the reason `@jarenjs/core/dates`
+ * refuses that spelling in the first place.
+ *
+ * Every function here returns `{ value, error }` rather than throwing:
+ * the caller owns the source line, and a `JM` error without one is not
+ * worth much.
+ *
+ * The vendored conformance table for all of this — which tokens the
+ * shipped Mermaid version documents, which of them this engine
+ * implements and why the rest are refused — is
+ * `test/mermaid/fixtures/gantt-grammar.json`, pinned against this file
+ * by `test/mermaid/gantt.test.js`.
+ */
+
+/** Mermaid's own default when a diagram declares no `dateFormat`. */
+export const DEFAULT_DATE_FORMAT = 'YYYY-MM-DD';
+
+/** Mermaid's own default when a diagram declares no `axisFormat`. */
+export const DEFAULT_AXIS_FORMAT = '%Y-%m-%d';
+
+/** dayjs token → the LDML token that reads and writes the same field. */
+const MOMENT_TO_LDML = Object.freeze({
+  YYYY: 'yyyy', YY: 'yy', Y: 'y',
+  MMMM: 'MMMM', MMM: 'MMM', MM: 'MM', M: 'M',
+  DD: 'dd', D: 'd',
+  HH: 'HH', H: 'H', hh: 'hh', h: 'h',
+  mm: 'mm', m: 'm', ss: 'ss', s: 's',
+  SSS: 'SSS', S: 'S',
+  A: 'a', a: 'a',
+  ZZ: 'XX', Z: 'XXX',
+});
+
+/** Documented dayjs tokens this engine will not read, and why. */
+const MOMENT_REFUSED = Object.freeze({
+  SS: 'the fraction tokens are tenths (S) and milliseconds (SSS); there is no hundredths field',
+  Q: 'a quarter is derived from a month, not a field of a date',
+  Do: 'the ordinal suffix is locale text and this engine ships no ordinal data',
+  DDDD: 'the day of the year is derived from a date, not a field of one',
+  DDD: 'the day of the year is derived from a date, not a field of one',
+  X: 'an epoch second is a whole value, not a calendar field',
+  x: 'an epoch millisecond is a whole value, not a calendar field',
+  ww: 'the ISO week number is derived from a date, not a field of one',
+  w: 'the ISO week number is derived from a date, not a field of one',
+});
+
+/** strftime specifier → the LDML fragment that writes the same field. */
+const STRFTIME_TO_LDML = Object.freeze({
+  Y: 'yyyy', y: 'yy', m: 'MM', d: 'dd',
+  H: 'HH', I: 'hh', M: 'mm', S: 'ss', L: 'SSS', j: 'DDD',
+  a: 'EEE', A: 'EEEE', b: 'MMM', B: 'MMMM', p: 'a',
+  Z: 'XX',
+  x: "MM'/'dd'/'yyyy", X: "HH':'mm':'ss",
+  '%': "'%'",
+});
+
+/** Documented strftime specifiers this engine will not write, and why. */
+const STRFTIME_REFUSED = Object.freeze({
+  e: 'a space-padded day is a token the formatter does not have',
+  c: 'it expands to %e, which is unsupported',
+  U: 'd3 counts weeks from the first Sunday; the core week number is ISO, so the two disagree',
+  W: 'd3 counts weeks from the first Monday; the core week number is ISO, so the two disagree',
+  w: 'd3 numbers Sunday 0; the core weekday number is ISO, where 1 is Monday',
+  f: 'microseconds are below the millisecond this suite measures time in',
+  g: 'the week-based year is a second year field, and the core parts record has one',
+  G: 'the week-based year is a second year field, and the core parts record has one',
+  q: 'a quarter on a time axis is a label, not a tick this engine plans',
+  Q: 'an epoch is a whole value, not a calendar field',
+  s: 'an epoch is a whole value, not a calendar field',
+  u: 'the ISO weekday number is a tick label this engine does not plan',
+  V: 'the ISO week number is a tick label this engine does not plan',
+});
+
+/** The LDML tokens that need a `names` provider before they compile. */
+const NEEDS_NAMES = new Set(['MMM', 'MMMM', 'EEE', 'EEEE', 'a']);
+
+const MAX_MOMENT_TOKEN = 4;
+
+/**
+ * @typedef {{ value: any, error: string | null }} Adapted
+ */
+
+/** @param {string} message @returns {Adapted} */
+function bad(message) {
+  return { value: null, error: message };
+}
+
+/** @param {any} value @returns {Adapted} */
+function ok(value) {
+  return { value, error: null };
+}
+
+/**
+ * Quote a run of literal text so `compileDateFormat` cannot read a
+ * letter inside it as a token.
+ * @param {string} text
+ * @returns {string}
+ */
+function quoted(text) {
+  return text === '' ? '' : `'${text.replace(/'/g, "''")}'`;
+}
+
+/**
+ * Adapt a Mermaid `dateFormat` to an LDML pattern.
+ * @param {string} pattern - a dayjs `customParseFormat` pattern
+ * @returns {Adapted} `value` is the LDML pattern
+ */
+export function momentToLdml(pattern) {
+  let out = '';
+  let literal = '';
+  for (let i = 0; i < pattern.length;) {
+    const ch = pattern[i];
+    if (ch === '[') { // dayjs' bracket escape
+      const end = pattern.indexOf(']', i + 1);
+      if (end < 0)
+        return bad(`unterminated '[' escape in dateFormat '${pattern}'`);
+      literal += pattern.slice(i + 1, end);
+      i = end + 1;
+      continue;
+    }
+    let matched = null;
+    for (let len = MAX_MOMENT_TOKEN; len >= 1; len--) {
+      const candidate = pattern.slice(i, i + len);
+      if (candidate.length !== len) continue;
+      if (MOMENT_TO_LDML[candidate] !== undefined || MOMENT_REFUSED[candidate] !== undefined) {
+        matched = candidate;
+        break;
+      }
+    }
+    if (matched === null) {
+      literal += ch;
+      i += 1;
+      continue;
+    }
+    if (MOMENT_REFUSED[matched] !== undefined) {
+      return bad(`dateFormat token '${matched}' is not supported: ${MOMENT_REFUSED[matched]}`);
+    }
+    out += quoted(literal);
+    literal = '';
+    out += MOMENT_TO_LDML[matched];
+    i += matched.length;
+  }
+  out += quoted(literal);
+  return ok(out);
+}
+
+/**
+ * Adapt a Mermaid `axisFormat` to an LDML pattern. This is a separate
+ * grammar from `dateFormat` on purpose: `%m` is a month and `m` is a
+ * minute, so one table serving both would silently mis-read half of
+ * every axis.
+ * @param {string} pattern - a d3-time-format (strftime) pattern
+ * @returns {Adapted} `value` is the LDML pattern
+ */
+export function strftimeToLdml(pattern) {
+  let out = '';
+  let literal = '';
+  for (let i = 0; i < pattern.length;) {
+    if (pattern[i] !== '%') {
+      literal += pattern[i];
+      i += 1;
+      continue;
+    }
+    const spec = pattern[i + 1];
+    if (spec === undefined)
+      return bad(`axisFormat '${pattern}' ends in a bare '%'`);
+    if (STRFTIME_REFUSED[spec] !== undefined)
+      return bad(`axisFormat specifier '%${spec}' is not supported: ${STRFTIME_REFUSED[spec]}`);
+    const ldml = STRFTIME_TO_LDML[spec];
+    if (ldml === undefined)
+      return bad(`axisFormat specifier '%${spec}' is not a d3-time-format directive`);
+    out += quoted(literal);
+    literal = '';
+    out += ldml;
+    i += 2;
+  }
+  out += quoted(literal);
+  return ok(out);
+}
+
+/**
+ * Whether an LDML pattern uses a token that needs locale names, and
+ * which token that is. Used to turn `compileDateFormat`'s TypeError into
+ * a `JM` error that names the Mermaid spelling and the way out.
+ * @param {string} ldml
+ * @returns {string | null}
+ */
+export function ldmlNeedsNames(ldml) {
+  let inQuote = false;
+  for (let i = 0; i < ldml.length;) {
+    if (ldml[i] === "'") {
+      if (ldml[i + 1] === "'") { i += 2; continue; }
+      inQuote = !inQuote;
+      i += 1;
+      continue;
+    }
+    if (inQuote) { i += 1; continue; }
+    for (let len = 4; len >= 1; len--) {
+      const candidate = ldml.slice(i, i + len);
+      if (candidate.length === len && NEEDS_NAMES.has(candidate))
+        return candidate;
+    }
+    i += 1;
+  }
+  return null;
+}
+
+// `tickInterval` is one regular grammar in the shipped renderer, and
+// this is that regular expression. It is a module constant: a Gantt
+// header is read once per parse, but building a pattern per parse is
+// the habit this codebase does not have.
+const TICK_INTERVAL = /^([1-9]\d*)(millisecond|second|minute|hour|day|week|month)$/;
+
+/**
+ * Parse a `tickInterval` directive.
+ * @param {string} text
+ * @returns {Adapted} `value` is `{ amount, unit }`, the unit a core
+ *   `DATE_UNITS` member
+ */
+export function parseTickInterval(text) {
+  const match = TICK_INTERVAL.exec(text.trim());
+  if (match === null) {
+    return bad(`tickInterval '${text}' is not a whole count followed by`
+      + ' millisecond, second, minute, hour, day, week or month');
+  }
+  return ok({ amount: Number(match[1]), unit: match[2] });
+}
+
+// The task duration grammar, likewise straight from the shipped chunk.
+const DURATION = /^(\d+(?:\.\d+)?)([Mdhmswy]|ms)$/;
+
+/** Mermaid's one-letter duration units → core calendar units. */
+const DURATION_UNITS = Object.freeze({
+  ms: 'millisecond', s: 'second', m: 'minute', h: 'hour',
+  d: 'day', w: 'week', M: 'month', y: 'year',
+});
+
+/**
+ * Parse a task duration (`3d`, `1.5w`, `2M`).
+ * @param {string} text
+ * @returns {Adapted} `value` is `{ amount, unit }`, or `null` with no
+ *   error when the text is simply not a duration (the caller then tries
+ *   to read it as a date)
+ */
+export function parseTaskDuration(text) {
+  const match = DURATION.exec(text.trim());
+  if (match === null)
+    return { value: null, error: null };
+  return ok({ amount: Number(match[1]), unit: DURATION_UNITS[match[2]] });
+}
+
+/** ISO weekday numbers, 1 is Monday — the numbering `isoWeekdayFromDays` uses. */
+export const ISO_WEEKDAYS = Object.freeze({
+  monday: 1, tuesday: 2, wednesday: 3, thursday: 4,
+  friday: 5, saturday: 6, sunday: 7,
+});
+
+/**
+ * Parse a `weekday` directive: which day a whole-week tick starts on.
+ * @param {string} text
+ * @returns {Adapted} `value` is an ISO weekday, 1 to 7
+ */
+export function parseWeekday(text) {
+  const day = ISO_WEEKDAYS[text.trim().toLowerCase()];
+  if (day === undefined)
+    return bad(`weekday '${text}' is not a day name (monday … sunday)`);
+  return ok(day);
+}
+
+/**
+ * Parse a `weekend` directive: the first of the two days
+ * `excludes weekends` removes.
+ * @param {string} text
+ * @returns {Adapted} `value` is an ISO weekday, 5 (friday) or 6 (saturday)
+ */
+export function parseWeekend(text) {
+  const name = text.trim().toLowerCase();
+  if (name !== 'friday' && name !== 'saturday')
+    return bad(`weekend '${text}' is neither friday nor saturday`);
+  return ok(ISO_WEEKDAYS[name]);
+}
+
+export { MOMENT_TO_LDML, MOMENT_REFUSED, STRFTIME_TO_LDML, STRFTIME_REFUSED };