npm - @barefootjs/hono - Versions diffs - 0.1.0 - Mend

@barefootjs/hono 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (81) hide show

package/dist/adapter/hono-adapter.d.ts +141 -0
package/dist/adapter/hono-adapter.d.ts.map +1 -0
package/dist/adapter/index.d.ts +6 -0
package/dist/adapter/index.d.ts.map +1 -0
package/dist/adapter/index.js +632 -0
package/dist/app.d.ts +131 -0
package/dist/app.d.ts.map +1 -0
package/dist/app.js +139 -0
package/dist/async.d.ts +15 -0
package/dist/async.d.ts.map +1 -0
package/dist/async.js +12 -0
package/dist/build.d.ts +65 -0
package/dist/build.d.ts.map +1 -0
package/dist/build.js +785 -0
package/dist/client-shim.d.ts +59 -0
package/dist/client-shim.d.ts.map +1 -0
package/dist/client-shim.js +90 -0
package/dist/dev-worker.d.ts +25 -0
package/dist/dev-worker.d.ts.map +1 -0
package/dist/dev-worker.js +65 -0
package/dist/dev.d.ts +36 -0
package/dist/dev.d.ts.map +1 -0
package/dist/dev.js +418 -0
package/dist/dialog-context.d.ts +13 -0
package/dist/dialog-context.d.ts.map +1 -0
package/dist/dialog-context.js +10 -0
package/dist/index.d.ts +13 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +632 -0
package/dist/jsx/jsx-dev-runtime/index.d.ts +9 -0
package/dist/jsx/jsx-dev-runtime/index.d.ts.map +1 -0
package/dist/jsx/jsx-dev-runtime/index.js +6 -0
package/dist/jsx/jsx-runtime/index.d.ts +32 -0
package/dist/jsx/jsx-runtime/index.d.ts.map +1 -0
package/dist/jsx/jsx-runtime/index.js +10 -0
package/dist/portal-ssr.d.ts +22 -0
package/dist/portal-ssr.d.ts.map +1 -0
package/dist/portal-ssr.js +73 -0
package/dist/portals.d.ts +26 -0
package/dist/portals.d.ts.map +1 -0
package/dist/portals.js +41 -0
package/dist/preload.d.ts +56 -0
package/dist/preload.d.ts.map +1 -0
package/dist/preload.js +51 -0
package/dist/scripts.d.ts +80 -0
package/dist/scripts.d.ts.map +1 -0
package/dist/scripts.js +198 -0
package/dist/test-render.d.ts +28 -0
package/dist/test-render.d.ts.map +1 -0
package/dist/utils.d.ts +16 -0
package/dist/utils.d.ts.map +1 -0
package/dist/utils.js +16 -0
package/package.json +116 -0
package/src/__tests__/async.test.tsx +106 -0
package/src/__tests__/bfscripts-entry-roots.test.tsx +135 -0
package/src/__tests__/build.test.ts +299 -0
package/src/__tests__/dev.test.tsx +123 -0
package/src/__tests__/hydration-props-type.test.ts +141 -0
package/src/__tests__/manifest-scripts.test.ts +87 -0
package/src/__tests__/scaffold.test.ts +209 -0
package/src/__tests__/ssr-context-bridge.test.ts +110 -0
package/src/__tests__/string-literal-css-var-prop.test.ts +84 -0
package/src/__tests__/stub-deps-scripts.test.ts +183 -0
package/src/adapter/hono-adapter.ts +1114 -0
package/src/adapter/index.ts +6 -0
package/src/app.ts +220 -0
package/src/async.tsx +55 -0
package/src/build.ts +230 -0
package/src/client-shim.ts +164 -0
package/src/dev-worker.ts +93 -0
package/src/dev.tsx +146 -0
package/src/dialog-context.tsx +44 -0
package/src/index.ts +26 -0
package/src/jsx/jsx-dev-runtime/index.ts +9 -0
package/src/jsx/jsx-runtime/index.ts +40 -0
package/src/portal-ssr.tsx +92 -0
package/src/portals.tsx +98 -0
package/src/preload.tsx +166 -0
package/src/scripts.tsx +220 -0
package/src/test-render.ts +143 -0
package/src/utils.ts +26 -0

