@barefootjs/xslate 0.8.0

package/lib/BarefootJS/Backend/Xslate.pm

@@ -0,0 +1,152 @@
+package BarefootJS::Backend::Xslate;
+our $VERSION = "0.01";
+use strict;
+use warnings;
+use utf8;
+use feature 'signatures';
+no warnings 'experimental::signatures';
+
+use Text::Xslate ();
+use JSON::PP ();
+
+# ---------------------------------------------------------------------------
+# Text::Xslate (Kolon) rendering backend for the BarefootJS runtime.
+# ---------------------------------------------------------------------------
+#
+# The engine-agnostic runtime logic — the JS-compat value helpers, array/string
+# methods, hydration markers, child rendering — lives in BarefootJS
+# (@barefootjs/perl). This backend supplies the four engine-specific operations
+# the runtime delegates to, targeting Text::Xslate's Kolon syntax:
+#
+#   encode_json($data)            -> JSON string (injectable encoder)
+#   mark_raw($str)                -> Text::Xslate raw value (no re-escaping)
+#   materialize($value)           -> resolve a captured-children value to a string
+#   render_named($name, $bf, \%v) -> render `<name>.tx` with `bf` + vars bound
+#
+# Pair it with the @barefootjs/xslate compile-time adapter, which emits Kolon
+# `.tx` templates that call the runtime as a `$bf` object: `<: $bf.scope_attr()
+# :>`, `<: $bf.json($x) :>`, `<: $bf.spread_attrs($bag) :>`. Kolon auto-escapes
+# `<: ... :>` interpolations (`type => 'html'`); helpers that emit markup return
+# `mark_raw` values (or the template adds `| mark_raw`), mirroring Mojo EP's
+# `<%==` vs `<%=` distinction.
+#
+# Unlike the Mojo backend, this has no dependency on a web framework: a plain
+# Text::Xslate instance renders templates from a path, so it runs under any
+# PSGI / Plack app (or none at all).
+
+sub new ($class, %args) {
+    my $json_encoder = $args{json_encoder} // do {
+        # Default pure-Perl encoder. `canonical` keeps key order deterministic
+        # (matching the runtime's sorted-key SSR policy); `allow_nonref` lets
+        # scalars / undef encode as `"x"` / `null`. Swap via `json_encoder`
+        # for a faster XS implementation.
+        my $j = JSON::PP->new->canonical->allow_nonref;
+        sub ($data) { return $j->encode($data) };
+    };
+
+    # Accept a pre-built Text::Xslate instance, or build one from `path`
+    # (a dir of `.tx` templates) plus any extra `xslate_options`.
+    my $xslate = $args{xslate};
+    unless ($xslate) {
+        $xslate = Text::Xslate->new(
+            syntax => 'Kolon',
+            type   => 'html',
+            ($args{path} ? (path => $args{path}) : ()),
+            %{ $args{xslate_options} // {} },
+        );
+    }
+
+    return bless { xslate => $xslate, json_encoder => $json_encoder }, $class;
+}
+
+sub xslate ($self) { return $self->{xslate} }
+
+sub encode_json ($self, $data) {
+    return $self->{json_encoder}->($data);
+}
+
+# Mark a string as already-safe so Kolon emits it verbatim (no auto-escape).
+sub mark_raw ($self, $str) {
+    return Text::Xslate::mark_raw($str);
+}
+
+# JSX children captured by the adapter (a Kolon macro call yields a rendered
+# string; some paths may pass a CODE ref) resolve to a string here.
+sub materialize ($self, $value) {
+    return ref($value) eq 'CODE' ? $value->() : $value;
+}
+
+# Render `<name>.tx` with `$child_bf` bound as the `bf` object for the nested
+# render, plus the supplied template vars. No stash juggling is needed: Kolon
+# resolves `$bf` from the per-render vars, so each child render gets its own
+# instance directly.
+sub render_named ($self, $template_name, $child_bf, $vars) {
+    return $self->{xslate}->render("$template_name.tx", { %$vars, bf => $child_bf });
+}
+
+1;
+__END__
+
+=encoding utf8
+
+=head1 NAME
+
+BarefootJS::Backend::Xslate - Text::Xslate (Kolon) rendering backend for BarefootJS
+
+=head1 SYNOPSIS
+
+    use BarefootJS;
+    use BarefootJS::Backend::Xslate;
+
+    my $backend = BarefootJS::Backend::Xslate->new(path => ['templates']);
+    my $bf = BarefootJS->new(undef, { backend => $backend });
+
+    # Renders templates/counter.tx, binding the runtime as the `bf` object.
+    my $html = $backend->render_named('counter', $bf, { count => 0 });
+
+=head1 DESCRIPTION
+
+A rendering backend that lets the engine-agnostic L<BarefootJS> runtime render
+its marked templates with L<Text::Xslate> (Kolon syntax). Because it has no
+dependency on a web framework, a plain Text::Xslate instance renders templates
+from a path, so it runs under any PSGI / Plack application (or none at all).
+
+Pair it with the C<@barefootjs/xslate> compile-time adapter, which emits Kolon
+C<.tx> templates that call the runtime as a C<bf> object — C<< <: $bf.scope_attr()
+:> >>, C<< <: $bf.json($x) :> >>, C<< <: $bf.spread_attrs($h) :> >>. Kolon
+auto-escapes C<< <: ... :> >> interpolations (the backend builds Text::Xslate
+with C<< type => 'html' >>); helpers that emit markup return C<mark_raw> values,
+mirroring Mojo EP's C<< <%== >> versus C<< <%= >>.
+
+=head1 METHODS
+
+=head2 new(%args)
+
+Constructs a backend. Accepts a pre-built C<xslate> instance, or a C<path>
+(arrayref of template directories) plus optional C<xslate_options> to build a
+Kolon, html-escaping Text::Xslate. C<json_encoder> overrides the default
+canonical L<JSON::PP> encoder.
+
+=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
+C<Text::Xslate::mark_raw>; C<render_named> renders C<< <name>.tx >> with C<$bf>
+bound as the C<bf> variable plus C<\%vars>.
+
+=head1 SEE ALSO
+
+L<BarefootJS>, L<Text::Xslate>, L<Plack>,
+L<https://github.com/piconic-ai/barefootjs>
+
+=head1 AUTHOR
+
+kobaken E<lt>kentafly88@gmail.comE<gt>
+
+=head1 LICENSE
+
+Copyright (c) 2025-present BarefootJS Contributors.
+
+This library is free software; you can redistribute it and/or modify it under
+the MIT License. See the F<LICENSE> file in the distribution for the full text.
+
+=cut

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@barefootjs/xslate",
+  "version": "0.8.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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapter": {
+      "types": "./src/adapter/index.ts",
+      "import": "./src/adapter/index.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"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "lib",
+    "README.md"
+  ],
+  "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:types": "tsgo --emitDeclarationOnly --outDir ./dist",
+    "test": "bun test",
+    "clean": "rm -rf dist",
+    "prepack": "node ../../scripts/swap-publish-config.mjs pack",
+    "postpack": "node ../../scripts/swap-publish-config.mjs unpack"
+  },
+  "keywords": [
+    "xslate",
+    "text-xslate",
+    "kolon",
+    "perl",
+    "plack",
+    "psgi",
+    "barefoot",
+    "ssr"
+  ],
+  "author": "kobaken <kentafly88@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/piconic-ai/barefootjs",
+    "directory": "packages/adapter-xslate"
+  },
+  "dependencies": {
+    "@barefootjs/perl": "0.8.0",
+    "@barefootjs/shared": "0.8.0"
+  },
+  "peerDependencies": {
+    "@barefootjs/jsx": ">=0.2.0"
+  },
+  "devDependencies": {
+    "@barefootjs/adapter-tests": "0.1.0",
+    "@barefootjs/jsx": "0.8.0",
+    "typescript": "^5.0.0"
+  }
+}

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

