@mgcrea/react-native-tailwind 0.13.0 → 0.15.0

package/src/parser/layout.test.ts

@@ -645,3 +645,171 @@ describe("parseLayout - specific property coverage", () => {
     expect(insetY).not.toHaveProperty("right");
   });
 });
+
+describe("parseLayout - logical positioning (RTL-aware)", () => {
+  it("should parse start positioning with preset values", () => {
+    expect(parseLayout("start-0")).toEqual({ start: 0 });
+    expect(parseLayout("start-4")).toEqual({ start: 16 });
+    expect(parseLayout("start-8")).toEqual({ start: 32 });
+    expect(parseLayout("start-0.5")).toEqual({ start: 2 });
+    expect(parseLayout("start-2.5")).toEqual({ start: 10 });
+  });
+
+  it("should parse end positioning with preset values", () => {
+    expect(parseLayout("end-0")).toEqual({ end: 0 });
+    expect(parseLayout("end-4")).toEqual({ end: 16 });
+    expect(parseLayout("end-8")).toEqual({ end: 32 });
+    expect(parseLayout("end-0.5")).toEqual({ end: 2 });
+    expect(parseLayout("end-2.5")).toEqual({ end: 10 });
+  });
+
+  it("should parse start/end with arbitrary pixel values", () => {
+    expect(parseLayout("start-[10px]")).toEqual({ start: 10 });
+    expect(parseLayout("start-[50]")).toEqual({ start: 50 });
+    expect(parseLayout("end-[10px]")).toEqual({ end: 10 });
+    expect(parseLayout("end-[50]")).toEqual({ end: 50 });
+  });
+
+  it("should parse start/end with arbitrary percentage values", () => {
+    expect(parseLayout("start-[10%]")).toEqual({ start: "10%" });
+    expect(parseLayout("start-[50%]")).toEqual({ start: "50%" });
+    expect(parseLayout("end-[10%]")).toEqual({ end: "10%" });
+    expect(parseLayout("end-[50%]")).toEqual({ end: "50%" });
+  });
+
+  it("should parse negative start/end with preset values", () => {
+    expect(parseLayout("-start-4")).toEqual({ start: -16 });
+    expect(parseLayout("-start-8")).toEqual({ start: -32 });
+    expect(parseLayout("-end-4")).toEqual({ end: -16 });
+    expect(parseLayout("-end-8")).toEqual({ end: -32 });
+  });
+
+  it("should parse negative start/end with arbitrary values", () => {
+    expect(parseLayout("-start-[10px]")).toEqual({ start: -10 });
+    expect(parseLayout("-start-[50]")).toEqual({ start: -50 });
+    expect(parseLayout("-end-[10px]")).toEqual({ end: -10 });
+    expect(parseLayout("-end-[50]")).toEqual({ end: -50 });
+    expect(parseLayout("-start-[10%]")).toEqual({ start: "-10%" });
+    expect(parseLayout("-end-[25%]")).toEqual({ end: "-25%" });
+  });
+
+  it("should handle auto value for start/end", () => {
+    expect(parseLayout("start-auto")).toEqual({});
+    expect(parseLayout("end-auto")).toEqual({});
+  });
+});
+
+describe("parseLayout - logical inset (RTL-aware)", () => {
+  it("should parse inset-s (start) with preset values", () => {
+    expect(parseLayout("inset-s-0")).toEqual({ start: 0 });
+    expect(parseLayout("inset-s-4")).toEqual({ start: 16 });
+    expect(parseLayout("inset-s-8")).toEqual({ start: 32 });
+  });
+
+  it("should parse inset-e (end) with preset values", () => {
+    expect(parseLayout("inset-e-0")).toEqual({ end: 0 });
+    expect(parseLayout("inset-e-4")).toEqual({ end: 16 });
+    expect(parseLayout("inset-e-8")).toEqual({ end: 32 });
+  });
+
+  it("should parse inset-s/inset-e with arbitrary values", () => {
+    expect(parseLayout("inset-s-[10px]")).toEqual({ start: 10 });
+    expect(parseLayout("inset-s-[20%]")).toEqual({ start: "20%" });
+    expect(parseLayout("inset-e-[10px]")).toEqual({ end: 10 });
+    expect(parseLayout("inset-e-[20%]")).toEqual({ end: "20%" });
+  });
+});
+
+describe("parseLayout - custom spacing", () => {
+  const customSpacing = {
+    xs: 4,
+    sm: 8,
+    md: 16,
+    lg: 32,
+    xl: 64,
+    "4": 20, // Override default (16)
+  };
+
+  it("should support custom spacing values for top/right/bottom/left", () => {
+    expect(parseLayout("top-xs", customSpacing)).toEqual({ top: 4 });
+    expect(parseLayout("top-sm", customSpacing)).toEqual({ top: 8 });
+    expect(parseLayout("top-md", customSpacing)).toEqual({ top: 16 });
+    expect(parseLayout("top-lg", customSpacing)).toEqual({ top: 32 });
+    expect(parseLayout("top-xl", customSpacing)).toEqual({ top: 64 });
+
+    expect(parseLayout("right-xs", customSpacing)).toEqual({ right: 4 });
+    expect(parseLayout("bottom-sm", customSpacing)).toEqual({ bottom: 8 });
+    expect(parseLayout("left-md", customSpacing)).toEqual({ left: 16 });
+  });
+
+  it("should override default spacing values", () => {
+    // Without custom spacing, top-4 is 16
+    expect(parseLayout("top-4")).toEqual({ top: 16 });
+
+    // With custom spacing, top-4 is 20 (overridden)
+    expect(parseLayout("top-4", customSpacing)).toEqual({ top: 20 });
+  });
+
+  it("should merge custom spacing with defaults", () => {
+    // Custom spacing should merge with defaults
+    // top-0 should still work (from defaults)
+    expect(parseLayout("top-0", customSpacing)).toEqual({ top: 0 });
+
+    // top-8 should still work (from defaults, not overridden)
+    expect(parseLayout("top-8", customSpacing)).toEqual({ top: 32 });
+
+    // top-xs should work (from custom)
+    expect(parseLayout("top-xs", customSpacing)).toEqual({ top: 4 });
+  });
+
+  it("should support custom spacing for start/end (RTL-aware)", () => {
+    expect(parseLayout("start-xs", customSpacing)).toEqual({ start: 4 });
+    expect(parseLayout("end-lg", customSpacing)).toEqual({ end: 32 });
+  });
+
+  it("should support custom spacing for inset utilities", () => {
+    expect(parseLayout("inset-xs", customSpacing)).toEqual({
+      top: 4,
+      right: 4,
+      bottom: 4,
+      left: 4,
+    });
+
+    expect(parseLayout("inset-x-sm", customSpacing)).toEqual({
+      left: 8,
+      right: 8,
+    });
+
+    expect(parseLayout("inset-y-md", customSpacing)).toEqual({
+      top: 16,
+      bottom: 16,
+    });
+  });
+
+  it("should support custom spacing for inset-s/inset-e", () => {
+    expect(parseLayout("inset-s-lg", customSpacing)).toEqual({ start: 32 });
+    expect(parseLayout("inset-e-xl", customSpacing)).toEqual({ end: 64 });
+  });
+
+  it("should support negative values with custom spacing for start/end", () => {
+    // Note: -top-*, -left-*, -right-*, -bottom-* negative prefixes are not supported
+    // Use arbitrary values like top-[-10px] for negative positioning
+    expect(parseLayout("-start-sm", customSpacing)).toEqual({ start: -8 });
+    expect(parseLayout("-end-md", customSpacing)).toEqual({ end: -16 });
+  });
+
+  it("should still support arbitrary values with custom spacing", () => {
+    expect(parseLayout("top-[100px]", customSpacing)).toEqual({ top: 100 });
+    expect(parseLayout("inset-[50%]", customSpacing)).toEqual({
+      top: "50%",
+      right: "50%",
+      bottom: "50%",
+      left: "50%",
+    });
+  });
+
+  it("should handle non-layout classes as null", () => {
+    expect(parseLayout("text-xl", customSpacing)).toBeNull();
+    expect(parseLayout("bg-blue-500", customSpacing)).toBeNull();
+  });
+});

