Refactor fontawesome icon usage. #6282

saurabhg772244 · 2025-02-14T11:32:31Z

📑 Summary

Registered icons are now embedded as SVG otherwise the icon will still be embedded as  tag
This will save clients using mermaid from having to include fontawesome in their project.
Updated styles to set proper fill color and position for icons

See mermaid-js/mermaid-cli#474

📏 Design Decisions

When text contains a FontAwesome icon reference:

Check if the icon is registered in the mermaid configuration.
If the icon is available in registered icons, replace with stringified SVG
If the icon is not found, return  tag with icon class

Update to styles.

We had a style defined that adds fill to all path elements inside node class. Now we are overriding this style to have fill: currentColor also reverting stroke and stroke-width to default

📋 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.
🦋 If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

…rk with i tag

changeset-bot · 2025-02-14T11:32:35Z

🦋 Changeset detected

Latest commit: 2fb7bc2

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

This PR includes changesets to release 1 package

Name	Type
mermaid	Patch

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

netlify · 2025-02-14T11:33:15Z

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	`2fb7bc2`
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/67b8c2e2cfcf640008246054
😎 Deploy Preview	https://deploy-preview-6282--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.

pkg-pr-new · 2025-02-14T11:33:57Z

Open in Stackblitz

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

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

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

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

commit: 2fb7bc2

saurabhg772244 · 2025-02-14T11:34:20Z

Note: Some e2e tests are failing as they were using fontawesome icon in them but the test file was not importing fontawesome cdn

codecov · 2025-02-14T11:35:44Z

Codecov Report

Attention: Patch coverage is 0% with 151 lines in your changes missing coverage. Please review.

Project coverage is 4.45%. Comparing base (0518e9c) to head (2fb7bc2).
Report is 15 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/mermaid/src/rendering-util/createText.ts	0.00%	32 Missing ⚠️
packages/mermaid/src/dagre-wrapper/nodes.js	0.00%	15 Missing ⚠️
packages/mermaid/src/diagrams/block/styles.ts	0.00%	14 Missing ⚠️
packages/mermaid/src/diagrams/class/styles.js	0.00%	14 Missing ⚠️
packages/mermaid/src/diagrams/flowchart/styles.ts	0.00%	14 Missing ⚠️
packages/mermaid/src/diagrams/kanban/styles.ts	0.00%	14 Missing ⚠️
...ckages/mermaid/src/diagrams/user-journey/styles.js	0.00%	14 Missing ⚠️
packages/mermaid/src/dagre-wrapper/clusters.js	0.00%	10 Missing ⚠️
packages/mermaid/src/dagre-wrapper/edges.js	0.00%	6 Missing ⚠️
packages/mermaid/src/dagre-wrapper/shapes/util.js	0.00%	6 Missing ⚠️
... and 3 more

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #6282      +/-   ##
==========================================
- Coverage     4.46%   4.45%   -0.02%     
==========================================
  Files          384     385       +1     
  Lines        54262   54384     +122     
  Branches       623     598      -25     
==========================================
- Hits          2425    2423       -2     
- Misses       51837   51961     +124

Flag	Coverage Δ
unit	`4.45% <0.00%> (-0.02%)`	⬇️

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

Files with missing lines	Coverage Δ
packages/mermaid/src/dagre-wrapper/createLabel.js	`0.00% <0.00%> (ø)`
packages/mermaid/src/dagre-wrapper/index.js	`0.00% <0.00%> (ø)`
packages/mermaid/src/dagre-wrapper/edges.js	`0.00% <0.00%> (ø)`
packages/mermaid/src/dagre-wrapper/shapes/util.js	`0.00% <0.00%> (ø)`
packages/mermaid/src/rendering-util/icons.ts	`0.00% <0.00%> (ø)`
packages/mermaid/src/dagre-wrapper/clusters.js	`0.00% <0.00%> (ø)`
packages/mermaid/src/diagrams/block/styles.ts	`0.00% <0.00%> (ø)`
packages/mermaid/src/diagrams/class/styles.js	`0.00% <0.00%> (ø)`
packages/mermaid/src/diagrams/flowchart/styles.ts	`0.00% <0.00%> (ø)`
packages/mermaid/src/diagrams/kanban/styles.ts	`0.00% <0.00%> (ø)`
... and 3 more

... and 2 files with indirect coverage changes

sidharthv96 · 2025-02-15T16:04:05Z

This increases the size of our bundle significantly!

…saurabh/refactor-fontawesome-icon-usage

argos-ci · 2025-02-19T06:13:06Z

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

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	14 changed, 483 added, 473 removed, 2 failures	Feb 21, 2025, 6:26 PM

aloisklink

