ref: rename to usePhysicalProperties opt-out, default to logical properties

Logical properties (paddingBlock/paddingInline) are now the default for 2-value
shorthand expansion, matching StyleX's ESLint plugin recommendations. Use
`usePhysicalProperties: true` in the adapter to opt out and get physical
properties (paddingTop/paddingRight/paddingBottom/paddingLeft) instead.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: skovhus

src/__tests__/transform.test.ts

@@ -3987,21 +3987,19 @@ export const App = () => <Input readOnly value="test" />;
       { adapter: fixtureAdapter },
     );
     expect(result.code).not.toBeNull();
-    // The base has physical longhands (from "8px 12px").
+    // The base has logical longhands (from "8px 12px" → paddingBlock/paddingInline).
     // The readonly block has padding: 0 which should be expanded to match.
-    expect(result.code).toContain("paddingTop");
-    expect(result.code).toContain("paddingRight");
-    expect(result.code).toContain("paddingBottom");
-    expect(result.code).toContain("paddingLeft");
+    expect(result.code).toContain("paddingBlock");
+    expect(result.code).toContain("paddingInline");
     // The readonly style should NOT have the shorthand "padding" since it conflicts
-    // with the base's physical longhands.
+    // with the base's logical longhands.
     const readonlyMatch = result.code!.match(/inputReadonly:\s*\{([^}]+)\}/);
     expect(readonlyMatch).toBeTruthy();
     const readonlyBlock = readonlyMatch![1]!;
     // Should have expanded longhands, not shorthand
-    expect(readonlyBlock).not.toMatch(/\bpadding\b(?!Top|Right|Bottom|Left)/);
-    expect(readonlyBlock).toContain("paddingTop");
-    expect(readonlyBlock).toContain("paddingLeft");
+    expect(readonlyBlock).not.toMatch(/\bpadding\b(?!Block|Inline)/);
+    expect(readonlyBlock).toContain("paddingBlock");
+    expect(readonlyBlock).toContain("paddingInline");
   });
 });
 
@@ -4059,18 +4057,16 @@ export const App = () => <Input />;
     );
     expect(result.code).not.toBeNull();
     // The base has paddingBlock (logical). The conditional has padding: 8px 12px.
-    // The expansion should produce physical longhands: paddingTop: 8, paddingRight: 12, etc.
-    expect(result.code).toContain("paddingTop: 8");
-    expect(result.code).toContain("paddingRight: 12");
-    expect(result.code).toContain("paddingBottom: 8");
-    expect(result.code).toContain("paddingLeft: 12");
+    // Both expand to logical longhands (default), so no conflict normalization needed.
+    expect(result.code).toContain("paddingBlock: 8");
+    expect(result.code).toContain("paddingInline: 12");
     // Should NOT have the unsplit value
     expect(result.code).not.toContain('"8px 12px"');
   });
 });
 
