@barefootjs/xslate 0.30.6 → 0.31.1

package/lib/BarefootJS/Backend/Xslate.pm

@@ -1,5 +1,5 @@
 package BarefootJS::Backend::Xslate;
-our $VERSION = "0.30.5";
+our $VERSION = "0.31.0";
 use strict;
 use warnings;
 use utf8;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/xslate",
-  "version": "0.30.6",
+  "version": "0.31.1",
   "description": "Text::Xslate (Kolon) adapter for BarefootJS — compiles IR to .tx templates and ships the Xslate rendering backend; runs under any PSGI/Plack app",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,9 +17,9 @@
     "./test-render": {
       "bun": "./src/test-render.ts"
     },
-    "./build": {
-      "types": "./dist/build.d.ts",
-      "import": "./dist/build.js"
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
     }
   },
   "files": [
@@ -30,7 +30,7 @@
   ],
   "scripts": {
     "build": "bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/index.ts ./src/adapter/index.ts ./src/build.ts --root ./src --outdir ./dist --format esm --external @barefootjs/jsx --external @barefootjs/shared",
+    "build:js": "bun build ./src/index.ts ./src/adapter/index.ts --root ./src --outdir ./dist --format esm --external @barefootjs/jsx --external @barefootjs/shared --external @barefootjs/vite --external vite && bun build ./src/vite.ts --outfile ./dist/vite.js --format esm --target node --external @barefootjs/vite --external vite --external typescript",
     "build:types": "tsgo --emitDeclarationOnly --outDir ./dist",
     "test": "bun test",
     "clean": "rm -rf dist",
@@ -55,14 +55,27 @@
     "directory": "packages/adapter-xslate"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.30.6"
+    "@barefootjs/shared": "0.31.1"
   },
   "peerDependencies": {
-    "@barefootjs/jsx": ">=0.2.0"
+    "@barefootjs/jsx": ">=0.2.0",
+    "@barefootjs/vite": ">=0.2.0",
+    "vite": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@barefootjs/vite": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@barefootjs/adapter-tests": "0.1.0",
-    "@barefootjs/jsx": "0.30.6",
-    "typescript": "^5.0.0"
+    "@barefootjs/jsx": "0.31.1",
+    "@barefootjs/vite": "0.31.1",
+    "@barefootjs/client": "0.31.1",
+    "typescript": "^5.0.0",
+    "vite": "^6.0.0"
   }
 }

