@runic-artifex/angular 0.7.0-preview.5 → 0.7.0-preview.7

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
@@ -47,22 +47,56 @@ already connected client is observed and left to its owner. Outside an
47
47
  injection context, pass `{ injector }`; pass `{ release }` to defer disposal,
48
48
  for example until queued commands finish.
49
49
 
50
+ ### Read-only state and two-way binding
51
+
52
+ As in any MVVM View, the ViewModel's C# setters decide what the page may set.
53
+ Read state one way from the `state` signal. A property with a public C# setter
54
+ also gets a `set<Property>` client method: bind the control's value from
55
+ `state` and call the setter from its change event. Status with a
56
+ `private set`, such as `IsDirty` or `Error`, has no setter and is only rendered:
57
+
58
+ ```ts
59
+ // C#: public partial int Count { get; private set; } public partial int Step { get; set; }
60
+ @Component({
61
+ selector: "counter-page",
62
+ template: `
63
+ <p>{{ counter.state()?.count ?? "…" }}</p>
64
+ <select #step (change)="setStep.run(+step.value)">
65
+ @for (value of [1, 5]; track value) {
66
+ <option [value]="value" [selected]="value === (counter.state()?.step ?? 1)">{{ value }}</option>
67
+ }
68
+ </select>
69
+ `,
70
+ })
71
+ export class CounterPage {
72
+ readonly page = input.required<CounterPageReference>();
73
+ readonly counter = injectView(this.page);
74
+ readonly setStep = injectCommand((step: number) => this.counter.client()?.setStep(step));
75
+ }
76
+ ```
77
+
50
78
  ## Outlet
51
79
 
52
80
  Register a component for each generated View kind and pass the current
53
81
  reference to the outlet.
54
82
 
55
83
  ```ts
56
- import { RunicViewOutlet, type ViewRegistry } from "@runic-artifex/angular";
84
+ import { ViewOutlet, type ViewRegistry } from "@runic-artifex/angular";
57
85
  import { DocumentPage } from "./document-page";
58
86
  import type { DocumentReference } from "./generated/document";
59
87
 
60
88
  const registry = { document: DocumentPage } satisfies ViewRegistry<DocumentReference>;
61
89
 
62
- // Add RunicViewOutlet to the parent's imports and bind:
90
+ // Add ViewOutlet to the parent's imports and bind:
63
91
  // <runic-view-outlet [content]="current()" [registry]="registry" />
64
92
  ```
65
93
 
94
+ `ViewOutlet` is the outlet's name in every Runic frontend package (React, Vue,
95
+ Svelte and Angular); its element keeps Angular's prefix convention,
96
+ `<runic-view-outlet>`. Before 0.7.0-preview.7 the Angular class was
97
+ `RunicViewOutlet`. That name is still exported as a deprecated subclass that
98
+ renders the same element, and is removed in the next preview.
99
+
66
100
  The outlet is generic over the reference union it receives, so the registry
67
101
  must have a component for every kind whose `page` input accepts that reference.
68
102
  It remounts the component when the logical View reference changes, and creates
@@ -98,14 +132,40 @@ For example, a navigation command whose departure guard awaits a dialog's
98
132
  answer never completes while the answer waits behind it. Order such commands
99
133
  by dispatch instead: start the next one once the previous one has been sent,
100
134
  as the Notes example's
101
- [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/main/examples/notes-view-first/Angular/src/app/window-operations.ts)
135
+ [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.7.0-preview.7/examples/notes-view-first/Angular/src/app/window-operations.ts)
102
136
  does for its navigation commands.
103
137
 
