Refactor `@wordpress/components` package to TypeScript

[andrewserong]

Related to #30503, #28399 and #27484

Context ✨

We would like to refactor the entire @wordpress/components package to TypeScript.

Some components are already written in TypeScript, while the majority of the code is still written in JavaScript.

By refactoring the whole package to TypeScript, we would be able to take advantage of type safety, while also providing first-party types to the package's consumers (instead of the third-party ones).

A fully-typed set of components would also potentially allow us to generate documentation programmatically based off types.

Details of the refactor 🔍

The refactors should introduce the least amount of runtime changes possible — ideally none. All JS files should be refactored to TypeScript.

You can also refer to the TypeScript migration guide in the @wordpress/components package guidelines., and reference an existing component like ItemGroup or ToolsPanel.

Next up

Once the refactor to TypeScript is complete, we'll be able to:

• migrate all components to Emotion for styles
• refactor folder structures, potentially split into hook+component
• refactor components to use context
• remove (or mark as deprecated) the third party types

List ⚒️

The components in the exclude list of our tsconfig are particularly high priority.

• AlignmentMatrixControl (packages/components/src/alignment-matrix-control) AlignmentMatrixControl: refactor to TypeScript #46162
• AnglePickerControl (packages/components/src/angle-picker-control) @ciampo AnglePickerControl: refactor to TypeScript #45820
• Animate (packages/components/src/animate) Animate: refactor to TypeScript #49243
• Animation (packages/components/src/animation)
• Autocomplete (packages/components/src/autocomplete) Autocomplete: refactor to TypeScript #47751
• BaseControl (packages/components/src/base-control) BaseControl: Migrate to TypeScript #39468
• BaseField (packages/components/src/base-field) useBaseField: Convert component to TypeScript #45712
• BorderBoxControl (packages/components/src/border-box-control) (Storybook BorderBoxControl: Refactor stories to TypeScript and Controls #45002, tests BorderBoxControl: migrate tests to TypeScript, remove act() call #47755)
• BorderControl (packages/components/src/border-control) BorderControl: Complete TypeScript migration #41843
• BoxControl (packages/components/src/box-control) BoxControl: Convert to TypeScript #47622
• Button (packages/components/src/button) Refactor Button component to TypeScript #46997
  • update types for components depending on button, like NavigatorBackButton and NavigatorButton) NavigatorButton: Reuse Button types #47754
