An open source design system that's fully customizable and agent ready
TypeScript
feat(eslint-plugin): add @astryx/no-physical-properties rule (warn) for RTL (#4437)
nynexman4464fdcae1d735bf
diff --git a/.changeset/lint-no-physical-props.md b/.changeset/lint-no-physical-props.mdnew file mode 100644index 0000000000..9d6c2ab5ee--- /dev/null+++ b/.changeset/lint-no-physical-props.md@@ -0,0 +1,13 @@+---+'@astryxdesign/core': patch+---++[chore] Add `@astryx/no-physical-properties` ESLint rule that flags physical left/right CSS properties inside `stylex.create()` and suggests the CSS logical equivalent for RTL support.++- KEY-BASED: `marginLeft`/`marginRight`, `paddingLeft`/`paddingRight`, `borderLeft`/`borderRight` (+ their `Width`/`Style`/`Color` longhands), `left`/`right` → `insetInlineStart`/`insetInlineEnd`, and the four physical corner radii → their diagonal-aware logical names (`borderTopLeftRadius` → `borderStartStartRadius`, etc.).+- VALUE-BASED: `textAlign: 'left'|'right'`, `float: 'left'|'right'`, and `clear: 'left'|'right'` (the key stays, only the physical value is flagged).+- Scoped strictly to `stylex.create()` — physical identifiers used elsewhere are ignored.++Shipped at `warn` in both the `strict` and `recommended` tiers until the RTL Phase 4 (Calendar/Slider/Table) physical-property migration lands; it will be flipped to `error` afterward.++@nynexman4464diff --git a/internal/eslint-plugin-astryx/index.js b/internal/eslint-plugin-astryx/index.jsindex 2b9cb2184b..113b0b25c5 100644--- a/internal/eslint-plugin-astryx/index.js+++ b/internal/eslint-plugin-astryx/index.js@@ -24,6 +24,7 @@ import noClassnameClobberRule from './no-classname-clobber.js';import noHardcodedAnchorRule from './no-hardcoded-anchor.js';import noRawParagraphRule from './no-raw-paragraph.js';import noBorderShorthandRule from './no-border-shorthand.js';+import noPhysicalPropertiesRule from './no-physical-properties.js';import noReactNamespaceHooksRule from './no-react-namespace-hooks.js';import copyrightHeaderRule from './copyright-header.js';import noRawConsoleCliRule from './no-raw-console-cli.js';@@ -240,6 +241,7 @@ const plugin = {'no-hardcoded-anchor': noHardcodedAnchorRule,'no-raw-paragraph': noRawParagraphRule,'no-border-shorthand': noBorderShorthandRule,+ 'no-physical-properties': noPhysicalPropertiesRule,'no-react-namespace-hooks': noReactNamespaceHooksRule,'require-base-props': requireBasePropsRule,'require-ref-prop': requireRefPropRule,@@ -267,6 +269,12 @@ plugin.configs.strict = {'@astryx/no-hardcoded-anchor': 'error','@astryx/no-raw-paragraph': 'error','@astryx/no-border-shorthand': 'error',+ // Deliberately 'warn' even in the strict tier (not 'error'): the core+ // package still has known un-migrated Phase-4 physical properties+ // (Calendar radii, Slider positioning, Table gradients) that would break CI+ // if this were an error. Ship at warn until RTL Phase 4 (Calendar/Slider/+ // Table) migration lands; flip to error afterward.+ '@astryx/no-physical-properties': 'warn','@astryx/no-react-namespace-hooks': 'error','@astryx/require-base-props': 'error','@astryx/require-ref-prop': 'error',@@ -292,6 +300,9 @@ plugin.configs.recommended = {'@astryx/no-hardcoded-anchor': 'warn','@astryx/no-raw-paragraph': 'warn','@astryx/no-border-shorthand': 'warn',+ // Warn now, flip to error after RTL Phase 4 (Calendar/Slider/Table)+ // physical-property migration lands.+ '@astryx/no-physical-properties': 'warn','@astryx/no-react-namespace-hooks': 'error','@astryx/require-base-props': 'warn','@astryx/require-ref-prop': 'warn',diff --git a/internal/eslint-plugin-astryx/no-physical-properties.js b/internal/eslint-plugin-astryx/no-physical-properties.jsnew file mode 100644index 0000000000..658eba78a2--- /dev/null+++ b/internal/eslint-plugin-astryx/no-physical-properties.js@@ -0,0 +1,222 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file no-physical-properties.js+ * @description Disallow physical left/right CSS properties (and physical+ * left/right VALUES) inside stylex.create(). Physical properties don't flip+ * under RTL; the CSS logical-property equivalents (inline-start/inline-end,+ * start/end) do, so they're required for correct right-to-left rendering.+ *+ * Two kinds of violation are detected:+ * 1. KEY-BASED — the object key is itself a banned physical property+ * (e.g. `marginLeft`, `borderRightColor`, `left`, `borderTopLeftRadius`).+ * The suggested fix renames the key to the logical equivalent.+ * 2. VALUE-BASED — the key is fine, but a specific physical VALUE is used+ * (e.g. `textAlign: 'left'`, `float: 'right'`, `clear: 'left'`). The+ * suggested fix replaces only the value; the key is left alone.+ *+ * SEVERITY: shipped at `warn` in BOTH the `strict` and `recommended` tiers+ * (see index.js). The core package still has known un-migrated Phase-4+ * physical properties (Calendar radii, Slider positioning, Table gradients)+ * that would break CI if this were an `error`. Ship at warn until RTL Phase 4+ * (Calendar/Slider/Table) migration lands; flip to error afterward.+ *+ * AUTOFIX: this rule is fixable (`meta.fixable: 'code'`).+ * - VALUE-BASED fixes are always safe: only the value literal is replaced.+ * - KEY-BASED fixes rename the key token, but ONLY when the logical key is not+ * already present in the same style object. If BOTH the physical and logical+ * key are present, renaming would produce a duplicate property (and the two+ * silently collide — last one wins in LTR), so instead of autofixing we+ * surface a distinct `physicalKeyConflict` message for a human to resolve.+ */++/**+ * Physical property KEYS → their CSS logical equivalent.+ * When one of these appears as an object key inside stylex.create(), flag it+ * and suggest the logical rename.+ *+ * The corner-radius mappings are diagonal-aware: a physical corner is named+ * <vertical><horizontal>, while the logical corner is named <block><inline>.+ * top-left → start(block) start(inline) → borderStartStartRadius+ * top-right → start(block) end(inline) → borderStartEndRadius+ * bottom-left → end(block) start(inline) → borderEndStartRadius+ * bottom-right → end(block) end(inline) → borderEndEndRadius+ */+const PHYSICAL_KEY_MAP = {+ // Margin+ marginLeft: 'marginInlineStart',+ marginRight: 'marginInlineEnd',+ // Padding+ paddingLeft: 'paddingInlineStart',+ paddingRight: 'paddingInlineEnd',+ // Border side shorthands+ borderLeft: 'borderInlineStart',+ borderRight: 'borderInlineEnd',+ // Border side longhands (left)+ borderLeftWidth: 'borderInlineStartWidth',+ borderLeftStyle: 'borderInlineStartStyle',+ borderLeftColor: 'borderInlineStartColor',+ // Border side longhands (right)+ borderRightWidth: 'borderInlineEndWidth',+ borderRightStyle: 'borderInlineEndStyle',+ borderRightColor: 'borderInlineEndColor',+ // Inset+ left: 'insetInlineStart',+ right: 'insetInlineEnd',+ // Corner radii (diagonal-aware: vertical+horizontal → block+inline)+ borderTopLeftRadius: 'borderStartStartRadius',+ borderTopRightRadius: 'borderStartEndRadius',+ borderBottomLeftRadius: 'borderEndStartRadius',+ borderBottomRightRadius: 'borderEndEndRadius',+};++/**+ * Property KEYS whose physical left/right VALUES should be flagged. The key+ * itself is fine — only the specific physical value literal is a violation.+ * Maps `key → { physicalValue → logicalValue }`.+ */+const PHYSICAL_VALUE_MAP = {+ textAlign: { left: 'start', right: 'end' },+ float: { left: 'inline-start', right: 'inline-end' },+ clear: { left: 'inline-start', right: 'inline-end' },+};++function isInsideStylexCreate(node) {+ let current = node;+ while (current) {+ if (+ current.type === 'CallExpression' &&+ current.callee?.type === 'MemberExpression' &&+ current.callee.object?.name === 'stylex' &&+ current.callee.property?.name === 'create'+ ) {+ return true;+ }+ current = current.parent;+ }+ return false;+}++function getStaticValue(node) {+ if (!node) return null;+ if (node.type === 'Literal' && typeof node.value === 'string') {+ return node.value;+ }+ return null;+}++/**+ * Does the given ObjectExpression already contain a Property whose key is+ * `keyName`? Handles both identifier keys (`marginLeft`) and string-literal+ * keys (`'marginLeft'`).+ */+function objectHasKey(objectExpression, keyName) {+ if (!objectExpression || objectExpression.type !== 'ObjectExpression') {+ return false;+ }+ return objectExpression.properties.some((prop) => {+ if (prop.type !== 'Property') return false;+ const name = prop.key?.name ?? prop.key?.value;+ return name === keyName;+ });+}++const rule = {+ meta: {+ type: 'problem',+ fixable: 'code',+ docs: {+ description:+ 'Disallow physical left/right CSS properties and values inside ' ++ 'stylex.create(). Use the CSS logical equivalents ' ++ '(inline-start/inline-end, start/end) for RTL support.',+ category: 'Best Practices',+ recommended: true,+ },+ messages: {+ physicalKey:+ 'Use `{{logical}}` instead of `{{physical}}` for RTL support.',+ physicalValue:+ 'Use `{{prop}}: \'{{logical}}\'` instead of ' ++ '`{{prop}}: \'{{physical}}\'` for RTL support.',+ physicalKeyConflict:+ '`{{physical}}` conflicts with `{{logical}}` already set on this ' ++ 'style object — remove `{{physical}}`.',+ },+ schema: [],+ },+ create(context) {+ return {+ Property(node) {+ if (!isInsideStylexCreate(node)) return;++ const propName = node.key?.name || node.key?.value;+ if (!propName) return;++ // KEY-BASED: the object key is itself a physical property.+ const logicalKey = PHYSICAL_KEY_MAP[propName];+ if (logicalKey) {+ // Guard: if the logical key is ALSO present in the same object,+ // renaming would create a duplicate/silent collision. Ambiguous+ // which value the author meant — surface a distinct message, no fix.+ if (objectHasKey(node.parent, logicalKey)) {+ context.report({+ node: node.key,+ messageId: 'physicalKeyConflict',+ data: {+ physical: propName,+ logical: logicalKey,+ },+ });+ return;+ }++ // Preserve the original key's quoting: a string-literal key is+ // replaced with a quoted string; an identifier key stays unquoted.+ // All logical names are valid identifiers.+ const isStringLiteralKey =+ node.key.type === 'Literal' && typeof node.key.value === 'string';+ const newKeyText = isStringLiteralKey+ ? `'${logicalKey}'`+ : logicalKey;++ context.report({+ node: node.key,+ messageId: 'physicalKey',+ data: {+ physical: propName,+ logical: logicalKey,+ },+ fix(fixer) {+ return fixer.replaceText(node.key, newKeyText);+ },+ });+ return;+ }++ // VALUE-BASED: the key is fine, but the value may be physical.+ const valueMap = PHYSICAL_VALUE_MAP[propName];+ if (valueMap) {+ const value = getStaticValue(node.value);+ if (value !== null && valueMap[value]) {+ const logicalValue = valueMap[value];+ context.report({+ node: node.value,+ messageId: 'physicalValue',+ data: {+ prop: propName,+ physical: value,+ logical: logicalValue,+ },+ fix(fixer) {+ return fixer.replaceText(node.value, `'${logicalValue}'`);+ },+ });+ }+ }+ },+ };+ },+};++export default rule;diff --git a/internal/eslint-plugin-astryx/no-physical-properties.test.mjs b/internal/eslint-plugin-astryx/no-physical-properties.test.mjsnew file mode 100644index 0000000000..0eff0a09b7--- /dev/null+++ b/internal/eslint-plugin-astryx/no-physical-properties.test.mjs@@ -0,0 +1,260 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file no-physical-properties.test.mjs+ */++import {RuleTester} from 'eslint';+import rule from './no-physical-properties.js';++const ruleTester = new RuleTester({+ languageOptions: {+ ecmaVersion: 2022,+ sourceType: 'module',+ },+});++/** Wrap a style-object body in a stylex.create() call. */+function inStylex(body) {+ return `+ import * as stylex from '@stylexjs/stylex';+ const styles = stylex.create({+ base: { ${body} },+ });+ `;+}++ruleTester.run('no-physical-properties', rule, {+ valid: [+ // Logical margin/padding are fine+ {code: inStylex(`marginInlineStart: 8`)},+ {code: inStylex(`paddingInlineEnd: 12`)},+ // Logical inset is fine+ {code: inStylex(`insetInlineStart: 0`)},+ // Logical border longhands are fine+ {code: inStylex(`borderInlineStartWidth: 1, borderInlineEndColor: 'red'`)},+ // Logical corner radii are fine+ {code: inStylex(`borderStartStartRadius: 4, borderEndEndRadius: 4`)},+ // textAlign with a logical value is fine+ {code: inStylex(`textAlign: 'start'`)},+ // float/clear with logical values are fine+ {code: inStylex(`float: 'inline-start'`)},+ {code: inStylex(`clear: 'inline-end'`)},+ // textAlign with a non-physical value (center) is fine+ {code: inStylex(`textAlign: 'center'`)},+ // Block-direction properties are never physical — fine+ {code: inStylex(`marginTop: 4, paddingBottom: 8`)},+ // SCOPING: physical key on a plain object OUTSIDE stylex.create — fine+ {code: `const x = { left: 5, marginLeft: 10, borderTopLeftRadius: 4 };`},+ // SCOPING: physical VALUE on a plain object outside stylex — fine+ {code: `const x = { textAlign: 'left', float: 'right' };`},+ // SCOPING: `left`/`right` as ordinary variable names — fine+ {code: `const left = 5; const right = 10; const sum = left + right;`},+ ],+ invalid: [+ // --- KEY-BASED: margin (autofix renames the key) ---+ {+ code: inStylex(`marginLeft: 8`),+ output: inStylex(`marginInlineStart: 8`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'marginLeft', logical: 'marginInlineStart'}},+ ],+ },+ {+ code: inStylex(`marginRight: 8`),+ output: inStylex(`marginInlineEnd: 8`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'marginRight', logical: 'marginInlineEnd'}},+ ],+ },+ // --- KEY-BASED: padding ---+ {+ code: inStylex(`paddingLeft: 8`),+ output: inStylex(`paddingInlineStart: 8`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'paddingLeft', logical: 'paddingInlineStart'}},+ ],+ },+ {+ code: inStylex(`paddingRight: 8`),+ output: inStylex(`paddingInlineEnd: 8`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'paddingRight', logical: 'paddingInlineEnd'}},+ ],+ },+ // --- KEY-BASED: border side shorthands ---+ {+ code: inStylex(`borderLeft: '1px solid red'`),+ output: inStylex(`borderInlineStart: '1px solid red'`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderLeft', logical: 'borderInlineStart'}},+ ],+ },+ {+ code: inStylex(`borderRight: '1px solid red'`),+ output: inStylex(`borderInlineEnd: '1px solid red'`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderRight', logical: 'borderInlineEnd'}},+ ],+ },+ // --- KEY-BASED: border side longhands (width/style/color) ---+ {+ code: inStylex(`borderLeftWidth: 1`),+ output: inStylex(`borderInlineStartWidth: 1`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderLeftWidth', logical: 'borderInlineStartWidth'}},+ ],+ },+ {+ code: inStylex(`borderLeftStyle: 'solid'`),+ output: inStylex(`borderInlineStartStyle: 'solid'`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderLeftStyle', logical: 'borderInlineStartStyle'}},+ ],+ },+ {+ code: inStylex(`borderLeftColor: 'red'`),+ output: inStylex(`borderInlineStartColor: 'red'`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderLeftColor', logical: 'borderInlineStartColor'}},+ ],+ },+ {+ code: inStylex(`borderRightWidth: 1`),+ output: inStylex(`borderInlineEndWidth: 1`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderRightWidth', logical: 'borderInlineEndWidth'}},+ ],+ },+ {+ code: inStylex(`borderRightStyle: 'solid'`),+ output: inStylex(`borderInlineEndStyle: 'solid'`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderRightStyle', logical: 'borderInlineEndStyle'}},+ ],+ },+ {+ code: inStylex(`borderRightColor: 'red'`),+ output: inStylex(`borderInlineEndColor: 'red'`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderRightColor', logical: 'borderInlineEndColor'}},+ ],+ },+ // --- KEY-BASED: inset left/right ---+ {+ code: inStylex(`left: 0`),+ output: inStylex(`insetInlineStart: 0`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'left', logical: 'insetInlineStart'}},+ ],+ },+ {+ code: inStylex(`right: 0`),+ output: inStylex(`insetInlineEnd: 0`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'right', logical: 'insetInlineEnd'}},+ ],+ },+ // --- KEY-BASED: string-literal key preserves quoting on rename ---+ {+ code: inStylex(`'left': 0`),+ output: inStylex(`'insetInlineStart': 0`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'left', logical: 'insetInlineStart'}},+ ],+ },+ // --- KEY-BASED: corner radii (verify the diagonal mapping) ---+ {+ code: inStylex(`borderTopLeftRadius: 4`),+ output: inStylex(`borderStartStartRadius: 4`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderTopLeftRadius', logical: 'borderStartStartRadius'}},+ ],+ },+ {+ code: inStylex(`borderTopRightRadius: 4`),+ output: inStylex(`borderStartEndRadius: 4`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderTopRightRadius', logical: 'borderStartEndRadius'}},+ ],+ },+ {+ code: inStylex(`borderBottomLeftRadius: 4`),+ output: inStylex(`borderEndStartRadius: 4`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderBottomLeftRadius', logical: 'borderEndStartRadius'}},+ ],+ },+ {+ code: inStylex(`borderBottomRightRadius: 4`),+ output: inStylex(`borderEndEndRadius: 4`),+ errors: [+ {messageId: 'physicalKey', data: {physical: 'borderBottomRightRadius', logical: 'borderEndEndRadius'}},+ ],+ },+ // --- KEY-BASED CONFLICT: both physical + logical present → no autofix ---+ {+ code: inStylex(`marginLeft: 8, marginInlineStart: 4`),+ // Fix is skipped: `output: null` asserts the code is left unchanged.+ output: null,+ errors: [+ {messageId: 'physicalKeyConflict', data: {physical: 'marginLeft', logical: 'marginInlineStart'}},+ ],+ },+ // Conflict also detected when the logical key is a string literal.+ {+ code: inStylex(`left: 0, 'insetInlineStart': 10`),+ output: null,+ errors: [+ {messageId: 'physicalKeyConflict', data: {physical: 'left', logical: 'insetInlineStart'}},+ ],+ },+ // --- VALUE-BASED: textAlign (autofix replaces the value only) ---+ {+ code: inStylex(`textAlign: 'left'`),+ output: inStylex(`textAlign: 'start'`),+ errors: [+ {messageId: 'physicalValue', data: {prop: 'textAlign', physical: 'left', logical: 'start'}},+ ],+ },+ {+ code: inStylex(`textAlign: 'right'`),+ output: inStylex(`textAlign: 'end'`),+ errors: [+ {messageId: 'physicalValue', data: {prop: 'textAlign', physical: 'right', logical: 'end'}},+ ],+ },+ // --- VALUE-BASED: float ---+ {+ code: inStylex(`float: 'left'`),+ output: inStylex(`float: 'inline-start'`),+ errors: [+ {messageId: 'physicalValue', data: {prop: 'float', physical: 'left', logical: 'inline-start'}},+ ],+ },+ {+ code: inStylex(`float: 'right'`),+ output: inStylex(`float: 'inline-end'`),+ errors: [+ {messageId: 'physicalValue', data: {prop: 'float', physical: 'right', logical: 'inline-end'}},+ ],+ },+ // --- VALUE-BASED: clear ---+ {+ code: inStylex(`clear: 'left'`),+ output: inStylex(`clear: 'inline-start'`),+ errors: [+ {messageId: 'physicalValue', data: {prop: 'clear', physical: 'left', logical: 'inline-start'}},+ ],+ },+ {+ code: inStylex(`clear: 'right'`),+ output: inStylex(`clear: 'inline-end'`),+ errors: [+ {messageId: 'physicalValue', data: {prop: 'clear', physical: 'right', logical: 'inline-end'}},+ ],+ },+ ],+});++console.log('All tests passed!');