@planningcenter/tapestry-migration-cli 3.2.2-rc.9 → 3.2.3-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planningcenter/tapestry-migration-cli",
-  "version": "3.2.2-rc.9",
+  "version": "3.2.3-rc.0",
   "description": "CLI tool for Tapestry migrations",
   "type": "module",
   "main": "dist/index.js",
@@ -32,7 +32,7 @@
   },
   "devDependencies": {
     "@emotion/react": "^11.14.0",
-    "@planningcenter/tapestry": "^3.2.2-rc.9",
+    "@planningcenter/tapestry": "^3.2.3-rc.0",
     "@planningcenter/tapestry-react": "^4.11.5",
     "@types/jscodeshift": "^17.3.0",
     "@types/node": "^20.0.0",
@@ -52,5 +52,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "4810e0377bd9ec8ee2c3ea474741af940ec9406e"
+  "gitHead": "e944c237ec8b2e0318f53f8a8a2a3b31b6e28a81"
 }

package/src/components/shared/helpers/unsupportedPropsHelpers.ts

@@ -151,3 +151,27 @@ export const TEXTAREA_SUPPORTED_PROPS = [
   ...TEXTAREA_SPECIFIC_PROPS,
   ...STYLE_PROP_NAMES_WITHOUT_CSS,
 ]
+
+export const TIME_FIELD_SPECIFIC_PROPS = [
+  "defaultValue",
+  "description",
+  "disabled",
+  "forceLeadingZeros",
+  "form",
+  "hideLabel",
+  "hideTimeZone",
+  "hourCycle",
+  "invalid",
+  "max",
+  "min",
+  "name",
+  "onChange",
+  "readOnly",
+  "required",
+  "value",
+]
+
+export const TIME_FIELD_SUPPORTED_PROPS = [
+  ...COMMON_PROPS,
+  ...TIME_FIELD_SPECIFIC_PROPS,
+]

package/src/components/shared/transformFactories/stylePropTransformFactory.test.ts

