@barefootjs/jsx 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/jsx",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "JSX compiler for BarefootJS - transforms JSX to server HTML + client JS",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,10 +49,10 @@
     "directory": "packages/jsx"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.2.0"
+    "@barefootjs/shared": "0.4.0"
   },
   "peerDependencies": {
-    "@barefootjs/client": "0.2.0",
+    "@barefootjs/client": ">=0.2.0",
     "typescript": "^5.0.0"
   },
   "devDependencies": {

package/src/__tests__/auto-defer-brand.test.ts

@@ -0,0 +1,284 @@
+/**
+ * Auto-defer of reactive brand-package bindings (#1638).
+ *
+ * Controlled bindings to `@barefootjs/form` state — `value={field.value()}`,
+ * `disabled={form.isSubmitting()}`, `{field.error() && …}` — read per-instance
+ * init-scope state (`createForm` calls `createSignal` internally) that the
+ * module-scope SSR template lambda cannot evaluate. Previously each binding
+ * raised BF061 and forced a manual `/* @client *​/`. The compiler now treats
+ * such reads as implicitly client-only: the SSR template skips them and a
+ * hydrate-time effect applies the value — exactly what `/* @client *​/` did.
+ *
+ * These tests need a real TypeChecker that resolves the `Reactive<T>` brand,
+ * so they build a ts.Program with virtual form-library type defs and inject
+ * it into `compileJSX` (the brand is invisible to the regex fallback).
+ */
+
+import { describe, test, expect } from 'bun:test'
+import ts from 'typescript'
+import path from 'path'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+import { extractTemplateBody, extractInitBody } from './staged-ir/helpers'
+
+const adapter = new TestAdapter()
+
+const FORM_DEFS = `
+  export type Reactive<T> = T & { readonly __reactive: true };
+  export type Memo<T> = Reactive<() => T>;
+
+  export interface FieldReturn<V> {
+    value: Reactive<() => V>;
+    error: Reactive<() => string>;
+    setValue: (value: V) => void;
+    handleInput: (e: Event) => void;
+  }
+
+  export interface FormReturn {
+    field: (name: string) => FieldReturn<string>;
+    isSubmitting: Reactive<() => boolean>;
+    handleSubmit: (e: Event) => Promise<void>;
+  }
+
+  export declare function createForm(opts?: unknown): FormReturn;
+`
+
+interface BrandCompileResult {
+  errors: string[]
+  templateBody: string
+  initBody: string
+  clientJs: string
+}
+
+/**
+ * Compile `componentSource` with a TypeChecker that resolves the form brand.
+ * The component must `import { createForm } from './_form-defs'`.
+ */
+function compileWithBrand(componentSource: string): BrandCompileResult {
+  const baseDir = path.resolve(__dirname)
+  const componentPath = path.join(baseDir, '_brand-component.tsx')
+  const defsPath = path.join(baseDir, '_form-defs.ts')
+
+  const virtualFiles = new Map<string, string>([
+    [componentPath, componentSource],
+    [defsPath, FORM_DEFS],
+  ])
+
+  const compilerOptions: ts.CompilerOptions = {
+    target: ts.ScriptTarget.Latest,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    jsx: ts.JsxEmit.ReactJSX,
+    strict: true,
+    skipLibCheck: true,
+    noEmit: true,
+  }
+
+  const defaultHost = ts.createCompilerHost(compilerOptions)
+  const host: ts.CompilerHost = {
+    ...defaultHost,
+    getSourceFile(fileName, languageVersion) {
+      const resolved = path.resolve(fileName)
+      const content = virtualFiles.get(resolved)
+      if (content !== undefined) {
+        const kind = resolved.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+        return ts.createSourceFile(fileName, content, languageVersion, true, kind)
+      }
+      return defaultHost.getSourceFile(fileName, languageVersion)
+    },
+    fileExists(fileName) {
+      return virtualFiles.has(path.resolve(fileName)) || defaultHost.fileExists(fileName)
+    },
+    readFile(fileName) {
+      return virtualFiles.get(path.resolve(fileName)) ?? defaultHost.readFile(fileName)
+    },
+  }
+
+  const program = ts.createProgram([componentPath], compilerOptions, host)
+  const result = compileJSX(componentSource, componentPath, { adapter, program })
+  const clientJs = result.files.find((f) => f.type === 'clientJs')?.content ?? ''
+  return {
+    errors: result.errors.map((e) => `[${e.code}] ${e.message}`),
+    templateBody: extractTemplateBody(clientJs),
+    initBody: extractInitBody(clientJs),
+    clientJs,
+  }
+}
+
+describe('auto-defer brand-package reactive bindings (#1638)', () => {
+  test('sanity: the injected program resolves the Reactive<T> brand', () => {
+    // If the brand did not resolve, the regex fallback would not flag
+    // `email.value()` reactive and nothing below would be meaningful.
+    const { errors } = compileWithBrand(`
+      'use client'
+      import { createForm } from './_form-defs'
+
+      export function Probe() {
+        const form = createForm()
+        const email = form.field('email')
+        return <input value={email.value()} />
+      }
+    `)
+    // No BF050 (we supplied a program) and, crucially, no BF061.
+    expect(errors.find((e) => e.startsWith('[BF061]'))).toBeUndefined()
+  })
+
+  test('element attribute `value={field.value()}` does not raise BF061', () => {
+    const { errors, templateBody, initBody } = compileWithBrand(`
+      'use client'
+      import { createForm } from './_form-defs'
+
+      export function SignupForm() {
+        const form = createForm()
+        const email = form.field('email')
+        return <input value={email.value()} />
+      }
+    `)
+
+    expect(errors.find((e) => e.startsWith('[BF061]'))).toBeUndefined()
+    // SSR template must not carry the deferred attribute...
+    expect(templateBody).not.toContain('value=')
+    // ...but the element keeps a slot marker and init wires the value.
+    expect(templateBody).toMatch(/bf="s\d+"/)
+    expect(initBody).toMatch(/setAttribute\(['"]value['"]|\.value\s*=/)
+  })
+
+  test('multiple controlled bindings each defer (value + disabled)', () => {
+    const { errors, templateBody } = compileWithBrand(`
+      'use client'
+      import { createForm } from './_form-defs'
+
+      export function SignupForm() {
+        const form = createForm()
+        const email = form.field('email')
+        return <input value={email.value()} disabled={form.isSubmitting()} />
+      }
+    `)
+
+    expect(errors.find((e) => e.startsWith('[BF061]'))).toBeUndefined()
+    expect(templateBody).not.toContain('value=')
+    expect(templateBody).not.toContain('disabled=')
+  })
+
+  test('conditional condition `field.error() && <p/>` defers instead of BF061', () => {
+    const { errors } = compileWithBrand(`
+      'use client'
+      import { createForm } from './_form-defs'
+
+      export function SignupForm() {
+        const form = createForm()
+        const email = form.field('email')
+        return (
+          <form>
+            <input value={email.value()} />
+            {email.error() && <p>{email.error()}</p>}
+          </form>
+        )
+      }
+    `)
+
+    expect(errors.find((e) => e.startsWith('[BF061]'))).toBeUndefined()
+    expect(errors.find((e) => e.startsWith('[BF060]'))).toBeUndefined()
+  })
+
+  test('native createSignal getter is NOT deferred (keeps SSR value)', () => {
+    // Same component imports the brand package (so a TypeChecker is present),
+    // but `count()` is a real signal with a derivable initial value — it must
+    // keep rendering server-side, not get stripped to a hydrate-only binding.
+    const { templateBody } = compileWithBrand(`
+      'use client'
+      import { createForm } from './_form-defs'
+      import { createSignal } from '@barefootjs/client'
+
+      export function Mixed() {
+        const form = createForm()
+        const [count, setCount] = createSignal(0)
+        return <input data-count={count()} />
+      }
+    `)
+
+    // The signal-backed attribute is still emitted into the SSR template.
+    expect(templateBody).toContain('data-count=')
+  })
+})
+
+describe('client hydrate template defers brand conditionals (#1645)', () => {
+  // The `template: (_p) => ...` lambda runs at module scope when the
+  // component is client-rendered via `createComponent` (not when hydrating
+  // existing SSR DOM). It cannot reproduce per-instance `createForm` state,
+  // so an auto-deferred conditional must emit empty cond markers — exactly
+  // like the SSR adapter — and let `init`'s `insert()` populate the branch.
+
+  test('non-inlinable createForm (onSubmit): no undefined.field, emits cond markers', () => {
+    const { templateBody } = compileWithBrand(`
+      'use client'
+      import { createForm } from './_form-defs'
+
+      export function SignupForm() {
+        const form = createForm({
+          onSubmit: async (data) => { await fetch('/signup', { method: 'POST', body: JSON.stringify(data) }) },
+        })
+        const email = form.field('email')
+        return (
+          <form>
+            <input value={email.value()} />
+            {email.error() && <p>{email.error()}</p>}
+          </form>
+        )
+      }
+    `)
+
+    // Never re-derive the form at module scope: `undefined.field(...)` throws.
+    expect(templateBody).not.toContain('undefined.field')
+    expect(templateBody).not.toContain('.field(')
+    // The deferred conditional collapses to the same empty markers SSR emits.
+    expect(templateBody).toMatch(/<!--bf-cond-start:s\d+--><!--bf-cond-end:s\d+-->/)
+  })
+
+  test('inlinable createForm (no onSubmit): no re-inlined createForm in template', () => {
+    const { templateBody } = compileWithBrand(`
+      'use client'
+      import { createForm } from './_form-defs'
+
+      export function SignupForm() {
+        const form = createForm({ defaultValues: { email: '' } })
+        const email = form.field('email')
+        return (
+          <form>
+            <input value={email.value()} />
+            {email.error() && <p>{email.error()}</p>}
+          </form>
+        )
+      }
+    `)
+
+    // A re-inlined `createForm({...})` would build a throwaway instance on
+    // every template render (error always '', never the live instance).
+    expect(templateBody).not.toContain('createForm(')
+    expect(templateBody).not.toContain('undefined.field')
+    expect(templateBody).toMatch(/<!--bf-cond-start:s\d+--><!--bf-cond-end:s\d+-->/)
+  })
+
+  test('init still wires the deferred conditional via insert()', () => {
+    const { initBody } = compileWithBrand(`
+      'use client'
+      import { createForm } from './_form-defs'
+
+      export function SignupForm() {
+        const form = createForm()
+        const email = form.field('email')
+        return (
+          <form>
+            <input value={email.value()} />
+            {email.error() && <p>{email.error()}</p>}
+          </form>
+        )
+      }
+    `)
+
+    // The reactive binding lives in init (where `email`/`form` are in scope),
+    // not in the module-scope template lambda.
+    expect(initBody).toMatch(/insert\(/)
+    expect(initBody).toContain('email.error()')
+  })
+})

package/src/__tests__/debug.test.ts

@@ -11,14 +11,20 @@ import {
   buildEventSummary,
   buildComponentAnalysis,
   buildLoopSummary,
+  buildWhyUpdate,
   traceUpdatePath,
   formatComponentGraph,
   formatUpdatePath,
   formatEventSummary,
   formatLoopSummary,
+  formatWhyUpdate,
   formatSignalTrace,
   generateStaticTrace,
   graphToJSON,
+  describeFallback,
+  formatFallbackExplanations,
+  buildComponentSummary,
+  formatComponentSummary,
 } from '../debug'
 
 const counterSource = `
@@ -815,7 +821,7 @@ describe('buildEventSummary', () => {
     expect(click.setterCalls).toHaveLength(1)
     expect(click.setterCalls[0].setter).toBe('setTodos')
     expect(click.setterCalls[0].signal).toBe('todos')
-    expect(click.setterCalls[0].via).toBe('addTodo')
+    expect(click.setterCalls[0].via).toEqual(['addTodo'])
   })
 
   test('includes component prop events (Button.onClick)', () => {
@@ -1055,3 +1061,342 @@ describe('formatLoopSummary', () => {
     expect(textBindings.length).toBeGreaterThan(0)
   })
 })
+
+// =============================================================================
+// Why-update analysis (bf debug why-update)
+// =============================================================================
+
+describe('buildWhyUpdate', () => {
+  test('traces attribute binding back to signal and event handler', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      export function Panel() {
+        const [color, setColor] = createSignal('red')
+        return (
+          <div>
+            <div style={color()} />
+            <button onClick={() => setColor('blue')}>Change</button>
+          </div>
+        )
+      }
+    `
+    const result = buildWhyUpdate(source, 'Panel.tsx', 'style')
+    expect(result).not.toBeNull()
+    expect(result!.binding).toBe('style')
+    expect(result!.expression).toContain('color()')
+    expect(result!.deps).toHaveLength(1)
+    expect(result!.deps[0].name).toBe('color')
+    expect(result!.deps[0].kind).toBe('signal')
+    expect(result!.deps[0].changedBy.length).toBeGreaterThan(0)
+    expect(result!.deps[0].changedBy[0].setter).toBe('setColor')
+  })
+
+  test('traces through memo dependencies', () => {
+    const source = `
+      'use client'
+      import { createSignal, createMemo } from '@barefootjs/client'
+
+      export function Dashboard() {
+        const [count, setCount] = createSignal(0)
+        const doubled = createMemo(() => count() * 2)
+        return (
+          <div>
+            <span>{doubled()}</span>
+            <button onClick={() => setCount(n => n + 1)}>+</button>
+          </div>
+        )
+      }
+    `
+    const result = buildWhyUpdate(source, 'Dashboard.tsx', 's0')
+    expect(result).not.toBeNull()
+    const memoDep = result!.deps.find(d => d.kind === 'memo')
+    expect(memoDep).toBeDefined()
+    expect(memoDep!.name).toBe('doubled')
+    expect(memoDep!.dependsOn).toContain('count')
+    const signalDep = result!.deps.find(d => d.kind === 'signal')
+    expect(signalDep).toBeDefined()
+    expect(signalDep!.name).toBe('count')
+    expect(signalDep!.changedBy[0].setter).toBe('setCount')
+  })
+
+  test('returns null for unknown binding', () => {
+    const result = buildWhyUpdate(counterSource, 'Counter.tsx', 'nonExistent')
+    expect(result).toBeNull()
+  })
+
+  test('traces indirect setter via local function', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      export function App() {
+        const [items, setItems] = createSignal([])
+        function addItem(text: string) {
+          setItems(prev => [...prev, text])
+        }
+        return (
+          <div>
+            <span>{items().length}</span>
+            <button onClick={() => addItem('test')}>Add</button>
+          </div>
+        )
+      }
+    `
+    const result = buildWhyUpdate(source, 'App.tsx', 's0')
+    expect(result).not.toBeNull()
+    const signalDep = result!.deps.find(d => d.name === 'items')
+    expect(signalDep).toBeDefined()
+    expect(signalDep!.changedBy[0].via).toEqual(['addItem'])
+  })
+
+  test('includes classification and wrapReason for fallback bindings', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { formatTitle } from './format'
+
+      export function Page() {
+        const [, setFoo] = createSignal(0)
+        const page = 'home'
+        return <h1 onClick={() => setFoo(1)}>{formatTitle(page)}</h1>
+      }
+    `
+    const graph = buildComponentGraph(source, 'Page.tsx')
+    const fallback = graph.domBindings.find(d => d.classification === 'fallback' && d.type === 'text')
+    expect(fallback).toBeDefined()
+    const result = buildWhyUpdate(source, 'Page.tsx', fallback!.slotId)
+    expect(result).not.toBeNull()
+    expect(result!.classification).toBe('fallback')
+    expect(result!.wrapReason).toBeDefined()
+    expect(result!.deps).toHaveLength(0)
+  })
+
+  test('returns ambiguous result when multiple bindings share the same label', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      export function TwoStyles() {
+        const [a, setA] = createSignal('red')
+        const [b, setB] = createSignal('blue')
+        return (
+          <div>
+            <div style={a()} />
+            <div style={b()} />
+            <button onClick={() => setA('green')}>A</button>
+          </div>
+        )
+      }
+    `
+    const result = buildWhyUpdate(source, 'TwoStyles.tsx', 'style')
+    expect(result).not.toBeNull()
+    expect(result!.ambiguous).toBeDefined()
+    expect(result!.ambiguous!.length).toBeGreaterThan(1)
+  })
+})
+
+describe('formatWhyUpdate', () => {
+  test('produces readable output', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      export function Panel() {
+        const [color, setColor] = createSignal('red')
+        return (
+          <div>
+            <div style={color()} />
+            <button onClick={() => setColor('blue')}>Change</button>
+          </div>
+        )
+      }
+    `
+    const result = buildWhyUpdate(source, 'Panel.tsx', 'style')!
+    const output = formatWhyUpdate(result)
+    expect(output).toContain('style updates because:')
+    expect(output).toContain('color changes from:')
+    expect(output).toContain('setColor')
+  })
+
+  test('shows fallback note when binding is fallback-wrapped', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { formatTitle } from './format'
+
+      export function Page() {
+        const [, setFoo] = createSignal(0)
+        return <h1 onClick={() => setFoo(1)}>{formatTitle('x')}</h1>
+      }
+    `
+    const graph = buildComponentGraph(source, 'Page.tsx')
+    const fallback = graph.domBindings.find(d => d.classification === 'fallback' && d.type === 'text')
+    expect(fallback).toBeDefined()
+    const result = buildWhyUpdate(source, 'Page.tsx', fallback!.slotId)!
+    const output = formatWhyUpdate(result)
+    expect(output).toContain('fallback-wrapped binding')
+    expect(output).toContain('could not statically prove')
+  })
+})
+
+// =============================================================================
+// Fallback explanations (bf debug fallbacks improved, #1611 TODO 5)
+// =============================================================================
+
+describe('describeFallback', () => {
+  test('provides human-readable reason for opaque function call', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { formatTitle } from './format'
+
+      export function Page() {
+        const [, setFoo] = createSignal(0)
+        const page = 'home'
+        return <h1 onClick={() => setFoo(1)}>{formatTitle(page)}</h1>
+      }
+    `
+    const graph = buildComponentGraph(source, 'Page.tsx')
+    const fallback = graph.domBindings.find(d => d.classification === 'fallback' && d.type === 'text')
+    expect(fallback).toBeDefined()
+    const ex = describeFallback(fallback!)
+    expect(ex.reason).toContain('opaque function call')
+    expect(ex.reason).toContain('text interpolation')
+    expect(ex.suggestion).toContain('createMemo')
+    expect(ex.isEventHandler).toBe(false)
+  })
+
+  test('identifies event handler props as safe fallbacks', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { Button } from './Button'
+
+      export function Counter() {
+        const [count, setCount] = createSignal(0)
+        return <Button onClick={() => setCount(0)}>Reset</Button>
+      }
+    `
+    const graph = buildComponentGraph(source, 'Counter.tsx')
+    const fallback = graph.domBindings.find(d =>
+      d.classification === 'fallback' && d.label.includes('onClick'),
+    )
+    expect(fallback).toBeDefined()
+    const ex = describeFallback(fallback!)
+    expect(ex.isEventHandler).toBe(true)
+    expect(ex.suggestion).toContain('safe to ignore')
+  })
+
+  test('includes source location', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { format } from './fmt'
+
+      export function Tag() {
+        const [, setFoo] = createSignal(0)
+        return <button class={format('x')} onClick={() => setFoo(1)}>x</button>
+      }
+    `
+    const graph = buildComponentGraph(source, 'Tag.tsx')
+    const fallback = graph.domBindings.find(d => d.classification === 'fallback' && d.type === 'attribute')
+    expect(fallback).toBeDefined()
+    const ex = describeFallback(fallback!)
+    expect(ex.loc).toBeDefined()
+    expect(ex.loc!.line).toBeGreaterThan(0)
+  })
+})
+
+describe('formatFallbackExplanations', () => {
+  test('produces detailed output with reason and suggestion', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { formatTitle } from './format'
+
+      export function Page() {
+        const [, setFoo] = createSignal(0)
+        const page = 'home'
+        return <h1 onClick={() => setFoo(1)}>{formatTitle(page)}</h1>
+      }
+    `
+    const graph = buildComponentGraph(source, 'Page.tsx')
+    const fallbacks = graph.domBindings.filter(d => d.classification === 'fallback')
+    const output = formatFallbackExplanations(graph.componentName, fallbacks)
+    expect(output).toContain('fallback:')
+    expect(output).toContain('expression:')
+    expect(output).toContain('reason:')
+    expect(output).toContain('suggestion:')
+    expect(output).toContain('runtime deps:')
+  })
+
+  test('returns clean message for zero fallbacks', () => {
+    const output = formatFallbackExplanations('Counter', [])
+    expect(output).toContain('no fallback-wrapped expressions')
+  })
+})
+
+// =============================================================================
+// Component summary (bf debug summary, #1611 TODO 6)
+// =============================================================================
+
+describe('buildComponentSummary', () => {
+  test('counts signals, memos, effects, and bindings for a client component', () => {
+    const summary = buildComponentSummary(dashboardSource, 'Dashboard.tsx')
+    expect(summary.componentName).toBe('Dashboard')
+    expect(summary.hydrated).toBe(true)
+    expect(summary.clientBundle).toBe('Dashboard.client.js')
+    expect(summary.signals).toBe(1)
+    expect(summary.memos).toBe(1)
+    expect(summary.effects).toBe(1)
+    expect(summary.eventHandlers).toBeGreaterThanOrEqual(1)
+    expect(summary.dynamicTextBindings).toBeGreaterThanOrEqual(1)
+  })
+
+  test('reports non-hydrated for stateless component', () => {
+    const source = `
+      export function Card(props: { title: string }) {
+        return <div>{props.title}</div>
+      }
+    `
+    const summary = buildComponentSummary(source, 'Card.tsx')
+    expect(summary.hydrated).toBe(false)
+    expect(summary.clientBundle).toBeNull()
+    expect(summary.signals).toBe(0)
+  })
+
+  test('counts loops', () => {
+    const summary = buildComponentSummary(todoSource, 'TodoList.tsx')
+    expect(summary.loops).toBeGreaterThanOrEqual(1)
+  })
+
+  test('counts fallbacks', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { formatTitle } from './format'
+
+      export function Page() {
+        const [, setFoo] = createSignal(0)
+        return <h1 onClick={() => setFoo(1)}>{formatTitle('x')}</h1>
+      }
+    `
+    const summary = buildComponentSummary(source, 'Page.tsx')
+    expect(summary.fallbacks).toBeGreaterThanOrEqual(1)
+  })
+})
+
+describe('formatComponentSummary', () => {
+  test('produces readable output', () => {
+    const summary = buildComponentSummary(dashboardSource, 'Dashboard.tsx')
+    const output = formatComponentSummary(summary)
+    expect(output).toContain('Dashboard')
+    expect(output).toContain('hydrated: yes')
+    expect(output).toContain('signals: 1')
+    expect(output).toContain('memos: 1')
+    expect(output).toContain('event handlers:')
+    expect(output).toContain('dynamic text bindings:')
+  })
+})