@runic-artifex/svelte 0.7.0-preview.5 → 0.7.0-preview.7

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
@@ -2,7 +2,7 @@
2
2
 
3
3
  Svelte 5 Application Views helpers. `@runic-artifex/svelte` and
4
4
  `@runic-artifex/svelte/views` export `useView`, `ViewOutlet`, `ViewRegistry`,
5
- `useCommand` and `useCollectionViewport` for generated Window/View clients.
5
+ `useCommand`, `useOperation` and `useCollectionViewport` for generated Window/View clients.
6
6
 
7
7
  Generated View clients import `@runic-artifex/views`, which this package also
8
8
  builds on, so a Views application installs both packages:
@@ -41,6 +41,32 @@ reference with a different `connect` function. An already connected client is
41
41
  observed and left to its owner. The result exposes reactive `state`, `client`,
42
42
  `error` and `pending` properties and `retry()`.
43
43
 
44
+ ### Read-only state and `bind:value`
45
+
46
+ As in any MVVM View, the ViewModel's C# setters decide what the page may set.
47
+ Read state one way from `state`. A property with a public C# setter also gets a
48
+ `set<Property>` client method; pass a getter and setter pair to `bind:value`
49
+ (Svelte 5.9 or later) to bind it two way. Status with a `private set`, such as
50
+ `IsDirty` or `Error`, has no setter and is only rendered:
51
+
52
+ ```svelte
53
+ <script lang="ts">
54
+ // C#: public partial int Count { get; private set; } public partial int Step { get; set; }
55
+ import { useCommand, useView } from "@runic-artifex/svelte/views";
56
+ import type { CounterPageReference } from "./generated/counter.js";
57
+
58
+ let { page }: { page: CounterPageReference } = $props();
59
+ const counter = useView(() => page);
60
+ const setStep = useCommand((step: number) => counter.client?.setStep(step));
61
+ </script>
62
+
63
+ <p>{counter.state?.count ?? "…"}</p>
64
+ <select bind:value={() => counter.state?.step ?? 1, step => setStep.run(step)}>
65
+ <option value={1}>1</option>
66
+ <option value={5}>5</option>
67
+ </select>
68
+ ```
69
+
44
70
  ## `ViewOutlet`
45
71
 
46
72
  Renders the component registered for a generated reference's `kind` and passes
@@ -83,10 +109,77 @@ from the outcome, while `error` keeps unexpected failures. Starting a run and
83
109
  `reset()` clear both, and a run superseded by a later run or by `reset()` sets
84
110
  neither.
85
111
 
