@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 +146 -12
- package/dist/esm/index.d.ts +6 -1
- package/dist/esm/index.js +5 -0
- package/dist/esm/inject-bridge-connection.d.ts +22 -0
- package/dist/esm/inject-bridge-connection.js +25 -0
- package/dist/esm/inject-collection-viewport.d.ts +1 -1
- package/dist/esm/inject-collection-viewport.js +1 -1
- package/dist/esm/inject-latest-operation.d.ts +25 -0
- package/dist/esm/inject-latest-operation.js +34 -0
- package/dist/esm/inject-menu-bar.d.ts +32 -0
- package/dist/esm/inject-menu-bar.js +38 -0
- package/dist/esm/view-outlet.d.ts +17 -3
- package/dist/esm/view-outlet.js +19 -4
- package/package.json +5 -10
- package/dist/esm/experimental.d.ts +0 -1
- package/dist/esm/experimental.js +0 -3
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
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
376
|
+
## Collection viewports
|
|
241
377
|
|
|
242
|
-
`injectCollectionViewport(element, options)
|
|
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.
|
|
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
|
|
package/dist/esm/index.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
package/dist/esm/view-outlet.js
CHANGED
|
@@ -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
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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": "
|
|
58
|
+
"gitHead": "318762a9d5dcdd74303ca30b095fed355a1ab21f"
|
|
64
59
|
}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export { injectCollectionViewport, type InjectCollectionViewportOptions } from "./inject-collection-viewport.js";
|
package/dist/esm/experimental.js
DELETED