@barefootjs/jsx 0.40.1 → 0.41.0

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 (211) hide show
  1. package/dist/adapters/boolean-result.d.ts +32 -10
  2. package/dist/adapters/boolean-result.d.ts.map +1 -1
  3. package/dist/adapters/brace-delimiter-text.d.ts +18 -0
  4. package/dist/adapters/brace-delimiter-text.d.ts.map +1 -0
  5. package/dist/adapters/callback-method.d.ts +45 -5
  6. package/dist/adapters/callback-method.d.ts.map +1 -1
  7. package/dist/adapters/component-props.d.ts +3 -4
  8. package/dist/adapters/component-props.d.ts.map +1 -1
  9. package/dist/adapters/computed-const.d.ts +11 -1
  10. package/dist/adapters/computed-const.d.ts.map +1 -1
  11. package/dist/adapters/dsl-template-adapter.d.ts +24 -12
  12. package/dist/adapters/dsl-template-adapter.d.ts.map +1 -1
  13. package/dist/adapters/loop-bound-names.d.ts +9 -1
  14. package/dist/adapters/loop-bound-names.d.ts.map +1 -1
  15. package/dist/adapters/loop-row-type.d.ts +59 -0
  16. package/dist/adapters/loop-row-type.d.ts.map +1 -0
  17. package/dist/adapters/nil-reading.d.ts +63 -0
  18. package/dist/adapters/nil-reading.d.ts.map +1 -0
  19. package/dist/adapters/non-primitive-equality.d.ts +33 -0
  20. package/dist/adapters/non-primitive-equality.d.ts.map +1 -0
  21. package/dist/adapters/number-value.d.ts +5 -3
  22. package/dist/adapters/number-value.d.ts.map +1 -1
  23. package/dist/adapters/operand-typing.d.ts +126 -0
  24. package/dist/adapters/operand-typing.d.ts.map +1 -0
  25. package/dist/adapters/parsed-expr-emitter.d.ts +80 -12
  26. package/dist/adapters/parsed-expr-emitter.d.ts.map +1 -1
  27. package/dist/adapters/primitive-plan.d.ts +320 -0
  28. package/dist/adapters/primitive-plan.d.ts.map +1 -0
  29. package/dist/adapters/prop-classes.d.ts +5 -0
  30. package/dist/adapters/prop-classes.d.ts.map +1 -1
  31. package/dist/analyzer-context.d.ts +4 -0
  32. package/dist/analyzer-context.d.ts.map +1 -1
  33. package/dist/analyzer.d.ts.map +1 -1
  34. package/dist/augment-inherited-props.d.ts +63 -8
  35. package/dist/augment-inherited-props.d.ts.map +1 -1
  36. package/dist/compiler.d.ts.map +1 -1
  37. package/dist/event-handler-name.d.ts +12 -0
  38. package/dist/event-handler-name.d.ts.map +1 -1
  39. package/dist/expression-parser.d.ts +8 -0
  40. package/dist/expression-parser.d.ts.map +1 -1
  41. package/dist/index.d.ts +20 -11
  42. package/dist/index.d.ts.map +1 -1
  43. package/dist/index.js +4903 -2311
  44. package/dist/ir-to-client-js/build-references.d.ts.map +1 -1
  45. package/dist/ir-to-client-js/child-props-object.d.ts +106 -0
  46. package/dist/ir-to-client-js/child-props-object.d.ts.map +1 -0
  47. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  48. package/dist/ir-to-client-js/control-flow/plan/build-inner-loop.d.ts.map +1 -1
  49. package/dist/ir-to-client-js/control-flow/plan/build-loop-child-arm.d.ts.map +1 -1
  50. package/dist/ir-to-client-js/control-flow/shared.d.ts.map +1 -1
  51. package/dist/ir-to-client-js/control-flow/stringify/claim-plan.d.ts +4 -2
  52. package/dist/ir-to-client-js/control-flow/stringify/claim-plan.d.ts.map +1 -1
  53. package/dist/ir-to-client-js/html-template.d.ts.map +1 -1
  54. package/dist/ir-to-client-js/imports.d.ts +2 -2
  55. package/dist/ir-to-client-js/imports.d.ts.map +1 -1
  56. package/dist/ir-to-client-js/index.d.ts +2 -6
  57. package/dist/ir-to-client-js/index.d.ts.map +1 -1
  58. package/dist/ir-to-client-js/phases/props-extraction.d.ts +3 -3
  59. package/dist/ir-to-client-js/plan/build-declaration-emit.d.ts.map +1 -1
  60. package/dist/ir-to-client-js/plan/build-static-array-child-init.d.ts.map +1 -1
  61. package/dist/ir-to-client-js/plan/static-array-child-init.d.ts +30 -18
  62. package/dist/ir-to-client-js/plan/static-array-child-init.d.ts.map +1 -1
  63. package/dist/ir-to-client-js/prop-handling.d.ts.map +1 -1
  64. package/dist/ir-to-client-js/prune-unused-prop-extractions.d.ts +3 -1
  65. package/dist/ir-to-client-js/prune-unused-prop-extractions.d.ts.map +1 -1
  66. package/dist/ir-to-client-js/stringify/static-array-child-init.d.ts +3 -2
  67. package/dist/ir-to-client-js/stringify/static-array-child-init.d.ts.map +1 -1
  68. package/dist/jsx-to-ir.d.ts +1 -0
  69. package/dist/jsx-to-ir.d.ts.map +1 -1
  70. package/dist/nullable-signal-attr.d.ts +51 -34
  71. package/dist/nullable-signal-attr.d.ts.map +1 -1
  72. package/dist/prop-rewrite.d.ts +7 -0
  73. package/dist/prop-rewrite.d.ts.map +1 -1
  74. package/dist/props-binding.d.ts +58 -13
  75. package/dist/props-binding.d.ts.map +1 -1
  76. package/dist/props-object-whole-read.d.ts +15 -0
  77. package/dist/props-object-whole-read.d.ts.map +1 -0
  78. package/dist/rich-type-refusal.d.ts.map +1 -1
  79. package/dist/scope/binding-scope.d.ts +85 -10
  80. package/dist/scope/binding-scope.d.ts.map +1 -1
  81. package/dist/scope/lexical-scope-walk.d.ts +3 -2
  82. package/dist/scope/lexical-scope-walk.d.ts.map +1 -1
  83. package/dist/scope/root-prop-alias.d.ts +10 -7
  84. package/dist/scope/root-prop-alias.d.ts.map +1 -1
  85. package/dist/ssr-defaults.d.ts +39 -3
  86. package/dist/ssr-defaults.d.ts.map +1 -1
  87. package/dist/strip-types.d.ts +13 -0
  88. package/dist/strip-types.d.ts.map +1 -1
  89. package/dist/template-position-walk.d.ts +21 -3
  90. package/dist/template-position-walk.d.ts.map +1 -1
  91. package/dist/types.d.ts +90 -0
  92. package/dist/types.d.ts.map +1 -1
  93. package/package.json +2 -2
  94. package/src/__tests__/__snapshots__/doc-examples.test.ts.snap +9 -9
  95. package/src/__tests__/binding-scope.test.ts +89 -1
  96. package/src/__tests__/body-destructure-props-object-alias.test.ts +123 -0
  97. package/src/__tests__/body-destructured-prop-default-arrow.test.ts +2 -2
  98. package/src/__tests__/body-destructured-props-live.test.ts +5 -5
  99. package/src/__tests__/boolean-result.test.ts +22 -5
  100. package/src/__tests__/brace-delimiter-text.test.ts +26 -0
  101. package/src/__tests__/callback-method.test.ts +62 -2
  102. package/src/__tests__/child-components-in-map.test.ts +1 -1
  103. package/src/__tests__/client-js-generation.test.ts +3 -3
  104. package/src/__tests__/computed-const.test.ts +103 -0
  105. package/src/__tests__/destructure-default-reads-earlier-param.test.ts +7 -7
  106. package/src/__tests__/destructured-props-live.test.ts +1 -1
  107. package/src/__tests__/emit-to-string-call.test.ts +2 -1
  108. package/src/__tests__/hydration-payload-analysis.test.ts +166 -0
  109. package/src/__tests__/issue-2724-prop-alias-loop-not-static.test.ts +7 -7
  110. package/src/__tests__/issue-2754-rest-spread-needs-slot.test.ts +5 -2
  111. package/src/__tests__/issue-2798-static-nested-loop-bindings.test.ts +1 -1
  112. package/src/__tests__/issue-2835-props-type-member-name-collision.test.ts +4 -4
  113. package/src/__tests__/issue-3044-nested-prop-object-array-not-static.test.ts +1 -1
  114. package/src/__tests__/issue-3688-props-spread-child-csr.test.ts +2 -1
  115. package/src/__tests__/issue-3713-props-spread-loop-row.test.ts +65 -0
  116. package/src/__tests__/issue-3861-object-spread-child.test.ts +102 -0
  117. package/src/__tests__/lookup-literal-const.test.ts +9 -3
  118. package/src/__tests__/loop-index-reactivity.test.ts +2 -2
  119. package/src/__tests__/loop-param-accessor-key-member-safety.test.ts +1 -1
  120. package/src/__tests__/loop-plan.test.ts +1 -1
  121. package/src/__tests__/loop-row-const-initializer-shadow.test.ts +146 -0
  122. package/src/__tests__/loop-row-type.test.ts +64 -0
  123. package/src/__tests__/lowering-value-position.test.ts +4 -0
  124. package/src/__tests__/memo-body-expr.test.ts +2 -2
  125. package/src/__tests__/module-const-destructure-default.test.ts +156 -0
  126. package/src/__tests__/nested-loop-index-param.test.ts +1 -1
  127. package/src/__tests__/nested-loop-reactive-attrs.test.ts +2 -2
  128. package/src/__tests__/nested-row-shadowing.test.ts +2 -2
  129. package/src/__tests__/nil-reading.test.ts +78 -0
  130. package/src/__tests__/nullable-signal-attr.test.ts +109 -48
  131. package/src/__tests__/primitive-plan.test.ts +494 -0
  132. package/src/__tests__/profile-loop-binding-ids.test.ts +2 -2
  133. package/src/__tests__/profile-nested-binding-ids.test.ts +2 -2
  134. package/src/__tests__/prop-default-undefined-only.test.ts +115 -0
  135. package/src/__tests__/prop-references.test.ts +2 -2
  136. package/src/__tests__/props-destructuring.test.ts +17 -0
  137. package/src/__tests__/props-object-whole-read.test.ts +40 -0
  138. package/src/__tests__/prune-unused-prop-extractions.test.ts +3 -3
  139. package/src/__tests__/reactive-attrs-in-map.test.ts +1 -1
  140. package/src/__tests__/reactive-factory-inlining.test.ts +4 -1
  141. package/src/__tests__/renamed-body-destructure-template.test.ts +7 -7
  142. package/src/__tests__/rest-binding-gaps.test.ts +192 -0
  143. package/src/__tests__/rewrite-destructured-props.test.ts +1 -1
  144. package/src/__tests__/root-prop-alias.test.ts +53 -8
  145. package/src/__tests__/ssr-defaults.test.ts +113 -25
  146. package/src/__tests__/static-loop-csr-materialize.test.ts +2 -2
  147. package/src/__tests__/static-record-literal-array.test.ts +171 -0
  148. package/src/__tests__/string-concat-identifier.test.ts +40 -1
  149. package/src/__tests__/written-binding-substitution.test.ts +8 -8
  150. package/src/adapters/boolean-result.ts +72 -66
  151. package/src/adapters/brace-delimiter-text.ts +25 -0
  152. package/src/adapters/callback-method.ts +159 -27
  153. package/src/adapters/component-props.ts +3 -4
  154. package/src/adapters/computed-const.ts +238 -4
  155. package/src/adapters/dsl-template-adapter.ts +62 -26
  156. package/src/adapters/loop-bound-names.ts +9 -1
  157. package/src/adapters/loop-plan.ts +1 -1
  158. package/src/adapters/loop-row-type.ts +149 -0
  159. package/src/adapters/nil-reading.ts +295 -0
  160. package/src/adapters/non-primitive-equality.ts +92 -0
  161. package/src/adapters/number-value.ts +17 -4
  162. package/src/adapters/operand-typing.ts +522 -0
  163. package/src/adapters/parsed-expr-emitter.ts +183 -19
  164. package/src/adapters/primitive-plan.ts +765 -0
  165. package/src/adapters/prop-classes.ts +16 -3
  166. package/src/analyzer-context.ts +6 -0
  167. package/src/analyzer.ts +532 -26
  168. package/src/augment-inherited-props.ts +108 -10
  169. package/src/compiler.ts +17 -0
  170. package/src/event-handler-name.ts +15 -0
  171. package/src/expression-parser.ts +70 -1
  172. package/src/index.ts +35 -16
  173. package/src/ir-to-client-js/build-references.ts +69 -0
  174. package/src/ir-to-client-js/child-props-object.ts +240 -0
  175. package/src/ir-to-client-js/collect-elements.ts +31 -63
  176. package/src/ir-to-client-js/control-flow/plan/build-inner-loop.ts +8 -1
  177. package/src/ir-to-client-js/control-flow/plan/build-loop-child-arm.ts +31 -28
  178. package/src/ir-to-client-js/control-flow/shared.ts +20 -22
  179. package/src/ir-to-client-js/control-flow/stringify/claim-plan.ts +5 -3
  180. package/src/ir-to-client-js/control-flow/stringify/inner-loop.ts +2 -2
  181. package/src/ir-to-client-js/control-flow/stringify/lazy-row.ts +1 -1
  182. package/src/ir-to-client-js/control-flow/stringify/loop-child-arm.ts +2 -2
  183. package/src/ir-to-client-js/control-flow/stringify/loop.ts +1 -1
  184. package/src/ir-to-client-js/control-flow/stringify/reactive-effects.ts +3 -3
  185. package/src/ir-to-client-js/html-template.ts +43 -17
  186. package/src/ir-to-client-js/imports.ts +2 -2
  187. package/src/ir-to-client-js/index.ts +53 -11
  188. package/src/ir-to-client-js/phases/props-extraction.ts +11 -7
  189. package/src/ir-to-client-js/plan/build-declaration-emit.ts +40 -7
  190. package/src/ir-to-client-js/plan/build-static-array-child-init.ts +31 -14
  191. package/src/ir-to-client-js/plan/static-array-child-init.ts +27 -18
  192. package/src/ir-to-client-js/prop-handling.ts +22 -3
  193. package/src/ir-to-client-js/prune-unused-prop-extractions.ts +58 -5
  194. package/src/ir-to-client-js/rewrite-destructured-props.ts +31 -1
  195. package/src/ir-to-client-js/stringify/static-array-child-init.ts +26 -10
  196. package/src/jsx-to-ir.ts +459 -37
  197. package/src/nullable-signal-attr.ts +200 -110
  198. package/src/prop-rewrite.ts +30 -6
  199. package/src/props-binding.ts +84 -19
  200. package/src/props-object-whole-read.ts +87 -0
  201. package/src/rich-type-refusal.ts +2 -1
  202. package/src/scope/binding-scope.ts +182 -18
  203. package/src/scope/lexical-scope-walk.ts +4 -3
  204. package/src/scope/root-prop-alias.ts +15 -8
  205. package/src/ssr-defaults.ts +100 -11
  206. package/src/strip-types.ts +31 -3
  207. package/src/template-position-walk.ts +57 -28
  208. package/src/types.ts +87 -0
  209. package/dist/adapters/ambiguous-nil-arithmetic.d.ts +0 -41
  210. package/dist/adapters/ambiguous-nil-arithmetic.d.ts.map +0 -1
  211. package/src/adapters/ambiguous-nil-arithmetic.ts +0 -94
