@barefootjs/mojolicious 0.16.0 → 0.17.1

package/src/adapter/expr/operand.ts

@@ -0,0 +1,55 @@
+/**
+ * Operand-type classification + index-access lowering for the Mojolicious
+ * EP template adapter.
+ *
+ * Extracted from `mojo-adapter.ts` (domain-module refactor, issue #2018
+ * track D). Pure functions over `ParsedExpr` — they take an `isStringName`
+ * predicate (supplied by the emitter from adapter state) rather than reading
+ * adapter instance state directly.
+ *
+ * SHARED CANDIDATE: `isStringTypedOperand` is byte-identical to the Xslate
+ * adapter's copy and is adapter-agnostic — an extraction candidate for a
+ * shared Perl-family codegen module (groundwork for the future Perl evaluator
+ * integration, issue #2018 track D). `emitIndexAccessPerl` stays Mojo-specific
+ * (Perl's `->[]` vs `->{}` split has no Kolon equivalent).
+ */
+
+import type { ParsedExpr } from '@barefootjs/jsx'
+
+/**
+ * Whether a comparison operand is string-typed, so JS `===`/`!==` against it
+ * must lower to Perl `eq`/`ne` instead of numeric `==`/`!=` (#1672). Covers a
+ * string literal, a string-signal getter call (`sel()`), and a string prop
+ * access (`props.x`). `isStringName` reports whether a getter/prop name is
+ * known-string. Loop-element fields (`t.id`) on untyped arrays have no known
+ * type and stay undetected — a separate, narrower gap.
+ */
+export function isStringTypedOperand(expr: ParsedExpr, isStringName: (n: string) => boolean): boolean {
+  if (expr.kind === 'literal' && expr.literalType === 'string') return true
+  if (expr.kind === 'call' && expr.callee.kind === 'identifier' && expr.args.length === 0) {
+    return isStringName(expr.callee.name)
+  }
+  if (expr.kind === 'member' && expr.object.kind === 'identifier' && expr.object.name === 'props') {
+    return isStringName(expr.property)
+  }
+  return false
+}
+
+/**
+ * Lower `arr[index]` to a Perl deref. Perl distinguishes array
+ * (`->[$i]`) from hash (`->{$k}`) access, which JS's single `[]` does
+ * not — so we pick by the index expression's type: a string-typed key
+ * derefs the hash, anything else (the common loop-index / arithmetic
+ * case, e.g. `selected()[index]`) derefs the array. #1897.
+ */
+export function emitIndexAccessPerl(
+  object: ParsedExpr,
+  index: ParsedExpr,
+  emit: (e: ParsedExpr) => string,
+  isStringName: (n: string) => boolean,
+): string {
+  const i = emit(index)
+  return isStringTypedOperand(index, isStringName)
+    ? `${emit(object)}->{${i}}`
+    : `${emit(object)}->[${i}]`
+}

package/src/adapter/lib/constants.ts

@@ -0,0 +1,39 @@
+/**
+ * Compile-time constant tables for the Mojolicious EP template adapter.
+ *
+ * Extracted from `mojo-adapter.ts` (domain-module refactor, issue #2018
+ * track D).
+ */
+
+import type { PrimitiveSpec } from './types.ts'
+
+/**
+ * Single source of truth for the Mojolicious adapter's
+ * template-primitive surface. Each entry pairs the expected arity
+ * with the emit function. Adding / removing a primitive is a
+ * one-line change.
+ *
+ * The emit fn returns a Perl expression (no surrounding `<%= %>`)
+ * suitable for embedding inside the Mojo template action —
+ * `bf->json($val)`, `bf->floor($val)`, etc. Args arrive already
+ * Perl-rendered via `convertExpressionToPerl` recursion, so a
+ * caller passing `props.config` reaches the emit fn as `$config`.
+ */
+export const MOJO_TEMPLATE_PRIMITIVES: Record<string, PrimitiveSpec> = {
+  'JSON.stringify': { arity: 1, emit: (args) => `bf->json(${args[0]})` },
+  'String':         { arity: 1, emit: (args) => `bf->string(${args[0]})` },
+  'Number':         { arity: 1, emit: (args) => `bf->number(${args[0]})` },
+  'Math.floor':     { arity: 1, emit: (args) => `bf->floor(${args[0]})` },
+  'Math.ceil':      { arity: 1, emit: (args) => `bf->ceil(${args[0]})` },
+  'Math.round':     { arity: 1, emit: (args) => `bf->round(${args[0]})` },
+}
+
+/**
+ * Module-scope `templatePrimitives` map derived once from the spec
+ * record. Per-instance derivation would re-build the same Map on
+ * every `new MojoAdapter()` call.
+ */
+export const MOJO_PRIMITIVE_EMIT_MAP: Record<string, (args: string[]) => string> =
+  Object.fromEntries(
+    Object.entries(MOJO_TEMPLATE_PRIMITIVES).map(([k, v]) => [k, v.emit])
+  )