• ButtonGroup (packages/components/src/button-group) ButtonGroup: Convert to TypeScript #41007
• Card (packages/components/src/card) Card: migrate to TypeScript #42941
• CheckboxControl (packages/components/src/checkbox-control) CheckboxControl: Convert component to TypeScript #40915
• CircularOptionPicker (packages/components/src/circular-option-picker) CircularOptionPicker: refactor to TypeScript #47937
• ClipboardButton (packages/components/src/clipboard-button) Convert ClipboardButton to TypeScript #51334
• ColorIndicator (packages/components/src/color-indicator) ColorIndicator: Convert component to TypeScript #41587
• ColorListPicker (packages/components/src/color-list-picker) ColorListPicker: refactor to TypeScript #46358
• ColorPalette (packages/components/src/color-palette) Convert the ColorPalette component to TypeScript #44632
• ColorPicker (packages/components/src/color-picker) @chad1008 ColorPicker: TypeScript refactor #49214
• ComboboxControl (packages/components/src/combobox-control) ComboboxControl: Convert to TypeScript #47581
• Composite (packages/components/src/composite) Composite: refactor to TypeScript #54028
• ConfirmDialog (packages/components/src/confirm-dialog) ConfirmDialog: ts unit test storybook #54954
• CustomGradientPicker (packages/components/src/custom-gradient-picker) CustomGradientPicker: Refactor to TypeScript #48929
• CustomSelectControl (packages/components/src/custom-select-control) (instead of a refactor, the component will be rewritten from scratch CustomSelectControl: refactor using ariakit #41726)
• Dashicon (packages/components/src/dashicon) Dashicon: refactor to TypeScript #45924
• DateTime (packages/components/src/date-time) Rewrite DatePicker, TimePicker and DateTimePicker in TypeScript #40775 Use TypeScript and controls for DateTimePicker's stories #40986 Add jest-console typings and convert DateTimePicker tests to TypeScript #40957
• DimensionControl (packages/components/src/dimension-control) DimensionControl(Experimental): refactor to TypeScript #47351
• Disabled (packages/components/src/disabled) Disabled: migrate to TypeScript #42708
• Disclosure (packages/components/src/disclosure) (will be migrated as part of the reakit -> ariakit refactor) DisclosureContent: migrate from reakit to @ariakit/react #55639
• Divider (packages/components/src/divider) Divider: Complete TypeScript migration of component #41991
• Draggable (packages/components/src/draggable) Draggable: Convert component to TypeScript #45471
• DropZone (packages/components/src/drop-zone) DropZone: Convert to TypeScript #43962
• Dropdown (packages/components/src/dropdown) (should also replace types in ColorPalette) Refactor Dropdown component to TypeScript #45787
• DropdownMenu (packages/components/src/dropdown-menu) (suggested in this comment) @chad1008 DropdownMenu: refactor to TypeScript #50187
• DuotonePicker, DuotoneSwatch (packages/components/src/duotone-picker) DuotonePicker, DuotoneSwatch: Convert to TypeScript #49060
• Elevation (packages/components/src/elevation) Elevation: Convert component to TypeScript #42302
• ExternalLink (packages/components/src/external-link) ExternalLink: Convert component to TypeScript #41681
• Flex (packages/components/src/flex) Flex: Convert component to TypeScript #42537
• FocalPointPicker (packages/components/src/focal-point-picker) FocalPointPicker: Convert to TypeScript #43872
• FocusableIframe (packages/components/src/focusable-iframe) FocusableIframe: refactor to TypeScript #53979
• FontSizePicker (packages/components/src/font-size-picker) Convert FontSizePicker to TypeScript #44449
• FormFileUpload (packages/components/src/form-file-upload) FormFileUpload: Convert to TypeScript #43960
• FormToggle (packages/components/src/form-toggle) FormToggle: Covert component to TypeScript #41729
• FormTokenField (packages/components/src/form-token-field) Rewrite <FormTokenField> to functional component and Typescript. #41216, FormTokenField: use KeyboardEvent.code, refactor tests to model RTL and user-event #43442
• GradientPicker (packages/components/src/gradient-picker) GradientPicker: refactor to TypeScript #48316 @chad1008
• Grid (packages/components/src/grid) Grid: Convert component to TypeScript #41923
• Guide (packages/components/src/guide) Guide: refactor to TypeScript #47493
• HStack packages/components/src/h-stack) HStack: Convert component to TypeScript #41580
• Heading (packages/components/src/heading) Heading: Complete TypeScript migration of component #41921
• HigherOrder (packages/components/src/higher-order)
  • navigate-regions navigateRegions: Convert to TypeScript #48632
  • with-constrained-tabbing Update: Change higher order with-constraint-tabbing from .js to .tsx #48162
  • with-fallback-styles withFallbackStyles: Convert to TypeScript #48720
  • with-filters withFilters: Convert to TypeScript #48721
  • with-focus-outside with-focus-outside: Convert to TypeScript #53980 (also remove the @ts-expect-error calls in ComboboxControl)
  • with-focus-return withFocusReturn: Convert to TypeScript #48748
  • with-notices withNotices: Convert to TypeScript #49088
  • with-spoken-messages withSpokenMessages: Change js files to typescript #48163