package/src/__tests__/vite.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Coverage of `@barefootjs/xslate/vite`'s `barefoot()`:
+ *
+ * - one real `vite build()` end to end (mirrors `@barefootjs/go-template/
+ *   vite`, `@barefootjs/hono/vite`, `@barefootjs/blade/vite`'s,
+ *   `@barefootjs/jinja/vite`'s, and `@barefootjs/erb/vite`'s own
+ *   `vite.test.ts` rigor — a plugin that only passes mocked unit tests
+ *   hasn't been shown to work) against a checked-in fixture (not a system
+ *   tmpdir) so `@barefootjs/client` resolves through the monorepo's real
+ *   node_modules symlinks;
+ * - the `assets` → generated `bf-assets.json` behavior, exercised the same
+ *   way (a real build, since it needs the real manifest Vite writes).
+ *
+ * Unlike Go, there is no `afterEmit`-driven type-combination step to test
+ * here (see `vite.ts`'s module docstring) — `XslateAdapter.generate()` never
+ * produces a `types` section at all, so `barefoot()` always returns a
+ * single-element array unless `assets` is set.
+ */
+import { describe, test, expect } from 'bun:test'
+import { build } from 'vite'
+import { mkdtemp, rm, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { barefoot, barefoot as defaultBarefoot } from '../vite.ts'
+
+const FIXTURE_ROOT = resolve(import.meta.dirname, '../../e2e-fixture')
+
+describe('@barefootjs/xslate/vite: real vite build', () => {
+  test('exports the same function as both named `barefoot` and default', () => {
+    expect(defaultBarefoot).toBe(barefoot)
+  })
+
+  test('returns a single-element plugin array when `assets` is omitted', () => {
+    const plugins = barefoot({ components: ['src/components'], templates: 'views' })
+    expect(plugins).toHaveLength(1)
+  })
+
+  test('writes a self-contained .tx template with scriptAssets baked in, same as core alone would do', async () => {
+    const outDir = await mkdtemp(join(tmpdir(), 'barefoot-xslate-vite-dist-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-xslate-vite-views-'))
+
+    try {
+      await build({
+        configFile: false,
+        root: FIXTURE_ROOT,
+        base: '/static/build/',
+        logLevel: 'warn',
+        build: { outDir, emptyOutDir: true },
+        plugins: barefoot({
+          components: ['src/components'],
+          templates: templatesDir,
+        }),
+      })
+
+      const template = await readFile(join(templatesDir, 'Counter.tx'), 'utf8')
+      expect(template).toContain("bf.register_script(")
+    } finally {
+      await rm(outDir, { recursive: true, force: true })
+      await rm(templatesDir, { recursive: true, force: true })
+    }
+  }, 60_000)
+
+  test('`assets` resolves a non-component entry\'s manifest-hashed URL into a generated JSON asset map', async () => {
+    const outDir = await mkdtemp(join(tmpdir(), 'barefoot-xslate-vite-dist-assets-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-xslate-vite-views-assets-'))
+    const assetsPath = join(FIXTURE_ROOT, 'dist/bf-assets.json')
+
+    try {
+      await build({
+        configFile: false,
+        root: FIXTURE_ROOT,
+        base: '/static/build/',
+        logLevel: 'warn',
+        build: {
+          outDir,
+          emptyOutDir: true,
+          // Registering the non-component entry is the CALLER's job (stock
+          // Vite config) — `assets` below only resolves the URL Vite
+          // already bundled it to, it doesn't request the bundling.
+          rollupOptions: { input: { bootstrap: resolve(FIXTURE_ROOT, 'client/bootstrap.ts') } },
+        },
+        plugins: barefoot({
+          components: ['src/components'],
+          templates: templatesDir,
+          assets: { Bootstrap: 'client/bootstrap.ts' },
+        }),
+      })
+
+      const manifest = JSON.parse(await readFile(join(outDir, '.vite/manifest.json'), 'utf8'))
+      const expectedUrl = `/static/build/${manifest['client/bootstrap.ts'].file}`
+
+      const content = JSON.parse(await readFile(assetsPath, 'utf8'))
+      expect(content).toEqual({ Bootstrap: expectedUrl })
+    } finally {
+      await rm(outDir, { recursive: true, force: true })
+      await rm(templatesDir, { recursive: true, force: true })
+      await rm(join(FIXTURE_ROOT, 'dist'), { recursive: true, force: true })
+    }
+  }, 60_000)
+
+  test('`assets` throws an actionable error when the entry was never registered as a Rollup input', async () => {
+    const outDir = await mkdtemp(join(tmpdir(), 'barefoot-xslate-vite-dist-assets-missing-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-xslate-vite-views-assets-missing-'))
+
+    try {
+      await expect(
+        build({
+          configFile: false,
+          root: FIXTURE_ROOT,
+          base: '/static/build/',
+          logLevel: 'silent',
+          build: { outDir, emptyOutDir: true },
+          plugins: barefoot({
+            components: ['src/components'],
+            templates: templatesDir,
+            assets: { Bootstrap: 'client/bootstrap.ts' },
+          }),
+        }),
+      ).rejects.toThrow(/was not found in the build manifest/)
+    } finally {
+      await rm(outDir, { recursive: true, force: true })
+      await rm(templatesDir, { recursive: true, force: true })
+      await rm(join(FIXTURE_ROOT, 'dist'), { recursive: true, force: true })
+    }
+  }, 60_000)
+})

package/src/__tests__/xslate-adapter.test.ts

@@ -572,3 +572,149 @@ function Widget({ rows }: { rows: { x: string }[] }) {
     expect(template).toContain('<: $cfg.x :>')
   })
 })
