@tamagui/web 2.7.7 → 3.0.0-beta.643.1

package/src/helpers/nativeStyleEngine.ts

@@ -0,0 +1,291 @@
+/**
+ * Injectable native style engine (plans/native-fast-path.md).
+ *
+ * When set (native only, experimental), eligible leaf components link their
+ * host view to the engine and theme changes commit styles straight to the
+ * native ShadowTree with zero React re-renders. The engine contract matches
+ * `@tamagui/native-registry`; core stays free of any native dependency and
+ * web builds never set an engine.
+ *
+ * Batching: one theme cascade fires many per-view updates synchronously; a
+ * microtask flush folds them into a single applyViewStates call, which the
+ * engine commits in one ShadowTree transaction.
+ */
+
+import { getVariableValue } from '../createVariable'
+
+export interface NativeStyleEngineLinkHandle {
+  id: number
+  unlink: () => void
+}
+
+export interface NativeViewStateUpdate {
+  id: number
+  state: string
+  props?: Record<string, unknown>
+}
+
+export interface NativeViewStateTableUpdate {
+  id: number
+  state: string
+  props: Record<string, unknown>
+}
+
+export interface NativeStyleEngineSlots {
+  base?: Record<string, unknown>
+  state?: Record<string, Record<string, unknown>>
+}
+
+export type NativeStyleThemeMapping = Record<string, string>
+
+export interface NativeStyleEngine {
+  link(
+    ref: unknown,
+    slots: NativeStyleEngineSlots,
+    scopeId?: string
+  ): NativeStyleEngineLinkHandle | null
+  applyViewStates(entries: NativeViewStateUpdate[]): void
+  updateViewStateTables(entries: NativeViewStateTableUpdate[]): void
+  processStyleColors(props: Record<string, unknown>): Record<string, unknown>
+  setStateName(stateName: string, scopeId?: string): void
+  removeScope(scopeId: string): void
+}
+
+let engine: NativeStyleEngine | null = null
+const scopeStates = new Map<string, { name: string; theme: object }>()
+
+interface CompiledMappingLink {
+  handle: NativeStyleEngineLinkHandle
+  scopeId: string
+  stateThemes: Map<string, object>
+}
+
+interface CompiledMapping {
+  mapping: NativeStyleThemeMapping
+  states: Map<string, { theme: object; props: Record<string, unknown> }>
+  links: Set<CompiledMappingLink>
+}
+
+const mappingKeys = new WeakMap<object, string>()
+const compiledMappings = new Map<string, CompiledMapping>()
+// linked mappings remain update owners across memo-generation rollovers
+const activeCompiledMappings = new Set<CompiledMapping>()
+const processedBases = new WeakMap<
+  object,
+  { engine: NativeStyleEngine; props: Record<string, unknown> }
+>()
+
+function getCompiledMapping(mapping: NativeStyleThemeMapping): CompiledMapping {
+  let key = mappingKeys.get(mapping)
+  if (!key) {
+    key = JSON.stringify(
+      Object.keys(mapping)
+        .sort()
+        .map((styleKey) => [styleKey, mapping[styleKey]])
+    )
+    mappingKeys.set(mapping, key)
+  }
+  let compiled = compiledMappings.get(key)
+  if (!compiled) {
+    compiled = { mapping, states: new Map(), links: new Set() }
+    if (compiledMappings.size >= 10_000) {
+      compiledMappings.clear()
+    }
+    compiledMappings.set(key, compiled)
+  }
+  return compiled
+}
+
+function resolveCompiledMapping(
+  compiled: CompiledMapping,
+  stateName: string,
+  theme: Record<string, unknown>
+): Record<string, unknown> {
+  const cached = compiled.states.get(stateName)
+  if (cached?.theme === theme) return cached.props
+
+  const props: Record<string, unknown> = {}
+  for (const styleKey in compiled.mapping) {
+    const value = theme[compiled.mapping[styleKey]]
+    props[styleKey] = value === undefined ? null : getVariableValue(value)
+  }
+  const processed = engine?.processStyleColors(props) ?? props
+  if (compiled.states.size >= 10_000) {
+    compiled.states.clear()
+    for (const link of compiled.links) {
+      link.stateThemes.clear()
+    }
+  }
+  compiled.states.set(stateName, { theme, props: processed })
+  return processed
+}
+
+export function setNativeStyleEngine(next: NativeStyleEngine | null): void {
+  if (engine !== next) {
+    compiledMappings.clear()
+    activeCompiledMappings.clear()
+  }
+  engine = next
+  if (next) {
+    for (const [scopeId, state] of scopeStates) {
+      next.setStateName(state.name, scopeId)
+    }
+  }
+}
+
+export function getNativeStyleEngine(): NativeStyleEngine | null {
+  return engine
+}
+
+export function updateNativeStyleScope(
+  scopeId: string,
+  stateName: string,
+  theme: object
+): void {
+  const previous = scopeStates.get(scopeId)
+  if (previous?.name === stateName && previous.theme === theme) return
+  scopeStates.set(scopeId, { name: stateName, theme })
+
+  if (engine) {
+    const entries: NativeViewStateTableUpdate[] = []
+    for (const compiled of activeCompiledMappings) {
+      let props: Record<string, unknown> | undefined
+      for (const link of compiled.links) {
+        if (link.scopeId !== scopeId) continue
+        const linkedTheme = link.stateThemes.get(stateName)
+        if (linkedTheme === theme) continue
+        props ||= resolveCompiledMapping(
+          compiled,
+          stateName,
+          theme as Record<string, unknown>
+        )
+        entries.push({ id: link.handle.id, state: stateName, props })
+        link.stateThemes.set(stateName, theme)
+      }
+    }
+    if (entries.length) engine.updateViewStateTables(entries)
+  }
+  engine?.setStateName(stateName, scopeId)
+}
+
+export function removeNativeStyleScope(scopeId: string): void {
+  if (!scopeStates.delete(scopeId)) return
+  engine?.removeScope(scopeId)
+}
+
+export function resolveNativeStyleMapping(
+  mapping: NativeStyleThemeMapping,
+  stateName: string,
+  theme: Record<string, unknown>
+): Record<string, unknown> {
+  return resolveCompiledMapping(getCompiledMapping(mapping), stateName, theme)
+}
+
+export function linkNativeStyleMapping(
+  ref: unknown,
+  baseStyle: Record<string, unknown>,
+  mapping: NativeStyleThemeMapping,
+  scopeId: string,
+  stateName: string,
+  theme: Record<string, unknown>
+): NativeStyleEngineLinkHandle | null {
+  if (!engine) return null
+
+  const compiled = getCompiledMapping(mapping)
+  const stateProps = resolveCompiledMapping(compiled, stateName, theme)
+  let base = processedBases.get(baseStyle)
+  if (!base || base.engine !== engine) {
+    base = { engine, props: engine.processStyleColors(baseStyle) }
+    processedBases.set(baseStyle, base)
+  }
+  const state: Record<string, Record<string, unknown>> = {}
+  const stateThemes = new Map<string, object>()
+  for (const [name, cached] of compiled.states) {
+    state[name] = cached.props
+    stateThemes.set(name, cached.theme)
+  }
+  state[stateName] = stateProps
+  stateThemes.set(stateName, theme)
+  const handle = engine.link(ref, { base: base.props, state }, scopeId)
+  if (!handle) return null
+
+  const link: CompiledMappingLink = {
+    handle,
+    scopeId,
+    stateThemes,
+  }
+  compiled.links.add(link)
+  activeCompiledMappings.add(compiled)
+  return {
+    id: handle.id,
+    unlink: () => {
+      compiled.links.delete(link)
+      if (!compiled.links.size) {
+        activeCompiledMappings.delete(compiled)
+      }
+      handle.unlink()
+    },
+  }
+}
+
+/** memo-generation and live-owner sizes for development diagnostics and probes */
+export const getNativeStyleEngineCacheStats = () => ({
+  mappings: compiledMappings.size,
+  activeMappings: activeCompiledMappings.size,
+  states: [...new Set([...compiledMappings.values(), ...activeCompiledMappings])].reduce(
+    (total, compiled) => total + compiled.states.size,
+    0
+  ),
+})
+
+let pending: NativeViewStateUpdate[] | null = null
+let flushListener: ((entries: NativeViewStateUpdate[]) => void) | null = null
+
+/**
+ * instrumentation hook: called after each batched native flush with the
+ * flushed entries (benchmarks, parity tests)
+ */
+export function setNativeStyleEngineFlushListener(
+  cb: ((entries: NativeViewStateUpdate[]) => void) | null
+): void {
+  flushListener = cb
+}
+
+/**
+ * Host-ref hook for createComponent: links eligible mounted hosts to the
+ * engine, unlinks on detach. `nativeStyleUpdate` presence is the per-render
+ * eligibility signal; a host that mounts ineligible simply never links.
+ */
+export function updateNativeStyleLink(
+  ref: {
+    nativeLink?: NativeStyleEngineLinkHandle | null
+    nativeStyleUpdate?: unknown
+    nativePushedKeys?: Set<string>
+  },
+  host: unknown
+): void {
+  if (ref.nativeLink) {
+    ref.nativeLink.unlink()
+    ref.nativeLink = null
+  }
+  // pushed-key tracking is per-link: a new native view starts from the props
+  // React committed, nothing pushed yet
+  ref.nativePushedKeys = undefined
+  if (host && engine && ref.nativeStyleUpdate) {
+    ref.nativeLink = engine.link(host, {})
+  }
+}
+
+export function queueNativeViewState(entry: NativeViewStateUpdate): void {
+  if (!engine) return
+  if (!pending) {
+    pending = []
+    queueMicrotask(() => {
+      const entries = pending!
+      pending = null
+      engine?.applyViewStates(entries)
+      flushListener?.(entries)
+    })
+  }
+  pending.push(entry)
+}

