@barefootjs/jsx 0.38.0 → 0.39.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/dist/action-accessor.d.ts +159 -0
  2. package/dist/action-accessor.d.ts.map +1 -0
  3. package/dist/adapters/interface.d.ts +19 -0
  4. package/dist/adapters/interface.d.ts.map +1 -1
  5. package/dist/adapters/jsx-adapter.d.ts.map +1 -1
  6. package/dist/analyzer.d.ts +49 -1
  7. package/dist/analyzer.d.ts.map +1 -1
  8. package/dist/async-action-refusal.d.ts +45 -0
  9. package/dist/async-action-refusal.d.ts.map +1 -0
  10. package/dist/compiler.d.ts.map +1 -1
  11. package/dist/debug.d.ts +61 -5
  12. package/dist/debug.d.ts.map +1 -1
  13. package/dist/errors.d.ts +4 -0
  14. package/dist/errors.d.ts.map +1 -1
  15. package/dist/format-date-refusal.d.ts +2 -6
  16. package/dist/format-date-refusal.d.ts.map +1 -1
  17. package/dist/html-types.d.ts +5 -0
  18. package/dist/html-types.d.ts.map +1 -1
  19. package/dist/index.d.ts +3 -2
  20. package/dist/index.d.ts.map +1 -1
  21. package/dist/index.js +1261 -422
  22. package/dist/ir-to-client-js/build-references.d.ts.map +1 -1
  23. package/dist/ir-to-client-js/collect-elements.d.ts +17 -1
  24. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  25. package/dist/ir-to-client-js/compute-inlinability.d.ts.map +1 -1
  26. package/dist/ir-to-client-js/compute-scope.d.ts.map +1 -1
  27. package/dist/ir-to-client-js/control-flow/plan/insert.d.ts +2 -0
  28. package/dist/ir-to-client-js/control-flow/plan/insert.d.ts.map +1 -1
  29. package/dist/ir-to-client-js/csr-substitute.d.ts.map +1 -1
  30. package/dist/ir-to-client-js/declaration-sort.d.ts +2 -1
  31. package/dist/ir-to-client-js/declaration-sort.d.ts.map +1 -1
  32. package/dist/ir-to-client-js/emit-module-level.d.ts.map +1 -1
  33. package/dist/ir-to-client-js/emit-registration.d.ts.map +1 -1
  34. package/dist/ir-to-client-js/plan/declaration-emit.d.ts +7 -5
  35. package/dist/ir-to-client-js/plan/declaration-emit.d.ts.map +1 -1
  36. package/dist/ir-to-client-js/prop-handling.d.ts.map +1 -1
  37. package/dist/ir-to-client-js/reactivity.d.ts +10 -2
  38. package/dist/ir-to-client-js/reactivity.d.ts.map +1 -1
  39. package/dist/ir-to-client-js/types.d.ts +4 -0
  40. package/dist/ir-to-client-js/types.d.ts.map +1 -1
  41. package/dist/ir-to-client-js/utils.d.ts +52 -9
  42. package/dist/ir-to-client-js/utils.d.ts.map +1 -1
  43. package/dist/jsx-to-ir.d.ts.map +1 -1
  44. package/dist/signal-initializer.d.ts +24 -0
  45. package/dist/signal-initializer.d.ts.map +1 -0
  46. package/dist/ssr-defaults.d.ts.map +1 -1
  47. package/dist/ssr-seed-plan.d.ts.map +1 -1
  48. package/dist/template-position-walk.d.ts +68 -0
  49. package/dist/template-position-walk.d.ts.map +1 -0
  50. package/dist/types.d.ts +95 -0
  51. package/dist/types.d.ts.map +1 -1
  52. package/package.json +2 -2
  53. package/src/__tests__/__snapshots__/doc-examples.test.ts.snap +194 -4
  54. package/src/__tests__/action-accessor.test.ts +166 -0
  55. package/src/__tests__/adapter-output.test.ts +142 -0
  56. package/src/__tests__/create-mutation.test.ts +250 -0
  57. package/src/__tests__/create-query.test.ts +696 -0
  58. package/src/__tests__/csr-fragment-root-scope-shape.test.ts +156 -0
  59. package/src/__tests__/debug.test.ts +305 -0
  60. package/src/__tests__/doc-examples.test.ts +66 -3
  61. package/src/__tests__/ir-fragment-transparency.test.ts +23 -0
  62. package/src/__tests__/issue-3240-nested-static-map-event-delegation.test.ts +245 -0
  63. package/src/__tests__/jsx-text-linebreak-whitespace.test.ts +80 -0
  64. package/src/__tests__/loop-param-accessor-key-member-safety.test.ts +445 -0
  65. package/src/__tests__/props-destructuring.test.ts +79 -4
  66. package/src/__tests__/reactive-factory-arity.test.ts +311 -0
  67. package/src/__tests__/ssr-portal-ref-callback.test.ts +5 -3
  68. package/src/action-accessor.ts +289 -0
  69. package/src/adapters/interface.ts +19 -0
  70. package/src/adapters/jsx-adapter.ts +47 -20
  71. package/src/analyzer.ts +593 -44
  72. package/src/async-action-refusal.ts +254 -0
  73. package/src/compiler.ts +81 -46
  74. package/src/debug.ts +351 -104
  75. package/src/errors.ts +39 -0
  76. package/src/format-date-refusal.ts +6 -125
  77. package/src/html-types.ts +14 -0
  78. package/src/index.ts +3 -1
  79. package/src/ir-to-client-js/build-references.ts +6 -2
  80. package/src/ir-to-client-js/collect-elements.ts +65 -4
  81. package/src/ir-to-client-js/compute-inlinability.ts +2 -1
  82. package/src/ir-to-client-js/compute-scope.ts +3 -1
  83. package/src/ir-to-client-js/control-flow/plan/build-insert.ts +1 -0
  84. package/src/ir-to-client-js/control-flow/plan/insert.ts +2 -0
  85. package/src/ir-to-client-js/control-flow/stringify/event-delegation.ts +112 -3
  86. package/src/ir-to-client-js/control-flow/stringify/insert.ts +1 -1
  87. package/src/ir-to-client-js/csr-substitute.ts +11 -3
  88. package/src/ir-to-client-js/declaration-sort.ts +7 -3
  89. package/src/ir-to-client-js/emit-module-level.ts +7 -4
  90. package/src/ir-to-client-js/emit-registration.ts +5 -10
  91. package/src/ir-to-client-js/index.ts +7 -2
  92. package/src/ir-to-client-js/phases/ref-callbacks.ts +1 -1
  93. package/src/ir-to-client-js/plan/build-declaration-emit.ts +16 -15
  94. package/src/ir-to-client-js/plan/declaration-emit.ts +7 -5
  95. package/src/ir-to-client-js/prop-handling.ts +4 -0
  96. package/src/ir-to-client-js/reactivity.ts +32 -1
  97. package/src/ir-to-client-js/stringify/declaration-emit.ts +14 -7
  98. package/src/ir-to-client-js/types.ts +4 -0
  99. package/src/ir-to-client-js/utils.ts +184 -21
  100. package/src/jsx-to-ir.ts +111 -14
  101. package/src/signal-initializer.ts +36 -0
  102. package/src/ssr-defaults.ts +10 -0
  103. package/src/ssr-seed-plan.ts +12 -1
  104. package/src/template-position-walk.ts +203 -0
  105. package/src/types.ts +99 -0
