@barefootjs/jsx 0.40.0 → 0.40.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 (140) hide show
  1. package/dist/adapters/ambiguous-nil-arithmetic.d.ts +41 -0
  2. package/dist/adapters/ambiguous-nil-arithmetic.d.ts.map +1 -0
  3. package/dist/adapters/attr-plan.d.ts.map +1 -1
  4. package/dist/adapters/boolean-carrier.d.ts +31 -0
  5. package/dist/adapters/boolean-carrier.d.ts.map +1 -0
  6. package/dist/adapters/component-props.d.ts +22 -7
  7. package/dist/adapters/component-props.d.ts.map +1 -1
  8. package/dist/adapters/computed-const.d.ts +17 -0
  9. package/dist/adapters/computed-const.d.ts.map +1 -1
  10. package/dist/adapters/dsl-template-adapter.d.ts +18 -1
  11. package/dist/adapters/dsl-template-adapter.d.ts.map +1 -1
  12. package/dist/adapters/number-value.d.ts +43 -0
  13. package/dist/adapters/number-value.d.ts.map +1 -0
  14. package/dist/analyzer-context.d.ts +7 -0
  15. package/dist/analyzer-context.d.ts.map +1 -1
  16. package/dist/analyzer.d.ts +34 -0
  17. package/dist/analyzer.d.ts.map +1 -1
  18. package/dist/expression-parser.d.ts.map +1 -1
  19. package/dist/index.d.ts +6 -3
  20. package/dist/index.d.ts.map +1 -1
  21. package/dist/index.js +1006 -351
  22. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  23. package/dist/ir-to-client-js/control-flow/plan/build-component-loop.d.ts.map +1 -1
  24. package/dist/ir-to-client-js/control-flow/plan/build-inner-loop.d.ts +29 -0
  25. package/dist/ir-to-client-js/control-flow/plan/build-inner-loop.d.ts.map +1 -1
  26. package/dist/ir-to-client-js/control-flow/plan/build-lazy-row.d.ts +2 -0
  27. package/dist/ir-to-client-js/control-flow/plan/build-lazy-row.d.ts.map +1 -1
  28. package/dist/ir-to-client-js/control-flow/plan/build-loop-child-arm.d.ts.map +1 -1
  29. package/dist/ir-to-client-js/control-flow/plan/build-reactive-effects.d.ts.map +1 -1
  30. package/dist/ir-to-client-js/control-flow/plan/inner-loop.d.ts +5 -4
  31. package/dist/ir-to-client-js/control-flow/plan/inner-loop.d.ts.map +1 -1
  32. package/dist/ir-to-client-js/control-flow/plan/loop-child-arm.d.ts +2 -0
  33. package/dist/ir-to-client-js/control-flow/plan/loop-child-arm.d.ts.map +1 -1
  34. package/dist/ir-to-client-js/control-flow/plan/loop.d.ts +15 -0
  35. package/dist/ir-to-client-js/control-flow/plan/loop.d.ts.map +1 -1
  36. package/dist/ir-to-client-js/control-flow/plan/reactive-effects.d.ts +2 -0
  37. package/dist/ir-to-client-js/control-flow/plan/reactive-effects.d.ts.map +1 -1
  38. package/dist/ir-to-client-js/control-flow/shared.d.ts.map +1 -1
  39. package/dist/ir-to-client-js/control-flow/stringify/claim-plan.d.ts +20 -0
  40. package/dist/ir-to-client-js/control-flow/stringify/claim-plan.d.ts.map +1 -1
  41. package/dist/ir-to-client-js/control-flow/stringify/component-loop.d.ts.map +1 -1
  42. package/dist/ir-to-client-js/control-flow/stringify/event-listener.d.ts +1 -1
  43. package/dist/ir-to-client-js/control-flow/stringify/event-listener.d.ts.map +1 -1
  44. package/dist/ir-to-client-js/control-flow/stringify/lazy-row.d.ts.map +1 -1
  45. package/dist/ir-to-client-js/html-template.d.ts +3 -2
  46. package/dist/ir-to-client-js/html-template.d.ts.map +1 -1
  47. package/dist/ir-to-client-js/plan/build-static-array-child-init.d.ts.map +1 -1
  48. package/dist/ir-to-client-js/plan/static-array-child-init.d.ts +7 -1
  49. package/dist/ir-to-client-js/plan/static-array-child-init.d.ts.map +1 -1
  50. package/dist/ir-to-client-js/reactivity.d.ts.map +1 -1
  51. package/dist/ir-to-client-js/safe-html.d.ts +9 -3
  52. package/dist/ir-to-client-js/safe-html.d.ts.map +1 -1
  53. package/dist/ir-to-client-js/stringify/static-array-child-init.d.ts.map +1 -1
  54. package/dist/ir-to-client-js/types.d.ts +30 -0
  55. package/dist/ir-to-client-js/types.d.ts.map +1 -1
  56. package/dist/ir-to-client-js/utils.d.ts +8 -0
  57. package/dist/ir-to-client-js/utils.d.ts.map +1 -1
  58. package/dist/jsx-to-ir.d.ts.map +1 -1
  59. package/dist/nullable-signal-attr.d.ts +29 -3
  60. package/dist/nullable-signal-attr.d.ts.map +1 -1
  61. package/dist/props-binding.d.ts +27 -3
  62. package/dist/props-binding.d.ts.map +1 -1
  63. package/dist/scope/binding-scope.d.ts +22 -1
  64. package/dist/scope/binding-scope.d.ts.map +1 -1
  65. package/dist/scope/root-prop-alias.d.ts +14 -1
  66. package/dist/scope/root-prop-alias.d.ts.map +1 -1
  67. package/dist/signal-prop-name-collision.d.ts.map +1 -1
  68. package/dist/ssr-defaults.d.ts +4 -2
  69. package/dist/ssr-defaults.d.ts.map +1 -1
  70. package/dist/ssr-seed-plan.d.ts +14 -0
  71. package/dist/ssr-seed-plan.d.ts.map +1 -1
  72. package/dist/template-parts.d.ts.map +1 -1
  73. package/dist/types.d.ts +30 -0
  74. package/dist/types.d.ts.map +1 -1
  75. package/package.json +2 -2
  76. package/src/__tests__/binding-scope-ratchet.test.ts +12 -2
  77. package/src/__tests__/boolean-carrier.test.ts +74 -0
  78. package/src/__tests__/component-props.test.ts +14 -0
  79. package/src/__tests__/computed-const.test.ts +85 -0
  80. package/src/__tests__/expression-parser.test.ts +24 -0
  81. package/src/__tests__/issue-3688-props-spread-child-csr.test.ts +142 -0
  82. package/src/__tests__/loop-row-prop-read.test.ts +111 -0
  83. package/src/__tests__/memo-body-expr.test.ts +137 -0
  84. package/src/__tests__/nullable-signal-attr.test.ts +97 -2
  85. package/src/__tests__/profile-binding-ids.test.ts +14 -0
  86. package/src/__tests__/root-prop-alias.test.ts +34 -1
  87. package/src/__tests__/signal-prop-name-collision.test.ts +102 -2
  88. package/src/__tests__/source-file-cache.test.ts +105 -0
  89. package/src/__tests__/ssr-seed-plan.test.ts +43 -0
  90. package/src/__tests__/template-parts-literal-boundary.test.ts +19 -0
  91. package/src/adapters/ambiguous-nil-arithmetic.ts +94 -0
  92. package/src/adapters/attr-plan.ts +6 -2
  93. package/src/adapters/boolean-carrier.ts +76 -0
  94. package/src/adapters/component-props.ts +28 -8
  95. package/src/adapters/computed-const.ts +206 -7
  96. package/src/adapters/dsl-template-adapter.ts +39 -0
  97. package/src/adapters/number-value.ts +95 -0
  98. package/src/analyzer-context.ts +8 -0
  99. package/src/analyzer.ts +187 -66
  100. package/src/expression-parser.ts +4 -1
  101. package/src/index.ts +12 -2
  102. package/src/ir-to-client-js/collect-elements.ts +104 -46
  103. package/src/ir-to-client-js/compute-inlinability.ts +1 -1
  104. package/src/ir-to-client-js/control-flow/plan/build-component-loop.ts +15 -1
  105. package/src/ir-to-client-js/control-flow/plan/build-inner-loop.ts +79 -4
  106. package/src/ir-to-client-js/control-flow/plan/build-lazy-row.ts +3 -0
  107. package/src/ir-to-client-js/control-flow/plan/build-loop-child-arm.ts +1 -0
  108. package/src/ir-to-client-js/control-flow/plan/build-reactive-effects.ts +1 -0
  109. package/src/ir-to-client-js/control-flow/plan/inner-loop.ts +5 -4
  110. package/src/ir-to-client-js/control-flow/plan/loop-child-arm.ts +2 -0
  111. package/src/ir-to-client-js/control-flow/plan/loop.ts +12 -0
  112. package/src/ir-to-client-js/control-flow/plan/reactive-effects.ts +2 -0
  113. package/src/ir-to-client-js/control-flow/shared.ts +3 -2
  114. package/src/ir-to-client-js/control-flow/stringify/claim-plan.ts +27 -0
  115. package/src/ir-to-client-js/control-flow/stringify/component-loop.ts +8 -2
  116. package/src/ir-to-client-js/control-flow/stringify/event-listener.ts +8 -1
  117. package/src/ir-to-client-js/control-flow/stringify/inner-loop.ts +8 -7
  118. package/src/ir-to-client-js/control-flow/stringify/lazy-row.ts +8 -7
  119. package/src/ir-to-client-js/control-flow/stringify/loop-child-arm.ts +4 -4
  120. package/src/ir-to-client-js/control-flow/stringify/loop.ts +3 -3
  121. package/src/ir-to-client-js/control-flow/stringify/reactive-effects.ts +6 -6
  122. package/src/ir-to-client-js/emit-reactive.ts +1 -1
  123. package/src/ir-to-client-js/html-template.ts +70 -30
  124. package/src/ir-to-client-js/plan/build-static-array-child-init.ts +11 -1
  125. package/src/ir-to-client-js/plan/static-array-child-init.ts +7 -1
  126. package/src/ir-to-client-js/reactivity.ts +14 -0
  127. package/src/ir-to-client-js/safe-html.ts +11 -4
  128. package/src/ir-to-client-js/stringify/static-array-child-init.ts +6 -4
  129. package/src/ir-to-client-js/types.ts +23 -0
  130. package/src/ir-to-client-js/utils.ts +15 -1
  131. package/src/jsx-to-ir.ts +78 -35
  132. package/src/nullable-signal-attr.ts +134 -13
  133. package/src/props-binding.ts +54 -3
  134. package/src/scope/binding-scope.ts +30 -2
  135. package/src/scope/root-prop-alias.ts +17 -1
  136. package/src/signal-prop-name-collision.ts +113 -22
  137. package/src/ssr-defaults.ts +10 -4
  138. package/src/ssr-seed-plan.ts +82 -17
  139. package/src/template-parts.ts +21 -1
  140. package/src/types.ts +30 -0
