@barefootjs/xslate 0.8.0 → 0.9.0

package/lib/BarefootJS/Backend/Xslate.pm

@@ -1,5 +1,5 @@
 package BarefootJS::Backend::Xslate;
-our $VERSION = "0.01";
+our $VERSION = "0.8.0";
 use strict;
 use warnings;
 use utf8;
@@ -45,7 +45,10 @@ sub new ($class, %args) {
     };
 
     # Accept a pre-built Text::Xslate instance, or build one from `path`
-    # (a dir of `.tx` templates) plus any extra `xslate_options`.
+    # (a dir of `.tx` templates) plus any extra `xslate_options`. The adapter
+    # calls every runtime helper as a `$bf` method (`$bf.filter`, `$bf.lc`, …)
+    # or a Kolon builtin (`.join`, `.size`), so no custom `function` map is
+    # needed here — a plain Kolon, html-escaping instance suffices.
     my $xslate = $args{xslate};
     unless ($xslate) {
         $xslate = Text::Xslate->new(
@@ -127,6 +130,11 @@ Constructs a backend. Accepts a pre-built C<xslate> instance, or a C<path>
 Kolon, html-escaping Text::Xslate. C<json_encoder> overrides the default
 canonical L<JSON::PP> encoder.
 
+No custom Kolon C<function> map is needed: the C<@barefootjs/xslate> adapter
+calls every runtime helper as a C<$bf> method (C<< $bf.filter($arr, -> $x {
+... }) >>, C<< $bf.lc($s) >>, …) or a Kolon builtin (C<< $arr.join(", ") >>,
+C<< $arr.size() >>), so a plain instance renders the emitted templates.
+
 =head2 encode_json($data) / mark_raw($str) / materialize($value) / render_named($name, $bf, \%vars)
 
 The four engine-specific operations the runtime delegates to. C<mark_raw> uses

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/xslate",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "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",
@@ -11,28 +11,15 @@
       "import": "./dist/index.js"
     },
     "./adapter": {
-      "types": "./src/adapter/index.ts",
-      "import": "./src/adapter/index.ts"
+      "types": "./dist/adapter/index.d.ts",
+      "import": "./dist/adapter/index.js"
+    },
+    "./test-render": {
+      "bun": "./src/test-render.ts"
     },
     "./build": {
-      "types": "./src/build.ts",
-      "import": "./src/build.ts"
-    }
-  },
-  "publishConfig": {
-    "exports": {
-      ".": {
-        "types": "./dist/index.d.ts",
-        "import": "./dist/index.js"
-      },
-      "./adapter": {
-        "types": "./dist/adapter/index.d.ts",
-        "import": "./dist/adapter/index.js"
-      },
-      "./build": {
-        "types": "./dist/build.d.ts",
-        "import": "./dist/build.js"
-      }
+      "types": "./dist/build.d.ts",
+      "import": "./dist/build.js"
     }
   },
   "files": [
@@ -68,15 +55,15 @@
     "directory": "packages/adapter-xslate"
   },
   "dependencies": {
-    "@barefootjs/perl": "0.8.0",
-    "@barefootjs/shared": "0.8.0"
+    "@barefootjs/perl": "0.9.0",
+    "@barefootjs/shared": "0.9.0"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0"
   },
   "devDependencies": {
     "@barefootjs/adapter-tests": "0.1.0",
-    "@barefootjs/jsx": "0.8.0",
+    "@barefootjs/jsx": "0.9.0",
     "typescript": "^5.0.0"
   }
 }

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

