@hanzogui/web 7.3.2 → 8.0.0

package/src/helpers/platformResolveValue.native.ts

@@ -2,7 +2,10 @@ import type { GetStyleState, SplitStyleProps } from '../types'
 import { getTokenForKey } from './getTokenForKey'
 import { parseNativeStyle } from './parseNativeStyle'
 
-const tokenPattern = /(\$[\w.-]+)/g
+// includes the optional `/NN` opacity-modifier suffix ($color9/50) so
+// getTokenForKey receives it and can apply the alpha — without it the token
+// resolves but the bare `/50` is left behind in the parsed gradient string
+const tokenPattern = /(\$[\w.-]+(?:\/[\d.]+)?)/g
 
 // keys that need native object parsing (DynamicColorIOS support)
 const nativeParseKeys: Record<string, boolean> = {

package/src/helpers/platformResolveValue.ts

@@ -1,7 +1,11 @@
 import type { GetStyleState, SplitStyleProps } from '../types'
 import { getTokenForKey } from './getTokenForKey'
 
-const tokenPattern = /(\$[\w.-]+)/g
+// includes the optional `/NN` opacity-modifier suffix ($color9/50) so
+// getTokenForKey receives it and can apply the alpha — without it the token
+// resolves but the bare `/50` is left behind in the CSS string, which makes
+// the whole declaration invalid
+const tokenPattern = /(\$[\w.-]+(?:\/[\d.]+)?)/g
 
 /**
  * web: resolves embedded $tokens in compound CSS strings via simple regex replacement.

package/src/helpers/pointerEvents.native.ts

@@ -25,13 +25,20 @@ export function usePointerEvents(props: any, viewProps: any) {
     onPointerEnter ||
     onPointerLeave
 
-  // track if pointer is currently inside bounds (for enter/leave)
-  const isInsideRef = useRef(false)
-  const layoutRef = useRef({ width: 0, height: 0 })
-  // track if pointer is captured (for move events outside bounds)
-  const isCapturedRef = useRef(false)
+  // single ref-bag (was three separate useRef slots) — one hook slot per
+  // component instead of three. isInside = pointer within bounds (enter/leave),
+  // layout = measured bounds, isCaptured = setPointerCapture state for moves.
+  const ref = useRef<{
+    isInside: boolean
+    layout: { width: number; height: number }
+    isCaptured: boolean
+  } | null>(null)
+  if (!ref.current) {
+    ref.current = { isInside: false, layout: { width: 0, height: 0 }, isCaptured: false }
+  }
 
   if (!hasPointerEvents) return
+  const bag = ref.current
 
   // create normalized event with setPointerCapture support
   const createNormalizedEvent = (e: any) => {
@@ -49,10 +56,10 @@ export function usePointerEvents(props: any, viewProps: any) {
       nativeEvent: touch,
       target: {
         setPointerCapture: (_pointerId: number) => {
-          isCapturedRef.current = true
+          bag.isCaptured = true
         },
         releasePointerCapture: (_pointerId: number) => {
-          isCapturedRef.current = false
+          bag.isCaptured = false
         },
       },
     }
@@ -69,7 +76,7 @@ export function usePointerEvents(props: any, viewProps: any) {
   // pointer up
   if (onPointerUp) {
     viewProps.onTouchEnd = composeEventHandlers(viewProps.onTouchEnd, (e: any) => {
-      isCapturedRef.current = false // auto-release on up
+      bag.isCaptured = false // auto-release on up
       onPointerUp(createNormalizedEvent(e))
     })
   }
@@ -78,12 +85,12 @@ export function usePointerEvents(props: any, viewProps: any) {
   if (onPointerMove) {
     viewProps.onTouchMove = composeEventHandlers(viewProps.onTouchMove, (e: any) => {
       const { locationX, locationY } = e.nativeEvent
-      const { width, height } = layoutRef.current
+      const { width, height } = bag.layout
       const isInBounds =
         locationX >= 0 && locationX <= width && locationY >= 0 && locationY <= height
 
       // fire if captured OR in bounds (matches web behavior)
-      if (isCapturedRef.current || isInBounds) {
+      if (bag.isCaptured || isInBounds) {
         onPointerMove(createNormalizedEvent(e))
       }
     })
@@ -92,7 +99,7 @@ export function usePointerEvents(props: any, viewProps: any) {
   // pointer cancel
   if (onPointerCancel) {
     viewProps.onTouchCancel = composeEventHandlers(viewProps.onTouchCancel, (e: any) => {
-      isCapturedRef.current = false
+      bag.isCaptured = false
       onPointerCancel(createNormalizedEvent(e))
     })
   }
@@ -101,7 +108,7 @@ export function usePointerEvents(props: any, viewProps: any) {
   if (onPointerEnter || onPointerLeave || onPointerMove) {
     // track layout for bounds checking
     viewProps.onLayout = composeEventHandlers(viewProps.onLayout, (e: any) => {
-      layoutRef.current = {
+      bag.layout = {
         width: e.nativeEvent.layout.width,
         height: e.nativeEvent.layout.height,
       }
@@ -112,9 +119,9 @@ export function usePointerEvents(props: any, viewProps: any) {
   if (onPointerEnter) {
     viewProps.onTouchStart = composeEventHandlers(viewProps.onTouchStart, (e: any) => {
       const { locationX, locationY } = e.nativeEvent
-      const { width, height } = layoutRef.current
+      const { width, height } = bag.layout
       if (locationX >= 0 && locationX <= width && locationY >= 0 && locationY <= height) {
-        isInsideRef.current = true
+        bag.isInside = true
         onPointerEnter(createNormalizedEvent(e))
       }
     })
@@ -124,18 +131,18 @@ export function usePointerEvents(props: any, viewProps: any) {
   if (onPointerLeave) {
     viewProps.onTouchMove = composeEventHandlers(viewProps.onTouchMove, (e: any) => {
       const { locationX, locationY } = e.nativeEvent
-      const { width, height } = layoutRef.current
+      const { width, height } = bag.layout
       const isInside =
         locationX >= 0 && locationX <= width && locationY >= 0 && locationY <= height
-      if (isInsideRef.current && !isInside) {
-        isInsideRef.current = false
+      if (bag.isInside && !isInside) {
+        bag.isInside = false
         onPointerLeave(createNormalizedEvent(e))
       }
     })
 
     viewProps.onTouchEnd = composeEventHandlers(viewProps.onTouchEnd, (e: any) => {
-      if (isInsideRef.current) {
-        isInsideRef.current = false
+      if (bag.isInside) {
+        bag.isInside = false
         onPointerLeave(createNormalizedEvent(e))
       }
     })

package/src/helpers/propMapper.ts

@@ -24,6 +24,7 @@ import { pseudoDescriptors } from './pseudoDescriptors'
 import { resolveCompoundTokens } from './resolveCompoundTokens'
 import { isRemValue, resolveRem } from './resolveRem'
 import { skipProps } from './skipProps'
+import { styleOriginalValues } from './styleOriginalValues'
 
 export { getTokenForKey } from './getTokenForKey'
 
@@ -42,11 +43,36 @@ export const propMapper: PropMapper = (key, value, styleState, disabled, map) =>
   const { conf, styleProps, staticConfig } = styleState
   const { variants } = staticConfig
 
+  // "unset" is a CSS-wide keyword: valid CSS on web, but React Native
+  // style props reject it (e.g. aspectRatio throws "must be a number, a
+  // ratio string or `auto`"). On native, clear anything an earlier prop or
+  // styled default already merged for this key — matching web, where unset
+  // resets toward initial — then drop the value so RN never sees it.
+  if (process.env.GUI_TARGET === 'native' && value === 'unset') {
+    const expandedKey =
+      (!styleProps.disableExpandShorthands && conf.shorthands[key]) || key
+    const expanded = styleProps.noExpand
+      ? null
+      : expandStyle(expandedKey, value, conf.settings.styleCompat || 'web')
+    if (styleState.style) {
+      if (expanded) {
+        for (const [nkey] of expanded) {
+          delete styleState.style[nkey]
+        }
+      } else {
+        delete styleState.style[expandedKey]
+      }
+    }
+    return
+  }
+
   if (!styleProps.noExpand) {
     if (variants && key in variants) {
       const variantValue = resolveVariants(key, value, styleProps, styleState, '')
       if (variantValue) {
-        variantValue.forEach(([key, value]) => map(key, value))
+        variantValue.forEach(([key, value, originalValue]) => {
+          map(key, value, originalValue)
+        })
         return
       }
     }
@@ -105,13 +131,15 @@ export const propMapper: PropMapper = (key, value, styleState, disabled, map) =>
       styleState.fontFamily = fontToken
     }
 
-    const expanded = styleProps.noExpand ? null : expandStyle(key, value)
+    const expanded = styleProps.noExpand
+      ? null
+      : expandStyle(key, value, conf.settings.styleCompat || 'web')
 
     if (expanded) {
       const max = expanded.length
       for (let i = 0; i < max; i++) {
-        const [nkey, nvalue] = expanded[i]
-        map(nkey, nvalue, originalValue)
+        const [nkey, nvalue, noriginalValue] = expanded[i]
+        map(nkey, nvalue, noriginalValue ?? originalValue)
       }
     } else {
       map(key, value, originalValue)
@@ -205,13 +233,14 @@ const resolveVariants: StyleResolver = (
       console.info(`   expanding styles from `, variantValue, `to`, expanded)
     }
     const next = Object.entries(expanded)
+    const originalValues = styleOriginalValues.get(expanded)
 
     // store any changed font family (only support variables for now)
     if (fontFamilyResult && fontFamilyResult[0] === '$') {
       setLastFontFamilyToken(getVariableValue(fontFamilyResult))
     }
 
-    return next
+    return next.map(([key, value]) => [key, value, originalValues?.[key]])
   }
 }
 
@@ -249,6 +278,7 @@ const resolveTokensAndVariants: StyleResolver<object> = (
   const { conf, staticConfig, debug, theme } = styleState
   const { variants } = staticConfig
   const res = {}
+  let originalValues: Record<string, any> | undefined
 
   if (process.env.NODE_ENV === 'development' && debug === 'verbose') {
     console.info(`   - resolveTokensAndVariants`, key, value)
@@ -262,6 +292,9 @@ const resolveTokensAndVariants: StyleResolver<object> = (
       continue
     }
 
+    originalValues ||= {}
+    originalValues[subKey] = val
+
     // Track context overrides for any key that's in context props (issues #3670, #3676)
     // Store the ORIGINAL token value (like '$8') before resolution so that
     // children's functional variants can look up token values
@@ -291,13 +324,24 @@ const resolveTokensAndVariants: StyleResolver<object> = (
 
           // apply, merging sub-styles
           if (variantOut) {
-            for (const [key, val] of variantOut) {
+            for (const [key, val, originalVal] of variantOut) {
               if (val == null) continue
               if (key in pseudoDescriptors) {
                 res[key] ??= {}
                 Object.assign(res[key], val)
+                const subOriginalValues = styleOriginalValues.get(val)
+                if (subOriginalValues) {
+                  styleOriginalValues.set(res[key], {
+                    ...styleOriginalValues.get(res[key]),
+                    ...subOriginalValues,
+                  })
+                }
               } else {
                 res[key] = val
+                if (originalVal !== undefined) {
+                  originalValues ||= {}
+                  originalValues[key] = originalVal
+                }
               }
             }
           }
@@ -335,6 +379,13 @@ const resolveTokensAndVariants: StyleResolver<object> = (
       // sub-objects: media queries, pseudos, shadowOffset
       res[subKey] ??= {}
       Object.assign(res[subKey], subObject)
+      const subOriginalValues = styleOriginalValues.get(subObject)
+      if (subOriginalValues) {
+        styleOriginalValues.set(res[subKey], {
+          ...styleOriginalValues.get(res[subKey]),
+          ...subOriginalValues,
+        })
+      }
     } else {
       // nullish values cant be tokens, need no extra parsing
       res[subKey] = val
@@ -354,6 +405,10 @@ const resolveTokensAndVariants: StyleResolver<object> = (
     }
   }
 
+  if (originalValues) {
+    styleOriginalValues.set(res, originalValues)
+  }
+
   return res
 }
 

package/src/helpers/resolveSafeArea.native.ts

@@ -10,7 +10,7 @@ export function resolveSafeAreaValue(value: string): number | undefined {
   if (!edge) return undefined
 
   const g = globalThis as any
-  const state = g.__gui_native_safe_area_state__
+  const state = g.__hanzogui_native_safe_area_state__
   if (state?.enabled && state.initialMetrics) {
     return state.initialMetrics.insets[edge]
   }

package/src/helpers/styleOriginalValues.ts

@@ -0,0 +1,2 @@
+// stores raw style values before token and unit normalization
+export const styleOriginalValues = new WeakMap<object, Record<string, any>>()

package/src/helpers/styleProvenance.ts

@@ -0,0 +1,49 @@
+// developer-tools contract: exact token provenance for a component's final
+// winning native style object. hanzogui only records it in development when
+// GUI_ENABLE_STYLE_TOKEN_PROVENANCE=1.
+//
+// this is a pure inspection side channel. it records, per resolved style key,
+// which token produced the value and the full theme name that resolved it
+// (e.g. { backgroundColor: { token: '$background', theme: 'light_accent' } }).
+// a literal value produces NO entry, which is how a literal that happens to
+// equal a token value stays distinguishable from the token.
+//
+// the data is attached as a NON-ENUMERABLE, symbol-keyed property so it never
+// changes the style object's enumerable keys or the React Native output, and
+// hanzogui's own rendering never reads it back. this mirrors the
+// `styleOriginalValues` WeakMap precedent (metadata beside the style, keyed off
+// to the side), but uses an own-property so a cross-package consumer can read it
+// without importing hanzogui.
+//
+// consumers read the property by the SAME registered symbol —
+// `Symbol.for(STYLE_TOKEN_PROVENANCE_KEY)` — which shares one global registry
+// per realm, so no shared module import is required.
+
+export const STYLE_TOKEN_PROVENANCE_KEY = 'hanzogui.styleTokenProvenance'
+
+const provenanceSymbol = /* @__PURE__ */ Symbol.for(STYLE_TOKEN_PROVENANCE_KEY)
+
+export type StyleTokenBinding = {
+  /** original token string before resolution, e.g. '$background' or '$color9' */
+  token: string
+  /** full resolved theme name that produced the value, e.g. 'light_accent' */
+  theme: string
+}
+
+export type StyleTokenProvenance = Record<string, StyleTokenBinding>
+
+export function setStyleTokenProvenance(style: object, provenance: StyleTokenProvenance) {
+  Object.defineProperty(style, provenanceSymbol, {
+    value: provenance,
+    enumerable: false,
+    configurable: true,
+    writable: true,
+  })
+}
+
+export function getStyleTokenProvenance(
+  style: object | null | undefined
+): StyleTokenProvenance | undefined {
+  if (!style) return undefined
+  return (style as Record<symbol, StyleTokenProvenance>)[provenanceSymbol]
+}

package/src/helpers/wrapStyleTags.tsx

@@ -1,31 +1,74 @@
+import type { ReactNode } from 'react'
 import { StyleObjectIdentifier, StyleObjectRules } from '@hanzogui/helpers'
 import type { StyleObject } from '../types'
 
 // turns out this is pretty slow, creating a bunch of extra tags...
 
+const styleTagCache = new Map<
+  string,
+  {
+    element: ReactNode
+    len: number
+    first: string | undefined
+    last: string | undefined
+  }
+>()
+
+let clearStyleTagCacheQueued = false
+
+function queueStyleTagCacheClear() {
+  if (clearStyleTagCacheQueued) return
+
+  clearStyleTagCacheQueued = true
+  queueMicrotask(() => {
+    styleTagCache.clear()
+    clearStyleTagCacheQueued = false
+  })
+}
+
+function getCachedStyleTag(styleObject: StyleObject) {
+  const identifier = styleObject[StyleObjectIdentifier]
+  const rules = styleObject[StyleObjectRules]
+  const cached = styleTagCache.get(identifier)
+
+  if (
+    cached &&
+    cached.len === rules.length &&
+    cached.first === rules[0] &&
+    cached.last === rules[rules.length - 1]
+  ) {
+    return cached.element
+  }
+
+  const element = (
+    <style
+      key={identifier}
+      // @ts-ignore
+      href={`t_${identifier}`}
+      // @ts-ignore
+      precedence="default"
+      // we remove after first render in favor of inserting to a global stylesheet (faster)
+      suppressHydrationWarning
+    >
+      {rules.join('\n')}
+    </style>
+  )
+
+  styleTagCache.set(identifier, {
+    element,
+    len: rules.length,
+    first: rules[0],
+    last: rules[rules.length - 1],
+  })
+
+  return element
+}
+
 export function getStyleTags(styles: StyleObject[]) {
   if (process.env.GUI_TARGET !== 'native') {
     if (styles.length) {
-      return (
-        <>
-          {styles.map((styleObject) => {
-            const identifier = styleObject[StyleObjectIdentifier]
-            return (
-              <style
-                key={identifier}
-                // @ts-ignore
-                href={`t_${identifier}`}
-                // @ts-ignore
-                precedence="default"
-                // we remove after first render in favor of inserting to a global stylesheet (faster)
-                suppressHydrationWarning
-              >
-                {styleObject[StyleObjectRules].join('\n')}
-              </style>
-            )
-          })}
-        </>
-      )
+      queueStyleTagCacheClear()
+      return <>{styles.map(getCachedStyleTag)}</>
     }
   }
 }

package/src/hooks/getThemeProxied.ts

@@ -1,4 +1,4 @@
-import { isIos } from '@hanzogui/constants'
+import { supportsDynamicColorIOS } from '@hanzogui/constants'
 import type { MutableRefObject } from 'react'
 import { getConfig, getSetting } from '../config'
 import { getVariable } from '../createVariable'
@@ -113,7 +113,7 @@ export function getThemeProxied(
         ...value,
         get val() {
           // when they touch the actual value we only track it if its a variable (web), its ignored!
-          if (!globalThis.guiAvoidTracking) {
+          if (!globalThis.hanzoguiAvoidTracking) {
             // always track .val - not scheme optimized since they're getting raw value
             track(key, false)
           }
@@ -126,23 +126,29 @@ export function getThemeProxied(
           const { name, scheme } = curState
 
           if (process.env.GUI_TARGET === 'native') {
-            // ios can avoid re-rendering for scheme changes (light↔dark) when using DynamicColorIOS
-            // this does NOT work for sub-theme changes (red→blue) or when scheme inverses from parent
+            // 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' &&
-              isIos &&
+              supportsDynamicColorIOS &&
               !curProps.deopt &&
-              !curState.isInverse &&
+              !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} (iOS=${isIos} deopt=${curProps.deopt} isInverse=${curState.isInverse} fastScheme=${fastSchemeChange} rootMatch=${rootMatchesSystem})`
+                `\n   shouldOptimize=${shouldOptimize} (dynamicColorIOS=${supportsDynamicColorIOS} deopt=${curProps.deopt} inverses=${curState.inverses} fastScheme=${fastSchemeChange} rootMatch=${rootMatchesSystem})`
               )
             }
 
@@ -177,7 +183,7 @@ export function getThemeProxied(
             if (process.env.NODE_ENV === 'development' && curProps.debug) {
               console.info(
                 ` 🎨 useTheme().get(${key}) tracking key (not optimizing)`,
-                `\n   platform=${platform} isIOS=${isIos} deopt=${curProps.deopt} fastScheme=${fastSchemeChange}`
+                `\n   platform=${platform} dynamicColorIOS=${supportsDynamicColorIOS} deopt=${curProps.deopt} fastScheme=${fastSchemeChange}`
               )
             }
 

package/src/hooks/useComponentState.ts

@@ -1,5 +1,5 @@
-import { isServer, isWeb } from '@hanzogui/constants'
-import { useCreateShallowSetState } from '@hanzogui/is-equal-shallow'
+import { getPlatformDriver, isServer, isWeb } from '@hanzogui/constants'
+import { mergeIfNotShallowEqual } from '@hanzogui/is-equal-shallow'
 import { useDidFinishSSR, useIsClientOnly } from '@hanzogui/use-did-finish-ssr'
 import { useRef, useState } from 'react'
 import { getSetting } from '../config'
@@ -63,8 +63,22 @@ export const useComponentState = (
     curStateRef.hasAnimated = true
   }
 
+  // a renderer platform driver with native pseudo states (react-native-gpui)
+  // makes ANY component with runtime pseudo styles ride the animation-driver
+  // emitter path — no per-site transition/animation prop required. the flip is
+  // driver-sourced (hover) or event-sourced (press/focus) but either way applies
+  // through the emitter with zero React commits; with no transition declared it
+  // resolves instant (see createComponent's effectiveTransition default).
+  const platformPseudo = Boolean(
+    !isHOC &&
+    useAnimations &&
+    animationDriver?.avoidReRenders &&
+    getPlatformDriver()?.pseudo &&
+    ('hoverStyle' in props || 'pressStyle' in props || 'focusStyle' in props)
+  )
+
   const willBeAnimatedClient = (() => {
-    const next = !!(hasAnimationProp && !isHOC && useAnimations)
+    const next = !!((hasAnimationProp || platformPseudo) && !isHOC && useAnimations)
     return Boolean(next || curStateRef.hasAnimated)
   })()
 
@@ -162,7 +176,44 @@ export const useComponentState = (
 
   const groupName = props.group as any as string | undefined
 
-  const setStateShallow = useCreateShallowSetState(setState, props.debug)
+  // hoisted shallow-set closure: created once per component instance and
+  // reused every render. drops the useCallback hook that useCreateShallowSetState
+  // would otherwise add. setState from useState is stable per instance so we
+  // can safely capture it. debug is read off stateRef at call time.
+  //
+  // important: this lives on `baseSetStateShallow`, not `setStateShallow`.
+  // createComponent's avoidReRenders path overwrites `stateRef.current.setStateShallow`
+  // with an emitter wrapper and captures this base as its real-re-render escape hatch.
+  // if the base shared the `setStateShallow` field, on the 2nd+ render this hook would
+  // read back the wrapper, the wrapper's escape hatch would point at itself, and a real
+  // re-render (e.g. unmounted 'should-enter' -> false) would never reach React, leaving
+  // enter animations stuck at opacity 0.
+  if (!stateRef.current.baseSetStateShallow) {
+    const r = stateRef.current
+    r.baseSetStateShallow = (stateOrGetState: any) => {
+      setState((prev: any) => {
+        const next =
+          typeof stateOrGetState === 'function' ? stateOrGetState(prev) : stateOrGetState
+        const update = mergeIfNotShallowEqual(prev, next)
+        if (process.env.NODE_ENV === 'development') {
+          const dbg = (r as any).__debug
+          if (dbg && update !== prev) {
+            console.groupCollapsed(`setStateShallow CHANGE`, '=>', update)
+            console.info(`previously`, prev)
+            console.trace()
+            console.groupEnd()
+          }
+        }
+        return update
+      })
+    }
+  }
+  if (process.env.NODE_ENV === 'development') {
+    ;(stateRef.current as any).__debug = props.debug
+  }
+  const setStateShallow = stateRef.current.baseSetStateShallow!
+  if (process.env.NODE_ENV === 'development' && globalThis.time)
+    globalThis.time`state-useCreateShallowSetState`
 
   // set enter/exit variants onto our new props object
   if (presenceState && isAnimated && isHydrated && staticConfig.variants) {
@@ -247,6 +298,7 @@ export const useComponentState = (
     outputStyle,
     willBeAnimated,
     willBeAnimatedClient,
+    platformPseudo,
   }
 }