@runic-artifex/vue 0.9.1 → 0.10.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
@@ -133,7 +133,7 @@ neither.
133
133
  ## `useOperation(start, options?)`
134
134
 
135
135
  Observes a generated `start<Command>()` operation through the framework-neutral
136
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#operation-feedback-and-latest-selection)
136
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#operation-feedback-and-latest-selection)
137
137
  and returns each state field as a shallow ref, with `run`, `cancel` and `reset`:
138
138
 
139
139
  ```vue
@@ -158,6 +158,40 @@ without an `error`; `failed` and `timed-out` statuses are still `error`. `pendin
158
158
  stays true after a Cancel response until the operation reaches its terminal status.
159
159
  Disposing the effect scope settles run promises without cancelling accepted work.
160
160
 
161
+ ## `useLatestOperation()`
162
+
163
+ Admits only the newest of several reads, for example loading the item the user
164
+ selected last, through the framework-neutral
165
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#operation-feedback-and-latest-selection),
166
+ and returns each state field as a shallow ref, with `run` and `clear`. Each
167
+ `run(intent)` replaces the queued intent and cancels the active read; the next read
168
+ starts only after the previous one reaches its terminal status and the intent's
169
+ optional `waitForCompletion` barrier:
170
+
171
+ ```vue
172
+ <script setup lang="ts">
173
+ const { run: load, outcome, blocked } = useLatestOperation<Item>();
174
+ function select(id: string) {
175
+ const current = client.value;
176
+ if (current) void load({ start: () => current.startLoad(id), isCurrent: () => client.value === current });
177
+ }
178
+ </script>
179
+
180
+ <template>
181
+ <ItemView v-if="outcome?.ok" :item="outcome.value" />
182
+ <p v-if="blocked" role="alert">Reconnect before selecting again.</p>
183
+ </template>
184
+ ```
185
+
186
+ The result has the `useOperation` fields plus `blocked`, with `run(intent)` and
187
+ `clear(mode?)`, which never reject. The intent carries `start` and the optional
188
+ `cancel`, `waitForCompletion` and `isCurrent` callbacks, so it captures the client or
189
+ session it belongs to. `blocked` means admission is uncertain, for example after a
190
+ lost Start reply; only `clear("replace")`, called after the application has
191
+ established a fresh session, clears it. `clear()` drops the queued intent and cancels
192
+ the active read. Disposing the effect scope settles run promises without cancelling
193
+ accepted work.
194
+
161
195
  ## Errors
162
196
 
163
197
  The `error` of `useView` and of a command or operation handle is typed
@@ -172,7 +206,7 @@ const offline = error.value instanceof BridgeError && error.value.kind === "disc
172
206
  ```
173
207
 
174
208
  `instanceof` holds for errors from every copy of the package on the page.
175
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#errors-and-diagnostics)
209
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#errors-and-diagnostics)
176
210
  lists the kinds. Any other value, such as an exception that your own connect
177
211
  function or command callback throws, arrives unchanged.
178
212
 
@@ -219,18 +253,15 @@ application's own dialog.
219
253
  departure before that is answered by the ViewModel's .NET fallback handler, or
220
254
  fails closed without one.
221
255
 
222
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.9.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
256
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.10.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
223
257
  has the .NET side and which View answers which departure. In a frontend test,
224
258
  the generated mock's `interactions.<name>.request(input)` resolves with the
225
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#testing).
226
-
227
- ## `useCollectionViewport(options)` (experimental)
259
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#testing).
228
260
 
229
- Exported from `@runic-artifex/vue/experimental`, like the
230
- `@runic-artifex/views/experimental` controller it wraps.
261
+ ## `useCollectionViewport(options)`
231
262
 
232
263
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
233
- `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#collectionviewportoptions-experimental)
264
+ `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#collectionviewportoptions)
234
265
  range; `attach` is a function ref for the container. Bind it to a native element
235
266
  such as a `<div>`: a component instance (`:ref="attach"` on a component) or a
236
267
  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 } from "vue";
2
- import { type BridgeOperation, type BridgeOutcomeFailure, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type ViewClient, type ViewSource } from "@runic-artifex/views";
2
+ import { 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. */
5
5
  readonly state: Readonly<Ref<TClient["snapshot"] | undefined>>;
@@ -119,3 +119,25 @@ export type OperationHandle<TArgs extends readonly unknown[], TResult, TFailure
119
119
  * ```
120
120
  */
121
121
  export declare function useOperation<TArgs extends readonly unknown[], TResult, TFailure = never>(start: (...args: TArgs) => BridgeOperation<TResult, TFailure> | undefined | PromiseLike<BridgeOperation<TResult, TFailure> | undefined>, options?: OperationControllerOptions<TResult, TFailure>): OperationHandle<TArgs, TResult, TFailure>;