package/src/adapter/lib/ir-scope.ts

@@ -0,0 +1,57 @@
+/**
+ * IR traversal helpers for the Mojolicious EP template adapter.
+ *
+ * Extracted from `mojo-adapter.ts` (domain-module refactor, issue #2018
+ * track D). Pure functions over the IR tree — no adapter instance state.
+ *
+ * SHARED CANDIDATE: the bodies here are byte-identical to the Xslate
+ * adapter's `lib/ir-scope.ts`. They are adapter-agnostic (no Perl/Kolon
+ * specifics), so they are the obvious first extraction into a shared
+ * Perl-family codegen module once one exists — the groundwork for the
+ * future Perl evaluator integration (issue #2018 track D). Kept per-adapter
+ * for now, matching the repo convention (the Go adapter keeps its own copy).
+ */
+
+import type { IRNode, IRProp, IRIfStatement, IRFragment } from '@barefootjs/jsx'
+
+/**
+ * Find the `children` prop's `jsx-children` payload (#1326). Narrowed
+ * via the AttrValue `kind` discriminator so adapter code stays type-
+ * safe if the IR shape evolves — adding a new AttrValue variant or
+ * renaming `children` to `jsxChildren` becomes a TS compile error
+ * here instead of silently dropping the children at runtime.
+ */
+export function resolveJsxChildrenProp(props: readonly IRProp[]): IRNode[] {
+  const prop = props.find(p => p.name === 'children')
+  if (!prop) return []
+  if (prop.value.kind !== 'jsx-children') return []
+  return prop.value.children
+}
+
+/**
+ * Collect the component's root scope element node(s) — the elements that
+ * become the rendered root and so carry `data-key` for a keyed loop item. A
+ * plain element root is itself; an `if-statement` (early-return) root
+ * contributes the top element of each branch (`consequent` + the `alternate`
+ * chain), since exactly one branch renders at runtime. Non-element branch
+ * tops (fragments / nested shapes) are walked one level so an
+ * `if (…) return <A/>` still resolves to `<A>`. (#1297)
+ */
+export function collectRootScopeNodes(node: IRNode): Set<IRNode> {
+  const out = new Set<IRNode>()
+  const visit = (n: IRNode | null): void => {
+    if (!n) return
+    if (n.type === 'element') { out.add(n); return }
+    if (n.type === 'if-statement') {
+      const s = n as IRIfStatement
+      visit(s.consequent)
+      visit(s.alternate)
+      return
+    }
+    if (n.type === 'fragment') {
+      for (const c of (n as IRFragment).children) visit(c)
+    }
+  }
+  visit(node)
+  return out
+}

package/src/adapter/lib/perl-naming.ts

@@ -0,0 +1,36 @@
+/**
+ * Perl identifier / hash-key conventions for the Mojolicious EP adapter.
+ *
+ * Pure helpers extracted from `mojo-adapter.ts` (domain-module refactor,
+ * issue #2018 track D): none read adapter instance state, so they live at
+ * module scope as the single source of truth for Perl-identifier quoting
+ * and marker-id encoding.
+ */
+
+/**
+ * (#checkbox) Quote a `render_child` named-arg / hashref key when it isn't a
+ * bare Perl identifier. A JSX attribute name like `data-slot` would otherwise
+ * emit `data-slot => '...'`, which Perl parses as the subtraction
+ * `data - slot`. Identifier-safe names (`className`, `size`, `_bf_slot`) pass
+ * through unquoted to keep the generated template readable.
+ */
+export function perlHashKey(name: string): string {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : `'${name.replace(/'/g, "\\'")}'`
+}
+
+/**
+ * Encode an `IRLoop.markerId` into a Perl-identifier-safe suffix
+ * for the `bf_iter_…` hoist var. Collision-free for marker ids
+ * that differ in any character — `-` and `_` map to distinct
+ * encodings (`_x2d` vs `__`) so `l-0` and `l_0` stay distinct.
+ *
+ * Today the IR only emits `l<digits>` so the encoding is mostly
+ * an identity, but pinning collision-freeness up front avoids a
+ * silent variable-shadow bug if a future marker generator widens
+ * the alphabet.
+ */
+export function perlIdentifierFromMarkerId(markerId: string): string {
+  return markerId.replace(/[^a-zA-Z0-9]/g, (ch) =>
+    ch === '_' ? '__' : `_x${ch.charCodeAt(0).toString(16)}`
+  )
+}

