@hanzogui/web 2.0.0

package/src/helpers/resolveAnimationDriver.ts

@@ -0,0 +1,23 @@
+import type { AnimationDriver } from '../types'
+
+/**
+ * Resolves a value that might be an AnimationDriver or a multi-driver config object
+ * like { default: motionDriver, css: cssDriver } into an actual AnimationDriver.
+ */
+export function resolveAnimationDriver(
+  driver: AnimationDriver | Record<string, AnimationDriver> | null | undefined
+): AnimationDriver | null {
+  if (!driver) return null
+  // valid driver
+  if (typeof (driver as any).useAnimations === 'function') {
+    return driver as AnimationDriver
+  }
+  // multi-driver object - extract default
+  if (
+    'default' in driver &&
+    typeof (driver as any).default?.useAnimations === 'function'
+  ) {
+    return (driver as any).default
+  }
+  return null
+}

package/src/helpers/resolveCompoundTokens.ts

@@ -0,0 +1,28 @@
+import type { GetStyleState, SplitStyleProps } from '../types'
+import { platformResolveValue } from './platformResolveValue'
+
+const compoundKeys: Record<string, boolean> = {
+  boxShadow: true,
+  textShadow: true,
+  filter: true,
+  backgroundImage: true,
+  border: true,
+  outline: true,
+}
+
+/**
+ * resolves embedded $tokens in compound CSS string values like
+ * boxShadow, textShadow, filter, backgroundImage, border, outline.
+ *
+ * returns the original value unchanged if no resolution is needed.
+ */
+export function resolveCompoundTokens(
+  key: string,
+  value: string,
+  styleProps: SplitStyleProps,
+  styleState: Partial<GetStyleState>
+): any {
+  if (!value.includes('$')) return value
+  if (!compoundKeys[key]) return value
+  return platformResolveValue(key, value, styleProps, styleState)
+}

package/src/helpers/resolveRem.native.ts

@@ -0,0 +1,44 @@
+import { PixelRatio } from 'react-native'
+import { getConfig } from '../config'
+
+const remRegex = /(-?[\d.]+)rem/g
+
+/**
+ * Resolves rem values to pixel values on native platforms.
+ * Uses PixelRatio.getFontScale() to account for user's font size preferences.
+ *
+ * @param value - A string value that may contain rem units (e.g., "1.5rem" or "calc(1rem + 2rem)")
+ * @returns The numeric pixel value
+ */
+export function resolveRem(value: string): number {
+  const config = getConfig()
+  const baseFontSize = config?.settings?.remBaseFontSize ?? 16
+
+  // Handle simple rem value like "1.5rem"
+  if (value.endsWith('rem') && !value.includes(' ')) {
+    const numericValue = Number.parseFloat(value)
+    if (!Number.isNaN(numericValue)) {
+      return PixelRatio.getFontScale() * baseFontSize * numericValue
+    }
+  }
+
+  // Handle multiple rem values in a string (e.g., in calc expressions)
+  let result = 0
+  let match: RegExpExecArray | null
+  while ((match = remRegex.exec(value)) !== null) {
+    const numericValue = Number.parseFloat(match[1])
+    if (!Number.isNaN(numericValue)) {
+      result += PixelRatio.getFontScale() * baseFontSize * numericValue
+    }
+  }
+  remRegex.lastIndex = 0 // Reset regex state
+
+  return result
+}
+
+/**
+ * Checks if a value is a rem string
+ */
+export function isRemValue(value: unknown): value is string {
+  return typeof value === 'string' && value.includes('rem')
+}

package/src/helpers/resolveRem.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolves rem values on web platforms.
+ * On web, browsers handle rem natively, so we just return the value as-is.
+ *
+ * @param value - A string value containing rem units
+ * @returns The same string value (browsers handle rem natively)
+ */
+export function resolveRem(value: string): string {
+  return value
+}
+
+/**
+ * Checks if a value is a rem string
+ */
+export function isRemValue(value: unknown): value is string {
+  return typeof value === 'string' && value.includes('rem')
+}

package/src/helpers/resolveSafeArea.native.ts

