@runic-artifex/angular 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
@@ -137,14 +137,14 @@ For example, a navigation command whose departure guard awaits a dialog's
137
137
  answer never completes while the answer waits behind it. Order such commands
138
138
  by dispatch instead: start the next one once the previous one has been sent,
139
139
  as the Notes example's
140
- [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/examples/notes-view-first/Angular/src/app/window-operations.ts)
140
+ [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/examples/notes-view-first/Angular/src/app/window-operations.ts)
141
141
  does for its navigation commands.
142
142
 
143
143
  ## Operations
144
144
 
145
145
  `injectOperation(start, options?)` observes a generated `start<Command>()` operation
146
146
  through the framework-neutral
147
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#operation-feedback-and-latest-selection)
147
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#operation-feedback-and-latest-selection)
148
148
  for the lifetime of the injection context:
149
149
 
150
150
  ```ts
@@ -166,6 +166,32 @@ accepted work. The options also take the controller's `cancel(operation)` and
166
166
  `waitForCompletion(operation, status)` callbacks, and `injector` outside an injection
167
167
  context.
168
168
 
169
+ `injectLatestOperation(options?)` admits only the newest of several reads, for example
170
+ loading the item the user selected last, through the framework-neutral
171
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#operation-feedback-and-latest-selection).
172
+ Each `run(intent)` replaces the queued intent and cancels the active read; the next
173
+ read starts only after the previous one reaches its terminal status and the intent's
174
+ optional `waitForCompletion` barrier:
175
+
176
+ ```ts
177
+ readonly load = injectLatestOperation<Item>();
178
+ select(id: string) {
179
+ const client = this.items.client();
180
+ if (client) void this.load.run({ start: () => client.startLoad(id), isCurrent: () => this.items.client() === client });
181
+ }
182
+ // @if (load.outcome()?.ok) { <item-view [item]="load.outcome()!.value" /> }
183
+ // @if (load.blocked()) { <p role="alert">Reconnect before selecting again.</p> }
184
+ ```
185
+
186
+ It returns the `injectOperation` signals 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. Destroying the injection context settles run promises without
193
+ cancelling accepted work. Pass `injector` outside an injection context.
194
+
169
195
  ## Errors
170
196
 
171
197
  The `error()` signal of `injectView` and of a command or operation is typed
@@ -181,7 +207,7 @@ const offline = error instanceof BridgeError && error.kind === "disconnected";
181
207
  ```
182
208
 
183
209
  `instanceof` holds for errors from every copy of the package on the page.
184
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#errors-and-diagnostics)
210
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#errors-and-diagnostics)
185
211
  lists the kinds. Any other value, such as an exception that your own connect
186
212
  function or command callback throws, arrives unchanged.
187
213
 
@@ -232,18 +258,16 @@ application's own dialog.
232
258
  departure before that is answered by the ViewModel's .NET fallback handler, or
233
259
  fails closed without one.
234
260
 
235
- 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)
261
+ 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)
236
262
  has the .NET side and which View answers which departure. In a frontend test,
237
263
  the generated mock's `interactions.<name>.request(input)` resolves with the
238
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#testing).
264
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#testing).
239
265
 
240
- ## Collection viewports (experimental)
266
+ ## Collection viewports
241
267
 
242
- `injectCollectionViewport(element, options)`, exported from
243
- `@runic-artifex/angular/experimental` like the `@runic-artifex/views/experimental`
244
- controller it wraps, follows a fixed-row-height scroll
268
+ `injectCollectionViewport(element, options)` follows a fixed-row-height scroll
245
269
  container and returns a signal with its