112
+ ## `useOperation(start, options?)`
113
+
114
+ Call during component initialization to observe a generated operation's admission,
115
+ pending state, terminal outcome and cancellation. Progress and recovery stay in the
116
+ generated View snapshot:
117
+
118
+ ```svelte
119
+ <script lang="ts">
120
+ import { useOperation, useView } from "@runic-artifex/svelte/views";
121
+ import { connectWorkspace } from "./generated/workspace.js";
122
+
123
+ const workspace = useView(() => ({ connect: connectWorkspace }));
124
+ const push = useOperation((remote: string) => workspace.client?.startPush(remote));
125
+ </script>
126
+
127
+ <button disabled={!workspace.client || push.pending} onclick={() => push.run("origin")}>Push</button>
128
+ {#if push.pending}
129
+ <p role="status">{workspace.state?.operationMessage ?? "Starting…"}</p>
130
+ <button disabled={push.cancellationRequested} onclick={() => push.cancel()}>Cancel</button>
131
+ {/if}
132
+ {#if push.cancelled}<p role="status">Push cancelled.</p>{/if}
133
+ {#if push.error ?? push.cancelError}<p role="alert">{String(push.error ?? push.cancelError)}</p>{/if}
134
+ ```
135
+
136
+ The result exposes reactive `pending`, `admitting`, `operation`, `status`, `outcome`,
137
+ `failure`, `error`, `cancelled`, `cancellationRequested`, `cancelling`, `cancellation`
138
+ and `cancelError`, with `run(...args)`, `cancel()` and `reset()`. Both async methods never
139
+ reject. A run that ends with a `cancelled` status sets `cancelled` and leaves `error`
140
+ undefined; `failed` and `timedOut` statuses are still `error`. Cancel before a delayed Start receipt is retained for that captured run;
141
+ its response does not release pending state. `reset()` clears feedback while
142
+ preserving busy state and cancellation identity. Component destruction settles UI
143
+ observation promises and detaches feedback without cancelling accepted mutations.
144
+ The host still owns accepted-work completion and shutdown drain.
145
+
146
+ The optional typed `cancel(operation)` callback can use a short application control
147
+ command. `waitForCompletion(operation, terminalStatus)` can await application drain
148
+ or command availability that outlives the invocation wrapper. By default the helper
149
+ uses the operation's public `wait()` and `outcome()`; the desktop transport keeps
150
+ Cancel and other callbacks responsive during observation.
151
+
152
+ For rapid read selection, compose the framework-neutral
153
+ [`createLatestOperationController`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.7.0-preview.7/packages/web/views#operation-feedback-and-latest-selection)
154
+ with Svelte state. It coalesces latest intent across delayed receipts and orders
155
+ the next admission after terminal observation and any application drain barrier:
156
+
157
+ ```svelte
158
+ <script lang="ts">
159
+ import { createLatestOperationController } from "@runic-artifex/views";
160
+
161
+ const selections = createLatestOperationController<void>();
162
+ let selection = $state.raw(selections.current);
163
+ const unsubscribe = selections.subscribe(() => { selection = selections.current; });
164
+ $effect.pre(() => () => { unsubscribe(); selections.dispose(); });
165
+ // Event handlers call selections.run({ start, cancel, isCurrent, waitForCompletion? }).
166
+ // Capture the original client/session in each intent. On application-owned
167
+ // session replacement, call selections.clear("replace") to detach old intent.
168
+ </script>
169
+
170
+ {#if selection.blocked}<p role="alert">Selection completion is uncertain. Reconnect or replace the session before retrying.</p>{/if}
171
+ ```
172
+
173
+ `clear()` drops queued input and cancels the captured read; `clear("replace")`
174
+ detaches it without cancellation and permits fresh admission. The application must
175
+ establish that replacement boundary and own the old work's drain. Lost terminal
176
+ observation blocks further Starts instead of retrying blindly, with its reason in
177
+ `current.error`; ordinary Cancel does not clear this block.
178
+
86
179
  ## `useCollectionViewport(options)`
87
180
 
88
181
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
89
- `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/main/packages/web/views#collectionviewportoptions)
182
+ `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.7.0-preview.7/packages/web/views#collectionviewportoptions)
90
183
  range; `attach` is an attachment for the container. Call it during component
91
184
  initialization and send the range to the ViewModel from an effect:
92
185
 
@@ -106,5 +199,5 @@ initialization and send the range to the ViewModel from an effect:
106
199
  ```
107
200
 
108
201
  Translation helpers moved to
109
- [`@runic-artifex/translations-svelte`](https://github.com/Runic-Artifex/runic-translations-sdk/tree/main/packages/web/translations-svelte).
110
- Use a prior SDK preview until application imports have been migrated.
202
+ [`@runic-artifex/translations-svelte`](https://www.npmjs.com/package/@runic-artifex/translations-svelte).
203
+ Import them from there instead of `@runic-artifex/svelte`.
@@ -2,5 +2,6 @@ export { default as ViewOutlet } from "./ViewOutlet.svelte";
2
2
  export type { ViewReference, ViewRegistry } from "./view-registry.js";
3
3
  export { useView, type ViewHandle } from "./use-view.svelte.js";
4
4
  export { useCommand, type CommandHandle } from "./use-command.svelte.js";
5
+ export { useOperation, type OperationHandle } from "./use-operation.svelte.js";
5
6
  export { useCollectionViewport, type CollectionViewportHandle } from "./use-collection-viewport.svelte.js";
6
7
  export type { CollectionViewport, CollectionViewportOptions, ViewClient, ViewConnector, ViewSource } from "@runic-artifex/views";
@@ -1,4 +1,5 @@
1
1
  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
+ export { useOperation } from "./use-operation.svelte.js";
4
5
  export { useCollectionViewport } from "./use-collection-viewport.svelte.js";
@@ -0,0 +1,10 @@
1
+ import { type BridgeOperation, type OperationController, type OperationControllerOptions, type OperationState } from "@runic-artifex/views";
2
+ export interface OperationHandle<TArgs extends readonly unknown[], TResult, TFailure = never> extends OperationState<TResult, TFailure>, Pick<OperationController<TArgs, TResult, TFailure>, "run" | "cancel" | "reset"> {
3
+ }
4
+ /**
5
+ * Tracks Start admission, pending work, cancellation and terminal feedback as
6
+ * reactive properties. Call during component initialization. Owner destruction
7
+ * detaches observation and settles run promises without cancelling accepted work.
8
+ * Progress remains in the generated View snapshot, where the application owns it.
9
+ */
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>;
@@ -0,0 +1,34 @@
1
+ import { createOperationController, } from "@runic-artifex/views";
2
+ /**
3
+ * Tracks Start admission, pending work, cancellation and terminal feedback as
4
+ * reactive properties. Call during component initialization. Owner destruction
5
+ * detaches observation and settles run promises without cancelling accepted work.
6
+ * Progress remains in the generated View snapshot, where the application owns it.
7
+ */
8
+ export function useOperation(start, options = {}) {
9
+ const controller = createOperationController(start, options);
10
+ let current = $state.raw(controller.current);
11
+ const unsubscribe = controller.subscribe(() => { current = controller.current; });
12
+ // Svelte runs a pre effect when it is created, during owner initialization,
13
+ // so this teardown exists even if the owner is destroyed before its first
14
+ // flush. onMount/onDestroy and $effect are deferred to that flush and would
15
+ // leak the controller then. The effect reads no state, so it never re-runs.
16
+ $effect.pre(() => () => { unsubscribe(); controller.dispose(); });
17
+ return {
18
+ run: controller.run,
19
+ cancel: controller.cancel,
20
+ 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 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
+ };
34
+ }
@@ -1,10 +1,13 @@
1
1
  import type { Component } from "svelte";
2
2
  import type { ViewReference } from "@runic-artifex/views";
3
3
  export type { ViewReference } from "@runic-artifex/views";
4
- /** Compile-time check that every View kind has a component with a matching page prop. */
5
- export type ViewRegistry<R extends ViewReference> = {
6
- readonly [K in R["kind"]]: Component<{
7
- page: Extract<R, {
4
+ /**
5
+ * Compile-time check that every View kind has a component with a matching page prop. A nullable
6
+ * reference, such as a region slot's `State["main"]`, checks its non-null kinds.
7
+ */
8
+ export type ViewRegistry<R extends ViewReference | null | undefined> = {
9
+ readonly [K in NonNullable<R>["kind"]]: Component<{
10
+ page: Extract<NonNullable<R>, {
8
11
  readonly kind: K;
9
12
  }>;
10
13
  }>;
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.7.0-preview.5",
3
+ "version": "0.7.0-preview.7",
4
4
  "description": "Svelte 5 Application Views helpers for Runic",
5
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/main/packages/web/svelte#readme",
5
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.7.0-preview.7/packages/web/svelte#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
8
8
  },
@@ -38,12 +38,12 @@
38
38
  "clean": "bun -e \"import('node:fs').then(({rmSync}) => rmSync('dist', { recursive: true, force: true }))\"",
39
39
  "build": "bun run --bun clean && svelte-package -i src -o dist",
40
40
  "check": "svelte-check --tsconfig ./tsconfig.json",
41
- "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",
41
+ "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",
42
42
  "pack:check": "bun pm pack --dry-run"
43
43
  },
44
44
  "peerDependencies": {
45
45
  "svelte": ">=5.46.4 <6",
46
- "@runic-artifex/views": "0.7.0-preview.5"
46
+ "@runic-artifex/views": "0.7.0-preview.7"
47
47
  },
48
48
  "publishConfig": {
49
49
  "access": "public",
@@ -59,7 +59,7 @@
59
59
  "node": ">=24.18.0 <25"
60
60
  },
61
61
  "devDependencies": {
62
- "@runic-artifex/views": "0.7.0-preview.5",
62
+ "@runic-artifex/views": "0.7.0-preview.7",
63
63
  "@sveltejs/adapter-static": "4.0.0",
64
64
  "@sveltejs/kit": "3.0.0",
65
65
  "@sveltejs/package": "3.0.0",
@@ -72,5 +72,5 @@
72
72
  "vitest": "5.0.3",
73
73
  "vite": "8.3.2"
74
74
  },
75
- "gitHead": "0ef2a51e2c03b47311093a979da823540db25ca6"
75
+ "gitHead": "d274acebd19284557ad6a3d02562ddfac93ae4e1"
76
76
  }