@barefootjs/xslate 0.16.0 → 0.17.0

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,125 @@
+/**
+ * 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,
+  extractArrowBodyExpression,
+  isSupported,
+  parseExpression,
+} from '@barefootjs/jsx'
+
+import type { XslateMemoContext } from '../emit-context.ts'
+import { referencedVarsAreAvailable } from '../lib/ir-scope.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'
+  )
+}
+
+/**
+ * Seed memos whose SSR default is `null` (not statically evaluable) by
+ * computing them in-template from the already-seeded prop / signal vars
+ * (`createMemo(() => props.value * 10)` → `: my $x = $value * 10;`). Without
+ * this the memo's `$x` renders empty — the reason
+ * `props-reactivity-comparison` was skipped. Only emitted when every var the
+ * lowering references is already in scope. (#1297)
+ */
+export function generateDerivedMemoSeed(ctx: XslateMemoContext, 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.
+  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 gets no stash seed, so its `$on` would render nil;
+  // and the static default can't capture the per-call prop. Seed it
+  // in-template when the init lowers cleanly AND references an in-scope var.
+  // Object/array/constant inits keep the existing ssr-defaults seeding.
+  for (const signal of signals) {
+    const kolon = tryLowerToKolon(ctx, signal.initialValue, available)
+    // Kolon can't express `: my $x = … $x …` — declaring `my $x` makes the
+    // RHS `$x` an undefined lexical rather than the render var. A same-name
+    // signal (`createSignal(props.x ?? d)`, getter == prop) is just the prop
+    // with a default, which the harness already seeds correctly from the
+    // passed prop — skip the in-template seed for it. (Different-name
+    // prop-derived signals like toggle's `on` from `defaultOn` are unaffected.)
+    const refsSelf = kolon !== null && new RegExp(`\\$${signal.getter}\\b`).test(kolon)
+    if (kolon !== null && !refsSelf) lines.push(`: my $${signal.getter} = ${kolon};`)
+    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 already in scope;
+    // block-bodied arrows / out-of-scope references fall back to the
+    // static ssr-defaults seed. Same self-reference guard as the signal
+    // loop above — Kolon's `my` shadows the render var on the RHS.
+    const body = extractArrowBodyExpression(memo.computation)
+    if (body !== null) {
+      const kolon = tryLowerToKolon(ctx, body, available)
+      const refsSelf = kolon !== null && new RegExp(`\\$${memo.name}\\b`).test(kolon)
+      if (kolon !== null && !refsSelf) lines.push(`: my $${memo.name} = ${kolon};`)
+    }
+    available.add(memo.name)
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : ''
+}
+
+/**
+ * Lower a signal init / memo body to Kolon for an in-template SSR seed, or
+ * `null` when it shouldn't be seeded this way: not a supported shape
+ * (`isSupported` pre-check, so object/array literals don't fail the build),
+ * references no in-scope var (a constant — keep ssr-defaults seeding), or
+ * references an out-of-scope binding. (#1297)
+ */
+export function tryLowerToKolon(
+  ctx: XslateMemoContext,
+  expr: string,
+  available: ReadonlySet<string>,
+): string | null {
+  const trimmed = expr.trim()
+  if (!trimmed) return null
+  if (!isSupported(parseExpression(trimmed)).supported) return null
+  const kolon = ctx.convertExpressionToKolon(trimmed)
+  if (kolon === '' || !/\$[A-Za-z_]\w*/.test(kolon)) return null
+  return referencedVarsAreAvailable(kolon, available) ? kolon : null
+}

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('"'))
+}