@barefootjs/cli 0.1.0

package/dist/docs/core/components/context-api.md

@@ -0,0 +1,236 @@
+---
+title: Context API
+description: Share state with deeply nested children without prop drilling using createContext and useContext.
+---
+
+# Context API
+
+Context shares state with deeply nested children without prop drilling. It is the foundation of compound components (Dialog, Accordion, Tabs).
+
+```tsx
+"use client"
+import { createContext, useContext } from '@barefootjs/client'
+```
+
+
+## `createContext`
+
+Creates a new context with an optional default value.
+
+```tsx
+const MyContext = createContext<T>(defaultValue?: T)
+```
+
+**Type:**
+
+```tsx
+type Context<T> = {
+  readonly id: symbol
+  readonly defaultValue: T | undefined
+  readonly Provider: (props: { value: T; children?: unknown }) => unknown
+}
+```
+
+
+## `Context.Provider`
+
+Provides a value to all descendants. Components inside the provider tree read it with `useContext`.
+
+```tsx
+<MyContext.Provider value={someValue}>
+  {props.children}
+</MyContext.Provider>
+```
+
+The compiler transforms this into a `provideContext()` call. The value is set synchronously before children initialize.
+
+
+## `useContext`
+
+Reads the current value from a context.
+
+```tsx
+const value = useContext(MyContext)
+```
+
+**Behavior:**
+
+- If a `Provider` ancestor exists, returns the provided value
+- If no `Provider` exists and a default value was passed to `createContext`, returns the default
+- Otherwise returns `undefined` — guard with optional chaining (`store?.value`)
+
+
+## Basic Example
+
+```tsx
+"use client"
+import { createContext, useContext } from '@barefootjs/client'
+
+// 1. Create the context
+const ThemeContext = createContext<'light' | 'dark'>('light')
+
+// 2. Provider component
+export function ThemeProvider(props: { theme: 'light' | 'dark'; children?: Child }) {
+  return (
+    <ThemeContext.Provider value={props.theme}>
+      {props.children}
+    </ThemeContext.Provider>
+  )
+}
+
+// 3. Consumer component
+export function ThemedButton(props: { children?: Child }) {
+  const handleMount = (el: HTMLButtonElement) => {
+    const theme = useContext(ThemeContext)
+    el.className = theme === 'dark' ? 'btn-dark' : 'btn-light'
+  }
+
+  return <button ref={handleMount}>{props.children}</button>
+}
+```
+
+```tsx
+// Usage
+<ThemeProvider theme="dark">
+  <ThemedButton>Click me</ThemedButton>  {/* Gets dark styling */}
+</ThemeProvider>
+```
+
+
+## Compound Components
+
+A group of related components sharing internal state. The root provides state; sub-components consume it.
+
+### Example: Accordion
+
+```tsx
+"use client"
+import { createSignal, createContext, useContext, createEffect } from '@barefootjs/client'
+
+// Context type
+interface AccordionContextValue {
+  activeItem: () => string | null
+  toggle: (id: string) => void
+}
+
+// Create context
+const AccordionContext = createContext<AccordionContextValue>()
+
+// Root component — provides state
+function Accordion(props: { children?: Child }) {
+  const [activeItem, setActiveItem] = createSignal<string | null>(null)
+
+  const toggle = (id: string) => {
+    setActiveItem(prev => prev === id ? null : id)
+  }
+
+  return (
+    <AccordionContext.Provider value={{ activeItem, toggle }}>
+      <div data-slot="accordion">{props.children}</div>
+    </AccordionContext.Provider>
+  )
+}
+
+// Trigger — toggles the active item
+function AccordionTrigger(props: { itemId: string; children?: Child }) {
+  const handleMount = (el: HTMLButtonElement) => {
+    const ctx = useContext(AccordionContext)
+
+    el.addEventListener('click', () => {
+      ctx.toggle(props.itemId)
+    })
+
+    createEffect(() => {
+      const isOpen = ctx.activeItem() === props.itemId
+      el.setAttribute('aria-expanded', String(isOpen))
+    })
+  }
+
+  return <button ref={handleMount}>{props.children}</button>
+}
+
+// Content — shows/hides based on active item
+function AccordionContent(props: { itemId: string; children?: Child }) {
+  const handleMount = (el: HTMLElement) => {
+    const ctx = useContext(AccordionContext)
+
+    createEffect(() => {
+      const isOpen = ctx.activeItem() === props.itemId
+      el.hidden = !isOpen
+    })
+  }
+
+  return <div ref={handleMount}>{props.children}</div>
+}
+```
+
+**Usage:**
+
+```tsx
+<Accordion>
+  <AccordionTrigger itemId="faq-1">What is BarefootJS?</AccordionTrigger>
+  <AccordionContent itemId="faq-1">
+    <p>A JSX-to-template compiler with signal-based reactivity.</p>
+  </AccordionContent>
+
+  <AccordionTrigger itemId="faq-2">How does hydration work?</AccordionTrigger>
+  <AccordionContent itemId="faq-2">
+    <p>Marker-driven: bf-* attributes tell the client JS where to attach.</p>
+  </AccordionContent>
+</Accordion>
+```
+
+
+## Reactive Context Values
+
+Context values can contain signal getters. Effects that read them re-run when the signal changes:
+
+```tsx
+// Provider passes signal getter
+<AccordionContext.Provider value={{ activeItem, toggle }}>
+```
+
+```tsx
+// Consumer reads inside createEffect — reactive
+const ctx = useContext(AccordionContext)
+createEffect(() => {
+  const isOpen = ctx.activeItem() === props.itemId  // Tracks activeItem signal
+  el.hidden = !isOpen
+})
+```
+
+`ctx.activeItem()` inside the effect subscribes to `activeItem`. When it changes, only affected effects re-run.
+
+
+## Context Without a Default
+
+Without a default value, `useContext` throws if no `Provider` ancestor exists. Recommended for compound components:
+
+```tsx
+const DialogContext = createContext<DialogContextValue>()
+
+// If DialogTrigger is used outside a Dialog, useContext throws
+function DialogTrigger(props: { children?: Child }) {
+  const handleMount = (el: HTMLElement) => {
+    const ctx = useContext(DialogContext) // Throws if no Dialog ancestor
+    // ...
+  }
+  return <button ref={handleMount}>{props.children}</button>
+}
+```
+
+This catches composition errors early — the error identifies the missing provider.
+
+
+## Context With a Default
+
+With a default, `useContext` always succeeds:
+
+```tsx
+const ThemeContext = createContext<'light' | 'dark'>('light')
+
+// Works even without a ThemeProvider ancestor — returns 'light'
+const theme = useContext(ThemeContext)
+```
+
+Use for optional contexts with a sensible fallback.

