Fix misleading icon import documentation

[jmuzina]

Done

Fixes misleading documentation for importing icon mixins. The current documentation directs users to import 3 mixins that do not exist (and would cause build errors if used):

• vf-p-icon-chevron-up
• vf-p-icon-chevron-down
• vf-p-icon-information

This updates the documentation to direct users to import vf-p-icon-chevron and vf-p-icon-info instead.

Fixes #5094, WD-11768

Problem

The icons page uses the same array of icon names to do two different things:

• Generate the icons sections that render the example icons to the page. These are rendered using a macro that uses the values from the array to create the class name for the icon by prepending p-icon--.
• Generate the import instructions. Jinja loops over the elements in the icons array and recreates mixin names by prepending vf-p-icon--.

The code is making the assumption that mixin names and icon class names are exactly the same except for the prefix vf- for mixins and p- for icons, and that each icon has its own dedicated mixin that matches this naming convention. This is mostly true, but is incorrect in three cases:

• vf-p-icon-chevron-up (mixin does not exist; class p-icon--chevron-up is generated by mixin vf-p-icon-chevron) (src)
• vf-p-icon-chevron-down (mixin does not exist; class p-icon--chevron-down is generated by mixin vf-p-icon-chevron) (src)
• vf-p-icon-information (mixin does not exist; class p-icon--information is generated by mixin vf-p-icon-info) (src)

Solutions

Creating the missing mixins; deprecate the old ones (alternate / more permanent solution)

We could create mixins to match the import instructions. These would create duplicate CSS to the current mixins but would fix the incorrect documentation without editing the Jinja template. While this PR does not do this, we should probably change the mixin names at some point in the future (next major version perhaps) in the interest of consistency.

Altering the Jinja template to fix the imports (PR / temporary solution)

A much simpler fix that does not alter our SCSS would be to update the icons Jinja template to fix the import instructions. This makes the Jinja template a bit uglier but has no effect on our users' SCSS (besides pointing them towards the right mixins to import).

Note that my first approach for this solution was simply hard-coding the correct mixins. However this is a bit brittle for my taste so I added some logic to the standard imports loop in Jinja to solve the problem.

QA

• Open demo icons page
• Verify that imports for vf-p-icon-chevron-up, vf-p-icon-chevron-down, and vf-p-icon-information have been removed.
• Verify that imports for vf-p-icon-chevron and vf-p-icon-info have been added.
• Copy-paste the imports block into an IDE with SCSS support in a project that has Vanilla installed. Verify that all mixins are importable and your project builds.

Check if PR is ready for release

If this PR contains Vanilla SCSS code changes, it should contain the following changes to make sure it's ready for the release:

• PR should have one of the following labels to automatically categorise it in release notes:
  • Feature 🎁, Breaking Change 💣, Bug 🐛, Documentation 📝, Maintenance 🔨.
• Vanilla version in package.json should be updated relative to the most recent release, following semver convention:
  • if CSS class names are not changed it can be bugfix relesase (x.x.X)
  • if CSS class names are changed/added/removed it should be minor version (x.X.0)
  • see the wiki for more details
• Any changes to component class names (new patterns, variants, removed or added features) should be listed on the what's new page.

Screenshots

Before:

After:

[webteam-app]

Demo

Jenkins

demos.haus

[bartaz]

As discussed in review before, would it be possible to move the logic from here somewhere to where lists of icons are created, and maybe create a separate list of icon_mixins to iterate through here?

[jmuzina]

@bartaz

Revised. Now I create a list of base_icon_mixin_names (contains the standard, status, & social icons). I didn't combine them all into a single icon_mixins list as the "additional icons" are visually separated from the rest in the import documentation and have a comment separately inserted, so I wanted to keep that in place.

[bartaz]

@jmuzina Would that need updating now that we have chevron-left and chevron-right merged?

[jmuzina]

@jmuzina Would that need updating now that we have chevron-left and chevron-right merged?

Yes, I've just pushed an update to make it compatible with new chevron icons

[bartaz]

Small nit pick on using Jinja comments instead of HTML ones.