@runic-artifex/angular 0.18.0 → 0.20.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 +130 -23
- package/dist/fesm2022/runic-artifex-angular-experimental.mjs +285 -0
- package/dist/fesm2022/runic-artifex-angular-experimental.mjs.map +1 -0
- package/dist/fesm2022/runic-artifex-angular-forms.mjs +246 -0
- package/dist/fesm2022/runic-artifex-angular-forms.mjs.map +1 -0
- package/dist/fesm2022/runic-artifex-angular.mjs +975 -0
- package/dist/fesm2022/runic-artifex-angular.mjs.map +1 -0
- package/dist/types/runic-artifex-angular-experimental.d.ts +85 -0
- package/dist/types/runic-artifex-angular-forms.d.ts +72 -0
- package/dist/types/runic-artifex-angular.d.ts +626 -0
- package/package.json +20 -17
- package/dist/esm/experimental.d.ts +0 -39
- package/dist/esm/experimental.js +0 -64
- package/dist/esm/forms/index.d.ts +0 -2
- package/dist/esm/forms/index.js +0 -2
- package/dist/esm/forms/runic-field.directive.d.ts +0 -48
- package/dist/esm/forms/runic-field.directive.js +0 -195
- package/dist/esm/forms/signal-forms.d.ts +0 -19
- package/dist/esm/forms/signal-forms.js +0 -29
- package/dist/esm/index.d.ts +0 -24
- package/dist/esm/index.js +0 -25
- package/dist/esm/inject-appearance.d.ts +0 -19
- package/dist/esm/inject-appearance.js +0 -28
- package/dist/esm/inject-bridge-connection.d.ts +0 -22
- package/dist/esm/inject-bridge-connection.js +0 -26
- package/dist/esm/inject-collection-viewport.d.ts +0 -13
- package/dist/esm/inject-collection-viewport.js +0 -31
- package/dist/esm/inject-command.d.ts +0 -35
- package/dist/esm/inject-command.js +0 -33
- package/dist/esm/inject-field.d.ts +0 -66
- package/dist/esm/inject-field.js +0 -58
- package/dist/esm/inject-form.d.ts +0 -40
- package/dist/esm/inject-form.js +0 -48
- package/dist/esm/inject-latest-operation.d.ts +0 -25
- package/dist/esm/inject-latest-operation.js +0 -35
- package/dist/esm/inject-menu-bar.d.ts +0 -32
- package/dist/esm/inject-menu-bar.js +0 -39
- package/dist/esm/inject-operation.d.ts +0 -23
- package/dist/esm/inject-operation.js +0 -33
- package/dist/esm/inject-query-collection.d.ts +0 -29
- package/dist/esm/inject-query-collection.js +0 -64
- package/dist/esm/inject-text-field.d.ts +0 -55
- package/dist/esm/inject-text-field.js +0 -51
- package/dist/esm/inject-text.d.ts +0 -57
- package/dist/esm/inject-text.js +0 -107
- package/dist/esm/inject-view-resource.d.ts +0 -39
- package/dist/esm/inject-view-resource.js +0 -98
- package/dist/esm/inject-view.d.ts +0 -41
- package/dist/esm/inject-view.js +0 -67
- package/dist/esm/instance.d.ts +0 -34
- package/dist/esm/instance.js +0 -48
- package/dist/esm/view-outlet.d.ts +0 -101
- package/dist/esm/view-outlet.js +0 -177
package/README.md
CHANGED
|
@@ -13,6 +13,42 @@ bun add @runic-artifex/angular@preview @runic-artifex/views@preview
|
|
|
13
13
|
Previews are published under the `preview` dist-tag. Install the versions that
|
|
14
14
|
match your Runic SDK packages. Angular 22 is supported.
|
|
15
15
|
|
|
16
|
+
## Building with the Angular CLI or Vite
|
|
17
|
+
|
|
18
|
+
The package is in the Angular Package Format, so every Angular-aware build links
|
|
19
|
+
it: the Angular CLI (`@angular/build`), and Vite through the Analog Angular
|
|
20
|
+
plugin (`@analogjs/vite-plugin-angular`). `dotnet new runic-app --frontend
|
|
21
|
+
angular` starts with the Angular CLI, and `--angular-build vite` with Vite.
|
|
22
|
+
|
|
23
|
+
The Angular CLI runs no Vite plugins, so the Runic development tools come in
|
|
24
|
+
through `runicDevSessionProxy()` in the dev server's `proxyConfig` and an
|
|
25
|
+
import in `main.ts`
|
|
26
|
+
([`@runic-artifex/vite-plugin-runic`, "SvelteKit and Angular"](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/angular/../vite-plugin-runic/README.md#sveltekit-and-angular)).
|
|
27
|
+
With Vite, the page uses the Vite plugins the other frameworks use:
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
// vite.config.ts
|
|
31
|
+
import { defineConfig } from "vite";
|
|
32
|
+
import angular from "@analogjs/vite-plugin-angular";
|
|
33
|
+
import { runic } from "@runic-artifex/vite-plugin-runic";
|
|
34
|
+
import { runicTranslations } from "@runic-artifex/vite-plugin-runic-translations";
|
|
35
|
+
|
|
36
|
+
export default defineConfig({
|
|
37
|
+
base: "./",
|
|
38
|
+
plugins: [angular({ liveReload: true }), runic(), runicTranslations()],
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
That adds the Translations development loop (an edited message reaches the
|
|
43
|
+
page without a build), the Runic DevTools dock and the
|
|
44
|
+
[component build target](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/angular/../vite-plugin-runic/README.md#component-build-target),
|
|
45
|
+
which the Angular CLI cannot build ([components](#components-experimental)). `vite build` checks no types: run
|
|
46
|
+
`ngc -p tsconfig.app.json --noEmit` for that, as the template's `build` and
|
|
47
|
+
`typecheck` scripts do. Without `angular.json`, `dotnet runic dev` serves the
|
|
48
|
+
page with Vite. Tests run on Vitest with the same plugin, after
|
|
49
|
+
`getTestBed().initTestEnvironment(BrowserTestingModule, platformBrowserTesting())`
|
|
50
|
+
in a setup file that imports `@angular/compiler` first.
|
|
51
|
+
|
|
16
52
|
## Connecting a View
|
|
17
53
|
|
|
18
54
|
`injectView(source)` connects a generated page reference, or
|
|
@@ -140,7 +176,7 @@ export class CounterPage {
|
|
|
140
176
|
|
|
141
177
|
Bind a text input to a member with `injectTextField(view, read, write, options?)`,
|
|
142
178
|
which wraps the framework-neutral
|
|
143
|
-
[text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
179
|
+
[text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#text-inputs)
|
|
144
180
|
for the lifetime of the injection context:
|
|
145
181
|
|
|
146
182
|
```ts
|
|
@@ -183,7 +219,7 @@ text at once and hides the race.
|
|
|
183
219
|
|
|
184
220
|
For generated Views prefer `injectField(view, field, options?)`: pass a descriptor of the
|
|
185
221
|
generated `{View}Fields`, such as `EditorFields.title`. It wraps the framework-neutral
|
|
186
|
-
[field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
222
|
+
[field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#fields)
|
|
187
223
|
for every kind (text, numbers, booleans, enums) and returns signals and actions:
|
|
188
224
|
|
|
189
225
|
- `value`, `text` (what a text input shows: `1.` stays while typing `1.5`), `editing`,
|
|
@@ -232,7 +268,7 @@ A checked write's receipt is read: `rejected` keeps the draft with a `FieldError
|
|
|
232
268
|
`reset()` (take the producer's value); `committed-with-error` keeps the committed value
|
|
233
269
|
with a `FieldError`. A text that does not parse is a `FieldError` `invalid-text` with a `reason` and `arguments`:
|
|
234
270
|
`{{ title.error() | runicText }}` shows your text for it after `configureFieldErrorText`, in the window's language
|
|
235
|
-
([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
271
|
+
([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#translating-field-errors)).
|
|
236
272
|
`errors` follows the member's validation in the View's state:
|
|
237
273
|
|
|
238
274
|
```html
|
|
@@ -249,7 +285,7 @@ Since 0.16, `InvoiceFields.address.street` and `InvoiceFields.lines.at(line.id).
|
|
|
249
285
|
`injectField(view, InvoiceFields.lines.at(line.id).quantity)` in the row's component, or bind it with
|
|
250
286
|
`[runicField]`; `at(key)` returns the same descriptor for the same key. Such a field always writes checked, conflicts
|
|
251
287
|
only when another writer changed the same cell, and shows the messages .NET reports at the cell's validation path. See
|
|
252
|
-
[Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
288
|
+
[Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/angular/../views/README.md#fields-below-a-member-and-row-cells).
|
|
253
289
|
|
|
254
290
|
### Forms: `injectForm(fields, options?)`
|
|
255
291
|
|
|
@@ -380,7 +416,7 @@ reference; `injectView(this.page)` owns its connection and cleanup. Declare
|
|
|
380
416
|
decorator `@Input() page` or an optional `input<DocumentReference>()` does not
|
|
381
417
|
satisfy `ViewRegistry`. A component whose `page` input is a shared page
|
|
382
418
|
reference, `input.required<ResultPagePageReference>()` for a .NET
|
|
383
|
-
[`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
419
|
+
[`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/angular/../../dotnet/Runic.Application.Views/README.md#shared-clients)
|
|
384
420
|
interface, registers for each of its kinds without a cast:
|
|
385
421
|
`{ ...registryEntries(resultPageKinds, ResultPage), settings: Settings }`. Missing kinds render an English `<p role="alert">` in a
|
|
386
422
|
development build (`isDevMode()`); a production build renders nothing and
|
|
@@ -493,14 +529,14 @@ For example, a navigation command whose departure guard awaits a dialog's
|
|
|
493
529
|
answer never completes while the answer waits behind it. Order such commands
|
|
494
530
|
by dispatch instead: start the next one once the previous one has been sent,
|
|
495
531
|
as the Notes example's
|
|
496
|
-
[`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
532
|
+
[`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/examples/notes-view-first/Angular/src/app/window-operations.ts)
|
|
497
533
|
does for its navigation commands.
|
|
498
534
|
|
|
499
535
|
## Operations
|
|
500
536
|
|
|
501
537
|
`injectOperation(start, options?)` observes a generated `start<Command>()` operation
|
|
502
538
|
through the framework-neutral
|
|
503
|
-
[operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
539
|
+
[operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#operation-feedback-and-latest-selection)
|
|
504
540
|
for the lifetime of the injection context:
|
|
505
541
|
|
|
506
542
|
```ts
|
|
@@ -526,7 +562,7 @@ context.
|
|
|
526
562
|
|
|
527
563
|
`injectLatestOperation(options?)` admits only the newest of several reads, for example
|
|
528
564
|
loading the item the user selected last, through the framework-neutral
|
|
529
|
-
[latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
565
|
+
[latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#operation-feedback-and-latest-selection).
|
|
530
566
|
Each `run(intent)` replaces the queued intent and cancels the active read; the next
|
|
531
567
|
read starts only after the previous one reaches its terminal status and the intent's
|
|
532
568
|
optional `waitForCompletion` barrier:
|
|
@@ -558,7 +594,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
|
|
|
558
594
|
`BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a signal of a
|
|
559
595
|
`BridgeConnectionState`: `connecting`, `connected`, `reconnecting`, `lost` or `closed` (the
|
|
560
596
|
application closed the window, since 0.15; a closed set, see
|
|
561
|
-
[Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
597
|
+
[Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#connection-state)):
|
|
562
598
|
|
|
563
599
|
```ts
|
|
564
600
|
import { injectBridgeConnection } from "@runic-artifex/angular";
|
|
@@ -576,7 +612,7 @@ not observe and stays `connecting`. An invalid `lostAfter` throws a `RangeError`
|
|
|
576
612
|
`injectMenuBar(options?)` follows the declared menu bar of a Runic Desktop
|
|
577
613
|
window that leaves it to the page (`DesktopMenuBarPresentation.Page`) for the
|
|
578
614
|
lifetime of the injection context. It wraps `createMenuBarController` from
|
|
579
|
-
`@runic-artifex/views` (see [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
615
|
+
`@runic-artifex/views` (see [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#in-page-menu-bar))
|
|
580
616
|
and returns `{ state, invoke, handleKeyDown }`, where `state` is a signal of a
|
|
581
617
|
`MenuBarState`. The bar is rendered by the application's own menubar, for
|
|
582
618
|
example the CDK Menu's `cdkMenuBar`. Runic ships no menubar component.
|
|
@@ -601,7 +637,7 @@ it creates none and stays `connecting`.
|
|
|
601
637
|
### With the CDK Menu
|
|
602
638
|
|
|
603
639
|
The CDK's `cdkMenuBar` with `CdkMenuTrigger.open()` for `open` requests; the
|
|
604
|
-
[Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
640
|
+
[Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
|
|
605
641
|
items (`cdkMenuItemCheckbox`, `cdkMenuItemRadio` in a `cdkMenuGroup`) and is
|
|
606
642
|
tested with real keys:
|
|
607
643
|
|
|
@@ -655,11 +691,12 @@ export class AppMenuBar {
|
|
|
655
691
|
`injectText(() => source, () => fallback?)` is a signal of a text reference in
|
|
656
692
|
the window's language, and the `runicText` pipe does the same in templates; both
|
|
657
693
|
follow a language switch. Connect the page's Translations runtime once with
|
|
658
|
-
`configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
694
|
+
`configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
|
|
659
695
|
`injectWindowLocale()` reads the window's locale. `textLocaleSignal()` is the
|
|
660
696
|
locale that text is shown in, as one signal for the page that needs no injection
|
|
661
697
|
context; when the locale resolver reads it, templates that call `m.*()`, also
|
|
662
|
-
`OnPush` ones, render again on a language switch
|
|
698
|
+
`OnPush` ones, render again on a language switch, and during development also
|
|
699
|
+
when an edited message updates in place (it then notifies with the same locale):
|
|
663
700
|
|
|
664
701
|
```ts
|
|
665
702
|
// main.ts
|
|
@@ -669,6 +706,14 @@ configureTranslatedText({ ...locale, resolve, direction: localeDirection });
|
|
|
669
706
|
syncDocumentLocale(); // <html lang dir>
|
|
670
707
|
```
|
|
671
708
|
|
|
709
|
+
**Edited messages during development.** The Angular CLI's dev server
|
|
710
|
+
(`ng serve`) runs no Vite plugins, so a page served by it imports the ESM of the
|
|
711
|
+
.NET build and reloads after `dotnet build`. To see an edited message update in
|
|
712
|
+
place, with the page's state kept, build Angular with Vite
|
|
713
|
+
(`@analogjs/vite-plugin-angular`) and the Translations Vite plugin 0.12.0 or
|
|
714
|
+
later. An added, removed or renamed message, or changed inputs or markup, still
|
|
715
|
+
reload the page ([Edited messages in `vite dev`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
|
|
716
|
+
|
|
672
717
|
The pipe formats again only
|
|
673
718
|
when its value, fallback or the language changed. Under server rendering, call
|
|
674
719
|
`configureTranslatedText` behind `isPlatformBrowser`, or render on the server
|
|
@@ -688,7 +733,7 @@ with `resolveTextReference` and the request's locale.
|
|
|
688
733
|
injection context: the colour scheme, contrast and reduced motion of the page's
|
|
689
734
|
engine, combined with the desktop's text scale, accent colour, forced-colours
|
|
690
735
|
palette, contrast and motion that a Runic host pushes
|
|
691
|
-
([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
736
|
+
([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/views/README.md#appearance)). On the server every member is `null`.
|
|
692
737
|
|
|
693
738
|
```ts
|
|
694
739
|
readonly appearance = injectAppearance();
|
|
@@ -712,7 +757,7 @@ readonly message = computed(() => describeBridgeError(this.view.error()));
|
|
|
712
757
|
```
|
|
713
758
|
|
|
714
759
|
`instanceof` holds for errors from every copy of the package on the page.
|
|
715
|
-
[Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
760
|
+
[Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#errors-and-diagnostics)
|
|
716
761
|
lists the kinds. Any other value, such as an exception that your own connect
|
|
717
762
|
function or command callback throws, arrives unchanged.
|
|
718
763
|
|
|
@@ -763,10 +808,10 @@ application's own dialog.
|
|
|
763
808
|
departure before that is answered by the ViewModel's .NET fallback handler, or
|
|
764
809
|
fails closed without one.
|
|
765
810
|
|
|
766
|
-
The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
811
|
+
The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
|
|
767
812
|
has the .NET side and which View answers which departure. In a frontend test,
|
|
768
813
|
the generated mock's `interactions.<name>.request(input)` resolves with the
|
|
769
|
-
registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
814
|
+
registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#testing).
|
|
770
815
|
|
|
771
816
|
## View requests
|
|
772
817
|
|
|
@@ -804,15 +849,15 @@ the page painted the state the request was raised with, so the field of that
|
|
|
804
849
|
state is rendered; `signal` aborts when the handler is replaced or removed, the
|
|
805
850
|
client is disposed or the connection is lost. A request is never replayed: one
|
|
806
851
|
raised before the effect ran, or while the page is disconnected, is not
|
|
807
|
-
delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
852
|
+
delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#view-requests) for the rules, and in a frontend
|
|
808
853
|
test raise one with the generated mock's `requests.<name>.raise(input)` (the
|
|
809
|
-
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
854
|
+
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#testing)).
|
|
810
855
|
|
|
811
856
|
## Collection viewports
|
|
812
857
|
|
|
813
858
|
`injectCollectionViewport(element, options)` follows a fixed-row-height scroll
|
|
814
859
|
container and returns a signal with its
|
|
815
|
-
[`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
860
|
+
[`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#collectionviewportoptions)
|
|
816
861
|
range. Pass the container as a signal, such as a `viewChild`, and the options as
|
|
817
862
|
a function or signal, then send the range to the ViewModel from an effect:
|
|
818
863
|
|
|
@@ -844,7 +889,7 @@ export class RowsPage {
|
|
|
844
889
|
## Query collections
|
|
845
890
|
|
|
846
891
|
`injectQueryCollection(element, collection, options)` follows a scroll container for a
|
|
847
|
-
[query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
892
|
+
[query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it loads the rows the container shows,
|
|
848
893
|
with placeholders until they arrive, and lays them out with variable heights. `viewport` is a signal of the
|
|
849
894
|
`QueryViewport` (`items` with `top` and `size`, `totalSize`, `total`, `query`, `loading`, `error`); `observe(element,
|
|
850
895
|
index)` measures a rendered row, and `scrollToKey`, `scrollToIndex`, `setQuery` and `retry` act on the collection.
|
|
@@ -861,13 +906,13 @@ The package re-exports `installBackNavigation`, `installNavigationPath`,
|
|
|
861
906
|
`@runic-artifex/views` (since 0.16). Call the installs once where the page
|
|
862
907
|
starts, before or after mounting: the mouse's Back button and Alt+Left then go
|
|
863
908
|
back in the .NET window, and `#/customers/42` follows its path region. See
|
|
864
|
-
[Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
909
|
+
[Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/views/README.md#back-and-the-url).
|
|
865
910
|
|
|
866
911
|
## Hosted regions (experimental)
|
|
867
912
|
|
|
868
913
|
`RunicHostedRegion` from `@runic-artifex/angular/experimental` is the component whose
|
|
869
914
|
element is `<runic-hosted-region>` itself, a region where the host application shows
|
|
870
|
-
a hosted guest's Window ([hosted regions](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
915
|
+
a hosted guest's Window ([hosted regions](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/angular/../views/README.md#hosted-regions-experimental)). Projected content shows while no
|
|
871
916
|
guest page shows in it, and `state()` tells which state the region is in:
|
|
872
917
|
|
|
873
918
|
```html
|
|
@@ -878,3 +923,65 @@ guest page shows in it, and `state()` tells which state the region is in:
|
|
|
878
923
|
```
|
|
879
924
|
|
|
880
925
|
Add `RunicHostedRegion` to the component's `imports`.
|
|
926
|
+
|
|
927
|
+
## Components (experimental)
|
|
928
|
+
|
|
929
|
+
In [trusted component mode](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/angular/../../../docs/hosted-regions.md#component-mode) a
|
|
930
|
+
guest's Views render as a custom element in the host application's page. A
|
|
931
|
+
guest built with Vite and the Analog plugin builds its component with the
|
|
932
|
+
`component` target of `runic()`, and `runicComponentMount` from
|
|
933
|
+
`@runic-artifex/angular/experimental` is the entry's mount function:
|
|
934
|
+
|
|
935
|
+
```ts
|
|
936
|
+
// vite.config.ts
|
|
937
|
+
export default defineConfig({
|
|
938
|
+
base: "./",
|
|
939
|
+
plugins: [angular(), runic({ component: { entry: "src/component.ts", name: "service-widget" } })],
|
|
940
|
+
});
|
|
941
|
+
```
|
|
942
|
+
|
|
943
|
+
```ts
|
|
944
|
+
// src/component.ts
|
|
945
|
+
import { runicComponentMount } from "@runic-artifex/angular/experimental";
|
|
946
|
+
import { Widget } from "./app/widget";
|
|
947
|
+
|
|
948
|
+
export default runicComponentMount(Widget);
|
|
949
|
+
```
|
|
950
|
+
|
|
951
|
+
The entry imports `@angular/platform-browser`, an optional peer of this package
|
|
952
|
+
that every browser application has. Each element gets an Angular application of
|
|
953
|
+
its own (`createApplication`, zoneless), whose `RUNIC_INSTANCE` is the element's Runic instance, so
|
|
954
|
+
`injectView` and the other helpers connect to the guest's Window, never to the
|
|
955
|
+
host page's. The standalone component renders in the element's shadow root.
|
|
956
|
+
`runicComponentMount(Widget, { providers })` adds providers to each
|
|
957
|
+
application; leave out document-level ones such as the router's history,
|
|
958
|
+
`provideBrowserGlobalErrorListeners` and `Title`.
|
|
959
|
+
|
|
960
|
+
- **Styles.** Angular adds component styles to `document.head`, where they
|
|
961
|
+
would neither apply in the shadow root nor leave the host document unchanged.
|
|
962
|
+
Each application's shared styles host (`ɵSHARED_STYLES_HOST`) is replaced by
|
|
963
|
+
one that adopts every component style as a constructable stylesheet of the
|
|
964
|
+
shadow root: no `<style>` element, so the host page's Content-Security-Policy
|
|
965
|
+
needs no `'unsafe-inline'` in `style-src`. `styles` and `styleUrl` work with
|
|
966
|
+
`Emulated` (the default) and `None` encapsulation. A
|
|
967
|
+
`ViewEncapsulation.ShadowDom` component writes `<style>` elements into its own
|
|
968
|
+
shadow root, which needs `'unsafe-inline'`; prefer `Emulated`. CSS that the
|
|
969
|
+
entry imports (`import "./widget.css"`) becomes the element's stylesheets too.
|
|
970
|
+
Use `:host` rather than `:root`; the host page's custom properties inherit.
|
|
971
|
+
- **Teardown.** Removing the element destroys its application, its stylesheets
|
|
972
|
+
and its instance; the last element of the bundle also destroys the bundle's
|
|
973
|
+
Angular platform. An element removed while its application starts never
|
|
974
|
+
renders.
|
|
975
|
+
- **Document state.** The application registers no global listener and writes
|
|
976
|
+
no history, title or `<html lang dir>`. Keep the component's own code free of
|
|
977
|
+
them too: `host: { "(window:resize)": … }`, `Router` with a location strategy,
|
|
978
|
+
`Title`, and overlays attached to `document.body` (CDK Overlay) leave the
|
|
979
|
+
shadow root.
|
|
980
|
+
- **Text outside DI.** Code outside an injection context, such as an event
|
|
981
|
+
handler calling `defaultInstance()`, reaches the element's instance while one
|
|
982
|
+
element of the bundle is on the page
|
|
983
|
+
([components](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/angular/../views/README.md#components)).
|
|
984
|
+
|
|
985
|
+
The [hosted components example](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/angular/../../../examples/hosted-components/README.md#an-angular-widget)
|
|
986
|
+
shows a widget built this way. Angular's private `ɵSHARED_STYLES_HOST` is
|
|
987
|
+
covered by the package's `@angular/core` range (`>=22 <23`) and its tests.
|
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
import * as i0 from "@angular/core";
|
|
2
|
+
import { Component, DestroyRef, destroyPlatform, inject, input, output, provideZonelessChangeDetection, signal, ɵSHARED_STYLES_HOST } from "@angular/core";
|
|
3
|
+
import { defineHostedRegion } from "@runic-artifex/views/experimental";
|
|
4
|
+
import { createApplication } from "@angular/platform-browser";
|
|
5
|
+
import { provideRunicInstance } from "@runic-artifex/angular";
|
|
6
|
+
function runicComponentMount(component, options = {}) {
|
|
7
|
+
if (typeof component !== "function") throw new TypeError("runicComponentMount needs a standalone component.");
|
|
8
|
+
const extra = options.providers ?? [];
|
|
9
|
+
return ({ root, container, instance }) => {
|
|
10
|
+
let ended = false;
|
|
11
|
+
let application;
|
|
12
|
+
applications++;
|
|
13
|
+
createApplication({ providers: [
|
|
14
|
+
provideZonelessChangeDetection(),
|
|
15
|
+
provideRunicInstance(instance),
|
|
16
|
+
{
|
|
17
|
+
provide: ɵSHARED_STYLES_HOST,
|
|
18
|
+
useFactory: () => shadowRootStyles(root)
|
|
19
|
+
},
|
|
20
|
+
...extra
|
|
21
|
+
] }).then((created) => {
|
|
22
|
+
if (ended) {
|
|
23
|
+
created.destroy();
|
|
24
|
+
release();
|
|
25
|
+
return;
|
|
26
|
+
}
|
|
27
|
+
application = created;
|
|
28
|
+
try {
|
|
29
|
+
created.bootstrap(component, container);
|
|
30
|
+
} catch (error) {
|
|
31
|
+
console.error("The Angular component could not start.", error);
|
|
32
|
+
}
|
|
33
|
+
}, (error) => {
|
|
34
|
+
release();
|
|
35
|
+
if (!ended) console.error("The Angular component could not start.", error);
|
|
36
|
+
});
|
|
37
|
+
return () => {
|
|
38
|
+
ended = true;
|
|
39
|
+
const started = application;
|
|
40
|
+
application = void 0;
|
|
41
|
+
if (started === void 0) return;
|
|
42
|
+
try {
|
|
43
|
+
if (!started.destroyed) started.destroy();
|
|
44
|
+
} finally {
|
|
45
|
+
release();
|
|
46
|
+
}
|
|
47
|
+
};
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
let applications = 0;
|
|
51
|
+
function release() {
|
|
52
|
+
if (--applications === 0) destroyPlatform();
|
|
53
|
+
}
|
|
54
|
+
function shadowRootStyles(root) {
|
|
55
|
+
const styles = new ShadowRootStyles(root);
|
|
56
|
+
inject(DestroyRef).onDestroy(() => styles.destroy());
|
|
57
|
+
return styles;
|
|
58
|
+
}
|
|
59
|
+
var ShadowRootStyles = class {
|
|
60
|
+
#hosts = /* @__PURE__ */ new Set();
|
|
61
|
+
#inline = /* @__PURE__ */ new Map();
|
|
62
|
+
#external = /* @__PURE__ */ new Map();
|
|
63
|
+
constructor(root) {
|
|
64
|
+
this.addHost(root);
|
|
65
|
+
}
|
|
66
|
+
addStyles(styles, urls) {
|
|
67
|
+
for (const style of styles) {
|
|
68
|
+
const record = this.#inline.get(style);
|
|
69
|
+
if (record !== void 0) {
|
|
70
|
+
record.usage++;
|
|
71
|
+
continue;
|
|
72
|
+
}
|
|
73
|
+
const sheet = new CSSStyleSheet();
|
|
74
|
+
sheet.replaceSync(style);
|
|
75
|
+
this.#inline.set(style, {
|
|
76
|
+
usage: 1,
|
|
77
|
+
value: sheet
|
|
78
|
+
});
|
|
79
|
+
for (const host of this.#hosts) adopt(host, sheet);
|
|
80
|
+
}
|
|
81
|
+
for (const url of urls ?? []) {
|
|
82
|
+
const record = this.#external.get(url);
|
|
83
|
+
if (record !== void 0) {
|
|
84
|
+
record.usage++;
|
|
85
|
+
continue;
|
|
86
|
+
}
|
|
87
|
+
this.#external.set(url, {
|
|
88
|
+
usage: 1,
|
|
89
|
+
value: [...this.#hosts].map((host) => appendLink(host, url))
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
removeStyles(styles, urls) {
|
|
94
|
+
for (const style of styles) {
|
|
95
|
+
const record = this.#inline.get(style);
|
|
96
|
+
if (record === void 0 || --record.usage > 0) continue;
|
|
97
|
+
this.#inline.delete(style);
|
|
98
|
+
for (const host of this.#hosts) unadopt(host, [record.value]);
|
|
99
|
+
}
|
|
100
|
+
for (const url of urls ?? []) {
|
|
101
|
+
const record = this.#external.get(url);
|
|
102
|
+
if (record === void 0 || --record.usage > 0) continue;
|
|
103
|
+
this.#external.delete(url);
|
|
104
|
+
for (const link of record.value) link.remove();
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
addHost(node) {
|
|
108
|
+
if (!isShadowRoot(node) || this.#hosts.has(node)) return;
|
|
109
|
+
this.#hosts.add(node);
|
|
110
|
+
for (const { value } of this.#inline.values()) adopt(node, value);
|
|
111
|
+
for (const [url, record] of this.#external) record.value.push(appendLink(node, url));
|
|
112
|
+
}
|
|
113
|
+
removeHost(node) {
|
|
114
|
+
if (!isShadowRoot(node) || !this.#hosts.delete(node)) return;
|
|
115
|
+
unadopt(node, [...this.#inline.values()].map(({ value }) => value));
|
|
116
|
+
for (const record of this.#external.values()) for (const link of record.value.filter((link) => link.parentNode === node)) {
|
|
117
|
+
link.remove();
|
|
118
|
+
record.value.splice(record.value.indexOf(link), 1);
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
destroy() {
|
|
122
|
+
const sheets = [...this.#inline.values()].map(({ value }) => value);
|
|
123
|
+
for (const host of this.#hosts) unadopt(host, sheets);
|
|
124
|
+
for (const record of this.#external.values()) for (const link of record.value) link.remove();
|
|
125
|
+
this.#hosts.clear();
|
|
126
|
+
this.#inline.clear();
|
|
127
|
+
this.#external.clear();
|
|
128
|
+
}
|
|
129
|
+
};
|
|
130
|
+
function isShadowRoot(node) {
|
|
131
|
+
return typeof ShadowRoot !== "undefined" && node instanceof ShadowRoot;
|
|
132
|
+
}
|
|
133
|
+
function adopt(host, sheet) {
|
|
134
|
+
host.adoptedStyleSheets = [...host.adoptedStyleSheets, sheet];
|
|
135
|
+
}
|
|
136
|
+
function unadopt(host, sheets) {
|
|
137
|
+
if (sheets.length === 0) return;
|
|
138
|
+
host.adoptedStyleSheets = host.adoptedStyleSheets.filter((sheet) => !sheets.includes(sheet));
|
|
139
|
+
}
|
|
140
|
+
function appendLink(host, url) {
|
|
141
|
+
const link = host.ownerDocument.createElement("link");
|
|
142
|
+
link.rel = "stylesheet";
|
|
143
|
+
link.href = url;
|
|
144
|
+
return host.appendChild(link);
|
|
145
|
+
}
|
|
146
|
+
var RunicHostedRegion = class RunicHostedRegion {
|
|
147
|
+
name = input.required(...ngDevMode ? [{ debugName: "name" }] : /* istanbul ignore next */ []);
|
|
148
|
+
sizing = input(...ngDevMode ? [void 0, { debugName: "sizing" }] : /* istanbul ignore next */ []);
|
|
149
|
+
label = input(...ngDevMode ? [void 0, { debugName: "label" }] : /* istanbul ignore next */ []);
|
|
150
|
+
stateChange = output();
|
|
151
|
+
titleChange = output();
|
|
152
|
+
#state = signal("waiting", ...ngDevMode ? [{ debugName: "#state" }] : /* istanbul ignore next */ []);
|
|
153
|
+
state = this.#state.asReadonly();
|
|
154
|
+
constructor() {
|
|
155
|
+
defineHostedRegion();
|
|
156
|
+
}
|
|
157
|
+
stateChanged(event) {
|
|
158
|
+
const detail = event.detail;
|
|
159
|
+
this.#state.set(detail.state);
|
|
160
|
+
this.stateChange.emit({
|
|
161
|
+
state: detail.state,
|
|
162
|
+
previous: detail.previous
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
titleChanged(event) {
|
|
166
|
+
this.titleChange.emit(event.detail.title);
|
|
167
|
+
}
|
|
168
|
+
static ɵfac = i0.ɵɵngDeclareFactory({
|
|
169
|
+
minVersion: "12.0.0",
|
|
170
|
+
version: "22.2.3",
|
|
171
|
+
ngImport: i0,
|
|
172
|
+
type: RunicHostedRegion,
|
|
173
|
+
deps: [],
|
|
174
|
+
target: i0.ɵɵFactoryTarget.Component
|
|
175
|
+
});
|
|
176
|
+
static ɵcmp = i0.ɵɵngDeclareComponent({
|
|
177
|
+
minVersion: "17.1.0",
|
|
178
|
+
version: "22.2.3",
|
|
179
|
+
type: RunicHostedRegion,
|
|
180
|
+
isStandalone: true,
|
|
181
|
+
selector: "runic-hosted-region",
|
|
182
|
+
inputs: {
|
|
183
|
+
name: {
|
|
184
|
+
classPropertyName: "name",
|
|
185
|
+
publicName: "name",
|
|
186
|
+
isSignal: true,
|
|
187
|
+
isRequired: true,
|
|
188
|
+
transformFunction: null
|
|
189
|
+
},
|
|
190
|
+
sizing: {
|
|
191
|
+
classPropertyName: "sizing",
|
|
192
|
+
publicName: "sizing",
|
|
193
|
+
isSignal: true,
|
|
194
|
+
isRequired: false,
|
|
195
|
+
transformFunction: null
|
|
196
|
+
},
|
|
197
|
+
label: {
|
|
198
|
+
classPropertyName: "label",
|
|
199
|
+
publicName: "label",
|
|
200
|
+
isSignal: true,
|
|
201
|
+
isRequired: false,
|
|
202
|
+
transformFunction: null
|
|
203
|
+
}
|
|
204
|
+
},
|
|
205
|
+
outputs: {
|
|
206
|
+
stateChange: "stateChange",
|
|
207
|
+
titleChange: "titleChange"
|
|
208
|
+
},
|
|
209
|
+
host: {
|
|
210
|
+
listeners: {
|
|
211
|
+
"runicregionstatechange": "stateChanged($event)",
|
|
212
|
+
"runicregiontitlechange": "titleChanged($event)"
|
|
213
|
+
},
|
|
214
|
+
properties: {
|
|
215
|
+
"attr.name": "name()",
|
|
216
|
+
"attr.sizing": "sizing() ?? null",
|
|
217
|
+
"attr.label": "label() ?? null"
|
|
218
|
+
}
|
|
219
|
+
},
|
|
220
|
+
exportAs: ["runicHostedRegion"],
|
|
221
|
+
ngImport: i0,
|
|
222
|
+
template: `<div slot="fallback" style="display: contents"><ng-content /></div>`,
|
|
223
|
+
isInline: true
|
|
224
|
+
});
|
|
225
|
+
};
|
|
226
|
+
i0.ɵɵngDeclareClassMetadata({
|
|
227
|
+
minVersion: "12.0.0",
|
|
228
|
+
version: "22.2.3",
|
|
229
|
+
ngImport: i0,
|
|
230
|
+
type: RunicHostedRegion,
|
|
231
|
+
decorators: [{
|
|
232
|
+
type: Component,
|
|
233
|
+
args: [{
|
|
234
|
+
selector: "runic-hosted-region",
|
|
235
|
+
standalone: true,
|
|
236
|
+
exportAs: "runicHostedRegion",
|
|
237
|
+
host: {
|
|
238
|
+
"[attr.name]": "name()",
|
|
239
|
+
"[attr.sizing]": "sizing() ?? null",
|
|
240
|
+
"[attr.label]": "label() ?? null",
|
|
241
|
+
"(runicregionstatechange)": "stateChanged($event)",
|
|
242
|
+
"(runicregiontitlechange)": "titleChanged($event)"
|
|
243
|
+
},
|
|
244
|
+
template: `<div slot="fallback" style="display: contents"><ng-content /></div>`
|
|
245
|
+
}]
|
|
246
|
+
}],
|
|
247
|
+
ctorParameters: () => [],
|
|
248
|
+
propDecorators: {
|
|
249
|
+
name: [{
|
|
250
|
+
type: i0.Input,
|
|
251
|
+
args: [{
|
|
252
|
+
isSignal: true,
|
|
253
|
+
alias: "name",
|
|
254
|
+
required: true
|
|
255
|
+
}]
|
|
256
|
+
}],
|
|
257
|
+
sizing: [{
|
|
258
|
+
type: i0.Input,
|
|
259
|
+
args: [{
|
|
260
|
+
isSignal: true,
|
|
261
|
+
alias: "sizing",
|
|
262
|
+
required: false
|
|
263
|
+
}]
|
|
264
|
+
}],
|
|
265
|
+
label: [{
|
|
266
|
+
type: i0.Input,
|
|
267
|
+
args: [{
|
|
268
|
+
isSignal: true,
|
|
269
|
+
alias: "label",
|
|
270
|
+
required: false
|
|
271
|
+
}]
|
|
272
|
+
}],
|
|
273
|
+
stateChange: [{
|
|
274
|
+
type: i0.Output,
|
|
275
|
+
args: ["stateChange"]
|
|
276
|
+
}],
|
|
277
|
+
titleChange: [{
|
|
278
|
+
type: i0.Output,
|
|
279
|
+
args: ["titleChange"]
|
|
280
|
+
}]
|
|
281
|
+
}
|
|
282
|
+
});
|
|
283
|
+
export { RunicHostedRegion, runicComponentMount };
|
|
284
|
+
|
|
285
|
+
//# sourceMappingURL=runic-artifex-angular-experimental.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"runic-artifex-angular-experimental.mjs","names":["SHARED_STYLES_HOST"],"sources":["../../src/component.ts","../../src/experimental.ts"],"sourcesContent":["// Trusted component mode for Angular guests (docs/hosted-regions.md, \"Component mode\"): the mount function that the\n// `component` build target of `@runic-artifex/vite-plugin-runic` calls for each element. It starts one Angular\n// application per element, zoneless, with the element's Runic instance, and renders the guest's standalone component\n// into the element's shadow root.\n//\n// The component contract (`@runic-artifex/views/component`) allows no document stylesheets. Angular adds component\n// styles as `<style>` elements to a style host: `document.head`, or the shadow root that contains the root component.\n// Inside a shadow root they would apply, but a `<style>` element needs `'unsafe-inline'` in the host page's\n// `style-src`, which the page should not have to grant. So the application's shared styles host (Angular's\n// `ɵSHARED_STYLES_HOST`, which `DomRendererFactory2` and the root component use) is replaced by one that adopts each\n// style as a constructable stylesheet in the shadow roots Angular hands it and nowhere else: nothing reaches the host\n// document, and the host page's Content-Security-Policy does not apply to the sheets.\nimport {\n DestroyRef,\n destroyPlatform,\n inject,\n type ApplicationRef,\n type EnvironmentProviders,\n type Provider,\n type Type,\n provideZonelessChangeDetection,\n ɵSHARED_STYLES_HOST as SHARED_STYLES_HOST,\n} from \"@angular/core\";\nimport { createApplication } from \"@angular/platform-browser\";\nimport type { RunicComponentMount } from \"@runic-artifex/views/component\";\n// The primary entry point, not ./instance.js: this entry point's bundle would get a second RUNIC_INSTANCE token.\nimport { provideRunicInstance } from \"@runic-artifex/angular\";\n\n/** Options of {@link runicComponentMount}. */\nexport interface RunicComponentMountOptions {\n /**\n * The providers of each element's application, after the ones the mount function adds (zoneless change detection,\n * the element's Runic instance and the shadow root's styles). Leave out the document-level ones, such as the router's\n * history, `provideBrowserGlobalErrorListeners` and `Title`: a component touches no document-level state.\n */\n readonly providers?: ReadonlyArray<Provider | EnvironmentProviders>;\n}\n\n/**\n * The mount function of an Angular guest's component: the default export of the component build's entry module.\n * Each element of the component gets an Angular application of its own, zoneless, whose `RUNIC_INSTANCE` is the\n * element's Runic instance, and `component`, a standalone component, renders in the element's shadow root. Its styles\n * (`styles`, `styleUrl`, with any `ViewEncapsulation` but `ShadowDom`) become constructable stylesheets of that shadow\n * root. Removing the element destroys the application and removes its stylesheets.\n *\n * ```ts\n * // src/component.ts, the `component.entry` of runic() in vite.config.ts\n * import { runicComponentMount } from \"@runic-artifex/angular/experimental\";\n * import { Widget } from \"./app/widget\";\n *\n * export default runicComponentMount(Widget);\n * ```\n */\nexport function runicComponentMount(component: Type<unknown>, options: RunicComponentMountOptions = {}): RunicComponentMount {\n if (typeof component !== \"function\") throw new TypeError(\"runicComponentMount needs a standalone component.\");\n const extra = options.providers ?? [];\n return ({ root, container, instance }) => {\n let ended = false;\n let application: ApplicationRef | undefined;\n applications++;\n // createApplication resolves after the application's initializers; the element may be removed before.\n createApplication({\n providers: [\n provideZonelessChangeDetection(),\n provideRunicInstance(instance),\n { provide: SHARED_STYLES_HOST, useFactory: () => shadowRootStyles(root) },\n ...extra,\n ],\n }).then((created) => {\n if (ended) {\n created.destroy();\n release();\n return;\n }\n application = created;\n try { created.bootstrap(component, container); }\n catch (error) { console.error(\"The Angular component could not start.\", error); }\n }, (error: unknown) => {\n release();\n if (!ended) console.error(\"The Angular component could not start.\", error);\n });\n return () => {\n ended = true;\n const started = application;\n application = undefined;\n if (started === undefined) return;\n try { if (!started.destroyed) started.destroy(); }\n finally { release(); }\n };\n };\n}\n\n// The applications of this bundle that started or are starting. The bundle's copy of Angular creates its platform\n// with the first; the last one destroys it, and with it what the platform added to the page (in development builds,\n// the Angular DevTools listener on `window`).\nlet applications = 0;\n\nfunction release(): void {\n if (--applications === 0) destroyPlatform();\n}\n\n// Ends with the application's injector.\nfunction shadowRootStyles(root: ShadowRoot): ShadowRootStyles {\n const styles = new ShadowRootStyles(root);\n inject(DestroyRef).onDestroy(() => styles.destroy());\n return styles;\n}\n\ninterface Usage<T> {\n usage: number;\n readonly value: T;\n}\n\n/**\n * The shared styles host of one element's application. Angular adds the shadow root that contains the root component\n * as a host (and the shadow root of each `ViewEncapsulation.ShadowDom` component); any other host, such as\n * `document.head` for a component created outside the shadow root, gets nothing.\n */\nclass ShadowRootStyles {\n readonly #hosts = new Set<ShadowRoot>();\n readonly #inline = new Map<string, Usage<CSSStyleSheet>>();\n // A style URL of a component built with external runtime styles: a <link> in each shadow root.\n readonly #external = new Map<string, Usage<HTMLLinkElement[]>>();\n\n constructor(root: ShadowRoot) {\n this.addHost(root);\n }\n\n addStyles(styles: readonly string[], urls?: readonly string[]): void {\n for (const style of styles) {\n const record = this.#inline.get(style);\n if (record !== undefined) {\n record.usage++;\n continue;\n }\n const sheet = new CSSStyleSheet();\n sheet.replaceSync(style);\n this.#inline.set(style, { usage: 1, value: sheet });\n for (const host of this.#hosts) adopt(host, sheet);\n }\n for (const url of urls ?? []) {\n const record = this.#external.get(url);\n if (record !== undefined) {\n record.usage++;\n continue;\n }\n this.#external.set(url, { usage: 1, value: [...this.#hosts].map((host) => appendLink(host, url)) });\n }\n }\n\n removeStyles(styles: readonly string[], urls?: readonly string[]): void {\n for (const style of styles) {\n const record = this.#inline.get(style);\n if (record === undefined || --record.usage > 0) continue;\n this.#inline.delete(style);\n for (const host of this.#hosts) unadopt(host, [record.value]);\n }\n for (const url of urls ?? []) {\n const record = this.#external.get(url);\n if (record === undefined || --record.usage > 0) continue;\n this.#external.delete(url);\n for (const link of record.value) link.remove();\n }\n }\n\n addHost(node: Node): void {\n if (!isShadowRoot(node) || this.#hosts.has(node)) return;\n this.#hosts.add(node);\n for (const { value } of this.#inline.values()) adopt(node, value);\n for (const [url, record] of this.#external) record.value.push(appendLink(node, url));\n }\n\n removeHost(node: Node): void {\n if (!isShadowRoot(node) || !this.#hosts.delete(node)) return;\n unadopt(node, [...this.#inline.values()].map(({ value }) => value));\n for (const record of this.#external.values()) {\n for (const link of record.value.filter((link) => link.parentNode === node)) {\n link.remove();\n record.value.splice(record.value.indexOf(link), 1);\n }\n }\n }\n\n destroy(): void {\n const sheets = [...this.#inline.values()].map(({ value }) => value);\n for (const host of this.#hosts) unadopt(host, sheets);\n for (const record of this.#external.values()) for (const link of record.value) link.remove();\n this.#hosts.clear();\n this.#inline.clear();\n this.#external.clear();\n }\n}\n\nfunction isShadowRoot(node: Node): node is ShadowRoot {\n return typeof ShadowRoot !== \"undefined\" && node instanceof ShadowRoot;\n}\n\nfunction adopt(host: ShadowRoot, sheet: CSSStyleSheet): void {\n host.adoptedStyleSheets = [...host.adoptedStyleSheets, sheet];\n}\n\nfunction unadopt(host: ShadowRoot, sheets: readonly CSSStyleSheet[]): void {\n if (sheets.length === 0) return;\n host.adoptedStyleSheets = host.adoptedStyleSheets.filter((sheet) => !sheets.includes(sheet));\n}\n\nfunction appendLink(host: ShadowRoot, url: string): HTMLLinkElement {\n const link = host.ownerDocument.createElement(\"link\");\n link.rel = \"stylesheet\";\n link.href = url;\n return host.appendChild(link);\n}\n","// The experimental entry (docs/experimental.md, \"npm packages\"): importing it is the opt-in. Hosted regions (0.18): the\n// .NET side is the experimental family RUNICDESK103.\nimport { Component, input, output, signal } from \"@angular/core\";\nimport {\n defineHostedRegion,\n type HostedRegionSizing,\n type HostedRegionState,\n type HostedRegionStateChangeDetail,\n type HostedRegionTitleChangeDetail,\n} from \"@runic-artifex/views/experimental\";\n\nexport type { HostedRegionSizing, HostedRegionState, RunicHostedRegionElement } from \"@runic-artifex/views/experimental\";\n// Trusted component mode (0.20): an Angular guest's component build.\nexport { runicComponentMount, type RunicComponentMountOptions } from \"./component.js\";\n\n/** The `stateChange` output of {@link RunicHostedRegion}. */\nexport interface HostedRegionStateChange {\n readonly state: HostedRegionState;\n readonly previous: HostedRegionState;\n}\n\n/**\n * A region where the host application shows a hosted guest's Window: the component's element is\n * `<runic-hosted-region>` itself, and the page never gets a reference to its frame. Projected content shows while no\n * guest page shows in the region; `state()` tells which state it is in:\n *\n * ```html\n * <runic-hosted-region #check name=\"check\" style=\"height: 420px\" (stateChange)=\"onState($event)\">\n * @if (check.state() === \"ended\") { <button (click)=\"runAgain()\">Run the check again</button> }\n * @else { <p>Starting the check…</p> }\n * </runic-hosted-region>\n * ```\n */\n@Component({\n selector: \"runic-hosted-region\",\n standalone: true,\n exportAs: \"runicHostedRegion\",\n host: {\n \"[attr.name]\": \"name()\",\n \"[attr.sizing]\": \"sizing() ?? null\",\n \"[attr.label]\": \"label() ?? null\",\n \"(runicregionstatechange)\": \"stateChanged($event)\",\n \"(runicregiontitlechange)\": \"titleChanged($event)\",\n },\n template: `<div slot=\"fallback\" style=\"display: contents\"><ng-content /></div>`,\n})\nexport class RunicHostedRegion {\n /** The region's name, which the host application's policy embeds a guest's Window in. */\n readonly name = input.required<string>();\n /** `fill` (the default): the page's layout sets the height. `content-height`: the guest's page does. */\n readonly sizing = input<HostedRegionSizing | undefined>();\n /** The region's accessible name; without it, the guest page's title. */\n readonly label = input<string | undefined>();\n readonly stateChange = output<HostedRegionStateChange>();\n /** The guest page's title as the host passed it on, or `null`. */\n readonly titleChange = output<string | null>();\n readonly #state = signal<HostedRegionState>(\"waiting\");\n /** What the region shows now. */\n readonly state = this.#state.asReadonly();\n\n constructor() {\n defineHostedRegion();\n }\n\n protected stateChanged(event: Event): void {\n const detail = (event as CustomEvent<HostedRegionStateChangeDetail>).detail;\n this.#state.set(detail.state);\n this.stateChange.emit({ state: detail.state, previous: detail.previous });\n }\n\n protected titleChanged(event: Event): void {\n this.titleChange.emit((event as CustomEvent<HostedRegionTitleChangeDetail>).detail.title);\n }\n}\n"],"mappings":"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"}
|