@barefootjs/jsx 0.37.1 → 0.39.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 (168) hide show
  1. package/dist/action-accessor.d.ts +159 -0
  2. package/dist/action-accessor.d.ts.map +1 -0
  3. package/dist/adapters/env-signal.d.ts +0 -8
  4. package/dist/adapters/env-signal.d.ts.map +1 -1
  5. package/dist/adapters/interface.d.ts +12 -0
  6. package/dist/adapters/interface.d.ts.map +1 -1
  7. package/dist/adapters/jsx-adapter.d.ts.map +1 -1
  8. package/dist/analyzer.d.ts +61 -1
  9. package/dist/analyzer.d.ts.map +1 -1
  10. package/dist/async-action-refusal.d.ts +45 -0
  11. package/dist/async-action-refusal.d.ts.map +1 -0
  12. package/dist/builtin-lowering-plugins.d.ts.map +1 -1
  13. package/dist/compiler.d.ts.map +1 -1
  14. package/dist/component-root-scope-comment.d.ts +36 -0
  15. package/dist/component-root-scope-comment.d.ts.map +1 -0
  16. package/dist/debug.d.ts +61 -5
  17. package/dist/debug.d.ts.map +1 -1
  18. package/dist/errors.d.ts +7 -0
  19. package/dist/errors.d.ts.map +1 -1
  20. package/dist/event-handler-name.d.ts +13 -0
  21. package/dist/event-handler-name.d.ts.map +1 -0
  22. package/dist/expression-parser.d.ts +9 -0
  23. package/dist/expression-parser.d.ts.map +1 -1
  24. package/dist/format-date-refusal.d.ts +33 -0
  25. package/dist/format-date-refusal.d.ts.map +1 -0
  26. package/dist/index.d.ts +6 -4
  27. package/dist/index.d.ts.map +1 -1
  28. package/dist/index.js +3260 -1914
  29. package/dist/ir-to-client-js/build-references.d.ts.map +1 -1
  30. package/dist/ir-to-client-js/collect-elements.d.ts.map +1 -1
  31. package/dist/ir-to-client-js/compute-inlinability.d.ts.map +1 -1
  32. package/dist/ir-to-client-js/compute-scope.d.ts.map +1 -1
  33. package/dist/ir-to-client-js/control-flow/plan/build-branch-loop.d.ts.map +1 -1
  34. package/dist/ir-to-client-js/control-flow/plan/build-component-loop.d.ts.map +1 -1
  35. package/dist/ir-to-client-js/control-flow/plan/build-composite-loop.d.ts.map +1 -1
  36. package/dist/ir-to-client-js/control-flow/plan/build-loop-child-arm.d.ts.map +1 -1
  37. package/dist/ir-to-client-js/control-flow/plan/build-loop.d.ts.map +1 -1
  38. package/dist/ir-to-client-js/control-flow/plan/insert.d.ts +2 -0
  39. package/dist/ir-to-client-js/control-flow/plan/insert.d.ts.map +1 -1
  40. package/dist/ir-to-client-js/control-flow/plan/lazy-row-eligibility.d.ts +1 -1
  41. package/dist/ir-to-client-js/control-flow/plan/loop.d.ts +57 -12
  42. package/dist/ir-to-client-js/control-flow/plan/loop.d.ts.map +1 -1
  43. package/dist/ir-to-client-js/control-flow/shared.d.ts +44 -3
  44. package/dist/ir-to-client-js/control-flow/shared.d.ts.map +1 -1
  45. package/dist/ir-to-client-js/control-flow/stringify/component-loop.d.ts +7 -5
  46. package/dist/ir-to-client-js/control-flow/stringify/component-loop.d.ts.map +1 -1
  47. package/dist/ir-to-client-js/csr-substitute.d.ts.map +1 -1
  48. package/dist/ir-to-client-js/declaration-sort.d.ts +2 -1
  49. package/dist/ir-to-client-js/declaration-sort.d.ts.map +1 -1
  50. package/dist/ir-to-client-js/emit-module-level.d.ts.map +1 -1
  51. package/dist/ir-to-client-js/emit-reactive.d.ts +43 -2
  52. package/dist/ir-to-client-js/emit-reactive.d.ts.map +1 -1
  53. package/dist/ir-to-client-js/emit-registration.d.ts.map +1 -1
  54. package/dist/ir-to-client-js/html-template.d.ts.map +1 -1
  55. package/dist/ir-to-client-js/plan/declaration-emit.d.ts +7 -5
  56. package/dist/ir-to-client-js/plan/declaration-emit.d.ts.map +1 -1
  57. package/dist/ir-to-client-js/prop-handling.d.ts.map +1 -1
  58. package/dist/ir-to-client-js/reactivity.d.ts +9 -1
  59. package/dist/ir-to-client-js/reactivity.d.ts.map +1 -1
  60. package/dist/ir-to-client-js/source-map.d.ts.map +1 -1
  61. package/dist/ir-to-client-js/types.d.ts +4 -0
  62. package/dist/ir-to-client-js/types.d.ts.map +1 -1
  63. package/dist/ir-to-client-js/utils.d.ts +66 -1
  64. package/dist/ir-to-client-js/utils.d.ts.map +1 -1
  65. package/dist/jsx-to-ir.d.ts.map +1 -1
  66. package/dist/opaque-local-accessor.d.ts +27 -0
  67. package/dist/opaque-local-accessor.d.ts.map +1 -0
  68. package/dist/signal-initializer.d.ts +24 -0
  69. package/dist/signal-initializer.d.ts.map +1 -0
  70. package/dist/template-position-walk.d.ts +68 -0
  71. package/dist/template-position-walk.d.ts.map +1 -0
  72. package/dist/to-locale-date-lowering.d.ts +7 -4
  73. package/dist/to-locale-date-lowering.d.ts.map +1 -1
  74. package/dist/types.d.ts +104 -17
  75. package/dist/types.d.ts.map +1 -1
  76. package/package.json +2 -2
  77. package/src/__tests__/__snapshots__/doc-examples.test.ts.snap +878 -4528
  78. package/src/__tests__/action-accessor.test.ts +166 -0
  79. package/src/__tests__/binding-scope-ratchet.test.ts +21 -10
  80. package/src/__tests__/branch-local-in-raw-capture.test.ts +1 -1
  81. package/src/__tests__/branch-local-same-name-collision.test.ts +9 -9
  82. package/src/__tests__/client-js-generation.test.ts +175 -0
  83. package/src/__tests__/component-root-scope-comment.test.ts +106 -0
  84. package/src/__tests__/create-mutation.test.ts +220 -0
  85. package/src/__tests__/create-query.test.ts +644 -0
  86. package/src/__tests__/csr-fragment-root-scope-shape.test.ts +156 -0
  87. package/src/__tests__/debug.test.ts +222 -0
  88. package/src/__tests__/doc-examples.test.ts +78 -25
  89. package/src/__tests__/event-handler-name.test.ts +74 -0
  90. package/src/__tests__/flatmap-segments.test.ts +11 -9
  91. package/src/__tests__/format-date-refusal.test.ts +134 -0
  92. package/src/__tests__/fragment-wrapped-conditional-return-branch.test.ts +132 -0
  93. package/src/__tests__/hydrate-template.test.ts +9 -1
  94. package/src/__tests__/issue-2798-static-nested-loop-bindings.test.ts +2 -2
  95. package/src/__tests__/issue-3009-loop-branch-ref.test.ts +2 -2
  96. package/src/__tests__/issue-3044-nested-prop-object-array-not-static.test.ts +213 -0
  97. package/src/__tests__/issue-3113-init-fn-name-collision.test.ts +133 -0
  98. package/src/__tests__/jsx-return-type-assertion.test.ts +2 -2
  99. package/src/__tests__/lazy-row-eligibility.test.ts +5 -4
  100. package/src/__tests__/loop-row-child-children-reactive-attrs.test.ts +108 -0
  101. package/src/__tests__/loop-row-child-text-children-markers.test.ts +158 -0
  102. package/src/__tests__/opaque-local-accessor.test.ts +90 -0
  103. package/src/__tests__/profiler-e2e.test.ts +13 -8
  104. package/src/__tests__/props-destructuring.test.ts +79 -4
  105. package/src/__tests__/reactive-factory-arity.test.ts +311 -0
  106. package/src/__tests__/ref-attr-absent-at-ssr.test.ts +472 -0
  107. package/src/__tests__/ssr-portal-ref-callback.test.ts +219 -0
  108. package/src/action-accessor.ts +289 -0
  109. package/src/adapters/env-signal.ts +2 -21
  110. package/src/adapters/interface.ts +13 -0
  111. package/src/adapters/jsx-adapter.ts +17 -0
  112. package/src/analyzer.ts +589 -60
  113. package/src/async-action-refusal.ts +254 -0
  114. package/src/builtin-lowering-plugins.ts +0 -2
  115. package/src/compiler.ts +27 -0
  116. package/src/component-root-scope-comment.ts +59 -0
  117. package/src/debug.ts +318 -103
  118. package/src/errors.ts +83 -1
  119. package/src/event-handler-name.ts +14 -0
  120. package/src/expression-parser.ts +41 -17
  121. package/src/format-date-refusal.ts +147 -0
  122. package/src/index.ts +14 -3
  123. package/src/ir-to-client-js/build-references.ts +6 -2
  124. package/src/ir-to-client-js/child-components.ts +8 -3
  125. package/src/ir-to-client-js/collect-elements.ts +28 -13
  126. package/src/ir-to-client-js/compute-inlinability.ts +2 -1
  127. package/src/ir-to-client-js/compute-scope.ts +3 -1
  128. package/src/ir-to-client-js/control-flow/plan/build-branch-loop.ts +2 -4
  129. package/src/ir-to-client-js/control-flow/plan/build-component-loop.ts +67 -5
  130. package/src/ir-to-client-js/control-flow/plan/build-composite-loop.ts +3 -6
  131. package/src/ir-to-client-js/control-flow/plan/build-insert.ts +1 -0
  132. package/src/ir-to-client-js/control-flow/plan/build-loop-child-arm.ts +2 -1
  133. package/src/ir-to-client-js/control-flow/plan/build-loop.ts +23 -11
  134. package/src/ir-to-client-js/control-flow/plan/insert.ts +2 -0
  135. package/src/ir-to-client-js/control-flow/plan/lazy-row-eligibility.ts +3 -3
  136. package/src/ir-to-client-js/control-flow/plan/loop.ts +51 -10
  137. package/src/ir-to-client-js/control-flow/shared.ts +78 -5
  138. package/src/ir-to-client-js/control-flow/stringify/component-loop.ts +25 -12
  139. package/src/ir-to-client-js/control-flow/stringify/insert.ts +1 -1
  140. package/src/ir-to-client-js/csr-substitute.ts +11 -3
  141. package/src/ir-to-client-js/declaration-sort.ts +7 -3
  142. package/src/ir-to-client-js/emit-module-level.ts +7 -4
  143. package/src/ir-to-client-js/emit-reactive.ts +140 -10
  144. package/src/ir-to-client-js/emit-registration.ts +6 -11
  145. package/src/ir-to-client-js/generate-init.ts +2 -2
  146. package/src/ir-to-client-js/html-template.ts +41 -19
  147. package/src/ir-to-client-js/index.ts +9 -3
  148. package/src/ir-to-client-js/phases/ref-callbacks.ts +1 -1
  149. package/src/ir-to-client-js/plan/build-declaration-emit.ts +16 -15
  150. package/src/ir-to-client-js/plan/declaration-emit.ts +7 -5
  151. package/src/ir-to-client-js/prop-handling.ts +4 -0
  152. package/src/ir-to-client-js/reactivity.ts +21 -16
  153. package/src/ir-to-client-js/source-map.ts +2 -1
  154. package/src/ir-to-client-js/stringify/declaration-emit.ts +14 -7
  155. package/src/ir-to-client-js/types.ts +4 -0
  156. package/src/ir-to-client-js/utils.ts +89 -7
  157. package/src/jsx-to-ir.ts +772 -50
  158. package/src/opaque-local-accessor.ts +44 -0
  159. package/src/rich-type-refusal.ts +1 -1
  160. package/src/signal-initializer.ts +36 -0
  161. package/src/template-position-walk.ts +203 -0
  162. package/src/to-locale-date-lowering.ts +7 -4
  163. package/src/types.ts +103 -15
  164. package/dist/format-date-lowering.d.ts +0 -30
  165. package/dist/format-date-lowering.d.ts.map +0 -1
  166. package/src/__tests__/create-selector.test.ts +0 -124
  167. package/src/__tests__/format-date-lowering.test.ts +0 -125
  168. package/src/format-date-lowering.ts +0 -55