246
- [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#collectionviewportoptions-experimental)
270
+ [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#collectionviewportoptions)
247
271
  range. Pass the container as a signal, such as a `viewChild`, and the options as
248
272
  a function or signal, then send the range to the ViewModel from an effect:
249
273
 
@@ -2,3 +2,5 @@ export { ViewOutlet, RunicViewOutlet, type ViewRegistry } from "./view-outlet.js
2
2
  export { injectView, type InjectViewOptions, type ViewHandle } from "./inject-view.js";
3
3
  export { injectCommand, type CommandHandle, type InjectCommandOptions } from "./inject-command.js";
4
4
  export { injectOperation, type InjectOperationOptions, type OperationHandle } from "./inject-operation.js";
5
+ export { injectLatestOperation, type InjectLatestOperationOptions, type LatestOperationHandle, } from "./inject-latest-operation.js";
6
+ export { injectCollectionViewport, type InjectCollectionViewportOptions } from "./inject-collection-viewport.js";
package/dist/esm/index.js CHANGED
@@ -2,3 +2,5 @@ export { ViewOutlet, RunicViewOutlet } from "./view-outlet.js";
2
2
  export { injectView } from "./inject-view.js";
3
3
  export { injectCommand } from "./inject-command.js";
4
4
  export { injectOperation } from "./inject-operation.js";
5
+ export { injectLatestOperation, } from "./inject-latest-operation.js";
6
+ export { injectCollectionViewport } from "./inject-collection-viewport.js";
@@ -1,5 +1,5 @@
1
1
  import { ElementRef, Injector, type Signal } from "@angular/core";
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 InjectCollectionViewportOptions {
4
4
  /** Required outside an injection context. */
5
5
  readonly injector?: Injector;
@@ -1,5 +1,5 @@
1
1
  import { assertInInjectionContext, DestroyRef, effect, ElementRef, inject, Injector, NgZone, signal, untracked } from "@angular/core";
2
- import { createCollectionViewportController } from "@runic-artifex/views/experimental";
2
+ import { createCollectionViewportController } from "@runic-artifex/views";
3
3
  /**
4
4
  * Follows a fixed-row-height scroll container and returns the rows to request
5
5
  * from .NET as a signal. Pass the container, for example
@@ -0,0 +1,25 @@
1
+ import { Injector, type Signal } from "@angular/core";
2
+ import { type LatestOperationController, type LatestOperationState } from "@runic-artifex/views";
3
+ /** Each field of the latest-operation feedback as a signal, with `run` and `clear`. */
4
+ export type LatestOperationHandle<TResult, TFailure = never> = {
5
+ readonly [K in keyof LatestOperationState<TResult, TFailure>]: Signal<LatestOperationState<TResult, TFailure>[K]>;
6
+ } & Pick<LatestOperationController<TResult, TFailure>, "run" | "clear">;
7
+ export interface InjectLatestOperationOptions {
8
+ /** Required outside an injection context. */
9
+ readonly injector?: Injector;
10
+ }
11
+ /**
12
+ * Admits only the newest selection, for reads such as "load the selected item", as signals
13
+ * for the lifetime of the injection context. Each `run(intent)` replaces the queued intent
14
+ * and cancels the active read, and the next read starts only after the previous one has
15
+ * finished (including `waitForCompletion`). `blocked` means admission is uncertain; only
16
+ * `clear("replace")`, after the application has established a fresh session, clears it.
17
+ * Destruction settles run promises without cancelling accepted work.
18
+ *
19
+ * ```ts
20
+ * readonly load = injectLatestOperation<Item>();
21
+ * select(id: string) { void this.load.run({ start: () => this.items.client()?.startLoad(id) }); }
22
+ * // @if (load.outcome()?.ok) { <item-view [item]="load.outcome()!.value" /> }
23
+ * ```
24
+ */
25
+ export declare function injectLatestOperation<TResult = void, TFailure = never>({ injector: provided }?: InjectLatestOperationOptions): LatestOperationHandle<TResult, TFailure>;
@@ -0,0 +1,34 @@
1
+ import { assertInInjectionContext, computed, DestroyRef, inject, Injector, signal } from "@angular/core";
2
+ import { createLatestOperationController, } from "@runic-artifex/views";
3
+ /**
4
+ * Admits only the newest selection, for reads such as "load the selected item", as signals
5
+ * for the lifetime of the injection context. Each `run(intent)` replaces the queued intent
6
+ * and cancels the active read, and the next read starts only after the previous one has
7
+ * finished (including `waitForCompletion`). `blocked` means admission is uncertain; only
8
+ * `clear("replace")`, after the application has established a fresh session, clears it.
9
+ * Destruction settles run promises without cancelling accepted work.
10
+ *
11
+ * ```ts
12
+ * readonly load = injectLatestOperation<Item>();
13
+ * select(id: string) { void this.load.run({ start: () => this.items.client()?.startLoad(id) }); }
14
+ * // @if (load.outcome()?.ok) { <item-view [item]="load.outcome()!.value" /> }
15
+ * ```
16
+ */
17
+ export function injectLatestOperation({ injector: provided } = {}) {
18
+ if (!provided)
19
+ assertInInjectionContext(injectLatestOperation);
20
+ const injector = provided ?? inject(Injector);
21
+ const controller = createLatestOperationController();
22
+ const state = signal(controller.current, /* @ts-ignore */
23
+ ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
24
+ controller.subscribe(() => state.set(controller.current));
25
+ injector.get(DestroyRef).onDestroy(() => controller.dispose());
26
+ const field = (key) => computed(() => state()[key]);
27
+ return {
28
+ run: controller.run, clear: controller.clear,
29
+ pending: field("pending"), admitting: field("admitting"), operation: field("operation"), status: field("status"),
30
+ outcome: field("outcome"), failure: field("failure"), error: field("error"), cancelled: field("cancelled"),
31
+ cancellationRequested: field("cancellationRequested"), cancelling: field("cancelling"),
32
+ cancellation: field("cancellation"), cancelError: field("cancelError"), blocked: field("blocked"),
33
+ };
34
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/angular",
3
- "version": "0.9.1",
3
+ "version": "0.10.0",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
@@ -8,16 +8,11 @@
8
8
  "import": "./dist/esm/index.js",
9
9
  "default": "./dist/esm/index.js"
10
10
  },
11
- "./experimental": {
12
- "types": "./dist/esm/experimental.d.ts",
13
- "import": "./dist/esm/experimental.js",
14
- "default": "./dist/esm/experimental.js"
15
- },
16
11
  "./package.json": "./package.json"
17
12
  },
18
13
  "peerDependencies": {
19
14
  "@angular/core": ">=22.0.0 <23",
20
- "@runic-artifex/views": "0.9.1"
15
+ "@runic-artifex/views": "0.10.0"
21
16
  },
22
17
  "description": "Angular outlet and signals for Runic Views",
23
18
  "license": "MIT",
@@ -26,7 +21,7 @@
26
21
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
27
22
  "directory": "packages/web/angular"
28
23
  },
29
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/angular#readme",
24
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/angular#readme",
30
25
  "bugs": {
31
26
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
32
27
  },
@@ -50,7 +45,7 @@
50
45
  "pack:check": "bun pm pack --dry-run"
51
46
  },
52
47
  "devDependencies": {
53
- "@runic-artifex/views": "0.9.1",
48
+ "@runic-artifex/views": "0.10.0",
54
49
  "@angular/common": "22.2.3",
55
50
  "@angular/compiler": "22.2.3",
56
51
  "@angular/compiler-cli": "22.2.3",
@@ -60,5 +55,5 @@
60
55
  "typescript": "6.0.3",
61
56
  "vitest": "5.0.3"
62
57
  },
63
- "gitHead": "7df2f00a9800c180e266ca545d4d6a03bf78dc89"
58
+ "gitHead": "fcc71ba13aa56c8f1a720909c1074825a1f5dd6f"
64
59
  }
@@ -1 +0,0 @@
1
- export { injectCollectionViewport, type InjectCollectionViewportOptions } from "./inject-collection-viewport.js";
@@ -1,3 +0,0 @@
1
- // `@runic-artifex/angular/experimental`: helpers whose shape may still change in a minor release
2
- // (docs/experimental.md). Graduation moves an export to `@runic-artifex/angular`.
3
- export { injectCollectionViewport } from "./inject-collection-viewport.js";