@runic-artifex/angular 0.8.0-preview.6 → 0.9.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
@@ -11,7 +11,7 @@ bun add @runic-artifex/angular@preview @runic-artifex/views@preview
11
11
  ```
12
12
 
13
13
  Previews are published under the `preview` dist-tag. Install the versions that
14
- match your Runic SDK packages.
14
+ match your Runic SDK packages. Angular 22 is supported.
15
15
 
16
16
  ## Connecting a View
17
17
 
@@ -88,9 +88,12 @@ import type { DocumentReference } from "./generated/document";
88
88
  const registry = { document: DocumentPage } satisfies ViewRegistry<DocumentReference>;
89
89
 
90
90
  // Add ViewOutlet to the parent's imports and bind:
91
- // <runic-view-outlet [content]="current()" [registry]="registry" />
91
+ // <runic-view-outlet [content]="current()" [registry]="registry">Connecting…</runic-view-outlet>
92
92
  ```
93
93
 
94
+ The outlet's projected content renders while there is no reference, like
95
+ React's `fallback`, Vue's default slot and Svelte's `fallback` snippet.
96
+
94
97
  `ViewOutlet` is the outlet's name in every Runic frontend package (React, Vue,
95
98
  Svelte and Angular); its element keeps Angular's prefix convention,
96
99
  `<runic-view-outlet>`. Before 0.7.0-preview.7 the Angular class was
@@ -101,9 +104,11 @@ The outlet is generic over the reference union it receives, so the registry
101
104
  must have a component for every kind whose `page` input accepts that reference.
102
105
  It remounts the component when the logical View reference changes, and creates
103
106
  it outside its own signal tracking. A component's `page` input receives that
104
- reference; `injectView(this.page)` owns its connection and cleanup. Missing
105
- kinds render an alert. The generated TypeScript client can also be used
106
- directly without Angular.
107
+ reference; `injectView(this.page)` owns its connection and cleanup. Declare
108
+ `page` as a required signal input, `input.required<DocumentReference>()`: a
109
+ decorator `@Input() page` or an optional `input<DocumentReference>()` does not
110
+ satisfy `ViewRegistry`. Missing kinds render an alert. The generated TypeScript
111
+ client can also be used directly without Angular.
107
112
 
108
113
  ## Commands
109
114
 
@@ -132,14 +137,14 @@ For example, a navigation command whose departure guard awaits a dialog's
132
137
  answer never completes while the answer waits behind it. Order such commands
133
138
  by dispatch instead: start the next one once the previous one has been sent,
134
139
  as the Notes example's
135
- [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.8.0-preview.6/examples/notes-view-first/Angular/src/app/window-operations.ts)
140
+ [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.0/examples/notes-view-first/Angular/src/app/window-operations.ts)
136
141
  does for its navigation commands.
137
142
 
138
143
  ## Operations
139
144
 
140
145
  `injectOperation(start, options?)` observes a generated `start<Command>()` operation
141
146
  through the framework-neutral
142
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.8.0-preview.6/packages/web/views#operation-feedback-and-latest-selection)
147
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.0/packages/web/views#operation-feedback-and-latest-selection)
143
148
  for the lifetime of the injection context:
144
149
 
