@tinkered/react 0.25.1 → 0.27.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/README.md CHANGED
@@ -80,7 +80,7 @@ function App() {
80
80
  - `useData(cell)` reads a cell and follows its changes.
81
81
  A selector reads part of its value.
82
82
  - `useData(cell, { writable: true })` returns the value and a setter.
83
- - `useData(total({ viewer }))` reads a Core `derived`.
83
+ - `useData(total({ viewer }))` reads a keyed Core `resource`.
84
84
  Each reader of the same config gets the same value, so it needs no `useMemo`.
85
85
  - `useController` supplies writes without subscribing the component.
86
86
  - `useResource` reads a built resource.
@@ -222,7 +222,7 @@ This appendix states each behaviour the seam tests pin, one line per promise, gr
222
222
  - useData with no provider raises NoProvider.
223
223
  - An unchanged object value keeps its identity across a parent re-render.
224
224
  - A write after unmount neither updates the removed subtree nor breaks the still-open scope.
225
- - A component reads a derived, keeps its reference across renders, and follows a write.
225
+ - A component reads a keyed resource, keeps its reference across renders, and follows a write.
226
226
  - A new config leaves the old entry.
227
227
 
228
228
  ### useResource
package/dist/index.d.mts CHANGED
@@ -67,10 +67,10 @@ export declare function useData<T>(view: Data.View<T>): T;
67
67
  * `useData(tasks.where({ project }))` (ADR 0136). It re-renders only when that part changes; a
68
68
  * new key leaves the old part. Read-only: write through an op. */
69
69
  export declare function useData<T>(read: Data.Read<T>): T;
70
- /** Reactively read a derived (ADR 0150): `useData(prView({ viewer, mode }))`, or the bare unit
70
+ /** Reactively read a keyed resource (ADR 0150): `useData(prView({ viewer, mode }))`, or the bare unit
71
71
  * when it needs no config. Every reader of the same config shares one entry; a new config leaves
72
72
  * the old one. */
73
- export declare function useData<T>(read: Data.Derived<T>): T;
73
+ export declare function useData<T>(read: Data.Built<T>): T;
74
74
  /** Reactively read a slice of a capsule's cell export. */
75
75
  export declare function useData<T, S>(view: Data.View<T>, selector: (value: T) => S, isEqual?: (a: S, b: S) => boolean): S;
76
76
  /** Reactively read a slice of a `data` cell: returns `selector(value)` and re-renders only when the
package/dist/index.mjs CHANGED
@@ -210,7 +210,7 @@ const isView = (target) => target.kind !== void 0;
210
210
  function wantsPair(cell, options) {
211
211
  return options?.writable === true && !isView(cell);
212
212
  }
213
- /** A cell reads through its controller; a view, a keyed read, and a derived read through the
213
+ /** A cell reads through its controller; a view, a keyed read, and a keyed resource read through the
214
214
  * reader the scope resolves them to. */
215
215
  function readableOf(scope, cell) {
216
216
  return isView(cell) ? scope.resolve(cell) : scope.controller(cell);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinkered/react",
3
- "version": "0.25.1",
3
+ "version": "0.27.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.1"
32
+ "@tinkered/core": "^0.27.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.1",
37
+ "@tinkered/core": "^0.27.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,
9
- tinker/one-wire or tinker/keyed-prop.
8
+ check prints tinker/kind, tinker/react-state
9
+ or tinker/one-wire.
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.1'
18
+ library_version: '0.27.0'
19
19
  requires:
20
20
  - '@tinkered/core#core'
21
21
  sources:
@@ -110,26 +110,24 @@ 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:
113
+ A list reads once with `where` and passes each
114
+ member to its item. Core keeps a member's
115
+ reference until that member changes, so a
116
+ `memo` item draws again only for its own change.
115
117
 
116
118
  ```tsx no-check
117
119
  {list.map((wave) => (
118
- <Wave key={wave.id} room={room} id={wave.id} />
120
+ <Wave key={wave.id} wave={wave} />
119
121
  ))}
120
-
121
- function Wave({ room, id }: WaveProps) {
122
- const wave = useData(sea.board.waves.of({ room, id }));
123
- // ...
124
- }
125
122
  ```
126
123
 
127
- A write to one member then draws that item
128
- alone.
124
+ Read `of(key)` when a component has the key and
125
+ no list above it.
129
126
 
130
127
  ### A computed value with a stable reference
131
128
 
132
- Use a Core `derived`, not `useMemo`. Pass its
129
+ Use a Core `resource` with a `config`, not
130
+ `useMemo`. Pass its
133
131
  config at each render. Every reader of the same
134
132
  config gets the same value.
135
133
 
@@ -175,8 +173,46 @@ function Form() {
175
173
  }
176
174
  ```
177
175
 
176
+ ### Show each kind of an answer
177
+
178
+ A call can answer a union by `kind`. The page
179
+ reads it in a `switch` with a case for each kind,
180
+ and no `default`. A new kind in the contract then
181
+ fails the check at this `switch`.
182
+
183
+ ```tsx no-check
184
+ function Moved({ out }: { out?: MoveAnswer }) {
185
+ switch (out?.kind) {
186
+ case undefined:
187
+ case "moved":
188
+ return null;
189
+ case "stale":
190
+ return <small role="status">Changed.</small>;
191
+ case "gone":
192
+ return <small role="status">Gone.</small>;
193
+ }
194
+ }
195
+ ```
196
+
197
+ Read a field only in the case of a kind that has
198
+ it. `out.version` in case `gone` fails the type
199
+ check.
200
+
178
201
  ## Common mistakes
179
202
 
203
+ ### HIGH: a kind with no case [tinker/kind]
204
+
205
+ Wrong:
206
+
207
+ ```tsx no-check
208
+ if (out?.kind === "stale") return <Stale />;
209
+ return null;
210
+ ```
211
+
212
+ Right: a `switch` on `kind`, with a case for
213
+ each kind the check names. Do not add `default:`.
214
+ Do not cast.
215
+
180
216
  ### HIGH: `useState` or `useReducer` [tinker/react-state]
181
217
 
182
218
  Wrong:
@@ -189,7 +225,7 @@ Right: a `data` cell, read with `useData`. For
189
225
  state that must end with a subtree, put the
190
226
  subtree in a `SessionProvider`.
191
227
 
192
- ### HIGH: `useEffect` [tinker/react-state]
228
+ ### HIGH: `useEffect` or `useLayoutEffect` [tinker/react-state]
193
229
 
194
230
  Wrong:
195
231
 
@@ -204,19 +240,6 @@ Right: a `resource` holds the timer and its
204
240
  cleanup. An operation or a capsule `start` hook
205
241
  depends on it.
206
242
 
207
- ### HIGH: a member passed as a prop [tinker/keyed-prop]
208
-
209
- Wrong:
210
-
211
- ```tsx no-check
212
- {list.map((wave) => <Wave wave={wave} />)}
213
- <Lanes list={list} />
214
- ```
215
-
216
- Right: pass the key. The child reads
217
- `useData(part.of(key))`, or `part.where(key)`
218
- for a list.
219
-
220
243
  ### HIGH: `fetch` in a component [tinker/one-wire]
221
244
 
222
245
  The page talks to the server by rpc and remote
@@ -235,8 +258,6 @@ third argument.
235
258
 
236
259
  ## Completion
237
260
 
238
- - The app's frontend check prints no
239
- `tinker/react-state`, `tinker/one-wire` or
240
- `tinker/keyed-prop`.
261
+ - `tinker check` prints `tinker check: OK`.
241
262
  - A browser test clicks the control and reads
242
263
  the new text.