@runic-artifex/vue 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 +53 -10
- package/dist/index.d.ts +49 -1
- package/dist/index.js +34 -2
- package/dist/menu-bar.js +1 -1
- package/package.json +8 -6
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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: "
|
|
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,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@runic-artifex/vue",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.0",
|
|
4
4
|
"description": "Vue composables for generated Runic Views clients",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
|
-
"packageManager": "bun@1.4.
|
|
7
|
+
"packageManager": "bun@1.4.4",
|
|
8
8
|
"sideEffects": false,
|
|
9
9
|
"files": [
|
|
10
10
|
"dist",
|
|
@@ -30,11 +30,13 @@
|
|
|
30
30
|
},
|
|
31
31
|
"peerDependencies": {
|
|
32
32
|
"vue": ">=3.5.30 <4",
|
|
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
|
+
"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.
|
|
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": "
|
|
63
|
+
"gitHead": "3331f81c7a2de34e209b53eb07515323d6d15cf3"
|
|
62
64
|
}
|