122
+ /** Each {@link LatestOperationState} field as a shallow ref, with the controller's `run` and `clear`. */
123
+ export type LatestOperationHandle<TResult, TFailure = never> = {
124
+ readonly [K in keyof LatestOperationState<TResult, TFailure>]-?: Readonly<Ref<LatestOperationState<TResult, TFailure>[K]>>;
125
+ } & Pick<LatestOperationController<TResult, TFailure>, "run" | "clear">;
126
+ /**
127
+ * Admits only the newest selection, for reads such as "load the selected item": each
128
+ * `run(intent)` replaces the queued intent and cancels the active read, and the next read
129
+ * starts only after the previous one has finished (including `waitForCompletion`). Each
130
+ * state field is a shallow ref, so the handle can be destructured. `blocked` means
131
+ * admission is uncertain; only `clear("replace")`, after the application has established a
132
+ * fresh session, clears it. Scope disposal settles run promises without cancelling accepted
133
+ * work. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never
134
+ * released (development builds warn).
135
+ *
136
+ * ```vue
137
+ * const load = useLatestOperation<Item>();
138
+ * <li @click="load.run({ start: () => client.value?.startLoad(id) })">…</li>
139
+ * <ItemView v-if="load.outcome.value?.ok" :item="load.outcome.value.value" />
140
+ * ```
141
+ */
142
+ export declare function useLatestOperation<TResult = void, TFailure = never>(): LatestOperationHandle<TResult, TFailure>;
143
+ export { useCollectionViewport, type CollectionViewportHandle } from "./viewport.js";
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { defineComponent, h, shallowRef, toValue, watch, } from "vue";
2
- import { createCommandController, createOperationController, createViewController, } from "@runic-artifex/views";
2
+ import { createCommandController, createLatestOperationController, createOperationController, createViewController, } 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 = {}) {
@@ -98,3 +98,34 @@ export function useOperation(start, options = {}) {
98
98
  releaseWithScope("useOperation", () => controller.dispose());
99
99
  return { ...refs, run: controller.run, cancel: controller.cancel, reset: controller.reset };
100
100
  }
101
+ /**
102
+ * Admits only the newest selection, for reads such as "load the selected item": each
103
+ * `run(intent)` replaces the queued intent and cancels the active read, and the next read
104
+ * starts only after the previous one has finished (including `waitForCompletion`). Each
105
+ * state field is a shallow ref, so the handle can be destructured. `blocked` means
106
+ * admission is uncertain; only `clear("replace")`, after the application has established a
107
+ * fresh session, clears it. Scope disposal settles run promises without cancelling accepted
108
+ * work. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never
109
+ * released (development builds warn).
110
+ *
111
+ * ```vue
112
+ * const load = useLatestOperation<Item>();
113
+ * <li @click="load.run({ start: () => client.value?.startLoad(id) })">…</li>
114
+ * <ItemView v-if="load.outcome.value?.ok" :item="load.outcome.value.value" />
115
+ * ```
116
+ */
117
+ export function useLatestOperation() {
118
+ const controller = createLatestOperationController();
119
+ const refs = {};
120
+ const keys = Object.keys(controller.current);
121
+ for (const key of keys)
122
+ refs[key] = shallowRef(controller.current[key]);
123
+ controller.subscribe(() => {
124
+ const current = controller.current;
125
+ for (const key of keys)
126
+ refs[key].value = current[key];
127
+ });
128
+ releaseWithScope("useLatestOperation", () => controller.dispose());
129
+ return { ...refs, run: controller.run, clear: controller.clear };
130
+ }
131
+ export { useCollectionViewport } from "./viewport.js";
@@ -1,5 +1,5 @@
1
1
  import { type ComponentPublicInstance, type MaybeRefOrGetter, type Ref } from "vue";
2
- import { type CollectionViewport, type CollectionViewportOptions } from "@runic-artifex/views/experimental";
2
+ import { type CollectionViewport, type CollectionViewportOptions } from "@runic-artifex/views";
3
3
  export interface CollectionViewportHandle {
4
4
  /** The rows to request and the sizes to render. */
5
5
  readonly viewport: Readonly<Ref<CollectionViewport>>;
package/dist/viewport.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { shallowRef, toValue, watch } from "vue";
2
- import { createCollectionViewportController, } from "@runic-artifex/views/experimental";
2
+ import { createCollectionViewportController, } from "@runic-artifex/views";
3
3
  import { releaseWithScope } from "./scope.js";
4
4
  /**
5
5
  * Follows a fixed-row-height scroll container and returns the rows to request
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/vue",
3
- "version": "0.9.1",
3
+ "version": "0.10.0",
4
4
  "description": "Vue composables for generated Runic Views clients",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -19,11 +19,6 @@
19
19
  "import": "./dist/index.js",
20
20
  "default": "./dist/index.js"
21
21
  },
22
- "./experimental": {
23
- "types": "./dist/experimental.d.ts",
24
- "import": "./dist/experimental.js",
25
- "default": "./dist/experimental.js"
26
- },
27
22
  "./package.json": "./package.json"
28
23
  },
29
24
  "scripts": {
@@ -35,10 +30,10 @@
35
30
  },
36
31
  "peerDependencies": {
37
32
  "vue": ">=3.5.30 <4",
38
- "@runic-artifex/views": "0.9.1"
33
+ "@runic-artifex/views": "0.10.0"
39
34
  },
40
35
  "devDependencies": {
41
- "@runic-artifex/views": "0.9.1",
36
+ "@runic-artifex/views": "0.10.0",
42
37
  "happy-dom": "20.14.5",
43
38
  "typescript": "6.0.3",
44
39
  "vitest": "5.0.3",
@@ -53,7 +48,7 @@
53
48
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
54
49
  "directory": "packages/web/vue"
55
50
  },
56
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/vue#readme",
51
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/vue#readme",
57
52
  "bugs": {
58
53
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
59
54
  },
@@ -63,5 +58,5 @@
63
58
  "views",
64
59
  "vue"
65
60
  ],
66
- "gitHead": "7df2f00a9800c180e266ca545d4d6a03bf78dc89"
61
+ "gitHead": "fcc71ba13aa56c8f1a720909c1074825a1f5dd6f"
67
62
  }
@@ -1 +0,0 @@
1
- export { useCollectionViewport, type CollectionViewportHandle } from "./viewport.js";
@@ -1,3 +0,0 @@
1
- // `@runic-artifex/vue/experimental`: composables whose shape may still change in a minor release
2
- // (docs/experimental.md). Graduation moves an export to `@runic-artifex/vue`.
3
- export { useCollectionViewport } from "./viewport.js";