@runic-artifex/vue 0.14.0 → 0.15.1

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
@@ -50,6 +50,9 @@ connected:
50
50
  "Connecting…" and do not open the route again. `keepAlive: 0` disposes at
51
51
  once.
52
52
  - An already connected client is observed and left to its owner.
53
+ - Each member is its own ref: `client` stays the same object for the
54
+ connection, so a `watch` or `watchEffect` that reads only `client` does not
55
+ run again when the View's state changes.
53
56
  - The source can be a value, a ref or a getter such as `() => props.page`.
54
57
  - `pending` is true while a reference connects. `error` holds a failed
55
58
  connection; `retry()` connects again.
@@ -181,8 +184,9 @@ is written. A string set on `value` of a field that is not text is taken as its
181
184
 
182
185
  - `commit: "pause"` writes the draft after `delay` milliseconds without input (700 by default) and at once on
183
186
  `commit()`, which blur calls; use it where each write is an undo step or starts work in .NET. The default,
184
- `commit: "input"`, writes each input. `commit()` resolves once the field's writes settled, so a command that
185
- depends on the field can follow them: `await title.commit(); await editor.save()`.
187
+ `commit: "input"`, writes each input. `commit()` resolves with the field's state once its writes settled, so a
188
+ command that depends on the field can follow them and skip a failed write:
189
+ `if ((await title.commit()).error === undefined) await editor.save()`.
186
190
  - `checked: true` writes with the member's checked write, so a change by another writer while the user edits is a
187
191
  conflict instead of being overwritten. A `rejected` receipt keeps the draft and sets `error` to a `FieldError` with
188
192
  the setter's message; a `conflict` keeps the draft, sets `conflict` to the producer's `{ value, version }` and
@@ -192,13 +196,13 @@ is written. A string set on `value` of a field that is not text is taken as its
192
196
  `errors` holds the member's validation messages from the descriptor (`[]` when valid), `error` why the latest write
193
197
  or text failed (a `BridgeError` or a `FieldError`, whose `kind` is `rejected`, `conflict`, `committed-with-error` or
194
198
  `invalid-text`). `FieldError`, `FieldOptions`, `FieldState` and `BridgeField` are exported from this package. See the
