@runic-artifex/react 0.12.1 → 0.13.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 +49 -10
- package/dist/index.d.ts +63 -0
- package/dist/index.js +44 -2
- package/dist/menu-bar.js +1 -1
- package/package.json +7 -5
package/README.md
CHANGED
|
@@ -88,6 +88,42 @@ export function CounterPage({ page }: { page: CounterPageReference }) {
|
|
|
88
88
|
The control shows the ViewModel's value, so it reverts when the setter throws
|
|
89
89
|
or keeps a different value.
|
|
90
90
|
|
|
91
|
+
### Text inputs: `useTextField(view, read, write, options?)`
|
|
92
|
+
|
|
93
|
+
Binds a controlled text input to a member through the framework-neutral
|
|
94
|
+
[text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#text-inputs)
|
|
95
|
+
while the component is mounted. `read` and `write` may close over render values:
|
|
96
|
+
|
|
97
|
+
```tsx
|
|
98
|
+
export function PersonPage({ page }: { page: PersonPageReference }) {
|
|
99
|
+
const person = useView(page);
|
|
100
|
+
const name = useTextField(person, state => state.name, (client, value) => client.setName(value));
|
|
101
|
+
return <>
|
|
102
|
+
<input value={name.value} onChange={name.onChange}
|
|
103
|
+
onCompositionStart={name.onCompositionStart} onCompositionEnd={name.onCompositionEnd} />
|
|
104
|
+
{name.error !== undefined && <p role="alert">{String(name.error)}</p>}
|
|
105
|
+
</>;
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
It returns `value`, `editing` and `error` with the `onChange`, `onCompositionStart`
|
|
110
|
+
and `onCompositionEnd` handlers and `reset()`. `view` is a `useView` handle or any
|
|
111
|
+
`{ state, client }`. The options `coalesce` and `keepDraftOnError` are read when the
|
|
112
|
+
component mounts.
|
|
113
|
+
The field shows what the user typed while its writes are in flight, so a reply or
|
|
114
|
+
frame that answers an older keystroke never replaces newer text. At most one write is
|
|
115
|
+
in flight; text typed meanwhile is written next as one value (`coalesce: false` writes
|
|
116
|
+
every change). Nothing is written during IME composition. Once the last write settled,
|
|
117
|
+
the field shows the View's value again, including any normalization the ViewModel
|
|
118
|
+
applied (trimmed, upper-cased). `write` may also be a command or a checked write. A
|
|
119
|
+
failed write keeps the draft and sets `error` (`keepDraftOnError: false` shows the
|
|
120
|
+
View's value instead); `reset()` drops the draft. `editing` is true while a draft
|
|
121
|
+
exists. Don't disable the input on the View's busy state (`isSaving`, `can…`) while
|
|
122
|
+
the user types: the field's own write causes it, and keys typed meanwhile would be
|
|
123
|
+
lost. Test such fields by typing key by key (Playwright `pressSequentially`, Testing
|
|
124
|
+
Library `user.type`) against the mock with `latency: "slow"`; `fill()` sets the whole
|
|
125
|
+
text at once and hides the race.
|
|
126
|
+
|
|
91
127
|
## `useSuspenseView(source, options?)`
|
|
92
128
|
|
|
93
129
|
Suspends the component until a reference connects, then returns
|
|
@@ -171,7 +207,7 @@ neither.
|
|
|
171
207
|
## `useOperation(start, options?)`
|
|
172
208
|
|
|
173
209
|
Observes a generated `start<Command>()` operation through the framework-neutral
|
|
174
|
-
[operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
210
|
+
[operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#operation-feedback-and-latest-selection).
|
|
175
211
|
`run(...args)` calls the latest `start`, so it may close over the current client:
|
|
176
212
|
|
|
177
213
|
```tsx
|
|
@@ -182,12 +218,15 @@ const push = useOperation((remote: string) => client?.startPush(remote));
|
|
|
182
218
|
{push.error !== undefined && <p role="alert">{String(push.error)}</p>}
|
|
183
219
|
```
|
|
184
220
|
|
|
185
|
-
The result has `pending`, `admitting`, `operation`, `status`, `outcome`, `failure`,
|
|
221
|
+
The result has `pending`, `admitting`, `operation`, `status`, `progress`, `outcome`, `failure`,
|
|
186
222
|
`error`, `cancelled`, `cancellationRequested`, `cancelling`, `cancellation` and
|
|
187
223
|
`cancelError`, with `run(...args)`, `cancel()` and `reset()`, which never reject. A
|
|
188
224
|
run that ends with a `cancelled` status sets `cancelled` and resolves to `undefined`
|
|
189
225
|
without an `error`; `failed` and `timed-out` statuses are still `error`. `pending`
|
|
190
226
|
stays true after a Cancel response until the operation reaches its terminal status.
|
|
227
|
+
`progress` is how far the running operation got, from 0 to 1, when its command
|
|
228
|
+
reports progress (`RunicOperationProgress.Report` in .NET), for example
|
|
229
|
+
`<progress value={push.progress} />`; it is `undefined` while unknown and after the run.
|
|
191
230
|
Unmounting disposes the controller, as `useCommand` does: a run still in flight
|
|
192
231
|
resolves to `undefined`, `waitForCompletion` is not called after it, and accepted
|
|
193
232
|
work is never cancelled. StrictMode's simulated unmount, and a component that
|
|
@@ -200,7 +239,7 @@ controller's options.
|
|
|
200
239
|
|
|
201
240
|
Admits only the newest of several reads, for example loading the item the user
|
|
202
241
|
selected last, through the framework-neutral
|
|
203
|
-
[latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
242
|
+
[latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#operation-feedback-and-latest-selection).
|
|
204
243
|
Each `run(intent)` replaces the queued intent and cancels the active read; the next
|
|
205
244
|
read starts only after the previous one reaches its terminal status and the intent's
|
|
206
245
|
optional `waitForCompletion` barrier:
|
|
@@ -230,7 +269,7 @@ It wraps `onBridgeConnection` from `@runic-artifex/views` (re-exported here sinc
|
|
|
230
269
|
`BridgeConnectionState` and `BridgeConnectionOptions` types) and returns
|
|
231
270
|
`{ state }`, where `state` is a `BridgeConnectionState`: `connecting`,
|
|
232
271
|
`connected`, `reconnecting` or `lost` (a closed set, see
|
|
233
|
-
[Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
272
|
+
[Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#connection-state)):
|
|
234
273
|
|
|
235
274
|
```tsx
|
|
236
275
|
import { useBridgeConnection } from "@runic-artifex/react";
|
|
@@ -251,7 +290,7 @@ subscribes again; an invalid one throws a `RangeError`. A server render reads
|
|
|
251
290
|
Follows the declared menu bar of a Runic Desktop window that leaves it to the
|
|
252
291
|
page (`DesktopMenuBarPresentation.Page`) while the component is mounted. It
|
|
253
292
|
wraps `createMenuBarController` from `@runic-artifex/views` (see
|
|
254
|
-
[In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
293
|
+
[In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a
|
|
255
294
|
`MenuBarState`, and the bar is rendered by the menubar component of the
|
|
256
295
|
application's own UI library. Runic ships no menubar component.
|
|
257
296
|
|
|
@@ -281,7 +320,7 @@ The controller starts in an effect, so a server render reads `connecting`, and
|
|
|
281
320
|
|
|
282
321
|
Base UI's `Menubar` (`@base-ui/react`, the base of shadcn/ui's Base UI
|
|
283
322
|
Menubar) with a controlled open menu; the
|
|
284
|
-
[Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
323
|
+
[Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
|
|
285
324
|
items and is tested with real keys:
|
|
286
325
|
|
|
287
326
|
```tsx
|
|
@@ -346,7 +385,7 @@ const offline = error instanceof BridgeError && error.kind === "disconnected";
|
|
|
346
385
|
```
|
|
347
386
|
|
|
348
387
|
`instanceof` holds for errors from every copy of the package on the page.
|
|
349
|
-
[Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
388
|
+
[Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#errors-and-diagnostics)
|
|
350
389
|
lists the kinds. Any other value, such as an exception that your own connect
|
|
351
390
|
function or command callback throws, arrives unchanged.
|
|
352
391
|
|
|
@@ -388,16 +427,16 @@ the application's own dialog.
|
|
|
388
427
|
such as a close during the page's first render, is answered by the
|
|
389
428
|
ViewModel's .NET fallback handler, or fails closed without one.
|
|
390
429
|
|
|
391
|
-
The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
430
|
+
The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.13.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
|
|
392
431
|
has the .NET side and which View answers which departure. In a frontend test,
|
|
393
432
|
the generated mock's `interactions.<name>.request(input)` resolves with the
|
|
394
433
|
registered handler's answer; see the
|
|
395
|
-
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
434
|
+
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#testing).
|
|
396
435
|
|
|
397
436
|
## `useCollectionViewport(options)`
|
|
398
437
|
|
|
399
438
|
Follows a fixed-row-height scroll container and returns `{ viewport, ref }`.
|
|
400
|
-
`viewport` is the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
439
|
+
`viewport` is the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#collectionviewportoptions)
|
|
401
440
|
range for the container; it changes only when the range or sizes change. Send
|
|
402
441
|
the range to the ViewModel from an effect:
|
|
403
442
|
|
package/dist/index.d.ts
CHANGED
|
@@ -123,6 +123,69 @@ export interface LatestOperationHandle<TResult, TFailure = never> extends Latest
|
|
|
123
123
|
* ```
|
|
124
124
|
*/
|
|
125
125
|
export declare function useLatestOperation<TResult = void, TFailure = never>(): LatestOperationHandle<TResult, TFailure>;
|
|
126
|
+
export interface TextFieldHandle {
|
|
127
|
+
/** What the input shows: the draft while one exists, otherwise the member's value in the View's state. */
|
|
128
|
+
readonly value: string;
|
|
129
|
+
/**
|
|
130
|
+
* True while a draft exists, from the first input until the last write settled and the state caught up, and after a
|
|
131
|
+
* failed write. Keep the input enabled while it is true, rather than disabling it on the View's busy state, which
|
|
132
|
+
* the field's own write causes.
|
|
133
|
+
*/
|
|
134
|
+
readonly editing: boolean;
|
|
135
|
+
/** Why the latest write failed, until the next input or `reset()`. */
|
|
136
|
+
readonly error: unknown;
|
|
137
|
+
/** The input's `onChange`: the user changed the text. */
|
|
138
|
+
onChange(event: {
|
|
139
|
+
readonly currentTarget: {
|
|
140
|
+
readonly value: string;
|
|
141
|
+
};
|
|
142
|
+
}): void;
|
|
143
|
+
/** The input's `onCompositionStart`: the text is kept but not written until the IME composition ends. */
|
|
144
|
+
onCompositionStart(): void;
|
|
145
|
+
/** The input's `onCompositionEnd`: the composed text is written. */
|
|
146
|
+
onCompositionEnd(event: {
|
|
147
|
+
readonly currentTarget: {
|
|
148
|
+
readonly value: string;
|
|
149
|
+
};
|
|
150
|
+
}): void;
|
|
151
|
+
/** Drops the draft and the error and shows the View's value. Writes in flight still complete. */
|
|
152
|
+
reset(): void;
|
|
153
|
+
}
|
|
154
|
+
export interface UseTextFieldOptions {
|
|
155
|
+
/**
|
|
156
|
+
* With `true` (the default) at most one write is in flight, and text typed meanwhile is written next, as one
|
|
157
|
+
* value. With `false` every change is written. Read when the component mounts.
|
|
158
|
+
*/
|
|
159
|
+
readonly coalesce?: boolean;
|
|
160
|
+
/**
|
|
161
|
+
* With `true` (the default) a failed write keeps the draft and sets `error`; with `false` the field shows the
|
|
162
|
+
* View's value again. Read when the component mounts.
|
|
163
|
+
*/
|
|
164
|
+
readonly keepDraftOnError?: boolean;
|
|
165
|
+
}
|
|
166
|
+
/** The View a text field binds to: a {@link useView} handle, or any state and client. */
|
|
167
|
+
export interface TextFieldView<TClient extends ViewClient> {
|
|
168
|
+
readonly state: TClient["snapshot"] | undefined;
|
|
169
|
+
readonly client: TClient | undefined;
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* Binds a controlled text input to one member of a View while the component is mounted, through
|
|
173
|
+
* `createTextFieldController`. Typing key by key never loses characters: while its writes are in flight the field
|
|
174
|
+
* shows what the user typed, at most one write is in flight (newer text is written next), nothing is written during
|
|
175
|
+
* IME composition, and once the last write settled it shows the View's value, including any normalization. `read`
|
|
176
|
+
* and `write` may close over render values; the latest ones are used.
|
|
177
|
+
*
|
|
178
|
+
* ```tsx
|
|
179
|
+
* const person = useView(page);
|
|
180
|
+
* const name = useTextField(person, state => state.name, (client, value) => client.setName(value));
|
|
181
|
+
* <input value={name.value} onChange={name.onChange}
|
|
182
|
+
* onCompositionStart={name.onCompositionStart} onCompositionEnd={name.onCompositionEnd} />
|
|
183
|
+
* ```
|
|
184
|
+
*
|
|
185
|
+
* `write` may be a generated setter, a command or a checked write. Its failure sets `error` and keeps the draft.
|
|
186
|
+
* Unmounting writes text that waits for a write in flight, and stops updating the handle.
|
|
187
|
+
*/
|
|
188
|
+
export declare function useTextField<TClient extends ViewClient>(view: TextFieldView<TClient>, read: (state: TClient["snapshot"]) => string, write: (client: TClient, value: string) => Promise<unknown>, options?: UseTextFieldOptions): TextFieldHandle;
|
|
126
189
|
export interface BridgeConnectionHandle {
|
|
127
190
|
/** The connection to the .NET host, as `onBridgeConnection` reports it. */
|
|
128
191
|
readonly state: BridgeConnectionState;
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { createElement, useCallback, useEffect, useInsertionEffect, useReducer, useRef, useState, useSyncExternalStore, } from "react";
|
|
2
|
-
import { createCommandController, createLatestOperationController, createOperationController, createViewController, onBridgeConnection, } from "@runic-artifex/views";
|
|
1
|
+
import { createElement, useCallback, useEffect, useInsertionEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore, } from "react";
|
|
2
|
+
import { createCommandController, createLatestOperationController, createOperationController, createTextFieldController, createViewController, onBridgeConnection, } from "@runic-artifex/views";
|
|
3
3
|
import { isViewClient, viewSourceIdentity } from "@runic-artifex/views/bindings";
|
|
4
4
|
// An inline `{ connect: () => connectX() }` creates a new function on every
|
|
5
5
|
// render, so every render reconnects and each connection renders again.
|
|
@@ -209,6 +209,48 @@ export function useLatestOperation() {
|
|
|
209
209
|
const current = useSyncExternalStore(controller.subscribe, read, read);
|
|
210
210
|
return { ...current, run: controller.run, clear: controller.clear };
|
|
211
211
|
}
|
|
212
|
+
/**
|
|
213
|
+
* Binds a controlled text input to one member of a View while the component is mounted, through
|
|
214
|
+
* `createTextFieldController`. Typing key by key never loses characters: while its writes are in flight the field
|
|
215
|
+
* shows what the user typed, at most one write is in flight (newer text is written next), nothing is written during
|
|
216
|
+
* IME composition, and once the last write settled it shows the View's value, including any normalization. `read`
|
|
217
|
+
* and `write` may close over render values; the latest ones are used.
|
|
218
|
+
*
|
|
219
|
+
* ```tsx
|
|
220
|
+
* const person = useView(page);
|
|
221
|
+
* const name = useTextField(person, state => state.name, (client, value) => client.setName(value));
|
|
222
|
+
* <input value={name.value} onChange={name.onChange}
|
|
223
|
+
* onCompositionStart={name.onCompositionStart} onCompositionEnd={name.onCompositionEnd} />
|
|
224
|
+
* ```
|
|
225
|
+
*
|
|
226
|
+
* `write` may be a generated setter, a command or a checked write. Its failure sets `error` and keeps the draft.
|
|
227
|
+
* Unmounting writes text that waits for a write in flight, and stops updating the handle.
|
|
228
|
+
*/
|
|
229
|
+
export function useTextField(view, read, write, options = {}) {
|
|
230
|
+
const latest = useRef({ read, write });
|
|
231
|
+
useInsertionEffect(() => { latest.current = { read, write }; });
|
|
232
|
+
const controller = useMountedController(() => createTextFieldController({
|
|
233
|
+
read: state => latest.current.read(state),
|
|
234
|
+
write: (client, value) => latest.current.write(client, value),
|
|
235
|
+
...options.coalesce === undefined ? {} : { coalesce: options.coalesce },
|
|
236
|
+
...options.keepDraftOnError === undefined ? {} : { keepDraftOnError: options.keepDraftOnError },
|
|
237
|
+
}));
|
|
238
|
+
const { state, client } = view;
|
|
239
|
+
useEffect(() => {
|
|
240
|
+
controller.setSource(state === undefined || client === undefined ? undefined : { state, client });
|
|
241
|
+
}, [controller, state, client]);
|
|
242
|
+
const readCurrent = useCallback(() => controller.current, [controller]);
|
|
243
|
+
const current = useSyncExternalStore(controller.subscribe, readCurrent, readCurrent);
|
|
244
|
+
const handlers = useMemo(() => ({
|
|
245
|
+
onChange: (event) => controller.input(event.currentTarget.value),
|
|
246
|
+
onCompositionStart: () => controller.compositionStart(),
|
|
247
|
+
onCompositionEnd: (event) => controller.compositionEnd(event.currentTarget.value),
|
|
248
|
+
reset: () => controller.reset(),
|
|
249
|
+
}), [controller]);
|
|
250
|
+
// Without a draft the field shows the state being rendered, which the effect passes to the controller after the render.
|
|
251
|
+
const value = current.editing ? current.value : state === undefined ? "" : read(state);
|
|
252
|
+
return { value, editing: current.editing, error: current.error, ...handlers };
|
|
253
|
+
}
|
|
212
254
|
// The state before the component subscribes: a subscription reports it at once.
|
|
213
255
|
function currentBridgeConnection(options) {
|
|
214
256
|
let current = "connecting";
|
package/dist/menu-bar.js
CHANGED
|
@@ -38,7 +38,7 @@ function createMenuBarStore(shortcuts) {
|
|
|
38
38
|
},
|
|
39
39
|
invoke: item => controller
|
|
40
40
|
? controller.invoke(item)
|
|
41
|
-
: Promise.reject(new BridgeError("disconnected", "The menu bar is not connected yet.", { route: "
|
|
41
|
+
: Promise.reject(new BridgeError("disconnected", "The menu bar is not connected yet.", { route: "runic.menu-bar" })),
|
|
42
42
|
handleKeyDown: event => controller?.handleKeyDown(event) ?? false,
|
|
43
43
|
};
|
|
44
44
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@runic-artifex/react",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.0",
|
|
4
4
|
"description": "React hooks for generated Runic Views clients",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -30,13 +30,15 @@
|
|
|
30
30
|
},
|
|
31
31
|
"peerDependencies": {
|
|
32
32
|
"react": ">=18.3.0 <20",
|
|
33
|
-
"@runic-artifex/views": "0.
|
|
33
|
+
"@runic-artifex/views": "0.13.0"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
|
-
"@runic-artifex/views": "0.
|
|
36
|
+
"@runic-artifex/views": "0.13.0",
|
|
37
37
|
"@types/react": "19.3.0",
|
|
38
38
|
"@types/react-dom": "19.3.0",
|
|
39
|
+
"esbuild": "0.28.2",
|
|
39
40
|
"happy-dom": "21.0.4",
|
|
41
|
+
"playwright-core": "1.63.0",
|
|
40
42
|
"react": "19.3.0",
|
|
41
43
|
"react-dom": "19.3.0",
|
|
42
44
|
"typescript": "6.0.3",
|
|
@@ -51,7 +53,7 @@
|
|
|
51
53
|
"url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
|
|
52
54
|
"directory": "packages/web/react"
|
|
53
55
|
},
|
|
54
|
-
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
56
|
+
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/react#readme",
|
|
55
57
|
"bugs": {
|
|
56
58
|
"url": "https://github.com/Runic-Artifex/runic-sdk/issues"
|
|
57
59
|
},
|
|
@@ -61,5 +63,5 @@
|
|
|
61
63
|
"views",
|
|
62
64
|
"react"
|
|
63
65
|
],
|
|
64
|
-
"gitHead": "
|
|
66
|
+
"gitHead": "3331f81c7a2de34e209b53eb07515323d6d15cf3"
|
|
65
67
|
}
|