refactor(ui-codemods): add codemod to remove the 'as' prop from InstUISettingsProvider

also some smaller refactoringa to codemods

INSTUI-4113

Author: matyasf

…cs/contributor-docs/v10-upgrade-guide.md docs/contributor-docs/upgrade-guide.mddocs/contributor-docs/v10-upgrade-guide.md renamed to docs/contributor-docs/upgrade-guide.md docs/contributor-docs/v10-upgrade-guide.md renamed to docs/contributor-docs/upgrade-guide.md

@@ -7,7 +7,11 @@ isWIP: true
 
 # Upgrade Guide for Version 11 (WIP)
 
-## Removal of deprecated props/components
+## Removal of deprecated props/components/APIs
+
+### InstUISettingsProvider
+
+[InstUISettingsProvider](/#InstUISettingsProvider)'s `as` prop was removed, it will always render as a `<span>` (note: it will only render anything to the DOM if you provide a value to the `dir` prop.). The provided codemod will remove this prop automatically (see below).
 
 ### Table
 
@@ -22,13 +26,31 @@ isWIP: true
 
 ### Theming engine changes
 
-| Deprecation                                | What to use instead?                                                                                     |
-| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
-| `canvas.use()`, `canvasHighContrast.use()` | Wrap all your application roots in `<InstUISettingsProvider>`                                            |
-| `variables` field on theme objects         | Use the fields from the object above, e.g. use `canvas.borders` instead of `canvas.variables.borders`    |
-| `@instructure/theme-registry` package      | This added the deprecated functions above. Wrap all your application roots in `<InstUISettingsProvider>` |
+| Deprecation                                | What to use instead?                                                                                  |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `canvas.use()`, `canvasHighContrast.use()` | Wrap all your application roots in `<InstUISettingsProvider>`                                         |
+| `variables` field on theme objects         | Use `canvas.borders` instead of `canvas.variables.borders` (same for all othere fields)               |
+| `@instructure/theme-registry` package      | This added the removed functions above. Wrap all your application roots in `<InstUISettingsProvider>` |
 
-## Changes
+## API Changes
 
 - `ui-dom-utils`/`getComputedStyle` can now return `undefined`: In previous versions sometimes returned an empty object which could lead to runtime exceptions when one tried to call methods of `CSSStyleDeclaration` on it.
 - TO-DO: [TimeSelect](/#TimeSelect) as a controlled component can now return an '' instead of a valid date when its input field is cleared. In previous versions it always reverted to the last selected value when the input field was cleared and lost focus.
+
+## Codemods
+
+To ease the upgrade we provide codemods that will automate most of the changes. Pay close attention to its output, it cannot refactor complex code! The codemod scripts can be run via the following commands:
+
+```sh
+---
+type: code
+---
+npm install @instructure/ui-codemods@11
+npx [email protected] -t node_modules/@instructure/ui-codemods/lib/instUIv11Codemods.ts <path> --usePrettier=false
+```
+
+Options for the codemod:
+
+- `filename`: if specified then emitted warnings are written to this file.
+- `usePrettier`: if `true` the transformed code will be run through Prettier. You can customize this through a [Prettier
+  config file](https://prettier.io/docs/configuration.html)

docs/contributor-docs/v11-upgrade-guide.md

@@ -76,6 +76,7 @@ const finalConfig = tseslint.config(
     // https://github.com/eslint/eslint/discussions/18304#discussioncomment-9069706
     ignores: [ // global ignores
       "**/node_modules/**",
+      "packages/ui-codemods/lib/__node_tests__/__testfixtures__/**",
       "**/types/**",
       "**/es/**",
       "packages/!(" + NODE_PACKAGES + ")/lib/**/*",

eslint.config.mjs

@@ -309,7 +309,7 @@ class Hero extends Component<HeroProps> {
           </Flex>
           <List isUnstyled margin="small none none">
             <List.Item>
-              <Link href="#v10-upgrade-guide">Version 10 Upgrade Guide</Link>
+              <Link href="#upgrade-guide">Version 10 Upgrade Guide</Link>
             </List.Item>
             <List.Item>
               <Link href="#CHANGELOG">Change Log ({version})</Link>
@@ -486,7 +486,7 @@ class Hero extends Component<HeroProps> {
                       <Button
                         focusColor="inverse"
                         color="success"
-                        href="#v10-upgrade-guide"
+                        href="#upgrade-guide"
                         size={bigScreen ? 'large' : 'medium'}
                         margin="0 x-small x-small 0"
                       >

packages/__docs__/src/Hero/index.tsx

@@ -95,24 +95,3 @@ type: example
   <div>LTR text</div>
 </InstUISettingsProvider>
 ```
-
-### Server Side Rendering support
-
-The `instanceCounterMap` prop is used for deterministic id generation. The prop accepts a [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) (generated by the `generateInstanceCounterMap` util) that keeps the id-s of the components in sync on both the frontend and backend.
-
-See more info on the [Server Side Rendering (SSR)](/#server-side-rendering) docs page.
-
-```jsx
----
-  type: code
----
-import { InstUISettingsProvider } from '@instructure/emotion'
-import { generateInstanceCounterMap } from '@instructure/ui-react-utils'
-
-const counter = generateInstanceCounterMap()
-counter.set('Alert', 5)
-;<InstUISettingsProvider instanceCounterMap={counter}>
-  // this Alert's rendered DOM Node will have [id="Alert_5"] on it
-  <Alert>Test!</Alert>
-</InstUISettingsProvider>
-```

packages/emotion/src/InstUISettingsProvider/README.md

@@ -61,15 +61,17 @@ type InstUIProviderProps = {
        */
       dir: 'ltr' | 'rtl'
       /**
-       *  @deprecated remove in v11
+       *  @deprecated This prop will be removed in InstUI v11
+       *
        *  The element type to render as
        */
       as?: AsElementType
     }
   | {
       dir?: never
       /**
-       *  @deprecated remove in v11
+       *  @deprecated This prop will be removed in InstUI v11
+       *
        *  The element type to render as
        */
       as?: never

packages/emotion/src/InstUISettingsProvider/index.tsx

@@ -19,19 +19,20 @@ The codemod scripts can be installed via the following command:
 type: code
 ---
 # use here the InstUI version number you are upgrading to
-npm install @instructure/ui-codemods@10
+npm install @instructure/ui-codemods@11
 ```
 
-### Codemod for changing the color palette to the v10 color palette
+Then run them with `jscodeshift`:
 
 ```sh
 ---
 type: code
 ---
-npx [email protected] -t node_modules/@instructure/ui-codemods/lib/updateV10Breaking.ts <path> --usePrettier=false
+# substitute updateV10Breaking with the codemod name you want to run
+npx jscodeshift@latest -t node_modules/@instructure/ui-codemods/lib/updateV10Breaking.ts <path>
 ```
 
-This codemod updates the `canvas` and `canvas-high-contrast` color palettes. Execute this in your project post-upgrade to InstUI v10. Prettier is turned on by default for output formatting, and you can also use the `usePrettier` flag.
+For more information about what the codemods do, see the [major version upgrade guides](#upgrade-guide)
 
 [npm]: https://img.shields.io/npm/v/@instructure/ui-codemods.svg
 [npm-url]: https://npmjs.com/package/@instructure/ui-codemods

packages/ui-codemods/README.md

@@ -0,0 +1,33 @@
+// @ts-nocheck
+
+import { InstUISettingsProvider as ABC } from '@instructure/emotion'
+import { Button } from '@instructure/ui-buttons'
+
+function asd() {
+  const a = (
+    <ABC
+      as="div"
+      theme={{
+        componentOverrides: {
+          AppNav: { borderWidth: 0 },
+          'AppNav.Item': {
+            as: 23,
+            fontWeight: 400,
+            textColor: 'white',
+            textColorSelected: 'white'
+          }
+        }
+      }}
+    >
+      as
+      <Button as="div" />
+    </ABC>
+  )
+
+  return (
+    <ABC as={callHereAFunction('as')} dir="rtl">
+      as
+      <div dir="rtl">as</div>
+    </ABC>
+  )
+}