@runic-artifex/vue 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 CHANGED
@@ -85,6 +85,46 @@ const step = computed({ get: () => state.value?.step ?? 1, set: value => void se
85
85
  </template>
86
86
  ```
87
87
 
88
+ ### Text inputs: `useTextField(view, read, write, options?)`
89
+
90
+ Binds a text input to a member through the framework-neutral
91
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#text-inputs)
92
+ while the effect scope is active. Each field is a ref, so the handle can be destructured:
93
+
94
+ ```vue
95
+ <script setup lang="ts">
96
+ import { useTextField, useView } from "@runic-artifex/vue";
97
+ import type { PersonPageReference } from "./generated/person.js";
98
+
99
+ const props = defineProps<{ page: PersonPageReference }>();
100
+ const person = useView(() => props.page);
101
+ const { value: name, error } = useTextField(person, state => state.name, (client, value) => client.setName(value));
102
+ </script>
103
+
104
+ <template>
105
+ <input v-model="name">
106
+ <p v-if="error !== undefined" role="alert">{{ String(error) }}</p>
107
+ </template>
108
+ ```
109
+
110
+ It returns `value`, a writable computed for `v-model`, the `editing` and `error`
111
+ refs and `reset()`. `v-model` already writes nothing during IME composition. `view`
112
+ is a `useView` handle or any `{ state, client }` refs. The options are `coalesce` and
113
+ `keepDraftOnError`.
114
+ The field shows what the user typed while its writes are in flight, so a reply or
115
+ frame that answers an older keystroke never replaces newer text. At most one write is
116
+ in flight; text typed meanwhile is written next as one value (`coalesce: false` writes
117
+ every change). Nothing is written during IME composition. Once the last write settled,
118
+ the field shows the View's value again, including any normalization the ViewModel
119
+ applied (trimmed, upper-cased). `write` may also be a command or a checked write. A
120
+ failed write keeps the draft and sets `error` (`keepDraftOnError: false` shows the
121
+ View's value instead); `reset()` drops the draft. `editing` is true while a draft
122
+ exists. Don't disable the input on the View's busy state (`isSaving`, `can…`) while
123
+ the user types: the field's own write causes it, and keys typed meanwhile would be
124
+ lost. Test such fields by typing key by key (Playwright `pressSequentially`, Testing
125
+ Library `user.type`) against the mock with `latency: "slow"`; `fill()` sets the whole
126
+ text at once and hides the race.
127
+
88
128
  ## `ViewOutlet`
89
129
 
90
130
  Renders the component registered for a generated reference's `kind` and
@@ -148,7 +188,7 @@ neither.
148
188
  ## `useOperation(start, options?)`
149
189
 
150
190
  Observes a generated `start<Command>()` operation through the framework-neutral
151
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#operation-feedback-and-latest-selection)
191
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#operation-feedback-and-latest-selection)
152
192
  and returns each state field as a shallow ref, with `run`, `cancel` and `reset`:
153
193
 
154
194
  ```vue
@@ -165,19 +205,22 @@ const { run: push, cancel, pending, cancellationRequested, cancelled, error } =
165
205
  </template>
166
206
  ```
167
207
 
168
- The result has `pending`, `admitting`, `operation`, `status`, `outcome`, `failure`,
208
+ The result has `pending`, `admitting`, `operation`, `status`, `progress`, `outcome`, `failure`,
169
209
  `error`, `cancelled`, `cancellationRequested`, `cancelling`, `cancellation` and
170
210
  `cancelError`, with `run(...args)`, `cancel()` and `reset()`, which never reject. A
171
211
  run that ends with a `cancelled` status sets `cancelled` and resolves to `undefined`
172
212
  without an `error`; `failed` and `timed-out` statuses are still `error`. `pending`
173
213
  stays true after a Cancel response until the operation reaches its terminal status.
214
+ `progress` is how far the running operation got, from 0 to 1, when its command
215
+ reports progress (`RunicOperationProgress.Report` in .NET), for example
216
+ `<progress :value="progress">`; it is `undefined` while unknown and after the run.
174
217
  Disposing the effect scope settles run promises without cancelling accepted work.
175
218
 
176
219
  ## `useLatestOperation()`
177
220
 
178
221
  Admits only the newest of several reads, for example loading the item the user
179
222
  selected last, through the framework-neutral
180
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#operation-feedback-and-latest-selection),
223
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#operation-feedback-and-latest-selection),
181
224
  and returns each state field as a shallow ref, with `run` and `clear`. Each
182
225
  `run(intent)` replaces the queued intent and cancels the active read; the next read
183
226
  starts only after the previous one reaches its terminal status and the intent's
@@ -214,7 +257,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
214
257
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a shallow ref holding a
215
258
  `BridgeConnectionState`: `connecting`, `connected`, `reconnecting` or `lost` (a
216
259
  closed set, see
217
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#connection-state)):
260
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#connection-state)):
218
261
 
219
262
  ```vue
220
263
  <script setup lang="ts">
@@ -237,7 +280,7 @@ development builds warn. An invalid `lostAfter` throws a `RangeError`.
237
280
  Follows the declared menu bar of a Runic Desktop window that leaves it to the
238
281
  page (`DesktopMenuBarPresentation.Page`) until the current effect scope is
239
282
  disposed. It wraps `createMenuBarController` from `@runic-artifex/views` (see
240
- [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a shallow ref
283
+ [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 shallow ref
241
284
  of a `MenuBarState`, and the bar is rendered by the menubar component of the
242
285
  application's own UI library. Runic ships no menubar component.
243
286
 
@@ -268,7 +311,7 @@ rendering creates no controller: `state` stays `connecting`.
268
311
  ### With Reka UI
269
312
 
270
313
  Reka UI's `MenubarRoot` with `v-model` of the open menu; the
271
- [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
314
+ [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
272
315
  items and is tested with real keys:
273
316
 
274
317
  ```vue
@@ -327,7 +370,7 @@ const offline = error.value instanceof BridgeError && error.value.kind === "disc
327
370
  ```
328
371
 
329
372
  `instanceof` holds for errors from every copy of the package on the page.
330
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#errors-and-diagnostics)
373
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#errors-and-diagnostics)
331
374
  lists the kinds. Any other value, such as an exception that your own connect
332
375
  function or command callback throws, arrives unchanged.
333
376
 
@@ -374,15 +417,15 @@ application's own dialog.
374
417
  departure before that is answered by the ViewModel's .NET fallback handler, or
375
418
  fails closed without one.
376
419
 
377
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.12.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
420
+ 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)
378
421
  has the .NET side and which View answers which departure. In a frontend test,
379
422
  the generated mock's `interactions.<name>.request(input)` resolves with the
380
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#testing).
423
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#testing).
381
424
 
382
425
  ## `useCollectionViewport(options)`
383
426
 
384
427
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
385
- `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#collectionviewportoptions)
428
+ `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#collectionviewportoptions)
386
429
  range; `attach` is a function ref for the container. Bind it to a native element
387
430
  such as a `<div>`: a component instance (`:ref="attach"` on a component) or a
388
431
  non-HTML element detaches the viewport, and development builds warn. Pass a getter for the
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { type Component, type MaybeRefOrGetter, type Ref } from "vue";
1
+ import { type Component, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from "vue";
2
2
  import { type BridgeConnectionOptions, type BridgeConnectionState, type BridgeOperation, type BridgeOutcomeFailure, type LatestOperationController, type LatestOperationState, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type ViewClient, type ViewSource } from "@runic-artifex/views";
3
3
  export interface ViewHandle<TClient extends ViewClient> {
4
4
  /** The latest state, or undefined until the client connects. */
@@ -147,6 +147,54 @@ export type LatestOperationHandle<TResult, TFailure = never> = {
147
147
  * ```
148
148
  */
149
149
  export declare function useLatestOperation<TResult = void, TFailure = never>(): LatestOperationHandle<TResult, TFailure>;
150
+ export interface TextFieldHandle {
151
+ /**
152
+ * What the input shows: the draft while one exists, otherwise the member's value in the View's state. Setting it
153
+ * is an input by the user, as `v-model` does; `v-model` also writes nothing during IME composition.
154
+ */
155
+ readonly value: WritableComputedRef<string>;
156
+ /**
157
+ * True while a draft exists, from the first input until the last write settled and the state caught up, and after a
158
+ * failed write. Keep the input enabled while it is true, rather than disabling it on the View's busy state, which
159
+ * the field's own write causes.
160
+ */
161
+ readonly editing: Readonly<Ref<boolean>>;
162
+ /** Why the latest write failed, until the next input or `reset()`. */
163
+ readonly error: Readonly<Ref<unknown>>;
164
+ /** Drops the draft and the error and shows the View's value. Writes in flight still complete. */
165
+ reset(): void;
166
+ }
167
+ export interface UseTextFieldOptions {
168
+ /**
169
+ * With `true` (the default) at most one write is in flight, and text typed meanwhile is written next, as one
170
+ * value. With `false` every input is written.
171
+ */
172
+ readonly coalesce?: boolean;
173
+ /** With `true` (the default) a failed write keeps the draft and sets `error`; with `false` the field shows the View's value again. */
174
+ readonly keepDraftOnError?: boolean;
175
+ }
176
+ /** The View a text field binds to: a {@link useView} handle, or any state and client refs. */
177
+ export interface TextFieldView<TClient extends ViewClient> {
178
+ readonly state: Readonly<Ref<TClient["snapshot"] | undefined>>;
179
+ readonly client: Readonly<Ref<TClient | undefined>>;
180
+ }
181
+ /**
182
+ * Binds a text input to one member of a View while the current effect scope is active, through
183
+ * `createTextFieldController`. Typing key by key never loses characters: while its writes are in flight the field
184
+ * shows what the user typed, at most one write is in flight (newer text is written next), and once the last write
185
+ * settled it shows the View's value, including any normalization. Each field is a ref, so the handle can be
186
+ * destructured. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never released
187
+ * (development builds warn).
188
+ *
189
+ * ```vue
190
+ * const person = useView(() => props.page);
191
+ * const { value: name, editing } = useTextField(person, state => state.name, (client, value) => client.setName(value));
192
+ * <input v-model="name">
193
+ * ```
194
+ *
195
+ * `write` may be a generated setter, a command or a checked write. Its failure sets `error` and keeps the draft.
196
+ */
197
+ 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;
150
198
  export interface BridgeConnectionHandle {
151
199
  /** The connection to the .NET host, as `onBridgeConnection` reports it. */
152
200
  readonly state: Readonly<Ref<BridgeConnectionState>>;
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { defineComponent, h, shallowRef, toValue, watch, } from "vue";
2
- import { createCommandController, createLatestOperationController, createOperationController, createViewController, onBridgeConnection, } from "@runic-artifex/views";
1
+ import { computed, defineComponent, h, shallowRef, toValue, watch, } from "vue";
2
+ import { createCommandController, createLatestOperationController, createOperationController, createTextFieldController, createViewController, onBridgeConnection, } from "@runic-artifex/views";
3
3
  import { viewSourceIdentity } from "@runic-artifex/views/bindings";
4
4
  import { releaseWithScope } from "./scope.js";
5
5
  export function useView(source, options = {}) {
@@ -138,6 +138,38 @@ export function useLatestOperation() {
138
138
  releaseWithScope("useLatestOperation", () => controller.dispose());
139
139
  return { ...refs, run: controller.run, clear: controller.clear };
140
140
  }
141
+ /**
142
+ * Binds a text input to one member of a View while the current effect scope is active, through
143
+ * `createTextFieldController`. Typing key by key never loses characters: while its writes are in flight the field
144
+ * shows what the user typed, at most one write is in flight (newer text is written next), and once the last write
145
+ * settled it shows the View's value, including any normalization. Each field is a ref, so the handle can be
146
+ * destructured. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never released
147
+ * (development builds warn).
148
+ *
149
+ * ```vue
150
+ * const person = useView(() => props.page);
151
+ * const { value: name, editing } = useTextField(person, state => state.name, (client, value) => client.setName(value));
152
+ * <input v-model="name">
153
+ * ```
154
+ *
155
+ * `write` may be a generated setter, a command or a checked write. Its failure sets `error` and keeps the draft.
156
+ */
157
+ export function useTextField(view, read, write, options = {}) {
158
+ const controller = createTextFieldController({ read, write, ...options });
159
+ const current = shallowRef(controller.current);
160
+ controller.subscribe(() => { current.value = controller.current; });
161
+ watch([view.state, view.client], ([state, client]) => {
162
+ controller.setSource(state === undefined || client === undefined ? undefined : { state, client });
163
+ current.value = controller.current;
164
+ }, { immediate: true });
165
+ releaseWithScope("useTextField", () => controller.dispose());
166
+ return {
167
+ value: computed({ get: () => current.value.value, set: text => controller.input(text) }),
168
+ editing: computed(() => current.value.editing),
169
+ error: computed(() => current.value.error),
170
+ reset: () => controller.reset(),
171
+ };
172
+ }
141
173
  /**
142
174
  * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`
143
175
  * or `lost`) as a shallow ref through `onBridgeConnection`, until the current effect scope is
package/dist/menu-bar.js CHANGED
@@ -23,7 +23,7 @@ export function useMenuBar(options = {}) {
23
23
  }));
24
24
  return {
25
25
  state,
26
- invoke: () => Promise.reject(new BridgeError("unavailable", "The menu bar is not followed during server rendering.", { route: "__runicMenuBarInvoke" })),
26
+ invoke: () => Promise.reject(new BridgeError("unavailable", "The menu bar is not followed during server rendering.", { route: "runic.menu-bar" })),
27
27
  handleKeyDown: () => false,
28
28
  };
29
29
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/vue",
3
- "version": "0.12.1",
3
+ "version": "0.13.0",
4
4
  "description": "Vue composables for generated Runic Views clients",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -30,11 +30,13 @@
30
30
  },
31
31
  "peerDependencies": {
32
32
  "vue": ">=3.5.30 <4",
33
- "@runic-artifex/views": "0.12.1"
33
+ "@runic-artifex/views": "0.13.0"
34
34
  },
35
35
  "devDependencies": {
36
- "@runic-artifex/views": "0.12.1",
36
+ "@runic-artifex/views": "0.13.0",
37
+ "esbuild": "0.28.2",
37
38
  "happy-dom": "21.0.4",
39
+ "playwright-core": "1.63.0",
38
40
  "typescript": "6.0.3",
39
41
  "vitest": "5.0.3",
40
42
  "vue": "3.5.43"
@@ -48,7 +50,7 @@
48
50
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
49
51
  "directory": "packages/web/vue"
50
52
  },
51
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/vue#readme",
53
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/vue#readme",
52
54
  "bugs": {
53
55
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
54
56
  },
@@ -58,5 +60,5 @@
58
60
  "views",
59
61
  "vue"
60
62
  ],
61
- "gitHead": "124a532e5861cff03e77d2ef0c5d4f081ee99a47"
63
+ "gitHead": "3331f81c7a2de34e209b53eb07515323d6d15cf3"
62
64
  }