@hanzogui/web 2.0.0

package/src/helpers/propMapper.ts

@@ -0,0 +1,404 @@
+import { isAndroid } from '@hanzogui/constants'
+import { getVariableValue, isVariable } from '../createVariable'
+import type {
+  GetStyleState,
+  PropMapper,
+  SplitStyleProps,
+  StyleResolver,
+  GuiInternalConfig,
+  Variable,
+  VariantSpreadFunction,
+} from '../types'
+import { expandStyle } from './expandStyle'
+import {
+  getLastFontFamilyToken,
+  getTokenForKey,
+  resolveVariableValue,
+  setLastFontFamilyToken,
+} from './getTokenForKey'
+import { getFontsForLanguage, getVariantExtras } from './getVariantExtras'
+import { isObj } from './isObj'
+import { normalizeStyle } from './normalizeStyle'
+import { parseNativeStyle } from './parseNativeStyle'
+import { pseudoDescriptors } from './pseudoDescriptors'
+import { resolveCompoundTokens } from './resolveCompoundTokens'
+import { isRemValue, resolveRem } from './resolveRem'
+import { skipProps } from './skipProps'
+
+export { getTokenForKey } from './getTokenForKey'
+
+export const propMapper: PropMapper = (key, value, styleState, disabled, map) => {
+  if (disabled) {
+    return map(key, value)
+  }
+
+  setLastFontFamilyToken(null)
+
+  if (!(process.env.HANZO_GUI_TARGET === 'native' && isAndroid)) {
+    // this shouldnt be necessary and handled in the outer loop
+    if (key === 'elevationAndroid') return
+  }
+
+  const { conf, styleProps, staticConfig } = styleState
+  const { variants } = staticConfig
+
+  if (!styleProps.noExpand) {
+    if (variants && key in variants) {
+      const variantValue = resolveVariants(key, value, styleProps, styleState, '')
+      if (variantValue) {
+        variantValue.forEach(([key, value]) => map(key, value))
+        return
+      }
+    }
+  }
+
+  // handle shorthands
+  if (!styleProps.disableExpandShorthands) {
+    if (key in conf.shorthands) {
+      key = conf.shorthands[key]
+    }
+  }
+
+  // Capture original value before resolution (for context prop tracking)
+  const originalValue = value
+
+  if (value != null) {
+    if (typeof value === 'string') {
+      if (value[0] === '$') {
+        value = getTokenForKey(key, value, styleProps, styleState)
+      } else {
+        const resolved = resolveCompoundTokens(key, value, styleProps, styleState)
+        value =
+          resolved !== value ? resolved : isRemValue(value) ? resolveRem(value) : value
+      }
+    } else if (isVariable(value)) {
+      value = resolveVariableValue(key, value, styleProps.resolveValues)
+    } else if (isRemValue(value)) {
+      value = resolveRem(value)
+    }
+  }
+
+  // on native, parse string backgroundImage/boxShadow/textShadow to RN object format
+  // this handles both token-resolved strings and plain strings without tokens
+  if (
+    process.env.HANZO_GUI_TARGET === 'native' &&
+    value != null &&
+    typeof value === 'string' &&
+    (key === 'backgroundImage' || key === 'boxShadow' || key === 'textShadow')
+  ) {
+    const parsed = parseNativeStyle(key, value)
+    if (parsed) {
+      // textShadow returns [key, value] pairs to expand into separate properties
+      if (key === 'textShadow' && Array.isArray(parsed) && Array.isArray(parsed[0])) {
+        for (const [nkey, nvalue] of parsed) {
+          map(nkey, nvalue, originalValue)
+        }
+        return
+      }
+      value = parsed
+    }
+  }
+
+  if (value != null) {
+    const fontToken = getLastFontFamilyToken()
+    if (key === 'fontFamily' && fontToken) {
+      styleState.fontFamily = fontToken
+    }
+
+    const expanded = styleProps.noExpand ? null : expandStyle(key, value)
+
+    if (expanded) {
+      const max = expanded.length
+      for (let i = 0; i < max; i++) {
+        const [nkey, nvalue] = expanded[i]
+        map(nkey, nvalue, originalValue)
+      }
+    } else {
+      map(key, value, originalValue)
+    }
+  }
+}
+
+const resolveVariants: StyleResolver = (
+  key,
+  value,
+  styleProps,
+  styleState,
+  parentVariantKey
+) => {
+  const { staticConfig, conf, debug } = styleState
+  const { variants } = staticConfig
+  if (!variants) return
+
+  let variantValue = getVariantDefinition(variants[key], value, conf, styleState)
+
+  if (process.env.NODE_ENV === 'development' && debug === 'verbose') {
+    console.groupCollapsed(`♦️♦️♦️ resolve variant ${key}`)
+    console.info({
+      key,
+      value,
+      variantValue,
+      variants,
+    })
+    console.groupEnd()
+  }
+
+  if (!variantValue) {
+    // variant at key exists, but no matching variant
+    // disabling warnings, its fine to pass through, could re-enable later somehoiw
+    if (process.env.HANZO_GUI_WARN_ON_MISSING_VARIANT === '1') {
+      // don't warn on missing booleans
+      if (typeof value !== 'boolean') {
+        const name = staticConfig.componentName || '[UnnamedComponent]'
+        console.warn(
+          `No variant found: ${name} has variant "${key}", but no matching value "${value}"`
+        )
+      }
+    }
+    return
+  }
+
+  if (typeof variantValue === 'function') {
+    const fn = variantValue as VariantSpreadFunction<any>
+    const extras = getVariantExtras(styleState)
+    variantValue = fn(value, extras)
+
+    if (
+      process.env.NODE_ENV === 'development' &&
+      debug === 'verbose' &&
+      process.env.HANZO_GUI_TARGET !== 'native'
+    ) {
+      console.groupCollapsed('   expanded functional variant', key)
+      console.info({ fn, variantValue, extras })
+      console.groupEnd()
+    }
+  }
+
+  let fontFamilyResult: any
+
+  if (isObj(variantValue)) {
+    const fontFamilyUpdate =
+      variantValue.fontFamily || variantValue[conf.inverseShorthands.fontFamily]
+
+    if (fontFamilyUpdate) {
+      fontFamilyResult = getFontFamilyFromNameOrVariable(fontFamilyUpdate, conf)
+      styleState.fontFamily = fontFamilyResult
+
+      if (process.env.NODE_ENV === 'development' && debug === 'verbose') {
+        console.info(`   updating font family`, fontFamilyResult)
+      }
+    }
+
+    variantValue = resolveTokensAndVariants(
+      key,
+      variantValue,
+      styleProps,
+      styleState,
+      parentVariantKey
+    )
+  }
+
+  if (variantValue) {
+    const expanded = normalizeStyle(variantValue, !!styleProps.noNormalize)
+
+    if (process.env.NODE_ENV === 'development' && debug === 'verbose') {
+      console.info(`   expanding styles from `, variantValue, `to`, expanded)
+    }
+    const next = Object.entries(expanded)
+
+    // store any changed font family (only support variables for now)
+    if (fontFamilyResult && fontFamilyResult[0] === '$') {
+      setLastFontFamilyToken(getVariableValue(fontFamilyResult))
+    }
+
+    return next
+  }
+}
+
+// handles finding and resolving the fontFamily to the token name
+// this is used as `font_[name]` in className for nice css variable support
+export function getFontFamilyFromNameOrVariable(input: any, conf: GuiInternalConfig) {
+  if (isVariable(input)) {
+    const val = variableToFontNameCache.get(input)
+    if (val) return val
+    for (const key in conf.fontsParsed) {
+      const familyVariable = conf.fontsParsed[key].family
+      if (isVariable(familyVariable)) {
+        variableToFontNameCache.set(familyVariable, key)
+        if (familyVariable === input) {
+          return key
+        }
+      }
+    }
+  } else if (typeof input === 'string') {
+    if (input[0] === '$') {
+      return input
+    }
+  }
+}
+
+const variableToFontNameCache = new WeakMap<Variable, string>()
+
+const resolveTokensAndVariants: StyleResolver<object> = (
+  key, // we dont use key assume value is object instead
+  value,
+  styleProps,
+  styleState,
+  parentVariantKey
+) => {
+  const { conf, staticConfig, debug, theme } = styleState
+  const { variants } = staticConfig
+  const res = {}
+
+  if (process.env.NODE_ENV === 'development' && debug === 'verbose') {
+    console.info(`   - resolveTokensAndVariants`, key, value)
+  }
+
+  for (const _key in value) {
+    const subKey = conf.shorthands[_key] || _key
+    const val = value[_key]
+
+    if (!styleProps.noSkip && subKey in skipProps) {
+      continue
+    }
+
+    // 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
+    if (staticConfig) {
+      const contextProps =
+        staticConfig.context?.props || staticConfig.parentStaticConfig?.context?.props
+      if (contextProps && subKey in contextProps) {
+        styleState.overriddenContextProps ||= {}
+        styleState.overriddenContextProps[subKey] = val
+        // Also track the original token value separately
+        styleState.originalContextPropValues ||= {}
+        styleState.originalContextPropValues[subKey] = val
+      }
+    }
+
+    if (styleProps.noExpand) {
+      res[subKey] = val
+    } else {
+      if (variants && subKey in variants) {
+        // avoids infinite loop if variant is matching a style prop
+        // eg: { variants: { flex: { true: { flex: 2 } } } }
+        if (parentVariantKey && parentVariantKey === key) {
+          res[subKey] =
+            val[0] === '$' ? getTokenForKey(subKey, val, styleProps, styleState) : val
+        } else {
+          const variantOut = resolveVariants(subKey, val, styleProps, styleState, key)
+
+          // apply, merging sub-styles
+          if (variantOut) {
+            for (const [key, val] of variantOut) {
+              if (val == null) continue
+              if (key in pseudoDescriptors) {
+                res[key] ??= {}
+                Object.assign(res[key], val)
+              } else {
+                res[key] = val
+              }
+            }
+          }
+        }
+        continue
+      }
+    }
+
+    if (isVariable(val)) {
+      res[subKey] = resolveVariableValue(subKey, val, styleProps.resolveValues)
+
+      if (process.env.NODE_ENV === 'development' && debug === 'verbose') {
+        console.info(`variable`, subKey, res[subKey])
+      }
+      continue
+    }
+
+    if (typeof val === 'string') {
+      const fVal =
+        val[0] === '$'
+          ? getTokenForKey(subKey, val, styleProps, styleState)
+          : resolveCompoundTokens(subKey, val, styleProps, styleState)
+
+      res[subKey] = fVal === val && isRemValue(val) ? resolveRem(val) : fVal
+      continue
+    }
+
+    if (isObj(val)) {
+      const subObject = resolveTokensAndVariants(subKey, val, styleProps, styleState, key)
+
+      if (process.env.NODE_ENV === 'development' && debug === 'verbose') {
+        console.info(`object`, subKey, subObject)
+      }
+
+      // sub-objects: media queries, pseudos, shadowOffset
+      res[subKey] ??= {}
+      Object.assign(res[subKey], subObject)
+    } else {
+      // nullish values cant be tokens, need no extra parsing
+      res[subKey] = val
+    }
+
+    if (process.env.NODE_ENV === 'development') {
+      if (debug) {
+        if (res[subKey]?.[0] === '$') {
+          console.warn(
+            `⚠️ Missing token in theme ${theme.name}:`,
+            subKey,
+            res[subKey],
+            theme
+          )
+        }
+      }
+    }
+  }
+
+  return res
+}
+
+const tokenCats = ['size', 'color', 'radius', 'space', 'zIndex'].map((name) => ({
+  name,
+  spreadName: `...${name}`,
+}))
+
+// goes through specificity finding best matching variant function
+function getVariantDefinition(
+  variant: any,
+  value: any,
+  conf: GuiInternalConfig,
+  { theme }: Partial<GetStyleState>
+) {
+  if (!variant) return
+  if (typeof variant === 'function') {
+    return variant
+  }
+  const exact = variant[value]
+  if (exact) {
+    return exact
+  }
+  if (value != null) {
+    const { tokensParsed } = conf
+    for (const { name, spreadName } of tokenCats) {
+      if (spreadName in variant) {
+        // check tokens first
+        if (name in tokensParsed && value in tokensParsed[name]) {
+          return variant[spreadName]
+        }
+        // or check theme (only color lives in theme, others are in tokens)
+        if (name === 'color' && theme && typeof value === 'string' && value[0] === '$') {
+          const themeKey = value.slice(1)
+          if (themeKey in theme) {
+            return variant[spreadName]
+          }
+        }
+      }
+    }
+    const fontSizeVariant = variant['...fontSize']
+    if (fontSizeVariant && conf.fontSizeTokens.has(value)) {
+      return fontSizeVariant
+    }
+  }
+  // fallback to catch all | size
+  return variant[`:${typeof value}`] || variant['...']
+}

