@barefootjs/blade 0.1.0

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

@@ -0,0 +1,179 @@
+/**
+ * Object-literal / conditional-spread → Blade hash lowering for the Blade
+ * template adapter.
+ *
+ * Ported from `packages/adapter-jinja/src/adapter/spread/spread-codegen.ts`.
+ * Free functions taking a `BladeSpreadContext` (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.
+ *
+ * The conditional-spread / object-literal entries read the IR-carried
+ * structured `ParsedExpr` tree (#2018) instead of re-parsing the source with
+ * `ts.createSourceFile`. The condition and scalar values are threaded
+ * straight into `ctx.convertExpressionToBlade` as its `preParsed` argument,
+ * so no stringify→re-parse round-trip occurs. The `ts.factory` rebuild in
+ * `recordIndexAccessToBlade` only reconstructs the `IDENT[KEY]` node the
+ * shared `parseRecordIndexAccess` parser accepts; no source-text re-parse.
+ *
+ * Twig→Blade divergence: a Twig hash literal `{'k': v}` becomes a PHP array
+ * literal `['k' => v]` (mapping table) — `'key' => value` entries joined by
+ * `, `, wrapped in `[...]`, never `{...}`. Empty hash is `[]`, not `{}`.
+ */
+
+import ts from 'typescript'
+import { parseRecordIndexAccess, stringifyParsedExpr } from '@barefootjs/jsx'
+import type { ParsedExpr } from '@barefootjs/jsx'
+
+import type { BladeSpreadContext } from '../emit-context.ts'
+import { escapeBladeSingleQuoted, bladeHashKey, bladeVar } from '../lib/blade-naming.ts'
+
+/**
+ * Lower a conditional inline-object spread
+ *   `COND ? { 'aria-describedby': describedBy } : {}`
+ * to a Blade inline ternary of PHP arrays
+ *   `($bf->truthy($describedBy) ? ['aria-describedby' => $describedBy] : [])`.
+ * Reads the IR-carried structured `ParsedExpr` tree; both branches must be
+ * object literals; the condition + values route through
+ * `convertExpressionToBlade`. Returns `null` for any other shape so the
+ * caller falls back to its normal lowering.
+ */
+export function conditionalSpreadToBlade(
+  ctx: BladeSpreadContext,
+  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.
+  const condBlade = ctx.convertConditionToBlade('', expr.test)
+  const trueBlade = objectLiteralToBladeDict(ctx, whenTrue)
+  const falseBlade = objectLiteralToBladeDict(ctx, whenFalse)
+  if (trueBlade === null || falseBlade === null) return null
+  // Blade's symbolic ternary (see `expr/emitters.ts`'s file header,
+  // divergence 1) — `(test ? a : b)`, not Jinja's `(a if test else b)`.
+  return `(${condBlade} ? ${trueBlade} : ${falseBlade})`
+}
+
+/**
+ * (#1971) Lower a bare object-literal expression (`{ align: 'start' }`),
+ * carried as the IR's structured `ParsedExpr` tree, to a PHP array via
+ * `objectLiteralToBladeDict`, or null when it isn't a plain object literal.
+ * Used for inline object-literal child props (carousel `opts`).
+ */
+export function objectLiteralExprToBladeDict(
+  ctx: BladeSpreadContext,
+  expr: ParsedExpr | undefined,
+): string | null {
+  if (!expr || expr.kind !== 'object-literal') return null
+  return objectLiteralToBladeDict(ctx, expr)
+}
+
+/**
+ * Convert a static object literal into a PHP array-literal string for a
+ * conditional spread. Only static string/identifier keys are allowed; values
+ * resolve via `convertExpressionToBlade` (or the `Record[propKey]` index
+ * lowering). Returns `null` for any computed/spread/dynamic key. Empty
+ * object → `[]`.
+ */
+export function objectLiteralToBladeDict(
+  ctx: BladeSpreadContext,
+  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 = recordIndexAccessToBlade(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).
+      // Record BF101 and bail so the spread surfaces the out-of-shape
+      // diagnostic, matching the Jinja port.
+      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 Blade hash.`,
+        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 valBlade =
+      indexed !== null
+        ? indexed
+        // Thread the carried `val` tree straight through as `preParsed`
+        // (#2018) — no stringify→re-parse round-trip.
+        : ctx.convertExpressionToBlade('', val)
+    entries.push(`${bladeHashKey(key)} => ${valBlade}`)
+  }
+  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 PHP array
+ *   `['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 +
+ * bracket-index emit. PHP indexes an array literal with the SAME bracket
+ * syntax `[...][key]` a JS object index would use (verified empirically —
+ * `php -r 'var_dump(["a"=>1]["a"]);'` → `1`) — no Kolon-style divergence to
+ * steer around here. Unlike Twig's own hash `{…}[key]`, a MISSING key here
+ * would normally raise a PHP warning rather than resolve to `null` — this
+ * call site's caller (`objectLiteralToBladeDict`'s data-table lookup path,
+ * and `blade-adapter.ts`'s `${MAP}[key]` template-literal lowering) always
+ * wraps the result in `?? ''`/`?? null`, which silences an undefined-index
+ * warning exactly like it silences an undefined-variable one (see
+ * `blade-adapter.ts`'s file header, the `??` divergence).
+ */
+export function recordIndexAccessToBlade(ctx: BladeSpreadContext, 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.
+  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 : `'${escapeBladeSingleQuoted(e.value.text)}'`
+    return `${bladeHashKey(e.key)} => ${mapVal}`
+  })
+  return `[${entries.join(', ')}][${bladeVar(parsed.indexPropName)}]`
+}

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

@@ -0,0 +1,75 @@
+/**
+ * String-literal value lowering for the Blade template adapter.
+ *
+ * Ported from `packages/adapter-jinja/src/adapter/value/parsed-literal.ts`.
+ * Byte-identical logic (the source-text parsing here is language-agnostic;
+ * only the caller's escaping of the resolved value into a template literal
+ * differs, and that happens at the call site in `blade-adapter.ts`, not
+ * here).
+ */
+
+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('"'))
+}