145
150
  ```ts
@@ -154,18 +159,91 @@ It returns `run(...args)`, `cancel()` and `reset()`, which never reject, and the
154
159
  `pending`, `admitting`, `operation`, `status`, `outcome`, `failure`, `error`,
155
160
  `cancelled`, `cancellationRequested`, `cancelling`, `cancellation` and `cancelError`
156
161
  signals. A run that ends with a `cancelled` status sets `cancelled` and resolves to
157
- `undefined` without an `error`; `failed` and `timedOut` statuses are still `error`.
162
+ `undefined` without an `error`; `failed` and `timed-out` statuses are still `error`.
158
163
  `pending` stays true after a Cancel response until the operation reaches its terminal
159
164
  status. Destroying the injection context settles run promises without cancelling
160
165
  accepted work. The options also take the controller's `cancel(operation)` and
161
166
  `waitForCompletion(operation, status)` callbacks, and `injector` outside an injection
162
167
  context.
163
168
 
164
- ## Collection viewports
169
+ ## Errors
170
+
171
+ The `error()` signal of `injectView` and of a command or operation is typed
172
+ `unknown`: it holds whatever the connection or the call rejected with. A Bridge
173
+ failure is a `BridgeError` from `@runic-artifex/views`; narrow it with
174
+ `instanceof` before reading `kind`, `route` or `detail`:
175
+
176
+ ```ts
177
+ import { BridgeError } from "@runic-artifex/views";
178
+
179
+ const error = this.view.error();
180
+ const offline = error instanceof BridgeError && error.kind === "disconnected";
181
+ ```
182
+
183
+ `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.0/packages/web/views#errors-and-diagnostics)
185
+ lists the kinds. Any other value, such as an exception that your own connect
186
+ function or command callback throws, arrives unchanged.
187
+
188
+ The signals run in the browser or webview that a Runic host serves. `injectView`
189
+ connects in an effect, which Angular also runs in a server render: render the
190
+ components that use it on the client only.
191
+
192
+ ## Interactions
193
+
194
+ A ReactiveUI `Interaction<TInput, TOutput>` on the ViewModel, such as the
195
+ question of a `ReactiveLeaveConfirmation.WithInteraction` leave guard, is
196
+ `client.interactions.<name>` on the generated client. Register the page's answer
197
+ in an `effect`: `handle((prompt, { signal }) => …)` returns the function that
198
+ removes it, so pass that to `onCleanup`, and Angular removes the handler when
199
+ the client changes or the component is destroyed:
200
+
201
+ ```ts
202
+ import { Component, effect, input } from "@angular/core";
203
+ import { injectView } from "@runic-artifex/angular";
204
+ import type { EditPageReference } from "./generated/edit";
205
+
206
+ @Component({ selector: "edit-page", template: `…` })
207
+ export class EditPage {
208
+ readonly page = input.required<EditPageReference>();
209
+ readonly view = injectView(this.page);
210
+
211
+ constructor() {
212
+ effect(onCleanup => {
213
+ const remove = this.view.client()?.interactions.confirmDiscard.handle(
214
+ async (prompt, { signal }) => confirmDialog(`Discard the changes to ${prompt.itemName}?`, signal),
215
+ );
216
+ if (remove) onCleanup(remove);
217
+ });
218
+ }
219
+ }
220
+ ```
165
221
 
166
- `injectCollectionViewport(element, options)` follows a fixed-row-height scroll
222
+ `prompt` and the answer are typed from the ViewModel's interaction. The handler
223
+ may return the answer or a promise of it; `confirmDialog` stands for the
224
+ application's own dialog.
225
+
226
+ - The page is asked for a departure that its own window starts: its Close, the
227
+ shell's Back in the same window, or a guarded window close.
228
+ - `signal` aborts when .NET no longer needs the answer, for example when the
229
+ departure is superseded or the window closes. Close the dialog then; a late
230
+ answer is ignored.
231
+ - The handler exists only after the client connected and the effect ran. A
232
+ departure before that is answered by the ViewModel's .NET fallback handler, or
233
+ fails closed without one.
234
+
235
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.9.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
236
+ has the .NET side and which View answers which departure. In a frontend test,
237
+ 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.0/packages/web/views#testing).
239
+
240
+ ## Collection viewports (experimental)
241
+
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
167
245
  container and returns a signal with its
