@tamagui/web 2.7.7 → 3.0.0-beta.1093.1

package/src/helpers/warnOnce.ts

@@ -0,0 +1,47 @@
+// One development warning per key, for the whole runtime.
+//
+// The set is BOUNDED rather than trusted to stay small, and that bound is what
+// lets a warning quote the offending value. A page rendering a CMS-supplied
+// colour can vary a refused value without limit, and keying on the value alone
+// would grow this set forever.
+//
+// Keying on the PROPERTY alone was the first answer to that and it was too
+// quiet: a second, different typo in the same prop said nothing, and once a
+// property had warned it stayed silent for the rest of the session, so a typo
+// reintroduced through HMR never reported at all. The cap buys the per-value
+// signal back at a fixed cost. Past it the console already holds hundreds of
+// distinct warnings and one more is not what is missing.
+const warnLimit = 500
+const warned = process.env.NODE_ENV !== 'production' ? new Set<string>() : null
+
+export function warnOnce(key: string, message = key) {
+  if (process.env.NODE_ENV === 'development') {
+    if (warned?.has(key) || (warned?.size ?? 0) >= warnLimit) return
+    warned?.add(key)
+    console.warn(`[tamagui] ${message}`)
+  }
+}
+
+/**
+ * A value the flat-value scanner refused, reported where the author can act on
+ * it. Item 5b left refusal silent, matching the clause scanner, so an author
+ * who typed a `;` got nothing back and the bad segment simply never appeared.
+ *
+ * It warns rather than throws, and the throw it replaced is the reason to say
+ * why. A style value is an ordinary place to put a string an app did not write
+ * (an image URL, a colour from a CMS, anything a user typed), so every refusal
+ * here is reachable from hostile input, and an exception on hostile input hands
+ * an attacker the page in exactly the builds a developer is watching.
+ *
+ * What the throw had that a warning must earn back is being hard to miss, so
+ * this names the property, quotes the whole value, and says which modifier or
+ * character caused it; the throw only said "unknown modifier" without naming
+ * one. Keying on the value means every distinct mistake reports, while the same
+ * mistake across a hundred renders still reports once.
+ */
+export function warnRefusedValue(property: string, value: string, reason: string) {
+  warnOnce(
+    `refused:${property}=${value}`,
+    `${property}="${value}" had a segment dropped: ${reason}`
+  )
+}

package/src/helpers/webPropsToSkip.native.ts

@@ -1,18 +1,17 @@
 import { webOnlyStylePropsText, webOnlyStylePropsView } from '@tamagui/helpers'
 