-describe("useLogicalProperties adapter option", () => {
-  it("should expand 2-value padding to logical properties when enabled", () => {
+describe("usePhysicalProperties adapter option", () => {
+  it("should expand 2-value padding to logical properties by default", () => {
     const source = `
 import styled from "styled-components";
 
@@ -4083,7 +4079,7 @@ export const App = () => <Box>test</Box>;
     const result = transformWithWarnings(
       { source, path: "test.tsx" },
       { jscodeshift: j, j, stats: () => {}, report: () => {} },
-      { adapter: { ...fixtureAdapter, useLogicalProperties: true } },
+      { adapter: fixtureAdapter },
     );
     expect(result.code).not.toBeNull();
     expect(result.code).toContain("paddingBlock");
@@ -4092,7 +4088,7 @@ export const App = () => <Box>test</Box>;
     expect(result.code).not.toContain("paddingRight");
   });
 
-  it("should expand 2-value padding to physical properties when disabled (default)", () => {
+  it("should expand 2-value padding to physical properties when usePhysicalProperties is true", () => {
     const source = `
 import styled from "styled-components";
 
@@ -4105,7 +4101,7 @@ export const App = () => <Box>test</Box>;
     const result = transformWithWarnings(
       { source, path: "test.tsx" },
       { jscodeshift: j, j, stats: () => {}, report: () => {} },
-      { adapter: fixtureAdapter },
+      { adapter: { ...fixtureAdapter, usePhysicalProperties: true } },
     );
     expect(result.code).not.toBeNull();
     expect(result.code).toContain("paddingTop");

src/adapter.ts

@@ -725,16 +725,17 @@ export interface Adapter {
   useSxProp: boolean;
 
   /**
-   * Use CSS logical properties (`paddingBlock`/`paddingInline`) instead of physical
-   * properties (`paddingTop`/`paddingRight`/`paddingBottom`/`paddingLeft`) when expanding
+   * Use physical CSS properties (`paddingTop`/`paddingRight`/`paddingBottom`/`paddingLeft`)
+   * instead of logical properties (`paddingBlock`/`paddingInline`) when expanding
    * 2-value CSS shorthands like `padding: 4px 8px`.
    *
-   * Enable this for codebases that support RTL (right-to-left) layouts, where logical
-   * properties automatically adapt to the writing direction.
+   * By default, the codemod uses logical properties which adapt to the writing direction
+   * (RTL/LTR), matching StyleX's ESLint plugin recommendations. Enable this if your
+   * codebase does not need RTL support and you prefer physical properties.
    *
    * @default false
    */
-  useLogicalProperties?: boolean;
+  usePhysicalProperties?: boolean;
 }
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -768,7 +769,7 @@ export interface AdapterInput {
   styleMerger: Adapter["styleMerger"];
   themeHook?: Adapter["themeHook"];
   useSxProp: Adapter["useSxProp"];
-  useLogicalProperties?: Adapter["useLogicalProperties"];
+  usePhysicalProperties?: Adapter["usePhysicalProperties"];
 }
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -837,8 +838,8 @@ export interface AdapterInput {
  *     // Emit sx={} JSX attributes instead of {...stylex.props()} spreads (requires StyleX ≥0.18)
  *     useSxProp: false,
  *
- *     // Use logical properties (paddingBlock/paddingInline) for 2-value shorthands (RTL support)
- *     useLogicalProperties: false,
+ *     // Opt out of logical properties — use paddingTop/Right/Bottom/Left instead of Block/Inline
+ *     // usePhysicalProperties: true,
  *
  *     // Optional: customize runtime theme hook import/call used by emitted wrappers
  *     themeHook: {

src/internal/css-prop-mapping.ts

@@ -11,7 +11,7 @@ export { isCssShorthandProperty, setUseLogicalProperties, getUseLogicalPropertie
 type StylexPropDecl = { prop: string; value: CssValue };
 
 /** Module-level flag controlling whether 2-value shorthand expansion uses logical properties. */
-let useLogicalProperties = false;
+let useLogicalProperties = true;
 
 function setUseLogicalProperties(value: boolean): void {
   useLogicalProperties = value;

src/internal/stylex-shorthands.test.ts

@@ -27,12 +27,10 @@ describe("splitDirectionalProperty", () => {
     ]);
   });
 
-  it("uses physical longhands for two-value shorthand", () => {
+  it("uses logical longhands for two-value shorthand (default)", () => {
     expect(splitDirectionalProperty({ prop: "padding", rawValue: "4px 8px" })).toEqual([
-      { prop: "paddingTop", value: "4px" },
-      { prop: "paddingRight", value: "8px" },
-      { prop: "paddingBottom", value: "4px" },
-      { prop: "paddingLeft", value: "8px" },
+      { prop: "paddingBlock", value: "4px" },
+      { prop: "paddingInline", value: "8px" },
     ]);
   });
 
@@ -85,26 +83,14 @@ describe("splitDirectionalProperty", () => {
     expect(result[3]!.prop).toBe("paddingInlineStart");
   });
 
-  it("uses logical longhands for two-value shorthand when useLogical is true", () => {
+  it("uses physical longhands for two-value shorthand when useLogical is false", () => {
     expect(
-      splitDirectionalProperty({ prop: "padding", rawValue: "4px 8px", useLogical: true }),
+      splitDirectionalProperty({ prop: "padding", rawValue: "4px 8px", useLogical: false }),
     ).toEqual([
-      { prop: "paddingBlock", value: "4px" },
-      { prop: "paddingInline", value: "8px" },
-    ]);
-  });
-
-  it("uses physical longhands for three-value shorthand even when useLogical is true", () => {
-    const result = splitDirectionalProperty({
-      prop: "margin",
-      rawValue: "4px 8px 12px",
-      useLogical: true,
-    });
-    expect(result).toEqual([
-      { prop: "marginTop", value: "4px" },
-      { prop: "marginRight", value: "8px" },
-      { prop: "marginBottom", value: "12px" },
-      { prop: "marginLeft", value: "8px" },
+      { prop: "paddingTop", value: "4px" },
+      { prop: "paddingRight", value: "8px" },
+      { prop: "paddingBottom", value: "4px" },
+      { prop: "paddingLeft", value: "8px" },
     ]);
   });
 
@@ -122,10 +108,8 @@ describe("splitDirectionalProperty", () => {
       rawValue: "calc(100% - 20px) 10px",
     });
     expect(result).toEqual([
-      { prop: "marginTop", value: "calc(100% - 20px)" },
-      { prop: "marginRight", value: "10px" },
-      { prop: "marginBottom", value: "calc(100% - 20px)" },
-      { prop: "marginLeft", value: "10px" },
+      { prop: "marginBlock", value: "calc(100% - 20px)" },
+      { prop: "marginInline", value: "10px" },
     ]);
   });
 

src/internal/stylex-shorthands.ts

@@ -118,7 +118,7 @@ export function splitDirectionalProperty(args: {
     important = false,
     preferInline = false,
     alwaysExpand = false,
-    useLogical = false,
+    useLogical = true,
   } = args;
   const values = splitDirectionalShorthands(rawValue, false);
   const top = values[0] ?? "";

src/internal/transform-context.ts

@@ -125,7 +125,7 @@ export class TransformContext {
       "transform(options) - missing `adapter` (if you run the jscodeshift transform directly, pass options.adapter)",
     );
 
-    setUseLogicalProperties(adapter.useLogicalProperties ?? false);
+    setUseLogicalProperties(!(adapter.usePhysicalProperties ?? false));
 
     const resolverImports = new Map<string, ImportSpec>();
     const {

test-cases/asProp-basic.output.tsx

@@ -68,10 +68,8 @@ const styles = stylex.create({
     color: "#bf4f74",
     fontSize: "1em",
     margin: "1em",
-    paddingTop: "0.25em",
-    paddingRight: "1em",
-    paddingBottom: "0.25em",
-    paddingLeft: "1em",
+    paddingBlock: "0.25em",
+    paddingInline: "1em",
     borderWidth: 2,
     borderStyle: "solid",
     borderColor: "#bf4f74",

test-cases/asProp-forwarded.output.tsx

@@ -45,10 +45,8 @@ export const App = () => (
 const styles = stylex.create({
   button: {
     display: "inline-block",
-    paddingTop: 8,
-    paddingRight: 16,
-    paddingBottom: 8,
-    paddingLeft: 16,
+    paddingBlock: 8,
+    paddingInline: 16,
     backgroundColor: "#bf4f74",
     color: "white",
     borderWidth: 0,

test-cases/basic-flowTypes.flow.output.jsx

@@ -20,10 +20,8 @@ const styles = stylex.create({
   button: {
     backgroundColor: "#bf4f74",
     color: "white",
-    paddingTop: 8,
-    paddingRight: 16,
-    paddingBottom: 8,
-    paddingLeft: 16,
+    paddingBlock: 8,
+    paddingInline: 16,
     borderWidth: 0,
     borderStyle: "none",
     borderColor: "initial",

test-cases/basic-plainJavascript.output.jsx

@@ -11,20 +11,16 @@ const styles = stylex.create({
   button: {
     backgroundColor: "#bf4f74",
     color: "white",
-    paddingTop: 8,
-    paddingRight: 16,
-    paddingBottom: 8,
-    paddingLeft: 16,
+    paddingBlock: 8,
+    paddingInline: 16,
     borderWidth: 0,
     borderStyle: "none",
     borderColor: "initial",
     borderRadius: 4,
   },
   card: {
-    paddingTop: 16,
-    paddingRight: 12,
-    paddingBottom: 16,
-    paddingLeft: 12,
+    paddingBlock: 16,
+    paddingInline: 12,
     backgroundColor: "white",
     borderRadius: 8,
   },