@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/
|
|
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://
|
|
110
|
-
|
|
202
|
+
[`@runic-artifex/translations-svelte`](https://www.npmjs.com/package/@runic-artifex/translations-svelte).
|
|
203
|
+
Import them from there instead of `@runic-artifex/svelte`.
|
package/dist/views/index.d.ts
CHANGED
|
@@ -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";
|
package/dist/views/index.js
CHANGED
|
@@ -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
|
-
/**
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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.
|
|
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/
|
|
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.
|
|
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.
|
|
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": "
|
|
75
|
+
"gitHead": "d274acebd19284557ad6a3d02562ddfac93ae4e1"
|
|
76
76
|
}
|