@hanzogui/web 2.0.0

package/src/createFont.ts

@@ -0,0 +1,50 @@
+import type { FontWeightValues, GenericFont } from './types'
+
+const fontWeights: FontWeightValues[] = [
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '700',
+  '800',
+  '900',
+]
+
+const processSection = <T>(
+  section: string | Record<string, T>,
+  keys: string[],
+  defaultValue?: any
+): string | Record<string, T> => {
+  if (typeof section === 'string') return section
+
+  const sectionKeys = Object.keys(section)
+  let fillValue = section[sectionKeys[0]]
+
+  return Object.fromEntries(
+    [...new Set([...keys, ...sectionKeys])].map((key) => {
+      const value = section[key] ?? defaultValue ?? fillValue
+      fillValue = value
+      defaultValue = value
+      return [key, value]
+    })
+  )
+}
+
+export const createFont = <A extends GenericFont>(font: A): A => {
+  const sizeKeys = Object.keys(font.size || {})
+  const processedFont = Object.fromEntries(
+    Object.entries(font).map(([key, section]) => {
+      return [
+        key,
+        processSection(
+          section as any,
+          key === 'face' ? fontWeights : sizeKeys,
+          key === 'face' ? { normal: font.family } : undefined
+        ),
+      ]
+    })
+  )
+  return Object.freeze(processedFont) as A
+}

package/src/createGui.ts