package/src/parser/layout.ts

@@ -237,8 +237,13 @@ export const INSET_SCALE: Record<string, number> = {
 
 /**
  * Parse layout classes
+ * @param cls - The class name to parse
+ * @param customSpacing - Optional custom spacing values from tailwind.config (for inset utilities)
  */
-export function parseLayout(cls: string): StyleObject | null {
+export function parseLayout(cls: string, customSpacing?: Record<string, number>): StyleObject | null {
+  // Merge custom spacing with defaults for inset utilities
+  const insetMap = customSpacing ? { ...INSET_SCALE, ...customSpacing } : INSET_SCALE;
+
   // Z-index: z-0, z-10, z-20, z-[999], etc.
   if (cls.startsWith("z-")) {
     const zKey = cls.substring(2);
@@ -270,7 +275,7 @@ export function parseLayout(cls: string): StyleObject | null {
       return { top: arbitraryTop };
     }
 
-    const topValue = INSET_SCALE[topKey];
+    const topValue = insetMap[topKey];
     if (topValue !== undefined) {
       return { top: topValue };
     }
@@ -291,7 +296,7 @@ export function parseLayout(cls: string): StyleObject | null {
       return { right: arbitraryRight };
     }
 
-    const rightValue = INSET_SCALE[rightKey];
+    const rightValue = insetMap[rightKey];
     if (rightValue !== undefined) {
       return { right: rightValue };
     }
@@ -312,7 +317,7 @@ export function parseLayout(cls: string): StyleObject | null {
       return { bottom: arbitraryBottom };
     }
 
-    const bottomValue = INSET_SCALE[bottomKey];
+    const bottomValue = insetMap[bottomKey];
     if (bottomValue !== undefined) {
       return { bottom: bottomValue };
     }
@@ -333,12 +338,74 @@ export function parseLayout(cls: string): StyleObject | null {
       return { left: arbitraryLeft };
     }
 
-    const leftValue = INSET_SCALE[leftKey];
+    const leftValue = insetMap[leftKey];
     if (leftValue !== undefined) {
       return { left: leftValue };
     }
   }
 
+  // Start positioning (RTL-aware): start-0, start-4, start-[10px], -start-4, etc.
+  const startMatch = cls.match(/^(-?)start-(.+)$/);
+  if (startMatch) {
+    const [, negPrefix, startKey] = startMatch;
+    const isNegative = negPrefix === "-";
+
+    // Auto value - return empty object (no-op, removes the property)
+    if (startKey === "auto") {
+      return {};
+    }
+
+    // Arbitrary values: start-[123px], start-[50%], -start-[10px]
+    const arbitraryStart = parseArbitraryInset(startKey);
+    if (arbitraryStart !== null) {
+      if (typeof arbitraryStart === "number") {
+        return { start: isNegative ? -arbitraryStart : arbitraryStart };
+      }
+      // Percentage values with negative prefix
+      if (isNegative && arbitraryStart.endsWith("%")) {
+        const numValue = parseFloat(arbitraryStart);
+        return { start: `${-numValue}%` };
+      }
+      return { start: arbitraryStart };
+    }
+
+    const startValue = insetMap[startKey];
+    if (startValue !== undefined) {
+      return { start: isNegative ? -startValue : startValue };
+    }
+  }
+
+  // End positioning (RTL-aware): end-0, end-4, end-[10px], -end-4, etc.
+  const endMatch = cls.match(/^(-?)end-(.+)$/);
+  if (endMatch) {
+    const [, negPrefix, endKey] = endMatch;
+    const isNegative = negPrefix === "-";
+
+    // Auto value - return empty object (no-op, removes the property)
+    if (endKey === "auto") {
+      return {};
+    }
+
+    // Arbitrary values: end-[123px], end-[50%], -end-[10px]
+    const arbitraryEnd = parseArbitraryInset(endKey);
+    if (arbitraryEnd !== null) {
+      if (typeof arbitraryEnd === "number") {
+        return { end: isNegative ? -arbitraryEnd : arbitraryEnd };
+      }
+      // Percentage values with negative prefix
+      if (isNegative && arbitraryEnd.endsWith("%")) {
+        const numValue = parseFloat(arbitraryEnd);
+        return { end: `${-numValue}%` };
+      }
+      return { end: arbitraryEnd };
+    }
+
+    const endValue = insetMap[endKey];
+    if (endValue !== undefined) {
+      return { end: isNegative ? -endValue : endValue };
+    }
+  }
+
   // Inset X (left and right): inset-x-0, inset-x-4, inset-x-[10px], etc.
   if (cls.startsWith("inset-x-")) {
     const insetKey = cls.substring(8);
@@ -349,7 +416,7 @@ export function parseLayout(cls: string): StyleObject | null {
       return { left: arbitraryInset, right: arbitraryInset };
     }
 
-    const insetValue = INSET_SCALE[insetKey];
+    const insetValue = insetMap[insetKey];
     if (insetValue !== undefined) {
       return { left: insetValue, right: insetValue };
     }
@@ -365,12 +432,44 @@ export function parseLayout(cls: string): StyleObject | null {
       return { top: arbitraryInset, bottom: arbitraryInset };
     }
 
-    const insetValue = INSET_SCALE[insetKey];
+    const insetValue = insetMap[insetKey];
     if (insetValue !== undefined) {
       return { top: insetValue, bottom: insetValue };
     }
   }
 
+  // Inset S (start, RTL-aware): inset-s-0, inset-s-4, inset-s-[10px], etc.
+  if (cls.startsWith("inset-s-")) {
+    const insetKey = cls.substring(8);
+
+    // Arbitrary values: inset-s-[123px], inset-s-[50%]
+    const arbitraryInset = parseArbitraryInset(insetKey);
+    if (arbitraryInset !== null) {
+      return { start: arbitraryInset };
+    }
+
+    const insetValue = insetMap[insetKey];
+    if (insetValue !== undefined) {
+      return { start: insetValue };
+    }
+  }
+
+  // Inset E (end, RTL-aware): inset-e-0, inset-e-4, inset-e-[10px], etc.
+  if (cls.startsWith("inset-e-")) {
+    const insetKey = cls.substring(8);
+
+    // Arbitrary values: inset-e-[123px], inset-e-[50%]
+    const arbitraryInset = parseArbitraryInset(insetKey);
+    if (arbitraryInset !== null) {
+      return { end: arbitraryInset };
+    }
+
+    const insetValue = insetMap[insetKey];
+    if (insetValue !== undefined) {
+      return { end: insetValue };
+    }
+  }
+
   // Inset (all sides): inset-0, inset-4, inset-[10px], etc.
   if (cls.startsWith("inset-")) {
     const insetKey = cls.substring(6);
@@ -381,7 +480,7 @@ export function parseLayout(cls: string): StyleObject | null {
       return { top: arbitraryInset, right: arbitraryInset, bottom: arbitraryInset, left: arbitraryInset };
     }
 
-    const insetValue = INSET_SCALE[insetKey];
+    const insetValue = insetMap[insetKey];
     if (insetValue !== undefined) {
       return { top: insetValue, right: insetValue, bottom: insetValue, left: insetValue };
     }

package/src/parser/modifiers.test.ts

@@ -4,7 +4,11 @@ import {
   expandSchemeModifier,
   hasModifier,
   isColorClass,
+  isColorSchemeModifier,
+  isDirectionalModifier,
+  isPlatformModifier,
   isSchemeModifier,
+  isStateModifier,
   parseModifier,
   splitModifierClasses,
 } from "./modifiers";
@@ -523,3 +527,205 @@ describe("expandSchemeModifier", () => {
     expect(result).toEqual([]);
   });
 });
+
+describe("parseModifier - directional modifiers (rtl/ltr)", () => {
+  it("should parse rtl modifier", () => {
+    const result = parseModifier("rtl:text-right");
+    expect(result).toEqual({
+      modifier: "rtl",
+      baseClass: "text-right",
+    });
+  });
+
+  it("should parse ltr modifier", () => {
+    const result = parseModifier("ltr:text-left");
+    expect(result).toEqual({
+      modifier: "ltr",
+      baseClass: "text-left",
+    });
+  });
+
+  it("should parse directional modifiers with various base classes", () => {
+    expect(parseModifier("rtl:ms-4")).toEqual({
+      modifier: "rtl",
+      baseClass: "ms-4",
+    });
+    expect(parseModifier("ltr:me-4")).toEqual({
+      modifier: "ltr",
+      baseClass: "me-4",
+    });
+    expect(parseModifier("rtl:flex-row-reverse")).toEqual({
+      modifier: "rtl",
+      baseClass: "flex-row-reverse",
+    });
+  });
+});
+
+describe("modifier type check functions", () => {
+  it("should identify state modifiers", () => {
+    expect(isStateModifier("active")).toBe(true);
+    expect(isStateModifier("hover")).toBe(true);
+    expect(isStateModifier("focus")).toBe(true);
+    expect(isStateModifier("disabled")).toBe(true);
+    expect(isStateModifier("placeholder")).toBe(true);
+    expect(isStateModifier("ios")).toBe(false);
+    expect(isStateModifier("dark")).toBe(false);
+    expect(isStateModifier("rtl")).toBe(false);
+  });
+
+  it("should identify platform modifiers", () => {
+    expect(isPlatformModifier("ios")).toBe(true);
+    expect(isPlatformModifier("android")).toBe(true);
+    expect(isPlatformModifier("web")).toBe(true);
+    expect(isPlatformModifier("active")).toBe(false);
+    expect(isPlatformModifier("dark")).toBe(false);
+    expect(isPlatformModifier("rtl")).toBe(false);
+  });
+
+  it("should identify color scheme modifiers", () => {
+    expect(isColorSchemeModifier("dark")).toBe(true);
+    expect(isColorSchemeModifier("light")).toBe(true);
+    expect(isColorSchemeModifier("active")).toBe(false);
+    expect(isColorSchemeModifier("ios")).toBe(false);
+    expect(isColorSchemeModifier("rtl")).toBe(false);
+  });
+
+  it("should identify directional modifiers", () => {
+    expect(isDirectionalModifier("rtl")).toBe(true);
+    expect(isDirectionalModifier("ltr")).toBe(true);
+    expect(isDirectionalModifier("active")).toBe(false);
+    expect(isDirectionalModifier("ios")).toBe(false);
+    expect(isDirectionalModifier("dark")).toBe(false);
+  });
+
+  it("should identify scheme modifier", () => {
+    expect(isSchemeModifier("scheme")).toBe(true);
+    expect(isSchemeModifier("active")).toBe(false);
+    expect(isSchemeModifier("dark")).toBe(false);
+    expect(isSchemeModifier("rtl")).toBe(false);
+  });
+});
+
+describe("splitModifierClasses - directional modifiers", () => {
+  it("should split directional modifier classes", () => {
+    const result = splitModifierClasses("bg-white rtl:bg-gray-100 ltr:bg-gray-50");
+    expect(result.baseClasses).toEqual(["bg-white"]);
+    expect(result.modifierClasses).toHaveLength(2);
+    expect(result.modifierClasses[0]).toEqual({
+      modifier: "rtl",
+      baseClass: "bg-gray-100",
+    });
+    expect(result.modifierClasses[1]).toEqual({
+      modifier: "ltr",
+      baseClass: "bg-gray-50",
+    });
+  });
+
+  it("should handle mixed modifiers including directional", () => {
+    const result = splitModifierClasses("p-4 rtl:ps-6 ios:p-8 dark:bg-gray-900");
+    expect(result.baseClasses).toEqual(["p-4"]);
+    expect(result.modifierClasses).toHaveLength(3);
+    expect(result.modifierClasses.map((m) => m.modifier)).toContain("rtl");
+    expect(result.modifierClasses.map((m) => m.modifier)).toContain("ios");
+    expect(result.modifierClasses.map((m) => m.modifier)).toContain("dark");
+  });
+});
+
+describe("splitModifierClasses - text-start/text-end expansion", () => {
+  it("should expand text-start to ltr:text-left rtl:text-right", () => {
+    const result = splitModifierClasses("text-start");
+    expect(result.baseClasses).toEqual([]);
+    expect(result.modifierClasses).toHaveLength(2);
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "ltr",
+      baseClass: "text-left",
+    });
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "rtl",
+      baseClass: "text-right",
+    });
+  });
+
+  it("should expand text-end to ltr:text-right rtl:text-left", () => {
+    const result = splitModifierClasses("text-end");
+    expect(result.baseClasses).toEqual([]);
+    expect(result.modifierClasses).toHaveLength(2);
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "ltr",
+      baseClass: "text-right",
+    });
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "rtl",
+      baseClass: "text-left",
+    });
+  });
+
+  it("should handle text-start with other classes", () => {
+    const result = splitModifierClasses("p-4 text-start bg-white");
+    expect(result.baseClasses).toEqual(["p-4", "bg-white"]);
+    expect(result.modifierClasses).toHaveLength(2);
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "ltr",
+      baseClass: "text-left",
+    });
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "rtl",
+      baseClass: "text-right",
+    });
+  });
+
+  it("should handle both text-start and text-end in same className", () => {
+    // This is unusual but should work
+    const result = splitModifierClasses("text-start text-end");
+    expect(result.baseClasses).toEqual([]);
+    expect(result.modifierClasses).toHaveLength(4);
+    // text-start expands
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "ltr",
+      baseClass: "text-left",
+    });
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "rtl",
+      baseClass: "text-right",
+    });
+    // text-end expands
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "ltr",
+      baseClass: "text-right",
+    });
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "rtl",
+      baseClass: "text-left",
+    });
+  });
+
+  it("should not affect text-left and text-right (no expansion)", () => {
+    const result = splitModifierClasses("text-left text-right text-center");
+    expect(result.baseClasses).toEqual(["text-left", "text-right", "text-center"]);
+    expect(result.modifierClasses).toEqual([]);
+  });
+
+  it("should handle text-start/text-end with other modifiers", () => {
+    const result = splitModifierClasses("text-start active:bg-blue-500 rtl:pr-4");
+    expect(result.baseClasses).toEqual([]);
+    expect(result.modifierClasses).toHaveLength(4);
+    // text-start expansion
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "ltr",
+      baseClass: "text-left",
+    });
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "rtl",
+      baseClass: "text-right",
+    });
+    // explicit modifiers
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "active",
+      baseClass: "bg-blue-500",
+    });
+    expect(result.modifierClasses).toContainEqual({
+      modifier: "rtl",
+      baseClass: "pr-4",
+    });
+  });
+});

