Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(core): rtlStyles.centerInline helper + lint detection for the centering idiom (#4613)

nynexman44643d3d463aaca8
diff --git a/.changeset/rtl-center-inline-util.md b/.changeset/rtl-center-inline-util.md
new file mode 100644
index 0000000000..804fbbdd42
--- /dev/null
+++ b/.changeset/rtl-center-inline-util.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Add a shared `rtlStyles.centerInline(blockOffset)` helper for horizontally centering an absolutely-positioned, auto-width element on the inline axis, with an optional block-axis offset folded into the same transform. It intentionally uses physical `left: 50%` + `translateX(-50%)` — both reference the same physical edge, so the pair is direction-symmetric and centers identically in LTR and RTL. A logical `insetInlineStart: 50%` anchor would flip in RTL while the physical translate does not, shifting the element off-center by its own width. This is the one case where physical `left` is correct, so the single sanctioned `no-physical-properties` suppression lives in the helper rather than at each call site.
+
+The `@astryx/no-physical-properties` rule now recognises this `left: '50%'` + centering `translate` idiom and points offenders at the helper instead of wrongly suggesting a logical rename.
+@nynexman4464
diff --git a/internal/eslint-plugin-astryx/no-physical-properties.js b/internal/eslint-plugin-astryx/no-physical-properties.js
index 658eba78a2..e138e98e0e 100644
--- a/internal/eslint-plugin-astryx/no-physical-properties.js
+++ b/internal/eslint-plugin-astryx/no-physical-properties.js
@@ -15,11 +15,17 @@
* (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.
+ * EXCEPTION — inline centering: `left: '50%'` paired with a `translate`/
+ * `translateX` in the same style object is a deliberate, direction-symmetric
+ * centering idiom (physical anchor + physical translate reference the same
+ * edge). Logicalizing it to `insetInlineStart` BREAKS RTL centering, so the
+ * rule flags it with a distinct, non-autofixing message that points to the
+ * shared `rtlStyles.centerInline()` helper (the one sanctioned place the
+ * physical `left` lives, behind a single suppression).
+ *
+ * SEVERITY: shipped at `error` in both the `strict` and `recommended` tiers
+ * (see index.js). The RTL physical→logical migration is complete, so this
+ * rule gates against regressions rather than merely warning.
*
* AUTOFIX: this rule is fixable (`meta.fixable: 'code'`).
* - VALUE-BASED fixes are always safe: only the value literal is replaced.
@@ -121,6 +127,38 @@ function objectHasKey(objectExpression, keyName) {
});
}
+/**
+ * Detects the inline-CENTERING pattern that must NOT be logicalized:
+ * `left: '50%'` (or `'-50%'`) paired, in the same style object, with a
+ * `transform` containing a `translate`/`translateX` — the physical anchor and
+ * the physical translate reference the SAME physical edge, so the pair centers
+ * symmetrically in both LTR and RTL. Renaming `left` → `insetInlineStart` here
+ * flips the anchor under RTL while the translate stays physical, breaking the
+ * centering by the element's own width. Callers should use the shared
+ * `rtlStyles.centerInline(blockOffset)` helper instead (which owns the one
+ * sanctioned physical-`left` suppression). Returns true when this Property is
+ * the `left: '50%'` of such a centering pair.
+ */
+function isInlineCenteringLeft(node) {
+ const value = getStaticValue(node.value);
+ if (value !== '50%' && value !== '-50%') return false;
+ const obj = node.parent;
+ if (!obj || obj.type !== 'ObjectExpression') return false;
+ return obj.properties.some((prop) => {
+ if (prop.type !== 'Property') return false;
+ const name = prop.key?.name ?? prop.key?.value;
+ if (name !== 'transform') return false;
+ // transform value may be a string literal or a template literal
+ let text = '';
+ if (prop.value?.type === 'Literal' && typeof prop.value.value === 'string') {
+ text = prop.value.value;
+ } else if (prop.value?.type === 'TemplateLiteral') {
+ text = prop.value.quasis.map((q) => q.value.raw).join(' ');
+ }
+ return /\btranslate(X)?\s*\(/.test(text);
+ });
+}
+
const rule = {
meta: {
type: 'problem',
@@ -142,6 +180,10 @@ const rule = {
physicalKeyConflict:
'`{{physical}}` conflicts with `{{logical}}` already set on this ' +
'style object — remove `{{physical}}`.',
+ inlineCentering:
+ '`left: {{value}}` with a `translate` centers this element — do NOT ' +
+ 'rename it to `insetInlineStart` (that breaks centering under RTL). ' +
+ 'Use the shared `rtlStyles.centerInline(blockOffset)` helper instead.',
},
schema: [],
},
@@ -156,6 +198,18 @@ const rule = {
// KEY-BASED: the object key is itself a physical property.
const logicalKey = PHYSICAL_KEY_MAP[propName];
if (logicalKey) {
+ // Special case: `left: '50%'` + a centering `translate` must NOT be
+ // logicalized (it would break RTL centering). Point at the shared
+ // helper instead, and do NOT autofix.
+ if (propName === 'left' && isInlineCenteringLeft(node)) {
+ context.report({
+ node: node.key,
+ messageId: 'inlineCentering',
+ data: {value: getStaticValue(node.value)},
+ });
+ return;
+ }
+
// 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.
diff --git a/internal/eslint-plugin-astryx/no-physical-properties.test.mjs b/internal/eslint-plugin-astryx/no-physical-properties.test.mjs
index 0eff0a09b7..82d626f73b 100644
--- a/internal/eslint-plugin-astryx/no-physical-properties.test.mjs
+++ b/internal/eslint-plugin-astryx/no-physical-properties.test.mjs
@@ -163,6 +163,34 @@ ruleTester.run('no-physical-properties', rule, {
{messageId: 'physicalKey', data: {physical: 'left', logical: 'insetInlineStart'}},
],
},
+ // --- INLINE-CENTERING EXCEPTION: left:'50%' + translate must NOT be
+ // logicalized (breaks RTL centering); flagged with a distinct, non-fixing
+ // message pointing to rtlStyles.centerInline. output:null = unchanged. ---
+ {
+ code: inStylex(`left: '50%', transform: 'translate(-50%, 100%)'`),
+ output: null,
+ errors: [{messageId: 'inlineCentering', data: {value: '50%'}}],
+ },
+ {
+ code: inStylex(`left: '50%', transform: 'translateX(-50%)'`),
+ output: null,
+ errors: [{messageId: 'inlineCentering', data: {value: '50%'}}],
+ },
+ {
+ // template-literal transform (the dynamic-style form) is also detected
+ code: inStylex('left: \'50%\', transform: `translate(-50%, ${o})`'),
+ output: null,
+ errors: [{messageId: 'inlineCentering', data: {value: '50%'}}],
+ },
+ {
+ // left:'50%' WITHOUT a translate is NOT the centering idiom — normal
+ // physicalKey rename still applies.
+ code: inStylex(`left: '50%'`),
+ output: inStylex(`insetInlineStart: '50%'`),
+ errors: [
+ {messageId: 'physicalKey', data: {physical: 'left', logical: 'insetInlineStart'}},
+ ],
+ },
// --- KEY-BASED: corner radii (verify the diagonal mapping) ---
{
code: inStylex(`borderTopLeftRadius: 4`),
diff --git a/packages/core/src/utils/rtlStyles.ts b/packages/core/src/utils/rtlStyles.ts
index 40185df092..e44422e265 100644
--- a/packages/core/src/utils/rtlStyles.ts
+++ b/packages/core/src/utils/rtlStyles.ts
@@ -14,6 +14,23 @@
* down when expanded under RTL. The `:is([dir="rtl"] *)` selector matches the
* MobileNav drawer convention; a bare `direction: rtl` alone won't trigger it.
*
+ * `centerInline(blockOffset?)` horizontally centers an absolutely-positioned,
+ * auto-width element on the inline axis, correctly in BOTH LTR and RTL, with an
+ * optional block-axis (Y) offset composed into the same transform. It
+ * intentionally uses PHYSICAL `left: 50%` + `translateX(-50%)`: both reference
+ * the same physical edge, so the pair is direction-symmetric and centers
+ * identically regardless of `dir`. A logical `insetInlineStart: 50%` would flip
+ * the anchor edge in RTL while the physical translate does not, leaving the
+ * element off-center by its own width (centered in LTR, broken in RTL). This is
+ * the one case where physical `left` is the correct choice, so the
+ * `no-physical-properties` suppression lives here ONCE rather than at each call
+ * site. The `@astryx/no-physical-properties` lint recognises this exact pattern
+ * and points offenders here.
+ *
+ * `blockOffset` is any CSS length/percentage for translateY (pass `'0px'` for
+ * none): e.g. `centerInline('100%')` sits the element one full height below its
+ * anchor, `centerInline('-50%')` centers it on both axes.
+ *
* SYNC: When modified, update:
* - /packages/core/src/utils/index.ts
*/
@@ -24,4 +41,9 @@ export const rtlStyles = stylex.create({
mirror: {
transform: {default: null, ':is([dir="rtl"] *)': 'scaleX(-1)'},
},
+ centerInline: (blockOffset: string) => ({
+ // eslint-disable-next-line @astryx/no-physical-properties -- intentional: physical left+translateX(-50%) is direction-symmetric and the correct way to center; a logical anchor would break RTL centering (see file header).
+ left: '50%',
+ transform: `translate(-50%, ${blockOffset})`,
+ }),
});