@barefootjs/jsx 0.37.0 → 0.38.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 (128) hide show
  1. package/dist/adapters/env-signal.d.ts +0 -8
  2. package/dist/adapters/env-signal.d.ts.map +1 -1
  3. package/dist/adapters/interface.d.ts +12 -0
  4. package/dist/adapters/interface.d.ts.map +1 -1
  5. package/dist/analyzer.d.ts +40 -0
  6. package/dist/analyzer.d.ts.map +1 -1
  7. package/dist/builtin-lowering-plugins.d.ts.map +1 -1
  8. package/dist/compiler.d.ts.map +1 -1
  9. package/dist/component-root-scope-comment.d.ts +36 -0
  10. package/dist/component-root-scope-comment.d.ts.map +1 -0
  11. package/dist/errors.d.ts +3 -0
  12. package/dist/errors.d.ts.map +1 -1
  13. package/dist/event-handler-name.d.ts +13 -0
  14. package/dist/event-handler-name.d.ts.map +1 -0
  15. package/dist/expression-parser.d.ts +9 -0
  16. package/dist/expression-parser.d.ts.map +1 -1
  17. package/dist/format-date-refusal.d.ts +37 -0
  18. package/dist/format-date-refusal.d.ts.map +1 -0
  19. package/dist/index.d.ts +5 -3
  20. package/dist/index.d.ts.map +1 -1
  21. package/dist/index.js +2973 -2310
  22. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  23. package/dist/ir-to-client-js/control-flow/plan/build-branch-loop.d.ts.map +1 -1
  24. package/dist/ir-to-client-js/control-flow/plan/build-component-loop.d.ts.map +1 -1
  25. package/dist/ir-to-client-js/control-flow/plan/build-composite-loop.d.ts.map +1 -1
  26. package/dist/ir-to-client-js/control-flow/plan/build-loop-child-arm.d.ts +13 -2
  27. package/dist/ir-to-client-js/control-flow/plan/build-loop-child-arm.d.ts.map +1 -1
  28. package/dist/ir-to-client-js/control-flow/plan/build-loop.d.ts.map +1 -1
  29. package/dist/ir-to-client-js/control-flow/plan/build-reactive-effects.d.ts.map +1 -1
  30. package/dist/ir-to-client-js/control-flow/plan/lazy-conditional.d.ts.map +1 -1
  31. package/dist/ir-to-client-js/control-flow/plan/lazy-row-eligibility.d.ts +1 -1
  32. package/dist/ir-to-client-js/control-flow/plan/loop-child-arm.d.ts +9 -0
  33. package/dist/ir-to-client-js/control-flow/plan/loop-child-arm.d.ts.map +1 -1
  34. package/dist/ir-to-client-js/control-flow/plan/loop.d.ts +57 -12
  35. package/dist/ir-to-client-js/control-flow/plan/loop.d.ts.map +1 -1
  36. package/dist/ir-to-client-js/control-flow/shared.d.ts +44 -3
  37. package/dist/ir-to-client-js/control-flow/shared.d.ts.map +1 -1
  38. package/dist/ir-to-client-js/control-flow/stringify/component-loop.d.ts +7 -5
  39. package/dist/ir-to-client-js/control-flow/stringify/component-loop.d.ts.map +1 -1
  40. package/dist/ir-to-client-js/control-flow/stringify/loop-child-arm.d.ts +9 -1
  41. package/dist/ir-to-client-js/control-flow/stringify/loop-child-arm.d.ts.map +1 -1
  42. package/dist/ir-to-client-js/emit-reactive.d.ts +43 -2
  43. package/dist/ir-to-client-js/emit-reactive.d.ts.map +1 -1
  44. package/dist/ir-to-client-js/html-template.d.ts.map +1 -1
  45. package/dist/ir-to-client-js/reactivity.d.ts +16 -1
  46. package/dist/ir-to-client-js/reactivity.d.ts.map +1 -1
  47. package/dist/ir-to-client-js/source-map.d.ts.map +1 -1
  48. package/dist/ir-to-client-js/types.d.ts +2 -0
  49. package/dist/ir-to-client-js/types.d.ts.map +1 -1
  50. package/dist/ir-to-client-js/utils.d.ts +26 -0
  51. package/dist/ir-to-client-js/utils.d.ts.map +1 -1
  52. package/dist/jsx-to-ir.d.ts.map +1 -1
  53. package/dist/opaque-local-accessor.d.ts +27 -0
  54. package/dist/opaque-local-accessor.d.ts.map +1 -0
  55. package/dist/to-locale-date-lowering.d.ts +7 -4
  56. package/dist/to-locale-date-lowering.d.ts.map +1 -1
  57. package/dist/types.d.ts +53 -17
  58. package/dist/types.d.ts.map +1 -1
  59. package/package.json +2 -2
  60. package/src/__tests__/__snapshots__/doc-examples.test.ts.snap +724 -4564
  61. package/src/__tests__/binding-scope-ratchet.test.ts +21 -10
  62. package/src/__tests__/branch-local-in-raw-capture.test.ts +1 -1
  63. package/src/__tests__/branch-local-same-name-collision.test.ts +9 -9
  64. package/src/__tests__/client-js-generation.test.ts +175 -0
  65. package/src/__tests__/component-root-scope-comment.test.ts +106 -0
  66. package/src/__tests__/doc-examples.test.ts +12 -22
  67. package/src/__tests__/event-handler-name.test.ts +74 -0
  68. package/src/__tests__/flatmap-segments.test.ts +11 -9
  69. package/src/__tests__/format-date-refusal.test.ts +134 -0
  70. package/src/__tests__/fragment-wrapped-conditional-return-branch.test.ts +132 -0
  71. package/src/__tests__/hydrate-template.test.ts +9 -1
  72. package/src/__tests__/issue-2798-static-nested-loop-bindings.test.ts +2 -2
  73. package/src/__tests__/issue-3009-loop-branch-ref.test.ts +80 -0
  74. package/src/__tests__/issue-3044-nested-prop-object-array-not-static.test.ts +213 -0
  75. package/src/__tests__/issue-3113-init-fn-name-collision.test.ts +133 -0
  76. package/src/__tests__/jsx-return-type-assertion.test.ts +2 -2
  77. package/src/__tests__/lazy-row-eligibility.test.ts +5 -4
  78. package/src/__tests__/loop-row-child-children-reactive-attrs.test.ts +108 -0
  79. package/src/__tests__/loop-row-child-text-children-markers.test.ts +158 -0
  80. package/src/__tests__/opaque-local-accessor.test.ts +90 -0
  81. package/src/__tests__/profiler-e2e.test.ts +13 -8
  82. package/src/__tests__/ref-attr-absent-at-ssr.test.ts +472 -0
  83. package/src/__tests__/ssr-portal-ref-callback.test.ts +217 -0
  84. package/src/adapters/env-signal.ts +2 -21
  85. package/src/adapters/interface.ts +13 -0
  86. package/src/analyzer.ts +40 -28
  87. package/src/builtin-lowering-plugins.ts +0 -2
  88. package/src/compiler.ts +24 -0
  89. package/src/component-root-scope-comment.ts +59 -0
  90. package/src/errors.ts +44 -1
  91. package/src/event-handler-name.ts +14 -0
  92. package/src/expression-parser.ts +41 -17
  93. package/src/format-date-refusal.ts +266 -0
  94. package/src/index.ts +13 -3
  95. package/src/ir-to-client-js/child-components.ts +8 -3
  96. package/src/ir-to-client-js/collect-elements.ts +29 -13
  97. package/src/ir-to-client-js/control-flow/plan/build-branch-loop.ts +2 -4
  98. package/src/ir-to-client-js/control-flow/plan/build-component-loop.ts +67 -5
  99. package/src/ir-to-client-js/control-flow/plan/build-composite-loop.ts +3 -6
  100. package/src/ir-to-client-js/control-flow/plan/build-loop-child-arm.ts +31 -1
  101. package/src/ir-to-client-js/control-flow/plan/build-loop.ts +23 -11
  102. package/src/ir-to-client-js/control-flow/plan/build-reactive-effects.ts +5 -0
  103. package/src/ir-to-client-js/control-flow/plan/lazy-conditional.ts +1 -0
  104. package/src/ir-to-client-js/control-flow/plan/lazy-row-eligibility.ts +3 -3
  105. package/src/ir-to-client-js/control-flow/plan/loop-child-arm.ts +11 -0
  106. package/src/ir-to-client-js/control-flow/plan/loop.ts +51 -10
  107. package/src/ir-to-client-js/control-flow/shared.ts +78 -5
  108. package/src/ir-to-client-js/control-flow/stringify/component-loop.ts +25 -12
  109. package/src/ir-to-client-js/control-flow/stringify/loop-child-arm.ts +22 -1
  110. package/src/ir-to-client-js/emit-reactive.ts +140 -10
  111. package/src/ir-to-client-js/emit-registration.ts +2 -2
  112. package/src/ir-to-client-js/generate-init.ts +2 -2
  113. package/src/ir-to-client-js/html-template.ts +41 -19
  114. package/src/ir-to-client-js/index.ts +4 -3
  115. package/src/ir-to-client-js/reactivity.ts +28 -17
  116. package/src/ir-to-client-js/source-map.ts +2 -1
  117. package/src/ir-to-client-js/types.ts +2 -0
  118. package/src/ir-to-client-js/utils.ts +34 -0
  119. package/src/jsx-to-ir.ts +737 -49
  120. package/src/opaque-local-accessor.ts +44 -0
  121. package/src/rich-type-refusal.ts +1 -1
  122. package/src/to-locale-date-lowering.ts +7 -4
  123. package/src/types.ts +51 -15
  124. package/dist/format-date-lowering.d.ts +0 -30
  125. package/dist/format-date-lowering.d.ts.map +0 -1
  126. package/src/__tests__/create-selector.test.ts +0 -124
  127. package/src/__tests__/format-date-lowering.test.ts +0 -125
  128. package/src/format-date-lowering.ts +0 -55
