@mgcrea/react-native-tailwind 0.6.1 → 0.7.0

package/src/runtime.test.ts

@@ -0,0 +1,325 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { clearCache, getCacheStats, getCustomColors, setConfig, tw, twStyle } from "./runtime";
+
+describe("runtime", () => {
+  beforeEach(() => {
+    clearCache();
+    setConfig({}); // Reset config
+  });
+
+  describe("tw template tag", () => {
+    it("should parse static classes", () => {
+      const result = tw`m-4 p-2 bg-blue-500`;
+      expect(result?.style).toEqual({
+        margin: 16,
+        padding: 8,
+        backgroundColor: "#2b7fff",
+      });
+      expect(result?.activeStyle).toBeUndefined();
+      expect(result?.disabledStyle).toBeUndefined();
+    });
+
+    it("should handle interpolated values", () => {
+      const isActive = true;
+      const result = tw`m-4 ${isActive && "bg-blue-500"}`;
+      expect(result?.style).toEqual({
+        margin: 16,
+        backgroundColor: "#2b7fff",
+      });
+    });
+
+    it("should handle conditional classes", () => {
+      const isLarge = true;
+      const result = tw`p-4 ${isLarge ? "text-xl" : "text-sm"}`;
+      expect(result?.style).toEqual({
+        padding: 16,
+        fontSize: 20,
+      });
+    });
+
+    it("should handle falsy values", () => {
+      const result = tw`m-4 ${false} ${null} ${undefined} p-2`;
+      expect(result?.style).toEqual({
+        margin: 16,
+        padding: 8,
+      });
+    });
+
+    it("should return empty style object for empty className", () => {
+      const result = tw``;
+      expect(result).toEqual({ style: {} });
+    });
+
+    it("should normalize whitespace", () => {
+      const result = tw`m-4    p-2   bg-blue-500`;
+      expect(result?.style).toEqual({
+        margin: 16,
+        padding: 8,
+        backgroundColor: "#2b7fff",
+      });
+    });
+  });
+
+  describe("twStyle function", () => {
+    it("should parse className string", () => {
+      const result = twStyle("m-4 p-2 bg-blue-500");
+      expect(result?.style).toEqual({
+        margin: 16,
+        padding: 8,
+        backgroundColor: "#2b7fff",
+      });
+      expect(result?.activeStyle).toBeUndefined();
+    });
+
+    it("should return undefined for empty string", () => {
+      const result = twStyle("");
+      expect(result).toBeUndefined();
+    });
+
+    it("should normalize whitespace", () => {
+      const result = twStyle("m-4    p-2   bg-blue-500");
+      expect(result?.style).toEqual({
+        margin: 16,
+        padding: 8,
+        backgroundColor: "#2b7fff",
+      });
+    });
+  });
+
+  describe("setConfig", () => {
+    it("should set custom colors", () => {
+      setConfig({
+        theme: {
+          extend: {
+            colors: {
+              primary: "#007AFF",
+              secondary: "#5856D6",
+            },
+          },
+        },
+      });
+
+      const colors = getCustomColors();
+      expect(colors).toEqual({
+        primary: "#007AFF",
+        secondary: "#5856D6",
+      });
+    });
+
+    it("should flatten nested colors", () => {
+      setConfig({
+        theme: {
+          extend: {
+            colors: {
+              brand: {
+                light: "#FF6B6B",
+                dark: "#CC0000",
+              },
+            },
+          },
+        },
+      });
+
+      const colors = getCustomColors();
+      expect(colors).toEqual({
+        "brand-light": "#FF6B6B",
+        "brand-dark": "#CC0000",
+      });
+    });
+
+    it("should handle mixed flat and nested colors", () => {
+      setConfig({
+        theme: {
+          extend: {
+            colors: {
+              primary: "#007AFF",
+              brand: {
+                light: "#FF6B6B",
+                dark: "#CC0000",
+              },
+            },
+          },
+        },
+      });
+
+      const colors = getCustomColors();
+      expect(colors).toEqual({
+        primary: "#007AFF",
+        "brand-light": "#FF6B6B",
+        "brand-dark": "#CC0000",
+      });
+    });
+
+    it("should clear cache when config changes", () => {
+      const style = tw`bg-blue-500`;
+      expect(style).toBeDefined();
+      expect(getCacheStats().size).toBe(1);
+
+      setConfig({
+        theme: {
+          extend: {
+            colors: { primary: "#007AFF" },
+          },
+        },
+      });
+
+      expect(getCacheStats().size).toBe(0);
+    });
+
+    it("should use custom colors in parsing", () => {
+      setConfig({
+        theme: {
+          extend: {
+            colors: {
+              primary: "#007AFF",
+            },
+          },
+        },
+      });
+
+      const result = tw`bg-primary`;
+      expect(result?.style).toEqual({
+        backgroundColor: "#007AFF",
+      });
+    });
+  });
+
+  describe("cache", () => {
+    it("should cache parsed styles", () => {
+      const result1 = tw`m-4 p-2`;
+      const result2 = tw`m-4 p-2`;
+
+      // Should return the same reference (cached)
+      expect(result1).toBe(result2);
+    });
+
+    it("should track cache stats", () => {
+      const style1 = tw`m-4`;
+      const style2 = tw`p-2`;
+      const style3 = tw`bg-blue-500`;
+      expect(style1).toBeDefined();
+      expect(style2).toBeDefined();
+      expect(style3).toBeDefined();
+
+      const stats = getCacheStats();
+      expect(stats.size).toBe(3);
+      expect(stats.keys).toContain("m-4");
+      expect(stats.keys).toContain("p-2");
+      expect(stats.keys).toContain("bg-blue-500");
+    });
+
+    it("should clear cache", () => {
+      const style1 = tw`m-4`;
+      const style2 = tw`p-2`;
+      expect(style1).toBeDefined();
+      expect(style2).toBeDefined();
+      expect(getCacheStats().size).toBe(2);
+
+      clearCache();
+      expect(getCacheStats().size).toBe(0);
+    });
+  });
+
+  describe("state modifiers", () => {
+    it("should return activeStyle when active: modifier is used", () => {
+      const result = tw`bg-blue-500 active:bg-blue-700`;
+      expect(result?.style).toEqual({
+        backgroundColor: "#2b7fff",
+      });
+      expect(result?.activeStyle).toEqual({
+        backgroundColor: "#1447e6",
+      });
+      expect(result?.disabledStyle).toBeUndefined();
+    });
+
+    it("should return disabledStyle when disabled: modifier is used", () => {
+      const result = tw`bg-blue-500 disabled:bg-gray-300`;
+      expect(result?.style).toEqual({
+        backgroundColor: "#2b7fff",
+      });
+      expect(result?.disabledStyle).toEqual({
+        backgroundColor: "#d1d5dc",
+      });
+      expect(result?.activeStyle).toBeUndefined();
+    });
+
+    it("should return both activeStyle and disabledStyle when both modifiers are used", () => {
+      const result = tw`bg-blue-500 active:bg-blue-700 disabled:bg-gray-300`;
+      expect(result?.style).toEqual({
+        backgroundColor: "#2b7fff",
+      });
+      expect(result?.activeStyle).toEqual({
+        backgroundColor: "#1447e6",
+      });
+      expect(result?.disabledStyle).toEqual({
+        backgroundColor: "#d1d5dc",
+      });
+    });
+
+    it("should merge base and active styles with multiple properties", () => {
+      const result = tw`p-4 m-2 bg-blue-500 active:bg-blue-700 active:p-6`;
+      expect(result?.style).toEqual({
+        padding: 16,
+        margin: 8,
+        backgroundColor: "#2b7fff",
+      });
+      expect(result?.activeStyle).toEqual({
+        backgroundColor: "#1447e6",
+        padding: 24,
+      });
+    });
+
+    it("should handle only modifier classes (no base)", () => {
+      const result = tw`active:bg-blue-700`;
+      expect(result?.style).toEqual({});
+      expect(result?.activeStyle).toEqual({
+        backgroundColor: "#1447e6",
+      });
+    });
+
+    it("should work with twStyle function", () => {
+      const result = twStyle("bg-blue-500 active:bg-blue-700");
+      expect(result?.style).toEqual({
+        backgroundColor: "#2b7fff",
+      });
+      expect(result?.activeStyle).toEqual({
+        backgroundColor: "#1447e6",
+      });
+    });
+
+    it("should provide raw hex values for animations", () => {
+      const result = tw`bg-blue-500 active:bg-blue-700`;
+      // Access raw backgroundColor value for use with reanimated
+      expect(result?.style.backgroundColor).toBe("#2b7fff");
+      expect(result?.activeStyle?.backgroundColor).toBe("#1447e6");
+    });
+
+    it("should return focusStyle when focus: modifier is used", () => {
+      const result = tw`bg-blue-500 focus:bg-blue-800`;
+      expect(result?.style).toEqual({
+        backgroundColor: "#2b7fff",
+      });
+      expect(result?.focusStyle).toEqual({
+        backgroundColor: "#193cb8",
+      });
+      expect(result?.activeStyle).toBeUndefined();
+      expect(result?.disabledStyle).toBeUndefined();
+    });
+
+    it("should return all three modifier styles when all are used", () => {
+      const result = tw`bg-blue-500 active:bg-blue-700 focus:bg-blue-800 disabled:bg-gray-300`;
+      expect(result?.style).toEqual({
+        backgroundColor: "#2b7fff",
+      });
+      expect(result?.activeStyle).toEqual({
+        backgroundColor: "#1447e6",
+      });
+      expect(result?.focusStyle).toEqual({
+        backgroundColor: "#193cb8",
+      });
+      expect(result?.disabledStyle).toEqual({
+        backgroundColor: "#d1d5dc",
+      });
+    });
+  });
+});