+
+describe('XslateAdapter - scriptAssets (Vite late-binding, PR1)', () => {
+  const CLIENT_COMPONENT = `
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function Counter() {
+  const [count, setCount] = createSignal(0)
+  return <button onClick={() => setCount(count() + 1)}>{count()}</button>
+}
+`
+
+  test('emits one register_script per URL, in order, when scriptAssets is set', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new XslateAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js', '/assets/counter-def456.js'],
+    })
+    const runtimeIdx = template.indexOf("$bf.register_script('/assets/runtime-abc123.js')")
+    const compIdx = template.indexOf("$bf.register_script('/assets/counter-def456.js')")
+    expect(runtimeIdx).toBeGreaterThanOrEqual(0)
+    expect(compIdx).toBeGreaterThanOrEqual(0)
+    expect(runtimeIdx).toBeLessThan(compIdx)
+    expect(template).toContain('_bf_reg0')
+    expect(template).toContain('_bf_reg1')
+    expect(template).not.toContain('/static/components/barefoot.js')
+    expect(template).not.toContain('Counter.client.js')
+  })
+
+  test('emits a single registration for a single-element scriptAssets array', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new XslateAdapter().generate(ir, {
+      scriptAssets: ['/assets/only-one.js'],
+    })
+    expect(template).toContain("$bf.register_script('/assets/only-one.js')")
+    expect(template.match(/register_script/g)?.length).toBe(1)
+  })
+
+  test('an empty scriptAssets array emits no script registrations', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new XslateAdapter().generate(ir, { scriptAssets: [] })
+    expect(template).not.toContain('register_script')
+  })
+
+  test('skipScriptRegistration still wins when scriptAssets is also set', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new XslateAdapter().generate(ir, {
+      skipScriptRegistration: true,
+      scriptAssets: ['/assets/should-not-appear.js'],
+    })
+    expect(template).not.toContain('register_script')
+  })
+
+  test('absent scriptAssets falls back to adapter-computed script paths', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const computed = new XslateAdapter().generate(ir).template
+    const explicitUndefined = new XslateAdapter().generate(ir, { scriptAssets: undefined }).template
+    expect(computed).toContain("$bf.register_script('/static/components/barefoot.js')")
+    expect(computed).toContain("$bf.register_script('/static/components/Counter.client.js')")
+    expect(explicitUndefined).toBe(computed)
+  })
+})
+
+describe('XslateAdapter - preloadAssets', () => {
+  const CLIENT_COMPONENT = `
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function Counter() {
+  const [count, setCount] = createSignal(0)
+  return <button onClick={() => setCount(count() + 1)}>{count()}</button>
+}
+`
+
+  test('non-empty preloadAssets + non-empty scriptAssets: preload registrations emitted, in order, before script registrations', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new XslateAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js', '/assets/counter-def456.js'],
+      preloadAssets: ['/assets/index-pre1.js', '/assets/shared-pre2.js'],
+    })
+    const pre1Idx = template.indexOf(": my $_bf_pre0 = $bf.register_preload('/assets/index-pre1.js');")
+    const pre2Idx = template.indexOf(": my $_bf_pre1 = $bf.register_preload('/assets/shared-pre2.js');")
+    const script1Idx = template.indexOf(": my $_bf_reg0 = $bf.register_script('/assets/runtime-abc123.js');")
+    const script2Idx = template.indexOf(": my $_bf_reg1 = $bf.register_script('/assets/counter-def456.js');")
+    expect(pre1Idx).toBeGreaterThanOrEqual(0)
+    expect(pre2Idx).toBeGreaterThan(pre1Idx)
+    expect(script1Idx).toBeGreaterThan(pre2Idx)
+    expect(script2Idx).toBeGreaterThan(script1Idx)
+  })
+
+  test('preloadAssets: [] emits no preload registration', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new XslateAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: [],
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).toContain("$bf.register_script('/assets/runtime-abc123.js')")
+  })
+
+  test('preloadAssets: undefined emits no preload registration', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new XslateAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: undefined,
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).toContain("$bf.register_script('/assets/runtime-abc123.js')")
+  })
+
+  test('preloadAssets non-empty but scriptAssets: [] emits no preload registration (preloads are only meaningful alongside a real script)', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new XslateAdapter().generate(ir, {
+      scriptAssets: [],
+      preloadAssets: ['/assets/index-pre1.js'],
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).not.toContain('register_script')
+  })
+
+  test('skipScriptRegistration: true suppresses both preloads and scripts', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new XslateAdapter().generate(ir, {
+      skipScriptRegistration: true,
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: ['/assets/index-pre1.js'],
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).not.toContain('register_script')
+  })
+
+  // Regression guard: a previous attempt emitted a literal
+  // `<link rel="modulepreload">` tag directly into the component template,
+  // which injected a rendered DOM node before the component's root and
+  // broke hydration across all eight integrations (blade, erb,
+  // go-template, jinja, mojolicious, rust, twig, xslate). Preload hints
+  // must ONLY ever be emitted as no-output register statements (here,
+  // `: my $_bf_preN = $bf.register_preload(...);`) that the adapter's
+  // runtime later renders itself — never as literal markup baked into the
+  // template.
+  test('never emits a literal <link tag into the template', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new XslateAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: ['/assets/index-pre1.js'],
+    })
+    expect(template).not.toContain('<link')
+  })
+})

package/src/adapter/expr/emitters.ts

