@barefootjs/jsx 0.40.2 → 0.41.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 (95) hide show
  1. package/dist/adapters/callback-method.d.ts +8 -1
  2. package/dist/adapters/callback-method.d.ts.map +1 -1
  3. package/dist/adapters/component-props.d.ts +14 -5
  4. package/dist/adapters/component-props.d.ts.map +1 -1
  5. package/dist/adapters/dsl-template-adapter.d.ts +3 -12
  6. package/dist/adapters/dsl-template-adapter.d.ts.map +1 -1
  7. package/dist/adapters/loop-row-type.d.ts +7 -0
  8. package/dist/adapters/loop-row-type.d.ts.map +1 -1
  9. package/dist/adapters/nil-reading.d.ts +15 -20
  10. package/dist/adapters/nil-reading.d.ts.map +1 -1
  11. package/dist/adapters/non-primitive-equality.d.ts +1 -1
  12. package/dist/adapters/number-value.d.ts +2 -1
  13. package/dist/adapters/number-value.d.ts.map +1 -1
  14. package/dist/adapters/parsed-expr-emitter.d.ts +11 -1
  15. package/dist/adapters/parsed-expr-emitter.d.ts.map +1 -1
  16. package/dist/adapters/primitive-plan.d.ts +40 -11
  17. package/dist/adapters/primitive-plan.d.ts.map +1 -1
  18. package/dist/adapters/prop-classes.d.ts +5 -0
  19. package/dist/adapters/prop-classes.d.ts.map +1 -1
  20. package/dist/analyzer.d.ts.map +1 -1
  21. package/dist/index.d.ts +6 -7
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +566 -367
  24. package/dist/ir-to-client-js/child-props-object.d.ts +43 -1
  25. package/dist/ir-to-client-js/child-props-object.d.ts.map +1 -1
  26. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  27. package/dist/ir-to-client-js/control-flow/plan/build-inner-loop.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/html-template.d.ts.map +1 -1
  30. package/dist/ir-to-client-js/imports.d.ts +2 -2
  31. package/dist/ir-to-client-js/imports.d.ts.map +1 -1
  32. package/dist/ir-to-client-js/phases/props-extraction.d.ts +3 -3
  33. package/dist/ir-to-client-js/plan/build-declaration-emit.d.ts.map +1 -1
  34. package/dist/ir-to-client-js/prune-unused-prop-extractions.d.ts +3 -1
  35. package/dist/ir-to-client-js/prune-unused-prop-extractions.d.ts.map +1 -1
  36. package/dist/jsx-to-ir.d.ts.map +1 -1
  37. package/dist/nullable-signal-attr.d.ts +4 -46
  38. package/dist/nullable-signal-attr.d.ts.map +1 -1
  39. package/dist/props-binding.d.ts +58 -13
  40. package/dist/props-binding.d.ts.map +1 -1
  41. package/dist/ssr-defaults.d.ts +39 -3
  42. package/dist/ssr-defaults.d.ts.map +1 -1
  43. package/dist/types.d.ts +14 -0
  44. package/dist/types.d.ts.map +1 -1
  45. package/package.json +2 -2
  46. package/src/__tests__/__snapshots__/doc-examples.test.ts.snap +6 -6
  47. package/src/__tests__/body-destructured-prop-default-arrow.test.ts +2 -2
  48. package/src/__tests__/body-destructured-props-live.test.ts +5 -5
  49. package/src/__tests__/client-js-generation.test.ts +3 -3
  50. package/src/__tests__/destructure-default-reads-earlier-param.test.ts +7 -7
  51. package/src/__tests__/destructured-props-live.test.ts +1 -1
  52. package/src/__tests__/issue-3861-object-spread-child.test.ts +102 -0
  53. package/src/__tests__/memo-body-expr.test.ts +2 -2
  54. package/src/__tests__/nil-reading.test.ts +3 -2
  55. package/src/__tests__/nullable-signal-attr.test.ts +30 -103
  56. package/src/__tests__/primitive-plan.test.ts +90 -12
  57. package/src/__tests__/prop-default-undefined-only.test.ts +115 -0
  58. package/src/__tests__/prop-references.test.ts +2 -2
  59. package/src/__tests__/props-destructuring.test.ts +17 -0
  60. package/src/__tests__/prune-unused-prop-extractions.test.ts +3 -3
  61. package/src/__tests__/renamed-body-destructure-template.test.ts +7 -7
  62. package/src/__tests__/rewrite-destructured-props.test.ts +1 -1
  63. package/src/__tests__/ssr-defaults.test.ts +113 -25
  64. package/src/__tests__/static-const-child-prop.test.ts +85 -0
  65. package/src/__tests__/written-binding-substitution.test.ts +8 -8
  66. package/src/adapters/callback-method.ts +13 -5
  67. package/src/adapters/component-props.ts +20 -6
  68. package/src/adapters/dsl-template-adapter.ts +26 -28
  69. package/src/adapters/loop-row-type.ts +10 -0
  70. package/src/adapters/nil-reading.ts +23 -25
  71. package/src/adapters/non-primitive-equality.ts +1 -1
  72. package/src/adapters/number-value.ts +26 -2
  73. package/src/adapters/parsed-expr-emitter.ts +31 -2
  74. package/src/adapters/primitive-plan.ts +84 -15
  75. package/src/adapters/prop-classes.ts +16 -3
  76. package/src/analyzer.ts +27 -7
  77. package/src/index.ts +5 -12
  78. package/src/ir-to-client-js/child-props-object.ts +140 -6
  79. package/src/ir-to-client-js/collect-elements.ts +7 -14
  80. package/src/ir-to-client-js/control-flow/plan/build-inner-loop.ts +4 -2
  81. package/src/ir-to-client-js/control-flow/plan/build-loop-child-arm.ts +4 -2
  82. package/src/ir-to-client-js/html-template.ts +18 -9
  83. package/src/ir-to-client-js/imports.ts +1 -1
  84. package/src/ir-to-client-js/phases/props-extraction.ts +11 -7
  85. package/src/ir-to-client-js/plan/build-declaration-emit.ts +40 -7
  86. package/src/ir-to-client-js/prune-unused-prop-extractions.ts +58 -5
  87. package/src/ir-to-client-js/rewrite-destructured-props.ts +31 -1
  88. package/src/jsx-to-ir.ts +113 -60
  89. package/src/nullable-signal-attr.ts +11 -138
  90. package/src/props-binding.ts +84 -19
  91. package/src/ssr-defaults.ts +100 -11
  92. package/src/types.ts +11 -0
  93. package/dist/adapters/ambiguous-nil-arithmetic.d.ts +0 -42
  94. package/dist/adapters/ambiguous-nil-arithmetic.d.ts.map +0 -1
  95. package/src/adapters/ambiguous-nil-arithmetic.ts +0 -103