package/dist/docs/core/components/portals.md

@@ -0,0 +1,192 @@
+---
+title: Portals
+description: Render elements outside their parent DOM hierarchy for overlays, modals, and tooltips.
+---
+
+# Portals
+
+Portals render elements outside their parent DOM hierarchy — useful for overlays, modals, and tooltips that need to escape `overflow: hidden` or `z-index` stacking contexts.
+
+```tsx
+"use client"
+import { createPortal } from '@barefootjs/client'
+```
+
+
+## `createPortal`
+
+Moves an element to a different DOM container.
+
+```tsx
+createPortal(children, container?, options?)
+```
+
+**Type:**
+
+```tsx
+type Portal = {
+  element: HTMLElement
+  unmount: () => void
+}
+
+interface PortalOptions {
+  ownerScope?: Element  // Component scope for scoped queries
+}
+
+function createPortal(
+  children: HTMLElement | string,
+  container?: HTMLElement,           // Default: document.body
+  options?: PortalOptions
+): Portal
+```
+
+**Returns** a `Portal` object with:
+- `element` — the mounted DOM element
+- `unmount()` — removes the element from the container
+
+
+## Basic Usage
+
+Create portals inside `ref` callbacks:
+
+```tsx
+"use client"
+import { createSignal, createEffect, createPortal, isSSRPortal } from '@barefootjs/client'
+
+export function Tooltip(props: { text: string; children?: Child }) {
+  const [visible, setVisible] = createSignal(false)
+
+  const handleMount = (el: HTMLElement) => {
+    // Move to document.body to avoid overflow/z-index issues
+    if (el.parentNode !== document.body && !isSSRPortal(el)) {
+      const ownerScope = el.closest('[bf-s]') ?? undefined
+      createPortal(el, document.body, { ownerScope })
+    }
+
+    createEffect(() => {
+      el.hidden = !visible()
+    })
+  }
+
+  return (
+    <div>
+      <span
+        onMouseEnter={() => setVisible(true)}
+        onMouseLeave={() => setVisible(false)}
+      >
+        {props.children}
+      </span>
+      <div className="tooltip" ref={handleMount}>
+        {props.text}
+      </div>
+    </div>
+  )
+}
+```
+
+
+## SSR Portal Detection
+
+`isSSRPortal` checks whether an element was already portaled during SSR to prevent double-portaling:
+
+```tsx
+"use client"
+import { isSSRPortal, createPortal } from '@barefootjs/client'
+
+const handleMount = (el: HTMLElement) => {
+  // Skip if already portaled during SSR
+  if (el.parentNode !== document.body && !isSSRPortal(el)) {
+    createPortal(el, document.body)
+  }
+}
+```
+
+After hydration, remove SSR placeholders:
+
+```tsx
+"use client"
+import { cleanupPortalPlaceholder } from '@barefootjs/client'
+
+declare const portalId: string
+cleanupPortalPlaceholder(portalId)
+```
+
+
+## Owner Scope
+
+A portaled element is outside its original component's scope, so `find()` cannot locate it. The `ownerScope` option links it back:
+
+```tsx
+const handleMount = (el: HTMLElement) => {
+  const ownerScope = el.closest('[bf-s]') ?? undefined
+  createPortal(el, document.body, { ownerScope })
+}
+```
+
+`bf-po` on the moved element lets scoped queries from the owner still find it.
+
+
+## Dialog Example
+
+Dialog overlays are a common portal use case:
+
+```tsx
+"use client"
+import { createPortal, isSSRPortal, useContext, createEffect } from '@barefootjs/client'
+
+function DialogOverlay() {
+  const handleMount = (el: HTMLElement) => {
+    // Portal to body
+    if (el.parentNode !== document.body && !isSSRPortal(el)) {
+      const ownerScope = el.closest('[bf-s]') ?? undefined
+      createPortal(el, document.body, { ownerScope })
+    }
+
+    const ctx = useContext(DialogContext)
+
+    // Reactive visibility
+    createEffect(() => {
+      const isOpen = ctx.open()
+      el.dataset.state = isOpen ? 'open' : 'closed'
+      el.className = isOpen ? 'overlay overlay-visible' : 'overlay overlay-hidden'
+    })
+
+    // Click overlay to close
+    el.addEventListener('click', () => {
+      ctx.onOpenChange(false)
+    })
+  }
+
+  return <div data-slot="dialog-overlay" ref={handleMount} />
+}
+```
+
+The overlay accesses `DialogContext` from the component tree but is moved to `document.body` to escape CSS containment.
+
+
+## Cleanup
+
+Combine `portal.unmount()` with `onCleanup`:
+
+```tsx
+"use client"
+import { createPortal, onCleanup } from '@barefootjs/client'
+
+const handleMount = (el: HTMLElement) => {
+  const portal = createPortal(el, document.body)
+
+  onCleanup(() => {
+    portal.unmount()
+  })
+}
+```
+
+
+## Custom Container
+
+Specify a different container instead of the default `document.body`:
+
+```tsx
+const container = document.getElementById('modal-root')!
+createPortal(el, container)
+```

