@hanzogui/web 2.0.0

package/src/animationDriverTypes.test-d.ts

@@ -0,0 +1,332 @@
+/**
+ * Type tests for animatedBy prop and animation driver configuration.
+ *
+ * These tests ensure type-safe inference for:
+ * 1. Single animation driver config
+ * 2. Multiple animation drivers config
+ * 3. TypeOverride for lazy-loaded drivers
+ * 4. Combination scenarios
+ *
+ * Run with: yarn test:types
+ */
+
+import { expectTypeOf, describe, test } from 'vitest'
+import type {
+  AnimationDriver,
+  AnimationDriverKeys,
+  AnimationsConfig,
+  AnimationsConfigObject,
+  CreateGuiConfig,
+  TransitionKeys,
+  TypeOverride,
+  GuiComponentPropsBaseBase,
+} from './types'
+
+// =============================================================================
+// Mock types for testing
+// =============================================================================
+
+type MockCSSAnimations = { slow: any; fast: any }
+type MockSpringAnimations = { bouncy: any; stiff: any }
+
+type MockCSSDriver = AnimationDriver<MockCSSAnimations>
+type MockSpringDriver = AnimationDriver<MockSpringAnimations>
+
+// =============================================================================
+// Test: AnimationsConfig types
+// =============================================================================
+
+describe('AnimationsConfig types', () => {
+  test('AnimationsConfig accepts single driver', () => {
+    expectTypeOf<MockCSSDriver>().toMatchTypeOf<AnimationsConfig>()
+  })
+
+  test('AnimationsConfig accepts multi-driver object', () => {
+    type MultiDriver = {
+      default: MockCSSDriver
+      spring: MockSpringDriver
+    }
+    expectTypeOf<MultiDriver>().toMatchTypeOf<AnimationsConfig>()
+  })
+
+  test('AnimationsConfigObject requires default key', () => {
+    type ValidConfig = {
+      default: MockCSSDriver
+      spring: MockSpringDriver
+    }
+    expectTypeOf<ValidConfig>().toMatchTypeOf<AnimationsConfigObject>()
+
+    // This should fail - no default key
+    type InvalidConfig = {
+      spring: MockSpringDriver
+    }
+    // @ts-expect-error - missing default key
+    expectTypeOf<InvalidConfig>().toMatchTypeOf<AnimationsConfigObject>()
+  })
+})
+
+// =============================================================================
+// Test: CreateGuiConfig preserves animation shape
+// =============================================================================
+
+describe('CreateGuiConfig animation types', () => {
+  test('CreateGuiConfig.animations accepts single driver', () => {
+    type Config = CreateGuiConfig<any, any, any, any, MockCSSAnimations, any>
+    type Animations = Config['animations']
+
+    // Should be a union of AnimationDriver<E> | AnimationsConfigObject
+    // Single driver should be assignable to this union
+    const _driver: Animations = {} as MockCSSDriver
+  })
+
+  test('CreateGuiConfig.animations accepts multi-driver object', () => {
+    type Config = CreateGuiConfig<any, any, any, any, MockCSSAnimations, any>
+    type Animations = Config['animations']
+
+    // Multi-driver object should also be assignable
+    type MultiDriver = {
+      default: MockCSSDriver
+      spring: MockSpringDriver
+    }
+    const _multi: Animations = {} as MultiDriver
+  })
+})
+
+// =============================================================================
+// Test: TransitionKeys inference
+// =============================================================================
+
+describe('TransitionKeys inference', () => {
+  test('TransitionKeys type exists and is string-based', () => {
+    // TransitionKeys should be a string union of animation names
+    expectTypeOf<TransitionKeys>().toMatchTypeOf<string>()
+  })
+})
+
+// =============================================================================
+// Test: AnimationDriverKeys inference
+// =============================================================================
+
+describe('AnimationDriverKeys inference', () => {
+  test('AnimationDriverKeys is string or string union', () => {
+    // Should be at least 'default'
+    expectTypeOf<'default'>().toMatchTypeOf<AnimationDriverKeys>()
+  })
+
+  test('TypeOverride.animationDrivers exists in interface', () => {
+    // TypeOverride should have animationDrivers method
+    type AnimDriversFn = TypeOverride['animationDrivers']
+    expectTypeOf<AnimDriversFn>().toBeFunction()
+  })
+
+  /**
+   * FIXED: AnimationDriverKeys now combines inferred keys with TypeOverride.
+   *
+   * New implementation:
+   *   'default'
+   *   | InferredAnimationDriverKeys
+   *   | (ReturnType<TypeOverride['animationDrivers']> extends 1 ? never : ReturnType<...>)
+   *
+   * This ensures both config-defined drivers AND lazy-loaded drivers are available.
+   */
+  test('AnimationDriverKeys always includes default', () => {
+    // 'default' is always available regardless of config
+    expectTypeOf<'default'>().toMatchTypeOf<AnimationDriverKeys>()
+  })
+})
+
+// =============================================================================
+// Test: animatedBy prop on components
+// =============================================================================
+
+describe('animatedBy prop', () => {
+  test('animatedBy exists on GuiComponentPropsBaseBase', () => {
+    type Props = GuiComponentPropsBaseBase
+    expectTypeOf<Props>().toHaveProperty('animatedBy')
+  })
+
+  test('animatedBy accepts null', () => {
+    type Props = GuiComponentPropsBaseBase
+    type AnimatedBy = Props['animatedBy']
+    expectTypeOf<null>().toMatchTypeOf<AnimatedBy>()
+  })
+
+  test('animatedBy accepts "default"', () => {
+    type Props = GuiComponentPropsBaseBase
+    type AnimatedBy = NonNullable<Props['animatedBy']>
+    expectTypeOf<'default'>().toMatchTypeOf<AnimatedBy>()
+  })
+
+  /**
+   * IMPORTANT: This test verifies the full type inference chain for multi-driver configs.
+   *
+   * When user configures: animations: { default: motionDriver, css: cssDriver }
+   * The animatedBy prop should accept: 'default' | 'css' | null
+   *
+   * The type flow is:
+   * 1. CreateGuiProps.animations accepts multi-driver object
+   * 2. InferGuiConfig extracts driver keys via ExtractAnimationDriverKeys
+   * 3. GuiInternalConfig stores keys in AnimDriverKeys generic param
+   * 4. GuiCustomConfig extends the inferred config type
+   * 5. GuiConfig merges with GuiCustomConfig
+   * 6. InferredAnimationDriverKeys reads from GuiConfig['animationDriverKeys']
+   * 7. AnimationDriverKeys combines inferred + TypeOverride
+   * 8. animatedBy uses AnimationDriverKeys
+   */
+  test('multi-driver config type flow preserves all driver keys', () => {
+    // internal helper mirrors the one in types.tsx
+    type ExtractAnimationDriverKeys<E> =
+      E extends AnimationDriver<any>
+        ? 'default'
+        : E extends { default: AnimationDriver<any> }
+          ? Extract<keyof E, string>
+          : 'default'
+
+    // simulate multi-driver config
+    type MultiDriverConfig = {
+      default: MockCSSDriver
+      css: MockSpringDriver
+    }
+
+    // should extract both keys
+    type ExtractedKeys = ExtractAnimationDriverKeys<MultiDriverConfig>
+    expectTypeOf<'default'>().toMatchTypeOf<ExtractedKeys>()
+    expectTypeOf<'css'>().toMatchTypeOf<ExtractedKeys>()
+  })
+})
+
+// =============================================================================
+// Test: Type regression scenarios
+// =============================================================================
+
+describe('Type regression scenarios', () => {
+  /**
+   * Scenario 1: Single driver config
+   * User sets: animations: cssDriver
+   * Expected animatedBy values: 'default' only
+   * Expected transition values: keys from cssDriver's animations
+   */
+  test('single driver config scenario', () => {
+    // animatedBy should only allow 'default' since there's one driver
+    // This is correct behavior
+  })
+
+  /**
+   * Scenario 2: Multiple drivers config
+   * User sets: animations: { default: css, spring: moti, physics: reanimated }
+   * Expected animatedBy values: 'default' | 'spring' | 'physics'
+   * Expected transition values: keys from default driver's animations
+   *
+   * FIXED: CreateGuiConfig.animations now accepts AnimationsConfigObject
+   * which preserves the multi-driver shape for type inference.
+   */
+  test('multiple drivers config scenario - CreateGuiConfig accepts it', () => {
+    type Config = CreateGuiConfig<any, any, any, any, MockCSSAnimations, any>
+    type Animations = Config['animations']
+
+    // Multi-driver config is now accepted
+    type MultiDriverConfig = {
+      default: MockCSSDriver
+      spring: MockSpringDriver
+    }
+    const _config: Animations = {} as MultiDriverConfig
+  })
+
+  /**
+   * Scenario 3: TypeOverride for lazy loading
+   * User uses TypeOverride to add 'lazySpring' driver loaded at runtime
+   * Expected animatedBy values: inferred keys + 'lazySpring'
+   *
+   * FIXED: AnimationDriverKeys now always includes:
+   * - 'default' (always)
+   * - InferredAnimationDriverKeys (from config)
+   * - TypeOverride keys (when defined)
+   */
+  test('TypeOverride combines with inferred', () => {
+    // Both inferred and override keys should be included
+    // 'default' is always available
+    expectTypeOf<'default'>().toMatchTypeOf<AnimationDriverKeys>()
+  })
+
+  /**
+   * Scenario 4: Both multiple drivers + TypeOverride
+   * Config: { default: css, spring: moti }
+   * Override: 'physics'
+   * Expected: 'default' | 'spring' | 'physics'
+   *
+   * FIXED: The union type combines all sources
+   */
+  test('combined multiple drivers and override', () => {
+    // All keys should be available from both sources
+    // Note: actual inference depends on user's GuiConfig setup
+    expectTypeOf<'default'>().toMatchTypeOf<AnimationDriverKeys>()
+  })
+})
+
+// =============================================================================
+// Documentation: Applied fixes
+// =============================================================================
+
+// =============================================================================
+// Test: ExtractAnimationDriverKeys helper
+// =============================================================================
+
+describe('ExtractAnimationDriverKeys helper', () => {
+  // Internal helper type for testing - mirrors the one in types.tsx
+  type ExtractAnimationDriverKeys<E> =
+    E extends AnimationDriver<any>
+      ? 'default'
+      : E extends { default: AnimationDriver<any> }
+        ? Extract<keyof E, string>
+        : 'default'
+
+  test('single driver returns "default"', () => {
+    type Result = ExtractAnimationDriverKeys<MockCSSDriver>
+    expectTypeOf<Result>().toEqualTypeOf<'default'>()
+  })
+
+  test('multi-driver returns all keys', () => {
+    type MultiDriverConfig = {
+      default: MockCSSDriver
+      spring: MockSpringDriver
+    }
+    type Result = ExtractAnimationDriverKeys<MultiDriverConfig>
+    expectTypeOf<'default'>().toMatchTypeOf<Result>()
+    expectTypeOf<'spring'>().toMatchTypeOf<Result>()
+  })
+
+  test('multi-driver with css key returns all keys', () => {
+    type MultiDriverConfig = {
+      default: MockCSSDriver
+      css: MockSpringDriver
+    }
+    type Result = ExtractAnimationDriverKeys<MultiDriverConfig>
+    expectTypeOf<'default'>().toMatchTypeOf<Result>()
+    expectTypeOf<'css'>().toMatchTypeOf<Result>()
+  })
+})
+
+/**
+ * SUMMARY OF APPLIED TYPE FIXES:
+ *
+ * 1. CreateGuiConfig (line ~737):
+ *    FIXED: Changed from `animations: AnimationDriver<E>`
+ *    To: `animations: AnimationDriver<E> | AnimationsConfigObject`
+ *    This preserves the multi-driver object shape for type inference.
+ *
+ * 2. AnimationDriverKeys (line ~888-895):
+ *    FIXED: Changed from conditional (inferred OR override)
+ *    To: Union of all sources:
+ *      | 'default'
+ *      | InferredAnimationDriverKeys
+ *      | (TypeOverride extends 1 ? never : TypeOverride)
+ *    This ensures both config-defined AND lazy-loaded drivers are available.
+ *
+ * 3. InferredAnimationDriverKeys (line 879-886):
+ *    No changes needed - works correctly with the above fixes.
+ *    Properly infers 'default' for single driver and keyof for multi-driver.
+ *
+ * 4. TransitionKeys (line 868-876):
+ *    No changes needed - already handles both single and multi-driver cases.
+ *    Uses default driver's config for animation names.
+ */