package/src/runtime.ts

@@ -0,0 +1,280 @@
+import type { ImageStyle, TextStyle, ViewStyle } from "react-native";
+import { parseClassName } from "./parser/index.js";
+import { flattenColors } from "./utils/flattenColors.js";
+import { hasModifiers, splitModifierClasses } from "./utils/modifiers.js";
+
+/**
+ * Union type for all React Native style types
+ */
+export type NativeStyle = ViewStyle | TextStyle | ImageStyle;
+
+/**
+ * Return type for tw/twStyle functions with separate style properties for modifiers
+ */
+export type TwStyle<T extends NativeStyle = NativeStyle> = {
+  style: T;
+  activeStyle?: T;
+  focusStyle?: T;
+  disabledStyle?: T;
+};
+
+/**
+ * Runtime configuration type matching Tailwind config structure
+ */
+export type RuntimeConfig = {
+  theme?: {
+    extend?: {
+      colors?: Record<string, string | Record<string, string>>;
+      // Future extensions can be added here:
+      // spacing?: Record<string, number | string>;
+      // fontFamily?: Record<string, string[]>;
+    };
+  };
+};
+
+// Global custom colors configuration
+let globalCustomColors: Record<string, string> | undefined;
+
+// Simple memoization cache
+const styleCache = new Map<string, TwStyle>();
+
+/**
+ * Configure runtime Tailwind settings
+ * Matches the structure of tailwind.config.mjs for consistency
+ *
+ * @param config - Runtime configuration object
+ *
+ * @example
+ * ```typescript
+ * import { setConfig } from '@mgcrea/react-native-tailwind/runtime';
+ *
+ * setConfig({
+ *   theme: {
+ *     extend: {
+ *       colors: {
+ *         primary: '#007AFF',
+ *         secondary: '#5856D6',
+ *         brand: {
+ *           light: '#FF6B6B',
+ *           dark: '#CC0000'
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function setConfig(config: RuntimeConfig): void {
+  // Extract and flatten custom colors
+  if (config.theme?.extend?.colors) {
+    globalCustomColors = flattenColors(config.theme.extend.colors);
+  } else {
+    globalCustomColors = undefined;
+  }
+
+  // Clear cache when config changes
+  styleCache.clear();
+}
+
+/**
+ * Get currently configured custom colors
+ */
+export function getCustomColors(): Record<string, string> | undefined {
+  return globalCustomColors;
+}
+
+/**
+ * Clear the memoization cache
+ * Useful for testing or when you want to force re-parsing
+ */
+export function clearCache(): void {
+  styleCache.clear();
+}
+
+/**
+ * Get cache statistics (for debugging/monitoring)
+ */
+export function getCacheStats(): { size: number; keys: string[] } {
+  return {
+    size: styleCache.size,
+    keys: Array.from(styleCache.keys()),
+  };
+}
+
+/**
+ * Parse className string and return a TwStyle object with separate modifier properties
+ * Internal helper that handles caching and StyleSheet.create wrapping
+ */
+function parseAndCache(className: string): TwStyle {
+  // Check cache first
+  const cached = styleCache.get(className);
+  if (cached) {
+    return cached;
+  }
+
+  // Check if className contains modifiers
+  if (!hasModifiers(className)) {
+    // No modifiers - simple case
+    const styleObject = parseClassName(className, globalCustomColors);
+
+    const result: TwStyle = {
+      // @ts-expect-error - StyleObject transform types are broader than React Native's strict types
+      style: styleObject,
+    };
+
+    // Cache the result
+    styleCache.set(className, result);
+
+    return result;
+  }
+
+  // Has modifiers - split and parse separately
+  const { base, modifiers } = splitModifierClasses(className);
+
+  // Parse base styles
+  const baseClassName = base.join(" ");
+  const baseStyle = baseClassName ? parseClassName(baseClassName, globalCustomColors) : {};
+
+  // Build result object
+  const result: TwStyle = {
+    // @ts-expect-error - StyleObject transform types are broader than React Native's strict types
+    style: baseStyle,
+  };
+
+  // Parse and add modifier styles
+  if (modifiers.has("active")) {
+    const activeClasses = modifiers.get("active");
+    if (activeClasses && activeClasses.length > 0) {
+      const activeClassName = activeClasses.join(" ");
+      // @ts-expect-error - StyleObject transform types are broader than React Native's strict types
+      result.activeStyle = parseClassName(activeClassName, globalCustomColors);
+    }
+  }
+
+  if (modifiers.has("focus")) {
+    const focusClasses = modifiers.get("focus");
+    if (focusClasses && focusClasses.length > 0) {
+      const focusClassName = focusClasses.join(" ");
+      // @ts-expect-error - StyleObject transform types are broader than React Native's strict types
+      result.focusStyle = parseClassName(focusClassName, globalCustomColors);
+    }
+  }
+
+  if (modifiers.has("disabled")) {
+    const disabledClasses = modifiers.get("disabled");
+    if (disabledClasses && disabledClasses.length > 0) {
+      const disabledClassName = disabledClasses.join(" ");
+      // @ts-expect-error - StyleObject transform types are broader than React Native's strict types
+      result.disabledStyle = parseClassName(disabledClassName, globalCustomColors);
+    }
+  }
+
+  // Cache the result
+  styleCache.set(className, result);
+
+  return result;
+}
+
+/**
+ * Runtime Tailwind CSS template tag for React Native
+ *
+ * Parses Tailwind class names at runtime and returns a TwStyle object with separate
+ * properties for base styles and modifier styles (active, focus, disabled).
+ * Results are memoized for performance.
+ *
+ * @param strings - Template string parts
+ * @param values - Interpolated values
+ * @returns TwStyle object with style, activeStyle, focusStyle, and disabledStyle properties
+ *
+ * @example
+ * ```tsx
+ * import { tw } from '@mgcrea/react-native-tailwind/runtime';
+ *
+ * // Simple usage - access .style property
+ * <View style={tw`m-4 p-2 bg-blue-500`.style} />
+ *
+ * // With interpolations
+ * <View style={tw`flex-1 ${isActive && 'bg-blue-500'} p-4`.style} />
+ *
+ * // With state modifiers - access activeStyle/focusStyle for animations
+ * const styles = tw`bg-blue-500 active:bg-blue-700 focus:bg-blue-800`;
+ * <Pressable style={(state) => [
+ *   styles.style,
+ *   state.pressed && styles.activeStyle,
+ *   state.focused && styles.focusStyle
+ * ]}>
+ *   <Text>Press me</Text>
+ * </Pressable>
+ *
+ * // Use with reanimated for animations with raw values
+ * const styles = tw`bg-blue-500 active:bg-blue-700`;
+ * const animatedStyles = useAnimatedStyle(() => ({
+ *   ...styles.style,
+ *   backgroundColor: interpolateColor(
+ *     progress.value,
+ *     [0, 1],
+ *     [styles.style.backgroundColor, styles.activeStyle?.backgroundColor]
+ *   )
+ * }));
+ * ```
+ */
+export function tw<T extends NativeStyle = NativeStyle>(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): TwStyle<T> {
+  // Combine template strings and values into a single className string
+  const className = strings.reduce((acc, str, i) => {
+    const value = values[i];
+    // Handle falsy values (false, null, undefined) - don't add them
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const valueStr = value ? String(value) : "";
+    return acc + str + valueStr;
+  }, "");
+
+  // Trim and normalize whitespace
+  const normalizedClassName = className.trim().replace(/\s+/g, " ");
+
+  // Handle empty className
+  if (!normalizedClassName) {
+    return { style: {} as T };
+  }
+
+  return parseAndCache(normalizedClassName) as TwStyle<T>;
+}
+
+/**
+ * String version of tw for cases where template literals aren't needed
+ *
+ * Parses Tailwind class names at runtime and returns a TwStyle object with separate
+ * properties for base styles and modifier styles (active, focus, disabled).
+ *
+ * @param className - Space-separated Tailwind class names
+ * @returns TwStyle object with style, activeStyle, focusStyle, and disabledStyle properties
+ *
+ * @example
+ * ```tsx
+ * import { twStyle } from '@mgcrea/react-native-tailwind/runtime';
+ *
+ * // Simple usage - access .style property
+ * <View style={twStyle('m-4 p-2 bg-blue-500').style} />
+ *
+ * // With state modifiers
+ * const styles = twStyle('bg-blue-500 active:bg-blue-700 focus:bg-blue-800');
+ * <Pressable style={(state) => [
+ *   styles.style,
+ *   state.pressed && styles.activeStyle,
+ *   state.focused && styles.focusStyle
+ * ]}>
+ *   <Text>Press me</Text>
+ * </Pressable>
+ * ```
+ */
+export function twStyle<T extends NativeStyle = NativeStyle>(className: string): TwStyle<T> | undefined {
+  const normalizedClassName = className.trim().replace(/\s+/g, " ");
+
+  if (!normalizedClassName) {
+    return undefined;
+  }
+
+  return parseAndCache(normalizedClassName) as TwStyle<T>;
+}