@@ -0,0 +1,142 @@
+import { test, expect } from 'bun:test'
+import { compileJSX } from '@barefootjs/jsx'
+import { XslateAdapter } from '../adapter'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+const COUNTER_SRC = `"use client"
+import { createSignal } from '@barefootjs/client'
+export function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = createSignal(initial)
+  const doubled = () => count() * 2
+  return (
+    <div class="counter">
+      <p>count: {count()}</p>
+      <p>doubled: {doubled()}</p>
+      <button onClick={() => setCount(n => n + 1)}>+1</button>
+    </div>
+  )
+}`
+
+const PERL_CORE_LIB = resolve(import.meta.dir, '../../../adapter-perl/lib')
+const XSLATE_LIB = resolve(import.meta.dir, '../../lib')
+
+let _perlAvailable: boolean | null = null
+async function isPerlXslateAvailable(): Promise<boolean> {
+  if (_perlAvailable !== null) return _perlAvailable
+  try {
+    const proc = Bun.spawn(['perl', '-MText::Xslate', '-e', 'print $Text::Xslate::VERSION'], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    await proc.exited
+    _perlAvailable = proc.exitCode === 0
+  } catch {
+    _perlAvailable = false
+  }
+  return _perlAvailable
+}
+
+test('Counter compiles to a Kolon .tx template', () => {
+  const result = compileJSX(COUNTER_SRC, 'Counter.tsx', {
+    adapter: new XslateAdapter(),
+    outputIR: true,
+  })
+  const errors = result.errors.filter(e => e.severity === 'error')
+  expect(errors).toEqual([])
+
+  const tpl = result.files.find(f => f.type === 'markedTemplate')
+  expect(tpl).toBeDefined()
+  const content = tpl!.content
+  // Script registration as silent Kolon line statements (bound to a throwaway
+  // `my` so the call's return value isn't printed into the HTML).
+  expect(content).toContain(`$bf.register_script('/static/components/barefoot.js')`)
+  expect(content).toContain(`$bf.register_script('/static/components/Counter.client.js')`)
+  // Hydration markers
+  expect(content).toContain(`bf-s="<: $bf.scope_attr() :>"`)
+  expect(content).toContain(`<: $bf.hydration_attrs() | mark_raw :>`)
+  expect(content).toContain(`<: $bf.props_attr() | mark_raw :>`)
+  // Text slots
+  expect(content).toContain(`<: $bf.text_start("s0") | mark_raw :><: $count :><: $bf.text_end() | mark_raw :>`)
+  expect(content).toContain(`<: $bf.text_start("s2") | mark_raw :><: $doubled :><: $bf.text_end() | mark_raw :>`)
+  // Button stays a plain element (onClick is client-only)
+  expect(content).toContain(`+1</button>`)
+})
+
+test('Counter renders through real Text::Xslate', async () => {
+  if (!(await isPerlXslateAvailable())) {
+    console.warn('perl with Text::Xslate not available — skipping render test')
+    return
+  }
+
+  const result = compileJSX(COUNTER_SRC, 'Counter.tsx', {
+    adapter: new XslateAdapter(),
+    outputIR: true,
+  })
+  const errors = result.errors.filter(e => e.severity === 'error')
+  expect(errors).toEqual([])
+  const tpl = result.files.find(f => f.type === 'markedTemplate')!
+
+  const dir = await mkdtemp(join(tmpdir(), 'xslate-counter-'))
+  try {
+    // Template file named `counter.tx` (snake_case of Counter).
+    await writeFile(join(dir, 'counter.tx'), tpl.content)
+
+    const renderScript = `#!/usr/bin/env perl
+use strict;
+use warnings;
+use utf8;
+use lib '${XSLATE_LIB}', '${PERL_CORE_LIB}';
+use BarefootJS;
+use BarefootJS::Backend::Xslate;
+
+my $backend = BarefootJS::Backend::Xslate->new(path => ['${dir}']);
+my $bf = BarefootJS->new(undef, { backend => $backend });
+$bf->_scope_id('Counter_test');
+
+binmode(STDOUT, ':utf8');
+my \$html = \$backend->render_named('counter', \$bf, { count => 3, doubled => 6 });
+print \$html;
+# The template's register_script calls populated \$bf's script list during
+# render; emit the resulting <script> tags so the test can assert them.
+print "\\n";
+print \$bf->scripts;
+`
+    const scriptPath = join(dir, 'render.pl')
+    await writeFile(scriptPath, renderScript)
+
+    const proc = Bun.spawn(['perl', scriptPath], {
+      cwd: dir,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ])
+    const exitCode = await proc.exited
+    if (exitCode !== 0) {
+      throw new Error(`perl render failed (exit ${exitCode}):\n${stderr}\n--- template ---\n${tpl.content}`)
+    }
+
+    const html = stdout
+    console.log('=== RENDERED HTML ===')
+    console.log(html)
+
+    // Scope marker
+    expect(html).toContain('bf-s="Counter_test"')
+    // Text slots with comment markers and values
+    expect(html).toMatch(/count: <!--bf:s0-->3<!--\/-->/)
+    expect(html).toMatch(/doubled: <!--bf:s2-->6<!--\/-->/)
+    // Plain button (no handler at SSR)
+    expect(html).toMatch(/<button[^>]*>\+1<\/button>/)
+    // No leaked register_script return values before the root element.
+    expect(html).toMatch(/^\s*<div class="counter"/)
+    // Registered client JS surfaces as <script> tags via $bf->scripts.
+    expect(html).toContain('<script type="module" src="/static/components/barefoot.js"></script>')
+    expect(html).toContain('<script type="module" src="/static/components/Counter.client.js"></script>')
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {})
+  }
+})

