feat: working typings for Paragon, better types for <Icon> component #3016

bradenmacdonald · 2024-03-12T21:24:37Z

Description

This represents my version of the minimal changes to Paragon to start getting (just a few!) useful type definitions shipping with it.

Before this PR, I wasn't seeing any types for Paragon imports, either in MFE code that uses it nor even in the www subproject of this repo, which nominally uses TypeScript.

After this PR, you still won't see many types, but TypeScript will at least know which component exist and which don't (it can check the imports). And a few components - <Icon>, <Chip>, <ChipCarousel>, and <Bubble> will have types because they are written in TypeScript (or in the case of Icon because there's a .d.ts file).

I deliberately didn't go any further than that because I want to keep the changeset small enough that we can confidently review and merge it. From that point on, it will be much easier to incrementally add types to individual components in separate PRs.

This PR:

Creates a src/index.d.ts file that makes all of the top-level exports visible to TypeScript. Without this fix, types were not being found in repos that import Paragon by path, such as the www subproject. It will be necessary to manually keep this file in sync with src/index.js. To make that as easy as possible, I made sure the files have a 1:1 correspondence line-by-line.

Example: www/src/components/IconsTable.tsx

Before: <Icon> has no types After: <Icon> is type checked
Adds "types": "dist/index.d.ts", to package.json. Without this change, types were not being found in MFEs that import Paragon via NPM.
Renames /src/Icon/Icon.test.jsx to be a .tsx file so that the <Icon /> component tests will use/check TypeScript.
Fixes incorrect types in src/Icon/index.d.ts. Now that Icon.test.tsx is enabled for type checking, we see that it contained type errors, because the .d.ts file was incomplete:
Adds type information to the icons sub-package. Now you get auto-completion and compile-time validation of the icon names. The new file, icons/es5/index.ts is completely auto-generated so there's no need to maintain the types manually.
Adds some compile-time (TypeScript-only) tests to Icon.test.tsx to avoid regressions.
Renames a few .jsx files in the documentation site (www subfolder) to .tsx because otherwise the linter was complaining that ~paragon-react couldn't be found. ~~This is because a .jsx file cannot import Paragon's src/index.ts anymore after the change in step 1.~~ This may not be an issue anymore after I changed the approach from step 1 above, but it doesn't hurt :)
Fixed the tsconfig.json (see inline comment) and separated out the build vs. dev tsconfigs.

How to test in an MFE

Have the MFE and paragon in folders next to each other on your host. This example will assume that frontend-app-course-authoring and paragon are peer folders on your host.
Make sure the MFE's dependencies are up to date (e.g. tutor dev run course-authoring npm install to do this for course-authoring)
In Paragon, edit package.json and change the line "@types/react": "17.0.0", to "@types/react": "../frontend-app-course-authoring/node_modules/@types/react", (otherwise you'll get weird conflicts with this package). Substitute the appropriate folder name if you're using a different MFE.
Run npm install in the paragon folder.
Mount paragon into the MFE's container: tutor mounts add course-authoring:/Users/yourname/path/to/paragon:/openedx/paragon (adjust this command as needed)
In the MFE's package.json change "@openedx/paragon": "^21.5.7", to "@openedx/paragon": "file:../paragon",
Link in the local paragon copy using tutor dev run course-authoring npm install --force (warnings about "Conflicting peer dependency" are expected; ignore them)
In VS Code, open any .jsx file in the MFE that has // @ts-check on its first line (or add that line in!), and you'll see type checking. Note that <Icon> should have correct typing, and other Paragon components like <Stack> should not show any type errors.

Example, showing the types appearing in VS Code for Course Authoring MFE's ImportTagsWizard.jsx:

Next Steps

Once this PR is merged, I think we should follow up with additional PRs to add typing to individual components (e.g. one component per PR, or similar). That can be done either by adding a .d.ts file for the component, or by converting the component implementation to TypeScript. In either case, I would encourage people to follow the example in this PR and make sure that the tests for the component are also converted to TypeScript (or some other mechanism is used to check that the types are working).

Once everything has a type (or close to it), the index.js file can be renamed to index.ts and the index.d.ts file can be deleted :)

Deploy Preview

The code for this page was changed, but you should not be able to see any changes:
https://deploy-preview-3016--paragon-openedx.netlify.app/foundations/icons/

Merge Checklist

If your update includes visual changes, have they been reviewed by a designer? Send them a link to the Netlify deploy preview, if applicable.
Does your change adhere to the documented style conventions?
Do any prop types have missing descriptions in the Props API tables in the documentation site (check deploy preview)?
Were your changes tested using all available themes (see theme switcher in the header of the deploy preview, under the "Settings" icon)?
Were your changes tested in the example app?
Is there adequate test coverage for your changes?
Consider whether this change needs to reviewed/QA'ed for accessibility (a11y). If so, please add wittjeff and adamstankiewicz as reviewers on this PR.

Post-merge Checklist

Verify your changes were released to NPM at the expected version.
If you'd like, share your contribution in #show-and-tell.
🎉 🙌 Celebrate! Thanks for your contribution.

openedx-webhooks · 2024-03-12T21:24:42Z

Thanks for the pull request, @bradenmacdonald! Please note that it may take us up to several weeks or months to complete a review and merge your PR.

Feel free to add as much of the following information to the ticket as you can:

supporting documentation
Open edX discussion forum threads
timeline information ("this must be merged by XX date", and why that is)
partner information ("this is a course on edx.org")
any other information that can help Product understand the context for the PR

All technical communication about the code itself will be done via the GitHub pull request interface. As a reminder, our process documentation is here.

Please let us know once your PR is ready for our review and all tests are green.

netlify · 2024-03-12T21:24:53Z

✅ Deploy Preview for paragon-openedx ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`f014498`
🔍 Latest deploy log	https://app.netlify.com/sites/paragon-openedx/deploys/65fb51dba7f71300087ea8d9
😎 Deploy Preview	https://deploy-preview-3016--paragon-openedx.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.

codecov · 2024-03-12T22:01:57Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.18%. Comparing base (98e6313) to head (f014498).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #3016   +/-   ##
=======================================
  Coverage   93.18%   93.18%           
=======================================
  Files         249      249           
  Lines        4342     4342           
  Branches     1036     1036           
=======================================
  Hits         4046     4046           
  Misses        292      292           
  Partials        4        4

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

bradenmacdonald · 2024-03-13T20:47:28Z

tsconfig.json

@@ -4,6 +4,7 @@
    "noImplicitAny": true,
    "allowJs": false,
    "rootDir": "src",
+    "outDir": "dist"


This fixed a major issue. Without this outDir setting, the build script was running tsc but tsc was putting its output .d.ts files into ./node_modules/@edx/typescript-config/dist/ !

brian-smith-tcril

Overall this looks great! Thank you so much for putting this together! I'm looking forward to pulling this down and testing it with an MFE!

brian-smith-tcril · 2024-03-20T15:46:56Z

www/tsconfig.json

@@ -1,7 +1,7 @@
 {
  "extends": "../tsconfig.json",
  "compilerOptions": {
-    "rootDir": "src",
+    "rootDir": "../",


I'm curious as to what happened before this was changed.

Without this change, I was getting errors like this when running ./node_modules/.bin/tsc --project www --noEmit from the main paragon root:

www/src/components/AutoToc.tsx:5:24 - error TS6059: File '/.../paragon/src/index.ts' is not under 'rootDir' '/.../paragon/www/src'. 'rootDir' is expected to contain all source files. The file is in the program because: Imported via '~paragon-react' from file '/.../paragon/www/src/components/AutoToc.tsx'

However, it seems like the commit 688d212 resolved this in another way, by changing from index.ts to index.d.ts so this change to www/tsconfig.json's rootDir is no longer needed. I'll just leave it as it was.

brian-smith-tcril · 2024-03-22T16:18:00Z

I tested this out in frontend-app-authn by replacing "@openedx/paragon": "^22.0.0", in package.json with "@openedx/paragon": "file:../paragon",, and adding // @ts-check to the top of EnterpriseSSO.jsx. I then looked at this line https://github.com/brian-smith-tcril/frontend-app-authn/blob/2d37b8b0bfd8d289dc4da409d5d9c749b6c01f2b/src/common-components/EnterpriseSSO.jsx#L62 and saw

I'm not sure if this is a "task failed successfully" moment or if this means there's more that needs to be explored here.

bradenmacdonald · 2024-03-22T16:42:09Z

@brian-smith-tcril That happens when you have two different versions of @types/react installed - Paragon has its own version that's different from what's in your MFE. It's a side effect of the way you added paragon as a local folder dependency. I ran into the same problem, and found a workaround, which is in the "How to test in an MFE" in the PR description.

Also, once this is merged and installed via NPM, its deduplication will make sure that doesn't happen. But here you're joining together two separate sets of npm installed packages and two different node_modules folders, rather than one big one.

brian-smith-tcril · 2024-03-22T16:55:43Z

@bradenmacdonald thanks for clarifying! I wasn't sure what you meant by "weird conflicts with this package" in that section. After following that step everything seems to work as expected!

brian-smith-tcril

Tested locally with frontend-app-authn, everything is working as expected!

openedx-webhooks · 2024-03-25T15:57:56Z

@bradenmacdonald 🎉 Your pull request was merged! Please take a moment to answer a two question survey so we can improve your experience in the future.

openedx-semantic-release-bot · 2024-03-25T16:08:39Z

🎉 This PR is included in version 22.2.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

feat: better types for <Icon> component

3a3a481

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Mar 12, 2024

bradenmacdonald added 2 commits March 12, 2024 14:33

fix: TypeScript rootDir now that it's checking '../src' files too

1c6988b

chore: fix eslint 'import/order' & 'import/no-unresolved' issues in www

b52c52f

bradenmacdonald mentioned this pull request Mar 12, 2024

[BD-46] feat: defined types for Paragon export #2566

Open

10 tasks

mphilbrick211 added the waiting for eng review PR is ready for review. Review and merge it, or suggest changes. label Mar 13, 2024

bradenmacdonald added 3 commits March 13, 2024 11:19

fix: build wasn't including types properly

bbe900f

fix: <Icon/> types still weren't correct

3b3d91e

fix: explicitly define other exports as having 'any' type

688d212

bradenmacdonald commented Mar 13, 2024

View reviewed changes

bradenmacdonald changed the title ~~feat: better types for <Icon> component~~ feat: working typings for Paragon, better types for <Icon> component Mar 13, 2024

brian-smith-tcril self-requested a review March 20, 2024 15:36

brian-smith-tcril reviewed Mar 20, 2024

View reviewed changes

fix: changing www/tsconfig.json is no longer needed

b40e037

bradenmacdonald force-pushed the braden/icon-typing branch from c1ad897 to fd07756 Compare March 20, 2024 20:40

fix: warning seen when gatsby parses index.d.ts during 'npm run start'

f014498

bradenmacdonald force-pushed the braden/icon-typing branch from fd07756 to f014498 Compare March 20, 2024 21:15

brian-smith-tcril approved these changes Mar 22, 2024

View reviewed changes

brian-smith-tcril requested a review from adamstankiewicz March 22, 2024 17:12

brian-smith-tcril removed the waiting for eng review PR is ready for review. Review and merge it, or suggest changes. label Mar 22, 2024

bradenmacdonald mentioned this pull request Mar 22, 2024

feat!: typescript configuration and jest v29 upgrade openedx/frontend-build#429

Merged

adamstankiewicz approved these changes Mar 23, 2024

View reviewed changes

brian-smith-tcril merged commit 0983219 into openedx:master Mar 25, 2024
10 checks passed

openedx-semantic-release-bot added the released label Mar 25, 2024

bradenmacdonald deleted the braden/icon-typing branch March 25, 2024 16:40

bradenmacdonald mentioned this pull request Apr 3, 2024

Bump Paragon to v22.2.1, fix some bugs that turned up openedx/frontend-app-authoring#933

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: working typings for Paragon, better types for <Icon> component #3016

feat: working typings for Paragon, better types for <Icon> component #3016

bradenmacdonald commented Mar 12, 2024 •

edited

Loading

openedx-webhooks commented Mar 12, 2024

netlify bot commented Mar 12, 2024 •

edited

Loading

codecov bot commented Mar 12, 2024 •

edited

Loading

bradenmacdonald Mar 13, 2024

brian-smith-tcril left a comment

brian-smith-tcril Mar 20, 2024

bradenmacdonald Mar 20, 2024 •

edited

Loading

brian-smith-tcril commented Mar 22, 2024

bradenmacdonald commented Mar 22, 2024

brian-smith-tcril commented Mar 22, 2024

brian-smith-tcril left a comment

openedx-webhooks commented Mar 25, 2024

openedx-semantic-release-bot commented Mar 25, 2024

feat: working typings for Paragon, better types for <Icon> component #3016

feat: working typings for Paragon, better types for <Icon> component #3016

Conversation

bradenmacdonald commented Mar 12, 2024 • edited Loading

Description

How to test in an MFE

Next Steps

Deploy Preview

Merge Checklist

Post-merge Checklist

openedx-webhooks commented Mar 12, 2024

netlify bot commented Mar 12, 2024 • edited Loading

✅ Deploy Preview for paragon-openedx ready!

codecov bot commented Mar 12, 2024 • edited Loading

Codecov Report

bradenmacdonald Mar 13, 2024

Choose a reason for hiding this comment

brian-smith-tcril left a comment

Choose a reason for hiding this comment

brian-smith-tcril Mar 20, 2024

Choose a reason for hiding this comment

bradenmacdonald Mar 20, 2024 • edited Loading

Choose a reason for hiding this comment

brian-smith-tcril commented Mar 22, 2024

bradenmacdonald commented Mar 22, 2024

brian-smith-tcril commented Mar 22, 2024

brian-smith-tcril left a comment

Choose a reason for hiding this comment

openedx-webhooks commented Mar 25, 2024

openedx-semantic-release-bot commented Mar 25, 2024

bradenmacdonald commented Mar 12, 2024 •

edited

Loading

netlify bot commented Mar 12, 2024 •

edited

Loading

codecov bot commented Mar 12, 2024 •

edited

Loading

bradenmacdonald Mar 20, 2024 •

edited

Loading