@barefootjs/xslate 0.16.0 → 0.17.1

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

@@ -0,0 +1,27 @@
+/**
+ * Kolon identifier / hash-key conventions for the Text::Xslate adapter.
+ *
+ * Pure helpers extracted from `xslate-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 Kolon-literal escaping and
+ * hashref-key quoting.
+ */
+
+/**
+ * Escape a string for a Kolon/Perl single-quoted literal: backslash first
+ * (so it doesn't double-escape the quote we add next), then the quote. Used
+ * by every `'…'` hashref key/value emitter.
+ */
+export function escapeKolonSingleQuoted(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+}
+
+/**
+ * Quote a hashref KEY for Kolon when it isn't a bare-identifier-safe name.
+ * Kolon parses `data-slot` as `data - slot` (subtraction) and faults on the
+ * undefined `data` symbol, so a hyphenated key (`data-slot`, `aria-label`)
+ * must be single-quoted: `'data-slot'`. Bare identifiers pass through unquoted.
+ */
+export function kolonHashKey(name: string): string {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : `'${escapeKolonSingleQuoted(name)}'`
+}

package/src/adapter/lib/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared type aliases for the Text::Xslate (Kolon) template adapter.
+ *
+ * Extracted from `xslate-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
+}
+
+/**
+ * Xslate adapter's IRNode render context. Like the Mojo adapter, Kolon's
+ * lowering doesn't consume any render-position flags, so the Ctx is empty.
+ * Kept as a named alias so future flags can extend it without changing the
+ * `IRNodeEmitter` interface.
+ */
+export type XslateRenderCtx = Record<string, never>
+
+export interface XslateAdapterOptions {
+  /** 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,78 @@
+/**
+ * In-template memo / context seeding for the Text::Xslate template adapter.
+ *
+ * Extracted from `xslate-adapter.ts` (domain-module refactor, issue #2018
+ * track D). Free functions taking a `XslateMemoContext` (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 = ...;` line-statements
+ * that let the body's bare `$x` resolve to a derived signal/memo value or an
+ * active context value at SSR time. Mirror of the Go / Mojo adapter's `memo/*`.
+ */
+
+import {
+  type ComponentIR,
+  type ContextConsumer,
+  collectContextConsumers,
+  computeSsrSeedPlan,
+} from '@barefootjs/jsx'
+
+import type { XslateMemoContext } from '../emit-context.ts'
+
+/** Kolon literal for a context-consumer's `createContext` default. */
+export function contextDefaultKolon(c: ContextConsumer): string {
+  const d = c.defaultValue
+  if (d === null || d === undefined) return 'nil'
+  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(...)` line-statement per
+ * context consumer so the 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}', ${contextDefaultKolon(c)});`,
+      )
+      .join('\n') + '\n'
+  )
+}
+
+/**
+ * Emit `: my $<name> = <kolon>;` line-statements 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 Kolon and applies the
+ * backend-specific emit guards: skip an empty lowering, 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),
+ * and skip a self-referencing lowering (Kolon's `my` shadows the RHS, so
+ * `: my $x = … $x …` would read the just-declared undefined lexical rather
+ * than the render var — the plan rules out SOURCE-level self-refs, but a
+ * lowered canonical name could still collide, so this stays as the cheap
+ * defense it always was). `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: XslateMemoContext, 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 kolon = ctx.convertExpressionToKolon(step.expr, step.parsed)
+    if (kolon === '' || !/\$[A-Za-z_]\w*/.test(kolon)) continue
+    if (new RegExp(`\\$${step.name}\\b`).test(kolon)) continue
+    lines.push(`: my $${step.name} = ${kolon};`)
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : ''
+}

package/src/adapter/props/prop-classes.ts