package/src/parser/modifiers.ts

@@ -1,19 +1,22 @@
 /**
- * Modifier parsing utilities for state-based, platform-specific, and color scheme class names
+ * Modifier parsing utilities for state-based, platform-specific, color scheme, and directional class names
  * - State modifiers: active:, hover:, focus:, disabled:, placeholder:
  * - Platform modifiers: ios:, android:, web:
  * - Color scheme modifiers: dark:, light:
+ * - Directional modifiers: rtl:, ltr: (RTL-aware styling)
  */
 
 export type StateModifierType = "active" | "hover" | "focus" | "disabled" | "placeholder";
 export type PlatformModifierType = "ios" | "android" | "web";
 export type ColorSchemeModifierType = "dark" | "light";
 export type SchemeModifierType = "scheme";
+export type DirectionalModifierType = "rtl" | "ltr";
 export type ModifierType =
   | StateModifierType
   | PlatformModifierType
   | ColorSchemeModifierType
-  | SchemeModifierType;
+  | SchemeModifierType
+  | DirectionalModifierType;
 
 export type ParsedModifier = {
   modifier: ModifierType;
@@ -47,13 +50,19 @@ const COLOR_SCHEME_MODIFIERS: readonly ColorSchemeModifierType[] = ["dark", "lig
 const SCHEME_MODIFIERS: readonly SchemeModifierType[] = ["scheme"] as const;
 
 /**
- * All supported modifiers (state + platform + color scheme + scheme)
+ * Supported directional modifiers that map to I18nManager.isRTL values
+ */
+const DIRECTIONAL_MODIFIERS: readonly DirectionalModifierType[] = ["rtl", "ltr"] as const;
+
+/**
+ * All supported modifiers (state + platform + color scheme + scheme + directional)
  */
 const SUPPORTED_MODIFIERS: readonly ModifierType[] = [
   ...STATE_MODIFIERS,
   ...PLATFORM_MODIFIERS,
   ...COLOR_SCHEME_MODIFIERS,
   ...SCHEME_MODIFIERS,
+  ...DIRECTIONAL_MODIFIERS,
 ] as const;
 
 /**
@@ -149,6 +158,16 @@ export function isSchemeModifier(modifier: ModifierType): modifier is SchemeModi
   return SCHEME_MODIFIERS.includes(modifier as SchemeModifierType);
 }
 
+/**
+ * Check if a modifier is a directional modifier (rtl, ltr)
+ *
+ * @param modifier - Modifier type to check
+ * @returns true if modifier is a directional modifier
+ */
+export function isDirectionalModifier(modifier: ModifierType): modifier is DirectionalModifierType {
+  return DIRECTIONAL_MODIFIERS.includes(modifier as DirectionalModifierType);
+}
+
 /**
  * Check if a class name is a color-based utility class
  *
@@ -242,6 +261,26 @@ export function expandSchemeModifier(
   ];
 }
 
+/**
+ * Classes that expand to directional modifiers for true RTL support
+ * text-start -> ltr:text-left rtl:text-right (start = left in LTR, right in RTL)
+ * text-end -> ltr:text-right rtl:text-left (end = right in LTR, left in RTL)
+ */
+const DIRECTIONAL_TEXT_ALIGN_EXPANSIONS: Record<string, { ltr: string; rtl: string }> = {
+  "text-start": { ltr: "text-left", rtl: "text-right" },
+  "text-end": { ltr: "text-right", rtl: "text-left" },
+};
+
+/**
+ * Check if a class should be expanded to directional modifiers
+ *
+ * @param cls - Class name to check
+ * @returns Expansion object if class should expand, undefined otherwise
+ */
+export function getDirectionalExpansion(cls: string): { ltr: string; rtl: string } | undefined {
+  return DIRECTIONAL_TEXT_ALIGN_EXPANSIONS[cls];
+}
+
 /**
  * Split a space-separated className string into base and modifier classes
  *
@@ -257,6 +296,17 @@ export function expandSchemeModifier(
  * //     { modifier: "active", baseClass: "p-6" }
  * //   ]
  * // }
+ *
+ * @example
+ * // text-start/text-end auto-expand to directional modifiers for true RTL support
+ * splitModifierClasses("text-start p-4")
+ * // {
+ * //   baseClasses: ["p-4"],
+ * //   modifierClasses: [
+ * //     { modifier: "ltr", baseClass: "text-left" },
+ * //     { modifier: "rtl", baseClass: "text-right" }
+ * //   ]
+ * // }
  */
 export function splitModifierClasses(className: string): {
   baseClasses: string[];
@@ -267,6 +317,15 @@ export function splitModifierClasses(className: string): {
   const modifierClasses: ParsedModifier[] = [];
 
   for (const cls of classes) {
+    // Check for directional text alignment expansion (text-start, text-end)
+    const directionalExpansion = getDirectionalExpansion(cls);
+    if (directionalExpansion) {
+      // Expand to ltr: and rtl: modifiers for true RTL support
+      modifierClasses.push({ modifier: "ltr", baseClass: directionalExpansion.ltr });
+      modifierClasses.push({ modifier: "rtl", baseClass: directionalExpansion.rtl });
+      continue;
+    }
+
     const parsed = parseModifier(cls);
     if (parsed) {
       modifierClasses.push(parsed);