@@ -0,0 +1,363 @@
+import { getConfigMaybe, setConfig, setTokens } from './config'
+import type { DeepVariableObject } from './createVariables'
+import { createVariables } from './createVariables'
+import { defaultAnimationDriver } from './helpers/defaultAnimationDriver'
+import { resolveAnimationDriver } from './helpers/resolveAnimationDriver'
+import {
+  buildCSSRuleSets,
+  createFontCSS,
+  createThemeCSS,
+  createTokenCSS,
+  getCSS as getCSSHelper,
+} from './helpers/createDesignSystem'
+import { scanAllSheets } from './helpers/insertStyleRule'
+import { proxyThemesToParents } from './helpers/proxyThemeToParents'
+import { ensureThemeVariable } from './helpers/themes'
+import { configureMedia } from './hooks/useMedia'
+import { parseFont, registerFontVariables } from './insertFont'
+import { Gui } from './Gui'
+import type {
+  CreateGuiProps,
+  DedupedTheme,
+  DedupedThemes,
+  GenericFont,
+  GetCSS,
+  InferGuiConfig,
+  GuiInternalConfig,
+  ThemeParsed,
+  ThemesLikeObject,
+  TokensMerged,
+  TokensParsed,
+  Variable,
+} from './types'
+
+/**
+ * Determines if a token category should have px units added.
+ * Following the principle: only add px to predefined categories that need them.
+ * Custom categories default to unitless.
+ */
+function shouldTokenCategoryHaveUnits(category: string): boolean {
+  // From TokenCategories type: 'color' | 'space' | 'size' | 'radius' | 'zIndex'
+  // These are the only predefined categories that should get px units
+  const UNIT_CATEGORIES = new Set(['size', 'space', 'radius'])
+
+  // Only add px to predefined dimensional categories
+  // Custom categories (like 'opacity', 'customWidth') default to unitless
+  return UNIT_CATEGORIES.has(category)
+}
+
+export function createGui<Conf extends CreateGuiProps>(
+  configIn: Conf
+): InferGuiConfig<Conf> {
+  // if config already exists (e.g., from another copy of hanzo-gui in vite ssr), reuse it
+  const existingConfig = getConfigMaybe()
+
+  if (existingConfig) {
+    // merge it and re-run since this new instance may add config
+    // or maybe a test case
+    configIn = { ...existingConfig, ...configIn }
+  }
+
+  // ensure variables
+  const tokensParsed: TokensParsed = {} as any
+  const tokens = createVariables(configIn.tokens || {})
+
+  if (configIn.tokens) {
+    // faster lookups
+    const tokensMerged: TokensMerged = {} as any
+    for (const cat in tokens) {
+      tokensParsed[cat] = {}
+      tokensMerged[cat] = {}
+      const tokenCat = tokens[cat]
+      for (const key in tokenCat) {
+        const val = tokenCat[key]
+        const prefixedKey = `$${key}`
+        tokensParsed[cat][prefixedKey] = val as any
+        tokensMerged[cat][prefixedKey] = val as any
+        tokensMerged[cat][key] = val as any
+      }
+    }
+    setTokens(tokensMerged)
+  }
+
+  let foundThemes: DedupedThemes | undefined
+  if (configIn.themes) {
+    const noThemes = Object.keys(configIn.themes).length === 0
+    if (noThemes && !process.env.HANZO_GUI_DID_OUTPUT_CSS) {
+      foundThemes = scanAllSheets(noThemes, tokensParsed)
+    }
+  }
+
+  let fontSizeTokens: Set<string> | null = null
+  let fontsParsed:
+    | {
+        [k: string]: DeepVariableObject<GenericFont<string>>
+      }
+    | undefined
+
+  if (configIn.fonts) {
+    const fontTokens = Object.fromEntries(
+      Object.entries(configIn.fonts).map(([k, v]) => {
+        return [k, createVariables(v, 'f', true)]
+      })
+    )
+
+    fontsParsed = (() => {
+      const res = {} as typeof fontTokens
+      for (const familyName in fontTokens) {
+        const font = fontTokens[familyName]
+        const fontParsed = parseFont(font)
+        res[`$${familyName}`] = fontParsed
+        if (!fontSizeTokens && fontParsed.size) {
+          fontSizeTokens = new Set(Object.keys(fontParsed.size))
+        }
+      }
+      return res!
+    })()
+  }
+
+  const specificTokens = {}
+
+  const themeConfig = (() => {
+    // populate specificTokens (needed for runtime)
+    const sortedTokenKeys = Object.keys(tokens).sort()
+    for (const key of sortedTokenKeys) {
+      const sortedSubKeys = Object.keys(tokens[key]).sort()
+      for (const skey of sortedSubKeys) {
+        const variable = tokens[key][skey] as any as Variable
+        specificTokens[`$${key}.${skey}`] = variable
+
+        if (process.env.NODE_ENV === 'development') {
+          if (typeof variable === 'undefined') {
+            throw new Error(
+              `No value for tokens.${key}.${skey}:\n${JSON.stringify(variable, null, 2)}`
+            )
+          }
+        }
+      }
+    }
+
+    // CSS generation (tree-shaken when HANZO_GUI_DID_OUTPUT_CSS is set)
+    const declarations = createTokenCSS(tokens as any, shouldTokenCategoryHaveUnits)
+    const fontDeclarations = createFontCSS(fontsParsed, registerFontVariables)
+    const cssRuleSets = buildCSSRuleSets(declarations, fontDeclarations)
+
+    const themesIn = configIn.themes as ThemesLikeObject
+    const dedupedThemes = foundThemes ?? getThemesDeduped(themesIn, tokens.color)
+    const themes = proxyThemesToParents(dedupedThemes)
+
+    return {
+      themes,
+      cssRuleSets,
+      getThemeRulesSets() {
+        return createThemeCSS(dedupedThemes, configIn)
+      },
+    }
+  })()
+
+  // Keep track of user-provided shorthands separately
+  const userShorthands = configIn.shorthands || {}
+
+  // Merge built-in shorthands with user shorthands (user takes precedence)
+  const shorthands = { ...builtinShorthands, ...userShorthands }
+
+  const lastCSSIndex = { value: -1 }
+
+  const getCSS: GetCSS = (opts = {}) => {
+    return getCSSHelper(themeConfig, opts, lastCSSIndex)
+  }
+
+  const getNewCSS: GetCSS = (opts) => getCSS({ ...opts, sinceLastCall: true })
+
+  const defaultFontSetting = configIn.settings?.defaultFont
+
+  const defaultFont = (() => {
+    let val = defaultFontSetting
+    if (val?.[0] === '$') {
+      val = val.slice(1)
+    }
+    return val
+  })()
+
+  const defaultPositionSetting = configIn.settings?.defaultPosition || 'static'
+
+  const defaultProps = configIn.defaultProps || {}
+  // apply defaultPosition via defaultProps when not static
+  if (process.env.HANZO_GUI_TARGET === 'web' && defaultPositionSetting !== 'static') {
+    defaultProps.View = {
+      ...defaultProps.View,
+      position: defaultPositionSetting,
+    }
+  }
+
+  // ensure prefixed with $
+  const defaultFontToken = defaultFont ? `$${defaultFont}` : ''
+
+  // Text inherits font from root via CSS, no need for default fontFamily
+  // only explicit fontFamily prop should add font_* class
+
+  // normalize multi-driver animation config to default driver
+  // supports format: { default: motionDriver, css: cssDriver }
+  // stores full config in animationDrivers for component-level selection via animatedBy
+  const inputAnimations = configIn.animations
+  const resolvedDriver = resolveAnimationDriver(inputAnimations)
+  // multi-driver when resolveAnimationDriver extracted .default (returned different ref)
+  const isMultiDriver = resolvedDriver !== null && resolvedDriver !== inputAnimations
+  const resolvedAnimations = resolvedDriver ?? inputAnimations
+  const animationDrivers = isMultiDriver
+    ? (inputAnimations as Record<string, any>)
+    : undefined
+
+  const config: GuiInternalConfig = {
+    fonts: {},
+    onlyAllowShorthands: false,
+    fontLanguages: [],
+    media: {},
+    ...configIn,
+    // normalized animations (resolved from multi-driver format if needed)
+    animations: resolvedAnimations ?? defaultAnimationDriver,
+    animationDrivers,
+    defaultProps,
+    settings: {
+      webContainerType: 'inline-size',
+      ...configIn.settings,
+    },
+    tokens: tokens as any,
+    // vite made this into a function if it wasn't set
+    shorthands,
+    userShorthands,
+    inverseShorthands: shorthands
+      ? Object.fromEntries(Object.entries(shorthands).map(([k, v]) => [v, k]))
+      : {},
+    themes: themeConfig.themes as any,
+    fontsParsed: fontsParsed || {},
+    themeConfig,
+    tokensParsed: tokensParsed as any,
+    parsed: true,
+    getNewCSS,
+    getCSS,
+    defaultFont,
+    fontSizeTokens: fontSizeTokens || new Set(),
+    specificTokens,
+    defaultFontToken,
+    // const tokens = [...getToken(tokens.size[0])]
+    // .spacer-sm + ._dsp_contents._dsp-sm-hidden { margin-left: -var(--${}) }
+  }
+
+  setConfig(config)
+  configureMedia(config)
+
+  if (process.env.NODE_ENV === 'development') {
+    if (process.env.DEBUG?.startsWith('@hanzo/gui')) {
+      console.info('Gui config:', config)
+    }
+    if (!globalThis['Gui']) {
+      globalThis['Gui'] = Gui
+    }
+  }
+
+  return config as any
+}
+
+// dedupes the themes if given them via JS config
+function getThemesDeduped(
+  themes: ThemesLikeObject,
+  colorTokens?: Record<string, any>
+): DedupedThemes {
+  const dedupedThemes: DedupedThemes = []
+  const existing = new Map<string, DedupedTheme>()
+
+  // Sort theme names for deterministic CSS output order
+  const sortedThemeNames = Object.keys(themes).sort()
+
+  // first, de-dupe and parse them
+  for (const themeName of sortedThemeNames) {
+    // forces us to separate the dark/light themes (otherwise we generate bad t_light prefix selectors)
+    const darkOrLightSpecificPrefix = themeName.startsWith('dark')
+      ? 'dark'
+      : themeName.startsWith('light')
+        ? 'light'
+        : ''
+
+    const rawTheme = themes[themeName]
+
+    // dont force referential equality but may need something more consistent than JSON.stringify
+    // separate between dark/light
+    const key = darkOrLightSpecificPrefix + JSON.stringify(rawTheme)
+
+    // if existing, avoid
+    if (existing.has(key)) {
+      const e = existing.get(key)!
+      e.names.push(themeName)
+      continue
+    }
+
+    // ensure each theme object unique for dedupe
+    // is ThemeParsed because we call ensureThemeVariable
+    // color tokens are spread first as fallbacks, theme values take precedence
+    const theme = { ...colorTokens, ...rawTheme } as any as ThemeParsed
+
+    // parse into variables
+    for (const key in theme) {
+      // make sure properly names theme variables
+      ensureThemeVariable(theme, key)
+    }
+
+    // set deduped
+    const deduped: DedupedTheme = {
+      names: [themeName],
+      theme,
+    }
+    dedupedThemes.push(deduped)
+    existing.set(key, deduped)
+  }
+
+  return dedupedThemes
+}
+
+// Built-in shorthands used internally for short classname generation
+const builtinShorthands = {
+  bblr: 'borderBottomLeftRadius',
+  bbrr: 'borderBottomRightRadius',
+  bbs: 'borderBottomStyle',
+  bls: 'borderLeftStyle',
+  brc: 'borderRightColor',
+  brs: 'borderRightStyle',
+  brw: 'borderRightWidth',
+  bs: 'borderStyle',
+  btc: 'borderTopColor',
+  btlr: 'borderTopLeftRadius',
+  btrr: 'borderTopRightRadius',
+  bts: 'borderTopStyle',
+  btw: 'borderTopWidth',
+  bw: 'borderWidth',
+  bxs: 'boxSizing',
+  bxsh: 'boxShadow',
+  col: 'color',
+  cur: 'cursor',
+  dsp: 'display',
+  fb: 'flexBasis',
+  fd: 'flexDirection',
+  ff: 'fontFamily',
+  fs: 'fontSize',
+  fst: 'fontStyle',
+  fw: 'fontWeight',
+  fwr: 'flexWrap',
+  // height: 'h',
+  lh: 'lineHeight',
+  ls: 'letterSpacing',
+  o: 'opacity',
+  ov: 'overflow',
+  ox: 'overflowX',
+  oy: 'overflowY',
+  pe: 'pointerEvents',
+  pos: 'position',
+  td: 'textDecorationLine',
+  tr: 'transform',
+  tt: 'textTransform',
+  va: 'verticalAlign',
+  wb: 'wordBreak',
+  // width: 'w',
+  ws: 'whiteSpace',
+  ww: 'wordWrap',
+} as const