@@ -0,0 +1,330 @@
+import jscodeshift from "jscodeshift"
+import { describe, expect, it } from "vitest"
+
+import { stackViewPlugin } from "../../../stubs/stackViewPlugin"
+import { stylePropTransformFactory } from "./stylePropTransformFactory"
+
+const j = jscodeshift.withParser("tsx")
+
+function applyTransform(
+  transform: ReturnType<typeof stylePropTransformFactory>,
+  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("stylePropTransformFactory", () => {
+  describe("grid alias remapping", () => {
+    const transform = stylePropTransformFactory({
+      stylesToRemove: [],
+      targetComponent: "Box",
+      targetPackage: "@planningcenter/tapestry-react",
+    })
+
+    it("remaps column/row string props to gridColumn/gridRow via splitStyles", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box column="1 / 3" row="2 / 4" />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box
+          style={{
+            gridColumn: "1 / 3",
+            gridRow: "2 / 4"
+          }} />"
+      `)
+    })
+
+    it("remaps column/row expression props to gridColumn/gridRow", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box column={1} row={2} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box
+          style={{
+            gridColumn: 1,
+            gridRow: 2
+          }} />"
+      `)
+    })
+
+    it("remaps column/row identifier expression props to gridColumn/gridRow", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box column={col} row={r} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box
+          style={{
+            gridColumn: col,
+            gridRow: r
+          }} />"
+      `)
+    })
+
+    it("remaps columnStart/columnEnd/rowStart/rowEnd expression props", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box columnStart={1} columnEnd={3} rowStart={2} rowEnd={4} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box
+          style={{
+            gridColumnStart: 1,
+            gridColumnEnd: 3,
+            gridRowStart: 2,
+            gridRowEnd: 4
+          }} />"
+      `)
+    })
+
+    it("remaps direction expression prop to flexDirection", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box direction={dir} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box style={{
+          flexDirection: dir
+        }} />"
+      `)
+    })
+
+    // Conditional expressions can't be evaluated at codemod time, so they
+    // bypass splitStyles and land in directProps as raw source. Without the
+    // alias map, the resulting `style` object would contain non-CSS keys
+    // like `column` / `row` instead of `gridColumn` / `gridRow`.
+    it("remaps column/row ternary expression props to gridColumn/gridRow", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box column={filter ? '1' : '2'} row={filter ? '2' : undefined} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box
+          style={{
+            gridColumn: filter ? '1' : '2',
+            gridRow: filter ? '2' : undefined
+          }} />"
+      `)
+    })
+  })
+
+  describe("non-aliased style props", () => {
+    const transform = stylePropTransformFactory({
+      stylesToRemove: [],
+      targetComponent: "Box",
+      targetPackage: "@planningcenter/tapestry-react",
+    })
+
+    it("preserves the prop name for non-aliased identifier expression props", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box marginTop={spacing} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box style={{
+          marginTop: spacing
+        }} />"
+      `)
+    })
+  })
+
+  describe("value-transforming aliases", () => {
+    const transform = stylePropTransformFactory({
+      stylesToRemove: [],
+      targetComponent: "Box",
+      targetPackage: "@planningcenter/tapestry-react",
+    })
+
+    it("comments out the renamed `wrap` → `flexWrap` and emits a TODO for expression values", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box wrap={someBool} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";/* TODO: tapestry-migration (styleProp): migrated from \`wrap\`; value may need manual transformation: flexWrap: someBool */
+        <Box />"
+      `)
+    })
+
+    it("comments out renamed `grow`/`shrink`/`basis` props with TODOs", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box grow={g} shrink={s} basis={b} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";/* TODO: tapestry-migration (styleProp): migrated from \`grow\`; value may need manual transformation: flexGrow: g */
+        /* TODO: tapestry-migration (styleProp): migrated from \`shrink\`; value may need manual transformation: flexShrink: s */
+        /* TODO: tapestry-migration (styleProp): migrated from \`basis\`; value may need manual transformation: flexBasis: b */
+        <Box />"
+      `)
+    })
+
+    it("comments out fanned-out `marginHorizontal` → marginLeft/marginRight with a TODO", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box marginHorizontal={spacing} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";/* TODO: tapestry-migration (styleProp): migrated from \`marginHorizontal\`; value may need manual transformation: marginLeft: spacing; marginRight: spacing */
+        <Box />"
+      `)
+    })
+
+    it("anchors commented-out renamed-key props inline when a real style key is present", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box wrap={someBool} marginTop={spacing} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box
+          style={{
+            /* TODO: tapestry-migration (styleProp): migrated from \`wrap\`; value may need manual transformation */
+            // flexWrap: someBool,
+            marginTop: spacing
+          }} />"
+      `)
+    })
+
+    it("comments out fanned-out `paddingVertical` → paddingTop/paddingBottom", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box paddingVertical={p} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";/* TODO: tapestry-migration (styleProp): migrated from \`paddingVertical\`; value may need manual transformation: paddingTop: p; paddingBottom: p */
+        <Box />"
+      `)
+    })
+
+    it("comments out fanned-out `radius` → all four borderRadius corners", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box radius={r} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";/* TODO: tapestry-migration (styleProp): migrated from \`radius\`; value may need manual transformation: borderTopLeftRadius: r; borderTopRightRadius: r; borderBottomRightRadius: r; borderBottomLeftRadius: r */
+        <Box />"
+      `)
+    })
+
+    it("comments out fanned-out `radiusTop` → the two top corners only", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box radiusTop={rt} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";/* TODO: tapestry-migration (styleProp): migrated from \`radiusTop\`; value may need manual transformation: borderTopLeftRadius: rt; borderTopRightRadius: rt */
+        <Box />"
+      `)
+    })
+
+    // `x`, `y`, `rotate`, `scale`, `elevation` produce CSS by combining
+    // multiple values or by theme lookup, so we comment out a draft of the
+    // target CSS property under the migrated name.
+    it("comments out `x` → `transform` anchored to the next style key", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box x={dx} marginLeft={ml} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box
+          style={{
+            /* TODO: tapestry-migration (styleProp): migrated from \`x\`; value may need manual transformation */
+            // transform: dx,
+            marginLeft: ml
+          }} />"
+      `)
+    })
+
+    it("commented-out-only elements emit JSX-level TODO comments and no style attribute", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box x={dx} y={dy} rotate={r} elevation={e} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";/* TODO: tapestry-migration (styleProp): migrated from \`x\`; value may need manual transformation: transform: dx */
+        /* TODO: tapestry-migration (styleProp): migrated from \`y\`; value may need manual transformation: transform: dy */
+        /* TODO: tapestry-migration (styleProp): migrated from \`rotate\`; value may need manual transformation: transform: r */
+        /* TODO: tapestry-migration (styleProp): migrated from \`elevation\`; value may need manual transformation: boxShadow: e */
+        <Box />"
+      `)
+    })
+
+    it("primitive `x` literals still go through splitStyles and produce a transform string", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box x={5} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box style={{
+          transform: "translateX(5) "
+        }} />"
+      `)
+    })
+
+    it("does not emit a TODO comment for safely renamed grid aliases", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box column={col} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box style={{
+          gridColumn: col
+        }} />"
+      `)
+    })
+
+    // Literal values flow through splitStyles, which expands shorthands like
+    // `marginHorizontal` into the underlying CSS properties. No TODO needed.
+    it("expands `marginHorizontal` string literals via splitStyles without a TODO", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box marginHorizontal="8px" />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box style={{
+          marginRight: "8px",
+          marginLeft: "8px"
+        }} />"
+      `)
+    })
+
+    it("expands `paddingHorizontal` numeric literals via splitStyles without a TODO", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box paddingHorizontal={1} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box style={{
+          paddingRight: "8px",
+          paddingLeft: "8px"
+        }} />"
+      `)
+    })
+
+    it("transforms `wrap`/`grow` boolean literals via splitStyles without a TODO", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box wrap={true} grow={true} />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box
+          style={{
+            flexWrap: "wrap",
+            flexGrow: 1
+          }} />"
+      `)
+    })
+
+    it("expands `radius` shortcut strings via splitStyles without a TODO", () => {
+      const input = `import { Box } from "@planningcenter/tapestry-react";<Box radius="pill" />`
+      const result = applyTransform(transform, input)
+      expect(result).toMatchInlineSnapshot(`
+        "import { Box } from "@planningcenter/tapestry-react";<Box style={{
+          borderRadius: "10em"
+        }} />"
+      `)
+    })
+  })
+
+  describe("non-inlineable plugin output", () => {
+    // stackViewPlugin maps `distribution: "fill"` to `{ "& > *": { flex: "1 0 0px" } }`,
+    // a nested CSS selector that cannot be represented as a React `style={}` object.
+    // The transform must not crash, must not silently drop the source props, and must
+    // leave an audit trail for manual review.
+    const transform = stylePropTransformFactory({
+      plugin: stackViewPlugin,
+      stylesToRemove: [],
+      targetComponent: "Stack",
+      targetPackage: "@planningcenter/tapestry-react",
+    })
+
+    it("preserves source props and emits an audit comment when plugin output includes nested CSS selectors", () => {
+      const input = `import { Stack } from "@planningcenter/tapestry-react";<Stack axis="horizontal" spacing={1} distribution="fill" />`
+      const result = applyTransform(transform, input)
+
+      // Source props must remain — they cannot be safely inlined.
+      expect(result).toContain('axis="horizontal"')
+      expect(result).toContain("spacing={1}")
+      expect(result).toContain('distribution="fill"')
+      // Must not have produced a broken inline style with a nested object.
+      expect(result).not.toContain('"& > *"')
+      // Must leave a visible audit trail so the user knows to review.
+      expect(result).toMatch(/TODO:\s*tapestry-migration/)
+    })
+
+    it("does not crash on distribution='fill' alongside other plugin props", () => {
+      const input = `import { Stack } from "@planningcenter/tapestry-react";<Stack distribution="fill" axis="horizontal" />`
+      const result = applyTransform(transform, input)
+
+      expect(result).toContain('distribution="fill"')
+      expect(result).toContain('axis="horizontal"')
+    })
+  })
+})

package/src/components/shared/transformFactories/stylePropTransformFactory.ts

@@ -12,7 +12,7 @@ import {
   splitStyles,
   stylePropNames,
 } from "../../../../dist/tapestry-react-shim.cjs"
-import { addComment } from "../../shared/actions/addComment"
+import { addComment, formatComment } from "../../shared/actions/addComment"
 import { addCommentToAttribute } from "../../shared/actions/addCommentToAttribute"
 import { getAttribute } from "../../shared/actions/getAttribute"
 import { removeAttribute } from "../../shared/actions/removeAttribute"
@@ -27,6 +27,49 @@ type StylePropMapping = Record<
   }
 >
 
+// JSX expression values bypass splitStyles, so we mirror its plugin behavior
+// for props that bypass it. Pure key renames pass through live; everything
+// else gets commented out under the css target(s) so the developer can verify
+// the value before enabling.
+const liveAliases: Record<string, string> = {
+  column: "gridColumn",
+  columnEnd: "gridColumnEnd",
+  columnStart: "gridColumnStart",
+  direction: "flexDirection",
+  row: "gridRow",
+  rowEnd: "gridRowEnd",
+  rowStart: "gridRowStart",
+}
+
+const commentedAliases: Record<string, string[]> = {
+  basis: ["flexBasis"],
+  elevation: ["boxShadow"],
+  grow: ["flexGrow"],
+  marginHorizontal: ["marginLeft", "marginRight"],
+  marginVertical: ["marginTop", "marginBottom"],
+  paddingHorizontal: ["paddingLeft", "paddingRight"],
+  paddingVertical: ["paddingTop", "paddingBottom"],
+  radius: [
+    "borderTopLeftRadius",
+    "borderTopRightRadius",
+    "borderBottomRightRadius",
+    "borderBottomLeftRadius",
+  ],
+  radiusBottom: ["borderBottomRightRadius", "borderBottomLeftRadius"],
+  radiusLeft: ["borderTopLeftRadius", "borderBottomLeftRadius"],
+  radiusRight: ["borderTopRightRadius", "borderBottomRightRadius"],
+  radiusTop: ["borderTopLeftRadius", "borderTopRightRadius"],
+  rotate: ["transform"],
+  scale: ["transform"],
+  shrink: ["flexShrink"],
+  strokeAlign: ["strokeAlign"],
+  strokeWeight: ["strokeWeight"],
+  uppercase: ["textTransform"],
+  wrap: ["flexWrap"],
+  x: ["transform"],
+  y: ["transform"],
+}
+
 function extractPropValue(attr: JSXAttribute, j: JSCodeshift) {
   if (!attr.value) {
     return true
@@ -50,22 +93,36 @@ function extractPropValue(attr: JSXAttribute, j: JSCodeshift) {
   }
 }
 
+type ManualReviewEntry = {
+  cssTargets: string[]
+  originalProp: string
+  originalValue: string
+}
+
+function reviewHeading(entry: ManualReviewEntry) {
+  return `migrated from \`${entry.originalProp}\`; value may need manual transformation`
+}
+
+function reviewBody(entry: ManualReviewEntry) {
+  return entry.cssTargets.map((key) => `${key}: ${entry.originalValue}`)
+}
+
 function processKeepStyleProps({
   attributes,
   j,
-  element,
-  source,
 }: {
   attributes: JSXAttribute[]
-  element: JSXElement
   j: JSCodeshift
-  source: Collection
 }): {
   directProps: Record<string, unknown>
+  manualReviewEntries: ManualReviewEntry[]
+  processedNames: string[]
   themeProps: Record<string, unknown>
 } {
   const themeProps: Record<string, unknown> = {}
   const directProps: Record<string, unknown> = {}
+  const manualReviewEntries: ManualReviewEntry[] = []
+  const processedNames: string[] = []
 
   attributes.forEach((attr) => {
     const propName = attr.name.name as string
@@ -76,15 +133,32 @@ function processKeepStyleProps({
       propValue.startsWith("{") &&
       propValue.endsWith("}")
     ) {
-      directProps[propName] = propValue
+      if (propName in commentedAliases) {
+        manualReviewEntries.push({
+          cssTargets: commentedAliases[propName],
+          originalProp: propName,
+          originalValue: propValue.slice(1, -1),
+        })
+      } else {
+        directProps[liveAliases[propName] ?? propName] = propValue
+      }
     } else {
       themeProps[propName] = propValue
     }
 
-    removeAttribute(propName, { element, j, source })
+    processedNames.push(propName)
   })
 
-  return { directProps, themeProps }
+  return { directProps, manualReviewEntries, processedNames, themeProps }
+}
+
+function isInlineableStyleValue(value: unknown): boolean {
+  return (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  )
 }
 
 function processRemoveStyleProps({
@@ -160,20 +234,36 @@ function processStylePropMappings({
   return styleProps
 }
 
+function buildManualReviewComments(
+  entries: ManualReviewEntry[],
+  j: JSCodeshift
+) {
+  return entries.flatMap((entry) => [
+    j.commentBlock(
+      formatComment(reviewHeading(entry), "styleProp"),
+      true,
+      false
+    ),
+    ...reviewBody(entry).map((line) => j.commentLine(` ${line},`)),
+  ])
+}
+
 function applyStylesToComponent({
   j,
   element,
   styles,
+  manualReviewEntries = [],
 }: {
   element: JSXElement
   j: JSCodeshift
+  manualReviewEntries?: ManualReviewEntry[]
   source: Collection
   styles: Record<string, unknown>
 }) {
   const styleAttr = getAttribute({ element, name: "style" })
   const styleValue = j.jsxExpressionContainer(
     j.objectExpression(
-      Object.entries(styles).map(([key, value]) => {
+      Object.entries(styles).map(([key, value], index) => {
         let valueNode
         if (
           typeof value === "string" &&
@@ -198,7 +288,11 @@ function applyStylesToComponent({
           valueNode = j.literal(value as string | number | boolean | null)
         }
 
-        return j.objectProperty(j.identifier(key), valueNode)
+        const property = j.objectProperty(j.identifier(key), valueNode)
+        if (index === 0 && manualReviewEntries.length > 0) {
+          property.comments = buildManualReviewComments(manualReviewEntries, j)
+        }
+        return property
       })
     )
   )
@@ -286,6 +380,7 @@ export function stylePropTransformFactory(config: {
     const allAttributes = element.openingElement.attributes || []
     let allStyleProps: Record<string, unknown> = {}
     let directStyleProps: Record<string, unknown> = {}
+    const manualReviewEntries: ManualReviewEntry[] = []
     const attributes = allAttributes.filter((attr) => {
       if (attr.type !== "JSXAttribute") return false
       const name = attr.name?.name as string
@@ -307,9 +402,7 @@ export function stylePropTransformFactory(config: {
     )
     const keepResult = processKeepStyleProps({
       attributes: keepAttributes,
-      element,
       j,
-      source,
     })
     allStyleProps = {
       ...allStyleProps,
@@ -319,6 +412,7 @@ export function stylePropTransformFactory(config: {
       ...directStyleProps,
       ...keepResult.directProps,
     }
+    manualReviewEntries.push(...keepResult.manualReviewEntries)
 
     allStyleProps = {
       ...allStyleProps,
@@ -343,7 +437,8 @@ export function stylePropTransformFactory(config: {
 
     if (
       Object.keys(allStyleProps).length > 0 ||
-      Object.keys(directStyleProps).length > 0
+      Object.keys(directStyleProps).length > 0 ||
+      manualReviewEntries.length > 0
     ) {
       try {
         let styles: Record<string, unknown> = {}
@@ -360,8 +455,39 @@ export function stylePropTransformFactory(config: {
         styles = { ...styles, ...directStyleProps }
         if (options.verbose) console.log("Final generated styles:", styles)
 
-        if (Object.keys(styles).length > 0) {
-          applyStylesToComponent({ element, j, source, styles })
+        // Plugins like stackViewPlugin can emit nested CSS selectors (e.g.
+        // `{ "& > *": { flex: "1 0 0px" } }` from `distribution: "fill"`)
+        // that can't be represented in React's inline `style={}`. Preserve
+        // the source props so nothing is silently dropped and flag for review.
+        const nonInlineableKeys = Object.entries(styles)
+          .filter(([, v]) => !isInlineableStyleValue(v))
+          .map(([k]) => k)
+        if (nonInlineableKeys.length > 0) {
+          addComment({
+            element,
+            j,
+            scope: "styleProp",
+            source,
+            text: `Could not migrate style props (${keepResult.processedNames.join(
+              ", "
+            )}) — produced non-inlineable style values (${nonInlineableKeys.join(
+              ", "
+            )}) that don't fit in inline style (for example, nested selectors). Manual review required.`,
+          })
+        } else {
+          for (const propName of keepResult.processedNames) {
+            removeAttribute(propName, { element, j, source })
+          }
+        }
+
+        if (nonInlineableKeys.length === 0 && Object.keys(styles).length > 0) {
+          applyStylesToComponent({
+            element,
+            j,
+            manualReviewEntries,
+            source,
+            styles,
+          })
 
           if (options.verbose) {
             const styleAttr = getAttribute({ element, name: "style" })
@@ -381,6 +507,21 @@ export function stylePropTransformFactory(config: {
               }
             }
           }
+        } else if (
+          nonInlineableKeys.length === 0 &&
+          manualReviewEntries.length > 0
+        ) {
+          // No anchoring property in the style block — emit each manual-review
+          // entry as a JSX-level TODO comment instead.
+          for (const entry of manualReviewEntries) {
+            addComment({
+              element,
+              j,
+              scope: "styleProp",
+              source,
+              text: `${reviewHeading(entry)}: ${reviewBody(entry).join("; ")}`,
+            })
+          }
         }
       } catch (error) {
         console.log("Error processing style props:", error)