package/src/config.ts

@@ -0,0 +1,232 @@
+import { isWeb } from '@hanzogui/constants'
+import { MISSING_THEME_MESSAGE } from './constants/constants'
+import type {
+  AnimationDriver,
+  ConfigListener,
+  GenericGuiSettings,
+  GuiInternalConfig,
+  Token,
+  Tokens,
+  TokensMerged,
+} from './types'
+
+let conf: GuiInternalConfig | null
+let setConfigCalledByThisInstance = false
+
+const haventCalledErrorMessage =
+  process.env.NODE_ENV === 'development'
+    ? `
+Haven't called createGui yet. ${MISSING_THEME_MESSAGE}
+`
+    : `❌ Error 001`
+
+// helper to get config from module-scoped variable or globalthis fallback
+// this handles vite ssr bundling where multiple copies of hanzo-gui may exist
+const getConfigFromGlobalOrLocal = (): GuiInternalConfig | null => {
+  if (conf) {
+    return conf
+  }
+
+  // fall back to globalthis (for vite ssr bundling scenarios)
+  if (globalThis.__guiConfig) {
+    // defer warning - if createGui runs in THIS instance, it's HMR (safe)
+    // if it never runs, it's a true duplicate (warn)
+    if (
+      process.env.NODE_ENV === 'development' &&
+      !globalThis.__guiHasWarnedGlobalFallback &&
+      !globalThis.__guiPendingCheck
+    ) {
+      globalThis.__guiPendingCheck = true
+      setTimeout(() => {
+        if (
+          !setConfigCalledByThisInstance &&
+          !globalThis.__guiHasWarnedGlobalFallback
+        ) {
+          globalThis.__guiHasWarnedGlobalFallback = true
+          console.warn(
+            `⚠️⚠️⚠️⚠️⚠️
+
+Hanzo GUI: Using global config fallback. This may indicate duplicate gui instances (e.g., from Vite SSR bundling). This is handled automatically, but likely causes issues!
+
+⚠️⚠️⚠️⚠️⚠️`
+          )
+        }
+        globalThis.__guiPendingCheck = false
+      }, 500)
+    }
+    return globalThis.__guiConfig
+  }
+
+  return null
+}
+
+export const getSetting = <Key extends keyof GenericGuiSettings>(
+  key: Key
+): GenericGuiSettings[Key] => {
+  const config = getConfigFromGlobalOrLocal()
+  if (process.env.NODE_ENV === 'development') {
+    if (!config) throw new Error(haventCalledErrorMessage)
+  }
+  return (
+    config!.settings[key] ??
+    // @ts-expect-error
+    config[key]
+  )
+}
+
+export const setConfig = (next: GuiInternalConfig) => {
+  setConfigCalledByThisInstance = true
+  conf = next
+  globalThis.__guiConfig = next
+}
+
+export const setConfigFont = (name: string, font: any, fontParsed: any) => {
+  const config = getConfigFromGlobalOrLocal()
+  if (process.env.NODE_ENV === 'development') {
+    if (!config) throw new Error(haventCalledErrorMessage)
+  }
+  config!.fonts[name] = font
+  config!.fontsParsed[`$${name}`] = fontParsed
+}
+
+export const getConfig = () => {
+  const config = getConfigFromGlobalOrLocal()
+  if (!config) {
+    throw new Error(
+      process.env.NODE_ENV !== 'production'
+        ? `Missing gui config, you either have a duplicate config, or haven't set it up. Be sure createGui is called before rendering. Also, make sure all of your hanzo-gui dependencies are on the same version (\`gui\`, \`@hanzogui/package-name\`, etc.) not just in your package.json, but in your lockfile.`
+        : 'Err0'
+    )
+  }
+  return config
+}
+
+export const getConfigMaybe = () => {
+  return getConfigFromGlobalOrLocal()
+}
+
+let tokensMerged: TokensMerged
+export function setTokens(_: TokensMerged) {
+  tokensMerged = _
+}
+
+export const getTokens = ({
+  prefixed,
+}: {
+  /**
+   * Force either with $ or without $ prefix
+   */
+  prefixed?: boolean
+} = {}): TokensMerged => {
+  const config = getConfigFromGlobalOrLocal()
+  if (process.env.NODE_ENV === 'development') {
+    if (!config) throw new Error(haventCalledErrorMessage)
+  }
+  const { tokens, tokensParsed } = config!
+  if (prefixed === false) return tokens as any
+  if (prefixed === true) return tokensParsed as any
+  return tokensMerged
+}
+
+export const getTokenObject = (value: Token, group?: keyof Tokens) => {
+  const config = getConfigFromGlobalOrLocal()
+  return (
+    config!.specificTokens[value] ??
+    (group
+      ? tokensMerged[group]?.[value]
+      : tokensMerged[
+          Object.keys(tokensMerged).find((cat) => tokensMerged[cat][value]) || ''
+        ]?.[value])
+  )
+}
+
+export const getToken = (value: Token, group?: keyof Tokens, useVariable = isWeb) => {
+  const token = getTokenObject(value, group)
+  return useVariable ? token?.variable : token?.val
+}
+
+export const getTokenValue = (value: Token | 'unset' | 'auto', group?: keyof Tokens) => {
+  if (value === 'unset' || value === 'auto') return
+  return getToken(value, group, false)
+}
+
+/**
+ * Note: this is the same as `getTokens`
+ */
+export const useTokens = getTokens
+
+export const getThemes = () => getConfigFromGlobalOrLocal()!.themes
+
+export const updateConfig = (key: string, value: any) => {
+  // for usage internally only
+  const config = getConfigFromGlobalOrLocal()
+  Object.assign(config![key], value)
+}
+
+// searches by value name or token name
+export const getFont = (name: string) => {
+  const conf = getConfig()
+  return (
+    conf.fontsParsed[name] ??
+    Object.entries(conf.fontsParsed).find(
+      ([k]) => conf.fontsParsed[k]?.family?.['val'] === name
+    )?.[1]
+  )
+}
+
+type DevConfig = {
+  visualizer?:
+    | boolean
+    | {
+        key?: string
+        delay?: number
+      }
+}
+
+export let devConfig: DevConfig | undefined
+
+export function setupDev(conf: DevConfig) {
+  if (process.env.NODE_ENV === 'development') {
+    devConfig = conf
+  }
+}
+
+/**
+ * Dynamically load an animation driver at runtime.
+ * Useful for lazy loading heavier animation drivers after initial page load.
+ *
+ * @example
+ * ```tsx
+ * // import loadAnimationDriver from gui
+ * // import createAnimations from your preferred driver (e.g. animations-reanimated)
+ *
+ * const driver = createAnimations({ bouncy: { type: 'spring', damping: 10 } })
+ * loadAnimationDriver('spring', driver)
+ * ```
+ */
+export function loadAnimationDriver(name: string, driver: AnimationDriver) {
+  const config = getConfigFromGlobalOrLocal()
+  if (!config) {
+    if (process.env.NODE_ENV === 'development') {
+      console.warn('loadAnimationDriver called before createGui')
+    }
+    return
+  }
+
+  // Convert single driver to object format if needed
+  if (config.animations && !('default' in config.animations)) {
+    ;(config as any).animations = {
+      default: config.animations,
+    }
+  }
+
+  // Add the new driver
+  if (config.animations) {
+    ;(config.animations as Record<string, any>)[name] = driver
+  } else {
+    ;(config as any).animations = {
+      default: driver,
+      [name]: driver,
+    }
+  }
+}

