@runic-artifex/angular 0.5.0-preview.2 → 0.6.0-preview.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
@@ -1,7 +1,53 @@
1
1
  # `@runic-artifex/angular`
2
2
 
3
- Angular outlet for generated Runic View references. Register a component for
4
- each generated View kind and pass the current reference to the outlet.
3
+ Angular outlet and signals for generated Runic View clients. The generated
4
+ modules import `@runic-artifex/views`, so install both:
5
+
6
+ ```sh
7
+ npm install @runic-artifex/angular@preview @runic-artifex/views@preview
8
+ pnpm add @runic-artifex/angular@preview @runic-artifex/views@preview
9
+ bun add @runic-artifex/angular@preview @runic-artifex/views@preview
10
+ ```
11
+
12
+ Previews are published under the `preview` dist-tag. Install the versions that
13
+ match your Runic SDK packages.
14
+
15
+ ## Connecting a View
16
+
17
+ `injectView(source)` connects a generated page reference, or
18
+ `{ connect: connect<Name> }` for a root ViewModel, for the lifetime of the
19
+ injection context and returns `state`, `client` and `error` signals and
20
+ `retry()`:
21
+
22
+ ```ts
23
+ import { Component, input } from "@angular/core";
24
+ import { injectView } from "@runic-artifex/angular";
25
+ import type { CounterPageReference } from "./generated/counter";
26
+
27
+ @Component({
28
+ selector: "counter-page",
29
+ template: `
30
+ <button [disabled]="!counter.client()" (click)="counter.client()?.increment()">
31
+ {{ counter.state()?.count ?? "…" }}
32
+ </button>
33
+ `,
34
+ })
35
+ export class CounterPage {
36
+ readonly page = input.required<CounterPageReference>();
37
+ readonly counter = injectView(this.page);
38
+ }
39
+ ```
40
+
41
+ Pass a signal, such as an input, to follow it: a reference with a different
42
+ `connect` function releases the previous client and connects the new one. An
43
+ already connected client is observed and left to its owner. Outside an
44
+ injection context, pass `{ injector }`; pass `{ release }` to defer disposal,
45
+ for example until queued commands finish.
46
+
47
+ ## Outlet
48
+
49
+ Register a component for each generated View kind and pass the current
50
+ reference to the outlet.
5
51
 
6
52
  ```ts
7
53
  import { RunicViewOutlet, type ViewRegistry } from "@runic-artifex/angular";
@@ -15,6 +61,6 @@ const registry = { document: DocumentPage } satisfies ViewRegistry<DocumentRefer
15
61
  ```
16
62
 
17
63
  The outlet remounts the component when the logical View reference changes. A
