@runic-artifex/angular 0.12.1 → 0.13.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
@@ -75,6 +75,47 @@ export class CounterPage {
75
75
  }
76
76
  ```
77
77
 
78
+ ### Text inputs
79
+
80
+ Bind a text input to a member with `injectTextField(view, read, write, options?)`,
81
+ which wraps the framework-neutral
82
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#text-inputs)
83
+ for the lifetime of the injection context:
84
+
85
+ ```ts
86
+ @Component({
87
+ selector: "person-page",
88
+ template: `
89
+ <input [value]="name.value()" (input)="name.input($event)"
90
+ (compositionstart)="name.compositionStart()" (compositionend)="name.compositionEnd($event)">
91
+ @if (name.error() !== undefined) { <p role="alert">{{ name.error() }}</p> }
92
+ `,
93
+ })
94
+ export class PersonPage {
95
+ readonly page = input.required<PersonPageReference>();
96
+ readonly person = injectView(this.page);
97
+ readonly name = injectTextField(this.person, state => state.name, (client, value) => client.setName(value));
98
+ }
99
+ ```
100
+
101
+ It returns the `value`, `editing` and `error` signals with `input(event | text)`,
102
+ `compositionStart()`, `compositionEnd(event | text)` and `reset()`. `view` is an
103
+ `injectView` handle or any pair of `state` and `client` signals. The options are
104
+ `coalesce`, `keepDraftOnError` and `injector` outside an injection context.
105
+ The field shows what the user typed while its writes are in flight, so a reply or
106
+ frame that answers an older keystroke never replaces newer text. At most one write is
107
+ in flight; text typed meanwhile is written next as one value (`coalesce: false` writes
108
+ every change). Nothing is written during IME composition. Once the last write settled,
109
+ the field shows the View's value again, including any normalization the ViewModel
110
+ applied (trimmed, upper-cased). `write` may also be a command or a checked write. A
111
+ failed write keeps the draft and sets `error` (`keepDraftOnError: false` shows the
112
+ View's value instead); `reset()` drops the draft. `editing` is true while a draft
113
+ exists. Don't disable the input on the View's busy state (`isSaving`, `can…`) while
114
+ the user types: the field's own write causes it, and keys typed meanwhile would be
115
+ lost. Test such fields by typing key by key (Playwright `pressSequentially`, Testing
116
+ Library `user.type`) against the mock with `latency: "slow"`; `fill()` sets the whole
117
+ text at once and hides the race.
118
+
78
119
  ## Outlet
79
120
 
80
121
  Register a component for each generated View kind and pass the current
@@ -147,14 +188,14 @@ For example, a navigation command whose departure guard awaits a dialog's
147
188
  answer never completes while the answer waits behind it. Order such commands
148
189
  by dispatch instead: start the next one once the previous one has been sent,
149
190
  as the Notes example's
150
- [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/examples/notes-view-first/Angular/src/app/window-operations.ts)
191
+ [`WindowOperations.runDispatched`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/examples/notes-view-first/Angular/src/app/window-operations.ts)
151
192
  does for its navigation commands.
152
193
 
153
194
  ## Operations
154
195
 
155
196
  `injectOperation(start, options?)` observes a generated `start<Command>()` operation
156
197
  through the framework-neutral
157
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#operation-feedback-and-latest-selection)
198
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#operation-feedback-and-latest-selection)
158
199
  for the lifetime of the injection context:
159
200
 
160
201
  ```ts