Awesome work! This will make me very happy in the mermaid-cli project too!

As far as I can tell, your code and approach looks great to me! But I think we need some work before we can merge this.

I think we need to do the following before we merge this PR:

E2E tests! Can you write some visual regression tests that work before and after this feature so we can see if there are any visual anomalies? You might want to try various themes too, to make sure the icon colors are still the same as they are currently.
Documentation updates:
- I think you forgot to update your PR description and changeset for a81c318
- You're not updating mindmaps in this PR. I think this is fine, as long as it's in the PR description, changeset, and docs.
- Please update the documentation for FontAwesome in https://mermaid.js.org too

aloisklink · 2025-02-20T11:28:54Z

packages/mermaid/src/rendering-util/createText.ts

+  const iconRegex = /(fas|fab|far|fa|fal|fak|fad):fa-([a-z-]+)/g;
+  const classNameMap = {
+    fas: 'fa-solid',
+    fab: 'fa-brands',
+    far: 'fa-regular',
+    fa: 'fa',
+    fal: 'fa-light',
+    fad: 'fa-duotone',
+    fak: 'fak',
+  } as const;
+  const matches = [...text.matchAll(iconRegex)];
+  if (matches.length === 0) {
+    return text;
+  }
+
+  let newText = text;
+
+  for (const match of matches) {
+    const [fullMatch, prefix, iconName] = match;
+    const className = classNameMap[prefix];
+    const registeredIconName = `${prefix}:${iconName}`;
+
+    try {
+      const isFreeIcon = await isIconAvailable(registeredIconName);
+      if (!isFreeIcon) {
+        log.warn(`Icon ${registeredIconName} is a pro icon.`);
+        newText = newText.replace(fullMatch, `<i class='${className} fa-${iconName}'></i>`);
+        continue;
+      }
+      const faIcon = await getIconSVG(registeredIconName, undefined, { class: 'label-icon' });
+      if (faIcon) {
+        newText = newText.replace(fullMatch, faIcon);
+      }
+    } catch (error) {
+      log.error(`Error processing ${registeredIconName}:`, error);
+    }
+  }
+  return newText;


issue(blocking): I'm not sure why we still need the free/pro difference, or the different class names. Can we change this function to output the exact same thing if users haven't set an icon pack?

suggestion: Maybe something like the following (we should probably also update the function TSDoc comment too):

Suggested change

const iconRegex = /(fas|fab|far|fa|fal|fak|fad):fa-([a-z-]+)/g;

const classNameMap = {

fas: 'fa-solid',

fab: 'fa-brands',

far: 'fa-regular',

fa: 'fa',

fal: 'fa-light',

fad: 'fa-duotone',

fak: 'fak',

} as const;

const matches = [...text.matchAll(iconRegex)];

if (matches.length === 0) {

return text;

}

let newText = text;

for (const match of matches) {

const [fullMatch, prefix, iconName] = match;

const className = classNameMap[prefix];

const registeredIconName = `${prefix}:${iconName}`;

try {

const isFreeIcon = await isIconAvailable(registeredIconName);

if (!isFreeIcon) {

log.warn(`Icon ${registeredIconName} is a pro icon.`);

newText = newText.replace(fullMatch, ``);

continue;

}

const faIcon = await getIconSVG(registeredIconName, undefined, { class: 'label-icon' });

if (faIcon) {

newText = newText.replace(fullMatch, faIcon);

}

} catch (error) {

log.error(`Error processing ${registeredIconName}:`, error);

}

}

return newText;

// The letters 'bklrs' stand for possible endings of the fontawesome prefix (e.g. 'fab' for brands, 'fak' for fa-kit) // cspell: disable-line

return text.replace(

/(fa[bklrs]?):fa-([\w-]+)/g, // cspell: disable-line

(fullMatch, prefix, iconName) => {

const registeredIconName = `${prefix}:${iconName}`;

if (await isIconAvailable(registeredIconName)) {

return await getIconSVG(registeredIconName, undefined, { class: 'label-icon' });

} else {

// fall back to FontAwesome CSS

return ``;

}

},

);

I will update regex but as of the text.replace() does not take async call back so we will have to update with other way.

Ah, that makes sense! Good catch.

The next question is, can we write it in such a way that uses Promise.all() to download these icon packets in parallel? (although maybe it's overkill to write the code like that, since it will only result in a performance improvement if you're using multiple icon packs in the same node label).

Fixed in 2fb7bc2

aloisklink · 2025-02-20T11:30:19Z

packages/mermaid/src/rendering-util/createText.spec.ts

-    const expected =
-      "This is an icon: <i class='fa fa-user'></i> and <i class='fab fa-github'></i>";
+    const output = await replaceIconSubstring(input);
+    const expected = `This is an icon: <i class='fa fa-user'></i> and <i class='fa-brands fa-github'></i>`;


