@farm.js/react 0.1.0-beta.20 → 0.1.0-beta.22

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.
package/README.md CHANGED
@@ -1,9 +1,9 @@
1
1
  # @farm.js/react
2
2
 
3
- React renderer integration for FARMJS, including the experimental AOT compiler.
3
+ React renderer integration for FARMJS, including the opt-in AOT compiler.
4
4
 
5
5
  React remains the default renderer and needs no package or configuration. Install this package only
6
- when opting into the compiler experiment:
6
+ when opting into the compiler:
7
7
 
8
8
  ```bash
9
9
  pnpm add @farm.js/react
@@ -15,9 +15,7 @@ import { react } from "@farm.js/react";
15
15
 
16
16
  export default defineConfig({
17
17
  renderer: react({
18
- experimental: {
19
- compiler: true,
20
- },
18
+ compiler: true,
21
19
  }),
22
20
  });
23
21
  ```
@@ -25,6 +23,25 @@ export default defineConfig({
25
23
  `compiler: true` uses inference: every application TSX/JSX component is considered, eligible
26
24
  components are compiled with hybrid reactivity, and everything else keeps the normal React path.
27
25
 
26
+ The compiler stays off when this option is omitted or `false`. The former
27
+ `react({ experimental: { compiler } })` spelling remains a deprecated alias with the same options
28
+ and a one-time warning. Do not configure both spellings, even when one is `false`.
29
+
30
+ ### Compatibility and upgrades
31
+
32
+ `react({ compiler })`, `ReactCompilerOptions`, and `List` from `@farm.js/react/list` are the
33
+ application-facing API. Both inference and annotation mode, static and hybrid reactivity, fallback
34
+ diagnostics, and coverage reporting remain supported. Annotation and static mode are advanced
35
+ options, not separate experimental APIs. The package is independently versioned; a prerelease
36
+ version remains a beta until its stable release is published.
37
+
38
+ The compiler and `@farm.js/react/compiler-runtime` ship together. Generated definitions must use
39
+ the runtime from the same installed package version; they are not a cross-version interchange
40
+ format. Upgrade the package and rebuild the complete app, including SSR and browser output,
41
+ together. Do not copy generated compiler output between package versions or deploy a new server
42
+ with an old browser build. Existing runtime exports remain available, but prefer ordinary React
43
+ source over hand-authored compiler definitions.
44
+
28
45
  Hybrid reactivity starts from the compiler's proven state-to-binding dependency lists, then marks
29
46
  only multi-state short-circuit bindings for runtime read tracking. For
30
47
  `enabled ? activeValue : inactiveValue`, an update to the inactive value does not schedule the
@@ -53,13 +70,11 @@ For selective adoption, use annotation mode:
53
70
 
54
71
  ```ts
55
72
  renderer: react({
56
- experimental: {
57
- compiler: {
58
- mode: "annotation",
59
- directive: "use compiler",
60
- onUnsupported: "warn",
61
- reactivity: "hybrid",
62
- },
73
+ compiler: {
74
+ mode: "annotation",
75
+ directive: "use compiler",
76
+ onUnsupported: "warn",
77
+ reactivity: "hybrid",
63
78
  },
64
79
  }),
65
80
  ```
@@ -925,6 +940,12 @@ components, fragments, refs, SVG, spreads, dangerous HTML, and index keys keep t
925
940
  row on React's fallback. Additional keyed levels that satisfy the same host-only contract are
926
941
  analyzed recursively instead of using a fixed nesting limit.
927
942
 
943
+ When every inner key stays in the same order, the nested scope reuses its row table and skips
944
+ position-map construction and LIS planning. It still validates all keys and updates every child
945
+ scope and binding. Insertions, removals, and reorders keep the existing structural reconciliation;
946
+ duplicate keys or an invalid child scope keep the existing React fallback. This also applies to
947
+ keyed ranges next to host-only conditions inside a nested mixed range.
948
+
928
949
  For example, `boards → columns → cards → tags` becomes a tree of keyed scopes. Each stable parent
929
950
  key owns its child key table and LIS pass. Moving a board carries its column, card, and tag scopes;
930
951
  reordering cards reconciles only the selected column. Block IDs stay globally unique while runtime