package/src/stubs/tw.ts

@@ -0,0 +1,80 @@
+/**
+ * Compile-time stub for tw/twStyle functions
+ *
+ * These functions are transformed by the Babel plugin at compile-time.
+ * If you see these errors at runtime, it means the Babel plugin is not configured correctly.
+ *
+ * For runtime parsing, use: import { tw } from '@mgcrea/react-native-tailwind/runtime'
+ */
+
+import type { ImageStyle, TextStyle, ViewStyle } from "react-native";
+
+/**
+ * Union type for all React Native style types
+ */
+export type NativeStyle = ViewStyle | TextStyle | ImageStyle;
+
+/**
+ * Return type for tw/twStyle functions with separate style properties for modifiers
+ */
+export type TwStyle<T extends NativeStyle = NativeStyle> = {
+  style: T;
+  activeStyle?: T;
+  focusStyle?: T;
+  disabledStyle?: T;
+};
+
+/**
+ * Compile-time Tailwind CSS template tag (transformed by Babel plugin)
+ *
+ * This function is replaced at compile-time by the Babel plugin.
+ * The import is removed and calls are transformed to inline style objects.
+ *
+ * @example
+ * ```tsx
+ * import { tw } from '@mgcrea/react-native-tailwind';
+ *
+ * const styles = tw`bg-blue-500 active:bg-blue-700`;
+ * // Transformed to:
+ * // const styles = {
+ * //   style: styles._bg_blue_500,
+ * //   activeStyle: styles._active_bg_blue_700
+ * // };
+ * ```
+ */
+export function tw<T extends NativeStyle = NativeStyle>(
+  _strings: TemplateStringsArray,
+  ..._values: unknown[]
+): TwStyle<T> {
+  throw new Error(
+    "tw() must be transformed by the Babel plugin. " +
+      "Ensure @mgcrea/react-native-tailwind/babel is configured in your babel.config.js. " +
+      "For runtime parsing, use: import { tw } from '@mgcrea/react-native-tailwind/runtime'",
+  );
+}
+
+/**
+ * Compile-time Tailwind CSS string function (transformed by Babel plugin)
+ *
+ * This function is replaced at compile-time by the Babel plugin.
+ * The import is removed and calls are transformed to inline style objects.
+ *
+ * @example
+ * ```tsx
+ * import { twStyle } from '@mgcrea/react-native-tailwind';
+ *
+ * const styles = twStyle('bg-blue-500 active:bg-blue-700');
+ * // Transformed to:
+ * // const styles = {
+ * //   style: styles._bg_blue_500,
+ * //   activeStyle: styles._active_bg_blue_700
+ * // };
+ * ```
+ */
+export function twStyle<T extends NativeStyle = NativeStyle>(_className: string): TwStyle<T> | undefined {
+  throw new Error(
+    "twStyle() must be transformed by the Babel plugin. " +
+      "Ensure @mgcrea/react-native-tailwind/babel is configured in your babel.config.js. " +
+      "For runtime parsing, use: import { twStyle } from '@mgcrea/react-native-tailwind/runtime'",
+  );
+}