-// pointerEvents is in webOnlyStylePropsView for web CSS, but it's a valid
-// React Native View prop, so we exclude it from the skip list on native.
-// It's handled specially in getSplitStyles.tsx
-const { pointerEvents: _, ...webOnlyStylePropsViewWithoutPointerEvents } =
-  webOnlyStylePropsView
+// textOverflow is in webOnlyStylePropsText for web CSS, but on native we map
+// textOverflow="ellipsis" to numberOfLines={1} + ellipsizeMode="tail" on Text.
+// Handled specially in getSplitStyles.tsx so we exclude it from the skip list.
+const { textOverflow: __, ...webOnlyStylePropsTextWithoutTextOverflow } =
+  webOnlyStylePropsText
 
 /**
  * Web-only props and event handlers that should be skipped on native
  */
 export const webPropsToSkip = {
-  // Reuse web-only style props from webOnlyStyleProps (excluding pointerEvents)
-  ...webOnlyStylePropsViewWithoutPointerEvents,
-  ...webOnlyStylePropsText,
+  ...webOnlyStylePropsView,
+  ...webOnlyStylePropsTextWithoutTextOverflow,
 
   // Web-only event handlers
   onClick: 1,

package/src/helpers/wrapStyleTags.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react'
 import { StyleObjectIdentifier, StyleObjectRules } from '@tamagui/helpers'
 import type { StyleObject } from '../types'
+import { wrapStyleRules } from './insertStyleRule'
 
 // turns out this is pretty slow, creating a bunch of extra tags...
 
@@ -40,6 +41,7 @@ function getCachedStyleTag(styleObject: StyleObject) {
     return cached.element
   }
 
+  const css = wrapStyleRules(rules.join('\n'))
   const element = (
     <style
       key={identifier}
@@ -50,7 +52,7 @@ function getCachedStyleTag(styleObject: StyleObject) {
       // we remove after first render in favor of inserting to a global stylesheet (faster)
       suppressHydrationWarning
     >
-      {rules.join('\n')}
+      {css}
     </style>
   )
 
@@ -65,7 +67,7 @@ function getCachedStyleTag(styleObject: StyleObject) {
 }
 
 export function getStyleTags(styles: StyleObject[]) {
-  if (process.env.TAMAGUI_TARGET !== 'native') {
+  if (!process.env.TAMAGUI_DID_OUTPUT_CSS && process.env.TAMAGUI_TARGET !== 'native') {
     if (styles.length) {
       queueStyleTagCacheClear()
       return <>{styles.map(getCachedStyleTag)}</>

package/src/hooks/getThemeProxied.ts

@@ -3,6 +3,10 @@ import type { MutableRefObject } from 'react'
 import { getConfig, getSetting } from '../config'
 import { getVariable } from '../createVariable'
 import { getDynamicVal } from '../helpers/getDynamicVal'
+import {
+  themeUpdateStateKey,
+  type ThemeUpdateLayerInfo,
+} from '../helpers/themeUpdateState'
 import type {
   ThemeParsed,
   ThemeState,
@@ -48,8 +52,11 @@ type ThemeGettable<Val> = Val & {
 }
 
 // only proxy each theme one time, after that we know that renders are sync,
-// so we can just change the focus of the proxied theme and it can be re-used
-const cache: Map<ThemeParsed, ThemeProxied> = new Map()
+// so we can just change the focus of the proxied theme and it can be re-used.
+// WeakMap so dynamically created ThemeUpdate theme objects
+// don't retain their proxies after the layer is gone
+const trackingCache: WeakMap<ThemeParsed, ThemeProxied> = new WeakMap()
+const untrackedCache: WeakMap<ThemeParsed, ThemeProxied> = new WeakMap()
 
 let curKeys: MutableRefObject<Set<string> | null>
 let curSchemeKeys: MutableRefObject<Set<string> | null>
@@ -58,22 +65,47 @@ let curState: ThemeState | null
 
 const emptyObject = {}
 
+function track(key: string, schemeOptimized = false) {
+  if (!curKeys) return
+  if (!curKeys.current) {
+    curKeys.current = new Set()
+  }
+  curKeys.current.add(key)
+
+  // track scheme-optimized keys separately so we know if a scheme-only
+  // change can skip re-render (when all accessed keys use DynamicColorIOS)
+  if (schemeOptimized && curSchemeKeys) {
+    if (!curSchemeKeys.current) {
+      curSchemeKeys.current = new Set()
+    }
+    curSchemeKeys.current.add(key)
+  }
+
+  if (process.env.NODE_ENV === 'development' && curProps.debug) {
+    console.info(` 🎨 useTheme() tracking key: ${key} schemeOptimized=${schemeOptimized}`)
+  }
+}
+
 export function getThemeProxied(
   // underscore to prevent accidental usage below
   _props: UseThemeWithStateProps,
   _state: ThemeState | null,
   _keys: MutableRefObject<Set<string> | null>,
-  _schemeKeys?: MutableRefObject<Set<string> | null>
+  _schemeKeys?: MutableRefObject<Set<string> | null>,
+  optimizeForFirstRender = false
 ): ThemeProxied {
   if (!_state?.theme) {
     return emptyObject
   }
 
-  curKeys = _keys
-  curSchemeKeys = _schemeKeys!
+  if (!optimizeForFirstRender) {
+    curKeys = _keys
+    curSchemeKeys = _schemeKeys!
+  }
   curProps = _props
   curState = _state
 
+  const cache = optimizeForFirstRender ? untrackedCache : trackingCache
   if (cache.has(curState.theme)) {
     const proxied = cache.get(curState.theme)!
     return proxied
@@ -84,121 +116,127 @@ export function getThemeProxied(
 
   const config = getConfig()
 
-  function track(key: string, schemeOptimized = false) {
-    if (!curKeys) return
-    if (!curKeys.current) {
-      curKeys.current = new Set()
-    }
-    curKeys.current.add(key)
-
-    // track scheme-optimized keys separately so we know if a scheme-only
-    // change can skip re-render (when all accessed keys use DynamicColorIOS)
-    if (schemeOptimized && curSchemeKeys) {
-      if (!curSchemeKeys.current) {
-        curSchemeKeys.current = new Set()
-      }
-      curSchemeKeys.current.add(key)
-    }
-
-    if (process.env.NODE_ENV === 'development' && curProps.debug) {
-      console.info(
-        ` 🎨 useTheme() tracking key: ${key} schemeOptimized=${schemeOptimized}`
-      )
-    }
-  }
-
   const proxied = Object.fromEntries(
     Object.entries(_state.theme).flatMap(([key, value]) => {
-      const proxied = {
-        ...value,
-        get val() {
-          // when they touch the actual value we only track it if its a variable (web), its ignored!
-          if (!globalThis.tamaguiAvoidTracking) {
-            // always track .val - not scheme optimized since they're getting raw value
-            track(key, false)
+      const get = (platform?: 'web') => {
+        if (!curState) return
+
+        const outVal = getVariable(value)
+        const { name, scheme } = curState
+
+        if (process.env.TAMAGUI_TARGET === 'native') {
+          // ios can avoid re-rendering for scheme changes (light↔dark) when using DynamicColorIOS.
+          // DynamicColorIOS always resolves by the OS appearance, so this is only correct for a
+          // subtree that follows the OS scheme. it does NOT work when a <Theme> forces a scheme
+          // away from the OS/root — at any depth. `inverses` counts scheme flips from the root, so
+          // `inverses === 0` is exactly "this subtree still follows the OS". isInverse alone was
+          // wrong: a sub-theme keeping its parent's forced scheme (dark_blue under a forced dark,
+          // light root) has isInverse=false yet must NOT optimize, or iOS would pick the OS-scheme
+          // value (light) instead of the forced dark value.
+          const fastSchemeChange = getSetting('fastSchemeChange')
+          const rootMatchesSystem = doesRootSchemeMatchSystem()
+          const shouldOptimize =
+            scheme &&
+            platform !== 'web' &&
+            supportsDynamicColorIOS &&
+            !curProps.deopt &&
+            !curState.inverses &&
+            fastSchemeChange &&
+            rootMatchesSystem
+
+          if (process.env.NODE_ENV === 'development' && curProps.debug === 'verbose') {
+            console.info(
+              ` 🎨 useTheme().get(${key}) theme=${name} scheme=${scheme}`,
+              `\n   shouldOptimize=${shouldOptimize} (dynamicColorIOS=${supportsDynamicColorIOS} deopt=${curProps.deopt} inverses=${curState.inverses} fastScheme=${fastSchemeChange} rootMatch=${rootMatchesSystem})`
+            )
+          }
+
+          // a ThemeUpdate layer overrides this key: the config.themes
+          // pair below would bypass it. use the layer's literal light/dark
+          // pair when it has one, otherwise deopt to normal tracking
+          const inlineLayer = (curState.theme as any)?.[themeUpdateStateKey] as
+            | ThemeUpdateLayerInfo
+            | undefined
+          const inlineOverridden = !!inlineLayer?.overridden.has(key)
+
+          if (shouldOptimize && inlineOverridden) {
+            const pair = inlineLayer!.pairs[key]
+            if (pair) {
+              if (!optimizeForFirstRender) {
+                track(key, true)
+              }
+              return getDynamicVal({
+                scheme,
+                val: String(pair[scheme]),
+                oppositeVal: String(pair[scheme === 'dark' ? 'light' : 'dark']),
+              })
+            }
+            // referenced values have no precomputed pair: fall through to
+            // the tracked path below
           }
-          return value.val
-        },
-        get(platform?: 'web') {
-          if (!curState) return
-
-          const outVal = getVariable(value)
-          const { name, scheme } = curState
-
-          if (process.env.TAMAGUI_TARGET === 'native') {
-            // ios can avoid re-rendering for scheme changes (light↔dark) when using DynamicColorIOS.
-            // DynamicColorIOS always resolves by the OS appearance, so this is only correct for a
-            // subtree that follows the OS scheme. it does NOT work when a <Theme> forces a scheme
-            // away from the OS/root — at any depth. `inverses` counts scheme flips from the root, so
-            // `inverses === 0` is exactly "this subtree still follows the OS". isInverse alone was
-            // wrong: a sub-theme keeping its parent's forced scheme (dark_blue under a forced dark,
-            // light root) has isInverse=false yet must NOT optimize, or iOS would pick the OS-scheme
-            // value (light) instead of the forced dark value.
-            const fastSchemeChange = getSetting('fastSchemeChange')
-            const rootMatchesSystem = doesRootSchemeMatchSystem()
-            const shouldOptimize =
-              scheme &&
-              platform !== 'web' &&
-              supportsDynamicColorIOS &&
-              !curProps.deopt &&
-              !curState.inverses &&
-              fastSchemeChange &&
-              rootMatchesSystem
+
+          if (shouldOptimize && !inlineOverridden) {
+            const oppositeScheme = scheme === 'dark' ? 'light' : 'dark'
+            const oppositeName = name.replace(scheme, oppositeScheme)
+            const color = getVariable(config.themes[name]?.[key])
+            const oppositeColor = getVariable(config.themes[oppositeName]?.[key])
 
             if (process.env.NODE_ENV === 'development' && curProps.debug === 'verbose') {
               console.info(
-                ` 🎨 useTheme().get(${key}) theme=${name} scheme=${scheme}`,
-                `\n   shouldOptimize=${shouldOptimize} (dynamicColorIOS=${supportsDynamicColorIOS} deopt=${curProps.deopt} inverses=${curState.inverses} fastScheme=${fastSchemeChange} rootMatch=${rootMatchesSystem})`
+                ` 🎨 useTheme().get(${key}) using DynamicColorIOS`,
+                `\n   color=${color} oppositeColor=${oppositeColor}`
               )
             }
 
-            if (shouldOptimize) {
-              const oppositeScheme = scheme === 'dark' ? 'light' : 'dark'
-              const oppositeName = name.replace(scheme, oppositeScheme)
-              const color = getVariable(config.themes[name]?.[key])
-              const oppositeColor = getVariable(config.themes[oppositeName]?.[key])
-
-              if (
-                process.env.NODE_ENV === 'development' &&
-                curProps.debug === 'verbose'
-              ) {
-                console.info(
-                  ` 🎨 useTheme().get(${key}) using DynamicColorIOS`,
-                  `\n   color=${color} oppositeColor=${oppositeColor}`
-                )
-              }
+            const dynamicVal = getDynamicVal({
+              scheme,
+              val: color,
+              oppositeVal: oppositeColor,
+            })
 
-              const dynamicVal = getDynamicVal({
-                scheme,
-                val: color,
-                oppositeVal: oppositeColor,
-              })
-
-              // track as scheme-optimized - can skip re-render for scheme-only changes
+            if (!optimizeForFirstRender) {
+              // track as scheme-optimized - can skip re-render for scheme changes
               track(key, true)
-
-              return dynamicVal
             }
 
-            if (process.env.NODE_ENV === 'development' && curProps.debug) {
-              console.info(
-                ` 🎨 useTheme().get(${key}) tracking key (not optimizing)`,
-                `\n   platform=${platform} dynamicColorIOS=${supportsDynamicColorIOS} deopt=${curProps.deopt} fastScheme=${fastSchemeChange}`
-              )
-            }
+            return dynamicVal
+          }
+
+          if (process.env.NODE_ENV === 'development' && curProps.debug) {
+            console.info(
+              ` 🎨 useTheme().get(${key}) tracking key (not optimizing)`,
+              `\n   platform=${platform} dynamicColorIOS=${supportsDynamicColorIOS} deopt=${curProps.deopt} fastScheme=${fastSchemeChange}`
+            )
+          }
 
-            // not scheme-optimized
+          if (!optimizeForFirstRender) {
             track(key, false)
           }
+        }
 
-          return outVal
-        },
+        return outVal
       }
 
-      return [
-        [key, proxied],
-        [`$${key}`, proxied],
-      ]
+      const proxied = optimizeForFirstRender
+        ? {
+            ...value,
+            val: value.val,
+            get,
+          }
+        : {
+            ...value,
+            get val() {
+              // when they touch the actual value we only track it if its a variable (web), its ignored!
+              if (!globalThis.tamaguiAvoidTracking) {
+                // always track .val - not scheme optimized since they're getting raw value
+                track(key, false)
+              }
+              return value.val
+            },
+            get,
+          }
+
+      return [[key, proxied]]
     })
   ) as ThemeProxied
 

package/src/hooks/isOptimizedForFirstRender.native.ts

@@ -0,0 +1,7 @@
+import { getSetting } from '../config'
+
+// native defaults to 'first-render': skip per-key theme/media tracking for
+// the fastest initial render, theme/media changes re-render coarsely
+export function isOptimizedForFirstRender(): boolean {
+  return getSetting('optimizeFor') !== 'updates'
+}

package/src/hooks/isOptimizedForFirstRender.ts

@@ -0,0 +1,7 @@
+import { getSetting } from '../config'
+
+// web defaults to 'updates': granular theme/media tracking so changes
+// re-render only consumers. see isOptimizedForFirstRender.native.ts
+export function isOptimizedForFirstRender(): boolean {
+  return getSetting('optimizeFor') === 'first-render'
+}

package/src/hooks/useAnimationDriver.ts

@@ -0,0 +1,56 @@
+import { useConfiguration } from '../contexts/ComponentContext'
+import type {
+  AnimationDriver,
+  AnimationDriverWithAnimatedNumbers,
+  UniversalAnimatedNumber,
+  UseAnimatedNumberReaction,
+  UseAnimatedNumberStyle,
+  UseAnimatedNumbersStyle,
+} from '../types'
+
+// resolves the configured animation driver from context/config. the wrappers below
+// delegate to it directly so first-party code and user code exercise the same surface.
+// the resolved driver must not change identity mid-lifecycle (only relevant with
+// `animatedBy` multi-driver setups).
+export function useAnimationDriver(): AnimationDriver {
+  const { animationDriver } = useConfiguration()
+  if (!animationDriver || animationDriver.isStub) {
+    throw new Error(
+      process.env.NODE_ENV !== 'production'
+        ? `No animation driver configured. Pass \`animations\` to createTamagui. See: https://tamagui.dev/docs/core/animations`
+        : '❌ Error 011'
+    )
+  }
+  return animationDriver
+}
+
+function useAnimatedNumberDriver(): AnimationDriverWithAnimatedNumbers {
+  const driver = useAnimationDriver()
+  const animatedDriver = driver as Partial<AnimationDriverWithAnimatedNumbers>
+  if (
+    typeof animatedDriver.useAnimatedNumber !== 'function' ||
+    typeof animatedDriver.useAnimatedNumberStyle !== 'function' ||
+    typeof animatedDriver.useAnimatedNumbersStyle !== 'function' ||
+    typeof animatedDriver.useAnimatedNumberReaction !== 'function'
+  ) {
+    throw new Error(
+      process.env.NODE_ENV !== 'production'
+        ? `The configured animation driver does not include animated-number hooks. When using the CSS driver, import \`createAnimations\` from \`@tamagui/animations-css/extras\` instead of \`@tamagui/animations-css\`. See: https://tamagui.dev/docs/core/animations-css`
+        : '❌ Error 012'
+    )
+  }
+  return animatedDriver as AnimationDriverWithAnimatedNumbers
+}
+
+export function useAnimatedNumber(initial: number): UniversalAnimatedNumber<any> {
+  return useAnimatedNumberDriver().useAnimatedNumber(initial)
+}
+
+export const useAnimatedNumberStyle: UseAnimatedNumberStyle = (value, getStyle) =>
+  useAnimatedNumberDriver().useAnimatedNumberStyle(value, getStyle)
+
+export const useAnimatedNumbersStyle: UseAnimatedNumbersStyle = (values, getStyle) =>
+  useAnimatedNumberDriver().useAnimatedNumbersStyle(values, getStyle)
+
+export const useAnimatedNumberReaction: UseAnimatedNumberReaction = (opts, onValue) =>
+  useAnimatedNumberDriver().useAnimatedNumberReaction(opts, onValue)