package/src/build.ts

@@ -0,0 +1,37 @@
+// Blade build config factory for barefoot.config.ts
+
+import type { BuildOptions } from '@barefootjs/jsx'
+import { BladeAdapter } from './adapter/index.ts'
+import type { BladeAdapterOptions } from './adapter/index.ts'
+
+export interface BladeBuildOptions extends BuildOptions {
+  /** Adapter-specific options passed to BladeAdapter */
+  adapterOptions?: BladeAdapterOptions
+}
+
+/**
+ * Create a BarefootBuildConfig for Blade (PHP) template projects.
+ *
+ * Uses structural typing — does not import BarefootBuildConfig to avoid a
+ * circular dependency between @barefootjs/blade and @barefootjs/cli.
+ */
+export function createConfig(options: BladeBuildOptions = {}) {
+  return {
+    adapter: new BladeAdapter(options.adapterOptions),
+    paths: options.paths,
+    components: options.components,
+    outDir: options.outDir,
+    minify: options.minify,
+    contentHash: options.contentHash,
+    externals: options.externals,
+    externalsBasePath: options.externalsBasePath,
+    bundleEntries: options.bundleEntries,
+    localImportPrefixes: options.localImportPrefixes,
+    outputLayout: options.outputLayout ?? {
+      templates: 'templates',
+      clientJs: 'client',
+      runtime: 'client',
+    },
+    postBuild: options.postBuild,
+  }
+}

package/src/conformance-pins.ts

