@barefootjs/cli 0.1.0

package/dist/docs/core/adapters/custom-adapter.md

@@ -0,0 +1,357 @@
+---
+title: Writing a Custom Adapter
+description: Step-by-step guide to building a custom adapter using the TestAdapter as a reference.
+---
+
+# Writing a Custom Adapter
+
+Build a custom adapter using the `TestAdapter` (`packages/jsx/src/adapters/test-adapter.ts`) as reference — a minimal working adapter that generates JSX output.
+
+
+## Step 1: Implement `TemplateAdapter`
+
+Extend `BaseAdapter` or implement `TemplateAdapter` directly:
+
+```typescript
+import type {
+  ComponentIR,
+  IRNode,
+  IRElement,
+  IRText,
+  IRExpression,
+  IRConditional,
+  IRLoop,
+  IRComponent,
+  IRFragment,
+  ParamInfo,
+} from '../types'
+import { type AdapterOutput, BaseAdapter } from './interface'
+
+export class TestAdapter extends BaseAdapter {
+  name = 'test'
+  extension = '.test.tsx'
+
+  private componentName: string = ''
+
+  generate(ir: ComponentIR): AdapterOutput {
+    this.componentName = ir.metadata.componentName
+
+    const imports = this.generateImports(ir)
+    const types = this.generateTypes(ir)
+    const component = this.generateComponent(ir)
+
+    const template = [imports, types, component].filter(Boolean).join('\n\n')
+
+    return {
+      template,
+      types: types || undefined,
+      extension: this.extension,
+    }
+  }
+
+  // ... node rendering methods (see below)
+}
+```
+
+## Step 2: Implement `renderNode()`
+
+Route each IR node to the correct rendering method:
+
+```typescript
+renderNode(node: IRNode): string {
+  switch (node.type) {
+    case 'element':     return this.renderElement(node)
+    case 'text':        return (node as IRText).value
+    case 'expression':  return this.renderExpression(node)
+    case 'conditional': return this.renderConditional(node)
+    case 'loop':        return this.renderLoop(node)
+    case 'component':   return this.renderComponent(node)
+    case 'fragment':    return this.renderChildren((node as IRFragment).children)
+    case 'slot':        return '{children}'
+    default:            return ''
+  }
+}
+```
+
+## Step 3: Implement Element Rendering
+
+Render the tag, attributes, hydration markers, and children:
+
+```typescript
+renderElement(element: IRElement): string {
+  const tag = element.tag
+  const attrs = this.renderAttributes(element)
+  const children = this.renderChildren(element.children)
+
+  let hydrationAttrs = ''
+  if (element.needsScope) {
+    hydrationAttrs += ' bf-s={__scopeId}'
+  }
+  if (element.slotId) {
+    hydrationAttrs += ` bf="${element.slotId}"`
+  }
+
+  if (children) {
+    return `<${tag}${attrs}${hydrationAttrs}>${children}</${tag}>`
+  } else {
+    return `<${tag}${attrs}${hydrationAttrs} />`
+  }
+}
+```
+
+### Attributes
+
+```typescript
+private renderAttributes(element: IRElement): string {
+  const parts: string[] = []
+
+  for (const attr of element.attrs) {
+    const attrName = attr.name === 'class' ? 'className' : attr.name
+
+    if (attr.name === '...') {
+      parts.push(`{...${attr.value}}`)
+    } else if (attr.value === null) {
+      parts.push(attrName)           // Boolean attribute
+    } else if (attr.dynamic) {
+      parts.push(`${attrName}={${attr.value}}`)
+    } else {
+      parts.push(`${attrName}="${attr.value}"`)
+    }
+  }
+
+  // Event handlers — render as no-op stubs for SSR
+  for (const event of element.events) {
+    const handlerName = `on${event.name.charAt(0).toUpperCase()}${event.name.slice(1)}`
+    parts.push(`${handlerName}={() => {}}`)
+  }
+
+  return parts.length > 0 ? ' ' + parts.join(' ') : ''
+}
+```
+
+The TestAdapter renders event handlers as no-op stubs for JSX. Non-JSX adapters omit them — handlers exist only in client JS.
+
+
+## Step 4: Implement Expression Rendering
+
+Reactive expressions with a `slotId` get a hydration marker for client JS updates:
+
+```typescript
+renderExpression(expr: IRExpression): string {
+  if (expr.expr === 'null' || expr.expr === 'undefined') {
+    return 'null'
+  }
+  if (expr.reactive && expr.slotId) {
+    return `<span bf="${expr.slotId}">{${expr.expr}}</span>`
+  }
+  return `{${expr.expr}}`
+}
+```
+
+Non-JSX adapters convert expressions to the target language (e.g., `count()` → `{{.Count}}`).
+
+
+## Step 5: Implement Conditional Rendering
+
+Ternaries pass through in JSX adapters:
+
+```typescript
+renderConditional(cond: IRConditional): string {
+  const whenTrue = this.renderNode(cond.whenTrue)
+  const whenFalse = this.renderNode(cond.whenFalse)
+
+  return `{${cond.condition} ? ${whenTrue} : ${whenFalse || 'null'}}`
+}
+```
+
+**Input (JSX):**
+```tsx
+{isActive ? <span>Active</span> : <span>Inactive</span>}
+```
+
+**Output (TestAdapter):**
+```tsx
+{isActive ? <span>Active</span> : <span>Inactive</span>}
+```
+
+Non-JSX adapters translate to the target conditional syntax (e.g., `{{if .IsActive}}...{{else}}...{{end}}`).
+
+
+## Step 6: Implement Loop Rendering
+
+`.map()` calls stay as JSX:
+
+```typescript
+renderLoop(loop: IRLoop): string {
+  const indexParam = loop.index ? `, ${loop.index}` : ''
+  const children = this.renderChildren(loop.children)
+
+  return `{${loop.array}.map((${loop.param}${indexParam}) => ${children})}`
+}
+```
+
+**Input (JSX):**
+```tsx
+{items.map(item => <li key={item.id}>{item.name}</li>)}
+```
+
+**Output (TestAdapter):**
+```tsx
+{items.map((item) => <li key={item.id}>{item.name}</li>)}
+```
+
+Non-JSX adapters translate to the target iteration syntax (e.g., `{{range .Items}}...{{end}}`).
+
+
+## Step 7: Implement Component Rendering
+
+Pass the parent's scope ID to nested components:
+
+```typescript
+renderComponent(comp: IRComponent): string {
+  const props = this.renderComponentProps(comp)
+  const children = this.renderChildren(comp.children)
+
+  const scopeAttr = ' __bfScope={__scopeId}'
+
+  if (children) {
+    return `<${comp.name}${props}${scopeAttr}>${children}</${comp.name}>`
+  } else {
+    return `<${comp.name}${props}${scopeAttr} />`
+  }
+}
+```
+
+## Step 8: Implement Hydration Markers
+
+```typescript
+renderScopeMarker(instanceIdExpr: string): string {
+  return `bf-s={${instanceIdExpr}}`
+}
+
+renderSlotMarker(slotId: string): string {
+  return `bf="${slotId}"`
+}
+
+renderCondMarker(condId: string): string {
+  return `bf-c="${condId}"`
+}
+```
+
+## Step 9: Generate Signal Initializers
+
+Signal getters return initial values during SSR via stub functions:
+
+```typescript
+private generateSignalInitializers(ir: ComponentIR): string {
+  const lines: string[] = []
+
+  for (const signal of ir.metadata.signals) {
+    lines.push(`  const ${signal.getter} = () => ${signal.initialValue}`)
+    lines.push(`  const ${signal.setter} = () => {}`)
+  }
+
+  for (const memo of ir.metadata.memos) {
+    lines.push(`  const ${memo.name} = ${memo.computation}`)
+  }
+
+  return lines.join('\n')
+}
+```
+
+`const [count, setCount] = createSignal(initial)` becomes:
+```typescript
+const count = () => initial   // getter returns initial value
+const setCount = () => {}     // setter is a no-op on the server
+```
+
+## Optional: Type Generation
+
+For typed backends, implement `generateTypes()`:
+
+```typescript
+generateTypes(ir: ComponentIR): string | null {
+  const lines: string[] = []
+
+  const propsTypeName = ir.metadata.propsType?.raw
+  if (propsTypeName) {
+    lines.push(`type ${this.componentName}PropsWithHydration = ${propsTypeName} & {`)
+    lines.push('  __instanceId?: string')
+    lines.push('  __bfScope?: string')
+    lines.push('}')
+  }
+
+  return lines.length > 0 ? lines.join('\n') : null
+}
+```
+
+For dynamically-typed backends, return `null`.
+
+
+## Testing
+
+```typescript
+import { compileJsxToIR } from '@barefootjs/jsx'
+import { TestAdapter } from './test-adapter'
+
+const source = `
+"use client"
+import { createSignal } from '@barefootjs/client'
+
+export function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = createSignal(initial)
+  return (
+    <div>
+      <p>{count()}</p>
+      <button onClick={() => setCount(n => n + 1)}>+1</button>
+    </div>
+  )
+}
+`
+
+const ir = compileJsxToIR(source)
+const adapter = new TestAdapter()
+const output = adapter.generate(ir)
+
+console.log(output.template)
+// export function Counter({ __instanceId, ... }) {
+//   const __scopeId = ...
+//   const count = () => 0
+//
+//   return (
+//     <div bf-s={__scopeId}>
+//       <span bf="s1">Count: {bfText("s0")}{count()}{bfTextEnd()}</span>
+//       <button bf="s2" onClick={() => {}}>+1</button>
+//     </div>
+//   )
+// }
+```
+
+
+## Checklist
+
+Ensure you handle:
+
+- [ ] All IR node types (`element`, `text`, `expression`, `conditional`, `loop`, `component`, `fragment`, `slot`)
+- [ ] Hydration markers (`bf-s`, `bf`, `bf-c`) on interactive elements
+- [ ] Static vs. dynamic attributes
+- [ ] Boolean HTML attributes (`disabled`, `checked`, etc.)
+- [ ] Spread attributes (`{...props}`)
+- [ ] Signal getter stubs for server-side initial values
+- [ ] Nested component scope passing
+- [ ] Props serialization (`bf-p` attribute) for client hydration
+- [ ] Script registration for client JS loading
+- [ ] `/* @client */` directive (skip client-only expressions server-side)
+
+Production adapters also handle:
+
+- [ ] Void HTML elements (`<input>`, `<br>`, etc.) — no closing tag
+- [ ] Expression translation to the target template language
+- [ ] Type generation for typed backend languages
+- [ ] `if-statement` and `provider` IR node types
+
+### Reference Implementations
+
+- **TestAdapter** (`packages/jsx/src/adapters/test-adapter.ts`) — Minimal working adapter used throughout this guide
+- **HonoAdapter** (`packages/adapter-hono/src/adapter/hono-adapter.ts`) — Production JSX-to-JSX adapter with script collection via Hono's request context
+- **GoTemplateAdapter** (`packages/adapter-go-template/src/adapter/go-template-adapter.ts`) — Production adapter with expression translation, type generation, and array method mapping