package/dist/docs/core/components/props-type-safety.md

@@ -0,0 +1,97 @@
+---
+title: Props & Type Safety
+description: Type component props with TypeScript interfaces and preserve type information through compilation.
+---
+
+# Props & Type Safety
+
+The compiler preserves TypeScript type information through compilation. Adapters use it to generate type-safe templates.
+
+Props in client components are reactive — see [Props Reactivity](../reactivity/props-reactivity.md). This page covers typing patterns.
+
+
+## Defining Props
+
+```tsx
+interface GreetingProps {
+  name: string
+  greeting?: string
+}
+
+export function Greeting(props: GreetingProps) {
+  return <h1>{props.greeting ?? 'Hello'}, {props.name}</h1>
+}
+```
+
+
+## Default Values
+
+Use nullish coalescing (`??`) on the props object:
+
+```tsx
+function Button(props: { variant?: 'default' | 'primary'; children?: Child }) {
+  const variant = props.variant ?? 'default'
+  return <button className={variant}>{props.children}</button>
+}
+```
+
+For initial-value-only props, default parameter syntax works. Add `@bf-ignore` to suppress the `BF043` destructuring warning:
+
+```tsx
+// @bf-ignore props-destructuring
+function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = createSignal(initial)
+  return <button onClick={() => setCount(n => n + 1)}>{count()}</button>
+}
+```
+
+
+## Extending HTML Attributes
+
+Extend HTML attribute types for components wrapping native elements:
+
+```tsx
+import type { ButtonHTMLAttributes } from '@barefootjs/jsx'
+
+interface ButtonProps extends ButtonHTMLAttributes {
+  variant?: 'default' | 'primary' | 'destructive'
+  size?: 'sm' | 'md' | 'lg'
+}
+
+function Button(props: ButtonProps) {
+  const variant = props.variant ?? 'default'
+  const size = props.size ?? 'md'
+  const classes = `btn btn-${variant} btn-${size} ${props.className ?? ''}`
+
+  return <button className={classes} {...props}>{props.children}</button>
+}
+```
+
+Callers can pass standard button attributes (`type`, `disabled`, `aria-label`, etc.) alongside custom props.
+
+
+## Rest Spreading
+
+Rest spreading captures values once, so use it for server components or non-reactive attributes:
+
+```tsx
+function Card(props: { title: string; children?: Child } & HTMLAttributes) {
+  return (
+    <div className={props.className}>
+      <h2>{props.title}</h2>
+      {props.children}
+    </div>
+  )
+}
+```
+
+```tsx
+<Card title="Dashboard" className="shadow-lg" data-testid="dashboard-card">
+  <p>Content</p>
+</Card>
+```
+
+
+## Type Preservation
+
+The compiler carries TypeScript type information through the IR. Each adapter uses it for type-safe server output. See [Adapters](../adapters.md) for backend-specific type mapping.

