@barefootjs/jsx 0.40.2 → 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 (88) 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 +3 -4
  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/parsed-expr-emitter.d.ts +11 -1
  13. package/dist/adapters/parsed-expr-emitter.d.ts.map +1 -1
  14. package/dist/adapters/primitive-plan.d.ts +40 -11
  15. package/dist/adapters/primitive-plan.d.ts.map +1 -1
  16. package/dist/adapters/prop-classes.d.ts +5 -0
  17. package/dist/adapters/prop-classes.d.ts.map +1 -1
  18. package/dist/analyzer.d.ts.map +1 -1
  19. package/dist/index.d.ts +5 -6
  20. package/dist/index.d.ts.map +1 -1
  21. package/dist/index.js +390 -228
  22. package/dist/ir-to-client-js/child-props-object.d.ts +43 -1
  23. package/dist/ir-to-client-js/child-props-object.d.ts.map +1 -1
  24. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  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-loop-child-arm.d.ts.map +1 -1
  27. package/dist/ir-to-client-js/html-template.d.ts.map +1 -1
  28. package/dist/ir-to-client-js/imports.d.ts +2 -2
  29. package/dist/ir-to-client-js/imports.d.ts.map +1 -1
  30. package/dist/ir-to-client-js/phases/props-extraction.d.ts +3 -3
  31. package/dist/ir-to-client-js/plan/build-declaration-emit.d.ts.map +1 -1
  32. package/dist/ir-to-client-js/prune-unused-prop-extractions.d.ts +3 -1
  33. package/dist/ir-to-client-js/prune-unused-prop-extractions.d.ts.map +1 -1
  34. package/dist/jsx-to-ir.d.ts.map +1 -1
  35. package/dist/nullable-signal-attr.d.ts +4 -46
  36. package/dist/nullable-signal-attr.d.ts.map +1 -1
  37. package/dist/props-binding.d.ts +58 -13
  38. package/dist/props-binding.d.ts.map +1 -1
  39. package/dist/ssr-defaults.d.ts +39 -3
  40. package/dist/ssr-defaults.d.ts.map +1 -1
  41. package/package.json +2 -2
  42. package/src/__tests__/__snapshots__/doc-examples.test.ts.snap +6 -6
  43. package/src/__tests__/body-destructured-prop-default-arrow.test.ts +2 -2
  44. package/src/__tests__/body-destructured-props-live.test.ts +5 -5
  45. package/src/__tests__/client-js-generation.test.ts +3 -3
  46. package/src/__tests__/destructure-default-reads-earlier-param.test.ts +7 -7
  47. package/src/__tests__/destructured-props-live.test.ts +1 -1
  48. package/src/__tests__/issue-3861-object-spread-child.test.ts +102 -0
  49. package/src/__tests__/memo-body-expr.test.ts +2 -2
  50. package/src/__tests__/nil-reading.test.ts +3 -2
  51. package/src/__tests__/nullable-signal-attr.test.ts +30 -103
  52. package/src/__tests__/primitive-plan.test.ts +90 -12
  53. package/src/__tests__/prop-default-undefined-only.test.ts +115 -0
  54. package/src/__tests__/prop-references.test.ts +2 -2
  55. package/src/__tests__/props-destructuring.test.ts +17 -0
  56. package/src/__tests__/prune-unused-prop-extractions.test.ts +3 -3
  57. package/src/__tests__/renamed-body-destructure-template.test.ts +7 -7
  58. package/src/__tests__/rewrite-destructured-props.test.ts +1 -1
  59. package/src/__tests__/ssr-defaults.test.ts +113 -25
  60. package/src/__tests__/written-binding-substitution.test.ts +8 -8
  61. package/src/adapters/callback-method.ts +13 -5
  62. package/src/adapters/component-props.ts +3 -4
  63. package/src/adapters/dsl-template-adapter.ts +26 -28
  64. package/src/adapters/loop-row-type.ts +10 -0
  65. package/src/adapters/nil-reading.ts +23 -25
  66. package/src/adapters/non-primitive-equality.ts +1 -1
  67. package/src/adapters/parsed-expr-emitter.ts +31 -2
  68. package/src/adapters/primitive-plan.ts +84 -15
  69. package/src/adapters/prop-classes.ts +16 -3
  70. package/src/analyzer.ts +27 -7
  71. package/src/index.ts +4 -11
  72. package/src/ir-to-client-js/child-props-object.ts +140 -6
  73. package/src/ir-to-client-js/collect-elements.ts +7 -14
  74. package/src/ir-to-client-js/control-flow/plan/build-inner-loop.ts +4 -2
  75. package/src/ir-to-client-js/control-flow/plan/build-loop-child-arm.ts +4 -2
  76. package/src/ir-to-client-js/html-template.ts +18 -9
  77. package/src/ir-to-client-js/imports.ts +1 -1
  78. package/src/ir-to-client-js/phases/props-extraction.ts +11 -7
  79. package/src/ir-to-client-js/plan/build-declaration-emit.ts +40 -7
  80. package/src/ir-to-client-js/prune-unused-prop-extractions.ts +58 -5
  81. package/src/ir-to-client-js/rewrite-destructured-props.ts +31 -1
  82. package/src/jsx-to-ir.ts +15 -2
  83. package/src/nullable-signal-attr.ts +11 -138
  84. package/src/props-binding.ts +84 -19
  85. package/src/ssr-defaults.ts +100 -11
  86. package/dist/adapters/ambiguous-nil-arithmetic.d.ts +0 -42
  87. package/dist/adapters/ambiguous-nil-arithmetic.d.ts.map +0 -1
  88. package/src/adapters/ambiguous-nil-arithmetic.ts +0 -103