package/dist/docs/core/adapters/go-template-adapter.md

@@ -0,0 +1,269 @@
+---
+title: Go Template Adapter
+description: Generate Go html/template files and type definitions from the compiler's IR.
+---
+
+# Go Template Adapter
+
+Generates Go `html/template` files (`.tmpl`) and type definitions (`_types.go`) from the compiler's IR.
+
+```
+npm install @barefootjs/go-template
+```
+
+
+## Basic Usage
+
+```typescript
+import { compile } from '@barefootjs/jsx'
+import { GoTemplateAdapter } from '@barefootjs/go-template'
+
+const adapter = new GoTemplateAdapter()
+const result = compile(source, { adapter })
+
+// result.template  → .tmpl file content
+// result.types     → _types.go file content
+// result.clientJs  → .client.js file content
+```
+
+
+## Options
+
+```typescript
+const adapter = new GoTemplateAdapter({
+  packageName: 'views',
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `packageName` | `string` | `'components'` | Go package name for generated type files |
+
+
+## Output Format
+
+### Server Component
+
+**Source:**
+
+```tsx
+export function Greeting(props: { name: string }) {
+  return <p>Hello, {props.name}!</p>
+}
+```
+
+**Output (.tmpl):**
+
+```go-template
+{{define "Greeting"}}
+<p bf-s="{{bfScopeAttr .}}" {{bfPropsAttr .}} bf="s1">
+  Hello, {{bfTextStart "s0"}}{{.Name}}{{bfTextEnd}}!
+</p>
+{{end}}
+```
+
+- `bfScopeAttr` — generates the `bf-s` scope ID
+- `bfPropsAttr` — serializes props for client hydration
+- `bfTextStart` / `bfTextEnd` — text node markers (rendered as `<!--bf:s0-->...<!--/-->`)
+
+### Client Component
+
+**Source:**
+
+```tsx
+"use client"
+import { createSignal } from '@barefootjs/client'
+
+export function Counter(props: { initial?: number }) {
+  const [count, setCount] = createSignal(props.initial ?? 0)
+
+  return (
+    <div>
+      <span>Count: {count()}</span>
+      <button onClick={() => setCount(n => n + 1)}>+1</button>
+    </div>
+  )
+}
+```
+
+**Output (.tmpl):**
+
+```go-template
+{{define "Counter"}}
+{{if .Scripts}}{{.Scripts.Register "/static/client/barefoot.js"}}{{.Scripts.Register "/static/client/Counter.client.js"}}{{end}}
+<div bf-s="{{bfScopeAttr .}}" {{bfPropsAttr .}}>
+  <span bf="s1">Count: {{bfTextStart "s0"}}{{.Count}}{{bfTextEnd}}</span>
+  <button bf="s2">+1</button>
+</div>
+{{end}}
+```
+
+
+## Expression Translation
+
+### Property Access
+
+```
+props.name       →  .Name
+props.user.email →  .User.Email
+```
+
+Field names are automatically capitalized to follow Go conventions.
+
+### Comparisons
+
+| JavaScript | Go Template |
+|-----------|-------------|
+| `a === b` | `eq .A .B` |
+| `a !== b` | `ne .A .B` |
+| `a > b` | `gt .A .B` |
+| `a < b` | `lt .A .B` |
+| `a >= b` | `ge .A .B` |
+| `a <= b` | `le .A .B` |
+
+### Arithmetic
+
+| JavaScript | Go Template |
+|-----------|-------------|
+| `a + b` | `bf_add .A .B` |
+| `a - b` | `bf_sub .A .B` |
+| `a * b` | `bf_mul .A .B` |
+| `a / b` | `bf_div .A .B` |
+
+### Logical Operators
+
+| JavaScript | Go Template |
+|-----------|-------------|
+| `a && b` | `and .A .B` |
+| `a \|\| b` | `or .A .B` |
+| `!a` | `not .A` |
+
+
+## Array Methods
+
+### `.map()`
+
+```tsx
+{items().map(item => <li key={item}>{item}</li>)}
+```
+
+```go-template
+{{range $_, $item := .Items}}
+<li>{{bfTextStart "s0"}}{{.Item}}{{bfTextEnd}}</li>
+{{end}}
+```
+
+### `.filter().map()`
+
+```tsx
+{items().filter(item => item.active).map(item => <li key={item.id}>{item.name}</li>)}
+```
+
+```go-template
+{{range $_, $item := .Items}}{{if .Active}}
+<li>{{bfTextStart "s0"}}{{.Item.Name}}{{bfTextEnd}}</li>
+{{end}}{{end}}
+```
+
+For complex filter predicates, the adapter generates template block functions.
+
+### `.sort().map()` / `.toSorted().map()`
+
+```tsx
+{items.toSorted((a, b) => a.priority - b.priority).map(t => <li key={t.id}>{t.name}</li>)}
+```
+
+```go-template
+{{range bf_sort .Items "Priority" "asc"}}
+<li>{{bfTextStart "s0"}}{{.Name}}{{bfTextEnd}}</li>
+{{end}}
+```
+
+### Other Array Methods
+
+| JavaScript | Go Template |
+|-----------|-------------|
+| `arr.find(fn)` | `bf_find` |
+| `arr.findIndex(fn)` | `bf_find_index` |
+| `arr.every(fn)` | `bf_every` |
+| `arr.some(fn)` | `bf_some` |
+| `arr.length` | `len .Arr` |
+
+
+## Type Generation
+
+For each component, the adapter generates:
+
+1. **Input struct** — external API
+2. **Props struct** — internal representation (includes hydration fields)
+3. **Constructor** — `New{Component}Props()` with defaults
+
+### Type Mapping
+
+| TypeScript | Go |
+|-----------|-----|
+| `string` | `string` |
+| `number` | `int` (or `float64` for decimals) |
+| `boolean` | `bool` |
+| `T[]` | `[]T` |
+| `T \| undefined` | Pointer type `*T` or zero value |
+| Object type | Named struct |
+
+### Nested Components
+
+```tsx
+export function TodoList({ items }: { items: TodoItem[] }) {
+  return (
+    <ul>
+      {items.map(item => <TodoItem key={item.id} {...item} />)}
+    </ul>
+  )
+}
+```
+
+## Conditional Rendering
+
+Ternaries become `{{if}}...{{else}}...{{end}}`:
+
+**Source:**
+
+```tsx
+{loggedIn() ? <span>Welcome back!</span> : <span>Please log in</span>}
+```
+
+**Output:**
+
+```go-template
+{{if .LoggedIn}}<span bf-c="s0">Welcome back!</span>{{else}}<span bf-c="s0">Please log in</span>{{end}}
+```
+
+Element branches use `bf-c` for conditional markers. Text-only ternaries use `bfComment` markers instead.
+
+
+## Script Registration
+
+Client components register their scripts via the `.Scripts` interface:
+
+```go-template
+{{if .Scripts}}{{.Scripts.Register "/static/client/barefoot.js"}}{{.Scripts.Register "/static/client/Counter.client.js"}}{{end}}
+```
+
+The `ScriptCollector` tracks needed scripts and renders `<script>` tags at page end. Each script loads at most once.
+
+
+## Go Helper Functions
+
+These helper functions must be in the Go template `FuncMap`:
+
+| Function | Purpose |
+|----------|---------|
+| `bf_add`, `bf_sub`, `bf_mul`, `bf_div` | Arithmetic operations |
+| `bf_neg` | Unary negation |
+| `bf_filter` | Filter a slice by field/value |
+| `bf_sort` | Sort a slice by field/direction |
+| `bf_find`, `bf_find_index` | Find element/index in a slice |
+| `bf_every`, `bf_some` | Test if all/any elements match |
+| `bf_json` | JSON-encode a value for props serialization |
+| `bf_concat` | String concatenation |
+
+Provided by the BarefootJS Go runtime package.