@hanzogui/static 7.3.0 → 8.0.0

package/src/extractor/extractToClassNames.ts

@@ -98,7 +98,7 @@ export async function extractToClassNames({
   tm.mark(`babel-parse`, shouldPrintDebug === 'verbose')
 
   const cssMap = new Map<string, { css: string; commentTexts: string[] }>()
-  const guiConfig = extractor.getGui()!
+  const hanzoguiConfig = extractor.getGui()!
 
   const res = await extractor.parse(ast, {
     shouldPrintDebug,
@@ -170,6 +170,75 @@ export async function extractToClassNames({
         originalNodeName
       )
 
+      // detect static `group="<name>"` literal — runtime side normally emits the
+      // container-name/container-type CSS lazily via getSplitStyles (createComponent
+      // path), but extracted elements never go through that code, so we emit the
+      // equivalent CSS at compile time and add `t_group_<name>` to the className.
+      let staticGroupName: string | null = null
+      for (const attr of jsxPath.node.openingElement.attributes) {
+        if (!t.isJSXAttribute(attr) || !t.isJSXIdentifier(attr.name)) continue
+        if (attr.name.name !== 'group') continue
+        if (t.isStringLiteral(attr.value)) {
+          staticGroupName = attr.value.value
+        } else if (
+          t.isJSXExpressionContainer(attr.value) &&
+          t.isStringLiteral(attr.value.expression)
+        ) {
+          staticGroupName = attr.value.expression.value
+        }
+        // dynamic group={someProp} falls back to the runtime path.
+        break
+      }
+      if (staticGroupName) {
+        const containerIdentifier = `t_group_${staticGroupName}`
+        const containerType =
+          (hanzoguiConfig.settings?.webContainerType as string | undefined) ||
+          'inline-size'
+        const containerSelector = `.${containerIdentifier}`
+        if (!cssMap.has(containerSelector)) {
+          cssMap.set(containerSelector, {
+            css: `${containerSelector} { container-name: ${staticGroupName}; container-type: ${containerType}; }`,
+            commentTexts: [comment],
+          })
+        } else {
+          cssMap.get(containerSelector)!.commentTexts.push(comment)
+        }
+      }
+
+      // invariant guard for $group-/$theme- CSS extraction (below): those styles
+      // can only be extracted to static @container / theme CSS when a class toggle
+      // alone expresses the change. JS animation drivers (reanimated, motion, moti,
+      // react-native) interpolate in JS and need the runtime path to read hard
+      // values when the element animates — a static class can't drive them. gated
+      // on whether THIS element animates rather than on the driver, because motion
+      // is isReactNative:false yet still needs JS.
+      //
+      // in practice createExtractor's deoptProps already de-opts every animated
+      // element upstream except CSS-only transitions, which lower to ordinary
+      // CSS. it keeps the invariant local and correct regardless of future
+      // deoptProps changes — it only ever bails the animated case to runtime,
+      // never widens what extracts.
+      const hasCSSOnlyAnimationDriver =
+        hanzoguiConfig.animations.outputStyle === 'css' && !hanzoguiConfig.animationDrivers
+      let elementIsAnimated = false
+      for (const attr of jsxPath.node.openingElement.attributes) {
+        if (!t.isJSXAttribute(attr) || !t.isJSXIdentifier(attr.name)) continue
+        const n = attr.name.name
+        if (n === 'transition' && hasCSSOnlyAnimationDriver) continue
+        if (
+          n === 'animation' ||
+          n === 'transition' ||
+          n === 'animateOnly' ||
+          n === 'animatePresence' ||
+          n === 'animatedBy' ||
+          n === 'enterStyle' ||
+          n === 'exitStyle'
+        ) {
+          elementIsAnimated = true
+          break
+        }
+      }
+
       function addStyle(style: StyleObject) {
         const identifier = style[StyleObjectIdentifier]
         const rules = style[StyleObjectRules]
@@ -194,20 +263,46 @@ export async function extractToClassNames({
           const property = style[0]
           const mediaName = property.slice(1)
 
-          // $group- styles must bail out entirely - they need runtime handling because
-          // group changes can affect children that may be animated and need hard values.
-          // In the future, CSS animation drivers could potentially optimize this.
+          // $group- styles extract through createMediaStyle which emits @container
+          // rules keyed on the parent's `t_group_<name>` className.
           if (mediaName.startsWith('group-')) {
-            throw new BailOptimizationError()
+            // a class toggle can't drive a JS animation driver's interpolation;
+            // keep animated elements on the runtime path (matches pre-extraction
+            // behavior for the group case).
+            if (elementIsAnimated) {
+              throw new BailOptimizationError()
+            }
+            const mediaStyle = createMediaStyle(
+              style,
+              mediaName,
+              extractor.getGui()!.media,
+              'group',
+              false,
+              mediaStylesSeen
+            )
+            const identifier = addStyle(mediaStyle)
+            classNames.push(identifier)
+            continue
           }
 
           // Check for theme/platform media queries (e.g., $theme-dark, $platform-web)
           const mediaTypeMatch = mediaName.match(/^(theme|platform)-/)
           if (mediaTypeMatch) {
             const mediaType = mediaTypeMatch[1] as 'theme' | 'platform'
+            // $theme- values can change at runtime (theme switch); if this
+            // element animates, a JS driver must interpolate the change, so keep
+            // it on the runtime path. $platform- is build-time static — never gated.
+            if (mediaType === 'theme' && elementIsAnimated) {
+              throw new BailOptimizationError()
+            }
+            // createMediaStyle internally calls getGroupPropParts(`theme-` + key)
+            // for theme, so we must pass the short key ("dark", not "theme-dark")
+            // to avoid double-prefixing. Platform stays as-is (runtime parity).
+            const innerKey =
+              mediaType === 'theme' ? mediaName.slice('theme-'.length) : mediaName
             const mediaStyle = createMediaStyle(
               style,
-              mediaName,
+              innerKey,
               extractor.getGui()!.media,
               mediaType,
               false,
@@ -218,7 +313,7 @@ export async function extractToClassNames({
             continue
           }
 
-          if (mediaName in guiConfig.media) {
+          if (mediaName in hanzoguiConfig.media) {
             const mediaStyle = createMediaStyle(
               style,
               mediaName,
@@ -343,6 +438,13 @@ export async function extractToClassNames({
         baseClassNameStr = `font_${baseFontFamily}${baseClassNameStr ? ` ${baseClassNameStr}` : ''}`
       }
 
+      // add t_group_<name> for elements with a static group="<name>" literal so
+      // descendants' @container <name> rules can match (runtime path normally
+      // appends this class; extracted elements bypass it).
+      if (staticGroupName) {
+        baseClassNameStr = `t_group_${staticGroupName}${baseClassNameStr ? ` ${baseClassNameStr}` : ''}`
+      }
+
       // add is_View or is_Text base class matching runtime behavior
       const baseTypeClass = staticConfig.isText ? 'is_Text' : 'is_View'
       baseClassNameStr = `${baseTypeClass}${baseClassNameStr ? ` ${baseClassNameStr}` : ''}`

package/src/extractor/extractToNative.ts

@@ -26,7 +26,7 @@ const importWithStyle = template.ast(`import { _withStableStyle } from '@hanzogu
 
 const extractor = createExtractor({ platform: 'native' })
 
-let guiBuildOptionsLoaded: GuiOptions | null
+let hanzoguiBuildOptionsLoaded: GuiOptions | null
 
 export function extractToNative(
   sourceFileName: string,
@@ -63,7 +63,7 @@ export function getBabelPlugin() {
 
 export function getBabelParseDefinition(options: GuiOptions) {
   return {
-    name: 'gui',
+    name: 'hanzogui',
 
     visitor: {
       Program: {
@@ -106,14 +106,14 @@ export function getBabelParseDefinition(options: GuiOptions) {
           }
 
           if (!options.config && !options.components) {
-            // if no config/components given try and load from the gui.build.ts file
-            guiBuildOptionsLoaded ||= loadGuiBuildConfigSync({})
+            // if no config/components given try and load from the hanzogui.build.ts file
+            hanzoguiBuildOptionsLoaded ||= loadGuiBuildConfigSync({})
           }
 
           const finalOptions = {
             // @ts-ignore just in case they leave it out
             platform: 'native',
-            ...guiBuildOptionsLoaded,
+            ...hanzoguiBuildOptionsLoaded,
             ...options,
           } satisfies GuiOptions
 
@@ -207,6 +207,7 @@ export function getBabelParseDefinition(options: GuiOptions) {
                 const stylesExpr = t.arrayExpression([])
                 const hocStylesExpr = t.arrayExpression([])
                 const expressions: t.Expression[] = []
+                const mediaExpressionIndexes = new Set<number>()
                 const finalAttrs: (t.JSXAttribute | t.JSXSpreadAttribute)[] = []
                 const themeKeysUsed = new Set<string>()
 
@@ -299,7 +300,22 @@ export function getBabelParseDefinition(options: GuiOptions) {
                         hasMediaKeys = true
                       }
 
-                      expressions.push(attr.value.test)
+                      let expression = attr.value.test
+                      if (
+                        attr.value.inlineMediaQuery &&
+                        t.isLogicalExpression(attr.value.test, { operator: '&&' }) &&
+                        t.isStringLiteral(attr.value.test.left)
+                      ) {
+                        expression = t.arrayExpression([
+                          t.stringLiteral(attr.value.inlineMediaQuery),
+                          t.unaryExpression(
+                            '!',
+                            t.unaryExpression('!', attr.value.test.right)
+                          ),
+                        ])
+                        mediaExpressionIndexes.add(expressions.length)
+                      }
+                      expressions.push(expression)
                       addStyleExpression(
                         t.conditionalExpression(
                           t.identifier(`_expressions[${expressions.length - 1}]`),
@@ -340,7 +356,8 @@ export function getBabelParseDefinition(options: GuiOptions) {
                 if (
                   themeKeysUsed.size ||
                   hocStylesExpr.elements.length > 1 ||
-                  hasDynamicStyle
+                  hasDynamicStyle ||
+                  hasMediaKeys
                 ) {
                   if (!hasImportedViewWrapper) {
                     root.unshiftContainer('body', importWithStyle)
@@ -386,8 +403,8 @@ export function getBabelParseDefinition(options: GuiOptions) {
                   if (expressions.length) {
                     // coerce runtime expressions to boolean so they can't be
                     // confused with string media keys at runtime
-                    const safeExpressions = expressions.map((expr) =>
-                      t.isStringLiteral(expr)
+                    const safeExpressions = expressions.map((expr, index) =>
+                      t.isStringLiteral(expr) || mediaExpressionIndexes.has(index)
                         ? expr
                         : t.unaryExpression('!', t.unaryExpression('!', expr))
                     )
@@ -466,7 +483,7 @@ function assertValidTag(node: t.JSXOpeningElement) {
   if (node.attributes.find((x) => x.type === 'JSXAttribute' && x.name.name === 'style')) {
     // we can just deopt here instead and log warning
     // need to make onExtractTag have a special catch error or similar
-    if (process.env.DEBUG?.startsWith('gui')) {
+    if (process.env.DEBUG?.startsWith('hanzogui')) {
       console.warn('⚠️ Cannot pass style attribute to extracted style')
     }
   }

package/src/extractor/getPrefixLogs.ts

@@ -4,6 +4,6 @@ import type { GuiOptions } from '../types'
 export function getPrefixLogs(options?: GuiOptions) {
   return (
     options?.prefixLogs ??
-    ` 🐥 [gui]  ${colorString(Color.FgYellow, options?.platform || 'web')}`
+    ` 🐥 [hanzogui]  ${colorString(Color.FgYellow, options?.platform || 'web')}`
   )
 }

package/src/extractor/getStaticBindingsForScope.ts

@@ -137,9 +137,9 @@ export async function getStaticBindingsForScope(
       } catch (err: any) {
         if (shouldPrintDebug) {
           console.warn(
-            `    | Skipping partial evaluation of constant file: ${moduleName} (DEBUG=gui for more)`
+            `    | Skipping partial evaluation of constant file: ${moduleName} (DEBUG=hanzogui for more)`
           )
-        } else if (process.env.DEBUG?.startsWith('gui')) {
+        } else if (process.env.DEBUG?.startsWith('hanzogui')) {
           console.info(`Error in partial evaluation`, err.message, err.stack)
         }
       }

package/src/extractor/loadGui.ts

@@ -28,8 +28,8 @@ import {
 const getFilledOptions = (propsIn: Partial<GuiOptions>): GuiOptions => ({
   // defaults
   platform: (process.env.GUI_TARGET as any) || 'web',
-  config: 'gui.config.ts',
-  components: ['gui'],
+  config: 'hanzogui.config.ts',
+  components: ['hanzogui'],
   ...(propsIn as Partial<GuiOptions>),
 })
 
@@ -53,7 +53,7 @@ export async function loadGui(
     const bundleInfo = await getBundledConfig(props)
     if (!bundleInfo) {
       console.warn(
-        `No bundled config generated, maybe an error in bundling. Set DEBUG=gui and re-run to get logs.`
+        `No bundled config generated, maybe an error in bundling. Set DEBUG=hanzogui and re-run to get logs.`
       )
       resolvePromise(null)
       return null
@@ -63,10 +63,10 @@ export async function loadGui(
     await generateThemesAndLog(props)
 
     // if they accidently pass in a config without createGui called,call it
-    const maybeGuiConfig = bundleInfo.guiConfig as GuiInternalConfig
+    const maybeGuiConfig = bundleInfo.hanzoguiConfig as GuiInternalConfig
     if (maybeGuiConfig && !maybeGuiConfig.parsed) {
       const { createGui } = requireGuiCore(props.platform || 'web')
-      bundleInfo.guiConfig = createGui(bundleInfo.guiConfig as any)
+      bundleInfo.hanzoguiConfig = createGui(bundleInfo.hanzoguiConfig as any)
     }
 
     if (!hasBundledConfigChanged()) {
@@ -102,7 +102,7 @@ export const generateThemesAndLog = async (options: GuiOptions, force = false) =
       const whitespaceBefore = `  `
       colorLog(
         Color.FgYellow,
-        `${whitespaceBefore}➡ [gui] generated themes: ${relative(
+        `${whitespaceBefore}➡ [hanzogui] generated themes: ${relative(
           process.cwd(),
           options.themeBuilder.output
         )}`
@@ -127,13 +127,13 @@ const lastVersion: Record<string, string> = {}
 let esbuildWasmInitialized = false
 
 /**
- * Load gui.build.ts config using esbuild-wasm transform
+ * Load hanzogui.build.ts config using esbuild-wasm transform
  * Uses WASM to avoid native esbuild service lifecycle issues (EPIPE errors)
  */
 export async function loadGuiBuildConfigAsync(
-  guiOptions: Partial<GuiOptions> | undefined
+  hanzoguiOptions: Partial<GuiOptions> | undefined
 ): Promise<GuiOptions> {
-  const buildFilePath = guiOptions?.buildFile ?? './gui.build.ts'
+  const buildFilePath = hanzoguiOptions?.buildFile ?? './hanzogui.build.ts'
   const absolutePath =
     buildFilePath[0] === '.' ? join(process.cwd(), buildFilePath) : buildFilePath
 
@@ -147,7 +147,11 @@ export async function loadGuiBuildConfigAsync(
         esbuildWasmInitialized = true
       }
 
-      // use esbuild-wasm.transform to compile - no native service needed
+      // use esbuild-wasm.transform to compile this one small config file. note
+      // that in node, even esbuild-wasm's transform spawns a long-lived
+      // `--service --ping` child via ensureServiceIsRunning, so we tear it down
+      // below - otherwise every plugin instance leaks a persistent esbuild
+      // process for the lifetime of the dev server.
       const result = await esbuildWasm.transform(source, {
         loader: 'ts',
         format: 'cjs',
@@ -166,26 +170,36 @@ export async function loadGuiBuildConfigAsync(
         throw new Error(`No default export found in ${buildFilePath}: ${out}`)
       }
 
-      guiOptions = {
-        ...guiOptions,
+      hanzoguiOptions = {
+        ...hanzoguiOptions,
         ...out,
       }
     } catch (err) {
-      console.error(`[gui] Error loading ${buildFilePath}:`, err)
+      console.error(`[hanzogui] Error loading ${buildFilePath}:`, err)
       throw err
+    } finally {
+      // this is a one-shot transform - don't keep the esbuild-wasm service
+      // running for the rest of the process. it gets lazily re-spawned if
+      // transform is ever called again.
+      try {
+        esbuildWasm.stop()
+        esbuildWasmInitialized = false
+      } catch {
+        // ok - service may already be gone
+      }
     }
   }
 
-  if (!guiOptions) {
+  if (!hanzoguiOptions) {
     throw new Error(
-      `No gui build options found either via input props or at gui.build.ts`
+      `No hanzogui build options found either via input props or at hanzogui.build.ts`
     )
   }
 
   return {
-    config: 'gui.config.ts',
-    components: ['gui', '@hanzogui/core'],
-    ...guiOptions,
+    config: 'hanzogui.config.ts',
+    components: ['hanzogui', '@hanzogui/core'],
+    ...hanzoguiOptions,
   } as GuiOptions
 }
 
@@ -193,9 +207,9 @@ export async function loadGuiBuildConfigAsync(
  * @deprecated Use loadGuiBuildConfigAsync instead to avoid EPIPE errors
  */
 export function loadGuiBuildConfigSync(
-  guiOptions: Partial<GuiOptions> | undefined
+  hanzoguiOptions: Partial<GuiOptions> | undefined
 ) {
-  const buildFilePath = guiOptions?.buildFile ?? './gui.build.ts'
+  const buildFilePath = hanzoguiOptions?.buildFile ?? './hanzogui.build.ts'
   if (fsExtra.existsSync(buildFilePath)) {
     const registered = registerRequire('web')
     try {
@@ -206,23 +220,23 @@ export function loadGuiBuildConfigSync(
         throw new Error(`No default export found in ${buildFilePath}: ${out}`)
       }
 
-      guiOptions = {
-        ...guiOptions,
+      hanzoguiOptions = {
+        ...hanzoguiOptions,
         ...out,
       }
     } finally {
       registered.unregister()
     }
   }
-  if (!guiOptions) {
+  if (!hanzoguiOptions) {
     throw new Error(
-      `No gui build options found either via input props or at gui.build.ts`
+      `No hanzogui build options found either via input props or at hanzogui.build.ts`
     )
   }
   return {
-    config: 'gui.config.ts',
-    components: ['gui', '@hanzogui/core'],
-    ...guiOptions,
+    config: 'hanzogui.config.ts',
+    components: ['hanzogui', '@hanzogui/core'],
+    ...hanzoguiOptions,
   } as GuiOptions
 }
 
@@ -262,7 +276,7 @@ export function loadGuiSync({
 
     try {
       // config
-      let guiConfig: GuiInternalConfig | null = null
+      let hanzoguiConfig: GuiInternalConfig | null = null
       if (propsIn.config) {
         const configPath = getGuiConfigPathFromOptionsConfig(propsIn.config)
         const exp = require(configPath)
@@ -271,9 +285,9 @@ export function loadGuiSync({
           throw new Error(`Got a empty / proxied config!`)
         }
 
-        guiConfig = (exp['default'] || exp['config'] || exp) as GuiInternalConfig
+        hanzoguiConfig = (exp['default'] || exp['config'] || exp) as GuiInternalConfig
 
-        if (!guiConfig || !guiConfig.parsed) {
+        if (!hanzoguiConfig || !hanzoguiConfig.parsed) {
           const confPath = require.resolve(configPath)
           throw new Error(`Can't find valid config in ${confPath}:
           
@@ -281,9 +295,9 @@ export function loadGuiSync({
         }
 
         // set up core
-        if (guiConfig) {
+        if (hanzoguiConfig) {
           const { createGui } = requireGuiCore(props.platform || 'web')
-          createGui(guiConfig as any)
+          createGui(hanzoguiConfig as any)
         }
       }
 
@@ -292,7 +306,7 @@ export function loadGuiSync({
       if (!components) {
         throw new Error(`No components loaded`)
       }
-      if (process.env.DEBUG === 'gui') {
+      if (process.env.DEBUG === 'hanzogui') {
         console.info(`components`, components)
       }
 
@@ -302,14 +316,14 @@ export function loadGuiSync({
 
       const info = {
         components,
-        guiConfig,
+        hanzoguiConfig,
         nameToPaths: getNameToPaths(),
       } satisfies GuiProjectInfo
 
-      if (guiConfig) {
+      if (hanzoguiConfig) {
         const { outputCSS } = props
         if (outputCSS) {
-          writeGuiCSS(outputCSS, guiConfig)
+          writeGuiCSS(outputCSS, hanzoguiConfig)
         }
 
         regenerateConfigSync(props, info)
@@ -325,7 +339,7 @@ export function loadGuiSync({
       if (err instanceof Error) {
         if (!SHOULD_DEBUG && !forceExports) {
           console.warn(
-            `Error loading gui.config.ts (set DEBUG=gui to see full stack), running gui without custom config`
+            `Error loading hanzogui.config.ts (set DEBUG=hanzogui to see full stack), running hanzogui without custom config`
           )
           console.info(`\n\n    ${err.message}\n\n`)
         } else {
@@ -334,12 +348,12 @@ export function loadGuiSync({
           }
         }
       } else {
-        console.error(`Error loading gui.config.ts`, err)
+        console.error(`Error loading hanzogui.config.ts`, err)
       }
 
       return {
         components: [],
-        guiConfig: null,
+        hanzoguiConfig: null,
         nameToPaths: {},
       }
     }
@@ -351,11 +365,11 @@ export function loadGuiSync({
 export async function getOptions({
   root = process.cwd(),
   tsconfigPath = 'tsconfig.json',
-  guiOptions,
+  hanzoguiOptions,
   host,
   debug,
 }: Partial<CLIUserOptions> = {}): Promise<CLIResolvedOptions> {
-  const dotDir = join(root, '.gui')
+  const dotDir = join(root, '.hanzogui')
   let pkgJson = {}
 
   try {
@@ -371,29 +385,30 @@ export async function getOptions({
     pkgJson,
     debug,
     tsconfigPath,
-    guiOptions: {
+    hanzoguiOptions: {
       platform: (process.env.GUI_TARGET as any) || 'web',
-      components: ['gui'],
-      ...guiOptions,
+      components: ['hanzogui'],
+      ...hanzoguiOptions,
       config:
-        guiOptions?.config ??
-        (await getDefaultGuiConfigPath(root, guiOptions?.config)),
+        hanzoguiOptions?.config ??
+        (await getDefaultGuiConfigPath(root, hanzoguiOptions?.config)),
     },
     paths: {
       root,
       dotDir,
-      conf: join(dotDir, 'gui.config.json'),
+      conf: join(dotDir, 'hanzogui.config.json'),
       types: join(dotDir, 'types.json'),
     },
   }
 }
 
-export function resolveWebOrNativeSpecificEntry(entry: string) {
+export function resolveWebOrNativeSpecificEntry(entry: string, platform?: string) {
   const workspaceRoot = resolve()
   const resolved = require.resolve(entry, { paths: [workspaceRoot] })
   const ext = extname(resolved)
   const fileName = basename(resolved).replace(ext, '')
-  const specificExt = process.env.GUI_TARGET === 'web' ? 'web' : 'native'
+  const target = platform || process.env.GUI_TARGET || 'web'
+  const specificExt = target === 'web' ? 'web' : 'native'
   const specificFile = join(dirname(resolved), fileName + '.' + specificExt + ext)
   if (fsExtra.existsSync(specificFile)) {
     return specificFile
@@ -401,7 +416,7 @@ export function resolveWebOrNativeSpecificEntry(entry: string) {
   return entry
 }
 
-const defaultPaths = ['gui.config.ts', join('src', 'gui.config.ts')]
+const defaultPaths = ['hanzogui.config.ts', join('src', 'hanzogui.config.ts')]
 let hasWarnedOnce = false
 
 async function getDefaultGuiConfigPath(root: string, configPath?: string) {
@@ -419,7 +434,7 @@ async function getDefaultGuiConfigPath(root: string, configPath?: string) {
 
   if (!hasWarnedOnce) {
     hasWarnedOnce = true
-    console.warn(`Warning: couldn't find gui.config.ts in the following paths given configuration "${configPath}":
+    console.warn(`Warning: couldn't find hanzogui.config.ts in the following paths given configuration "${configPath}":
     ${searchPaths.join(`\n  `)}
   `)
   }