package/src/helpers/proxyThemeToParents.ts

@@ -0,0 +1,52 @@
+import type { DedupedThemes, ThemeParsed } from '../types'
+
+const themesRaw: Record<string, ThemeParsed> = {}
+
+// this seems expensive but its necessary to do two loops unless we want to refactor a variety of things again
+// not *too* much work but not a big cost doing the two loops
+export function proxyThemesToParents(
+  dedupedThemes: DedupedThemes
+): Record<string, ThemeParsed> {
+  // fill it in so we can look it up next
+  for (const { names, theme } of dedupedThemes) {
+    for (const name of names) {
+      themesRaw[name] = theme
+    }
+  }
+
+  const themes: Record<string, ThemeParsed> = {}
+  // now go back and re-fill it in
+  // we do have to call this once per non-duplicated theme!
+  // because they could have different parent chains
+  // despite being the same theme
+
+  for (const { names, theme } of dedupedThemes) {
+    for (const themeName of names) {
+      const proxiedTheme = proxyThemeToParents(themeName, theme)
+      themes[themeName] = proxiedTheme
+    }
+  }
+
+  return themes
+}
+
+export function proxyThemeToParents(themeName: string, theme: ThemeParsed) {
+  const out = {}
+  const cur: string[] = []
+
+  // if theme is dark_blue_alt1_Button
+  // this will be the parent names in order: ['dark', 'dark_blue', 'dark_blue_alt1"]
+  const parents = themeName
+    .split('_')
+    .slice(0, -1)
+    .map((part) => {
+      cur.push(part)
+      return cur.join('_')
+    })
+
+  for (const parent of parents) {
+    Object.assign(out, themesRaw[parent])
+  }
+  Object.assign(out, theme)
+  return out
+}