18
- component's `page` input receives that reference and owns its page connection
19
- and cleanup. Missing kinds render an alert. The generated TypeScript client can
20
- also be used directly without Angular.
64
+ component's `page` input receives that reference; `injectView(this.page)` owns
65
+ its connection and cleanup. Missing kinds render an alert. The generated
66
+ TypeScript client can also be used directly without Angular.
@@ -0,0 +1,2 @@
1
+ export { RunicViewOutlet, type ViewReference, type ViewRegistry } from "./view-outlet.js";
2
+ export { injectView, type InjectViewOptions, type ViewClient, type ViewHandle, type ViewSource } from "./inject-view.js";
@@ -0,0 +1,2 @@
1
+ export { RunicViewOutlet } from "./view-outlet.js";
2
+ export { injectView } from "./inject-view.js";
@@ -0,0 +1,41 @@
1
+ import { Injector, type Signal } from "@angular/core";
2
+ /** The framework-neutral surface of a generated `<Name>Client`. */
3
+ export interface ViewClient<TState = unknown> {
4
+ readonly snapshot: TState;
5
+ subscribe(listener: (state: TState) => void): () => void;
6
+ dispose(): void;
7
+ }
8
+ /**
9
+ * A generated content reference or `{ connect: connect<Name> }` for a root
10
+ * ViewModel, which `injectView` connects and disposes, or an already connected
11
+ * client, which it only observes.
12
+ */
13
+ export type ViewSource<TClient extends ViewClient> = {
14
+ connect(): Promise<TClient>;
15
+ } | TClient | null | undefined;
16
+ export interface ViewHandle<TClient extends ViewClient> {
17
+ /** The latest state, or undefined until the client connects. */
18
+ readonly state: Signal<TClient["snapshot"] | undefined>;
19
+ /** The connected client for commands, or undefined until it connects. */
20
+ readonly client: Signal<TClient | undefined>;
21
+ /** The connection failure, if any. */
22
+ readonly error: Signal<unknown>;
23
+ /** Connects a reference again after a failure. */
24
+ retry(): void;
25
+ }
26
+ export interface InjectViewOptions<TClient extends ViewClient> {
27
+ /** Required outside an injection context. */
28
+ readonly injector?: Injector;
29
+ /** Releases a client this helper connected. Defaults to `client.dispose()`. */
30
+ readonly release?: (client: TClient) => void;
31
+ }
32
+ /**
33
+ * Connects a generated View reference for the lifetime of the injection
34
+ * context (normally a component) and exposes its state as signals. Pass a
35
+ * signal, such as a `page` input, to follow it: a changed reference releases
36
+ * the previous client and connects the new one.
37
+ *
38
+ * A reference is identified by its `connect` function, so a signal producing a
39
+ * new `{ connect: connectShell }` object does not reconnect.
40
+ */
41
+ export declare function injectView<TClient extends ViewClient>(source: Signal<ViewSource<TClient>> | ViewSource<TClient>, options?: InjectViewOptions<TClient>): ViewHandle<TClient>;
@@ -0,0 +1,84 @@
1
+ import { assertInInjectionContext, computed, effect, inject, Injector, isSignal, signal, untracked } from "@angular/core";
2
+ function isClient(source) {
3
+ return typeof source.subscribe === "function";
4
+ }
5
+ /**
6
+ * Connects a generated View reference for the lifetime of the injection
7
+ * context (normally a component) and exposes its state as signals. Pass a
8
+ * signal, such as a `page` input, to follow it: a changed reference releases
9
+ * the previous client and connects the new one.
10
+ *
11
+ * A reference is identified by its `connect` function, so a signal producing a
12
+ * new `{ connect: connectShell }` object does not reconnect.
13
+ */
14
+ export function injectView(source, options = {}) {
15
+ if (!options.injector)
16
+ assertInInjectionContext(injectView);
17
+ const injector = options.injector ?? inject(Injector);
18
+ const release = options.release ?? ((client) => client.dispose());
19
+ const read = () => isSignal(source) ? source() : source;
20
+ const identity = computed(() => {
21
+ const value = read();
22
+ return value ? isClient(value) ? value : value.connect : undefined;
23
+ }, /* @ts-ignore */
24
+ ...(ngDevMode ? [{ debugName: "identity" }] : /* istanbul ignore next */ []));
25
+ const observed = computed(() => {
26
+ const value = read();
27
+ return value && isClient(value) ? value : undefined;
28
+ }, /* @ts-ignore */
29
+ ...(ngDevMode ? [{ debugName: "observed" }] : /* istanbul ignore next */ []));
30
+ const attempt = signal(0, /* @ts-ignore */
31
+ ...(ngDevMode ? [{ debugName: "attempt" }] : /* istanbul ignore next */ []));
32
+ const latest = signal(undefined, /* @ts-ignore */
33
+ ...(ngDevMode ? [{ debugName: "latest" }] : /* istanbul ignore next */ []));
34
+ const connectedClient = signal(undefined, /* @ts-ignore */
35
+ ...(ngDevMode ? [{ debugName: "connectedClient" }] : /* istanbul ignore next */ []));
36
+ const error = signal(undefined, /* @ts-ignore */
37
+ ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
38
+ effect(onCleanup => {
39
+ identity();
40
+ attempt();
41
+ const value = untracked(read);
42
+ latest.set(undefined);
43
+ connectedClient.set(undefined);
44
+ error.set(undefined);
45
+ if (!value)
46
+ return;
47
+ let active = true;
48
+ let connected;
49
+ let unsubscribe;
50
+ const observe = (next) => {
51
+ connectedClient.set(next);
52
+ unsubscribe = next.subscribe(update => { if (active)
53
+ latest.set(update); });
54
+ };
55
+ if (isClient(value))
56
+ observe(value);
57
+ else
58
+ value.connect().then(next => {
59
+ if (!active) {
60
+ release(next);
61
+ return;
62
+ }
63
+ connected = next;
64
+ observe(next);
65
+ }, cause => { if (active)
66
+ error.set(cause); });
67
+ onCleanup(() => {
68
+ active = false;
69
+ unsubscribe?.();
70
+ if (connected)
71
+ release(connected);
72
+ });
73
+ }, { injector });
74
+ return {
75
+ // A connected client is readable before the effect subscribes to it.
76
+ state: computed(() => {
77
+ const value = observed();
78
+ return value && value !== connectedClient() ? value.snapshot : latest();
79
+ }),
80
+ client: computed(() => observed() ?? connectedClient()),
81
+ error: error.asReadonly(),
82
+ retry: () => attempt.update(value => value + 1),
83
+ };
84
+ }
@@ -30,13 +30,13 @@ export class RunicViewOutlet {
30
30
  component.setInput("page", selection.reference);
31
31
  });
