@runic-artifex/angular 0.15.1 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -140,7 +140,7 @@ export class CounterPage {
140
140
 
141
141
  Bind a text input to a member with `injectTextField(view, read, write, options?)`,
142
142
  which wraps the framework-neutral
143
- [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#text-inputs)
143
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#text-inputs)
144
144
  for the lifetime of the injection context:
145
145
 
146
146
  ```ts
@@ -183,7 +183,7 @@ text at once and hides the race.
183
183
 
184
184
  For generated Views prefer `injectField(view, field, options?)`: pass a descriptor of the
185
185
  generated `{View}Fields`, such as `EditorFields.title`. It wraps the framework-neutral
186
- [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#fields)
186
+ [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#fields)
187
187
  for every kind (text, numbers, booleans, enums) and returns signals and actions:
188
188
 
189
189
  - `value`, `text` (what a text input shows: `1.` stays while typing `1.5`), `editing`,
@@ -230,7 +230,10 @@ A checked write's receipt is read: `rejected` keeps the draft with a `FieldError
230
230
  `rejected`; `conflict` keeps the draft, sets `conflict` to the producer's
231
231
  `{ value, version }` and writes nothing until `retry()` (write the draft over it) or
232
232
  `reset()` (take the producer's value); `committed-with-error` keeps the committed value
233
- with a `FieldError`. `errors` follows the member's validation in the View's state:
233
+ with a `FieldError`. A text that does not parse is a `FieldError` `invalid-text` with a `reason` and `arguments`:
234
+ `{{ 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.17.0/packages/web/views#translating-field-errors)).
236
+ `errors` follows the member's validation in the View's state:
234
237
 
235
238
  ```html
236
239
  @if (title.conflict(); as theirs) {
@@ -239,6 +242,26 @@ with a `FieldError`. `errors` follows the member's validation in the View's stat
239
242
  }
240
243
  ```
241
244
 
245
+ ### Row cells and nested members
246
+
247
+ Since 0.16, `InvoiceFields.address.street` and `InvoiceFields.lines.at(line.id).quantity` are fields too
248
+ (`field-paths/1`): a member of an object member, and a cell of a row that .NET edits with `[RunicRowEditor]`. Call
249
+ `injectField(view, InvoiceFields.lines.at(line.id).quantity)` in the row's component, or bind it with
250
+ `[runicField]`; `at(key)` returns the same descriptor for the same key. Such a field always writes checked, conflicts
251
+ 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.17.0/packages/web/angular/../views/README.md#fields-below-a-member-and-row-cells).
253
+
254
+ ### Forms: `injectForm(fields, options?)`
255
+
256
+ Signals over `injectField` handles (`dirty`, `editing`, `validating`, `pending`, `valid`, `submitting`, `state`), and a
257
+ `submit` that writes every field before its command (`createFormController` in `@runic-artifex/views`). It needs no
258
+ injection context.
259
+
260
+ ```ts
261
+ readonly form = injectForm({ title: this.title, step: this.step }, { dirty: computed(() => this.editor.state()?.isDirty === true) });
262
+ // <button [disabled]="!form.valid() || form.submitting()" (click)="form.submit(() => editor.client()!.save())">Save</button>
263
+ ```
264
+
242
265
  ### `[runicField]` and Reactive Forms
243
266
 
244
267
  `@runic-artifex/angular/forms` needs `@angular/forms` (an optional peer; the main
@@ -355,8 +378,15 @@ it outside its own signal tracking. A component's `page` input receives that
355
378
  reference; `injectView(this.page)` owns its connection and cleanup. Declare
356
379
  `page` as a required signal input, `input.required<DocumentReference>()`: a
357
380
  decorator `@Input() page` or an optional `input<DocumentReference>()` does not
358
- satisfy `ViewRegistry`. Missing kinds render an English `<p role="alert">`. The
359
- generated TypeScript client can also be used directly without Angular.
381
+ satisfy `ViewRegistry`. A component whose `page` input is a shared page
382
+ reference, `input.required<ResultPagePageReference>()` for a .NET
383
+ [`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/angular/../../dotnet/Runic.Application.Views/README.md#shared-clients)
384
+ interface, registers for each of its kinds without a cast:
385
+ `{ ...registryEntries(resultPageKinds, ResultPage), settings: Settings }`. Missing kinds render an English `<p role="alert">` in a
386
+ development build (`isDevMode()`); a production build renders nothing and
387
+ reports the kind once through the page's error reporting
388
+ (`installErrorReporting`, `onBridgeDiagnostic`). The generated TypeScript client
389
+ can also be used directly without Angular.
360
390
 
361
391
  The `missing` input replaces that alert with a template, for example with
362
392
  localized text. Its context (`ViewOutletMissingContext`) passes the reference
@@ -368,6 +398,74 @@ whose kind has no component as `$implicit` and as `content`, and its markup
368
398
  <ng-template #missingView let-page><p role="alert">{{ missingText(page.kind) }}</p></ng-template>
369
399
  ```
370
400
 
401
+ ### Region collections
402
+
403
+ A .NET `[RunicRegionCollection]` member, such as `state.documents`, lists
404
+ regions that each keep their own back stack. `<runic-region-outlets>`
405
+ (`RegionOutlets`) renders a `ViewOutlet` for each region, tracked by the
406
+ region's key, inside a `<div data-region-key>`. The default
407
+ `mode="keep-mounted"` keeps every region mounted and sets `hidden` and an inline
408
+ `display: none` on all but the selected one, so a tab keeps its component,
409
+ scroll position and unsent input. Author CSS cannot show a hidden panel without
410
+ `!important`. `mode="selected"` renders only the selected region. Projected
411
+ content renders while there is no region, and `missing` is passed to each
412
+ outlet. A region with `content: null` renders nothing.
413
+
414
+ The package has no tab bar. Build one with `regionEntries` and the generated
415
+ `selectDocuments(key)` and `closeDocuments(key)`. The `panelProps` input is a function that returns attributes
416
+ (`RegionPanelAttributes`) for each region's wrapper, such as `id`,
417
+ `role="tabpanel"` and `aria-labelledby`, so each tab can name its panel in
418
+ `aria-controls`. A `null` value leaves an attribute out. `hidden`, `style` and
419
+ `data-region-key` stay controlled by the outlet and are ignored.
420
+
421
+ ```html
422
+ <div role="tablist">
423
+ @for (tab of tabs(); track tab.key) {
424
+ <button [id]="tabId(tab.key)" role="tab" [attr.aria-selected]="tab.selected" [attr.aria-controls]="panelId(tab.key)"
425
+ (click)="client()?.selectDocuments(tab.key)">
426
+ {{ tab.content?.kind ?? "Empty" }}
427
+ </button>
428
+ <button aria-label="Close" (click)="close(tab.key)">×</button>
429
+ }
430
+ </div>
431
+ <runic-region-outlets [collection]="state()?.documents" [registry]="documentPages" [panelProps]="panel">
432
+ No open documents
433
+ </runic-region-outlets>
434
+ ```
435
+
436
+ ```ts
437
+ readonly tabs = computed(() => regionEntries(this.state()?.documents));
438
+ readonly tabId = (key: string) => `document-tab-${key}`;
439
+ readonly panelId = (key: string) => `document-panel-${key}`;
440
+ readonly panel = (tab: RegionEntry<DocumentReference>): RegionPanelAttributes =>
441
+ ({ id: this.panelId(tab.key), role: "tabpanel", "aria-labelledby": this.tabId(tab.key) });
442
+ private readonly injector = inject(Injector);
443
+
444
+ async close(key: string) {
445
+ if ((await this.client()?.closeDocuments(key))?.kind !== "Committed") return;
446
+ afterNextRender(() => {
447
+ const selected = selectedRegion(this.state()?.documents);
448
+ if (selected) document.getElementById(this.tabId(selected.key))?.focus();
449
+ }, { injector: this.injector });
450
+ }
451
+ ```
452
+
453
+ `selected` changes only when a switch or close commits. A departure guard can
454
+ keep the current tab, so highlight `selected` and do not move the highlight
455
+ before the request settles. `select…` and `close…` resolve to the .NET
456
+ `NavigationOutcome`, such as `{ kind: "Rejected", rejection: "Guard" }`.
457
+
458
+ Closing the selected tab removes its button, and the next tab becomes selected
459
+ when the close commits. After `closeDocuments` resolves with `kind: "Committed"`,
460
+ move focus to the button of the new selected tab, as `close` above does.
461
+
462
+ In both modes the region collection keeps presenting every region's content,
463
+ so the pages of hidden tabs stay live and still receive state. `"selected"`
464
+ mode only unmounts the components of the regions that are not selected.
465
+
466
+ `regionEntries`, `selectedRegion` and the region types are re-exported from
467
+ `@runic-artifex/views`.
468
+
371
469
  ## Commands
372
470
 
373
471
  `injectCommand(command)` returns `run(...args)` and `pending`, `error` and
@@ -395,14 +493,14 @@ For example, a navigation command whose departure guard awaits a dialog's
395
493
  answer never completes while the answer waits behind it. Order such commands
396
494
  by dispatch instead: start the next one once the previous one has been sent,
397
495
  as the Notes example's
398
- [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/examples/notes-view-first/Angular/src/app/window-operations.ts)
496
+ [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/examples/notes-view-first/Angular/src/app/window-operations.ts)
399
497
  does for its navigation commands.
400
498
 
401
499
  ## Operations
402
500
 
403
501
  `injectOperation(start, options?)` observes a generated `start<Command>()` operation
404
502
  through the framework-neutral
405
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#operation-feedback-and-latest-selection)
503
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#operation-feedback-and-latest-selection)
406
504
  for the lifetime of the injection context:
407
505
 
408
506
  ```ts
@@ -428,7 +526,7 @@ context.
428
526
 
429
527
  `injectLatestOperation(options?)` admits only the newest of several reads, for example
430
528
  loading the item the user selected last, through the framework-neutral
431
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#operation-feedback-and-latest-selection).
529
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#operation-feedback-and-latest-selection).
432
530
  Each `run(intent)` replaces the queued intent and cancels the active read; the next
433
531
  read starts only after the previous one reaches its terminal status and the intent's
434
532
  optional `waitForCompletion` barrier:
@@ -460,7 +558,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
460
558
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a signal of a
461
559
  `BridgeConnectionState`: `connecting`, `connected`, `reconnecting`, `lost` or `closed` (the
462
560
  application closed the window, since 0.15; a closed set, see
463
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#connection-state)):
561
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#connection-state)):
464
562
 
465
563
  ```ts
466
564
  import { injectBridgeConnection } from "@runic-artifex/angular";
@@ -478,7 +576,7 @@ not observe and stays `connecting`. An invalid `lostAfter` throws a `RangeError`
478
576
  `injectMenuBar(options?)` follows the declared menu bar of a Runic Desktop
479
577
  window that leaves it to the page (`DesktopMenuBarPresentation.Page`) for the
480
578
  lifetime of the injection context. It wraps `createMenuBarController` from
481
- `@runic-artifex/views` (see [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#in-page-menu-bar))
579
+ `@runic-artifex/views` (see [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#in-page-menu-bar))
482
580
  and returns `{ state, invoke, handleKeyDown }`, where `state` is a signal of a
483
581
  `MenuBarState`. The bar is rendered by the application's own menubar, for
484
582
  example the CDK Menu's `cdkMenuBar`. Runic ships no menubar component.
@@ -503,7 +601,7 @@ it creates none and stays `connecting`.
503
601
  ### With the CDK Menu
504
602
 
505
603
  The CDK's `cdkMenuBar` with `CdkMenuTrigger.open()` for `open` requests; the
506
- [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
604
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
507
605
  items (`cdkMenuItemCheckbox`, `cdkMenuItemRadio` in a `cdkMenuGroup`) and is
508
606
  tested with real keys:
509
607
 
@@ -552,6 +650,51 @@ export class AppMenuBar {
552
650
  }
553
651
  ```
554
652
 
653
+ ## Translated text
654
+
655
+ `injectText(() => source, () => fallback?)` is a signal of a text reference in
656
+ the window's language, and the `runicText` pipe does the same in templates; both
657
+ 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.17.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
659
+ `injectWindowLocale()` reads the window's locale. `textLocaleSignal()` is the
660
+ locale that text is shown in, as one signal for the page that needs no injection
661
+ context; when the locale resolver reads it, templates that call `m.*()`, also
662
+ `OnPush` ones, render again on a language switch:
663
+
664
+ ```ts
665
+ // main.ts
666
+ const textLocale = textLocaleSignal();
667
+ configureLocaleResolver(() => textLocale() ?? locale.getLocale());
668
+ configureTranslatedText({ ...locale, resolve, direction: localeDirection });
669
+ syncDocumentLocale(); // <html lang dir>
670
+ ```
671
+
672
+ The pipe formats again only
673
+ when its value, fallback or the language changed. Under server rendering, call
674
+ `configureTranslatedText` behind `isPlatformBrowser`, or render on the server
675
+ with `resolveTextReference` and the request's locale.
676
+
677
+ ```ts
678
+ @Component({
679
+ imports: [RunicTextPipe],
680
+ template: `<p>{{ view.state()?.status | runicText }}</p>
681
+ @for (error of view.state()?.validation.errors; track $index) { <li>{{ error.text | runicText: error.message }}</li> }`,
682
+ })
683
+ ```
684
+
685
+ ## Appearance
686
+
687
+ `injectAppearance()` is the page's appearance as a signal for the lifetime of the
688
+ injection context: the colour scheme, contrast and reduced motion of the page's
689
+ engine, combined with the desktop's text scale, accent colour, forced-colours
690
+ palette, contrast and motion that a Runic host pushes
691
+ ([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/views/README.md#appearance)). On the server every member is `null`.
692
+
693
+ ```ts
694
+ readonly appearance = injectAppearance();
695
+ readonly fontSize = computed(() => `${this.appearance().textScale ?? 1}rem`);
696
+ ```
697
+
555
698
  ## Errors
556
699
 
557
700
  The `error()` signal of `injectView` and of a command or operation is typed
@@ -569,7 +712,7 @@ readonly message = computed(() => describeBridgeError(this.view.error()));
569
712
  ```
570
713
 
571
714
  `instanceof` holds for errors from every copy of the package on the page.
572
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#errors-and-diagnostics)
715
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#errors-and-diagnostics)
573
716
  lists the kinds. Any other value, such as an exception that your own connect
574
717
  function or command callback throws, arrives unchanged.
575
718
 
@@ -620,16 +763,56 @@ application's own dialog.
620
763
  departure before that is answered by the ViewModel's .NET fallback handler, or
621
764
  fails closed without one.
622
765
 
623
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
766
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
624
767
  has the .NET side and which View answers which departure. In a frontend test,
625
768
  the generated mock's `interactions.<name>.request(input)` resolves with the
626
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#testing).
769
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#testing).
770
+
771
+ ## View requests
772
+
773
+ A `ViewRequest<T>` property of the ViewModel asks the View for a one-way
774
+ presentation action, such as focusing a field or showing a toast, and is
775
+ `client.requests.<name>` on the generated client. Register the page's
776
+ handler in an `effect`: `handle((input, { signal }) => …)` returns the function
777
+ that removes it, so pass that to `onCleanup`, and Angular removes the handler
778
+ when the client changes or the component is destroyed:
779
+
780
+ ```ts
781
+ import { Component, effect, ElementRef, input, viewChild } from "@angular/core";
782
+ import { injectView } from "@runic-artifex/angular";
783
+ import type { EditPageReference } from "./generated/edit";
784
+
785
+ @Component({ selector: "edit-page", template: `<input #name>` })
786
+ export class EditPage {
787
+ readonly page = input.required<EditPageReference>();
788
+ readonly view = injectView(this.page);
789
+ readonly name = viewChild<ElementRef<HTMLInputElement>>("name");
790
+
791
+ constructor() {
792
+ effect(onCleanup => {
793
+ const remove = this.view.client()?.requests.focus.handle(({ member }) => {
794
+ if (member === "name") this.name()?.nativeElement.focus();
795
+ });
796
+ if (remove) onCleanup(remove);
797
+ });
798
+ }
799
+ }
800
+ ```
801
+
802
+ `input` is typed from the request's `ViewRequest<T>`. The handler runs once
803
+ the page painted the state the request was raised with, so the field of that
804
+ state is rendered; `signal` aborts when the handler is replaced or removed, the
805
+ client is disposed or the connection is lost. A request is never replayed: one
806
+ 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.17.0/packages/web/views#view-requests) for the rules, and in a frontend
808
+ 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.17.0/packages/web/views#testing)).
627
810
 
628
811
  ## Collection viewports
629
812
 
630
813
  `injectCollectionViewport(element, options)` follows a fixed-row-height scroll
631
814
  container and returns a signal with its
632
- [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#collectionviewportoptions)
815
+ [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#collectionviewportoptions)
633
816
  range. Pass the container as a signal, such as a `viewChild`, and the options as
634
817
  a function or signal, then send the range to the ViewModel from an effect:
635
818
 
@@ -657,3 +840,25 @@ export class RowsPage {
657
840
  }
658
841
  }
659
842
  ```
843
+
844
+ ## Query collections
845
+
846
+ `injectQueryCollection(element, collection, options)` follows a scroll container for a
847
+ [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it loads the rows the container shows,
848
+ with placeholders until they arrive, and lays them out with variable heights. `viewport` is a signal of the
849
+ `QueryViewport` (`items` with `top` and `size`, `totalSize`, `total`, `query`, `loading`, `error`); `observe(element,
850
+ index)` measures a rendered row, and `scrollToKey`, `scrollToIndex`, `setQuery` and `retry` act on the collection.
851
+
852
+ ```ts
853
+ readonly list = injectQueryCollection(viewChild<ElementRef<HTMLElement>>("scroller"),
854
+ () => this.view.client()?.queries.rows, () => ({ estimateSize: 32 }));
855
+ ```
856
+
857
+ ## Back and the URL
858
+
859
+ The package re-exports `installBackNavigation`, `installNavigationPath`,
860
+ `navigateBack`, `openNavigationPath` and `onNavigationPath` from
861
+ `@runic-artifex/views` (since 0.16). Call the installs once where the page
862
+ starts, before or after mounting: the mouse's Back button and Alt+Left then go
863
+ 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.17.0/packages/web/views/README.md#back-and-the-url).
@@ -1,12 +1,22 @@
1
- export { ViewOutlet, RunicViewOutlet, type ViewOutletMissingContext, type ViewRegistry } from "./view-outlet.js";
1
+ export { ViewOutlet, RegionOutlets, RunicViewOutlet, type RegionOutletsMode, type RegionPanelAttributes, type ViewOutletMissingContext, type ViewRegistry, } from "./view-outlet.js";
2
2
  export { injectView, type InjectViewOptions, type ViewHandle } from "./inject-view.js";
3
3
  export { injectViewResource, type InjectViewResourceOptions, type ViewResource } from "./inject-view-resource.js";
4
4
  export { injectCommand, type CommandHandle, type InjectCommandOptions } from "./inject-command.js";
5
5
  export { injectOperation, type InjectOperationOptions, type OperationHandle } from "./inject-operation.js";
6
6
  export { injectField, type FieldHandle, type FieldView, type InjectFieldOptions } from "./inject-field.js";
7
+ export { injectForm, type FormFieldHandle, type FormHandle, type InjectFormOptions } from "./inject-form.js";
8
+ export { commitAllFields, type FormState, type FormSubmitOptions, type FormSubmitResult } from "@runic-artifex/views";
7
9
  export { injectTextField, type InjectTextFieldOptions, type TextFieldHandle, type TextFieldView } from "./inject-text-field.js";
8
10
  export { injectLatestOperation, type InjectLatestOperationOptions, type LatestOperationHandle, } from "./inject-latest-operation.js";
9
11
  export { injectCollectionViewport, type InjectCollectionViewportOptions } from "./inject-collection-viewport.js";
12
+ export { injectQueryCollection, type InjectQueryCollectionOptions, type QueryCollectionHandle } from "./inject-query-collection.js";
10
13
  export { injectBridgeConnection, type BridgeConnectionHandle, type InjectBridgeConnectionOptions } from "./inject-bridge-connection.js";
14
+ export { injectText, injectWindowLocale, RunicTextPipe, textLocaleSignal, type InjectTextOptions } from "./inject-text.js";
15
+ export { injectAppearance, type InjectAppearanceOptions } from "./inject-appearance.js";
16
+ export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, type DocumentLocaleOptions, type FieldErrorArguments, type FieldErrorReason, type FieldErrorText, type TextReference, type TextTranslations, } from "@runic-artifex/views";
17
+ export { appearance, onAppearance, type Appearance, type AppearanceColorScheme, type AppearanceContrast, type AppearanceSystemColors, type HostAppearance, } from "@runic-artifex/views";
11
18
  export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
19
+ export { upload, type BlobRef, type RunicBlob, type UploadOptions, type UploadProgress } from "@runic-artifex/views";
20
+ export { regionEntries, selectedRegion, type RegionCollection, type RegionEntry, type RegionOutcome, type RegionSlot, } from "@runic-artifex/views";
21
+ export { installBackNavigation, installNavigationPath, navigateBack, onNavigationPath, openNavigationPath, type NavigationPathChange, type NavigationPathOptions, type NavigationReply, } from "@runic-artifex/views";
12
22
  export { injectMenuBar, type InjectMenuBarOptions, type MenuBarEntry, type MenuBarHandle, type MenuBarInvokeResult, type MenuBarItem, type MenuBarMenu, type MenuBarRequest, type MenuBarSeparator, type MenuBarState, } from "./inject-menu-bar.js";
package/dist/esm/index.js CHANGED
@@ -1,12 +1,23 @@
1
- export { ViewOutlet, RunicViewOutlet } from "./view-outlet.js";
1
+ export { ViewOutlet, RegionOutlets, RunicViewOutlet, } from "./view-outlet.js";
2
2
  export { injectView } from "./inject-view.js";
3
3
  export { injectViewResource } from "./inject-view-resource.js";
4
4
  export { injectCommand } from "./inject-command.js";
5
5
  export { injectOperation } from "./inject-operation.js";
6
6
  export { injectField } from "./inject-field.js";
7
+ export { injectForm } from "./inject-form.js";
8
+ export { commitAllFields } from "@runic-artifex/views";
7
9
  export { injectTextField } from "./inject-text-field.js";
8
10
  export { injectLatestOperation, } from "./inject-latest-operation.js";
9
11
  export { injectCollectionViewport } from "./inject-collection-viewport.js";
12
+ export { injectQueryCollection } from "./inject-query-collection.js";
10
13
  export { injectBridgeConnection } from "./inject-bridge-connection.js";
14
+ export { injectText, injectWindowLocale, RunicTextPipe, textLocaleSignal } from "./inject-text.js";
15
+ export { injectAppearance } from "./inject-appearance.js";
16
+ export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, } from "@runic-artifex/views";
17
+ export { appearance, onAppearance, } from "@runic-artifex/views";
11
18
  export { onBridgeConnection } from "@runic-artifex/views";
19
+ // blobs/1: uploads from the page and the blob values of state.
20
+ export { upload } from "@runic-artifex/views";
21
+ export { regionEntries, selectedRegion, } from "@runic-artifex/views";
22
+ export { installBackNavigation, installNavigationPath, navigateBack, onNavigationPath, openNavigationPath, } from "@runic-artifex/views";
12
23
  export { injectMenuBar, } from "./inject-menu-bar.js";
@@ -0,0 +1,19 @@
1
+ import { Injector, type Signal } from "@angular/core";
2
+ import { type Appearance } from "@runic-artifex/views";
3
+ /** Options of {@link injectAppearance}. */
4
+ export interface InjectAppearanceOptions {
5
+ /** The injector to use outside an injection context. */
6
+ readonly injector?: Injector;
7
+ }
8
+ /**
9
+ * The page's appearance (`appearance` from `@runic-artifex/views`) as a signal for the lifetime of the injection
10
+ * context: the colour scheme, contrast and reduced motion of the page's engine combined with the desktop's values that a
11
+ * Runic host pushes (`appearance/1`), which also carry the text scale, the accent colour and the forced-colours palette.
12
+ * Every member is `null` under server rendering.
13
+ *
14
+ * ```ts
15
+ * readonly appearance = injectAppearance();
16
+ * readonly animate = computed(() => this.appearance().reducedMotion !== true);
17
+ * ```
18
+ */
19
+ export declare function injectAppearance({ injector: provided }?: InjectAppearanceOptions): Signal<Appearance>;
@@ -0,0 +1,26 @@
1
+ import { assertInInjectionContext, DestroyRef, inject, Injector, PLATFORM_ID, signal } from "@angular/core";
2
+ import { appearance, onAppearance, unknownAppearance } from "@runic-artifex/views";
3
+ /**
4
+ * The page's appearance (`appearance` from `@runic-artifex/views`) as a signal for the lifetime of the injection
5
+ * context: the colour scheme, contrast and reduced motion of the page's engine combined with the desktop's values that a
6
+ * Runic host pushes (`appearance/1`), which also carry the text scale, the accent colour and the forced-colours palette.
7
+ * Every member is `null` under server rendering.
8
+ *
9
+ * ```ts
10
+ * readonly appearance = injectAppearance();
11
+ * readonly animate = computed(() => this.appearance().reducedMotion !== true);
12
+ * ```
13
+ */
14
+ export function injectAppearance({ injector: provided } = {}) {
15
+ if (!provided)
16
+ assertInInjectionContext(injectAppearance);
17
+ const injector = provided ?? inject(Injector);
18
+ if (injector.get(PLATFORM_ID, null) === "server")
19
+ return signal(unknownAppearance).asReadonly();
20
+ const current = signal(appearance(), /* @ts-ignore */
21
+ ...(ngDevMode ? [{ debugName: "current" }] : /* istanbul ignore next */ []));
22
+ const stop = onAppearance(next => current.set(next));
23
+ injector.get(DestroyRef).onDestroy(stop);
24
+ current.set(appearance());
25
+ return current.asReadonly();
26
+ }
@@ -5,7 +5,7 @@ export interface FieldView<TClient extends ViewClient> {
5
5
  readonly state: Signal<TClient["snapshot"] | undefined>;
6
6
  readonly client: Signal<TClient | undefined>;
7
7
  }
8
- export interface InjectFieldOptions extends FieldOptions {
8
+ export interface InjectFieldOptions<TValue = any> extends FieldOptions<TValue> {
9
9
  /** Required outside an injection context. */
10
10
  readonly injector?: Injector;
11
11
  }
@@ -27,6 +27,8 @@ export interface FieldHandle<TValue> {
27
27
  readonly errors: Signal<readonly string[]>;
28
28
  /** The producer's value and version while a checked write's `conflict` keeps the draft. */
29
29
  readonly conflict: Signal<FieldBaseline<TValue> | undefined>;
30
+ /** The member's validation is in progress, such as an asynchronous rule that is still checking: show "checking…". */
31
+ readonly validating: Signal<boolean>;
30
32
  /** The definition's `kind`, `nullable`, `integer` and `choices`. */
31
33
  readonly field: FieldController<unknown, unknown, TValue>["field"];
32
34
  /** The user changed the value, such as a checkbox's `checked`. */
@@ -61,4 +63,4 @@ export interface FieldHandle<TValue> {
61
63
  * // (compositionstart)="title.compositionStart()" (compositionend)="title.compositionEnd($event)">
62
64
  * ```
63
65
  */
64
- export declare function injectField<TClient extends ViewClient, TValue>(view: FieldView<TClient>, field: BridgeField<TClient, TClient["snapshot"], TValue> | FieldDefinition<TClient, TClient["snapshot"], TValue>, { injector: provided, ...options }?: InjectFieldOptions): FieldHandle<TValue>;
66
+ export declare function injectField<TClient extends ViewClient, TValue>(view: FieldView<TClient>, field: BridgeField<TClient, TClient["snapshot"], TValue> | FieldDefinition<TClient, TClient["snapshot"], TValue>, { injector: provided, ...options }?: InjectFieldOptions<TValue>): FieldHandle<TValue>;
@@ -44,6 +44,7 @@ export function injectField(view, field, { injector: provided, ...options } = {}
44
44
  error: computed(() => current().error),
45
45
  errors: computed(() => current().errors),
46
46
  conflict: computed(() => current().conflict),
47
+ validating: computed(() => current().validating),
47
48
  field: controller.field,
48
49
  input(value) { controller.input(value); },
49
50
  inputText(event) { controller.inputText(textOf(event)); },
@@ -0,0 +1,40 @@
1
+ import { type Signal } from "@angular/core";
2
+ import { type FormField, type FormFields, type FormState, type FormSubmitOptions, type FormSubmitResult } from "@runic-artifex/views";
3
+ /** A field as {@link injectForm} reads it: an `injectField` handle. */
4
+ export interface FormFieldHandle extends FormField {
5
+ readonly editing: Signal<boolean>;
6
+ readonly validating: Signal<boolean>;
7
+ readonly errors: Signal<readonly string[]>;
8
+ readonly error: Signal<unknown>;
9
+ }
10
+ export interface InjectFormOptions {
11
+ /** Whether the View reports unsaved changes, such as `computed(() => this.editor.state()?.isDirty === true)`. */
12
+ readonly dirty?: Signal<boolean | undefined>;
13
+ }
14
+ /** A form bound by {@link injectForm}: its state as signals, and its actions. */
15
+ export interface FormHandle {
16
+ /** The whole state. */
17
+ readonly state: Signal<FormState>;
18
+ readonly dirty: Signal<boolean>;
19
+ readonly editing: Signal<boolean>;
20
+ readonly validating: Signal<boolean>;
21
+ readonly pending: Signal<boolean>;
22
+ readonly valid: Signal<boolean>;
23
+ readonly submitting: Signal<boolean>;
24
+ /** Commits every field, waits for their writes and runs `command` unless a field's write or text failed. */
25
+ submit<T>(command: () => T | PromiseLike<T>, options?: FormSubmitOptions): Promise<FormSubmitResult<T>>;
26
+ /** Commits every field and resolves once their writes settled. */
27
+ commit(): Promise<FormState>;
28
+ /** Resets every field. */
29
+ reset(): void;
30
+ }
31
+ /**
32
+ * One dirty, pending and valid state over `injectField` handles, and a `submit` that writes every field before its
33
+ * command (`createFormController` in `@runic-artifex/views`). It needs no injection context.
34
+ *
35
+ * ```ts
36
+ * readonly form = injectForm({ title: this.title, body: this.body }, { dirty: computed(() => this.editor.state()?.isDirty === true) });
37
+ * // <button [disabled]="!form.valid() || form.submitting()" (click)="form.submit(() => editor.client()!.save())">Save</button>
38
+ * ```
39
+ */
40
+ export declare function injectForm(fields: FormFields<FormFieldHandle>, options?: InjectFormOptions): FormHandle;
@@ -0,0 +1,48 @@
1
+ import { computed, signal } from "@angular/core";
2
+ import { formFieldList, formStateOf, submitFields, } from "@runic-artifex/views";
3
+ /**
4
+ * One dirty, pending and valid state over `injectField` handles, and a `submit` that writes every field before its
5
+ * command (`createFormController` in `@runic-artifex/views`). It needs no injection context.
6
+ *
7
+ * ```ts
8
+ * readonly form = injectForm({ title: this.title, body: this.body }, { dirty: computed(() => this.editor.state()?.isDirty === true) });
9
+ * // <button [disabled]="!form.valid() || form.submitting()" (click)="form.submit(() => editor.client()!.save())">Save</button>
10
+ * ```
11
+ */
12
+ export function injectForm(fields, options = {}) {
13
+ const list = formFieldList(fields);
14
+ const submitting = signal(false, /* @ts-ignore */
15
+ ...(ngDevMode ? [{ debugName: "submitting" }] : /* istanbul ignore next */ []));
16
+ const state = computed(() => formStateOf(list.map(field => ({ editing: field.editing(), validating: field.validating(), errors: field.errors(), error: field.error() })), options.dirty?.() === true, submitting()), /* @ts-ignore */
17
+ ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
18
+ return {
19
+ state,
20
+ dirty: computed(() => state().dirty),
21
+ editing: computed(() => state().editing),
22
+ validating: computed(() => state().validating),
23
+ pending: computed(() => state().pending),
24
+ valid: computed(() => state().valid),
25
+ submitting: computed(() => state().submitting),
26
+ async submit(command, submitOptions = {}) {
27
+ if (submitting())
28
+ return { status: "busy" };
29
+ submitting.set(true);
30
+ const read = (index) => {
31
+ const field = list[index];
32
+ return { editing: field.editing(), error: field.error(), validating: field.validating() };
33
+ };
34
+ try {
35
+ return await submitFields(list, command, submitOptions, read);
36
+ }
37
+ finally {
38
+ submitting.set(false);
39
+ }
40
+ },
41
+ async commit() {
42
+ await Promise.all(list.map(field => field.commit()));
43
+ return state();
44
+ },
45
+ reset() { for (const field of list)
46
+ field.reset(); },
47
+ };
48
+ }
@@ -0,0 +1,29 @@
1
+ import { ElementRef, Injector, type Signal } from "@angular/core";
2
+ import { type QueryCollection, type QueryViewport, type QueryViewportOptions, type RunicQuery } from "@runic-artifex/views";
3
+ export interface InjectQueryCollectionOptions {
4
+ /** Required outside an injection context. */
5
+ readonly injector?: Injector;
6
+ }
7
+ export interface QueryCollectionHandle<TRow> {
8
+ /** The rows to render with their offsets, the spacer's `totalSize`, the total, query, loading and error state. */
9
+ readonly viewport: Signal<QueryViewport<TRow>>;
10
+ /**
11
+ * Measures a rendered row's height until the returned function is called, for example from an `effect` over
12
+ * `viewChildren` of the rows.
13
+ */
14
+ observe(element: Element | ElementRef<Element>, index: number): () => void;
15
+ /** Scrolls to the row with `key` in the current query; resolves `false` when no row has it. */
16
+ scrollToKey(key: string, align?: "start" | "center" | "end"): Promise<boolean>;
17
+ scrollToIndex(index: number, align?: "start" | "center" | "end"): void;
18
+ /** Changes the collection's sort and filter (ViewModel state every presentation shares). */
19
+ setQuery(query: RunicQuery): Promise<void>;
20
+ /** Loads the range again after a failure. */
21
+ retry(): void;
22
+ }
23
+ /**
24
+ * Follows a scroll container for a query collection (`client.queries.{name}`): it loads the rows the container shows
25
+ * from .NET, with placeholders until they arrive, and lays them out with variable heights. Pass the container, for
26
+ * example `viewChild<ElementRef<HTMLElement>>("scroller")`, the collection as a function such as
27
+ * `() => view.client()?.queries.rows`, and the options.
28
+ */
29
+ export declare function injectQueryCollection<TRow>(element: Signal<ElementRef<HTMLElement> | HTMLElement | null | undefined>, collection: () => QueryCollection<TRow> | undefined, options: () => QueryViewportOptions, { injector: provided }?: InjectQueryCollectionOptions): QueryCollectionHandle<TRow>;
@@ -0,0 +1,64 @@
1
+ import { assertInInjectionContext, DestroyRef, effect, ElementRef, inject, Injector, NgZone, signal, untracked } from "@angular/core";
2
+ import { createQueryViewportController, } from "@runic-artifex/views";
3
+ const empty = { items: [], totalSize: 0, total: null, query: { sort: [], filters: [] }, loading: false, error: undefined };
4
+ /**
5
+ * Follows a scroll container for a query collection (`client.queries.{name}`): it loads the rows the container shows
6
+ * from .NET, with placeholders until they arrive, and lays them out with variable heights. Pass the container, for
7
+ * example `viewChild<ElementRef<HTMLElement>>("scroller")`, the collection as a function such as
8
+ * `() => view.client()?.queries.rows`, and the options.
9
+ */
10
+ export function injectQueryCollection(element, collection, options, { injector: provided } = {}) {
11
+ if (!provided)
12
+ assertInInjectionContext(injectQueryCollection);
13
+ const injector = provided ?? inject(Injector);
14
+ const viewport = signal(empty, /* @ts-ignore */
15
+ ...(ngDevMode ? [{ debugName: "viewport" }] : /* istanbul ignore next */ []));
16
+ const zone = injector.get(NgZone, null);
17
+ const outside = (run) => zone ? zone.runOutsideAngular(run) : run();
18
+ let controller;
19
+ const container = () => {
20
+ const target = untracked(element);
21
+ return target instanceof ElementRef ? target.nativeElement : target ?? null;
22
+ };
23
+ let release;
24
+ effect(() => {
25
+ const current = collection();
26
+ untracked(() => {
27
+ release?.();
28
+ release = undefined;
29
+ if (!current) {
30
+ viewport.set(empty);
31
+ return;
32
+ }
33
+ const created = controller = createQueryViewportController(current, options());
34
+ const stop = created.subscribe(() => viewport.set(created.current));
35
+ outside(() => created.attach(container()));
36
+ viewport.set(created.current);
37
+ release = () => { stop(); created.dispose(); if (controller === created)
38
+ controller = undefined; };
39
+ });
40
+ }, { injector });
41
+ effect(() => {
42
+ const { estimateSize, overscan } = options();
43
+ untracked(() => controller?.update({ estimateSize, ...(overscan === undefined ? {} : { overscan }) }));
44
+ }, { injector });
45
+ // Scroll and resize events only update the viewport signal, which schedules change detection itself.
46
+ effect(() => {
47
+ element();
48
+ untracked(() => outside(() => controller?.attach(container())));
49
+ }, { injector });
50
+ injector.get(DestroyRef).onDestroy(() => { release?.(); release = undefined; });
51
+ return {
52
+ viewport: viewport.asReadonly(),
53
+ observe: (target, index) => controller?.observe(target instanceof ElementRef ? target.nativeElement : target, index) ?? (() => { }),
54
+ scrollToKey: async (key, align) => controller ? controller.scrollToKey(key, align) : false,
55
+ scrollToIndex: (index, align) => controller?.scrollToIndex(index, align),
56
+ setQuery: async (query) => {
57
+ const current = untracked(collection);
58
+ if (!current)
59
+ throw new TypeError("injectQueryCollection has no collection yet.");
60
+ await current.setQuery(query);
61
+ },
62
+ retry: () => untracked(collection)?.retry(),
63
+ };
64
+ }
@@ -0,0 +1,55 @@
1
+ import { Injector, type OnDestroy, type PipeTransform, type Signal } from "@angular/core";
2
+ import { type FieldError, type TextReference } from "@runic-artifex/views";
3
+ import * as i0 from "@angular/core";
4
+ export interface InjectTextOptions {
5
+ /** Required outside an injection context. */
6
+ readonly injector?: Injector;
7
+ }
8
+ /**
9
+ * A text reference that a ViewModel produced, such as a status line or a validation message's `text`, in the window's
10
+ * language (`resolveText`), as a signal that follows a language switch for the lifetime of the injection context.
11
+ * `source` and `fallback` are read in a computed signal, so they may read other signals:
12
+ * `injectText(() => view.state()?.status)`. A string shows as it is; `null` and `undefined` show `fallback`. Configure
13
+ * the page's Translations runtime once with `configureTranslatedText`; without one, a reference shows its fallback text.
14
+ * A field's `FieldError` shows the application's text for it (`configureFieldErrorText`), or its English message.
15
+ * Under server rendering it does not observe a language switch. In templates, the `runicText` pipe does the same.
16
+ *
17
+ * ```ts
18
+ * readonly status = injectText(() => this.view.state()?.status);
19
+ * // <p>{{ status() }}</p>
20
+ * ```
21
+ */
22
+ export declare function injectText(source: () => TextReference | FieldError | string | null | undefined, fallback?: () => string | undefined, { injector: provided }?: InjectTextOptions): Signal<string>;
23
+ /**
24
+ * The window's locale that the application set, or `null` while it sets none, as a signal for the lifetime of the
25
+ * injection context, for example to bind `lang`.
26
+ */
27
+ export declare function injectWindowLocale({ injector: provided }?: InjectTextOptions): Signal<string | null>;
28
+ /**
29
+ * The locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's locale),
30
+ * as a signal. It is one signal for the page and needs no injection context, so the page's locale resolver can read
31
+ * it: a template that calls `m.*()` reads the signal through the resolver and renders again on a language switch.
32
+ * `undefined` while the page has no Translations runtime and the application sets no window locale.
33
+ *
34
+ * ```ts
35
+ * const textLocale = textLocaleSignal();
36
+ * configureLocaleResolver(() => textLocale() ?? locale.getLocale());
37
+ * ```
38
+ */
39
+ export declare function textLocaleSignal(): Signal<string | undefined>;
40
+ /**
41
+ * Shows a text reference in the window's language in a template, and marks the view for check when the language
42
+ * changes: `{{ error.text | runicText: error.message }}`, `{{ state.status | runicText }}`. A string shows as it is;
43
+ * `null` and `undefined` show the fallback argument; a field's error, `{{ name.error() | runicText }}`, the application's
44
+ * text for it (`configureFieldErrorText`). The pipe is impure so that it sees a language switch; it formats
45
+ * again only when the value, the fallback or the language changed, and returns its last text otherwise.
46
+ */
47
+ export declare class RunicTextPipe implements PipeTransform, OnDestroy {
48
+ private readonly changes;
49
+ private readonly stop;
50
+ private last;
51
+ transform(value: TextReference | FieldError | string | null | undefined, fallback?: string): string;
52
+ ngOnDestroy(): void;
53
+ static ɵfac: i0.ɵɵFactoryDeclaration<RunicTextPipe, never>;
54
+ static ɵpipe: i0.ɵɵPipeDeclaration<RunicTextPipe, "runicText", true>;
55
+ }
@@ -0,0 +1,98 @@
1
+ import { assertInInjectionContext, ChangeDetectorRef, computed, DestroyRef, inject, Injector, Pipe, PLATFORM_ID, signal, } from "@angular/core";
2
+ import { onWindowLocale, resolveText, subscribeText, textLocale, textVersion, windowLocale, } from "@runic-artifex/views";
3
+ import * as i0 from "@angular/core";
4
+ /**
5
+ * A text reference that a ViewModel produced, such as a status line or a validation message's `text`, in the window's
6
+ * language (`resolveText`), as a signal that follows a language switch for the lifetime of the injection context.
7
+ * `source` and `fallback` are read in a computed signal, so they may read other signals:
8
+ * `injectText(() => view.state()?.status)`. A string shows as it is; `null` and `undefined` show `fallback`. Configure
9
+ * the page's Translations runtime once with `configureTranslatedText`; without one, a reference shows its fallback text.
10
+ * A field's `FieldError` shows the application's text for it (`configureFieldErrorText`), or its English message.
11
+ * Under server rendering it does not observe a language switch. In templates, the `runicText` pipe does the same.
12
+ *
13
+ * ```ts
14
+ * readonly status = injectText(() => this.view.state()?.status);
15
+ * // <p>{{ status() }}</p>
16
+ * ```
17
+ */
18
+ export function injectText(source, fallback, { injector: provided } = {}) {
19
+ if (!provided)
20
+ assertInInjectionContext(injectText);
21
+ const injector = provided ?? inject(Injector);
22
+ const version = signal(0, /* @ts-ignore */
23
+ ...(ngDevMode ? [{ debugName: "version" }] : /* istanbul ignore next */ []));
24
+ if (injector.get(PLATFORM_ID, null) !== "server") {
25
+ const stop = subscribeText(() => version.update(value => value + 1));
26
+ injector.get(DestroyRef).onDestroy(stop);
27
+ }
28
+ return computed(() => {
29
+ version();
30
+ return resolveText(source(), fallback?.());
31
+ });
32
+ }
33
+ /**
34
+ * The window's locale that the application set, or `null` while it sets none, as a signal for the lifetime of the
35
+ * injection context, for example to bind `lang`.
36
+ */
37
+ export function injectWindowLocale({ injector: provided } = {}) {
38
+ if (!provided)
39
+ assertInInjectionContext(injectWindowLocale);
40
+ const injector = provided ?? inject(Injector);
41
+ const locale = signal(windowLocale(), /* @ts-ignore */
42
+ ...(ngDevMode ? [{ debugName: "locale" }] : /* istanbul ignore next */ []));
43
+ if (injector.get(PLATFORM_ID, null) !== "server") {
44
+ const stop = onWindowLocale(next => locale.set(next));
45
+ injector.get(DestroyRef).onDestroy(stop);
46
+ }
47
+ return locale.asReadonly();
48
+ }
49
+ let pageTextLocale;
50
+ /**
51
+ * The locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's locale),
52
+ * as a signal. It is one signal for the page and needs no injection context, so the page's locale resolver can read
53
+ * it: a template that calls `m.*()` reads the signal through the resolver and renders again on a language switch.
54
+ * `undefined` while the page has no Translations runtime and the application sets no window locale.
55
+ *
56
+ * ```ts
57
+ * const textLocale = textLocaleSignal();
58
+ * configureLocaleResolver(() => textLocale() ?? locale.getLocale());
59
+ * ```
60
+ */
61
+ export function textLocaleSignal() {
62
+ if (pageTextLocale)
63
+ return pageTextLocale;
64
+ const current = signal(textLocale(), /* @ts-ignore */
65
+ ...(ngDevMode ? [{ debugName: "current" }] : /* istanbul ignore next */ []));
66
+ subscribeText(() => current.set(textLocale()));
67
+ return pageTextLocale = current.asReadonly();
68
+ }
69
+ /**
70
+ * Shows a text reference in the window's language in a template, and marks the view for check when the language
71
+ * changes: `{{ error.text | runicText: error.message }}`, `{{ state.status | runicText }}`. A string shows as it is;
72
+ * `null` and `undefined` show the fallback argument; a field's error, `{{ name.error() | runicText }}`, the application's
73
+ * text for it (`configureFieldErrorText`). The pipe is impure so that it sees a language switch; it formats
74
+ * again only when the value, the fallback or the language changed, and returns its last text otherwise.
75
+ */
76
+ export class RunicTextPipe {
77
+ changes = inject(ChangeDetectorRef);
78
+ stop = subscribeText(() => this.changes.markForCheck());
79
+ last;
80
+ transform(value, fallback) {
81
+ const version = textVersion();
82
+ const last = this.last;
83
+ if (last && last.value === value && last.fallback === fallback && last.version === version)
84
+ return last.text;
85
+ const text = resolveText(value, fallback);
86
+ this.last = { value, fallback, version, text };
87
+ return text;
88
+ }
89
+ ngOnDestroy() {
90
+ this.stop();
91
+ }
92
+ static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.2.3", ngImport: i0, type: RunicTextPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
93
+ static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "22.2.3", ngImport: i0, type: RunicTextPipe, isStandalone: true, name: "runicText", pure: false });
94
+ }
95
+ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.3", ngImport: i0, type: RunicTextPipe, decorators: [{
96
+ type: Pipe,
97
+ args: [{ name: "runicText", standalone: true, pure: false }]
98
+ }] });
@@ -1,17 +1,17 @@
1
1
  import { type InputSignal, type TemplateRef, type Type } from "@angular/core";
2
- import type { PageReference } from "@runic-artifex/views";
2
+ import { type PageReference, type RegionCollection, type RegionEntry, type ViewRegistryPage } from "@runic-artifex/views";
3
3
  import * as i0 from "@angular/core";
4
4
  /**
5
5
  * A build-known map checks each generated reference against its component input. A nullable
6
- * reference, such as a region slot's `State["main"]`, checks its non-null kinds.
6
+ * reference, such as a region slot's `State["main"]`, checks its non-null kinds. A component whose `page` input is a
7
+ * shared page reference (`[RunicSharedClient]`), such as `ResultPagePageReference`, registers for each of its kinds.
7
8
  */
8
9
  export type ViewRegistry<R extends PageReference | null | undefined> = {
9
- readonly [K in NonNullable<R>["kind"]]: Type<{
10
- readonly page: InputSignal<Extract<NonNullable<R>, {
11
- readonly kind: K;
12
- }>>;
13
- }>;
10
+ readonly [K in NonNullable<R>["kind"]]: PageComponent<ViewRegistryPage<R, K>>;
14
11
  };
12
+ type PageComponent<P> = P extends unknown ? Type<{
13
+ readonly page: InputSignal<P>;
14
+ }> : never;
15
15
  /** The context of a `missing` template: the reference without a component, as `$implicit` (`let-page`) and `content`. */
16
16
  export interface ViewOutletMissingContext<R extends PageReference = PageReference> {
17
17
  readonly $implicit: R;
@@ -20,7 +20,9 @@ export interface ViewOutletMissingContext<R extends PageReference = PageReferenc
20
20
  /**
21
21
  * Headless host for a selected logical .NET View. A changed reference remounts its component, and
22
22
  * the projected content renders while there is no reference. A kind without a component renders
23
- * the `missing` template, for example localized text, or an English alert without it:
23
+ * the `missing` template, for example localized text. Without it, a development build (`isDevMode()`) renders an
24
+ * English alert, and a production build renders nothing and reports the kind (`installErrorReporting`,
25
+ * `onBridgeDiagnostic`):
24
26
  *
25
27
  * ```html
26
28
  * <runic-view-outlet [content]="state()?.main" [registry]="pages" [missing]="missingView" />
@@ -32,7 +34,7 @@ export interface ViewOutletMissingContext<R extends PageReference = PageReferenc
32
34
  export declare class ViewOutlet<R extends PageReference = PageReference> {
33
35
  readonly content: InputSignal<R | null | undefined>;
34
36
  readonly registry: InputSignal<ViewRegistry<R>>;
35
- /** Renders a reference whose kind has no registered component instead of the English alert. */
37
+ /** Renders a reference whose kind has no registered component instead of the development alert. */
36
38
  readonly missing: InputSignal<TemplateRef<ViewOutletMissingContext<R>> | undefined>;
37
39
  readonly error: import("@angular/core").WritableSignal<string | undefined>;
38
40
  private readonly mount;
@@ -41,6 +43,49 @@ export declare class ViewOutlet<R extends PageReference = PageReference> {
41
43
  static ɵfac: i0.ɵɵFactoryDeclaration<ViewOutlet<any>, never>;
42
44
  static ɵcmp: i0.ɵɵComponentDeclaration<ViewOutlet<any>, "runic-view-outlet", never, { "content": { "alias": "content"; "required": false; "isSignal": true; }; "registry": { "alias": "registry"; "required": true; "isSignal": true; }; "missing": { "alias": "missing"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
43
45
  }
46
+ /** How {@link RegionOutlets} renders the regions of a collection. */
47
+ export type RegionOutletsMode = "keep-mounted" | "selected";
48
+ /**
49
+ * Attributes that {@link RegionOutlets} sets on a region's wrapper, such as `id`, `role` and `aria-labelledby`. A
50
+ * `null` or `undefined` value leaves the attribute out. `hidden`, `style` and `data-region-key` stay controlled by
51
+ * the outlet and are ignored here.
52
+ */
53
+ export type RegionPanelAttributes = Readonly<Record<string, string | null | undefined>>;
54
+ export declare class RegionPanel {
55
+ readonly attributes: InputSignal<Readonly<Record<string, string | null | undefined>> | undefined>;
56
+ constructor();
57
+ static ɵfac: i0.ɵɵFactoryDeclaration<RegionPanel, never>;
58
+ static ɵdir: i0.ɵɵDirectiveDeclaration<RegionPanel, "[runicRegionPanel]", never, { "attributes": { "alias": "runicRegionPanel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
59
+ }
60
+ /**
61
+ * Renders a {@link ViewOutlet} for the regions of a region collection, each in a `<div data-region-key>` tracked by
62
+ * the region's key. A region that is not selected is rendered with `hidden` and an inline `display: none`, which
63
+ * author CSS without `!important` cannot override. A new content reference in a region remounts only that region's
64
+ * component. The projected content renders while the collection has no region, and `missing` is passed to each
65
+ * outlet. `panelProps` returns attributes for each wrapper, so a tab can point `aria-controls` at its panel:
66
+ *
67
+ * ```html
68
+ * <runic-region-outlets [collection]="state()?.documents" [registry]="pages" [panelProps]="panel">No open documents</runic-region-outlets>
69
+ * ```
70
+ *
71
+ * `mode` `"keep-mounted"` (the default) renders every region and hides all but the selected one, so each region
72
+ * keeps its component and DOM. `"selected"` renders only the selected region.
73
+ */
74
+ export declare class RegionOutlets<R extends PageReference = PageReference> {
75
+ readonly collection: InputSignal<RegionCollection<R> | null | undefined>;
76
+ readonly registry: InputSignal<ViewRegistry<R>>;
77
+ /** Renders a reference whose kind has no registered component instead of the English alert. */
78
+ readonly missing: InputSignal<TemplateRef<ViewOutletMissingContext<R>> | undefined>;
79
+ readonly mode: InputSignal<RegionOutletsMode>;
80
+ /** Returns attributes for a region's wrapper, for example `{ id, role: "tabpanel", "aria-labelledby" }`. */
81
+ readonly panelProps: InputSignal<((entry: RegionEntry<R>) => RegionPanelAttributes) | undefined>;
82
+ protected readonly shown: import("@angular/core").Signal<{
83
+ region: RegionEntry<R>;
84
+ attributes: Readonly<Record<string, string | null | undefined>> | undefined;
85
+ }[]>;
86
+ static ɵfac: i0.ɵɵFactoryDeclaration<RegionOutlets<any>, never>;
87
+ static ɵcmp: i0.ɵɵComponentDeclaration<RegionOutlets<any>, "runic-region-outlets", never, { "collection": { "alias": "collection"; "required": false; "isSignal": true; }; "registry": { "alias": "registry"; "required": true; "isSignal": true; }; "missing": { "alias": "missing"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "panelProps": { "alias": "panelProps"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
88
+ }
44
89
  /**
45
90
  * The name of {@link ViewOutlet} before 0.7.0-preview.7, where React, Vue and Svelte already used
46
91
  * `ViewOutlet`. It is the same component class, so it renders the same `<runic-view-outlet>` element
@@ -53,3 +98,4 @@ export declare const RunicViewOutlet: typeof ViewOutlet;
53
98
  * @deprecated Import `ViewOutlet` instead; this alias is removed in the next major release.
54
99
  */
55
100
  export type RunicViewOutlet<R extends PageReference = PageReference> = ViewOutlet<R>;
101
+ export {};
@@ -1,11 +1,15 @@
1
- import { Component, computed, effect, input, signal, untracked, viewChild, ViewContainerRef } from "@angular/core";
1
+ import { Component, computed, Directive, effect, ElementRef, inject, input, isDevMode, Renderer2, signal, untracked, viewChild, ViewContainerRef, } from "@angular/core";
2
+ import { regionEntries } from "@runic-artifex/views";
3
+ import { missingViewMessage, reportMissingView } from "@runic-artifex/views/bindings";
2
4
  import * as i0 from "@angular/core";
3
5
  // Projected content renders while there is no reference, like React's `fallback`, Vue's default slot
4
6
  // and Svelte's `fallback` snippet: `<runic-view-outlet [content]="…" [registry]="…">Loading…</runic-view-outlet>`.
5
7
  /**
6
8
  * Headless host for a selected logical .NET View. A changed reference remounts its component, and
7
9
  * the projected content renders while there is no reference. A kind without a component renders
8
- * the `missing` template, for example localized text, or an English alert without it:
10
+ * the `missing` template, for example localized text. Without it, a development build (`isDevMode()`) renders an
11
+ * English alert, and a production build renders nothing and reports the kind (`installErrorReporting`,
12
+ * `onBridgeDiagnostic`):
9
13
  *
10
14
  * ```html
11
15
  * <runic-view-outlet [content]="state()?.main" [registry]="pages" [missing]="missingView" />
@@ -19,7 +23,7 @@ export class ViewOutlet {
19
23
  ...(ngDevMode ? [undefined, { debugName: "content" }] : /* istanbul ignore next */ []));
20
24
  registry = input.required(/* @ts-ignore */
21
25
  ...(ngDevMode ? [{ debugName: "registry" }] : /* istanbul ignore next */ []));
22
- /** Renders a reference whose kind has no registered component instead of the English alert. */
26
+ /** Renders a reference whose kind has no registered component instead of the development alert. */
23
27
  missing = input(/* @ts-ignore */
24
28
  ...(ngDevMode ? [undefined, { debugName: "missing" }] : /* istanbul ignore next */ []));
25
29
  error = signal(undefined, /* @ts-ignore */
@@ -51,7 +55,10 @@ export class ViewOutlet {
51
55
  container.createEmbeddedView(selection.missing, { $implicit: selection.reference, content: selection.reference });
52
56
  return;
53
57
  }
54
- this.error.set(`No web component is registered for ${selection.reference.kind}.`);
58
+ if (isDevMode())
59
+ this.error.set(missingViewMessage(selection.reference.kind));
60
+ else
61
+ reportMissingView(selection.reference.kind);
55
62
  return;
56
63
  }
57
64
  const component = container.createComponent(selection.component);
@@ -74,6 +81,91 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.3", ngImpor
74
81
  @if (error(); as issue) { <p role="alert">{{ issue }}</p> }
75
82
  ` }]
76
83
  }], ctorParameters: () => [], propDecorators: { content: [{ type: i0.Input, args: [{ isSignal: true, alias: "content", required: false }] }], registry: [{ type: i0.Input, args: [{ isSignal: true, alias: "registry", required: true }] }], missing: [{ type: i0.Input, args: [{ isSignal: true, alias: "missing", required: false }] }], mount: [{ type: i0.ViewChild, args: ["mount", { ...{ read: ViewContainerRef }, isSignal: true }] }] } });
84
+ const outletAttributes = new Set(["hidden", "style", "data-region-key"]);
85
+ // Sets the attributes of the latest panelProps result on its element and removes the ones it no longer returns.
86
+ export class RegionPanel {
87
+ attributes = input(undefined, { ...(ngDevMode ? { debugName: "attributes" } : /* istanbul ignore next */ {}), alias: "runicRegionPanel" });
88
+ constructor() {
89
+ const element = inject(ElementRef).nativeElement;
90
+ const renderer = inject(Renderer2);
91
+ let applied = new Set();
92
+ effect(() => {
93
+ const set = new Set();
94
+ for (const [name, value] of Object.entries(this.attributes() ?? {})) {
95
+ if (value === null || value === undefined || outletAttributes.has(name.toLowerCase()))
96
+ continue;
97
+ renderer.setAttribute(element, name, value);
98
+ set.add(name);
99
+ }
100
+ for (const name of applied)
101
+ if (!set.has(name))
102
+ renderer.removeAttribute(element, name);
103
+ applied = set;
104
+ });
105
+ }
106
+ static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.2.3", ngImport: i0, type: RegionPanel, deps: [], target: i0.ɵɵFactoryTarget.Directive });
107
+ static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.2.3", type: RegionPanel, isStandalone: true, selector: "[runicRegionPanel]", inputs: { attributes: { classPropertyName: "attributes", publicName: "runicRegionPanel", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
108
+ }
109
+ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.3", ngImport: i0, type: RegionPanel, decorators: [{
110
+ type: Directive,
111
+ args: [{ selector: "[runicRegionPanel]", standalone: true }]
112
+ }], ctorParameters: () => [], propDecorators: { attributes: [{ type: i0.Input, args: [{ isSignal: true, alias: "runicRegionPanel", required: false }] }] } });
113
+ /**
114
+ * Renders a {@link ViewOutlet} for the regions of a region collection, each in a `<div data-region-key>` tracked by
115
+ * the region's key. A region that is not selected is rendered with `hidden` and an inline `display: none`, which
116
+ * author CSS without `!important` cannot override. A new content reference in a region remounts only that region's
117
+ * component. The projected content renders while the collection has no region, and `missing` is passed to each
118
+ * outlet. `panelProps` returns attributes for each wrapper, so a tab can point `aria-controls` at its panel:
119
+ *
120
+ * ```html
121
+ * <runic-region-outlets [collection]="state()?.documents" [registry]="pages" [panelProps]="panel">No open documents</runic-region-outlets>
122
+ * ```
123
+ *
124
+ * `mode` `"keep-mounted"` (the default) renders every region and hides all but the selected one, so each region
125
+ * keeps its component and DOM. `"selected"` renders only the selected region.
126
+ */
127
+ export class RegionOutlets {
128
+ collection = input(/* @ts-ignore */
129
+ ...(ngDevMode ? [undefined, { debugName: "collection" }] : /* istanbul ignore next */ []));
130
+ registry = input.required(/* @ts-ignore */
131
+ ...(ngDevMode ? [{ debugName: "registry" }] : /* istanbul ignore next */ []));
132
+ /** Renders a reference whose kind has no registered component instead of the English alert. */
133
+ missing = input(/* @ts-ignore */
134
+ ...(ngDevMode ? [undefined, { debugName: "missing" }] : /* istanbul ignore next */ []));
135
+ mode = input("keep-mounted", /* @ts-ignore */
136
+ ...(ngDevMode ? [{ debugName: "mode" }] : /* istanbul ignore next */ []));
137
+ /** Returns attributes for a region's wrapper, for example `{ id, role: "tabpanel", "aria-labelledby" }`. */
138
+ panelProps = input(/* @ts-ignore */
139
+ ...(ngDevMode ? [undefined, { debugName: "panelProps" }] : /* istanbul ignore next */ []));
140
+ shown = computed(() => {
141
+ const keepMounted = this.mode() === "keep-mounted";
142
+ const panelProps = this.panelProps();
143
+ return regionEntries(this.collection())
144
+ .filter(region => keepMounted || region.selected)
145
+ .map(region => ({ region, attributes: panelProps?.(region) }));
146
+ }, /* @ts-ignore */
147
+ ...(ngDevMode ? [{ debugName: "shown" }] : /* istanbul ignore next */ []));
148
+ static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.2.3", ngImport: i0, type: RegionOutlets, deps: [], target: i0.ɵɵFactoryTarget.Component });
149
+ static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.2.3", type: RegionOutlets, isStandalone: true, selector: "runic-region-outlets", inputs: { collection: { classPropertyName: "collection", publicName: "collection", isSignal: true, isRequired: false, transformFunction: null }, registry: { classPropertyName: "registry", publicName: "registry", isSignal: true, isRequired: true, transformFunction: null }, missing: { classPropertyName: "missing", publicName: "missing", isSignal: true, isRequired: false, transformFunction: null }, mode: { classPropertyName: "mode", publicName: "mode", isSignal: true, isRequired: false, transformFunction: null }, panelProps: { classPropertyName: "panelProps", publicName: "panelProps", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `
150
+ @for (panel of shown(); track panel.region.key) {
151
+ <div [runicRegionPanel]="panel.attributes" [hidden]="!panel.region.selected" [style.display]="panel.region.selected ? null : 'none'"
152
+ [attr.data-region-key]="panel.region.key">
153
+ <runic-view-outlet [content]="panel.region.content" [registry]="registry()" [missing]="missing()" />
154
+ </div>
155
+ } @empty { <ng-content /> }
156
+ `, isInline: true, dependencies: [{ kind: "component", type: ViewOutlet, selector: "runic-view-outlet", inputs: ["content", "registry", "missing"] }, { kind: "directive", type: RegionPanel, selector: "[runicRegionPanel]", inputs: ["runicRegionPanel"] }] });
157
+ }
158
+ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.3", ngImport: i0, type: RegionOutlets, decorators: [{
159
+ type: Component,
160
+ args: [{ selector: "runic-region-outlets", standalone: true, imports: [ViewOutlet, RegionPanel], template: `
161
+ @for (panel of shown(); track panel.region.key) {
162
+ <div [runicRegionPanel]="panel.attributes" [hidden]="!panel.region.selected" [style.display]="panel.region.selected ? null : 'none'"
163
+ [attr.data-region-key]="panel.region.key">
164
+ <runic-view-outlet [content]="panel.region.content" [registry]="registry()" [missing]="missing()" />
165
+ </div>
166
+ } @empty { <ng-content /> }
167
+ ` }]
168
+ }], propDecorators: { collection: [{ type: i0.Input, args: [{ isSignal: true, alias: "collection", required: false }] }], registry: [{ type: i0.Input, args: [{ isSignal: true, alias: "registry", required: true }] }], missing: [{ type: i0.Input, args: [{ isSignal: true, alias: "missing", required: false }] }], mode: [{ type: i0.Input, args: [{ isSignal: true, alias: "mode", required: false }] }], panelProps: [{ type: i0.Input, args: [{ isSignal: true, alias: "panelProps", required: false }] }] } });
77
169
  /**
78
170
  * The name of {@link ViewOutlet} before 0.7.0-preview.7, where React, Vue and Svelte already used
79
171
  * `ViewOutlet`. It is the same component class, so it renders the same `<runic-view-outlet>` element
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/angular",
3
- "version": "0.15.1",
3
+ "version": "0.17.0",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
@@ -18,7 +18,7 @@
18
18
  "peerDependencies": {
19
19
  "@angular/core": ">=22.0.0 <23",
20
20
  "@angular/forms": ">=22.0.0 <23",
21
- "@runic-artifex/views": "0.15.1"
21
+ "@runic-artifex/views": "0.17.0"
22
22
  },
23
23
  "peerDependenciesMeta": {
24
24
  "@angular/forms": {
@@ -32,7 +32,7 @@
32
32
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
33
33
  "directory": "packages/web/angular"
34
34
  },
35
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/angular#readme",
35
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/angular#readme",
36
36
  "bugs": {
37
37
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
38
38
  },
@@ -56,7 +56,7 @@
56
56
  "pack:check": "bun pm pack --dry-run"
57
57
  },
58
58
  "devDependencies": {
59
- "@runic-artifex/views": "0.15.1",
59
+ "@runic-artifex/views": "0.17.0",
60
60
  "@angular/common": "22.2.3",
61
61
  "@angular/compiler": "22.2.3",
62
62
  "@angular/compiler-cli": "22.2.3",
@@ -69,5 +69,5 @@
69
69
  "typescript": "6.0.3",
70
70
  "vitest": "5.0.3"
71
71
  },
72
- "gitHead": "fce42f47296a4784532fbba0fec9602cd3778fbb"
72
+ "gitHead": "daeb17e5c3fb0b625d5d988d359cd12ffa51f8c6"
73
73
  }