@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 +51 -5
- package/dist/esm/index.d.ts +2 -0
- package/dist/esm/index.js +2 -0
- package/dist/esm/inject-view.d.ts +41 -0
- package/dist/esm/inject-view.js +84 -0
- package/dist/esm/view-outlet.js +3 -3
- package/package.json +17 -12
package/README.md
CHANGED
|
@@ -1,7 +1,53 @@
|
|
|
1
1
|
# `@runic-artifex/angular`
|
|
2
2
|
|
|
3
|
-
Angular outlet for generated Runic View
|
|
4
|
-
|
|
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
|
|
19
|
-
and cleanup. Missing kinds render an alert. The generated
|
|
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,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
|
+
}
|
package/dist/esm/view-outlet.js
CHANGED
|
@@ -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
|
|
34
|
-
static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1
|
|
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
|
|
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.
|
|
3
|
+
"version": "0.6.0-preview.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"exports": {
|
|
6
6
|
".": {
|
|
7
|
-
"types": "./dist/esm/
|
|
8
|
-
"import": "./dist/esm/
|
|
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/
|
|
41
|
-
"types": "./dist/esm/
|
|
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/
|
|
49
|
-
"@angular/compiler
|
|
50
|
-
"@angular/
|
|
51
|
-
"
|
|
52
|
-
|
|
53
|
-
|
|
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
|
}
|