32
32
  }
33
- static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.5", ngImport: i0, type: RunicViewOutlet, deps: [], target: i0.ɵɵFactoryTarget.Component });
34
- static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.5", 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: `
33
+ static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: RunicViewOutlet, deps: [], target: i0.ɵɵFactoryTarget.Component });
34
+ 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: `
35
35
  <ng-container #mount />
36
36
  @if (error(); as issue) { <p role="alert">{{ issue }}</p> }
37
37
  `, isInline: true });
38
38
  }
39
- i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.5", ngImport: i0, type: RunicViewOutlet, decorators: [{
39
+ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: RunicViewOutlet, decorators: [{
40
40
  type: Component,
41
41
  args: [{
42
42
  selector: "runic-view-outlet",
package/package.json CHANGED
@@ -1,18 +1,18 @@
1
1
  {
2
2
  "name": "@runic-artifex/angular",
3
- "version": "0.5.0-preview.2",
3
+ "version": "0.6.0-preview.1",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
7
- "types": "./dist/esm/view-outlet.d.ts",
8
- "import": "./dist/esm/view-outlet.js"
7
+ "types": "./dist/esm/index.d.ts",
8
+ "import": "./dist/esm/index.js"
9
9
  },
10
10
  "./package.json": "./package.json"
11
11
  },
12
12
  "peerDependencies": {
13
13
  "@angular/core": ">=20.3.26 <23"
14
14
  },
15
- "description": "Angular outlet for Runic Views",
15
+ "description": "Angular outlet and signals for Runic Views",
16
16
  "license": "MIT",
17
17
  "repository": {
18
18
  "type": "git",
@@ -37,18 +37,23 @@
37
37
  },
38
38
  "packageManager": "bun@1.4.2",
39
39
  "sideEffects": false,
40
- "main": "./dist/esm/view-outlet.js",
41
- "types": "./dist/esm/view-outlet.d.ts",
40
+ "main": "./dist/esm/index.js",
41
+ "types": "./dist/esm/index.d.ts",
42
42
  "scripts": {
43
43
  "build": "ngc -p tsconfig.json",
44
44
  "check": "ngc -p tsconfig.json --noEmit",
45
+ "test": "bun run --bun build && vitest run",
45
46
  "pack:check": "bun pm pack --dry-run"
46
47
  },
47
48
  "devDependencies": {
48
- "@angular/compiler": "22.1.5",
49
- "@angular/compiler-cli": "22.1.5",
50
- "@angular/core": "22.1.5",
51
- "typescript": "6.0.3"
52
- },
53
- "gitHead": "1870bc34b044abfdea9341769090e42b4096a0ec"
49
+ "@angular/common": "22.2.1",
50
+ "@angular/compiler": "22.2.1",
51
+ "@angular/compiler-cli": "22.2.1",
52
+ "@angular/core": "22.2.1",
53
+ "@angular/platform-browser": "22.2.1",
54
+ "happy-dom": "20.14.5",
55
+ "typescript": "6.0.3",
56
+ "vitest": "5.0.3"
57
+ },
58
+ "gitHead": "3026ada4e531cf58ba5081d8ee53b32b60f1ab6a"
54
59
  }