package/src/jsx-to-ir.ts CHANGED
@@ -47,6 +47,7 @@ import { parseExpression, freeIdentifiers, isSupported, parseBlockBody, foldBloc
47
47
  import { fallbackChainParts, nullishChainParts } from './children-nullish.ts'
48
48
  import type { IRLoopSort, FunctionInfo, ConstantInfo, ParamInfo, FreeReference, SpreadAttr, JsSourceText } from './types.ts'
49
49
  import { resolveStaticConstBinding } from './augment-inherited-props.ts'
50
+ import { isFullyStaticLiteral } from './static-literal.ts'
50
51
  import { componentScopeNames } from './adapters/computed-const.ts'
51
52
  import { formatParamWithType } from './module-exports.ts'
52
53
  import { createError, ErrorCodes, internalInvariant } from './errors.ts'
@@ -7391,7 +7392,7 @@ function closedRestSpreadSource(attr: ts.JsxSpreadAttribute, ctx: TransformConte
7391
7392
  if (ctx.analyzer.restPropsExpandedKeys.length === 0 || !restName || ctx.scope.isBound(restName)) return null
7392
7393
  let expr: ts.Expression = attr.expression
7393
7394
  while (ts.isParenthesizedExpression(expr)) expr = expr.expression
7394
- if (!ts.isIdentifier(expr) || expr.text !== restName) return null
7395
+ if (!ts.isIdentifier(expr) || !isRestBinding(expr.text, restName, ctx)) return null
7395
7396
  const source = ctx.analyzer.restPropsOmittedKeys && ctx.analyzer.propsObjectName ? ctx.analyzer.propsObjectName : restName
7396
7397
  // A body rest's keys read the props object, which a loop row or callback
7397
7398
  // parameter of the same name hides here: no spelling of the per-key read
@@ -7399,6 +7400,19 @@ function closedRestSpreadSource(attr: ts.JsxSpreadAttribute, ctx: TransformConte
7399
7400
  return source !== restName && ctx.scope.isBound(source) ? null : source
7400
7401
  }
7401
7402
 
7403
+ /**
7404
+ * Whether the use-site identifier `name` holds the component's rest props:
7405
+ * the rest binding itself, or a component-scope `const` alias hop of it
7406
+ * (`const a = rest`, through any number of hops). An alias reads the same
7407
+ * object, so its spread unrolls per key like the rest's own. A name the
7408
+ * enclosing loop rows or callbacks bind is that binding.
7409
+ */
7410
+ function isRestBinding(name: string, restName: string, ctx: TransformContext): boolean {
7411
+ if (name === restName) return true
7412
+ if (ctx.scope.isBound(name)) return false
7413
+ return resolveAliasOrigin(childrenAliasHops(ctx.analyzer), name, n => (n === restName ? true : null)) === true
7414
+ }
7415
+
7402
7416
  /**
7403
7417
  * BF101 for a spread of a props-object body rest (`const { a, ...rest } =
7404
7418
  * props`) where a loop row or callback parameter shadows the props
@@ -7412,7 +7426,7 @@ function refuseBodyRestSpreadUnderShadowedProps(attr: ts.JsxSpreadAttribute, ctx
7412
7426
  if (ctx.scope.isBound(restName) || !ctx.scope.isBound(propsName)) return false
7413
7427
  let expr: ts.Expression = attr.expression
7414
7428
  while (ts.isParenthesizedExpression(expr)) expr = expr.expression
7415
- if (!ts.isIdentifier(expr) || expr.text !== restName) return false
7429
+ if (!ts.isIdentifier(expr) || !isRestBinding(expr.text, restName, ctx)) return false
7416
7430
  ctx.analyzer.errors.push({
7417
7431
  code: 'BF101',
7418
7432
  severity: 'error',
@@ -7655,16 +7669,46 @@ function isEffectFreeExpression(expr: ts.Expression): boolean {
7655
7669
  * handler name. `null` otherwise, and the spread stays a spread.
7656
7670
  */
7657
7671
  function expandStaticConstSpread(attr: ts.JsxSpreadAttribute, ctx: TransformContext): Array<{ key: string; text: string }> | null {
7658
- let expr: ts.Expression = attr.expression
7672
+ const init = staticConstInitializerOf(attr.expression, ctx)
7673
+ if (!init || !ts.isObjectLiteralExpression(init)) return null
7674
+ return staticObjectSpreadEntries(init)
7675
+ }
7676
+
7677
+ /**
7678
+ * The initializer of the const a bare-name read `expr` reaches, when that
7679
+ * const holds an array or object literal (`const QS = ['a', 'b']`,
7680
+ * `const base = { label: 'x' }`): the read is the const's value, so the IR
7681
+ * can carry the literal in its place. Which declaration the name reaches is
7682
+ * `resolveStaticConstBinding`'s decision; a module const a component
7683
+ * binding of the same name hides (`function C({ QS })`) is not reached.
7684
+ * `null` for any other read or initializer.
7685
+ */
7686
+ function staticConstInitializerOf(expr: ts.Expression, ctx: TransformContext): ts.ArrayLiteralExpression | ts.ObjectLiteralExpression | null {
7659
7687
  while (ts.isParenthesizedExpression(expr)) expr = expr.expression
7660
7688
  if (!ts.isIdentifier(expr)) return null
7661
7689
  const name = expr.text
7662
7690
  const constant = resolveStaticConstBinding(name, ctx.analyzer.localConstants, n => ctx.scope.isBound(n))
7663
- if (!constant || constant.parsed?.kind !== 'object-literal') return null
7691
+ const kind = constant?.parsed?.kind
7692
+ if (!constant || (kind !== 'object-literal' && kind !== 'array-literal')) return null
7664
7693
  if (constant.isModule && componentScopeNames(ctx.analyzer).has(name)) return null
7665
7694
  const init = parseConstInitializer(constant)
7666
- if (!init || !ts.isObjectLiteralExpression(init)) return null
7667
- return staticObjectSpreadEntries(init)
7695
+ if (!init || !(ts.isObjectLiteralExpression(init) || ts.isArrayLiteralExpression(init))) return null
7696
+ return init
7697
+ }
7698
+
7699
+ /**
7700
+ * `value` with `staticConstLiteral` set when the prop's value is a bare read
7701
+ * of a const holding a fully static array or object literal (`<Kid xs={QS} />`
7702
+ * beside `const QS = ['a', 'b']`): only a literal that reads no name and
7703
+ * calls nothing (`isFullyStaticLiteral`). `value` unchanged otherwise.
7704
+ */
7705
+ function withStaticConstLiteral(value: AttrValue, attr: ts.JsxAttribute, ctx: TransformContext): AttrValue {
7706
+ if (value.kind !== 'expression' || !attr.initializer || !ts.isJsxExpression(attr.initializer) || !attr.initializer.expression) return value
7707
+ const init = staticConstInitializerOf(attr.initializer.expression, ctx)
7708
+ if (!init) return value
7709
+ const parsed = tsNodeToParsedExpr(init)
7710
+ if (!isFullyStaticLiteral(parsed)) return value
7711
+ return { ...value, staticConstLiteral: { expr: astText(init), parsed } }
7668
7712
  }
7669
7713
 
7670
7714
  /**
@@ -9514,65 +9558,74 @@ function processComponentProps(
9514
9558
  }
9515
9559
  }
9516
9560
 
9517
- let value = getAttributeValue(attr, ctx)
9518
- // Components receive props as runtime values, so collapse a structured
9519
- // template literal back into a JS expression — but keep the parsed
9520
- // parts in `parts` so template-based SSR adapters (Mojo, Go) can still
9521
- // emit structured lookups / ternaries instead of round-tripping a raw
9522
- // JS source through their expression pipelines. JS-runtime adapters
9523
- // (Hono) keep using `expr`. Boolean-attr is also promoted to
9524
- // shorthand (`<X disabled />` → `disabled={true}`).
9525
- if (value.kind === 'template') {
9526
- // Collapse using the raw part values, but also carry the
9527
- // template-variant projection (parts' `templateExpr` /
9528
- // `templateCondition` / `templateKey`, i.e. destructured-prop refs
9529
- // rewritten to `_p.X`) as `templateExpr`. Without it, the
9530
- // `templateExpr` derivation below walks the ORIGINAL initializer AST
9531
- // — for a const-resolved template (`className={classes}`) that AST is
9532
- // the bare `classes` identifier with no prop refs, so the rewrite
9533
- // no-ops and the module-scope registration template leaks bare
9534
- // destructured props into `renderChild(...)` (#2468).
9535
- const collapsed = templatePartsToJsExpr(value.parts)
9536
- const collapsedTemplate = templatePartsToJsExpr(value.parts, { useTemplate: true })
9537
- value = AttrValueOf.expression(collapsed, {
9538
- parts: value.parts,
9539
- ...(collapsedTemplate !== collapsed && { templateExpr: collapsedTemplate }),
9540
- })
9541
- } else if (value.kind === 'boolean-attr') {
9542
- value = AttrValueOf.booleanShorthand()
9543
- }
9561
+ props.push(valueComponentProp(attr, name, ctx))
9562
+ }
9544
9563
 
9545
- let clientOnly: boolean | undefined
9546
- if (attr.initializer && ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
9547
- if (value.kind === 'expression' && value.templateExpr === undefined) {
9548
- const rewritten = rewriteBarePropRefs(value.expr, attr.initializer.expression, ctx)
9549
- if (rewritten !== value.expr) {
9550
- value = { ...value, templateExpr: rewritten }
9551
- }
9552
- }
9553
- // `/* @client */` in component-prop initializer position: defer
9554
- // to hydrate. Detection routed through the shared helper so it
9555
- // agrees with JSX-child / element-attr sites. Downstream:
9556
- // html-template strips the prop from `renderChild`; `initChild`'s
9557
- // `propsExpr` already runs in init scope so the value reaches
9558
- // the child component once init runs.
9559
- if (hasLeadingClientDirective(attr.initializer.expression, ctx.sourceFile)) {
9560
- clientOnly = true
9561
- }
9562
- }
9564
+ return props
9565
+ }
9563
9566
 
9564
- const freeIdentifiers = attrFreeIdentifiers(attr)
9565
- props.push({
9566
- name,
9567
- value,
9568
- clientOnly,
9569
- loc: getSourceLocation(attr, ctx.sourceFile, ctx.filePath),
9570
- ...computeReactivityFlags(attr, ctx),
9571
- ...(freeIdentifiers !== undefined && { freeIdentifiers }),
9567
+ /**
9568
+ * The `IRProp` for one JSX attribute of a component whose value is not a
9569
+ * spread, a JSX element or a refused JSX-wrapping shape (those are
9570
+ * `processComponentProps`'s own cases).
9571
+ */
9572
+ function valueComponentProp(attr: ts.JsxAttribute, name: string, ctx: TransformContext): IRProp {
9573
+ let value = getAttributeValue(attr, ctx)
9574
+ // Components receive props as runtime values, so collapse a structured
9575
+ // template literal back into a JS expression — but keep the parsed
9576
+ // parts in `parts` so template-based SSR adapters (Mojo, Go) can still
9577
+ // emit structured lookups / ternaries instead of round-tripping a raw
9578
+ // JS source through their expression pipelines. JS-runtime adapters
9579
+ // (Hono) keep using `expr`. Boolean-attr is also promoted to
9580
+ // shorthand (`<X disabled />` → `disabled={true}`).
9581
+ if (value.kind === 'template') {
9582
+ // Collapse using the raw part values, but also carry the
9583
+ // template-variant projection (parts' `templateExpr` /
9584
+ // `templateCondition` / `templateKey`, i.e. destructured-prop refs
9585
+ // rewritten to `_p.X`) as `templateExpr`. Without it, the
9586
+ // `templateExpr` derivation below walks the ORIGINAL initializer AST
9587
+ // — for a const-resolved template (`className={classes}`) that AST is
9588
+ // the bare `classes` identifier with no prop refs, so the rewrite
9589
+ // no-ops and the module-scope registration template leaks bare
9590
+ // destructured props into `renderChild(...)` (#2468).
9591
+ const collapsed = templatePartsToJsExpr(value.parts)
9592
+ const collapsedTemplate = templatePartsToJsExpr(value.parts, { useTemplate: true })
9593
+ value = AttrValueOf.expression(collapsed, {
9594
+ parts: value.parts,
9595
+ ...(collapsedTemplate !== collapsed && { templateExpr: collapsedTemplate }),
9572
9596
  })
9597
+ } else if (value.kind === 'boolean-attr') {
9598
+ value = AttrValueOf.booleanShorthand()
9573
9599
  }
9574
9600
 
9575
- return props
9601
+ let clientOnly: boolean | undefined
9602
+ if (attr.initializer && ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
9603
+ if (value.kind === 'expression' && value.templateExpr === undefined) {
9604
+ const rewritten = rewriteBarePropRefs(value.expr, attr.initializer.expression, ctx)
9605
+ if (rewritten !== value.expr) {
9606
+ value = { ...value, templateExpr: rewritten }
9607
+ }
9608
+ }
9609
+ // `/* @client */` in component-prop initializer position: defer
9610
+ // to hydrate. Detection routed through the shared helper so it
9611
+ // agrees with JSX-child / element-attr sites. Downstream:
9612
+ // html-template strips the prop from `renderChild`; `initChild`'s
9613
+ // `propsExpr` already runs in init scope so the value reaches
9614
+ // the child component once init runs.
9615
+ if (hasLeadingClientDirective(attr.initializer.expression, ctx.sourceFile)) {
9616
+ clientOnly = true
9617
+ }
9618
+ }
9619
+
9620
+ const freeIdentifiers = attrFreeIdentifiers(attr)
9621
+ return {
9622
+ name,
9623
+ value: clientOnly ? value : withStaticConstLiteral(value, attr, ctx),
9624
+ clientOnly,
9625
+ loc: getSourceLocation(attr, ctx.sourceFile, ctx.filePath),
9626
+ ...computeReactivityFlags(attr, ctx),
9627
+ ...(freeIdentifiers !== undefined && { freeIdentifiers }),
9628
+ }
9576
9629
  }
9577
9630
 
9578
9631
  // =============================================================================
@@ -17,7 +17,6 @@
17
17
 
18
18
  import type { ParsedExpr } from './expression-parser.ts'
19
19
  import { isBooleanResultParsed } from './adapters/boolean-result.ts'
20
- import { BindingScope } from './scope/binding-scope.ts'
21
20
  import type { ComponentIR, IRMetadata, MemoInfo, SignalInfo, TypeInfo } from './types.ts'
22
21
 
23
22
  function isNullishType(type: TypeInfo): boolean {
@@ -253,15 +252,14 @@ export interface NullableScalarProp {
253
252
 
254
253
  /**
255
254
  * What a nullable number prop's nil stands for at SSR (#3533). JS reads an
256
- * absent prop as `undefined` (`NaN` in arithmetic) and a `null` one as `0`,
257
- * while a template engine holds both as the same nil, so the declared type
258
- * decides. A prop whose type admits `null` (`n: number | null`) reads its
255
+ * absent prop as `undefined` (`NaN` in arithmetic) and a `null` one as `0`;
256
+ * the declared type decides the coercion an adapter spells statically. A prop whose type admits `null` (`n: number | null`) reads its
259
257
  * nil as `null`. A prop that can only be absent (`n?: number`,
260
258
  * `n: number | undefined`) reads it as `undefined`; a present value, `0`
261
259
  * included, is unaffected. A prop that admits both (`n?: number | null`,
262
260
  * `n: number | null | undefined`) is `'either'`: the type cannot say which
263
- * one its nil stands for, so arithmetic over it is refused
264
- * (`arithmeticOperandNilIsAmbiguous`).
261
+ * one its nil stands for, so the operand is left to the runtime's helper,
262
+ * which reads the value itself (spec/js-undefined-value.md).
265
263
  */
266
264
  export type NullableNumberPropNil = 'null' | 'undefined' | 'either'
267
265
 
@@ -601,9 +599,10 @@ export function arithmeticOperandCoercion(
601
599
  if (!isNumericArithmetic(op, other)) return null
602
600
  const seed = arithmeticOperandSeed(operand, ctx, isShadowed)
603
601
  if (seed === 'absent') return 'undefined'
604
- // `'either'` is refused (`arithmeticOperandNilIsAmbiguous`); the spelling
605
- // keeps the `null` reading so the refused template stays well-formed.
606
- return seed === 'either' ? 'null' : seed
602
+ // `'either'`: the type cannot say which nil the operand holds, so it is
603
+ // left as it is and the runtime's helper reads its value, `null` or
604
+ // `UNDEF`, exactly (spec/js-undefined-value.md).
605
+ return seed === 'either' ? null : seed
607
606
  }
608
607
 
609
608
  /** The relational operators, whose operands JS converts with ToNumber unless both are strings. */
@@ -614,9 +613,9 @@ const RELATIONAL_OPS: ReadonlySet<string> = new Set(['<', '<=', '>', '>='])
614
613
  * relational helpers read a nil operand as JS `null` (`0`), so only an operand
615
614
  * whose nil reads as `undefined` needs spelling: it goes through `NaN`, which
616
615
  * makes the comparison false, as `undefined < 1` is in JS. A nil whose
617
- * reading the type leaves open (`n?: number | null`) is refused as it is in
618
- * arithmetic (`arithmeticOperandNilIsAmbiguous`, #3700); the spelling keeps
619
- * the helper's `null` reading so the refused template stays well-formed.
616
+ * reading the type leaves open (`n?: number | null`, `s?: string | null`) is
617
+ * left as it is: the relational helper reads its value, `null` or `UNDEF`,
618
+ * exactly.
620
619
  */
621
620
  function relationalOperandCoercion(
622
621
  operand: ParsedExpr | undefined,
@@ -631,132 +630,6 @@ function relationalOperandCoercion(
631
630
  return scalarPropRead(operand, ctx, isShadowed)?.nil === 'undefined' ? 'undefined-keep' : null
632
631
  }
633
632
 
634
- /**
635
- * Whether an arithmetic operand reads a number prop whose type admits both
636
- * `null` and absence (`n?: number | null`), directly or through a memo
637
- * (#3700). JS reads the omitted prop as `undefined` (`NaN` in arithmetic)
638
- * and a `null` one as `0`; a template engine holds both as one nil and the
639
- * type cannot say which, so no spelling of {@link arithmeticOperandCoercion}
640
- * renders both. Template adapters refuse such an operand instead of
641
- * rendering one reading silently. Same operators and scope as
642
- * {@link arithmeticOperandCoercion}, relational operators included: they
643
- * apply ToNumber too (`undefined < 1` is false, `null < 1` is true). Under a
644
- * relational operator a string or boolean prop admitting both
645
- * (`s?: string | null`) is ambiguous for the same reason
646
- * ({@link ambiguousNilFamily}).
647
- */
648
- export function arithmeticOperandNilIsAmbiguous(
649
- op: string,
650
- operand: ParsedExpr | undefined,
651
- other: ParsedExpr | undefined,
652
- ctx: NullishAttrContext,
653
- isShadowed: (name: string) => boolean = () => false,
654
- ): boolean {
655
- return ambiguousNilFamily(op, operand, other, ctx, isShadowed) !== null
656
- }
657
-
658
- /** The declared family of a prop whose nil an operator cannot read ({@link ambiguousNilFamily}). */
659
- export type AmbiguousNilFamily = 'number' | 'string' | 'boolean'
660
-
661
- /**
662
- * The declared family of the prop behind an operand that
663
- * {@link arithmeticOperandNilIsAmbiguous} matches, or `null` when it does
664
- * not match: `'number'` for a numeric `either` operand of arithmetic or a
665
- * comparison, `'string'` / `'boolean'` for a string or boolean `either`
666
- * operand of a comparison (#3824 step 3).
667
- */
668
- export function ambiguousNilFamily(
669
- op: string,
670
- operand: ParsedExpr | undefined,
671
- other: ParsedExpr | undefined,
672
- ctx: NullishAttrContext,
673
- isShadowed: (name: string) => boolean = () => false,
674
- ): AmbiguousNilFamily | null {
675
- const relational = RELATIONAL_OPS.has(op)
676
- if (!relational && !isNumericArithmetic(op, other)) return null
677
- if (arithmeticOperandSeed(operand, ctx, isShadowed) === 'either') return 'number'
678
- if (!relational) return null
679
- const scalar = scalarPropRead(operand, ctx, isShadowed)
680
- return scalar?.nil === 'either' ? scalar.family : null
681
- }
682
-
683
- /**
684
- * Every arithmetic operand in `expr` that {@link arithmeticOperandNilIsAmbiguous}
685
- * matches, for a whole expression a template adapter lowers without visiting
686
- * each operator through its emitter (a memo body, a `.filter()` predicate, an
687
- * expression the runtime evaluator runs). Operands of binary operators and of
688
- * unary minus and plus count. `scope` is where the expression is read; each arrow in
689
- * it enters its params as a callback frame (`BindingScope.enterCallback`),
690
- * so they shadow within its body only.
691
- */
692
- export function ambiguousNilArithmeticOperands(
693
- expr: ParsedExpr,
694
- ctx: NullishAttrContext,
695
- scope: BindingScope = BindingScope.EMPTY,
696
- ): ParsedExpr[] {
697
- return ambiguousNilOperands(expr, ctx, scope).map(found => found.operand)
698
- }
699
-
700
- /** {@link ambiguousNilArithmeticOperands}, each operand with its prop's family ({@link ambiguousNilFamily}). */
701
- export function ambiguousNilOperands(
702
- expr: ParsedExpr,
703
- ctx: NullishAttrContext,
704
- scope: BindingScope = BindingScope.EMPTY,
705
- ): Array<{ operand: ParsedExpr; family: AmbiguousNilFamily }> {
706
- const found: Array<{ operand: ParsedExpr; family: AmbiguousNilFamily }> = []
707
- const visit = (e: ParsedExpr, at: BindingScope): void => {
708
- if (e.kind === 'arrow') {
709
- visit(e.body, at.enterCallback(e.params))
710
- return
711
- }
712
- for (const [op, operand, other] of arithmeticOperandsOf(e)) {
713
- const family = ambiguousNilFamily(op, operand, other, ctx, at.asShadowPredicate())
714
- if (family !== null) found.push({ operand, family })
715
- }
716
- for (const child of parsedExprChildren(e)) visit(child, at)
717
- }
718
- if (!ctx.nullableNumberProps?.size && !ctx.nullableScalarProps?.size) return found
719
- visit(expr, scope)
720
- return found
721
- }
722
-
723
- /** The `[op, operand, other]` triples of an arithmetic node's operands. A
724
- * unary minus or plus applies ToNumber to its operand and has no `other`. */
725
- function arithmeticOperandsOf(e: ParsedExpr): Array<[string, ParsedExpr, ParsedExpr | undefined]> {
726
- if (e.kind === 'binary') return [[e.op, e.left, e.right], [e.op, e.right, e.left]]
727
- if (e.kind === 'unary' && (e.op === '-' || e.op === '+')) return [[e.op, e.argument, undefined]]
728
- return []
729
- }
730
-
731
- /** The value-position sub-expressions of `e` (an arrow's body included). */
732
- function parsedExprChildren(e: ParsedExpr): ParsedExpr[] {
733
- switch (e.kind) {
734
- case 'call':
735
- return [e.callee, ...e.args]
736
- case 'member':
737
- return [e.object]
738
- case 'index-access':
739
- return [e.object, e.index]
740
- case 'binary':
741
- case 'logical':
742
- return [e.left, e.right]
743
- case 'unary':
744
- return [e.argument]
745
- case 'conditional':
746
- return [e.test, e.consequent, e.alternate]
747
- case 'template-literal':
748
- return e.parts.flatMap(p => (p.type === 'expression' ? [p.expr] : []))
749
- case 'array-literal':
750
- return e.elements
751
- case 'array-method':
752
- return [e.object, ...e.args, ...(e.method === 'flat' && e.depthExpr ? [e.depthExpr] : [])]
753
- case 'object-literal':
754
- return e.properties.map(p => (p.kind === 'spread' ? p.expr : p.value))
755
- default:
756
- return []
757
- }
758
- }
759
-
760
633
  /** The operators {@link arithmeticOperandCoercion} applies `ToNumber` under:
761
634
  * a `+` with no `other` is unary plus, which always does. */
762
635
  function isNumericArithmetic(op: string, other: ParsedExpr | undefined): boolean {
@@ -455,7 +455,14 @@ const EMPTY_SET: ReadonlySet<string> = new Set()
455
455
  * never bound a parameter — so callers synthesize one of these instead of a
456
456
  * full `ParamInfo` (which would need a fabricated `type`/`optional`).
457
457
  */
458
- export type LivePropReadInfo = Pick<ParamInfo, 'name' | 'sourceName' | 'defaultValue' | 'defaultContainsArrow' | 'defaultParts'>
458
+ export type LivePropReadInfo = Pick<ParamInfo, 'name' | 'sourceName' | 'defaultValue' | 'defaultContainsArrow' | 'defaultParts'> & {
459
+ /**
460
+ * The fallback is the author's own `??` (`const label = props.label ??
461
+ * 'x'`, a body alias), which replaces `null` too, not a destructure
462
+ * default, which replaces only `undefined`.
463
+ */
464
+ readonly coalescesNull?: boolean
465
+ }
459
466
 
460
467
  /** `_p.<callerKey>` — `_p` is always keyed by the caller-facing name (#2524 CSR half). */
461
468
  export function propReadBase(p: LivePropReadInfo): string {
@@ -463,8 +470,8 @@ export function propReadBase(p: LivePropReadInfo): string {
463
470
  }
464
471
 
465
472
  /**
466
- * The text a destructure default contributes as the right operand of a `??`
467
- * prop read. An arrow (or function-expression) default needs its own
473
+ * The text a destructure default contributes to a prop read
474
+ * ({@link composePropRead}). An arrow (or function-expression) default needs its own
468
475
  * parens — `??` binds tighter than an arrow head, so `_p.onInput ?? () =>
469
476
  * {}` is a SyntaxError. The one implementation of that decision, shared by
470
477
  * `propReadFallback` below (every live `_p.X` read) and `collectConstant`'s
@@ -477,11 +484,24 @@ export function coalesceDefaultText(defaultValue: string, defaultContainsArrow:
477
484
  }
478
485
 
479
486
  /**
480
- * The `??` right-hand side for a prop read, or null when the bare read is
481
- * correct. Precedence:
487
+ * What a prop read falls back to:
488
+ * - `default`: the prop's destructure default, which JS applies to an
489
+ * absent or `undefined` prop only, never to `null`
490
+ * (`spec/js-undefined-value.md`, "Decisions" (6)).
491
+ * - `guard`: a value the compiler supplies for a defaultless prop so the
492
+ * read cannot throw (`[]` for a loop array, `{}` for a member read); it
493
+ * replaces either nil.
494
+ */
495
+ export interface PropReadFallback {
496
+ readonly kind: 'default' | 'guard'
497
+ readonly text: string
498
+ }
499
+
500
+ /**
501
+ * The fallback of a prop read, or null when the bare read is correct.
502
+ * Precedence:
482
503
  * 1. an explicit destructure default (`{ x = 1 }`) — an arrow default gets
483
- * an extra paren, since `??` binds tighter than the arrow head and
484
- * `_p.onInput ?? () => {}` would be a syntax error.
504
+ * an extra paren, since `??` / `?:` bind tighter than the arrow head.
485
505
  * 2. `usedAsLoopArray` → `[]`.
486
506
  * 3. property/index access → `{}`, UNLESS the prop also guards a
487
507
  * conditional: `{}` is truthy, so that would always render the branch.
@@ -494,28 +514,72 @@ export function propReadFallback(
494
514
  p: LivePropReadInfo,
495
515
  usage: PropUsage | undefined,
496
516
  usedAsCondition: boolean,
497
- ): string | null {
498
- const defaultText = propDefaultText(p)
499
- if (defaultText) return coalesceDefaultText(defaultText, p.defaultContainsArrow)
500
- if (usage?.usedAsLoopArray) return '[]'
501
- if (propHasPropertyAccess(usage) && !usedAsCondition) return '{}'
517
+ retained?: ReadonlySet<string>,
518
+ ): PropReadFallback | null {
519
+ const defaultText = propDefaultText(p, retained)
520
+ if (defaultText) return { kind: p.coalescesNull ? 'guard' : 'default', text: coalesceDefaultText(defaultText, p.defaultContainsArrow) }
521
+ if (usage?.usedAsLoopArray) return { kind: 'guard', text: '[]' }
522
+ if (propHasPropertyAccess(usage) && !usedAsCondition) return { kind: 'guard', text: '{}' }
502
523
  return null
503
524
  }
504
525
 
526
+ /**
527
+ * A prop read `base` (a plain property read, `_p.x` / `props.x`, so reading
528
+ * it twice is safe) with its fallback, unparenthesized: a destructure
529
+ * default as `base === undefined ? default : base`, which keeps an explicit
530
+ * `null`, as JS does; a guard as `base ?? guard`. The one spelling every
531
+ * client-JS prop read and the body-destructure expansion share, and the
532
+ * shape `parsePropReadInitializer` recognizes.
533
+ */
534
+ export function composePropRead(base: string, fallback: PropReadFallback | null): string {
535
+ if (fallback === null) return base
536
+ return fallback.kind === 'default' ? `${base} === undefined ? ${fallback.text} : ${base}` : `${base} ?? ${fallback.text}`
537
+ }
538
+
505
539
  /**
506
540
  * A prop's destructure default as client JS. A default that reads an earlier
507
541
  * binding of its own pattern (`{ off = false, on = off }`, #3531) renders each
508
- * read as that prop's own live read (`_p.off ?? false`), since the emitted
509
- * scope binds no `off`; any other default is its source text. Undefined when
510
- * the prop has no default.
542
+ * read as that prop's own live read (`_p.off === undefined ? false :
543
+ * _p.off`) where the emitted scope binds no `off`; any other default is its
544
+ * source text. `retained` names the earlier bindings that ARE locals of the
545
+ * emitted scope (`retainedPropLocals`): a read of one stays a read of that
546
+ * local, as in JS, so a default sharing an earlier binding's array, or
547
+ * reading a value a default assigned to it, sees that binding. Undefined
548
+ * when the prop has no default.
511
549
  */
512
- export function propDefaultText(p: LivePropReadInfo): string | undefined {
550
+ export function propDefaultText(p: LivePropReadInfo, retained: ReadonlySet<string> = EMPTY_SET): string | undefined {
513
551
  if (!p.defaultParts) return p.defaultValue
514
552
  return p.defaultParts
515
- .map(part => (part.kind === 'text' ? part.text : livePropReadExpr(part.param, undefined, false)))
553
+ .map(part => {
554
+ if (part.kind === 'text') return part.text
555
+ return retained.has(part.param.name) ? part.param.name : livePropReadExpr(part.param, undefined, false, retained)
556
+ })
516
557
  .join('')
517
558
  }
518
559
 
560
+ /**
561
+ * The destructured prop bindings the init body keeps as locals, by local
562
+ * name: a written or mutated parameter (`let start = …`, `emitPropsExtraction`)
563
+ * and a body destructure of the props object that does not keep its declared
564
+ * value (`let { a } = props`, or one mutated later). Every other destructured
565
+ * binding is read live (`keepsDeclaredValue`). A default reading one of these
566
+ * reads the local ({@link propDefaultText}).
567
+ */
568
+ export function retainedPropLocals(b: {
569
+ propsObjectName: string | null
570
+ propsParams: readonly ParamInfo[]
571
+ localConstants: readonly ConstantInfo[]
572
+ }): ReadonlySet<string> {
573
+ const names = new Set<string>()
574
+ if (b.propsObjectName === null) {
575
+ for (const p of b.propsParams) if (!p.isRest && !keepsDeclaredValue(p)) names.add(p.name)
576
+ }
577
+ for (const c of b.localConstants) {
578
+ if (c.propsDestructure && !c.isModule && !keepsDeclaredValue(c)) names.add(c.name)
579
+ }
580
+ return names
581
+ }
582
+
519
583
  /**
520
584
  * The live read of a destructured prop inside init scope, in the same shape
521
585
  * props-object mode emits for `props.X`. The one formula every live-read
@@ -536,10 +600,11 @@ export function livePropReadExpr(
536
600
  p: LivePropReadInfo,
537
601
  usage: PropUsage | undefined,
538
602
  usedAsCondition: boolean,
603
+ retained?: ReadonlySet<string>,
539
604
  ): string {
540
605
  const base = propReadBase(p)
541
- const fallback = propReadFallback(p, usage, usedAsCondition)
542
- return fallback === null ? base : `(${base} ?? ${fallback})`
606
+ const fallback = propReadFallback(p, usage, usedAsCondition, retained)
607
+ return fallback === null ? base : `(${composePropRead(base, fallback)})`
543
608
  }
544
609
 
545
610
  /**