@mgcrea/react-native-tailwind 0.15.1 → 0.15.3

package/dist/utils/mergeStyles.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Smart merge utility for StyleObject values
+ * Handles transform arrays with "last wins" semantics for same transform types
+ */
+import type { StyleObject } from "../types/core";
+/**
+ * Merge two StyleObject instances, handling transform arrays specially
+ *
+ * @param target - The target object to merge into (mutated)
+ * @param source - The source object to merge from
+ * @returns The merged target object
+ *
+ * @example
+ * // Standard properties are overwritten (like Object.assign)
+ * mergeStyles({ margin: 4 }, { padding: 8 })
+ * // => { margin: 4, padding: 8 }
+ *
+ * @example
+ * // Different transform types are combined
+ * mergeStyles(
+ *   { transform: [{ rotate: '45deg' }] },
+ *   { transform: [{ scale: 1.1 }] }
+ * )
+ * // => { transform: [{ rotate: '45deg' }, { scale: 1.1 }] }
+ *
+ * @example
+ * // Same transform type: last wins (Tailwind parity)
+ * mergeStyles(
+ *   { transform: [{ rotate: '45deg' }] },
+ *   { transform: [{ rotate: '90deg' }] }
+ * )
+ * // => { transform: [{ rotate: '90deg' }] }
+ */
+export declare function mergeStyles(target: StyleObject, source: StyleObject): StyleObject;

package/dist/utils/mergeStyles.js

@@ -0,0 +1 @@
+var _interopRequireDefault=require("@babel/runtime/helpers/interopRequireDefault");Object.defineProperty(exports,"__esModule",{value:true});exports.mergeStyles=mergeStyles;var _toConsumableArray2=_interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));function getTransformType(transform){return Object.keys(transform)[0];}function mergeTransforms(target,source){var result=(0,_toConsumableArray2.default)(target);var _loop=function _loop(){var sourceType=getTransformType(sourceTransform);var existingIndex=result.findIndex(function(t){return getTransformType(t)===sourceType;});if(existingIndex!==-1){result[existingIndex]=sourceTransform;}else{result.push(sourceTransform);}};for(var sourceTransform of source){_loop();}return result;}function mergeStyles(target,source){for(var key in source){if(Object.prototype.hasOwnProperty.call(source,key)){var sourceValue=source[key];if(key==="transform"&&Array.isArray(sourceValue)){var targetValue=target[key];if(Array.isArray(targetValue)){target.transform=mergeTransforms(targetValue,sourceValue);}else{target[key]=sourceValue;}}else{target[key]=sourceValue;}}}return target;}

package/dist/utils/mergeStyles.test.js