package/src/preload.tsx ADDED Viewed

@@ -0,0 +1,166 @@
+// @jsxRuntime automatic
+// @jsxImportSource hono/jsx
+//
+// Pragmas as line-comments above the JSDoc; see scripts.tsx for the rationale.
+/**
+ * BfPreload Component
+ *
+ * Renders modulepreload link tags in the document head for faster module loading.
+ * Modulepreload hints tell the browser to fetch and parse JavaScript modules early,
+ * reducing the critical path latency.
+ *
+ * Usage:
+ * ```tsx
+ * import { BfPreload } from '@barefootjs/hono/preload'
+ * import manifest from './dist/components/manifest.json'
+ *
+ * <html>
+ *   <head>
+ *     <BfPreload />
+ *     {/* or with additional scripts *\/}
+ *     <BfPreload scripts={['/static/components/button.js']} />
+ *     {/* or with manifest-based dependency preloading *\/}
+ *     <BfPreload manifest={manifest} components={['Button', 'TodoApp']} />
+ *   </head>
+ *   <body>
+ *     {children}
+ *     <BfScripts />
+ *   </body>
+ * </html>
+ * ```
+ */
+import { Fragment } from 'hono/jsx'
+/**
+ * Manifest entry type for dependency tracking.
+ */
+export interface ManifestEntry {
+  markedTemplate: string
+  clientJs?: string
+  props?: Array<{ name: string; type: string; optional: boolean }>
+  dependencies?: string[]
+}
+/**
+ * Manifest type mapping component names to their metadata.
+ */
+export type Manifest = Record<string, ManifestEntry>
+export interface BfPreloadProps {
+  /**
+   * Path to static files directory.
+   * @default '/static'
+   */
+  staticPath?: string
+  /**
+   * Additional script URLs to preload.
+   * These are added in addition to the barefoot runtime.
+   */
+  scripts?: string[]
+  /**
+   * Whether to preload the barefoot runtime.
+   * @default true
+   */
+  includeRuntime?: boolean
+  /**
+   * Component manifest with dependency information.
+   * Used for automatic dependency chain preloading.
+   */
+  manifest?: Manifest
+  /**
+   * Component names to preload with their dependencies.
+   * Requires manifest to be provided.
+   */
+  components?: string[]
+}
+/**
+ * Resolves the full dependency chain for given components.
+ * Uses a visited set to prevent infinite loops from circular dependencies.
+ *
+ * @param components - Component names to resolve
+ * @param manifest - Component manifest with dependency information
+ * @param visited - Set of already visited component names (for cycle detection)
+ * @returns Array of clientJs paths for all dependencies
+ */
+function resolveDependencyChain(
+  components: string[],
+  manifest: Manifest,
+  visited = new Set<string>()
+): string[] {
+  const result: string[] = []
+  for (const compName of components) {
+    if (visited.has(compName)) continue
+    visited.add(compName)
+    const entry = manifest[compName]
+    if (!entry) continue
+    // Add this component's clientJs
+    if (entry.clientJs) {
+      result.push(entry.clientJs)
+    }
+    // Recursively add dependencies
+    if (entry.dependencies && entry.dependencies.length > 0) {
+      const childScripts = resolveDependencyChain(entry.dependencies, manifest, visited)
+      result.push(...childScripts)
+    }
+  }
+  return result
+}
+/**
+ * Renders modulepreload link tags for BarefootJS scripts.
+ * Place this component in your <head> element.
+ *
+ * By default, preloads the barefoot.js runtime which is required
+ * by all BarefootJS components.
+ *
+ * When manifest and components props are provided, automatically
+ * preloads the full dependency chain for those components.
+ */
+export function BfPreload({
+  staticPath = '/static',
+  scripts = [],
+  includeRuntime = true,
+  manifest,
+  components = [],
+}: BfPreloadProps = {}) {
+  const urls: string[] = []
+  // Always preload the barefoot runtime first (most critical)
+  if (includeRuntime) {
+    urls.push(`${staticPath}/components/barefoot.js`)
+  }
+  // Auto-preload component dependencies from manifest
+  if (manifest && components.length > 0) {
+    const dependencyScripts = resolveDependencyChain(components, manifest)
+    for (const script of dependencyScripts) {
+      urls.push(`${staticPath}/${script}`)
+    }
+  }
+  // Add additional scripts
+  urls.push(...scripts)
+  // Deduplicate URLs while preserving order
+  const uniqueUrls = [...new Set(urls)]
+  return (
+    <Fragment>
+      {uniqueUrls.map((url) => (
+        <link rel="modulepreload" href={url} />
+      ))}
+    </Fragment>
+  )
+}

