@barefootjs/jsx 0.14.0 → 0.15.1

package/src/adapters/env-signal.ts

@@ -0,0 +1,75 @@
+// Shared recognition of the router v0.5 `searchParams()` environment signal
+// for the template-string adapters (Mojo / Xslate today; Go has its own
+// struct-field path). A request-scoped reactive env signal reads like an
+// ordinary signal getter, but its value is a URLSearchParams-like reader with
+// real methods (`.get(key)`) — not a hashref. The generic `member` lowering
+// would deref `.get` as a property access and drop the call + argument, so the
+// adapters special-case it to a real per-request reader method call. See #1922.
+
+import type { ParsedExpr } from '../expression-parser.ts'
+import type { IRMetadata } from '../types.ts'
+
+/**
+ * The local binding name(s) that `searchParams` from `@barefootjs/client` is
+ * imported under in this component — the same import the analyzer allow-lists
+ * (`CLIENT_EXPORTS`). Usually the single name `searchParams`, but an aliased
+ * import (`import { searchParams as sp }`) binds it to `sp`, and the template
+ * expression then reads `sp()` — so adapters must gate + match against the
+ * LOCAL name(s), not the literal `searchParams`. Empty when the env signal is
+ * not imported (the component keeps the generic signal lowering).
+ *
+ * `ImportSpecifier.name` is the exported name and `alias` the local rebinding
+ * (see `collectImport` in analyzer.ts), so the import is detected by `name ===
+ * 'searchParams'` and the local binding is `alias ?? name`. Namespace / default
+ * specifiers bind a different identifier and are excluded.
+ */
+export function searchParamsLocalNames(metadata: IRMetadata): Set<string> {
+  const names = new Set<string>()
+  for (const imp of metadata.imports) {
+    if (imp.source !== '@barefootjs/client' || imp.isTypeOnly) continue
+    for (const s of imp.specifiers) {
+      if (s.isTypeOnly || s.isNamespace || s.isDefault) continue
+      if (s.name === 'searchParams') names.add(s.alias ?? s.name)
+    }
+  }
+  return names
+}
+
+/**
+ * True when the component imports the `searchParams` env signal under any local
+ * name. Convenience for adapters/harnesses that only need to gate on presence
+ * (the lowering itself needs the {@link searchParamsLocalNames} set to match the
+ * actual binding in the expression).
+ */
+export function importsSearchParams(metadata: IRMetadata): boolean {
+  return searchParamsLocalNames(metadata).size > 0
+}
+
+/**
+ * Recognise a `<binding>().<method>(<args>)` env-signal method call from a
+ * `call` node's callee + args, where `<binding>` is one of the local names
+ * `searchParams` was imported under (`localNames`, from
+ * {@link searchParamsLocalNames}). Returns the method name and argument nodes
+ * when the receiver is the zero-arg env-signal getter, else null. The caller
+ * lowers the match to a real method call on its per-request reader object
+ * (`$searchParams->get('sort')` in Mojo, `$searchParams.get('sort')` in
+ * Xslate — the canonical `$searchParams` var regardless of the JS alias);
+ * without it the generic `member` lowering drops the call + arg.
+ */
+export function matchSearchParamsMethodCall(
+  callee: ParsedExpr,
+  args: ParsedExpr[],
+  localNames: ReadonlySet<string>,
+): { method: string; args: ParsedExpr[] } | null {
+  if (callee.kind !== 'member' || callee.computed) return null
+  const recv = callee.object
+  if (
+    recv.kind !== 'call' ||
+    recv.args.length !== 0 ||
+    recv.callee.kind !== 'identifier' ||
+    !localNames.has(recv.callee.name)
+  ) {
+    return null
+  }
+  return { method: callee.property, args }
+}

package/src/adapters/parsed-expr-emitter.ts

@@ -66,6 +66,7 @@ export type ArrayMethod =
   | 'toLowerCase'
   | 'toUpperCase'
   | 'trim'
+  | 'toFixed'
   | 'split'
   | 'startsWith'
   | 'endsWith'
@@ -115,6 +116,14 @@ export interface ParsedExprEmitter {
     computed: boolean,
     emit: (e: ParsedExpr) => string,
   ): string