package/src/helpers/nativeTransitionTarget.native.ts

@@ -0,0 +1,22 @@
+import { Platform } from 'react-native'
+import type { NativeTransitionTarget } from '@tamagui/style-grammar'
+
+// the native transition capability matrix is version-gated with NO default:
+// an unknown React Native minor is a diagnostic upstream, never a guessed
+// literal (CODEX-1's recorded wiring precondition). detection reads the
+// platform's own constants; null means "could not detect".
+export function detectNativeTransitionTarget(): NativeTransitionTarget | null {
+  if (Platform.OS !== 'ios' && Platform.OS !== 'android') return null
+  const version = (Platform.constants as any)?.reactNativeVersion
+  const minor = version?.minor
+  if (typeof minor !== 'number' || !Number.isInteger(minor)) return null
+  const target: NativeTransitionTarget = {
+    platform: Platform.OS,
+    reactNativeMinor: minor,
+  }
+  if (Platform.OS === 'android') {
+    const api = Number(Platform.Version)
+    if (Number.isInteger(api)) target.androidApi = api
+  }
+  return target
+}

package/src/helpers/nativeTransitionTarget.ts

@@ -0,0 +1,6 @@
+import type { NativeTransitionTarget } from '@tamagui/style-grammar'
+
+// web build: there is no native target to detect
+export function detectNativeTransitionTarget(): NativeTransitionTarget | null {
+  return null
+}