package/src/helpers/proxyThemeVariables.tsx

@@ -0,0 +1,13 @@
+export function proxyThemeVariables<A extends object>(obj: A): A {
+  return new Proxy<A>(obj || {}, {
+    has(target, key) {
+      return Reflect.has(target, removeStarting$(key))
+    },
+    get(target, key) {
+      return Reflect.get(target, removeStarting$(key))
+    },
+  })
+}
+
+const removeStarting$ = (str: string | symbol) =>
+  typeof str === 'string' && str[0] === '$' ? str.slice(1) : str

package/src/helpers/pseudoDescriptors.ts

@@ -0,0 +1,74 @@
+// *0 order matches to *1
+
+export const pseudoDescriptorsBase = {
+  // order of keys here important! in priority order
+  hoverStyle: {
+    name: 'hover',
+    priority: 2,
+  },
+  pressStyle: {
+    name: 'active',
+    stateKey: 'press',
+    priority: 3,
+  },
+  focusVisibleStyle: {
+    name: 'focus-visible',
+    priority: 4,
+    stateKey: 'focusVisible',
+  },
+  focusStyle: {
+    name: 'focus',
+    priority: 4,
+  },
+  focusWithinStyle: {
+    name: 'focus-within',
+    priority: 4,
+    stateKey: 'focusWithin',
+  },
+  disabledStyle: {
+    name: 'disabled',
+    priority: 5,
+    stateKey: 'disabled',
+  },
+} as const
+
+export const pseudoPriorities = {
+  hover: pseudoDescriptorsBase.hoverStyle.priority,
+  press: pseudoDescriptorsBase.pressStyle.priority,
+  focus: pseudoDescriptorsBase.focusStyle.priority,
+  focusVisible: pseudoDescriptorsBase.focusVisibleStyle.priority,
+  focusWithin: pseudoDescriptorsBase.focusWithinStyle.priority,
+  disabled: pseudoDescriptorsBase.disabledStyle.priority,
+}
+
+export type PseudoDescriptorKey = keyof typeof pseudoDescriptorsBase
+
+export const pseudoDescriptors: Record<
+  PseudoDescriptorKey | 'enterStyle' | 'exitStyle',
+  PseudoDescriptor
+> = {
+  ...pseudoDescriptorsBase,
+  enterStyle: {
+    name: 'enter',
+    selector: '.t_unmounted',
+    priority: 4,
+  },
+  exitStyle: {
+    name: 'exit',
+    priority: 5,
+  },
+}
+
+export type PseudoDescriptor = {
+  name: string
+  priority: number
+  stateKey?: string
+  selector?: string
+}
+
+export type PseudoDescriptors = {
+  [Key in keyof typeof pseudoDescriptors]: PseudoDescriptor
+}
+
+// media always above pseudos
+export const defaultMediaImportance = Object.keys(pseudoDescriptors).length

