@runic-artifex/angular 0.19.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +130 -23
  2. package/dist/fesm2022/runic-artifex-angular-experimental.mjs +285 -0
  3. package/dist/fesm2022/runic-artifex-angular-experimental.mjs.map +1 -0
  4. package/dist/fesm2022/runic-artifex-angular-forms.mjs +246 -0
  5. package/dist/fesm2022/runic-artifex-angular-forms.mjs.map +1 -0
  6. package/dist/fesm2022/runic-artifex-angular.mjs +975 -0
  7. package/dist/fesm2022/runic-artifex-angular.mjs.map +1 -0
  8. package/dist/types/runic-artifex-angular-experimental.d.ts +85 -0
  9. package/dist/types/runic-artifex-angular-forms.d.ts +72 -0
  10. package/dist/types/runic-artifex-angular.d.ts +626 -0
  11. package/package.json +20 -17
  12. package/dist/esm/experimental.d.ts +0 -39
  13. package/dist/esm/experimental.js +0 -64
  14. package/dist/esm/forms/index.d.ts +0 -2
  15. package/dist/esm/forms/index.js +0 -2
  16. package/dist/esm/forms/runic-field.directive.d.ts +0 -48
  17. package/dist/esm/forms/runic-field.directive.js +0 -195
  18. package/dist/esm/forms/signal-forms.d.ts +0 -19
  19. package/dist/esm/forms/signal-forms.js +0 -29
  20. package/dist/esm/index.d.ts +0 -24
  21. package/dist/esm/index.js +0 -25
  22. package/dist/esm/inject-appearance.d.ts +0 -19
  23. package/dist/esm/inject-appearance.js +0 -28
  24. package/dist/esm/inject-bridge-connection.d.ts +0 -22
  25. package/dist/esm/inject-bridge-connection.js +0 -26
  26. package/dist/esm/inject-collection-viewport.d.ts +0 -13
  27. package/dist/esm/inject-collection-viewport.js +0 -31
  28. package/dist/esm/inject-command.d.ts +0 -35
  29. package/dist/esm/inject-command.js +0 -33
  30. package/dist/esm/inject-field.d.ts +0 -66
  31. package/dist/esm/inject-field.js +0 -58
  32. package/dist/esm/inject-form.d.ts +0 -40
  33. package/dist/esm/inject-form.js +0 -48
  34. package/dist/esm/inject-latest-operation.d.ts +0 -25
  35. package/dist/esm/inject-latest-operation.js +0 -35
  36. package/dist/esm/inject-menu-bar.d.ts +0 -32
  37. package/dist/esm/inject-menu-bar.js +0 -39
  38. package/dist/esm/inject-operation.d.ts +0 -23
  39. package/dist/esm/inject-operation.js +0 -33
  40. package/dist/esm/inject-query-collection.d.ts +0 -29
  41. package/dist/esm/inject-query-collection.js +0 -64
  42. package/dist/esm/inject-text-field.d.ts +0 -55
  43. package/dist/esm/inject-text-field.js +0 -51
  44. package/dist/esm/inject-text.d.ts +0 -57
  45. package/dist/esm/inject-text.js +0 -107
  46. package/dist/esm/inject-view-resource.d.ts +0 -39
  47. package/dist/esm/inject-view-resource.js +0 -98
  48. package/dist/esm/inject-view.d.ts +0 -41
  49. package/dist/esm/inject-view.js +0 -67
  50. package/dist/esm/instance.d.ts +0 -34
  51. package/dist/esm/instance.js +0 -48
  52. package/dist/esm/view-outlet.d.ts +0 -101
  53. package/dist/esm/view-outlet.js +0 -177