package/src/helpers/normalizeColor.native.ts

@@ -4,9 +4,8 @@ export { rgba } from '@tamagui/normalize-css-color'
 
 export const normalizeColor = (color?: string | null, opacity?: number) => {
   if (!color) return
-  // handle dynamic color objects (from $theme-dark/$theme-light)
+  // handle dynamic color objects
   if (typeof color !== 'string') return color
-  if (color[0] === '$') return color
 
   const rgbaVal = getRgba(color)
   if (rgbaVal) {
@@ -20,7 +19,7 @@ export const normalizeColor = (color?: string | null, opacity?: number) => {
 }
 
 export const getRgba = (color: string) => {
-  // handle dynamic color objects (from $theme-dark/$theme-light)
+  // handle dynamic color objects
   if (typeof color !== 'string') return
   const colorNum = normalizeCSSColor(color)
   if (colorNum != null) {

package/src/helpers/normalizeColor.ts

@@ -1,7 +1,7 @@
-// web: use color-mix for opacity (CSS-native, works with variables and named colors)
-// animation drivers that need rgba handle their own conversion
-
-import { normalizeCSSColor, rgba } from '@tamagui/normalize-css-color'
+// web: use color-mix for opacity (CSS-native, works with variables and named
+// colors), so nothing here has to parse a color. animation drivers that need
+// numeric channels handle their own conversion. `getRgba` is native-only, see
+// normalizeColor.native.ts.
 
 export const normalizeColor = (color?: string | null, opacity?: number) => {
   if (!color) return
@@ -17,13 +17,3 @@ export const normalizeColor = (color?: string | null, opacity?: number) => {
 
   return color
 }
-
-export const getRgba = (
-  color: string
-): { r: number; g: number; b: number; a: number } | undefined => {
-  if (typeof color !== 'string') return
-  const colorNum = normalizeCSSColor(color)
-  if (colorNum != null) {
-    return rgba(colorNum)
-  }
-}

package/src/helpers/normalizeShadow.native.ts

@@ -1,5 +1,5 @@
 import { defaultOffset } from './defaultOffset'
-import { getRgba, normalizeColor } from './normalizeColor'
+import { getRgba, normalizeColor } from './normalizeColor.native'
 
 export function normalizeShadow({
   shadowColor,

package/src/helpers/normalizeStyle.ts

@@ -1,8 +1,6 @@
 import { expandStyle } from './expandStyle'
 import { fixStyles } from './expandStyles'
-import { isObj } from './isObj'
 import { normalizeValueWithProperty } from './normalizeValueWithProperty'
-import { pseudoDescriptors } from './pseudoDescriptors'
 import { styleOriginalValues } from './styleOriginalValues'
 
 /**
@@ -10,7 +8,7 @@ import { styleOriginalValues } from './styleOriginalValues'
  * It does the following:
  *   1. Shorthands into longhands, px = paddingHorizontal
  *   2. Expands flex, borderColor and other properties that can expand into sub-parts
- *   3. Normalizes all sub pseudo-media-etc styles
+ *   3. Preserves original-value provenance across expanded longhands
  */
 
 export function normalizeStyle(style: Record<string, any>, disableNormalize = false) {
@@ -22,18 +20,6 @@ export function normalizeStyle(style: Record<string, any>, disableNormalize = fa
     const prop = style[key]
     if (prop == null) continue
     const originalValue = originalValues?.[key]
-    if (
-      key in pseudoDescriptors ||
-      // this should capture all parent-based styles like media, group, etc
-      (key[0] === '$' && isObj(prop))
-    ) {
-      res[key] = normalizeStyle(prop, disableNormalize)
-      if (originalValue !== undefined) {
-        nextOriginalValues ||= {}
-        nextOriginalValues[key] = originalValue
-      }
-      continue
-    }
     const value = disableNormalize ? prop : normalizeValueWithProperty(prop, key)
     // expand react-native shorthands
     const out = expandStyle(key, value)

package/src/helpers/normalizeValueWithProperty.ts

@@ -14,8 +14,17 @@ const stylePropsAllPlusTransforms = {
   translateY: true,
 }
 
+// literal "Npx" values (e.g. fontSize="17px"). react native only accepts
+// numbers, so parse them there; web keeps the string and outputs it as css.
+const pxStringRe = /^-?\d*\.?\d+px$/
+
 export function normalizeValueWithProperty(value: any, property = ''): any {
-  if (!isWeb) return value
+  if (!isWeb) {
+    if (typeof value === 'string' && pxStringRe.test(value)) {
+      return Number.parseFloat(value)
+    }
+    return value
+  }
   if (
     stylePropsUnitless[property] ||
     (property && !stylePropsAllPlusTransforms[property]) ||

package/src/helpers/noteOnce.ts

@@ -0,0 +1,9 @@
+const noted = new Set<string>()
+
+export function noteOnce(message: string): void {
+  if (process.env.NODE_ENV === 'development' && !noted.has(message)) {
+    if (noted.size > 1000) noted.clear()
+    noted.add(message)
+    console.warn(message)
+  }
+}

package/src/helpers/{parseNativeStyle.ts → parseNativeStyle.native.ts}

@@ -35,6 +35,23 @@ function resolveColor(raw: string, tokenMap?: TokenMap): any {
   return raw
 }
 
+// the direction grammar React Native itself accepts, sourced from
+// react-native/Libraries/StyleSheet/processBackgroundImage.js — signed and
+// leading-decimal angles, case-insensitive units and keywords. what matters
+// is what React Native reads, not what the CSS spec permits
+const gradientAngle = /^([+-]?\d*\.?\d+)(deg|grad|rad|turn)$/i
+const gradientKeyword =
+  /^to\s+(?:top|bottom|left|right)(?:\s+(?:top|bottom|left|right))?$/i
+
+// RN's object path accepts a position as a NUMBER (points) or a string
+// ending in % — mirroring its own getPositionFromCSSValue: px becomes
+// parseFloat points, % stays a string, anything else is not a position
+function gradientPosition(token: string): number | string | undefined {
+  if (/px$/i.test(token)) return Number.parseFloat(token)
+  if (token.endsWith('%')) return token
+  return undefined
+}
+
 // parse "linear-gradient(direction, color1 pos1, color2 pos2, ...)"
 function parseBackgroundImage(css: string, tokenMap?: TokenMap): any[] | undefined {
   const match = css.match(/^linear-gradient\((.+)\)$/s)
@@ -49,21 +66,44 @@ function parseBackgroundImage(css: string, tokenMap?: TokenMap): any[] | undefin
   let startIdx = 0
 
   const firstPart = parts[0].trim()
-  // check if first part is a direction (starts with "to " or ends with "deg/rad/turn/grad")
-  if (firstPart.startsWith('to ') || /^\d+(\.\d+)?(deg|rad|turn|grad)$/.test(firstPart)) {
+  if (gradientAngle.test(firstPart) || gradientKeyword.test(firstPart)) {
     direction = firstPart
     startIdx = 1
   }
 
+  // tokens classify by what they ARE, never by falling through to the color
+  // slot — the direction, position, and transition-hint misreads were all one
+  // assumption ("any unrecognized token is a color") wearing three costumes
   const colorStops: any[] = []
-  for (let i = startIdx; i < parts.length; i++) {
-    const stopParts = parts[i].trim().match(/\S+\([^)]*\)|\S+/g)
+  const stops = parts.slice(startIdx)
+  let prevWasHint = false
+  for (let i = 0; i < stops.length; i++) {
+    const stopParts = stops[i].trim().match(/\S+\([^)]*\)|\S+/g)
     if (!stopParts) continue
-    const colorRaw = stopParts[0]
-    const color = resolveColor(colorRaw, tokenMap)
-    const positions = stopParts.slice(1)
+
+    // a lone position is a transition hint (RN string parser case 4):
+    // {color:null, positions:[n]} — invalid first, last, or after another
+    // hint, which invalidates the gradient exactly as RN and the web do
+    if (stopParts.length === 1) {
+      const hint = gradientPosition(stopParts[0])
+      if (hint !== undefined) {
+        if (i === 0 || i === stops.length - 1 || prevWasHint) return undefined
+        colorStops.push({ color: null, positions: [hint] })
+        prevWasHint = true
+        continue
+      }
+    }
+    prevWasHint = false
+
+    const color = resolveColor(stopParts[0], tokenMap)
     const stop: any = { color }
-    if (positions.length > 0) {
+    if (stopParts.length > 1) {
+      const positions: (number | string)[] = []
+      for (let p = 1; p < stopParts.length; p++) {
+        const position = gradientPosition(stopParts[p])
+        if (position === undefined) return undefined
+        positions.push(position)
+      }
       stop.positions = positions
     }
     colorStops.push(stop)
@@ -168,8 +208,8 @@ function parseTextShadow(css: string, tokenMap?: TokenMap): [string, any][] | un
 }
 
 function parseDimension(s: string): number | undefined {
-  // strip px/dp suffix
-  const cleaned = s.replace(/px$|dp$/, '')
+  // strip px/dp suffix (css units are case-insensitive)
+  const cleaned = s.replace(/px$|dp$/i, '')
   const n = Number(cleaned)
   return Number.isFinite(n) ? n : undefined
 }

package/src/helpers/parseNativeTransform.native.ts

@@ -0,0 +1,35 @@
+export function parseNativeTransform(raw: string): any[] | null {
+  const out: any[] = []
+  const pattern = /([A-Za-z][\w]*)\(([^()]*)\)/g
+  let end = 0
+  let match: RegExpExecArray | null
+  while ((match = pattern.exec(raw))) {
+    if (raw.slice(end, match.index).trim().replace(/^,/, '').trim()) return null
+    end = pattern.lastIndex
+    const name = match[1]
+    const values = match[2].split(/\s*,\s*|\s+/).filter(Boolean)
+    if (!values.length) return null
+    const converted: (string | number)[] = []
+    for (const value of values) {
+      converted.push(
+        /^-?(?:\d+\.?\d*|\.\d+)(?:px|dp)$/i.test(value)
+          ? Number.parseFloat(value)
+          : /^-?(?:\d+\.?\d*|\.\d+)$/.test(value)
+            ? Number(value)
+            : value
+      )
+    }
+    if (name === 'translate' && converted.length > 1) {
+      out.push({ translateX: converted[0] }, { translateY: converted[1] })
+    } else if (
+      name === 'scale' &&
+      converted.length > 1 &&
+      converted[0] !== converted[1]
+    ) {
+      out.push({ scaleX: converted[0] }, { scaleY: converted[1] })
+    } else {
+      out.push({ [name]: converted[0] })
+    }
+  }
+  return end && !raw.slice(end).trim() ? out : null
+}