168
- [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.8.0-preview.6/packages/web/views#collectionviewportoptions)
246
+ [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.0/packages/web/views#collectionviewportoptions-experimental)
169
247
  range. Pass the container as a signal, such as a `viewChild`, and the options as
170
248
  a function or signal, then send the range to the ViewModel from an effect:
171
249
 
@@ -0,0 +1 @@
1
+ export { injectCollectionViewport, type InjectCollectionViewportOptions } from "./inject-collection-viewport.js";
@@ -0,0 +1,3 @@
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";
@@ -2,5 +2,3 @@ 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 { injectCollectionViewport, type InjectCollectionViewportOptions } from "./inject-collection-viewport.js";
6
- export type { CollectionViewport, CollectionViewportOptions, ViewClient, ViewConnector, ViewReference, ViewSource, } from "@runic-artifex/views";
package/dist/esm/index.js CHANGED
@@ -2,4 +2,3 @@ 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 { 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";
2
+ import { type CollectionViewport, type CollectionViewportOptions } from "@runic-artifex/views/experimental";
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";
2
+ import { createCollectionViewportController } from "@runic-artifex/views/experimental";
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
@@ -1,5 +1,6 @@
1
1
  import { assertInInjectionContext, computed, DestroyRef, effect, inject, Injector, isSignal, signal, untracked } from "@angular/core";
2
- import { createViewController, isViewClient, viewSourceIdentity } from "@runic-artifex/views";
2
+ import { createViewController } from "@runic-artifex/views";
3
+ import { isViewClient, viewSourceIdentity } from "@runic-artifex/views/bindings";
3
4
  /**
4
5
  * Connects a generated View reference for the lifetime of the injection
5
6
  * context (normally a component) and exposes its state as signals. Pass a
@@ -1,11 +1,11 @@
1
1
  import { type InputSignal, type Type } from "@angular/core";
2
- import type { ViewReference } from "@runic-artifex/views";
2
+ import type { PageReference } from "@runic-artifex/views";
3
3
  import * as i0 from "@angular/core";
4
4
  /**
5
5
  * A build-known map checks each generated reference against its component input. A nullable
6
6
  * reference, such as a region slot's `State["main"]`, checks its non-null kinds.
7
7
  */
8
- export type ViewRegistry<R extends ViewReference | null | undefined> = {
8
+ export type ViewRegistry<R extends PageReference | null | undefined> = {
9
9
  readonly [K in NonNullable<R>["kind"]]: Type<{
10
10
  readonly page: InputSignal<Extract<NonNullable<R>, {
11
11
  readonly kind: K;
@@ -13,10 +13,11 @@ export type ViewRegistry<R extends ViewReference | null | undefined> = {
13
13
  }>;
14
14
  };
15
15
  /**
16
- * Headless host for a selected logical .NET View. A changed reference remounts its component.
16
+ * Headless host for a selected logical .NET View. A changed reference remounts its component, and
17
+ * the projected content renders while there is no reference.
17
18
  * The element keeps Angular's prefix convention: `<runic-view-outlet [content]="…" [registry]="…" />`.
18
19
  */
19
- export declare class ViewOutlet<R extends ViewReference = ViewReference> {
20
+ export declare class ViewOutlet<R extends PageReference = PageReference> {
20
21
  readonly content: InputSignal<R | null | undefined>;
21
22
  readonly registry: InputSignal<ViewRegistry<R>>;
22
23
  readonly error: import("@angular/core").WritableSignal<string | undefined>;
@@ -24,14 +25,14 @@ export declare class ViewOutlet<R extends ViewReference = ViewReference> {
24
25
  private readonly selected;
25
26
  constructor();
26
27
  static ɵfac: i0.ɵɵFactoryDeclaration<ViewOutlet<any>, never>;
27
- static ɵcmp: i0.ɵɵComponentDeclaration<ViewOutlet<any>, "runic-view-outlet", never, { "content": { "alias": "content"; "required": false; "isSignal": true; }; "registry": { "alias": "registry"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
28
+ static ɵcmp: i0.ɵɵComponentDeclaration<ViewOutlet<any>, "runic-view-outlet", never, { "content": { "alias": "content"; "required": false; "isSignal": true; }; "registry": { "alias": "registry"; "required": true; "isSignal": true; }; }, {}, never, ["*"], true, never>;
28
29
  }
29
30
  /**
30
31
  * The name of {@link ViewOutlet} before 0.7.0-preview.7, where React, Vue and Svelte already used
31
32
  * `ViewOutlet`. It renders the same `<runic-view-outlet>` element.
32
33
  * @deprecated Import `ViewOutlet` instead; this alias is removed in the next preview.
33
34
  */
34
- export declare class RunicViewOutlet<R extends ViewReference = ViewReference> extends ViewOutlet<R> {
35
+ export declare class RunicViewOutlet<R extends PageReference = PageReference> extends ViewOutlet<R> {
35
36
  static ɵfac: i0.ɵɵFactoryDeclaration<RunicViewOutlet<any>, never>;
36
- static ɵcmp: i0.ɵɵComponentDeclaration<RunicViewOutlet<any>, "runic-view-outlet", never, {}, {}, never, never, true, never>;
37
+ static ɵcmp: i0.ɵɵComponentDeclaration<RunicViewOutlet<any>, "runic-view-outlet", never, {}, {}, never, ["*"], true, never>;
37
38
  }
@@ -1,11 +1,15 @@
1
1
  import { Component, computed, effect, input, signal, untracked, viewChild, ViewContainerRef } from "@angular/core";
2
2
  import * as i0 from "@angular/core";
3
+ // Projected content renders while there is no reference, like React's `fallback`, Vue's default slot
4
+ // and Svelte's `fallback` snippet: `<runic-view-outlet [content]="…" [registry]="…">Loading…</runic-view-outlet>`.
3
5
  const outletTemplate = `
4
6
  <ng-container #mount />
7
+ @if (!content()) { <ng-content /> }
5
8
  @if (error(); as issue) { <p role="alert">{{ issue }}</p> }
6
9
  `;
7
10
  /**
8
- * Headless host for a selected logical .NET View. A changed reference remounts its component.
11
+ * Headless host for a selected logical .NET View. A changed reference remounts its component, and
12
+ * the projected content renders while there is no reference.
9
13
  * The element keeps Angular's prefix convention: `<runic-view-outlet [content]="…" [registry]="…" />`.
10
14
  */
11
15
  export class ViewOutlet {
@@ -46,7 +50,7 @@ export class ViewOutlet {
46
50
  });
47
51
  }
48
52
  static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: ViewOutlet, deps: [], target: i0.ɵɵFactoryTarget.Component });
49
- static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.2.1", type: ViewOutlet, isStandalone: true, selector: "runic-view-outlet", inputs: { content: { classPropertyName: "content", publicName: "content", isSignal: true, isRequired: false, transformFunction: null }, registry: { classPropertyName: "registry", publicName: "registry", isSignal: true, isRequired: true, transformFunction: null } }, viewQueries: [{ propertyName: "mount", first: true, predicate: ["mount"], descendants: true, read: ViewContainerRef, isSignal: true }], ngImport: i0, template: "\n <ng-container #mount />\n @if (error(); as issue) { <p role=\"alert\">{{ issue }}</p> }\n ", isInline: true });
53
+ static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.2.1", type: ViewOutlet, isStandalone: true, selector: "runic-view-outlet", inputs: { content: { classPropertyName: "content", publicName: "content", isSignal: true, isRequired: false, transformFunction: null }, registry: { classPropertyName: "registry", publicName: "registry", isSignal: true, isRequired: true, transformFunction: null } }, viewQueries: [{ propertyName: "mount", first: true, predicate: ["mount"], descendants: true, read: ViewContainerRef, isSignal: true }], ngImport: i0, template: "\n <ng-container #mount />\n @if (!content()) { <ng-content /> }\n @if (error(); as issue) { <p role=\"alert\">{{ issue }}</p> }\n ", isInline: true });
50
54
  }
51
55
  i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: ViewOutlet, decorators: [{
52
56
  type: Component,
@@ -59,7 +63,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.1", ngImpor
59
63
  */
60
64
  export class RunicViewOutlet extends ViewOutlet {
61
65
  static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: RunicViewOutlet, deps: null, target: i0.ɵɵFactoryTarget.Component });
62
- static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.2.1", type: RunicViewOutlet, isStandalone: true, selector: "runic-view-outlet", usesInheritance: true, ngImport: i0, template: "\n <ng-container #mount />\n @if (error(); as issue) { <p role=\"alert\">{{ issue }}</p> }\n ", isInline: true });
66
+ static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.2.1", type: RunicViewOutlet, isStandalone: true, selector: "runic-view-outlet", usesInheritance: true, ngImport: i0, template: "\n <ng-container #mount />\n @if (!content()) { <ng-content /> }\n @if (error(); as issue) { <p role=\"alert\">{{ issue }}</p> }\n ", isInline: true });
63
67
  }
64
68
  i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: RunicViewOutlet, decorators: [{
65
69
  type: Component,
package/package.json CHANGED
@@ -1,17 +1,23 @@
1
1
  {
2
2
  "name": "@runic-artifex/angular",
3
- "version": "0.8.0-preview.6",
3
+ "version": "0.9.0",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
7
7
  "types": "./dist/esm/index.d.ts",
8
- "import": "./dist/esm/index.js"
8
+ "import": "./dist/esm/index.js",
9
+ "default": "./dist/esm/index.js"
10
+ },
11
+ "./experimental": {
12
+ "types": "./dist/esm/experimental.d.ts",
13
+ "import": "./dist/esm/experimental.js",
14
+ "default": "./dist/esm/experimental.js"
9
15
  },
10
16
  "./package.json": "./package.json"
11
17
  },
12
18
  "peerDependencies": {
13
- "@angular/core": ">=20.3.26 <23",
14
- "@runic-artifex/views": "0.8.0-preview.6"
19
+ "@angular/core": ">=22.0.0 <23",
20
+ "@runic-artifex/views": "0.9.0"
15
21
  },
16
22
  "description": "Angular outlet and signals for Runic Views",
17
23
  "license": "MIT",
@@ -20,7 +26,7 @@
20
26
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
21
27
  "directory": "packages/web/angular"
22
28
  },
23
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.8.0-preview.6/packages/web/angular#readme",
29
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.0/packages/web/angular#readme",
24
30
  "bugs": {
25
31
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
26
32
  },
@@ -33,9 +39,6 @@
33
39
  "README.md",
34
40
  "LICENSE"
35
41
  ],
36
- "engines": {
37
- "node": ">=24.18.0 <25"
38
- },
39
42
  "packageManager": "bun@1.4.2",
40
43
  "sideEffects": false,
41
44
  "main": "./dist/esm/index.js",
@@ -47,7 +50,7 @@
47
50
  "pack:check": "bun pm pack --dry-run"
48
51
  },
49
52
  "devDependencies": {
50
- "@runic-artifex/views": "0.8.0-preview.6",
53
+ "@runic-artifex/views": "0.9.0",
51
54
  "@angular/common": "22.2.1",
52
55
  "@angular/compiler": "22.2.1",
53
56
  "@angular/compiler-cli": "22.2.1",
@@ -57,5 +60,5 @@
57
60
  "typescript": "6.0.3",
58
61
  "vitest": "5.0.3"
59
62
  },
60
- "gitHead": "9840f55faf97e0258af065eaa75c380802bc69ff"
63
+ "gitHead": "6793f99c726af8b1d05067108761905aa5e8d0d6"
61
64
  }