package/dist/docs/core/components/styling.md

@@ -0,0 +1,37 @@
+---
+title: Style Overrides
+description: How user-supplied classes override component base classes via CSS Cascade Layers
+---
+
+# Style Overrides
+
+User-supplied classes always override component base classes — guaranteed by CSS Cascade Layers. No runtime JS, no merge functions, no class-order concerns.
+
+Styles in a named `@layer` lose to un-layered styles regardless of specificity. BarefootJS puts component base classes into `@layer components`:
+
+```css
+@layer preflights, base, shortcuts, components, default;
+```
+
+The compiler's `cssLayerPrefix` option prefixes base classes at compile time:
+
+```tsx
+// Source
+const baseClasses = 'inline-flex items-center bg-primary text-primary-foreground'
+
+// Compiled (cssLayerPrefix: 'components')
+const baseClasses = 'layer-components:inline-flex layer-components:items-center layer-components:bg-primary layer-components:text-primary-foreground'
+```
+
+User classes remain un-layered and always win:
+
+```
+<Button className="bg-red-500">
+
+  layer-components:bg-primary     → @layer components  (lower priority)
+  bg-red-500                      → un-layered          (higher priority)
+
+Result: bg-red-500 wins.
+```
+
+Zero runtime cost. Prefixing applies to the IR, so all adapters benefit.

package/dist/docs/core/components.md