@@ -0,0 +1 @@
+var _vitest=require("vitest");var _mergeStyles=require("./mergeStyles");(0,_vitest.describe)("mergeStyles",function(){(0,_vitest.describe)("standard properties",function(){(0,_vitest.it)("should merge non-array properties like Object.assign",function(){var target={margin:4};var source={padding:8};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({margin:4,padding:8});});(0,_vitest.it)("should overwrite non-array properties",function(){var target={margin:4};var source={margin:8};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({margin:8});});(0,_vitest.it)("should handle shadowOffset as standard property (object, not array)",function(){var target={shadowOffset:{width:0,height:1}};var source={shadowOffset:{width:0,height:2}};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({shadowOffset:{width:0,height:2}});});});(0,_vitest.describe)("transform array merging - different types combined",function(){(0,_vitest.it)("should combine different transform types",function(){var target={transform:[{rotate:"45deg"}]};var source={transform:[{scale:1.1}]};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({transform:[{rotate:"45deg"},{scale:1.1}]});});(0,_vitest.it)("should handle multiple transforms in source",function(){var target={transform:[{rotate:"45deg"}]};var source={transform:[{scale:1.1},{translateX:10}]};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({transform:[{rotate:"45deg"},{scale:1.1},{translateX:10}]});});(0,_vitest.it)("should assign transform when target has no transform",function(){var target={margin:4};var source={transform:[{scale:1.1}]};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({margin:4,transform:[{scale:1.1}]});});(0,_vitest.it)("should handle empty target transform array",function(){var target={transform:[]};var source={transform:[{scale:1.1}]};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({transform:[{scale:1.1}]});});});(0,_vitest.describe)("transform array merging - same type last wins (Tailwind parity)",function(){(0,_vitest.it)("should replace same transform type with last value",function(){var target={transform:[{rotate:"45deg"}]};var source={transform:[{rotate:"90deg"}]};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({transform:[{rotate:"90deg"}]});});(0,_vitest.it)("should replace same scale type with last value",function(){var target={transform:[{scale:0.5}]};var source={transform:[{scale:1.1}]};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({transform:[{scale:1.1}]});});(0,_vitest.it)("should preserve order when replacing - rotate stays in position",function(){var target={transform:[{rotate:"45deg"},{scale:1.1}]};var source={transform:[{rotate:"90deg"}]};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({transform:[{rotate:"90deg"},{scale:1.1}]});});(0,_vitest.it)("should handle mixed: replace same types, add new types",function(){var target={transform:[{rotate:"45deg"},{scale:0.5}]};var source={transform:[{scale:1.1},{translateX:10}]};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({transform:[{rotate:"45deg"},{scale:1.1},{translateX:10}]});});(0,_vitest.it)("should handle scaleX and scaleY as different types",function(){var target={transform:[{scaleX:0.5}]};var source={transform:[{scaleY:1.5}]};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({transform:[{scaleX:0.5},{scaleY:1.5}]});});});(0,_vitest.describe)("mixed properties",function(){(0,_vitest.it)("should handle mix of standard and transform properties",function(){var target={margin:4,transform:[{rotate:"45deg"}]};var source={padding:8,transform:[{scale:1.1}]};(0,_vitest.expect)((0,_mergeStyles.mergeStyles)(target,source)).toEqual({margin:4,padding:8,transform:[{rotate:"45deg"},{scale:1.1}]});});});(0,_vitest.describe)("mutation behavior",function(){(0,_vitest.it)("should mutate and return target object",function(){var target={margin:4};var source={padding:8};var result=(0,_mergeStyles.mergeStyles)(target,source);(0,_vitest.expect)(result).toBe(target);(0,_vitest.expect)(target).toEqual({margin:4,padding:8});});});});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgcrea/react-native-tailwind",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "description": "Compile-time Tailwind CSS for React Native with zero runtime overhead",
   "author": "Olivier Louvignes <olivier@mgcrea.io> (https://github.com/mgcrea)",
   "homepage": "https://github.com/mgcrea/react-native-tailwind#readme",

package/src/index.ts

@@ -9,6 +9,7 @@ export { tw, twStyle } from "./stubs/tw";
 // Main parser functions
 export { parseClass, parseClassName } from "./parser";
 export { flattenColors } from "./utils/flattenColors";
+export { mergeStyles } from "./utils/mergeStyles";
 export { generateStyleKey } from "./utils/styleKey";
 
 // Re-export types

package/src/parser/index.ts

@@ -4,6 +4,7 @@
  */
 
 import type { StyleObject } from "../types";
+import { mergeStyles } from "../utils/mergeStyles";
 import { parseAspectRatio } from "./aspectRatio";
 import { parseBorder } from "./borders";
 import { parseColor } from "./colors";
@@ -36,7 +37,7 @@ export function parseClassName(className: string, customTheme?: CustomTheme): St
 
   for (const cls of classes) {
     const parsedStyle = parseClass(cls, customTheme);
-    Object.assign(style, parsedStyle);
+    mergeStyles(style, parsedStyle);
   }
 
   return style;

package/src/parser/layout.test.ts

@@ -521,6 +521,39 @@ describe("parseLayout - positioning utilities", () => {
     expect(parseLayout("left-[12.5%]")).toEqual({ left: "12.5%" });
     expect(parseLayout("left-[-20px]")).toEqual({ left: -20 });
   });
