@runic-artifex/angular 0.9.1 → 0.11.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
@@ -107,8 +107,18 @@ it outside its own signal tracking. A component's `page` input receives that
107
107
  reference; `injectView(this.page)` owns its connection and cleanup. Declare
108
108
  `page` as a required signal input, `input.required<DocumentReference>()`: a
109
109
  decorator `@Input() page` or an optional `input<DocumentReference>()` does not
110
- satisfy `ViewRegistry`. Missing kinds render an alert. The generated TypeScript
111
- client can also be used directly without Angular.
110
+ satisfy `ViewRegistry`. Missing kinds render an English `<p role="alert">`. The
111
+ generated TypeScript client can also be used directly without Angular.
112
+
113
+ The `missing` input replaces that alert with a template, for example with
114
+ localized text. Its context (`ViewOutletMissingContext`) passes the reference
115
+ whose kind has no component as `$implicit` and as `content`, and its markup
116
+ (including any `role`) is yours. The outlet then leaves its `error` signal unset:
117
+
118
+ ```html
119
+ <runic-view-outlet [content]="current()" [registry]="registry" [missing]="missingView" />
120
+ <ng-template #missingView let-page><p role="alert">{{ missingText(page.kind) }}</p></ng-template>
121
+ ```
112
122
 
113
123
  ## Commands
114
124
 
@@ -137,14 +147,14 @@ For example, a navigation command whose departure guard awaits a dialog's
137
147
  answer never completes while the answer waits behind it. Order such commands
138
148
  by dispatch instead: start the next one once the previous one has been sent,
139
149
  as the Notes example's
140
- [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/examples/notes-view-first/Angular/src/app/window-operations.ts)
150
+ [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/examples/notes-view-first/Angular/src/app/window-operations.ts)
141
151
  does for its navigation commands.
142
152
 
143
153
  ## Operations
144
154
 
145
155
  `injectOperation(start, options?)` observes a generated `start<Command>()` operation
146
156
  through the framework-neutral
147
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#operation-feedback-and-latest-selection)
157
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#operation-feedback-and-latest-selection)
148
158
  for the lifetime of the injection context:
149
159
 
