standardized pie definitions

[Yokozuna59]

📑 Summary

Brief description about the content of your PR.

Partial Resolves #4499

📏 Design Decisions

Discussed inside #4499

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added unit/e2e tests (if appropriate)
• 📓 have added documentation (if appropriate)
• 🔖 targeted develop branch

[sidharthv96]

LGTM.

In future PRs, please try to do the .js -> .ts conversion (rename) in one commit (with git commit -n to skip pre commit hooks), and the actual code changes in another, which will help git keep track of things in a better way.

[Yokozuna59]

In future PRs, please try to do the .js -> .ts conversion (rename) in one commit (with git commit -n to skip pre commit hooks), and the actual code changes in another, which will help git keep track of things in a better way.

Well do.

---

Please replay on the discussed stuff in #4499 (comment) if you have time. And I'm planning to update pie docs, should it be in this pr or another one?

[codecov-commenter]

Codecov Report

Merging #4501 (e7ee3eb) into develop (b85c011) will increase coverage by 0.05%.
The diff coverage is 96.87%.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #4501      +/-   ##
===========================================
+ Coverage    77.04%   77.09%   +0.05%     
===========================================
  Files          144      144              
  Lines        14565    14563       -2     
  Branches       586      590       +4     
===========================================
+ Hits         11221    11227       +6     
+ Misses        3233     3224       -9     
- Partials       111      112       +1     

Flag	Coverage Δ
e2e	83.97% <97.64%> (+0.07%)	⬆️
unit	45.36% <85.71%> (+0.01%)	⬆️

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

Files Changed	Coverage Δ
packages/mermaid/src/diagrams/pie/pieDiagram.ts	100.00% <ø> (ø)
packages/mermaid/src/utils.ts	61.73% <85.71%> (+0.12%)	⬆️
packages/mermaid/src/diagrams/pie/pieDb.ts	96.15% <96.15%> (ø)
packages/mermaid/src/diagrams/pie/pieRenderer.ts	98.18% <98.18%> (ø)
packages/mermaid/src/defaultConfig.ts	47.21% <100.00%> (+0.39%)	⬆️
...s/mermaid/src/diagram-api/diagram-orchestration.ts	39.53% <100.00%> (ø)
packages/mermaid/src/diagrams/pie/pieDetector.ts	90.90% <100.00%> (-0.76%)	⬇️
packages/mermaid/src/diagrams/pie/pieStyles.ts	100.00% <100.00%> (ø)

[Yokozuna59]

@sidharthv96 What happened? Why workflows aren't running?

[sidharthv96]

I'm not sure, maybe GH issue.

[sidharthv96]

It's because you have conflicts. Sync with develop and push.
I was on mobile earlier, didn't notice the conflict.

[aloisklink]

Everything seems to good to me, except changing pieDb.ts to have it's own config that's separate to the main config object.

My gut feeling is that this should be in a separate PR, since it's a pretty significant change, and I'm not entirely convinced it's a good idea. See my comments below:

[aloisklink]

Ideally, we should be loading these values from the JSON Schema, if they exist.

That way, all of these default values with be visible in the docs, like https://mermaid.js.org/config/schema-docs/config.html#definitions-group-piediagramconfig

Suggested change

	export const DEFAULT_PIE_CONFIG: Required<PieDiagramConfig> = {
	useMaxWidth: true,
	useWidth: 984,
	textPosition: 0.75,
	} as const;
	import DEFAULT_CONFIG from '../../defaultConfig.js';
	export const DEFAULT_PIE_CONFIG: Required<PieDiagramConfig> = DEFAULT_CONFIG.pie;

[Yokozuna59]

I agree with you that we need load values from JSON Schema, but it's not fully typed and what to do with values that they're undefined? Using Required here would throw errors.

And we need to change the default config to RequiredDeep<MermaidConfig>.

[aloisklink]

but it's not fully typed and what to do with values that they're undefined? Using Required here would throw errors.