@@ -0,0 +1,64 @@
+/**
+ * Prop classification for the Text::Xslate (Kolon) template adapter.
+ *
+ * Extracted from `xslate-adapter.ts` (domain-module refactor, issue #2018
+ * track D). Pure functions over `ir.metadata` that derive the per-compile
+ * prop/name sets the adapter consults during lowering. Mirror of the Go
+ * adapter's `props/prop-types.ts`. No adapter instance state.
+ */
+
+import type { ComponentIR } from '@barefootjs/jsx'
+import { isStringTypeInfo, isBareStringLiteral } from '../value/parsed-literal.ts'
+
+/**
+ * Props whose declared TS type is boolean — a bare binding of one
+ * (`data-active={props.isActive}`) must stringify as JS `String(boolean)`
+ * ("true"/"false"), not Perl's native `1`/`''` (#1897, pagination's
+ * data-active).
+ */
+export function collectBooleanTypedProps(ir: ComponentIR): Set<string> {
+  return new Set(
+    ir.metadata.propsParams
+      .filter(prop => prop.type?.primitive === 'boolean' || prop.type?.raw === 'boolean')
+      .map(prop => prop.name),
+  )
+}
+
+/**
+ * Bare references to optional, no-default, non-primitive props (e.g.
+ * textarea's `rows`) are `undef` when omitted → `defined`-guarded in
+ * `emitExpression`. See the `nullableOptionalProps` field docstring.
+ */
+export function collectNullableOptionalProps(ir: ComponentIR): Set<string> {
+  return new Set(
+    ir.metadata.propsParams
+      .filter(
+        p =>
+          p.defaultValue === undefined &&
+          !p.isRest &&
+          p.type?.kind !== 'primitive',
+      )
+      .map(p => p.name),
+  )
+}
+
+/**
+ * String-typed signals and props. A signal is string-typed when its inferred
+ * type is `string` (or, defensively, when its initial value is a bare string
+ * literal); a prop when its annotated type is `string`. In the Mojo adapter
+ * this drives `eq`/`ne` selection for string equality; the Kolon emitters
+ * don't consume the distinction (Kolon's `==`/`!=` compare strings and numbers
+ * correctly), so this set is carried for parity with the Mojo adapter.
+ */
+export function collectStringValueNames(ir: ComponentIR): Set<string> {
+  const names = new Set<string>()
+  for (const s of ir.metadata.signals) {
+    if (isStringTypeInfo(s.type) || isBareStringLiteral(s.initialValue)) {
+      names.add(s.getter)
+    }
+  }
+  for (const p of ir.metadata.propsParams) {
+    if (isStringTypeInfo(p.type)) names.add(p.name)
+  }
+  return names
+}

package/src/adapter/spread/spread-codegen.ts