package/src/createShorthands.ts

@@ -0,0 +1,7 @@
+import type { CreateShorthands } from './types'
+
+// just a type helper util
+
+export function createShorthands<A extends CreateShorthands>(shorthands: A): A {
+  return Object.freeze(shorthands) as any
+}

package/src/createTokens.ts

@@ -0,0 +1,31 @@
+import { createVariables } from './createVariables'
+import type { CreateTokens, Variable } from './types'
+
+export function createTokens<T extends CreateTokens>(tokens: T): MakeTokens<T> {
+  return createVariables(tokens, process.env.HANZO_GUI_TOKEN_PREFIX ?? 't') as any
+}
+
+type NormalizeTokens<A, Type = A[keyof A]> = {
+  [Key in keyof A as Key extends number ? `${Key}` : Key]: Variable<Type>
+}
+
+type MakeTokens<T extends CreateTokens> = T extends {
+  color?: infer E
+  space?: infer F
+  size?: infer G
+  radius?: infer H
+  zIndex?: infer J
+}
+  ? {
+      color: NormalizeTokens<E, string>
+      space: NormalizeTokens<F, number>
+      size: NormalizeTokens<G, number>
+      radius: NormalizeTokens<H, number>
+      zIndex: NormalizeTokens<J, number>
+    } & Omit<
+      {
+        [key in keyof T]: NormalizeTokens<T[key]>
+      },
+      'color' | 'space' | 'size' | 'radius' | 'zIndex'
+    >
+  : never