138
+ ## Operations
139
+
140
+ `injectOperation(start, options?)` observes a generated `start<Command>()` operation
141
+ through the framework-neutral
142
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.7.0-preview.7/packages/web/views#operation-feedback-and-latest-selection)
143
+ for the lifetime of the injection context:
144
+
145
+ ```ts
146
+ readonly push = injectOperation((remote: string) => this.workspace.client()?.startPush(remote));
147
+ // <button [disabled]="!workspace.client() || push.pending()" (click)="push.run('origin')">Push</button>
148
+ // @if (push.pending()) { <button [disabled]="push.cancellationRequested()" (click)="push.cancel()">Cancel</button> }
149
+ // @if (push.cancelled()) { <p role="status">Push cancelled.</p> }
150
+ // @if (push.error() !== undefined) { <p role="alert">{{ push.error() }}</p> }
151
+ ```
152
+
153
+ It returns `run(...args)`, `cancel()` and `reset()`, which never reject, and the
154
+ `pending`, `admitting`, `operation`, `status`, `outcome`, `failure`, `error`,
155
+ `cancelled`, `cancellationRequested`, `cancelling`, `cancellation` and `cancelError`
156
+ 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`.
158
+ `pending` stays true after a Cancel response until the operation reaches its terminal
159
+ status. Destroying the injection context settles run promises without cancelling
160
+ accepted work. The options also take the controller's `cancel(operation)` and
161
+ `waitForCompletion(operation, status)` callbacks, and `injector` outside an injection
162
+ context.
163
+
104
164
  ## Collection viewports
105
165
 
106
166
  `injectCollectionViewport(element, options)` follows a fixed-row-height scroll
107
167
  container and returns a signal with its
108
- [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/main/packages/web/views#collectionviewportoptions)
168
+ [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.7.0-preview.7/packages/web/views#collectionviewportoptions)
109
169
  range. Pass the container as a signal, such as a `viewChild`, and the options as
110
170
  a function or signal, then send the range to the ViewModel from an effect:
111
171
 
@@ -1,5 +1,6 @@
1
- export { RunicViewOutlet, type ViewRegistry } from "./view-outlet.js";
1
+ 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
+ export { injectOperation, type InjectOperationOptions, type OperationHandle } from "./inject-operation.js";
4
5
  export { injectCollectionViewport, type InjectCollectionViewportOptions } from "./inject-collection-viewport.js";
5
6
  export type { CollectionViewport, CollectionViewportOptions, ViewClient, ViewConnector, ViewReference, ViewSource, } from "@runic-artifex/views";
package/dist/esm/index.js CHANGED
@@ -1,4 +1,5 @@
1
- export { RunicViewOutlet } from "./view-outlet.js";
1
+ export { ViewOutlet, RunicViewOutlet } from "./view-outlet.js";
2
2
  export { injectView } from "./inject-view.js";
3
3
  export { injectCommand } from "./inject-command.js";
4
+ export { injectOperation } from "./inject-operation.js";
4
5
  export { injectCollectionViewport } from "./inject-collection-viewport.js";
@@ -0,0 +1,23 @@
1
+ import { Injector, type Signal } from "@angular/core";
2
+ import { type BridgeOperation, type OperationController, type OperationControllerOptions, type OperationState } from "@runic-artifex/views";
3
+ /** Each field of the operation's feedback as a signal, with `run`, `cancel` and `reset`. */
4
+ export type OperationHandle<TArgs extends readonly unknown[], TResult, TFailure = never> = {
5
+ readonly [K in keyof OperationState<TResult, TFailure>]: Signal<OperationState<TResult, TFailure>[K]>;
6
+ } & Pick<OperationController<TArgs, TResult, TFailure>, "run" | "cancel" | "reset">;
7
+ export interface InjectOperationOptions<TResult, TFailure = never> extends OperationControllerOptions<TResult, TFailure> {
8
+ /** Required outside an injection context. */
9
+ readonly injector?: Injector;
10
+ }
11
+ /**
12
+ * Tracks Start admission, pending work, cancellation and terminal feedback of a
13
+ * generated `start<Command>()` operation as signals for the lifetime of the
14
+ * injection context. A run that ends `cancelled` sets `cancelled`, not `error`.
15
+ * Destruction settles run promises without cancelling accepted work.
16
+ *
17
+ * ```ts
18
+ * readonly push = injectOperation((remote: string) => this.workspace.client()?.startPush(remote));
19
+ * // <button [disabled]="push.pending()" (click)="push.run('origin')">Push</button>
20
+ * // @if (push.cancelled()) { <p role="status">Push cancelled.</p> }
21
+ * ```
22
+ */
23
+ export declare function injectOperation<TArgs extends readonly unknown[], TResult, TFailure = never>(start: (...args: TArgs) => BridgeOperation<TResult, TFailure> | undefined | PromiseLike<BridgeOperation<TResult, TFailure> | undefined>, { injector: provided, ...options }?: InjectOperationOptions<TResult, TFailure>): OperationHandle<TArgs, TResult, TFailure>;
@@ -0,0 +1,32 @@
1
+ import { assertInInjectionContext, computed, DestroyRef, inject, Injector, signal } from "@angular/core";
2
+ import { createOperationController, } from "@runic-artifex/views";
3
+ /**
4
+ * Tracks Start admission, pending work, cancellation and terminal feedback of a
5
+ * generated `start<Command>()` operation as signals for the lifetime of the
6
+ * injection context. A run that ends `cancelled` sets `cancelled`, not `error`.
7
+ * Destruction settles run promises without cancelling accepted work.
8
+ *
9
+ * ```ts
10
+ * readonly push = injectOperation((remote: string) => this.workspace.client()?.startPush(remote));
11
+ * // <button [disabled]="push.pending()" (click)="push.run('origin')">Push</button>
12
+ * // @if (push.cancelled()) { <p role="status">Push cancelled.</p> }
13
+ * ```
14
+ */
15
+ export function injectOperation(start, { injector: provided, ...options } = {}) {
16
+ if (!provided)
17
+ assertInInjectionContext(injectOperation);
18
+ const injector = provided ?? inject(Injector);
19
+ const controller = createOperationController(start, options);
20
+ const state = signal(controller.current, /* @ts-ignore */
21
+ ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
22
+ controller.subscribe(() => state.set(controller.current));
23
+ injector.get(DestroyRef).onDestroy(() => controller.dispose());
24
+ const field = (key) => computed(() => state()[key]);
25
+ return {
26
+ run: controller.run, cancel: controller.cancel, reset: controller.reset,
27
+ pending: field("pending"), admitting: field("admitting"), operation: field("operation"), status: field("status"),
28
+ outcome: field("outcome"), failure: field("failure"), error: field("error"), cancelled: field("cancelled"),
29
+ cancellationRequested: field("cancellationRequested"), cancelling: field("cancelling"),
30
+ cancellation: field("cancellation"), cancelError: field("cancelError"),
31
+ };
32
+ }
@@ -1,22 +1,37 @@
1
1
  import { type InputSignal, type Type } from "@angular/core";
2
2
  import type { ViewReference } from "@runic-artifex/views";
3
3
  import * as i0 from "@angular/core";
4
- /** A build-known map checks each generated reference against its component input. */
5
- export type ViewRegistry<R extends ViewReference> = {
6
- readonly [K in R["kind"]]: Type<{
7
- readonly page: InputSignal<Extract<R, {
4
+ /**
5
+ * A build-known map checks each generated reference against its component input. A nullable
6
+ * reference, such as a region slot's `State["main"]`, checks its non-null kinds.
7
+ */
8
+ export type ViewRegistry<R extends ViewReference | null | undefined> = {
9
+ readonly [K in NonNullable<R>["kind"]]: Type<{
10
+ readonly page: InputSignal<Extract<NonNullable<R>, {
8
11
  readonly kind: K;
9
12
  }>>;
10
13
  }>;
11
14
  };
12
- /** Headless host for a selected logical .NET View. A changed reference remounts its component. */
13
- export declare class RunicViewOutlet<R extends ViewReference = ViewReference> {
15
+ /**
16
+ * Headless host for a selected logical .NET View. A changed reference remounts its component.
17
+ * The element keeps Angular's prefix convention: `<runic-view-outlet [content]="…" [registry]="…" />`.
18
+ */
19
+ export declare class ViewOutlet<R extends ViewReference = ViewReference> {
14
20
  readonly content: InputSignal<R | null | undefined>;
15
21
  readonly registry: InputSignal<ViewRegistry<R>>;
16
22
  readonly error: import("@angular/core").WritableSignal<string | undefined>;
17
23
  private readonly mount;
18
24
  private readonly selected;
19
25
  constructor();
26
+ 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
+ }
29
+ /**
30
+ * The name of {@link ViewOutlet} before 0.7.0-preview.7, where React, Vue and Svelte already used
31
+ * `ViewOutlet`. It renders the same `<runic-view-outlet>` element.
32
+ * @deprecated Import `ViewOutlet` instead; this alias is removed in the next preview.
33
+ */
34
+ export declare class RunicViewOutlet<R extends ViewReference = ViewReference> extends ViewOutlet<R> {
20
35
  static ɵfac: i0.ɵɵFactoryDeclaration<RunicViewOutlet<any>, never>;
21
- static ɵcmp: i0.ɵɵComponentDeclaration<RunicViewOutlet<any>, "runic-view-outlet", never, { "content": { "alias": "content"; "required": false; "isSignal": true; }; "registry": { "alias": "registry"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
36
+ static ɵcmp: i0.ɵɵComponentDeclaration<RunicViewOutlet<any>, "runic-view-outlet", never, {}, {}, never, never, true, never>;
22
37
  }
@@ -1,7 +1,14 @@
1
1
  import { Component, computed, effect, input, signal, untracked, viewChild, ViewContainerRef } from "@angular/core";
2
2
  import * as i0 from "@angular/core";
3
- /** Headless host for a selected logical .NET View. A changed reference remounts its component. */
4
- export class RunicViewOutlet {
3
+ const outletTemplate = `
4
+ <ng-container #mount />
5
+ @if (error(); as issue) { <p role="alert">{{ issue }}</p> }
6
+ `;
7
+ /**
8
+ * Headless host for a selected logical .NET View. A changed reference remounts its component.
9
+ * The element keeps Angular's prefix convention: `<runic-view-outlet [content]="…" [registry]="…" />`.
10
+ */
11
+ export class ViewOutlet {
5
12
  content = input(/* @ts-ignore */
6
13
  ...(ngDevMode ? [undefined, { debugName: "content" }] : /* istanbul ignore next */ []));
7
14
  registry = input.required(/* @ts-ignore */
@@ -38,20 +45,23 @@ export class RunicViewOutlet {
38
45
  });
39
46
  });
40
47
  }
41
- static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: RunicViewOutlet, deps: [], target: i0.ɵɵFactoryTarget.Component });
42
- static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.2.1", type: RunicViewOutlet, 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: `
43
- <ng-container #mount />
44
- @if (error(); as issue) { <p role="alert">{{ issue }}</p> }
45
- `, isInline: true });
48
+ 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 });
46
50
  }
47
- i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: RunicViewOutlet, decorators: [{
51
+ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: ViewOutlet, decorators: [{
48
52
  type: Component,
49
- args: [{
50
- selector: "runic-view-outlet",
51
- standalone: true,
52
- template: `
53
- <ng-container #mount />
54
- @if (error(); as issue) { <p role="alert">{{ issue }}</p> }
55
- `,
56
- }]
53
+ args: [{ selector: "runic-view-outlet", standalone: true, template: outletTemplate }]
57
54
  }], ctorParameters: () => [], propDecorators: { content: [{ type: i0.Input, args: [{ isSignal: true, alias: "content", required: false }] }], registry: [{ type: i0.Input, args: [{ isSignal: true, alias: "registry", required: true }] }], mount: [{ type: i0.ViewChild, args: ["mount", { ...{ read: ViewContainerRef }, isSignal: true }] }] } });
55
+ /**
56
+ * The name of {@link ViewOutlet} before 0.7.0-preview.7, where React, Vue and Svelte already used
57
+ * `ViewOutlet`. It renders the same `<runic-view-outlet>` element.
58
+ * @deprecated Import `ViewOutlet` instead; this alias is removed in the next preview.
59
+ */
60
+ export class RunicViewOutlet extends ViewOutlet {
61
+ 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 });
63
+ }
64
+ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: RunicViewOutlet, decorators: [{
65
+ type: Component,
66
+ args: [{ selector: "runic-view-outlet", standalone: true, template: outletTemplate }]
67
+ }] });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/angular",
3
- "version": "0.7.0-preview.5",
3
+ "version": "0.7.0-preview.7",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
@@ -11,7 +11,7 @@
11
11
  },
12
12
  "peerDependencies": {
13
13
  "@angular/core": ">=20.3.26 <23",
14
- "@runic-artifex/views": "0.7.0-preview.5"
14
+ "@runic-artifex/views": "0.7.0-preview.7"
15
15
  },
16
16
  "description": "Angular outlet and signals for Runic Views",
17
17
  "license": "MIT",
@@ -20,7 +20,7 @@
20
20
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
21
21
  "directory": "packages/web/angular"
22
22
  },
23
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/main/packages/web/angular#readme",
23
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.7.0-preview.7/packages/web/angular#readme",
24
24
  "bugs": {
25
25
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
26
26
  },
@@ -47,7 +47,7 @@
47
47
  "pack:check": "bun pm pack --dry-run"
48
48
  },
49
49
  "devDependencies": {
50
- "@runic-artifex/views": "0.7.0-preview.5",
50
+ "@runic-artifex/views": "0.7.0-preview.7",
51
51
  "@angular/common": "22.2.1",
52
52
  "@angular/compiler": "22.2.1",
53
53
  "@angular/compiler-cli": "22.2.1",
@@ -57,5 +57,5 @@
57
57
  "typescript": "6.0.3",
58
58
  "vitest": "5.0.3"
59
59
  },
60
- "gitHead": "0ef2a51e2c03b47311093a979da823540db25ca6"
60
+ "gitHead": "d274acebd19284557ad6a3d02562ddfac93ae4e1"
61
61
  }