@@ -166,9 +207,11 @@ readonly push = injectOperation((remote: string) => this.workspace.client()?.sta
166
207
  ```
167
208
 
168
209
  It returns `run(...args)`, `cancel()` and `reset()`, which never reject, and the
169
- `pending`, `admitting`, `operation`, `status`, `outcome`, `failure`, `error`,
210
+ `pending`, `admitting`, `operation`, `status`, `progress`, `outcome`, `failure`, `error`,
170
211
  `cancelled`, `cancellationRequested`, `cancelling`, `cancellation` and `cancelError`
171
- signals. A run that ends with a `cancelled` status sets `cancelled` and resolves to
212
+ signals. `progress` is how far the running operation got, from 0 to 1, when its
213
+ command reports progress (`RunicOperationProgress.Report` in .NET), for example
214
+ `<progress [value]="push.progress()">`; it is `undefined` while unknown and after the run. A run that ends with a `cancelled` status sets `cancelled` and resolves to
172
215
  `undefined` without an `error`; `failed` and `timed-out` statuses are still `error`.
173
216
  `pending` stays true after a Cancel response until the operation reaches its terminal
174
217
  status. Destroying the injection context settles run promises without cancelling
@@ -178,7 +221,7 @@ context.
178
221
 
179
222
  `injectLatestOperation(options?)` admits only the newest of several reads, for example
180
223
  loading the item the user selected last, through the framework-neutral
181
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#operation-feedback-and-latest-selection).
224
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#operation-feedback-and-latest-selection).
182
225
  Each `run(intent)` replaces the queued intent and cancels the active read; the next
183
226
  read starts only after the previous one reaches its terminal status and the intent's
184
227
  optional `waitForCompletion` barrier:
@@ -210,7 +253,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
210
253
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a signal of a
211
254
  `BridgeConnectionState`: `connecting`, `connected`, `reconnecting` or `lost` (a
212
255
  closed set, see
213
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#connection-state)):
256
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#connection-state)):
214
257
 
215
258
  ```ts
216
259
  import { injectBridgeConnection } from "@runic-artifex/angular";
@@ -228,7 +271,7 @@ not observe and stays `connecting`. An invalid `lostAfter` throws a `RangeError`
228
271
  `injectMenuBar(options?)` follows the declared menu bar of a Runic Desktop
229
272
  window that leaves it to the page (`DesktopMenuBarPresentation.Page`) for the
230
273
  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.12.1/packages/web/views#in-page-menu-bar))
274
+ `@runic-artifex/views` (see [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#in-page-menu-bar))
232
275
  and returns `{ state, invoke, handleKeyDown }`, where `state` is a signal of a
233
276
  `MenuBarState`. The bar is rendered by the application's own menubar, for
234
277
  example the CDK Menu's `cdkMenuBar`. Runic ships no menubar component.
@@ -253,7 +296,7 @@ it creates none and stays `connecting`.
253
296
  ### With the CDK Menu
254
297
 
255
298
  The CDK's `cdkMenuBar` with `CdkMenuTrigger.open()` for `open` requests; the
256
- [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
299
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
257
300
  items (`cdkMenuItemCheckbox`, `cdkMenuItemRadio` in a `cdkMenuGroup`) and is
258
301
  tested with real keys:
259
302
 
@@ -317,7 +360,7 @@ const offline = error instanceof BridgeError && error.kind === "disconnected";
317
360
  ```
318
361
 
319
362
  `instanceof` holds for errors from every copy of the package on the page.
320
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#errors-and-diagnostics)
363
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#errors-and-diagnostics)
321
364
  lists the kinds. Any other value, such as an exception that your own connect
322
365
  function or command callback throws, arrives unchanged.
323
366
 
@@ -368,16 +411,16 @@ application's own dialog.
368
411
  departure before that is answered by the ViewModel's .NET fallback handler, or
369
412
  fails closed without one.
370
413
 
371
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.12.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
414
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.13.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
372
415
  has the .NET side and which View answers which departure. In a frontend test,
373
416
  the generated mock's `interactions.<name>.request(input)` resolves with the
374
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#testing).
417
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#testing).
375
418
 
376
419
  ## Collection viewports
377
420
 
378
421
  `injectCollectionViewport(element, options)` follows a fixed-row-height scroll
379
422
  container and returns a signal with its
380
- [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#collectionviewportoptions)
423
+ [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#collectionviewportoptions)
381
424
  range. Pass the container as a signal, such as a `viewChild`, and the options as
382
425
  a function or signal, then send the range to the ViewModel from an effect:
383
426
 
@@ -2,6 +2,7 @@ export { ViewOutlet, RunicViewOutlet, type ViewOutletMissingContext, type ViewRe
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 { injectTextField, type InjectTextFieldOptions, type TextFieldHandle, type TextFieldView } from "./inject-text-field.js";
5
6
  export { injectLatestOperation, type InjectLatestOperationOptions, type LatestOperationHandle, } from "./inject-latest-operation.js";
6
7
  export { injectCollectionViewport, type InjectCollectionViewportOptions } from "./inject-collection-viewport.js";
7
8
  export { injectBridgeConnection, type BridgeConnectionHandle, type InjectBridgeConnectionOptions } from "./inject-bridge-connection.js";
package/dist/esm/index.js CHANGED
@@ -2,6 +2,7 @@ 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 { injectTextField } from "./inject-text-field.js";
5
6
  export { injectLatestOperation, } from "./inject-latest-operation.js";
6
7
  export { injectCollectionViewport } from "./inject-collection-viewport.js";
7
8
  export { injectBridgeConnection } from "./inject-bridge-connection.js";
@@ -29,6 +29,6 @@ export function injectLatestOperation({ injector: provided } = {}) {
29
29
  pending: field("pending"), admitting: field("admitting"), operation: field("operation"), status: field("status"),
30
30
  outcome: field("outcome"), failure: field("failure"), error: field("error"), cancelled: field("cancelled"),
31
31
  cancellationRequested: field("cancellationRequested"), cancelling: field("cancelling"),
32
- cancellation: field("cancellation"), cancelError: field("cancelError"), blocked: field("blocked"),
32
+ progress: field("progress"), cancellation: field("cancellation"), cancelError: field("cancelError"), blocked: field("blocked"),
33
33
  };
34
34
  }
@@ -23,7 +23,7 @@ export function injectMenuBar({ injector: provided, onRequest, ...options } = {}
23
23
  ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
24
24
  return {
25
25
  state: state.asReadonly(),
26
- invoke: () => Promise.reject(new BridgeError("unavailable", "The menu bar is not followed during server rendering.", { route: "__runicMenuBarInvoke" })),
26
+ invoke: () => Promise.reject(new BridgeError("unavailable", "The menu bar is not followed during server rendering.", { route: "runic.menu-bar" })),
27
27
  handleKeyDown: () => false,
28
28
  };
29
29
  }
@@ -27,6 +27,6 @@ export function injectOperation(start, { injector: provided, ...options } = {})
27
27
  pending: field("pending"), admitting: field("admitting"), operation: field("operation"), status: field("status"),
28
28
  outcome: field("outcome"), failure: field("failure"), error: field("error"), cancelled: field("cancelled"),
29
29
  cancellationRequested: field("cancellationRequested"), cancelling: field("cancelling"),
30
- cancellation: field("cancellation"), cancelError: field("cancelError"),
30
+ progress: field("progress"), cancellation: field("cancellation"), cancelError: field("cancelError"),
31
31
  };
32
32
  }
@@ -0,0 +1,55 @@
1
+ import { Injector, type Signal } from "@angular/core";
2
+ import { type ViewClient } from "@runic-artifex/views";
3
+ /** A text input bound to one View member. */
4
+ export interface TextFieldHandle {
5
+ /** What the input shows: the draft while one exists, otherwise the member's value in the View's state. */
6
+ readonly value: Signal<string>;
7
+ /**
8
+ * True while a draft exists, from the first input until the last write settled and the state caught up, and after a
9
+ * failed write. Keep the input enabled while it is true, rather than disabling it on the View's busy state, which
10
+ * the field's own write causes.
11
+ */
12
+ readonly editing: Signal<boolean>;
13
+ /** Why the latest write failed, until the next input or `reset()`. */
14
+ readonly error: Signal<unknown>;
15
+ /** The user changed the text: pass the `input` event, or the new text. */
16
+ input(event: Event | string): void;
17
+ /** An IME composition started: the text is kept but not written until it ends. Bind it to `compositionstart`. */
18
+ compositionStart(): void;
19
+ /** The IME composition ended: pass the `compositionend` event, or the text, which is then written. */
20
+ compositionEnd(event: Event | string): void;
21
+ /** Drops the draft and the error and shows the View's value. Writes in flight still complete. */
22
+ reset(): void;
23
+ }
24
+ export interface InjectTextFieldOptions {
25
+ /** Required outside an injection context. */
26
+ readonly injector?: Injector;
27
+ /**
28
+ * With `true` (the default) at most one write is in flight, and text typed meanwhile is written next, as one
29
+ * value. With `false` every input is written.
30
+ */
31
+ readonly coalesce?: boolean;
32
+ /** With `true` (the default) a failed write keeps the draft and sets `error`; with `false` the field shows the View's value again. */
33
+ readonly keepDraftOnError?: boolean;
34
+ }
35
+ /** The View a text field binds to: an {@link injectView} handle, or any pair of state and client signals. */
36
+ export interface TextFieldView<TClient extends ViewClient> {
37
+ readonly state: Signal<TClient["snapshot"] | undefined>;
38
+ readonly client: Signal<TClient | undefined>;
39
+ }
40
+ /**
41
+ * Binds a text input to one member of a View for the lifetime of the injection context, through
42
+ * `createTextFieldController`. Typing key by key never loses characters: while its writes are in flight the field
43
+ * shows what the user typed, at most one write is in flight (newer text is written next), nothing is written during
44
+ * IME composition, and once the last write settled it shows the View's value, including any normalization.
45
+ *
46
+ * ```ts
47
+ * readonly person = injectView(this.page);
48
+ * readonly name = injectTextField(this.person, state => state.name, (client, value) => client.setName(value));
49
+ * // <input [value]="name.value()" (input)="name.input($event)"
50
+ * // (compositionstart)="name.compositionStart()" (compositionend)="name.compositionEnd($event)">
51
+ * ```
52
+ *
53
+ * `write` may be a generated setter, a command or a checked write. Its failure sets `error` and keeps the draft.
54
+ */
55
+ 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;
@@ -0,0 +1,50 @@
1
+ import { assertInInjectionContext, computed, DestroyRef, effect, inject, Injector, signal, untracked } from "@angular/core";
2
+ import { createTextFieldController } from "@runic-artifex/views";
3
+ function textOf(event) {
4
+ if (typeof event === "string")
5
+ return event;
6
+ const target = event.target;
7
+ return typeof target?.value === "string" ? target.value : "";
8
+ }
9
+ /**
10
+ * Binds a text input to one member of a View for the lifetime of the injection context, through
11
+ * `createTextFieldController`. Typing key by key never loses characters: while its writes are in flight the field
12
+ * shows what the user typed, at most one write is in flight (newer text is written next), nothing is written during
13
+ * IME composition, and once the last write settled it shows the View's value, including any normalization.
14
+ *
15
+ * ```ts
16
+ * readonly person = injectView(this.page);
17
+ * readonly name = injectTextField(this.person, state => state.name, (client, value) => client.setName(value));
18
+ * // <input [value]="name.value()" (input)="name.input($event)"
19
+ * // (compositionstart)="name.compositionStart()" (compositionend)="name.compositionEnd($event)">
20
+ * ```
21
+ *
22
+ * `write` may be a generated setter, a command or a checked write. Its failure sets `error` and keeps the draft.
23
+ */
24
+ export function injectTextField(view, read, write, { injector: provided, ...options } = {}) {
25
+ if (!provided)
26
+ assertInInjectionContext(injectTextField);
27
+ const injector = provided ?? inject(Injector);
28
+ const controller = createTextFieldController({ read, write, ...options });
29
+ const current = signal(controller.current, /* @ts-ignore */
30
+ ...(ngDevMode ? [{ debugName: "current" }] : /* istanbul ignore next */ []));
31
+ controller.subscribe(() => current.set(controller.current));
32
+ effect(() => {
33
+ const state = view.state();
34
+ const client = view.client();
35
+ untracked(() => {
36
+ controller.setSource(state === undefined || client === undefined ? undefined : { state, client });
37
+ current.set(controller.current);
38
+ });
39
+ }, { injector });
40
+ injector.get(DestroyRef).onDestroy(() => controller.dispose());
41
+ return {
42
+ value: computed(() => current().value),
43
+ editing: computed(() => current().editing),
44
+ error: computed(() => current().error),
45
+ input(event) { controller.input(textOf(event)); },
46
+ compositionStart() { controller.compositionStart(); },
47
+ compositionEnd(event) { controller.compositionEnd(textOf(event)); },
48
+ reset() { controller.reset(); },
49
+ };
50
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/angular",
3
- "version": "0.12.1",
3
+ "version": "0.13.0",
4
4
  "type": "module",
5
5
  "exports": {
6
6
  ".": {
@@ -12,7 +12,7 @@
12
12
  },
13
13
  "peerDependencies": {
14
14
  "@angular/core": ">=22.0.0 <23",
15
- "@runic-artifex/views": "0.12.1"
15
+ "@runic-artifex/views": "0.13.0"
16
16
  },
17
17
  "description": "Angular outlet and signals for Runic Views",
18
18
  "license": "MIT",
@@ -21,7 +21,7 @@
21
21
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
22
22
  "directory": "packages/web/angular"
23
23
  },
24
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/angular#readme",
24
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/angular#readme",
25
25
  "bugs": {
26
26
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
27
27
  },
@@ -45,15 +45,17 @@
45
45
  "pack:check": "bun pm pack --dry-run"
46
46
  },
47
47
  "devDependencies": {
48
- "@runic-artifex/views": "0.12.1",
48
+ "@runic-artifex/views": "0.13.0",
49
49
  "@angular/common": "22.2.3",
50
50
  "@angular/compiler": "22.2.3",
51
51
  "@angular/compiler-cli": "22.2.3",
52
52
  "@angular/core": "22.2.3",
53
53
  "@angular/platform-browser": "22.2.3",
54
+ "esbuild": "0.28.2",
54
55
  "happy-dom": "21.0.4",
56
+ "playwright-core": "1.63.0",
55
57
  "typescript": "6.0.3",
56
58
  "vitest": "5.0.3"
57
59
  },
58
- "gitHead": "124a532e5861cff03e77d2ef0c5d4f081ee99a47"
60
+ "gitHead": "3331f81c7a2de34e209b53eb07515323d6d15cf3"
59
61
  }