@barefootjs/go-template 0.16.0 → 0.17.1

package/src/__tests__/lowering-plugin.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Registry → adapter end-to-end (#2057). Every lowering — first-party built-ins
+ * (like `queryHref`) and userland plugins alike — flows through the one
+ * lowering-plugin *registry*. This test guarantees that seam works all the way
+ * through: a SAMPLE plugin (registered via the public `registerLoweringPlugin`)
+ * recognises a call from an arbitrary package and returns a backend-neutral
+ * `guard-list` node, and the Go adapter renders it via its own `bf_query`
+ * mapping — no adapter code knows the sample plugin exists.
+ *
+ * The plugin reuses the `'query'` helper id so it exercises the exact same
+ * renderer path as the built-in `queryHref` plugin, proving that a userland
+ * plugin and a default-registered built-in are indistinguishable to the adapter
+ * (which is the whole point of the neutral-node layer).
+ */
+import { describe, test, expect, afterEach } from 'bun:test'
+import {
+  compileJSX,
+  registerLoweringPlugin,
+  getLoweringPlugins,
+  __resetLoweringPluginsForTest,
+  type ComponentIR,
+  type LoweringPlugin,
+} from '@barefootjs/jsx'
+import { GoTemplateAdapter } from '../adapter/go-template-adapter'
+
+function generate(src: string) {
+  const adapter = new GoTemplateAdapter()
+  const result = compileJSX(src.trimStart(), 'T.tsx', { adapter, outputIR: true })
+  const irFile = result.files.find(f => f.type === 'ir')
+  if (!irFile) throw new Error('no IR')
+  const ir = JSON.parse(irFile.content) as ComponentIR
+  return adapter.generate(ir)
+}
+
+// A userland-style plugin: active only when the component imports `demoUrl` from
+// `@sample/pkg`, lowering `demoUrl(base, { key: value })` to a neutral
+// `guard-list` on the `'query'` helper. It reuses the sub-parts of the parsed
+// call directly (base = first arg, one triple per object property) so no
+// adapter syntax leaks into the plugin.
+const samplePlugin: LoweringPlugin = {
+  name: 'sample-demo-url',
+  prepare(metadata) {
+    const spec = metadata.imports
+      .filter(i => i.source === '@sample/pkg' && !i.isTypeOnly)
+      .flatMap(i => i.specifiers)
+      .filter(s => !s.isTypeOnly && !s.isNamespace && !s.isDefault)
+      .find(s => s.name === 'demoUrl')
+    if (!spec) return null
+    const local = spec.alias ?? spec.name // the name it's bound under in this file
+    return (callee, args) => {
+      if (callee.kind !== 'identifier' || callee.name !== local) return null
+      const [base, obj] = args
+      if (!base || obj?.kind !== 'object-literal') return null
+      return {
+        kind: 'guard-list',
+        helper: 'query',
+        base,
+        triples: obj.properties.map(p => ({ guard: null, key: p.key, value: p.value })),
+      }
+    }
+  },
+}
+
+afterEach(() => {
+  __resetLoweringPluginsForTest(getLoweringPlugins().filter(p => p.name !== 'sample-demo-url'))
+})
+
+describe('lowering-plugin registry → Go adapter (#2057)', () => {
+  test('a registered plugin lowers its call to the neutral node the adapter renders', () => {
+    registerLoweringPlugin(samplePlugin)
+    const src = `
+'use client'
+import { demoUrl } from '@sample/pkg'
+export function P(props: { base: string; tag: string }) {
+  return <a href={demoUrl(props.base, { tag: props.tag })}>x</a>
+}
+`
+    const { template } = generate(src)
+    // Same render path as built-in queryHref: guard-list → bf_query.
+    expect(template).toContain('bf_query .Base (true) "tag" .Tag')
+  })
+
+  test('without the plugin registered the same call falls back to the generic lowering', () => {
+    // No registerLoweringPlugin call — the registry is empty for this component.
+    const src = `
+'use client'
+import { demoUrl } from '@sample/pkg'
+export function P(props: { base: string; tag: string }) {
+  return <a href={demoUrl(props.base, { tag: props.tag })}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).not.toContain('bf_query')
+  })
+
+  test('the plugin is inert when the component does not import from its package', () => {
+    registerLoweringPlugin(samplePlugin)
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; tag: string }) {
+  return <a href={queryHref(props.base, { tag: props.tag })}>x</a>
+}
+`
+    const { template } = generate(src)
+    // Built-in queryHref still lowers; the sample plugin simply isn't active.
+    expect(template).toContain('bf_query .Base (true) "tag" .Tag')
+  })
+})

package/src/__tests__/query-href.test.ts

@@ -0,0 +1,179 @@
+/**
+ * `queryHref(base, { … })` → `bf_query` lowering for the Go adapter (#2042).
+ *
+ * The pure functional URL builder is a structured `call` + `object-literal` in
+ * the IR, so the adapter lowers it directly — no block-body recognizer, no
+ * re-parse. The lowering emits `(include) "key" value` triples and lets the
+ * `bf_query` runtime helper own the non-empty check (so it can also append array
+ * values member-by-member, #2048): a plain `key: v` → `(true) "key" v`; a
+ * conditional `key: cond ? a : undefined` → `(cond) "key" a` (the helper drops an
+ * empty `a`). The full value semantics are conformance-tested against
+ * URLSearchParams in the shared golden vectors (TestHelperVectors, fn "query").
+ */
+import { describe, test, expect } from 'bun:test'
+import { compileJSX, type ComponentIR } from '@barefootjs/jsx'
+import { GoTemplateAdapter } from '../adapter/go-template-adapter'
+
+function generate(src: string) {
+  const adapter = new GoTemplateAdapter()
+  const result = compileJSX(src.trimStart(), 'T.tsx', { adapter, outputIR: true })
+  const irFile = result.files.find(f => f.type === 'ir')
+  if (!irFile) throw new Error('no IR')
+  const ir = JSON.parse(irFile.content) as ComponentIR
+  return adapter.generate(ir)
+}
+
+describe('queryHref → bf_query (#2042)', () => {
+  test('a plain value passes a `true` include — bf_query drops it if empty', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; tag: string }) {
+  return <a href={queryHref(props.base, { tag: props.tag })}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain('bf_query .Base (true) "tag" .Tag')
+    expect(template).not.toContain('.QueryHref')
+  })
+
+  test('a conditional include lowers to `(cond)` — the helper applies the non-empty check', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; sort: string; tag: string }) {
+  return (
+    <a href={queryHref(props.base, {
+      sort: props.sort !== 'date' ? props.sort : undefined,
+      tag: props.tag,
+    })}>x</a>
+  )
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain(
+      'bf_query .Base (ne (bf_string .Sort) "date") "sort" .Sort (true) "tag" .Tag',
+    )
+    // The `ne consequent ""` non-empty check is no longer folded into the
+    // include — bf_query owns it (so it can also append array values).
+    expect(template).not.toContain('(ne .Sort "")')
+  })
+
+  // A `&&` / `||` guard is NOT a comparison, so `lowerUrlGuard` can't emit it as
+  // a bare Go bool — `and`/`or` return one of their operands (a string), which
+  // `bf_query` type-asserts against. It must take the truthiness-wrap path,
+  // `ne (and …) ""`, yielding a real bool.
+  test('a `&&` guard is wrapped to a bool — `ne (and …) ""`, not a bare `and`', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; a: string; b: string }) {
+  return <a href={queryHref(props.base, { both: props.a && props.b ? props.a : undefined })}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain('bf_query .Base (ne (and .A .B) "") "both" .A')
+  })
+
+  test('null / empty-string alternates are both treated as the omit branch', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; mode: string; a: string; b: string }) {
+  return <a href={queryHref(props.base, {
+    a: props.mode !== 'off' ? props.a : '',
+    b: props.mode !== 'off' ? props.b : null,
+  })}>x</a>
+}
+`
+    const { template } = generate(src)
+    // Both '' and null alternates fold to the same conditional-include form.
+    expect(template).toContain('(ne (bf_string .Mode) "off") "a" .A')
+    expect(template).toContain('(ne (bf_string .Mode) "off") "b" .B')
+  })
+
+  test('an array value lowers the slice expression; bf_query appends its members', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; tags: string[] }) {
+  return <a href={queryHref(props.base, { tag: props.tags })}>x</a>
+}
+`
+    const { template } = generate(src)
+    // The value is the raw slice field; member-append + non-empty omit happen in
+    // the helper at render time (verified against URLSearchParams in the golden
+    // vectors). The old `ne value ""` fold would have been invalid Go here.
+    expect(template).toContain('bf_query .Base (true) "tag" .Tags')
+  })
+
+  test('a conditional array value keeps the guard and passes the slice', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; on: string; tags: string[] }) {
+  return <a href={queryHref(props.base, { tag: props.on !== '' ? props.tags : undefined })}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain('bf_query .Base (ne (bf_string .On) "") "tag" .Tags')
+  })
+
+  test('an aliased import is still recognised', () => {
+    const src = `
+'use client'
+import { queryHref as qh } from '@barefootjs/client'
+export function P(props: { base: string; tag: string }) {
+  return <a href={qh(props.base, { tag: props.tag })}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain('bf_query .Base')
+    expect(template).toContain('"tag" .Tag')
+  })
+
+  test('a param-free expression-bodied helper wrapping queryHref inlines + lowers', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string }) {
+  const homeHref = () => queryHref(props.base, { view: 'home' })
+  return <a href={homeHref()}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain('bf_query .Base (true) "view" "home"')
+    expect(template).not.toContain('.HomeHref')
+  })
+
+  // Known limitation (pre-existing, not queryHref-specific): the generic helper
+  // inliner declines a body whose object literal references the helper's params,
+  // because an object literal lowers opaquely from its `raw` source — so the
+  // param can't be substituted. queryHref's idiom is the direct call, so this is
+  // a minor gap; helper-delegation ergonomics are a follow-up (#2042).
+  test('a helper whose params-object references a param is not yet inlined (falls back)', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string }) {
+  const hrefFor = (s: string) => queryHref(props.base, { sort: s })
+  return <a href={hrefFor('title')}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).not.toContain('bf_query')
+    expect(template).toContain('.HrefFor "title"')
+  })
+
+  test('a dynamic (non-literal) params object falls back to the generic lowering', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; q: Record<string, string> }) {
+  return <a href={queryHref(props.base, props.q)}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).not.toContain('bf_query')
+  })
+})

package/src/adapter/analysis/component-tree.ts

@@ -0,0 +1,174 @@
+/**
+ * IR component-tree analysis for the Go html/template adapter.
+ *
+ * Pure structural walks over the IR — no adapter instance state, no rendering.
+ * Only the two entry points (`hasClientInteractivity`,
+ * `findNestedComponents`) are exported; the recursive collectors stay
+ * module-internal.
+ */
+
+import type {
+  ComponentIR,
+  IRNode,
+  IRElement,
+  IRFragment,
+  IRConditional,
+  IRLoop,
+  IRIfStatement,
+  IRComponent,
+} from '@barefootjs/jsx'
+
+import type { NestedComponentInfo } from '../lib/types.ts'
+
+/**
+ * Does the component need client JS? True when it has reactive state
+ * (signals), effects, onMounts, any event handler in the tree, or any
+ * child component (which needs the parent's hydration).
+ */
+export function hasClientInteractivity(ir: ComponentIR): boolean {
+  if (ir.metadata.signals.length > 0) return true
+  if (ir.metadata.effects.length > 0) return true
+  if (ir.metadata.onMounts.length > 0) return true
+  if (hasEventsInTree(ir.root)) return true
+  // Child components need the parent's hydration.
+  if (findChildComponentNames(ir.root).size > 0) return true
+  return false
+}
+
+/** Recursively check if any element in the tree has events. */
+function hasEventsInTree(node: IRNode): boolean {
+  if (node.type === 'element') {
+    const element = node as IRElement
+    if (element.events.length > 0) return true
+    for (const child of element.children) {
+      if (hasEventsInTree(child)) return true
+    }
+  } else if (node.type === 'fragment') {
+    const fragment = node as IRFragment
+    for (const child of fragment.children) {
+      if (hasEventsInTree(child)) return true
+    }
+  } else if (node.type === 'conditional') {
+    const cond = node as IRConditional
+    if (hasEventsInTree(cond.whenTrue)) return true
+    if (cond.whenFalse && hasEventsInTree(cond.whenFalse)) return true
+  } else if (node.type === 'loop') {
+    const loop = node as IRLoop
+    for (const child of loop.children) {
+      if (hasEventsInTree(child)) return true
+    }
+  } else if (node.type === 'if-statement') {
+    const ifStmt = node as IRIfStatement
+    if (hasEventsInTree(ifStmt.consequent)) return true
+    if (ifStmt.alternate && hasEventsInTree(ifStmt.alternate)) return true
+  }
+  return false
+}
+
+/** Find all child component names used in the IR tree. */
+function findChildComponentNames(node: IRNode): Set<string> {
+  const names = new Set<string>()
+  collectChildComponentNames(node, names)
+  return names
+}
+
+function collectChildComponentNames(node: IRNode, names: Set<string>): void {
+  if (node.type === 'component') {
+    const comp = node as IRComponent
+    names.add(comp.name)
+  } else if (node.type === 'element') {
+    const element = node as IRElement
+    for (const child of element.children) {
+      collectChildComponentNames(child, names)
+    }
+  } else if (node.type === 'fragment') {
+    const fragment = node as IRFragment
+    for (const child of fragment.children) {
+      collectChildComponentNames(child, names)
+    }
+  } else if (node.type === 'conditional') {
+    const cond = node as IRConditional
+    collectChildComponentNames(cond.whenTrue, names)
+    if (cond.whenFalse) {
+      collectChildComponentNames(cond.whenFalse, names)
+    }
+  } else if (node.type === 'loop') {
+    const loop = node as IRLoop
+    for (const child of loop.children) {
+      collectChildComponentNames(child, names)
+    }
+  } else if (node.type === 'if-statement') {
+    const ifStmt = node as IRIfStatement
+    collectChildComponentNames(ifStmt.consequent, names)
+    if (ifStmt.alternate) {
+      collectChildComponentNames(ifStmt.alternate, names)
+    }
+  }
+}
+
+/**
+ * Find all nested components (loops with `childComponent`). Returns extended
+ * info that includes whether the component comes from a dynamic (signal) array
+ * loop vs a static one.
+ */
+export function findNestedComponents(node: IRNode): NestedComponentInfo[] {
+  const result: NestedComponentInfo[] = []
+  collectNestedComponents(node, result)
+  return result
+}
+
+function collectNestedComponents(node: IRNode, result: NestedComponentInfo[]): void {
+  if (node.type === 'loop') {
+    const loop = node as IRLoop
+    if (loop.childComponent) {
+      if (!result.some(c => c.name === loop.childComponent!.name)) {
+        const hasBodyChildren = loop.childComponent.children.length > 0
+        result.push({
+          ...loop.childComponent,
+          isDynamic: !loop.isStaticArray,
+          isPropDerived: !!loop.isPropDerivedArray,
+          loopKey: loop.key ?? undefined,
+          loopParam: loop.param ?? undefined,
+          bodyChildren: hasBodyChildren ? loop.childComponent.children : undefined,
+          loopArray: loop.array,
+          loopArrayParsed: loop.arrayParsed,
+          loopMarkerId: loop.markerId,
+          loopItemType: loop.itemType,
+        })
+      }
+    }
+    for (const child of loop.children) {
+      collectNestedComponents(child, result)
+    }
+  } else if (node.type === 'element') {
+    const element = node as IRElement
+    for (const child of element.children) {
+      collectNestedComponents(child, result)
+    }
+  } else if (node.type === 'fragment') {
+    const fragment = node as IRFragment
+    for (const child of fragment.children) {
+      collectNestedComponents(child, result)
+    }
+  } else if (node.type === 'conditional') {
+    const cond = node as IRConditional
+    collectNestedComponents(cond.whenTrue, result)
+    if (cond.whenFalse) {
+      collectNestedComponents(cond.whenFalse, result)
+    }
+  } else if (node.type === 'if-statement') {
+    const stmt = node as IRIfStatement
+    collectNestedComponents(stmt.consequent, result)
+    if (stmt.alternate) {
+      collectNestedComponents(stmt.alternate, result)
+    }
+  } else if (node.type === 'component') {
+    // JSX children passed to an imported component render via a companion
+    // define with the PARENT's data, so a keyed loop nested inside them needs
+    // its `<Name>s` slice on THIS component's props like any other nested loop.
+    const comp = node as IRComponent
+    for (const child of comp.children) {
+      collectNestedComponents(child, result)
+    }
+  }
+}

package/src/adapter/emit-context.ts

@@ -0,0 +1,59 @@
+/**
+ * The contract extracted emit modules depend on instead of the concrete
+ * `GoTemplateAdapter`.
+ *
+ * The Go adapter's lowering is deeply mutually recursive (expression ↔
+ * condition ↔ rendering), so a module pulled out still needs to call back into
+ * the shared per-compile state and the recursive entry points. `GoEmitContext`
+ * is that seam: extracted free functions take it as their first argument, and
+ * the adapter — which owns the state and implements the entry points — passes
+ * `this`. Modules depend on this narrow interface, so they stay unit-testable
+ * against a stub.
+ *
+ * Keep this surface minimal: add a member only when an extracted module
+ * genuinely needs it, so the seam documents the real cross-module coupling.
+ */
+
+import type { ParsedExpr } from '@barefootjs/jsx'
+
+import type { CompileState } from './lib/compile-state.ts'
+
+export interface GoEmitContext {
+  /** Per-compile mutable state (signals, consts, type tables, errors, …). */
+  readonly state: CompileState
+
+  /**
+   * Lower a JS expression to its Go-template form (the core recursive entry).
+   * `preParsed` reuses an already-built tree instead of re-parsing `jsExpr`.
+   */
+  convertExpressionToGo(
+    jsExpr: string,
+    out?: { parsed?: ParsedExpr },
+    preParsed?: ParsedExpr,
+  ): string
+
+  /**
+   * Lower a JS condition to a Go-template bool + any hoisted preamble.
+   * `preParsed` reuses an already-built tree instead of re-parsing `jsCondition`.
+   */
+  convertConditionToGo(
+    jsCondition: string,
+    preParsed?: ParsedExpr,
+  ): { condition: string; preamble: string }
+
+  /** Extract the prop name from a `props.X ?? …` initial value, or null. */
+  extractPropNameFromInitialValue(initialValue: string): string | null
+
+  /**
+   * Parse a signal-time initial value `props.X ?? <literal>` into the source
+   * prop name and the Go-formatted fallback, or null when it isn't that shape.
+   */
+  extractPropFallback(initialValue: string): { propName: string; goFallback: string } | null
+
+  /**
+   * Inline a module string const by name as a Go double-quoted literal
+   * (`"<escaped>"`), or null when the name is not such a const (loop vars and
+   * outer-loop params are excluded).
+   */
+  resolveModuleStringConst(name: string): string | null
+}