@@ -0,0 +1,179 @@
+/**
+ * Object-literal / conditional-spread → Kolon hashref lowering for the
+ * Text::Xslate template adapter.
+ *
+ * Extracted from `xslate-adapter.ts` (domain-module refactor, issue #2018
+ * track D). Free functions taking a `XslateSpreadContext` (built by the adapter's
+ * `spreadCtx` getter) so the cluster depends on the narrow seam — the recursive
+ * expression entry plus per-compile bookkeeping — rather than the whole
+ * adapter class. Mirror of the Go / Mojo adapter's `spread/spread-codegen.ts`.
+ *
+ * The conditional-spread / object-literal entries read the IR-carried
+ * structured `ParsedExpr` tree (#2018, mirroring go-template's U5/U6) instead
+ * of re-parsing the source with `ts.createSourceFile`. The condition and scalar
+ * values are threaded straight into `ctx.convertExpressionToKolon` as its
+ * `preParsed` argument (cf. go-template's
+ * `convertExpressionToGo(jsExpr, out?, preParsed?)`), so no stringify→re-parse
+ * round-trip occurs — the emitted Kolon is byte-identical to the former path
+ * because the carried tree is exactly what re-parsing the stringified text
+ * produced. The `ts.factory` rebuild in `recordIndexAccessToKolon` only
+ * reconstructs the `IDENT[KEY]` node the shared `parseRecordIndexAccess` parser
+ * accepts; no source-text re-parse. `stringifyParsedExpr` is retained solely for
+ * the BF101 diagnostic message (display purposes).
+ */
+
+import ts from 'typescript'
+import { parseRecordIndexAccess, stringifyParsedExpr } from '@barefootjs/jsx'
+import type { ParsedExpr } from '@barefootjs/jsx'
+
+import type { XslateSpreadContext } from '../emit-context.ts'
+import { escapeKolonSingleQuoted } from '../lib/kolon-naming.ts'
+
+/**
+ * Lower a conditional inline-object spread
+ *   `COND ? { 'aria-describedby': describedBy } : {}`
+ * to a Kolon inline ternary of hashrefs
+ *   `$describedBy ? { 'aria-describedby' => $describedBy } : {}`.
+ * Reads the IR-carried structured `ParsedExpr` tree; both branches must be
+ * object literals; the condition + values route through
+ * `convertExpressionToKolon`. Returns `null` for any other shape so the caller
+ * falls back to its normal lowering. Mirror of `conditionalSpreadToPerl`.
+ * `parseExpression` already strips redundant parentheses, so the conditional /
+ * object-literal shapes surface directly.
+ */
+export function conditionalSpreadToKolon(
+  ctx: XslateSpreadContext,
+  expr: ParsedExpr | undefined,
+): string | null {
+  if (!expr || expr.kind !== 'conditional') return null
+  const whenTrue = expr.consequent
+  const whenFalse = expr.alternate
+  if (whenTrue.kind !== 'object-literal' || whenFalse.kind !== 'object-literal') {
+    return null
+  }
+  // Thread the condition's carried `ParsedExpr` tree straight through as
+  // `preParsed` (#2018) — no stringify→re-parse round-trip; `convertExpressionToKolon`
+  // uses the tree directly and derives any diagnostic text from it.
+  const condKolon = ctx.convertExpressionToKolon('', expr.test)
+  const trueKolon = objectLiteralToKolonHashref(ctx, whenTrue)
+  const falseKolon = objectLiteralToKolonHashref(ctx, whenFalse)
+  if (trueKolon === null || falseKolon === null) return null
+  return `${condKolon} ? ${trueKolon} : ${falseKolon}`
+}
+
+/**
+ * (#1971 Perl) Lower a bare object-literal expression (`{ align: 'start' }`),
+ * carried as the IR's structured `ParsedExpr` tree, to a Kolon hashref via
+ * `objectLiteralToKolonHashref`, or null when it isn't a plain object literal.
+ * Used for inline object-literal child props (carousel `opts`).
+ */
+export function objectLiteralExprToKolonHashref(
+  ctx: XslateSpreadContext,
+  expr: ParsedExpr | undefined,
+): string | null {
+  if (!expr || expr.kind !== 'object-literal') return null
+  return objectLiteralToKolonHashref(ctx, expr)
+}
+
+/**
+ * Convert a static object literal into a Kolon hashref string for a
+ * conditional spread. Only static string/identifier keys are allowed; values
+ * resolve via `convertExpressionToKolon` (or the `Record[propKey]` index
+ * lowering). Returns `null` for any computed/spread/dynamic key. Empty object
+ * → `{}`. Mirror of `objectLiteralToPerlHashref`.
+ */
+export function objectLiteralToKolonHashref(
+  ctx: XslateSpreadContext,
+  obj: Extract<ParsedExpr, { kind: 'object-literal' }>,
+): string | null {
+  const entries: string[] = []
+  for (const prop of obj.properties) {
+    // Shorthand `{ a }` was a `ShorthandPropertyAssignment` (not a
+    // `PropertyAssignment`), so the former parser rejected it — keep refusing.
+    if (prop.shorthand) return null
+    // A numeric key (`{ 1: x }`) was rejected by the former parser (only
+    // identifier / string-literal names were accepted); `keyKind`
+    // distinguishes it from a same-text string `'1'` key.
+    if (prop.keyKind === 'numeric') return null
+    const key = prop.key
+    const val = prop.value
+    const indexed = recordIndexAccessToKolon(ctx, val)
+    if (
+      indexed === null &&
+      val.kind === 'index-access' &&
+      !isLiteralIndex(val.index)
+    ) {
+      // Variable-index record access (`sizeMap[size]`) the static-inline
+      // path couldn't resolve (non-scalar value / non-const receiver).
+      // Since #1897 made variable indices parseable (`index-access`),
+      // the generic value lowering would emit `$sizeMap[$size]` against
+      // an UNBOUND module const instead of refusing — record BF101 and
+      // bail so the spread surfaces the out-of-shape diagnostic,
+      // matching pre-#1897 behaviour. (Mirrors the Mojo adapter.)
+      ctx.errors.push({
+        code: 'BF101',
+        severity: 'error',
+        message: `Spread object value '${stringifyParsedExpr(val)}' indexes a record map whose values aren't scalar literals — it can't lower to an inline Kolon hashref.`,
+        loc: { file: ctx.componentName + '.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } },
+        suggestion: {
+          message: 'Index a record whose values are number/string literals, or move the spread into a `\'use client\'` component so hydration computes it.',
+        },
+      })
+      return null
+    }
+    const valKolon =
+      indexed !== null
+        ? indexed
+        // Thread the carried `val` tree straight through as `preParsed` (#2018)
+        // — no stringify→re-parse round-trip.
+        : ctx.convertExpressionToKolon('', val)
+    entries.push(`'${escapeKolonSingleQuoted(key)}' => ${valKolon}`)
+  }
+  return entries.length === 0 ? '{}' : `{ ${entries.join(', ')} }`
+}
+
+/** True when a parsed index is a numeric or string literal (`arr[0]`, `m['k']`). */
+function isLiteralIndex(index: ParsedExpr): boolean {
+  return (
+    index.kind === 'literal' &&
+    (index.literalType === 'number' || index.literalType === 'string')
+  )
+}
+
+/**
+ * Lower a spread-object VALUE of the form `IDENT[KEY]` (CheckIcon's
+ * `sizeMap[size]`) to an inline indexed Kolon hashref
+ *   `{ 'sm' => 16, 'md' => 20, ... }[$size]`.
+ * Reuses the shared structural parse (`parseRecordIndexAccess`) — rebuilding
+ * the `IDENT[KEY]` node from the carried tree via `ts.factory` rather than
+ * re-parsing source text; this wrapper only does the single-quote escaping +
+ * Kolon index emit. NB: Kolon indexes a hashref literal with bracket syntax
+ * `{…}[$key]`, NOT Perl's arrow-deref `{…}->{$key}` (which Kolon's parser
+ * rejects) — this is the one divergence from the Mojo `recordIndexAccessToPerl`
+ * emit.
+ */
+export function recordIndexAccessToKolon(ctx: XslateSpreadContext, val: ParsedExpr): string | null {
+  // The only shape `parseRecordIndexAccess` accepts is `IDENT[KEY]` with
+  // identifier object and index, so rebuild exactly that node from the carried
+  // tree via `ts.factory` — no source-text re-parse. Any other shape can't
+  // match and short-circuits to `null` here.
+  if (
+    val.kind !== 'index-access' ||
+    val.object.kind !== 'identifier' ||
+    val.index.kind !== 'identifier'
+  ) {
+    return null
+  }
+  const tsVal = ts.factory.createElementAccessExpression(
+    ts.factory.createIdentifier(val.object.name),
+    ts.factory.createIdentifier(val.index.name),
+  )
+  const parsed = parseRecordIndexAccess(tsVal, ctx.localConstants ?? [], ctx.propsParams)
+  if (!parsed) return null
+  const entries = parsed.entries.map(e => {
+    const mapVal =
+      e.value.kind === 'number' ? e.value.text : `'${escapeKolonSingleQuoted(e.value.text)}'`
+    return `'${escapeKolonSingleQuoted(e.key)}' => ${mapVal}`
+  })
+  return `{ ${entries.join(', ')} }[$${parsed.indexPropName}]`
+}

package/src/adapter/value/parsed-literal.ts

@@ -0,0 +1,80 @@
+/**
+ * String-literal value lowering for the Text::Xslate (Kolon) template adapter.
+ *
+ * Extracted from `xslate-adapter.ts` (domain-module refactor, issue #2018
+ * track D). Pure functions over const-initializer source text and analyzer
+ * type info — no adapter instance state.
+ *
+ * SHARED CANDIDATE: `isStringTypeInfo` and `isBareStringLiteral` are
+ * byte-identical to the Mojo adapter's copies and adapter-agnostic —
+ * extraction candidates for a shared Perl-family codegen module (groundwork
+ * for the future Perl evaluator integration, issue #2018 track D).
+ * `parsePureStringLiteral` deliberately differs (Xslate hand-parses; Mojo
+ * uses the TS parser), so it stays per-adapter.
+ */
+
+import { evalStringArrayJoin, type TypeInfo } from '@barefootjs/jsx'
+
+/**
+ * Parse a const initializer's source text. Returns the unescaped string value
+ * when the whole initializer is a single pure string literal — single/double
+ * quoted, or a no-substitution backtick template (no `${}`) — else `null`.
+ * Only such a value can be inlined byte-for-byte; template literals with
+ * interpolation, numbers, objects, and `Record<T,string>` maps are excluded.
+ */
+export function parsePureStringLiteral(source: string): string | null {
+  let s = source.trim()
+  // Peel a single layer of wrapping parens.
+  while (s.startsWith('(') && s.endsWith(')')) s = s.slice(1, -1).trim()
+  const quote = s[0]
+  if ((quote === "'" || quote === '"') && s[s.length - 1] === quote) {
+    const body = s.slice(1, -1)
+    // Reject if an unescaped matching quote appears inside (not a single
+    // literal then).
+    if (containsUnescaped(body, quote)) return null
+    return unescapeStringLiteralBody(body)
+  }
+  if (quote === '`' && s[s.length - 1] === '`') {
+    const body = s.slice(1, -1)
+    if (body.includes('${')) return null
+    if (containsUnescaped(body, '`')) return null
+    return unescapeStringLiteralBody(body)
+  }
+  // `[<literals>].join(' ')` module consts (e.g. Switch's `trackStateClasses`)
+  // → inline the flattened string byte-for-byte. See `evalStringArrayJoin`.
+  return evalStringArrayJoin(source)
+}
+
+/** Whether `s` contains an unescaped occurrence of `ch`. */
+export function containsUnescaped(s: string, ch: string): boolean {
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '\\') { i++; continue }
+    if (s[i] === ch) return true
+  }
+  return false
+}
+
+/** Unescape a JS string-literal body's common escape sequences. */
+export function unescapeStringLiteralBody(s: string): string {
+  return s.replace(/\\(.)/g, (_, c) => {
+    switch (c) {
+      case 'n': return '\n'
+      case 'r': return '\r'
+      case 't': return '\t'
+      case '0': return '\0'
+      default: return c
+    }
+  })
+}
+
+/** True when `type` is the `string` primitive. */
+export function isStringTypeInfo(type: TypeInfo | undefined): boolean {
+  return type?.kind === 'primitive' && type.primitive === 'string'
+}
+
+/** True when `initialValue` is a bare string-literal expression. */
+export function isBareStringLiteral(initialValue: string | undefined): boolean {
+  if (!initialValue) return false
+  const v = initialValue.trim()
+  return (v.startsWith("'") && v.endsWith("'")) || (v.startsWith('"') && v.endsWith('"'))
+}