@tamagui/web 2.0.0-rc.3 → 2.0.0-rc.31

package/src/types.tsx

@@ -426,7 +426,7 @@ export type FontLanguageProps = LanguageContextType & {
 
 export type ThemeProviderProps = {
   className?: string
-  defaultTheme: string
+  defaultTheme: string | null | undefined
   /** @deprecated moved to createTamagui({ settings: { disableRootThemeClass } }) */
   disableRootThemeClass?: boolean
   /** @deprecated moved to createTamagui({ settings: { themeClassNameOnRoot } }) */
@@ -612,6 +612,14 @@ export type TamaguiComponentStateRef = {
 
   // cleanup function for media emit listener
   mediaEmitCleanup?: () => void
+
+  // previous pseudo state for detecting enter vs exit transitions
+  prevPseudoState?: {
+    hover?: boolean
+    press?: boolean
+    focus?: boolean
+    groups?: Record<string, { hover?: boolean; press?: boolean; focus?: boolean }>
+  }
 }
 
 export type ComponentGroupEmitter = {
@@ -789,6 +797,12 @@ export type OnlyAllowShorthandsSetting = TamaguiConfig['settings'] extends {
   ? X
   : false
 
+export type OnlyShorthandStylePropsSetting = TamaguiConfig['settings'] extends {
+  onlyShorthandStyleProps: infer X
+}
+  ? X
+  : false
+
 export type CreateTamaguiConfig<
   A extends GenericTokens,
   B extends GenericThemes,
@@ -797,6 +811,9 @@ export type CreateTamaguiConfig<
   E extends GenericAnimations = GenericAnimations,
   F extends GenericFonts = GenericFonts,
   H extends GenericTamaguiSettings = GenericTamaguiSettings,
+  // preserve the raw animation driver keys ('default' | 'css' | etc)
+  // defaults to string so generic TamaguiInternalConfig accepts any driver keys
+  AnimDriverKeys extends string = string,
 > = {
   fonts: RemoveLanguagePostfixes<F>
   fontLanguages: GetLanguagePostfixes<F> extends never
@@ -815,6 +832,8 @@ export type CreateTamaguiConfig<
   // Multi-driver: { default: cssDriver, spring: motiDriver }
   // Single: AnimationDriver<E>
   animations: AnimationDriver<E> | AnimationsConfigObject
+  // phantom type for preserving driver keys - never set at runtime, only for type inference
+  animationDriverKeys?: AnimDriverKeys
   settings: H
 }
 
@@ -880,6 +899,16 @@ type ExtractAnimationConfig<E> =
         ? E
         : EmptyAnimations
 
+// Helper to extract animation driver keys from raw animations prop
+// Single driver: returns 'default'
+// Multi-driver { default: x, css: y }: returns 'default' | 'css'
+type ExtractAnimationDriverKeys<E> =
+  E extends AnimationDriver<any>
+    ? 'default'
+    : E extends { default: AnimationDriver<any> }
+      ? Extract<keyof E, string>
+      : 'default'
+
 export type InferTamaguiConfig<Conf> =
   Conf extends ConfProps<infer A, infer B, infer C, infer D, infer E, infer F, infer H>
     ? TamaguiInternalConfig<
@@ -889,7 +918,8 @@ export type InferTamaguiConfig<Conf> =
         D extends GenericMedia ? D : EmptyMedia,
         ExtractAnimationConfig<E>,
         F extends GenericFonts ? F : EmptyFonts,
-        H extends GenericTamaguiSettings ? H : EmptyTamaguiSettings
+        H extends GenericTamaguiSettings ? H : EmptyTamaguiSettings,
+        ExtractAnimationDriverKeys<E>
       >
     : unknown
 
@@ -948,7 +978,10 @@ export type ThemeTokens = `$${ThemeKeys}`
 // Animation names (slow, fast, bouncy) for the `transition` prop
 // Extract animation keys from the driver's `animations` property
 // The AnimationDriver<Config> has an `animations: Config` property
-type GetAnimationsFromDriver<T> = T extends { animations: infer A } ? keyof A : never
+// Use Extract<keyof A, string> to filter out number/symbol keys from fallback case
+type GetAnimationsFromDriver<T> = T extends { animations: infer A }
+  ? Extract<keyof A, string>
+  : never
 
 // For multi-driver configs like { default: AnimationDriver, css: AnimationDriver }
 // Extract from the 'default' driver or first driver found
@@ -970,21 +1003,18 @@ type InferredTransitionKeys =
 export type TransitionKeys = InferredTransitionKeys
 
 // Driver keys (default, css, spring) for the `animatedBy` prop
-type InferredAnimationDriverKeys =
-  TamaguiConfig['animations'] extends AnimationDriver<any>
-    ? 'default'
-    : TamaguiConfig['animations'] extends Record<string, AnimationDriver<any>>
-      ? keyof TamaguiConfig['animations']
-      : 'default'
-
-// Combine inferred keys from config with TypeOverride keys
-// This ensures both config-defined drivers AND lazy-loaded drivers are available
+// Gets driver keys directly from TamaguiConfig.animationDriverKeys
+// Falls back to 'default' only when TamaguiCustomConfig is empty (no augmentation)
+// The Exclude<X, undefined> handles optional property, then we intersect with string
+// to ensure only string keys (not symbols/numbers)
 export type AnimationDriverKeys =
   | 'default'
-  | InferredAnimationDriverKeys
+  | Extract<Exclude<TamaguiConfig['animationDriverKeys'], undefined>, string>
+  // add TypeOverride keys for lazy-loaded drivers
   | (ReturnType<TypeOverride['animationDrivers']> extends 1
       ? never
       : ReturnType<TypeOverride['animationDrivers']>)
+
 export type FontLanguages = ArrayIntersection<TamaguiConfig['fontLanguages']>
 
 export interface ThemeProps {
@@ -1208,6 +1238,23 @@ export interface GenericTamaguiSettings {
    * @default 16
    */
   remBaseFontSize?: number
+
+  /**
+   * When true, removes the individual longhand style props for border,
+   * outline, and shadow (borderWidth, borderStyle, borderColor,
+   * outlineWidth, outlineStyle, outlineColor, outlineOffset,
+   * shadowColor, shadowOffset, shadowOpacity, shadowRadius) from the
+   * type system, encouraging use of the combined shorthand props instead
+   * (`border`, `outline`, `boxShadow`).
+   *
+   * This avoids specificity issues when mixing shorthand and longhand
+   * props in atomic CSS output.
+   *
+   * Note: this is type-level only - it does not change runtime behavior.
+   *
+   * @default false
+   */
+  onlyShorthandStyleProps?: boolean
 }
 
 export type TamaguiSettings = TamaguiConfig['settings']
@@ -1282,8 +1329,11 @@ export type TamaguiInternalConfig<
   E extends GenericAnimations = GenericAnimations,
   F extends GenericFonts = GenericFonts,
   G extends GenericTamaguiSettings = GenericTamaguiSettings,
+  // preserve the raw animation driver keys ('default' | 'css' | etc)
+  // defaults to string so generic TamaguiInternalConfig accepts any driver keys
+  AnimDriverKeys extends string = string,
 > = Omit<CreateTamaguiProps, keyof GenericTamaguiConfig> &
-  Omit<CreateTamaguiConfig<A, B, C, D, E, F, G>, 'tokens'> & {
+  Omit<CreateTamaguiConfig<A, B, C, D, E, F, G, AnimDriverKeys>, 'tokens'> & {
     // TODO need to make it this but this breaks types, revisit
     // animations: E //AnimationDriver<E>
     // with $ prefixes for fast lookups (one time cost at startup vs every render)
@@ -1302,6 +1352,9 @@ export type TamaguiInternalConfig<
     settings: Omit<GenericTamaguiSettings, keyof G> & G
     defaultFont?: string
     defaultFontToken: `${string}`
+    // multi-driver animation config (e.g., { default: motionDriver, css: cssDriver })
+    // used for component-level driver selection via animatedBy prop
+    animationDrivers?: Record<string, AnimationDriver>
   }
 
 export type GetAnimationKeys<A extends GenericTamaguiConfig> = keyof A['animations']
@@ -1414,29 +1467,58 @@ export type MatchMedia = (query: string) => MediaQueryList
 // TODO can override for better types
 export type AnimationConfigType = any
 
+/**
+ * Spring configuration parameters that can override preset defaults.
+ * Use with array syntax: transition={['bouncy', { stiffness: 1000, damping: 70 }]}
+ */
+export type TransitionSpringConfig = {
+  stiffness?: number
+  damping?: number
+  mass?: number
+  tension?: number
+  friction?: number
+  velocity?: number
+  overshootClamping?: boolean
+  duration?: number
+  bounciness?: number
+  speed?: number
+}
+
 export type TransitionProp =
   | TransitionKeys
-  | {
-      [key: string]:
-        | TransitionKeys
-        | {
-            type: TransitionKeys
-            [key: string]: any
-          }
-    }
-  | [
-      TransitionKeys,
-      {
-        delay?: number
+  | ({
+      default?: TransitionKeys
+      enter?: TransitionKeys
+      exit?: TransitionKeys
+      delay?: number
+    } & TransitionSpringConfig & {
         [key: string]:
           | TransitionKeys
           | {
-              type?: TransitionKeys
+              type: TransitionKeys
               [key: string]: any
             }
           | number
+          | boolean
           | undefined
-      },
+      })
+  | [
+      TransitionKeys,
+      {
+        delay?: number
+        enter?: TransitionKeys
+        exit?: TransitionKeys
+      } & TransitionSpringConfig & {
+          [key: string]:
+            | TransitionKeys
+            | {
+                type?: TransitionKeys
+                [key: string]: any
+              }
+            | number
+            | boolean
+            | undefined
+        },
     ]
 
 /**
@@ -1615,11 +1697,13 @@ export type ColorTokens =
 export type ZIndexTokens =
   | SpecificTokensSpecial
   | GetTokenString<keyof Tokens['zIndex']>
+  | ThemeValueFallbackZIndex
   | number
 
 export type RadiusTokens =
   | SpecificTokensSpecial
   | GetTokenString<keyof Tokens['radius']>
+  | ThemeValueFallbackRadius
   | number
   | RemString
 
@@ -1719,16 +1803,18 @@ export type ThemeValueByCategory<K extends string | number | symbol> = K extends
             ? ColorTokens
             : K extends 'zIndex'
               ? ZIndexTokens
-              : K extends 'lineHeight'
-                ? FontLineHeightTokens
-                : K extends 'fontWeight'
-                  ? FontWeightTokens
-                  : K extends 'letterSpacing'
-                    ? FontLetterSpacingTokens
-                    : K extends keyof Tokens
-                      ? // fallback to user-defined tokens
-                        GetTokenString<keyof Tokens[K]>
-                      : never
+              : K extends 'radius'
+                ? RadiusTokens
+                : K extends 'lineHeight'
+                  ? FontLineHeightTokens
+                  : K extends 'fontWeight'
+                    ? FontWeightTokens
+                    : K extends 'letterSpacing'
+                      ? FontLetterSpacingTokens
+                      : K extends keyof Tokens
+                        ? // fallback to user-defined tokens
+                          GetTokenString<keyof Tokens[K]>
+                        : never
 
 export type FontKeys = 'fontFamily'
 export type FontSizeKeys = 'fontSize'
@@ -1741,21 +1827,21 @@ export type OpacityKeys = 'opacity'
 export type ThemeValueGet<K extends string | number | symbol> = K extends 'theme'
   ? ThemeTokens
   : K extends SizeKeys
-    ? SizeTokens | ThemeValueFallbackSize
+    ? SizeTokens
     : K extends FontKeys
       ? FontTokens
       : K extends FontSizeKeys
         ? FontSizeTokens
         : K extends `${`border${string | ''}Radius`}`
-          ? RadiusTokens | ThemeValueFallbackRadius
+          ? RadiusTokens
           : K extends SpaceKeys
             ? K extends 'shadowOffset'
               ? { width: SpaceTokens; height: SpaceTokens }
-              : SpaceTokens | ThemeValueFallbackSpace
+              : SpaceTokens
             : K extends ColorKeys
               ? ColorTokens | ThemeValueFallbackColor
               : K extends ZIndexKeys
-                ? ZIndexTokens | ThemeValueFallbackZIndex
+                ? ZIndexTokens
                 : K extends LineHeightKeys
                   ? FontLineHeightTokens
                   : K extends FontWeightKeys
@@ -1787,6 +1873,21 @@ export type NarrowShorthands = Narrow<Shorthands>
 export type Longhands = NarrowShorthands[keyof NarrowShorthands]
 
 type OnlyAllowShorthands = TamaguiConfig['settings']['onlyAllowShorthands']
+type OnlyShorthandStyleProps = TamaguiConfig['settings']['onlyShorthandStyleProps']
+
+// longhand style props that overlap with border/outline/shadow shorthands
+type ShorthandLonghandProps =
+  | 'borderWidth'
+  | 'borderStyle'
+  | 'borderColor'
+  | 'outlineWidth'
+  | 'outlineStyle'
+  | 'outlineColor'
+  | 'outlineOffset'
+  | 'shadowColor'
+  | 'shadowOffset'
+  | 'shadowOpacity'
+  | 'shadowRadius'
 
 // adds shorthand props
 export type WithShorthands<StyleProps> = {
@@ -1796,15 +1897,30 @@ export type WithShorthands<StyleProps> = {
 }
 
 // adds pseudo props
+// PseudoStyleWithTransition allows transition inside pseudo-style props for enter/exit timing
+export type PseudoStyleWithTransition<A> = A & { transition?: TransitionProp | null }
+
 export type WithPseudoProps<A> = {
-  hoverStyle?: A | null
-  pressStyle?: A | null
-  focusStyle?: A | null
-  focusWithinStyle?: A | null
-  focusVisibleStyle?: A | null
-  disabledStyle?: A | null
-  exitStyle?: A | null
-  enterStyle?: A | null
+  hoverStyle?: PseudoStyleWithTransition<A> | null
+  pressStyle?: PseudoStyleWithTransition<A> | null
+  focusStyle?: PseudoStyleWithTransition<A> | null
+  focusWithinStyle?: PseudoStyleWithTransition<A> | null
+  focusVisibleStyle?: PseudoStyleWithTransition<A> | null
+  disabledStyle?: PseudoStyleWithTransition<A> | null
+  exitStyle?: PseudoStyleWithTransition<A> | null
+  enterStyle?: PseudoStyleWithTransition<A> | null
+}
+
+// type for transitions extracted from pseudo-style props (e.g., hoverStyle.transition)
+// includes $group-*-hover, $group-*-press, $group-*-focus patterns
+export type PseudoTransitions = Partial<
+  Record<keyof WithPseudoProps<any>, TransitionProp | null>
+> & {
+  // allow $group-{name}-{pseudo} keys dynamically
+  [key: `$group-${string}-${'hover' | 'press' | 'focus'}`]:
+    | TransitionProp
+    | null
+    | undefined
 }
 
 export type PseudoPropKeys = keyof WithPseudoProps<any>
@@ -1827,12 +1943,18 @@ export type AllPlatforms = 'web' | 'native' | 'android' | 'ios'
 //
 // add both theme and shorthands
 //
+type MaybeOmitLonghands<A> = OnlyShorthandStyleProps extends true
+  ? Omit<A, ShorthandLonghandProps>
+  : A
+
 export type WithThemeAndShorthands<
   A extends object,
   Variants = {},
 > = OnlyAllowShorthands extends true
-  ? WithThemeValues<Omit<A, Longhands>> & Variants & WithShorthands<WithThemeValues<A>>
-  : WithThemeValues<A> & Variants & WithShorthands<WithThemeValues<A>>
+  ? WithThemeValues<MaybeOmitLonghands<Omit<A, Longhands>>> &
+      Variants &
+      WithShorthands<WithThemeValues<A>>
+  : WithThemeValues<MaybeOmitLonghands<A>> & Variants & WithShorthands<WithThemeValues<A>>
 
 //
 // combines all of theme, shorthands, pseudos...
@@ -1932,6 +2054,18 @@ type BorderPreset =
 // Note: on native, only supports a single border (all sides)
 export type BorderValue = BorderPreset | (string & {})
 
+// outline shorthand presets - examples for autocomplete hints
+type OutlinePreset =
+  | '1px solid' // width + style
+  | '1px solid $outlineColor' // width + style + color token
+  | '2px dashed $outlineColor' // width + style + color
+  | '1px dotted red' // width + style + color
+  | 'none'
+
+// Outline - CSS shorthand string format (e.g. "2px solid $outlineColor")
+// Expands to outlineWidth, outlineStyle, outlineColor on native
+export type OutlineValue = OutlinePreset | (string & {})
+
 interface ExtraStyleProps {
   /**
    * Controls the curve style of rounded corners.
@@ -1965,6 +2099,12 @@ interface ExtraStyleProps {
    * Outline width. Supported on web and native.
    */
   outlineWidth?: SpaceValue
+  /**
+   * CSS outline shorthand string. Supports tokens: "2px solid $outlineColor"
+   * Expands to outlineWidth, outlineStyle, outlineColor on native.
+   * Works on web and native.
+   */
+  outline?: OutlineValue
   /**
    * On native, maps to the `selectable` prop on Text (userSelect !== 'none')
    */
@@ -2613,6 +2753,10 @@ export type GetStyleState = {
   // Track original token values (like '$8') before they get resolved to CSS vars
   // This is used to preserve token strings in overriddenContextProps
   originalContextPropValues?: Record<string, any>
+  // Transitions extracted from pseudo-style props (e.g., hoverStyle.transition)
+  pseudoTransitions?: PseudoTransitions | null
+  // Resolved animation driver (respects animatedBy prop)
+  animationDriver?: AnimationDriver | null
 }
 
 export type StyleResolver<Response = PropMappedValue> = (
@@ -3051,18 +3195,15 @@ export type UseAnimatedNumber<
 
 export type AnimationDriver<A extends AnimationConfig = AnimationConfig> = {
   isReactNative?: boolean
-  supportsCSS?: boolean
   /** What style format the driver expects as input: 'css' (CSS variables) or 'value' (resolved values) */
   inputStyle?: 'css' | 'value'
   /** How the driver outputs styles: 'css' (className-based) or 'inline' (style object) */
   outputStyle?: 'css' | 'inline'
-  needsWebStyles?: boolean
+  needsCustomComponent?: boolean
   avoidReRenders?: boolean
   onMount?: () => void
   /** When true, this is a stub driver with no real animation support */
   isStub?: boolean
-  /** When true, the driver uses CSS classes for animations (doesn't need inline styles) */
-  classNameAnimation?: boolean
   useAnimations: UseAnimationHook
   usePresence: () => UsePresenceResult
   ResetPresence: (props: {
@@ -3079,7 +3220,10 @@ export type AnimationDriver<A extends AnimationConfig = AnimationConfig> = {
 
 export type UseAnimationProps = TamaguiComponentPropsBase & Record<string, any>
 
-type UseStyleListener = (nextStyle: Record<string, unknown>) => void
+type UseStyleListener = (
+  nextStyle: Record<string, unknown>,
+  effectiveTransition?: TransitionProp | null
+) => void
 export type UseStyleEmitter = (cb: UseStyleListener) => void
 
 export type UseAnimationHook = (props: {
@@ -3123,6 +3267,10 @@ export type GetStyleResult = {
   mediaGroups?: Set<string>
   // Style values that override context props (for issues #3670, #3676)
   overriddenContextProps?: Record<string, any>
+  // Transitions extracted from pseudo-style props (e.g., hoverStyle.transition)
+  pseudoTransitions?: PseudoTransitions | null
+  // Effective transition to use (accounts for entering pseudo states)
+  effectiveTransition?: TransitionProp | null
 }
 
 export type ClassNamesObject = Record<string, string>

package/src/views/TamaguiProvider.tsx

@@ -1,22 +1,39 @@
-import { isWeb, useIsomorphicLayoutEffect } from '@tamagui/constants'
+import { useIsomorphicLayoutEffect } from '@tamagui/constants'
 import { ClientOnly } from '@tamagui/use-did-finish-ssr'
 import React, { useEffect } from 'react'
-import { getConfig, getSetting } from '../config'
+import { getSetting } from '../config'
 import { ComponentContext } from '../contexts/ComponentContext'
 import { stopAccumulatingRules } from '../helpers/insertStyleRule'
 import { updateMediaListeners } from '../hooks/useMedia'
+import { resolveAnimationDriver } from '../helpers/resolveAnimationDriver'
 import type { AnimationDriver, TamaguiProviderProps } from '../types'
+import { TamaguiRoot } from './TamaguiRoot'
 import { ThemeProvider } from './ThemeProvider'
 
+// cache first theme key per config to avoid Object.keys allocation on every render
+let _cachedFirstKey: string | undefined
+let _cachedConfig: any
+
+function firstThemeKey(config: any): string | undefined {
+  if (config !== _cachedConfig) {
+    _cachedConfig = config
+    _cachedFirstKey = config?.themes ? Object.keys(config.themes)[0] : undefined
+  }
+  return _cachedFirstKey
+}
+
 export function TamaguiProvider({
   children,
   disableInjectCSS,
   config,
   className,
-  defaultTheme,
+  defaultTheme: defaultThemeProp,
   reset,
   insets,
 }: TamaguiProviderProps) {
+  // fall back to first theme when defaultTheme is null/undefined
+  // (e.g. useColorScheme() returns null on first render in RN 0.83+)
+  const defaultTheme = defaultThemeProp || firstThemeKey(config) || 'light'
   useIsomorphicLayoutEffect(() => {
     stopAccumulatingRules()
     updateMediaListeners()
@@ -28,31 +45,28 @@ export function TamaguiProvider({
   )
 
   // Get the default animation driver from config
-  // animations can be a single driver or { default: driver, ...others }
-  const defaultAnimationDriver: AnimationDriver = React.useMemo(() => {
-    const animations = config?.animations
-    if (!animations) return null
-    if ('default' in animations) {
-      return (animations as { default: any }).default
-    }
-    return animations
-  }, [config?.animations])
+  // config.animations is already normalized to the default driver in createTamagui
+  // resolveAnimationDriver handles edge cases where raw multi-driver object leaks through
+  const defaultAnimationDriver: AnimationDriver | null = React.useMemo(
+    () => resolveAnimationDriver(config?.animations),
+    [config?.animations]
+  )
 
   useEffect(() => {
     defaultAnimationDriver?.onMount?.()
   }, [])
 
   let contents = (
-    <UnmountedClassName>
-      <ComponentContext.Provider
-        animationDriver={defaultAnimationDriver}
-        insets={memoizedInsets}
-      >
-        <ThemeProvider defaultTheme={defaultTheme} reset={reset} className={className}>
+    <ComponentContext.Provider
+      animationDriver={defaultAnimationDriver}
+      insets={memoizedInsets}
+    >
+      <ThemeProvider defaultTheme={defaultTheme} reset={reset} className={className}>
+        <TamaguiRoot theme={defaultTheme} isRootRoot>
           {children}
-        </ThemeProvider>
-      </ComponentContext.Provider>
-    </UnmountedClassName>
+        </TamaguiRoot>
+      </ThemeProvider>
+    </ComponentContext.Provider>
   )
 
   if (getSetting('disableSSR')) {
@@ -79,36 +93,3 @@ export function TamaguiProvider({
     </>
   )
 }
-
-// for CSS animations and default font inheritance
-function UnmountedClassName(props: { children: React.ReactNode }) {
-  const [mounted, setMounted] = React.useState(false)
-
-  React.useEffect(() => {
-    setMounted(true)
-  }, [])
-
-  if (!isWeb) {
-    return props.children
-  }
-
-  const config = getConfig()
-  const defaultFont = config.defaultFont
-  const fontClass = defaultFont ? `font_${defaultFont}` : ''
-  const className = [mounted ? '' : 't_unmounted', fontClass].filter(Boolean).join(' ')
-
-  return (
-    <span
-      style={{
-        display: 'contents',
-        // set default font so nested text inherits
-        fontFamily: defaultFont ? 'var(--f-family)' : undefined,
-      }}
-      className={className || undefined}
-    >
-      {props.children}
-    </span>
-  )
-}
-
-TamaguiProvider['displayName'] = 'TamaguiProvider'

package/src/views/TamaguiRoot.native.tsx

@@ -0,0 +1,9 @@
+import type React from 'react'
+
+export function TamaguiRoot(props: {
+  children: React.ReactNode
+  trackMount?: boolean
+  style?: any
+}) {
+  return props.children
+}

package/src/views/TamaguiRoot.tsx

@@ -0,0 +1,64 @@
+import React from 'react'
+import { getConfig } from '../config'
+import { ThemeName } from '../types'
+import { Theme } from './Theme'
+
+let defaultFontClass = ''
+
+/**
+ * Applies default font class and CSS variable inheritance via display:contents.
+ * Used by TamaguiProvider at the root and by portals to re-establish font scope.
+ * Pass trackMount to also handle the t_unmounted class for CSS animation gating.
+ */
+export function TamaguiRoot({
+  children,
+  theme,
+  isRootRoot,
+  passThrough,
+  style,
+}: {
+  children: React.ReactNode
+  theme: ThemeName
+  isRootRoot?: boolean
+  passThrough?: boolean
+  style?: React.CSSProperties
+}) {
+  const [mounted, setMounted] = React.useState(!isRootRoot)
+
+  React.useEffect(() => {
+    if (!mounted) {
+      setMounted(true)
+    }
+  }, [])
+
+  // cache the font class name
+  if (!defaultFontClass) {
+    const config = getConfig()
+    const defaultFont = config.defaultFont
+    if (defaultFont) {
+      defaultFontClass = `font_${defaultFont}`
+    }
+  }
+
+  const contents = (
+    <span
+      style={style}
+      // font_body (or default font) sets all font properties via shared CSS rule
+      className={`_dsp_contents ${mounted ? '' : 't_unmounted'} ${defaultFontClass}`}
+    >
+      {children}
+    </span>
+  )
+
+  // at root, ThemeProvider already applied theme - skip re-wrapping
+  // for portals/modals, we re-thread the theme so each root gets the right className setup
+  if (isRootRoot) {
+    return contents
+  }
+
+  return (
+    <Theme passThrough={passThrough} contain forceClassName name={theme}>
+      {contents}
+    </Theme>
+  )
+}