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: 5c7f567

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?

This feels separate-ticket worthy to figure out how we keep the list up-to-date without having to manually do it. In the CI would be good, or if we can run it when we run yarn start locally, then we remember to commit the changes to that file like we do to metadata.json, that would work too.

.storybook/data/migrated-components.json

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.

I don't get that error, but I also don't get anything else. 😭

I think this question and your other question are sort of related. Forgive me if I am restating things you already know.

So I think this is doing exactly what it should- this getComponentsByStatus is the wrapper, which detects the environment. There isn't really a situation where this would run outside of Node, except possibly with unit testing or SSR I believe. The utility wrapper getComponentByStatus basically just detects the environment and then passes off any actual logic to the getComponentByStatus in the migrated-components-scanner.js file. So if we bypass the logic with the JSON file, the browser returns an empty array and we get the Node warning. According to Cursor, it sounds like it's not expected to work in the browser. And that utility wrapper (at least as it is right now) is basically a fallback for only Node contexts like testing or SSR.

Also Cursor seems to think we should keep that JSON data committed. 😆

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.

Good call. I think that depends on whether we want to commit that JSON file, right? I had some other questions about that file, but this is another good one.

Because, yes, if we always pull from that file, I don't think we need the fallback. 👍

Yep. It's not hurting anything to keep the loading state logic but as it is right now, I don't think there's a situation where we'd see the loading state in the UI.

Now, it is also fair to say we don't have a way to handle if the json file somehow fails after the build (if it's somehow missing when ComponentDetails reaches for it, right now this causes an error; or if the components array is empty, or the components property is missing altogether, which makes the list empty, which is okay)...

And yeah, I'd agree, I think we do want to commit the json file unless it's set up to automatically regenerate when you start storybook?

.storybook/blocks/utilities.js

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.

rise-erpelding

Just a few more little things! I called out the console.log issue when running the script in the terminal, but I think the main thing that may need addressing is ensuring that we have both text field and text area on the list, or at least minimally, we want text field showing up on the list instead of text area.

Also we'll want to have a follow-up ticket to make sure that we continue to update the list as new components are added!

rise-erpelding · 2025-08-14T17:07:51Z

tasks/migrated-component-scanner.js

+			console.log(`Found ${report.migrated} migrated components out of ${report.total} total components.`);
+		} else {
+			console.log("Migrated Components:");
+			console.log(report.components.join(", "));


If I run this in the terminal, I get a lot of [object Object] for the list of migrated components, would it be possible to update to something like this to get a readable list there?

Suggested change

console.log(report.components.join(", "));

const componentNames = report.components.map(component => component.title || component.name || component);

console.log(componentNames.join(", "));

love that idea!

rise-erpelding · 2025-08-14T18:21:33Z

.storybook/data/migrated-components.json

+    {
+      "name": "textfield",
+      "title": "Text area",
+      "url": "text-area"
+    },


Hmmm, I was wondering why textfield didn't show up on the list for me, and it is here... just pretending to be text area instead?

rise-erpelding · 2025-08-14T18:26:57Z

tasks/migrated-component-scanner.js

+		const storyFiles = fs.readdirSync(storiesDir).filter(file => file.endsWith(".stories.js"));
+		let title = null;
+		for (const file of storyFiles) {
+			title = extractTitleFromStoryFile(path.join(storiesDir, file));
+			if (title) break;


I think the logic around here needs updating if we want to be able to pick up both text field and text area. When I log storyFiles for text field I get [ 'textarea.stories.js', 'textfield.stories.js' ], but then we have it set up to only extract one title and in this weird edge case we have two.

I think that's the only place where we have that situation though. I wonder if there are other places where this is potentially causing an issue? If so we could consider modifying the way textfield and textarea are packaged?

My vote based on what I know currently would be trying to update the logic here rather than doing that.

Great call, thank you so much. Yes, I think it's the only place right now. We separated meter from progress bar, and those would have been in the same boat.

Anyways. the script has been updated to account for multiple story files in a directory. 👍

rise-erpelding · 2025-08-14T18:41:00Z

.storybook/data/migrated-components.json

+      "name": "stepper",
+      "title": "Number field",
+      "url": "number-field"


Does this one show up out of alphabetical order for you in the list?

Not a deal breaker at all, but worth mentioning.

It's probably because only that component's title in Storybook is Number field- it's package and component name that we ship are still Stepper.

Yeah, we could do something to sort it alphabetically by title if we want it to be ordered in a more expected way, or potentially put the name in parentheses so it reads "Number field (stepper)" (I'm thinking without looking closely at the code that you'd do this in any situation where the lowercased joined/no-space/no-punctuation title is different from the name, so it would catch this and also breadcrumbs/breadcrumb), but it's also ok as is.

lemme know what you think of the sorting functions!

rise-erpelding · 2025-08-14T18:47:17Z

.storybook/project.json

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


This feels separate-ticket worthy to figure out how we keep the list up-to-date without having to manually do it. In the CI would be good, or if we can run it when we run yarn start locally, then we remember to commit the changes to that file like we do to metadata.json, that would work too.

- 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

- alphabetically sort console output - handle directories that have multiple story files with different components/titles - add code comments/documentation

rise-erpelding

marissahuysentruyt · 2025-08-21T21:00:36Z

I think I'm going to close this, just in case we ever want to come back to this script (that feels unlikely, but you never know!)

I'll open a new branch to document the filtering-by-tag functionality better. That will be loads easier and will remove the extra work we identified in this PR related to keeping the list up to date. Thanks @rise-erpelding and @castastrophe!

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

.storybook/data/migrated-components.json Show resolved Hide resolved

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 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

marissahuysentruyt force-pushed the marissahuysentruyt/add-migrated-components-list branch from 7fa91f2 to 2871f37 Compare August 14, 2025 14:43

rise-erpelding reviewed Aug 14, 2025

View reviewed changes

marissahuysentruyt added 9 commits August 15, 2025 16:41

feat: add more data to migrated components list

adc508f

- 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

5744d85

- 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

d4efdcb

feat: update migrated components json

ac24f4b

refactor: rename utilities function to getComponentsByStatusWrapper

b538eca

docs: add JSDoc comments for wrapper

895af59

chore: pr feedback

62d0b78

- alphabetically sort console output - handle directories that have multiple story files with different components/titles - add code comments/documentation

fix: update migrated components json

5c7f567

marissahuysentruyt force-pushed the marissahuysentruyt/add-migrated-components-list branch from 6b38dbe to 5c7f567 Compare August 15, 2025 21:17

rise-erpelding approved these changes Aug 15, 2025

View reviewed changes

marissahuysentruyt removed the ready-for-review label Aug 21, 2025

marissahuysentruyt closed this Aug 21, 2025


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

		<MigratedComponentsList />

	console.log(report.components.join(", "));
	const componentNames = report.components.map(component => component.title \|\| component.name \|\| component);
	console.log(componentNames.join(", "));

chore(storybook): add migrated components list #3745

chore(storybook): add migrated components list #3745

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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

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

rise-erpelding Aug 15, 2025 •

edited

Loading