package/src/createVariable.ts

@@ -0,0 +1,121 @@
+import { isWeb } from '@hanzogui/constants'
+import { simpleHash } from '@hanzogui/helpers'
+
+import { getConfig } from './config'
+import type { PxValue, TokenCategories, Variable } from './types'
+
+/**
+ * Should rename this to Token
+ * Moving to objects for React Server Components support
+ */
+
+function constructCSSVariableName(name: string) {
+  return `var(--${process.env.HANZO_GUI_CSS_VARIABLE_PREFIX || ''}${name})`
+}
+
+type VariableIn<A = any> = Pick<Variable<A>, 'key' | 'name' | 'val'>
+
+export const createVariable = <A extends string | number | Variable = any>(
+  props: VariableIn<A>,
+  skipHash = false
+): Variable<A> => {
+  if (!skipHash && isVariable(props)) return props
+  const { key, name, val } = props
+  return {
+    isVar: true,
+    key,
+    name: skipHash ? name : simpleHash(name, 40),
+    val,
+    variable: isWeb
+      ? skipHash
+        ? constructCSSVariableName(name)
+        : createCSSVariable(name)
+      : '',
+  }
+}
+
+// could do weakmap cache
+export function variableToString(vrble?: any, getValue = false) {
+  if (isVariable(vrble)) {
+    if (!getValue && isWeb && vrble.variable) {
+      return vrble.variable
+    }
+    return `${vrble.val}`
+  }
+  return `${vrble || ''}`
+}
+
+export function isVariable(v: Variable | any): v is Variable {
+  return v && typeof v === 'object' && 'isVar' in v
+}
+
+export function getVariable(
+  nameOrVariable: Variable | string | any,
+  group: TokenCategories = 'size'
+) {
+  // dynamic color-like
+  if (nameOrVariable?.dynamic) {
+    return nameOrVariable
+  }
+  setDidGetVariableValue(true)
+  if (isVariable(nameOrVariable)) {
+    return variableToString(nameOrVariable)
+  }
+  const tokens = getConfig().tokensParsed
+  return variableToString(tokens[group]?.[nameOrVariable] ?? nameOrVariable)
+}
+
+let accessed = false
+export const setDidGetVariableValue = (val: boolean) => (accessed = val)
+export const didGetVariableValue = () => accessed
+
+export function getVariableValue(v: Variable | any, group?: TokenCategories) {
+  if (isVariable(v)) {
+    setDidGetVariableValue(true)
+    return v.val
+  }
+  if (group) {
+    const tokens = getConfig().tokensParsed
+    const token = tokens[group]?.[v]
+    if (token) {
+      setDidGetVariableValue(true)
+      return token.val
+    }
+  }
+  return v
+}
+
+export function getVariableName(v: Variable | any) {
+  if (isVariable(v)) return v.name
+  return v
+}
+
+export function getVariableVariable(v: Variable | string | undefined) {
+  if (isVariable(v)) return v.variable
+  return v
+}
+
+// bugfix { space: { 0.5: 10 } } was generating var(--space-0.5) (invalid CSS):
+export const createCSSVariable = (nameProp: string, includeVar = true) => {
+  if (process.env.NODE_ENV === 'development') {
+    if (!nameProp || typeof nameProp !== 'string') {
+      throw new Error(`createCSSVariable expected string, got: ${nameProp}`)
+    }
+  }
+  const name = simpleHash(nameProp, 60)
+  return includeVar ? constructCSSVariableName(name) : name
+}
+
+/**
+ * Helper function to mark a token value as needing px units.
+ * Usage: px(100) creates a token that will become "100px" on web, 100 on native.
+ *
+ * @param value - The numeric value
+ * @returns A special object that indicates this value needs px units
+ */
+export function px(value: number): PxValue {
+  return {
+    val: value,
+    needsPx: true,
+  }
+}