package/src/adapter/boolean-result.ts

@@ -0,0 +1,126 @@
+/**
+ * Structural classifier for JS expressions whose result is a boolean
+ * value (or unambiguously stringifies to "true"/"false" in JS).
+ *
+ * Used by the Mojo adapter's `emitExpression` to decide whether to
+ * route a reactive attribute binding through the `bf->bool_str` Perl
+ * runtime helper (#1466 follow-up). Perl has no native boolean type;
+ * `($count > 0)` evaluates to `''` / `1`, not `"false"` / `"true"`,
+ * so the literal stringification diverges from Hono / Go. Wrapping
+ * the value with `bool_str` realigns the serialised attribute with
+ * JS `String(boolean)` semantics.
+ *
+ * The classifier walks a `ParsedExpr` produced by
+ * `@barefootjs/jsx::parseExpression` — same AST the filter / loop
+ * lowerings already use — so detection is structural rather than
+ * regex-text-matching. Wrapped expression text is left to the
+ * caller's existing `convertExpressionToPerl` pipeline; this module
+ * only decides whether to wrap.
+ *
+ * Detected shapes:
+ *   - `binary` with a comparison operator (`<`, `>`, `<=`, `>=`,
+ *     `==`, `===`, `!=`, `!==`)
+ *   - `unary` with logical `!`
+ *   - `literal` with `literalType: 'boolean'`
+ *   - `logical` (`&&` / `||` / `??`) when both sides are themselves
+ *     boolean-result (catches `x > 0 && y < 10`; intentionally does
+ *     NOT catch `x() || 'fallback'` whose right side stringifies as
+ *     a regular value)
+ *   - `conditional` (`?:`) when both branches are themselves
+ *     boolean-result
+ *
+ * Anything else returns `false` — including bare identifiers
+ * (`accepted`) and call expressions (`accepted()`) whose return type
+ * the adapter has no way to infer from source text alone. Those
+ * carry their own (Perl-coerced) value through unchanged, which
+ * stays correct for non-boolean shapes and is handled by
+ * `normalizeHTML`'s `aria-*="0"` rule for the specific Mojo-Perl
+ * `aria-*={booleanFn()}` divergence.
+ */
+
+import { parseExpression, type ParsedExpr } from '@barefootjs/jsx'
+
+const COMPARISON_OPS = new Set([
+  '<',
+  '>',
+  '<=',
+  '>=',
+  '==',
+  '===',
+  '!=',
+  '!==',
+])
+
+function isBooleanResultParsed(node: ParsedExpr): boolean {
+  switch (node.kind) {
+    case 'literal':
+      return node.literalType === 'boolean'
+    case 'binary':
+      return COMPARISON_OPS.has(node.op)
+    case 'unary':
+      return node.op === '!'
+    case 'logical':
+      // `x > 0 && y < 10` is boolean; `x() || 'fallback'` is not.
+      // Only both-sides-boolean qualifies.
+      return (
+        isBooleanResultParsed(node.left) && isBooleanResultParsed(node.right)
+      )
+    case 'conditional':
+      // `cond ? bool : bool` is boolean; `cond ? 'a' : 'b'` is not.
+      return (
+        isBooleanResultParsed(node.consequent) &&
+        isBooleanResultParsed(node.alternate)
+      )
+    default:
+      return false
+  }
+}
+
+export function isBooleanResultExpr(expr: string): boolean {
+  const parsed = parseExpression(expr.trim())
+  if (!parsed) return false
+  return isBooleanResultParsed(parsed)
+}
+
+/**
+ * ARIA attributes whose spec values are `"true"`, `"false"`, and (for
+ * tri-state members) `"mixed"`. When a fixture binds one of these to
+ * an arbitrary JS expression (`aria-checked={accepted()}`), the
+ * expression's actual type isn't recoverable from source text — but
+ * the attribute name itself witnesses that the binding is
+ * boolean-shaped. Routing these through `bf->bool_str` produces the
+ * spec-canonical `"true"` / `"false"` even when the expression is
+ * opaque, eliminating the Mojo-only `aria-*="0"` divergence at the
+ * source rather than papering it over in `normalizeHTML`.
+ *
+ * Deliberately conservative — only includes ARIA attributes whose
+ * spec value set is exactly `true | false` or `true | false | mixed`.
+ * Tokenised ARIA attributes (`aria-current` is `page | step | …`,
+ * `aria-sort` is `ascending | descending | …`) are intentionally
+ * excluded so a string-valued binding doesn't get coerced to
+ * `"true"` / `"false"`.
+ */
+const ARIA_BOOLEAN_ATTRS = new Set([
+  // Strict boolean state (true | false; some allow `undefined` =
+  // attribute absent, which the runtime emits as no-attr regardless).
+  'aria-atomic',
+  'aria-busy',
+  'aria-disabled',
+  'aria-hidden',
+  'aria-modal',
+  'aria-multiline',
+  'aria-multiselectable',
+  'aria-readonly',
+  'aria-required',
+  // Tri-state (true | false | mixed). The `bool_str` helper only
+  // maps Perl truthy / falsy to true / false — a fixture that wants
+  // the literal `"mixed"` would bind a string-valued JSX attr
+  // (`aria-checked="mixed"`), which lowers through the `literal` emit
+  // path and never touches this code.
+  'aria-checked',
+  'aria-pressed',
+])
+
+export function isAriaBooleanAttr(name: string): boolean {
+  return ARIA_BOOLEAN_ATTRS.has(name)
+}

package/src/adapter/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Text::Xslate (Kolon) Template Adapter Exports
+ */
+
+export { XslateAdapter, xslateAdapter } from './xslate-adapter'
+export type { XslateAdapterOptions } from './xslate-adapter'