You're right. Ideally we also need to fix the defaulConfig.ts types first, but that'd need to wait until Mermaid v11 (see https://github.com/orgs/mermaid-js/discussions/4710#discussioncomment-6709156).

Is it worth doing something like the following instead? Maybe it's overkill since we'll remove most of it once we get the types working, though 🤷. Up to you.

import DEFAULT_CONFIG from '../../defaultConfig.js';

function isValidDefaultPieConfig(x: PieDiagramConfig): x is  Required<PieDiagramConfig> {
  return x.useMaxWidth && x.useWidth && x.textPosition;
};

export const DEFAULT_PIE_CONFIG: Required<PieDiagramConfig> = (() => {
  const defaultConfig = {useWidth: 984, ...DEFAULT_CONFIG.pie};
  if (!isValidDefaultPieConfig(defaultConfig)) {
    throw new Error("DEFAULT_PIE_CONFIG is missing required entries: ", defaultConfig);
  }
  return defaultConfig;
});

And we need to change the default config to RequiredDeep<MermaidConfig>.

This works for Pie diagrams, but it won't work for all diagram configs, because some values actually can be undefined and are undefined be default, see #4501 (comment).

[Yokozuna59]

Is it worth doing something like the following instead? Maybe it's overkill since we'll remove most of it once we get the types working, though shrug. Up to you.

I think it's kinda overengineering to do so.

[aloisklink]

What about this, we modify

mermaid/packages/mermaid/src/defaultConfig.ts

Lines 233 to 236 in 99978da

	pie: {
	...defaultConfigJson.pie,
	useWidth: undefined,
	},

to have:

  pie: {
    ...defaultConfigJson.pie,
    useWidth: true, // this line probably can be removed, because `true` is the default value
    useMaxWidth: 984, // should this be 1200 instead?
  },

Then, in this file, we just tell TypeScript this is a Required<PieDiagramConfig> object, e.g. something like:

// @ts-expect-error: This is valid, since the `defaultConfig` defined in packages/mermaid/src/defaultConfig.ts has no `undefined` values
const getConfig = (): Required<PieDiagramConfig> => commonGetConfig().pie;

It's not perfect, but you're right, it's probably over-engineering to do anything more.

[Yokozuna59]

Note: you also flipped default values of useWidth and useMaxWidth in example :)

---

  pie: {
    useWidth: 984, // should this be 1200 instead?
  },

As I said before, useWidth is kinda vogue, the width in pie depends on the parent element, e.g., in cypress/integration/rendering/pie.spec.ts the width is 984:

mermaid/cypress/integration/rendering/pie.spec.js

Lines 54 to 57 in 3d11781

	const style = svg.attr('style');
	expect(style).to.match(/^max-width: [\d.]+px;$/);
	const maxWidthValue = parseFloat(style.match(/[\d.]+/g).join(''));
	expect(maxWidthValue).to.eq(984);

But in demos/pie.html, the parent element width here is 1904.

But the previous (apparently) default value is 1200:

mermaid/packages/mermaid/src/diagrams/pie/pieRenderer.js

Lines 42 to 44 in 3d11781

	if (width === undefined) {
	width = 1200;
	}

It was discussed here and here.

---

Then, in this file, we just tell TypeScript this is a Required<PieDiagramConfig> object, e.g. something like:

// @ts-expect-error: This is valid, since the `defaultConfig` defined in packages/mermaid/src/defaultConfig.ts has no `undefined` values
const getConfig = (): Required<PieDiagramConfig> => commonGetConfig().pie;

It's not perfect, but you're right, it's probably over-engineering to do anything more.

Thanks! I'll do as you suggested.

[Yokozuna59]

But I'm not sure why we're returning config from current global config.

[Yokozuna59]

Since the schema import expect errors:

mermaid/packages/mermaid/src/defaultConfig.ts

Lines 8 to 9 in defe406

	// @ts-expect-error This file is automatically generated via a custom Vite plugin
	import defaultConfigJson from './schemas/config.schema.yaml?only-defaults=true';

We can change the defaultConfig type into RequiredDeep without errors (although other values are actually undefined) defe406

[aloisklink]

But I'm not sure why we're returning config from current global config.

In the packages/mermaid/src/config.ts file, the getSiteConfig() returns:

• The defaultConfig, merged with
• the global site config (e.g. set by mermaid.initialize())

In the packages/mermaid/src/config.ts file, the getConfig() returns the diagram specific config, e.g.:

