docs: S2 migration docs and codemod setup (#6828)

* initialize migration docs

* more docs for Item updates

* move upgrade-cli to codemods package

* improve rendered diffs

* setup codemod entry

* update yarn.lock

* fix component index path resolving

* update package.json

* update yarn.lock

* move to src

* update component index path

* update lock file

* fix ts

* update command in docs

* fix --components option for providing a subset of components to upgrade

* update docs to not collapse manual guide

* update index to use parseArgs and pass args into codemod functions

* just rely on require.resolve to get S2 index path

* remove commander dep

* move use-monopackages codemod into new package

* update @react-spectrum/s2 dep

* update yarn.lock

* fix types and update use-monopackages readme

* try removing main from package.json

* use path module

* use moduleResolution in tsconfig

* remove module.exports

* try renaming transformer functions

* Revert "try renaming transformer functions"

This reverts commit b2177f7.

* try targets: main: false in package.json

* move to packages/dev

* update docs

* add anchor links

* update yarn.lock

* fix anchor links in built docs

---------

Co-authored-by: Robert Snow <[email protected]>

Author: reidbarber

.storybook-s2/docs/Migrating.jsx

@@ -1,27 +1,56 @@
 import { style } from '../../packages/@react-spectrum/s2/style/spectrum-theme' with {type: 'macro'};
 import {Link} from '@react-spectrum/s2';
+import {useFocusRing, useHover} from 'react-aria';
+
+function AnchorLink({id, isHovered}) {
+  let { isFocusVisible, focusProps } = useFocusRing({within: true});
+  const url = `${location.origin}${location.pathname.replace('iframe', 'index')}${location.search.replace('viewMode=docs&id=', 'path=/docs/')}#${id}`;
+  return (
+    <span {...focusProps} style={{opacity: isHovered || isFocusVisible ? 1 : 0}}>
+      <Link href={url}>#</Link>
+    </span>
+  );
+}
 
 export function H2({children}) {
   let id = anchorId(children);
-  return <h2 className={style({font: 'heading-xl', marginTop: 48, marginBottom: 24})} id={id}>{children}</h2>
+  let {hoverProps, isHovered} = useHover({});
+  return (
+    <h2 className={style({font: 'heading-xl', marginTop: 48, marginBottom: 24, display: 'flex', alignItems: 'center', gap: 8})} id={id} {...hoverProps}>
+      {children}
+      <AnchorLink id={id} isHovered={isHovered} />
+    </h2>
+  )
 }
 
 export function H3({children}) {
   let id = anchorId(children);
-  return <h3 className={style({font: 'heading', marginTop: 32, marginBottom: 16})} id={anchorId(children)}>{children}</h3>
+  let {hoverProps, isHovered} = useHover({});
+  return (
+    <h3 className={style({font: 'heading', marginTop: 32, marginBottom: 16, display: 'flex', alignItems: 'center', gap: 8})} id={id} {...hoverProps}>
+      {children}
+      <AnchorLink id={id} isHovered={isHovered} />
+    </h3>
+  );
 }
 
 export function H4({children}) {
   let id = anchorId(children);
-  return <h4 className={style({font: 'heading-sm', marginTop: 32, marginBottom: 8})} id={anchorId(children)}>{children}</h4>
+  let {hoverProps, isHovered} = useHover({});
+  return (
+    <h4 className={style({font: 'heading-sm', marginTop: 32, marginBottom: 8, display: 'flex', alignItems: 'center', gap: 8})} id={id} {...hoverProps}>
+      {children}
+      <AnchorLink id={id} isHovered={isHovered} />
+    </h4>
+  );
 }
 
 export function P({children}) {
   return <p className={style({font: 'body-lg', marginTop: 0, marginBottom: 24})}>{children}</p>
 }
 
 export function Code({children}) {
-  return <code className={style({font: 'code-sm', backgroundColor: 'layer-1', paddingX: 4, borderWidth: 1, borderColor: 'gray-100', borderStyle: 'solid', borderRadius: 'sm'})}>{children}</code>;
+  return <code className={style({font: 'code-sm', backgroundColor: 'layer-1', paddingX: 4, borderWidth: 1, borderColor: 'gray-100', borderStyle: 'solid', borderRadius: 'sm', whiteSpace: 'pre-wrap'})}>{children}</code>;
 }
 
 export function Strong({children}) {

.storybook-s2/docs/Migrating.mdx

@@ -1,14 +1,16 @@
 {
-  "name": "@react-spectrum/upgrade-cli",
+  "name": "@react-spectrum/codemods",
   "version": "0.0.1",
   "private": true,
-  "source": "src/index.ts",
   "main": "dist/index.js",
-  "bin": {
-    "upgrade-react-spectrum": "./dist/index.js"
+  "source": "src/index.ts",
+  "bin": "dist/index.js",
+  "targets": {
+    "main": false
   },
   "scripts": {
-    "start": "node --loader=ts-node/esm src/index.ts"
+    "build": "tsc",
+    "prepublishOnly": "yarn build"
   },
   "files": [
     "dist"
@@ -23,12 +25,12 @@
     "@babel/parser": "^7.24.5",
     "@babel/traverse": "^7.24.5",
     "@babel/types": "^7.24.5",
+    "@react-spectrum/s2": "^0.2.0",
     "@react-types/shared": "^3.24.0",
     "@types/node": "^20",
     "boxen": "^5.1.2",
     "build": "^0.1.4",
     "chalk": "^4.0.0",
-    "commander": "^12.0.0",
     "execa": "^5.1.1",
     "jscodeshift": "^0.15.2",
     "ts-node": "^10.9.2",

.storybook-s2/docs/typography.js

@@ -0,0 +1,100 @@
+const {parseArgs} = require('node:util');
+import {s1_to_s2} from './s1-to-s2/src';
+import {use_monopackages} from './use-monopackages/src';
+
+interface JSCodeshiftOptions {
+  /**
+   * The parser for jscodeshift to use for parsing the source files: https://github.com/facebook/jscodeshift?tab=readme-ov-file#parser.
+   * 
+   * @default 'tsx'
+   */
+  parser?: 'babel' | 'babylon' | 'flow' | 'ts' |' tsx',
+  /**
+   * A glob pattern of files to ignore: https://github.com/facebook/jscodeshift?tab=readme-ov-file#ignoring-files-and-directories.
+   * 
+   * @default '*\*\/node_modules/*\*\'
+   */
+  ignorePattern?: string,
+  /**
+   * Whether to run the codemod in dry mode, which will not write any changes to disk.
+   * 
+   * @default false
+   */
+  dry?: boolean,
+  /**
+   * The path to the directory to run the codemod in.
+   * 
+   * @default '.'
+   */
+  path?: string
+}
+
+export interface S1ToS2CodemodOptions extends JSCodeshiftOptions {
+  /**
+   * An optional subset of components to have the s1-to-s2 codemod apply to.
+   * Provide a comma-separated list of component names.
+   */
+  components?: string
+}
+
+export interface UseMonopackagesCodemodOptions extends JSCodeshiftOptions {
+  /**
+   * The packages to apply the use-monopackages codemod to.
+   */
+  packages?: string
+}
+
+const codemods: Record<string, (options: S1ToS2CodemodOptions | UseMonopackagesCodemodOptions) => void> = {
+  's1-to-s2': s1_to_s2,
+  'use-monopackages': use_monopackages
+};
+
+// https://github.com/facebook/jscodeshift?tab=readme-ov-file#usage-cli
+const options = {
+  'parser': {
+    type: 'string'
+  },
+  'ignore-pattern': {
+    type: 'string'
+  },
+  'dry': {
+    type: 'boolean',
+    short: 'd'
+  },
+  'path': {
+    type: 'string'
+  },
+  'components': {
+    type: 'string'
+  }
+};
+
+const {values, positionals} = parseArgs({
+  options,
+  allowPositionals: true
+});
+
+if (positionals.length < 1) {
+  console.error('Please specify a codemod to run. Available codemods: ', Object.keys(codemods).join(', '));
+  process.exit(1);
+}
+
+const codemodName = positionals[0];
+const codemodFunction = codemods[codemodName];
+
+if (!codemodFunction) {
+  console.error(`Unknown codemod: ${codemodName}, available codemods: ${Object.keys(codemods).join(', ')}`);
+  process.exit(1);
+}
+
+try {  
+  codemodFunction({
+    parser: 'tsx',
+    ignorePattern: '**/node_modules/**',
+    path: '.',
+    ...values
+  });
+} catch (error) {
+  console.error(`Error running codemod: ${error}`);
+  process.exit(1);
+}