+  // Element access with a non-literal index (`arr[index]`). The index
+  // is a full `ParsedExpr` (loop variable, arithmetic, etc.); the
+  // adapter picks array vs hash deref per target language. #1897.
+  indexAccess(
+    object: ParsedExpr,
+    index: ParsedExpr,
+    emit: (e: ParsedExpr) => string,
+  ): string
   binary(op: string, left: ParsedExpr, right: ParsedExpr, emit: (e: ParsedExpr) => string): string
   unary(op: string, argument: ParsedExpr, emit: (e: ParsedExpr) => string): string
   logical(
@@ -196,6 +205,8 @@ export function emitParsedExpr(expr: ParsedExpr, emitter: ParsedExprEmitter): st
       return emitter.call(expr.callee, expr.args, emit)
     case 'member':
       return emitter.member(expr.object, expr.property, expr.computed, emit)
+    case 'index-access':
+      return emitter.indexAccess(expr.object, expr.index, emit)
     case 'binary':
       return emitter.binary(expr.op, expr.left, expr.right, emit)
     case 'unary':

package/src/analyzer.ts

@@ -1648,6 +1648,13 @@ const CLIENT_EXPORTS = new Set([
   'forwardProps', 'unwrap', '__slot',
   'createContext', 'useContext', 'provideContext',
   'createPortal', 'isSSRPortal', 'findSiblingSlot', 'cleanupPortalPlaceholder',
+  // Request-scoped environment signal (router v0.5) — a real user-facing
+  // reactive export the compiler lowers like any other `@barefootjs/client`
+  // signal read (SSR: a template binding; client: a `createEffect`).
+  'searchParams',
+  // Compile-away JSX built-ins (#1915) — importing them is what scopes the
+  // compiler's `<Async>` / `<Region>` recognition; the import is elided on emit.
+  'Async', 'Region',
 ])
 
 /**
@@ -1748,6 +1755,8 @@ function collectImport(node: ts.ImportDeclaration, ctx: AnalyzerContext): void {
             alias: element.propertyName ? element.name.text : null,
             isDefault: false,
             isNamespace: false,
+            // Per-specifier `import { type Foo }` — no value binding (#1915).
+            isTypeOnly: element.isTypeOnly,
           })
         }
       }

package/src/augment-inherited-props.ts

@@ -164,7 +164,31 @@ export function augmentInheritedPropAccesses(ir: ComponentIR): void {
     if (!node) return
     const el = node as unknown as IRElement
     for (const attr of el.attrs ?? []) {
-      const v = attr.value as { kind?: string; expr?: string; presenceOrUndefined?: boolean }
+      const v = attr.value as {
+        kind?: string
+        expr?: string
+        presenceOrUndefined?: boolean
+        parts?: Array<
+          | { type: 'string'; value: string }
+          | { type: 'ternary'; condition: string; whenTrue: string; whenFalse: string }
+          | { type: 'lookup'; key: string }
+        >
+      }
+      // Template-literal attr values (`className={\`… \${props.className ??
+      // ''}\`}`) carry their `props.X` reads inside the parts structure,
+      // not a flat expr string (#1896 — TabsContent's template referenced
+      // `.ClassName` while the Props struct never declared it). Scan every
+      // textual field of every part shape.
+      if (v?.parts) {
+        for (const part of v.parts) {
+          if (part.type === 'string') scan(part.value)
+          else if (part.type === 'ternary') {
+            scan(part.condition)
+            scan(part.whenTrue)
+            scan(part.whenFalse)
+          } else if (part.type === 'lookup') scan(part.key)
+        }
+      }
       if (v?.kind === 'expression' && typeof v.expr === 'string') {
         scan(v.expr)
         const expr = v.expr.trim()
@@ -186,6 +210,20 @@ export function augmentInheritedPropAccesses(ir: ComponentIR): void {
       const c = child as { element?: IRNode }
       walk((c.element ?? child) as IRNode)
     }
+    // Conditional / if-statement nodes keep their subtrees in branch
+    // fields, not `children` (#1896 — DialogTrigger's asChild
+    // if-statement hid the button branch's `id={props.id}` from this
+    // scan, so the template referenced `.ID` without a Props field).
+    const branchy = node as unknown as {
+      whenTrue?: IRNode
+      whenFalse?: IRNode
+      consequent?: IRNode
+      alternate?: IRNode
+    }
+    walk(branchy.whenTrue)
+    walk(branchy.whenFalse)
+    walk(branchy.consequent)
+    walk(branchy.alternate)
   }
   walk(ir.root)
 
@@ -206,6 +244,134 @@ export function augmentInheritedPropAccesses(ir: ComponentIR): void {
   }
 }
 
+/**
+ * Parse a const initializer to its static string value: a string literal,
+ * a no-substitution template literal, or a `[<string literals>].join(sep)`
+ * call. Returns `null` for anything else. The TS parser resolves escapes
+ * and quoting exactly as JS would, matching the value the Hono reference
+ * inlines at runtime. Shared by the Go, Mojo, and Xslate adapters.
+ */
+export function parseStaticStringConst(source: string): string | null {
+  const sf = ts.createSourceFile(
+    '__const.ts', `const __x = (${source});`, ts.ScriptTarget.Latest, /*setParentNodes*/ false,
+  )
+  const stmt = sf.statements[0]
+  if (!stmt || !ts.isVariableStatement(stmt)) return null
+  let init = stmt.declarationList.declarations[0]?.initializer
+  while (init && ts.isParenthesizedExpression(init)) init = init.expression
+  if (!init) return null
+  if (ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)) {
+    return init.text
+  }
+  return evalStringArrayJoin(source)
+}
+
+/**
+ * Statically evaluate a template literal whose every interpolation is a
+ * bare identifier present in `resolved` to its flat string, else `null`.
+ * Companion to `parseStaticStringConst` for COMPOSED module consts
+ * (#1896 / #1897 — radio-group's
+ * `itemClasses = \`\${itemBaseClasses} \${itemFocusClasses} …\``).
+ */
+export function evalTemplateOfStringConsts(
+  source: string,
+  resolved: ReadonlyMap<string, string>,
+): string | null {
+  const sf = ts.createSourceFile(
+    '__const.ts', `const __x = (${source});`, ts.ScriptTarget.Latest, /*setParentNodes*/ false,
+  )
+  const stmt = sf.statements[0]
+  if (!stmt || !ts.isVariableStatement(stmt)) return null
+  let init = stmt.declarationList.declarations[0]?.initializer
+  while (init && ts.isParenthesizedExpression(init)) init = init.expression
+  if (!init || !ts.isTemplateExpression(init)) return null
+  let out = init.head.text
+  for (const span of init.templateSpans) {
+    if (!ts.isIdentifier(span.expression)) return null
+    const value = resolved.get(span.expression.text)
+    if (value === undefined) return null
+    out += value + span.literal.text
+  }
+  return out
+}
+
+/**
+ * Build the module string-const map from the IR's localConstants —
+ * the SINGLE SOURCE OF TRUTH for all three SSR template adapters.
+ * A const qualifies when module-scope and statically resolvable as:
+ *   - a pure string / no-substitution-template literal,
+ *   - `[<string literals>].join(sep)`,
+ *   - a template literal COMPOSED of other qualifying module consts
+ *     (resolved to a fixed point, so composition order doesn't matter).
+ */
+export function collectModuleStringConsts(
+  constants: IRMetadata['localConstants'] | undefined,
+): Map<string, string> {
+  const map = new Map<string, string>()
+  const candidates = (constants ?? []).filter(
+    c => c.isModule && c.value !== undefined,
+  )
+  let progressed = true
+  while (progressed) {
+    progressed = false
+    for (const c of candidates) {
+      if (map.has(c.name)) continue
+      const literal =
+        parseStaticStringConst(c.value!) ??
+        evalTemplateOfStringConsts(c.value!, map)
+      if (literal !== null) {
+        map.set(c.name, literal)
+        progressed = true
+      }
+    }
+  }
+  return map
+}
+
+/**
+ * Resolve `IDENT.key` / `IDENT['key']` where `IDENT` is a module-scope
+ * object-literal const and the key/value are static literals — a fully
+ * compile-time lookup (the icon registry's `strokePaths['chevron-down']`,
+ * pagination's `variantClasses.ghost`; #1896 / #1897). Returns the
+ * looked-up scalar, or `null` for any other shape so callers fall back
+ * to their generic lowering. Shared by all three SSR template adapters;
+ * the prop-KEYED variant of the pattern lives in `parseRecordIndexAccess`.
+ */
+export function lookupStaticRecordLiteral(
+  objectName: string,
+  key: string,
+  constants: IRMetadata['localConstants'] | undefined,
+): { kind: 'string' | 'number'; text: string } | null {
+  const constInfo = (constants ?? []).find(c => c.name === objectName && c.isModule)
+  if (constInfo?.value === undefined) return null
+  const sf = ts.createSourceFile(
+    '__rec.ts', `(${constInfo.value})`, ts.ScriptTarget.Latest, /*setParentNodes*/ true,
+  )
+  if (sf.statements.length !== 1) return null
+  const stmt = sf.statements[0]
+  if (!ts.isExpressionStatement(stmt)) return null
+  let parsed: ts.Expression = stmt.expression
+  while (ts.isParenthesizedExpression(parsed)) parsed = parsed.expression
+  if (!ts.isObjectLiteralExpression(parsed)) return null
+  for (const prop of parsed.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue
+    const name = prop.name
+    const propKey =
+      ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name)
+        ? name.text
+        : null
+    if (propKey !== key) continue
+    let v: ts.Expression = prop.initializer
+    while (ts.isParenthesizedExpression(v)) v = v.expression
+    if (ts.isNumericLiteral(v)) return { kind: 'number', text: v.text }
+    if (ts.isStringLiteral(v) || ts.isNoSubstitutionTemplateLiteral(v)) {
+      return { kind: 'string', text: v.text }
+    }
+    return null
+  }
+  return null
+}
+
 /**
  * Statically evaluate `[<string literals>].join(<sep?>)` (e.g. a module-scope
  * `const stateClasses = ['…', …].join(' ')`) to its joined string, so SSR
@@ -213,7 +379,9 @@ export function augmentInheritedPropAccesses(ir: ComponentIR): void {
  * instead of referencing a binding that doesn't exist server-side. Default
  * separator `,` matches JS `Array.prototype.join`. Returns `null` for any
  * other shape (non-`.join` call, non-array receiver, non-string-literal element
- * or separator). Shared by the Mojo + Xslate adapters; Go keeps a private copy.
+ * or separator). Shared by the Go, Mojo, and Xslate adapters (all three
+ * resolve module consts through `collectModuleStringConsts` above, which
+ * folds these joins during its fixed-point pass).
  */
 export function evalStringArrayJoin(source: string): string | null {
   const sf = ts.createSourceFile(

package/src/builtins.ts

@@ -0,0 +1,63 @@
+/**
+ * Compiler built-in JSX tags that are import-scoped to `@barefootjs/client`
+ * and compiled away (no runtime value survives in emitted output).
+ *
+ * `<Async>` and `<Region>` are recognised **structurally** — by their
+ * `@barefootjs/client` import in `ir.metadata.imports`, never by a bare
+ * capitalized tag-name match — so a user's own `<Async>` / `<Region>`
+ * component (imported from elsewhere or declared locally) does not collide
+ * with the built-in. The import is elided on emit (both `templateImports`
+ * and the client-JS DOM imports) so it never lingers as a phantom runtime
+ * import.
+ *
+ * Runtime stubs + types ship from `@barefootjs/client` (see
+ * `packages/client/src/builtins.ts`). See piconic-ai/barefootjs#1915.
+ */
+
+import type { ImportInfo } from './types.ts'
+
+/** Package that the built-in tags must be imported from to be recognised. */
+export const CLIENT_BUILTIN_SOURCE = '@barefootjs/client'
+
+export type ClientBuiltinTag = 'Async' | 'Region'
+
+/** The recognised built-in tag (export) names. */
+export const CLIENT_BUILTIN_TAGS: readonly ClientBuiltinTag[] = ['Async', 'Region']
+
+/** True when `name` is one of the compile-away built-in export names. */
+export function isClientBuiltinName(name: string): name is ClientBuiltinTag {
+  return name === 'Async' || name === 'Region'
+}
+
+/**
+ * Elide the compile-away built-ins from an import list for emission (#1915).
+ * `<Async>` / `<Region>` are lowered into the template, so their
+ * `@barefootjs/client` import must not survive as a phantom runtime import in
+ * either the SSR template or the client JS bundle. Drops the `Async` / `Region`
+ * specifiers from `@barefootjs/client` imports, and drops the whole import
+ * statement when it has no remaining specifiers.
+ */
+export function stripClientBuiltinImports(imports: ImportInfo[]): ImportInfo[] {
+  const result: ImportInfo[] = []
+  for (const imp of imports) {
+    // Only a *value* named import of the built-ins can become a phantom runtime
+    // import. Leave everything else untouched: imports from other sources;
+    // `import type { Async }` (erased by TS — never a runtime import, and may be
+    // needed to type-check emitted templates); and side-effect imports (no
+    // specifiers, deliberate). See #1915 review.
+    if (imp.source !== CLIENT_BUILTIN_SOURCE || imp.isTypeOnly || imp.specifiers.length === 0) {
+      result.push(imp)
+      continue
+    }
+    const kept = imp.specifiers.filter(
+      // Keep per-specifier type-only built-ins (`import { type Async }`) — they
+      // are erased by TS and never a runtime phantom.
+      spec => spec.isDefault || spec.isNamespace || spec.isTypeOnly || !isClientBuiltinName(spec.name),
+    )
+    // Drop the import entirely when every specifier was a built-in; otherwise
+    // re-emit without them.
+    if (kept.length === 0) continue
+    result.push(kept.length === imp.specifiers.length ? imp : { ...imp, specifiers: kept })
+  }
+  return result
+}

package/src/compiler.ts

@@ -14,6 +14,7 @@ import type {
 import type { TemplateAdapter } from './adapters/interface.ts'
 import { analyzeComponent, listComponentFunctions, createProgramForFile, needsTypeBasedDetection } from './analyzer.ts'
 import { jsxToIR } from './jsx-to-ir.ts'
+import { stripClientBuiltinImports } from './builtins.ts'
 import { generateClientJs, generateClientJsWithSourceMap, analyzeClientNeeds } from './ir-to-client-js/index.ts'
 import { emitModuleLevelDeclarations } from './ir-to-client-js/emit-module-level.ts'
 import { RUNTIME_MODULE, detectUsedImports as detectUsedImportsFromCode } from './ir-to-client-js/imports.ts'
@@ -502,8 +503,11 @@ export function buildMetadata(
     // re-emission. Adapters that re-emit imports (Hono, test) call
     // `rewriteImportsForTemplate` themselves to apply client-shim rewrite or
     // strip behaviour; adapters whose templates never carry imports (Go,
-    // Mojo) only consult this list for diagnostics like BF103.
-    templateImports: ctx.imports,
+    // Mojo) only consult this list for diagnostics like BF103. The
+    // compile-away built-ins (`<Async>` / `<Region>`) are stripped here so
+    // their `@barefootjs/client` import never reaches any adapter's template
+    // as a phantom (#1915).
+    templateImports: stripClientBuiltinImports(ctx.imports),
     namedExports: ctx.namedExports,
     localFunctions: ctx.localFunctions,
     localConstants: ctx.localConstants,

package/src/errors.ts

@@ -47,6 +47,11 @@ export const ErrorCodes = {
   // Import errors (BF050-BF059)
   SHARED_PROGRAM_REQUIRED: 'BF050',
   WRONG_PACKAGE_IMPORT: 'BF051',
+  // A bare `<Async>` / `<Region>` tag was used without importing it from
+  // `@barefootjs/client`. The built-ins are recognised import-scoped (#1915),
+  // so an unimported tag with the built-in name is either a forgotten import
+  // or an undeclared component — fail loud with the import to add.
+  BUILTIN_REQUIRES_IMPORT: 'BF054',
 
   // Init statement errors (BF052)
   UNDECLARED_INIT_STATEMENT_REFERENCE: 'BF052',
@@ -135,6 +140,11 @@ const errorMessages: Record<ErrorCode, string> = {
   [ErrorCodes.WRONG_PACKAGE_IMPORT]:
     'Import from wrong package.',
 
+  [ErrorCodes.BUILTIN_REQUIRES_IMPORT]:
+    "Built-in <Async> / <Region> must be imported from '@barefootjs/client'. " +
+    'The compiler recognises these tags by their import (not by tag name), ' +
+    'so an unimported tag with this name is treated as an undeclared component.',
+
   [ErrorCodes.UNDECLARED_INIT_STATEMENT_REFERENCE]:
     'Init statement references an undeclared identifier. Declare it at module scope, inside the component, or import it — otherwise ESM strict mode throws ReferenceError at runtime.',