@barefootjs/mojolicious 0.16.0 → 0.17.0

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,70 @@
+/**
+ * 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
+}
+
+/**
+ * True when every `$var` the lowered (Perl / Kolon) expression references is
+ * in the available set — i.e. the template already has that var in scope.
+ * Guards in-template memo seeding from referencing an out-of-scope binding
+ * (which would trip Perl strict mode). (#1297)
+ */
+export function referencedVarsAreAvailable(expr: string, available: ReadonlySet<string>): boolean {
+  for (const m of expr.matchAll(/\$([A-Za-z_]\w*)/g)) {
+    if (!available.has(m[1])) return false
+  }
+  return true
+}

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,126 @@
+/**
+ * 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,
+  extractArrowBodyExpression,
+  isSupported,
+  parseExpression,
+} from '@barefootjs/jsx'
+
+import type { MojoMemoContext } from '../emit-context.ts'
+import { referencedVarsAreAvailable } from '../lib/ir-scope.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'
+  )
+}
+
+/**
+ * Seed memos whose SSR default is `null` (not statically evaluable) by
+ * computing them in-template from the already-seeded prop / signal vars.
+ * Targets the prop-derived memo shape (`createMemo(() => props.value * 10)`)
+ * that the static `extractSsrDefaults` evaluator can't fold — without this
+ * the memo's `$x` renders empty (the reason `props-reactivity-comparison`
+ * was skipped). Only emitted when the lowered expression references vars the
+ * template already has in scope (props params + signals + prior memos), so a
+ * memo over an out-of-scope binding stays on the null path rather than
+ * tripping Perl strict mode. (#1297)
+ */
+export function generateDerivedMemoSeed(ctx: MojoMemoContext, ir: ComponentIR): string {
+  const memos = ir.metadata.memos ?? []
+  const signals = ir.metadata.signals ?? []
+  if (memos.length === 0 && signals.length === 0) return ''
+  // Props seed first; each signal/memo adds its own name as it lands so a
+  // later one can reference an earlier one.
+  const available = new Set<string>(ir.metadata.propsParams.map(p => p.name))
+  const lines: string[] = []
+
+  // Prop/signal-derived signals (`createSignal(props.defaultOn ?? false)`):
+  // a loop-child render receives no stash seed for the signal, so its `$on`
+  // would trip strict mode; and even when an entry render seeds it, the
+  // static default can't capture the per-call prop. Seed it in-template from
+  // the passed prop — but ONLY when the init lowers cleanly AND references an
+  // in-scope var (i.e. it's genuinely derived). Object/array/constant inits
+  // (`createSignal({…})`, `createSignal([…])`, `createSignal('b')`) keep the
+  // existing ssr-defaults seeding, so the spread / loop fixtures are
+  // untouched.
+  for (const signal of signals) {
+    const perl = tryLowerToPerl(ctx, signal.initialValue, available)
+    if (perl !== null) lines.push(`% my $${signal.getter} = ${perl};`)
+    available.add(signal.getter)
+  }
+
+  for (const memo of memos) {
+    // Seed every memo whose body lowers cleanly — not just the ones whose
+    // static SSR default is null. A statically-foldable prop-derived memo
+    // (`createMemo(() => props.disabled ?? false)` → default `false`)
+    // still depends on the per-call prop: the static stash seed bakes in
+    // the absent-prop fold, so a caller passing `disabled => 1` would
+    // render the default branch (#1897, select's disabled item). The
+    // in-template recomputation reads the prop lexical the stash already
+    // seeded, so it's correct per call; block-bodied arrows /
+    // out-of-scope references fall back to the static ssr-defaults seed.
+    const body = extractArrowBodyExpression(memo.computation)
+    if (body !== null) {
+      const perl = tryLowerToPerl(ctx, body, available)
+      if (perl !== null) lines.push(`% my $${memo.name} = ${perl};`)
+    }
+    available.add(memo.name)
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : ''
+}
+
+/**
+ * Lower a signal init / memo body to Perl for an in-template SSR seed, or
+ * `null` when it shouldn't be seeded this way. Returns null — without
+ * recording a BF101 — when the expression isn't a supported shape
+ * (`isSupported` pre-check, so object/array literals don't fail the build),
+ * when the lowering references no in-scope var (a constant — keep the
+ * existing ssr-defaults seeding), or when it references an out-of-scope
+ * binding. (#1297)
+ */
+export function tryLowerToPerl(
+  ctx: MojoMemoContext,
+  expr: string,
+  available: ReadonlySet<string>,
+): string | null {
+  const trimmed = expr.trim()
+  if (!trimmed) return null
+  if (!isSupported(parseExpression(trimmed)).supported) return null
+  const perl = ctx.convertExpressionToPerl(trimmed)
+  if (perl === '' || !/\$[A-Za-z_]\w*/.test(perl)) return null
+  return referencedVarsAreAvailable(perl, available) ? perl : null
+}