feat(gantt): support multiple excludes and includes lines

[devareddy05]

📑 Summary

Allow Gantt diagrams to split long excludes (and includes) lists across multiple lines, optionally grouped with %% comments:

gantt
    dateFormat DD-MM-YYYY
    excludes weekends
    %% week 7 is winter break
    excludes 10-02-2025 11-02-2025 12-02-2025
    %% workers holiday 1 maj
    excludes 01-05-2025

Loading

Previously each excludes line replaced the previous one.

Resolves #6270

Changes

• ganttDb.js: setExcludes / setIncludes now merge tokens via a shared helper with Set-based dedupe. Single-line usage is unchanged; repeated lines concatenate.
• ganttDb.spec.ts: refreshed the "should not infinite loop when excluding everything" test that previously relied on replace-semantics; it now uses clear() between scenarios.
• New unit tests in ganttDb.spec.ts and parser/gantt.spec.js covering merge, dedupe, includes, and the issue diagram.
• docs/syntax/gantt.md: documented the multi-line form.

Testing

pnpm exec vitest run packages/mermaid/src/diagrams/gantt/ -> 76 pass, 1 skipped (timezone-gated).

📋 Tasks

• 📖 read the contribution guidelines
• 💻 added unit tests
• 📓 documentation updated
• 🦋 changeset added (minor)

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	ad24fb5
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6a197a8cc7d4b0000860dfc2
😎 Deploy Preview	https://deploy-preview-7772--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[changeset-bot]

🦋 Changeset detected

Latest commit: ad24fb5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
mermaid	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/@mermaid-js/examples@7772

mermaid

npm i https://pkg.pr.new/mermaid@7772

@mermaid-js/layout-elk

npm i https://pkg.pr.new/@mermaid-js/layout-elk@7772

@mermaid-js/layout-tidy-tree

npm i https://pkg.pr.new/@mermaid-js/layout-tidy-tree@7772

@mermaid-js/mermaid-zenuml

npm i https://pkg.pr.new/@mermaid-js/mermaid-zenuml@7772

@mermaid-js/parser

npm i https://pkg.pr.new/@mermaid-js/parser@7772

@mermaid-js/tiny

npm i https://pkg.pr.new/@mermaid-js/tiny@7772

commit: ad24fb5

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 3.27%. Comparing base (f472f50) to head (ad24fb5).

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7772      +/-   ##
==========================================
+ Coverage     3.25%   3.27%   +0.01%     
==========================================
  Files          599     599              
  Lines        60979   60986       +7     
  Branches       917     921       +4     
==========================================
+ Hits          1986    1997      +11     
+ Misses       58993   58989       -4     

Flag	Coverage Δ
unit	3.27% <100.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/mermaid/src/diagrams/gantt/ganttDb.js	77.92% <100.00%> (+0.73%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	👍 Changes approved	1 added	May 29, 2026, 11:42 AM

[pbrolin47]

Hi @devareddy05, thanks for this PR that improves the Gant-diagrams. Some things to adress:

[sisyphos-bot]

---

What's working well

🎉 mergeTokens is clean and well-designed. The lowercase normalization, whitespace/comma splitting, and Set-based deduplication are all correct. Switching from replace-semantics
to accumulate-semantics is the right fix for multi-line excludes.

🎉 The infinite loop guard in fixTaskDates is a good defensive addition. The 10,000-day cap and the informative error message (Failed to find a valid date…) turn an infinite
hang into a debuggable error.

🎉 Changeset and docs are present. minor bump with feat: prefix is correct for new syntax.

---

Things to address

🟡 [important] vert task order change is undocumented and untested

ganttDb.js lines 578–583 contain a behavior change that isn't mentioned in the PR description:

// Before (inferred)
rawTask.order = lastOrder;
lastOrder++;

// After
if (rawTask.vert) {
rawTask.order = -1;
} else {
rawTask.order = lastOrder;
lastOrder++;
}

The fix is correct — vert tasks consumed lastOrder slots, creating invisible row gaps in non-vert task layout (because ganttRenderer.js:246 filters vert tasks out with
tasksWithoutVert = theArray.filter(task => !task.vert) before row assignment). But this is a behavioral change that should have either a unit test asserting that vert tasks
don't affect the order sequence, or at minimum a note in the PR description explaining what it fixes.

Suggested addition — unit test in ganttDb.spec.ts:

it('should not consume order slots for vert tasks', () => {
ganttDb.setDateFormat('YYYY-MM-DD');
ganttDb.addSection('s');
ganttDb.addTask('vert-task :vert, 2024-01-01, 1d');
ganttDb.addTask('normal-task : 2024-01-02, 1d');
const tasks = ganttDb.getTasks();
const vertTask = tasks.find(t => t.id === 'vert-task');
const normalTask = tasks.find(t => t.id === 'normal-task');
expect(vertTask!.order).toBe(-1);
expect(normalTask!.order).toBe(0); // not 1
});

🟡 [important] No Cypress E2E test for multi-line excludes

The core feature — writing excludes or includes on multiple lines — has unit tests for DB logic but no visual regression test. Since this changes rendered gantt chart output
(which days are grayed out), a Cypress test is needed per the project's test strategy.

Suggested test in cypress/integration/rendering/gantt.spec.ts:
it('should render gantt with multi-line excludes', () => {
imgSnapshotTest(gantt dateFormat YYYY-MM-DD excludes weekends excludes 2024-01-01 section S Task : 2024-01-01, 7d);
});

---

Security

No XSS or injection issues introduced by this PR. The mergeTokens tokens are consumed exclusively as comparison strings in isInvalidDate — they never reach any DOM sink. Error
messages in fixTaskDates are static string literals. DOMPurify sanitization of final SVG output remains undisturbed.

(One pre-existing concern noted but out of scope: todayMarker.replace(/,/g, ';') at renderer line ~867 sets a style attribute from user-supplied text without sanitization —
unrelated to this PR.)

---

[devareddy05]

Thanks for the review @pbrolin47.

On the two points raised by sisyphos-bot:

vert task order change — this is not part of this PR. The diff (git diff origin/develop..HEAD -- packages/mermaid/src/diagrams/gantt/ganttDb.js) touches only the new mergeTokens helper plus setIncludes / setExcludes. The if (rawTask.vert) { rawTask.order = -1; ... } block is already on develop (visible in git blame origin/develop and git show origin/develop:packages/mermaid/src/diagrams/gantt/ganttDb.js). Happy to add a test for it under a separate issue if useful, but it is out of scope here.

No Cypress E2E test for multi-line excludes — fair point, added in 2d5c4289e. New test should render multi-line excludes (issue #6270) in cypress/integration/rendering/gantt/gantt.spec.js snapshots a chart that uses three excludes lines (one weekend rule, one closure block with comments, one one-off holiday) and a task spanning all three so the rendered grayed-out columns prove the tokens were concatenated rather than overwritten.

Let me know if you would like anything else changed.

[pbrolin47]

Hi @devareddy05,
Thanks for adding the Cypress E2E-test.

[mermaid-bot]

@devareddy05, Thank you for the contribution!
You are now eligible for a year of Premium account on MermaidChart.
Sign up with your GitHub account to activate.