react-native-css 3.0.6 → 3.1.0-rc.0

package/src/native/styles/index.ts

@@ -172,9 +172,10 @@ export const stylesFamily = family(
     /**
      * A family is a map, so we need to cleanup the observers when the the hash is no longer used
      */
+    const unsubscribe = obs.unsubscribe;
     return Object.assign(obs, {
-      cleanup: (effect: Effect) => {
-        obs.observers.delete(effect);
+      unsubscribe: (effect: Effect) => {
+        unsubscribe(effect);
         if (obs.observers.size === 0) {
           stylesFamily.delete(hash);
         }
@@ -186,15 +187,23 @@ export const stylesFamily = family(
 export function getStyledProps(
   state: ComponentState,
   inline: Record<string, any> | undefined | null,
+  adaptProps: (
+    props: Record<string, any> | undefined,
+  ) => Record<string, any> | undefined = (props) => props,
 ) {
   let result: Record<string, any> | undefined;
 
   const styledProps = state.stylesObs?.get(state.styleEffect);
 
+  // Each config merges a complete props object. Preserve its full target path
+  // before the next config merges unrelated inline props over that object.
+  const computedTargets: { path: string[]; value: unknown }[] = [];
+  const consumedSources: string[] = [];
+
   for (const config of state.configs) {
     result = deepMergeConfig(
       config,
-      nativeStyleMapping(config, styledProps?.normal),
+      nativeStyleMapping(config, adaptProps(styledProps?.normal)),
       inline,
       true,
     );
@@ -203,10 +212,27 @@ export function getStyledProps(
       result = deepMergeConfig(
         config,
         result,
-        nativeStyleMapping(config, styledProps.important),
+        nativeStyleMapping(config, adaptProps(styledProps.important)),
       );
     }
 
+    if (result && config.target) {
+      const path = Array.isArray(config.target)
+        ? config.target
+        : [config.target];
+      let target = result;
+      for (const key of path.slice(0, -1)) target = target?.[key];
+      const key = path[path.length - 1];
+      if (target && key && key in target) {
+        computedTargets.push({ path, value: target[key] });
+      }
+    }
+
+    // Track consumed className sources for cleanup
+    if (config.source !== config.target) {
+      consumedSources.push(config.source);
+    }
+
     // Apply the handlers
     if (hoverFamily.has(state.ruleEffectGetter)) {
       result ??= {};
@@ -265,6 +291,68 @@ export function getStyledProps(
     }
   }
 
+  // Restore correctly-merged target props that may have been overwritten
+  // by later config iterations' Object.assign({}, left, right)
+  if (result) {
+    for (const { path, value } of computedTargets) {
+      let target = result;
+      for (const key of path.slice(0, -1)) {
+        const existing = target[key];
+        target = target[key] = Array.isArray(existing)
+          ? [...existing]
+          : { ...existing };
+      }
+      target[path[path.length - 1]!] = value;
+    }
+    for (const source of consumedSources) {
+      delete result[source];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Merges two prop objects, skipping keys from `right` whose value is `undefined`
+ * or an empty plain object.
+ *
+ * `Object.assign({}, left, right)` copies all enumerable own properties from `right`,
+ * including those with value `undefined` or `{}`. When a component passes
+ * `style={undefined}` or `contentContainerStyle={{}}`, the computed NativeWind
+ * style from `left` gets overwritten. This function prevents that by only copying
+ * values that carry meaningful style information.
+ *
+ * Empty object detection uses inline `for...in` instead of a separate function or
+ * `Object.keys().length` — avoids both function call overhead and intermediate array
+ * allocation on a hot path (called per-prop per-render). Consistent with how the
+ * `["style"]` target path handles this via `filterCssVariables({})` returning `undefined`.
+ *
+ * @param left - The computed NativeWind props (className-derived styles)
+ * @param right - The inline props from the component (guaranteed non-null by caller; may contain undefined values)
+ * @returns A new object with all properties from `left`, overridden only by meaningful values from `right`
+ */
+function mergeDefinedProps(
+  left: Record<string, any> | undefined,
+  right: Record<string, any>,
+) {
+  const result = left ? { ...left } : {};
+  for (const key in right) {
+    const value = right[key];
+    if (value === undefined) continue;
+    // Non-object values (strings, numbers, booleans, null, arrays): always assign
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      result[key] = value;
+      continue;
+    }
+    // Plain object: assign only if non-empty. An empty style object (e.g.,
+    // contentContainerStyle={{}}) has no properties to apply and should not
+    // overwrite computed className styles. The for...in loop only executes
+    // if the object has enumerable keys — empty objects are skipped.
+    for (const _ in value) {
+      result[key] = value;
+      break;
+    }
+  }
   return result;
 }
 
@@ -359,10 +447,10 @@ function deepMergeConfig(
         }
       }
     } else {
-      result = Object.assign({}, left, right);
+      result = mergeDefinedProps(left, right);
     }
   } else {
-    result = Object.assign({}, left, right);
+    result = mergeDefinedProps(left, right);
   }
 
   if (
@@ -378,21 +466,59 @@ function deepMergeConfig(
    *  If target is a path, deep merge until we get to the last key
    */
   if (Array.isArray(config.target)) {
-    for (let i = 0; i < config.target.length - 1; i++) {
-      const key = config.target[i];
-
-      if (key === undefined) {
-        return result;
-      }
-
+    if (config.target.length > 1) {
+      const key = config.target[0]!;
       result[key] = deepMergeConfig(
-        { source: config.source, target: config.target.slice(i + 1) },
+        { source: config.source, target: config.target.slice(1) },
         left?.[key],
         right?.[key],
         rightIsInline,
       );
     }
 
+    // For length-1 array targets (e.g. ["contentContainerStyle"]), the loop
+    // above runs 0 iterations. Merge the target prop so inline styles don't
+    // silently overwrite className-computed styles (same as string target path).
+    const finalKey = config.target[config.target.length - 1];
+    if (config.target.length === 1 && finalKey && rightIsInline) {
+      let rightValue = right?.[finalKey];
+      if (rightValue !== undefined) {
+        rightValue = filterCssVariables(rightValue);
+      }
+      if (rightValue === undefined || rightValue === null) {
+        // Inline is empty or fully filtered — preserve className-computed value
+        if (left && finalKey in left) {
+          result[finalKey] = left[finalKey];
+        } else {
+          // No left value either — remove unfiltered inline value from result
+          delete result[finalKey];
+        }
+      } else if (left && finalKey in left) {
+        const leftValue = left[finalKey];
+        const leftIsObj =
+          typeof leftValue === "object" &&
+          leftValue !== null &&
+          !Array.isArray(leftValue);
+        const rightIsObj =
+          typeof rightValue === "object" &&
+          rightValue !== null &&
+          !Array.isArray(rightValue);
+        if (leftIsObj && rightIsObj) {
+          if (hasNonOverlappingProperties(leftValue, rightValue)) {
+            result[finalKey] = [leftValue, rightValue];
+          } else {
+            // All left keys are in right — use filtered right value
+            result[finalKey] = rightValue;
+          }
+        } else {
+          result[finalKey] = [leftValue, rightValue];
+        }
+      } else {
+        // No left value — use filtered right value (not the unfiltered one from mergeDefinedProps)
+        result[finalKey] = rightValue;
+      }
+    }
+
     return result;
   }
 
@@ -421,7 +547,11 @@ function nativeStyleMapping(
   config: Config,
   props: Record<string, any> | undefined,
 ) {
-  if (!config.nativeStyleMapping || !props) {
+  if (!props) {
+    return props;
+  }
+  if (!config.nativeStyleMapping) {
+    if (config.target === false) delete props.style;
     return props;
   }
 
@@ -470,5 +600,6 @@ function nativeStyleMapping(
     target[lastToken!] = styleValue;
   }
 
+  if (config.target === false) delete props.style;
   return props;
 }

package/src/native/styles/resolve.ts

@@ -5,6 +5,7 @@ import type {
   StyleDescriptor,
   StyleFunction,
 } from "react-native-css/compiler";
+import { isStyleDescriptorArray } from "react-native-css/utilities";
 
 import type { RenderGuard } from "../conditions/guards";
 import { type Getter, type VariableContextValue } from "../reactivity";
@@ -12,6 +13,7 @@ import type { calculateProps } from "./calculate-props";
 import { transformKeys } from "./defaults";
 import * as functions from "./functions";
 import { lineHeight } from "./line-height";
+import { scaleFactor } from "./scale-factor";
 import * as shorthands from "./shorthands";
 import { em, rem, vh, vw } from "./units";
 import { varResolver } from "./variables";
@@ -51,6 +53,7 @@ export type ResolveValueOptions = {
   inlineVariables?: InlineVariable | undefined;
   renderGuards?: RenderGuard[];
   variableHistory?: Set<string>;
+  variableCycles?: Set<string>;
   /** Pass down to perform recursive calculations and avoid circular dependencies */
   calculateProps?: typeof calculateProps;
 };
@@ -77,7 +80,7 @@ export function resolveValue(
         return null;
       } else if (value.endsWith("px")) {
         // Inline vars() might set a value with a px suffix
-        return parseInt(value.slice(0, -2), 10);
+        return parseFloat(value.slice(0, -2));
       } else {
         return value;
       }
@@ -87,7 +90,7 @@ export function resolveValue(
         return value;
       }
 
-      if (isDescriptorArray(value)) {
+      if (isStyleDescriptorArray(value)) {
         value = value
           .map((d) => resolveValue(d, get, options))
           .filter((d) => d !== undefined);
@@ -122,7 +125,16 @@ export function resolveValue(
         ) as StyleDescriptor;
       } else if (transformKeys.has(name)) {
         // translate, rotate, scale, etc.
-        return { [name]: simpleResolve(value[2], castToArray) };
+        let resolved = simpleResolve(value[2], castToArray);
+        // CSS scale percentages describe a factor, unlike translation percentages.
+        if (
+          (name === "scaleX" || name === "scaleY" || name === "scale") &&
+          typeof resolved === "string" &&
+          resolved.endsWith("%")
+        ) {
+          resolved = scaleFactor(resolved);
+        }
+        return { [name]: resolved };
       } else {
         let args = simpleResolve(value[2], castToArray);
 
@@ -154,11 +166,3 @@ export function resolveValue(
     }
   }
 }
-
-function isDescriptorArray(
-  value: StyleDescriptor | StyleDescriptor[],
-): value is StyleDescriptor[] {
-  return Array.isArray(value) && typeof value[0] === "object"
-    ? Array.isArray(value[0])
-    : true;
-}

package/src/native/styles/scale-factor.ts

@@ -0,0 +1,6 @@
+export function scaleFactor(value: unknown) {
+  if (typeof value === "string" && value.endsWith("%")) {
+    return Number(value.slice(0, -1)) / 100;
+  }
+  return value;
+}

package/src/native/styles/shorthands/animation.ts

@@ -39,6 +39,8 @@ export const animationShorthand = shorthandHandler(
     [name],
     [duration, name],
     [name, duration],
+    [name, duration, timingFunction],
+    [duration, timingFunction, name],
     [name, duration, iteration],
     [name, duration, timingFunction, iteration],
     [duration, delay, name],
@@ -67,7 +69,7 @@ export const animation: StyleFunctionResolver = (
 ) => {
   const animationShortHandTuples = animationShorthand(
     resolveValue,
-    value,
+    [value[2]],
     get,
     options,
   );
@@ -86,6 +88,10 @@ export const animation: StyleFunctionResolver = (
     return;
   }
 
+  if (name === "none") {
+    return applyShorthand(animationShortHandTuples);
+  }
+
   const keyframes = get(StyleCollection.keyframes(name));
 
   const animation: Record<string, any> = {};
@@ -127,5 +133,5 @@ export const animationName: StyleFunctionResolver = (
   options,
 ) => {
   const shorthand: any = animation(resolveValue, value, get, options);
-  return shorthand.animationName;
+  return shorthand?.animationName;
 };

package/src/native/styles/shorthands/index.ts

@@ -1,5 +1,6 @@
 export * from "./animation";
 export * from "./border";
+export * from "./logical-border-width";
 export * from "./box-shadow";
 export * from "./text-shadow";
 export * from "./transform";

package/src/native/styles/shorthands/logical-border-width.ts

@@ -0,0 +1,32 @@
+import { ShortHandSymbol } from "../constants";
+import type { StyleFunctionResolver } from "../resolve";
+
+function logicalWidth(start: string, end: string): StyleFunctionResolver {
+  return (resolve, descriptor) => {
+    const resolved = resolve(descriptor[2]);
+    const values: unknown[] = Array.isArray(resolved) ? resolved : [resolved];
+    if (
+      values.length < 1 ||
+      values.length > 2 ||
+      !values.every(
+        (value) =>
+          typeof value === "number" && Number.isFinite(value) && value >= 0,
+      )
+    )
+      return;
+    return {
+      [ShortHandSymbol]: true,
+      [start]: values[0],
+      [end]: values[1] ?? values[0],
+    };
+  };
+}
+
+export const borderBlockWidth = logicalWidth(
+  "borderTopWidth",
+  "borderBottomWidth",
+);
+export const borderInlineWidth = logicalWidth(
+  "borderStartWidth",
+  "borderEndWidth",
+);

package/src/native/styles/variables.ts

@@ -18,7 +18,8 @@ export function varResolver(
     renderGuards,
     inheritedVariables: variables = { [VAR_SYMBOL]: true },
     inlineVariables,
-    variableHistory = new Set(),
+    variableHistory = (options.variableHistory ??= new Set()),
+    variableCycles = (options.variableCycles ??= new Set()),
   } = options;
 
   const args = fn[2];
@@ -29,11 +30,10 @@ export function varResolver(
   if (typeof args === "string") {
     name = args;
   } else {
-    const result = resolve(args);
-
-    if (isStyleDescriptorArray(result)) {
-      name = result[0] as string;
-      fallback = result[1];
+    // Fallbacks are substituted only when needed, after reading the variable.
+    if (isStyleDescriptorArray(args)) {
+      name = args[0] as string;
+      fallback = args[1];
     }
   }
 
@@ -41,48 +41,58 @@ export function varResolver(
     return;
   }
 
-  // If this recurses back to the same variable, we need to stop
+  if (variableCycles.has(name)) return resolve(fallback);
+
+  // Share the active resolution path with recursive calls. Mark only the
+  // actual cycle, so a dependent variable can still use its own fallback.
   if (variableHistory.has(name)) {
+    let inCycle = false;
+    for (const dependency of variableHistory) {
+      if (dependency === name) inCycle = true;
+      if (inCycle) variableCycles.add(dependency);
+    }
     return;
   }
 
-  if (name in variables) {
-    renderGuards?.push(["v", name, variables[name]]);
-    return resolve(variables[name]);
-  }
-
   variableHistory.add(name);
 
-  let value = resolve(inlineVariables?.[name] as StyleDescriptor);
-  if (value !== undefined) {
-    options.inlineVariables ??= { [VAR_SYMBOL]: "inline" };
-    options.inlineVariables[name] = value;
+  try {
+    let value = resolve(inlineVariables?.[name] as StyleDescriptor);
+    if (variableCycles.has(name)) return resolve(fallback);
+    if (value !== undefined) {
+      options.inlineVariables ??= { [VAR_SYMBOL]: "inline" };
+      options.inlineVariables[name] = value;
 
-    return value;
-  }
+      return value;
+    }
 
-  value = resolve(variables[name]);
-  if (value !== undefined) {
-    renderGuards?.push(["v", name, value]);
-    options.inlineVariables ??= { [VAR_SYMBOL]: "inline" };
-    options.inlineVariables[name] = value;
+    // A universal selector declares the variable on this element. It has lower
+    // specificity than the element's class declarations, but beats inheritance.
+    value = resolve(get(universalVariables(name)));
+    if (variableCycles.has(name)) return resolve(fallback);
+    if (value !== undefined) {
+      options.inlineVariables ??= { [VAR_SYMBOL]: "inline" };
+      options.inlineVariables[name] = value;
+      return value;
+    }
 
-    return value;
-  }
+    // Guards retain the ancestor's raw descriptor, matching the context value.
+    if (name in variables) {
+      renderGuards?.push(["v", name, variables[name]]);
+      value = resolve(variables[name]);
+      return variableCycles.has(name) ? resolve(fallback) : value;
+    }
 
-  value = resolve(get(universalVariables(name)));
-  if (value !== undefined) {
-    options.inlineVariables ??= { [VAR_SYMBOL]: "inline" };
-    options.inlineVariables[name] = value;
-    return value;
-  }
+    value = resolve(get(rootVariables(name)));
+    if (variableCycles.has(name)) return resolve(fallback);
+    if (value !== undefined) {
+      options.inlineVariables ??= { [VAR_SYMBOL]: "inline" };
+      options.inlineVariables[name] = value;
+      return value;
+    }
 
-  value = resolve(get(rootVariables(name)));
-  if (value !== undefined) {
-    options.inlineVariables ??= { [VAR_SYMBOL]: "inline" };
-    options.inlineVariables[name] = value;
-    return value;
+    return resolve(fallback);
+  } finally {
+    variableHistory.delete(name);
   }
-
-  return resolve(fallback);
 }

package/src/native-internal/style-collection.ts

@@ -91,7 +91,7 @@ globalThis.__react_native_css_style_collection ??= {
 
     if (options.vu) {
       for (const entry of options.vu) {
-        rootVariables(entry[0]).set(entry[1]);
+        universalVariables(entry[0]).set(entry[1]);
       }
     }
 

package/src/runtime.types.ts

@@ -3,6 +3,7 @@ import type {
   ClassicComponentClass,
   ComponentClass,
   ComponentProps,
+  ComponentPropsWithRef,
   ComponentType,
   ForwardRefExoticComponent,
   FunctionComponent,
@@ -44,20 +45,24 @@ export type StyledProps<P, M extends StyledConfiguration<any>> = P & {
     : never]?: string;
 };
 
-export type Styled = <
-  const C extends ReactComponent,
-  const M extends StyledConfiguration<C>,
->(
-  component: C,
-  mapping: M & StyledConfiguration<C>,
-  options?: StyledOptions,
-) => StyledComponent<C, M>;
+export interface Styled {
+  <const C extends ReactComponent>(
+    component: C,
+    mapping?: undefined,
+    options?: StyledOptions,
+  ): ComponentType<ComponentPropsWithRef<C> & { className?: string }>;
+  <const C extends ReactComponent, const M extends StyledConfiguration<C>>(
+    component: C,
+    mapping: M & StyledConfiguration<C>,
+    options?: StyledOptions,
+  ): StyledComponent<C, M>;
+}
 
 type StyledComponent<
   C extends ReactComponent,
   M extends StyledConfiguration<C>,
 > = ComponentType<
-  ComponentProps<C> & {
+  ComponentPropsWithRef<C> & {
     [K in keyof M as K extends string
       ? M[K] extends undefined | false
         ? never
@@ -90,10 +95,7 @@ interface StyledConfigurationObject<
         ComponentProps<C>
       >;
   /** @deprecated Please use nativeStyleMapping */
-  nativeStyleToProp?: NativeStyleMapping<
-    ResolveDotPath<T, ComponentProps<C>>,
-    ComponentProps<C>
-  >;
+  nativeStyleToProp?: StyledConfigurationObject<C, T>["nativeStyleMapping"];
 }
 
 type NativeStyleMapping<T, S> = T extends object
@@ -145,6 +147,6 @@ export type RNStyle = ViewStyle & TextStyle & ImageStyle;
 /********************************    Globals    ********************************/
 
 export interface ColorScheme {
-  get: () => ColorSchemeName;
-  set: (value: ColorSchemeName) => void;
+  get: () => ColorSchemeName | null | undefined;
+  set: (value: ColorSchemeName | null | undefined) => void;
 }

package/src/utilities/dot-notation.types.ts

@@ -1,4 +1,6 @@
 /* eslint-disable */
+import type { Component, ReactElement } from "react";
+
 // ---------- Base Utilities ----------
 
 type Falsy = undefined | null | false | "";
@@ -32,14 +34,13 @@ export type StyleProp<T> =
 type UnwrapRecursiveArray<
   T,
   Depth extends unknown[] = [],
-  MaxDepth extends number = 10
+  MaxDepth extends number = 10,
 > = Depth["length"] extends MaxDepth
   ? T
   : T extends (infer I)[]
     ? UnwrapRecursiveArray<I, [...Depth, unknown], MaxDepth>
     : T;
 
-
 // Remove null, false, undefined, etc.
 type RemoveFalsy<T> = Exclude<T, Falsy>;
 
@@ -53,7 +54,7 @@ type ExtractStyleObject<T> = RemoveRegisteredStyle<
 
 // Check if something is a non-array plain object
 type IsPlainObject<T> = T extends object
-  ? T extends Function
+  ? T extends Function | Component | ReactElement
     ? false
     : T extends readonly any[]
       ? false

package/src/utilities/style-descriptor.ts

@@ -3,22 +3,17 @@ import type { StyleDescriptor, StyleFunction } from "react-native-css/compiler";
 export function isStyleDescriptorArray(
   value: unknown,
 ): value is StyleDescriptor[] {
-  if (Array.isArray(value)) {
-    // If its an array and the first item is an object, the only allowed value is an array
-    return typeof value[0] === "object" ? Array.isArray(value[0]) : true;
-  }
-
-  return false;
+  return Array.isArray(value) && !isStyleFunction(value);
 }
 
-export function isStyleFunction(
-  value: StyleDescriptor,
-): value is StyleFunction {
-  if (Array.isArray(value)) {
-    return typeof value[0] === "object"
-      ? Object.keys(value[0]).length === 0
-      : false;
-  }
-
-  return false;
+export function isStyleFunction(value: unknown): value is StyleFunction {
+  if (!Array.isArray(value)) return false;
+  const marker: unknown = value[0];
+  return (
+    marker !== null &&
+    typeof marker === "object" &&
+    !Array.isArray(marker) &&
+    Object.keys(marker).length === 0 &&
+    typeof value[1] === "string"
+  );
 }