@tinkered/react 0.25.0 → 0.26.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinkered/react",
3
- "version": "0.25.0",
3
+ "version": "0.26.0",
4
4
  "description": "Tinkered React: a thin React adapter over @tinkered/core.",
5
5
  "keywords": [
6
6
  "tanstack-intent"
@@ -29,12 +29,12 @@
29
29
  "access": "public"
30
30
  },
31
31
  "dependencies": {
32
- "@tinkered/core": "^0.25.0"
32
+ "@tinkered/core": "^0.26.0"
33
33
  },
34
34
  "devDependencies": {
35
35
  "@stryker-mutator/core": "^10.0.0",
36
36
  "@stryker-mutator/vitest-runner": "^10.0.0",
37
- "@tinkered/core": "^0.25.0",
37
+ "@tinkered/core": "^0.26.0",
38
38
  "@types/node": "^26.1.1",
39
39
  "@types/react": "^19",
40
40
  "@types/react-dom": "^19",
@@ -5,8 +5,8 @@ description: >
5
5
  component in a Tinker app: read a cell, run
6
6
  an operation from a button, show a pending or
7
7
  failed call, or mount the app. Also when a
8
- check prints tinker/react-state or
9
- tinker/one-wire.
8
+ check prints tinker/kind, tinker/react-state,
9
+ tinker/one-wire or tinker/keyed-prop.
10
10
  metadata:
11
11
  purpose: >
12
12
  How React reads cells and runs operations
@@ -15,7 +15,7 @@ metadata:
15
15
  type: framework
16
16
  framework: react
17
17
  library: '@tinkered/react'
18
- library_version: '0.25.0'
18
+ library_version: '0.26.0'
19
19
  requires:
20
20
  - '@tinkered/core#core'
21
21
  sources:
@@ -110,6 +110,23 @@ const one = useData(
110
110
  );
111
111
  ```
112
112
 
113
+ A list item reads its own member by key. The
114
+ list passes the key, never the member:
115
+
116
+ ```tsx no-check
117
+ {list.map((wave) => (
118
+ <Wave key={wave.id} room={room} id={wave.id} />
119
+ ))}
120
+
121
+ function Wave({ room, id }: WaveProps) {
122
+ const wave = useData(sea.board.waves.of({ room, id }));
123
+ // ...
124
+ }
125
+ ```
126
+
127
+ A write to one member then draws that item
128
+ alone.
129
+
113
130
  ### A computed value with a stable reference
114
131
 
115
132
  Use a Core `derived`, not `useMemo`. Pass its
@@ -158,8 +175,46 @@ function Form() {
158
175
  }
159
176
  ```
160
177
 
178
+ ### Show each kind of an answer
179
+
180
+ A call can answer a union by `kind`. The page
181
+ reads it in a `switch` with a case for each kind,
182
+ and no `default`. A new kind in the contract then
183
+ fails the check at this `switch`.
184
+
185
+ ```tsx no-check
186
+ function Moved({ out }: { out?: MoveAnswer }) {
187
+ switch (out?.kind) {
188
+ case undefined:
189
+ case "moved":
190
+ return null;
191
+ case "stale":
192
+ return <small role="status">Changed.</small>;
193
+ case "gone":
194
+ return <small role="status">Gone.</small>;
195
+ }
196
+ }
197
+ ```
198
+
199
+ Read a field only in the case of a kind that has
200
+ it. `out.version` in case `gone` fails the type
201
+ check.
202
+
161
203
  ## Common mistakes
162
204
 
205
+ ### HIGH: a kind with no case [tinker/kind]
206
+
207
+ Wrong:
208
+
209
+ ```tsx no-check
210
+ if (out?.kind === "stale") return <Stale />;
211
+ return null;
212
+ ```
213
+
214
+ Right: a `switch` on `kind`, with a case for
215
+ each kind the check names. Do not add `default:`.
216
+ Do not cast.
217
+
163
218
  ### HIGH: `useState` or `useReducer` [tinker/react-state]
164
219
 
165
220
  Wrong:
@@ -172,7 +227,7 @@ Right: a `data` cell, read with `useData`. For
172
227
  state that must end with a subtree, put the
173
228
  subtree in a `SessionProvider`.
174
229
 
175
- ### HIGH: `useEffect` [tinker/react-state]
230
+ ### HIGH: `useEffect` or `useLayoutEffect` [tinker/react-state]
176
231
 
177
232
  Wrong:
178
233
 
@@ -187,6 +242,19 @@ Right: a `resource` holds the timer and its
187
242
  cleanup. An operation or a capsule `start` hook
188
243
  depends on it.
189
244
 
245
+ ### HIGH: a member passed as a prop [tinker/keyed-prop]
246
+
247
+ Wrong:
248
+
249
+ ```tsx no-check
250
+ {list.map((wave) => <Wave wave={wave} />)}
251
+ <Lanes list={list} />
252
+ ```
253
+
254
+ Right: pass the key. The child reads
255
+ `useData(part.of(key))`, or `part.where(key)`
256
+ for a list.
257
+
190
258
  ### HIGH: `fetch` in a component [tinker/one-wire]
191
259
 
192
260
  The page talks to the server by rpc and remote
@@ -205,7 +273,6 @@ third argument.
205
273
 
206
274
  ## Completion
207
275
 
208
- - The app's frontend check prints no
209
- `tinker/react-state` and no `tinker/one-wire`.
276
+ - `tinker check` prints `tinker check: OK`.
210
277
  - A browser test clicks the control and reads
211
278
  the new text.