@tamagui/web 3.0.3 → 3.0.4

package/src/_withNativeStyle.tsx

@@ -1,20 +1,47 @@
 import { setRef } from '@tamagui/compose-refs'
-import React, { useCallback, useContext, useRef, useState } from 'react'
+import { isAndroid, isIos } from '@tamagui/constants'
+import React, { use } from 'react'
 import { _withStableStyle } from './_withStableStyle'
 import {
   getNativeStyleEngine,
   linkNativeStyleMapping,
   resolveNativeStyleMapping,
-  type NativeStyleEngineLinkHandle,
   type NativeStyleThemeMapping,
 } from './helpers/nativeStyleEngine'
 import { getThemeState, ThemeStateContext } from './hooks/useThemeState'
+import { hooks } from './setupHooks'
 
-/** internal: emitted by the native compiler when experimental.nativeFastPath is on */
+// the host props RN's <Text> passes for a non-pressable text outside a text
+// ancestor, given none of the props it remaps (the compiler guarantees that)
+const hostTextProps = {
+  accessible: isAndroid ? false : isIos ? true : undefined,
+  allowFontScaling: true,
+  ellipsizeMode: 'tail',
+}
+
+/**
+ * internal: emitted by the native compiler when experimental.nativeFastPath is on.
+ *
+ * One component over the host: the theme scope is the only context read, the
+ * host ref links straight to the engine and unlinks through React's ref
+ * cleanup, so a themed view costs one component and one engine call to mount.
+ *
+ * `host: 'view'`: `Component` is RN's host view (`unstable_NativeView`).
+ * <View> resets TextAncestorContext for its children when it sits inside a
+ * <Text>; this wrapper does that reset itself, so the host view can carry
+ * children without changing what a nested <Text> renders.
+ *
+ * `host: 'text'`: `Component` is RN's <Text>, and outside a text ancestor this
+ * renders its host (`unstable_NativeText`) with the exact props <Text> would
+ * pass: the defaults above, `overflow: 'hidden'` first in the style, a string
+ * fontWeight, and TextAncestorContext only around element children. Inside a
+ * text ancestor it renders <Text>, which owns the virtual text path.
+ */
 export const _withNativeStyle = (
   Component: any,
   baseStyle: Record<string, unknown>,
-  themeStyleKeys: NativeStyleThemeMapping
+  themeStyleKeys: NativeStyleThemeMapping,
+  host?: 'view' | 'text'
 ) => {
   const Fallback = _withStableStyle(
     Component,
@@ -28,62 +55,121 @@ export const _withNativeStyle = (
     true,
     false
   )
+  const baseViews = host ? hooks.getBaseViews?.() : undefined
+  const TextAncestor: React.Context<boolean> | undefined = baseViews?.TextAncestor
+  const TextAncestorProvider = TextAncestor?.Provider as React.Provider<boolean>
+  // <Text> rewrites userSelect and verticalAlign into other props
+  const HostText =
+    host === 'text' && !('userSelect' in baseStyle) && !('verticalAlign' in baseStyle)
+      ? baseViews?.NativeText
+      : undefined
+  const hostTextBase = HostText
+    ? {
+        overflow: 'hidden',
+        ...baseStyle,
+        ...(typeof baseStyle.fontWeight === 'number' && {
+          fontWeight: String(baseStyle.fontWeight),
+        }),
+      }
+    : baseStyle
+  // one style array per scope and host mode, its theme slot set to the scope's
+  // current state on every render. the engine owns a linked view's theme
+  // values, so a re-render after a switch hands React the same array, its diff
+  // skips the style, and the host is not re-committed with values the engine
+  // already applied. a new host reads the array's current state at creation
+  const styles = new Map<string, (object | null)[]>()
+  const hostTextStyles = new Map<string, (object | null)[]>()
+  // bundlers inline imports as a module lookup at every use; bind them once
+  // here, outside the per-mount path
+  const ScopeContext = ThemeStateContext
+  const engineOf = getNativeStyleEngine
+  const scopeState = getThemeState
+  const resolve = resolveNativeStyleMapping
+  const linkMapping = linkNativeStyleMapping
+  const assignRef = setRef
 
-  const Native = React.memo(function NativeStyleView({
-    _scopeId,
-    ...props
-  }: {
-    _scopeId: string
-    [key: string]: any
-  }) {
-    const { ref, _expressions: _ignoredExpressions, ...rest } = props
-    const link = useRef<NativeStyleEngineLinkHandle | null>(null)
-    // a host the engine refuses (a nitro view) never gets theme pushes, so
-    // this view renders through the theme-subscribed fallback instead
-    const [refused, setRefused] = useState(false)
-    const themeState = getThemeState(_scopeId)
-    const stateName = themeState?.name
-    const theme = themeState?.theme
-    const hostRef = useCallback(
-      (host: unknown) => {
-        link.current?.unlink()
-        link.current = null
-        setRef(ref, host)
-        if (host && stateName && theme) {
-          link.current = linkNativeStyleMapping(
-            host,
-            baseStyle,
-            themeStyleKeys,
-            _scopeId,
-            stateName,
-            theme
-          )
-          if (!link.current) setRefused(true)
-        }
-      },
-      [ref, _scopeId, stateName, theme]
-    )
-    if (refused) return <Fallback {...props} />
-    const stateStyle =
-      stateName && theme
-        ? resolveNativeStyleMapping(themeStyleKeys, stateName, theme)
-        : undefined
+  // `use` reads context from whichever render calls it, so the compiler can
+  // call this straight from the parent component's render (see `inline`)
+  const render = (props: any, key?: React.Key | null) => {
+    const scopeId = use(ScopeContext)
+    const inText = TextAncestor ? use(TextAncestor) : false
+    const themeState = scopeId && engineOf() ? scopeState(scopeId) : undefined
+    const resetsText = inText && host === 'view'
 
-    if (process.env.NODE_ENV === 'development' && (!stateName || !theme)) {
-      throw new Error(
-        `[@tamagui/core] native fast path cannot resolve theme ${JSON.stringify(stateName)}`
+    if (!themeState) {
+      return resetsText ? (
+        <TextAncestorProvider key={key} value={false}>
+          <Fallback {...props} />
+        </TextAncestorProvider>
+      ) : (
+        <Fallback key={key} {...props} />
       )
     }
 
-    return <Component ref={hostRef} style={[baseStyle, stateStyle]} {...rest} />
-  })
+    // compiled createElement calls carry an `_expressions` prop for the
+    // fallback; jsx never does, so it forwards its props without a copy
+    let rest = props
+    if (props._expressions !== undefined) {
+      const { _expressions: _ignoredExpressions, ...withoutExpressions } = props
+      rest = withoutExpressions
+    }
+    const ref = props.ref
+    const { name, theme } = themeState
+    const asHostText = HostText && !inText
+    const Rendered = asHostText ? HostText : Component
+    const cache = asHostText ? hostTextStyles : styles
+    let style = cache.get(scopeId)
+    if (!style) {
+      style = [asHostText ? hostTextBase : baseStyle, null]
+      cache.set(scopeId, style)
+    }
+    style[1] = resolve(themeStyleKeys, name, theme)
+    const wrapped = resetsText || (asHostText && mayRenderText(rest.children))
+    const element = (
+      <Rendered
+        key={wrapped ? undefined : key}
+        {...(asHostText && hostTextProps)}
+        {...rest}
+        ref={(node: unknown) => {
+          // a callback ref may return its own cleanup (React 19), which then
+          // replaces the null call
+          let refCleanup: unknown
+          if (typeof ref === 'function') refCleanup = ref(node)
+          else assignRef(ref, node)
+          const link = linkMapping(node, themeStyleKeys, scopeId, name, theme)
+          return () => {
+            link?.unlink()
+            if (typeof refCleanup === 'function') refCleanup()
+            else assignRef(ref, null)
+          }
+        }}
+        style={style}
+      />
+    )
 
-  return React.memo(function NativeStyleBoundary(props: any) {
-    const scopeId = useContext(ThemeStateContext)
-    return getNativeStyleEngine() && scopeId ? (
-      <Native {...props} _scopeId={scopeId} />
-    ) : (
-      <Fallback {...props} />
+    if (!wrapped) return element
+    return (
+      <TextAncestorProvider key={key} value={!resetsText}>
+        {element}
+      </TextAncestorProvider>
     )
-  })
+  }
+
+  const NativeStyleView = (props: any) => render(props)
+  // the compiler emits `View.inline(<View ... />)` where the calling
+  // component's theme scope is provably the element's own: the element is
+  // only built, never mounted, and its host renders in the caller's place
+  NativeStyleView.inline = (element: React.ReactElement<any>) =>
+    render(element.props, element.key)
+  return NativeStyleView
+}
+
+// <Text>'s own check for children that could render a nested <Text>: arrays
+// longer than three are assumed to
+function mayRenderText(children: unknown): boolean {
+  if (children == null) return false
+  if (Array.isArray(children) && children.length <= 3) {
+    return children.some((child) => child != null && typeof child === 'object')
+  }
+  return typeof children === 'object'
 }

package/src/helpers/nativeStyleEngine.ts

@@ -86,27 +86,45 @@ export interface NativeViewStateUpdate {
   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 {
+  /**
+   * links a mounted host. `table` is a shared table id from setTableState
+   * (compiler mappings) or per-view slots (runtime views driven through
+   * applyViewStates). `commitNow` commits the table's active state for the
+   * view once, for a host whose render raced a scope change.
+   */
   link(
     ref: unknown,
-    slots: NativeStyleEngineSlots,
-    scopeId?: string
+    table: NativeStyleEngineSlots | number,
+    scopeId?: string,
+    commitNow?: boolean
   ): NativeStyleEngineLinkHandle | null
+  /**
+   * links many mounted hosts to shared tables in one call: entry i links
+   * refs[i] to tableIds[i] under scopes[scopeIndexes[i]]. returns the id of
+   * entry 0; ids are consecutive, and an entry whose host is gone consumes
+   * its id unlinked
+   */
+  linkTables(
+    refs: unknown[],
+    tableIds: number[],
+    scopeIndexes: number[],
+    scopes: string[]
+  ): number
+  /** unlinks an id from linkTables */
+  unlink(id: number): void
+  /**
+   * fills one state of a shared table, read by every view linked to it;
+   * views already showing that state commit the new props
+   */
+  setTableState(tableId: number, state: string, props: Record<string, unknown>): void
   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
@@ -115,12 +133,6 @@ export interface NativeStyleEngine {
 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 ResolvedMappingState {
   theme: object
   /** raw resolved values, what React renders through RN's own style normalizer */
@@ -132,17 +144,19 @@ interface ResolvedMappingState {
 interface CompiledMapping {
   mapping: NativeStyleThemeMapping
   states: Map<string, ResolvedMappingState>
-  links: Set<CompiledMappingLink>
+  /** the engine table every view of this mapping links to */
+  tableId: number
+  /** the resolved state last sent to the engine table, per state name */
+  sent: Map<string, ResolvedMappingState>
 }
 
 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> }
->()
+// linked mappings per scope, with their live link counts. they remain update
+// owners across memo-generation rollovers, and a scope change only syncs the
+// mappings linked under that scope
+const scopeMappings = new Map<string, Map<CompiledMapping, number>>()
+let nextTableId = 1
 
 function getCompiledMapping(mapping: NativeStyleThemeMapping): CompiledMapping {
   let key = mappingKeys.get(mapping)
@@ -156,7 +170,12 @@ function getCompiledMapping(mapping: NativeStyleThemeMapping): CompiledMapping {
   }
   let compiled = compiledMappings.get(key)
   if (!compiled) {
-    compiled = { mapping, states: new Map(), links: new Set() }
+    compiled = {
+      mapping,
+      states: new Map(),
+      tableId: nextTableId++,
+      sent: new Map(),
+    }
     if (compiledMappings.size >= 10_000) {
       compiledMappings.clear()
     }
@@ -184,19 +203,31 @@ function resolveCompiledMapping(
   const nativeProps = engine?.processStyleColors(renderProps) ?? renderProps
   if (compiled.states.size >= 10_000) {
     compiled.states.clear()
-    for (const link of compiled.links) {
-      link.stateThemes.clear()
-    }
   }
   const resolved: ResolvedMappingState = { theme, renderProps, nativeProps }
   compiled.states.set(stateName, resolved)
   return resolved
 }
 
+/** resolves one state of a mapping and sends it to the engine table once */
+function syncTableState(
+  compiled: CompiledMapping,
+  stateName: string,
+  theme: Record<string, unknown>
+): void {
+  const resolved = resolveCompiledMapping(compiled, stateName, theme)
+  if (compiled.sent.get(stateName) === resolved) return
+  compiled.sent.set(stateName, resolved)
+  engine!.setTableState(compiled.tableId, stateName, resolved.nativeProps)
+}
+
 export function setNativeStyleEngine(next: NativeStyleEngine | null): void {
   if (engine !== next) {
+    settleReleases()
     compiledMappings.clear()
-    activeCompiledMappings.clear()
+    scopeMappings.clear()
+    pendingLinks = []
+    unlinkedPending = 0
   }
   engine = next
   if (next) {
@@ -217,26 +248,19 @@ export function updateNativeStyleScope(
 ): void {
   const previous = scopeStates.get(scopeId)
   if (previous?.name === stateName && previous.theme === theme) return
+  // pending views rendered the outgoing state: link them before it changes
+  flushNativeStyleLinks()
   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>
-        ).nativeProps
-        entries.push({ id: link.handle.id, state: stateName, props })
-        link.stateThemes.set(stateName, theme)
+    // one table entry per mapping, never per view: a state name resolves to
+    // one theme, so every scope showing it reads the same table entry
+    const linked = scopeMappings.get(scopeId)
+    if (linked) {
+      for (const compiled of linked.keys()) {
+        syncTableState(compiled, stateName, theme as Record<string, unknown>)
       }
     }
-    if (entries.length) engine.updateViewStateTables(entries)
   }
   engine?.setStateName(stateName, scopeId)
 }
@@ -254,9 +278,112 @@ export function resolveNativeStyleMapping(
   return resolveCompiledMapping(getCompiledMapping(mapping), stateName, theme).renderProps
 }
 
+interface MappingLink {
+  ref: unknown
+  compiled: CompiledMapping
+  scopeId: string
+  /** 0 while pending, -1 once unlinked */
+  id: number
+  /** the engine that assigned `id`: a later engine swap must not receive its unlink */
+  owner: NativeStyleEngine | null
+}
+
+// views link lazily: a mount only records its host here, and the engine
+// links every pending view in one call before a scope next changes. linking
+// exists for theme switches, so a mount pays nothing native, and a view that
+// unmounts before any switch never reaches the engine
+let pendingLinks: MappingLink[] = []
+// pending entries unlinked before any flush; compacted once they dominate
+let unlinkedPending = 0
+
+function trackScopeMapping(link: MappingLink, delta: 1 | -1) {
+  let linked = scopeMappings.get(link.scopeId)
+  if (!linked) scopeMappings.set(link.scopeId, (linked = new Map()))
+  const count = (linked.get(link.compiled) ?? 0) + delta
+  if (count) {
+    linked.set(link.compiled, count)
+  } else {
+    linked.delete(link.compiled)
+    if (!linked.size) scopeMappings.delete(link.scopeId)
+  }
+}
+
+/** links every pending view in one engine call */
+export function flushNativeStyleLinks(): void {
+  settleReleases()
+  if (!pendingLinks.length) return
+  const links = pendingLinks
+  pendingLinks = []
+  unlinkedPending = 0
+  if (!engine) return
+  const live = links.filter((link) => link.id === 0)
+  if (!live.length) return
+  const refs: unknown[] = []
+  const tableIds: number[] = []
+  const scopeIndexes: number[] = []
+  const scopes: string[] = []
+  for (const link of live) {
+    let scopeIndex = scopes.indexOf(link.scopeId)
+    if (scopeIndex === -1) scopeIndex = scopes.push(link.scopeId) - 1
+    refs.push(link.ref)
+    tableIds.push(link.compiled.tableId)
+    scopeIndexes.push(scopeIndex)
+  }
+  const firstId = engine.linkTables(refs, tableIds, scopeIndexes, scopes)
+  for (let i = 0; i < live.length; i++) {
+    const link = live[i]!
+    link.id = firstId + i
+    link.owner = engine
+    link.ref = null
+    trackScopeMapping(link, 1)
+  }
+}
+
+// React detaches and re-attaches a callback ref whenever the callback changes,
+// which a parent re-render does to every child. a release settles after the
+// commit, so the same host attaching again keeps its link and the engine keeps
+// its per-view caches instead of unlinking and relinking every view
+interface Release {
+  compiled: CompiledMapping
+  scopeId: string
+  handle: NativeStyleEngineLinkHandle
+  settle: () => void
+}
+const releases = new Map<unknown, Release>()
+let settleQueued = false
+
+function settleReleases() {
+  settleQueued = false
+  if (!releases.size) return
+  const settling = [...releases.values()]
+  releases.clear()
+  for (const release of settling) release.settle()
+}
+
+function releasable(
+  ref: unknown,
+  compiled: CompiledMapping,
+  scopeId: string,
+  id: number,
+  settle: () => void
+): NativeStyleEngineLinkHandle {
+  const handle: NativeStyleEngineLinkHandle = {
+    id,
+    unlink: () => {
+      const prior = releases.get(ref)
+      if (prior && prior.handle !== handle) prior.settle()
+      releases.set(ref, { compiled, scopeId, handle, settle })
+      if (!settleQueued) {
+        settleQueued = true
+        queueMicrotask(settleReleases)
+      }
+    },
+  }
+  return handle
+}
+
 export function linkNativeStyleMapping(
   ref: unknown,
-  baseStyle: Record<string, unknown>,
   mapping: NativeStyleThemeMapping,
   scopeId: string,
   stateName: string,
@@ -266,71 +393,73 @@ export function linkNativeStyleMapping(
 
   const compiled = getCompiledMapping(mapping)
   // a scope can advance (layout effect) after a concurrent render captured its
-  // theme but before that render's host ref links. the engine's link() only
-  // stores tables, it never commits, so link against the live scope state and
-  // commit that table once to correct the stale React commit.
+  // theme but before that render's host ref links. link that host now against
+  // the live scope state and have the engine commit it once to correct the
+  // stale React commit.
   const scopeState = scopeStates.get(scopeId)
-  const currentStateName = scopeState?.name ?? stateName
-  const currentTheme = (scopeState?.theme ?? theme) as Record<string, unknown>
-  const stale = currentStateName !== stateName || currentTheme !== theme
-  const stateProps = resolveCompiledMapping(
-    compiled,
-    currentStateName,
-    currentTheme
-  ).nativeProps
-  let base = processedBases.get(baseStyle)
-  if (!base || base.engine !== engine) {
-    base = {
-      engine,
-      props: engine.processStyleColors(normalizeNativeStyle(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.nativeProps
-    stateThemes.set(name, cached.theme)
+  const stale =
+    scopeState && (scopeState.name !== stateName || scopeState.theme !== theme)
+  const kept = releases.get(ref)
+  if (kept) {
+    releases.delete(ref)
+    if (!stale && kept.compiled === compiled && kept.scopeId === scopeId)
+      return kept.handle
+    kept.settle()
   }
-  state[currentStateName] = stateProps
-  stateThemes.set(currentStateName, currentTheme)
-  const handle = engine.link(ref, { base: base.props, state }, scopeId)
-  if (!handle) return null
-
   if (stale) {
-    engine.updateViewStateTables([
-      { id: handle.id, state: currentStateName, props: stateProps },
-    ])
-  }
-
-  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)
-      }
+    syncTableState(compiled, scopeState.name, scopeState.theme as Record<string, unknown>)
+    const handle = engine.link(ref, compiled.tableId, scopeId, true)
+    if (!handle) return null
+    const link: MappingLink = {
+      ref: null,
+      compiled,
+      scopeId,
+      id: handle.id,
+      owner: engine,
+    }
+    trackScopeMapping(link, 1)
+    return releasable(ref, compiled, scopeId, handle.id, () => {
+      if (link.id === -1) return
+      link.id = -1
+      if (link.owner === engine) trackScopeMapping(link, -1)
       handle.unlink()
-    },
+    })
   }
+
+  // the table must hold the state this view rendered before a switch links it
+  syncTableState(compiled, stateName, theme)
+  const link: MappingLink = { ref, compiled, scopeId, id: 0, owner: null }
+  pendingLinks.push(link)
+  return releasable(ref, compiled, scopeId, 0, () => {
+    const id = link.id
+    if (id === -1) return
+    link.id = -1
+    link.ref = null
+    if (id > 0) {
+      // scope accounting was reset when the engine changed
+      if (link.owner === engine) trackScopeMapping(link, -1)
+      link.owner!.unlink(id)
+    } else if (++unlinkedPending > 512 && unlinkedPending * 2 > pendingLinks.length) {
+      pendingLinks = pendingLinks.filter((pending) => pending.id === 0)
+      unlinkedPending = 0
+    }
+  })
 }
 
 /** 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
-  ),
-})
+export const getNativeStyleEngineCacheStats = () => {
+  const active = new Set(
+    [...scopeMappings.values()].flatMap((linked) => [...linked.keys()])
+  )
+  return {
+    mappings: compiledMappings.size,
+    activeMappings: active.size,
+    states: [...new Set([...compiledMappings.values(), ...active])].reduce(
+      (total, compiled) => total + compiled.states.size,
+      0
+    ),
+  }
+}
 
 let pending: NativeViewStateUpdate[] | null = null
 let flushListener: ((entries: NativeViewStateUpdate[]) => void) | null = null

package/src/index.ts

@@ -23,6 +23,7 @@ export {
   setNativeStyleEngine,
   getNativeStyleEngine,
   setNativeStyleEngineFlushListener,
+  flushNativeStyleLinks,
   updateNativeStyleScope,
   removeNativeStyleScope,
   type NativeStyleEngine,

package/src/setupHooks.ts

@@ -31,5 +31,6 @@ type InternalHooks = {
     View: any
     Text: any
     TextAncestor: any
+    NativeText?: any
   }
 }