@barefootjs/jsx 0.18.4 → 0.18.5

package/src/jsx-to-ir.ts

@@ -48,7 +48,7 @@ import { resolveFreeRefs, isNameBound as isNameBoundInEnv, type BindingEnvironme
 import { computeFileScope } from './ir-to-client-js/component-scope.ts'
 import { extractFreeIdentifiersFromNode, initializerShapeContainsJsx } from './analyzer.ts'
 import { iterateJsTokens, replaceInExprContexts } from './scanner/js-scanner.ts'
-import { toHTMLAttrName } from '@barefootjs/shared'
+import { toHTMLAttrName, decodeEntities } from '@barefootjs/shared'
 
 // =============================================================================
 // Transform Context
@@ -82,6 +82,17 @@ interface TransformContext {
   _destructuredPropNames?: Set<string> | null
   /** Active loop parameter names for slotId assignment to loop-param-dependent expressions */
   loopParams: Set<string>
+  /**
+   * Count of enclosing `.map()` loops (0 = outermost), incremented/
+   * decremented in lockstep with entering/leaving `transformMapCall`.
+   * Unlike `loopParams` (a name Set that can gain several entries for
+   * ONE loop level via destructuring), this is a plain per-level
+   * counter — the single source of truth `IRLoop.depth` is stamped
+   * from, so every adapter's `data-key`/`data-key-N` suffix derives
+   * from one IR-computed value instead of each adapter re-deriving
+   * nesting depth its own way (#2168 nested-loop-outer-binding).
+   */
+  loopDepth: number
   /** Counter for async boundary IDs (a0, a1, ...) */
   asyncIdCounter: number
   /** Counter for <Region> structural index (0, 1, ...) within a file. */
@@ -395,6 +406,7 @@ function createTransformContext(analyzer: AnalyzerContext): TransformContext {
     isRoot: true,
     insideComponentChildren: false,
     loopParams: new Set(),
+    loopDepth: 0,
     patterns: {
       signals: analyzer.signals.map(s => ({
         getter: s.getter,
@@ -1563,7 +1575,12 @@ function transformText(node: ts.JsxText, ctx: TransformContext): IRText | null {
 
   return {
     type: 'text',
-    value: text,
+    // JSX decodes character references at parse time (`&copy;` IS the
+    // text `©`), so the IR carries the DECODED value — the semantics —
+    // and each adapter re-escapes for its own emission context.
+    // Decode AFTER whitespace normalization: `&nbsp;` yields U+00A0,
+    // which `\s+` would otherwise collapse into a plain space.
+    value: decodeEntities(text),
     loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
   }
 }
@@ -2483,6 +2500,31 @@ function isIteratorShapeCall(
   return { array: node.expression.expression, shape: name }
 }
 
+/**
+ * Check if a node is the STATIC `Object.entries(x)` / `Object.keys(x)` /
+ * `Object.values(x)` call form (#2168 object-entries-map) — the
+ * one-argument form where `x` is a plain object/Record being iterated,
+ * as opposed to {@link isIteratorShapeCall}'s zero-arg instance-method
+ * form (`arr.entries()`) on an actual array. Returns the object
+ * expression (any expression — `props.x`, `x ?? {}`, not just a bare
+ * identifier) and the iteration shape so `transformMapCall` can strip
+ * the `Object.<method>(...)` wrapper and record it on the IRLoop as
+ * `objectIteration` (see that field's docstring in `types.ts` for why
+ * this is a distinct field from `iterationShape`, not a shared one).
+ */
+function isObjectIteratorCall(
+  node: ts.Expression,
+): { object: ts.Expression; shape: 'entries' | 'keys' | 'values' } | null {
+  if (!ts.isCallExpression(node)) return null
+  if (!ts.isPropertyAccessExpression(node.expression)) return null
+  if (!ts.isIdentifier(node.expression.expression)) return null
+  if (node.expression.expression.text !== 'Object') return null
+  if (node.arguments.length !== 1) return null
+  const name = node.expression.name.text
+  if (name !== 'entries' && name !== 'keys' && name !== 'values') return null
+  return { object: node.arguments[0], shape: name }
+}
+
 type SortExtractionResult = {
   result: IRLoopSort | null
   unsupportedReason?: string
@@ -3246,6 +3288,10 @@ function transformMapCall(
   // Capture nesting depth before we register this map's own params.
   // ctx.loopParams is populated by the *outer* map; if non-empty we are inside one.
   const isNested = ctx.loopParams.size > 0
+  // This loop's own depth (0 = outermost) is however many enclosing
+  // loops are already active, captured before `ctx.loopDepth` below is
+  // bumped for THIS loop's own descendants.
+  const depth = ctx.loopDepth
 
   const propAccess = node.expression as ts.PropertyAccessExpression
   const mapSource = propAccess.expression
@@ -3271,6 +3317,7 @@ function transformMapCall(
   let templateMapPreamble: string | undefined
   let typedMapPreamble: string | undefined
   let iterationShape: 'entries' | 'keys' | undefined
+  let objectIteration: 'entries' | 'keys' | 'values' | undefined
 
   // Helper to set both array and templateArray
   const setArray = (node: ts.Expression) => {
@@ -3284,8 +3331,11 @@ function transformMapCall(
   // adapters emit the right loop variable bindings. `.values()` is a
   // no-op (same as plain `.map()`) so it's stripped but not recorded.
   // The inner expression (after stripping) feeds into the standard
-  // filter/sort chain detection below.
-  let chainSource = mapSource
+  // filter/sort chain detection below. Widened to `ts.Expression` (not
+  // narrowed to `mapSource`'s own `LeftHandSideExpression` type) since
+  // `isObjectIteratorCall`'s stripped argument can be any expression
+  // (`x ?? {}`, not just a `LeftHandSideExpression`).
+  let chainSource: ts.Expression = mapSource
   const iteratorInfo = isIteratorShapeCall(mapSource)
   if (iteratorInfo) {
     chainSource = iteratorInfo.array
@@ -3295,6 +3345,18 @@ function transformMapCall(
       iterationShape = 'keys'
     }
     // 'values' is a no-op — same as plain .map()
+  } else {
+    // Detect the STATIC `Object.entries(x)` / `.keys(x)` / `.values(x)`
+    // form (#2168 object-entries-map) — see `isObjectIteratorCall`'s and
+    // `IRLoop.objectIteration`'s docstrings for why this is a SEPARATE
+    // shape from the array-instance-method case above, not a shared one.
+    // Unlike that case, `'values'` DOES need recording here (it isn't a
+    // no-op: `x` itself isn't iterable as a plain object).
+    const objectIteratorInfo = isObjectIteratorCall(mapSource)
+    if (objectIteratorInfo) {
+      chainSource = objectIteratorInfo.object
+      objectIteration = objectIteratorInfo.shape
+    }
   }
 
   const filterInfo = isFilterCall(chainSource)
@@ -3445,8 +3507,12 @@ function transformMapCall(
       // `.entries()` synthesises `[index, value]` — when the callback
       // destructures exactly two array elements, extract the names into
       // `index` and `param` so the loop renders with proper bindings and
-      // the BF104 destructure-param refusal doesn't fire.
-      if (iterationShape === 'entries' && ts.isArrayBindingPattern(firstParam.name)) {
+      // the BF104 destructure-param refusal doesn't fire. `Object.entries(x)`
+      // (`objectIteration === 'entries'`) synthesises the SAME `[key,
+      // value]` 2-tuple shape — `index` just holds a string key instead
+      // of a numeric position — so it reuses this exact extraction.
+      const isEntriesShape = iterationShape === 'entries' || objectIteration === 'entries'
+      if (isEntriesShape && ts.isArrayBindingPattern(firstParam.name)) {
         const elements = firstParam.name.elements.filter(
           el => !ts.isOmittedExpression(el),
         )
@@ -3485,7 +3551,7 @@ function transformMapCall(
         }
       }
     }
-    if (callback.parameters.length > 1 && iterationShape !== 'entries') {
+    if (callback.parameters.length > 1 && iterationShape !== 'entries' && objectIteration !== 'entries') {
       const secondParam = callback.parameters[1]
       index = secondParam.name.getText(ctx.sourceFile)
       if (secondParam.type) {
@@ -3504,6 +3570,7 @@ function transformMapCall(
       ctx.loopParams.add(param)
     }
     if (index) ctx.loopParams.add(index)
+    ctx.loopDepth++
 
     // Logical control flow (`cond && <X/>`, `a ?? themeLogo()`) as the map
     // body. This is not a JSX literal, ternary, or block, so without this
@@ -3626,6 +3693,7 @@ function transformMapCall(
       ctx.loopParams.delete(param)
     }
     if (index) ctx.loopParams.delete(index)
+    ctx.loopDepth--
   }
 
   // If no JSX children were found (e.g., callback returns a function call),
@@ -3705,6 +3773,16 @@ function transformMapCall(
     !isSignalOrMemoArray(array, ctx)
     && !isDirectPropArray
     && !hasCalls
+    // `objectIteration` (#2168 object-entries-map): `array` here is the
+    // STRIPPED object expression (`Object.entries(x)`'s `x`), which can
+    // itself be a static module-scope const object literal and would
+    // otherwise satisfy every check above — but a plain OBJECT has no
+    // `.forEach()`/`.map()` (the static-array client codegen's own
+    // methods), unlike an actual array literal. Force the dynamic
+    // `mapArray()` path instead, which this shape's client-JS array-expr
+    // reconstruction (`applyObjectIterationWrap`, `ir-to-client-js/utils.ts`)
+    // already handles correctly.
+    && !objectIteration
 
   // Collect nested components for both static and dynamic arrays.
   // Static arrays: needed for initChild hydration.
@@ -3744,6 +3822,8 @@ function transformMapCall(
     sortComparator,
     chainOrder,
     iterationShape,
+    objectIteration,
+    depth,
     clientOnly: isClientOnly || undefined,
     mapPreamble,
     templateMapPreamble,
@@ -4157,9 +4237,12 @@ function getAttributeValue(attr: ts.JsxAttribute, ctx: TransformContext): AttrVa
     return AttrValueOf.booleanAttr()
   }
 
-  // String literal: <div id="main" />
+  // String literal: <div id="main" />. JSX decodes character references
+  // in quoted attribute values just like in text children, so the IR
+  // carries the decoded string (`title="Fish &amp; Chips"` IS the value
+  // `Fish & Chips`); adapters re-escape on emit.
   if (ts.isStringLiteral(attr.initializer)) {
-    return AttrValueOf.literal(attr.initializer.text)
+    return AttrValueOf.literal(decodeEntities(attr.initializer.text))
   }
 
   // Expression: <div class={className} />

package/src/types.ts

@@ -574,6 +574,74 @@ export interface IRLoop {
    */
   iterationShape?: 'entries' | 'keys'
 
+  /**
+   * Pre-`.map()` object iteration (#2168 object-entries-map). Distinct
+   * from {@link iterationShape}, which is scoped ENTIRELY to an array's
+   * own zero-arg `.entries()`/`.keys()`/`.values()` methods — those
+   * synthesize a real numeric index off the array's position, and every
+   * adapter's consumption of `iterationShape` assumes an actual
+   * array/slice underneath.
+   *
+   * `objectIteration` instead records the STATIC `Object.entries(x)` /
+   * `Object.keys(x)` / `Object.values(x)` call form, where `x` is a
+   * plain object/Record (not an array): the "index" bound for `'entries'`
+   * is a STRING KEY, not a numeric position, and the collection an
+   * adapter must iterate is its native map/dict/hash type, not an
+   * array/slice. `transformMapCall` strips the `Object.<method>(...)`
+   * wrapper the same way it strips `arr.entries()` — `array`/`arrayParsed`
+   * end up holding just `x` — and records the shape here so each
+   * adapter's loop renderer picks the right native construct:
+   *
+   *   - `'entries'` → both `index` (bound to the KEY) and `param` (bound
+   *     to the VALUE), synthesized from the 2-element destructure the
+   *     same way `iterationShape: 'entries'` is (see `jsx-to-ir.ts`'s
+   *     `transformMapCall`) — e.g. Jinja `for k, v in x.items()`.
+   *   - `'keys'` → `param` bound to the key only — e.g. Jinja
+   *     `for k in x.keys()`.
+   *   - `'values'` → `param` bound to the value only — e.g. Jinja
+   *     `for v in x.values()`. Unlike the array case, `'values'` is NOT
+   *     a no-op here: `Object.values(x)` genuinely differs from
+   *     iterating `x` itself (`x` isn't iterable at all as a plain
+   *     object), so it must be recorded.
+   *
+   * Iteration ORDER is native-map-dependent: Python `dict`/PHP
+   * array-object/Ruby `Hash` preserve the source object's insertion
+   * order (matching JS `Object.entries()` semantics exactly), so Jinja,
+   * Twig, Blade, and ERB lower directly to their native map/dict/hash
+   * iteration. Go's `map[string]T`, Rust's `BTreeMap` (deliberate design,
+   * see `num.rs`), and Perl's hash (Xslate/Mojolicious) have NO
+   * order-preserving native map type, so those four instead lower to a
+   * DETERMINISTIC SORTED-BY-KEY iteration — Go's `{{range}}` (the
+   * stdlib's own `fmtsort`), minijinja's `BTreeMap` (already sorted),
+   * Kolon's `.kv()`/`.keys()`/`.values()` (verified empirically sorted),
+   * and Mojolicious's explicit `sort keys %$hash` (mirroring the
+   * existing `spread_attrs`/`_style_to_css` convention in
+   * `BarefootJS.pm`). This is a documented, permanent known limitation
+   * relative to JS's insertion-order guarantee (not a follow-up TODO) —
+   * true insertion order is physically unrecoverable from those
+   * languages' native map types once constructed, so sorted order is the
+   * best available deterministic approximation, not an interim refusal.
+   *
+   * Only the OUTERMOST, unchained `Object.<method>(x).map(cb)` shape is
+   * recognized — mirroring `iterationShape`'s own scope, chaining
+   * (`Object.entries(x).filter(pred).map(cb)`) is not (yet) recognized
+   * either, same as the array case.
+   */
+  objectIteration?: 'entries' | 'keys' | 'values'
+
+  /**
+   * Count of enclosing `.map()` loops (0 = outermost, 1 = nested one
+   * level deep, ...). Adapters use this to derive the loop body's
+   * `key`/`data-key` attribute suffix — `depth > 0 ? 'data-key-' +
+   * depth : 'data-key'` — matching `keyAttrName()` in
+   * `ir-to-client-js/utils.ts`, which the CSR path and the Hono SSR
+   * adapter each already derive independently (a recursion counter and
+   * a push/pop stack respectively). Before this field, the 8 template
+   * (non-JS) adapters had no depth awareness at all and always emitted
+   * plain `data-key` on nested-loop items (#2168 nested-loop-outer-binding).
+   */
+  depth: number
+
   /**
    * When true, loop should be evaluated on client side only.
    * SSR adapters should skip rendering and output placeholder markers.