+
+  it("should parse negative positioning prefixes", () => {
+    // Standard spacing scale
+    expect(parseLayout("-top-1")).toEqual({ top: -4 });
+    expect(parseLayout("-top-4")).toEqual({ top: -16 });
+    expect(parseLayout("-right-1")).toEqual({ right: -4 });
+    expect(parseLayout("-right-2")).toEqual({ right: -8 });
+    expect(parseLayout("-bottom-4")).toEqual({ bottom: -16 });
+    expect(parseLayout("-bottom-8")).toEqual({ bottom: -32 });
+    expect(parseLayout("-left-2")).toEqual({ left: -8 });
+    expect(parseLayout("-left-4")).toEqual({ left: -16 });
+  });
+
+  it("should parse negative positioning with fractional values", () => {
+    expect(parseLayout("-top-0.5")).toEqual({ top: -2 });
+    expect(parseLayout("-right-1.5")).toEqual({ right: -6 });
+    expect(parseLayout("-bottom-2.5")).toEqual({ bottom: -10 });
+    expect(parseLayout("-left-3.5")).toEqual({ left: -14 });
+  });
+
+  it("should parse negative positioning with arbitrary values", () => {
+    expect(parseLayout("-top-[10px]")).toEqual({ top: -10 });
+    expect(parseLayout("-right-[20px]")).toEqual({ right: -20 });
+    expect(parseLayout("-bottom-[30]")).toEqual({ bottom: -30 });
+    expect(parseLayout("-left-[40px]")).toEqual({ left: -40 });
+  });
+
+  it("should parse negative positioning with arbitrary percentages", () => {
+    expect(parseLayout("-top-[10%]")).toEqual({ top: "-10%" });
+    expect(parseLayout("-right-[25%]")).toEqual({ right: "-25%" });
+    expect(parseLayout("-bottom-[50%]")).toEqual({ bottom: "-50%" });
+    expect(parseLayout("-left-[100%]")).toEqual({ left: "-100%" });
+  });
 });
 
 describe("parseLayout - inset utilities", () => {
@@ -791,9 +824,11 @@ describe("parseLayout - custom spacing", () => {
     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
+  it("should support negative values with custom spacing for positioning", () => {
+    expect(parseLayout("-top-sm", customSpacing)).toEqual({ top: -8 });
+    expect(parseLayout("-right-md", customSpacing)).toEqual({ right: -16 });
+    expect(parseLayout("-bottom-lg", customSpacing)).toEqual({ bottom: -32 });
+    expect(parseLayout("-left-xl", customSpacing)).toEqual({ left: -64 });
     expect(parseLayout("-start-sm", customSpacing)).toEqual({ start: -8 });
     expect(parseLayout("-end-md", customSpacing)).toEqual({ end: -16 });
   });

package/src/parser/layout.ts

@@ -260,87 +260,127 @@ export function parseLayout(cls: string, customSpacing?: Record<string, number>)
     }
   }
 
-  // Top positioning: top-0, top-4, top-[10px], top-[50%], etc.
-  if (cls.startsWith("top-")) {
-    const topKey = cls.substring(4);
+  // Top positioning: top-0, top-4, top-[10px], top-[50%], -top-4, etc.
+  const topMatch = cls.match(/^(-?)top-(.+)$/);
+  if (topMatch) {
+    const [, negPrefix, topKey] = topMatch;
+    const isNegative = negPrefix === "-";
 
     // Auto value - return empty object (no-op, removes the property)
     if (topKey === "auto") {
       return {};
     }
 
-    // Arbitrary values: top-[123px], top-[50%], top-[-10px]
+    // Arbitrary values: top-[123px], top-[50%], -top-[10px]
     const arbitraryTop = parseArbitraryInset(topKey);
     if (arbitraryTop !== null) {
+      if (typeof arbitraryTop === "number") {
+        return { top: isNegative ? -arbitraryTop : arbitraryTop };
+      }
+      // Percentage values with negative prefix
+      if (isNegative && arbitraryTop.endsWith("%")) {
+        const numValue = parseFloat(arbitraryTop);
+        return { top: `${-numValue}%` };
+      }
       return { top: arbitraryTop };
     }
 
     const topValue = insetMap[topKey];
     if (topValue !== undefined) {
-      return { top: topValue };
+      return { top: isNegative ? -topValue : topValue };
     }
   }
 
-  // Right positioning: right-0, right-4, right-[10px], right-[50%], etc.
-  if (cls.startsWith("right-")) {
-    const rightKey = cls.substring(6);
+  // Right positioning: right-0, right-4, right-[10px], right-[50%], -right-4, etc.
+  const rightMatch = cls.match(/^(-?)right-(.+)$/);
+  if (rightMatch) {
+    const [, negPrefix, rightKey] = rightMatch;
+    const isNegative = negPrefix === "-";
 
     // Auto value - return empty object (no-op, removes the property)
     if (rightKey === "auto") {
       return {};
     }
 
-    // Arbitrary values: right-[123px], right-[50%], right-[-10px]
+    // Arbitrary values: right-[123px], right-[50%], -right-[10px]
     const arbitraryRight = parseArbitraryInset(rightKey);
     if (arbitraryRight !== null) {
+      if (typeof arbitraryRight === "number") {
+        return { right: isNegative ? -arbitraryRight : arbitraryRight };
+      }
+      // Percentage values with negative prefix
+      if (isNegative && arbitraryRight.endsWith("%")) {
+        const numValue = parseFloat(arbitraryRight);
+        return { right: `${-numValue}%` };
+      }
       return { right: arbitraryRight };
     }
 
     const rightValue = insetMap[rightKey];
     if (rightValue !== undefined) {
-      return { right: rightValue };
+      return { right: isNegative ? -rightValue : rightValue };
     }
   }
 
-  // Bottom positioning: bottom-0, bottom-4, bottom-[10px], bottom-[50%], etc.
-  if (cls.startsWith("bottom-")) {
-    const bottomKey = cls.substring(7);
+  // Bottom positioning: bottom-0, bottom-4, bottom-[10px], bottom-[50%], -bottom-4, etc.
+  const bottomMatch = cls.match(/^(-?)bottom-(.+)$/);
+  if (bottomMatch) {
+    const [, negPrefix, bottomKey] = bottomMatch;
+    const isNegative = negPrefix === "-";
 
     // Auto value - return empty object (no-op, removes the property)
     if (bottomKey === "auto") {
       return {};
     }
 
-    // Arbitrary values: bottom-[123px], bottom-[50%], bottom-[-10px]
+    // Arbitrary values: bottom-[123px], bottom-[50%], -bottom-[10px]
     const arbitraryBottom = parseArbitraryInset(bottomKey);
     if (arbitraryBottom !== null) {
+      if (typeof arbitraryBottom === "number") {
+        return { bottom: isNegative ? -arbitraryBottom : arbitraryBottom };
+      }
+      // Percentage values with negative prefix
+      if (isNegative && arbitraryBottom.endsWith("%")) {
+        const numValue = parseFloat(arbitraryBottom);
+        return { bottom: `${-numValue}%` };
+      }
       return { bottom: arbitraryBottom };
     }
 
     const bottomValue = insetMap[bottomKey];
     if (bottomValue !== undefined) {
-      return { bottom: bottomValue };
+      return { bottom: isNegative ? -bottomValue : bottomValue };
     }
   }
 
-  // Left positioning: left-0, left-4, left-[10px], left-[50%], etc.
-  if (cls.startsWith("left-")) {
-    const leftKey = cls.substring(5);
+  // Left positioning: left-0, left-4, left-[10px], left-[50%], -left-4, etc.
+  const leftMatch = cls.match(/^(-?)left-(.+)$/);
+  if (leftMatch) {
+    const [, negPrefix, leftKey] = leftMatch;
+    const isNegative = negPrefix === "-";
 
     // Auto value - return empty object (no-op, removes the property)
     if (leftKey === "auto") {
       return {};
     }
 
-    // Arbitrary values: left-[123px], left-[50%], left-[-10px]
+    // Arbitrary values: left-[123px], left-[50%], -left-[10px]
     const arbitraryLeft = parseArbitraryInset(leftKey);
     if (arbitraryLeft !== null) {
+      if (typeof arbitraryLeft === "number") {
+        return { left: isNegative ? -arbitraryLeft : arbitraryLeft };
+      }
+      // Percentage values with negative prefix
+      if (isNegative && arbitraryLeft.endsWith("%")) {
+        const numValue = parseFloat(arbitraryLeft);
+        return { left: `${-numValue}%` };
+      }
       return { left: arbitraryLeft };
     }
 
     const leftValue = insetMap[leftKey];
     if (leftValue !== undefined) {
-      return { left: leftValue };
+      return { left: isNegative ? -leftValue : leftValue };
     }
   }
 

package/src/parser/transforms.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { parseClassName } from "./index";
 import { PERSPECTIVE_SCALE, ROTATE_MAP, SCALE_MAP, SKEW_MAP, parseTransform } from "./transforms";
 
 describe("SCALE_MAP", () => {
@@ -373,3 +374,107 @@ describe("parseTransform - custom spacing", () => {
     expect(parseTransform("perspective-500", customSpacing)).toEqual({ transform: [{ perspective: 500 }] });
   });
 });
+
+describe("parseClassName - multiple transforms", () => {
+  it("should combine rotate and scale transforms", () => {
+    const result = parseClassName("rotate-45 scale-110");
+    expect(result).toEqual({
+      transform: [{ rotate: "45deg" }, { scale: 1.1 }],
+    });
+  });
+
+  it("should combine scale and rotate with arbitrary values", () => {
+    const result = parseClassName("rotate-45 scale-[0.2]");
+    expect(result).toEqual({
+      transform: [{ rotate: "45deg" }, { scale: 0.2 }],
+    });
+  });
+
+  it("should combine multiple different transforms", () => {
+    const result = parseClassName("rotate-45 scale-110 translate-x-4");
+    expect(result).toEqual({
+      transform: [{ rotate: "45deg" }, { scale: 1.1 }, { translateX: 16 }],
+    });
+  });
+
+  it("should preserve order of transforms", () => {
+    // Order matters in React Native transforms!
+    const result1 = parseClassName("rotate-45 scale-110");
+    const result2 = parseClassName("scale-110 rotate-45");
+
+    expect(result1.transform).toEqual([{ rotate: "45deg" }, { scale: 1.1 }]);
+    expect(result2.transform).toEqual([{ scale: 1.1 }, { rotate: "45deg" }]);
+  });
+
+  it("should combine transforms with other properties", () => {
+    const result = parseClassName("m-4 rotate-45 scale-110 p-2");
+    expect(result).toEqual({
+      margin: 16,
+      padding: 8,
+      transform: [{ rotate: "45deg" }, { scale: 1.1 }],
+    });
+  });
+
+  it("should handle all transform types together", () => {
+    const result = parseClassName("perspective-500 rotate-45 scale-110 translate-x-4 skew-x-6");
+    expect(result).toEqual({
+      transform: [
+        { perspective: 500 },
+        { rotate: "45deg" },
+        { scale: 1.1 },
+        { translateX: 16 },
+        { skewX: "6deg" },
+      ],
+    });
+  });
+
+  it("should handle negative transforms", () => {
+    const result = parseClassName("-rotate-45 -translate-x-4");
+    expect(result).toEqual({
+      transform: [{ rotate: "-45deg" }, { translateX: -16 }],
+    });
+  });
+
+  it("should handle scale-x and scale-y together", () => {
+    const result = parseClassName("scale-x-50 scale-y-150");
+    expect(result).toEqual({
+      transform: [{ scaleX: 0.5 }, { scaleY: 1.5 }],
+    });
+  });
+
+  it("should handle single transform (backward compatibility)", () => {
+    const result = parseClassName("rotate-45");
+    expect(result).toEqual({
+      transform: [{ rotate: "45deg" }],
+    });
+  });
+
+  it("should handle arbitrary values combined", () => {
+    const result = parseClassName("rotate-[37deg] scale-[0.2] translate-x-[50px]");
+    expect(result).toEqual({
+      transform: [{ rotate: "37deg" }, { scale: 0.2 }, { translateX: 50 }],
+    });
+  });
+
+  // "Last wins" behavior for same transform type (Tailwind parity)
+  it("should use last value for duplicate rotate (Tailwind parity)", () => {
+    const result = parseClassName("rotate-45 rotate-90");
+    expect(result).toEqual({
+      transform: [{ rotate: "90deg" }],
+    });
+  });
+
+  it("should use last value for duplicate scale (Tailwind parity)", () => {
+    const result = parseClassName("scale-50 scale-110");
+    expect(result).toEqual({
+      transform: [{ scale: 1.1 }],
+    });
+  });
+
+  it("should preserve different types while replacing duplicates", () => {
+    const result = parseClassName("rotate-45 scale-110 rotate-90");
+    expect(result).toEqual({
+      transform: [{ rotate: "90deg" }, { scale: 1.1 }],
+    });
+  });
+});

package/src/utils/mergeStyles.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import { mergeStyles } from "./mergeStyles";
+
+describe("mergeStyles", () => {
+  describe("standard properties", () => {
+    it("should merge non-array properties like Object.assign", () => {
+      const target = { margin: 4 };
+      const source = { padding: 8 };
+      expect(mergeStyles(target, source)).toEqual({ margin: 4, padding: 8 });
+    });
+
+    it("should overwrite non-array properties", () => {
+      const target = { margin: 4 };
+      const source = { margin: 8 };
+      expect(mergeStyles(target, source)).toEqual({ margin: 8 });
+    });
+
+    it("should handle shadowOffset as standard property (object, not array)", () => {
+      const target = { shadowOffset: { width: 0, height: 1 } };
+      const source = { shadowOffset: { width: 0, height: 2 } };
+      expect(mergeStyles(target, source)).toEqual({
+        shadowOffset: { width: 0, height: 2 },
+      });
+    });
+  });
+
+  describe("transform array merging - different types combined", () => {
+    it("should combine different transform types", () => {
+      const target = { transform: [{ rotate: "45deg" }] };
+      const source = { transform: [{ scale: 1.1 }] };
+      expect(mergeStyles(target, source)).toEqual({
+        transform: [{ rotate: "45deg" }, { scale: 1.1 }],
+      });
+    });
+
+    it("should handle multiple transforms in source", () => {
+      const target = { transform: [{ rotate: "45deg" }] };
+      const source = { transform: [{ scale: 1.1 }, { translateX: 10 }] };
+      expect(mergeStyles(target, source)).toEqual({
+        transform: [{ rotate: "45deg" }, { scale: 1.1 }, { translateX: 10 }],
+      });
+    });
+
+    it("should assign transform when target has no transform", () => {
+      const target = { margin: 4 };
+      const source = { transform: [{ scale: 1.1 }] };
+      expect(mergeStyles(target, source)).toEqual({
+        margin: 4,
+        transform: [{ scale: 1.1 }],
+      });
+    });
+
+    it("should handle empty target transform array", () => {
+      const target = { transform: [] as Array<{ scale?: number }> };
+      const source = { transform: [{ scale: 1.1 }] };
+      expect(mergeStyles(target, source)).toEqual({
+        transform: [{ scale: 1.1 }],
+      });
+    });
+  });
+
+  describe("transform array merging - same type last wins (Tailwind parity)", () => {
+    it("should replace same transform type with last value", () => {
+      const target = { transform: [{ rotate: "45deg" }] };
+      const source = { transform: [{ rotate: "90deg" }] };
+      expect(mergeStyles(target, source)).toEqual({
+        transform: [{ rotate: "90deg" }],
+      });
+    });
+
+    it("should replace same scale type with last value", () => {
+      const target = { transform: [{ scale: 0.5 }] };
+      const source = { transform: [{ scale: 1.1 }] };
+      expect(mergeStyles(target, source)).toEqual({
+        transform: [{ scale: 1.1 }],
+      });
+    });
+
+    it("should preserve order when replacing - rotate stays in position", () => {
+      const target = { transform: [{ rotate: "45deg" }, { scale: 1.1 }] };
+      const source = { transform: [{ rotate: "90deg" }] };
+      expect(mergeStyles(target, source)).toEqual({
+        transform: [{ rotate: "90deg" }, { scale: 1.1 }],
+      });
+    });
+
+    it("should handle mixed: replace same types, add new types", () => {
+      const target = { transform: [{ rotate: "45deg" }, { scale: 0.5 }] };
+      const source = { transform: [{ scale: 1.1 }, { translateX: 10 }] };
+      expect(mergeStyles(target, source)).toEqual({
+        transform: [{ rotate: "45deg" }, { scale: 1.1 }, { translateX: 10 }],
+      });
+    });
+
+    it("should handle scaleX and scaleY as different types", () => {
+      const target = { transform: [{ scaleX: 0.5 }] };
+      const source = { transform: [{ scaleY: 1.5 }] };
+      expect(mergeStyles(target, source)).toEqual({
+        transform: [{ scaleX: 0.5 }, { scaleY: 1.5 }],
+      });
+    });
+  });
+
+  describe("mixed properties", () => {
+    it("should handle mix of standard and transform properties", () => {
+      const target = { margin: 4, transform: [{ rotate: "45deg" }] };
+      const source = { padding: 8, transform: [{ scale: 1.1 }] };
+      expect(mergeStyles(target, source)).toEqual({
+        margin: 4,
+        padding: 8,
+        transform: [{ rotate: "45deg" }, { scale: 1.1 }],
+      });
+    });
+  });
+
+  describe("mutation behavior", () => {
+    it("should mutate and return target object", () => {
+      const target = { margin: 4 };
+      const source = { padding: 8 };
+      const result = mergeStyles(target, source);
+      expect(result).toBe(target);
+      expect(target).toEqual({ margin: 4, padding: 8 });
+    });
+  });
+});

package/src/utils/mergeStyles.ts

@@ -0,0 +1,103 @@
+/**
+ * Smart merge utility for StyleObject values
+ * Handles transform arrays with "last wins" semantics for same transform types
+ */
+
+import type { StyleObject, TransformStyle } from "../types/core";
+
+/**
+ * Get the transform type key from a transform object
+ * e.g., { rotate: '45deg' } -> 'rotate', { scale: 1.1 } -> 'scale'
+ */
+function getTransformType(transform: TransformStyle): string {
+  return Object.keys(transform)[0];
+}
+
+/**
+ * Merge transform arrays with "last wins" semantics for duplicate transform types.
+ * Different transform types are combined, but if the same type appears twice,
+ * the later one replaces the earlier one (matching Tailwind CSS behavior).
+ *
+ * @example
+ * // Different types are combined
+ * mergeTransforms([{ rotate: '45deg' }], [{ scale: 1.1 }])
+ * // => [{ rotate: '45deg' }, { scale: 1.1 }]
+ *
+ * @example
+ * // Same type: last wins
+ * mergeTransforms([{ rotate: '45deg' }], [{ rotate: '90deg' }])
+ * // => [{ rotate: '90deg' }]
+ */
+function mergeTransforms(target: TransformStyle[], source: TransformStyle[]): TransformStyle[] {
+  // Build result by processing target first, then source
+  // For each source transform, replace any existing transform of the same type
+  const result: TransformStyle[] = [...target];
+
+  for (const sourceTransform of source) {
+    const sourceType = getTransformType(sourceTransform);
+    const existingIndex = result.findIndex((t) => getTransformType(t) === sourceType);
+
+    if (existingIndex !== -1) {
+      // Replace existing transform of same type (last wins)
+      result[existingIndex] = sourceTransform;
+    } else {
+      // Add new transform type
+      result.push(sourceTransform);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Merge two StyleObject instances, handling transform arrays specially
+ *
+ * @param target - The target object to merge into (mutated)
+ * @param source - The source object to merge from
+ * @returns The merged target object
+ *
+ * @example
+ * // Standard properties are overwritten (like Object.assign)
+ * mergeStyles({ margin: 4 }, { padding: 8 })
+ * // => { margin: 4, padding: 8 }
+ *
+ * @example
+ * // Different transform types are combined
+ * mergeStyles(
+ *   { transform: [{ rotate: '45deg' }] },
+ *   { transform: [{ scale: 1.1 }] }
+ * )
+ * // => { transform: [{ rotate: '45deg' }, { scale: 1.1 }] }
+ *
+ * @example
+ * // Same transform type: last wins (Tailwind parity)
+ * mergeStyles(
+ *   { transform: [{ rotate: '45deg' }] },
+ *   { transform: [{ rotate: '90deg' }] }
+ * )
+ * // => { transform: [{ rotate: '90deg' }] }
+ */
+export function mergeStyles(target: StyleObject, source: StyleObject): StyleObject {
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const sourceValue = source[key];
+
+      // Handle transform arrays specially
+      if (key === "transform" && Array.isArray(sourceValue)) {
+        const targetValue = target[key];
+        if (Array.isArray(targetValue)) {
+          // Merge transforms with "last wins" for same types
+          target.transform = mergeTransforms(targetValue, sourceValue);
+        } else {
+          // No existing array, just assign
+          target[key] = sourceValue;
+        }
+      } else {
+        // Standard Object.assign behavior for non-transform properties
+        target[key] = sourceValue;
+      }
+    }
+  }
+
+  return target;
+}