@@ -0,0 +1,86 @@
+/**
+ * Per-fixture build-time contracts for shapes the Blade adapter
+ * intentionally refuses to lower. Mirrors Jinja's set — the lowering
+ * gates are shared code paths in the ported adapter (BF103/BF104 are
+ * structural: cross-template child registration / destructure-loop-param
+ * limits that apply identically regardless of target template language).
+ * Consumed by this package's own conformance test (as `expectedDiagnostics`)
+ * and by `bf compat` (issue-URL attribution).
+ */
+
+import type { ConformancePins } from '@barefootjs/jsx'
+
+export const conformancePins: ConformancePins = {
+  // Sibling-imported child component in a loop body: emits a
+  // cross-template call needing separate registration. BF103 makes
+  // the requirement loud (same as Jinja).
+  'static-array-children': [{ code: 'BF103', severity: 'error' }],
+  // TodoApp / TodoAppSSR import `TodoItem` from a sibling file and
+  // call it inside a keyed `.map`. Same BF103 (imported child in
+  // `.map`) as Jinja.
+  'todo-app': [{ code: 'BF103', severity: 'error' }],
+  'todo-app-ssr': [{ code: 'BF103', severity: 'error' }],
+  // The `([emoji, users]) => …` array-destructure param itself now lowers
+  // (#2087 Phase B — see the destructure comment below), but the loop
+  // ARRAY is a function-scope computed const (`const entries =
+  // Object.entries(props.reactions ?? {}).filter(...)`) that the adapter
+  // can't bind as a template variable — refused loudly with BF101 (same
+  // check and policy as Jinja / ERB) instead of silently iterating zero
+  // times over an unbound name.
+  'static-array-from-props': [{ code: 'BF101', severity: 'error' }],
+  // Both BF103 (imported child) and BF101 (computed local-const loop
+  // array, as above) fire.
+  'static-array-from-props-with-component': [
+    { code: 'BF103', severity: 'error' },
+    { code: 'BF101', severity: 'error' },
+  ],
+  // #2087 Phase B: every `.map()` destructure shape in the shared corpus
+  // now lowers on Blade via an `@php(...)` local built from the binding's
+  // structured `segments` path (`bladeLoopBindingAccessor` in
+  // `lib/blade-naming.ts`) — fixed bindings at any field/index depth
+  // (`destructure-array-index-in-map`, `destructure-nested-object-in-map`),
+  // array-rest via `$bf->slice` (`rest-destructure-array-in-map`,
+  // `rest-destructure-nested-in-map`), and object-rest via the new
+  // `$bf->omit` residual helper, read by member access
+  // (`rest-destructure-object-in-map`) or spread onto the element
+  // (`rest-destructure-object-spread-in-map`). No `expectedDiagnostics`
+  // pins remain for any of them — see `blade-adapter.ts`'s `renderLoop` for
+  // the still-refused shapes (bare-value rest use, `.filter().map()`
+  // chains, `__bf_`-prefixed names).
+  // (button/kbd graduated: the site/ui Button/Kbd `<Slot>` `{...props}` /
+  // `{...children.props}` component-spread now lowers via an
+  // `array_merge(...)` fold — see `blade-adapter.ts`'s `renderComponent` —
+  // instead of refusing with BF101, so these two no longer need a pin here.)
+  // (`tagged-template-classname` graduated by #2092 — the tag resolves
+  // through the interleave-tag catalogue and desugars to an untagged
+  // template literal, so it lowers like any other className template.)
+  // #2038: a filter predicate whose body contains a NESTED callback call
+  // (`t => !picked().some(p => …)` / `t => picked().find(p => …)`). Blade
+  // has no inline comprehension-with-nested-callback form usable from the
+  // evaluator-JSON `*_eval` payload mechanism (this adapter's ONLY
+  // higher-order-callback lowering path — see `blade-adapter.ts`'s file
+  // header, divergence 3), so the compiler is loud (BF101) instead of
+  // lossy, same as Jinja. The `/* @client */` twin
+  // (`filter-nested-callback-predicate-client`) has no pin here: it must
+  // render clean on every adapter, which asserts the suppression contract.
+  // https://github.com/piconic-ai/barefootjs/issues/2038
+  'filter-nested-callback-predicate': [
+    { code: 'BF101', severity: 'error', issue: 'https://github.com/piconic-ai/barefootjs/issues/2038' },
+  ],
+  'filter-nested-find-predicate': [
+    { code: 'BF101', severity: 'error', issue: 'https://github.com/piconic-ai/barefootjs/issues/2038' },
+  ],
+  // NB: TOP-LEVEL `.find` / `.findIndex` / `.findLast` / `.findLastIndex`
+  // (text position) are NOT pinned here — like Jinja (unlike mojo, which
+  // refuses them), Blade lowers them to `$bf->find_eval` / `find_index_eval`
+  // / etc. via the same evaluator-JSON mechanism as `.filter` / `.every` /
+  // `.some`, so they render. Only the NESTED-in-a-predicate form above is
+  // refused (#2038).
+  // #2073 follow-up (same as Jinja): a function-reference `.map(format)`
+  // callback has no arrow body to serialize — not a CALLBACK_METHODS shape
+  // (`asCallbackMethodCall` requires an arrow argument) — so the shared
+  // `isSupported`'s `UNSUPPORTED_METHODS` gate refuses it with the generic
+  // "Expression not supported" BF101 rather than emitting a broken
+  // template.
+  'array-map-function-reference': [{ code: 'BF101', severity: 'error' }],
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * BarefootJS Blade (PHP) Template Adapter
+ *
+ * Generates Blade template files (.blade.php) from BarefootJS IR.
+ */
+
+export { BladeAdapter, bladeAdapter } from './adapter/index.ts'
+export type { BladeAdapterOptions } from './adapter/index.ts'
+export { conformancePins } from './conformance-pins.ts'