feat(gitGraph): Add interactive click support for commits, branches, and tags

.changeset/dirty-corners-relax.md

@@ -0,0 +1,5 @@
+---
+'mermaid': minor
+---
+
+feat: Add interactive click support for commits, branches, and tags in gitGraph

demos/git.html

@@ -554,6 +554,34 @@ <h2>Three branches and a cherry-pick from each graph</h2>
     commit id:"C"
     merge featureA
     </pre>
+    <h2>Click interaction tests (click nodes/branches/tags below)</h2>
+    <pre class="mermaid">
+    gitGraph
+      commit id: "no-click"
+      commit id: "click-same-tab"
+      commit id: "click-new-tab" tag: "tag-new-tab"
+      branch "br-click-same"
+      checkout "br-click-same"
+      commit id: "reverse-type" type: REVERSE
+      checkout main
+      branch "br-click-new"
+      checkout "br-click-new"
+      commit id: "highlight-type" type: HIGHLIGHT tag: "tag-same-tab"
+      checkout main
+      merge "br-click-same" id: "merge-click"
+
+      click commit "click-same-tab" "https://example.com/click-same-tab" "same tab"
+      click commit "click-new-tab" "https://example.com/click-new-tab" "new tab" "_blank"
+      click commit "reverse-type" "https://example.com/reverse" "reverse"
+      click commit "highlight-type" "https://example.com/highlight" "highlight"
+      click commit "merge-click" "https://example.com/merge" "merge"
+
+      click branch "br-click-same" "https://example.com/br-click-same" "same tab"
+      click branch "br-click-new" "https://example.com/br-click-new" "new tab" "_blank"
+
+      click tag "tag-same-tab" "https://example.com/tag-same-tab" "same tab"
+      click tag "tag-new-tab" "https://example.com/tag-new-tab" "new tab" "_blank"
+    </pre>
     <script type="module">
       import mermaid from './mermaid.esm.mjs';
       const ALLOWED_TAGS = [

docs/syntax/gitgraph.md

@@ -413,6 +413,67 @@ Let see an example:
         commit id:"C"
 ```
 
+## Interaction
+
+You can add clickable links to commits, branches, and tags. This allows you to navigate to external URLs when clicking on the corresponding element in the diagram.
+
+> **Note**
+>
+> - `securityLevel='strict'`: Click links are disabled.
+> - `securityLevel='loose'`: Click links are enabled and respect specified targets (`_blank`, `_self`, etc.).
+> - `securityLevel='sandbox'`: Click links are enabled and override the link target to `_top`.
+> - `securityLevel='antiscript'`: Click links are enabled, but unsafe URL schemes are suppressed.
+
+Usage:
+
+- `click commit <id> "<url>"`: Adds a link to a commit with the given ID.
+- `click branch <name> "<url>"`: Adds a link to a branch with the given name.
+- `click tag <name> "<url>"`: Adds a link to a tag with the given name.
+
+You can also specify an optional tooltip and target (e.g., `_blank` for new tab).
+
+Syntax: `click <type> <id> "<url>" ["tooltip"] [target]`
+
+Links are opened in the same browser tab/window by default. It is possible to change this by adding a link target to the click definition (`_self`, `_blank`, `_parent` and `_top` are supported):
+
+Example:
+
+```mermaid-example
+gitGraph
+   commit id: "ONE"
+   commit id: "TWO" type: REVERSE
+   commit id: "THREE" type: HIGHLIGHT tag: "v1.0"
+   branch develop
+   commit id: "FOUR"
+   checkout main
+   merge develop id: "FIVE"
+
+   click commit "ONE" "https://github.com/mermaid-js/mermaid" "This is a link"
+   click commit "TWO" "https://www.wikipedia.org" "Open this in a new tab" _blank
+   click commit "THREE" "https://mermaid.js.org" "HIGHLIGHT type"
+   click commit "FIVE" "https://github.com/mermaid-js/mermaid/pulls" "MERGE type"
+   click branch "develop" "https://example.org"
+   click tag "v1.0" "https://github.com/mermaid-js/mermaid/releases" "Open this in a new tab" _blank
+```
+
+```mermaid
+gitGraph
+   commit id: "ONE"
+   commit id: "TWO" type: REVERSE
+   commit id: "THREE" type: HIGHLIGHT tag: "v1.0"
+   branch develop
+   commit id: "FOUR"
+   checkout main
+   merge develop id: "FIVE"
+
+   click commit "ONE" "https://github.com/mermaid-js/mermaid" "This is a link"
+   click commit "TWO" "https://www.wikipedia.org" "Open this in a new tab" _blank
+   click commit "THREE" "https://mermaid.js.org" "HIGHLIGHT type"
+   click commit "FIVE" "https://github.com/mermaid-js/mermaid/pulls" "MERGE type"
+   click branch "develop" "https://example.org"
+   click tag "v1.0" "https://github.com/mermaid-js/mermaid/releases" "Open this in a new tab" _blank
+```
+
 ## GitGraph specific configuration options
 
 In Mermaid, you have the option to configure the gitgraph diagram. You can configure the following options:

e2e/diagrams/git/nightly-check/98-should-render-gitgraph-with-click-interactions.mmd

@@ -0,0 +1,14 @@
+---
+config:
+  securityLevel: loose
+---
+gitGraph
+  commit id: "ONE"
+  commit id: "TWO" tag: "v1.0"
+  branch develop
+  commit id: "THREE"
+  checkout main
+  merge develop id: "FOUR"
+  click commit "ONE" "https://example.com/commit" "Commit Tooltip"
+  click branch "develop" "https://example.com/branch" "Branch Tooltip"
+  click tag "v1.0" "https://example.com/tag" "Tag Tooltip"

e2e/helpers/util.ts

@@ -285,7 +285,7 @@ export const verifyScreenshot = async (
 
     if (!existsSync(snapshotPath)) {
       mkdirSync(dirname(snapshotPath), { recursive: true });
-      const screenshot = await target.screenshot({ animations: 'disabled', scale: 'device' });
+      const screenshot = await target.screenshot({ animations: 'disabled', scale: 'css' });
       writeFileSync(snapshotPath, screenshot);
       return;
     }

e2e/other/pr-check/interaction.spec.js

@@ -102,12 +102,45 @@ test.describe('Interaction', () => {
         'Clicked By Gant test1 test2 test3'
       );
     });
+
+    test('gitGraph: should handle a click on a commit with a bound url', async ({ page }) => {
+      const commitLinks = page.getByRole('link', { name: 'Commit Tooltip', exact: true });
+      await expect(commitLinks).toHaveCount(2);
+      await expect(commitLinks.first()).toHaveAttribute('target', '_blank');
+      const popupPromise = page.waitForEvent('popup');
+      await commitLinks.first().click();
+      const popup = await popupPromise;
+      await expect(popup).toHaveURL('/empty.html');
+    });
+
+    test('gitGraph: should handle a click on a branch with a bound url', async ({ page }) => {
+      const branchLink = page.getByRole('link', { name: 'Branch Tooltip', exact: true });
+      await expect(branchLink).toHaveCount(1);
+      await branchLink.click();
+      await expect(page).toHaveURL('/empty.html');
+    });
+
+    test('gitGraph: should handle a click on a tag with a bound url', async ({ page }) => {
+      const tagLink = page.getByRole('link', { name: 'Tag Tooltip', exact: true });
+      await expect(tagLink).toHaveCount(1);
+      await tagLink.click();
+      await expect(page).toHaveURL('/empty.html');
+    });
   });
 
   test.describe('Interaction - security level tight', () => {
     test.beforeEach(async ({ page }) => {
       await page.goto('/click_security_strict.html');
     });
+
+    test('gitGraph: should not create interactive links in strict mode', async ({ page }) => {
+      const gitGraph = page.locator('svg').filter({ has: page.locator('.commit-bullets') });
+      await expect(gitGraph).toHaveCount(1);
+      await expect(gitGraph).toBeVisible();
+      await expect(gitGraph.locator('a')).toHaveCount(0);
+      await expect(gitGraph.locator('.clickable')).toHaveCount(0);
+    });
+
     test('should handle a click on a node without a bound function', async ({ page }) => {
       await page.locator('.node').filter({ hasText: 'Function1' }).click();
       await expect(page.locator('.created-by-click')).toHaveCount(0);

e2e/platform/click_security_loose.html

@@ -123,6 +123,17 @@
         class ShapeCallback2
         click ShapeCallback2 call clickByClass(123) "This is a tooltip for a callback"
       </pre>
+
+      <pre class="mermaid">
+      gitGraph
+        commit id: "ONE"
+        commit id: "TWO" tag: "v1.0"
+        branch develop
+        commit id: "THREE"
+        click commit "ONE" "/empty.html" "Commit Tooltip" "_blank"
+        click branch "develop" "/empty.html" "Branch Tooltip"
+        click tag "v1.0" "/empty.html" "Tag Tooltip"
+      </pre>
     </div>
 
     <script>

e2e/platform/click_security_strict.html

@@ -20,6 +20,17 @@
     click 2URL "/empty.html" "Visit <strong>mermaid docs</strong>"
     </pre>
 
+    <pre class="mermaid">
+    gitGraph
+      commit id: "ONE"
+      commit id: "TWO" tag: "v1.0"
+      branch develop
+      commit id: "THREE"
+      click commit "ONE" "/empty.html" "Commit Tooltip"
+      click branch "develop" "/empty.html" "Branch Tooltip"
+      click tag "v1.0" "/empty.html" "Tag Tooltip"
+    </pre>
+
     <pre class="mermaid">
     gantt
     dateFormat  YYYY-MM-DD

e2e/sheet-order.json

@@ -807,7 +807,8 @@
     "94-should-render-with-parallelcommits-set-to-false.png",
     "95-should-render-with-custom-mainbranchname.png",
     "96-should-render-with-custom-mainbranchorder.png",
-    "97-should-render-branch-labels-with-multi-line-text-aligned-with-background-in-lr-layout.png"
+    "97-should-render-branch-labels-with-multi-line-text-aligned-with-background-in-lr-layout.png",
+    "98-should-render-gitgraph-with-click-interactions.png"
   ],
   "diagrams/info": [
     "should-handle-an-info-definition-with-showinfo.png",

packages/mermaid/src/diagrams/git/gitGraph.spec.ts

@@ -1,6 +1,7 @@
 import { log } from '../../logger.js';
 import { db } from './gitGraphAst.js';
 import { parser } from './gitGraphParser.js';
+import getStyles from './styles.js';
 
 describe('when parsing a gitGraph', function () {
   beforeEach(function () {
@@ -1388,4 +1389,14 @@ describe('when parsing a gitGraph', function () {
       expect(config).toHaveProperty('parallelCommits');
     });
   });
+
+  describe('getStyles', () => {
+    it('should include keyboard focus-visible selectors for clickable elements', () => {
+      const styles = getStyles({});
+      expect(styles).toContain('a:focus-visible .clickable text');
+      expect(styles).toContain('a:focus-visible .commit.clickable circle');
+      expect(styles).toContain('a:focus-visible .commit.clickable rect:not(.commit-label-bkg)');
+      expect(styles).toContain('a:focus-visible .commit.clickable path');
+    });
+  });
 });

packages/mermaid/src/diagrams/git/gitGraphAst.spec.ts

@@ -0,0 +1,103 @@
+import { db, clear } from './gitGraphAst.js';
+
+describe('gitGraph links', () => {
+  beforeEach(() => {
+    clear();
+  });
+
+  describe('setLink', () => {
+    it('should store a basic link', () => {
+      db.setLink('commit1', 'https://example.com', 'commit');
+      expect(db.getLinks().has('commit:commit1')).toBe(true);
+      expect(db.getLink('commit1')?.link).toBe('https://example.com');
+    });
+
+    it('should default target to _self', () => {
+      db.setLink('commit1', 'https://example.com', 'commit');
+      expect(db.getLink('commit1')?.target).toBe('_self');
+    });
+
+    it('should store tooltip when provided', () => {
+      db.setLink('commit1', 'https://example.com', 'commit', 'My tooltip');
+      expect(db.getLink('commit1')?.tooltip).toBe('My tooltip');
+    });
+
+    it('should store target when provided', () => {
+      db.setLink('commit1', 'https://example.com', 'commit', undefined, '_blank');
+      expect(db.getLink('commit1')?.target).toBe('_blank');
+    });
+
+    it('should store all options together', () => {
+      db.setLink('commit1', 'https://example.com', 'commit', 'Tooltip', '_blank');
+      const link = db.getLink('commit1');
+      expect(link?.link).toBe('https://example.com');
+      expect(link?.tooltip).toBe('Tooltip');
+      expect(link?.target).toBe('_blank');
+    });
+
+    it('should overwrite existing link for same id', () => {
+      db.setLink('commit1', 'https://old.com', 'commit');
+      db.setLink('commit1', 'https://new.com', 'commit');
+      expect(db.getLink('commit1')?.link).toBe('https://new.com');
+    });
+
+    it('should handle special characters in commit id', () => {
+      db.setLink('v1.0.0-beta', 'https://example.com', 'commit');
+      expect(db.getLink('v1.0.0-beta')?.link).toBe('https://example.com');
+    });
+
+    it('should handle overlapping identifiers across commit, branch, and tag types', () => {
+      db.setLink('v1.0', 'https://example.com/commit', 'commit');
+      db.setLink('v1.0', 'https://example.com/branch', 'branch');
+      db.setLink('v1.0', 'https://example.com/tag', 'tag');
+
+      expect((db.getLink as any)('v1.0', 'commit')?.link).toBe('https://example.com/commit');
+      expect((db.getLink as any)('v1.0', 'branch')?.link).toBe('https://example.com/branch');
+      expect((db.getLink as any)('v1.0', 'tag')?.link).toBe('https://example.com/tag');
+    });
+  });
+
+  describe('getLinks', () => {
+    it('should return empty map when no links', () => {
+      expect(db.getLinks().size).toBe(0);
+    });
+
+    it('should return all stored links', () => {
+      db.setLink('c1', 'https://example.com/1', 'commit');
+      db.setLink('c2', 'https://example.com/2', 'commit');
+      const links = db.getLinks();
+      expect(links.size).toBe(2);
+      expect(links.has('commit:c1')).toBe(true);
+      expect(links.has('commit:c2')).toBe(true);
+    });
+
+    it('should return the internal map (performance)', () => {
+      db.setLink('c1', 'https://example.com', 'commit');
+      const links1 = db.getLinks();
+      const links2 = db.getLinks();
+      expect(links1).toBe(links2);
+    });
+  });
+
+  describe('getLink', () => {
+    it('should return undefined for non-existent id', () => {
+      expect(db.getLink('nonexistent')).toBeUndefined();
+    });
+
+    it('should return link data for existing id', () => {
+      db.setLink('c1', 'https://example.com', 'commit');
+      const link = db.getLink('c1');
+      expect(link).toBeDefined();
+      expect(link?.id).toBe('c1');
+    });
+  });
+
+  describe('clear', () => {
+    it('should clear all links', () => {
+      db.setLink('c1', 'https://example.com', 'commit');
+      db.setLink('c2', 'https://example.com', 'commit');
+      clear();
+      expect(db.getLinks().size).toBe(0);
+    });
+  });
+});