@barefootjs/cli 0.31.4 → 0.31.6

package/dist/docs/core/advanced/error-codes.md

@@ -24,6 +24,8 @@ error[BF001]: 'use client' directive required for components with createSignal
 
 ## Directive Errors (BF001–BF003)
 
+<a id="bf001"></a>
+
 ### BF001 — Missing `"use client"` Directive
 
 **Trigger:** Reactive APIs used without `"use client"`.
@@ -46,6 +48,8 @@ import { createSignal } from '@barefootjs/client'
 export function Counter() { ... }
 ```
 
+<a id="bf003"></a>
+
 ### BF003 — Client Component Importing Server Component
 
 **Trigger:** Client component imports from a file without `"use client"`.
@@ -56,6 +60,8 @@ export function Counter() { ... }
 
 ## Signal Errors (BF011)
 
+<a id="bf011"></a>
+
 ### BF011 — Module-Level Reactive Declaration
 
 **Trigger:** A `createSignal` or `createMemo` call at module scope without a leading `/* @client */` directive.
@@ -100,6 +106,8 @@ export function Counter() {
 
 ## JSX Errors (BF021–BF023)
 
+<a id="bf021"></a>
+
 ### BF021 — Unsupported JSX Pattern
 
 **Trigger:** Array method chain before `.map()` cannot compile to SSR template.
@@ -201,6 +209,8 @@ that a component-body local (`const iso = createdAt.toISOString()`) is NOT a
 workaround: it lowers to a template variable whose value the template
 backend cannot compute, and dies at render time the same way.
 
+<a id="bf023"></a>
+
 ### BF023 — Missing Key in List
 
 **Trigger:** `.map()` loop without `key` prop.
@@ -219,8 +229,56 @@ backend cannot compute, and dies at render time the same way.
 
 ---
 
+## Template Adapter Errors (BF101)
+
+<a id="bf101"></a>
+
+### BF101 — No Template-Language Lowering
+
+**Trigger:** An expression that a JS-runtime adapter (Hono, CSR) executes verbatim has no lowering on a non-JS template adapter (Go, Mojo, Xslate, Twig, ERB, Blade, Jinja, MiniJinja). Two shapes are permanent known limitations rather than subset widenings:
+
+**A nested `.some()` / `.find()` inside a filter predicate** ([#2320](https://github.com/piconic-ai/barefootjs/issues/2320)) — `find`-family methods return an element, not a boolean, so degrading them to their receiver would silently change predicate semantics:
+
+```tsx
+// ❌ BF101 on Go/Mojo/Xslate/Twig/ERB/Blade/Jinja/MiniJinja
+{items().filter(t => picked().some(p => p.id === t.id)).map(t => <li key={t.id}>{t.name}</li>)}
+```
+
+**A `.map()` loop array bound to a component-scope `const` with a computed initializer** ([#2321](https://github.com/piconic-ai/barefootjs/issues/2321)) — no template adapter binds an arbitrary computed local, only a prop/param it passes straight through:
+
+```tsx
+// ❌ BF101 on Go/Mojo/Xslate/Twig/ERB/Blade/Jinja/MiniJinja
+function ReactionBar(props: { reactions: Record<string, string[]> }) {
+  const entries = Object.entries(props.reactions).filter(([, users]) => users.length > 0)
+  return <div>{entries.map(([emoji, users]) => <span key={emoji}>{emoji}</span>)}</div>
+}
+```
+
+**Escapes** — each verified by a conformance twin that compiles clean on the refusing adapter, listed best-SSR-first:
+
+- **Pass the computed result as a prop** (`prop-precompute`) — available for the loop-source shape, wherever the array is already computable server-side. **Full server render**: the rendered result is present in the server HTML.
+- **`/* @client */`** (`client-directive`) — available for both shapes, and compiles clean on every adapter. **Client-render**: the region is *empty in server HTML until hydration*. That trade is the cost of the escape, not a bug — the twin fixtures pin the empty region in their own committed `expectedHtml`.
+
+```tsx
+// ✅ Best for the loop-source shape: pass the computed array as a prop
+function ReactionBar({ entries }: { entries: [string, string[]][] }) {
+  return <div>{entries.map(([emoji, users]) => <span key={emoji}>{emoji}</span>)}</div>
+}
+
+// ✅ Either shape: defer to the client
+{/* @client */ items().filter(t => picked().some(p => p.id === t.id)).map(t => (
+  <li key={t.id}>{t.name}</li>
+))}
+```
+
+See [JSX Compatibility](../rendering/jsx-compatibility.md) for the full worked examples.
+
+---
+
 ## Component Errors (BF043–BF044)
 
+<a id="bf043"></a>
+
 ### BF043 — Props Destructuring (Warning)
 
 **Trigger:** Props destructured in function parameter.
@@ -257,6 +315,8 @@ function Child({ initialCount }: Props) {
 }
 ```
 