package/src/jsx-to-ir.ts CHANGED
@@ -7391,7 +7391,7 @@ function closedRestSpreadSource(attr: ts.JsxSpreadAttribute, ctx: TransformConte
7391
7391
  if (ctx.analyzer.restPropsExpandedKeys.length === 0 || !restName || ctx.scope.isBound(restName)) return null
7392
7392
  let expr: ts.Expression = attr.expression
7393
7393
  while (ts.isParenthesizedExpression(expr)) expr = expr.expression
7394
- if (!ts.isIdentifier(expr) || expr.text !== restName) return null
7394
+ if (!ts.isIdentifier(expr) || !isRestBinding(expr.text, restName, ctx)) return null
7395
7395
  const source = ctx.analyzer.restPropsOmittedKeys && ctx.analyzer.propsObjectName ? ctx.analyzer.propsObjectName : restName
7396
7396
  // A body rest's keys read the props object, which a loop row or callback
7397
7397
  // parameter of the same name hides here: no spelling of the per-key read
@@ -7399,6 +7399,19 @@ function closedRestSpreadSource(attr: ts.JsxSpreadAttribute, ctx: TransformConte
7399
7399
  return source !== restName && ctx.scope.isBound(source) ? null : source
7400
7400
  }
7401
7401
 
7402
+ /**
7403
+ * Whether the use-site identifier `name` holds the component's rest props:
7404
+ * the rest binding itself, or a component-scope `const` alias hop of it
7405
+ * (`const a = rest`, through any number of hops). An alias reads the same
7406
+ * object, so its spread unrolls per key like the rest's own. A name the
7407
+ * enclosing loop rows or callbacks bind is that binding.
7408
+ */
7409
+ function isRestBinding(name: string, restName: string, ctx: TransformContext): boolean {
7410
+ if (name === restName) return true
7411
+ if (ctx.scope.isBound(name)) return false
7412
+ return resolveAliasOrigin(childrenAliasHops(ctx.analyzer), name, n => (n === restName ? true : null)) === true
7413
+ }
7414
+
7402
7415
  /**
7403
7416
  * BF101 for a spread of a props-object body rest (`const { a, ...rest } =
7404
7417
  * props`) where a loop row or callback parameter shadows the props
@@ -7412,7 +7425,7 @@ function refuseBodyRestSpreadUnderShadowedProps(attr: ts.JsxSpreadAttribute, ctx
7412
7425
  if (ctx.scope.isBound(restName) || !ctx.scope.isBound(propsName)) return false
7413
7426
  let expr: ts.Expression = attr.expression
7414
7427
  while (ts.isParenthesizedExpression(expr)) expr = expr.expression
7415
- if (!ts.isIdentifier(expr) || expr.text !== restName) return false
7428
+ if (!ts.isIdentifier(expr) || !isRestBinding(expr.text, restName, ctx)) return false
7416
7429
  ctx.analyzer.errors.push({
7417
7430
  code: 'BF101',
7418
7431
  severity: 'error',
@@ -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
  /**
@@ -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
  }
@@ -1,42 +0,0 @@
1
- import { type ParsedExpr } from '../expression-parser.ts';
2
- import { type ArithmeticCoercion, type NullishAttrContext } from '../nullable-signal-attr.ts';
3
- import { BindingScope } from '../scope/binding-scope.ts';
4
- import type { CompilerError, MemoInfo } from '../types.ts';
5
- /**
6
- * Where a template adapter records the refusal of an arithmetic operand
7
- * whose nil the declared type cannot classify (#3700).
8
- */
9
- export interface AmbiguousNilArithmeticSink {
10
- readonly errors: CompilerError[];
11
- readonly componentName: string;
12
- }
13
- /**
14
- * The shared arithmetic-operand decision for a template adapter's emission
15
- * site: the coercion the adapter spells (`arithmeticOperandCoercion`), after
16
- * refusing (BF101) an operand that reads a number prop declared both
17
- * optional and nullable (`n?: number | null`, `arithmeticOperandNilIsAmbiguous`).
18
- * JS reads that prop as `undefined` when omitted (`NaN` in arithmetic) and
19
- * as `0` when `null`; the engine holds both as one nil, so any spelling
20
- * renders one of them wrong. Under a comparison the same holds for a string
21
- * or boolean prop declared `?: string | null` / `?: boolean | null` (#3824
22
- * step 3). Asked at the emission site so the operand is classified in the
23
- * scope it is read in (`isShadowed`). One error per operand text per compile.
24
- */
25
- export declare function arithmeticCoercionOrRefuse(op: string, operand: ParsedExpr, other: ParsedExpr | undefined, ctx: NullishAttrContext, isShadowed: (name: string) => boolean, sink: AmbiguousNilArithmeticSink): ArithmeticCoercion;
26
- /**
27
- * Refuse (BF101) each arithmetic operand in a whole expression that a
28
- * template adapter lowers without asking {@link arithmeticCoercionOrRefuse}
29
- * per operator: a `.filter()` predicate, an expression the runtime evaluator
30
- * runs, a condition lowered by its own renderer (`ambiguousNilArithmeticOperands`).
31
- * `scope` is the scope the expression is read in.
32
- */
33
- export declare function refuseAmbiguousNilArithmetic(expr: ParsedExpr, ctx: NullishAttrContext, scope: BindingScope, sink: AmbiguousNilArithmeticSink): void;
34
- /**
35
- * Refuse the ambiguous arithmetic in the component's memo bodies. A template
36
- * adapter seeds every memo at SSR, and some seed a memo through a path that
37
- * never reaches its operator emitter (a static seed after a speculative
38
- * lowering, a constructor-time evaluation), so the bodies are checked as a
39
- * whole, in the component scope they are declared in.
40
- */
41
- export declare function refuseAmbiguousNilMemoArithmetic(memos: readonly MemoInfo[], ctx: NullishAttrContext, sink: AmbiguousNilArithmeticSink): void;
42
- //# sourceMappingURL=ambiguous-nil-arithmetic.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"ambiguous-nil-arithmetic.d.ts","sourceRoot":"","sources":["../../src/adapters/ambiguous-nil-arithmetic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACvE,OAAO,EAKL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE1D;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,CAAA;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,GAAG,EAAE,kBAAkB,EACvB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,EACrC,IAAI,EAAE,0BAA0B,GAC/B,kBAAkB,CAIpB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,0BAA0B,GAC/B,IAAI,CAIN;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,GAAG,EAAE,kBAAkB,EACvB,IAAI,EAAE,0BAA0B,GAC/B,IAAI,CAIN"}