195
- [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/views#fields) for the receipts
199
+ [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#fields) for the receipts
196
200
  and text forms.
197
201
 
198
202
  ### Text inputs: `useTextField(view, read, write, options?)`
199
203
 
200
204
  Binds a text input to a member through the framework-neutral
201
- [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/views#text-inputs)
205
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#text-inputs)
202
206
  while the effect scope is active. Each field is a ref, so the handle can be destructured:
203
207
 
204
208
  ```vue
@@ -300,7 +304,7 @@ neither.
300
304
  ## `useOperation(start, options?)`
301
305
 
302
306
  Observes a generated `start<Command>()` operation through the framework-neutral
303
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/views#operation-feedback-and-latest-selection)
307
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#operation-feedback-and-latest-selection)
304
308
  and returns each state field as a shallow ref, with `run`, `cancel` and `reset`:
305
309
 
306
310
  ```vue
@@ -332,7 +336,7 @@ Disposing the effect scope settles run promises without cancelling accepted work
332
336
 
333
337
  Admits only the newest of several reads, for example loading the item the user
334
338
  selected last, through the framework-neutral
335
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/views#operation-feedback-and-latest-selection),
339
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#operation-feedback-and-latest-selection),
336
340
  and returns each state field as a shallow ref, with `run` and `clear`. Each
337
341
  `run(intent)` replaces the queued intent and cancels the active read; the next read
338
342
  starts only after the previous one reaches its terminal status and the intent's
@@ -367,9 +371,9 @@ accepted work.
367
371
  Follows the page's connection to its .NET host. It wraps `onBridgeConnection`
368
372
  from `@runic-artifex/views` (re-exported here since 0.11, with the
369
373
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a shallow ref holding a
370
- `BridgeConnectionState`: `connecting`, `connected`, `reconnecting` or `lost` (a
371
- closed set, see
372
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/views#connection-state)):
374
+ `BridgeConnectionState`: `connecting`, `connected`, `reconnecting`, `lost` or `closed` (the
375
+ application closed the window, since 0.15; a closed set, see
376
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#connection-state)):
373
377
 
374
378
  ```vue
375
379
  <script setup lang="ts">
@@ -392,7 +396,7 @@ development builds warn. An invalid `lostAfter` throws a `RangeError`.
392
396
  Follows the declared menu bar of a Runic Desktop window that leaves it to the
393
397
  page (`DesktopMenuBarPresentation.Page`) until the current effect scope is
394
398
  disposed. It wraps `createMenuBarController` from `@runic-artifex/views` (see
395
- [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a shallow ref
399
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a shallow ref
396
400
  of a `MenuBarState`, and the bar is rendered by the menubar component of the
397
401
  application's own UI library. Runic ships no menubar component.
398
402
 
@@ -423,7 +427,7 @@ rendering creates no controller: `state` stays `connecting`.
423
427
  ### With Reka UI
424
428
 
425
429
  Reka UI's `MenubarRoot` with `v-model` of the open menu; the
426
- [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
430
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
427
431
  items and is tested with real keys:
428
432
 
429
433
  ```vue
@@ -485,7 +489,7 @@ const message = computed(() => describeBridgeError(error.value));
485
489
  ```
486
490
 
487
491
  `instanceof` holds for errors from every copy of the package on the page.
488
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/views#errors-and-diagnostics)
492
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#errors-and-diagnostics)
489
493
  lists the kinds. Any other value, such as an exception that your own connect
490
494
  function or command callback throws, arrives unchanged.
491
495
 
@@ -532,15 +536,15 @@ application's own dialog.
532
536
  departure before that is answered by the ViewModel's .NET fallback handler, or
533
537
  fails closed without one.
534
538
 
535
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.14.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
539
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
536
540
  has the .NET side and which View answers which departure. In a frontend test,
537
541
  the generated mock's `interactions.<name>.request(input)` resolves with the
538
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/views#testing).
542
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#testing).
539
543
 
540
544
  ## `useCollectionViewport(options)`
541
545
 
542
546
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
543
- `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/views#collectionviewportoptions)
547
+ `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#collectionviewportoptions)
544
548
  range; `attach` is a function ref for the container. Bind it to a native element
545
549
  such as a `<div>`: a component instance (`:ref="attach"` on a component) or a
546
550
  non-HTML element detaches the viewport, and development builds warn. Pass a getter for the
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { type Component, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from "vue";
2
- import { type BridgeConnectionOptions, type BridgeConnectionState, type BridgeField, type BridgeOperation, type BridgeOutcomeFailure, type FieldBaseline, type FieldDefinition, type FieldOptions, type LatestOperationController, type LatestOperationState, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type ViewClient, type ViewConnector, type ViewSource } from "@runic-artifex/views";
2
+ import { type BridgeConnectionOptions, type BridgeConnectionState, type BridgeField, type BridgeOperation, type BridgeOutcomeFailure, type FieldBaseline, type FieldDefinition, type FieldState, type FieldOptions, type LatestOperationController, type LatestOperationState, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type ViewClient, type ViewConnector, 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. */
5
5
  readonly state: Readonly<Ref<TClient["snapshot"] | undefined>>;
@@ -260,10 +260,11 @@ export interface FieldHandle<TValue> {
260
260
  input(value: TValue): void;
261
261
  /**
262
262
  * The user is done with the field (`@blur="title.commit"`): with `commit: "pause"` the draft is written now.
263
- * Resolves once the field's writes settled, so a command that depends on the field can run after it:
264
- * `await title.commit(); await editor.save()`. Never rejects; a failure is `error`.
263
+ * Resolves with the field's state once its writes settled, so a command that depends on the field can run after it
264
+ * and skip a failed write: `if ((await title.commit()).error === undefined) await editor.save()`. Never rejects; a
265
+ * failure is `error`.
265
266
  */
266
- commit(): Promise<void>;
267
+ commit(): Promise<FieldState<TValue>>;
267
268
  /** Writes the draft again after a failed write; after a `conflict`, over the producer's value. */
268
269
  retry(): void;
269
270
  /** Drops the draft, the error and a conflict and shows the View's value. Writes in flight still complete. */
@@ -294,8 +295,8 @@ export interface BridgeConnectionHandle {
294
295
  readonly state: Readonly<Ref<BridgeConnectionState>>;
295
296
  }
296
297
  /**
297
- * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`
298
- * or `lost`) as a shallow ref through `onBridgeConnection`, until the current effect scope is
298
+ * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`,
299
+ * `lost` or `closed`) as a shallow ref through `onBridgeConnection`, until the current effect scope is
299
300
  * disposed. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never
300
301
  * released (development builds warn).
301
302
  *
package/dist/index.js CHANGED
@@ -260,14 +260,14 @@ export function useField(view, field, options = {}) {
260
260
  errors: computed(() => current.value.errors),
261
261
  conflict: computed(() => current.value.conflict),
262
262
  input: (value) => controller.input(value),
263
- commit: async () => { await controller.commit(); },
263
+ commit: () => controller.commit(),
264
264
  retry: () => controller.retry(),
265
265
  reset: () => controller.reset(),
266
266
  });
267
267
  }
268
268
  /**
269
- * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`
270
- * or `lost`) as a shallow ref through `onBridgeConnection`, until the current effect scope is
269
+ * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`,
270
+ * `lost` or `closed`) as a shallow ref through `onBridgeConnection`, until the current effect scope is
271
271
  * disposed. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never
272
272
  * released (development builds warn).
273
273
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/vue",
3
- "version": "0.14.0",
3
+ "version": "0.15.1",
4
4
  "description": "Vue composables for generated Runic Views clients",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -30,10 +30,10 @@
30
30
  },
31
31
  "peerDependencies": {
32
32
  "vue": ">=3.5.30 <4",
33
- "@runic-artifex/views": "0.14.0"
33
+ "@runic-artifex/views": "0.15.1"
34
34
  },
35
35
  "devDependencies": {
36
- "@runic-artifex/views": "0.14.0",
36
+ "@runic-artifex/views": "0.15.1",
37
37
  "esbuild": "0.28.2",
38
38
  "happy-dom": "21.0.4",
39
39
  "playwright-core": "1.63.0",
@@ -50,7 +50,7 @@
50
50
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
51
51
  "directory": "packages/web/vue"
52
52
  },
53
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.14.0/packages/web/vue#readme",
53
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/vue#readme",
54
54
  "bugs": {
55
55
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
56
56
  },
@@ -60,5 +60,5 @@
60
60
  "views",
61
61
  "vue"
62
62
  ],
63
- "gitHead": "11dc038ea80315c4d2b7e15cbd03dfe175ed6124"
63
+ "gitHead": "fce42f47296a4784532fbba0fec9602cd3778fbb"
64
64
  }