+<a id="bf044"></a>
+
 ### BF044 — Signal/Memo Getter Not Called
 
 **Trigger:** Signal/memo getter passed without calling it.
@@ -273,6 +333,8 @@ function Child({ initialCount }: Props) {
 <Child count={count()} />
 ```
 
+<a id="bf054"></a>
+
 ### BF054 — Built-in `<Async>` / `<Region>` Used Without Import
 
 **Trigger:** A bare `<Async>` or `<Region>` tag is used without importing it

package/dist/docs/core/rendering/jsx-compatibility.md

@@ -125,6 +125,7 @@ Some JavaScript expressions cannot be translated into marked template syntax. Wh
 | JSX-returning `.flatMap()` with a statement body (early `return`, `const` before the projection) | works (runs as JS) | **BF021** |
 | Nested `.filter()` / `.map()` in a filter predicate (`x => x.tags.filter(...).length > 0`) | works | works |
 | Nested `.some()` / `.find()` / `.reduce()` in a filter predicate | works | **BF101** |
+| `.map()` loop array bound to a component-scope `const` with a computed initializer (e.g. `Object.entries(props.x).filter(...)`) | works | **BF101** |
 | Sort comparator that's a multi-statement block body or `localeCompare(b, locale, opts)` | works (runs as JS) | **BF021** |
 | Sort comparator that's a function reference to an imported/prop identifier, or an alias chain (`const c2 = c1`) | works (runs as JS) | **BF021** |
 | `typeof` in a filter predicate | works (runs as JS) | **BF021** |
@@ -182,6 +183,39 @@ A nested `.some()` / `.find()` / `.reduce()` still has no faithful Go/Mojo lower
 {items().filter(x => x.done)}
 ```
 
+**Computed loop array (`const` with a runtime initializer):**
+
+A `.map()` loop whose array is a bare identifier works when that identifier is a prop or a signal read, but not when it's a component-scope `const` computed from one at render time (`Object.entries(...)`, `.filter(...)`, …) — no template adapter has a binding for an arbitrary computed local, only for a prop/param it can pass straight through:
+
+```tsx
+// ❌ BF101 on Go/Mojo/Xslate/Twig/ERB/Blade/Jinja/MiniJinja; works on Hono
+type Props = { reactions: Record<string, string[]> }
+function ReactionBar(props: Props) {
+  const entries = Object.entries(props.reactions).filter(([, users]) => users.length > 0)
+  return <div>{entries.map(([emoji, users]) => (
+    <span key={emoji}>{emoji}: {String(users.length)}</span>
+  ))}</div>
+}
+
+// ✅ Best: precompute the array in the parent/route handler and pass it as a prop
+type Entry = [string, string[]]
+function ReactionBarByProp({ entries }: { entries: Entry[] }) {
+  return <div>{entries.map(([emoji, users]) => (
+    <span key={emoji}>{emoji}: {String(users.length)}</span>
+  ))}</div>
+}
+
+// ✅ Or defer to the client with /* @client */
+function ReactionBarClientOnly(props: Props) {
+  const entries = Object.entries(props.reactions).filter(([, users]) => users.length > 0)
+  return <div>{/* @client */ entries.map(([emoji, users]) => (
+    <span key={emoji}>{emoji}: {String(users.length)}</span>
+  ))}</div>
+}
+```
+
+The prop-passing form is the better fix — it keeps full SSR output, since the template adapters bind a plain prop array directly. `/* @client */` compiles clean too, but renders **nothing** for that region at SSR — no content until hydration/mount runs the loop client-side.
+
 ### Sort comparators that error on Go / Mojo
 
 **Unsupported sort comparators** (imperative block bodies, unresolved function references) — a JS-runtime adapter (Hono, CSR) runs any of these verbatim; only non-JS template backends refuse them: