@planningcenter/tapestry-migration-cli 2.4.0-rc.9 → 2.4.1-rc.0

package/README.md

@@ -1,12 +1,106 @@
 # tapestry-migration-cli
 
-A simple cli tool used to help to migration Tapestry React components to formats that match Planning Center specs (usually to `@planningcenter/tapestry` components).
+A CLI tool to migrate Tapestry React components to Planning Center's Tapestry format.
 
-## Quick Use
+## Installation
 
 ```bash
-# For help
-npx @planningcenter/tapestry-migration-cli
-# Run a migration with autofixing
-npx @planningcenter/tapestry-migration-cli run ComponentName -p ./path/to/files -f
+yarn add --dev @planningcenter/tapestry-migration-cli
+```
+
+## Usage
+
+### Recommended Migration Order
+
+For optimal results, migrate components in this order:
+
+1. **Button components first**: `npx @planningcenter/tapestry-migration-cli run button -p ./src/components --fix`
+2. **Link components second**: `npx @planningcenter/tapestry-migration-cli run link -p ./src/components --fix`
+
+This order ensures that Button components with navigation props are properly handled before Link components are migrated.
+
+### Basic Commands
+
+```bash
+# Run a dry-run migration (preview changes)
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components
+
+# Apply the migration changes
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components --fix
+
+# Run with verbose output
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components --fix --verbose
+
+# Generate a migration report
+npx @planningcenter/tapestry-migration-cli run button -p ./src/components --fix --report-path ./migration-report.md
+```
+
+## Available Components
+
+- `button` - Migrate Button components
+- `link` - Migrate Link components
+
+## Required Arguments
+
+- `-p, --path <path>` - **REQUIRED**: Path to the folder or file to migrate
+
+## Optional Arguments
+
+- `-f, --fix` - Write changes to files (without this flag, it's a dry run)
+- `-v, --verbose` - Show detailed output
+- `-j, --js-theme <path>` - Path to JavaScript theme file
+- `-r, --report-path <path>` - Path for migration report (default: MIGRATION_REPORT.md)
+
+## How It Works
+
+The migration tool automatically transforms your components to match Planning Center's current Tapestry specifications. Most property and usage changes are handled automatically, including:
+
+- Converting deprecated props to their modern equivalents
+- Updating import statements and component references
+- Adjusting prop names and values to match current API
+
+### Unsupported Props
+
+For properties that cannot be automatically migrated, the tool will:
+
+1. **Keep the prop as-is** - The prop remains in your code but will not work with the new Tapestry component
+2. **Add a TODO comment** - Flagging the prop for manual migration
+
+Example of an unsupported prop comment:
+
+```tsx
+<Button
+  /* TODO: tapestry-migration (propName): 'mediaQueries' is not supported, please migrate as needed.
+   * It is recommended to use CSS media queries in a class that you apply to the component.
+   */
+  mediaQueries={{ mobile: { fontSize: 14 } }}
+>
+  Click me
+</Button>
+```
+
+The comment includes guidance on how to handle the unsupported prop. Common recommendations include:
+
+- Using CSS classes for styling instead of props
+- Moving state-based styles (hover, focus, active) to CSS selectors
+- Applying responsive styles through CSS media queries
+
+## Alternative: Local Installation
+
+If you prefer to install it locally and use a shorter command:
+
+```bash
+# Install locally
+yarn add --dev @planningcenter/tapestry-migration-cli
+
+# Add to package.json scripts
+{
+  "scripts": {
+    "migrate": "tapestry-migration-cli"
+  }
+}
+
+# Then run (following recommended order)
+yarn migrate run button -p app/javascript/components --fix
+yarn migrate run link -p app/javascript/components --fix
 ```

package/dist/tapestry-react-shim.cjs

@@ -2681,7 +2681,7 @@ const PageHeaderActionsDropdownButton = reactExports.forwardRef(({ needsAttentio
 });
 PageHeaderActionsDropdownButton.displayName = "PageHeaderActionsDropdownButton";
 const buildComponentClassName = (size, kind, className) => {
-  return classNames(kind && "tds-btn", size && size !== "md" && kind && COMPONENT_SIZE_CLASS_MAP[size], kind && COMPONENT_KIND_CLASS_MAP[kind], className);
+  return classNames("tds-btn", size && size !== "md" && kind && COMPONENT_SIZE_CLASS_MAP[size], kind && COMPONENT_KIND_CLASS_MAP[kind], className);
 };
 const BaseLink = reactExports.forwardRef(({ size, prefix, suffix, kind, label, children, className, href, external = false, ...restProps }, ref) => {
   const combinedClassName = buildComponentClassName(size, kind, className);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planningcenter/tapestry-migration-cli",
-  "version": "2.4.0-rc.9",
+  "version": "2.4.1-rc.0",
   "description": "CLI tool for Tapestry migrations",
   "type": "module",
   "main": "dist/index.js",
@@ -51,5 +51,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "354ebc1e0619c2e82f46fe9b9c981b674803af3d"
+  "gitHead": "c643ce32f1e79ee51403daeaaeac4940729ab69d"
 }

package/src/components/button/index.ts

@@ -8,7 +8,7 @@ import convertStyleProps from "./transforms/convertStyleProps"
 import iconLeftToPrefix from "./transforms/iconLeftToPrefix"
 import iconRightToSuffix from "./transforms/iconRightToSuffix"
 import iconToIconButton from "./transforms/iconToIconButton"
-import linkToButton from "./transforms/linkToButton"
+import innerRefToRef from "./transforms/innerRefToRef"
 import moveButtonImport from "./transforms/moveButtonImport"
 import removeAsButton from "./transforms/removeAsButton"
 import removeDuplicateKeys from "./transforms/removeDuplicateKeys"
@@ -47,7 +47,6 @@ const transform: Transform = async (fileInfo, api, options) => {
   }
 
   const transforms = [
-    linkToButton,
     tooltipToWrapper,
     iconRightToSuffix,
     iconLeftToPrefix,
@@ -55,16 +54,17 @@ const transform: Transform = async (fileInfo, api, options) => {
     themeVariantToKind,
     titleToLabel,
     childrenToLabel,
+    innerRefToRef,
     removeToTransform,
     removeDuplicateKeys,
     removeAsButton,
     removeTypeButton,
     auditSpreadProps,
     reviewStyles,
+    spinnerToLoadingButton,
     convertStyleProps,
     unsupportedProps,
     iconToIconButton,
-    spinnerToLoadingButton,
     moveButtonImport,
   ]
 

package/src/components/button/transforms/innerRefToRef.test.ts

@@ -0,0 +1,170 @@
+import jscodeshift from "jscodeshift"
+import { describe, expect, it } from "vitest"
+
+import transform from "./innerRefToRef"
+
+const j = jscodeshift.withParser("tsx")
+
+function applyTransform(source: string): string | null {
+  const fileInfo = { path: "test.tsx", source }
+  return transform(
+    fileInfo,
+    { j, jscodeshift: j, report: () => {}, stats: () => {} },
+    {}
+  ) as string | null
+}
+
+describe("innerRefToRef transform", () => {
+  describe("basic transformations", () => {
+    it("should transform Button 'innerRef' prop to 'ref' prop", () => {
+      const input = `
+import { Button } from "@planningcenter/tapestry-react"
+
+export default function Test() {
+  return <Button innerRef={buttonRef}>Click me</Button>
+}
+      `.trim()
+
+      const expected = `
+import { Button } from "@planningcenter/tapestry-react"
+
+export default function Test() {
+  return <Button ref={buttonRef}>Click me</Button>;
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toBe(expected)
+    })
+
+    it("should transform Button 'innerRef' prop to 'ref' prop with function", () => {
+      const input = `
+import { Button } from "@planningcenter/tapestry-react"
+
+export default function Test() {
+  return <Button innerRef={(el) => setButtonRef(el)}>Click me</Button>
+}
+      `.trim()
+
+      const expected = `
+import { Button } from "@planningcenter/tapestry-react"
+
+export default function Test() {
+  return <Button ref={(el) => setButtonRef(el)}>Click me</Button>;
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toBe(expected)
+    })
+
+    it("should transform Button 'innerRef' prop to 'ref' prop with useRef", () => {
+      const input = `
+import { Button } from "@planningcenter/tapestry-react"
+import { useRef } from "react"
+
+export default function Test() {
+  const buttonRef = useRef(null)
+  return <Button innerRef={buttonRef}>Click me</Button>
+}
+      `.trim()
+
+      const expected = `
+import { Button } from "@planningcenter/tapestry-react"
+import { useRef } from "react"
+
+export default function Test() {
+  const buttonRef = useRef(null)
+  return <Button ref={buttonRef}>Click me</Button>;
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toBe(expected)
+    })
+  })
+
+  describe("multiple components", () => {
+    it("should transform multiple Button components with innerRef", () => {
+      const input = `
+import { Button } from "@planningcenter/tapestry-react"
+
+export default function Test() {
+  return (
+    <div>
+      <Button innerRef={buttonRef1}>First</Button>
+      <Button innerRef={buttonRef2}>Second</Button>
+    </div>
+  )
+}
+      `.trim()
+
+      const expected = `
+import { Button } from "@planningcenter/tapestry-react"
+
+export default function Test() {
+  return (
+    <div>
+      <Button ref={buttonRef1}>First</Button>
+      <Button ref={buttonRef2}>Second</Button>
+    </div>
+  );
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toBe(expected)
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should not transform Button without innerRef", () => {
+      const input = `
+import { Button } from "@planningcenter/tapestry-react"
+
+export default function Test() {
+  return <Button onClick={handleClick}>Click me</Button>
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toBe(null)
+    })
+
+    it("should not transform other components with innerRef", () => {
+      const input = `
+import { Link } from "@planningcenter/tapestry-react"
+
+export default function Test() {
+  return <Link innerRef={linkRef}>Go somewhere</Link>
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toBe(null)
+    })
+
+    it("should preserve other props when transforming innerRef", () => {
+      const input = `
+import { Button } from "@planningcenter/tapestry-react"
+
+export default function Test() {
+  const buttonRef = null
+  return <Button innerRef={buttonRef} onClick={() => {}} disabled>Click me</Button>
+}
+      `.trim()
+
+      const expected = `
+import { Button } from "@planningcenter/tapestry-react"
+
+export default function Test() {
+  const buttonRef = null
+  return <Button ref={buttonRef} onClick={() => {}} disabled>Click me</Button>;
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toBe(expected)
+    })
+  })
+})

package/src/components/button/transforms/innerRefToRef.ts

@@ -0,0 +1,14 @@
+import { transformAttributeName } from "../../shared/actions/transformAttributeName"
+import { hasAttribute } from "../../shared/conditions/hasAttribute"
+import { attributeTransformFactory } from "../../shared/transformFactories/attributeTransformFactory"
+
+const transform = attributeTransformFactory({
+  condition: hasAttribute("innerRef"),
+  targetComponent: "Button",
+  targetPackage: "@planningcenter/tapestry-react",
+  transform: (element) => {
+    return transformAttributeName("innerRef", "ref", { element })
+  },
+})
+
+export default transform

package/src/components/button/transforms/unsupportedProps.ts

@@ -1,44 +1,21 @@
 import { JSXAttribute, Transform } from "jscodeshift"
 
-import { stylePropNames } from "../../../../dist/tapestry-react-shim.cjs"
 import { addCommentToUnsupportedProps } from "../../shared/actions/addCommentToUnsupportedProps"
+import { SUPPORTED_PROPS_BASE } from "../../shared/helpers/unsupportedPropsHelpers"
 import { attributeTransformFactory } from "../../shared/transformFactories/attributeTransformFactory"
 
-const SUPPORTED_PROPS = [
-  ...stylePropNames,
-  "children",
-  "className",
+const BUTTON_SPECIFIC_PROPS = [
   "disabled",
-  "kind",
-  "label",
-  "onClick",
-  "style",
-  "type",
-  "prefix",
-  "suffix",
-  "size",
   "fullWidth",
-  "needsAttention",
-  "key",
-  "external",
-  "id",
-  "onMouseOver",
-  "onMouseOut",
-  "onMouseDown",
-  "onMouseUp",
-  "onKeyUp",
-  "icon",
-  "weight",
-  "tabIndex",
-  "onKeyDown",
-  "onFocus",
-  "onBlur",
-  "role",
+  "loading",
+  "loadingAriaLabel",
   "name",
-  "ref",
-  "spinner", // taken care of by spinnerToLoadingButton transform
+  "type",
+  "icon",
 ]
 
+const SUPPORTED_PROPS = [...SUPPORTED_PROPS_BASE, ...BUTTON_SPECIFIC_PROPS]
+
 const transform: Transform = attributeTransformFactory({
   targetComponent: "Button",
   targetPackage: "@planningcenter/tapestry-react",

package/src/components/checkbox/index.ts

@@ -0,0 +1,38 @@
+import { Transform } from "jscodeshift"
+
+import childrenToLabel from "./transforms/childrenToLabel"
+import convertStyleProps from "./transforms/convertStyleProps"
+import innerRefToRef from "./transforms/innerRefToRef"
+import moveCheckboxImport from "./transforms/moveCheckboxImport"
+import sizeMapping from "./transforms/sizeMapping"
+import unsupportedProps from "./transforms/unsupportedProps"
+
+const transform: Transform = (fileInfo, api, options) => {
+  let currentSource = fileInfo.source
+  let hasAnyChanges = false
+
+  const transforms = [
+    childrenToLabel,
+    sizeMapping,
+    innerRefToRef,
+    convertStyleProps,
+    unsupportedProps,
+    moveCheckboxImport,
+  ]
+
+  for (const individualTransform of transforms) {
+    const result = individualTransform(
+      { ...fileInfo, source: currentSource },
+      api,
+      options
+    )
+    if (result && result !== currentSource) {
+      currentSource = result as string
+      hasAnyChanges = true
+    }
+  }
+
+  return hasAnyChanges ? currentSource : null
+}
+
+export default transform

package/src/components/checkbox/transforms/childrenToLabel.test.ts

@@ -0,0 +1,146 @@
+import jscodeshift from "jscodeshift"
+import { describe, expect, it } from "vitest"
+
+import transform from "./childrenToLabel"
+
+const j = jscodeshift.withParser("tsx")
+
+function applyTransform(source: string): string {
+  const fileInfo = { path: "test.tsx", source }
+  const result = transform(
+    fileInfo,
+    { j, jscodeshift: j, report: () => {}, stats: () => {} },
+    {}
+  ) as string | null
+  return result || source
+}
+
+describe("childrenToLabel transform for Checkbox", () => {
+  describe("simple text conversion", () => {
+    it("should convert simple text children to label prop", () => {
+      const input = `
+import { Checkbox } from "@planningcenter/tapestry-react"
+
+function Test() {
+  return <Checkbox>Accept terms</Checkbox>
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toContain('<Checkbox label="Accept terms" />')
+      expect(result).not.toContain("Accept terms</Checkbox>")
+    })
+
+    it("should not convert when label prop already exists", () => {
+      const input = `
+import { Checkbox } from "@planningcenter/tapestry-react"
+
+function Test() {
+  return <Checkbox label="Already has label">Accept terms</Checkbox>
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toContain('label="Already has label"')
+      expect(result).toContain("Accept terms</Checkbox>")
+    })
+
+    it("should handle whitespace in text content", () => {
+      const input = `
+import { Checkbox } from "@planningcenter/tapestry-react"
+
+function Test() {
+  return <Checkbox>  Accept terms  </Checkbox>
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toContain('<Checkbox label="Accept terms" />')
+    })
+
+    it("should not convert complex children", () => {
+      const input = `
+import { Checkbox } from "@planningcenter/tapestry-react"
+
+function Test() {
+  return (
+    <Checkbox>
+      <span>Accept</span> terms
+    </Checkbox>
+  )
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).not.toContain("label=")
+      expect(result).toContain("<span>Accept</span>terms")
+      expect(result).toContain(
+        "TODO: tapestry-migration (children): complex children cannot be converted to label prop"
+      )
+    })
+
+    it("should not convert when children contain JSX elements", () => {
+      const input = `
+import { Checkbox } from "@planningcenter/tapestry-react"
+
+function Test() {
+  return (
+    <Checkbox>
+      Accept <strong>terms</strong>
+    </Checkbox>
+  )
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).not.toContain("label=")
+      expect(result).toContain("Accept <strong>terms</strong>")
+      expect(result).toContain(
+        "TODO: tapestry-migration (children): complex children cannot be converted to label prop"
+      )
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should handle empty children", () => {
+      const input = `
+import { Checkbox } from "@planningcenter/tapestry-react"
+
+function Test() {
+  return <Checkbox></Checkbox>
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toContain("<Checkbox></Checkbox>")
+    })
+
+    it("should handle self-closing checkbox", () => {
+      const input = `
+import { Checkbox } from "@planningcenter/tapestry-react"
+
+function Test() {
+  return <Checkbox />
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toContain("<Checkbox />")
+    })
+
+    it("should handle checkbox with other props", () => {
+      const input = `
+import { Checkbox } from "@planningcenter/tapestry-react"
+
+function Test() {
+  return <Checkbox checked disabled>Accept terms</Checkbox>
+}
+      `.trim()
+
+      const result = applyTransform(input)
+      expect(result).toContain(
+        '<Checkbox checked disabled label="Accept terms" />'
+      )
+    })
+  })
+})

package/src/components/checkbox/transforms/childrenToLabel.ts

@@ -0,0 +1,54 @@
+import { Transform } from "jscodeshift"
+
+import { addAttribute } from "../../shared/actions/addAttribute"
+import { addComment } from "../../shared/actions/addComment"
+import { removeChildren } from "../../shared/actions/removeChildren"
+import { hasAttribute } from "../../shared/conditions/hasAttribute"
+import { hasChildren } from "../../shared/conditions/hasChildren"
+import {
+  buildComment,
+  extractTextContent,
+} from "../../shared/helpers/childrenToLabelHelpers"
+import { attributeTransformFactory } from "../../shared/transformFactories/attributeTransformFactory"
+
+const transform: Transform = attributeTransformFactory({
+  condition: hasChildren,
+  targetComponent: "Checkbox",
+  targetPackage: "@planningcenter/tapestry-react",
+  transform: (element, { j, source }) => {
+    if (hasAttribute("label")(element)) {
+      addComment({
+        element,
+        j,
+        scope: "label",
+        source,
+        text: buildComment("Checkbox has both label prop and children", false),
+      })
+      return true
+    }
+
+    const { isSimpleText, textContent } = extractTextContent(element.children!)
+
+    if (isSimpleText && textContent) {
+      addAttribute({ element, j, name: "label", value: textContent })
+      removeChildren(element)
+      return true
+    } else if (!isSimpleText) {
+      addComment({
+        element,
+        j,
+        scope: "children",
+        source,
+        text: buildComment(
+          "complex children cannot be converted to label prop",
+          true
+        ),
+      })
+      return true
+    }
+
+    return false
+  },
+})
+
+export default transform