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

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:
@@ -83,6 +83,71 @@ from the outcome, while `error` keeps unexpected failures. Starting a run and
83
83
  `reset()` clear both, and a run superseded by a later run or by `reset()` sets
84
84
  neither.
85
85
 
86
+ ## `useOperation(start, options?)`
87
+
88
+ Call during component initialization to observe a generated operation's admission,
89
+ pending state, terminal outcome and cancellation. Progress and recovery stay in the
90
+ generated View snapshot:
91
+
92
+ ```svelte
93
+ <script lang="ts">
94
+ import { useOperation, useView } from "@runic-artifex/svelte/views";
95
+ import { connectWorkspace } from "./generated/workspace.js";
96
+
97
+ const workspace = useView(() => ({ connect: connectWorkspace }));
98
+ const push = useOperation((remote: string) => workspace.client?.startPush(remote));
99
+ </script>
100
+
101
+ <button disabled={!workspace.client || push.pending} onclick={() => push.run("origin")}>Push</button>
102
+ {#if push.pending}
103
+ <p role="status">{workspace.state?.operationMessage ?? "Starting…"}</p>
104
+ <button disabled={push.cancellationRequested} onclick={() => push.cancel()}>Cancel</button>
105
+ {/if}
106
+ {#if push.error ?? push.cancelError}<p role="alert">{String(push.error ?? push.cancelError)}</p>{/if}
107
+ ```
108
+
109
+ The result exposes reactive `pending`, `admitting`, `operation`, `status`, `outcome`,
110
+ `failure`, `error`, `cancellationRequested`, `cancelling`, `cancellation` and
111
+ `cancelError`, with `run(...args)`, `cancel()` and `reset()`. Both async methods never
112
+ reject. Cancel before a delayed Start receipt is retained for that captured run;
113
+ its response does not release pending state. `reset()` clears feedback while
114
+ preserving busy state and cancellation identity. Component destruction settles UI
115
+ observation promises and detaches feedback without cancelling accepted mutations.
116
+ The host still owns accepted-work completion and shutdown drain.
117
+
118
+ The optional typed `cancel(operation)` callback can use a short application control
119
+ command. `waitForCompletion(operation, terminalStatus)` can await application drain
120
+ or command availability that outlives the invocation wrapper. By default the helper
121
+ uses the operation's public `wait()` and `outcome()`; the desktop transport keeps
122
+ Cancel and other callbacks responsive during observation.
123
+
124
+ For rapid read selection, compose the framework-neutral
125
+ [`createLatestOperationController`](https://github.com/Runic-Artifex/runic-sdk/tree/main/packages/web/views#operation-feedback-and-latest-selection)
126
+ with Svelte state. It coalesces latest intent across delayed receipts and orders
127
+ the next admission after terminal observation and any application drain barrier:
128
+
129
+ ```svelte
130
+ <script lang="ts">
131
+ import { createLatestOperationController } from "@runic-artifex/views";
132
+
133
+ const selections = createLatestOperationController<void>();
134
+ let selection = $state.raw(selections.current);
135
+ const unsubscribe = selections.subscribe(() => { selection = selections.current; });
136
+ $effect.pre(() => () => { unsubscribe(); selections.dispose(); });
137
+ // Event handlers call selections.run({ start, cancel, isCurrent, waitForCompletion? }).
138
+ // Capture the original client/session in each intent. On application-owned
139
+ // session replacement, call selections.clear("replace") to detach old intent.
140
+ </script>
141
+
142
+ {#if selection.blocked}<p role="alert">Selection completion is uncertain. Reconnect or replace the session before retrying.</p>{/if}
143
+ ```
144
+
145
+ `clear()` drops queued input and cancels the captured read; `clear("replace")`
146
+ detaches it without cancellation and permits fresh admission. The application must
147
+ establish that replacement boundary and own the old work's drain. Lost terminal
148
+ observation blocks further Starts instead of retrying blindly, with its reason in
149
+ `current.error`; ordinary Cancel does not clear this block.
150
+
86
151
  ## `useCollectionViewport(options)`
87
152
 
88
153
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
@@ -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,31 @@
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
+ // Register teardown immediately, even if the owner is destroyed before the
13
+ // first deferred effect flush. This effect has no reactive dependencies.
14
+ $effect.pre(() => () => { unsubscribe(); controller.dispose(); });
15
+ return {
16
+ run: controller.run,
17
+ cancel: controller.cancel,
18
+ reset: controller.reset,
19
+ get pending() { return current.pending; },
20
+ get admitting() { return current.admitting; },
21
+ get operation() { return current.operation; },
22
+ get status() { return current.status; },
23
+ get outcome() { return current.outcome; },
24
+ get failure() { return current.failure; },
25
+ get error() { return current.error; },
26
+ get cancellationRequested() { return current.cancellationRequested; },
27
+ get cancelling() { return current.cancelling; },
28
+ get cancellation() { return current.cancellation; },
29
+ get cancelError() { return current.cancelError; },
30
+ };
31
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.7.0-preview.5",
3
+ "version": "0.7.0-preview.6",
4
4
  "description": "Svelte 5 Application Views helpers for Runic",
5
5
  "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/main/packages/web/svelte#readme",
6
6
  "bugs": {
@@ -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.6"
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.6",
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": "3ae26934626510c83e01aaf6d67bcdc5543d3d38"
76
76
  }