@@ -0,0 +1,18 @@
+const safeAreaEdges: Record<string, 'top' | 'bottom' | 'left' | 'right'> = {
+  $safeAreaTop: 'top',
+  $safeAreaBottom: 'bottom',
+  $safeAreaLeft: 'left',
+  $safeAreaRight: 'right',
+}
+
+export function resolveSafeAreaValue(value: string): number | undefined {
+  const edge = safeAreaEdges[value]
+  if (!edge) return undefined
+
+  const g = globalThis as any
+  const state = g.__gui_native_safe_area_state__
+  if (state?.enabled && state.initialMetrics) {
+    return state.initialMetrics.insets[edge]
+  }
+  return 0
+}

package/src/helpers/resolveSafeArea.ts

@@ -0,0 +1,10 @@
+const safeAreaTokens: Record<string, string> = {
+  $safeAreaTop: 'env(safe-area-inset-top)',
+  $safeAreaBottom: 'env(safe-area-inset-bottom)',
+  $safeAreaLeft: 'env(safe-area-inset-left)',
+  $safeAreaRight: 'env(safe-area-inset-right)',
+}
+
+export function resolveSafeAreaValue(value: string): string | undefined {
+  return safeAreaTokens[value]
+}

package/src/helpers/setElementProps.native.tsx

@@ -0,0 +1,9 @@
+export function setElementProps(element) {
+  if (element && !element.getBoundingClientRect) {
+    element.getBoundingClientRect = () => {
+      if (element.unstable_getBoundingClientRect != null) {
+        return element.unstable_getBoundingClientRect()
+      }
+    }
+  }
+}

package/src/helpers/setElementProps.tsx

@@ -0,0 +1,5 @@
+import { hooks } from '../setupHooks'
+
+export const setElementProps = (node) => {
+  hooks.setElementProps?.(node)
+}

package/src/helpers/skipProps.ts

@@ -0,0 +1,35 @@
+import { nativeOnlyProps } from './nativeOnlyProps'
+import { webPropsToSkip } from './webPropsToSkip'
+
+/**
+ * These are props that dont pass down below Hanzo GUI styled components
+ */
+export const skipProps = {
+  untilMeasured: 1,
+  transition: 1,
+  space: 1,
+  animateOnly: 1,
+  animatedBy: 1,
+  disableClassName: 1,
+  debug: 1,
+  componentName: 1,
+  disableOptimization: 1,
+  render: 1,
+  style: 1, // handled after loop so pseudos set usedKeys and override it if necessary
+  group: 1,
+  animatePresence: 1,
+}
+
+if (process.env.NODE_ENV === 'test') {
+  skipProps['data-test-renders'] = 1
+}
+
+// Skip web-only props on native
+if (process.env.HANZO_GUI_TARGET === 'native') {
+  Object.assign(skipProps, webPropsToSkip)
+}
+
+// Skip native-only props on web
+if (process.env.HANZO_GUI_TARGET === 'web') {
+  Object.assign(skipProps, nativeOnlyProps)
+}

package/src/helpers/sortString.ts

@@ -0,0 +1 @@
+export const sortString = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0)

package/src/helpers/subscribeToContextGroup.tsx