@@ -70,15 +70,33 @@ const PREDICATE_METHODS = new Set<HigherOrderMethod>([
  * (#2038) instead of silently degrading to the callback's receiver.
  */
 export class XslateFilterEmitter implements ParsedExprEmitter {
+  // Plain field declarations + assignment, NOT TS constructor-parameter-
+  // property shorthand: Vite's `bundleConfigFile` externalizes any bare
+  // (non-relative) import when loading `vite.config.ts` (see
+  // `@barefootjs/xslate/vite`'s docstring), so this file can be loaded
+  // directly by Node's OWN native TypeScript type-stripping (enabled by
+  // default since Node 22.18/23.6) rather than esbuild — and Node's
+  // strip-only mode does not support parameter properties (`SyntaxError
+  // [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]`), only plain type annotations.
+  private readonly param: string
+  private readonly localVarMap: Map<string, string>
+  private readonly isStringName: (n: string) => boolean
+  // Records a BF101 for predicate shapes this emitter can only degrade
+  // (#2038). Optional so emitter construction stays possible without an
+  // adapter; a missing hook keeps the old silent-degrade emit.
+  private readonly onUnsupported?: (message: string, reason?: string) => void
+
   constructor(
-    private readonly param: string,
-    private readonly localVarMap: Map<string, string>,
-    private readonly isStringName: (n: string) => boolean = () => false,
-    // Records a BF101 for predicate shapes this emitter can only degrade
-    // (#2038). Optional so emitter construction stays possible without an
-    // adapter; a missing hook keeps the old silent-degrade emit.
-    private readonly onUnsupported?: (message: string, reason?: string) => void,
-  ) {}
+    param: string,
+    localVarMap: Map<string, string>,
+    isStringName: (n: string) => boolean = () => false,
+    onUnsupported?: (message: string, reason?: string) => void,
+  ) {
+    this.param = param
+    this.localVarMap = localVarMap
+    this.isStringName = isStringName
+    this.onUnsupported = onUnsupported
+  }
 
   identifier(name: string): string {
     if (name === this.param) return `$${this.param}`
@@ -239,7 +257,13 @@ export class XslateFilterEmitter implements ParsedExprEmitter {
  *   - higher-order methods route through `$bf` array helpers.
  */
 export class XslateTopLevelEmitter implements ParsedExprEmitter {
-  constructor(private readonly ctx: XslateEmitContext) {}
+  // Plain field + assignment, not a parameter property — see
+  // `XslateFilterEmitter`'s constructor comment above for why.
+  private readonly ctx: XslateEmitContext
+
+  constructor(ctx: XslateEmitContext) {
+    this.ctx = ctx
+  }
 
   identifier(name: string): string {
     // `undefined` / `null` nested inside a larger expression tree —

package/src/adapter/xslate-adapter.ts

@@ -163,9 +163,6 @@ export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRe
   name = 'xslate'
   extension = '.tx'
   templatesPerComponent = true
-  // Template-string target with no component layer: `bf build` emits a static
-  // import-map HTML snippet to include into the page <head>.
-  importMapInjection = 'html-snippet' as const
 
   /**
    * Identifier-path callees the Xslate runtime can render in template scope.
@@ -334,7 +331,7 @@ export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRe
     // Generate script registration
     const scriptReg = options?.skipScriptRegistration
       ? ''
-      : this.generateScriptRegistrations(ir, options?.scriptBaseName)
+      : this.generateScriptRegistrations(ir, options?.scriptBaseName, options?.scriptAssets, options?.preloadAssets)
 
     // SSR context consumers (`const x = useContext(Ctx)`): seed each local
     // from the active provider value (or the `createContext` default). The
@@ -376,7 +373,38 @@ export class XslateAdapter extends BaseAdapter implements IRNodeEmitter<XslateRe
   // Script Registration
   // ===========================================================================
 
-  private generateScriptRegistrations(ir: ComponentIR, scriptBaseName?: string): string {
+  private generateScriptRegistrations(
+    ir: ComponentIR,
+    scriptBaseName?: string,
+    scriptAssets?: string[],
+    preloadAssets?: string[],
+  ): string {
+    // `scriptAssets`, when present (including `[]`), fully supersedes the
+    // adapter-computed `barefootJsPath` / `clientJsBasePath` pair — see
+    // `AdapterGenerateOptions.scriptAssets`. The caller (e.g. the Vite
+    // plugin) has already decided the exact ordered URL list, including
+    // whether any script is needed at all.
+    if (scriptAssets) {
+      if (scriptAssets.length === 0) return ''
+      // `preloadAssets` is only meaningful alongside a non-empty
+      // `scriptAssets` (see `AdapterGenerateOptions.preloadAssets`), and
+      // every preload registration is emitted BEFORE every script
+      // registration — a hint that arrives after the script it describes
+      // is useless. Distinct `_bf_pre*` var prefix keeps these `my`
+      // bindings from colliding with the `_bf_reg*` script ones below
+      // (Kolon forbids re-`my` of the same name in one scope). Same
+      // throwaway-`my` no-output trick as `register_script`:
+      // `register_preload`'s return value is never printed.
+      const lines = (preloadAssets ?? []).map(
+        (url, i) => `: my $_bf_pre${i} = $bf.register_preload('${url}');`,
+      )
+      lines.push(
+        ...scriptAssets.map((url, i) => `: my $_bf_reg${i} = $bf.register_script('${url}');`),
+      )
+      lines.push('')
+      return lines.join('\n')
+    }
+
     const hasInteractivity = hasClientInteractivity(ir)
     if (!hasInteractivity) return ''