• The defaultConfig, merged with
• the global site config (e.g. set by mermaid.initialize())
• the diagram specific config (e.g. set by directives like %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%

I know it's a bit confusing, but even though getConfig() in packages/mermaid/src/config.ts is globally available, because it's reset in-between diagram renders, and Mermaid renders each diagram sequentially, it actually contains the diagram-specific config that is set in %%{init: directives (and maybe YAML directives once we get it set up).

It's definitely worth changing in a future PR, though, since I know the behavior is pretty weird, and it causes bugs like #4345

---

We can change the defaultConfig type into RequiredDeep without errors

It's probably best not to do that, since it's not actually correct, since other variables are undefined.

Maybe something like MermaidConfig & {pie: Required<MermaidConfig["pie"]>} could work, if we know that all values in the pie chart are defined by default?

[Yokozuna59]

@aloisklink if we need to preform a BREAKING CHANGE on config then we might just point merge distinction to next, not merging this PR would lead to delaying the addition of pie langium parser (#4727 is almost done).

Although pointing it into next would mean more conflict when merging later on.

[aloisklink]

I'm going to mark this PR as approved, since it's blocking you on #4727, and although I still don't like the about giving pieDb.ts it's own config in this PR, I think that the overall PR is great :)

Before merging, if you have time, I'd still prefer to have the DEFAULT_PIE_CONFIG and getConfig() function in pieDb.ts use the old way of doing things (e.g. putting the default config in packages/mermaid/src/defaultConfig.ts and having the pieDb's getConfig() function calling the getConfig() function in develop/packages/mermaid/src/config.ts), although we would have to add a // @ts-expect-error comment to make TypeScript happy. In a future PR, we could then update pieDb.ts to have it's own config.
See https://github.com/mermaid-js/mermaid/pull/4501/files#r1296277525

---

@aloisklink if we need to preform a BREAKING CHANGE on config

I think we can get away without doing a BREAKING CHANGE in the config! Your idea on doing RequiredDeep<MermaidConfig> has me convinced, we just need to make sure that our defaultConfig has no undefined values. See discussion in https://github.com/orgs/mermaid-js/discussions/4710#discussioncomment-6732808.

Giving the pie chart it's own config will also not be a breaking change, since it would be internal to Mermaid.

[aloisklink]

What about this, we modify

mermaid/packages/mermaid/src/defaultConfig.ts

Lines 233 to 236 in 99978da

	pie: {
	...defaultConfigJson.pie,
	useWidth: undefined,
	},

to have:

  pie: {
    ...defaultConfigJson.pie,
    useWidth: true, // this line probably can be removed, because `true` is the default value
    useMaxWidth: 984, // should this be 1200 instead?
  },

Then, in this file, we just tell TypeScript this is a Required<PieDiagramConfig> object, e.g. something like:

// @ts-expect-error: This is valid, since the `defaultConfig` defined in packages/mermaid/src/defaultConfig.ts has no `undefined` values
const getConfig = (): Required<PieDiagramConfig> => commonGetConfig().pie;

It's not perfect, but you're right, it's probably over-engineering to do anything more.

[Yokozuna59]

I'm going to mark this PR as approved, since it's blocking you on #4727

Just to clarify, we don't actually need it in #4727; it will be in a separate PR I'll be working on it after it's merged.

Before merging, if you have time, I'd still prefer to have the DEFAULT_PIE_CONFIG and getConfig() function in pieDb.ts use the old way of doing things (e.g. putting the default config in packages/mermaid/src/defaultConfig.ts and having the pieDb's getConfig() function calling the getConfig() function in develop/packages/mermaid/src/config.ts)

Sure!

[nirname]

Why do we switch to exact width and to this strange value? I needed exact width only once, when I failed to calculate this properly...

[Yokozuna59]

It's not strange, it's the default one expected in cypress.

The width defined in pie is possibly undefined, so we use this value if it doesn't exists.

See #4501 (comment)

[sidharthv96]

@Yokozuna59 please don't self-resolve comments like this one. Resolving this comment is fine, as you did an action that the reviewer was asking, and it was straightforward.

In this case, the comment was a question, which you answered correctly. But you don't know if @nirname has seen the answer, or has any follow-up questions. The only way for @nirname to see your answer would be to click on each resolved comment to see which one it was. As you know, some PRs have many comments, and it would not be practical to go through each. :)

Leaving the comments unresolved makes the life of the reviewer easy. In case comments are left unresolved for a long time, other maintainers will handle it (By resolving it, or merging without resolving).

[Yokozuna59]

@sidharthv96 Okay.

GitHub sends emails to subscribers when new actions occurs, so they'll be notified by an email.
And GitHub would also mark the PR/issue with blue circle showing that it has new actions.

:)

[sidharthv96]

GitHub sends emails to subscribers when new actions occurs, so they'll be notified by an email.

Yeah, and in active PRs, there are many comments and emails going out. And Gmail sometimes collapses the thread. So I, personally, rarely check email for PR comments.

And GitHub would also mark the PR/issue with blue circle showing that it has new actions.

But we won't know which comments were resolved recently when opening the PR. Everything would just be resolved and collapsed.