@@ -0,0 +1,131 @@
+/**
+ * XslateAdapter — Conformance Tests
+ *
+ * Runs the shared adapter conformance corpus (JSX fixtures, template
+ * primitives, marker conformance) against the Text::Xslate (Kolon)
+ * adapter, rendering each fixture end-to-end through real Text::Xslate +
+ * `BarefootJS::Backend::Xslate` via `renderXslateComponent`.
+ *
+ * The Xslate adapter was ported from the Mojolicious adapter and shares
+ * its Perl-scoping + SSR-context limitations, so the skip / diagnostic
+ * sets below start from mojo's and diverge only where the engine
+ * genuinely differs. Every divergence carries a one-line rationale.
+ */
+
+import {
+  runAdapterConformanceTests,
+  TemplatePrimitiveCaseId,
+} from '@barefootjs/adapter-tests'
+import { XslateAdapter } from '../adapter'
+import { renderXslateComponent, XslateNotAvailableError } from '../test-render'
+
+runAdapterConformanceTests({
+  name: 'xslate',
+  factory: () => new XslateAdapter(),
+  render: renderXslateComponent,
+  // Skips here are VERIFIED, not inherited from mojo. Notably, the six
+  // fixtures mojo skips for Perl-EP scoping faults — `logical-or-jsx`,
+  // `nullish-coalescing-jsx`, `branch-map`, `return-logical-or`,
+  // `return-nullish-coalescing`, `return-map` (bare `$label` / `$items`
+  // without a `my` binding) — all PASS on Xslate, because Kolon resolves
+  // `$label` from the per-render vars rather than a Perl lexical, so there
+  // is no undefined-symbol fault. Xslate therefore skips strictly fewer
+  // fixtures than mojo. Each entry below was confirmed to fail with
+  // skipJsx emptied.
+  skipJsx: [
+    // SSR context propagation (`<Ctx.Provider value>` → `useContext`): the
+    // template reads a stash key that's never seeded. Implemented on Go; the
+    // Perl stash-seed path is a follow-up port, so Xslate stays skipped (#1297).
+    'context-provider',
+    // Multi-component shared-state pairs whose children render inside a keyed
+    // `.map` (loop children, no `_bf_slot`): the test harness derives a
+    // non-deterministic `<child>_<rand>` scope id instead of the canonical
+    // `<ChildName>_*` the reference HTML pins, and per-item loop state isn't
+    // seeded server-side. Harness-level scope-id plumbing; single-component
+    // `reactive-props` passes. (Same pair mojo skips.)
+    'toggle-shared',
+    'props-reactivity-comparison',
+    // (`kbd` is not skipped here — it's a BF101 refusal pinned in
+    // `expectedDiagnostics` below, not a render-mismatch.)
+  ],
+  // Per-fixture build-time contracts for shapes the Xslate adapter
+  // intentionally refuses to lower. Mirrors mojo's set — the lowering
+  // gates are shared code paths in the ported adapter.
+  expectedDiagnostics: {
+    // Sibling-imported child component in a loop body: emits a
+    // cross-template call needing separate registration. BF103 makes
+    // the requirement loud (same as mojo).
+    'static-array-children': [{ code: 'BF103', severity: 'error' }],
+    // TodoApp / TodoAppSSR import `TodoItem` from a sibling file and
+    // call it inside a keyed `.map`. With the standalone-filter fix in
+    // place these reach the SAME BF103 (imported child in `.map`) as
+    // mojo — NOT BF101 — confirming the `.filter(...)` chain itself now
+    // lowers and the only remaining gate is the imported-child one.
+    'todo-app': [{ code: 'BF103', severity: 'error' }],
+    'todo-app-ssr': [{ code: 'BF103', severity: 'error' }],
+    // Array-destructure loop param (`([k, v]) => …`) can't lower to a
+    // single Kolon loop variable (same BF104 as mojo).
+    'static-array-from-props': [{ code: 'BF104', severity: 'error' }],
+    // Both BF103 (imported child) and BF104 (destructure) fire.
+    'static-array-from-props-with-component': [
+      { code: 'BF103', severity: 'error' },
+      { code: 'BF104', severity: 'error' },
+    ],
+    // Rest-destructure `.map()` callbacks — the loop emitter raises the
+    // generic BF104 destructure refusal regardless of rest-vs-plain
+    // (same surface as mojo).
+    'rest-destructure-object-in-map': [{ code: 'BF104', severity: 'error' }],
+    'rest-destructure-object-spread-in-map': [{ code: 'BF104', severity: 'error' }],
+    'rest-destructure-array-in-map': [{ code: 'BF104', severity: 'error' }],
+    'rest-destructure-nested-in-map': [{ code: 'BF104', severity: 'error' }],
+    // XSLATE-SPECIFIC (mojo passes this): the site/ui Button auto-infers a
+    // `<Slot>` sibling that spreads `{...props}` / `{...children.props}`
+    // onto its root element. Kolon hashref method args can't splat a
+    // runtime hash into named entries (no `%$h`-into-call-args form), so
+    // the adapter refuses the spread with BF101 rather than emit a broken
+    // render_child call. Mojo's EP `%= include` accepts a flat stash, so it
+    // lowers the same shape; this is a genuine engine divergence, pinned
+    // declaratively here.
+    'button': [{ code: 'BF101', severity: 'error' }],
+    // `kbd` auto-infers the same `<Slot>` `{...props}` spread as `button`
+    // above — refused with BF101 for the identical Kolon engine reason, not a
+    // render-mismatch (so it's pinned here, not in `skipJsx`).
+    'kbd': [{ code: 'BF101', severity: 'error' }],
+    // JS object literal in an attribute value (`style={{ … }}`) has no
+    // Kolon form — refused via the same gate as mojo (BF101).
+    'style-3-signals': [{ code: 'BF101', severity: 'error' }],
+    // Dynamic `style={{ … }}` object: the Xslate adapter cleanly refuses it
+    // with BF101 (no idiomatic Kolon form). mojo *skips* this fixture because
+    // its EP path emits invalid Perl silently — Xslate's build-time diagnostic
+    // is the stronger contract, so it's pinned here rather than skipped.
+    'style-object-dynamic': [{ code: 'BF101', severity: 'error' }],
+    // Tagged-template-literal call in a className — same family, same
+    // refusal (BF101).
+    'tagged-template-classname': [{ code: 'BF101', severity: 'error' }],
+    // NB: `.find` / `.findIndex` / `.findLast` / `.findLastIndex` are NOT
+    // pinned here — unlike mojo (which refuses them), Xslate lowers them to
+    // `$bf.find` / `find_index` / `find_last` / `find_last_index` via the same
+    // Kolon-lambda mechanism as `.filter` / `.every` / `.some`, so they render.
+  },
+  // Template-primitive registry parity: same V1 surface as mojo, so the
+  // same two cases stay skipped (bespoke user import + customSerialize
+  // can't render server-side without user-supplied helper mappings).
+  skipTemplatePrimitives: new Set([
+    TemplatePrimitiveCaseId.USER_IMPORT_VIA_CONST,
+    TemplatePrimitiveCaseId.NO_DOUBLE_REWRITE_OF_PROPS_OBJECT,
+  ]),
+  // Loop boundary markers for `@client` loops aren't emitted by the
+  // Xslate adapter yet (ported from mojo, which skips the same set).
+  skipMarkerConformance: new Set([
+    'client-only',
+    'client-only-loop-with-sibling-cond',
+    'todo-app',
+  ]),
+  onRenderError: (err, id) => {
+    if (err instanceof XslateNotAvailableError) {
+      console.log(`Skipping [${id}]: ${err.message}`)
+      return true
+    }
+    return false
+  },
+})