@@ -0,0 +1,19 @@
+---
+title: Components
+description: How to author, compose, and type components in BarefootJS, including props, children, context, and portals.
+---
+
+# Components
+
+For the `"use client"` directive and the server/client boundary, see [Backend Freedom](./core-concepts/backend-freedom.md#the-use-client-directive).
+
+## Pages
+
+| Topic | Description |
+|-------|-------------|
+| [Component Authoring](./components/component-authoring.md) | Server components, client components, and the compilation model |
+| [Props & Type Safety](./components/props-type-safety.md) | Typing props, defaults, and rest spreading |
+| [Children & Slots](./components/children-slots.md) | Children prop, the `Slot` component, and the `asChild` pattern |
+| [Context API](./components/context-api.md) | Sharing state across compound components with `createContext` / `useContext` |
+| [Portals](./components/portals.md) | Rendering elements outside their parent DOM hierarchy |
+| [Style Overrides](./components/styling.md) | How user-supplied classes override component base classes via CSS Cascade Layers |

package/dist/docs/core/core-concepts/ai-native.md

@@ -0,0 +1,83 @@
+---
+title: AI-native Development
+description: Millisecond IR tests and the bf CLI for human + agent workflows
+---
+
+# AI-native Development
+
+BarefootJS is designed so both humans and AI agents can build components without reading source files. Two pillars carry that:
+
+1. **IR tests** verify component structure in milliseconds, no browser required.
+2. **The `bf` CLI** drives discovery, scaffolding, testing, and debugging — every command supports `--json` for machine consumption.
+
+## IR Tests
+
+`renderToTest()` verifies component structure, signals, events, and accessibility against the compiler's IR — in milliseconds, without a browser. Real interactions and visual behavior still need E2E tests, but structural issues are caught before you get there:
+
+> **Test runner**: the snippet below uses `bun:test`. `bf init` picks the runner that matches your package manager — bun users get `bun:test`, everyone else gets [Vitest](https://vitest.dev) (`from 'vitest'`). The surfaces are API-compatible, so swap the import line if you're following along under npm / pnpm / yarn. `bf gen test` and `bf gen component` emit the right line for you.
+
+```tsx
+import { describe, test, expect } from 'bun:test'
+import { readFileSync } from 'fs'
+import { resolve } from 'path'
+import { renderToTest } from '@barefootjs/test'
+
+const source = readFileSync(resolve(__dirname, 'Counter.tsx'), 'utf-8')
+
+describe('Counter', () => {
+  const ir = renderToTest(source, 'Counter.tsx')
+
+  test('compiles cleanly with a `count` signal', () => {
+    expect(ir.errors).toEqual([])
+    expect(ir.signals).toContain('count')
+  })
+
+  test('has a button wired to a click handler', () => {
+    const button = ir.find({ tag: 'button' })
+    expect(button).not.toBeNull()
+    expect(button!.events).toContain('click')
+  })
+})
+```
+
+`renderToTest(source, filePath)` takes the component source as a string and returns a queryable `TestResult` (`root`, `signals`, `memos`, `errors`, plus `find`/`findAll`/`findByText` for traversal). The same call shape is what `bf gen component` and `bf gen test` write — see the auto-generated `index.test.tsx` next to any component for a richer worked example.
+
+See [IR Schema Reference](../advanced/ir-schema.md) for the full specification.
+
+## CLI Workflow
+
+Install via `npm create barefootjs@latest`. Run `bf --help` for the full command surface — this section shows the daily loop, not the manual page.
+
+A typical component task is one straight line:
+
+```
+search → docs → add → <pm> test → debug
+```
+
+```bash
+bf search dialog          # find a component in the registry + docs
+bf docs dialog            # read its API (props, examples, a11y)
+bf add dialog             # copy it into your project
+<pm> test                 # verify the IR (bun test / npm test / pnpm test / yarn test)
+bf debug graph dialog     # inspect reactivity
+```
+
+When nothing in the registry fits, `bf gen component <name> <comps...>` scaffolds a new component composed from existing ones, with an IR test stub. When a signal doesn't update what you expect, `bf debug trace <comp> <signal>` walks the propagation path.
+
+**Visual preview**: hosted previews live at [ui.barefootjs.dev/components/&lt;name&gt;](https://ui.barefootjs.dev). Standalone `bf preview` for npm-installed projects is tracked in [#885](https://github.com/piconic-ai/barefootjs/issues/885).
+
+## Agent Loop
+
+The same workflow driven by an AI agent — say, "add a settings form":
+
+```bash
+bf search settings-form --json
+bf docs field --json
+bf docs switch --json
+bf gen component settings-form field switch label
+# edit components/ui/settings-form/index.tsx
+bun test components/ui/settings-form/index.test.tsx   # or `npm test -- <path>`, `pnpm test <path>`, etc.
+bf debug graph settings-form
+```
+
+No source files read — the CLI is the API.

package/dist/docs/core/core-concepts/backend-freedom.md

@@ -0,0 +1,31 @@
+---
+title: Backend Freedom
+description: How adapters let the same JSX run on any server — Hono, Go, and beyond
+---
+
+# Backend Freedom
+
+JSX gives you components with props, composition, and type checking. But server rendering with JSX usually means running Node.js on the server.
+
+BarefootJS compiles JSX at build time into your backend's native template format. Go renders `.tmpl` with `html/template`; Perl renders `.html.ep` with Mojolicious; Hono renders the generated `.tsx`. For non-Node backends, no Node.js runs at serving time. The compiler produces a backend-agnostic IR, then an adapter converts it:
+
+```
+JSX → IR (backend-agnostic) → Adapter → Template
+```
+
+| Language | Adapter | Notes |
+|----------|---------|-------|
+| TypeScript | [HonoAdapter](../adapters/hono-adapter.md) | Hono / JSX-based TS servers |
+| TypeScript | [TestAdapter](https://github.com/piconic-ai/barefootjs/tree/main/packages/test) | IR-based component testing |
+| Go | [GoTemplateAdapter](../adapters/go-template-adapter.md) | `html/template` |
+| Perl | [MojoliciousAdapter](https://github.com/piconic-ai/barefootjs/tree/main/packages/adapter-mojolicious) | Mojolicious EP templates |
+
+### Planned
+
+| Language | Adapter |
+|----------|---------|
+| Rust | (TBD) |
+| Python | Jinja2Adapter |
+| Ruby | ERBAdapter |
+
+The IR contract is stable. You can [write a custom adapter](../adapters/custom-adapter.md) for any backend.