• Icon (packages/components/src/icon) - convert tests Icon: refactor tests to TypeScript #49066
• InputControl (packages/components/src/input-control) components: InputControl to TypeScript #33696
• IsolatedEventContainer IsolatedEventContainer to Typescript (just test file) #54316 (packages/components/src/isolated-event-container)
• ItemGroup (packages/components/src/item-group) (ItemGroup: migrate Storybook to controls, refactor to TypeScript #46945)
• KeyboardShortcuts (packages/components/src/keyboard-shortcuts) KeyboardShortcuts: Convert to TypeScript #47429
• MenuGroup (packages/components/src/menu-group) MenuGroup: refactor to TypeScript and Emotion #36561 MenuGroup: Convert component to TypeScript #45617
• MenuItem (packages/components/src/menu-item) MenuItem: Refactor to TypeScript #53132 MenuItem: refactor to TypeScript and Emotion #37020
• MenuItemsChoice (packages/components/src/menu-items-choice) MenuItemsChoice: Refactor to TypeScript #47180
• Modal (packages/components/src/modal) Modal: Convert component to TypeScript #42949
• NavigableContainer (packages/components/src/navigable-container) NavigableContainer: convert to TypeScript #49377
• Navigation (packages/components/src/navigation) Navigation: refactor to TypeScript #48742
• Navigator (packages/components/src/navigator) (unit tests: Navigator: refactor tests to TypeScript and user-event #44970, storybook: Navigator: refactor Storybook code to TypeScript and controls #44979)
• Notice (packages/components/src/notice) Notice: refactor to TypeScript #47118
• NumberControl (packages/components/src/number-control) (suggested in this comment) (include also changes proposed in LineHeightControl: Migrate internals to NumberControl (Part 2: Behavior) #37164 (comment))
  • NumberControl: Add TypeScript prop types #43791
  • Type the value prop and remove the last @ts-expect-error comments
    • NumberControl: refactor styles/tests/stories to TypeScript, replace fireEvent with user-event #45990
    • NumberControl: tidy up and fix types around value prop #45982
• PaletteEdit (packages/components/src/palette-edit): PaletteEdit: Convert to TypeScript #47764
• Panel (packages/components/src/panel) Panel: Convert to TypeScript #47259
• Placeholder (packages/components/src/placeholder) Placeholder: Convert component to TypeScript #42990 Components: Refactor Placeholder tests to @testing-library/react #43069
• Popover (packages/components/src/popover) Popover: refactor to TypeScript #43823 Popover: convert unit tests to TypeScript and modern RTL assertions #44373
• QueryControl (packages/components/src/query-controls) Refactor QueryControls component to TypeScript #46721
• Radio (packages/components/src/radio)
• RadioContext (packages/components/src/radio-context)
• RadioControl (packages/components/src/radio-control) RadioControl: Convert component to TypeScript #41568
• RadioGroup (packages/components/src/radio-group)
• RangeControl (packages/components/src/range-control) (suggested in this comment) RangeControl: Convert component to TypeScript #40535, RangeControl: Convert stories to TypeScript #41444, RangeControl: Convert unit tests to typescript #41445
• ResizableBox (packages/components/src/resizable-box) (ResizableBox: Remove knobs in stories #46774, ResizableBox: refactor styles to TypeScript #47756)
• ResponsiveWrapper (packages/components/src/responsive-wrapper) ResponsiveWrapper: Convert to TypeScript #46480
• Sandbox (packages/components/src/sandbox) SandBox: Convert to TypeScript #46478
• ScrollLock (packages/components/src/scroll-lock) ScrollLock: Covert component to TypeScript #42303
• Scrollable (packages/components/src/scrollable) Scrollable: Convert component to TypeScript #42016
• SearchControl (packages/components/src/search-control) SearchControl: Convert to TypeScript and add flag to remove bottom margin #43871
• SelectControl (packages/components/src/select-control) SelectControl: Finish typescript migration #40737
  • Improve type of value prop (string[] if multiple is true, string otherwise) SelectControl: improve prop types for single vs multiple selection #47390
• Shortcut (packages/components/src/shortcut) Shortcut: Covert component to TypeScript #42272
• SlotFill (packages/components/src/slot-fill) SlotFill: Migrate to Typescript. #51350
• Snackbar (packages/components/src/snackbar) (Convert the Snackbar component to TypeScript #45472)
• Spacer (packages/components/src/spacer) Spacer: Complete TypeScript migration of component #42013
• Spinner (packages/components/src/spinner) Spinner: Convert component to TypeScript #41540
• StyleProvider (packages/components/src/style-provider) StyleProvider: Convert component to TypeScript #42541
• Surface (packages/components/src/surface) Surface: Convert component to TypeScript #41212
• Swatch (packages/components/src/swatch) Swatch: Convert component to TypeScript #42162
• TabPanel (packages/components/src/tab-panel) TabPanel: Convert to TypeScript #43536
• Text (packages/components/src/text) (check truncate behaviors noted in this comment, try removing boolean types from adjustLineHeightForInnerControls) Text Component: Typescript'n #54953
• TextControl (packages/components/src/text-control) TextControl: Convert component to TypeScript #40633
• TextHighlight (packages/components/src/text-highlight) TextHighlight: Convert component to TypeScript #41698
• TextareaControl (packages/components/src/textarea-control) TextareaControl: Convert component to TypeScript #41215
• Tip (packages/components/src/tip) Tip: Covert component to TypeScript #42262
• ToggleControl (packages/components/src/toggle-control) ToggleControl: Convert to TypeScript #43717
• ToggleGroupControl (packages/components/src/toggle-group-control)
• Toolbar:
  • Toolbar (packages/components/src/toolbar) Refactor Toolbar component to TypeScript #47087
  • ToolbarButton (packages/components/src/toolbar-button) Refactor/toolbar button component to typescript #47750
  • ToolbarContext (packages/components/src/toolbar-context) Refactor ToolbarContext to TS #49002
  • ToolbarDropdownMenu (packages/components/src/toolbar-dropdown-menu) Toolbar/ToolbarDropdownMenu Typescript Conversion #54321
  • ToolbarGroup (packages/components/src/toolbar-group) ToolbarGroup - Typescript #54317
  • ToolbarItem (packages/components/src/toolbar-item) Refactor/toolbar item component to typescript #49190
• ToolsPanel (packages/components/src/tools-panel) @ciampo (Storybook: ToolsPanel: refactor Storybook examples to TypeScript, fix types inconsistencies #47944, Unit tests: ToolsPanel: refactor unit tests to TypeScript #48275)
• Tooltip (packages/components/src/tooltip) (As per Tooltip: discuss simplifying the component #42753, the component won't be refactored, but will be instead completely rewritten) ToolTip: refactor using ariakit  #48440
• TreeGrid (packages/components/src/tree-grid) TreeGrid: Convert to TypeScript #47516
• TreeSelect (packages/components/src/tree-select) TreeSelect Convert to Typescript. #41536
• Truncate (packages/components/src/truncate) Truncate: Convert component to TypeScript #41697
• UnitControl (packages/components/src/unit-control) (refactored to TS in 35281, suggested follow ups in this comment, tests refactored in UnitControl: rewrite tests in TypeScript #40697)
• VStack (packages/components/src/v-stack) VStack: Convert component to TypeScript #41850
• View (packages/components/src/view) View component: rename index.js to index.ts #45667
• VisuallyHidden (packages/components/src/visually-hidden) VisuallyHidden: Convert component to TypeScript #42220
• ZStack (packages/components/src/z-stack) ZStack: Convert component story to TypeScript and add inline docs #41694
• index.js

Click to reveal the dependency graph

[rajnish93]

Hello everyone 👋 I want to work on this issue. Can anyone tell me if I need to convert all js file to typescript. (example in DropdownMenu have index.js , index.native.js, test folder and stories folder) Do I need to change only index.js to typescript or all files.

[ciampo]

Hello everyone 👋 I want to work on this issue. Can anyone tell me if I need to convert all js file to typescript. (example in DropdownMenu have index.js , index.native.js, test folder and stories folder) Do I need to change only index.js to typescript or all files.

Hey @rajnish93 , thank you for your interest! I would ask you to wait before contributing to this issue, as I'm going to update the list of components that need refactoring. Some of the refactors are quite complex and it's probably better if we champion a few of them first to understand any caveat along the way.

We'd still love to get your help further down the line though, if that's ok!

[ciampo]

Alright, I've edited this issue's description and added all components/folders in the package.

There's still a couple of things of which I’m not sure yet:

1. so far, even with fully-typed components, we left a few files still in JS — in particular unit tests, storybook examples, and react native files. Is there a particular reason for each of those?
2. Where to draw the line in the refactor? On one hand, as we refactor, it would good to hook components to the context system, and therefore use the WordPressComponent type. On the other hand, we may want to keep the refactor as lean as possible and only aim changing file extension, fixing TS errors, and (maybe) adding a types.ts file. We should also consider that certain components are still written in class form — in that case, should we first refactor them to functional components in a separate PR preceding the TypeScript refactor?

Would love to hear folks' opinions on this (cc @mirka @diegohaz @sarayourfriend )

[sarayourfriend]

so far, even with fully-typed components, we left a few files still in JS — in particular unit tests, storybook examples, and react native files. Is there a particular reason for each of those?

From a "value" perspective I don't think there's a compelling reason to spend contributor time on updating unit tests and storybook examples to use TypeScript.

React native is a separate beast altogether. I'm not sure what it would take to convert those to TypeScript or if it's even possible with the current tooling.

Where to draw the line in the refactor? On one hand, as we refactor, it would good to hook components to the context system, and therefore use the WordPressComponent type. On the other hand, we may want to keep the refactor as lean as possible and only aim changing file extension, fixing TS errors, and (maybe) adding a types.ts file. We should also consider that certain components are still written in class form — in that case, should we first refactor them to functional components in a separate PR preceding the TypeScript refactor?

From a perspective of what will benefit the consumers of the components package the most, just adding types is a big win. The rest of the things help bring the components package inline with itself (context, Emotion, hooks, etc) but don't necessarily have a big effect on the consumers of the package. While converting to TypeScript will increase the maintainability of the package, it probably has the greatest effect on consumers of it. Given it will be the largest most widely used package to be typed in Gutenberg, it will also serve to evangelize the benefits of TypeScript to other contributors, many of whom may still have doubts that TypeScript is a valuable tool to learn in addition to everything else they've already been asked to learn to be able to contribute to Gutenberg (JavaScript, React (twice over now given the transition to hooks happened during Gutenberg's lifetime), etc).

Remember, we don't refactor just because we can. In the spirit of this, we should continue only converting to TypeScript (instead of just annotating with JSDoc) when necessary. This was the agreement made in the Make post that added TypeScript to Gutenberg (see When to use TypeScript for existing code section).

[ciampo]

From a "value" perspective I don't think there's a compelling reason to spend contributor time on updating unit tests and storybook examples to use TypeScript.

I see your point, although I liked the idea that a component would have all of its files in TypeScript, rather than a mix of TypeScript and JavaScript. But definitely not a priority when considering which order we should tackle components.

React native is a separate beast altogether. I'm not sure what it would take to convert those to TypeScript or if it's even possible with the current tooling.

I'll be seeking more advice from mobile folks on this matter specifically and come back with updates

Remember, we don't refactor just because we can. In the spirit of this, we should continue only converting to TypeScript (instead of just annotating with JSDoc) when necessary.

Thank you for the link! I would argue that a refactor to TypeScript has become, for this package, quite a necessity. As you explained too, it will bring benefits to the consumers of the package by adding first-party types, allowing us to deprecate (and stop maintaining) the DefinitelyTyped ones

Another added benefit that you mentioned is maintainability: the package is currently very fragmented in terms of technology:

• some components are written in JavaScript, some in TypeScript
• some components are styles in Sass, some in Emotion
• some components use the context system, most don't

Aligning the components in the package on the same tech stack as much as possible would make it easier for devs to maintain the package and for new folks to contribute to it.

Having said that, in the context of this TypeScript refactor, I think it makes the most sense to keep the refactor as "lean" as possible — i.e. adding the necessary types and refactoring the code without (theoretically) introducing any runtime changes. We can only iterate later on in case we want to introduce more changes to each component when necessary.

[sarayourfriend]

Having said that, in the context of this TypeScript refactor, I think it makes the most sense to keep the refactor as "lean" as possible — i.e. adding the necessary types and refactoring the code without (theoretically) introducing any runtime changes. We can only iterate later on in case we want to introduce more changes to each component when necessary.

Yes! I think this is the clearest path forward for this issue, otherwise the scope is far too large!