package/src/adapter/lib/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared type aliases for the Mojolicious EP template adapter.
+ *
+ * Extracted from `mojo-adapter.ts` (domain-module refactor, issue #2018
+ * track D). Pure type declarations — no runtime behaviour — so the
+ * extracted emit modules and the main adapter share one definition
+ * rather than re-declaring the render context / options shape.
+ */
+
+/** A template-primitive spec: expected call arity + the emit fn. */
+export interface PrimitiveSpec {
+  arity: number
+  emit: (args: string[]) => string
+}
+
+/**
+ * Mojo adapter's IRNode render context. Mojo's lowering currently
+ * doesn't consume any render-position flags (`isRootOfClientComponent`
+ * is handled differently here than in Hono/Go), so the Ctx is empty.
+ * Kept as a named alias so future flags can extend it without changing
+ * the `IRNodeEmitter` interface.
+ */
+export type MojoRenderCtx = Record<string, never>
+
+export interface MojoAdapterOptions {
+  /** Base path for client JS files (default: '/static/components/') */
+  clientJsBasePath?: string
+
+  /** Path to barefoot.js runtime (default: '/static/components/barefoot.js') */
+  barefootJsPath?: string
+}

package/src/adapter/memo/seed.ts

@@ -0,0 +1,73 @@
+/**
+ * In-template memo / context seeding for the Mojolicious EP template adapter.
+ *
+ * Extracted from `mojo-adapter.ts` (domain-module refactor, issue #2018
+ * track D). Free functions taking a `MojoMemoContext` (built by the adapter's
+ * `memoCtx` getter) so the cluster depends only on the recursive expression entry, not
+ * the whole adapter class. These emit the `% my $x = ...;` seed lines that let
+ * the template body's bare `$x` resolve to a derived signal/memo value or an
+ * active context value at SSR time. Mirror of the Go adapter's `memo/*`.
+ */
+
+import {
+  type ComponentIR,
+  type ContextConsumer,
+  collectContextConsumers,
+  computeSsrSeedPlan,
+} from '@barefootjs/jsx'
+
+import type { MojoMemoContext } from '../emit-context.ts'
+
+/** Perl literal for a context-consumer's `createContext` default. */
+export function contextDefaultPerl(c: ContextConsumer): string {
+  const d = c.defaultValue
+  if (d === null || d === undefined) return 'undef'
+  if (typeof d === 'string') return `'${d.replace(/[\\']/g, m => `\\${m}`)}'`
+  if (typeof d === 'boolean') return d ? '1' : '0'
+  return String(d)
+}
+
+/**
+ * Emit one `% my $<local> = bf->use_context(...)` seed line per context
+ * consumer so the template body's bare `$<local>` resolves to the active
+ * provider value (or the `createContext` default). (#1297)
+ */
+export function generateContextConsumerSeed(ir: ComponentIR): string {
+  const consumers = collectContextConsumers(ir.metadata)
+  if (consumers.length === 0) return ''
+  return (
+    consumers
+      .map(
+        c =>
+          `% my $${c.localName} = bf->use_context('${c.contextName}', ${contextDefaultPerl(c)});`,
+      )
+      .join('\n') + '\n'
+  )
+}
+
+/**
+ * Emit `% my $<name> = <perl>;` seed lines for every `derived` step of the
+ * backend-neutral SSR seed plan — the scope/availability/ordering analysis
+ * lives in `computeSsrSeedPlan` (packages/jsx/src/ssr-seed-plan.ts); this
+ * only lowers each step's expression to Perl and applies the two
+ * backend-specific emit guards: skip an empty lowering, and skip a lowering
+ * that references no `$var` at all (a constant init/body — e.g. a `derived`
+ * step with empty `frees` — keeps the existing static ssr-defaults seed
+ * instead). `env-reader` and `opaque` steps emit nothing (the runtime
+ * supplies the reader, or the adapter's ssr-defaults path already covers it).
+ * (#1297, #2075)
+ */
+export function generateDerivedMemoSeed(ctx: MojoMemoContext, ir: ComponentIR): string {
+  // Package G attached this to metadata at compile time; the `??` fallback
+  // only covers hand-built metadata in older tests that predate the attached
+  // plan — same shared function, so there's no divergence from the compiler.
+  const plan = ir.metadata.ssrSeedPlan ?? computeSsrSeedPlan(ir.metadata)
+  const lines: string[] = []
+  for (const step of plan.steps) {
+    if (step.kind !== 'derived') continue
+    const perl = ctx.convertExpressionToPerl(step.expr, step.parsed)
+    if (perl === '' || !/\$[A-Za-z_]\w*/.test(perl)) continue
+    lines.push(`% my $${step.name} = ${perl};`)
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : ''
+}