@runic-artifex/react 0.12.0 → 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 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.12.0/packages/web/views#operation-feedback-and-latest-selection).
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.12.0/packages/web/views#operation-feedback-and-latest-selection).
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.12.0/packages/web/views#connection-state)):
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.12.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a
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.12.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
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.12.0/packages/web/views#errors-and-diagnostics)
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.12.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
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.12.0/packages/web/views#testing).
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.12.0/packages/web/views#collectionviewportoptions)
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: "__runicMenuBarInvoke" })),
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,10 +1,10 @@
1
1
  {
2
2
  "name": "@runic-artifex/react",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "description": "React hooks for generated Runic Views clients",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
- "packageManager": "bun@1.4.2",
7
+ "packageManager": "bun@1.4.4",
8
8
  "sideEffects": false,
9
9
  "files": [
10
10
  "dist",
@@ -30,13 +30,15 @@
30
30
  },
31
31
  "peerDependencies": {
32
32
  "react": ">=18.3.0 <20",
33
- "@runic-artifex/views": "0.12.0"
33
+ "@runic-artifex/views": "0.13.0"
34
34
  },
35
35
  "devDependencies": {
36
- "@runic-artifex/views": "0.12.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.12.0/packages/web/react#readme",
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": "cb95ea2838ba61c7a24b9cda05bf5f0bd6fcc2d7"
66
+ "gitHead": "3331f81c7a2de34e209b53eb07515323d6d15cf3"
65
67
  }