package/src/jsx-to-ir.ts CHANGED
@@ -55,7 +55,7 @@ import {
55
55
  collectAstPropRefs,
56
56
  rewriteScopedValueRefs,
57
57
  } from './prop-rewrite.ts'
58
- import { boundPropLocalNames, buildPropAliasMap, isPropsAliasConst, isRenamedBodyPropParam, keepsDeclaredValue, resolveAliasOrigin, resolveRestSpreadOriginCore, livePropReadExpr } from './props-binding.ts'
58
+ import { boundPropLocalNames, buildPropAliasMap, templatePropReadParams, resolveAliasOrigin, resolveRestSpreadOriginCore, livePropReadExpr } from './props-binding.ts'
59
59
  import { PROPS_PARAM } from './ir-to-client-js/utils.ts'
60
60
  import { walkIR } from './ir-to-client-js/walker.ts'
61
61
  import { resolveFreeRefs, rebindHelperParamRefs, isNameBound as isNameBoundInEnv, type BindingEnvironment } from './free-refs.ts'
@@ -745,8 +745,7 @@ function collectBranchLocalPropRefsViaSubstitution(
745
745
  */
746
746
  function getDestructuredPropNames(ctx: TransformContext): Set<string> | null {
747
747
  if (ctx._destructuredPropNames === undefined) {
748
- const shadowed = propShadowingNames(ctx.analyzer)
749
- const eligible = ctx.analyzer.propsParams.filter(p => !shadowed.has(p.name))
748
+ const eligible = templatePropReadParams(ctx.analyzer)
750
749
  const names = eligible.map(p => p.name)
751
750
  ctx._destructuredPropNames = names.length > 0 ? new Set(names) : null
752
751
  ctx._destructuredPropAliases = buildPropAliasMap(eligible) ?? null
@@ -762,35 +761,6 @@ function getDestructuredPropNames(ctx: TransformContext): Set<string> | null {
762
761
  return ctx._destructuredPropNames ?? null
763
762
  }
764
763
 
765
- /**
766
- * The component-scope names that shadow a prop of the same name in a
767
- * `(props)`-arg component (`getDestructuredPropNames`' shadow guard): its
768
- * signals, memos and locals, except a local that is the prop itself.
769
- */
770
- function propShadowingNames(analyzer: AnalyzerContext): Set<string> {
771
- const shadowed = new Set<string>()
772
- if (!analyzer.propsObjectName) return shadowed
773
- for (const s of analyzer.signals) {
774
- shadowed.add(s.getter)
775
- if (s.setter) shadowed.add(s.setter)
776
- }
777
- for (const m of analyzer.memos) shadowed.add(m.name)
778
- for (const c of analyzer.localConstants) {
779
- // A body destructure binding that is reassigned or mutated no longer
780
- // holds its prop, renamed or not, so the template keeps it a local.
781
- if (c.propsDestructure && !keepsDeclaredValue(c)) {
782
- shadowed.add(c.name)
783
- continue
784
- }
785
- if (isPropsAliasConst(c, analyzer.propsObjectName)) continue
786
- // A renamed body binding with a default reads as its own prop entry,
787
- // like the parameter form (#3579).
788
- if (isRenamedBodyPropParam(c, analyzer.propsParams)) continue
789
- shadowed.add(c.name)
790
- }
791
- return shadowed
792
- }
793
-
794
764
  /**
795
765
  * Companion to `getDestructuredPropNames`: local-name → `ParamInfo` for the
796
766
  * same shadow-filtered eligible set. Both caches are written in one pass.
@@ -1186,6 +1156,61 @@ function childrenReadOf(
1186
1156
  return readsProps && isPropsChildrenMember(parsed, analyzer) ? 'bare' : null
1187
1157
  }
1188
1158
 
1159
+ /**
1160
+ * Whether `parsed`, read in the component scope, is `<props object>.<name>`
1161
+ * for a prop other than `children` (`props.footer`, `p.footer` for `const p
1162
+ * = props`).
1163
+ */
1164
+ function isPropsValueMember(parsed: ParsedExpr | undefined, analyzer: AnalyzerContext): boolean {
1165
+ return (
1166
+ parsed?.kind === 'member' &&
1167
+ !parsed.computed &&
1168
+ parsed.property !== 'children' &&
1169
+ parsed.object.kind === 'identifier' &&
1170
+ isPropsObjectBinding(parsed.object.name, analyzer)
1171
+ )
1172
+ }
1173
+
1174
+ /**
1175
+ * Whether the component-scope name `name` holds one of the component's own
1176
+ * props other than `children`: a destructured props param (renamed or not),
1177
+ * a body destructure or member read of the props object (`const { footer }
1178
+ * = props`, `const f = props.footer`), or a const alias hop of one.
1179
+ */
1180
+ function isPropValueBinding(name: string, analyzer: AnalyzerContext): boolean {
1181
+ const consts = childrenHopConstants(analyzer)
1182
+ const params = boundPropLocalNames(analyzer)
1183
+ const terminal = (n: string): true | null => {
1184
+ if (consts.has(n)) return isPropsValueMember(consts.get(n), analyzer) ? true : null
1185
+ return params.has(n) && !analyzer.propsParams.some(p => p.name === n && isChildrenPropParam(p)) ? true : null
1186
+ }
1187
+ return resolveAliasOrigin(childrenAliasHops(analyzer), name, terminal) === true
1188
+ }
1189
+
1190
+ /**
1191
+ * Whether a child-position expression inside a loop row is a bare read of one
1192
+ * of the component's own props other than `children`
1193
+ * (`IRExpression.loopRowPropRead`). A name or `props` object the enclosing
1194
+ * loop rows bind shadows the prop.
1195
+ */
1196
+ function isLoopRowPropRead(parsed: ParsedExpr, analyzer: AnalyzerContext, scope: BindingScope): boolean {
1197
+ if (!scope.insideLoopRow()) return false
1198
+ if (parsed.kind === 'identifier') return !scope.isBound(parsed.name) && isPropValueBinding(parsed.name, analyzer)
1199
+ return (
1200
+ parsed.kind === 'member' &&
1201
+ parsed.object.kind === 'identifier' &&
1202
+ !scope.isBound(parsed.object.name) &&
1203
+ isPropsValueMember(parsed, analyzer)
1204
+ )
1205
+ }
1206
+
1207
+ /** Set `childrenRead` and `loopRowPropRead` on an expression child from its parse. */
1208
+ function attachPropReadFlags(node: IRExpression, parsed: ParsedExpr, analyzer: AnalyzerContext, scope: BindingScope): void {
1209
+ const childrenRead = childrenReadOf(parsed, analyzer, scope)
1210
+ if (childrenRead) node.childrenRead = childrenRead
1211
+ if (isLoopRowPropRead(parsed, analyzer, scope)) node.loopRowPropRead = true
1212
+ }
1213
+
1189
1214
  /**
1190
1215
  * Attach `parsed` to every expression-valued attribute / prop so adapters can
1191
1216
  * lower from the tree instead of re-parsing the string. Element attrs,
@@ -1242,8 +1267,7 @@ function attachParsedExpressions(node: IRNode, analyzer: AnalyzerContext, scope:
1242
1267
  if (node.type === 'expression') {
1243
1268
  const trimmed = node.expr.trim()
1244
1269
  if (trimmed) node.parsed = parse(trimmed)
1245
- const childrenRead = node.parsed ? childrenReadOf(node.parsed, analyzer, scope) : null
1246
- if (childrenRead) node.childrenRead = childrenRead
1270
+ if (node.parsed) attachPropReadFlags(node, node.parsed, analyzer, scope)
1247
1271
  } else if (node.type === 'conditional' || node.type === 'if-statement') {
1248
1272
  const trimmed = node.condition.trim()
1249
1273
  if (trimmed) node.parsedCondition = parse(trimmed)
@@ -9019,7 +9043,7 @@ function processComponentProps(
9019
9043
  // rewrite, so `IRProp` declares no such field. Strip it here rather
9020
9044
  // than letting the shared helper's per-key marking leak into IRProp
9021
9045
  // as an inert flag nothing reads.
9022
- props.push(...expandSpreadAttribute(attr, ctx).map(({ restExpandedKey: _restExpandedKey, ...prop }) => prop))
9046
+ props.push(...expandSpreadAttribute(attr, ctx).map(({ restExpandedKey: _restExpandedKey, ...prop }) => markPropsObjectSpread(prop, ctx)))
9023
9047
  continue
9024
9048
  }
9025
9049
 
@@ -9826,6 +9850,25 @@ function forwardsCallerRestProps(attrs: IRAttribute[], ctx: TransformContext): b
9826
9850
  return false
9827
9851
  }
9828
9852
 
9853
+ /**
9854
+ * Mark a child-component spread of the component's own props object
9855
+ * (`SpreadAttr.propsObject`, #3688). Resolved with the same rule — and the
9856
+ * same `expr` / `templateExpr` pair — as `forwardsCallerRestProps`, narrowed
9857
+ * to the `'props'` origin: a `{...rest}` bag leaves out the keys the
9858
+ * component destructured, so it does not merge as the caller's props.
9859
+ */
9860
+ function markPropsObjectSpread<T extends { value: AttrValue }>(prop: T, ctx: TransformContext): T {
9861
+ const value = prop.value
9862
+ if (value.kind !== 'spread') return prop
9863
+ const constants = constantValuesByName(ctx)
9864
+ for (const name of new Set([value.expr, value.templateExpr])) {
9865
+ if (name && resolveRestSpreadOriginCore(ctx.analyzer, constants, name) === 'props') {
9866
+ return { ...prop, value: { ...value, propsObject: true } }
9867
+ }
9868
+ }
9869
+ return prop
9870
+ }
9871
+
9829
9872
  /** `ctx.analyzer.localConstants` indexed by name → value text, memoized per component walk. */
9830
9873
  function constantValuesByName(ctx: TransformContext): ReadonlyMap<string, string | undefined> {
9831
9874
  if (ctx._constantValuesByName) return ctx._constantValuesByName
@@ -16,6 +16,7 @@
16
16
  */
17
17
 
18
18
  import type { ParsedExpr } from './expression-parser.ts'
19
+ import { BindingScope } from './scope/binding-scope.ts'
19
20
  import type { ComponentIR, MemoInfo, SignalInfo, TypeInfo } from './types.ts'
20
21
 
21
22
  function isNullishType(type: TypeInfo): boolean {
@@ -189,10 +190,12 @@ export interface NullishAttrContext {
189
190
  * decides. A prop whose type admits `null` (`n: number | null`) reads its
190
191
  * nil as `null`. A prop that can only be absent (`n?: number`,
191
192
  * `n: number | undefined`) reads it as `undefined`; a present value, `0`
192
- * included, is unaffected. A prop that admits both (`n?: number | null`)
193
- * keeps the `null` reading: its nil can be either.
193
+ * included, is unaffected. A prop that admits both (`n?: number | null`,
194
+ * `n: number | null | undefined`) is `'either'`: the type cannot say which
195
+ * one its nil stands for, so arithmetic over it is refused
196
+ * (`arithmeticOperandNilIsAmbiguous`).
194
197
  */
195
- export type NullableNumberPropNil = 'null' | 'undefined'
198
+ export type NullableNumberPropNil = 'null' | 'undefined' | 'either'
196
199
 
197
200
  export function collectNullishAttrContext(ir: ComponentIR): NullishAttrContext {
198
201
  const signals = ir.metadata.signals ?? []
@@ -218,10 +221,11 @@ function nullableNumberPropNil(type: TypeInfo | undefined, optional: boolean): N
218
221
  const members = type.kind === 'union' ? (type.unionTypes ?? []) : [type]
219
222
  const families = new Set(members.map(m => (m.kind === 'primitive' ? m.primitive : m.kind)))
220
223
  const admitsNull = families.has('null')
221
- const nullable = optional || admitsNull || families.has('undefined')
224
+ const admitsAbsent = optional || families.has('undefined')
222
225
  families.delete('null')
223
226
  families.delete('undefined')
224
- if (!nullable || families.size !== 1 || !families.has('number')) return null
227
+ if (!(admitsNull || admitsAbsent) || families.size !== 1 || !families.has('number')) return null
228
+ if (admitsNull && admitsAbsent) return 'either'
225
229
  return admitsNull ? 'null' : 'undefined'
226
230
  }
227
231
 
@@ -230,7 +234,7 @@ function collectNullableNumberProps(ir: ComponentIR): ReadonlyMap<string, Nullab
230
234
  const objectName = ir.metadata.propsObjectName
231
235
  for (const p of ir.metadata.propsParams) {
232
236
  if (p.isRest || p.defaultValue !== undefined) continue
233
- const nil = nullableNumberPropNil(p.type, p.optional)
237
+ const nil = nullableNumberPropNil(p.declaredType ?? p.type, p.optional)
234
238
  if (nil !== null) names.set(objectName ? `${objectName}.${p.sourceName ?? p.name}` : p.name, nil)
235
239
  }
236
240
  return names
@@ -249,6 +253,8 @@ function collectNullableNumberProps(ir: ComponentIR): ReadonlyMap<string, Nullab
249
253
  * (`pair[1]`, `row[key]`), or a member read of a value that can itself be
250
254
  * nullish;
251
255
  * - a ternary branch, or an `??` / `||` / `&&` operand the result can be;
256
+ * - a method call that reads `undefined` when nothing is there
257
+ * (`word.at(-1)`, `items.find(...)`, {@link methodMayReturnUndefined});
252
258
  * - a literal `undefined` / `null`.
253
259
  *
254
260
  * Like the bare-signal guard it is presence-only: a non-nil value renders
@@ -267,6 +273,7 @@ export function attrValueMayBeNullish(
267
273
  // loop bindings at the top level, none inside a memo body — its getters
268
274
  // resolve where the memo is declared, not where it is read.
269
275
  const walk = (expr: ParsedExpr, shadowed: (name: string) => boolean): boolean => {
276
+ if (methodMayReturnUndefined(expr)) return true
270
277
  switch (expr.kind) {
271
278
  case 'identifier':
272
279
  return expr.name === 'undefined'
@@ -303,6 +310,24 @@ export function attrValueMayBeNullish(
303
310
  return parsed !== undefined && walk(parsed, isShadowed)
304
311
  }
305
312
 
313
+ /** Array / string methods that read `undefined` when nothing matches. */
314
+ const UNDEFINED_ON_MISS_METHODS: ReadonlySet<string> = new Set(['find', 'findLast'])
315
+
316
+ /**
317
+ * Whether `expr` is a method call that reads `undefined` for some receiver:
318
+ * `.at(i)` out of range (an empty string or array included, `''.at(-1)`),
319
+ * or `.find()` / `.findLast()` with no matching element.
320
+ */
321
+ function methodMayReturnUndefined(expr: ParsedExpr): boolean {
322
+ if (expr.kind === 'array-method') return expr.method === 'at'
323
+ return (
324
+ expr.kind === 'call' &&
325
+ expr.callee.kind === 'member' &&
326
+ !expr.callee.computed &&
327
+ UNDEFINED_ON_MISS_METHODS.has(expr.callee.property)
328
+ )
329
+ }
330
+
306
331
  /**
307
332
  * Whether an arithmetic operand's SSR value is certainly `null` — a literal
308
333
  * `null`, a read of a signal seeded with `null`, or a memo whose body is
@@ -317,7 +342,8 @@ export function arithmeticOperandIsNull(
317
342
  ctx: NullishAttrContext,
318
343
  isShadowed: (name: string) => boolean = () => false,
319
344
  ): boolean {
320
- return arithmeticOperandSeed(parsed, ctx, isShadowed) === 'null'
345
+ const seed = arithmeticOperandSeed(parsed, ctx, isShadowed)
346
+ return seed === 'null' || seed === 'either'
321
347
  }
322
348
 
323
349
  /**
@@ -339,9 +365,11 @@ export function arithmeticOperandIsUndefined(
339
365
  * What an arithmetic operand's SSR nil stands for: `'null'` / `'undefined'`
340
366
  * when the operand is that value (a nullable number prop's `null` reading
341
367
  * included), `'absent'` when it is a number prop that may be absent
342
- * (`n?: number`), whose nil is `undefined` but which may hold a number.
368
+ * (`n?: number`), whose nil is `undefined` but which may hold a number,
369
+ * `'either'` when it is a number prop whose nil may be either
370
+ * (`n?: number | null`).
343
371
  */
344
- type OperandSeed = 'null' | 'undefined' | 'absent' | null
372
+ type OperandSeed = 'null' | 'undefined' | 'absent' | 'either' | null
345
373
 
346
374
  function arithmeticOperandSeed(
347
375
  parsed: ParsedExpr | undefined,
@@ -353,7 +381,7 @@ function arithmeticOperandSeed(
353
381
  if (expr.kind === 'literal') return expr.literalType === 'null' ? 'null' : null
354
382
  if (expr.kind === 'identifier' && expr.name === 'undefined' && !shadowed('undefined')) return 'undefined'
355
383
  const prop = nullableNumberPropRead(expr, ctx, shadowed)
356
- if (prop !== null) return prop === 'undefined' ? 'absent' : 'null'
384
+ if (prop !== null) return prop === 'undefined' ? 'absent' : prop
357
385
  const getter = expr.kind === 'identifier' ? expr.name : bareGetterCallName(expr)
358
386
  if (getter === null || shadowed(getter)) return null
359
387
  if (ctx.nullSeededSignals?.has(getter)) return 'null'
@@ -419,10 +447,103 @@ export function arithmeticOperandCoercion(
419
447
  ctx: NullishAttrContext,
420
448
  isShadowed: (name: string) => boolean = () => false,
421
449
  ): ArithmeticCoercion {
422
- const numeric = NULL_COERCING_ARITHMETIC_OPS.has(op) || (op === '+' && isNumberLiteral(other))
423
- if (!numeric) return null
450
+ if (!isNumericArithmetic(op, other)) return null
424
451
  const seed = arithmeticOperandSeed(operand, ctx, isShadowed)
425
- return seed === 'absent' ? 'undefined' : seed
452
+ if (seed === 'absent') return 'undefined'
453
+ // `'either'` is refused (`arithmeticOperandNilIsAmbiguous`); the spelling
454
+ // keeps the `null` reading so the refused template stays well-formed.
455
+ return seed === 'either' ? 'null' : seed
456
+ }
457
+
458
+ /**
459
+ * Whether an arithmetic operand reads a number prop whose type admits both
460
+ * `null` and absence (`n?: number | null`), directly or through a memo
461
+ * (#3700). JS reads the omitted prop as `undefined` (`NaN` in arithmetic)
462
+ * and a `null` one as `0`; a template engine holds both as one nil and the
463
+ * type cannot say which, so no spelling of {@link arithmeticOperandCoercion}
464
+ * renders both. Template adapters refuse such an operand instead of
465
+ * rendering one reading silently. Same operators and scope as
466
+ * {@link arithmeticOperandCoercion}.
467
+ */
468
+ export function arithmeticOperandNilIsAmbiguous(
469
+ op: string,
470
+ operand: ParsedExpr | undefined,
471
+ other: ParsedExpr | undefined,
472
+ ctx: NullishAttrContext,
473
+ isShadowed: (name: string) => boolean = () => false,
474
+ ): boolean {
475
+ return isNumericArithmetic(op, other) && arithmeticOperandSeed(operand, ctx, isShadowed) === 'either'
476
+ }
477
+
478
+ /**
479
+ * Every arithmetic operand in `expr` that {@link arithmeticOperandNilIsAmbiguous}
480
+ * matches, for a whole expression a template adapter lowers without visiting
481
+ * each operator through its emitter (a memo body, a `.filter()` predicate, an
482
+ * expression the runtime evaluator runs). Operands of binary operators and of
483
+ * unary minus count. `scope` is where the expression is read; each arrow in
484
+ * it enters its params as a callback frame (`BindingScope.enterCallback`),
485
+ * so they shadow within its body only.
486
+ */
487
+ export function ambiguousNilArithmeticOperands(
488
+ expr: ParsedExpr,
489
+ ctx: NullishAttrContext,
490
+ scope: BindingScope = BindingScope.EMPTY,
491
+ ): ParsedExpr[] {
492
+ const found: ParsedExpr[] = []
493
+ const visit = (e: ParsedExpr, at: BindingScope): void => {
494
+ if (e.kind === 'arrow') {
495
+ visit(e.body, at.enterCallback(e.params))
496
+ return
497
+ }
498
+ for (const [op, operand, other] of arithmeticOperandsOf(e)) {
499
+ if (arithmeticOperandNilIsAmbiguous(op, operand, other, ctx, at.asShadowPredicate())) found.push(operand)
500
+ }
501
+ for (const child of parsedExprChildren(e)) visit(child, at)
502
+ }
503
+ if (!ctx.nullableNumberProps?.size) return found
504
+ visit(expr, scope)
505
+ return found
506
+ }
507
+
508
+ /** The `[op, operand, other]` triples of an arithmetic node's operands. */
509
+ function arithmeticOperandsOf(e: ParsedExpr): Array<[string, ParsedExpr, ParsedExpr | undefined]> {
510
+ if (e.kind === 'binary') return [[e.op, e.left, e.right], [e.op, e.right, e.left]]
511
+ if (e.kind === 'unary' && e.op === '-') return [['-', e.argument, undefined]]
512
+ return []
513
+ }
514
+
515
+ /** The value-position sub-expressions of `e` (an arrow's body included). */
516
+ function parsedExprChildren(e: ParsedExpr): ParsedExpr[] {
517
+ switch (e.kind) {
518
+ case 'call':
519
+ return [e.callee, ...e.args]
520
+ case 'member':
521
+ return [e.object]
522
+ case 'index-access':
523
+ return [e.object, e.index]
524
+ case 'binary':
525
+ case 'logical':
526
+ return [e.left, e.right]
527
+ case 'unary':
528
+ return [e.argument]
529
+ case 'conditional':
530
+ return [e.test, e.consequent, e.alternate]
531
+ case 'template-literal':
532
+ return e.parts.flatMap(p => (p.type === 'expression' ? [p.expr] : []))
533
+ case 'array-literal':
534
+ return e.elements
535
+ case 'array-method':
536
+ return [e.object, ...e.args, ...(e.method === 'flat' && e.depthExpr ? [e.depthExpr] : [])]
537
+ case 'object-literal':
538
+ return e.properties.map(p => (p.kind === 'spread' ? p.expr : p.value))
539
+ default:
540
+ return []
541
+ }
542
+ }
543
+
544
+ /** The operators {@link arithmeticOperandCoercion} applies `ToNumber` under. */
545
+ function isNumericArithmetic(op: string, other: ParsedExpr | undefined): boolean {
546
+ return NULL_COERCING_ARITHMETIC_OPS.has(op) || (op === '+' && isNumberLiteral(other))
426
547
  }
427
548
 
428
549
  function isNumberLiteral(expr: ParsedExpr | undefined): boolean {
@@ -1,5 +1,5 @@
1
1
  import ts from 'typescript'
2
- import type { ConstantInfo, ParamInfo, PropUsage, SignalPropSeed } from './types.ts'
2
+ import type { ConstantInfo, FunctionInfo, MemoInfo, ParamInfo, PropUsage, SignalInfo, SignalPropSeed } from './types.ts'
3
3
  import type { ParsedExpr } from './expression-parser.ts'
4
4
  import { propHasPropertyAccess } from './ir-to-client-js/compute-prop-usage.ts'
5
5
  import { parsePropReadInitializer } from './ir-to-client-js/prune-unused-prop-extractions.ts'
@@ -115,8 +115,8 @@ export function isPropsAliasConst(
115
115
  * binding into a live prop read: the init body's alias rewrite
116
116
  * (`resolveBodyPropAliases`) and parameter rewrite
117
117
  * (`rewriteDestructuredPropReads`), the reactive attribute rewrite
118
- * (`rewriteDestructuredPropsInExpr`), and the template's prop shadow guard
119
- * (`propShadowingNames`, `jsx-to-ir.ts`, #3579).
118
+ * (`rewriteDestructuredPropsInExpr`), and the template's prop read set
119
+ * (`templatePropReadParams`, #3579).
120
120
  */
121
121
  export function keepsDeclaredValue(
122
122
  b: { declarationKind?: ConstantInfo['declarationKind']; mutatedAfterDeclaration?: boolean; reassigned?: boolean },
@@ -167,6 +167,57 @@ export function isRenamedBodyPropParam(
167
167
  return propsParams.some(p => !p.isRest && p.name === c.name && p.sourceName === key)
168
168
  }
169
169
 
170
+ /** The component bindings {@link templatePropReadParams} reads. */
171
+ export interface TemplatePropReadBindings {
172
+ propsObjectName: string | null
173
+ propsParams: readonly ParamInfo[]
174
+ signals: readonly Pick<SignalInfo, 'getter' | 'setter'>[]
175
+ memos: readonly Pick<MemoInfo, 'name'>[]
176
+ localFunctions: readonly Pick<FunctionInfo, 'name'>[]
177
+ localConstants: readonly ConstantInfo[]
178
+ }
179
+
180
+ /**
181
+ * The props bindings a client `template:` reads as their live prop
182
+ * (`livePropReadExpr`, default included). The one set the Phase-1 markup
183
+ * rewrite and a signal seed's or memo body's template text share, so a
184
+ * binding read through a memo takes the same default as one read in markup.
185
+ *
186
+ * In a destructured-parameter component that is every parameter. In a
187
+ * `(props)`-arg component a bare name is a prop only where the body binds it
188
+ * as one, so the set is exactly the body bindings that hold their prop
189
+ * ({@link holdsProp}) and that no other component binding (a signal, memo,
190
+ * local function or other local) shares a name with. A typed prop the body
191
+ * does not bind is not in scope as a bare name: a bare `value` there is a
192
+ * local function, a module binding or a global, never `_p.value`.
193
+ */
194
+ export function templatePropReadParams(b: TemplatePropReadBindings): ParamInfo[] {
195
+ if (!b.propsObjectName) return [...b.propsParams]
196
+ const held = new Set<string>()
197
+ const other = new Set<string>()
198
+ for (const s of b.signals) {
199
+ other.add(s.getter)
200
+ if (s.setter) other.add(s.setter)
201
+ }
202
+ for (const m of b.memos) other.add(m.name)
203
+ for (const f of b.localFunctions) other.add(f.name)
204
+ for (const c of b.localConstants) (holdsProp(c, b.propsObjectName, b.propsParams) ? held : other).add(c.name)
205
+ return b.propsParams.filter(p => held.has(p.name) && !other.has(p.name))
206
+ }
207
+
208
+ /**
209
+ * Whether a `(props)`-arg component's body binding is the prop itself: an
210
+ * alias (`const { b } = props`, `const b = props.b`) or a renamed body
211
+ * binding with a default, which reads as its own prop entry like the
212
+ * parameter form (#3579). A body destructure binding that is reassigned or
213
+ * mutated no longer holds its prop, renamed or not, so the template keeps it
214
+ * a local.
215
+ */
216
+ function holdsProp(c: ConstantInfo, propsObjectName: string, propsParams: readonly ParamInfo[]): boolean {
217
+ if (c.propsDestructure && !keepsDeclaredValue(c)) return false
218
+ return isPropsAliasConst(c, propsObjectName) || isRenamedBodyPropParam(c, propsParams)
219
+ }
220
+
170
221
  /**
171
222
  * How a parsed signal initializer reads a prop: a member chain rooted at the
172
223
  * props object (`props.<name>`, `props.row.count`, `props.items[0]`) or a
@@ -29,6 +29,13 @@
29
29
  * "just names you can't resolve against component-level state."
30
30
  */
31
31
 
32
+ /**
33
+ * The identifier a template reads as the component's props object:
34
+ * `props.X` is the component's prop `X` while no binding shadows `props`
35
+ * (#3693).
36
+ */
37
+ export const PROPS_OBJECT_IDENTIFIER = 'props'
38
+
32
39
  /**
33
40
  * How a name inside a `ScopeFrame` came to be bound — the row shapes
34
41
  * (`'item'`/`'index'`/`'destructure'`/`'preamble'`) for `'loop-row'` frames,
@@ -206,13 +213,34 @@ export class BindingScope {
206
213
  return false
207
214
  }
208
215
 
209
- /** Resolve string typing at this position, respecting the nearest binding. */
216
+ /**
217
+ * Whether a binding here shadows the component's props object
218
+ * ({@link PROPS_OBJECT_IDENTIFIER}): a `.map((props) => …)` row, a
219
+ * destructured `({ props })` field, a preamble local or a callback param.
220
+ * `props.X` then reads that binding's member, not the component's prop
221
+ * `X` (#3693).
222
+ */
223
+ shadowsPropsObject(): boolean {
224
+ return this.isBound(PROPS_OBJECT_IDENTIFIER)
225
+ }
226
+
227
+ /**
228
+ * Resolve string typing at this position, respecting the nearest binding.
229
+ * `componentProperty`: `name` is read as `props.<name>`, which is the
230
+ * component's prop only while no binding shadows `props`; a shadowing
231
+ * binding's member has no typing here.
232
+ */
210
233
  isStringValueName(name: string, outer: (name: string) => boolean, componentProperty = false): boolean {
211
- if (componentProperty) return outer(name)
234
+ if (componentProperty) return !this.shadowsPropsObject() && outer(name)
212
235
  const hit = this.lookup(name)
213
236
  return hit ? hit.binding.stringValue === true : outer(name)
214
237
  }
215
238
 
239
+ /** Whether any frame is a loop row: the position sits inside a `.map()` row body. */
240
+ insideLoopRow(): boolean {
241
+ return this.frames.some(frame => frame.kind === 'loop-row')
242
+ }
243
+
216
244
  /** The names the innermost frame binds, in binding order. */
217
245
  innermostNames(): readonly string[] {
218
246
  return this.frames[0] ? [...this.frames[0].bindings.keys()] : []
@@ -1,6 +1,7 @@
1
1
  import { collectLoopBoundNames } from '../adapters/loop-bound-names.ts'
2
+ import type { ParsedExpr } from '../expression-parser.ts'
2
3
  import type { ComponentIR } from '../types.ts'
3
- import type { BindingScope } from './binding-scope.ts'
4
+ import { PROPS_OBJECT_IDENTIFIER, type BindingScope } from './binding-scope.ts'
4
5
 
5
6
  /**
6
7
  * Root-prop aliases for template engines that flatten `props.X` to the bare
@@ -79,3 +80,18 @@ export function rootPropReadName(
79
80
  if (!scope.isBound(name)) return name
80
81
  return aliases.get(name) ?? name
81
82
  }
83
+
84
+ /**
85
+ * Whether `expr` reads the component's props object at a position where
86
+ * `isBound` answers which names a binding shadows: the bare identifier
87
+ * `props` that no binding shadows (#3693). A `.map((props) => …)` row, a
88
+ * destructured `({ props })` field, a preamble local or a callback param
89
+ * named `props` is that binding instead, so `props.X` reads its member
90
+ * rather than flattening to the component's prop `X`. Template emitters
91
+ * flatten a `props.X` read only when this holds; `isBound` is the
92
+ * adapter's current `BindingScope` (`scope.isBound`), or, in a filter
93
+ * predicate, the predicate's own params plus the enclosing scope.
94
+ */
95
+ export function isRootPropsObject(expr: ParsedExpr, isBound: (name: string) => boolean): boolean {
96
+ return expr.kind === 'identifier' && expr.name === PROPS_OBJECT_IDENTIFIER && !isBound(expr.name)
97
+ }