@runic-artifex/svelte 0.15.0 → 0.15.1

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
@@ -43,7 +43,11 @@ replaces `client.dispose()` for a client the helper connected. It connects a gen
43
43
  reference, or `{ connect: connect<Name> }` for a root ViewModel, while the
44
44
  component is mounted. An already connected client is observed and left to its
45
45
  owner. The result exposes reactive `state`, `client`, `error` and `pending`
46
- properties and `retry()`.
46
+ properties and `retry()`. Only `state` follows each published state: `client`
47
+ stays the same object for the connection, and `client`, `error` and `pending`
48
+ notify their readers only when their own value changes, so an `$effect` that
49
+ reads `client` to call a command does not run again when the command's answer
50
+ changes the state.
47
51
 
48
52
  When the component is destroyed or the getter returns a reference with a
49
53
  different `connect` function, the client stays connected for
@@ -82,7 +86,7 @@ the failure. Await it with `{#await}`:
82
86
  The source is read once: wrap the component in `{#key page}` to follow another
83
87
  reference. Do not `{#await page.connect()}` directly: nothing would dispose
84
88
  that client. In SvelteKit, connect in a `load` function instead
85
- ([`@runic-artifex/sveltekit`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.0/packages/web/svelte/../sveltekit/README.md#connecting-in-load)).
89
+ ([`@runic-artifex/sveltekit`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.1/packages/web/svelte/../sveltekit/README.md#connecting-in-load)).
86
90
 
87
91
  ### Selecting state: `$derived`
88
92
 
@@ -178,14 +182,14 @@ handle also has `value` and `text`, which `bind:value={title.value}` reads and s
178
182
  `errors` holds the member's validation messages from the descriptor (`[]` when valid), `error` why the latest write
179
183
  or text failed (a `BridgeError` or a `FieldError`, whose `kind` is `rejected`, `conflict`, `committed-with-error` or
180
184
  `invalid-text`). `FieldError`, `FieldOptions`, `FieldState` and `BridgeField` are exported from this package. See the
181
- [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/packages/web/views#fields) for the receipts
185
+ [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#fields) for the receipts
182
186
  and text forms.
183
187
 
184
188
  ### Text inputs: `useTextField(view, read, write, options?)`
185
189
 
186
190
  Call during component initialization to bind a text input to a member through the
187
191
  framework-neutral
188
- [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/packages/web/views#text-inputs):
192
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#text-inputs):
189
193
 
190
194
  ```svelte
191
195
  <script lang="ts">
@@ -324,7 +328,7 @@ Cancel and other callbacks responsive during observation.
324
328
  ## `useLatestOperation()`
325
329
 
326
330
  For rapid read selection, `useLatestOperation()` wraps the framework-neutral
327
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/packages/web/views#operation-feedback-and-latest-selection)
331
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#operation-feedback-and-latest-selection)
328
332
  for the component's lifetime. It coalesces the latest intent across delayed receipts
329
333
  and orders the next admission after terminal observation and any application drain
330
334
  barrier:
@@ -355,7 +359,7 @@ establish that replacement boundary and own the old work's drain. Lost terminal
355
359
  observation blocks further Starts instead of retrying blindly, with its reason in
356
360
  `error`; ordinary Cancel does not clear this block. Component destruction settles
357
361
  observation without cancelling accepted work. The
358
- [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/tests/fixtures/application/operations-consumer)
362
+ [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/tests/fixtures/application/operations-consumer)
359
363
  runs this hook against the packed packages and the desktop transport.
360
364
 
361
365
  ## `useBridgeConnection(options?)`
@@ -365,7 +369,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
365
369
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a reactive
366
370
  `BridgeConnectionState`: `connecting`, `connected`, `reconnecting`, `lost` or `closed` (the
367
371
  application closed the window, since 0.15; a closed set, see
368
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/packages/web/views#connection-state)):
372
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#connection-state)):
369
373
 
370
374
  ```svelte
371
375
  <script lang="ts">
@@ -387,7 +391,7 @@ server render does not observe, and destroying the owner unsubscribes. An invali
387
391
  Follows the declared menu bar of a Runic Desktop window that leaves it to the
388
392
  page (`DesktopMenuBarPresentation.Page`) while its owner lives. It wraps
389
393
  `createMenuBarController` from `@runic-artifex/views` (see
390
- [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`, where `state` is a
394
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`, where `state` is a
391
395
  reactive `MenuBarState` property. The bar is rendered by the menubar component
392
396
  of the application's own UI library. Runic ships no menubar component.
393
397
 
@@ -416,7 +420,7 @@ the `shortcuts: "app"` lease.
416
420
  ### With Bits UI
417
421
 
418
422
  Bits UI's `Menubar.Root bind:value`; the
419
- [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
423
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
420
424
  items and is tested with real keys:
421
425
 
422
426
  ```svelte
@@ -483,7 +487,7 @@ const message = $derived(describeBridgeError(view.error));
483
487
  ```
484
488
 
485
489
  `instanceof` holds for errors from every copy of the package on the page.
486
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/packages/web/views#errors-and-diagnostics)
490
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#errors-and-diagnostics)
487
491
  lists the kinds. Any other value, such as an exception that your own connect
488
492
  function or command callback throws, arrives unchanged.
489
493
 
@@ -522,15 +526,15 @@ application's own dialog.
522
526
  departure before that is answered by the ViewModel's .NET fallback handler, or
523
527
  fails closed without one.
524
528
 
525
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
529
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
526
530
  has the .NET side and which View answers which departure. In a frontend test,
527
531
  the generated mock's `interactions.<name>.request(input)` resolves with the
528
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/packages/web/views#testing).
532
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#testing).
529
533
 
530
534
  ## `useCollectionViewport(options)`
531
535
 
532
536
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
533
- `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/packages/web/views#collectionviewportoptions)
537
+ `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#collectionviewportoptions)
534
538
  range; `attach` is an attachment for the container. Call it during component
535
539
  initialization and send the range to the ViewModel from an effect:
536
540
 
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Derives each member of a record that a controller replaces as a whole, so a reader of one member, such as an
3
+ * `$effect` that reads only `pending`, runs again only when that member changes and not with every new record.
4
+ * Call it where `$derived` may be created: during component initialization or in an `$effect.root`.
5
+ */
6
+ export declare function derivedFields<T extends object, K extends keyof T>(record: () => T, keys: readonly K[]): {
7
+ readonly [P in K]: () => T[P];
8
+ };
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Derives each member of a record that a controller replaces as a whole, so a reader of one member, such as an
3
+ * `$effect` that reads only `pending`, runs again only when that member changes and not with every new record.
4
+ * Call it where `$derived` may be created: during component initialization or in an `$effect.root`.
5
+ */
6
+ export function derivedFields(record, keys) {
7
+ const readers = {};
8
+ for (const key of keys) {
9
+ const value = $derived(record()[key]);
10
+ readers[key] = () => value;
11
+ }
12
+ return readers;
13
+ }
@@ -1,4 +1,5 @@
1
1
  import { createCommandController } from "@runic-artifex/views";
2
+ import { derivedFields } from "./derived-fields.svelte.js";
2
3
  /**
3
4
  * Tracks a command's pending state and failure as reactive properties. Called
4
5
  * during component initialization (or in `$effect.root`), owner destruction
@@ -24,11 +25,13 @@ export function useCommand(command) {
24
25
  if (!String(error?.message).includes("effect_orphan"))
25
26
  throw error;
26
27
  }
28
+ // One derived per member, so a reader of one member runs again only when that member changes.
29
+ const fields = derivedFields(() => current, ["pending", "error", "failure"]);
27
30
  return {
28
31
  run: controller.run,
29
- get pending() { return current.pending; },
30
- get error() { return current.error; },
31
- get failure() { return current.failure; },
32
+ get pending() { return fields.pending(); },
33
+ get error() { return fields.error(); },
34
+ get failure() { return fields.failure(); },
32
35
  reset: controller.reset,
33
36
  };
34
37
  }
@@ -1,5 +1,6 @@
1
1
  import { untrack } from "svelte";
2
2
  import { createFieldController, } from "@runic-artifex/views";
3
+ import { derivedFields } from "./derived-fields.svelte.js";
3
4
  /**
4
5
  * Binds an element to one View member while the calling component is mounted, through `createFieldController`: pass a
5
6
  * generated descriptor such as `EditorFields.title`, or any definition with `read` and `write`. Call it during
@@ -67,15 +68,17 @@ export function useField(view, field, options = {}) {
67
68
  element.removeEventListener("blur", blur);
68
69
  };
69
70
  };
71
+ // One derived per member, so a reader of one member runs again only when that member changes.
72
+ const fields = derivedFields(() => current, ["value", "text", "editing", "error", "errors", "conflict"]);
70
73
  return {
71
- get value() { return current.value; },
74
+ get value() { return fields.value(); },
72
75
  set value(value) { controller.input(value); },
73
- get text() { return current.text; },
76
+ get text() { return fields.text(); },
74
77
  set text(text) { controller.inputText(text); },
75
- get editing() { return current.editing; },
76
- get error() { return current.error; },
77
- get errors() { return current.errors; },
78
- get conflict() { return current.conflict; },
78
+ get editing() { return fields.editing(); },
79
+ get error() { return fields.error(); },
80
+ get errors() { return fields.errors(); },
81
+ get conflict() { return fields.conflict(); },
79
82
  input: (value) => controller.input(value),
80
83
  commit: () => controller.commit(),
81
84
  retry: () => controller.retry(),
@@ -1,4 +1,5 @@
1
1
  import { createLatestOperationController, } from "@runic-artifex/views";
2
+ import { derivedFields } from "./derived-fields.svelte.js";
2
3
  /**
3
4
  * Admits only the newest selection, for reads such as "load the selected item": each
4
5
  * `run(intent)` replaces the queued intent and cancels the active read, and the next read
@@ -14,22 +15,24 @@ export function useLatestOperation() {
14
15
  const unsubscribe = controller.subscribe(() => { current = controller.current; });
15
16
  // Registered before the first flush, so a destroyed owner never leaks the controller (see useOperation).
16
17
  $effect.pre(() => () => { unsubscribe(); controller.dispose(); });
18
+ // One derived per member, so a reader of one member runs again only when that member changes.
19
+ const fields = derivedFields(() => current, ["pending", "admitting", "operation", "status", "progress", "outcome", "failure", "error", "cancelled", "cancellationRequested", "cancelling", "cancellation", "cancelError", "blocked"]);
17
20
  return {
18
21
  run: controller.run,
19
22
  clear: controller.clear,
20
- get pending() { return current.pending; },
21
- get admitting() { return current.admitting; },
22
- get operation() { return current.operation; },
23
- get status() { return current.status; },
24
- get progress() { return current.progress; },
25
- get outcome() { return current.outcome; },
26
- get failure() { return current.failure; },
27
- get error() { return current.error; },
28
- get cancelled() { return current.cancelled; },
29
- get cancellationRequested() { return current.cancellationRequested; },
30
- get cancelling() { return current.cancelling; },
31
- get cancellation() { return current.cancellation; },
32
- get cancelError() { return current.cancelError; },
33
- get blocked() { return current.blocked; },
23
+ get pending() { return fields.pending(); },
24
+ get admitting() { return fields.admitting(); },
25
+ get operation() { return fields.operation(); },
26
+ get status() { return fields.status(); },
27
+ get progress() { return fields.progress(); },
28
+ get outcome() { return fields.outcome(); },
29
+ get failure() { return fields.failure(); },
30
+ get error() { return fields.error(); },
31
+ get cancelled() { return fields.cancelled(); },
32
+ get cancellationRequested() { return fields.cancellationRequested(); },
33
+ get cancelling() { return fields.cancelling(); },
34
+ get cancellation() { return fields.cancellation(); },
35
+ get cancelError() { return fields.cancelError(); },
36
+ get blocked() { return fields.blocked(); },
34
37
  };
35
38
  }
@@ -1,4 +1,5 @@
1
1
  import { createOperationController, } from "@runic-artifex/views";
2
+ import { derivedFields } from "./derived-fields.svelte.js";
2
3
  /**
3
4
  * Tracks Start admission, pending work, cancellation and terminal feedback as
4
5
  * reactive properties. Call during component initialization. Owner destruction
@@ -14,22 +15,24 @@ export function useOperation(start, options = {}) {
14
15
  // flush. onMount/onDestroy and $effect are deferred to that flush and would
15
16
  // leak the controller then. The effect reads no state, so it never re-runs.
16
17
  $effect.pre(() => () => { unsubscribe(); controller.dispose(); });
18
+ // One derived per member, so a reader of one member runs again only when that member changes.
19
+ const fields = derivedFields(() => current, ["pending", "admitting", "operation", "status", "progress", "outcome", "failure", "error", "cancelled", "cancellationRequested", "cancelling", "cancellation", "cancelError"]);
17
20
  return {
18
21
  run: controller.run,
19
22
  cancel: controller.cancel,
20
23
  reset: controller.reset,
21
- get pending() { return current.pending; },
22
- get admitting() { return current.admitting; },
23
- get operation() { return current.operation; },
24
- get status() { return current.status; },
25
- get progress() { return current.progress; },
26
- get outcome() { return current.outcome; },
27
- get failure() { return current.failure; },
28
- get error() { return current.error; },
29
- get cancelled() { return current.cancelled; },
30
- get cancellationRequested() { return current.cancellationRequested; },
31
- get cancelling() { return current.cancelling; },
32
- get cancellation() { return current.cancellation; },
33
- get cancelError() { return current.cancelError; },
24
+ get pending() { return fields.pending(); },
25
+ get admitting() { return fields.admitting(); },
26
+ get operation() { return fields.operation(); },
27
+ get status() { return fields.status(); },
28
+ get progress() { return fields.progress(); },
29
+ get outcome() { return fields.outcome(); },
30
+ get failure() { return fields.failure(); },
31
+ get error() { return fields.error(); },
32
+ get cancelled() { return fields.cancelled(); },
33
+ get cancellationRequested() { return fields.cancellationRequested(); },
34
+ get cancelling() { return fields.cancelling(); },
35
+ get cancellation() { return fields.cancellation(); },
36
+ get cancelError() { return fields.cancelError(); },
34
37
  };
35
38
  }
@@ -1,5 +1,6 @@
1
1
  import { untrack } from "svelte";
2
2
  import { createTextFieldController } from "@runic-artifex/views";
3
+ import { derivedFields } from "./derived-fields.svelte.js";
3
4
  function textOf(event) {
4
5
  if (typeof event === "string")
5
6
  return event;
@@ -37,11 +38,13 @@ export function useTextField(view, read, write, options = {}) {
37
38
  current = controller.current;
38
39
  });
39
40
  });
41
+ // One derived per member, so a reader of one member runs again only when that member changes.
42
+ const fields = derivedFields(() => current, ["value", "editing", "error"]);
40
43
  return {
41
- get value() { return current.value; },
44
+ get value() { return fields.value(); },
42
45
  set value(text) { controller.input(text); },
43
- get editing() { return current.editing; },
44
- get error() { return current.error; },
46
+ get editing() { return fields.editing(); },
47
+ get error() { return fields.error(); },
45
48
  compositionStart: () => controller.compositionStart(),
46
49
  compositionEnd: (event) => controller.compositionEnd(textOf(event)),
47
50
  reset: () => controller.reset(),
@@ -2,7 +2,11 @@ import { type ViewClient, type ViewConnector, type ViewSource } from "@runic-art
2
2
  export interface ViewHandle<TClient extends ViewClient> {
3
3
  /** The latest state, or undefined until the client connects. */
4
4
  readonly state: TClient["snapshot"] | undefined;
5
- /** The connected client for commands, or undefined until it connects. */
5
+ /**
6
+ * The connected client for commands, or undefined until it connects. It stays the same object for the connection,
7
+ * and only `state` follows each published state, so an `$effect` that reads `client`, `error` or `pending` does not
8
+ * run again when the View's state changes.
9
+ */
6
10
  readonly client: TClient | undefined;
7
11
  /** The connection failure, if any. */
8
12
  readonly error: unknown;
@@ -28,15 +28,16 @@ export function useView(source, options = {}) {
28
28
  return fresh() ? undefined : viewSourcePreview(value);
29
29
  };
30
30
  const fresh = () => viewSourceIdentity(current.source) === identity;
31
+ // `current` is replaced with every published state, which only `state` follows. The other members are derived, so
32
+ // an `$effect` that reads only `client` (to call a command) does not run again when the answer publishes a state.
33
+ const client = $derived(preview()?.client ?? (fresh() ? current.client : undefined));
34
+ const error = $derived(fresh() ? current.error : undefined);
35
+ const pending = $derived(preview() ? false : fresh() ? current.pending : identity !== undefined);
31
36
  return {
32
37
  get state() { return preview()?.state ?? (fresh() ? current.state : undefined); },
33
- get client() { return preview()?.client ?? (fresh() ? current.client : undefined); },
34
- get error() { return fresh() ? current.error : undefined; },
35
- get pending() {
36
- if (preview())
37
- return false;
38
- return fresh() ? current.pending : identity !== undefined;
39
- },
38
+ get client() { return client; },
39
+ get error() { return error; },
40
+ get pending() { return pending; },
40
41
  retry() { controller.retry(); },
41
42
  };
42
43
  }
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.15.0",
3
+ "version": "0.15.1",
4
4
  "description": "Svelte 5 Application Views helpers for Runic",
5
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.0/packages/web/svelte#readme",
5
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/svelte#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
8
8
  },
@@ -40,7 +40,7 @@
40
40
  },
41
41
  "peerDependencies": {
42
42
  "svelte": ">=5.57.1 <6",
43
- "@runic-artifex/views": "0.15.0"
43
+ "@runic-artifex/views": "0.15.1"
44
44
  },
45
45
  "publishConfig": {
46
46
  "access": "public",
@@ -53,7 +53,7 @@
53
53
  },
54
54
  "packageManager": "bun@1.4.4",
55
55
  "devDependencies": {
56
- "@runic-artifex/views": "0.15.0",
56
+ "@runic-artifex/views": "0.15.1",
57
57
  "@sveltejs/adapter-static": "4.0.0",
58
58
  "@sveltejs/kit": "3.0.0",
59
59
  "@sveltejs/package": "3.0.0",
@@ -67,5 +67,5 @@
67
67
  "vitest": "5.0.3",
68
68
  "vite": "8.3.4"
69
69
  },
70
- "gitHead": "c94bda07cf363bad056eda86ae77c514b66e61dd"
70
+ "gitHead": "fce42f47296a4784532fbba0fec9602cd3778fbb"
71
71
  }