@@ -0,0 +1,99 @@
+import { mergeIfNotShallowEqual } from '@hanzogui/is-equal-shallow'
+import { getMediaState } from '../hooks/useMedia'
+import type { ComponentSetStateShallow, DisposeFn, AllGroupContexts } from '../types'
+
+type SubscribeToContextGroupProps = {
+  setStateShallow: ComponentSetStateShallow
+  pseudoGroups?: Set<string>
+  mediaGroups?: Set<string>
+  groupContext: AllGroupContexts
+}
+
+export const subscribeToContextGroup = (props: SubscribeToContextGroupProps) => {
+  const { pseudoGroups, mediaGroups, groupContext } = props
+  if (pseudoGroups || mediaGroups) {
+    if (process.env.NODE_ENV === 'development' && !groupContext) {
+      console.debug(`No context group found`)
+    }
+
+    const disposables = new Set<DisposeFn>()
+
+    if (pseudoGroups) {
+      for (const name of pseudoGroups) {
+        disposables.add(createGroupListener(name, props))
+      }
+    }
+
+    if (mediaGroups) {
+      for (const name of mediaGroups) {
+        disposables.add(createGroupListener(name, props))
+      }
+    }
+
+    return () => {
+      disposables.forEach((d) => d())
+    }
+  }
+}
+
+const createGroupListener = (
+  name: string,
+  {
+    setStateShallow,
+    pseudoGroups,
+    mediaGroups,
+    groupContext,
+  }: SubscribeToContextGroupProps
+): DisposeFn => {
+  const parent = groupContext?.[name]
+
+  if (!parent) {
+    return () => {}
+  }
+
+  const dispose = parent.subscribe(({ layout, pseudo }) => {
+    setStateShallow((prev) => {
+      let didChange = false
+      const group = prev.group?.[name] || {
+        pseudo: {},
+        media: {},
+      }
+
+      if (pseudo && pseudoGroups?.has(name)) {
+        group.pseudo ||= {}
+        const next = mergeIfNotShallowEqual(group.pseudo, pseudo)
+        if (next !== group.pseudo) {
+          Object.assign(group.pseudo, pseudo)
+          didChange = true
+        }
+      } else if (layout && mediaGroups) {
+        group.media ||= {}
+        const mediaState = getMediaState(mediaGroups, layout)
+        const next = mergeIfNotShallowEqual(group.media, mediaState)
+        if (next !== group.media) {
+          Object.assign(group.media, next)
+          didChange = true
+        }
+      }
+
+      if (didChange) {
+        return {
+          group: {
+            ...prev.group,
+            [name]: group,
+          },
+        }
+      }
+
+      return prev
+    })
+  })
+
+  return () => {
+    dispose()
+    // we no longer have any active group, need to remove state so the style updates
+    setStateShallow({
+      group: {},
+    })
+  }
+}

package/src/helpers/themeable.tsx

@@ -0,0 +1,104 @@
+import React from 'react'
+
+import type { StaticConfig, ThemeableProps, ThemeProps } from '../types'
+import { Theme } from '../views/Theme'
+import { getDefaultProps } from './getDefaultProps'
+
+export function themeable<ComponentType extends (props: any) => any>(
+  Component: ComponentType,
+  staticConfig: Partial<StaticConfig>,
+  optimize = false
+) {
+  const withThemeComponent = React.forwardRef(function WithTheme(
+    props: ThemeableProps,
+    ref
+  ) {
+    'use no memo'
+
+    const userDefaults = getDefaultProps(staticConfig, props.componentName)
+    const defaultTheme = userDefaults?.theme
+    const defaultResetTheme = userDefaults?.themeReset
+    const { theme, componentName, themeReset, ...rest } = props
+
+    let overriddenContextProps: object | undefined
+    const context = staticConfig?.context
+    if (context) {
+      for (const key in context.props) {
+        const val = props[key]
+        if (val !== undefined) {
+          overriddenContextProps = overriddenContextProps || {}
+          overriddenContextProps[key] = val
+        }
+      }
+    }
+
+    const element = (
+      // @ts-expect-error its ok
+      <Component ref={ref} {...rest} data-disable-theme />
+    )
+
+    // we filter out the props here, why?
+    // Theme internally avoids wrapping <span /> unless 'theme' in props
+    // reason for this is to avoid wrapping every single component with span
+    // *if* ever it themes once, it leaves the span, to avoid reparenting
+    // its expected if users want to avoid re-parenting, they keep the theme prop
+    // and just set it to null. but we need to "respect" that here by filtering
+    // one example of a bug caused by not doing this is in <Select native> on web
+    // where it renders to an <option />, and then Theme would wrap a <span /> in that
+    // which is not allowed in HTML and causes hydration errors / logs
+    let filteredProps: Partial<ThemeProps> | null = null
+
+    const compName = componentName || staticConfig?.componentName
+    if (compName) {
+      filteredProps = filteredProps || {}
+      filteredProps.componentName = compName
+    }
+    if ('debug' in props) {
+      filteredProps = filteredProps || {}
+      filteredProps.debug = props.debug
+    }
+    if ('theme' in props || defaultTheme) {
+      filteredProps = filteredProps || {}
+      filteredProps.name = 'theme' in props ? props.theme : defaultTheme
+    }
+    if ('themeReset' in props || defaultResetTheme) {
+      filteredProps = filteredProps || {}
+      filteredProps.reset = 'themeReset' in props ? themeReset : defaultResetTheme
+    }
+
+    if (optimize && !filteredProps) {
+      // optimize by avoiding theme! this can re-parent but we should just document that to avoid performance
+      // in cases where you remove/add themes, just keep a theme={x ? '' : null} pattern
+      return element
+    }
+
+    let contents = (
+      <Theme disable-child-theme {...filteredProps}>
+        {element}
+      </Theme>
+    )
+
+    if (context) {
+      const Provider = context.Provider
+      const contextValue = React.useContext(context)
+      contents = (
+        <Provider {...contextValue} {...overriddenContextProps}>
+          {contents}
+        </Provider>
+      )
+    }
+
+    return contents
+  })
+
+  const withTheme: any = withThemeComponent
+  withTheme.displayName = `Themed(${
+    (Component as any)?.displayName || (Component as any)?.name || 'Anonymous'
+  })`
+
+  type FinalComponentType = ComponentType extends (props: infer P) => infer R
+    ? (props: Omit<P, 'theme'> & ThemeableProps) => R
+    : unknown
+
+  return withTheme as FinalComponentType
+}