@@ -0,0 +1,87 @@
1
+ /**
2
+ * Whether a component observes its props object as a whole: any read of the
3
+ * props parameter other than a member read with a known key (`props.x`,
4
+ * `props['x']`). A whole read — `{...props}` on an element or a component,
5
+ * `Object.keys(props)`, `props[key]`, passing `props` to a function,
6
+ * `const { a, ...rest } = props` — can see a key the props type does not
7
+ * declare, so a caller's undeclared prop is not dead there.
8
+ *
9
+ * Syntactic, over the component's TS AST: a nested function, catch clause or
10
+ * block that rebinds the name shadows it, and a type position is not a read.
11
+ * A shadow this misses only makes the answer `true` more often.
12
+ */
13
+
14
+ import ts from 'typescript'
15
+
16
+ export function observesWholePropsObject(
17
+ fn: ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression,
18
+ name: string,
19
+ ): boolean {
20
+ if (!fn.body) return false
21
+ let found = false
22
+ const visit = (node: ts.Node): void => {
23
+ if (found || ts.isTypeNode(node) || rebinds(node, name)) return
24
+ if (ts.isIdentifier(node) && node.text === name && isWholeRead(node)) {
25
+ found = true
26
+ return
27
+ }
28
+ ts.forEachChild(node, visit)
29
+ }
30
+ visit(fn.body)
31
+ return found
32
+ }
33
+
34
+ /** A member read with a key known at compile time (`props.x`, `props['x']`). */
35
+ function isKnownKeyMemberRead(id: ts.Identifier): boolean {
36
+ const parent = id.parent
37
+ if (ts.isPropertyAccessExpression(parent)) return parent.expression === id
38
+ if (ts.isElementAccessExpression(parent) && parent.expression === id) {
39
+ return ts.isStringLiteralLike(parent.argumentExpression) || ts.isNumericLiteral(parent.argumentExpression)
40
+ }
41
+ return false
42
+ }
43
+
44
+ /** An identifier in a name position (a property name, a declaration, a JSX attribute name), not a read. */
45
+ function isNamePosition(id: ts.Identifier): boolean {
46
+ const parent = id.parent
47
+ if (ts.isPropertyAccessExpression(parent)) return parent.name === id
48
+ if (ts.isPropertyAssignment(parent) || ts.isJsxAttribute(parent)) return parent.name === id
49
+ if (ts.isBindingElement(parent)) return parent.name === id || parent.propertyName === id
50
+ if (ts.isVariableDeclaration(parent) || ts.isParameter(parent)) return parent.name === id
51
+ if (ts.isFunctionDeclaration(parent) || ts.isMethodDeclaration(parent)) return parent.name === id
52
+ return false
53
+ }
54
+
55
+ function isWholeRead(id: ts.Identifier): boolean {
56
+ if (isNamePosition(id)) return false
57
+ if (isKnownKeyMemberRead(id)) return false
58
+ return !isRestFreeDestructure(id)
59
+ }
60
+
61
+ /** `const { a, b } = props`: reads only the named keys. */
62
+ function isRestFreeDestructure(id: ts.Identifier): boolean {
63
+ const parent = id.parent
64
+ if (!ts.isVariableDeclaration(parent) || parent.initializer !== id) return false
65
+ const pattern = parent.name
66
+ return ts.isObjectBindingPattern(pattern) &&
67
+ pattern.elements.every(el => !el.dotDotDotToken && (!el.propertyName || !ts.isComputedPropertyName(el.propertyName)))
68
+ }
69
+
70
+ /** Whether `node` opens a scope that binds `name` again. */
71
+ function rebinds(node: ts.Node, name: string): boolean {
72
+ if (ts.isFunctionLike(node)) return node.parameters.some(p => bindsName(p.name, name))
73
+ if (ts.isCatchClause(node)) return !!node.variableDeclaration && bindsName(node.variableDeclaration.name, name)
74
+ if (ts.isBlock(node)) return node.statements.some(s => declaresInBlock(s, name))
75
+ return false
76
+ }
77
+
78
+ function declaresInBlock(stmt: ts.Statement, name: string): boolean {
79
+ if (ts.isVariableStatement(stmt)) return stmt.declarationList.declarations.some(d => bindsName(d.name, name))
80
+ if (ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt)) return stmt.name?.text === name
81
+ return false
82
+ }
83
+
84
+ function bindsName(binding: ts.BindingName, name: string): boolean {
85
+ if (ts.isIdentifier(binding)) return binding.text === name
86
+ return binding.elements.some(el => !ts.isOmittedExpression(el) && bindsName(el.name, name))
87
+ }
@@ -65,6 +65,7 @@ import type { ParsedExpr } from './expression-parser.ts'
65
65
  import { parseExpression } from './expression-parser.ts'
