@hanzogui/web 7.3.2 → 8.0.0

package/src/hooks/useThemeState.ts

@@ -1,11 +1,11 @@
-import { isIos } from '@hanzogui/constants'
-import { useIsomorphicLayoutEffect } from '@hanzogui/constants'
+import { supportsDynamicColorIOS, useIsomorphicLayoutEffect } from '@hanzogui/constants'
 import {
   createContext,
-  useCallback,
   useContext,
+  useEffect,
   useId,
-  useSyncExternalStore,
+  useReducer,
+  useRef,
   type MutableRefObject,
 } from 'react'
 import { getConfig, getSetting } from '../config'
@@ -55,11 +55,22 @@ export const getRootThemeState = () => rootThemeState
 // extracts base name without scheme: "light_red_surface1" -> "red_surface1"
 const getThemeBaseName = (name: string) => name.replace(/^(light|dark)_/, '')
 
+// useReducer-based force-update; cheaper than useSyncExternalStore's internal
+// useState+useLayoutEffect+useEffect+useDebugValue chain on Hermes.
+const incReducer = (c: number): number => c + 1
+
 export const useThemeState = (
   props: UseThemeWithStateProps,
   isRoot = false,
   keys: MutableRefObject<Set<string> | null>,
-  schemeKeys?: MutableRefObject<Set<string> | null>
+  schemeKeys?: MutableRefObject<Set<string> | null>,
+  // when true, install the propsKey-watching useIsomorphicLayoutEffect that
+  // schedules descendant updates via listenersByParent[id]. Only <Theme>
+  // providers actually push their themeState.id into ThemeStateContext, so
+  // only they can have descendants subscribed under their id. Leaf styled
+  // components pass false (the default) and save one hook slot per mount.
+  // Stable per call-site (rule of hooks satisfied).
+  cascadeOnChange = false
 ): ThemeState => {
   'use no memo'
 
@@ -87,148 +98,271 @@ Looked for theme${props.name ? ` "${props.name}"` : ''}${props.componentName ? `
     )
   }
 
+  // useId keeps theme-provider ids tied to the React tree. A process-wide
+  // counter can let children observe a provider context id whose matching
+  // states Map entry was never populated in multi-root/native surfaces.
   const id = useId()
-  const subscribe = useCallback(
-    (cb: Function) => {
-      listenersByParent[parentId] = listenersByParent[parentId] || new Set()
-      listenersByParent[parentId].add(id)
-      allListeners.set(id, () => {
-        PendingUpdate.set(id, shouldForce ? 'force' : true)
-        cb()
-      })
-      return () => {
-        allListeners.delete(id)
-        listenersByParent[parentId].delete(id)
-        localStates.delete(id)
-        states.delete(id)
-        PendingUpdate.delete(id)
-      }
-    },
-    [id, parentId]
-  )
-
   const propsKey = getPropsKey(props)
 
-  const getSnapshot = () => {
-    let local = localStates.get(id)
-    const parentState = states.get(parentId)
-
-    // fast path: nothing changed since last snapshot
-    if (local && !PendingUpdate.has(id)) {
-      if (
-        parentState &&
-        (local as any)._parentName === parentState.name &&
-        (local as any)._propsKey === propsKey
-      ) {
-        return local
-      }
-    }
-
-    // check if this is a scheme-only change (light↔dark) where DynamicColorIOS handles it
-    const isSchemeOnlyChange =
-      process.env.GUI_TARGET === 'native' &&
-      isIos &&
-      getSetting('fastSchemeChange') &&
-      local &&
-      parentState &&
-      local.scheme !== parentState.scheme &&
-      getThemeBaseName(local.name) === getThemeBaseName(parentState.name)
-
-    // all tracked keys are scheme-optimized = can skip re-render for scheme changes
-    const keysSize = keys?.current?.size ?? 0
-    const schemeKeysSize = schemeKeys?.current?.size ?? 0
-    const allKeysSchemeOptimized = schemeKeysSize === keysSize && keysSize > 0
-
-    const canSkipForSchemeChange = isSchemeOnlyChange && allKeysSchemeOptimized
-
-    const needsUpdate = props.passThrough
-      ? false
-      : isRoot || props.name === 'light' || props.name === 'dark' || props.name === null
-        ? true
-        : !HasRenderedOnce.get(keys)
-          ? true
-          : canSkipForSchemeChange
-            ? false // skip re-render for scheme-only changes with DynamicColorIOS
-            : keys?.current?.size
-              ? true
-              : props.needsUpdate?.()
-
-    const [rerender, next] = getNextState(
-      local,
+  // stable ref-bag for render inputs and the optional subscription cleanup.
+  // lastSnap caches the last getSnapshot result for the subscription bailout.
+  const ref = useRef<ThemeStateRef>(null as any)
+  if (!ref.current) {
+    ref.current = {
+      id,
+      parentId,
       props,
       propsKey,
       isRoot,
-      id,
-      parentId,
-      needsUpdate,
-      PendingUpdate.get(id)
-    )
+      keys,
+      schemeKeys,
+      renderVersion: 0,
+    }
+  } else {
+    // refresh latest values for the stable closures to read
+    ref.current.props = props
+    ref.current.propsKey = propsKey
+    ref.current.isRoot = isRoot
+    ref.current.keys = keys
+    ref.current.schemeKeys = schemeKeys
+    ref.current.parentId = parentId
+  }
+  ref.current.renderVersion++
+
+  if (process.env.NODE_ENV === 'development' && globalThis.time)
+    globalThis.time`theme-prep-uses`
 
-    PendingUpdate.delete(id)
+  // manual subscription replaces useSyncExternalStore: same granular bailout
+  // (getSnapshot returning the same ref → React doesn't re-render), fewer
+  // React-internal hook slots on Hermes. We don't need tearing prevention
+  // here: theme/media updates are event-driven, not transition-driven, and
+  // useReducer in normal mode already gives same-tick batching.
+  const [, forceUpdate] = useReducer(incReducer, 0)
+  const state = getSnapshotImpl(ref.current)
+  ref.current.lastSnap = state
+
+  useEffect(() => {
+    const r = ref.current
+    const renderVersion = r.renderVersion
+
+    // strict-mode dev double-invokes effects: cleanup runs between the two
+    // invocations with no render in between, so the "unchanged renderVersion
+    // means unmount" check below false-positives and deletes this component's
+    // registered theme state mid-lifecycle. the registry is only re-populated
+    // on this component's next render, so until then children resolve a
+    // missing parent and fall back to the root theme state (isNew: true) —
+    // which flips getThemedChildren to wrap and re-parents/remounts their
+    // hosts, losing focus (keyboard dismiss on first Input tap). per react's
+    // strict-mode contract, setup restores whatever cleanup tore down.
+    if (r.lastSnap && !states.has(r.id)) {
+      states.set(r.id, r.lastSnap)
+      localStates.set(r.id, r.lastSnap)
+    }
 
-    // we always create a new localState for every component
-    // that way we can use it to de-opt and avoid renders granularly
-    // we always return the localState object in each component
-    // the global state (states) should always be up to date with the latest
-    if (!local || rerender) {
-      local = { ...next }
-      localStates.set(id, local)
+    if (r.unsubscribe && r.subscribedParentId !== r.parentId) {
+      cleanupThemeSubscription(r)
     }
 
-    if (process.env.NODE_ENV === 'development' && props.debug === 'verbose') {
-      console.groupCollapsed(` ${id} getSnapshot ${rerender}`, local.name, '>', next.name)
-      console.info({
-        props,
-        propsKey,
-        isRoot,
-        parentId,
-        local,
-        next,
-        needsUpdate,
-        isSchemeOnlyChange,
-        allKeysSchemeOptimized,
-        canSkipForSchemeChange,
-      })
-      console.groupEnd()
+    if (shouldSubscribeToTheme(r, cascadeOnChange)) {
+      if (!r.unsubscribe) {
+        const pid = r.parentId
+        const sid = r.id
+        const cb = () => {
+          const next = getSnapshotImpl(r)
+          if (next !== r.lastSnap) {
+            r.lastSnap = next
+            forceUpdate()
+          }
+        }
+
+        listenersByParent[pid] = listenersByParent[pid] || new Set()
+        listenersByParent[pid].add(sid)
+        allListeners.set(sid, () => {
+          PendingUpdate.set(sid, shouldForce ? 'force' : true)
+          cb()
+        })
+        r.subscribedParentId = pid
+        r.unsubscribe = () => {
+          allListeners.delete(sid)
+          listenersByParent[pid]?.delete(sid)
+          localStates.delete(sid)
+          states.delete(sid)
+          PendingUpdate.delete(sid)
+          r.unsubscribe = undefined
+          r.subscribedParentId = undefined
+        }
+      }
+    } else if (r.unsubscribe) {
+      cleanupThemeSubscription(r)
     }
 
-    if (next !== local) {
-      Object.assign(local, next)
-      local.id = id
+    return () => {
+      // react runs passive cleanup before the next effect as well as on unmount.
+      // a newer render bumps renderVersion before that cleanup, so equality here
+      // means this is the final unmount cleanup.
+      if (r.renderVersion === renderVersion) {
+        cleanupThemeState(r)
+      }
     }
-    ;(local as any)._parentName = parentState?.name
-    ;(local as any)._propsKey = propsKey
-    states.set(id, next)
+  })
 
-    return local
+  if (cascadeOnChange) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useIsomorphicLayoutEffect(() => {
+      if (!HasRenderedOnce.get(keys)) {
+        HasRenderedOnce.set(keys, true)
+        return
+      }
+      if (!propsKey) {
+        if (HadTheme.get(keys)) {
+          // we're removing the last theme, make sure to notify
+          scheduleUpdate(id)
+        }
+        HadTheme.set(keys, false)
+        return
+      }
+      if (process.env.NODE_ENV === 'development' && props.debug === 'verbose') {
+        console.warn(` · useTheme(${id}) scheduleUpdate`, propsKey, states.get(id)?.name)
+      }
+      scheduleUpdate(id)
+      HadTheme.set(keys, true)
+    }, [keys, propsKey])
   }
 
-  if (process.env.NODE_ENV === 'development' && globalThis.time)
-    globalThis.time`theme-prep-uses`
+  return state
+}
 
-  const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+type SnapshotRef = {
+  id: string
+  parentId: string
+  props: UseThemeWithStateProps
+  propsKey: string
+  isRoot: boolean
+  keys: MutableRefObject<Set<string> | null>
+  schemeKeys?: MutableRefObject<Set<string> | null>
+}
 
-  useIsomorphicLayoutEffect(() => {
-    if (!HasRenderedOnce.get(keys)) {
-      HasRenderedOnce.set(keys, true)
-      return
-    }
-    if (!propsKey) {
-      if (HadTheme.get(keys)) {
-        // we're removing the last theme, make sure to notify
-        scheduleUpdate(id)
-      }
-      HadTheme.set(keys, false)
-      return
-    }
-    if (process.env.NODE_ENV === 'development' && props.debug === 'verbose') {
-      console.warn(` · useTheme(${id}) scheduleUpdate`, propsKey, states.get(id)?.name)
+type ThemeStateRef = SnapshotRef & {
+  renderVersion: number
+  unsubscribe?: () => void
+  subscribedParentId?: string
+  lastSnap?: ThemeState
+}
+
+const shouldSubscribeToTheme = (r: ThemeStateRef, cascadeOnChange: boolean): boolean =>
+  r.isRoot ||
+  cascadeOnChange ||
+  hasThemeUpdatingProps(r.props) ||
+  !!r.keys.current?.size ||
+  !!r.props.needsUpdate?.()
+
+function cleanupThemeSubscription(r: ThemeStateRef) {
+  r.unsubscribe?.()
+}
+
+function cleanupThemeState(r: ThemeStateRef) {
+  if (r.unsubscribe) {
+    cleanupThemeSubscription(r)
+  } else {
+    localStates.delete(r.id)
+    states.delete(r.id)
+    PendingUpdate.delete(r.id)
+  }
+}
+
+const getSnapshotImpl = (r: SnapshotRef): ThemeState => {
+  const { id, parentId, props, propsKey, isRoot, keys, schemeKeys } = r
+  let local = localStates.get(id)
+  const parentState = states.get(parentId)
+
+  // fast path: nothing changed since last snapshot
+  if (local && !PendingUpdate.has(id)) {
+    if (
+      parentState &&
+      (local as any)._parentName === parentState.name &&
+      (local as any)._propsKey === propsKey
+    ) {
+      return local
     }
-    scheduleUpdate(id)
-    HadTheme.set(keys, true)
-  }, [keys, propsKey])
+  }
 
-  return state
+  // check if this is a scheme-only change (light↔dark) where DynamicColorIOS handles it
+  const isSchemeOnlyChange =
+    process.env.GUI_TARGET === 'native' &&
+    supportsDynamicColorIOS &&
+    getSetting('fastSchemeChange') &&
+    local &&
+    parentState &&
+    local.scheme !== parentState.scheme &&
+    getThemeBaseName(local.name) === getThemeBaseName(parentState.name)
+
+  // all tracked keys are scheme-optimized = can skip re-render for scheme changes
+  const keysSize = keys?.current?.size ?? 0
+  const schemeKeysSize = schemeKeys?.current?.size ?? 0
+  const allKeysSchemeOptimized = schemeKeysSize === keysSize && keysSize > 0
+
+  const canSkipForSchemeChange = isSchemeOnlyChange && allKeysSchemeOptimized
+
+  const needsUpdate = props.passThrough
+    ? false
+    : isRoot || props.name === 'light' || props.name === 'dark' || props.name === null
+      ? true
+      : !HasRenderedOnce.get(keys)
+        ? true
+        : canSkipForSchemeChange
+          ? false // skip re-render for scheme-only changes with DynamicColorIOS
+          : keys?.current?.size
+            ? true
+            : props.needsUpdate?.()
+
+  const [rerender, next] = getNextState(
+    local,
+    props,
+    propsKey,
+    isRoot,
+    id,
+    parentId,
+    needsUpdate,
+    PendingUpdate.get(id)
+  )
+
+  PendingUpdate.delete(id)
+
+  // we always create a new localState for every component
+  // that way we can use it to de-opt and avoid renders granularly
+  // we always return the localState object in each component
+  // the global state (states) should always be up to date with the latest
+  if (!local || rerender) {
+    local = { ...next }
+    localStates.set(id, local)
+  }
+
+  if (process.env.NODE_ENV === 'development' && props.debug === 'verbose') {
+    console.groupCollapsed(` ${id} getSnapshot ${rerender}`, local.name, '>', next.name)
+    console.info({
+      props,
+      propsKey,
+      isRoot,
+      parentId,
+      local,
+      next,
+      needsUpdate,
+      isSchemeOnlyChange,
+      allKeysSchemeOptimized,
+      canSkipForSchemeChange,
+    })
+    console.groupEnd()
+  }
+
+  if (next !== local) {
+    Object.assign(local, next)
+    local.id = id
+  }
+  ;(local as any)._parentName = parentState?.name
+  ;(local as any)._propsKey = propsKey
+  states.set(id, next)
+
+  return local
 }
 
 const getNextState = (
@@ -285,20 +419,25 @@ const getNextState = (
   }
 
   if (!name) {
-    const next = lastState ?? parentState
-
-    if (!next) {
-      throw new Error(
-        process.env.NODE_ENV === 'development'
-          ? `${MISSING_THEME_MESSAGE}
-
-Looked for theme${props.name ? ` "${props.name}"` : ''}${props.componentName ? ` (component: ${props.componentName})` : ''}, but no theme state was resolved (parentId: ${parentId}, id: ${id}).`
-          : MISSING_THEME_MESSAGE
-      )
-    }
+    // parentState can be transiently missing when a consumer renders in a
+    // separate sync flush (a portal/Toast viewport, or a native multi-root
+    // surface) before its provider has populated the module-level `states` map.
+    // that's recoverable — the next render resolves it — so fall back to the
+    // root theme (or a light stub) instead of throwing. the "no parent context"
+    // throw above still catches a genuinely missing provider. going back to
+    // useSyncExternalStore would avoid the race but force every themed node out
+    // of concurrent rendering, so we keep the manual store and tolerate the
+    // ordering here.
+    const next = lastState ??
+      parentState ??
+      rootThemeState ?? {
+        id,
+        name: 'light',
+        theme: getConfig().themes.light,
+      }
 
     if (shouldRerender) {
-      const updated = { ...(parentState || lastState)! }
+      const updated = { ...(parentState || lastState || next)! }
       return [true, updated]
     }
 
@@ -306,9 +445,12 @@ Looked for theme${props.name ? ` "${props.name}"` : ''}${props.componentName ? `
   }
 
   const scheme = getScheme(name)
-  // const parentInverses = parentState?.inverses ?? 0
+  const parentInverses = parentState?.inverses ?? 0
   const isInverse = parentState && scheme !== parentState.scheme
-  // const inverses = parentInverses + (isInverse ? 1 : 0)
+  // cumulative from the root: once any level flips scheme, every descendant is
+  // considered inverted vs the OS, even sub-themes that match their immediate
+  // parent (dark_blue under dark). gates the DynamicColorIOS optimization below.
+  const inverses = parentInverses + (isInverse ? 1 : 0)
 
   const nextState = {
     id,
@@ -317,7 +459,7 @@ Looked for theme${props.name ? ` "${props.name}"` : ''}${props.componentName ? `
     scheme,
     parentId,
     parentName: parentState?.name,
-    // inverses,
+    inverses,
     isInverse,
     isNew: true,
   } satisfies ThemeState

package/src/index.ts

@@ -56,6 +56,7 @@ export * from './interfaces/GetRef'
 export {
   getConfig,
   getSetting,
+  getStyleCompat,
   getThemes,
   getToken,
   getTokens,
@@ -64,6 +65,7 @@ export {
   setConfig,
   setupDev,
   updateConfig,
+  type StyleCompat,
 } from './config'
 
 export { setNonce } from './helpers/insertStyleRule'
@@ -75,10 +77,16 @@ export {
   _disableMediaTouch,
   configureMedia,
   mediaKeyMatch,
+  updateMediaListeners,
   useMedia,
 } from './hooks/useMedia'
 export { mediaObjectToString } from './helpers/mediaObjectToString'
-export { getMedia, mediaQueryConfig, mediaState } from './helpers/mediaState'
+export {
+  getMedia,
+  mediaQueryConfig,
+  mediaState,
+  setMediaState,
+} from './helpers/mediaState'
 export * from './hooks/useProps'
 export * from './hooks/useTheme'
 export * from './hooks/useThemeName'

package/src/interfaces/GuiComponentPropsBaseBase.tsx

@@ -68,13 +68,13 @@ export type GuiComponentPropsBaseBase = {
 
   /**
    * Marks this component as a group for use in styling children based on parents named group
-   * See: https://gui.dev/docs/intro/props
+   * See: https://hanzogui.dev/docs/intro/props
    */
   group?: GroupNames | boolean
 
   /**
    * Works only alongside group, when children of the group are using container based sizing on native you can hide them until parent is measured.
-   * See: https://gui.dev/docs/intro/props
+   * See: https://hanzogui.dev/docs/intro/props
    */
   untilMeasured?: 'hide' | 'show'
 

package/src/opacityModifier.test-d.ts

@@ -0,0 +1,65 @@
+/**
+ * type tests for the opacity modifier syntax (e.g., $color/50)
+ *
+ * the runtime already supports this syntax in getTokenForKey, but the types
+ * were not accepting it. these tests verify that color tokens with opacity
+ * modifiers are now type-safe.
+ */
+
+import { expectTypeOf, describe, test } from 'vitest'
+import type { ColorTokens, FontColorTokens, GetThemeValueForKey } from './types'
+
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+type ColorTokenKey = `color${Digit}${Digit}${Digit}`
+
+describe('opacity modifier types', () => {
+  test('ColorTokens accepts opacity modifier syntax', () => {
+    // should accept token with opacity modifier
+    const colorWithOpacity: ColorTokens = '$color/50'
+    const colorWithFullOpacity: ColorTokens = '$color/100'
+    const colorWithLowOpacity: ColorTokens = '$color/10'
+
+    // should still accept regular tokens
+    const regularToken: ColorTokens = '$color'
+    const colorName: ColorTokens = 'red'
+
+    expectTypeOf(colorWithOpacity).toMatchTypeOf<ColorTokens>()
+    expectTypeOf(colorWithFullOpacity).toMatchTypeOf<ColorTokens>()
+    expectTypeOf(colorWithLowOpacity).toMatchTypeOf<ColorTokens>()
+    expectTypeOf(regularToken).toMatchTypeOf<ColorTokens>()
+    expectTypeOf(colorName).toMatchTypeOf<ColorTokens>()
+  })
+
+  test('FontColorTokens accepts opacity modifier syntax', () => {
+    const fontColorNumber: FontColorTokens = 42
+    const fontColorWithOpacity: FontColorTokens = '$bodyColor/50'
+
+    expectTypeOf(fontColorNumber).toMatchTypeOf<FontColorTokens>()
+    expectTypeOf(fontColorWithOpacity).toMatchTypeOf<FontColorTokens>()
+    expectTypeOf<number>().toMatchTypeOf<FontColorTokens>()
+  })
+
+  test('opacity modifier requires token prefix', () => {
+    const validOpacity: ColorTokens = '$color/75'
+    expectTypeOf(validOpacity).toMatchTypeOf<ColorTokens>()
+
+    // @ts-expect-error opacity modifiers only apply to token-like values.
+    const cssColorWithOpacity: ColorTokens = 'red/75'
+    expectTypeOf(cssColorWithOpacity).toMatchTypeOf<ColorTokens>()
+  })
+
+  test('color props accept opacity without expanding large token unions', () => {
+    type LargeColorTokens = `$${ColorTokenKey}` | ColorTokens
+
+    const colorToken: LargeColorTokens = '$color123'
+    const colorTokenWithOpacity: LargeColorTokens = '$color123/50'
+    const propColorTokenWithOpacity: GetThemeValueForKey<'backgroundColor'> =
+      '$color123/50'
+
+    expectTypeOf(colorToken).toMatchTypeOf<LargeColorTokens>()
+    expectTypeOf(colorTokenWithOpacity).toMatchTypeOf<LargeColorTokens>()
+    expectTypeOf(propColorTokenWithOpacity).toMatchTypeOf<
+      GetThemeValueForKey<'backgroundColor'>
+    >()
+  })
+})

package/src/styled.tsx

@@ -82,7 +82,7 @@ type TextLikeElements =
   | 'u'
   | 'var'
 
-// props that conflict with gui style props
+// props that conflict with hanzogui style props
 type ConflictingHTMLProps =
   | 'color'
   | 'display'