rtl-shield 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Berkin Duz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# 🛡️ RTL Shield
+
+**Automated ESLint guardrails for robust RTL support in the GCC market.**
+
+[![npm version](https://img.shields.io/npm/v/eslint-plugin-rtl-shield.svg)](https://www.npmjs.com/package/eslint-plugin-rtl-shield)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## ⚠️ The Problem
+
+In the Middle East and North Africa (MENA) region, Arabic and other RTL (Right-to-Left) languages represent a massive market opportunity. However, **many engineering teams still build with physical CSS properties** like `left`, `right`, `marginLeft`, and `paddingRight`—properties that fundamentally break bidirectional layouts.
+
+### Why This Matters
+
+- **Physical properties are direction-specific**: `left: 10px` means "move 10px from the left edge"—in RTL, this is visually incorrect.
+- **Manual reviews are error-prone**: CSS property mapping is tedious and easy to overlook in code reviews.
+- **Scale is impossible**: As codebases grow, maintaining RTL consistency becomes exponentially harder without automation.
+- **Lost revenue**: Poorly localized experiences drive users away from your platform.
+
+**RTL Shield solves this at the source**—by enforcing logical CSS properties during development, ensuring your application is RTL-ready before it ships.
+
+---
+
+## ✨ Key Features
+
+### 🎨 **CSS-in-JS & Style Objects**
+
+Full support for React, Next.js, and JavaScript style objects (Emotion, Styled Components, inline styles, etc.)
+
+- Automatically detects and fixes physical properties
+- Works with object literals in JavaScript
+- Smart autofix saves hundreds of manual hours
+
+### 🌬️ **Tailwind CSS Support**
+
+Seamlessly handles Tailwind utility classes in `className` and `class` attributes
+
+- Converts `ml-4` → `ms-4`, `text-left` → `text-start`
+- Processes multiple classes in a single string
+- Fully compatible with Next.js and modern React projects
+
+### 🔄 **Comprehensive Property Mapping**
+
+Covers the full spectrum of directional CSS:
+
+- **Margins & Padding**: `marginLeft` → `marginInlineStart`
+- **Positioning**: `left` → `insetInlineStart`, `right` → `insetInlineEnd`
+- **Borders**: All variants—`borderLeft`, `borderLeftWidth`, `borderLeftColor`, etc.
+- **Border Radius**: Complex radius properties like `borderTopLeftRadius` → `borderStartStartRadius`
+
+### ⚡ **Smart Autofix**
+
+One command to fix your entire codebase:
+
+```bash
+eslint --fix
+```
+
+No manual intervention required—just commit and deploy.
+
+### 🎯 **Zero Configuration**
+
+The `recommended` preset works out-of-the-box with sensible defaults.
+
+---
+
+## 📦 Installation
+
+### Step 1: Install the Plugin
+
+```bash
+npm install --save-dev eslint-plugin-rtl-shield
+# or
+yarn add --dev eslint-plugin-rtl-shield
+# or
+pnpm add --save-dev eslint-plugin-rtl-shield
+```
+
+### Step 2: Configure ESLint
+
+Add the plugin to your ESLint configuration file (`.eslintrc.json`, `.eslintrc.js`, or `eslint.config.js`):
+
+#### Using the Recommended Config (Recommended ✅)
+
+```json
+{
+  "extends": ["plugin:rtl-shield/recommended"]
+}
+```
+
+This automatically enables both rules with error-level severity:
+
+- `rtl-shield/prefer-logical-properties` — for CSS-in-JS
+- `rtl-shield/prefer-logical-tailwindcss` — for Tailwind CSS
+
+#### Manual Configuration
+
+If you prefer granular control:
+
+```json
+{
+  "plugins": ["rtl-shield"],
+  "rules": {
+    "rtl-shield/prefer-logical-properties": "error",
+    "rtl-shield/prefer-logical-tailwindcss": "error"
+  }
+}
+```
+
+### Step 3: Run ESLint
+
+Lint your project:
+
+```bash
+eslint .
+```
+
+Auto-fix issues:
+
+```bash
+eslint --fix .
+```
+
+---
+
+## 📊 Showcase: Physical vs. Logical
+
+### CSS-in-JS / Style Objects
+
+| Physical (❌ Breaks RTL)  | Logical (✅ RTL-Ready)       | Use Case        |
+| ------------------------- | ---------------------------- | --------------- |
+| `marginLeft: 16`          | `marginInlineStart: 16`      | Outer spacing   |
+| `paddingRight: 8`         | `paddingInlineEnd: 8`        | Inner spacing   |
+| `left: 0`                 | `insetInlineStart: 0`        | Positioning     |
+| `right: 10`               | `insetInlineEnd: 10`         | Positioning     |
+| `borderLeftWidth: 2`      | `borderInlineStartWidth: 2`  | Border styling  |
+| `borderTopLeftRadius: 12` | `borderStartStartRadius: 12` | Rounded corners |
+
+### Tailwind CSS
+
+| Physical (❌ Breaks RTL) | Logical (✅ RTL-Ready) | Use Case                     |
+| ------------------------ | ---------------------- | ---------------------------- |
+| `ml-4`                   | `ms-4`                 | Margin start                 |
+| `mr-8`                   | `me-8`                 | Margin end                   |
+| `pl-2`                   | `ps-2`                 | Padding start                |
+| `pr-6`                   | `pe-6`                 | Padding end                  |
+| `text-left`              | `text-start`           | Text alignment               |
+| `text-right`             | `text-end`             | Text alignment               |
+| `rounded-tl-lg`          | `rounded-ss-lg`        | Border radius (top-left)     |
+| `rounded-br-md`          | `rounded-ee-md`        | Border radius (bottom-right) |
+| `left-0`                 | `start-0`              | Positioning                  |
+| `right-10`               | `end-10`               | Positioning                  |
+
+### Before & After Example
+
+**Before (Physical Properties):**
+
+```jsx
+// ❌ Breaks in Arabic/RTL
+const Card = () => (
+  <div className="ml-4 p-4 rounded-tl-lg">
+    <h1 style={{ paddingLeft: 16, textAlign: "left" }}>Title</h1>
+  </div>
+);
+```
+
+**After (Logical Properties):**
+
+```jsx
+// ✅ Works perfectly in RTL
+const Card = () => (
+  <div className="ms-4 p-4 rounded-ss-lg">
+    <h1 style={{ paddingInlineStart: 16, textAlign: "start" }}>Title</h1>
+  </div>
+);
+```
+
+---
+
+## 🌍 Why for the GCC Market?
+
+The GCC region (United Arab Emirates, Saudi Arabia, Qatar, Kuwait, Bahrain, and Oman) represents one of the fastest-growing digital markets:
+
+- **High-value market**: GCC users have the highest digital spending in the MENA region
+- **Native RTL requirement**: Arabic is a constitutional requirement in government and enterprise apps
+- **Business critical**: Improper RTL support directly impacts user trust and platform adoption
+- **Regulatory compliance**: Many GCC-based companies must meet localization standards
+- **Competitive advantage**: Teams that ship proper RTL support get better retention and market share
+
+**RTL Shield enables your engineering team to:**
+
+- Ship RTL-ready code from day one
+- Reduce localization QA cycles
+- Avoid expensive refactoring late in the project lifecycle
+- Build products that resonate with users across the MENA region
+
+---
+
+## 📋 Rules
+
+### `prefer-logical-properties`
+
+Enforces logical CSS properties in JavaScript style objects, preventing physical properties that break bidirectional layouts.
+
+**Type:** Suggestion
+**Fixable:** Yes ✅
+
+**Example:**
+
+```js
+// ❌ Error
+const styles = { marginLeft: 10, borderRightColor: "red" };
+
+// ✅ Correct
+const styles = { marginInlineStart: 10, borderInlineEndColor: "red" };
+```
+
+### `prefer-logical-tailwindcss`
+
+Enforces logical Tailwind CSS utility classes in JSX `className` and `class` attributes.
+
+**Type:** Suggestion
+**Fixable:** Yes ✅
+
+**Example:**
+
+```jsx
+// ❌ Error
+<div className="ml-4 text-left rounded-tl-lg" />
+
+// ✅ Correct
+<div className="ms-4 text-start rounded-ss-lg" />
+```
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# 1. Install
+npm install --save-dev eslint-plugin-rtl-shield
+
+# 2. Add to .eslintrc.json
+echo '{
+  "extends": ["plugin:rtl-shield/recommended"]
+}' > .eslintrc.json
+
+# 3. Fix all files
+npx eslint --fix .
+
+# 4. Commit and deploy
+git add .
+git commit -m "chore: enforce RTL-safe logical properties"
+```
+
+---
+
+## 📚 Resources
+
+- [MDN: CSS Logical Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties)
+- [Tailwind CSS: Logical Properties](https://tailwindcss.com/docs/guides/rtl)
+- [W3C: Structural Markup and Right-to-Left Text in HTML](https://www.w3.org/International/questions/qa-html-dir)
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please feel free to open issues or submit pull requests on [GitHub](https://github.com/berkinduz/rtl-shield).
+
+---
+
+## 📄 License
+
+MIT © 2025 [Berkin Duz](https://github.com/berkinduz)
+
+---
+
+## 💡 Support
+
+Have questions or feedback? Open an issue on our [GitHub repository](https://github.com/berkinduz/rtl-shield/issues).
+
+**Built with ❤️ for the GCC market and the broader MENA region.**

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import type { Rule } from "eslint";
+declare const _default: {
+    rules: Record<string, Rule.RuleModule>;
+    configs: {
+        recommended: {
+            plugins: string[];
+            rules: {
+                "rtl-shield/prefer-logical-properties": string;
+                "rtl-shield/prefer-logical-tailwindcss": string;
+            };
+        };
+    };
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const prefer_logical_properties_1 = __importDefault(require("./rules/prefer-logical-properties"));
+const prefer_logical_tailwindcss_1 = __importDefault(require("./rules/prefer-logical-tailwindcss"));
+const rules = {
+    "prefer-logical-properties": prefer_logical_properties_1.default,
+    "prefer-logical-tailwindcss": prefer_logical_tailwindcss_1.default,
+};
+const configs = {
+    recommended: {
+        plugins: ["rtl-shield"],
+        rules: {
+            "rtl-shield/prefer-logical-properties": "error",
+            "rtl-shield/prefer-logical-tailwindcss": "error",
+        },
+    },
+};
+exports.default = {
+    rules,
+    configs,
+};

package/dist/rules/prefer-logical-properties.d.ts

@@ -0,0 +1,3 @@
+import { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/rules/prefer-logical-properties.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const PHYSICAL_TO_LOGICAL = {
+    marginLeft: "marginInlineStart",
+    marginRight: "marginInlineEnd",
+    paddingLeft: "paddingInlineStart",
+    paddingRight: "paddingInlineEnd",
+    left: "insetInlineStart",
+    right: "insetInlineEnd",
+    borderTopLeftRadius: "borderStartStartRadius",
+    borderBottomLeftRadius: "borderStartEndRadius",
+    borderTopRightRadius: "borderEndStartRadius",
+    borderBottomRightRadius: "borderEndEndRadius",
+    borderLeft: "borderInlineStart",
+    borderRight: "borderInlineEnd",
+    borderLeftWidth: "borderInlineStartWidth",
+    borderRightWidth: "borderInlineEndWidth",
+    borderLeftStyle: "borderInlineStartStyle",
+    borderRightStyle: "borderInlineEndStyle",
+    borderLeftColor: "borderInlineStartColor",
+    borderRightColor: "borderInlineEndColor",
+};
+const TEXT_ALIGN_MAPPING = {
+    left: "start",
+    right: "end",
+};
+const rule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Enforce CSS Logical Properties instead of physical properties for better RTL support",
+            recommended: true,
+        },
+        fixable: "code",
+        schema: [],
+    },
+    create(context) {
+        return {
+            Property(node) {
+                // Check if this is a property with an Identifier or Literal key
+                const key = node.key;
+                let propName = "";
+                if (key.type === "Identifier") {
+                    propName = key.name;
+                }
+                else if (key.type === "Literal" && typeof key.value === "string") {
+                    propName = key.value;
+                }
+                // Check for physical properties that should be logical
+                if (propName in PHYSICAL_TO_LOGICAL) {
+                    const logicalProperty = PHYSICAL_TO_LOGICAL[propName];
+                    context.report({
+                        node,
+                        message: `Use logical property '${logicalProperty}' instead of '${propName}' for better RTL support`,
+                        fix(fixer) {
+                            return fixer.replaceText(key, logicalProperty);
+                        },
+                    });
+                }
+                // Check for textAlign property
+                if (propName === "textAlign") {
+                    const value = node.value;
+                    if (value.type === "Literal" &&
+                        typeof value.value === "string" &&
+                        value.value in TEXT_ALIGN_MAPPING) {
+                        const logicalValue = TEXT_ALIGN_MAPPING[value.value];
+                        context.report({
+                            node: value,
+                            message: `Use textAlign: '${logicalValue}' instead of '${value.value}' for better RTL support`,
+                            fix(fixer) {
+                                return fixer.replaceText(value, `'${logicalValue}'`);
+                            },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

package/dist/rules/prefer-logical-tailwindcss.d.ts

@@ -0,0 +1,3 @@
+import { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/rules/prefer-logical-tailwindcss.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Mapping of physical Tailwind classes to their logical counterparts
+const TAILWIND_PHYSICAL_TO_LOGICAL = {
+    "ml-": "ms-",
+    "mr-": "me-",
+    "pl-": "ps-",
+    "pr-": "pe-",
+    "text-left": "text-start",
+    "text-right": "text-end",
+    "rounded-tl-": "rounded-ss-",
+    "rounded-tr-": "rounded-se-",
+    "rounded-bl-": "rounded-es-",
+    "rounded-br-": "rounded-ee-",
+    "left-": "start-",
+    "right-": "end-",
+};
+const EXACT_REPLACEMENTS = {
+    "text-left": "text-start",
+    "text-right": "text-end",
+};
+/**
+ * Replace physical Tailwind classes with their logical equivalents
+ */
+function replaceClassesInString(str) {
+    let result = str;
+    // First, handle exact replacements (e.g., text-left -> text-start)
+    for (const [physical, logical] of Object.entries(EXACT_REPLACEMENTS)) {
+        result = result.replace(new RegExp(`\\b${physical}\\b`, "g"), logical);
+    }
+    // Then handle prefix replacements (e.g., ml- -> ms-)
+    // We need to be careful to match the full class name
+    for (const [physical, logical] of Object.entries(TAILWIND_PHYSICAL_TO_LOGICAL)) {
+        // Skip exact replacements as they're already handled
+        if (physical in EXACT_REPLACEMENTS)
+            continue;
+        // Create a regex that matches the physical prefix followed by any characters until whitespace or end
+        const regex = new RegExp(`\\b${physical.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([a-zA-Z0-9-]*)\\b`, "g");
+        result = result.replace(regex, `${logical}$1`);
+    }
+    return result;
+}
+/**
+ * Check if a string contains any physical Tailwind classes that need to be replaced
+ */
+function hasPhysicalClasses(str) {
+    // Check for exact matches first
+    for (const physical of Object.keys(EXACT_REPLACEMENTS)) {
+        if (new RegExp(`\\b${physical}\\b`).test(str)) {
+            return true;
+        }
+    }
+    // Check for prefix matches
+    for (const physical of Object.keys(TAILWIND_PHYSICAL_TO_LOGICAL)) {
+        if (physical in EXACT_REPLACEMENTS)
+            continue;
+        if (new RegExp(`\\b${physical.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`).test(str)) {
+            return true;
+        }
+    }
+    return false;
+}
+const rule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Enforce logical Tailwind CSS classes instead of physical ones for better RTL support",
+            recommended: true,
+        },
+        fixable: "code",
+        schema: [],
+    },
+    create(context) {
+        return {
+            Literal(node) {
+                // Check if this is a className or class attribute value
+                if (typeof node.value !== "string") {
+                    return;
+                }
+                const value = node.value;
+                // Only process if this looks like a className/class value
+                if (!hasPhysicalClasses(value)) {
+                    return;
+                }
+                // Check if the parent is a JSXAttribute with name "className" or "class"
+                const parent = node.parent;
+                if (parent && parent.type === "JSXExpressionContainer") {
+                    // Parent is within a JSX expression container
+                    const grandParent = parent.parent;
+                    if (grandParent &&
+                        grandParent.type === "JSXAttribute" &&
+                        (grandParent.name.name === "className" ||
+                            grandParent.name.name === "class")) {
+                        const logicalValue = replaceClassesInString(value);
+                        if (logicalValue !== value) {
+                            context.report({
+                                node,
+                                message: "Use logical Tailwind CSS classes instead of physical ones for better RTL support",
+                                fix(fixer) {
+                                    return fixer.replaceText(node, `"${logicalValue}"`);
+                                },
+                            });
+                        }
+                    }
+                }
+                else if (parent && parent.type === "JSXAttribute") {
+                    // Direct attribute value
+                    if (parent.name.name === "className" ||
+                        parent.name.name === "class") {
+                        const logicalValue = replaceClassesInString(value);
+                        if (logicalValue !== value) {
+                            context.report({
+                                node,
+                                message: "Use logical Tailwind CSS classes instead of physical ones for better RTL support",
+                                fix(fixer) {
+                                    return fixer.replaceText(node, `"${logicalValue}"`);
+                                },
+                            });
+                        }
+                    }
+                }
+            },
+            TemplateElement(node) {
+                // Handle template literals in className attributes
+                const value = node.value.raw;
+                if (!hasPhysicalClasses(value)) {
+                    return;
+                }
+                // Check if this is part of a template literal in className
+                const parent = node.parent;
+                if (parent && parent.type === "TemplateLiteral") {
+                    const grandParent = parent.parent;
+                    if (grandParent &&
+                        grandParent.type === "JSXExpressionContainer" &&
+                        grandParent.parent &&
+                        grandParent.parent.type === "JSXAttribute") {
+                        const attr = grandParent.parent;
+                        if (attr.name.name === "className" || attr.name.name === "class") {
+                            const logicalValue = replaceClassesInString(value);
+                            if (logicalValue !== value) {
+                                context.report({
+                                    node,
+                                    message: "Use logical Tailwind CSS classes instead of physical ones for better RTL support",
+                                    fix(fixer) {
+                                        return fixer.replaceText(node, logicalValue);
+                                    },
+                                });
+                            }
+                        }
+                    }
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "rtl-shield",
+  "version": "0.1.0",
+  "description": "ESLint plugin to enforce CSS Logical Properties for robust RTL support",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "prepublishOnly": "npm run build && npm run test -- --run"
+  },
+  "keywords": [
+    "eslint",
+    "eslint-plugin",
+    "rtl",
+    "css-logical-properties",
+    "i18n"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/berkinduz/rtl-shield.git"
+  },
+  "bugs": {
+    "url": "https://github.com/berkinduz/rtl-shield/issues"
+  },
+  "homepage": "https://github.com/berkinduz/rtl-shield#readme",
+  "peerDependencies": {
+    "eslint": "^8.0.0 || ^9.0.0"
+  },
+  "dependencies": {
+    "@typescript-eslint/utils": "^6.0.0"
+  },
+  "devDependencies": {
+    "@babel/eslint-parser": "^7.28.5",
+    "@babel/preset-react": "^7.28.5",
+    "@types/eslint": "^9.6.1",
+    "@types/node": "^20.0.0",
+    "eslint": "^8.0.0",
+    "espree": "^11.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}