@@ -128,33 +128,14 @@ export function queryHrefLocalNames(metadata: IRMetadata): Set<string> {
128
128
 
129
129
  /**
130
130
  * Entry points that re-export the pure client helpers with an SSR lowering
131
- * (`queryHref` #2042, `formatDate` #2324) — the main entry and the runtime
132
- * re-export. Importing from either must enable the lowering.
131
+ * (`queryHref` #2042) — the main entry and the runtime re-export. Importing
132
+ * from either must enable the lowering.
133
133
  */
134
134
  const CLIENT_HELPER_SOURCES: ReadonlySet<string> = new Set([
135
135
  '@barefootjs/client',
136
136
  '@barefootjs/client/runtime',
137
137
  ])
138
138
 
139
- /**
140
- * The local binding name(s) that `formatDate` is imported under in this
141
- * component (#2324) — the pure-function date formatter an adapter lowers to
142
- * its `format_date` helper (spec/template-helpers.md). Same resolution rules
143
- * as {@link queryHrefLocalNames}: matched by exported name, gated on the LOCAL
144
- * alias, accepted from both the main entry and the runtime re-export.
145
- */
146
- export function formatDateLocalNames(metadata: IRMetadata): Set<string> {
147
- const names = new Set<string>()
148
- for (const imp of metadata.imports) {
149
- if (!CLIENT_HELPER_SOURCES.has(imp.source) || imp.isTypeOnly) continue
150
- for (const s of imp.specifiers) {
151
- if (s.isTypeOnly || s.isNamespace || s.isDefault) continue
152
- if (s.name === 'formatDate') names.add(s.alias ?? s.name)
153
- }
154
- }
155
- return names
156
- }
157
-
158
139
  /**
159
140
  * Recognise a `<binding>().<method>(<args>)` env-signal method call from a
160
141
  * `call` node's callee + args, where `<binding>` is one of the local names
@@ -313,6 +313,19 @@ export interface TemplateAdapter {
313
313
  // Type generation (for typed languages)
314
314
  generateTypes?(ir: ComponentIR): string | null
315
315
 
316
+ /**
317
+ * Register a component's shape (declared props, rest bag, derived-field
318
+ * dependencies) with the adapter BEFORE any component that may nest it
319
+ * generates, so a parent finds a child's shape whatever the declaration
320
+ * order. Cross-file children reach it from the CLI / compat /
321
+ * test-render pre-passes (one call per sibling file);
322
+ * `compileMultipleComponents` calls it for every same-file component
323
+ * ahead of its generate loop, so a child declared AFTER its parent —
324
+ * legal through function-declaration hoisting — is registered too.
325
+ * Adapters with no cross-component shape registry leave it undefined.
326
+ */
327
+ registerChildComponentShape?(ir: ComponentIR): void
328
+
316
329
  /**
317
330
  * Generate the SSR declaration block for the user's reactive bindings
318
331
  * (signals, memos, locally-declared functions/constants) at the top
package/src/analyzer.ts CHANGED
@@ -55,11 +55,6 @@ export function needsTypeBasedDetection(source: string): boolean {
55
55
  if (REACTIVE_BRAND_PACKAGES.some(pkg => source.includes(pkg))) return true
56
56
  // BF023/BF024 nullable-key check needs getTypeAtLocation() on the key expression.
57
57
  if (/\.map\s*\(/.test(source)) return true
58
- // createSelector's returned accessor is Reactive<>-branded like a library
59
- // accessor above — a selector call outside any `.map()` (no loop in the
60
- // file at all) would otherwise skip the TypeChecker entirely and miss the
61
- // brand.
62
- if (source.includes('createSelector')) return true
63
58
  return false
64
59
  }
65
60
 
@@ -1982,21 +1977,31 @@ const MUTATING_METHOD_NAMES: ReadonlySet<string> = new Set([
1982
1977
  * binding) silently drops everything the mutation was supposed to do. See
1983
1978
  * `ConstantInfo.mutatedAfterDeclaration` for where this is consumed.
1984
1979
  */
1980
+ /**
1981
+ * The identifier a (possibly chained) member/element-access/parenthesized/
1982
+ * non-null-asserted expression is ultimately rooted at (`a.b.c`, `a?.b[0]`,
1983
+ * `(a!).b` all resolve to `a`), or `null` when the root isn't a bare
1984
+ * identifier (e.g. a call result). Shared by `extractMutatedIdentifiersFromNode`
1985
+ * below and `isArrayExprDirectPropRef` (`jsx-to-ir.ts`, #3044 pullfrog
1986
+ * review) — the same "walk a member chain to its root" question, structural
1987
+ * and side-effect-free, so one implementation serves both instead of a
1988
+ * second inline while-loop reinventing it with narrower node coverage.
1989
+ */
1990
+ export function rootIdentifierOf(expr: ts.Expression): string | null {
1991
+ let current: ts.Expression = expr
1992
+ while (true) {
1993
+ if (ts.isIdentifier(current)) return current.text
1994
+ if (ts.isParenthesizedExpression(current)) { current = current.expression; continue }
1995
+ if (ts.isNonNullExpression(current)) { current = current.expression; continue }
1996
+ if (ts.isPropertyAccessExpression(current)) { current = current.expression; continue }
1997
+ if (ts.isElementAccessExpression(current)) { current = current.expression; continue }
1998
+ return null
1999
+ }
2000
+ }
2001
+
1985
2002
  function extractMutatedIdentifiersFromNode(node: ts.Node): Set<string> {
1986
2003
  const ids = new Set<string>()
1987
2004
 
1988
- function rootIdentifierOf(expr: ts.Expression): string | null {
1989
- let current: ts.Expression = expr
1990
- while (true) {
1991
- if (ts.isIdentifier(current)) return current.text
1992
- if (ts.isParenthesizedExpression(current)) { current = current.expression; continue }
1993
- if (ts.isNonNullExpression(current)) { current = current.expression; continue }
1994
- if (ts.isPropertyAccessExpression(current)) { current = current.expression; continue }
1995
- if (ts.isElementAccessExpression(current)) { current = current.expression; continue }
1996
- return null
1997
- }
1998
- }
1999
-
2000
2005
  function visit(n: ts.Node): void {
2001
2006
  // Same init/sub-init boundary as `extractAssignedIdentifiersFromNode`:
2002
2007
  // a mutation inside a nested function literal doesn't run at init time.
@@ -2124,14 +2129,10 @@ function collectLocalDeclarations(root: ts.Node): Set<string> {
2124
2129
  // and are emitted by the compiler for 'use client' components.
2125
2130
  const CLIENT_EXPORTS = new Set([
2126
2131
  'createSignal', 'createEffect', 'createDisposableEffect', 'createMemo',
2127
- 'createSelector',
2128
2132
  'createRoot', 'onCleanup', 'onMount', 'untrack', 'batch', 'splitProps',
2129
2133
  'forwardProps', 'unwrap', '__slot',
2130
2134
  'createContext', 'useContext', 'provideContext',
2131
- 'createPortal', 'isSSRPortal', 'findSiblingSlot', 'cleanupPortalPlaceholder',
2132
- // Floating-element position tracking (#2848) — same runtime-only shape
2133
- // as the portal entries above.
2134
- 'trackPosition',
2135
+ 'createPortal', 'isSSRPortal', 'findSiblingSlot',
2135
2136
  // Request-scoped environment signal factory (router v0.5) — `createSignal`-
2136
2137
  // shaped, recognised structurally (#2057) so its getter is just a signal
2137
2138
  // getter; the compiler lowers the reader value per adapter via the signal's
@@ -2141,9 +2142,14 @@ const CLIENT_EXPORTS = new Set([
2141
2142
  // `searchParams`. Runs natively on the client; SSR adapters lower a
2142
2143
  // `queryHref(base, { … })` call to their query helper (go-template: `bf_query`).
2143
2144
  'queryHref',
2144
- // Pure date formatter (#2324). Runs natively on the client; SSR adapters
2145
- // lower a `formatDate(date, pattern, tz)` call to their `format_date`
2146
- // helper (spec/template-helpers.md).
2145
+ // Pure date formatter (#2324), demoted to compiler ABI in #3089: it is
2146
+ // still a REAL (now `@internal`) export — the lowering TARGET the
2147
+ // `.toLocaleDateString()` sugar rewrites to, and the emitted client JS's
2148
+ // own import — so it stays in this set to keep `WRONG_PACKAGE_IMPORT`'s
2149
+ // "is this actually exported" check truthful (same reasoning as
2150
+ // `forwardProps`/`unwrap` above, also `@internal` and also still listed).
2151
+ // An AUTHORED call is refused separately and more specifically by
2152
+ // `format-date-refusal.ts`'s BF056, which fires regardless of this entry.
2147
2153
  'formatDate',
2148
2154
  // Compile-away JSX built-ins (#1915) — importing them is what scopes the
2149
2155
  // compiler's `<Async>` / `<Region>` recognition; the import is elided on emit.
@@ -4228,7 +4234,15 @@ function scanImportedClientSignals(ctx: AnalyzerContext): void {
4228
4234
  }
4229
4235
  }
4230
4236
 
4231
- function resolveRelativeImportToFile(source: string, fromFile: string): string | null {
4237
+ /**
4238
+ * Resolve a relative import specifier (`./Zebra`, `../shared/types`) against
4239
+ * the importing file's own absolute path to an on-disk source file, trying
4240
+ * each of BarefootJS's known extensions and `index.*` forms. Exported (#2992)
4241
+ * so an adapter can resolve — and read — a sibling component file on demand,
4242
+ * instead of depending on that file having already been compiled and
4243
+ * registered a cross-file lookup earlier in the same build.
4244
+ */
4245
+ export function resolveRelativeImportToFile(source: string, fromFile: string): string | null {
4232
4246
  const baseDir = path.dirname(fromFile)
4233
4247
  const candidate = path.resolve(baseDir, source)
4234
4248
  // Source already carries an extension (`./x.tsx`) — try the candidate
@@ -4386,8 +4400,6 @@ export const BROWSER_ONLY_CLIENT_APIS = new Set([
4386
4400
  'createPortal',
4387
4401
  'isSSRPortal',
4388
4402
  'findSiblingSlot',
4389
- 'cleanupPortalPlaceholder',
4390
- 'trackPosition',
4391
4403
  ])
4392
4404
 
4393
4405
  function importsBrowserOnlyClientApi(ctx: AnalyzerContext): boolean {
@@ -17,7 +17,6 @@ import { registerLoweringPlugin } from './lowering-registry.ts'
17
17
  import { queryHrefLocalNames } from './adapters/env-signal.ts'
18
18
  import { matchQueryHrefCall } from './query-href-lowering.ts'
19
19
  import { datePlugin } from './date-lowering.ts'
20
- import { formatDatePlugin } from './format-date-lowering.ts'
21
20
  import { toLocaleDatePlugin } from './to-locale-date-lowering.ts'
22
21
 
23
22
  /**
@@ -47,7 +46,6 @@ export const queryHrefPlugin: LoweringPlugin = {
47
46
  export const BUILTIN_LOWERING_PLUGINS: readonly LoweringPlugin[] = [
48
47
  queryHrefPlugin,
49
48
  datePlugin,
50
- formatDatePlugin,
51
49
  toLocaleDatePlugin,
52
50
  ]
53
51
 
package/src/compiler.ts CHANGED
@@ -18,6 +18,7 @@ import { jsxToIR } from './jsx-to-ir.ts'
18
18
  import { stripClientBuiltinImports } from './builtins.ts'
19
19
  import { generateClientJs, generateClientJsWithSourceMap, analyzeClientNeeds } from './ir-to-client-js/index.ts'
20
20
  import { decideClientOnlyElision } from './ir-to-client-js/client-only-elision.ts'
21
+ import { decideComponentRootScopeComment } from './component-root-scope-comment.ts'
21
22
  import { emitModuleLevelDeclarations } from './ir-to-client-js/emit-module-level.ts'
22
23
  import { RUNTIME_MODULE, detectUsedImports as detectUsedImportsFromCode, makeValueUsageTest, renderUsedImportLines, mergeCompiledClientJsImports } from './ir-to-client-js/imports.ts'
23
24
  import { setActiveComponentScope, computeFileScope } from './ir-to-client-js/component-scope.ts'
@@ -27,6 +28,7 @@ import { preprocessInlineJsxCallbacks } from './preprocess-inline-jsx-callbacks.
27
28
  import { extractSsrDefaults } from './ssr-defaults.ts'
28
29
  import { computeSsrSeedPlan } from './ssr-seed-plan.ts'
29
30
  import { checkRichTypeMethodCalls, checkRichTypePropSerialization } from './rich-type-refusal.ts'
31
+ import { checkAuthoredFormatDateCalls } from './format-date-refusal.ts'
30
32
  import { ErrorCodes, createError } from './errors.ts'
31
33
  import { collectComponentNamesFromIR } from './ir-to-client-js/child-components.ts'
32
34
 
@@ -209,6 +211,12 @@ function compileMultipleComponents(
209
211
  componentIR.metadata.clientAnalysis = analyzeClientNeeds(componentIR)
210
212
  checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors)
211
213
  checkRichTypePropSerialization(componentIR.root, componentIR.metadata, errors, ctx.propsDestructuring?.loc)
214
+ checkAuthoredFormatDateCalls(componentIR.root, componentIR.metadata, errors)
215
+
216
+ // #3141: decide once whether a component-call render root needs the
217
+ // comment-based scope marker pair, same "right after clientAnalysis"
218
+ // timing as Step B below.
219
+ decideComponentRootScopeComment(componentIR)
212
220
 
213
221
  // Slot unification Step B — see the single-component path's identical
214
222
  // call for why this must run before adapter.generate/generateClientJs.
@@ -400,6 +408,16 @@ function compileMultipleComponents(
400
408
  }
401
409
  try {
402
410
 
411
+ // Same-file siblings: hand every component's shape to the adapter before
412
+ // any of them generates, so a parent finds a same-file child's shape
413
+ // whatever the declaration order — `entries` follows source order, and a
414
+ // child declared AFTER its parent is legal (function-declaration
415
+ // hoisting). Cross-file children reach the same hook from the CLI /
416
+ // compat / test-render pre-passes; this is the same-file door.
417
+ if (adapter.registerChildComponentShape) {
418
+ for (const { componentIR } of entries) adapter.registerChildComponentShape(componentIR)
419
+ }
420
+
403
421
  for (const { componentIR } of entries) {
404
422
  // Non-default exports share the parent's .client.js, so they
405
423
  // route to the default export's script name. The pipeline's
@@ -769,6 +787,12 @@ export function compileJSX(
769
787
  componentIR.metadata.clientAnalysis = analyzeClientNeeds(componentIR)
770
788
  checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors)
771
789
  checkRichTypePropSerialization(componentIR.root, componentIR.metadata, errors, ctx.propsDestructuring?.loc)
790
+ checkAuthoredFormatDateCalls(componentIR.root, componentIR.metadata, errors)
791
+
792
+ // #3141: decide once whether a component-call render root needs the
793
+ // comment-based scope marker pair, same "right after clientAnalysis"
794
+ // timing as Step B below.
795
+ decideComponentRootScopeComment(componentIR)
772
796
 
773
797
  // Slot unification Step B (`spec/slot-unification.md` §5 Step B): decide
774
798
  // marker elision ONCE, mutating `componentIR.root` in place, before either
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Component-root scope comment (#3141): decide, EXACTLY ONCE and right after
3
+ * `metadata.clientAnalysis` becomes available, whether a client-interactive
4
+ * component's render ROOT — when that root is itself a single child-
5
+ * component call with no wrapping element of its own — needs a comment-based
6
+ * scope marker pair around its rendered output.
7
+ *
8
+ * Before this, the decision was answered independently by Hono
9
+ * (`isRootComponent` + `wrapWithScopeComment` in `hono-adapter.ts`) and NOT
10
+ * AT ALL by the eight DSL adapters, which only ever wrap a `needsScopeComment`
11
+ * FRAGMENT root (the analogous multi-element-root case) — go-template alone
12
+ * had a partial, adapter-local re-derivation that emitted the opening marker
13
+ * but not the closing one. That's the "one decision, two implementations"
14
+ * defect CLAUDE.md calls out: this function is the single shared answer
15
+ * every adapter's `IRNodeEmitter.emitComponent` now reads off
16
+ * `IRComponent.needsScopeComment` instead of re-deriving.
17
+ *
18
+ * Mirrors `IRFragment.needsScopeComment`, computed inside `jsx-to-ir.ts`'s
19
+ * `transformFragment` at parse time — but THIS flag can't live there: "is
20
+ * this component client-interactive" isn't knowable until
21
+ * `analyzeClientNeeds` has run over the whole IR, which happens in
22
+ * `compiler.ts` after `jsxToIR` returns. So, like Slot Unification Step B's
23
+ * `decideClientOnlyElision`, this is a post-hoc mutation of the already-built
24
+ * IR, run once, before any adapter or `generateClientJs` sees it.
25
+ */
26
+
27
+ import type { ComponentIR, IRComponent } from './types.ts'
28
+
29
+ /**
30
+ * True when `ir`'s render root needs the comment-based scope marker pair:
31
+ * the root is a single component call (no wrapping element) AND the
32
+ * component is client-interactive (owns a `'use client'` directive, or the
33
+ * client-JS pre-pass determined it needs an init call regardless).
34
+ *
35
+ * Matches the Hono reference's existing `hasClientInteractivity` formula
36
+ * exactly (`isClientComponent || needsInit`) — this function REPLACES that
37
+ * adapter-local computation for the one decision it fed (the scope-comment
38
+ * wrap), not the adapter's other, still-adapter-owned uses of the same two
39
+ * inputs (namespaced prop passthrough to the child, `bf-p` presence).
40
+ */
41
+ function needsComponentRootScopeComment(ir: ComponentIR): boolean {
42
+ if (ir.root.type !== 'component') return false
43
+ const hasClientInteractivity =
44
+ ir.metadata.isClientComponent || (ir.metadata.clientAnalysis?.needsInit ?? false)
45
+ return hasClientInteractivity
46
+ }
47
+
48
+ /**
49
+ * Mutate `ir.root` in place, marking it `needsScopeComment: true` when
50
+ * `needsComponentRootScopeComment` says so. A no-op otherwise (including
51
+ * when the root isn't a `component` node at all) — mirrors
52
+ * `decideClientOnlyElision`'s in-place-mutation convention so both
53
+ * `compileMultipleComponents` and the single-component path can call it
54
+ * identically right after `metadata.clientAnalysis` is set.
55
+ */
56
+ export function decideComponentRootScopeComment(ir: ComponentIR): void {
57
+ if (!needsComponentRootScopeComment(ir)) return
58
+ ;(ir.root as IRComponent).needsScopeComment = true
59
+ }
package/src/errors.ts CHANGED
@@ -35,7 +35,7 @@ export const ErrorCodes = {
35
35
  // JSX errors (BF021-BF029). BF022 was retired (see
36
36
  // `invalid-jsx-attribute.audit.test.ts`) and BF026 is reserved by
37
37
  // `spec/callback-fidelity.md` for a future `.map()`-callback-shape
38
- // diagnostic — BF027 is the next free slot.
38
+ // diagnostic — BF029 is the next free slot.
39
39
  UNSUPPORTED_JSX_PATTERN: 'BF021',
40
40
  MISSING_KEY_IN_LIST: 'BF023',
41
41
  MISSING_KEY_IN_NESTED_LIST: 'BF024',
@@ -50,6 +50,20 @@ export const ErrorCodes = {
50
50
  // no IR and no diagnostic (#2720). Loud stopgap until the analyzer learns
51
51
  // to resolve the identifier at return position too.
52
52
  RETURN_VALUE_NOT_JSX: 'BF027',
53
+ // #3063: a `'use client'` (or otherwise client-interactive) component
54
+ // whose multi-return `if`/`else` chain has at least one branch wrapped in
55
+ // a bare JSX fragment (`return <>…</>`, no wrapping element). The
56
+ // `ComponentDef`'s `comment: true` / `fragmentRoot: true` client-JS flags
57
+ // (`emit-registration.ts`) are decided ONCE per component from
58
+ // `ir.root.type`, which is always `'if-statement'` here regardless of any
59
+ // individual branch's shape — so the client hydration claim
60
+ // (`materializeComponent`, `packages/client/src/runtime/component.ts`)
61
+ // never learns to look for that branch's comment-scope boundary. SSR and
62
+ // a fresh CSR mount both render the branch correctly; only claiming
63
+ // existing SSR markup during hydration misses it (no `bf-s`, so the
64
+ // branch's own events never bind). See
65
+ // `packages/adapter-tests/limitations/fragment-wrapped-conditional-return-branch-scope.ts`.
66
+ FRAGMENT_WRAPPED_CONDITIONAL_RETURN_BRANCH: 'BF029',
53
67
 
54
68
  // Component errors (BF043-BF049). BF043 is retired (it warned that props
55
69
  // destructuring broke reactivity, which it no longer does) and is the next
@@ -105,6 +119,14 @@ export const ErrorCodes = {
105
119
  // dangling reference (#2432).
106
120
  INLINED_IMPORT_MISSING_EXPORT: 'BF055',
107
121
 
122
+ // `@barefootjs/client`'s `formatDate` called directly by name in a
123
+ // template-lowered position (#3089). `formatDate` is compiler ABI — the
124
+ // lowering TARGET of the `.toLocaleDateString()` sugar, emitted by the
125
+ // compiler itself — never an authored API, so this is a POLICY refusal
126
+ // (not a per-adapter capability gap) and fires identically on every
127
+ // adapter including Hono. See `format-date-refusal.ts`.
128
+ FORMAT_DATE_AUTHORED_CALL: 'BF056',
129
+
108
130
  // Init statement errors (BF052)
109
131
  UNDECLARED_INIT_STATEMENT_REFERENCE: 'BF052',
110
132
 
@@ -130,6 +152,19 @@ export const ErrorCodes = {
130
152
  STAGE_REACTIVE_IN_TEMPLATE: 'BF060',
131
153
  STAGE_INIT_LOCAL_IN_TEMPLATE: 'BF061',
132
154
  STAGE_AWAIT_IN_TEMPLATE: 'BF062',
155
+ // An element's `ref` callback unconditionally writes an attribute
156
+ // (`el.setAttribute('<name>', …)` / `el.dataset.<x> = …`) at mount —
157
+ // directly, or at the top level of a directly nested `createEffect` /
158
+ // `onMount` — that the element's own JSX never renders. A `ref` callback
159
+ // never runs at SSR, so the server HTML always lacks the attribute and
160
+ // the first client pass adds it: pre- and post-hydration DOM differ (a
161
+ // visible snap). Narrowed to that decidable, always-divergent shape: an
162
+ // attribute the JSX DOES render (e.g. a `data-state="closed"` literal an
163
+ // effect later overwrites) is out of scope, since the literal is often
164
+ // exactly the value the effect computes on its first run. Escapable with
165
+ // `/* @client */` before the ref expression. See
166
+ // `packages/adapter-tests/limitations/ref-effect-attr-state-ssr.ts`.
167
+ REF_ATTR_ABSENT_AT_SSR: 'BF063',
133
168
 
134
169
  // Inline JSX-callback synthesis errors (BF080-BF089) — raised by the
135
170
  // preprocess-inline-jsx-callbacks pass (#1211) when an inline JSX-
@@ -182,6 +217,9 @@ const errorMessages: Record<ErrorCode, string> = {
182
217
  [ErrorCodes.RETURN_VALUE_NOT_JSX]:
183
218
  "Component's return value is not recognized as JSX — return the JSX expression directly instead of binding it to a local variable first.",
184
219
 
220
+ [ErrorCodes.FRAGMENT_WRAPPED_CONDITIONAL_RETURN_BRANCH]:
221
+ 'A fragment-wrapped branch of a multi-return client component is never hydrated: the client only decides once per component whether its root scope is comment-based, so this branch renders correctly at SSR and on a fresh client mount, but its events never bind after hydrating existing server HTML. Wrap this branch\'s JSX in a real element instead of a bare fragment (`<>…</>` → `<div>…</div>`), or add /* @client */ immediately before the fragment to compile it anyway and accept the known hydration gap.',
222
+
185
223
  [ErrorCodes.SIGNAL_GETTER_NOT_CALLED]:
186
224
  'Signal/memo getter passed without calling it. Use getter() to read the value.',
187
225
  [ErrorCodes.JSX_IN_LOCAL_FUNCTION]:
@@ -211,6 +249,9 @@ const errorMessages: Record<ErrorCode, string> = {
211
249
  [ErrorCodes.WRONG_PACKAGE_IMPORT]:
212
250
  'Import from wrong package.',
213
251
 
252
+ [ErrorCodes.FORMAT_DATE_AUTHORED_CALL]:
253
+ 'formatDate cannot be called directly — it is compiler ABI, not an authored API.',
254
+
214
255
  [ErrorCodes.BUILTIN_REQUIRES_IMPORT]:
215
256
  "Built-in <Async> / <Region> must be imported from '@barefootjs/client'. " +
216
257
  'The compiler recognises these tags by their import (not by tag name), ' +
@@ -233,6 +274,8 @@ const errorMessages: Record<ErrorCode, string> = {
233
274
 
234
275
  [ErrorCodes.STAGE_AWAIT_IN_TEMPLATE]:
235
276
  'AwaitExpression in template scope. The generated template and init functions are synchronous — a bare `await` produces a SyntaxError at parse time. Move the await into the component body (before the return) or into an onMount/effect callback, and pass the resolved value to JSX.',
277
+ [ErrorCodes.REF_ATTR_ABSENT_AT_SSR]:
278
+ 'A ref callback writes an attribute on mount that the element\'s JSX never renders. A ref callback never runs at SSR, so the server HTML lacks the attribute and hydration adds it — the DOM visibly changes at the hydrate boundary.',
236
279
 
237
280
  [ErrorCodes.INLINE_JSX_CALLBACK_CAPTURE]:
238
281
  "Inline JSX-returning arrow function captures a non-module identifier. Extract the callback into a top-level 'use client' component (e.g. `function MyNode(n) { return <div/> }` then `renderNode={MyNode}`) or pass captured values via component props.",
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Whether a JSX attribute / component-prop name is an event handler
3
+ * (`onClick`, `onValueChange`, ...) rather than a plain attribute or data
4
+ * prop: `on` followed by an uppercase letter. `on`, `only`, `once`, `online`
5
+ * are ordinary names.
6
+ *
7
+ * The one decision every site shares: native-element attribute extraction
8
+ * (routes into `IREvent`, never rendered HTML), the `isEventHandler` flag on
9
+ * loop child-component props, client-JS prop wiring, and the SSR adapters'
10
+ * "handler has no SSR value" skips.
11
+ */
12
+ export function isEventHandlerName(name: string): boolean {
13
+ return /^on[A-Z]/.test(name)
14
+ }
@@ -600,6 +600,46 @@ export type ProviderObjectMember =
600
600
  | { name: string; kind: 'function' }
601
601
  | { name: string; kind: 'expression'; expr: string }
602
602
 
603
+ /**
604
+ * Whether an expression node is function-shaped: an arrow / function
605
+ * expression, or a `??` / `||` fallback chain with one as an operand
606
+ * (`props.onX ?? (() => {})` is function-typed whichever side wins).
607
+ */
608
+ function isFunctionShapedNode(e: ts.Expression): boolean {
609
+ let v: ts.Expression = e
610
+ while (ts.isParenthesizedExpression(v)) v = v.expression
611
+ if (ts.isArrowFunction(v) || ts.isFunctionExpression(v)) return true
612
+ if (
613
+ ts.isBinaryExpression(v) &&
614
+ (v.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken ||
615
+ v.operatorToken.kind === ts.SyntaxKind.BarBarToken)
616
+ ) {
617
+ return isFunctionShapedNode(v.left) || isFunctionShapedNode(v.right)
618
+ }
619
+ return false
620
+ }
621
+
622
+ /**
623
+ * Whether `source` is a function-shaped expression — behavior, not data, so
624
+ * SSR never has a value for it (the same classification
625
+ * `parseProviderObjectLiteral` gives a provider member's `function` kind).
626
+ * Covers the block-bodied arrows `parseExpression` leaves `unsupported`
627
+ * (`(el) => { el.focus() }`). Parses `source`, so callers reach for it off
628
+ * the hot path only (e.g. before refusing a value they could not lower).
629
+ */
630
+ export function isFunctionShapedExpression(source: string): boolean {
631
+ const sf = ts.createSourceFile(
632
+ '__fn__.tsx',
633
+ `(${source})`,
634
+ ts.ScriptTarget.Latest,
635
+ /* setParentNodes */ true,
636
+ ts.ScriptKind.TSX,
637
+ )
638
+ const stmt = sf.statements[0]
639
+ if (sf.statements.length !== 1 || !stmt || !ts.isExpressionStatement(stmt)) return false
640
+ return isFunctionShapedNode(stmt.expression)
641
+ }
642
+
603
643
  /**
604
644
  * Structurally parse a `<Ctx.Provider value={{ … }}>` object literal into
605
645
  * per-member SSR lowering classifications (see `ProviderObjectMember`).
@@ -625,22 +665,6 @@ export function parseProviderObjectLiteral(source: string): ProviderObjectMember
625
665
  while (init && ts.isParenthesizedExpression(init)) init = init.expression
626
666
  if (!init || !ts.isObjectLiteralExpression(init)) return null
627
667
 
628
- const isFunctionShaped = (e: ts.Expression): boolean => {
629
- let v: ts.Expression = e
630
- while (ts.isParenthesizedExpression(v)) v = v.expression
631
- if (ts.isArrowFunction(v) || ts.isFunctionExpression(v)) return true
632
- // `props.onX ?? (() => {})` — a fallback chain with a function operand
633
- // is function-typed regardless of which side wins at runtime.
634
- if (
635
- ts.isBinaryExpression(v) &&
636
- (v.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken ||
637
- v.operatorToken.kind === ts.SyntaxKind.BarBarToken)
638
- ) {
639
- return isFunctionShaped(v.left) || isFunctionShaped(v.right)
640
- }
641
- return false
642
- }
643
-
644
668
  const members: ProviderObjectMember[] = []
645
669
  for (const prop of init.properties) {
646
670
  if (ts.isShorthandPropertyAssignment(prop)) {
@@ -668,7 +692,7 @@ export function parseProviderObjectLiteral(source: string): ProviderObjectMember
668
692
  members.push({ name, kind: 'getter', body: v.body.getText(sf).trim() })
669
693
  continue
670
694
  }
671
- if (isFunctionShaped(v)) {
695
+ if (isFunctionShapedNode(v)) {
672
696
  members.push({ name, kind: 'function' })
673
697
  continue
674
698
  }