@@ -0,0 +1,626 @@
1
+ import * as i0 from "@angular/core";
2
+ import { ElementRef, InjectionToken, Injector, InputSignal, OnDestroy, PipeTransform, Provider, Resource, Signal, TemplateRef, Type } from "@angular/core";
3
+ import { Appearance, AppearanceColorScheme, AppearanceContrast, AppearanceSystemColors, BlobRef, BridgeConnectionOptions, BridgeConnectionState, BridgeField, BridgeOperation, BridgeOutcomeFailure, CollectionViewport, CollectionViewportOptions, DocumentLocaleOptions, FieldBaseline, FieldController, FieldDefinition, FieldError, FieldErrorArguments, FieldErrorReason, FieldErrorText, FieldOptions, FieldState, FormField, FormFields, FormState, FormSubmitOptions, FormSubmitResult, HostAppearance, LatestOperationController, LatestOperationState, MenuBarController, MenuBarControllerOptions, MenuBarEntry, MenuBarInvokeResult, MenuBarItem, MenuBarMenu, MenuBarRequest, MenuBarSeparator, MenuBarState, NavigationPathChange, NavigationPathOptions, NavigationReply, OperationController, OperationControllerOptions, OperationState, PageReference, QueryCollection, QueryViewport, QueryViewportOptions, RegionCollection, RegionEntry, RegionOutcome, RegionSlot, RunicBlob, RunicInstance, RunicInstanceOptions, RunicQuery, TextReference, TextTranslations, UploadOptions, UploadProgress, ViewClient, ViewRegistryPage, ViewSource, appearance, commitAllFields, configureFieldErrorText, configureTranslatedText, createRunicInstance, fieldErrorText, installBackNavigation, installNavigationPath, navigateBack, onAppearance, onBridgeConnection, onNavigationPath, openNavigationPath, pageInstance, regionEntries, resolveText, selectedRegion, syncDocumentLocale, textDirection, upload, windowLocale } from "@runic-artifex/views";
4
+ /**
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. A component whose `page` input is a
7
+ * shared page reference (`[RunicSharedClient]`), such as `ResultPagePageReference`, registers for each of its kinds.
8
+ */
9
+ type ViewRegistry<R extends PageReference | null | undefined> = { readonly [K in NonNullable<R>["kind"]]: PageComponent<ViewRegistryPage<R, K>>; };
10
+ type PageComponent<P> = P extends unknown ? Type<{
11
+ readonly page: InputSignal<P>;
12
+ }> : never;
13
+ /** The context of a `missing` template: the reference without a component, as `$implicit` (`let-page`) and `content`. */
14
+ interface ViewOutletMissingContext<R extends PageReference = PageReference> {
15
+ readonly $implicit: R;
16
+ readonly content: R;
17
+ }
18
+ /**
19
+ * Headless host for a selected logical .NET View. A changed reference remounts its component, and
20
+ * the projected content renders while there is no reference. A kind without a component renders
21
+ * the `missing` template, for example localized text. Without it, a development build (`isDevMode()`) renders an
22
+ * English alert, and a production build renders nothing and reports the kind (`installErrorReporting`,
23
+ * `onBridgeDiagnostic`):
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
+ *
30
+ * The element keeps Angular's prefix convention: `<runic-view-outlet [content]="…" [registry]="…" />`.
31
+ */
32
+ export declare class ViewOutlet<R extends PageReference = PageReference> {
33
+ readonly content: InputSignal<R | null | undefined>;
34
+ readonly registry: InputSignal<ViewRegistry<R>>;
35
+ /** Renders a reference whose kind has no registered component instead of the development alert. */
36
+ readonly missing: InputSignal<TemplateRef<ViewOutletMissingContext<R>> | undefined>;
37
+ readonly error: import("@angular/core").WritableSignal<string | undefined>;
38
+ private readonly mount;
39
+ private readonly selected;
40
+ constructor();
41
+ static ɵfac: i0.ɵɵFactoryDeclaration<ViewOutlet<any>, never>;
42
+ static ɵcmp: i0.ɵɵComponentDeclaration<ViewOutlet<any>, "runic-view-outlet", never, {
43
+ "content": {
44
+ "alias": "content";
45
+ "required": false;
46
+ "isSignal": true;
47
+ };
48
+ "registry": {
49
+ "alias": "registry";
50
+ "required": true;
51
+ "isSignal": true;
52
+ };
53
+ "missing": {
54
+ "alias": "missing";
55
+ "required": false;
56
+ "isSignal": true;
57
+ };
58
+ }, {}, never, ["*"], true, never>;
59
+ }
60
+ /** How {@link RegionOutlets} renders the regions of a collection. */
61
+ type RegionOutletsMode = "keep-mounted" | "selected";
62
+ /**
63
+ * Attributes that {@link RegionOutlets} sets on a region's wrapper, such as `id`, `role` and `aria-labelledby`. A
64
+ * `null` or `undefined` value leaves the attribute out. `hidden`, `style` and `data-region-key` stay controlled by
65
+ * the outlet and are ignored here.
66
+ */
67
+ type RegionPanelAttributes = Readonly<Record<string, string | null | undefined>>;
68
+ /**
69
+ * Renders a {@link ViewOutlet} for the regions of a region collection, each in a `<div data-region-key>` tracked by
70
+ * the region's key. A region that is not selected is rendered with `hidden` and an inline `display: none`, which
71
+ * author CSS without `!important` cannot override. A new content reference in a region remounts only that region's
72
+ * component. The projected content renders while the collection has no region, and `missing` is passed to each
73
+ * outlet. `panelProps` returns attributes for each wrapper, so a tab can point `aria-controls` at its panel:
74
+ *
75
+ * ```html
76
+ * <runic-region-outlets [collection]="state()?.documents" [registry]="pages" [panelProps]="panel">No open documents</runic-region-outlets>
77
+ * ```
78
+ *
79
+ * `mode` `"keep-mounted"` (the default) renders every region and hides all but the selected one, so each region
80
+ * keeps its component and DOM. `"selected"` renders only the selected region.
81
+ */
82
+ export declare class RegionOutlets<R extends PageReference = PageReference> {
83
+ readonly collection: InputSignal<RegionCollection<R> | null | undefined>;
84
+ readonly registry: InputSignal<ViewRegistry<R>>;
85
+ /** Renders a reference whose kind has no registered component instead of the English alert. */
86
+ readonly missing: InputSignal<TemplateRef<ViewOutletMissingContext<R>> | undefined>;
87
+ readonly mode: InputSignal<RegionOutletsMode>;
88
+ /** Returns attributes for a region's wrapper, for example `{ id, role: "tabpanel", "aria-labelledby" }`. */
89
+ readonly panelProps: InputSignal<((entry: RegionEntry<R>) => RegionPanelAttributes) | undefined>;
90
+ protected readonly shown: import("@angular/core").Signal<{
91
+ region: RegionEntry<R>;
92
+ attributes: Readonly<Record<string, string | null | undefined>> | undefined;
93
+ }[]>;
94
+ static ɵfac: i0.ɵɵFactoryDeclaration<RegionOutlets<any>, never>;
95
+ static ɵcmp: i0.ɵɵComponentDeclaration<RegionOutlets<any>, "runic-region-outlets", never, {
96
+ "collection": {
97
+ "alias": "collection";
98
+ "required": false;
99
+ "isSignal": true;
100
+ };
101
+ "registry": {
102
+ "alias": "registry";
103
+ "required": true;
104
+ "isSignal": true;
105
+ };
106
+ "missing": {
107
+ "alias": "missing";
108
+ "required": false;
109
+ "isSignal": true;
110
+ };
111
+ "mode": {
112
+ "alias": "mode";
113
+ "required": false;
114
+ "isSignal": true;
115
+ };
116
+ "panelProps": {
117
+ "alias": "panelProps";
118
+ "required": false;
119
+ "isSignal": true;
120
+ };
121
+ }, {}, never, ["*"], true, never>;
122
+ }
123
+ /**
124
+ * The name of {@link ViewOutlet} before 0.7.0-preview.7, where React, Vue and Svelte already used
125
+ * `ViewOutlet`. It is the same component class, so it renders the same `<runic-view-outlet>` element
126
+ * without a second component definition for that selector (NG0912).
127
+ * @deprecated Import `ViewOutlet` instead; this alias is removed in the next major release.
128
+ */
129
+ export declare const RunicViewOutlet: typeof ViewOutlet;
130
+ /**
131
+ * The name of {@link ViewOutlet} before 0.7.0-preview.7.
132
+ * @deprecated Import `ViewOutlet` instead; this alias is removed in the next major release.
133
+ */
134
+ export type RunicViewOutlet<R extends PageReference = PageReference> = ViewOutlet<R>;
135
+ interface ViewHandle<TClient extends ViewClient> {
136
+ /** The latest state, or undefined until the client connects. */
137
+ readonly state: Signal<TClient["snapshot"] | undefined>;
138
+ /** The connected client for commands, or undefined until it connects. */
139
+ readonly client: Signal<TClient | undefined>;
140
+ /** The connection failure, if any. */
141
+ readonly error: Signal<unknown>;
142
+ /** True while a reference is connecting. */
143
+ readonly pending: Signal<boolean>;
144
+ /** Connects a reference again after a failure. */
145
+ retry(): void;
146
+ }
147
+ interface InjectViewOptions<TClient extends ViewClient> {
148
+ /** Required outside an injection context. */
149
+ readonly injector?: Injector;
150
+ /** Releases a client this helper connected. Defaults to `client.dispose()`. */
151
+ readonly release?: (client: TClient) => void;
152
+ /**
153
+ * Milliseconds a client this helper connected stays connected after the component unmounts or the source changes,
154
+ * for the next helper that follows the same reference (StrictMode, HMR, `<Activity>`, A→B→A navigation). `0`
155
+ * disposes it at once. Defaults to 2000. Read once, when the helper is created.
156
+ */
157
+ readonly keepAlive?: number;
158
+ }
159
+ /**
160
+ * Connects a generated View reference for the lifetime of the injection
161
+ * context (normally a component) and exposes its state as signals. Pass a
162
+ * signal, such as a `page` input, to follow it: a changed reference releases
163
+ * the previous client and connects the new one.
164
+ *
165
+ * A released client stays connected for `keepAlive` milliseconds (2000 by
166
+ * default), and the next `injectView` of the same reference takes it over with
167
+ * its state: an `@if` that toggles, HMR and A→B→A navigation show the View at
168
+ * once instead of opening the route again.
169
+ *
170
+ * A reference is identified by its `connect` function, so a signal producing a
171
+ * new `{ connect: connectShell }` object does not reconnect.
172
+ */
173
+ export declare function injectView<TClient extends ViewClient>(source: Signal<ViewSource<TClient>> | ViewSource<TClient>, options?: InjectViewOptions<TClient>): ViewHandle<TClient>;
174
+ /**
175
+ * A View connection as an Angular `Resource`: `value()` is the View's state, `status()` is `loading` until the
176
+ * client connected (`reloading` after `reload()`), then `resolved`, or `error` with `error()` the connection
177
+ * failure; `idle` while the source is `null` or `undefined`.
178
+ */
179
+ interface ViewResource<TClient extends ViewClient> extends Resource<TClient["snapshot"] | undefined> {
180
+ /** The connected client for commands, or undefined until it connects. */
181
+ readonly client: Signal<TClient | undefined>;
182
+ /** Connects again, for example after a failure. Returns false while the source is `null` or `undefined`. */
183
+ reload(): boolean;
184
+ /** Releases the client and returns the resource to `idle`; the injector's destruction does this too. */
185
+ destroy(): void;
186
+ }
187
+ type InjectViewResourceOptions<TClient extends ViewClient> = InjectViewOptions<TClient>;
188
+ /**
189
+ * Connects a generated View reference as an Angular `resource()` for the lifetime of the injection context, the
190
+ * asynchronous counterpart of `injectView` (D053.11): a template branches on `hasValue()`, `isLoading()` and
191
+ * `error()` as for any resource, and `value()` is never `undefined` once `hasValue()` is true.
192
+ *
193
+ * ```ts
194
+ * readonly page = input.required<CounterPageReference>();
195
+ * readonly counter = injectViewResource(this.page);
196
+ * ```
197
+ * ```html
198
+ * @if (counter.hasValue()) {
199
+ * <button (click)="counter.client()?.increment()">{{ counter.value().count }}</button>
200
+ * } @else if (counter.error()) {
201
+ * <p role="alert">{{ describe(counter.error()) }}</p> <button (click)="counter.reload()">Retry</button>
202
+ * } @else { <p>Connecting…</p> }
203
+ * ```
204
+ *
205
+ * A changed reference (by its `connect` function) releases the previous client and loads the new one. Released
206
+ * clients are kept for `keepAlive` milliseconds, as with `injectView`, so a component that is created again
207
+ * resolves at once.
208
+ */
209
+ export declare function injectViewResource<TClient extends ViewClient>(source: Signal<ViewSource<TClient>> | ViewSource<TClient>, options?: InjectViewResourceOptions<TClient>): ViewResource<TClient>;
210
+ interface CommandHandle<TArgs extends readonly unknown[], TResult, TFailure = BridgeOutcomeFailure<TResult>> {
211
+ /**
212
+ * Runs the command. Resolves to its result, including a `BridgeOutcome` with a
213
+ * declared failure, which `failure` then holds, or to undefined after an
214
+ * unexpected failure, which `error` then holds. Never rejects.
215
+ */
216
+ run(...args: TArgs): Promise<TResult | undefined>;
217
+ /** True while a run is in flight. */
218
+ readonly pending: Signal<boolean>;
219
+ /** Why the latest run failed unexpectedly, until the next run starts. */
220
+ readonly error: Signal<unknown>;
221
+ /**
222
+ * The declared failure of the latest run, for a command that resolves a
223
+ * `BridgeOutcome`, until the next run starts. A superseded run sets neither.
224
+ */
225
+ readonly failure: Signal<TFailure | undefined>;
226
+ /** Clears `error` and `failure`. */
227
+ reset(): void;
228
+ }
229
+ interface InjectCommandOptions {
230
+ /** Required outside an injection context. */
231
+ readonly injector?: Injector;
232
+ }
233
+ /**
234
+ * Tracks a command's pending state and failure as signals for the lifetime of
235
+ * the injection context. The command may read signals, such as a client:
236
+ *
237
+ * ```ts
238
+ * readonly increment = injectCommand(() => this.counter.client()?.increment());
239
+ * // <button [disabled]="!counter.client() || increment.pending()" (click)="increment.run()">
240
+ * ```
241
+ */
242
+ export declare function injectCommand<TArgs extends readonly unknown[], TReturn>(command: (...args: TArgs) => TReturn, options?: InjectCommandOptions): CommandHandle<TArgs, Awaited<TReturn>>;
243
+ /** Each field of the operation's feedback as a signal, with `run`, `cancel` and `reset`. */
244
+ type OperationHandle<TArgs extends readonly unknown[], TResult, TFailure = never> = { readonly [K in keyof OperationState<TResult, TFailure>]: Signal<OperationState<TResult, TFailure>[K]>; } & Pick<OperationController<TArgs, TResult, TFailure>, "run" | "cancel" | "reset">;
245
+ interface InjectOperationOptions<TResult, TFailure = never> extends OperationControllerOptions<TResult, TFailure> {
246
+ /** Required outside an injection context. */
247
+ readonly injector?: Injector;
248
+ }
249
+ /**
250
+ * Tracks Start admission, pending work, cancellation and terminal feedback of a
251
+ * generated `start<Command>()` operation as signals for the lifetime of the
252
+ * injection context. A run that ends `cancelled` sets `cancelled`, not `error`.
253
+ * Destruction settles run promises without cancelling accepted work.
254
+ *
255
+ * ```ts
256
+ * readonly push = injectOperation((remote: string) => this.workspace.client()?.startPush(remote));
257
+ * // <button [disabled]="push.pending()" (click)="push.run('origin')">Push</button>
258
+ * // @if (push.cancelled()) { <p role="status">Push cancelled.</p> }
259
+ * ```
260
+ */
261
+ export declare function injectOperation<TArgs extends readonly unknown[], TResult, TFailure = never>(start: (...args: TArgs) => BridgeOperation<TResult, TFailure> | undefined | PromiseLike<BridgeOperation<TResult, TFailure> | undefined>, { injector: provided, ...options }?: InjectOperationOptions<TResult, TFailure>): OperationHandle<TArgs, TResult, TFailure>;
262
+ /** The View a field binds to: an {@link injectView} handle, or any pair of state and client signals. */
263
+ interface FieldView<TClient extends ViewClient> {
264
+ readonly state: Signal<TClient["snapshot"] | undefined>;
265
+ readonly client: Signal<TClient | undefined>;
266
+ }
267
+ interface InjectFieldOptions<TValue = any> extends FieldOptions<TValue> {
268
+ /** Required outside an injection context. */
269
+ readonly injector?: Injector;
270
+ }
271
+ /** One View member bound to an input, as signals. See `FieldState` and `FieldController` in `@runic-artifex/views`. */
272
+ interface FieldHandle<TValue> {
273
+ /** The draft while one exists, otherwise the member's value in the View's state. */
274
+ readonly value: Signal<TValue>;
275
+ /** What a text input shows: the text typed while it does not parse or still means `value`, otherwise `value` formatted. */
276
+ readonly text: Signal<string>;
277
+ /**
278
+ * True while a draft exists, from the first input until the last write settled and the state caught up, and after a
279
+ * failed write. Keep the input enabled while it is true, rather than disabling it on the View's busy state, which
280
+ * the field's own write causes.
281
+ */
282
+ readonly editing: Signal<boolean>;
283
+ /** Why the latest write or text failed: a `BridgeError` of the write, or a `FieldError`. `undefined` otherwise. */
284
+ readonly error: Signal<unknown>;
285
+ /** The member's validation messages; `[]` when valid. */
286
+ readonly errors: Signal<readonly string[]>;
287
+ /** The producer's value and version while a checked write's `conflict` keeps the draft. */
288
+ readonly conflict: Signal<FieldBaseline<TValue> | undefined>;
289
+ /** The member's validation is in progress, such as an asynchronous rule that is still checking: show "checking…". */
290
+ readonly validating: Signal<boolean>;
291
+ /** The definition's `kind`, `nullable`, `integer` and `choices`. */
292
+ readonly field: FieldController<unknown, unknown, TValue>["field"];
293
+ /** The user changed the value, such as a checkbox's `checked`. */
294
+ input(value: TValue): void;
295
+ /** The user changed the text: pass the `input` event, or the text. It is parsed for the field's kind. */
296
+ inputText(event: Event | string): void;
297
+ /** An IME composition started: the text is kept but not written until it ends. Bind it to `compositionstart`. */
298
+ compositionStart(): void;
299
+ /** The IME composition ended: pass the `compositionend` event, or the text, which is then written. */
300
+ compositionEnd(event: Event | string): void;
301
+ /**
302
+ * The user is done with the field (bind it to `blur`): with `commit: "pause"` the draft is written now. Resolves
303
+ * with the field's state once its writes settled, so a command that depends on the field can follow it.
304
+ */
305
+ commit(): Promise<FieldState<TValue>>;
306
+ /** Writes the draft again after a failed write; after a `conflict`, over the producer's value. */
307
+ retry(): void;
308
+ /** Drops the draft, the error and a conflict and shows the View's value. Writes in flight still complete. */
309
+ reset(): void;
310
+ }
311
+ /**
312
+ * Binds one member of a View to an input for the lifetime of the injection context, through
313
+ * `createFieldController`: pass a generated descriptor such as `EditorFields.title`. Typing never loses characters,
314
+ * nothing is written during IME composition, checked-write receipts and the member's validation show as `error`,
315
+ * `errors` and `conflict`, and once the last write settled the field shows the View's value.
316
+ *
317
+ * ```ts
318
+ * readonly editor = injectView(this.page);
319
+ * readonly title = injectField(this.editor, EditorFields.title);
320
+ * // <input [runicField]="title"> with RunicFieldDirective from @runic-artifex/angular/forms, or by hand:
321
+ * // <input [value]="title.text()" (input)="title.inputText($event)" (blur)="title.commit()"
322
+ * // (compositionstart)="title.compositionStart()" (compositionend)="title.compositionEnd($event)">
323
+ * ```
324
+ */
325
+ 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>;
326
+ /** A field as {@link injectForm} reads it: an `injectField` handle. */
327
+ interface FormFieldHandle extends FormField {
328
+ readonly editing: Signal<boolean>;
329
+ readonly validating: Signal<boolean>;
330
+ readonly errors: Signal<readonly string[]>;
331
+ readonly error: Signal<unknown>;
332
+ }
333
+ interface InjectFormOptions {
334
+ /** Whether the View reports unsaved changes, such as `computed(() => this.editor.state()?.isDirty === true)`. */
335
+ readonly dirty?: Signal<boolean | undefined>;
336
+ }
337
+ /** A form bound by {@link injectForm}: its state as signals, and its actions. */
338
+ interface FormHandle {
339
+ /** The whole state. */
340
+ readonly state: Signal<FormState>;
341
+ readonly dirty: Signal<boolean>;
342
+ readonly editing: Signal<boolean>;
343
+ readonly validating: Signal<boolean>;
344
+ readonly pending: Signal<boolean>;
345
+ readonly valid: Signal<boolean>;
346
+ readonly submitting: Signal<boolean>;
347
+ /** Commits every field, waits for their writes and runs `command` unless a field's write or text failed. */
348
+ submit<T>(command: () => T | PromiseLike<T>, options?: FormSubmitOptions): Promise<FormSubmitResult<T>>;
349
+ /** Commits every field and resolves once their writes settled. */
350
+ commit(): Promise<FormState>;
351
+ /** Resets every field. */
352
+ reset(): void;
353
+ }
354
+ /**
355
+ * One dirty, pending and valid state over `injectField` handles, and a `submit` that writes every field before its
356
+ * command (`createFormController` in `@runic-artifex/views`). It needs no injection context.
357
+ *
358
+ * ```ts
359
+ * readonly form = injectForm({ title: this.title, body: this.body }, { dirty: computed(() => this.editor.state()?.isDirty === true) });
360
+ * // <button [disabled]="!form.valid() || form.submitting()" (click)="form.submit(() => editor.client()!.save())">Save</button>
361
+ * ```
362
+ */
363
+ export declare function injectForm(fields: FormFields<FormFieldHandle>, options?: InjectFormOptions): FormHandle;
364
+ /** A text input bound to one View member. */
365
+ interface TextFieldHandle {
366
+ /** What the input shows: the draft while one exists, otherwise the member's value in the View's state. */
367
+ readonly value: Signal<string>;
368
+ /**
369
+ * True while a draft exists, from the first input until the last write settled and the state caught up, and after a
370
+ * failed write. Keep the input enabled while it is true, rather than disabling it on the View's busy state, which
371
+ * the field's own write causes.
372
+ */
373
+ readonly editing: Signal<boolean>;
374
+ /** Why the latest write failed, until the next input or `reset()`. */
375
+ readonly error: Signal<unknown>;
376
+ /** The user changed the text: pass the `input` event, or the new text. */
377
+ input(event: Event | string): void;
378
+ /** An IME composition started: the text is kept but not written until it ends. Bind it to `compositionstart`. */
379
+ compositionStart(): void;
380
+ /** The IME composition ended: pass the `compositionend` event, or the text, which is then written. */
381
+ compositionEnd(event: Event | string): void;
382
+ /** Drops the draft and the error and shows the View's value. Writes in flight still complete. */
383
+ reset(): void;
384
+ }
385
+ interface InjectTextFieldOptions {
386
+ /** Required outside an injection context. */
387
+ readonly injector?: Injector;
388
+ /**
389
+ * With `true` (the default) at most one write is in flight, and text typed meanwhile is written next, as one
390
+ * value. With `false` every input is written.
391
+ */
392
+ readonly coalesce?: boolean;
393
+ /** With `true` (the default) a failed write keeps the draft and sets `error`; with `false` the field shows the View's value again. */
394
+ readonly keepDraftOnError?: boolean;
395
+ }
396
+ /** The View a text field binds to: an {@link injectView} handle, or any pair of state and client signals. */
397
+ interface TextFieldView<TClient extends ViewClient> {
398
+ readonly state: Signal<TClient["snapshot"] | undefined>;
399
+ readonly client: Signal<TClient | undefined>;
400
+ }
401
+ /**
402
+ * Binds a text input to one member of a View for the lifetime of the injection context, through
403
+ * `createTextFieldController`. Typing key by key never loses characters: while its writes are in flight the field
404
+ * shows what the user typed, at most one write is in flight (newer text is written next), nothing is written during
405
+ * IME composition, and once the last write settled it shows the View's value, including any normalization.
406
+ *
407
+ * ```ts
408
+ * readonly person = injectView(this.page);
409
+ * readonly name = injectTextField(this.person, state => state.name, (client, value) => client.setName(value));
410
+ * // <input [value]="name.value()" (input)="name.input($event)"
411
+ * // (compositionstart)="name.compositionStart()" (compositionend)="name.compositionEnd($event)">
412
+ * ```
413
+ *
414
+ * `write` may be a generated setter, a command or a checked write. Its failure sets `error` and keeps the draft.
415
+ */
416
+ export declare function injectTextField<TClient extends ViewClient>(view: TextFieldView<TClient>, read: (state: TClient["snapshot"]) => string, write: (client: TClient, value: string) => Promise<unknown>, { injector: provided, ...options }?: InjectTextFieldOptions): TextFieldHandle;
417
+ /** Each field of the latest-operation feedback as a signal, with `run` and `clear`. */
418
+ type LatestOperationHandle<TResult, TFailure = never> = { readonly [K in keyof LatestOperationState<TResult, TFailure>]: Signal<LatestOperationState<TResult, TFailure>[K]>; } & Pick<LatestOperationController<TResult, TFailure>, "run" | "clear">;
419
+ interface InjectLatestOperationOptions {
420
+ /** Required outside an injection context. */
421
+ readonly injector?: Injector;
422
+ }
423
+ /**
424
+ * Admits only the newest selection, for reads such as "load the selected item", as signals
425
+ * for the lifetime of the injection context. Each `run(intent)` replaces the queued intent
426
+ * and cancels the active read, and the next read starts only after the previous one has
427
+ * finished (including `waitForCompletion`). `blocked` means admission is uncertain; only
428
+ * `clear("replace")`, after the application has established a fresh session, clears it.
429
+ * Destruction settles run promises without cancelling accepted work.
430
+ *
431
+ * ```ts
432
+ * readonly load = injectLatestOperation<Item>();
433
+ * select(id: string) { void this.load.run({ start: () => this.items.client()?.startLoad(id) }); }
434
+ * // @if (load.outcome()?.ok) { <item-view [item]="load.outcome()!.value" /> }
435
+ * ```
436
+ */
437
+ export declare function injectLatestOperation<TResult = void, TFailure = never>({ injector: provided }?: InjectLatestOperationOptions): LatestOperationHandle<TResult, TFailure>;
438
+ interface InjectCollectionViewportOptions {
439
+ /** Required outside an injection context. */
440
+ readonly injector?: Injector;
441
+ }
442
+ /**
443
+ * Follows a fixed-row-height scroll container and returns the rows to request
444
+ * from .NET as a signal. Pass the container, for example
445
+ * `viewChild<ElementRef<HTMLElement>>("scroller")`, and the list options as a
446
+ * signal or function, then send `start` and `size` to the ViewModel from an effect.
447
+ */
448
+ export declare function injectCollectionViewport(element: Signal<ElementRef<HTMLElement> | HTMLElement | null | undefined>, options: () => CollectionViewportOptions, { injector: provided }?: InjectCollectionViewportOptions): Signal<CollectionViewport>;
449
+ interface InjectQueryCollectionOptions {
450
+ /** Required outside an injection context. */
451
+ readonly injector?: Injector;
452
+ }
453
+ interface QueryCollectionHandle<TRow> {
454
+ /** The rows to render with their offsets, the spacer's `totalSize`, the total, query, loading and error state. */
455
+ readonly viewport: Signal<QueryViewport<TRow>>;
456
+ /**
457
+ * Measures a rendered row's height until the returned function is called, for example from an `effect` over
458
+ * `viewChildren` of the rows.
459
+ */
460
+ observe(element: Element | ElementRef<Element>, index: number): () => void;
461
+ /** Scrolls to the row with `key` in the current query; resolves `false` when no row has it. */
462
+ scrollToKey(key: string, align?: "start" | "center" | "end"): Promise<boolean>;
463
+ scrollToIndex(index: number, align?: "start" | "center" | "end"): void;
464
+ /** Changes the collection's sort and filter (ViewModel state every presentation shares). */
465
+ setQuery(query: RunicQuery): Promise<void>;
466
+ /** Loads the range again after a failure. */
467
+ retry(): void;
468
+ }
469
+ /**
470
+ * Follows a scroll container for a query collection (`client.queries.{name}`): it loads the rows the container shows
471
+ * from .NET, with placeholders until they arrive, and lays them out with variable heights. Pass the container, for
472
+ * example `viewChild<ElementRef<HTMLElement>>("scroller")`, the collection as a function such as
473
+ * `() => view.client()?.queries.rows`, and the options.
474
+ */
475
+ export declare function injectQueryCollection<TRow>(element: Signal<ElementRef<HTMLElement> | HTMLElement | null | undefined>, collection: () => QueryCollection<TRow> | undefined, options: () => QueryViewportOptions, { injector: provided }?: InjectQueryCollectionOptions): QueryCollectionHandle<TRow>;
476
+ interface BridgeConnectionHandle {
477
+ /** The connection to the .NET host, as `onBridgeConnection` reports it. */
478
+ readonly state: Signal<BridgeConnectionState>;
479
+ }
480
+ interface InjectBridgeConnectionOptions extends BridgeConnectionOptions {
481
+ /** Required outside an injection context. */
482
+ readonly injector?: Injector;
483
+ }
484
+ /**
485
+ * Follows the connection of the injection context's Runic instance to its .NET host (`connecting`, `connected`, `reconnecting`,
486
+ * `lost` or `closed`) as a signal through `onBridgeConnection`, for the lifetime of the injection context.
487
+ * Destruction unsubscribes. Under server rendering (`PLATFORM_ID` `"server"`) it does not
488
+ * observe and stays `connecting`.
489
+ *
490
+ * ```ts
491
+ * readonly connection = injectBridgeConnection();
492
+ * // @if (connection.state() === "lost") { <p role="alert">The application stopped responding.</p> }
493
+ * ```
494
+ */
495
+ export declare function injectBridgeConnection({ injector: provided, ...options }?: InjectBridgeConnectionOptions): BridgeConnectionHandle;
496
+ interface InjectTextOptions {
497
+ /** Required outside an injection context. */
498
+ readonly injector?: Injector;
499
+ }
500
+ /**
501
+ * A text reference that a ViewModel produced, such as a status line or a validation message's `text`, in the window's
502
+ * language (`resolveText`), as a signal that follows a language switch for the lifetime of the injection context.
503
+ * `source` and `fallback` are read in a computed signal, so they may read other signals:
504
+ * `injectText(() => view.state()?.status)`. A string shows as it is; `null` and `undefined` show `fallback`. Configure
505
+ * the page's Translations runtime once with `configureTranslatedText`; without one, a reference shows its fallback text.
506
+ * A field's `FieldError` shows the application's text for it (`configureFieldErrorText`), or its English message.
507
+ * Under server rendering it does not observe a language switch. In templates, the `runicText` pipe does the same.
508
+ *
509
+ * ```ts
510
+ * readonly status = injectText(() => this.view.state()?.status);
511
+ * // <p>{{ status() }}</p>
512
+ * ```
513
+ */
514
+ export declare function injectText(source: () => TextReference | FieldError | string | null | undefined, fallback?: () => string | undefined, { injector: provided }?: InjectTextOptions): Signal<string>;
515
+ /**
516
+ * The window's locale that the application set, or `null` while it sets none, as a signal for the lifetime of the
517
+ * injection context, for example to bind `lang`.
518
+ */
519
+ export declare function injectWindowLocale({ injector: provided }?: InjectTextOptions): Signal<string | null>;
520
+ /**
521
+ * The locale that text is shown in (`textLocale`: the instance's Translations locale, which follows the window's
522
+ * locale), as a signal. It is one signal per Runic instance and needs no injection context, so the page's locale
523
+ * resolver can read it: a template that calls `m.*()` reads the signal through the resolver and renders again on a
524
+ * language switch. During development it also notifies, with the same locale, when the Runic Translations Vite plugin
525
+ * (0.12.0 or later) updates an edited message in place, so OnPush templates show the new text. `undefined` while the
526
+ * instance has no Translations runtime and the application sets no window locale. The instance is `instance`, else
527
+ * that of the injection context, else the page instance.
528
+ *
529
+ * ```ts
530
+ * const textLocale = textLocaleSignal();
531
+ * configureLocaleResolver(() => textLocale() ?? locale.getLocale());
532
+ * ```
533
+ */
534
+ export declare function textLocaleSignal(instance?: RunicInstance): Signal<string | undefined>;
535
+ /**
536
+ * Shows a text reference in the window's language in a template, and marks the view for check when the language
537
+ * changes: `{{ error.text | runicText: error.message }}`, `{{ state.status | runicText }}`. A string shows as it is;
538
+ * `null` and `undefined` show the fallback argument; a field's error, `{{ name.error() | runicText }}`, the application's
539
+ * text for it (`configureFieldErrorText`). The pipe is impure so that it sees a language switch; it formats
540
+ * again only when the value, the fallback or the language changed, and returns its last text otherwise.
541
+ */
542
+ export declare class RunicTextPipe implements PipeTransform, OnDestroy {
543
+ private readonly changes;
544
+ private readonly instance;
545
+ private readonly stop;
546
+ private last;
547
+ transform(value: TextReference | FieldError | string | null | undefined, fallback?: string): string;
548
+ ngOnDestroy(): void;
549
+ static ɵfac: i0.ɵɵFactoryDeclaration<RunicTextPipe, never>;
550
+ static ɵpipe: i0.ɵɵPipeDeclaration<RunicTextPipe, "runicText", true>;
551
+ }
552
+ /** Options of {@link injectAppearance}. */
553
+ interface InjectAppearanceOptions {
554
+ /** The injector to use outside an injection context. */
555
+ readonly injector?: Injector;
556
+ }
557
+ /**
558
+ * The appearance of the injection context's Runic instance (`appearance` from `@runic-artifex/views`) as a signal for the lifetime of the injection
559
+ * context: the colour scheme, contrast and reduced motion of the page's engine combined with the desktop's values that a
560
+ * Runic host pushes (`appearance/1`), which also carry the text scale, the accent colour and the forced-colours palette.
561
+ * Every member is `null` under server rendering.
562
+ *
563
+ * ```ts
564
+ * readonly appearance = injectAppearance();
565
+ * readonly animate = computed(() => this.appearance().reducedMotion !== true);
566
+ * ```
567
+ */
568
+ export declare function injectAppearance({ injector: provided }?: InjectAppearanceOptions): Signal<Appearance>;
569
+ /**
570
+ * The Runic instance (`createRunicInstance` in `@runic-artifex/views`) that the `inject*` helpers, `ViewOutlet` and the
571
+ * `runicText` pipe connect and read through. Without a provider it is the default instance: the page instance, on
572
+ * `globalThis.__runicBridge`, as before instances existed, or in a component bundle its element's.
573
+ */
574
+ export declare const RUNIC_INSTANCE: InjectionToken<RunicInstance>;
575
+ /**
576
+ * Provides `instance` as the {@link RUNIC_INSTANCE} of an injector: `injectView`, `injectField`, `injectText`,
577
+ * `injectBridgeConnection`, `injectAppearance` and the other helpers below it use it instead of the page instance. A
578
+ * guest that renders inside another page, such as an embedded component, adds it to its application's or its root
579
+ * component's `providers`.
580
+ *
581
+ * ```ts
582
+ * const instance = createRunicInstance({ bridge });
583
+ * bootstrapApplication(App, { providers: [provideRunicInstance(instance)] });
584
+ * ```
585
+ */
586
+ export declare function provideRunicInstance(instance: RunicInstance): Provider;
587
+ /** Options of {@link injectRunicInstance}. */
588
+ interface InjectRunicInstanceOptions {
589
+ /** Required outside an injection context. */
590
+ readonly injector?: Injector;
591
+ }
592
+ /**
593
+ * The Runic instance of the injection context: the nearest {@link provideRunicInstance}, or the default instance
594
+ * (`defaultInstance()`: the page instance, or in a component bundle its element's).
595
+ */
596
+ export declare function injectRunicInstance({ injector }?: InjectRunicInstanceOptions): RunicInstance;
597
+ interface MenuBarHandle {
598
+ /** The menu bar as the page renders it; render a bar only when `placement` is `"page"`. */
599
+ readonly state: Signal<MenuBarState>;
600
+ /** Runs an item through the native bar's command path. Rejects with a BridgeError under server rendering. */
601
+ readonly invoke: MenuBarController["invoke"];
602
+ /** Matches a `keydown` event against the items' shortcuts, for the `shortcuts: "app"` option. */
603
+ readonly handleKeyDown: MenuBarController["handleKeyDown"];
604
+ }
605
+ interface InjectMenuBarOptions extends Omit<MenuBarControllerOptions, "signal"> {
606
+ /**
607
+ * Receives the `focus` (Alt tap, F10) and `open` (Alt plus a menu's access key) requests: focus the first
608
+ * `cdkMenuItem` of the bar or open a menu's `CdkMenuTrigger`.
609
+ */
610
+ readonly onRequest?: (request: MenuBarRequest) => void;
611
+ /** Required outside an injection context. */
612
+ readonly injector?: Injector;
613
+ }
614
+ /**
615
+ * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) as a signal, as headless
616
+ * state for the application's own menubar (for example the CDK Menu's `cdkMenuBar`), through
617
+ * `createMenuBarController`, for the lifetime of the injection context. Destruction disposes the controller. Under
618
+ * server rendering (`PLATFORM_ID` `"server"`) it creates none and stays `connecting`.
619
+ *
620
+ * ```ts
621
+ * readonly menuBar = injectMenuBar({ onRequest: request => this.onMenuRequest(request) });
622
+ * // @if (menuBar.state().placement === "page") { <div cdkMenuBar>…<button cdkMenuItem (cdkMenuItemTriggered)="menuBar.invoke(item)"> }
623
+ * ```
624
+ */
625
+ export declare function injectMenuBar({ injector: provided, onRequest, ...options }?: InjectMenuBarOptions): MenuBarHandle;
626
+ export { type Appearance, type AppearanceColorScheme, type AppearanceContrast, type AppearanceSystemColors, type BlobRef, type BridgeConnectionHandle, type BridgeConnectionOptions, type BridgeConnectionState, type CommandHandle, type DocumentLocaleOptions, type FieldErrorArguments, type FieldErrorReason, type FieldErrorText, type FieldHandle, type FieldView, type FormFieldHandle, type FormHandle, type FormState, type FormSubmitOptions, type FormSubmitResult, type HostAppearance, type InjectAppearanceOptions, type InjectBridgeConnectionOptions, type InjectCollectionViewportOptions, type InjectCommandOptions, type InjectFieldOptions, type InjectFormOptions, type InjectLatestOperationOptions, type InjectMenuBarOptions, type InjectOperationOptions, type InjectQueryCollectionOptions, type InjectRunicInstanceOptions, type InjectTextFieldOptions, type InjectTextOptions, type InjectViewOptions, type InjectViewResourceOptions, type LatestOperationHandle, type MenuBarEntry, type MenuBarHandle, type MenuBarInvokeResult, type MenuBarItem, type MenuBarMenu, type MenuBarRequest, type MenuBarSeparator, type MenuBarState, type NavigationPathChange, type NavigationPathOptions, type NavigationReply, type OperationHandle, type QueryCollectionHandle, type RegionCollection, type RegionEntry, type RegionOutcome, type RegionOutletsMode, type RegionPanelAttributes, type RegionSlot, type RunicBlob, type RunicInstance, type RunicInstanceOptions, type TextFieldHandle, type TextFieldView, type TextReference, type TextTranslations, type UploadOptions, type UploadProgress, type ViewHandle, type ViewOutletMissingContext, type ViewRegistry, type ViewResource, appearance, commitAllFields, configureFieldErrorText, configureTranslatedText, createRunicInstance, fieldErrorText, installBackNavigation, installNavigationPath, navigateBack, onAppearance, onBridgeConnection, onNavigationPath, openNavigationPath, pageInstance, regionEntries, resolveText, selectedRegion, syncDocumentLocale, textDirection, upload, windowLocale };