150
160
  ```ts
@@ -166,6 +176,132 @@ accepted work. The options also take the controller's `cancel(operation)` and
166
176
  `waitForCompletion(operation, status)` callbacks, and `injector` outside an injection
167
177
  context.
168
178
 
179
+ `injectLatestOperation(options?)` admits only the newest of several reads, for example
180
+ loading the item the user selected last, through the framework-neutral
181
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#operation-feedback-and-latest-selection).
182
+ Each `run(intent)` replaces the queued intent and cancels the active read; the next
183
+ read starts only after the previous one reaches its terminal status and the intent's
184
+ optional `waitForCompletion` barrier:
185
+
186
+ ```ts
187
+ readonly load = injectLatestOperation<Item>();
188
+ select(id: string) {
189
+ const client = this.items.client();
190
+ if (client) void this.load.run({ start: () => client.startLoad(id), isCurrent: () => this.items.client() === client });
191
+ }
192
+ // @if (load.outcome()?.ok) { <item-view [item]="load.outcome()!.value" /> }
193
+ // @if (load.blocked()) { <p role="alert">Reconnect before selecting again.</p> }
194
+ ```
195
+
196
+ It returns the `injectOperation` signals plus `blocked`, with `run(intent)` and
197
+ `clear(mode?)`, which never reject. The intent carries `start` and the optional
198
+ `cancel`, `waitForCompletion` and `isCurrent` callbacks, so it captures the client or
199
+ session it belongs to. `blocked` means admission is uncertain, for example after a
200
+ lost Start reply; only `clear("replace")`, called after the application has
201
+ established a fresh session, clears it. `clear()` drops the queued intent and cancels
202
+ the active read. Destroying the injection context settles run promises without
203
+ cancelling accepted work. Pass `injector` outside an injection context.
204
+
205
+ ## Connection state
206
+
207
+ `injectBridgeConnection(options?)` follows the page's connection to its .NET
208
+ host for the lifetime of the injection context. It wraps `onBridgeConnection`
209
+ from `@runic-artifex/views` (re-exported here since 0.11, with the
210
+ `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a signal of a
211
+ `BridgeConnectionState`: `connecting`, `connected`, `reconnecting` or `lost` (a
212
+ closed set, see
213
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#connection-state)):
214
+
215
+ ```ts
216
+ import { injectBridgeConnection } from "@runic-artifex/angular";
217
+
218
+ readonly connection = injectBridgeConnection({ lostAfter: 5_000 });
219
+ // @if (connection.state() === "lost") { <p role="alert">The application stopped responding.</p> }
220
+ ```
221
+
222
+ Destroying the injection context unsubscribes. Pass `injector` outside an
223
+ injection context. Under server rendering (`PLATFORM_ID` is `"server"`) it does
224
+ not observe and stays `connecting`. An invalid `lostAfter` throws a `RangeError`.
225
+
226
+ ## In-page menu bar
227
+
228
+ `injectMenuBar(options?)` follows the declared menu bar of a Runic Desktop
229
+ window that leaves it to the page (`DesktopMenuBarPresentation.Page`) for the
230
+ lifetime of the injection context. It wraps `createMenuBarController` from
231
+ `@runic-artifex/views` (see [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#in-page-menu-bar))
232
+ and returns `{ state, invoke, handleKeyDown }`, where `state` is a signal of a
233
+ `MenuBarState`. The bar is rendered by the application's own menubar, for
234
+ example the CDK Menu's `cdkMenuBar`. Runic ships no menubar component.
235
+
236
+ ```ts
237
+ import { injectMenuBar } from "@runic-artifex/angular";
238
+
239
+ readonly menuBar = injectMenuBar({
240
+ onRequest: request => request.kind === "open" ? this.openMenu(request.menu.key) : this.focusFirstItem(),
241
+ });
242
+ // On macOS the application menu bar keeps the menus ("global"): render nothing.
243
+ // @if (menuBar.state().placement === "page") { <div cdkMenuBar>…(cdkMenuItemTriggered)="menuBar.invoke(item)"…</div> }
244
+ ```
245
+
246
+ Options are those of `createMenuBarController` (`shortcuts`, `keyboard`)
247
+ without `signal`, plus `onRequest`, which receives the `focus` and `open`
248
+ requests, and `injector`, required outside an injection context. Destroying the
249
+ injection context disposes the controller, which also returns the
250
+ `shortcuts: "app"` lease. Under server rendering (`PLATFORM_ID` is `"server"`)
251
+ it creates none and stays `connecting`.
252
+
253
+ ### With the CDK Menu
254
+
255
+ The CDK's `cdkMenuBar` with `CdkMenuTrigger.open()` for `open` requests; the
256
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
257
+ items (`cdkMenuItemCheckbox`, `cdkMenuItemRadio` in a `cdkMenuGroup`) and is
258
+ tested with real keys:
259
+
260
+ ```ts
261
+ @Component({
262
+ selector: "app-menu-bar",
263
+ imports: [CdkMenuBar, CdkMenu, CdkMenuItem, CdkMenuTrigger],
264
+ template: `
265
+ @if (menuBar.state().placement === "page") {
266
+ <div cdkMenuBar aria-label="Application">
267
+ @for (menu of menuBar.state().menus; track menu.key) {
268
+ <button cdkMenuItem [cdkMenuTriggerFor]="popup" [cdkMenuTriggerData]="{ $implicit: menu.key }"
269
+ [cdkMenuItemDisabled]="!menu.enabled">{{ menu.label }}</button>
270
+ }
271
+ </div>
272
+ }
273
+ <!-- The CDK keeps a trigger's first data, so the popup reads the current entries by key. -->
274
+ <ng-template #popup let-key>
275
+ <div cdkMenu>
276
+ @for (entry of entriesOf(key); track entry.key) {
277
+ @if (entry.kind === "separator") { <div role="separator"></div> }
278
+ @else if (entry.kind === "item") {
279
+ <button cdkMenuItem [cdkMenuItemDisabled]="!entry.enabled" [attr.aria-keyshortcuts]="entry.ariaKeyShortcuts ?? null"
280
+ (cdkMenuItemTriggered)="menuBar.invoke(entry)">{{ entry.label }} <kbd aria-hidden="true">{{ entry.shortcutText }}</kbd></button>
281
+ }
282
+ }
283
+ </div>
284
+ </ng-template>
285
+ `,
286
+ })
287
+ export class AppMenuBar {
288
+ private readonly bar = viewChild(CdkMenuBar);
289
+ private readonly items = viewChildren(CdkMenuItem);
290
+ readonly menuBar = injectMenuBar({
291
+ onRequest: request => {
292
+ const bar = this.bar();
293
+ if (request.kind === "focus") bar?.focusFirstItem("keyboard");
294
+ else if (request.kind === "open") {
295
+ const index = this.menuBar.state().menus.indexOf(request.menu);
296
+ const item = this.items()[index];
297
+ if (bar && item) { bar.setActiveMenuItem(item); item.getMenuTrigger()?.open(); }
298
+ }
299
+ },
300
+ });
301
+ entriesOf(key: string) { return this.menuBar.state().menus.find(menu => menu.key === key)?.entries ?? []; }
302
+ }
303
+ ```
304
+
169
305
  ## Errors
170
306
 
171
307
  The `error()` signal of `injectView` and of a command or operation is typed
@@ -181,7 +317,7 @@ const offline = error instanceof BridgeError && error.kind === "disconnected";
181
317
  ```
182
318
 
183
319
  `instanceof` holds for errors from every copy of the package on the page.
184
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#errors-and-diagnostics)
320
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#errors-and-diagnostics)
185
321
  lists the kinds. Any other value, such as an exception that your own connect
186
322
  function or command callback throws, arrives unchanged.
187
323
 
@@ -232,18 +368,16 @@ application's own dialog.
232
368
  departure before that is answered by the ViewModel's .NET fallback handler, or
233
369
  fails closed without one.
234
370
 
235
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.9.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
371
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.11.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
236
372
  has the .NET side and which View answers which departure. In a frontend test,
237
373
  the generated mock's `interactions.<name>.request(input)` resolves with the
238
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#testing).
374
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#testing).
239
375
 
240
- ## Collection viewports (experimental)
376
+ ## Collection viewports
241
377
 
242
- `injectCollectionViewport(element, options)`, exported from
243
- `@runic-artifex/angular/experimental` like the `@runic-artifex/views/experimental`
244
- controller it wraps, follows a fixed-row-height scroll
378
+ `injectCollectionViewport(element, options)` follows a fixed-row-height scroll
245
379
  container and returns a signal with its
246
- [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#collectionviewportoptions-experimental)
380
+ [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#collectionviewportoptions)
247
381
  range. Pass the container as a signal, such as a `viewChild`, and the options as
248
382
  a function or signal, then send the range to the ViewModel from an effect:
249
383
 
@@ -1,4 +1,9 @@
1
- export { ViewOutlet, RunicViewOutlet, type ViewRegistry } from "./view-outlet.js";
1
+ export { ViewOutlet, RunicViewOutlet, type ViewOutletMissingContext, type ViewRegistry } from "./view-outlet.js";
2
2
  export { injectView, type InjectViewOptions, type ViewHandle } from "./inject-view.js";
3
3
  export { injectCommand, type CommandHandle, type InjectCommandOptions } from "./inject-command.js";
4
4
  export { injectOperation, type InjectOperationOptions, type OperationHandle } from "./inject-operation.js";
5
+ export { injectLatestOperation, type InjectLatestOperationOptions, type LatestOperationHandle, } from "./inject-latest-operation.js";
6
+ export { injectCollectionViewport, type InjectCollectionViewportOptions } from "./inject-collection-viewport.js";
7
+ export { injectBridgeConnection, type BridgeConnectionHandle, type InjectBridgeConnectionOptions } from "./inject-bridge-connection.js";
8
+ export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
9
+ 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
@@ -2,3 +2,8 @@ export { ViewOutlet, RunicViewOutlet } from "./view-outlet.js";
2
2
  export { injectView } from "./inject-view.js";
3
3
  export { injectCommand } from "./inject-command.js";
4
4
  export { injectOperation } from "./inject-operation.js";
5
+ export { injectLatestOperation, } from "./inject-latest-operation.js";
6
+ export { injectCollectionViewport } from "./inject-collection-viewport.js";
7
+ export { injectBridgeConnection } from "./inject-bridge-connection.js";
8
+ export { onBridgeConnection } from "@runic-artifex/views";
9
+ export { injectMenuBar, } from "./inject-menu-bar.js";
@@ -0,0 +1,22 @@
1
+ import { Injector, type Signal } from "@angular/core";
2
+ import { type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
3
+ export interface BridgeConnectionHandle {
4
+ /** The connection to the .NET host, as `onBridgeConnection` reports it. */
5
+ readonly state: Signal<BridgeConnectionState>;
6
+ }
7
+ export interface InjectBridgeConnectionOptions extends BridgeConnectionOptions {
8
+ /** Required outside an injection context. */
9
+ readonly injector?: Injector;
10
+ }
11
+ /**
12
+ * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting` or
13
+ * `lost`) as a signal through `onBridgeConnection`, for the lifetime of the injection context.
14
+ * Destruction unsubscribes. Under server rendering (`PLATFORM_ID` `"server"`) it does not
15
+ * observe and stays `connecting`.
16
+ *
17
+ * ```ts
18
+ * readonly connection = injectBridgeConnection();
19
+ * // @if (connection.state() === "lost") { <p role="alert">The application stopped responding.</p> }
20
+ * ```
21
+ */
22
+ export declare function injectBridgeConnection({ injector: provided, ...options }?: InjectBridgeConnectionOptions): BridgeConnectionHandle;
@@ -0,0 +1,25 @@
1
+ import { assertInInjectionContext, DestroyRef, inject, Injector, PLATFORM_ID, signal } from "@angular/core";
2
+ import { onBridgeConnection } from "@runic-artifex/views";
3
+ /**
4
+ * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting` or
5
+ * `lost`) as a signal through `onBridgeConnection`, for the lifetime of the injection context.
6
+ * Destruction unsubscribes. Under server rendering (`PLATFORM_ID` `"server"`) it does not
7
+ * observe and stays `connecting`.
8
+ *
9
+ * ```ts
10
+ * readonly connection = injectBridgeConnection();
11
+ * // @if (connection.state() === "lost") { <p role="alert">The application stopped responding.</p> }
12
+ * ```
13
+ */
14
+ export function injectBridgeConnection({ injector: provided, ...options } = {}) {
15
+ if (!provided)
16
+ assertInInjectionContext(injectBridgeConnection);
17
+ const injector = provided ?? inject(Injector);
18
+ const state = signal("connecting", /* @ts-ignore */
19
+ ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
20
+ if (injector.get(PLATFORM_ID, null) !== "server") {
21
+ const stop = onBridgeConnection(next => state.set(next), options);
22
+ injector.get(DestroyRef).onDestroy(stop);
23
+ }
24
+ return { state: state.asReadonly() };
25
+ }
@@ -1,5 +1,5 @@
1
1
  import { ElementRef, Injector, type Signal } from "@angular/core";
2
- import { type CollectionViewport, type CollectionViewportOptions } from "@runic-artifex/views/experimental";
2
+ import { type CollectionViewport, type CollectionViewportOptions } from "@runic-artifex/views";
3
3
  export interface InjectCollectionViewportOptions {
4
4
  /** Required outside an injection context. */
5
5
  readonly injector?: Injector;
@@ -1,5 +1,5 @@
1
1
  import { assertInInjectionContext, DestroyRef, effect, ElementRef, inject, Injector, NgZone, signal, untracked } from "@angular/core";
2
- import { createCollectionViewportController } from "@runic-artifex/views/experimental";
2
+ import { createCollectionViewportController } from "@runic-artifex/views";
3
3
  /**
4
4
  * Follows a fixed-row-height scroll container and returns the rows to request
5
5
  * from .NET as a signal. Pass the container, for example
@@ -0,0 +1,25 @@
1
+ import { Injector, type Signal } from "@angular/core";
2
+ import { type LatestOperationController, type LatestOperationState } from "@runic-artifex/views";
3
+ /** Each field of the latest-operation feedback as a signal, with `run` and `clear`. */
4
+ export type LatestOperationHandle<TResult, TFailure = never> = {
5
+ readonly [K in keyof LatestOperationState<TResult, TFailure>]: Signal<LatestOperationState<TResult, TFailure>[K]>;
6
+ } & Pick<LatestOperationController<TResult, TFailure>, "run" | "clear">;
7
+ export interface InjectLatestOperationOptions {
8
+ /** Required outside an injection context. */
9
+ readonly injector?: Injector;
10
+ }
11
+ /**
12
+ * Admits only the newest selection, for reads such as "load the selected item", as signals
13
+ * for the lifetime of the injection context. Each `run(intent)` replaces the queued intent
14
+ * and cancels the active read, and the next read starts only after the previous one has
15
+ * finished (including `waitForCompletion`). `blocked` means admission is uncertain; only
16
+ * `clear("replace")`, after the application has established a fresh session, clears it.
17
+ * Destruction settles run promises without cancelling accepted work.
18
+ *
19
+ * ```ts
20
+ * readonly load = injectLatestOperation<Item>();
21
+ * select(id: string) { void this.load.run({ start: () => this.items.client()?.startLoad(id) }); }
22
+ * // @if (load.outcome()?.ok) { <item-view [item]="load.outcome()!.value" /> }
23
+ * ```
24
+ */
25
+ export declare function injectLatestOperation<TResult = void, TFailure = never>({ injector: provided }?: InjectLatestOperationOptions): LatestOperationHandle<TResult, TFailure>;
@@ -0,0 +1,34 @@
1
+ import { assertInInjectionContext, computed, DestroyRef, inject, Injector, signal } from "@angular/core";
2
+ import { createLatestOperationController, } from "@runic-artifex/views";
3
+ /**
4
+ * Admits only the newest selection, for reads such as "load the selected item", as signals
5
+ * for the lifetime of the injection context. Each `run(intent)` replaces the queued intent
6
+ * and cancels the active read, and the next read starts only after the previous one has
7
+ * finished (including `waitForCompletion`). `blocked` means admission is uncertain; only
8
+ * `clear("replace")`, after the application has established a fresh session, clears it.
9
+ * Destruction settles run promises without cancelling accepted work.
10
+ *
11
+ * ```ts
12
+ * readonly load = injectLatestOperation<Item>();
13
+ * select(id: string) { void this.load.run({ start: () => this.items.client()?.startLoad(id) }); }
14
+ * // @if (load.outcome()?.ok) { <item-view [item]="load.outcome()!.value" /> }
15
+ * ```
16
+ */
17
+ export function injectLatestOperation({ injector: provided } = {}) {
18
+ if (!provided)
19
+ assertInInjectionContext(injectLatestOperation);
20
+ const injector = provided ?? inject(Injector);
21
+ const controller = createLatestOperationController();
22
+ const state = signal(controller.current, /* @ts-ignore */
23
+ ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
24
+ controller.subscribe(() => state.set(controller.current));
25
+ injector.get(DestroyRef).onDestroy(() => controller.dispose());
26
+ const field = (key) => computed(() => state()[key]);
27
+ return {
28
+ run: controller.run, clear: controller.clear,
29
+ pending: field("pending"), admitting: field("admitting"), operation: field("operation"), status: field("status"),
30
+ outcome: field("outcome"), failure: field("failure"), error: field("error"), cancelled: field("cancelled"),
31
+ cancellationRequested: field("cancellationRequested"), cancelling: field("cancelling"),
32
+ cancellation: field("cancellation"), cancelError: field("cancelError"), blocked: field("blocked"),
33
+ };
34
+ }
@@ -0,0 +1,32 @@
1
+ import { Injector, type Signal } from "@angular/core";
2
+ import { type MenuBarController, type MenuBarControllerOptions, type MenuBarRequest, type MenuBarState } from "@runic-artifex/views";
3
+ export type { MenuBarEntry, MenuBarInvokeResult, MenuBarItem, MenuBarMenu, MenuBarRequest, MenuBarSeparator, MenuBarState, } from "@runic-artifex/views";
4
+ export interface MenuBarHandle {
5
+ /** The menu bar as the page renders it; render a bar only when `placement` is `"page"`. */
6
+ readonly state: Signal<MenuBarState>;
7
+ /** Runs an item through the native bar's command path. Rejects with a BridgeError under server rendering. */
8
+ readonly invoke: MenuBarController["invoke"];
9
+ /** Matches a `keydown` event against the items' shortcuts, for the `shortcuts: "app"` option. */
10
+ readonly handleKeyDown: MenuBarController["handleKeyDown"];
11
+ }
12
+ export interface InjectMenuBarOptions extends Omit<MenuBarControllerOptions, "signal"> {
13
+ /**
14
+ * Receives the `focus` (Alt tap, F10) and `open` (Alt plus a menu's access key) requests: focus the first
15
+ * `cdkMenuItem` of the bar or open a menu's `CdkMenuTrigger`.
16
+ */
17
+ readonly onRequest?: (request: MenuBarRequest) => void;
18
+ /** Required outside an injection context. */
19
+ readonly injector?: Injector;
20
+ }
21
+ /**
22
+ * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) as a signal, as headless
23
+ * state for the application's own menubar (for example the CDK Menu's `cdkMenuBar`), through
24
+ * `createMenuBarController`, for the lifetime of the injection context. Destruction disposes the controller. Under
25
+ * server rendering (`PLATFORM_ID` `"server"`) it creates none and stays `connecting`.
26
+ *
27
+ * ```ts
28
+ * readonly menuBar = injectMenuBar({ onRequest: request => this.onMenuRequest(request) });
29
+ * // @if (menuBar.state().placement === "page") { <div cdkMenuBar>…<button cdkMenuItem (cdkMenuItemTriggered)="menuBar.invoke(item)"> }
30
+ * ```
31
+ */
32
+ export declare function injectMenuBar({ injector: provided, onRequest, ...options }?: InjectMenuBarOptions): MenuBarHandle;
@@ -0,0 +1,38 @@
1
+ import { assertInInjectionContext, DestroyRef, inject, Injector, PLATFORM_ID, signal } from "@angular/core";
2
+ import { BridgeError, createMenuBarController, } from "@runic-artifex/views";
3
+ /**
4
+ * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) as a signal, as headless
5
+ * state for the application's own menubar (for example the CDK Menu's `cdkMenuBar`), through
6
+ * `createMenuBarController`, for the lifetime of the injection context. Destruction disposes the controller. Under
7
+ * server rendering (`PLATFORM_ID` `"server"`) it creates none and stays `connecting`.
8
+ *
9
+ * ```ts
10
+ * readonly menuBar = injectMenuBar({ onRequest: request => this.onMenuRequest(request) });
11
+ * // @if (menuBar.state().placement === "page") { <div cdkMenuBar>…<button cdkMenuItem (cdkMenuItemTriggered)="menuBar.invoke(item)"> }
12
+ * ```
13
+ */
14
+ export function injectMenuBar({ injector: provided, onRequest, ...options } = {}) {
15
+ if (!provided)
16
+ assertInInjectionContext(injectMenuBar);
17
+ const injector = provided ?? inject(Injector);
18
+ if (injector.get(PLATFORM_ID, null) === "server") {
19
+ const state = signal(Object.freeze({
20
+ status: "connecting", placement: "none", shortcuts: options.shortcuts === "app" ? "app" : "host",
21
+ accessKeyHints: false, revision: 0, menus: Object.freeze([]),
22
+ }), /* @ts-ignore */
23
+ ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
24
+ return {
25
+ state: state.asReadonly(),
26
+ invoke: () => Promise.reject(new BridgeError("unavailable", "The menu bar is not followed during server rendering.", { route: "__runicMenuBarInvoke" })),
27
+ handleKeyDown: () => false,
28
+ };
29
+ }
30
+ const controller = createMenuBarController(options);
31
+ const state = signal(controller.current, /* @ts-ignore */
32
+ ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
33
+ controller.subscribe(() => state.set(controller.current));
34
+ if (onRequest)
35
+ controller.onRequest(onRequest);
36
+ injector.get(DestroyRef).onDestroy(() => controller.dispose());
37
+ return { state: state.asReadonly(), invoke: controller.invoke, handleKeyDown: controller.handleKeyDown };
38
+ }
@@ -1,4 +1,4 @@
1
- import { type InputSignal, type Type } from "@angular/core";
1
+ import { type InputSignal, type TemplateRef, type Type } from "@angular/core";
2
2
  import type { PageReference } from "@runic-artifex/views";
3
3
  import * as i0 from "@angular/core";
4
4
  /**
@@ -12,20 +12,34 @@ export type ViewRegistry<R extends PageReference | null | undefined> = {
12
12
  }>>;
13
13
  }>;
14
14
  };
15
+ /** The context of a `missing` template: the reference without a component, as `$implicit` (`let-page`) and `content`. */
16
+ export interface ViewOutletMissingContext<R extends PageReference = PageReference> {
17
+ readonly $implicit: R;
18
+ readonly content: R;
19
+ }
15
20
  /**
16
21
  * Headless host for a selected logical .NET View. A changed reference remounts its component, and
17
- * the projected content renders while there is no reference.
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:
24
+ *
25
+ * ```html
26
+ * <runic-view-outlet [content]="state()?.main" [registry]="pages" [missing]="missingView" />
27
+ * <ng-template #missingView let-page><p role="alert">{{ missingText(page.kind) }}</p></ng-template>
28
+ * ```
29
+ *
18
30
  * The element keeps Angular's prefix convention: `<runic-view-outlet [content]="…" [registry]="…" />`.
19
31
  */
20
32
  export declare class ViewOutlet<R extends PageReference = PageReference> {
21
33
  readonly content: InputSignal<R | null | undefined>;
22
34
  readonly registry: InputSignal<ViewRegistry<R>>;
35
+ /** Renders a reference whose kind has no registered component instead of the English alert. */
36
+ readonly missing: InputSignal<TemplateRef<ViewOutletMissingContext<R>> | undefined>;
23
37
  readonly error: import("@angular/core").WritableSignal<string | undefined>;
24
38
  private readonly mount;
25
39
  private readonly selected;
26
40
  constructor();
27
41
  static ɵfac: i0.ɵɵFactoryDeclaration<ViewOutlet<any>, never>;
28
- static ɵcmp: i0.ɵɵComponentDeclaration<ViewOutlet<any>, "runic-view-outlet", never, { "content": { "alias": "content"; "required": false; "isSignal": true; }; "registry": { "alias": "registry"; "required": true; "isSignal": true; }; }, {}, never, ["*"], true, never>;
42
+ 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>;
29
43
  }
30
44
  /**
31
45
  * The name of {@link ViewOutlet} before 0.7.0-preview.7, where React, Vue and Svelte already used
@@ -9,7 +9,14 @@ const outletTemplate = `
9
9
  `;
10
10
  /**
11
11
  * Headless host for a selected logical .NET View. A changed reference remounts its component, and
12
- * the projected content renders while there is no reference.
12
+ * the projected content renders while there is no reference. A kind without a component renders
13
+ * the `missing` template, for example localized text, or an English alert without it:
14
+ *
15
+ * ```html
16
+ * <runic-view-outlet [content]="state()?.main" [registry]="pages" [missing]="missingView" />
17
+ * <ng-template #missingView let-page><p role="alert">{{ missingText(page.kind) }}</p></ng-template>
18
+ * ```
19
+ *
13
20
  * The element keeps Angular's prefix convention: `<runic-view-outlet [content]="…" [registry]="…" />`.
14
21
  */
15
22
  export class ViewOutlet {
@@ -17,6 +24,9 @@ export class ViewOutlet {
17
24
  ...(ngDevMode ? [undefined, { debugName: "content" }] : /* istanbul ignore next */ []));
18
25
  registry = input.required(/* @ts-ignore */
19
26
  ...(ngDevMode ? [{ debugName: "registry" }] : /* istanbul ignore next */ []));
27
+ /** Renders a reference whose kind has no registered component instead of the English alert. */
28
+ missing = input(/* @ts-ignore */
29
+ ...(ngDevMode ? [undefined, { debugName: "missing" }] : /* istanbul ignore next */ []));
20
30
  error = signal(undefined, /* @ts-ignore */
21
31
  ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
22
32
  mount = viewChild.required("mount", { ...(ngDevMode ? { debugName: "mount" } : /* istanbul ignore next */ {}), read: ViewContainerRef });
@@ -26,7 +36,8 @@ export class ViewOutlet {
26
36
  return undefined;
27
37
  // A registry built without `satisfies ViewRegistry<R>` may miss a kind at run time.
28
38
  const component = this.registry()[reference.kind];
29
- return { reference, component };
39
+ // `missing` is a dependency only while the kind has no component, so changing it never remounts one.
40
+ return { reference, component, missing: component ? undefined : this.missing() };
30
41
  }, /* @ts-ignore */
31
42
  ...(ngDevMode ? [{ debugName: "selected" }] : /* istanbul ignore next */ []));
32
43
  constructor() {
@@ -41,6 +52,10 @@ export class ViewOutlet {
41
52
  if (!selection)
42
53
  return;
43
54
  if (!selection.component) {
55
+ if (selection.missing) {
56
+ container.createEmbeddedView(selection.missing, { $implicit: selection.reference, content: selection.reference });
57
+ return;
58
+ }
44
59
  this.error.set(`No web component is registered for ${selection.reference.kind}.`);
45
60
  return;
46
61
  }
@@ -50,12 +65,12 @@ export class ViewOutlet {
50
65
  });
51
66
  }
52
67
  static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.2.3", ngImport: i0, type: ViewOutlet, deps: [], target: i0.ɵɵFactoryTarget.Component });
53
- static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.2.3", type: ViewOutlet, isStandalone: true, selector: "runic-view-outlet", inputs: { content: { classPropertyName: "content", publicName: "content", isSignal: true, isRequired: false, transformFunction: null }, registry: { classPropertyName: "registry", publicName: "registry", isSignal: true, isRequired: true, transformFunction: null } }, viewQueries: [{ propertyName: "mount", first: true, predicate: ["mount"], descendants: true, read: ViewContainerRef, isSignal: true }], ngImport: i0, template: "\n <ng-container #mount />\n @if (!content()) { <ng-content /> }\n @if (error(); as issue) { <p role=\"alert\">{{ issue }}</p> }\n ", isInline: true });
68
+ static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.2.3", type: ViewOutlet, isStandalone: true, selector: "runic-view-outlet", inputs: { content: { classPropertyName: "content", publicName: "content", isSignal: true, isRequired: false, transformFunction: null }, registry: { classPropertyName: "registry", publicName: "registry", isSignal: true, isRequired: true, transformFunction: null }, missing: { classPropertyName: "missing", publicName: "missing", isSignal: true, isRequired: false, transformFunction: null } }, viewQueries: [{ propertyName: "mount", first: true, predicate: ["mount"], descendants: true, read: ViewContainerRef, isSignal: true }], ngImport: i0, template: "\n <ng-container #mount />\n @if (!content()) { <ng-content /> }\n @if (error(); as issue) { <p role=\"alert\">{{ issue }}</p> }\n ", isInline: true });
54
69
  }
55
70
  i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.3", ngImport: i0, type: ViewOutlet, decorators: [{
56
71
  type: Component,
57
72
  args: [{ selector: "runic-view-outlet", standalone: true, template: outletTemplate }]
58
- }], ctorParameters: () => [], propDecorators: { content: [{ type: i0.Input, args: [{ isSignal: true, alias: "content", required: false }] }], registry: [{ type: i0.Input, args: [{ isSignal: true, alias: "registry", required: true }] }], mount: [{ type: i0.ViewChild, args: ["mount", { ...{ read: ViewContainerRef }, isSignal: true }] }] } });
73
+ }], 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 }] }] } });
59
74
  /**
60
75
  * The name of {@link ViewOutlet} before 0.7.0-preview.7, where React, Vue and Svelte already used
61
76
  * `ViewOutlet`. 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.9.1",
3
+ "version": "0.11.0",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
@@ -8,16 +8,11 @@
8
8
  "import": "./dist/esm/index.js",
9
9
  "default": "./dist/esm/index.js"
10
10
  },
11
- "./experimental": {
12
- "types": "./dist/esm/experimental.d.ts",
13
- "import": "./dist/esm/experimental.js",
14
- "default": "./dist/esm/experimental.js"
15
- },
16
11
  "./package.json": "./package.json"
17
12
  },
18
13
  "peerDependencies": {
19
14
  "@angular/core": ">=22.0.0 <23",
20
- "@runic-artifex/views": "0.9.1"
15
+ "@runic-artifex/views": "0.11.0"
21
16
  },
22
17
  "description": "Angular outlet and signals for Runic Views",
23
18
  "license": "MIT",
@@ -26,7 +21,7 @@
26
21
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
27
22
  "directory": "packages/web/angular"
28
23
  },
29
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/angular#readme",
24
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/angular#readme",
30
25
  "bugs": {
31
26
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
32
27
  },
@@ -50,7 +45,7 @@
50
45
  "pack:check": "bun pm pack --dry-run"
51
46
  },
52
47
  "devDependencies": {
53
- "@runic-artifex/views": "0.9.1",
48
+ "@runic-artifex/views": "0.11.0",
54
49
  "@angular/common": "22.2.3",
55
50
  "@angular/compiler": "22.2.3",
56
51
  "@angular/compiler-cli": "22.2.3",
@@ -60,5 +55,5 @@
60
55
  "typescript": "6.0.3",
61
56
  "vitest": "5.0.3"
62
57
  },
63
- "gitHead": "7df2f00a9800c180e266ca545d4d6a03bf78dc89"
58
+ "gitHead": "318762a9d5dcdd74303ca30b095fed355a1ab21f"
64
59
  }
@@ -1 +0,0 @@
1
- export { injectCollectionViewport, type InjectCollectionViewportOptions } from "./inject-collection-viewport.js";
@@ -1,3 +0,0 @@
1
- // `@runic-artifex/angular/experimental`: helpers whose shape may still change in a minor release
2
- // (docs/experimental.md). Graduation moves an export to `@runic-artifex/angular`.
3
- export { injectCollectionViewport } from "./inject-collection-viewport.js";