package/src/constants/accessibilityDirectMap.native.tsx

@@ -0,0 +1,10 @@
+export const accessibilityDirectMap = {}
+
+export const webToNativeAccessibilityDirectMap = {}
+
+export const nativeAccessibilityValue = {}
+
+export const nativeAccessibilityState = {}
+
+// Note: left side is not always web role, for example togglebutton
+export const accessibilityWebRoleToNativeRole = {}

package/src/constants/accessibilityDirectMap.tsx

@@ -0,0 +1,11 @@
+// v2: RN accessibility props are no longer converted
+// Users should use web-standard aria-* props directly (aria-label, role, etc.)
+// See https://gui.hanzo.ai/docs/intro/version-two for migration guide
+
+export const accessibilityDirectMap: Record<string, string> = {}
+
+export const webToNativeAccessibilityDirectMap = null as unknown as Record<string, string>
+export const nativeAccessibilityValue = null as unknown as Record<string, string>
+
+export const nativeAccessibilityState = null as unknown as Record<string, string>
+export const accessibilityWebRoleToNativeRole = null as unknown as Record<string, string>

package/src/constants/constants.ts

@@ -0,0 +1,16 @@
+import type { StackStyle } from '../types'
+
+export const THEME_NAME_SEPARATOR = '_'
+export const THEME_CLASSNAME_PREFIX = 't_'
+export const FONT_DATA_ATTRIBUTE_NAME = 'data-gui-font'
+
+export const MISSING_THEME_MESSAGE =
+  process.env.NODE_ENV === 'development'
+    ? `Can't find Hanzo GUI configuration.
+    
+Most of the time this is due to having mis-matched versions of Hanzo GUI dependencies, or bundlers somehow duplicating them.
+First step is to ensure every "@hanzo/gui" and "@hanzogui/*" dependency is on the same version, we have a CLI tool to help: 
+
+  npx @hanzogui/cli check
+`
+    : `Missing theme.`

package/src/constants/isDevTools.ts

@@ -0,0 +1,12 @@
+// for verbose logging outside node/cli
+
+export const isDevTools = (() => {
+  if (process.env.NODE_ENV === 'development') {
+    try {
+      return new Function('try {return this===window;}catch(e){ return false;}')()
+    } catch {
+      //
+    }
+  }
+  return false
+})()

package/src/contexts/ComponentContext.tsx

@@ -0,0 +1,16 @@
+import { useContext } from 'react'
+import { createStyledContext } from '../helpers/createStyledContext'
+import type { ComponentContextI } from '../types'
+
+export const ComponentContext = createStyledContext<ComponentContextI>({
+  disableSSR: undefined,
+  inText: false,
+  language: null,
+  animationDriver: null,
+  setParentFocusState: null,
+  insets: null,
+})
+
+export const useConfiguration = () => {
+  return useContext(ComponentContext)
+}

package/src/contexts/GroupContext.tsx

@@ -0,0 +1,4 @@
+import { createContext } from 'react'
+import type { AllGroupContexts } from '../types'
+
+export const GroupContext = createContext<AllGroupContexts | null>(null)