@@ -0,0 +1,44 @@
1
+ /**
2
+ * #3144: shared detection for "opaque local accessor invoked in a template
3
+ * position" — `const label = makeLabel(); {label()}`, where `makeLabel()`
4
+ * is a call the compiler cannot evaluate at compile time (a helper
5
+ * returning a function, or an accessor returned by a library, e.g.
6
+ * `const posts = createQuery(…); {posts()}`).
7
+ *
8
+ * Every non-JS-runtime adapter's `call()` fallback treats ANY zero-arg
9
+ * identifier call as a signal-getter reference (`count() → $count` /
10
+ * `.Count` / `{{ count }}` / …) unconditionally — correct for a real
11
+ * signal/memo getter, but silently wrong here: `label` is never a signal,
12
+ * never a prop, and never reaches the template as a bound variable at all,
13
+ * so the emitted bare-name reference resolves to nothing. The reference
14
+ * adapter (Hono, real JS) evaluates `label()` correctly and does NOT
15
+ * consult this — it has no such gap to guard against.
16
+ *
17
+ * This function answers ONLY the structural question "is `name` bound to a
18
+ * COMPONENT-BODY local whose own initializer is itself an unresolved call
19
+ * expression" — every DSL adapter's `call()` method calls it, with its own
20
+ * `localConstants`, before falling into the zero-arg-identifier branch, and
21
+ * refuses loudly (reusing each adapter's own BF101 recording, matching the
22
+ * #2994 / #3012 precedent for a bare-name call to a module-scope helper)
23
+ * instead of guessing.
24
+ */
25
+
26
+ import type { ConstantInfo } from './types.ts'
27
+
28
+ export function isOpaqueLocalAccessorName(
29
+ name: string,
30
+ localConstants: readonly ConstantInfo[] | undefined,
31
+ ): boolean {
32
+ const constant = (localConstants ?? []).find((c) => c.name === name)
33
+ if (!constant) return false
34
+ // Module-scope bindings go through the #2994/#3012 module-helper-call
35
+ // refusal path already (a DIFFERENT shape: the bare name IS the helper,
36
+ // not a local re-binding of one) — out of scope here.
37
+ if (constant.isModule) return false
38
+ // `ConstantInfo.parsed` is the analyzer's best-effort structural parse of
39
+ // the initializer (`jsx-to-ir.ts`/analyzer). `kind === 'call'` means the
40
+ // local's value came from invoking something — exactly the opaque-
41
+ // accessor shape, regardless of whether that call itself would separately
42
+ // refuse if written bare in a template position.
43
+ return constant.parsed?.kind === 'call'
44
+ }
@@ -225,7 +225,7 @@ function buildSuggestion(
225
225
  if (method === 'toLocaleDateString' && typeName === 'Date') {
226
226
  return {
227
227
  message:
228
- "Pass a literal locale and an explicit literal timeZone — .toLocaleDateString('ja-JP', { timeZone: 'UTC' }), a fixed '±HH:MM' offset, or a canonical IANA zone ID like 'Asia/Tokyo' (exact case; #2344) — to compile it to the format_date helper; for a runtime locale, resolve the pattern in your i18n layer and use formatDate(date, pattern, tz) from @barefootjs/client. " +
228
+ "Pass a literal locale and an explicit literal timeZone — .toLocaleDateString('ja-JP', { timeZone: 'UTC' }), a fixed '±HH:MM' offset, or a canonical IANA zone ID like 'Asia/Tokyo' (exact case; #2344) — to compile it to the format_date helper; for a runtime locale, defer the whole read to the client with /* @client */, which can call any date-formatting API you like (Intl.DateTimeFormat, your i18n layer, ...) since it runs as real JS in the browser — formatDate itself is compiler ABI and cannot be called by name (BF056). " +
229
229
  `Alternatively pre-compute server-side, or evaluate client-only by ${revivalExpr} — ${revivalReason}.`,
230
230
  escape: [{ kind: 'rewrite' }, { kind: 'prop-precompute' }, { kind: 'client-directive' }],
231
231
  }
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Client-JS initializers for signals that `createSignal` does not produce.
3
+ *
4
+ * Two factory families are collected as signals: env signals
5
+ * (`createSearchParams()`, #2057) and async reactive factories
6
+ * (`createQuery(fn, options)`, #3165). Every backend that re-emits a signal
7
+ * declaration into client JS asks this module for the initializer instead of
8
+ * hard-coding `createSignal`, so a new factory kind is one entry here rather
9
+ * than a special case per emit site.
10
+ */
11
+
12
+ import type { SignalInfo } from './types.ts'
13
+ import { ENV_SIGNAL_CLIENT_FACTORY } from './adapters/env-signal.ts'
14
+
15
+ /**
16
+ * The initializer expression that produces this signal's tuple in client JS
17
+ * when it isn't `createSignal(<initialValue>)`, or `null` for an ordinary
18
+ * signal. An async factory re-emits its own call with the authored arguments;
19
+ * an env signal calls its factory with none.
20
+ */
21
+ export function signalFactoryInitializer(signal: SignalInfo): string | null {
22
+ if (signal.factory) return `${signal.factory.callee}(${signal.factory.argsText})`
23
+ if (signal.envReader) {
24
+ const factory = signal.envFactory ?? ENV_SIGNAL_CLIENT_FACTORY[signal.envReader]
25
+ return factory ? `${factory}()` : null
26
+ }
27
+ return null
28
+ }
29
+
30
+ /**
31
+ * The second binding of the signal's tuple as written in the source: the
32
+ * setter for `createSignal` and env signals, the action for an async factory.
33
+ */
34
+ export function signalSecondBinding(signal: SignalInfo): string | null {
35
+ return signal.setter ?? signal.factory?.action ?? null
36
+ }
@@ -0,0 +1,203 @@
1
+ /**
2
+ * Every template-lowered position in a component's IR, as parsed expressions.
3
+ *
4
+ * Shared by the policy refusals that fire in the IR-build phase ahead of every
5
+ * adapter's `generate()` — `checkAuthoredFormatDateCalls` (BF056) and
6
+ * `checkAsyncActionReads` (BF117) — so "every position a template could
7
+ * render" is decided once. Covered: text expressions, conditional and
8
+ * if-statement conditions, element / component / provider attribute values
9
+ * (expression, spread, and structured template parts), loop arrays, and the
10
+ * children of elements, components, fragments, providers, async boundaries,
11
+ * loops (including child components, nested components, and `flatMap` /
12
+ * preamble JSX segments) and conditional branches.
13
+ *
14
+ * A `/* @client *\/`-marked position (`clientOnly`) is skipped: the whole read
15
+ * is deferred to the client, where real JS evaluates it.
16
+ *
17
+ * Each position also reports its `role` — how the template USES the value
18
+ * there (rendered as text, tested for truthiness, written as an attribute…)
19
+ * — and, for the two roles a pass may rewrite in place, the IR `host` that
20
+ * holds it. The action-accessor seed (`action-accessor.ts`, #3166) reads
21
+ * both: a seed is only sound where it renders like the reference adapter,
22
+ * which depends on the role, and BF117's refusal-lift and the seed itself
23
+ * must see the SAME position set, which is why both ride this one walk.
24
+ * BF056 reads neither.
25
+ */
26
+
27
+ import type {
28
+ AttrValue,
29
+ ExpressionAttr,
30
+ IRConditional,
31
+ IRIfStatement,
32
+ IRNode,
33
+ IRTemplatePart,
34
+ SourceLocation,
35
+ } from './types.ts'
36
+ import type { ParsedExpr } from './expression-parser.ts'
37
+ import { parseExpression } from './expression-parser.ts'
38
+
39
+ /**
40
+ * How the template uses the value at a position:
41
+ *
42
+ * - `text` — an `IRExpression` child, rendered as text.
43
+ * - `condition` — an `IRConditional` / `IRIfStatement` condition, only ever
44
+ * tested for truthiness.
45
+ * - `element-attr` — an intrinsic element's attribute value (an `expression`
46
+ * attr's whole parse), rendered as the attribute.
47
+ * - `prop` — a component prop or a provider's `value`, handed on as a value.
48
+ * - `spread` — a spread bag (`{...x}`), on an element or a component.
49
+ * - `template-part` — a piece of a structured template attribute
50
+ * (`IRTemplatePart` ternary condition / branch, lookup key). These are raw
51
+ * text parsed on demand here; every adapter lowers them from that raw text,
52
+ * so nothing attached to the IR can stand in for them.
53
+ * - `loop-array` — a loop's array expression.
54
+ */
55
+ export type TemplatePositionRole =
56
+ | 'text'
57
+ | 'condition'
58
+ | 'element-attr'
59
+ | 'prop'
60
+ | 'spread'
61
+ | 'template-part'
62
+ | 'loop-array'
63
+
64
+ /**
65
+ * The IR slot a position's `expr` lives in, for a pass that rewrites the
66
+ * position in place (the action-accessor seed). Only the two roles such a
67
+ * pass may rewrite carry one: a `condition` (its `parsedCondition` /
68
+ * `templateCondition`) and an `element-attr` (the `ExpressionAttr`'s
69
+ * `parsed` / `templateExpr`).
70
+ */
71
+ export type TemplatePositionHost =
72
+ | { kind: 'condition'; node: IRConditional | IRIfStatement }
73
+ | { kind: 'element-attr'; value: ExpressionAttr }
74
+
75
+ export interface TemplatePosition {
76
+ expr: ParsedExpr
77
+ loc: SourceLocation
78
+ role: TemplatePositionRole
79
+ /** The attribute or prop name, when the position is an attribute / prop value. */
80
+ attrName?: string
81
+ host?: TemplatePositionHost
82
+ }
83
+
84
+ export function walkTemplatePositions(root: IRNode, visit: (position: TemplatePosition) => void): void {
85
+ walkNode(root, visit)
86
+ }
87
+
88
+ /**
89
+ * `IRTemplatePart.ternary.condition` / `.lookup.key` carry no attached parse
90
+ * (unlike every other position here), so parse on demand. `ternary.whenTrue`
91
+ * / `.whenFalse` are ALSO raw, unparsed text (the per-branch rendered
92
+ * snippet), so they get the same on-demand treatment — this is the
93
+ * `format-date-ternary` shape (#2843): a call in a ternary CONSEQUENT inside a
94
+ * structured template-literal attribute.
95
+ */
96
+ function walkTemplateParts(
97
+ parts: readonly IRTemplatePart[],
98
+ loc: SourceLocation,
99
+ attrName: string | undefined,
100
+ visit: (position: TemplatePosition) => void,
101
+ ): void {
102
+ const visitText = (text: string) => {
103
+ const trimmed = text.trim()
104
+ if (!trimmed) return
105
+ visit({ expr: parseExpression(trimmed), loc, role: 'template-part', attrName })
106
+ }
107
+ for (const part of parts) {
108
+ if (part.type === 'ternary') {
109
+ visitText(part.condition)
110
+ visitText(part.whenTrue)
111
+ visitText(part.whenFalse)
112
+ } else if (part.type === 'lookup') {
113
+ visitText(part.key)
114
+ }
115
+ }
116
+ }
117
+
118
+ function walkAttrValue(
119
+ value: AttrValue,
120
+ clientOnly: boolean | undefined,
121
+ loc: SourceLocation,
122
+ attrName: string,
123
+ onElement: boolean,
124
+ visit: (position: TemplatePosition) => void,
125
+ ): void {
126
+ if (clientOnly) return
127
+ if (value.kind === 'expression') {
128
+ if (value.parsed) {
129
+ visit(
130
+ onElement
131
+ ? { expr: value.parsed, loc, role: 'element-attr', attrName, host: { kind: 'element-attr', value } }
132
+ : { expr: value.parsed, loc, role: 'prop', attrName },
133
+ )
134
+ }
135
+ if (value.parts) walkTemplateParts(value.parts, loc, attrName, visit)
136
+ } else if (value.kind === 'spread') {
137
+ if (value.parsed) visit({ expr: value.parsed, loc, role: 'spread', attrName })
138
+ } else if (value.kind === 'template') {
139
+ walkTemplateParts(value.parts, loc, attrName, visit)
140
+ }
141
+ }
142
+
143
+ function walkNode(node: IRNode, visit: (position: TemplatePosition) => void): void {
144
+ if (node.type === 'expression') {
145
+ if (!node.clientOnly && node.parsed) visit({ expr: node.parsed, loc: node.loc, role: 'text' })
146
+ } else if (node.type === 'conditional') {
147
+ if (!node.clientOnly && node.parsedCondition) {
148
+ visit({ expr: node.parsedCondition, loc: node.loc, role: 'condition', host: { kind: 'condition', node } })
149
+ }
150
+ } else if (node.type === 'if-statement') {
151
+ if (node.parsedCondition) {
152
+ visit({ expr: node.parsedCondition, loc: node.loc, role: 'condition', host: { kind: 'condition', node } })
153
+ }
154
+ }
155
+
156
+ if (node.type === 'element') {
157
+ for (const attr of node.attrs) walkAttrValue(attr.value, attr.clientOnly, attr.loc, attr.name, true, visit)
158
+ } else if (node.type === 'component') {
159
+ for (const prop of node.props) walkAttrValue(prop.value, prop.clientOnly, prop.loc, prop.name, false, visit)
160
+ } else if (node.type === 'provider') {
161
+ walkAttrValue(node.valueProp.value, node.valueProp.clientOnly, node.valueProp.loc, 'value', false, visit)
162
+ }
163
+
164
+ switch (node.type) {
165
+ case 'element':
166
+ case 'component':
167
+ case 'fragment':
168
+ case 'provider':
169
+ for (const child of node.children) walkNode(child, visit)
170
+ break
171
+ case 'async':
172
+ walkNode(node.fallback, visit)
173
+ for (const child of node.children) walkNode(child, visit)
174
+ break
175
+ case 'loop': {
176
+ if (node.clientOnly) break
177
+ if (node.arrayParsed) visit({ expr: node.arrayParsed, loc: node.loc, role: 'loop-array' })
178
+ for (const child of node.children) walkNode(child, visit)
179
+ if (node.childComponent) {
180
+ for (const child of node.childComponent.children) walkNode(child, visit)
181
+ }
182
+ for (const nested of node.nestedComponents ?? []) {
183
+ for (const child of nested.children) walkNode(child, visit)
184
+ }
185
+ for (const seg of node.flatMapCallback?.segments ?? []) {
186
+ if (seg.kind === 'jsx') walkNode(seg.ir, visit)
187
+ }
188
+ for (const seg of node.preamble?.segments ?? []) {
189
+ if (seg.kind === 'jsx') walkNode(seg.ir, visit)
190
+ }
191
+ break
192
+ }
193
+ case 'conditional':
194
+ if (node.clientOnly) break
195
+ walkNode(node.whenTrue, visit)
196
+ walkNode(node.whenFalse, visit)
197
+ break
198
+ case 'if-statement':
199
+ walkNode(node.consequent, visit)
200
+ if (node.alternate) walkNode(node.alternate, visit)
201
+ break
202
+ }
203
+ }
@@ -31,9 +31,11 @@
31
31
  * timezone, the implicit-environment hole #2273 closed;
32
32
  * - an OPEN-typed runtime locale (`locale: string`) — build-time CLDR
33
33
  * resolution is impossible; the app's i18n layer owns locale → pattern
34
- * there, feeding `formatDate` directly. An OPTIONAL union prop also
35
- * declines: `undefined` at runtime makes real `toLocaleDateString` read
36
- * the host locale, which no frozen pattern table can reproduce;
34
+ * there, deferring the whole read to the client with `/* @client *\/`
35
+ * (`formatDate` itself is compiler ABI and cannot be called by name —
36
+ * BF056, #3089). An OPTIONAL union prop also declines: `undefined` at
37
+ * runtime makes real `toLocaleDateString` read the host locale, which
38
+ * no frozen pattern table can reproduce;
37
39
  * - an IANA `timeZone` literal the build machine cannot verify (#2344):
38
40
  * a named zone IS admitted when the build's own `Intl` echoes it back
39
41
  * verbatim from `resolvedOptions().timeZone` — the canonical primary
@@ -89,7 +91,8 @@ const tzProbeCache = new Map<string, boolean>()
89
91
  * spellings are exactly where backend tzdata layers disagree (Go/Python/
90
92
  * Ruby/Rust resolve the exact ID set; PHP folds case; link availability
91
93
  * varies by tzdata vintage). Anything the probe can't verify declines
92
- * (→ BF021) — the `formatDate` primitive stays available for edge cases.
94
+ * (→ BF021) — `/* @client *\/` stays available for edge cases (`formatDate`
95
+ * itself is compiler ABI and cannot be called by name — BF056, #3089).
93
96
  */
94
97
  export function isBuildResolvableTimeZone(value: string): boolean {
95
98
  const cached = tzProbeCache.get(value)
package/src/types.ts CHANGED
@@ -392,6 +392,15 @@ export interface IRElement {
392
392
  * shared partial carries the same id across every page that composes it.
393
393
  */
394
394
  regionId?: string
395
+ /**
396
+ * True when this element's `ref` callback is the recognized SSR-portal
397
+ * pattern (#3059): a local named callback whose body directly calls
398
+ * `createPortal(<this element>, document.body, { ownerScope })` — see
399
+ * `isSsrPortalRefCallback` in `jsx-to-ir.ts`. Every adapter's own SSR
400
+ * portal outlet (#3119) places the element's SSR markup there instead
401
+ * of inline, matching where hydration's `createPortal` moves it.
402
+ */
403
+ ssrPortalOwnerScope?: boolean
395
404
  loc: SourceLocation
396
405
  }
397
406
 
@@ -1154,6 +1163,21 @@ export interface IRComponent {
1154
1163
  * predicate every backend must consult instead of re-deriving this fact.
1155
1164
  */
1156
1165
  loopItemRoot?: boolean
1166
+ /**
1167
+ * True when this component IS the entire render root of a client-
1168
+ * interactive component (`'use client'`, or otherwise needing client
1169
+ * init) — no wrapping element of its own. Such a root has no DOM node
1170
+ * to hang `bf-s`/`bf-p` on, so the adapter must wrap its rendered
1171
+ * output in a comment-based scope marker pair instead, mirroring
1172
+ * `IRFragment.needsScopeComment` (which handles the analogous
1173
+ * multi-element-fragment-root case). Computed once, in `compiler.ts`
1174
+ * (`decideComponentRootScopeComment`) right after `metadata.clientAnalysis`
1175
+ * becomes available — NOT in `jsx-to-ir.ts`'s per-node transform, since
1176
+ * "is this component client-interactive" isn't known until then. Every
1177
+ * adapter renders the pair from this ONE flag (#3141) instead of each
1178
+ * re-deriving the "root is a component" check locally.
1179
+ */
1180
+ needsScopeComment?: boolean
1157
1181
  loc: SourceLocation
1158
1182
  }
1159
1183
 
@@ -1613,6 +1637,47 @@ export interface SignalInfo {
1613
1637
  * actually in scope, not a hardcoded canonical name (#2057).
1614
1638
  */
1615
1639
  envFactory?: string
1640
+ /**
1641
+ * Set when this signal is the value half of an async reactive factory
1642
+ * (`const [posts, action] = createQuery(fn, options)`, #3165) rather than
1643
+ * `createSignal`. The getter is a normal reactive getter (so it seeds,
1644
+ * substitutes and folds like any signal), and `initialValue` is the
1645
+ * `options.initial` expression — the literal `undefined` when the call has
1646
+ * no `initial`. `setter` is always `null`: the second tuple binding is
1647
+ * the factory's action, recorded here, never a setter.
1648
+ */
1649
+ factory?: SignalFactoryCall
1650
+ }
1651
+
1652
+ /**
1653
+ * The async reactive factory call a signal's value comes from (#3165). Every
1654
+ * backend that re-emits the declaration reads this instead of assuming
1655
+ * `createSignal`: client JS re-emits `<callee>(<argsText>)` (the request
1656
+ * function is never evaluated on the server), and SSR seeds the value from
1657
+ * `initialValue` like any other signal.
1658
+ */
1659
+ export interface SignalFactoryCall {
1660
+ /** Which factory: `createQuery` (#3165) or `createMutation` (#3210). */
1661
+ kind: 'query' | 'mutation'
1662
+ /** The callee as written: `createQuery` / `createMutation`, an alias, or `bf.createQuery`. */
1663
+ callee: string
1664
+ /**
1665
+ * The call's argument list as JS (type annotations stripped), emitted
1666
+ * verbatim into the client `init` body, where the props-rewrite passes turn
1667
+ * prop reads into live `_p` reads like any effect body.
1668
+ */
1669
+ argsText: string
1670
+ /**
1671
+ * The request function alone (the first argument, type annotations
1672
+ * stripped) and its free identifiers — `''` / empty when the call has no
1673
+ * argument. Kept apart from `argsText` because only the request function is
1674
+ * tracked: `options` (`initial`, `ttl`, `invalidates`) is read once, at
1675
+ * creation, so a signal read there re-sends nothing (`bf debug graph`, #3167).
1676
+ */
1677
+ requestText: string
1678
+ requestFreeIdentifiers: ReadonlySet<string>
1679
+ /** The action binding (the second tuple element), or `null` when it isn't destructured. */
1680
+ action: string | null
1616
1681
  }
1617
1682
 
1618
1683
  export interface MemoInfo {
@@ -1942,6 +2007,11 @@ export interface FunctionInfo {
1942
2007
  * migration; legacy emit paths default to inferring from `body`.
1943
2008
  */
1944
2009
  declarationKind?: 'function' | 'arrow' | 'function-expression'
2010
+ /**
2011
+ * Free identifiers of the function (parameters excluded), computed from the
2012
+ * AST: what its body reads when it is called.
2013
+ */
2014
+ freeIdentifiers?: ReadonlySet<string>
1945
2015
  /** When true, declared at module level (outside the component function). */
1946
2016
  isModule?: boolean
1947
2017
  /** When true, this function returns JSX and is inlined at call sites (#569). */
@@ -1995,6 +2065,12 @@ export interface ConstantInfo {
1995
2065
  isJsxFunction?: boolean
1996
2066
  /** When true, the initializer contains an arrow function or function expression (computed from AST). */
1997
2067
  containsArrow?: boolean
2068
+ /**
2069
+ * When true, the initializer IS an arrow function or function expression
2070
+ * (`const status = () => …`), so reading the constant yields a function and
2071
+ * only calling it evaluates the body. Computed from the AST.
2072
+ */
2073
+ isFunctionValue?: boolean
1998
2074
  /**
1999
2075
  * When true, a same-scope statement (a `for`/`while` body, or any other
2000
2076
  * imperative statement) mutates this binding's value AFTER its
@@ -2350,28 +2426,36 @@ export interface ErrorSuggestion {
2350
2426
  * fixture (packages/adapter-tests) instead of lowering it — the adapter's
2351
2427
  * machine-readable known-limitations declaration. Consumed by the adapter's
2352
2428
  * own conformance test (as `expectedDiagnostics`) and by `bf compat`
2353
- * (issue-URL attribution). Tracked limitations carry the `known-limitation`
2354
- * label: https://github.com/piconic-ai/barefootjs/labels/known-limitation
2429
+ * (limitation attribution). Every pin cites the registry entry that
2430
+ * defines the limitation it is an instance of:
2431
+ * `packages/adapter-tests/limitations/<id>.ts` (see that package's
2432
+ * `src/limitations.ts` for the entry format). The registry, not a label or
2433
+ * an issue tracker, is the source of truth for what is limited and why.
2355
2434
  */
2356
2435
  export interface ConformancePin {
2357
2436
  /** Diagnostic code, e.g. 'BF101'. */
2358
2437
  code: string
2359
2438
  severity: 'error' | 'warning'
2360
- /** Tracking issue URL (known-limitation label) for this refusal, when one exists. */
2361
- issue?: string
2439
+ /**
2440
+ * The registry id (`packages/adapter-tests/limitations/<id>.ts`) of the
2441
+ * limitation this refusal is an instance of. Required: a pin with no
2442
+ * definition behind it is a gap nobody can read about. The join test
2443
+ * (`packages/compat/src/__tests__/limitations-join.test.ts`) fails on an
2444
+ * id that has no entry, and on an entry whose `fixtures` do not list this
2445
+ * pin's fixture.
2446
+ */
2447
+ limitation: string
2362
2448
  /**
2363
2449
  * Present when THIS adapter has no verified escape yet for this
2364
- * refusal — the per-adapter half of #2613's "loud-or-escapable" floor
2365
- * (`packages/compat/src/__tests__/escape-coverage.test.ts`). `issue` is
2366
- * the tracking pointer for closing the gap (fall back to
2367
- * https://github.com/piconic-ai/barefootjs/issues/2613 itself when no
2368
- * more specific issue exists yet).
2450
+ * refusal — the per-adapter half of the "loud-or-escapable" floor
2451
+ * (`packages/compat/src/__tests__/escape-coverage.test.ts`).
2369
2452
  *
2370
2453
  * Declared here, next to the refusal it qualifies, so an adapter's own
2371
2454
  * package is the sole place that states what it knows about its own
2372
2455
  * refusal — no central cross-adapter ledger to keep in sync (that was
2373
- * the architectural defect increment 1 shipped with: a `packages/compat`
2374
- * test hardcoding every adapter's id, which made adapters non-additive).
2456
+ * the architectural defect the floor's first increment shipped with: a
2457
+ * `packages/compat` test hardcoding every adapter's id, which made
2458
+ * adapters non-additive).
2375
2459
  *
2376
2460
  * Absent means the adapter believes an escape is owed here — either
2377
2461
  * already satisfied (the refused fixture's `escapes` twin compiles
@@ -2381,8 +2465,10 @@ export interface ConformancePin {
2381
2465
  * Shrink-only, same discipline `KNOWN_HOLES` established: once a
2382
2466
  * working twin exists here, a lingering `unescapable` becomes a STALE
2383
2467
  * declaration and the floor test fails loudly on it, naming this pin.
2468
+ * The set of pins still carrying it is the "escape twins still to
2469
+ * author" work list — derived, never tracked elsewhere.
2384
2470
  */
2385
- unescapable?: { issue: string }
2471
+ unescapable?: true
2386
2472
  }
2387
2473
  /** Keyed by shared-fixture id (`JSXFixture.id`). */
2388
2474
  export type ConformancePins = Record<string, ReadonlyArray<ConformancePin>>
@@ -2397,10 +2483,12 @@ export type ConformancePins = Record<string, ReadonlyArray<ConformancePin>>
2397
2483
  * file derives the skip list from this object so the two can't drift)
2398
2484
  * and by `packages/compat` (the fixture-divergences section of
2399
2485
  * `ui/compat.lock.json`, rendered on the docs compatibility-matrix
2400
- * page). Keyed by shared-fixture id; the value is a one-line
2401
- * human-readable description of the divergence.
2486
+ * page). Keyed by shared-fixture id; the value cites the registry entry
2487
+ * (`packages/adapter-tests/limitations/<id>.ts`, kind `silent`) that
2488
+ * defines the divergence — what the reference renders, what this
2489
+ * adapter renders instead.
2402
2490
  */
2403
- export type RenderDivergences = Record<string, string>
2491
+ export type RenderDivergences = Record<string, { limitation: string }>
2404
2492
 
2405
2493
  // =============================================================================
2406
2494
  // Compile Options & Results
@@ -1,30 +0,0 @@
1
- /**
2
- * `formatDate` lowering plugin (#2324) — the pure-function date formatter
3
- * (`packages/client/src/format-date.ts`). A call to the `formatDate` binding
4
- * imported from `@barefootjs/client` lowers to a backend-neutral
5
- * `helper-call` on the `format_date` helper (spec/template-helpers.md), which
6
- * every adapter renders through its generic helper-call path (#2069) — no
7
- * adapter-specific recognition code, only the runtime helper each backend
8
- * ships.
9
- *
10
- * The canonical helper arity is 3: a two-arg call site
11
- * (`formatDate(d, 'YYYY/M/D')`) is normalized here by supplying the
12
- * `'UTC'` literal the client function defaults to, so backend helpers stay
13
- * fixed-arity. Unlike the `date` plugin there is no receiver-type gate —
14
- * `formatDate` is recognised by its import binding (like `queryHref`), and
15
- * its own receiver contract (native date / ISO string / nil → `''`) is total,
16
- * so any argument expression the adapter can evaluate is admissible.
17
- */
18
- import type { ParsedExpr } from './expression-parser.ts';
19
- import type { LoweringNode, LoweringPlugin } from './lowering-registry.ts';
20
- /**
21
- * Recognise `formatDate(date, pattern[, timeZone[, names]])` against the
22
- * component's local import bindings, or decline (null): a non-identifier
23
- * callee, a name not bound to the `@barefootjs/client` import, or an arity
24
- * outside 2–4. The canonical helper arity is 4 (#2334): omitted `timeZone` /
25
- * `names` normalize to the `'UTC'` literal and the empty table the client
26
- * function defaults to, so backend helpers stay fixed-arity.
27
- */
28
- export declare function matchFormatDateCall(callee: ParsedExpr, args: readonly ParsedExpr[], locals: ReadonlySet<string>): LoweringNode | null;
29
- export declare const formatDatePlugin: LoweringPlugin;
30
- //# sourceMappingURL=format-date-lowering.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"format-date-lowering.d.ts","sourceRoot":"","sources":["../src/format-date-lowering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAM1E;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3B,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,GAC1B,YAAY,GAAG,IAAI,CAQrB;AAED,eAAO,MAAM,gBAAgB,EAAE,cAO9B,CAAA"}
@@ -1,124 +0,0 @@
1
- /**
2
- * `createSelector` compiler recognition (perf, #2143 gap 5).
3
- *
4
- * `createSelector`'s returned accessor is `Reactive<(key) => boolean>`
5
- * branded exactly like a signal/memo getter, so the existing type-based
6
- * reactivity analyzer (`reactivity-checker.ts`) recognises a call like
7
- * `isSelected(row.id)` as reactive with no analyzer changes — the callee's
8
- * type carries the brand, not the call's return type. These tests pin:
9
- * - the classic js-framework-benchmark row compiles with `isSelected(row.id)`
10
- * wired through the lazy row graph — ZERO emitted per-row effects, the
11
- * loop-level effect living in `mapArrayLazy` (spec §9). Until §9.3a
12
- * was lifted this shape was gate-INELIGIBLE (an opaque local whose call
13
- * is the reactive read could not be primed) and compiled to one per-row
14
- * `createEffect`; the runtime re-subscribe seam replaced that, so the
15
- * loop is emitted like any other. Either way it is never
16
- * the legacy `selected() === row.id` shape, which subscribes every row
17
- * to the raw signal.
18
- * - the loop-param accessor wrap applies only to the call ARGUMENT
19
- * (`row.id` -> `row().id`), leaving the `isSelected` callee untouched
20
- * - the hoisted skeleton fast path (#2223) still fires for a selector-driven
21
- * attr, since it's covered by a loop-child reactive-attr effect like any
22
- * other dynamic attribute
23
- * - `createSelector` is pulled into the runtime import line
24
- * - the attr is auto-deferred out of the SSR-mirror `template:` lambda
25
- * (mechanism #1638, same as `@barefootjs/form` accessors) — pinned as
26
- * documented behavior, not a regression: full SSR parity for selector
27
- * calls is a known follow-up, not in scope here
28
- */
29
-
30
- import { describe, test, expect } from 'bun:test'
31
- import { compileJSX } from '../compiler'
32
- import { TestAdapter } from '../adapters/test-adapter'
33
-
34
- const adapter = new TestAdapter()
35
-
36
- function compile(source: string, filename: string): { clientJs: string; template: string; errors: readonly { severity: string }[] } {
37
- const result = compileJSX(source, filename, { adapter })
38
- const clientJs = result.files.find(f => f.type === 'clientJs')
39
- const template = result.files.find(f => f.type === 'markedTemplate')
40
- return { clientJs: clientJs?.content ?? '', template: template?.content ?? '', errors: result.errors }
41
- }
42
-
43
- describe('createSelector (perf, #2143 gap 5)', () => {
44
- test('isSelected(row.id) in a loop body compiles through the lazy row graph', () => {
45
- const source = `
46
- 'use client'
47
- import { createSignal, createSelector } from '@barefootjs/client'
48
-
49
- interface RowData { id: number; label: string }
50
-
51
- export function Bench() {
52
- const [rows, setRows] = createSignal<RowData[]>([])
53
- const [selected, setSelected] = createSignal<number>(0)
54
- const isSelected = createSelector(selected)
55
- return (
56
- <table>
57
- <tbody>
58
- {rows().map(row => (
59
- <tr key={row.id} className={isSelected(row.id) ? 'danger' : ''}></tr>
60
- ))}
61
- </tbody>
62
- </table>
63
- )
64
- }
65
- `
66
- const { clientJs, errors } = compile(source, 'Bench.tsx')
67
- expect(errors.filter(e => e.severity === 'error')).toHaveLength(0)
68
-
69
- // Loop-param wrap applies to the call ARGUMENT only.
70
- expect(clientJs).toContain('isSelected(row().id)')
71
- // The callee itself is never rewritten to an accessor call.
72
- expect(clientJs).not.toContain('isSelected()(')
73
-
74
- // The selector-driven class attribute costs NO emitted effect at all:
75
- // the loop is lazy-eligible, so its one loop-level effect lives inside
76
- // `mapArrayLazy` rather than in the emitted row body. It is also never
77
- // the O(rows) `selected() === row.id` shape.
78
- const effectCount = (clientJs.match(/createEffect\(/g) ?? []).length
79
- expect(effectCount).toBe(0)
80
- expect(clientJs).toContain('mapArrayLazy(')
81
- expect(clientJs).not.toContain('selected() ===')
82
-
83
- // `isSelected` is an opaque local (its CALL is the reactive read). Nothing
84
- // in the emission marks that: the runtime's re-subscribe seam applies to
85
- // every loop-level outer effect, so the compiler has no judgement to
86
- // encode here (§9.3a).
87
- expect(clientJs).not.toContain('outerNeedsResubscribe')
88
-
89
- // The hoisted skeleton fast path (#2223) still fires: a single-line
90
- // renderItem clones from a once-per-loop template.
91
- expect(clientJs).toMatch(/const __tpl_\w+ = document\.createElement\('template'\)/)
92
-
93
- // createSelector is pulled into the runtime import line.
94
- expect(clientJs).toMatch(/import \{[^}]*\bcreateSelector\b[^}]*\} from '@barefootjs\/client\/runtime'/)
95
- })
96
-
97
- test('selector-driven attr is deferred out of the SSR-mirror template lambda (documented, not a regression)', () => {
98
- const source = `
99
- 'use client'
100
- import { createSignal, createSelector } from '@barefootjs/client'
101
-
102
- interface RowData { id: number; label: string }
103
-
104
- export function Bench() {
105
- const [rows, setRows] = createSignal<RowData[]>([])
106
- const [selected, setSelected] = createSignal<number>(0)
107
- const isSelected = createSelector(selected)
108
- return (
109
- <ul>
110
- {rows().map(row => (
111
- <li key={row.id} className={isSelected(row.id) ? 'danger' : ''}>{row.label}</li>
112
- ))}
113
- </ul>
114
- )
115
- }
116
- `
117
- const { clientJs } = compile(source, 'BenchDefer.tsx')
118
- const csrMirror = clientJs.slice(clientJs.indexOf('hydrate('))
119
- // The class attribute never appears as a literal `class="..."` write in
120
- // the SSR-mirror template string — it's covered entirely by the
121
- // per-row createEffect, matching the documented auto-defer mechanism.
122
- expect(csrMirror).not.toMatch(/class="danger"/)
123
- })
124
- })