package/src/helpers/themes.ts

@@ -0,0 +1,23 @@
+import { createVariable, isVariable } from '../createVariable'
+
+// mutates, freeze after
+// shared by createGui so extracted here
+export function ensureThemeVariable(theme: any, key: string) {
+  const val = theme[key]
+  if (!isVariable(val)) {
+    theme[key] = createVariable({
+      key,
+      name: key,
+      val,
+    })
+  } else {
+    if (val.name !== key) {
+      // rename to theme name
+      theme[key] = createVariable({
+        key: val.name,
+        name: key,
+        val: val.val,
+      })
+    }
+  }
+}

package/src/helpers/timer.ts

@@ -0,0 +1,9 @@
+const timer = require('@hanzogui/timer').timer()
+
+setTimeout(() => {
+  timer.print()
+}, 2000)
+
+export const time = timer.start({
+  quiet: true,
+})

package/src/helpers/transformsToString.ts

@@ -0,0 +1,20 @@
+import { normalizeValueWithProperty } from './normalizeValueWithProperty'
+
+export function transformsToString(transforms: object[]) {
+  return transforms
+    .map(
+      // { scale: 2 } => 'scale(2)'
+      // { translateX: 20 } => 'translateX(20px)'
+      // { matrix: [1,2,3,4,5,6] } => 'matrix(1,2,3,4,5,6)'
+      // { perspective: 1000 } => perspective(1000px)
+      (transform) => {
+        const type = Object.keys(transform)[0]
+        const value = transform[type]
+        if (type === 'matrix' || type === 'matrix3d') {
+          return `${type}(${value.join(',')})`
+        }
+        return `${type}(${normalizeValueWithProperty(value, type)})`
+      }
+    )
+    .join(' ')
+}

package/src/helpers/useRenderElement.tsx

@@ -0,0 +1,73 @@
+import type React from 'react'
+import { cloneElement, createElement, isValidElement } from 'react'
+import { composeRefs } from '@hanzogui/compose-refs'
+import type { GuiComponentState } from '../types'
+import { mergeSlotStyleProps } from './mergeSlotStyleProps'
+
+export type RenderProp<Props = Record<string, any>> =
+  | string
+  | React.ReactElement
+  | ((props: Props, state: GuiComponentState) => React.ReactElement)
+
+/**
+ * Evaluates a render prop and returns the element to render.
+ *
+ * @param render - The render prop (tag string, JSX element, or function)
+ * @param props - Props to pass to the rendered element (including ref)
+ * @param state - Component state for render functions
+ * @param defaultElement - Fallback element if render prop is not provided
+ */
+export function evaluateRenderProp(
+  render: RenderProp | undefined,
+  props: Record<string, any>,
+  state: GuiComponentState,
+  defaultElement: React.ReactElement<any>
+): React.ReactElement {
+  if (!render) {
+    return defaultElement
+  }
+
+  const defaultChildren = defaultElement.props.children
+
+  // String tag - swap element type, reuse props from defaultElement
+  if (typeof render === 'string') {
+    // on native, ignore lowercase tags (html/jsx elements like "div", "span")
+    if (
+      process.env.HANZO_GUI_TARGET === 'native' &&
+      render[0] === render[0].toLowerCase()
+    ) {
+      return defaultElement
+    }
+    return createElement(render, props, defaultChildren)
+  }
+
+  // Render function - call with props and state
+  if (typeof render === 'function') {
+    return render(props, state)
+  }
+
+  // JSX element - clone with merged props
+  if (isValidElement(render)) {
+    const renderProps = render.props as Record<string, any>
+    const renderRef = renderProps?.ref
+
+    // Fast path: no props to merge
+    if (!renderProps || Object.keys(renderProps).length === 0) {
+      if (renderRef) {
+        return cloneElement(
+          render,
+          { ...props, ref: composeRefs(props.ref, renderRef) } as any,
+          defaultChildren
+        )
+      }
+      return cloneElement(render, props as any, defaultChildren)
+    }
+
+    // Merge props (component props as base, render props as overlay)
+    const merged = mergeSlotStyleProps({ ...props }, renderProps)
+    const children = renderProps.children ?? defaultChildren
+    return cloneElement(render, merged as any, children)
+  }
+
+  return defaultElement
+}

