styled-components-to-stylex-codemod 0.0.9 → 0.0.10

package/dist/logger-DC-1uogs.d.mts

@@ -0,0 +1,452 @@
+//#region src/adapter.d.ts
+/**
+ * Adapter entry point for customizing the codemod.
+ * Core concepts: value resolution hooks and adapter validation.
+ */
+type ThemeResolveContext = {
+  kind: "theme";
+  path: string;
+  /**
+   * Absolute path of the file currently being transformed.
+   * Useful for adapter logic that wants to branch by caller file.
+   */
+  filePath: string;
+  /**
+   * Source location (line/column) of the expression being resolved.
+   * Useful for error reporting.
+   */
+  loc?: {
+    line: number;
+    column: number;
+  };
+};
+type CssVariableResolveContext = {
+  kind: "cssVariable";
+  name: string;
+  fallback?: string;
+  definedValue?: string;
+  /**
+   * Absolute path of the file currently being transformed.
+   * Useful for adapter logic that wants to branch by caller file.
+   */
+  filePath: string;
+  /**
+   * Source location (line/column) of the expression being resolved.
+   * Useful for error reporting.
+   */
+  loc?: {
+    line: number;
+    column: number;
+  };
+};
+type ImportedValueResolveContext = {
+  kind: "importedValue";
+  /**
+   * Imported name of the binding used in the interpolation.
+   * Example: `import { zIndex as z } from "./lib"` -> importedName: "zIndex"
+   */
+  importedName: string;
+  /**
+   * Import source for the binding.
+   */
+  source: ImportSource;
+  /**
+   * Member path from the imported binding (if any).
+   * Example: `zIndex.popover` -> "popover"
+   */
+  path?: string;
+  /**
+   * Absolute path of the file currently being transformed.
+   * Useful for adapter logic that wants to branch by caller file.
+   */
+  filePath: string;
+  /**
+   * Source location (line/column) of the expression being resolved.
+   * Useful for error reporting.
+   */
+  loc?: {
+    line: number;
+    column: number;
+  };
+};
+type CallResolveContext = {
+  /**
+   * Absolute path of the file currently being transformed.
+   * Useful for adapter logic that wants to branch by caller file.
+   */
+  callSiteFilePath: string;
+  /**
+   * Imported name when the callee is a named import (including aliases).
+   * Example: `import { transitionSpeed as ts } ...; ts("x")` -> "transitionSpeed"
+   */
+  calleeImportedName: string;
+  /**
+   * Import source for this call: either an absolute file path (relative imports)
+   * or the module specifier (package imports).
+   */
+  calleeSource: {
+    kind: "absolutePath";
+    value: string;
+  } | {
+    kind: "specifier";
+    value: string;
+  };
+  /**
+   * Call arguments.
+   * - literals are surfaced precisely
+   * - theme member access can be surfaced as `{ kind: "theme", path }`
+   * - everything else is `unknown`
+   */
+  args: Array<{
+    kind: "literal";
+    value: string | number | boolean | null;
+  } | {
+    kind: "theme";
+    path: string;
+  } | {
+    kind: "unknown";
+  }>;
+  /**
+   * Source location (line/column) of the call expression being resolved.
+   * Useful for error reporting.
+   */
+  loc?: {
+    line: number;
+    column: number;
+  };
+  /**
+   * CSS property being set (when available).
+   * Useful for adapters to return different results for directional properties.
+   * Example: "border-left", "border", "color"
+   */
+  cssProperty?: string;
+};
+/**
+ * Context for `adapter.resolveValue(...)` (theme + css variables + imported values).
+ *
+ * Helper calls are handled separately via `adapter.resolveCall(...)`.
+ */
+type ResolveValueContext = ThemeResolveContext | CssVariableResolveContext | ImportedValueResolveContext;
+/**
+ * Result for `adapter.resolveValue(...)` (theme + css variables + imported values).
+ */
+type ResolveValueResult = {
+  /**
+   * JS expression string to inline into generated output.
+   * Example: `vars.spacingSm` or `calcVars.baseSize`
+   */
+  expr: string;
+  /**
+   * Import statements required by `expr`.
+   * These are rendered and merged into the file by the codemod.
+   */
+  imports: ImportSpec[];
+  /**
+   * If true, the transformer should drop the corresponding `--name: ...` definition
+   * from the emitted style object (useful when replacing with StyleX vars).
+   *
+   * Note: Only meaningful for `{ kind: "cssVariable" }`.
+   */
+  dropDefinition?: boolean;
+  /**
+   * Disambiguates how the resolved expression is used:
+   * - "props": a StyleX style object suitable for passing to `stylex.props(...)`.
+   *   Use this when resolving imported styled component mixins to their StyleX equivalent.
+   * - undefined (default): a value that can be used inside `stylex.create(...)`.
+   *
+   * Note: Only meaningful for `{ kind: "importedValue" }`.
+   */
+  usage?: "props";
+};
+type CallResolveResult = {
+  /**
+   * JS expression string to inline into generated output.
+   *
+   * The codemod determines how to use this expression based on context:
+   * - If called with a CSS property (e.g., `border: ${helper()}`) → used as a CSS value
+   * - If called without a CSS property (e.g., `${helper()}`) → used as a StyleX style object
+   *
+   * Use `ctx.cssProperty` to check the context and return the appropriate expression.
+   *
+   * Example (CSS value): `\`1px solid \${$colors.labelMuted}\``
+   * Example (StyleX reference): `helpers.truncate`
+   */
+  expr: string;
+  /**
+   * Import statements required by `expr`.
+   * These are rendered and merged into the file by the codemod.
+   */
+  imports: ImportSpec[];
+  /**
+   * Disambiguates how the resolved expression is used:
+   * - `"create"`: Use as a CSS value in `stylex.create()` property values
+   * - `"props"`: Use as a StyleX styles reference in `stylex.props()`
+   *
+   * When not specified, the codemod infers from context:
+   * - If `cssProperty` exists → treated as `"create"`
+   * - If `cssProperty` doesn't exist → treated as `"props"`
+   *
+   * Use this field when the default inference is incorrect, such as when a helper
+   * returns a StyleX styles object even when used with a CSS property like `border:`.
+   */
+  usage?: "create" | "props";
+  /**
+   * Optional raw CSS text for helpers that return CSS declaration blocks.
+   *
+   * When provided alongside `usage: "props"`, the codemod can expand the CSS
+   * declarations for pseudo-selector wrapping. Without this, the codemod treats
+   * the resolved expression as opaque and cannot wrap individual properties
+   * inside pseudo selectors like `:hover`.
+   *
+   * Example: `"white-space: nowrap; overflow: hidden; text-overflow: ellipsis;"`
+   */
+  cssText?: string;
+};
+type ImportSource = {
+  kind: "absolutePath";
+  value: string;
+} | {
+  kind: "specifier";
+  value: string;
+};
+type ImportSpec = {
+  from: ImportSource;
+  names: Array<{
+    imported: string;
+    local?: string;
+  }>;
+};
+/**
+ * Context for `adapter.resolveSelector(...)`.
+ *
+ * This handles patterns like `${screenSize.phone} { ... }` where an imported
+ * value is used as a CSS selector (typically a media query helper).
+ */
+type SelectorResolveContext = {
+  kind: "selectorInterpolation";
+  /**
+   * Imported name of the binding used in the interpolation.
+   * Example: `import { screenSize } from "./lib"` -> importedName: "screenSize"
+   */
+  importedName: string;
+  /**
+   * Import source for the binding.
+   */
+  source: ImportSource;
+  /**
+   * Member path from the imported binding (if any).
+   * Example: `screenSize.phone` -> "phone"
+   */
+  path?: string;
+  /**
+   * Absolute path of the file currently being transformed.
+   */
+  filePath: string;
+  /**
+   * Source location (line/column) of the selector interpolation being resolved.
+   * Useful for error reporting.
+   */
+  loc?: {
+    line: number;
+    column: number;
+  };
+};
+/**
+ * Result for `adapter.resolveSelector(...)`.
+ */
+type SelectorResolveResult = {
+  /**
+   * The kind of selector resolved.
+   * Currently only "media" is supported.
+   */
+  kind: "media";
+  /**
+   * JS expression to use as the computed property key.
+   * Should reference a `defineConsts` value for media queries.
+   * Example: "breakpoints.phone"
+   */
+  expr: string;
+  /**
+   * Import statements required by `expr`.
+   * Example: [{ from: { kind: "specifier", value: "./breakpoints.stylex" }, names: [{ imported: "breakpoints" }] }]
+   */
+  imports: ImportSpec[];
+};
+interface ExternalInterfaceContext {
+  /** Absolute path of the file being transformed */
+  filePath: string;
+  /** Local name of the styled component */
+  componentName: string;
+  /** The export name (may differ from componentName for renamed exports) */
+  exportName: string;
+  /** Whether it's a default export */
+  isDefaultExport: boolean;
+}
+/**
+ * Result type for `adapter.externalInterface(...)`.
+ *
+ * - `null` → no external interface support (neither styles nor `as`)
+ * - `{ styles: true }` → enable className/style support AND polymorphic `as` prop
+ * - `{ styles: false, as: true }` → enable only polymorphic `as` prop (no style merging)
+ * - `{ styles: false, as: false }` → equivalent to `null`
+ *
+ * Note: When `styles: true`, the `as` prop is always enabled because the style
+ * merging implementation requires polymorphic rendering support.
+ */
+type ExternalInterfaceResult = {
+  styles: true;
+} | {
+  styles: false;
+  as: boolean;
+} | null;
+/**
+ * Configuration for a custom style merger function that combines stylex.props()
+ * results with external className/style props.
+ *
+ * When configured, generates cleaner output:
+ *   `{...stylexProps(styles.foo, className, style)}`
+ * instead of the verbose pattern:
+ *   `{...sx} className={[sx.className, className].filter(Boolean).join(" ")} style={{...sx.style, ...style}}`
+ */
+interface StyleMergerConfig {
+  /**
+   * Function name to use for merging (e.g., "stylexProps" or "mergeStylexProps").
+   */
+  functionName: string;
+  /**
+   * Import source for the merger function.
+   * Example: `{ kind: "specifier", value: "@company/ui-utils" }`
+   */
+  importSource: ImportSource;
+}
+interface Adapter {
+  /**
+   * Resolver for theme paths + CSS variables + imported values.
+   *
+   * Return:
+   * - `{ expr, imports }` for theme, css variables, and imported values.
+   * - Optionally return `{ dropDefinition: true }` for css variables to remove the local `--x: ...` definition.
+   * - `undefined` to bail/skip the file (for cssVariable: keeps the original `var(...)` unchanged)
+   */
+  resolveValue: (context: ResolveValueContext) => ResolveValueResult | undefined;
+  /**
+   * Resolver for helper calls found inside template interpolations.
+   *
+   * The codemod determines how to use the result based on context:
+   * - If `ctx.cssProperty` exists (e.g., `border: ${helper()}`) → result is used as a CSS value
+   * - If `ctx.cssProperty` is undefined (e.g., `${helper()}`) → result is used as a StyleX style object
+   *
+   * Use `ctx.cssProperty` to return the appropriate expression for the context.
+   *
+   * Return:
+   * - `{ expr, imports }` with the resolved expression
+   * - `undefined` to bail/skip the file
+   */
+  resolveCall: (context: CallResolveContext) => CallResolveResult | undefined;
+  /**
+   * Resolver for interpolations used in selector position.
+   *
+   * This handles patterns like `${screenSize.phone} { ... }` where an imported
+   * value is used as a CSS selector (typically a media query helper).
+   *
+   * Return:
+   * - `{ kind: "media", expr, imports }` when the interpolation resolves to a media query
+   * - `undefined` to bail/skip the file
+   */
+  resolveSelector: (context: SelectorResolveContext) => SelectorResolveResult | undefined;
+  /**
+   * Called for exported styled components to determine their external interface.
+   *
+   * Return:
+   * - `null` → no external interface (neither styles nor `as`)
+   * - `{ styles: true }` → accept className/style props AND polymorphic `as` prop
+   * - `{ styles: false, as: true }` → accept only polymorphic `as` prop
+   * - `{ styles: false, as: false }` → equivalent to `null`
+   */
+  externalInterface: (context: ExternalInterfaceContext) => ExternalInterfaceResult;
+  /**
+   * Custom merger function for className/style combining.
+   * When provided, generates cleaner output using this function instead of
+   * the verbose className/style merging pattern.
+   * Set to `null` to use the verbose pattern (default).
+   *
+   * Expected merger function signature:
+   * ```typescript
+   * function merger(
+   *   styles: StyleXStyles | StyleXStyles[],
+   *   className?: string,
+   *   style?: React.CSSProperties
+   * ): { className?: string; style?: React.CSSProperties }
+   * ```
+   */
+  styleMerger: StyleMergerConfig | null;
+}
+/**
+ * Helper for nicer user authoring + type inference.
+ *
+ * `defineAdapter(...)` also performs runtime validation (helpful for JS consumers)
+ * and will throw a descriptive error message if the adapter shape is invalid.
+ *
+ * Usage:
+ *   export default defineAdapter({
+ *     resolveValue(ctx) {
+ *       if (ctx.kind === "theme") {
+ *         return {
+ *           expr: `tokens.${ctx.path}`,
+ *           imports: [
+ *             { from: { kind: "specifier", value: "./tokens" }, names: [{ imported: "tokens" }] },
+ *           ],
+ *         };
+ *       }
+ *       // Return undefined to bail/skip the file
+ *     },
+ *
+ *     resolveCall(ctx) {
+ *       // Resolve helper calls inside template interpolations.
+ *       // Use ctx.cssProperty to determine context:
+ *       // - If ctx.cssProperty exists → return a CSS value expression
+ *       // - If ctx.cssProperty is undefined → return a StyleX style object reference
+ *       // Return { expr, imports } or undefined to bail/skip the file
+ *       void ctx;
+ *     },
+ *
+ *     resolveSelector(ctx) {
+ *       // Resolve imported values used in selector position (e.g., media query helpers).
+ *       // Return:
+ *       // - { kind: "media", expr, imports } for media queries (e.g., breakpoints.phone)
+ *       // - undefined to bail/skip the file
+ *       void ctx;
+ *     },
+ *
+ *     // Configure external interface for exported components
+ *     externalInterface(ctx) {
+ *       // Example: Enable styles (and `as`) for shared components folder
+ *       if (ctx.filePath.includes("/shared/components/")) {
+ *         return { styles: true };
+ *       }
+ *       return null;
+ *     },
+ *
+ *     // Optional: provide a custom merger, or use `null` for the default verbose merge output
+ *     styleMerger: null,
+ *   });
+ */
+declare function defineAdapter(adapter: Adapter): Adapter;
+//#endregion
+//#region src/internal/logger.d.ts
+type Severity = "info" | "warning" | "error";
+type WarningType = "`css` helper function switch must return css templates in all branches" | "`css` helper usage as a function call (css(...)) is not supported" | "`css` helper used outside of a styled component template cannot be statically transformed" | "Adapter helper call in border interpolation did not resolve to a single CSS value" | "Adapter resolveCall returned an unparseable styles expression" | "Adapter resolveCall returned an unparseable value expression" | "Adapter resolveCall returned StyleX styles for helper call where a CSS value was expected" | "Adapter resolveCall returned undefined for helper call" | "Adapter resolved StyleX styles cannot be applied under nested selectors/at-rules" | "Adapter resolved StyleX styles inside pseudo selector but did not provide cssText for property expansion — add cssText to resolveCall result to enable pseudo-wrapping" | 'Adapter resolveCall cssText could not be parsed as CSS declarations — expected semicolon-separated property: value pairs (e.g. "white-space: nowrap; overflow: hidden;")' | "Adapter resolveValue returned an unparseable value expression" | "Adapter resolveValue returned undefined for imported value" | "Arrow function: body is not a recognized pattern (expected ternary, logical, call, or member expression)" | "Arrow function: conditional branches could not be resolved to static or theme values" | "Arrow function: helper call body is not supported" | "Arrow function: indexed theme lookup pattern not matched" | "Arrow function: logical expression pattern not supported" | "Arrow function: prop access cannot be converted to style function for this CSS property" | "Arrow function: theme access path could not be resolved" | "Component selectors like `${OtherComponent}:hover &` are not directly representable in StyleX. Manual refactor is required" | "Conditional `css` block: !important is not supported in StyleX" | "Conditional `css` block: @-rules (e.g., @media, @supports) are not supported" | "Conditional `css` block: failed to parse expression" | "Conditional `css` block: missing CSS property name" | "Conditional `css` block: missing interpolation expression" | "Conditional `css` block: mixed static/dynamic values with non-theme expressions cannot be safely transformed" | "Conditional `css` block: multiple interpolation slots in a single property value" | "Conditional `css` block: ternary branch value could not be resolved (imported values require adapter support)" | "Conditional `css` block: ternary expressions inside pseudo selectors are not supported" | "Conditional `css` block: unsupported selector" | "Directional border helper styles are not supported" | "createGlobalStyle is not supported in StyleX. Global styles should be handled separately (e.g., in a CSS file or using CSS reset libraries)" | "Dynamic styles inside pseudo elements (::before/::after) are not supported by StyleX. See https://github.com/facebook/stylex/issues/1396" | "Failed to parse theme expressions" | "Heterogeneous background values (mix of gradients and colors) not currently supported" | "Higher-order styled factory wrappers (e.g. hoc(styled)) are not supported" | "Imported CSS helper mixins: cannot determine inherited properties for correct pseudo selector handling" | "Styled-components specificity hacks like `&&` / `&&&` are not representable in StyleX" | "Theme-dependent block-level conditional could not be fully resolved (branches may contain dynamic interpolations)" | "Theme-dependant call expression could not be resolved (e.g. theme helper calls like theme.highlight() are not supported)" | "Theme value with fallback (props.theme.X ?? / || default) cannot be resolved statically — use adapter.resolveValue to map theme paths to StyleX tokens" | "Theme-dependent nested prop access requires a project-specific theme source (e.g. useTheme())" | "Theme-dependent template literals require a project-specific theme source (e.g. useTheme())" | "Theme prop overrides on styled components are not supported" | "Universal selectors (`*`) are currently unsupported" | "Unsupported call expression (expected imported helper(...) or imported helper(...)(...))" | "Unsupported conditional test in shouldForwardProp" | "Unsupported shouldForwardProp pattern (only !prop.startsWith(), ![].includes(prop), and prop !== are supported)" | "Unsupported interpolation: arrow function" | "Unsupported interpolation: call expression" | "Unsupported interpolation: identifier" | "Unsupported interpolation: member expression" | "Unsupported interpolation: property" | "Unsupported interpolation: unknown" | "Unsupported nested conditional interpolation" | "Unsupported prop-based inline style expression cannot be safely inlined" | "Unsupported prop-based inline style props.theme access is not supported" | "Unsupported selector interpolation: imported value in selector position" | "Unsupported selector: class selector" | "Unsupported selector: comma-separated selectors must all be simple pseudos" | "Unsupported selector: descendant pseudo selector (space before pseudo)" | "Unsupported selector: descendant/child/sibling selector" | "Unsupported selector: interpolated pseudo selector" | "Unsupported selector: sibling combinator" | "Unsupported selector: unknown component selector" | "Unsupported css`` mixin: after-base mixin style is not a plain object" | "Unsupported css`` mixin: nested contextual conditions in after-base mixin" | "Unsupported css`` mixin: cannot infer base default for after-base contextual override (base value is non-literal)" | "css`` helper function interpolation references closure variable that cannot be hoisted" | "Using styled-components components as mixins is not supported; use css`` mixins or strings instead";
+interface WarningLog {
+  severity: Severity;
+  type: WarningType;
+  loc: {
+    line: number;
+    column: number;
+  } | null | undefined;
+  context?: Record<string, unknown>;
+}
+interface CollectedWarning extends WarningLog {
+  filePath: string;
+}
+//#endregion
+export { defineAdapter as i, WarningLog as n, Adapter as r, CollectedWarning as t };

package/dist/transform.d.mts

@@ -1,9 +1,8 @@
-import { n as WarningLog, r as Adapter } from "./logger-CNmtK-uJ.mjs";
+import { n as WarningLog, r as Adapter } from "./logger-DC-1uogs.mjs";
 import "stylis";
 import { API, FileInfo, Options } from "jscodeshift";
 
 //#region src/internal/transform-types.d.ts
-
 /**
  * Result of the transform including any log entries
  */