package/src/jsx-to-ir.ts CHANGED
@@ -70,6 +70,7 @@ import { toHTMLAttrName, decodeEntities, BF_KEY, keyAttrName } from '@barefootjs
70
70
  import { BindingScope } from './scope/binding-scope.ts'
71
71
  import { identifierPattern, identifierCallPattern } from './identifier-pattern.ts'
72
72
  import { isEventHandlerName } from './event-handler-name.ts'
73
+ import { seedActionAccessorReads } from './action-accessor.ts'
73
74
 
74
75
  // =============================================================================
75
76
  // Transform Context
@@ -1188,6 +1189,11 @@ export function jsxToIR(analyzer: AnalyzerContext): IRNode | null {
1188
1189
  if (root) {
1189
1190
  reportRefAttrsAbsentAtSsr(root, ctx)
1190
1191
  attachParsedExpressions(root, analyzer)
1192
+ // #3166: seed a query/mutation action's `isPending()` / `error()` read
1193
+ // where the seed renders like the reference — `action-accessor.ts`'s gate
1194
+ // decides which positions, the same gate BF117's refusal-lift reads.
1195
+ // Runs on the attached `parsed` trees, so it must follow the attach walk.
1196
+ seedActionAccessorReads(root, analyzer.signals)
1191
1197
  resolveRootKeyAttr(root)
1192
1198
  }
1193
1199
  return root
@@ -2201,7 +2207,7 @@ function isTransparentFragment(
2201
2207
  // Filter out whitespace-only text nodes
2202
2208
  const children = node.children.filter(child => {
2203
2209
  if (ts.isJsxText(child)) {
2204
- return child.text.trim() !== ''
2210
+ return cleanJsxWhitespace(child.text) !== ''
2205
2211
  }
2206
2212
  return true
2207
2213
  })
@@ -2276,7 +2282,8 @@ function markDataKeyCarrier(children: IRNode[]): IRNode[] {
2276
2282
  * The marked copy of `node` if this subtree can render an element in first
2277
2283
  * position, or null if it cannot.
2278
2284
  *
2279
- * Descends through `conditional` because a fragment whose only top-level
2285
+ * Descends through a nested `fragment` (no DOM of its own) and through
2286
+ * `conditional`, because a fragment whose only top-level
2280
2287
  * child is a ternary or `&&` is still a single-visual-root row —
2281
2288
  * `{done ? <li class="done"/> : <li/>}` renders exactly one `<li>`. A flat
2282
2289
  * `children.findIndex(c => c.type === 'element')` returns -1 there and
@@ -2304,6 +2311,15 @@ function markCarrierIn(node: IRNode): IRNode | null {
2304
2311
  if (!whenTrue && !whenFalse) return null
2305
2312
  return { ...cond, whenTrue: whenTrue ?? cond.whenTrue, whenFalse: whenFalse ?? cond.whenFalse }
2306
2313
  }
2314
+ if (node.type === 'fragment') {
2315
+ // A fragment nested directly inside the root fragment (`<><><li/></></>`)
2316
+ // renders no DOM of its own, so its first element is the row's first
2317
+ // element too — the one the CSR runtime stamps the key on
2318
+ // (`component.ts`'s `roots.find(isElement)`, #2735).
2319
+ const frag = node as IRFragment
2320
+ const children = markDataKeyCarrier(frag.children)
2321
+ return children === frag.children ? null : { ...frag, children }
2322
+ }
2307
2323
  return null
2308
2324
  }
2309
2325
 
@@ -2359,11 +2375,15 @@ function transformChildren(
2359
2375
 
2360
2376
  const transformed = transformNode(child, ctx)
2361
2377
  if (transformed) {
2362
- // Skip empty text nodes
2363
- if (transformed.type === 'text' && transformed.value.trim() === '') {
2364
- continue
2365
- }
2366
-
2378
+ // `transformText` (the only producer of `type: 'text'` reached from
2379
+ // here — a `JsxText` child) already returns `null` for a node the
2380
+ // JSX whitespace rule says renders nothing, and keeps a node whose
2381
+ // cleaned value is a meaningful single space (`<b>a</b> <i>b</i>`,
2382
+ // #3237). Re-checking `.value.trim() === ''` here duplicated that
2383
+ // decision with a looser rule that silently discarded exactly that
2384
+ // meaningful space — the "one decision, two implementations"
2385
+ // pattern CLAUDE.md's Reference Adapter section calls out. Trust
2386
+ // the single source of truth instead of re-deciding here.
2367
2387
  result.push(transformed)
2368
2388
  }
2369
2389
  }
@@ -2411,10 +2431,25 @@ function isRenderNothingLiteral(expr: ts.Expression, ctx: TransformContext): boo
2411
2431
  }
2412
2432
 
2413
2433
  function transformText(node: ts.JsxText, ctx: TransformContext): IRText | null {
2414
- // Normalize whitespace (React-like behavior)
2415
- const text = node.text.replace(/\s+/g, ' ')
2416
-
2417
- if (text.trim() === '') {
2434
+ // Normalize whitespace the way JSX itself does (TypeScript/Babel/React
2435
+ // agree): a text node is split on line breaks, and only whitespace that
2436
+ // sits at a line break — the leading run of a non-first line, the
2437
+ // trailing run of a non-last line — is trimmed away; empty lines are
2438
+ // dropped and the rest are rejoined with a single space. Whitespace
2439
+ // that does NOT straddle a line break (interior runs on one line, or
2440
+ // the entirety of a single-line text node) is left exactly as written.
2441
+ // A naive `\s+` collapse over the whole node (the previous behavior)
2442
+ // over-trims: `<div>\n Light\n</div>` compiled to `" Light "` instead
2443
+ // of `"Light"` (#3237).
2444
+ const text = cleanJsxWhitespace(node.text)
2445
+
2446
+ // Empty STRING, not empty-after-trim: a single-line text node made
2447
+ // entirely of whitespace (no line break) is a meaningful single space
2448
+ // in JSX — `<b>a</b> <i>b</i>` — and `cleanJsxWhitespace` already
2449
+ // reduces a multi-line, indentation-only node (no line break survives
2450
+ // the per-line trim) to `''`. Checking `.trim() === ''` here would
2451
+ // discard that meaningful single space too.
2452
+ if (text === '') {
2418
2453
  return null
2419
2454
  }
2420
2455
 
@@ -2430,6 +2465,38 @@ function transformText(node: ts.JsxText, ctx: TransformContext): IRText | null {
2430
2465
  }
2431
2466
  }
2432
2467
 
2468
+ /**
2469
+ * JSX's whitespace-cleanup rule for a text child, as TypeScript, Babel and
2470
+ * React all implement it (see e.g. Babel's `cleanJSXElementLiteralChild`):
2471
+ *
2472
+ * - Split the raw text on line breaks.
2473
+ * - A tab is treated as a space.
2474
+ * - On every line except the first, strip the leading run of spaces
2475
+ * (it is indentation introduced by the line break, not authored text).
2476
+ * - On every line except the last, strip the trailing run of spaces
2477
+ * (same reasoning, from the other side).
2478
+ * - Drop lines that are empty after that trim.
2479
+ * - Join what's left with a single space.
2480
+ *
2481
+ * A single-line text node (no line break at all) is both "first" and
2482
+ * "last", so neither trim applies and the text passes through untouched —
2483
+ * `<b>a</b> <i>b</i>`'s single-space text node, or `const x = 1; ` inside
2484
+ * a `<pre>`, keep their interior whitespace exactly as written.
2485
+ */
2486
+ function cleanJsxWhitespace(raw: string): string {
2487
+ const lines = raw.split(/\r\n|\n|\r/)
2488
+ const kept: string[] = []
2489
+ for (let i = 0; i < lines.length; i++) {
2490
+ const isFirstLine = i === 0
2491
+ const isLastLine = i === lines.length - 1
2492
+ let line = lines[i].replace(/\t/g, ' ')
2493
+ if (!isFirstLine) line = line.replace(/^ +/, '')
2494
+ if (!isLastLine) line = line.replace(/ +$/, '')
2495
+ if (line !== '') kept.push(line)
2496
+ }
2497
+ return kept.join(' ')
2498
+ }
2499
+
2433
2500
  // =============================================================================
2434
2501
  // Expression Transformation
2435
2502
  // =============================================================================
@@ -6509,6 +6576,7 @@ function expandSpreadAttribute(
6509
6576
  value: AttrValue
6510
6577
  loc: SourceLocation
6511
6578
  freeIdentifiers?: ReadonlySet<string>
6579
+ restExpandedKey?: boolean
6512
6580
  }> {
6513
6581
  const spreadExpr = ctx.getJS(attr.expression)
6514
6582
  const expandedKeys = ctx.analyzer.restPropsExpandedKeys
@@ -6519,13 +6587,17 @@ function expandSpreadAttribute(
6519
6587
  if (expandedKeys.length > 0 && restName && spreadExpr === restName) {
6520
6588
  // Expanded per-key attrs reference `${restName}.${key}` — `restName` is
6521
6589
  // the only free identifier (the `.${key}` tail is a member-access name,
6522
- // not an identifier reference).
6590
+ // not an identifier reference). `restExpandedKey` (#3057) marks these so
6591
+ // Phase 2 (`collectElements`) can bind them reactively off a live
6592
+ // `_p.<key>` read instead of the one-time `${restName}.${key}` snapshot
6593
+ // — see `IRAttribute.restExpandedKey`'s docstring.
6523
6594
  const perKeyFreeIds: ReadonlySet<string> = new Set([restName])
6524
6595
  return expandedKeys.map(key => ({
6525
6596
  name: key,
6526
6597
  value: AttrValueOf.expression(`${restName}.${key}`),
6527
6598
  loc,
6528
6599
  freeIdentifiers: perKeyFreeIds,
6600
+ restExpandedKey: true,
6529
6601
  }))
6530
6602
  }
6531
6603
 
@@ -7161,7 +7233,8 @@ function bindingDeclares(binding: ts.BindingName, name: string): boolean {
7161
7233
  * lookup, so sharing the resolution does not widen what is recognized. It
7162
7234
  * is not a `.map()`-row guard: a portal element inside a row is broken
7163
7235
  * either way (a row-declared callback is still recognized, and still
7164
- * breaks), a pre-existing defect tracked separately.
7236
+ * breaks) — the known limitation `loop-row-ref-portal`
7237
+ * (`packages/adapter-tests/limitations/loop-row-ref-portal.ts`).
7165
7238
  *
7166
7239
  * A match makes `element.ssrPortalOwnerScope` true, which every adapter
7167
7240
  * (#3119) uses to place the element's SSR markup at its own portal
@@ -8264,7 +8337,14 @@ function processComponentProps(
8264
8337
 
8265
8338
  for (const attr of attributes.properties) {
8266
8339
  if (ts.isJsxSpreadAttribute(attr)) {
8267
- props.push(...expandSpreadAttribute(attr, ctx))
8340
+ // `restExpandedKey` (#3057) is consumed only by the element-attribute
8341
+ // path (`collect-elements.ts`'s `attr.restExpandedKey` branch) — a
8342
+ // component-prop forwarded via `{...rest}` already gets a live
8343
+ // `_p.<key>` read through `buildComponentPropsExpr`'s own rest
8344
+ // rewrite, so `IRProp` declares no such field. Strip it here rather
8345
+ // than letting the shared helper's per-key marking leak into IRProp
8346
+ // as an inert flag nothing reads.
8347
+ props.push(...expandSpreadAttribute(attr, ctx).map(({ restExpandedKey: _restExpandedKey, ...prop }) => prop))
8268
8348
  continue
8269
8349
  }
8270
8350
 
@@ -8971,9 +9051,26 @@ function shouldAutoDeferReactiveBrand(expr: ts.Expression, ctx: TransformContext
8971
9051
  // Preserves the original "any native ref anywhere defers to non-deferred"
8972
9052
  // semantics by checking every reactive-brand leaf, not just the first.
8973
9053
  if (leaves.some((leaf) => isSignalOrMemoReference(ctx.getJS(leaf), ctx))) return false
9054
+ // A query action's accessors (`fetchPosts.isPending()`, #3165) are not a
9055
+ // client-only brand package: they stay in the template, where BF117
9056
+ // (`async-action-refusal.ts`) refuses them until they are seeded.
9057
+ if (leaves.some((leaf) => isAsyncActionLeaf(leaf, ctx))) return false
8974
9058
  return true
8975
9059
  }
8976
9060
 
9061
+ /**
9062
+ * Whether a reactive-brand leaf (`fetchPosts.isPending`,
9063
+ * `fetchPosts.isPending()`) is rooted at the action binding of an async
9064
+ * factory (`const [, fetchPosts] = createQuery(…)`, #3165).
9065
+ */
9066
+ function isAsyncActionLeaf(leaf: ts.Node, ctx: TransformContext): boolean {
9067
+ let node: ts.Node = leaf
9068
+ while (ts.isCallExpression(node) || ts.isPropertyAccessExpression(node)) node = node.expression
9069
+ if (!ts.isIdentifier(node)) return false
9070
+ const name = node.text
9071
+ return ctx.analyzer.signals.some((s) => s.factory?.action === name)
9072
+ }
9073
+
8977
9074
  /**
8978
9075
  * Regex-based signal/memo detection.
8979
9076
  * Complements TypeChecker for cases where imported types can't be resolved.
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Client-JS initializers for signals that `createSignal` does not produce.
3
+ *
4
+ * Two factory families are collected as signals: env signals
5
+ * (`createSearchParams()`, #2057) and async reactive factories
6
+ * (`createQuery(fn, options)`, #3165). Every backend that re-emits a signal
7
+ * declaration into client JS asks this module for the initializer instead of
8
+ * hard-coding `createSignal`, so a new factory kind is one entry here rather
9
+ * than a special case per emit site.
10
+ */
11
+
12
+ import type { SignalInfo } from './types.ts'
13
+ import { ENV_SIGNAL_CLIENT_FACTORY } from './adapters/env-signal.ts'
14
+
15
+ /**
16
+ * The initializer expression that produces this signal's tuple in client JS
17
+ * when it isn't `createSignal(<initialValue>)`, or `null` for an ordinary
18
+ * signal. An async factory re-emits its own call with the authored arguments;
19
+ * an env signal calls its factory with none.
20
+ */
21
+ export function signalFactoryInitializer(signal: SignalInfo): string | null {
22
+ if (signal.factory) return `${signal.factory.callee}(${signal.factory.argsText})`
23
+ if (signal.envReader) {
24
+ const factory = signal.envFactory ?? ENV_SIGNAL_CLIENT_FACTORY[signal.envReader]
25
+ return factory ? `${factory}()` : null
26
+ }
27
+ return null
28
+ }
29
+
30
+ /**
31
+ * The second binding of the signal's tuple as written in the source: the
32
+ * setter for `createSignal` and env signals, the action for an async factory.
33
+ */
34
+ export function signalSecondBinding(signal: SignalInfo): string | null {
35
+ return signal.setter ?? signal.factory?.action ?? null
36
+ }
@@ -34,6 +34,7 @@ import { extractFreeIdentifiersFromNode } from './analyzer.ts'
34
34
  import { resolveGetterAliases, collectAliasableGetterNames } from './ir-to-client-js/csr-substitute.ts'
35
35
  import { resolveBodyDestructuredPropAliases } from './props-binding.ts'
36
36
  import type { IRMetadata } from './types.ts'
37
+ import { isElidedFactoryGetter } from './types.ts'
37
38
 
38
39
  /**
39
40
  * A single template-variable default. Keyed in the manifest by the
@@ -247,6 +248,15 @@ export function extractSsrDefaults(metadata: IRMetadata): Record<string, SsrDefa
247
248
  // request-scoped reader, seeded by the adapter's env-signal binding, not a
248
249
  // baked initial value.
249
250
  if (sig.envReader) continue
251
+ // An elided async-factory value (#3245): `getter` holds a synthesized
252
+ // internal name that no expression in the source ever references.
253
+ // Seeding it here would leak that compiler-internal name into every
254
+ // template-stash backend's manifest (and, transitively, the Perl/etc.
255
+ // stash) for a binding nothing reads. See `isElidedFactoryGetter`'s
256
+ // docstring for the full rationale — a plain `createSignal`
257
+ // getter-elided form is unaffected, a pre-existing, separate question
258
+ // this issue doesn't cover.
259
+ if (isElidedFactoryGetter(sig)) continue
250
260
  const value = tryStaticEval(sig.initialValue, { bindings, propsLike })
251
261
  // Self-derivation collision (#2669): a signal whose getter shares its
252
262
  // name with the prop its OWN initializer derives from
@@ -41,6 +41,7 @@ import {
41
41
  type ParsedExpr,
42
42
  } from './expression-parser.ts'
43
43
  import type { IRMetadata } from './types.ts'
44
+ import { isElidedFactoryGetter } from './types.ts'
44
45
 
45
46
  /**
46
47
  * One binding in component declaration order (signals first, then memos —
@@ -197,7 +198,17 @@ export function computeSsrSeedPlan(metadata: IRMetadata): SsrSeedPlan {
197
198
  }
198
199
  const expr = signal.initialValue.trim()
199
200
  steps.push(
200
- expr === ''
201
+ // An elided async-factory value (#3245): `signal.getter` is a
202
+ // synthesized internal name nothing in the source ever references
203
+ // (see `isElidedFactoryGetter`'s docstring). Forced `opaque` (never
204
+ // `derived`) so an adapter that seeds `derived` steps in-template
205
+ // (Jinja/Erb/Pebble's `generateDerivedMemoSeed`) can't emit a
206
+ // `{% set __bfGet_x = ... %}` for it — the invariant "one step per
207
+ // signal" still holds (the name stays out of every backend's
208
+ // rendered output; only ITS OWN classify outcome is overridden, not
209
+ // the name's presence in `steps`/`available` for other signals'
210
+ // scope checks).
211
+ expr === '' || isElidedFactoryGetter(signal)
201
212
  ? { kind: 'opaque', name: signal.getter, origin: 'signal' }
202
213
  : classify(
203
214
  signal.getter,
@@ -0,0 +1,203 @@
1
+ /**
2
+ * Every template-lowered position in a component's IR, as parsed expressions.
3
+ *
4
+ * Shared by the policy refusals that fire in the IR-build phase ahead of every
5
+ * adapter's `generate()` — `checkAuthoredFormatDateCalls` (BF056) and
6
+ * `checkAsyncActionReads` (BF117) — so "every position a template could
7
+ * render" is decided once. Covered: text expressions, conditional and
8
+ * if-statement conditions, element / component / provider attribute values
9
+ * (expression, spread, and structured template parts), loop arrays, and the
10
+ * children of elements, components, fragments, providers, async boundaries,
11
+ * loops (including child components, nested components, and `flatMap` /
12
+ * preamble JSX segments) and conditional branches.
13
+ *
14
+ * A `/* @client *\/`-marked position (`clientOnly`) is skipped: the whole read
15
+ * is deferred to the client, where real JS evaluates it.
16
+ *
17
+ * Each position also reports its `role` — how the template USES the value
18
+ * there (rendered as text, tested for truthiness, written as an attribute…)
19
+ * — and, for the two roles a pass may rewrite in place, the IR `host` that
20
+ * holds it. The action-accessor seed (`action-accessor.ts`, #3166) reads
21
+ * both: a seed is only sound where it renders like the reference adapter,
22
+ * which depends on the role, and BF117's refusal-lift and the seed itself
23
+ * must see the SAME position set, which is why both ride this one walk.
24
+ * BF056 reads neither.
25
+ */
26
+
27
+ import type {
28
+ AttrValue,
29
+ ExpressionAttr,
30
+ IRConditional,
31
+ IRIfStatement,
32
+ IRNode,
33
+ IRTemplatePart,
34
+ SourceLocation,
35
+ } from './types.ts'
36
+ import type { ParsedExpr } from './expression-parser.ts'
37
+ import { parseExpression } from './expression-parser.ts'
38
+
39
+ /**
40
+ * How the template uses the value at a position:
41
+ *
42
+ * - `text` — an `IRExpression` child, rendered as text.
43
+ * - `condition` — an `IRConditional` / `IRIfStatement` condition, only ever
44
+ * tested for truthiness.
45
+ * - `element-attr` — an intrinsic element's attribute value (an `expression`
46
+ * attr's whole parse), rendered as the attribute.
47
+ * - `prop` — a component prop or a provider's `value`, handed on as a value.
48
+ * - `spread` — a spread bag (`{...x}`), on an element or a component.
49
+ * - `template-part` — a piece of a structured template attribute
50
+ * (`IRTemplatePart` ternary condition / branch, lookup key). These are raw
51
+ * text parsed on demand here; every adapter lowers them from that raw text,
52
+ * so nothing attached to the IR can stand in for them.
53
+ * - `loop-array` — a loop's array expression.
54
+ */
55
+ export type TemplatePositionRole =
56
+ | 'text'
57
+ | 'condition'
58
+ | 'element-attr'
59
+ | 'prop'
60
+ | 'spread'
61
+ | 'template-part'
62
+ | 'loop-array'
63
+
64
+ /**
65
+ * The IR slot a position's `expr` lives in, for a pass that rewrites the
66
+ * position in place (the action-accessor seed). Only the two roles such a
67
+ * pass may rewrite carry one: a `condition` (its `parsedCondition` /
68
+ * `templateCondition`) and an `element-attr` (the `ExpressionAttr`'s
69
+ * `parsed` / `templateExpr`).
70
+ */
71
+ export type TemplatePositionHost =
72
+ | { kind: 'condition'; node: IRConditional | IRIfStatement }
73
+ | { kind: 'element-attr'; value: ExpressionAttr }
74
+
75
+ export interface TemplatePosition {
76
+ expr: ParsedExpr
77
+ loc: SourceLocation
78
+ role: TemplatePositionRole
79
+ /** The attribute or prop name, when the position is an attribute / prop value. */
80
+ attrName?: string
81
+ host?: TemplatePositionHost
82
+ }
83
+
84
+ export function walkTemplatePositions(root: IRNode, visit: (position: TemplatePosition) => void): void {
85
+ walkNode(root, visit)
86
+ }
87
+
88
+ /**
89
+ * `IRTemplatePart.ternary.condition` / `.lookup.key` carry no attached parse
90
+ * (unlike every other position here), so parse on demand. `ternary.whenTrue`
91
+ * / `.whenFalse` are ALSO raw, unparsed text (the per-branch rendered
92
+ * snippet), so they get the same on-demand treatment — this is the
93
+ * `format-date-ternary` shape (#2843): a call in a ternary CONSEQUENT inside a
94
+ * structured template-literal attribute.
95
+ */
96
+ function walkTemplateParts(
97
+ parts: readonly IRTemplatePart[],
98
+ loc: SourceLocation,
99
+ attrName: string | undefined,
100
+ visit: (position: TemplatePosition) => void,
101
+ ): void {
102
+ const visitText = (text: string) => {
103
+ const trimmed = text.trim()
104
+ if (!trimmed) return
105
+ visit({ expr: parseExpression(trimmed), loc, role: 'template-part', attrName })
106
+ }
107
+ for (const part of parts) {
108
+ if (part.type === 'ternary') {
109
+ visitText(part.condition)
110
+ visitText(part.whenTrue)
111
+ visitText(part.whenFalse)
112
+ } else if (part.type === 'lookup') {
113
+ visitText(part.key)
114
+ }
115
+ }
116
+ }
117
+
118
+ function walkAttrValue(
119
+ value: AttrValue,
120
+ clientOnly: boolean | undefined,
121
+ loc: SourceLocation,
122
+ attrName: string,
123
+ onElement: boolean,
124
+ visit: (position: TemplatePosition) => void,
125
+ ): void {
126
+ if (clientOnly) return
127
+ if (value.kind === 'expression') {
128
+ if (value.parsed) {
129
+ visit(
130
+ onElement
131
+ ? { expr: value.parsed, loc, role: 'element-attr', attrName, host: { kind: 'element-attr', value } }
132
+ : { expr: value.parsed, loc, role: 'prop', attrName },
133
+ )
134
+ }
135
+ if (value.parts) walkTemplateParts(value.parts, loc, attrName, visit)
136
+ } else if (value.kind === 'spread') {
137
+ if (value.parsed) visit({ expr: value.parsed, loc, role: 'spread', attrName })
138
+ } else if (value.kind === 'template') {
139
+ walkTemplateParts(value.parts, loc, attrName, visit)
140
+ }
141
+ }
142
+
143
+ function walkNode(node: IRNode, visit: (position: TemplatePosition) => void): void {
144
+ if (node.type === 'expression') {
145
+ if (!node.clientOnly && node.parsed) visit({ expr: node.parsed, loc: node.loc, role: 'text' })
146
+ } else if (node.type === 'conditional') {
147
+ if (!node.clientOnly && node.parsedCondition) {
148
+ visit({ expr: node.parsedCondition, loc: node.loc, role: 'condition', host: { kind: 'condition', node } })
149
+ }
150
+ } else if (node.type === 'if-statement') {
151
+ if (node.parsedCondition) {
152
+ visit({ expr: node.parsedCondition, loc: node.loc, role: 'condition', host: { kind: 'condition', node } })
153
+ }
154
+ }
155
+
156
+ if (node.type === 'element') {
157
+ for (const attr of node.attrs) walkAttrValue(attr.value, attr.clientOnly, attr.loc, attr.name, true, visit)
158
+ } else if (node.type === 'component') {
159
+ for (const prop of node.props) walkAttrValue(prop.value, prop.clientOnly, prop.loc, prop.name, false, visit)
160
+ } else if (node.type === 'provider') {
161
+ walkAttrValue(node.valueProp.value, node.valueProp.clientOnly, node.valueProp.loc, 'value', false, visit)
162
+ }
163
+
164
+ switch (node.type) {
165
+ case 'element':
166
+ case 'component':
167
+ case 'fragment':
168
+ case 'provider':
169
+ for (const child of node.children) walkNode(child, visit)
170
+ break
171
+ case 'async':
172
+ walkNode(node.fallback, visit)
173
+ for (const child of node.children) walkNode(child, visit)
174
+ break
175
+ case 'loop': {
176
+ if (node.clientOnly) break
177
+ if (node.arrayParsed) visit({ expr: node.arrayParsed, loc: node.loc, role: 'loop-array' })
178
+ for (const child of node.children) walkNode(child, visit)
179
+ if (node.childComponent) {
180
+ for (const child of node.childComponent.children) walkNode(child, visit)
181
+ }
182
+ for (const nested of node.nestedComponents ?? []) {
183
+ for (const child of nested.children) walkNode(child, visit)
184
+ }
185
+ for (const seg of node.flatMapCallback?.segments ?? []) {
186
+ if (seg.kind === 'jsx') walkNode(seg.ir, visit)
187
+ }
188
+ for (const seg of node.preamble?.segments ?? []) {
189
+ if (seg.kind === 'jsx') walkNode(seg.ir, visit)
190
+ }
191
+ break
192
+ }
193
+ case 'conditional':
194
+ if (node.clientOnly) break
195
+ walkNode(node.whenTrue, visit)
196
+ walkNode(node.whenFalse, visit)
197
+ break
198
+ case 'if-statement':
199
+ walkNode(node.consequent, visit)
200
+ if (node.alternate) walkNode(node.alternate, visit)
201
+ break
202
+ }
203
+ }
package/src/types.ts CHANGED
@@ -1515,6 +1515,29 @@ export interface IRAttribute extends AttrMeta {
1515
1515
  * same opt-out, applied to element-attribute position.
1516
1516
  */
1517
1517
  clientOnly?: boolean
1518
+ /**
1519
+ * Set when this attribute entry was produced by statically expanding a
1520
+ * closed-type `{...rest}` spread onto one of its known keys
1521
+ * (`expandSpreadAttribute`'s per-key branch, jsx-to-ir.ts) — #3057. The
1522
+ * expanded value (`<restName>.<key>`) reads the destructured rest
1523
+ * OBJECT, a one-time snapshot built at component-init time, so Phase 2's
1524
+ * string-level reactivity heuristics (`needsEffectWrapper`) never
1525
+ * recognize it as reading a live prop the way a bare destructured
1526
+ * parameter does — `rest` isn't itself a tracked prop name, and neither
1527
+ * is the expanded key. Without this flag the attribute is silently
1528
+ * treated as static: it renders once from SSR/the initial client
1529
+ * construction and never updates again, even though the value the child
1530
+ * forwards is exactly as live as any other prop.
1531
+ *
1532
+ * `collectElements` reads this to unconditionally push the attribute
1533
+ * into `ctx.reactiveAttrs`, rewriting its expression onto a live
1534
+ * `_p.<key>` read instead of the snapshot `<restName>.<key>` — the same
1535
+ * write shape `emitAttrUpdate` already produces for a developer-authored
1536
+ * reactive attribute, so a forwarded rest key updates reactively end to
1537
+ * end (undefined → present, present → absent → present again) exactly
1538
+ * like SSR / hydrated / csr-mount agree it should.
1539
+ */
1540
+ restExpandedKey?: boolean
1518
1541
  }
1519
1542
 
1520
1543
  export interface IREvent {
@@ -1637,6 +1660,71 @@ export interface SignalInfo {
1637
1660
  * actually in scope, not a hardcoded canonical name (#2057).
1638
1661
  */
1639
1662
  envFactory?: string
1663
+ /**
1664
+ * Set when this signal is the value half of an async reactive factory
1665
+ * (`const [posts, action] = createQuery(fn, options)`, #3165) rather than
1666
+ * `createSignal`. The getter is a normal reactive getter (so it seeds,
1667
+ * substitutes and folds like any signal), and `initialValue` is the
1668
+ * `options.initial` expression — the literal `undefined` when the call has
1669
+ * no `initial`. `setter` is always `null`: the second tuple binding is
1670
+ * the factory's action, recorded here, never a setter.
1671
+ */
1672
+ factory?: SignalFactoryCall
1673
+ }
1674
+
1675
+ /**
1676
+ * True for the value-elided form of an async reactive factory declaration
1677
+ * (`const [, save] = createMutation(...)`, #3245): `signal.getter` then
1678
+ * holds the synthesized internal name (`__bfGet_<action>`, see
1679
+ * `SignalInfo.getterElided`'s docstring) that nothing in the source ever
1680
+ * references. Every consumer that would otherwise re-emit or seed that name
1681
+ * into caller-facing output (an SSR getter stub, a props struct/constructor
1682
+ * field, an SSR-defaults manifest entry, an SSR seed-plan step) checks this
1683
+ * first and skips it — see `bf debug graph`'s `debug.ts` precedent (#3227)
1684
+ * this generalizes.
1685
+ *
1686
+ * A plain `createSignal` getter-elided form (`const [, setX] =
1687
+ * createSignal(0)`) is NOT covered by this predicate, even though
1688
+ * `analyzer.ts`'s synthesis and `SignalInfo.getterElided`'s own docstring
1689
+ * make clear its getter is *equally* synthesized and unreferenced — it
1690
+ * leaks `__bfGet_<setter>` through the exact same sites today. #3245 scoped
1691
+ * this fix to the `factory` case only; widening this predicate to plain
1692
+ * `getterElided` (dropping the `factory` restriction) would close that gap
1693
+ * too, but is left for a separate follow-up rather than folded in here.
1694
+ */
1695
+ export function isElidedFactoryGetter(signal: Pick<SignalInfo, 'factory' | 'getterElided'>): boolean {
1696
+ return Boolean(signal.factory && signal.getterElided)
1697
+ }
1698
+
1699
+ /**
1700
+ * The async reactive factory call a signal's value comes from (#3165). Every
1701
+ * backend that re-emits the declaration reads this instead of assuming
1702
+ * `createSignal`: client JS re-emits `<callee>(<argsText>)` (the request
1703
+ * function is never evaluated on the server), and SSR seeds the value from
1704
+ * `initialValue` like any other signal.
1705
+ */
1706
+ export interface SignalFactoryCall {
1707
+ /** Which factory: `createQuery` (#3165) or `createMutation` (#3210). */
1708
+ kind: 'query' | 'mutation'
1709
+ /** The callee as written: `createQuery` / `createMutation`, an alias, or `bf.createQuery`. */
1710
+ callee: string
1711
+ /**
1712
+ * The call's argument list as JS (type annotations stripped), emitted
1713
+ * verbatim into the client `init` body, where the props-rewrite passes turn
1714
+ * prop reads into live `_p` reads like any effect body.
1715
+ */
1716
+ argsText: string
1717
+ /**
1718
+ * The request function alone (the first argument, type annotations
1719
+ * stripped) and its free identifiers — `''` / empty when the call has no
1720
+ * argument. Kept apart from `argsText` because only the request function is
1721
+ * tracked: `options` (`initial`, `ttl`, `invalidates`) is read once, at
1722
+ * creation, so a signal read there re-sends nothing (`bf debug graph`, #3167).
1723
+ */
1724
+ requestText: string
1725
+ requestFreeIdentifiers: ReadonlySet<string>
1726
+ /** The action binding (the second tuple element), or `null` when it isn't destructured. */
1727
+ action: string | null
1640
1728
  }
1641
1729
 
1642
1730
  export interface MemoInfo {
@@ -1966,6 +2054,11 @@ export interface FunctionInfo {
1966
2054
  * migration; legacy emit paths default to inferring from `body`.
1967
2055
  */
1968
2056
  declarationKind?: 'function' | 'arrow' | 'function-expression'
2057
+ /**
2058
+ * Free identifiers of the function (parameters excluded), computed from the
2059
+ * AST: what its body reads when it is called.
2060
+ */
2061
+ freeIdentifiers?: ReadonlySet<string>
1969
2062
  /** When true, declared at module level (outside the component function). */
1970
2063
  isModule?: boolean
1971
2064
  /** When true, this function returns JSX and is inlined at call sites (#569). */
@@ -2019,6 +2112,12 @@ export interface ConstantInfo {
2019
2112
  isJsxFunction?: boolean
2020
2113
  /** When true, the initializer contains an arrow function or function expression (computed from AST). */
2021
2114
  containsArrow?: boolean
2115
+ /**
2116
+ * When true, the initializer IS an arrow function or function expression
2117
+ * (`const status = () => …`), so reading the constant yields a function and
2118
+ * only calling it evaluates the body. Computed from the AST.
2119
+ */
2120
+ isFunctionValue?: boolean
2022
2121
  /**
2023
2122
  * When true, a same-scope statement (a `for`/`while` body, or any other
2024
2123
  * imperative statement) mutates this binding's value AFTER its