package/src/helpers/webPropsToSkip.native.ts

@@ -0,0 +1,56 @@
+import { webOnlyStylePropsText, webOnlyStylePropsView } from '@hanzogui/helpers'
+
+// pointerEvents is in webOnlyStylePropsView for web CSS, but it's a valid
+// React Native View prop, so we exclude it from the skip list on native.
+// It's handled specially in getSplitStyles.tsx
+const { pointerEvents: _, ...webOnlyStylePropsViewWithoutPointerEvents } =
+  webOnlyStylePropsView
+
+/**
+ * Web-only props and event handlers that should be skipped on native
+ */
+export const webPropsToSkip = {
+  // Reuse web-only style props from webOnlyStyleProps (excluding pointerEvents)
+  ...webOnlyStylePropsViewWithoutPointerEvents,
+  ...webOnlyStylePropsText,
+
+  // Web-only event handlers
+  onClick: 1,
+  onDoubleClick: 1,
+  onContextMenu: 1,
+  onMouseEnter: 1,
+  onMouseLeave: 1,
+  onMouseMove: 1,
+  onMouseOver: 1,
+  onMouseOut: 1,
+  onMouseDown: 1,
+  onMouseUp: 1,
+  onWheel: 1,
+  onKeyDown: 1,
+  onKeyUp: 1,
+  onKeyPress: 1,
+  onPointerDown: 1,
+  onPointerMove: 1,
+  onPointerUp: 1,
+  onPointerCancel: 1,
+  onPointerEnter: 1,
+  onPointerLeave: 1,
+  onDrag: 1,
+  onDragStart: 1,
+  onDragEnd: 1,
+  onDragEnter: 1,
+  onDragLeave: 1,
+  onDragOver: 1,
+  onDrop: 1,
+  onChange: 1,
+  onInput: 1,
+  onBeforeInput: 1,
+  onScroll: 1,
+  onCopy: 1,
+  onCut: 1,
+  onPaste: 1,
+
+  // Other web-only props
+  htmlFor: 1,
+  dangerouslySetInnerHTML: 1,
+}

package/src/helpers/webPropsToSkip.ts

@@ -0,0 +1 @@
+export const webPropsToSkip = {}

package/src/helpers/wrapStyleTags.tsx

@@ -0,0 +1,31 @@
+import { StyleObjectIdentifier, StyleObjectRules } from '@hanzogui/helpers'
+import type { StyleObject } from '../types'
+
+// turns out this is pretty slow, creating a bunch of extra tags...
+
+export function getStyleTags(styles: StyleObject[]) {
+  if (process.env.HANZO_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>
+            )
+          })}
+        </>
+      )
+    }
+  }
+}

package/src/hooks/doesRootSchemeMatchSystem.native.ts

@@ -0,0 +1,7 @@
+import { Appearance } from 'react-native'
+import { getRootThemeState } from './useThemeState'
+
+export function doesRootSchemeMatchSystem() {
+  // only used on native for now
+  return getRootThemeState()?.scheme === Appearance.getColorScheme()
+}

package/src/hooks/doesRootSchemeMatchSystem.ts

@@ -0,0 +1,4 @@
+export function doesRootSchemeMatchSystem() {
+  // only used on native for now
+  return false
+}