@runic-artifex/svelte 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
@@ -72,6 +72,44 @@ Read state one way from `state`. A property with a public C# setter also gets a
72
72
  </select>
73
73
  ```
74
74
 
75
+ ### Text inputs: `useTextField(view, read, write, options?)`
76
+
77
+ Call during component initialization to bind a text input to a member through the
78
+ framework-neutral
79
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#text-inputs):
80
+
81
+ ```svelte
82
+ <script lang="ts">
83
+ import { useTextField, useView } from "@runic-artifex/svelte";
84
+ import type { PersonPageReference } from "./generated/person.js";
85
+
86
+ let { page }: { page: PersonPageReference } = $props();
87
+ const person = useView(() => page);
88
+ const name = useTextField(() => person, state => state.name, (client, value) => client.setName(value));
89
+ </script>
90
+
91
+ <input bind:value={name.value} oncompositionstart={name.compositionStart} oncompositionend={name.compositionEnd}>
92
+ {#if name.error !== undefined}<p role="alert">{String(name.error)}</p>{/if}
93
+ ```
94
+
95
+ It returns `value`, which `bind:value` reads and sets, the reactive `editing` and
96
+ `error`, and `compositionStart()`, `compositionEnd(event | text)` and `reset()`.
97
+ `view` returns a `useView` handle or any `{ state, client }`. The options are
98
+ `coalesce` and `keepDraftOnError`.
99
+ The field shows what the user typed while its writes are in flight, so a reply or
100
+ frame that answers an older keystroke never replaces newer text. At most one write is
101
+ in flight; text typed meanwhile is written next as one value (`coalesce: false` writes
102
+ every change). Nothing is written during IME composition. Once the last write settled,
103
+ the field shows the View's value again, including any normalization the ViewModel
104
+ applied (trimmed, upper-cased). `write` may also be a command or a checked write. A
105
+ failed write keeps the draft and sets `error` (`keepDraftOnError: false` shows the
106
+ View's value instead); `reset()` drops the draft. `editing` is true while a draft
107
+ exists. Don't disable the input on the View's busy state (`isSaving`, `can…`) while
108
+ the user types: the field's own write causes it, and keys typed meanwhile would be
109
+ lost. Test such fields by typing key by key (Playwright `pressSequentially`, Testing
110
+ Library `user.type`) against the mock with `latency: "slow"`; `fill()` sets the whole
111
+ text at once and hides the race.
112
+
75
113
  ## `ViewOutlet`
76
114
 
77
115
  Renders the component registered for a generated reference's `kind` and passes
@@ -134,8 +172,7 @@ neither.
134
172
  ## `useOperation(start, options?)`
135
173
 
136
174
  Call during component initialization to observe a generated operation's admission,
137
- pending state, terminal outcome and cancellation. Progress and recovery stay in the
138
- generated View snapshot:
175
+ pending state, progress, terminal outcome and cancellation:
139
176
 
140
177
  ```svelte
141
178
  <script lang="ts">
@@ -148,16 +185,18 @@ generated View snapshot:
148
185
 
149
186
  <button disabled={!workspace.client || push.pending} onclick={() => push.run("origin")}>Push</button>
150
187
  {#if push.pending}
151
- <p role="status">{workspace.state?.operationMessage ?? "Starting…"}</p>
188
+ <progress value={push.progress}></progress>
152
189
  <button disabled={push.cancellationRequested} onclick={() => push.cancel()}>Cancel</button>
153
190
  {/if}
154
191
  {#if push.cancelled}<p role="status">Push cancelled.</p>{/if}
155
192
  {#if push.error ?? push.cancelError}<p role="alert">{String(push.error ?? push.cancelError)}</p>{/if}
156
193
  ```
157
194
 
158
- The result exposes reactive `pending`, `admitting`, `operation`, `status`, `outcome`,
195
+ The result exposes reactive `pending`, `admitting`, `operation`, `status`, `progress`, `outcome`,
159
196
  `failure`, `error`, `cancelled`, `cancellationRequested`, `cancelling`, `cancellation`
160
- and `cancelError`, with `run(...args)`, `cancel()` and `reset()`. Both async methods never
197
+ and `cancelError`, with `run(...args)`, `cancel()` and `reset()`. `progress` is how far
198
+ the running operation got, from 0 to 1, when its command reports progress
199
+ (`RunicOperationProgress.Report` in .NET); it is `undefined` while unknown and after the run. Both async methods never
161
200
  reject. A run that ends with a `cancelled` status sets `cancelled` and leaves `error`
162
201
  undefined; `failed` and `timed-out` statuses are still `error`. Cancel before a delayed Start receipt is retained for that captured run;
163
202
  its response does not release pending state. `reset()` clears feedback while
@@ -174,7 +213,7 @@ Cancel and other callbacks responsive during observation.
174
213
  ## `useLatestOperation()`
175
214
 
176
215
  For rapid read selection, `useLatestOperation()` wraps the framework-neutral
177
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#operation-feedback-and-latest-selection)
216
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#operation-feedback-and-latest-selection)
178
217
  for the component's lifetime. It coalesces the latest intent across delayed receipts
179
218
  and orders the next admission after terminal observation and any application drain
180
219
  barrier:
@@ -205,7 +244,7 @@ establish that replacement boundary and own the old work's drain. Lost terminal
205
244
  observation blocks further Starts instead of retrying blindly, with its reason in
206
245
  `error`; ordinary Cancel does not clear this block. Component destruction settles
207
246
  observation without cancelling accepted work. The
208
- [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/tests/fixtures/application/operations-consumer)
247
+ [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/tests/fixtures/application/operations-consumer)
209
248
  runs this hook against the packed packages and the desktop transport.
210
249
 
211
250
  ## `useBridgeConnection(options?)`
@@ -215,7 +254,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
215
254
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a reactive
216
255
  `BridgeConnectionState`: `connecting`, `connected`, `reconnecting` or `lost` (a
217
256
  closed set, see
218
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#connection-state)):
257
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#connection-state)):
219
258
 
220
259
  ```svelte
221
260
  <script lang="ts">
@@ -237,7 +276,7 @@ server render does not observe, and destroying the owner unsubscribes. An invali
237
276
  Follows the declared menu bar of a Runic Desktop window that leaves it to the
238
277
  page (`DesktopMenuBarPresentation.Page`) while its owner lives. It wraps
239
278
  `createMenuBarController` from `@runic-artifex/views` (see
240
- [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`, where `state` is a
279
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`, where `state` is a
241
280
  reactive `MenuBarState` property. The bar is rendered by the menubar component
242
281
  of the application's own UI library. Runic ships no menubar component.
243
282
 
@@ -266,7 +305,7 @@ the `shortcuts: "app"` lease.
266
305
  ### With Bits UI
267
306
 
268
307
  Bits UI's `Menubar.Root bind:value`; the
269
- [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
308
+ [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
270
309
  items and is tested with real keys:
271
310
 
272
311
  ```svelte
@@ -330,7 +369,7 @@ const offline = view.error instanceof BridgeError && view.error.kind === "discon
330
369
  ```
331
370
 
332
371
  `instanceof` holds for errors from every copy of the package on the page.
333
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#errors-and-diagnostics)
372
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#errors-and-diagnostics)
334
373
  lists the kinds. Any other value, such as an exception that your own connect
335
374
  function or command callback throws, arrives unchanged.
336
375
 
@@ -369,15 +408,15 @@ application's own dialog.
369
408
  departure before that is answered by the ViewModel's .NET fallback handler, or
370
409
  fails closed without one.
371
410
 
372
- 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)
411
+ 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)
373
412
  has the .NET side and which View answers which departure. In a frontend test,
374
413
  the generated mock's `interactions.<name>.request(input)` resolves with the
375
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#testing).
414
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#testing).
376
415
 
377
416
  ## `useCollectionViewport(options)`
378
417
 
379
418
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
380
- `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/views#collectionviewportoptions)
419
+ `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/views#collectionviewportoptions)
381
420
  range; `attach` is an attachment for the container. Call it during component
382
421
  initialization and send the range to the ViewModel from an effect:
383
422
 
@@ -3,6 +3,7 @@ export type { ViewRegistry } from "./view-registry.js";
3
3
  export { useView, type UseViewOptions, type ViewHandle } from "./use-view.svelte.js";
4
4
  export { useCommand, type CommandHandle } from "./use-command.svelte.js";
5
5
  export { useOperation, type OperationHandle } from "./use-operation.svelte.js";
6
+ export { useTextField, type TextFieldHandle, type TextFieldView, type UseTextFieldOptions } from "./use-text-field.svelte.js";
6
7
  export { useLatestOperation, type LatestOperationHandle } from "./use-latest-operation.svelte.js";
7
8
  export { useCollectionViewport, type CollectionViewportHandle } from "./use-collection-viewport.svelte.js";
8
9
  export { useBridgeConnection, type BridgeConnectionHandle } from "./use-bridge-connection.svelte.js";
@@ -2,6 +2,7 @@ export { default as ViewOutlet } from "./ViewOutlet.svelte";
2
2
  export { useView } from "./use-view.svelte.js";
3
3
  export { useCommand } from "./use-command.svelte.js";
4
4
  export { useOperation } from "./use-operation.svelte.js";
5
+ export { useTextField } from "./use-text-field.svelte.js";
5
6
  export { useLatestOperation } from "./use-latest-operation.svelte.js";
6
7
  export { useCollectionViewport } from "./use-collection-viewport.svelte.js";
7
8
  export { useBridgeConnection } from "./use-bridge-connection.svelte.js";
@@ -21,6 +21,7 @@ export function useLatestOperation() {
21
21
  get admitting() { return current.admitting; },
22
22
  get operation() { return current.operation; },
23
23
  get status() { return current.status; },
24
+ get progress() { return current.progress; },
24
25
  get outcome() { return current.outcome; },
25
26
  get failure() { return current.failure; },
26
27
  get error() { return current.error; },
@@ -36,7 +36,7 @@ export function useMenuBar(options = {}) {
36
36
  get state() { return state; },
37
37
  invoke: item => controller
38
38
  ? controller.invoke(item)
39
- : Promise.reject(new BridgeError("disconnected", "The menu bar is not connected yet.", { route: "__runicMenuBarInvoke" })),
39
+ : Promise.reject(new BridgeError("disconnected", "The menu bar is not connected yet.", { route: "runic.menu-bar" })),
40
40
  handleKeyDown: event => controller?.handleKeyDown(event) ?? false,
41
41
  };
42
42
  }
@@ -5,6 +5,6 @@ export interface OperationHandle<TArgs extends readonly unknown[], TResult, TFai
5
5
  * Tracks Start admission, pending work, cancellation and terminal feedback as
6
6
  * reactive properties. Call during component initialization. Owner destruction
7
7
  * detaches observation and settles run promises without cancelling accepted work.
8
- * Progress remains in the generated View snapshot, where the application owns it.
8
+ * `progress` follows the running operation (`BridgeOperation.subscribe`).
9
9
  */
10
10
  export declare function useOperation<TArgs extends readonly unknown[], TResult, TFailure = never>(start: (...args: TArgs) => BridgeOperation<TResult, TFailure> | undefined | PromiseLike<BridgeOperation<TResult, TFailure> | undefined>, options?: OperationControllerOptions<TResult, TFailure>): OperationHandle<TArgs, TResult, TFailure>;
@@ -3,7 +3,7 @@ import { createOperationController, } from "@runic-artifex/views";
3
3
  * Tracks Start admission, pending work, cancellation and terminal feedback as
4
4
  * reactive properties. Call during component initialization. Owner destruction
5
5
  * detaches observation and settles run promises without cancelling accepted work.
6
- * Progress remains in the generated View snapshot, where the application owns it.
6
+ * `progress` follows the running operation (`BridgeOperation.subscribe`).
7
7
  */
8
8
  export function useOperation(start, options = {}) {
9
9
  const controller = createOperationController(start, options);
@@ -22,6 +22,7 @@ export function useOperation(start, options = {}) {
22
22
  get admitting() { return current.admitting; },
23
23
  get operation() { return current.operation; },
24
24
  get status() { return current.status; },
25
+ get progress() { return current.progress; },
25
26
  get outcome() { return current.outcome; },
26
27
  get failure() { return current.failure; },
27
28
  get error() { return current.error; },
@@ -0,0 +1,53 @@
1
+ import { type ViewClient } from "@runic-artifex/views";
2
+ /** A text input bound to one View member. */
3
+ export interface TextFieldHandle {
4
+ /**
5
+ * What the input shows: the draft while one exists, otherwise the member's value in the View's state. Setting it
6
+ * is an input by the user, as `bind:value` does.
7
+ */
8
+ value: string;
9
+ /**
10
+ * True while a draft exists, from the first input until the last write settled and the state caught up, and after a
11
+ * failed write. Keep the input enabled while it is true, rather than disabling it on the View's busy state, which
12
+ * the field's own write causes.
13
+ */
14
+ readonly editing: boolean;
15
+ /** Why the latest write failed, until the next input or `reset()`. */
16
+ readonly error: unknown;
17
+ /** An IME composition started: the text is kept but not written until it ends. Use it as `oncompositionstart`. */
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 UseTextFieldOptions {
25
+ /**
26
+ * With `true` (the default) at most one write is in flight, and text typed meanwhile is written next, as one
27
+ * value. With `false` every input is written.
28
+ */
29
+ readonly coalesce?: boolean;
30
+ /** With `true` (the default) a failed write keeps the draft and sets `error`; with `false` the field shows the View's value again. */
31
+ readonly keepDraftOnError?: boolean;
32
+ }
33
+ /** The View a text field binds to: a `useView` handle, or any state and client. */
34
+ export interface TextFieldView<TClient extends ViewClient> {
35
+ readonly state: TClient["snapshot"] | undefined;
36
+ readonly client: TClient | undefined;
37
+ }
38
+ /**
39
+ * Binds a text input to one member of a View while the calling component is mounted, through
40
+ * `createTextFieldController`. Call it during component initialization. Typing key by key never loses characters:
41
+ * while its writes are in flight the field shows what the user typed, at most one write is in flight (newer text is
42
+ * written next), nothing is written during IME composition, and once the last write settled it shows the View's
43
+ * value, including any normalization.
44
+ *
45
+ * ```svelte
46
+ * const person = useView(() => page);
47
+ * const name = useTextField(() => person, state => state.name, (client, value) => client.setName(value));
48
+ * <input bind:value={name.value} oncompositionstart={name.compositionStart} oncompositionend={name.compositionEnd}>
49
+ * ```
50
+ *
51
+ * `write` may be a generated setter, a command or a checked write. Its failure sets `error` and keeps the draft.
52
+ */
53
+ export declare function useTextField<TClient extends ViewClient>(view: () => TextFieldView<TClient>, read: (state: TClient["snapshot"]) => string, write: (client: TClient, value: string) => Promise<unknown>, options?: UseTextFieldOptions): TextFieldHandle;
@@ -0,0 +1,47 @@
1
+ import { untrack } from "svelte";
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 while the calling component is mounted, through
11
+ * `createTextFieldController`. Call it during component initialization. Typing key by key never loses characters:
12
+ * while its writes are in flight the field shows what the user typed, at most one write is in flight (newer text is
13
+ * written next), nothing is written during IME composition, and once the last write settled it shows the View's
14
+ * value, including any normalization.
15
+ *
16
+ * ```svelte
17
+ * const person = useView(() => page);
18
+ * const name = useTextField(() => person, state => state.name, (client, value) => client.setName(value));
19
+ * <input bind:value={name.value} oncompositionstart={name.compositionStart} oncompositionend={name.compositionEnd}>
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 useTextField(view, read, write, options = {}) {
25
+ const controller = createTextFieldController({ read, write, ...options });
26
+ let current = $state.raw(controller.current);
27
+ const unsubscribe = controller.subscribe(() => { current = controller.current; });
28
+ // A pre effect runs when it is created, so the teardown exists even if the owner is destroyed before its first
29
+ // flush (see useOperation). It reads no state, so it never re-runs.
30
+ $effect.pre(() => () => { unsubscribe(); controller.dispose(); });
31
+ $effect.pre(() => {
32
+ const { state, client } = view();
33
+ untrack(() => {
34
+ controller.setSource(state === undefined || client === undefined ? undefined : { state, client });
35
+ current = controller.current;
36
+ });
37
+ });
38
+ return {
39
+ get value() { return current.value; },
40
+ set value(text) { controller.input(text); },
41
+ get editing() { return current.editing; },
42
+ get error() { return current.error; },
43
+ compositionStart: () => controller.compositionStart(),
44
+ compositionEnd: (event) => controller.compositionEnd(textOf(event)),
45
+ reset: () => controller.reset(),
46
+ };
47
+ }
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.12.1",
3
+ "version": "0.13.0",
4
4
  "description": "Svelte 5 Application Views helpers for Runic",
5
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.1/packages/web/svelte#readme",
5
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.13.0/packages/web/svelte#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
8
8
  },
@@ -35,12 +35,12 @@
35
35
  "clean": "bun -e \"import('node:fs').then(({rmSync}) => rmSync('dist', { recursive: true, force: true }))\"",
36
36
  "build": "bun run --bun clean && svelte-package -i src -o dist",
37
37
  "check": "svelte-check --tsconfig ./tsconfig.json",
38
- "test": "bun run --bun build && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && vitest run test/use-view.svelte.test.ts test/glue.svelte.test.ts test/use-operation.svelte.test.ts test/use-latest-operation.svelte.test.ts test/lifecycle.svelte.test.ts test/use-bridge-connection.svelte.test.ts test/use-menu-bar.svelte.test.ts",
38
+ "test": "bun run --bun build && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && vitest run test/use-view.svelte.test.ts test/glue.svelte.test.ts test/use-operation.svelte.test.ts test/use-latest-operation.svelte.test.ts test/lifecycle.svelte.test.ts test/use-bridge-connection.svelte.test.ts test/use-menu-bar.svelte.test.ts test/use-text-field.svelte.test.ts test/text-field.browser.test.ts",
39
39
  "pack:check": "bun pm pack --dry-run"
40
40
  },
41
41
  "peerDependencies": {
42
42
  "svelte": ">=5.57.1 <6",
43
- "@runic-artifex/views": "0.12.1"
43
+ "@runic-artifex/views": "0.13.0"
44
44
  },
45
45
  "publishConfig": {
46
46
  "access": "public",
@@ -53,18 +53,19 @@
53
53
  },
54
54
  "packageManager": "bun@1.4.4",
55
55
  "devDependencies": {
56
- "@runic-artifex/views": "0.12.1",
56
+ "@runic-artifex/views": "0.13.0",
57
57
  "@sveltejs/adapter-static": "4.0.0",
58
58
  "@sveltejs/kit": "3.0.0",
59
59
  "@sveltejs/package": "3.0.0",
60
60
  "@sveltejs/vite-plugin-svelte": "7.3.1",
61
61
  "@types/node": "24.19.1",
62
62
  "happy-dom": "^21.0.4",
63
+ "playwright-core": "1.63.0",
63
64
  "svelte": "5.57.1",
64
65
  "svelte-check": "4.7.6",
65
66
  "typescript": "6.0.3",
66
67
  "vitest": "5.0.3",
67
68
  "vite": "8.3.4"
68
69
  },
69
- "gitHead": "124a532e5861cff03e77d2ef0c5d4f081ee99a47"
70
+ "gitHead": "3331f81c7a2de34e209b53eb07515323d6d15cf3"
70
71
  }