package/src/scripts.tsx ADDED Viewed

@@ -0,0 +1,220 @@
+// @jsxRuntime automatic
+// @jsxImportSource hono/jsx
+//
+// Both pragmas must stay as the first lines of the file. The runtime
+// pragma enables the React-17-style import transform — without it
+// esbuild drops the import-source pragma on the floor and the JSX
+// compiles against the consumer's tsconfig runtime. In the scaffold's
+// case that's `@barefootjs/hono/jsx` (the marked-template adapter),
+// which doesn't register Hono's request context, so
+// `useRequestContext()` throws, the catch below swallows it, and
+// BfScripts returns null on every request — pages render server HTML
+// but never hydrate. esbuild also only looks for these pragmas in the
+// FIRST comment block in the file; a JSDoc above them silently wins.
+/**
+ * BfScripts Component
+ *
+ * Renders collected script tags at the end of the document body.
+ * BarefootJS components collect their script URLs during SSR render,
+ * and this component outputs them all at once to avoid DOM traversal issues.
+ *
+ * Usage:
+ * ```tsx
+ * import { BfScripts } from '@barefoot/hono/scripts'
+ *
+ * <html>
+ *   <body>
+ *     {children}
+ *     <BfScripts manifest={manifest} base="/static/components/" />
+ *   </body>
+ * </html>
+ * ```
+ *
+ * Pass `manifest` + `base` to follow stub references emitted by the
+ * 'use client' import rewriter (#1241). Without those props the
+ * component falls back to the JSX-driven script set, which misses
+ * components reached only through imperative `createComponent()`
+ * stub calls — see issue #1243.
+ */
+import { useRequestContext } from 'hono/jsx-renderer'
+import { Fragment } from 'hono/jsx'
+import { relPathFromComponentsBase, type BarefootBuildManifest } from './app'
+export type CollectedScript = {
+  src: string
+}
+export interface BfScriptsProps {
+  /**
+   * Build manifest from `dist/components/manifest.json`. When supplied
+   * alongside `base`, the component follows each rendered entry's
+   * `stubDeps` transitively and emits a `<script>` for every reachable
+   * `.client.js` — necessary for pages that only touch a child
+   * component through an imperative stub call (issue #1243).
+   *
+   * When omitted, behavior matches the pre-#1243 collector: only
+   * components whose SSR function executed get a script tag.
+   */
+  manifest?: BarefootBuildManifest
+  /**
+   * URL base where the component bundles are served (e.g.
+   * `/static/components/`). Required when `manifest` is supplied —
+   * stubDep entries store dist-relative paths and the component
+   * needs the URL prefix to emit a working `<script src>`.
+   */
+  base?: string
+  /**
+   * Extra manifest keys to treat as walk roots in addition to the
+   * SSR-rendered set. Use this for pages that mount a `'use client'`
+   * component via an inline `<script type="module">import "X.client.js"; render(root, "X", …)`
+   * instead of SSR'ing `<X />` directly. Without `entryRoots`, the
+   * walker has no anchor for `X`'s `stubDeps` and any sibling `'use
+   * client'` `.tsx` reached only through the imperative
+   * `createComponent` stub rewrite (#1240) never ships as a
+   * `<script>`, leaving the runtime registry empty and rendering
+   * `[ComponentName]` placeholders.
+   *
+   * The caller's inline `<script type="module">import …</script>`
+   * already loads the root bundle, so the root itself is *not*
+   * emitted as a separate `<script src>` — only the transitively
+   * reached `stubDeps` are. See #1431.
+   */
+  entryRoots?: string[]
+}
+/**
+ * Renders all collected BarefootJS script tags.
+ * Place this component at the end of your <body> element.
+ *
+ * After rendering, sets 'bfScriptsRendered' flag to true.
+ * Components rendered after BfScripts (e.g., inside Suspense boundaries)
+ * will check this flag and output their scripts inline instead of
+ * collecting them here.
+ */
+export function BfScripts(props: BfScriptsProps = {}) {
+  try {
+    const c = useRequestContext()
+    // Mark that BfScripts has been rendered.
+    // Components rendered after this point (e.g., inside Suspense)
+    // should output their scripts inline.
+    c.set('bfScriptsRendered', true)
+    const scripts: CollectedScript[] = c.get('bfCollectedScripts') || []
+    const outputSet: Set<string> = c.get('bfOutputScripts') || new Set()
+    const { manifest, base, entryRoots } = props
+    // `entryRoots` extends both the walk-root set AND the `excluded` set.
+    // Walk-root so the root's `stubDeps` get visited (the manually-mounted
+    // component never SSR'd, so it isn't in `bfOutputScripts`). Excluded
+    // so the root's own `.client.js` isn't re-emitted — the caller's
+    // inline `<script type="module">import "X.client.js"; render(...)`
+    // already loaded it. See #1431.
+    const roots = entryRoots && entryRoots.length > 0
+      ? new Set([...outputSet, ...entryRoots])
+      : outputSet
+    if (entryRoots) for (const r of entryRoots) outputSet.add(r)
+    const stubScripts = manifest && base
+      ? collectStubDepScripts(manifest, base, roots, outputSet)
+      : new Map<string, CollectedScript>()
+    // Record stub-derived names on the same context flag so any later
+    // SSR pass (e.g. a Suspense boundary that renders after this point)
+    // won't double-emit the same `.client.js`. The flag's name keeps
+    // it symmetric with the snippet in `addScriptCollection`.
+    if (stubScripts.size > 0) c.set('bfOutputScripts', outputSet)
+    // Reverse script order so child components load before parents.
+    // During SSR, parent components render first and collect their scripts,
+    // then child components add their scripts. But for hydration, children
+    // need to register their templates before parents try to use createComponent().
+    // barefoot.js must stay first since it provides the runtime.
+    //
+    // Stub-derived scripts must come BEFORE the component scripts in the
+    // emitted order — `<script type="module">` tags evaluate in document
+    // order with microtask checkpoints between them, so a parent's
+    // `hydrate()`-scheduled walk fires (and its `init` calls
+    // `createComponent(...)` against the stub) before any later module
+    // script has registered. Within stubScripts, `collectStubDepScripts`
+    // already returns DFS post-order (deps before their dependent), so
+    // a chain A→B→C ships C, B, then the component bundle that stubs A.
+    const barefootScript = scripts.find(s => s.src.includes('barefoot.js'))
+    const componentScripts = scripts.filter(s => !s.src.includes('barefoot.js'))
+    const finalScripts = [
+      ...(barefootScript ? [barefootScript] : []),
+      ...stubScripts.values(),
+      ...componentScripts.reverse(),
+    ]
+    return (
+      <Fragment>
+        {finalScripts.map(({ src }) => (
+          <script type="module" src={src} />
+        ))}
+      </Fragment>
+    )
+  } catch {
+    // Context unavailable (e.g., not using jsxRenderer)
+    return null
+  }
+}
+/**
+ * Walk stub-rewrite edges from each manifest entry in `roots`,
+ * returning the script URLs for every transitively reachable
+ * `.client.js` in **DFS post-order** — every dep precedes its
+ * dependent in iteration order. Skips any name already present in
+ * `excluded` (these have a script tag elsewhere). Mutates `excluded`
+ * to record every dep that's been resolved so the caller can pass
+ * it to the next SSR pass without double-emitting. Exported for tests.
+ *
+ * Typical call shape: `roots` ⊆ `excluded`. The caller passes the
+ * set of components whose SSR function already pushed a `<script>`
+ * (`bfOutputScripts`) as BOTH arguments — "these are already
+ * emitted, now walk their stubDeps." A `roots` value already in
+ * `excluded` is still walked (we need its `stubDeps`); a `dep`
+ * already in `excluded` is recorded as visited but not re-emitted.
+ *
+ * Why post-order: `<script type="module">` tags evaluate in document
+ * order with microtask checkpoints between them, so the first
+ * script's `hydrate()`-scheduled walk fires before any later
+ * module loads. A chain A→B→C must ship C, B, then A's bundle —
+ * BFS order (B, C) would let B's hydration call
+ * `createComponent('C', ...)` against an empty registry. Post-order
+ * also handles DAG edges like A→B, A→C, C→B correctly
+ * (deepest-first, dependencies-first).
+ *
+ * Cycle-safe: a visited set short-circuits any A → B → A loop.
+ */
+export function collectStubDepScripts(
+  manifest: BarefootBuildManifest,
+  base: string,
+  roots: Iterable<string>,
+  excluded: Set<string>,
+): Map<string, CollectedScript> {
+  const result = new Map<string, CollectedScript>()
+  const prefix = base.endsWith('/') ? base : base + '/'
+  const visited = new Set<string>()
+  function visit(name: string): void {
+    if (name === '__barefoot__') return
+    if (visited.has(name)) return
+    visited.add(name)
+    const entry = manifest[name]
+    if (entry?.stubDeps) {
+      // Recurse FIRST so deps are emitted before this node — that's
+      // what produces post-order. Cycles short-circuit at the
+      // `visited.has(name)` check at the top of each call.
+      for (const dep of entry.stubDeps) visit(dep)
+    }
+    if (excluded.has(name)) return
+    excluded.add(name)
+    if (entry?.clientJs) {
+      const src = prefix + relPathFromComponentsBase(entry.clientJs)
+      result.set(name, { src })
+    }
+  }
+  for (const name of roots) visit(name)
+  return result
+}