package/src/helpers/pseudoTransitions.ts

@@ -0,0 +1,97 @@
+import type { TransitionProp, PseudoTransitions, GuiComponentState } from '../types'
+
+/**
+ * Pseudo state for tracking enter/exit transitions
+ */
+export type PseudoState = {
+  hover?: boolean
+  press?: boolean
+  focus?: boolean
+  // track group pseudo states: { groupName: { hover: boolean, press: boolean } }
+  groups?: Record<string, { hover?: boolean; press?: boolean; focus?: boolean }>
+}
+
+/**
+ * Resolves the effective transition based on pseudo state changes.
+ * When entering a pseudo state (e.g., hover), use that pseudo's transition.
+ * When exiting (returning to base), use the base transition.
+ *
+ * CSS-like semantics:
+ * - Enter hover: Uses hover's transition (fast snap)
+ * - Exit hover: Uses base transition (slow fade)
+ */
+export function resolveEffectivePseudoTransition(
+  prev: PseudoState | undefined,
+  next: GuiComponentState,
+  pseudoTransitions: PseudoTransitions | undefined | null,
+  baseTransition: TransitionProp | undefined | null
+): TransitionProp | undefined | null {
+  if (!pseudoTransitions) {
+    return baseTransition
+  }
+
+  // treat undefined prev as all-false so first interaction detects entering
+  const prevState = prev || { hover: false, press: false, focus: false, groups: {} }
+
+  // check which pseudo states are being entered (priority: press > hover > focus)
+  if (next.press && !prevState.press && pseudoTransitions.pressStyle) {
+    return pseudoTransitions.pressStyle
+  }
+  if (next.hover && !prevState.hover && pseudoTransitions.hoverStyle) {
+    return pseudoTransitions.hoverStyle
+  }
+  if (next.focus && !prevState.focus && pseudoTransitions.focusStyle) {
+    return pseudoTransitions.focusStyle
+  }
+
+  // check group pseudo transitions (e.g., $group-scenario4-hover)
+  for (const key in pseudoTransitions) {
+    if (key.startsWith('$group-')) {
+      // parse $group-{name}-{pseudo} format
+      const match = key.match(/^\$group-(.+)-(hover|press|focus)$/)
+      if (!match) continue
+
+      const groupName = match[1]
+      const pseudoType = match[2] as 'hover' | 'press' | 'focus'
+
+      // get current and previous group pseudo state
+      const nextGroupPseudo = next.group?.[groupName]?.pseudo
+      const prevGroupPseudo = prevState.groups?.[groupName]
+
+      // check if entering this group pseudo state
+      if (nextGroupPseudo?.[pseudoType] && !prevGroupPseudo?.[pseudoType]) {
+        return pseudoTransitions[key as `$group-${string}-${'hover' | 'press' | 'focus'}`]
+      }
+    }
+  }
+
+  // exiting uses base transition
+  return baseTransition
+}
+
+/**
+ * Extracts pseudo state from GuiComponentState for storage in prevPseudoState
+ */
+export function extractPseudoState(state: GuiComponentState): PseudoState {
+  const groups: PseudoState['groups'] = {}
+
+  if (state.group) {
+    for (const groupName in state.group) {
+      const pseudo = state.group[groupName]?.pseudo
+      if (pseudo) {
+        groups[groupName] = {
+          hover: pseudo.hover,
+          press: pseudo.press,
+          focus: pseudo.focus,
+        }
+      }
+    }
+  }
+
+  return {
+    hover: state.hover,
+    press: state.press,
+    focus: state.focus,
+    groups,
+  }
+}

