@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 +2 -2
- package/dist/index.d.mts +2 -2
- package/dist/index.mjs +1 -1
- package/package.json +3 -3
- package/skills/react/SKILL.md +52 -31
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 `
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
37
|
+
"@tinkered/core": "^0.27.0",
|
|
38
38
|
"@types/node": "^26.1.1",
|
|
39
39
|
"@types/react": "^19",
|
|
40
40
|
"@types/react-dom": "^19",
|
package/skills/react/SKILL.md
CHANGED
|
@@ -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
|
|
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.
|
|
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
|
|
114
|
-
|
|
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}
|
|
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
|
-
|
|
128
|
-
|
|
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 `
|
|
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
|
-
-
|
|
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.
|