@tamagui/web 3.0.0-beta.922.1 → 3.0.0

package/src/helpers/getThemeCSSRules.ts

@@ -5,6 +5,7 @@ import { variableToString } from '../createVariable'
 import type { CreateTamaguiProps, ThemeParsed, Variable } from '../types'
 import { getOrCreateVariable, getOrCreateMutatedVariable } from './registerCSSVariable'
 import { sortString } from './sortString'
+import { getAuthoredThemeScheme, themeSchemeSelectorPrefix } from './themes'
 
 const darkLight = ['dark', 'light']
 const lightDark = ['light', 'dark']
@@ -29,6 +30,9 @@ export function getThemeCSSRules(props: {
   ) {
     const cssRuleSets: string[] = []
     const { config, themeName, theme, names } = props
+    const whitespace = process.env.NODE_ENV === 'development' ? ' ' : ''
+    const mediaIndent = process.env.NODE_ENV === 'development' ? '\n    ' : ''
+    const mediaClose = process.env.NODE_ENV === 'development' ? '\n  ' : ''
 
     // special case for SSR
     const hasDarkLight =
@@ -60,6 +64,7 @@ export function getThemeCSSRules(props: {
     const isLightBase = themeName === 'light'
     const baseSelectors = names.map((name) => `${CNP}${name}`)
     const selectorsSet = new Set(isDarkBase || isLightBase ? baseSelectors : [])
+    const selectorScheme = new Map<string, 'light' | 'dark'>()
 
     // The full resolved name is authoritative. `:not(#t_theme_full_name)` is
     // an always-matching specificity anchor: a bounded relative selector for
@@ -78,8 +83,16 @@ export function getThemeCSSRules(props: {
       const maxDepth = 2
 
       for (const subName of names) {
-        const isDark = isDarkBase || subName.startsWith('dark_')
-        const isLight = !isDark && (isLightBase || subName.startsWith('light_'))
+        // identical themes dedupe into one canonical name, and an alias can carry
+        // the opposite scheme to the name it deduped into: light_inverse IS dark,
+        // so it arrives here under themeName "dark". its own prefix therefore
+        // decides its scheme, and the base only answers for an unprefixed name.
+        // reading the base first pointed every cross-scheme alias at the wrong
+        // parent, which silently made <Theme name="inverse"> a no-op.
+        const hasDarkPrefix = subName === 'dark' || subName.startsWith('dark_')
+        const hasLightPrefix = subName === 'light' || subName.startsWith('light_')
+        const isDark = hasDarkPrefix || (!hasLightPrefix && isDarkBase)
+        const isLight = hasLightPrefix || (!hasDarkPrefix && isLightBase)
 
         if (!(isDark || isLight)) {
           // neither light nor dark subtheme, just generate one selector with :root:root which
@@ -117,12 +130,18 @@ export function getThemeCSSRules(props: {
 
           // for light/dark/light:
           const parentSelectorString = parentSelectors.join(' ')
-          selectorsSet.add(`${parentSelectorString} ${nextChildSelector}`)
+          const selector = `${parentSelectorString} ${nextChildSelector}`
+          selectorsSet.add(selector)
+          // remember which scheme's root this selector was built for, so the
+          // prefers-color-scheme pass below can route it. a theme carrying
+          // aliases from both schemes has to reach both media blocks.
+          selectorScheme.set(selector, isDark ? 'dark' : 'light')
         }
       }
     }
 
     const selectors = [...selectorsSet].sort(sortString)
+    const authoredScheme = getAuthoredThemeScheme(theme)
 
     // only do our :root attach if it's not light/dark - not support sub themes on root saves a lot of effort/size
     const selectorsString =
@@ -133,44 +152,63 @@ export function getThemeCSSRules(props: {
           if (!isOnRoot) return `:root ${x}`
           return `${addTo === 'body' ? 'body' : ':root'}${x}`
         })
-        .join(', ') + `, .tm_xxt`
+        .join(', ') +
+      `, .tm_xxt` +
+      (authoredScheme ? `, ${themeSchemeSelectorPrefix}${authoredScheme}` : '')
 
-    const css = `${selectorsString} {${vars}}`
+    const css = `${selectorsString}${whitespace}{${vars}}`
     cssRuleSets.push(css)
 
     if (getSetting('shouldAddPrefersColorThemes')) {
-      const isDark = themeName.startsWith('dark')
-      const baseName = isDark ? 'dark' : 'light'
-      const lessSpecificSelectors = selectors
-        .map((x) => {
-          if (x == darkSelector || x === lightSelector) return `:root`
-          if (
-            (isDark && x.startsWith(lightSelector)) ||
-            (!isDark && x.startsWith(darkSelector))
-          ) {
-            return
-          }
-          return x.replace(/^\.t_(dark|light) /, '').trim()
-        })
-        .filter(Boolean)
-        .join(', ')
-
-      // only emit body background/color for base themes, not every sub-theme
-      const isBase = !themeName.includes('_')
-      let bodyRulesString = ''
-      if (isBase) {
-        const bgString = theme.background
-          ? `background:${variableToString(theme.background)};`
-          : ''
-        const fgString = theme.color ? `color:${variableToString(theme.color)}` : ''
-        bodyRulesString = bgString || fgString ? `body{${bgString}${fgString}}\n    ` : ''
+      // inside a media block the root carries no theme class, so the leading
+      // `.t_light `/`.t_dark ` is stripped and the block itself stands in for it.
+      // a theme reached under BOTH roots therefore has to emit into both blocks:
+      // light_inverse dedupes into dark, so the dark values it holds are what an
+      // implicitly-light root must serve, while dark's own values serve the dark
+      // one. keying the whole set off themeName dropped one of the two.
+      const schemeOf = (x: string) => {
+        if (x === darkSelector) return 'dark'
+        if (x === lightSelector) return 'light'
+        if (x.startsWith(`${darkSelector} `)) return 'dark'
+        if (x.startsWith(`${lightSelector} `)) return 'light'
+        return selectorScheme.get(x)
       }
 
-      const themeRules = `${lessSpecificSelectors} {${vars}}`
-      const prefersMediaSelectors = `@media(prefers-color-scheme:${baseName}){
-    ${bodyRulesString}${themeRules}
-  }`
-      cssRuleSets.push(prefersMediaSelectors)
+      for (const baseName of lightDark) {
+        const lessSpecificSelectors = selectors
+          .map((x) => {
+            if (x === darkSelector || x === lightSelector) {
+              return schemeOf(x) === baseName ? ':root' : undefined
+            }
+            // a selector rooted in the other scheme is unreachable here: that
+            // root would have to carry an explicit class, which the non-media
+            // rules above already cover at higher specificity.
+            const scheme = schemeOf(x)
+            if (scheme && scheme !== baseName) return
+            return x.replace(/^\.t_(dark|light) /, '').trim()
+          })
+          .filter(Boolean)
+          .join(', ')
+
+        if (!lessSpecificSelectors) continue
+
+        // only emit body background/color for base themes, not every sub-theme,
+        // and only for the scheme this theme actually grounds
+        const isBase = !themeName.includes('_')
+        let bodyRulesString = ''
+        if (isBase && themeName === baseName) {
+          const bgString = theme.background
+            ? `background:${variableToString(theme.background)};`
+            : ''
+          const fgString = theme.color ? `color:${variableToString(theme.color)}` : ''
+          bodyRulesString =
+            bgString || fgString ? `body{${bgString}${fgString}}${mediaIndent}` : ''
+        }
+
+        cssRuleSets.push(
+          `@media(prefers-color-scheme:${baseName}){${mediaIndent}${bodyRulesString}${lessSpecificSelectors}${whitespace}{${vars}}${mediaClose}}`
+        )
+      }
     }
 
     const selectionStyles = getSetting('selectionStyles')

package/src/helpers/grammarConfig.ts

@@ -1,3 +1,6 @@
+// leaf subpath on purpose: the barrel pulls in the transition parser, which
+// belongs to drivers and the compiler, not to every app that imports core
+import { canonicalTransitionProperty } from '@tamagui/animation-helpers/propertyNames'
 import { platformMatches } from '@tamagui/constants'
 import { simpleHash } from '@tamagui/helpers'
 import {
@@ -201,6 +204,15 @@ export function prepareConfigRevision(
     borderRadius: 8,
   }
   const propertyKind = (property: string) => propertyKinds[property] || 0
+  // every border side width reads the one borderWidth group, as css does
+  const tokenCategory = (property: string): RuntimeTokenCategory | undefined =>
+    config.tokensParsed[property]
+      ? property
+      : config.tokensParsed.borderWidth &&
+          property.startsWith('border') &&
+          property.endsWith('Width')
+        ? 'borderWidth'
+        : getTokenCategoryForProperty(property)
   // transition strings are re-normalized on every render of every animated
   // element; the result only depends on this revision's shorthands
   const normalizedTransitions = new Map<string, string>()
@@ -209,7 +221,7 @@ export function prepareConfigRevision(
     modifiers,
     mediaQueries,
     resolveCondition,
-    tokenCategory: getTokenCategoryForProperty,
+    tokenCategory,
     expandSafeArea: expandSafeAreaValue,
     safeAreaVariable: resolveSafeAreaVariable,
     parseFlatValue,
@@ -259,11 +271,10 @@ export function prepareConfigRevision(
           ) {
             return authored
           }
-          let property = config.shorthands[authored] || authored
-          if (property === 'x' || property === 'y') property = 'translate'
-          else if (property === 'scaleX' || property === 'scaleY') property = 'scale'
-          else if (propertyKind(property) === 5) property = 'transform'
-          return property.replace(/[A-Z]/g, '-$&').toLowerCase()
+          // the drivers file entries under the same names through
+          // canonicalTransitionProperty, so a raw css string and a resolved
+          // transition cannot disagree about what `y` or `rotateX` targets
+          return canonicalTransitionProperty(config.shorthands[authored] || authored)
         }
       )
       if (normalizedTransitions.size > 2048) normalizedTransitions.clear()
@@ -272,7 +283,11 @@ export function prepareConfigRevision(
     },
     embeddedTokens: (raw, resolve) =>
       raw.replace(
-        /\/\*[\s\S]*?\*\/|(["'])(?:\\.|(?!\1)[^\\])*\1|[$A-Za-z_][\w.$-]*(?:\/\d+)?/g,
+        // the alpha suffix matches decimals too, so `$color/0.7` is handed to
+        // resolve() whole and rejected as one token. matching only `\d+` split it
+        // into `$color/0` plus a stray `.7`, which left the `.7` glued onto the
+        // resolved value.
+        /\/\*[\s\S]*?\*\/|(["'])(?:\\.|(?!\1)[^\\])*\1|[$A-Za-z_][\w.$-]*(?:\/\d*\.?\d+)?/g,
         (word, quote, offset) => {
           const before = raw.charCodeAt(offset - 1)
           return quote ||
@@ -332,7 +347,7 @@ export function getConfigRevisionSnapshot(
     for (const key of Object.keys(themes[name] || {})) themeKeys.add(key)
   }
   sections.themeVariables.push(`v:${[...themeKeys].sort().join(',')}`)
-  for (const category of ['color', 'space', 'size', 'radius', 'zIndex']) {
+  for (const category of Object.keys(tokensParsed).sort()) {
     const tokens = tokensParsed[category]
     sections.tokens.push(
       `${category}:${tokens ? Object.keys(tokens).sort().join(',') : ''}`

package/src/helpers/insertStyleRule.tsx

@@ -1,6 +1,7 @@
 import { StyleObjectIdentifier, StyleObjectRules } from '@tamagui/helpers'
 import { createVariable } from '../createVariable'
 import { formatDiagnostic } from './formatDiagnostic'
+import { setAuthoredThemeScheme, themeSchemeSelectorPrefix } from './themes'
 import type {
   DedupedTheme,
   DedupedThemes,
@@ -10,7 +11,7 @@ import type {
 } from '../types'
 
 // only cache tamagui styles
-// TODO merge totalSelectorsInserted and allSelectors?
+// kept separate: allSelectors stores rule text for inspection, totalSelectorsInserted counts stylesheet insertions
 const scannedCache = new WeakMap<CSSStyleSheet, string>()
 const totalSelectorsInserted = new Map<string, number>()
 const allSelectors: Record<string, string> = {}
@@ -25,7 +26,7 @@ let sortedRules: string[] = []
 let sortedRulesStale = true
 
 export const getAllRules = () => {
-  if (!process.env.TAMAGUI_DID_OUTPUT_CSS) {
+  if (process.env.TAMAGUI_RUNTIME !== 'island') {
     if (sortedRulesStale) {
       // Sort by identifier to ensure deterministic CSS output order
       const sortedKeys = Object.keys(allRules).sort()
@@ -58,10 +59,9 @@ export function scanAllSheets(
   collectThemes = false,
   tokens?: TokensParsed
 ): DedupedThemes | undefined {
-  // with a proven CSS artifact the style dedup scan is dead weight, but theme
-  // collection must still run: a client config passing empty themes hydrates
-  // its theme values from that same CSS artifact
-  if (!process.env.TAMAGUI_DID_OUTPUT_CSS || collectThemes) {
+  // runtime components still emit styles alongside the config CSS artifact.
+  // an island only scans when rebuilding empty client themes from that artifact
+  if (process.env.TAMAGUI_RUNTIME !== 'island' || collectThemes) {
     if (process.env.NODE_ENV === 'test') return
     if (process.env.TAMAGUI_TARGET !== 'web') return
     if (typeof document === 'undefined') return
@@ -267,6 +267,12 @@ function addThemesFromCSS(cssStyleRule: CSSStyleRule, tokens?: TokensParsed) {
 
   // loop selectors and build deduped
   for (const selector of selectors) {
+    const marker = selector.trim()
+    if (marker.startsWith(themeSchemeSelectorPrefix)) {
+      const scheme = marker.slice(themeSchemeSelectorPrefix.length)
+      if (scheme === 'light' || scheme === 'dark') setAuthoredThemeScheme(values, scheme)
+      continue
+    }
     const themeName = getThemeNameFromSelector(selector)
     if (themeName) names.add(themeName)
   }
@@ -341,7 +347,7 @@ export function stopAccumulatingRules() {
 }
 
 export function updateRules(identifier: string, rules: string[]) {
-  if (!process.env.TAMAGUI_DID_OUTPUT_CSS && trackAllRules) {
+  if (process.env.TAMAGUI_RUNTIME !== 'island' && trackAllRules) {
     allRules[identifier] = rules.join(' ')
     allRuleSets[identifier] = rules
     sortedRulesStale = true
@@ -355,7 +361,7 @@ export function setNonce(_: string) {
 }
 
 export function insertStyleRules(rulesToInsert: RulesToInsert) {
-  if (process.env.TAMAGUI_DID_OUTPUT_CSS || process.env.TAMAGUI_TARGET !== 'web') {
+  if (process.env.TAMAGUI_RUNTIME === 'island' || process.env.TAMAGUI_TARGET !== 'web') {
     return
   }
 

package/src/helpers/mainThreadPressEvents.native.ts

@@ -1,31 +1,7 @@
-/**
- * Fallback press handling when RNGH is not available.
- *
- * Implements the responder-based press detection that usePressability provides,
- * without the deep RN internal import. Supports pressIn/pressOut delays,
- * long press, cancellation, and min press duration.
- */
-
 import { unstable_hasExternalPressOwnership } from '@tamagui/native'
 import { useRef } from 'react'
-
-type PressState =
-  | 'idle'
-  | 'pressing' // responder granted, waiting for delay
-  | 'active' // pressIn fired
-  | 'longPressed' // long press detected
-
-interface PressRef {
-  state: PressState
-  pressInTimer: ReturnType<typeof setTimeout> | null
-  pressOutTimer: ReturnType<typeof setTimeout> | null
-  longPressTimer: ReturnType<typeof setTimeout> | null
-  activateTime: number
-  blockedByExternalOwnership: boolean
-}
-
-const DEFAULT_LONG_PRESS_DELAY = 500
-const DEFAULT_MIN_PRESS_DURATION = 130
+import type { GestureResponderEvent } from 'react-native'
+import type { usePressability as usePressabilityType } from 'react-native'
 
 export function useMainThreadPressEvents(
   events: any,
@@ -33,145 +9,93 @@ export function useMainThreadPressEvents(
   enabled = true,
   debugName?: string | null
 ) {
-  const ref = useRef<PressRef>(null as any)
-  if (!ref.current) {
-    ref.current = {
-      state: 'idle',
-      pressInTimer: null,
-      pressOutTimer: null,
-      longPressTimer: null,
-      activateTime: 0,
-      blockedByExternalOwnership: false,
-    }
+  // static config evaluation does not render; load native code at render time.
+  const usePressability: typeof usePressabilityType =
+    require('react-native').usePressability
+  const initialized = useRef(false)
+  const ownsResponder = useRef(false)
+  const pressActive = useRef(false)
+  const active = enabled && Boolean(events)
+  if (active) initialized.current = true
+
+  function endPress(e: GestureResponderEvent) {
+    if (!pressActive.current) return
+    pressActive.current = false
+    events?.onPressOut?.(e)
   }
 
-  if (!enabled || !events) return
-
-  const delayPressIn = Math.max(0, events.delayPressIn ?? 0)
-  const delayPressOut = Math.max(0, events.delayPressOut ?? 0)
-  const delayLongPress = Math.max(0, events.delayLongPress ?? DEFAULT_LONG_PRESS_DELAY)
-  const minPressDuration = Math.max(
-    0,
-    events.minPressDuration ?? DEFAULT_MIN_PRESS_DURATION
+  // react native owns press geometry, timing and cancellation; initialize only
+  // for pressable components and remove callbacks when the responder path stops.
+  const handlers = usePressability(
+    initialized.current
+      ? {
+          ...(active ? events : {}),
+          disabled: !active || events?.disabled,
+          android_disableSound: true,
+          onPressIn: active
+            ? (e: GestureResponderEvent) => {
+                endPress(e)
+                pressActive.current = true
+                events.onPressIn?.(e)
+              }
+            : undefined,
+          onPressOut: active ? endPress : undefined,
+          hitSlop: viewProps.hitSlop,
+          pressRectOffset: viewProps.pressRetentionOffset,
+        }
+      : null
   )
+  if (!active || !handlers) return
 
-  function activate(e: any) {
-    ref.current.state = 'active'
-    ref.current.activateTime = Date.now()
-    events.onPressIn?.(e)
-  }
-
-  function deactivate(e: any) {
-    const pressDuration = Date.now() - ref.current.activateTime
-    const remaining = Math.max(minPressDuration - pressDuration, delayPressOut)
-
-    if (remaining > 0) {
-      ref.current.pressOutTimer = setTimeout(() => {
-        events.onPressOut?.(e)
-      }, remaining)
-    } else {
-      events.onPressOut?.(e)
-    }
-  }
-
-  function cleanup() {
-    if (ref.current.pressInTimer) clearTimeout(ref.current.pressInTimer)
-    if (ref.current.pressOutTimer) clearTimeout(ref.current.pressOutTimer)
-    if (ref.current.longPressTimer) clearTimeout(ref.current.longPressTimer)
-    ref.current.pressInTimer = null
-    ref.current.pressOutTimer = null
-    ref.current.longPressTimer = null
-  }
-
-  // user-supplied responder props (the View's raw RN gesture API) must keep
-  // working: blindly overwriting them here silently killed any press-hold-drag
-  // gesture built on onResponderMove/onResponderRelease whenever the element
-  // also had hover/press events. compose instead — user handler first, then
-  // the press synthesis.
   const userStartShouldSet = viewProps.onStartShouldSetResponder
   const userGrant = viewProps.onResponderGrant
   const userRelease = viewProps.onResponderRelease
   const userTerminate = viewProps.onResponderTerminate
   const userTerminationRequest = viewProps.onResponderTerminationRequest
   const userMove = viewProps.onResponderMove
+  const userClick = viewProps.onClick
 
-  viewProps.onStartShouldSetResponder = (e: any) => {
-    if (userStartShouldSet?.(e)) return true
-    return !events.disabled && !unstable_hasExternalPressOwnership()
-  }
-
-  viewProps.onResponderGrant = (e: any) => {
-    cleanup()
-
-    if (unstable_hasExternalPressOwnership()) {
-      ref.current.state = 'idle'
-      ref.current.blockedByExternalOwnership = true
-      return
-    }
+  viewProps.onStartShouldSetResponder = (e: GestureResponderEvent) =>
+    userStartShouldSet?.(e) ||
+    (!unstable_hasExternalPressOwnership() && handlers.onStartShouldSetResponder())
 
+  viewProps.onResponderGrant = (e: GestureResponderEvent) => {
+    endPress(e)
+    if (unstable_hasExternalPressOwnership()) return
     userGrant?.(e)
-    ref.current.blockedByExternalOwnership = false
-    ref.current.state = 'pressing'
-
-    if (delayPressIn > 0) {
-      ref.current.pressInTimer = setTimeout(() => activate(e), delayPressIn)
-    } else {
-      activate(e)
-    }
-
-    if (events.onLongPress) {
-      ref.current.longPressTimer = setTimeout(() => {
-        if (ref.current.state === 'active') {
-          ref.current.state = 'longPressed'
-          events.onLongPress?.(e)
-        }
-      }, delayLongPress + delayPressIn)
-    }
+    ownsResponder.current = true
+    return handlers.onResponderGrant(e)
   }
 
-  viewProps.onResponderRelease = (e: any) => {
-    if (ref.current.blockedByExternalOwnership || unstable_hasExternalPressOwnership()) {
-      cleanup()
-      ref.current.blockedByExternalOwnership = false
-      ref.current.state = 'idle'
+  viewProps.onResponderRelease = (e: GestureResponderEvent) => {
+    if (!ownsResponder.current) return
+    ownsResponder.current = false
+    if (unstable_hasExternalPressOwnership()) {
+      handlers.onResponderTerminate(e)
+      endPress(e)
       return
     }
-
     userRelease?.(e)
-    const wasLongPressed = ref.current.state === 'longPressed'
-    cleanup()
-
-    // if pressIn hasn't fired yet (was in delay), fire it now then immediately deactivate
-    if (ref.current.state === 'pressing') {
-      activate(e)
-    }
-
-    if (!wasLongPressed) {
-      events.onPress?.(e)
-    }
-
-    deactivate(e)
-    ref.current.state = 'idle'
-    ref.current.blockedByExternalOwnership = false
+    handlers.onResponderRelease(e)
   }
 
-  viewProps.onResponderTerminate = (e: any) => {
+  viewProps.onResponderTerminate = (e: GestureResponderEvent) => {
     userTerminate?.(e)
-    cleanup()
-    if (ref.current.state === 'active' || ref.current.state === 'longPressed') {
-      deactivate(e)
-    }
-    ref.current.state = 'idle'
-    ref.current.blockedByExternalOwnership = false
+    if (ownsResponder.current) handlers.onResponderTerminate(e)
+    endPress(e)
+    ownsResponder.current = false
   }
 
-  viewProps.onResponderTerminationRequest = (e: any) => {
-    if (userTerminationRequest) return userTerminationRequest(e)
-    return events.cancelable !== false
-  }
+  viewProps.onResponderTerminationRequest = (e: GestureResponderEvent) =>
+    userTerminationRequest?.(e) ?? handlers.onResponderTerminationRequest()
 
-  viewProps.onResponderMove = (e: any) => {
+  viewProps.onResponderMove = (e: GestureResponderEvent) => {
     userMove?.(e)
-    events.onPressMove?.(e)
+    if (ownsResponder.current) handlers.onResponderMove(e)
+  }
+
+  viewProps.onClick = (e: GestureResponderEvent) => {
+    userClick?.(e)
+    if (!unstable_hasExternalPressOwnership()) handlers.onClick(e)
   }
 }

package/src/helpers/mergeProps.ts

@@ -1,49 +1,31 @@
-/**
- * Preserves prop ordering, so that the order most closely matches the last spread objects
- * Useful for having { ...defaultProps, ...props } that ensure props ordering is always kept
- *
- * Honestly this is somehwat backwards logically from Object.assign, reason was that we typically
- * are merging defaultProps, givenProps, but we started using it elsewhere and now its a bit confusing
- * Should look into refactoring this to match common usage
- *
- *    Given:
- *      mergeProps({ a: 1, b: 2 }, { b: 1, a: 2 })
- *    The final key order will be:
- *      b, a
- *
- */
-
 export type GenericProps = Record<string, any>
 
-export const mergeProps = (defaultProps: object, props: object) => {
-  const out: GenericProps = {}
-
-  // in general objects keys are sorted by order of insertion
-  // we merge "defaultProps" first as they should come first
-  // (so Object.keys(finalProps) will list [...defaultPropKeys] first)
-  // but we ignore any keys from props, and merge it after, that way
-  // final order is [...defaultPropKeys, ...propKeys]
-
-  // ⚠️ keep in sync with mergeComponentProps logic
-
-  for (const key in defaultProps) {
-    if (key in props) continue
-    out[key] = defaultProps[key]
-  }
-
-  for (const key in props) {
-    out[key] = props[key]
+// layers merge in order (defaults, styled context, the caller's props), so key
+// order in the result follows that order. one rule for every layer: an
+// undefined value never replaces what a lower layer set (React defaultProps
+// semantics); it lands only when nothing set the key, which keeps `key in
+// props` true for a caller who passed the key.
+const mergeLayer = (out: GenericProps, layer: object) => {
+  for (const key in layer) {
+    const value = layer[key]
+    if (value === undefined && key in out) continue
+    out[key] = value
   }
+}
 
+export const mergeProps = (defaultProps: object, props: object) => {
+  const out: GenericProps = {}
+  mergeLayer(out, defaultProps)
+  mergeLayer(out, props)
   return out
 }
 
-// merge props but also handles defaultProps + styledContext
+// same merge with a styled-context layer between defaults and props. also
+// reports which context keys the caller's props overrode, in prop order, so
+// the component can stop publishing those to its own descendants.
 export const mergeComponentProps = (
-  // this is "a" in mergeProps
   defaultProps: object | null | undefined,
-  contextProps: object | undefined,
-  // this is "b" in mergeProps
+  contextProps: object | null | undefined,
   props: object
 ) => {
   let overriddenContext: GenericProps | null = null
@@ -52,38 +34,23 @@ export const mergeComponentProps = (
     return [props, overriddenContext] as const
   }
 
-  if (defaultProps && !contextProps) {
-    return [mergeProps(defaultProps, props), overriddenContext] as const
-  }
-
-  // the only unique case is contextProps, we need to track overrides and do something a bit tricky
-  // since we respect prop order for styles, we want to preserve the object key order in overriddenContext
-
   const out: GenericProps = {}
-
-  // ⚠️ keep in sync with mergeProps logic
-  // same logic as mergeProps but tracking overrides!
-
-  for (const key in defaultProps) {
-    if (key in props) continue
-    out[key] = defaultProps[key]
-  }
-
-  // styled context props go after defaultProps but before props
-  for (const key in contextProps) {
-    if (key in props) continue
-    const contextValue = contextProps[key]
-    // don't merge undefined context values to preserve inheritance
-    if (contextValue !== undefined) {
-      out[key] = contextValue
+  if (defaultProps) mergeLayer(out, defaultProps)
+  if (contextProps) {
+    // undefined context defaults declare a key without overriding styled values.
+    for (const key in contextProps) {
+      const value = contextProps[key]
+      if (value !== undefined) out[key] = value
     }
   }
 
   for (const key in props) {
-    out[key] = props[key]
+    const value = props[key]
+    if (value === undefined && key in out) continue
+    out[key] = value
     if (contextProps && key in contextProps) {
       overriddenContext ||= {}
-      overriddenContext[key] = props[key]
+      overriddenContext[key] = value
     }
   }