package/src/__tests__/xslate-spread-attrs.test.ts

@@ -0,0 +1,218 @@
+/**
+ * XslateAdapter — conditional-spread / nullish-omission / hyphenated-key
+ * regression tests (#textarea / #checkbox Phase 2b parity).
+ *
+ * Mirrors the Mojo adapter's same-named suites
+ * (`packages/adapter-mojolicious/src/__tests__/mojo-adapter.test.ts`), pinning
+ * the Kolon form of each ported shape. The shared adapter-conformance fixtures
+ * (`textarea`, `checkbox`) only exercise the falsy branch of the conditional
+ * spread and the unset branch of the optional attr, so these unit tests pin the
+ * truthy / present branches the fixtures can't reach.
+ */
+
+import { test, expect, describe } from 'bun:test'
+import { compileJSX } from '@barefootjs/jsx'
+import type { ComponentIR } from '@barefootjs/jsx'
+import { XslateAdapter } from '../adapter'
+
+function compileToIR(source: string, adapter?: XslateAdapter): ComponentIR {
+  const result = compileJSX(source.trimStart(), 'test.tsx', {
+    adapter: adapter ?? new XslateAdapter(),
+    outputIR: true,
+  })
+  const irFile = result.files.find(f => f.type === 'ir')
+  if (!irFile) throw new Error('No IR output')
+  return JSON.parse(irFile.content) as ComponentIR
+}
+
+function compileAndGenerate(source: string, adapter?: XslateAdapter) {
+  const a = adapter ?? new XslateAdapter()
+  const ir = compileToIR(source, a)
+  return a.generate(ir)
+}
+
+describe('XslateAdapter - conditional inline-object spread (textarea aria-describedby)', () => {
+  // `{...(cond ? { 'aria-describedby': cond } : {})}` lowers to a Kolon inline
+  // ternary of hashrefs so the falsy `{}` branch OMITS the key
+  // ($bf.spread_attrs does not emit empty entries). The shared fixture only
+  // exercises the falsy branch; this pins the truthy one.
+  test('emits a Kolon inline ternary of hashrefs through $bf.spread_attrs', () => {
+    const { template } = compileAndGenerate(`
+function Box({ describedBy }: { describedBy?: string }) {
+  return <div {...(describedBy ? { 'aria-describedby': describedBy } : {})} />
+}
+`)
+    expect(template).toContain(
+      "$bf.spread_attrs($describedBy ? { 'aria-describedby' => $describedBy } : {})",
+    )
+  })
+
+  test('resolves the value reference and preserves the static key for a second prop', () => {
+    const { template } = compileAndGenerate(`
+function Box({ label }: { label: string }) {
+  return <div {...(label ? { 'data-label': label } : {})} />
+}
+`)
+    expect(template).toContain(
+      "$bf.spread_attrs($label ? { 'data-label' => $label } : {})",
+    )
+  })
+
+  test('falls back to BF101 for a computed (non-static) object key', () => {
+    const adapter = new XslateAdapter()
+    const ir = compileToIR(`
+function Box({ k, v }: { k?: string; v?: string }) {
+  return <div {...(v ? { [k]: v } : {})} />
+}
+`, adapter)
+    adapter.generate(ir)
+    const errs = (adapter as unknown as { errors: { code: string }[] }).errors
+    expect(errs.some(e => e.code === 'BF101')).toBe(true)
+  })
+})
+
+describe('XslateAdapter - local-const conditional-spread resolution (#checkbox icon)', () => {
+  // A FUNCTION-scope const holding a `cond ? {…} : {}` ternary, spread as a bare
+  // identifier (`{...attrs}`), resolves through the same Kolon
+  // ternary-of-hashrefs lowering as the inline form. CheckIcon's
+  // `const sizeAttrs = size ? {…} : {}` is exactly this shape.
+  test('resolves a bare-identifier spread of a function-scope conditional const', () => {
+    const { template } = compileAndGenerate(`
+function Box({ flag }: { flag?: boolean }) {
+  const attrs = flag ? { 'data-on': 'yes' } : {}
+  return <div {...attrs} />
+}
+`)
+    expect(template).toContain(
+      "$bf.spread_attrs($flag ? { 'data-on' => 'yes' } : {})",
+    )
+  })
+
+  // A const that aliases another bare identifier must NOT be forwarded (loop
+  // guard): the resolver bails, so the spread falls through to the standard
+  // lowering emitting the bare `$attrs` variable.
+  test('does not forward a const that aliases another identifier (loop guard)', () => {
+    const { template } = compileAndGenerate(`
+function Box({ other }: { other?: object }) {
+  const attrs = other
+  return <div {...attrs} />
+}
+`)
+    expect(template).toContain('$bf.spread_attrs($attrs)')
+  })
+})
+
+describe('XslateAdapter - Record<staticKeys,scalar>[propKey] spread value (#checkbox icon)', () => {
+  // `const sizeMap: Record<IconSize, number> = { sm: 16, ... }` indexed by a
+  // prop inside a conditional-spread object value lowers to an inline indexed
+  // Kolon hashref `{ ... }[$key]` (bracket index — Kolon rejects Perl's
+  // `->{$key}` arrow-deref). This is CheckIcon's
+  // `{ width: sizeMap[size], height: sizeMap[size] }` shape.
+  test('lowers an indexed module-const map to an inline bracket-indexed hashref', () => {
+    const { template } = compileAndGenerate(`
+const sizeMap: Record<string, number> = { sm: 16, md: 20, lg: 24, xl: 32 }
+function Box({ size }: { size?: string }) {
+  const attrs = size ? { width: sizeMap[size] } : {}
+  return <div {...attrs} />
+}
+`)
+    expect(template).toContain(
+      "{ 'sm' => 16, 'md' => 20, 'lg' => 24, 'xl' => 32 }[$size]",
+    )
+    // Must NOT emit the Perl arrow-deref form (Kolon rejects it).
+    expect(template).not.toContain('->{$size}')
+  })
+
+  test('lowers string-valued record maps too', () => {
+    const { template } = compileAndGenerate(`
+const labelMap: Record<string, string> = { a: 'Alpha', b: 'Beta' }
+function Box({ k }: { k?: string }) {
+  const attrs = k ? { 'data-label': labelMap[k] } : {}
+  return <div {...attrs} />
+}
+`)
+    expect(template).toContain("{ 'a' => 'Alpha', 'b' => 'Beta' }[$k]")
+  })
+
+  // A non-scalar record value (object) is out of shape: the spread object value
+  // can't lower, so the whole spread falls back to BF101.
+  test('refuses a non-scalar record value with BF101 (out-of-shape fallback)', () => {
+    const adapter = new XslateAdapter()
+    const ir = compileToIR(`
+const sizeMap: Record<string, object> = { sm: { w: 1 } }
+function Box({ size }: { size?: string }) {
+  const attrs = size ? { width: sizeMap[size] } : {}
+  return <div {...attrs} />
+}
+`, adapter)
+    adapter.generate(ir)
+    const errs = (adapter as unknown as { errors: { code: string }[] }).errors
+    expect(errs.some(e => e.code === 'BF101')).toBe(true)
+  })
+})
+
+describe('XslateAdapter - props-object inherited-attribute enumeration (#checkbox)', () => {
+  // A SolidJS props-object component reads inherited attributes (`props.id`)
+  // not enumerated in `propsParams`. The bare optional attribute must be guarded
+  // with Kolon `defined` so it's omitted when unset (Hono parity), even though
+  // `id` isn't a declared param.
+  test('guards a props-object bare optional attr (props.id) with defined', () => {
+    const { template } = compileAndGenerate(`
+"use client"
+interface P { tone?: string }
+export function Widget(props: P) {
+  return <button id={props.id}>x</button>
+}
+`)
+    expect(template).toContain(': if (defined $id) {')
+    expect(template).toContain('id="<: $id :>"')
+  })
+})
+
+describe('XslateAdapter - hyphenated child attr hash key (#checkbox)', () => {
+  // A child component prop whose JSX name isn't a bare Kolon identifier
+  // (`<CheckIcon data-slot="..."/>`) must be quoted in the `render_child`
+  // hashref — an unquoted `data-slot => ...` parses as `data - slot`.
+  test('quotes a hyphenated child attribute name in render_child', () => {
+    const { template } = compileAndGenerate(`
+"use client"
+import { Leaf } from './leaf'
+export function Host() {
+  return <div><Leaf data-slot="indicator" size="sm" /></div>
+}
+`)
+    expect(template).toContain("'data-slot' => 'indicator'")
+    // A bare-identifier name stays unquoted.
+    expect(template).toContain('size => ')
+    expect(template).not.toContain('data-slot => ')
+  })
+})
+
+describe('XslateAdapter - nullish optional-attribute omission (textarea rows)', () => {
+  // A no-destructure-default, nillable-typed prop is `undef` when the caller
+  // omits it; guard its bare-reference attribute with Kolon `defined` so it
+  // DROPS instead of rendering `attr=""` — matching Hono's nullish-attribute
+  // omission. Concrete/defaulted props are never `undef` and stay
+  // unconditional.
+  test('guards a no-default nillable attr with a Kolon defined check', () => {
+    const { template } = compileAndGenerate(`
+function C({ rows }: { rows?: number }) {
+  return <textarea rows={rows} />
+}
+`)
+    expect(template).toContain(': if (defined $rows) {')
+    expect(template).toContain('rows="<: $rows :>"')
+  })
+
+  test('leaves a defaulted attr unconditional (scope did not widen)', () => {
+    const { template } = compileAndGenerate(`
+function C({ value = '' }: { value?: string }) {
+  return <textarea value={value} />
+}
+`)
+    // `value` has a destructure default → never undef → unconditional, exactly
+    // like Hono's value="".
+    expect(template).toContain('value="<: $value :>"')
+    expect(template).not.toContain('defined $value')
+  })
+})