66
66
  import { prepareLoweringMatchers, type LoweringMatcher } from './lowering-registry.ts'
67
67
  import { ErrorCodes } from './errors.ts'
68
+ import { isHydrationPayloadPropName } from './event-handler-name.ts'
68
69
  import {
69
70
  resolveReceiverType,
70
71
  baseTypeName,
@@ -119,7 +120,7 @@ export function checkRichTypePropSerialization(root: IRNode, metadata: IRMetadat
119
120
  const usedProps = new Set(metadata.clientAnalysis.usedProps)
120
121
  const loc = declLoc ?? root.loc
121
122
  for (const param of metadata.propsParams) {
122
- if (param.isRest || param.name.startsWith('on') || param.name.startsWith('__')) continue
123
+ if (param.isRest || !isHydrationPayloadPropName(param.name)) continue
123
124
  if (!usedProps.has(param.name)) continue
124
125
  const declared = resolvePropDeclaredType(param.sourceName ?? param.name, metadata)
125
126
  const typeName = jsonUnsafeTypeName(declared)
@@ -30,12 +30,26 @@
30
30
  */
31
31
 
32
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).
33
+ * The identifier a template reads as the component's props object when the
34
+ * component does not name one itself: `props.X` is the component's prop `X`
35
+ * while no binding shadows `props` (#3693). A component that takes its props
36
+ * as one object names it with its parameter (`function C(p)`), and
37
+ * {@link BindingScope.forComponent} makes that name the props object instead.
36
38
  */
37
39
  export const PROPS_OBJECT_IDENTIFIER = 'props'
38
40
 
41
+ /**
42
+ * The identifier that names the props object of a component whose props
43
+ * parameter is `propsObjectName` (`IRMetadata.propsObjectName`): that name
44
+ * (`function C(p)` → `p`), or {@link PROPS_OBJECT_IDENTIFIER} when the
45
+ * component destructures its props (`null`). The single answer to "which
46
+ * identifier is the component's props object"; {@link BindingScope.propsObject}
47
+ * carries it.
48
+ */
49
+ export function propsObjectIdentifier(propsObjectName: string | null | undefined): string {
50
+ return propsObjectName ?? PROPS_OBJECT_IDENTIFIER
51
+ }
52
+
39
53
  /**
40
54
  * How a name inside a `ScopeFrame` came to be bound — the row shapes
41
55
  * (`'item'`/`'index'`/`'destructure'`/`'preamble'`) for `'loop-row'` frames,
@@ -88,10 +102,33 @@ export interface LoopBindingSource {
88
102
 
89
103
  /** Structural pick of `TypeInfo` (`packages/jsx/src/types.ts`). */
90
104
  export interface LoopValueType {
105
+ /** `TypeInfo.kind`; `'unknown'` for `any`, `unknown` and unresolved types. */
106
+ readonly kind?: string
91
107
  readonly primitive?: string
92
108
  readonly unionTypes?: readonly LoopValueType[]
109
+ /** A named type's name (`Row`), resolved through {@link NamedTypeFields}. */
110
+ readonly raw?: string
111
+ readonly properties?: readonly LoopValueField[]
112
+ readonly elementType?: LoopValueType
113
+ }
114
+
115
+ /** Structural pick of `PropertyInfo` (`packages/jsx/src/types.ts`). */
116
+ export interface LoopValueField {
117
+ readonly name: string
118
+ readonly type: LoopValueType
119
+ /** `name?:` — the field may be absent, so its value may be `undefined`. */
120
+ readonly optional?: boolean
93
121
  }
94
122
 
123
+ /** The value of a field that may be absent: its declared type or `undefined`. */
124
+ const ABSENT: LoopValueType = { kind: 'primitive', raw: 'undefined', primitive: 'undefined' }
125
+
126
+ /**
127
+ * The fields of a named type (`type Row = { … }`, an interface), by name;
128
+ * undefined when the component's file does not define it as an object type.
129
+ */
130
+ export type NamedTypeFields = (name: string) => readonly LoopValueField[] | undefined
131
+
95
132
  /** Structural copy of `LoopBindingPathSegment` (`packages/jsx/src/types.ts`). */
96
133
  export type RowPathSegment =
97
134
  | { readonly kind: 'field'; readonly key: string; readonly isIdent: boolean }
@@ -102,6 +139,85 @@ function isStringLoopValue(type: LoopValueType): boolean {
102
139
  (type.unionTypes !== undefined && type.unionTypes.length > 0 && type.unionTypes.every(isStringLoopValue))
103
140
  }
104
141
 
142
+ /**
143
+ * The type at `segments` below `type`, through object types, named types
144
+ * (`namedFields`) and array elements; null when a step is not known.
145
+ *
146
+ * A union resolves the path in each member and is the union of the results,
147
+ * null when any member has no such path. A field is therefore definitely a
148
+ * string only when it is one in every member: the element type of a
149
+ * `concat` (`loopRowType`) is the union of its receiver's and arguments'
150
+ * element types, so `Row` and a same-shaped `Other` both read `id: string`,
151
+ * while an `any` member or an omitted field reads nothing (#3762 review).
152
+ */
153
+ export function loopValueTypeAt(
154
+ type: LoopValueType,
155
+ segments: readonly RowPathSegment[],
156
+ namedFields: NamedTypeFields = () => undefined,
157
+ ): LoopValueType | null {
158
+ if (segments.length === 0) return type
159
+ if (type.unionTypes && type.unionTypes.length > 0) {
160
+ const members = type.unionTypes.map(member => loopValueTypeAt(member, segments, namedFields))
161
+ return members.every(m => m !== null) ? unionOfLoopValueTypes(members as LoopValueType[]) : null
162
+ }
163
+ const [segment, ...rest] = segments
164
+ const next = segment.kind === 'index' ? arrayElementType(type) : fieldType(type, segment.key, namedFields)
165
+ return next ? loopValueTypeAt(next, rest, namedFields) : null
166
+ }
167
+
168
+ /**
169
+ * The element type of an array type, or of a union whose every member is an
170
+ * array (a `concat` of arrays, a field read across `concat` rows): the union
171
+ * of their element types. Undefined for anything else. Every reader of an
172
+ * element type goes through this, so a union of arrays reads like an array
173
+ * (#3762 review).
174
+ */
175
+ export function arrayElementType<T extends LoopValueType>(type: T | null | undefined): T | undefined {
176
+ if (!type) return undefined
177
+ if (type.elementType) return type.elementType as T
178
+ const members = type.unionTypes
179
+ if (!members || members.length === 0) return undefined
180
+ const elements = members.map(member => arrayElementType(member))
181
+ return elements.every(e => e !== undefined) ? unionOfLoopValueTypes(elements as T[]) : undefined
182
+ }
183
+
184
+ /**
185
+ * The union of `members`, normalised: one member, or members that are all
186
+ * structurally the same type, is that member itself, so `Row[] ∪ Row[]`
187
+ * keeps the plain `Row[]` shape.
188
+ */
189
+ export function unionOfLoopValueTypes<T extends LoopValueType>(members: readonly T[]): T {
190
+ const [first] = members
191
+ if (members.every(member => isSameLoopValueShape(member, first))) return first
192
+ return { kind: 'union', raw: members.map(m => m.raw ?? 'unknown').join(' | '), unionTypes: members } as unknown as T
193
+ }
194
+
195
+ /** Whether two types have the same structure: kind, name, primitive, fields, elements and members. */
196
+ export function isSameLoopValueShape(a: LoopValueType | undefined, b: LoopValueType | undefined): boolean {
197
+ if (a === b) return true
198
+ if (!a || !b) return false
199
+ return a.kind === b.kind && a.raw === b.raw && a.primitive === b.primitive &&
200
+ isSameLoopValueShape(a.elementType, b.elementType) &&
201
+ sameMembers(a.unionTypes, b.unionTypes, isSameLoopValueShape) &&
202
+ sameMembers(a.properties, b.properties, (x, y) =>
203
+ x.name === y.name && Boolean(x.optional) === Boolean(y.optional) && isSameLoopValueShape(x.type, y.type))
204
+ }
205
+
206
+ function sameMembers<T>(a: readonly T[] | undefined, b: readonly T[] | undefined, same: (x: T, y: T) => boolean): boolean {
207
+ if (!a || !b) return a === b
208
+ return a.length === b.length && a.every((x, i) => same(x, b[i]))
209
+ }
210
+
211
+ /** A field's declared type; an optional one may also be `undefined`. */
212
+ function fieldType(type: LoopValueType, key: string, namedFields: NamedTypeFields): LoopValueType | undefined {
213
+ const fields: readonly LoopValueField[] | undefined =
214
+ type.properties ?? (type.raw !== undefined ? namedFields(type.raw) : undefined)
215
+ const field = fields?.find(f => f.name === key)
216
+ // An optional field reads `undefined` when the row omits it, so it is
217
+ // never definitely its declared type (#3762 review).
218
+ return field && (field.optional ? { kind: 'union', unionTypes: [field.type, ABSENT] } : field.type)
219
+ }
220
+
105
221
  /**
106
222
  * A stack of `ScopeFrame`s, innermost frame at index 0 of the internal
107
223
  * array (i.e. `frames[0]` is what `enterLoopRow`/`enterCallback` most
@@ -110,9 +226,30 @@ function isStringLoopValue(type: LoopValueType): boolean {
110
226
  * frames exist.
111
227
  */
112
228
  export class BindingScope {
113
- static readonly EMPTY: BindingScope = new BindingScope([])
229
+ static readonly EMPTY: BindingScope = new BindingScope([], PROPS_OBJECT_IDENTIFIER)
114
230
 
115
- private constructor(private readonly frames: readonly ScopeFrame[]) {}
231
+ /**
232
+ * `propsObject`: the identifier that names the component's props object
233
+ * in this scope's component ({@link forComponent}). Every child scope
234
+ * keeps it.
235
+ */
236
+ private constructor(
237
+ private readonly frames: readonly ScopeFrame[],
238
+ readonly propsObject: string,
239
+ ) {}
240
+
241
+ /**
242
+ * The empty scope of a component whose props object parameter is
243
+ * `propsObjectName` (`IRMetadata.propsObjectName`, decided in Phase 1):
244
+ * `function C(p)` reads its props as `p.X`, so `p` is the props object.
245
+ * A component that destructures its props (`null`) keeps
246
+ * {@link PROPS_OBJECT_IDENTIFIER}.
247
+ */
248
+ static forComponent(propsObjectName: string | null): BindingScope {
249
+ const propsObject = propsObjectIdentifier(propsObjectName)
250
+ if (propsObject === PROPS_OBJECT_IDENTIFIER) return BindingScope.EMPTY
251
+ return new BindingScope([], propsObject)
252
+ }
116
253
 
117
254
  /**
118
255
  * Child scope with a new `'loop-row'` frame for one loop's per-item
@@ -144,8 +281,8 @@ export class BindingScope {
144
281
  * `adapters/loop-bound-names.ts`'s `collectLoopBoundNames` adds BOTH
145
282
  * `node.param` AND every `paramBindings[i].name` unconditionally
146
283
  * (never skipping `param` in the destructured case) — a deliberately
147
- * coarser, over-inclusive collection used only to subtract names from
148
- * a flat string-typing Set (safe to over-exclude there). This method
284
+ * coarser, over-inclusive collection for whole-component "may be
285
+ * shadowed somewhere" checks (safe to over-exclude there). This method
149
286
  * follows the precise `jsx-to-ir.ts` `ctx.loopParams` semantics, since
150
287
  * that is the mechanism actually doing scope-shadowed name RESOLUTION
151
288
  * (the behavior `BindingScope` replaces), not coarse exclusion.
@@ -171,7 +308,7 @@ export class BindingScope {
171
308
  for (const name of loop.preamble?.declaredNames ?? []) bindings.set(name, { source: 'preamble' })
172
309
 
173
310
  const frame: ScopeFrame = { kind: 'loop-row', bindings }
174
- return new BindingScope([frame, ...this.frames])
311
+ return new BindingScope([frame, ...this.frames], this.propsObject)
175
312
  }
176
313
 
177
314
  /**
@@ -183,7 +320,7 @@ export class BindingScope {
183
320
  const bindings = new Map<string, ScopeBinding>()
184
321
  for (const name of params) bindings.set(name, { source: 'param' })
185
322
  const frame: ScopeFrame = { kind: 'callback', bindings }
186
- return new BindingScope([frame, ...this.frames])
323
+ return new BindingScope([frame, ...this.frames], this.propsObject)
187
324
  }
188
325
 
189
326
  /**
@@ -202,7 +339,7 @@ export class BindingScope {
202
339
  if (hit) bindings.set(alias, hit.binding)
203
340
  }
204
341
  if (bindings.size === 0) return this
205
- return new BindingScope([{ kind: 'callback', bindings }, ...this.frames])
342
+ return new BindingScope([{ kind: 'callback', bindings }, ...this.frames], this.propsObject)
206
343
  }
207
344
 
208
345
  /** Innermost-first membership check across every frame in the stack. */
@@ -215,25 +352,52 @@ export class BindingScope {
215
352
 
216
353
  /**
217
354
  * Whether a binding here shadows the component's props object
218
- * ({@link PROPS_OBJECT_IDENTIFIER}): a `.map((props) => …)` row, a
355
+ * ({@link propsObject}): a `.map((props) => …)` row, a
219
356
  * destructured `({ props })` field, a preamble local or a callback param.
220
357
  * `props.X` then reads that binding's member, not the component's prop
221
358
  * `X` (#3693).
222
359
  */
223
360
  shadowsPropsObject(): boolean {
224
- return this.isBound(PROPS_OBJECT_IDENTIFIER)
361
+ return this.isBound(this.propsObject)
225
362
  }
226
363
 
227
364
  /**
228
365
  * 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.
366
+ * `componentProperty`: `name` is read as the literal `props.<name>`. That is
367
+ * the component's prop only when `props` is this component's props object
368
+ * and no binding shadows it; while a binding named `props` is in scope, it
369
+ * is that binding's member. `path`: the read is the member chain
370
+ * `name.<path…>` (`row.id`). A loop row binding resolves the chain against
371
+ * its row type (`LoopBindingSource.rowType`), through `namedFields` for a
372
+ * named type; an outer name has typing for itself only.
232
373
  */
233
- isStringValueName(name: string, outer: (name: string) => boolean, componentProperty = false): boolean {
234
- if (componentProperty) return !this.shadowsPropsObject() && outer(name)
374
+ isStringValueName(
375
+ name: string,
376
+ outer: (name: string) => boolean,
377
+ componentProperty = false,
378
+ path: readonly string[] = [],
379
+ namedFields?: NamedTypeFields,
380
+ ): boolean {
381
+ if (componentProperty) {
382
+ // The operand classifiers flag only the literal receiver `props`
383
+ // (`props.<name>`). A binding named `props` reads its own member.
384
+ if (this.isBound(PROPS_OBJECT_IDENTIFIER)) {
385
+ return this.isStringValueName(PROPS_OBJECT_IDENTIFIER, outer, false, [name, ...path], namedFields)
386
+ }
387
+ // In a component whose props object has another name (`function C(p)`),
388
+ // an unbound `props` is not that object, so it carries no prop typing.
389
+ if (this.propsObject !== PROPS_OBJECT_IDENTIFIER) return false
390
+ return path.length === 0 && outer(name)
391
+ }
235
392
  const hit = this.lookup(name)
236
- return hit ? hit.binding.stringValue === true : outer(name)
393
+ // An outer name's typing covers the name itself, not a member of it.
394
+ if (!hit) return path.length === 0 && outer(name)
395
+ const { stringValue, row } = hit.binding
396
+ if (path.length === 0 && stringValue !== undefined) return stringValue
397
+ if (!row) return false
398
+ const segments = [...row.segments, ...path.map(key => ({ kind: 'field' as const, key, isIdent: true }))]
399
+ const type = loopValueTypeAt(row.itemType, segments, namedFields)
400
+ return type !== null && isStringLoopValue(type)
237
401
  }
238
402
 
239
403
  /** Whether any frame is a loop row: the position sits inside a `.map()` row body. */
@@ -141,11 +141,12 @@ function computedNameOf(n: ts.Node): ts.ComputedPropertyName | undefined {
141
141
  /**
142
142
  * Depth-first walk that maintains the binding stack described above and
143
143
  * reports every identifier along with whether a binding within `root`
144
- * currently shadows it.
144
+ * currently shadows it. `isShadowed` answers the same question for any
145
+ * other name at that identifier's position.
145
146
  */
146
147
  export function walkWithScope(
147
148
  root: ts.Node,
148
- visit: (ident: ts.Identifier, parent: ts.Node | undefined, shadowed: boolean) => void,
149
+ visit: (ident: ts.Identifier, parent: ts.Node | undefined, shadowed: boolean, isShadowed: (name: string) => boolean) => void,
149
150
  ): void {
150
151
  const scopeStack: Set<string>[] = []
151
152
  const isShadowed = (name: string) => scopeStack.some(frame => frame.has(name))
@@ -157,7 +158,7 @@ export function walkWithScope(
157
158
  const outerName = frame ? computedNameOf(n) : undefined
158
159
  if (outerName) rec(outerName, n)
159
160
  if (frame) scopeStack.push(frame)
160
- if (ts.isIdentifier(n)) visit(n, parent, isShadowed(n.text))
161
+ if (ts.isIdentifier(n)) visit(n, parent, isShadowed(n.text), isShadowed)
161
162
  ts.forEachChild(n, child => {
162
163
  if (child !== outerName) rec(child, n)
163
164
  })
@@ -1,7 +1,7 @@
1
1
  import { collectLoopBoundNames } from '../adapters/loop-bound-names.ts'
2
2
  import type { ParsedExpr } from '../expression-parser.ts'
3
3
  import type { ComponentIR } from '../types.ts'
4
- import { PROPS_OBJECT_IDENTIFIER, type BindingScope } from './binding-scope.ts'
4
+ import type { BindingScope } from './binding-scope.ts'
5
5
 
6
6
  /**
7
7
  * Root-prop aliases for template engines that flatten `props.X` to the bare
@@ -84,14 +84,21 @@ export function rootPropReadName(
84
84
  /**
85
85
  * Whether `expr` reads the component's props object at a position where
86
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
87
+ * `propsObject` that no binding shadows (#3693). `propsObject` is the
88
+ * component's props object identifier, `BindingScope.propsObject`: the
89
+ * props parameter's own name (`function C(p)` reads `p.X`), or `props` for
90
+ * a component that destructures its props. A `.map((props) => …)` row, a
91
+ * destructured `({ props })` field, a preamble local or a callback param of
92
+ * that name is that binding instead, so `props.X` reads its member rather
93
+ * than flattening to the component's prop `X`. Template emitters flatten a
94
+ * props-object member read only when this holds; `isBound` is the
92
95
  * adapter's current `BindingScope` (`scope.isBound`), or, in a filter
93
96
  * predicate, the predicate's own params plus the enclosing scope.
94
97
  */
95
- export function isRootPropsObject(expr: ParsedExpr, isBound: (name: string) => boolean): boolean {
96
- return expr.kind === 'identifier' && expr.name === PROPS_OBJECT_IDENTIFIER && !isBound(expr.name)
98
+ export function isRootPropsObject(
99
+ expr: ParsedExpr,
100
+ isBound: (name: string) => boolean,
101
+ propsObject: string,
102
+ ): boolean {
103
+ return expr.kind === 'identifier' && expr.name === propsObject && !isBound(expr.name)
97
104
  }
@@ -47,10 +47,19 @@ export interface SsrDefault {
47
47
  /**
48
48
  * Static fallback value when neither the caller's props nor the
49
49
  * adapter's own derivation supplies one. JSON-encodable: number,
50
- * string, boolean, null, or a tree of plain objects / arrays. `null`
51
- * when the source expression isn't statically evaluable.
50
+ * string, boolean, null, or a tree of plain objects / arrays, in which
51
+ * an `undefined` array element or object member is the sentinel
52
+ * `{"$undef": true}` (`UNDEFINED_SENTINEL`) that every runtime's seed
53
+ * decodes to its undefined value, and an object key that begins with `$`
54
+ * carries one more `$` (`encodeUndefinedMembers`). `null` when the source expression
55
+ * isn't statically evaluable.
56
+ *
57
+ * Absent on a prop entry whose prop has no destructure default
58
+ * (`spec/js-undefined-value.md`, "Shared: the seed and the default"):
59
+ * there is no default to fall back to, and every reader seeds such an
60
+ * entry with its nil, as {@link deriveStashFromDefaults} does.
52
61
  */
53
- value: unknown
62
+ value?: unknown
54
63
  /**
55
64
  * When set, the manifest consumer prefers `props[propName]` over
56
65
  * `value`. Mirrors destructured-prop defaults
@@ -135,18 +144,28 @@ export function deriveStashFromDefaults(
135
144
  continue
136
145
  }
137
146
  if (d.isRestProps) {
138
- extra[name] = name in props ? props[name] : d.value
147
+ extra[name] = name in props ? props[name] : fallbackOf(d)
139
148
  continue
140
149
  }
141
150
  if (d.propName !== undefined && d.propName in props && props[d.propName] != null) {
142
151
  extra[name] = props[d.propName]
143
152
  } else {
144
- extra[name] = d.value
153
+ extra[name] = fallbackOf(d)
145
154
  }
146
155
  }
147
156
  return extra
148
157
  }
149
158
 
159
+ /**
160
+ * An entry's static fallback: its `value`, or `null` when it has none (a
161
+ * prop with no default), as every runtime port reads a missing `value`
162
+ * (Python `d.get("value")`, Perl `$d->{value}`, PHP `?? null`, Rust
163
+ * `unwrap_or(Null)`, Ruby `d[:value]`, Java `d.get("value")`).
164
+ */
165
+ function fallbackOf(d: SsrDefault): unknown {
166
+ return 'value' in d ? decodeUndefinedMembers(d.value) : null
167
+ }
168
+
150
169
  const UNRESOLVED = Symbol('unresolved')
151
170
  type EvalResult = unknown | typeof UNRESOLVED
152
171
 
@@ -199,8 +218,11 @@ function addPropSsrDefaults(
199
218
  // No destructure default — the template reads the prop as-is;
200
219
  // Perl's `//` operator decides what `undef` becomes. The entry
201
220
  // still matters so the template variable exists and consumers
202
- // can supply the propName even with no static fallback.
203
- out[p.name] = { propName: callerPropName, value: null }
221
+ // can supply the propName even with no static fallback. It has no
222
+ // `value` (`spec/js-undefined-value.md`, "Shared: the seed and the
223
+ // default"): every runtime's seed reads a missing `value` as its
224
+ // nil, as it read the `null` this used to write.
225
+ out[p.name] = { propName: callerPropName }
204
226
  }
205
227
  }
206
228
  }
@@ -456,7 +478,72 @@ export function extractSsrDefaults(metadata: IRMetadata): Record<string, SsrDefa
456
478
  }
457
479
  }
458
480
 
459
- return Object.keys(out).length === 0 ? undefined : out
481
+ return Object.keys(out).length === 0 ? undefined : encodeSeedValues(out)
482
+ }
483
+
484
+ /**
485
+ * Each entry's `value` through {@link encodeUndefinedMembers}, in place.
486
+ * A getter alias shares its origin's entry object, so each distinct entry
487
+ * is encoded exactly once: encoding twice would escape the first pass's
488
+ * sentinels and `$`-prefixed keys again.
489
+ */
490
+ function encodeSeedValues(out: Record<string, SsrDefault>): Record<string, SsrDefault> {
491
+ for (const d of new Set(Object.values(out))) {
492
+ if ('value' in d) d.value = encodeUndefinedMembers(d.value)
493
+ }
494
+ return out
495
+ }
496
+
497
+ /**
498
+ * The manifest's spelling of JS `undefined` inside a seed value: the
499
+ * one-key sentinel the golden vectors use (`spec/js-undefined-value.md`,
500
+ * "JSON encoding for vectors"). JSON has no `undefined`, and dropping it
501
+ * would turn an array element into `null` and a present member into a
502
+ * missing key.
503
+ */
504
+ export const UNDEFINED_SENTINEL: Readonly<{ $undef: true }> = Object.freeze({ $undef: true })
505
+
506
+ /**
507
+ * `v` with each `undefined` array element and object member replaced by
508
+ * {@link UNDEFINED_SENTINEL}, as a new tree; a top-level `undefined` stays
509
+ * itself (the entry then has no `value`, which every seed reads as its
510
+ * undefined value). So that seed data shaped like the sentinel stays data,
511
+ * every object key that begins with `$` gets one more `$` (`$undef` to
512
+ * `$$undef`, `$$x` to `$$$x`): the only object left with the single key
513
+ * `$undef` is the sentinel, and {@link decodeUndefinedMembers} inverts the
514
+ * encoding exactly.
515
+ */
516
+ export function encodeUndefinedMembers(v: unknown): unknown {
517
+ const member = (x: unknown): unknown => (x === undefined ? { ...UNDEFINED_SENTINEL } : encodeUndefinedMembers(x))
518
+ if (Array.isArray(v)) return v.map(member)
519
+ if (v !== null && typeof v === 'object') {
520
+ return Object.fromEntries(
521
+ Object.entries(v as Record<string, unknown>).map(([k, x]) => [k.startsWith('$') ? `$${k}` : k, member(x)]),
522
+ )
523
+ }
524
+ return v
525
+ }
526
+
527
+ /**
528
+ * {@link encodeUndefinedMembers} inverted: each sentinel (an object whose
529
+ * only key is `$undef`, holding `true`) becomes `undefined` again, and each
530
+ * key that begins with `$$` loses one leading `$`.
531
+ */
532
+ export function decodeUndefinedMembers(v: unknown): unknown {
533
+ if (isUndefinedSentinel(v)) return undefined
534
+ if (Array.isArray(v)) return v.map(decodeUndefinedMembers)
535
+ if (v !== null && typeof v === 'object') {
536
+ return Object.fromEntries(
537
+ Object.entries(v as Record<string, unknown>).map(([k, x]) => [k.startsWith('$$') ? k.slice(1) : k, decodeUndefinedMembers(x)]),
538
+ )
539
+ }
540
+ return v
541
+ }
542
+
543
+ function isUndefinedSentinel(v: unknown): boolean {
544
+ if (v === null || typeof v !== 'object' || Array.isArray(v)) return false
545
+ const keys = Object.keys(v)
546
+ return keys.length === 1 && keys[0] === '$undef' && (v as { $undef: unknown }).$undef === true
460
547
  }
461
548
 
462
549
  /**
@@ -736,7 +823,9 @@ function evalNode(node: ts.Expression, ctx: EvalContext): EvalResult {
736
823
  }
737
824
  const v = evalNode(prop.initializer, ctx)
738
825
  if (v === UNRESOLVED) return UNRESOLVED
739
- obj[key] = v === undefined ? null : v
826
+ // An `undefined` member is a present key holding `undefined`; the
827
+ // manifest carries it as `{"$undef": true}` (`encodeUndefinedMembers`).
828
+ obj[key] = v
740
829
  }
741
830
  return obj
742
831
  }
@@ -747,7 +836,7 @@ function evalNode(node: ts.Expression, ctx: EvalContext): EvalResult {
747
836
  if (ts.isOmittedExpression(elem)) return UNRESOLVED
748
837
  const v = evalNode(elem, ctx)
749
838
  if (v === UNRESOLVED) return UNRESOLVED
750
- arr.push(v === undefined ? null : v)
839
+ arr.push(v)
751
840
  }
752
841
  return arr
753
842
  }
@@ -830,7 +919,7 @@ function evalNode(node: ts.Expression, ctx: EvalContext): EvalResult {
830
919
  const localBindings: Record<string, EvalResult> = { ...ctx.bindings, [paramName]: item }
831
920
  const v = evalNode(arrow.body as ts.Expression, { ...ctx, bindings: localBindings })
832
921
  if (v === UNRESOLVED) return UNRESOLVED
833
- mapped.push(v === undefined ? null : v)
922
+ mapped.push(v)
834
923
  }
835
924
  return mapped
836
925
  }