Replace Storybook icon docs with icon table (including metadata)

[fredvisser]

Pull Request

🤨 Rationale

We received feedback that it's difficult to find icons by name, and that it's particularly difficult to look up icons using common metaphors. This PR replaces the Storybook autodocs for the Icon story with a generated MDX file that includes icon, icon name, and icon synonyms.

👩‍💻 Implementation

Modified the generate-icon.js source to generate a Storybook docs icons.mdx file (in addition to the Nimble components and the all-icons barrel file).

Alternates considered

Initial put the icons in a IconGallery DocBlock, but it lacked flexibility with long icons names, and including synonyms made it look even worse. (We are still using the IconItem component to format the icon)

🧪 Testing

Manual Storybook review

✅ Checklist

• I have updated the project documentation to reflect my changes or determined no changes are needed.

[fredvisser]

I put the icons.mdx file in the top-level icons directory, instead of a tests directory. Since the whole folder is autogenerated, maybe that's fine?

[rajsite]

The files generated should be treated as source code. I.e. could turn off the generation and check them in. So it's fine to be in icons but should go under icons/tests.

Reason behind the reason is files in any folder named tests/ get excluded from the final package automatically, so lean into that convention.

[rajsite]

Can see Malcolm's script for setting up the directory structure:

nimble/packages/nimble-blazor/build/generate-playwright-version-properties/source/index.js

Line 11 in 4bbe120

const destAbsoluteDir = path.resolve(__dirname, '../dist/');

[jattasNI]

This could be a good topic for our next call with our Chromatic rep. If you agree, it'd be good to save off some links/screenshots/chromatic builds/notes to show why we didn't end up using the icon gallery doc block.

[jattasNI]

I think it would be easier to follow the output document structure if we kept all the MDX stuff together inside the loop and concatenated the parts of the output file all at once after the loop. So something more like this:

let mdxImportStatements = '';
let mdxTable = mdxIconTablePrefix;
for (const key of Object.keys(icons)) {
    // ...
    mdxImportStatements += `import { ${tagName} } from './${fileName}';\n`;
    mdxTable += `| <IconItem name="${fileName}"><${elementName} /></IconItem> | ${iconSynonyms?.tags.join(', ')} |\n`;
    // ...
}

const mdxFileContents = `
${mdxFilePrefix}
${mdxImportStatements}
${mdxTable}`;

[rajsite]

There is a chicken and egg problem here. The components build needs the icons to be generated before typescript runs to create the dist/esm output. The icons need the dist/esm output to generate the story.

Some options:

• Have a separate script that runs after components build but before storybook build to generate the icon story
• Can we just make an icons story in mdx that loops over all the available icons? I'd expect we can do something like that in the React mdx syntax

[rajsite]

Maybe something like this comment could work? storybookjs/storybook#8392 (comment)