package/src/helpers/registerCSSVariable.ts

@@ -0,0 +1,54 @@
+import { createCSSVariable, getVariableValue } from '../createVariable'
+import type { Variable, VariableVal } from '../types'
+
+export const registerCSSVariable = (v: Variable | VariableVal) => {
+  if (!process.env.HANZO_GUI_DID_OUTPUT_CSS) {
+    tokensValueToVariable.set(getVariableValue(v), v)
+  }
+}
+
+export const variableToCSS = (v: Variable, unitless = false) => {
+  if (!process.env.HANZO_GUI_DID_OUTPUT_CSS) {
+    return `--${process.env.HANZO_GUI_CSS_VARIABLE_PREFIX || ''}${createCSSVariable(
+      v.name,
+      false
+    )}:${!unitless && typeof v.val === 'number' ? `${v.val}px` : v.val}`
+  }
+  return ''
+}
+
+export const tokensValueToVariable = new Map<any, any>()
+
+// auto-generated vars for theme values not in tokens
+let autoVarId = 0
+export const autoVariables: Variable[] = []
+
+export const getOrCreateVariable = (val: any): Variable => {
+  if (tokensValueToVariable.has(val)) {
+    return tokensValueToVariable.get(val)!
+  }
+  const name = `t${autoVarId++}`
+  const variable = `var(--${name})`
+  const v = { val, name, variable } as Variable
+  tokensValueToVariable.set(val, v)
+  autoVariables.push(v)
+  return v
+}
+
+// For mutated themes (runtime theme changes like in /theme builder)
+// Uses same 't' prefix but starts at 10000 to avoid conflicts with SSR-generated vars
+let mutatedVarId = 10000
+export const mutatedAutoVariables: Variable[] = []
+const mutatedTokensValueToVariable = new Map<any, any>()
+
+export const getOrCreateMutatedVariable = (val: any): Variable => {
+  if (mutatedTokensValueToVariable.has(val)) {
+    return mutatedTokensValueToVariable.get(val)!
+  }
+  const name = `t${mutatedVarId++}`
+  const variable = `var(--${name})`
+  const v = { val, name, variable } as Variable
+  mutatedTokensValueToVariable.set(val, v)
+  mutatedAutoVariables.push(v)
+  return v
+}