question(blocking): Why has the class changed from fab to fa-brands and is this a breaking change? Do we need to put this info in the PR description and changeset entry?

Fixed in 16573d9

aloisklink · 2025-02-20T11:35:43Z

pnpm-lock.yaml

suggestion(non-blocking but recommended): I think you can revert these changes, since it looks like these pnpm-lock.yaml are not needed for your PR, but will just increase the risk of merge conflicts by a lot.

Updated in 83a6e69

packages/mermaid/src/rendering-util/createText.ts

…saurabh/refactor-fontawesome-icon-usage

…mermaid:mermaid-js/mermaid into saurabh/refactor-fontawesome-icon-usage

saurabhg772244 added 3 commits February 14, 2025 16:32

embed free font awesome svg instead of i tag. pro icons will still wo…

302ba72

…rk with i tag

update styles so that proper fill is applied to icons

33e5694

added changeset

d63d3bf

saurabhg772244 requested review from knsv, sidharthv96 and aloisklink February 14, 2025 11:32

saurabhg772244 added 2 commits February 18, 2025 19:53

removed font awesome packages and used registered icons instead

a81c318

Merge branch 'develop' of https://github.com/mermaid-js/mermaid into …

8857e77

…saurabh/refactor-fontawesome-icon-usage

aloisklink requested changes Feb 20, 2025

View reviewed changes

Updated docs, added visual regression test

16573d9

github-advanced-security bot found potential problems Feb 21, 2025

View reviewed changes

packages/mermaid/src/rendering-util/createText.ts Fixed Show fixed Hide fixed

saurabhg772244 added 4 commits February 21, 2025 23:00

Merge branch 'develop' of github.com-mermaid:mermaid-js/mermaid into …

6a81a90

…saurabh/refactor-fontawesome-icon-usage

Merge branch 'saurabh/refactor-fontawesome-icon-usage' of github.com-…

a89e001

…mermaid:mermaid-js/mermaid into saurabh/refactor-fontawesome-icon-usage

fix lock file

83a6e69

fix pnpm lock and use promise.all to speed up icon replacement

2fb7bc2

saurabhg772244 requested a review from aloisklink February 21, 2025 18:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor fontawesome icon usage. #6282

Refactor fontawesome icon usage. #6282

saurabhg772244 commented Feb 14, 2025 •

edited

Loading

changeset-bot bot commented Feb 14, 2025 •

edited

Loading

netlify bot commented Feb 14, 2025 •

edited

Loading

pkg-pr-new bot commented Feb 14, 2025 •

edited

Loading

saurabhg772244 commented Feb 14, 2025

codecov bot commented Feb 14, 2025 •

edited

Loading

sidharthv96 commented Feb 15, 2025

argos-ci bot commented Feb 19, 2025 •

edited

Loading

aloisklink left a comment •

edited by saurabhg772244

Loading

aloisklink Feb 20, 2025

saurabhg772244 Feb 21, 2025

aloisklink Feb 21, 2025

saurabhg772244 Feb 21, 2025

aloisklink Feb 20, 2025

saurabhg772244 Feb 21, 2025

aloisklink Feb 20, 2025

saurabhg772244 Feb 21, 2025

Refactor fontawesome icon usage. #6282

Are you sure you want to change the base?

Refactor fontawesome icon usage. #6282

Conversation

saurabhg772244 commented Feb 14, 2025 • edited Loading

📑 Summary

📏 Design Decisions

When text contains a FontAwesome icon reference:

Update to styles.

📋 Tasks

changeset-bot bot commented Feb 14, 2025 • edited Loading

🦋 Changeset detected

netlify bot commented Feb 14, 2025 • edited Loading

✅ Deploy Preview for mermaid-js ready!

pkg-pr-new bot commented Feb 14, 2025 • edited Loading

saurabhg772244 commented Feb 14, 2025

codecov bot commented Feb 14, 2025 • edited Loading

Codecov Report

sidharthv96 commented Feb 15, 2025

argos-ci bot commented Feb 19, 2025 • edited Loading

aloisklink left a comment • edited by saurabhg772244 Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

saurabhg772244 commented Feb 14, 2025 •

edited

Loading

changeset-bot bot commented Feb 14, 2025 •

edited

Loading

netlify bot commented Feb 14, 2025 •

edited

Loading

pkg-pr-new bot commented Feb 14, 2025 •

edited

Loading

codecov bot commented Feb 14, 2025 •

edited

Loading

argos-ci bot commented Feb 19, 2025 •

edited

Loading

aloisklink left a comment •

edited by saurabhg772244

Loading