package/src/test-render.ts ADDED Viewed

@@ -0,0 +1,143 @@
+/**
+ * Hono test renderer
+ *
+ * Compiles JSX source with HonoAdapter and renders to HTML via Hono's app.request().
+ * Used by adapter-tests conformance runner.
+ */
+import { compileJSX } from '@barefootjs/jsx'
+import type { TemplateAdapter } from '@barefootjs/jsx'
+import { Hono } from 'hono'
+import { mkdir, rm } from 'node:fs/promises'
+import { resolve } from 'node:path'
+// Place temp files inside the hono package so hono/jsx resolves correctly
+const RENDER_TEMP_DIR = resolve(import.meta.dir, '../.render-temp')
+export interface RenderOptions {
+  /** JSX source code */
+  source: string
+  /** Template adapter to use */
+  adapter: TemplateAdapter
+  /** Props to inject (optional) */
+  props?: Record<string, unknown>
+  /** Additional component files (filename → source) */
+  components?: Record<string, string>
+  /**
+   * Explicit component to render when the source declares multiple
+   * exports. When omitted, the first function-valued export in
+   * `Object.keys(mod)` iteration order is picked — that order is
+   * alphabetical for dynamically imported ES modules in Bun/V8, so
+   * relying on declaration order can pick the wrong component
+   * (e.g. `PropsReactivityComparison` before `ReactiveProps`).
+   */
+  componentName?: string
+}
+export async function renderHonoComponent(options: RenderOptions): Promise<string> {
+  const { source, adapter, props, components, componentName: requestedName } = options
+  // Compile child components first
+  const childCodes: string[] = []
+  const componentKeys = new Set<string>()
+  if (components) {
+    for (const [filename, childSource] of Object.entries(components)) {
+      componentKeys.add(filename)
+      const childResult = compileJSX(childSource, filename, { adapter })
+      const childErrors = childResult.errors.filter(e => e.severity === 'error')
+      if (childErrors.length > 0) {
+        throw new Error(`Compilation errors in ${filename}:\n${childErrors.map(e => e.message).join('\n')}`)
+      }
+      const childTemplate = childResult.files.find(f => f.type === 'markedTemplate')
+      if (!childTemplate) throw new Error(`No marked template for ${filename}`)
+      // Strip export keywords so only the parent component is exported
+      const localCode = childTemplate.content.replace(/\bexport\s+(default\s+)?/g, '')
+      childCodes.push(localCode)
+    }
+  }
+  // Compile parent source
+  const result = compileJSX(source, 'component.tsx', { adapter })
+  const errors = result.errors.filter(e => e.severity === 'error')
+  if (errors.length > 0) {
+    throw new Error(`Compilation errors:\n${errors.map(e => e.message).join('\n')}`)
+  }
+  const templateFile = result.files.find(f => f.type === 'markedTemplate')
+  if (!templateFile) throw new Error('No marked template in compile output')
+  let parentCode = templateFile.content
+  // Strip import lines that reference component files
+  if (componentKeys.size > 0) {
+    parentCode = parentCode
+      .split('\n')
+      .filter(line => {
+        const importMatch = line.match(/^\s*import\s+.*from\s+['"](.+?)['"]/)
+        if (!importMatch) return true
+        const importPath = importMatch[1]
+        // Match against component keys: './badge' matches './badge.tsx'
+        for (const key of componentKeys) {
+          const keyWithoutExt = key.replace(/\.tsx?$/, '')
+          if (importPath === keyWithoutExt || importPath === key) return false
+        }
+        return true
+      })
+      .join('\n')
+  }
+  // Combine: JSX pragma + child compiled functions + parent compiled code
+  const codeParts = ['/** @jsxImportSource hono/jsx */']
+  for (const childCode of childCodes) {
+    codeParts.push(childCode)
+  }
+  codeParts.push(parentCode)
+  const code = codeParts.join('\n')
+  await mkdir(RENDER_TEMP_DIR, { recursive: true })
+  // Unique filename per render to avoid Bun's process-level module cache
+  // (bun#12371: re-importing the same path returns stale module)
+  const tempFile = resolve(
+    RENDER_TEMP_DIR,
+    `render-${Date.now()}-${Math.random().toString(36).slice(2)}.tsx`,
+  )
+  await Bun.write(tempFile, code)
+  try {
+    const mod = await import(tempFile)
+    // Explicit `componentName` wins; otherwise pick the first
+    // function-valued export. `Object.keys` for dynamically imported
+    // modules iterates alphabetically in Bun/V8, so the fallback can
+    // surprise multi-component files — pass `componentName` to pin.
+    let resolvedName: string | undefined = requestedName
+    if (resolvedName) {
+      if (typeof mod[resolvedName] !== 'function') {
+        const available = Object.keys(mod).filter(k => typeof mod[k] === 'function')
+        throw new Error(
+          `Requested component "${resolvedName}" not found in compiled module. Available: ${available.join(', ')}`,
+        )
+      }
+    } else {
+      resolvedName = Object.keys(mod).find(k => typeof mod[k] === 'function')
+      if (!resolvedName) throw new Error('No component function found in compiled module')
+    }
+    const Component = mod[resolvedName]
+    // Render using Hono's app.request()
+    const app = new Hono()
+    app.get('/', (c) =>
+      c.html(Component({ __instanceId: 'test', __bfChild: false, ...props })),
+    )
+    const res = await app.request('/')
+    if (!res.ok) {
+      const body = await res.text()
+      throw new Error(`Render failed with status ${res.status}: ${body}`)
+    }
+    return await res.text()
+  } finally {
+    await rm(tempFile, { force: true }).catch(() => {})
+  }
+}

package/src/utils.ts ADDED Viewed

@@ -0,0 +1,26 @@
+import { raw } from 'hono/html'
+/**
+ * Output HTML comment marker for conditional reconciliation.
+ * Same signature as Go template bfComment function.
+ */
+export function bfComment(key: string) {
+  return raw(`<!--bf-${key}-->`)
+}
+/**
+ * Output opening comment marker for reactive text expressions.
+ * Renders <!--bf:slotId-->
+ */
+export function bfText(slotId: string) {
+  return raw(`<!--bf:${slotId}-->`)
+}
+/**
+ * Output closing comment marker for reactive text expressions.
+ * Renders <!--/-->
+ */
+export function bfTextEnd() {
+  return raw('<!--/-->')
+}