feat: Add packet diagram

[sidharthv96]

📑 Summary

Adds packet diagram
Resolves #948

TODO:

• Add title support
• Add accessibility support
• Fix theming
• Add docs

📏 Design Decisions

The syntax was adapted from the existing one at http://blockdiag.com/en/nwdiag/packetdiag-examples.html#structure-of-tcp-header

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🔖 targeted next branch

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	5cc20b5
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/65b013a3a144c700088dffd7
😎 Deploy Preview	https://deploy-preview-4839--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[codecov]

Codecov Report

Attention: 18 lines in your changes are missing coverage. Please review.

Comparison is base (ce9a9db) 44.50% compared to head (5cc20b5) 44.38%.

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #4839      +/-   ##
==========================================
- Coverage   44.50%   44.38%   -0.13%     
==========================================
  Files          25       25              
  Lines        5206     5227      +21     
  Branches       25       25              
==========================================
+ Hits         2317     2320       +3     
- Misses       2888     2906      +18     
  Partials        1        1              

Flag	Coverage Δ
unit	44.38% <25.00%> (-0.13%)	⬇️

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

Files	Coverage Δ
packages/mermaid/src/defaultConfig.ts	45.65% <100.00%> (+0.59%)	⬆️
packages/mermaid/src/themes/theme-dark.js	2.74% <10.00%> (-0.07%)	⬇️
packages/mermaid/src/themes/theme-forest.js	3.81% <18.18%> (-0.10%)	⬇️

[Yokozuna59]

Sorry for making all comments in this review request changes. Some of them are just comments, but the review got so big that I couldn't separate them.

There's two files I haven't fully review db.ts and renderer.ts. I'll review them when I've time.

And please mock the packet renderer in __mocks__ and here packages/mermaid/src/mermaidAPI.spec.ts.

[sidharthv96]

Thanks for the detailed review @Yokozuna59 !
This was like a first-draft with the new system, and actually, my first new diagram in mermaid :)
You've made some excellent points, will fix these :)

[Yokozuna59]

It would be better if add another image for the diagram with title in PR description.

I'm not sure about this, but shouldn't the title be at the top of the diagram, or it expected to be at the bottom?

And two more things:

And please mock the packet renderer in __mocks__ and here packages/mermaid/src/mermaidAPI.spec.ts.

#4839 (review)

And maybe add some test cases in packages/parser/tests for packet diagram.

[sidharthv96]

And please mock the packet renderer in mocks and here packages/mermaid/src/mermaidAPI.spec.ts.

@Yokozuna59 @aloisklink @nirname Are the files except d3.ts in __mocks__ actually used?
I removed all of them in 96ae4a5, and nothing broke locally, or in CI.
Maybe a vitest update made them redundant?

[aloisklink]

Are the files except d3.ts in __mocks__ actually used?

Looking at #3808, I believe all of these diagram mocks are only being used for the following test:

mermaid/packages/mermaid/src/mermaidAPI.spec.ts

Lines 698 to 746 in d7f59c1

	describe('render', () => {
	// These are more like integration tests right now because nothing is mocked.
	// But it is faster that a cypress test and there's no real reason to actually evaluate an image pixel by pixel.
	// render(id, text, cb?, svgContainingElement?)
	// Test all diagram types. Note that old flowchart 'graph' type will invoke the flowRenderer-v2. (See the flowchart v2 detector.)
	// We have to have both the specific textDiagramType and the expected type name because the expected type may be slightly different than was is put in the diagram text (ex: in -v2 diagrams)
	const diagramTypesAndExpectations = [
	{ textDiagramType: 'C4Context', expectedType: 'c4' },
	{ textDiagramType: 'classDiagram', expectedType: 'classDiagram' },
	{ textDiagramType: 'classDiagram-v2', expectedType: 'classDiagram' },
	{ textDiagramType: 'erDiagram', expectedType: 'er' },
	{ textDiagramType: 'graph', expectedType: 'flowchart-v2' },
	{ textDiagramType: 'flowchart', expectedType: 'flowchart-v2' },
	{ textDiagramType: 'gitGraph', expectedType: 'gitGraph' },
	{ textDiagramType: 'gantt', expectedType: 'gantt' },
	{ textDiagramType: 'journey', expectedType: 'journey' },
	{ textDiagramType: 'pie', expectedType: 'pie' },
	{ textDiagramType: 'requirementDiagram', expectedType: 'requirement' },
	{ textDiagramType: 'sequenceDiagram', expectedType: 'sequence' },
	{ textDiagramType: 'stateDiagram-v2', expectedType: 'stateDiagram' },
	];
	describe('accessibility', () => {
	const id = 'mermaid-fauxId';
	const a11yTitle = 'a11y title';
	const a11yDescr = 'a11y description';
	diagramTypesAndExpectations.forEach((testedDiagram) => {
	describe(`${testedDiagram.textDiagramType}`, () => {
	const diagramType = testedDiagram.textDiagramType;
	const diagramText = `${diagramType}\n accTitle: ${a11yTitle}\n accDescr: ${a11yDescr}\n`;
	const expectedDiagramType = testedDiagram.expectedType;
	it('should set aria-roledscription to the diagram type AND should call addSVGa11yTitleDescription', async () => {
	const a11yDiagramInfo_spy = vi.spyOn(accessibility, 'setA11yDiagramInfo');
	const a11yTitleDesc_spy = vi.spyOn(accessibility, 'addSVGa11yTitleDescription');
	await mermaidAPI.render(id, diagramText);
	expect(a11yDiagramInfo_spy).toHaveBeenCalledWith(
	expect.anything(),
	expectedDiagramType
	);
	expect(a11yTitleDesc_spy).toHaveBeenCalled();
	});
	});
	});
	});
	});

But it sounds like the mocks are mainly there to force diagram.draw() to return an empty string instead of undefined, but the diagram.draw() function is only supposed to return undefined anyway, so it does look like this mock files aren't needed anymore:

mermaid/packages/mermaid/src/diagram-api/types.ts

Lines 91 to 104 in d7f59c1

	/**
	* Type for function draws diagram in the tag with id: id based on the graph definition in text.
	*
	* @param text - The text of the diagram.
	* @param id - The id of the diagram which will be used as a DOM element id.
	* @param version - MermaidJS version from package.json.
	* @param diagramObject - A standard diagram containing the DB and the text and type etc of the diagram.
	*/
	export type DrawDefinition = (
	text: string,
	id: string,
	version: string,
	diagramObject: Diagram
	) => void | Promise<void>;

It seems safe to me, but if you think it's high risk, you could make the change in a separate PR so we could more easily revert it?

[Yokozuna59]

LGTM, thanks!

Just a minor question: when will we drop v10? This is the first diagram; we only have a language parser for it, so users can't use it (unless they use the preview link).

[sidharthv96]

@Yokozuna59 we're planning to release v11 soon.

The plan is to merge your Pie PR first, update this one as necessary, then start the release process (testing, docs, etc).