package/src/createVariables.ts

@@ -0,0 +1,78 @@
+import { isWeb } from '@hanzogui/constants'
+import { simpleHash } from '@hanzogui/helpers'
+import { createVariable, isVariable } from './createVariable'
+import type { Variable } from './types'
+
+type DeepTokenObject<Val extends string | number = any> = {
+  [key: string]: Val | DeepTokenObject<Val>
+}
+
+export type DeepVariableObject<A extends DeepTokenObject> = {
+  [Key in keyof A]: A[Key] extends string | number
+    ? Variable<A[Key]>
+    : A[Key] extends DeepTokenObject
+      ? DeepVariableObject<A[Key]>
+      : never
+}
+
+const cache = new WeakMap()
+
+// recursive...
+
+export const createVariables = <A extends DeepTokenObject>(
+  tokens: A,
+  parentPath = '',
+  isFont = false
+): DeepVariableObject<A> => {
+  if (cache.has(tokens)) return tokens
+
+  const res: any = {}
+  let i = 0
+  for (let keyIn in tokens) {
+    i++
+    const val = tokens[keyIn]
+    const isPrefixed = keyIn[0] === '$'
+    const keyWithPrefix = isPrefixed ? keyIn : `$${keyIn}`
+    const key = isPrefixed ? keyWithPrefix.slice(1) : keyIn
+
+    if (isVariable(val)) {
+      res[key] = val
+      continue
+    }
+    const niceKey = simpleHash(key, 1000)
+    const name =
+      parentPath && parentPath !== 't-color' ? `${parentPath}-${niceKey}` : `c-${niceKey}`
+
+    // Handle px() helper objects
+    if (val && typeof val === 'object' && 'needsPx' in val && 'val' in val) {
+      const finalValue = createVariable({
+        val: val.val,
+        name,
+        key: keyWithPrefix,
+      })
+      // Only set needsPx flag on web platform, avoid on native
+      if (isWeb) {
+        finalValue.needsPx = val.needsPx
+      }
+      res[key] = finalValue
+      continue
+    }
+
+    if (val && typeof val === 'object') {
+      // recurse
+      res[key] = createVariables(
+        tokens[key] as any,
+        name,
+        false /* note: don't pass isFont down, we want to avoid it past the first level */
+      )
+      continue
+    }
+    const finalValue = isVariable(val)
+      ? val
+      : createVariable({ val, name, key: keyWithPrefix })
+    res[key] = finalValue
+  }
+
+  cache.set(res, true)
+  return res
+}

package/src/defaultComponentState.tsx

@@ -0,0 +1,22 @@
+import type { GuiComponentState } from './types'
+
+export const defaultComponentState: GuiComponentState = {
+  hover: false,
+  press: false,
+  pressIn: false,
+  focus: false,
+  focusVisible: false,
+  focusWithin: false,
+  unmounted: true,
+  disabled: false,
+}
+
+export const defaultComponentStateMounted: GuiComponentState = {
+  ...defaultComponentState,
+  unmounted: false,
+}
+
+export const defaultComponentStateShouldEnter: GuiComponentState = {
+  ...defaultComponentState,
+  unmounted: 'should-enter',
+}