chore(storybook): add migrated components list #3745

marissahuysentruyt · 2025-05-15T21:38:36Z

Description

DISCLAIMER: MOST CODE GENERATED BY CURSOR

adds a MigratedComponentsList() block to ComponentDetails.jsx. That block gets used in the S2 Migration guide MDX file
adds a migrated-component-scanner.js task to scan the components directory and generate a list of migrated components based on their status (status: type: "migrated")
adds a migrated-components.json file to the .storybook/data directory
updates the project.json script to include a new report target that runs migrated-component-scanner.js so that it builds and captures the migration status
captures the component title (so there is proper capitalization) and generates the url fragment so that the list of components links back to their corresponding docs pages

Jira/Specs

CSS-1259

How and where has this been tested?

Please tag yourself on the tests you've marked complete to confirm the tests have been run by someone other than the author.

Validation steps

Pull down the branch to run locally or visit the deploy preview. [@rise-erpelding]
yarn nx run .storybook:report should run the migrated-component-status.js task. You should get some feedback like this in the terminal: [@rise-erpelding]

Don't be alarmed if you see changes in the migrated-components.json file- new components merged so that's a good sign that this script is working!

The branch should run as normal. [@rise-erpelding]
Verify that each of the links on the migration guide page correctly navigates to the docs page of the component. [@rise-erpelding]

Regression testing

Validate:

The documentation pages for at least two other components are still loading, including:

The pages render correctly, are accessible, and are responsive.

If components have been modified, VRTs have been run on this branch:

VRTs have been run and looked at.
Any VRT changes have been accepted (by reviewer and/or PR author), or there are no changes.

Screenshots

Screen.Recording.2025-07-25.at.12.41.55.PM.mov

To-do list

I have read the contribution guidelines.
If my change impacts documentation, I have updated the documentation accordingly.
✨ This pull request is ready to merge. ✨

changeset-bot · 2025-05-15T21:38:41Z

⚠️ No Changeset found

Latest commit: 7fa91f2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2025-05-15T21:48:42Z

🚀 Deployed on https://pr-3745--spectrum-css.netlify.app

github-actions · 2025-05-15T21:57:33Z

File metrics

Summary

Total size: 1.43 MB^*

🎉 No changes detected in any packages

* Size is the sum of all main files for packages in the library.
* An ASCII character in UTF-8 is 8 bits or 1 byte.

castastrophe · 2025-06-20T14:08:00Z

.storybook/guides/s2_migration.mdx

+
+This is a list of all components that have been fully migrated to Spectrum 2.
+
+<MigratedComponentsList />


castastrophe · 2025-06-20T14:09:33Z

package.json

@@ -15,7 +15,7 @@
 	"scripts": {
 		"build": "yarn builder tag:component,ui-icons",
 		"build:docs": "yarn build:preview --output-dir ../dist/",
-		"build:preview": "yarn report && nx build storybook",
+		"build:preview": "yarn report && yarn component:data && nx build storybook",


I wonder if there's a way to include this task as a storybook report. In the storybook project.json, if we use this script as the report, would it get run automatically with the others? What's the downside of doing that, maybe it's run more than it needs to be?

I'm picturing you could run it like nx report storybook

Left you a comment! #3745 (comment)

github-actions · 2025-07-10T15:25:54Z

📚 Branch preview

PR #3745 has been deployed to Azure Blob Storage: https://spectrumcss.z13.web.core.windows.net/pr-3745/index.html.

marissahuysentruyt · 2025-07-25T16:25:16Z

.storybook/project.json

+		"report": {
+			"executor": "nx:run-commands",
+			"options": {
+				"commands": [
+					"node tasks/migrated-component-scanner.js --output=.storybook/data/migrated-components.json"
+				],
+				"cwd": "{workspaceRoot}"
+			}


@castastrophe I added a report target to the storybook/project.json. Is that sort of what you were going for?

Right now, we can trigger this manually with yarn nx run .storybook:report

According to Cursor, yes it could run more than it needs to.

you can add it as a dependency for other targets (like "build" or "start"), so it runs automatically before those.

Example, to run it before build:

"build": { ... "dependsOn": ["report", ...] }

Downsides / Considerations
Performance: If you add "report" as a dependency for "build" or "start", it will run every time you build or start Storybook, even if the component list hasn't changed. This could be unnecessary if the migration status doesn't change often.
Redundancy: If the script is slow or does heavy file I/O, it could slow down your workflow.

Best Practice: Only add "report" as a dependency if you want the report to always be up-to-date for every build. Otherwise, run it manually or as part of CI.

Does that mean that we'd have to run yarn nx run .storybook:report in order to get a component added/removed from the migrated-components.json? I noticed I did have a difficult time trying to remove accordion from the json file after I removed the migrated status/tags but see that running report works (guess I should have read the validation instructions first 😏). I can see us easily forgetting to update the migrated list once we merge a migration if it's not a part of our regular workflows.

Right now, yes. We would have to run this manually. I was also curious about this report should be incorporated.

We could add it as a dependency to the build task I think, but that would/could make it run more. I'm thinking maybe we err on the side of running as part of our CI workflow when we try to merge to spectrum-two. I wanted to explore if we can make it a GH action that would commit the changes if there are any?

marissahuysentruyt · 2025-07-25T16:32:39Z

.storybook/data/migrated-components.json

Is this file something we need and/or want to keep committed? At first, this was basically just to verify that I was grabbing the right data, but I'm not sold that it needs to be committed to the repo. Thoughts? 🤷‍♀️ Maybe we add it to the .gitignore or something? Maybe there's some options to update it occasionally, sort of like renovate PRs? Whenever we deploy the site, we have to make sure this is up-to-date or something? I don't know...

- adds a MigratedComponentsList() block to ComponentDetails.jsx. That block gets used in the S2 Migration guide MDX file - adds a migrated-component-scanner.js task to scan the components directory and generate a list of migrated components based on their status (status: type: "migrated") - adds a migrated-components.json file to the .storybook/data directory - updates the package.json scripts to include the new migrated-component-scanner.js task so that it builds and captures the migration status when storybook is started

- captures the component title so it displays with proper capitalization in the list - generate a component url so it can be used to link to component docs

- in .storybook/project.json, a report script generates the migrated components list - yarn nx run .storybook:report can manually run migrated-component- scanner.js - removes component:data sripts from package.json commands

rise-erpelding

Works as expected, but I had some other questions related to the code!

rise-erpelding · 2025-07-29T19:50:35Z

.storybook/blocks/ComponentDetails.jsx

+			// Dynamic loading as fallback
+			const migrated = getComponentsByStatus({ statusType: 'migrated' });
+
+			if (migrated && migrated.length > 0) {
+				setComponents(migrated);


It seems like this part of the code might be unreachable? If I comment out the previous if block to force the fallback to work, I get an error that this getComponentsByStatus can only be used in a Node.js environment.

rise-erpelding · 2025-07-29T20:00:51Z

.storybook/blocks/ComponentDetails.jsx

+					</ul>
+				</>
+			) : (
+				<Body>Loading migrated components...</Body>


If the fallback to load dynamically doesn't work and we're always pulling from the json file, it might be worth another look to determine if we need a loading state.

rise-erpelding · 2025-07-29T20:29:46Z

.storybook/blocks/utilities.js

+
+	const { statusType } = options;
+
+	return componentUtils.getComponentsByStatus(statusType);


It is a tad confusing to have a getComponentsByStatus here and also in componentUtils/migrated-component-scanner.js.

rise-erpelding · 2025-07-29T20:38:49Z

.storybook/blocks/utilities.js

+ * @param {string} options.statusType Status type to filter by (e.g., 'migrated')
+ * @returns {string[]} Array of matching component directory names
+ */
+export function getComponentsByStatus(options = {}) {


Is there a situation where this getComponentsByStatus would run outside of the browser? I see that it gets called by the <MigratedComponentsList> component, which seems like it wouldn't be in a node.js environment?

rise-erpelding · 2025-07-29T21:16:33Z

.storybook/project.json

+		"report": {
+			"executor": "nx:run-commands",
+			"options": {
+				"commands": [
+					"node tasks/migrated-component-scanner.js --output=.storybook/data/migrated-components.json"
+				],
+				"cwd": "{workspaceRoot}"
+			}


Does that mean that we'd have to run yarn nx run .storybook:report in order to get a component added/removed from the migrated-components.json? I noticed I did have a difficult time trying to remove accordion from the json file after I removed the migrated status/tags but see that running report works (guess I should have read the validation instructions first 😏). I can see us easily forgetting to update the migrated list once we merge a migration if it's not a part of our regular workflows.

marissahuysentruyt self-assigned this May 15, 2025

marissahuysentruyt added size-2 S ~6-18hrs; not hard or time consuming, one or two work days to complete. wip This is a work in progress, don't judge. S2 Spectrum 2 labels May 15, 2025

marissahuysentruyt force-pushed the marissahuysentruyt/add-migrated-components-list branch 2 times, most recently from 83e37cf to 17e141a Compare June 17, 2025 20:35

castastrophe reviewed Jun 20, 2025

View reviewed changes

marissahuysentruyt force-pushed the marissahuysentruyt/add-migrated-components-list branch 2 times, most recently from 8425ef1 to 5d64978 Compare July 10, 2025 15:19

marissahuysentruyt force-pushed the marissahuysentruyt/add-migrated-components-list branch from 5d64978 to 0bd74e6 Compare July 25, 2025 15:40

marissahuysentruyt commented Jul 25, 2025

View reviewed changes

marissahuysentruyt force-pushed the marissahuysentruyt/add-migrated-components-list branch from 195b688 to 8e250a8 Compare July 25, 2025 16:31

marissahuysentruyt commented Jul 25, 2025

View reviewed changes

marissahuysentruyt force-pushed the marissahuysentruyt/add-migrated-components-list branch from 8e250a8 to 45b8911 Compare July 25, 2025 16:40

marissahuysentruyt marked this pull request as ready for review July 29, 2025 14:27

marissahuysentruyt added 4 commits July 29, 2025 14:44

feat: add more data to migrated components list

d2e79c5

- captures the component title so it displays with proper capitalization in the list - generate a component url so it can be used to link to component docs

refactor: add report script to project.json

3168db7

- in .storybook/project.json, a report script generates the migrated components list - yarn nx run .storybook:report can manually run migrated-component- scanner.js - removes component:data sripts from package.json commands

fix: pathing for component docs links

7fa91f2

marissahuysentruyt force-pushed the marissahuysentruyt/add-migrated-components-list branch from 45b8911 to 7fa91f2 Compare July 29, 2025 18:52

marissahuysentruyt added ready-for-review and removed wip This is a work in progress, don't judge. labels Jul 29, 2025

rise-erpelding reviewed Jul 29, 2025

View reviewed changes


		This is a list of all components that have been fully migrated to Spectrum 2.

		<MigratedComponentsList />


		const { statusType } = options;

		return componentUtils.getComponentsByStatus(statusType);

chore(storybook): add migrated components list #3745

Are you sure you want to change the base?

chore(storybook): add migrated components list #3745

Conversation

marissahuysentruyt commented May 15, 2025 • edited by rise-erpelding Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Jira/Specs

How and where has this been tested?

Validation steps

Regression testing

Screenshots

To-do list

Uh oh!

changeset-bot bot commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

File metrics

Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch preview

Uh oh!

marissahuysentruyt Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rise-erpelding left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marissahuysentruyt commented May 15, 2025 •

edited by rise-erpelding

Loading

changeset-bot bot commented May 15, 2025 •

edited

Loading

github-actions bot commented May 15, 2025 •

edited

Loading

github-actions bot commented May 15, 2025 •

edited

Loading

github-actions bot commented Jul 10, 2025 •

edited

Loading

marissahuysentruyt Jul 25, 2025 •

edited

Loading

marissahuysentruyt Jul 25, 2025 •

edited

Loading