@runic-artifex/svelte 0.9.0 → 0.10.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
@@ -1,10 +1,11 @@
1
1
  # `@runic-artifex/svelte`
2
2
 
3
3
  Svelte 5 Application Views helpers. `@runic-artifex/svelte` exports `useView`,
4
- `ViewOutlet`, `ViewRegistry`, `useCommand` and `useOperation` for generated
5
- Window/View clients, and `@runic-artifex/svelte/experimental` exports
6
- `useCollectionViewport`. The `@runic-artifex/svelte/views` entry of earlier
7
- previews is gone: import from `@runic-artifex/svelte`.
4
+ `ViewOutlet`, `ViewRegistry`, `useCommand`, `useOperation`, `useLatestOperation`
5
+ and `useCollectionViewport` for generated Window/View clients. The
6
+ `@runic-artifex/svelte/views` entry of earlier previews and the
7
+ `@runic-artifex/svelte/experimental` entry of 0.9 are gone: import from
8
+ `@runic-artifex/svelte`.
8
9
 
9
10
  Generated View clients import `@runic-artifex/views`, which this package also
10
11
  builds on, so a Views application installs both packages:
@@ -155,32 +156,42 @@ or command availability that outlives the invocation wrapper. By default the hel
155
156
  uses the operation's public `wait()` and `outcome()`; the desktop transport keeps
156
157
  Cancel and other callbacks responsive during observation.
157
158
 
158
- For rapid read selection, compose the framework-neutral
159
- [`createLatestOperationController`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.0/packages/web/views#operation-feedback-and-latest-selection)
160
- with Svelte state. It coalesces latest intent across delayed receipts and orders
161
- the next admission after terminal observation and any application drain barrier:
159
+ ## `useLatestOperation()`
160
+
161
+ For rapid read selection, `useLatestOperation()` wraps the framework-neutral
162
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#operation-feedback-and-latest-selection)
163
+ for the component's lifetime. It coalesces the latest intent across delayed receipts
164
+ and orders the next admission after terminal observation and any application drain
165
+ barrier:
162
166
 
163
167
  ```svelte
164
168
  <script lang="ts">
165
- import { createLatestOperationController } from "@runic-artifex/views/experimental";
166
-
167
- const selections = createLatestOperationController<void>();
168
- let selection = $state.raw(selections.current);
169
- const unsubscribe = selections.subscribe(() => { selection = selections.current; });
170
- $effect.pre(() => () => { unsubscribe(); selections.dispose(); });
171
- // Event handlers call selections.run({ start, cancel, isCurrent, waitForCompletion? }).
172
- // Capture the original client/session in each intent. On application-owned
173
- // session replacement, call selections.clear("replace") to detach old intent.
169
+ import { useLatestOperation, useView } from "@runic-artifex/svelte";
170
+ import { connectCatalog } from "./generated/catalog.js";
171
+
172
+ const catalog = useView(() => ({ connect: connectCatalog }));
173
+ const load = useLatestOperation<Item>();
174
+ function select(id: string) {
175
+ const client = catalog.client;
176
+ if (client) void load.run({ start: () => client.startLoad(id), isCurrent: () => catalog.client === client });
177
+ }
174
178
  </script>
175
179
 
176
- {#if selection.blocked}<p role="alert">Selection completion is uncertain. Reconnect or replace the session before retrying.</p>{/if}
180
+ {#if load.outcome?.ok}<ItemView item={load.outcome.value} />{/if}
181
+ {#if load.blocked}<p role="alert">Selection completion is uncertain. Reconnect or replace the session before retrying.</p>{/if}
177
182
  ```
178
183
 
184
+ The result has the `useOperation` properties plus `blocked`, with `run(intent)` and
185
+ `clear(mode?)`, which never reject. Capture the original client/session in each intent
186
+ (`start`, and optionally `cancel`, `waitForCompletion` and `isCurrent`).
179
187
  `clear()` drops queued input and cancels the captured read; `clear("replace")`
180
188
  detaches it without cancellation and permits fresh admission. The application must
181
189
  establish that replacement boundary and own the old work's drain. Lost terminal
182
190
  observation blocks further Starts instead of retrying blindly, with its reason in
183
- `current.error`; ordinary Cancel does not clear this block.
191
+ `error`; ordinary Cancel does not clear this block. Component destruction settles
192
+ observation without cancelling accepted work. The
193
+ [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/tests/fixtures/application/operations-consumer)
194
+ runs this hook against the packed packages and the desktop transport.
184
195
 
185
196
  ## Errors
186
197
 
@@ -196,7 +207,7 @@ const offline = view.error instanceof BridgeError && view.error.kind === "discon
196
207
  ```
197
208
 
198
209
  `instanceof` holds for errors from every copy of the package on the page.
199
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.0/packages/web/views#errors-and-diagnostics)
210
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#errors-and-diagnostics)
200
211
  lists the kinds. Any other value, such as an exception that your own connect
201
212
  function or command callback throws, arrives unchanged.
202
213
 
@@ -235,18 +246,15 @@ application's own dialog.
235
246
  departure before that is answered by the ViewModel's .NET fallback handler, or
236
247
  fails closed without one.
237
248
 
238
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.9.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
249
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.10.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
239
250
  has the .NET side and which View answers which departure. In a frontend test,
240
251
  the generated mock's `interactions.<name>.request(input)` resolves with the
241
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.0/packages/web/views#testing).
242
-
243
- ## `useCollectionViewport(options)` (experimental)
252
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#testing).
244
253
 
245
- Exported from `@runic-artifex/svelte/experimental`, like the
246
- `@runic-artifex/views/experimental` controller it wraps.
254
+ ## `useCollectionViewport(options)`
247
255
 
248
256
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
249
- `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.0/packages/web/views#collectionviewportoptions-experimental)
257
+ `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#collectionviewportoptions)
250
258
  range; `attach` is an attachment for the container. Call it during component
251
259
  initialization and send the range to the ViewModel from an effect:
252
260
 
@@ -3,3 +3,5 @@ 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 { useLatestOperation, type LatestOperationHandle } from "./use-latest-operation.svelte.js";
7
+ export { useCollectionViewport, type CollectionViewportHandle } from "./use-collection-viewport.svelte.js";
@@ -2,3 +2,5 @@ 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 { useLatestOperation } from "./use-latest-operation.svelte.js";
6
+ export { useCollectionViewport } from "./use-collection-viewport.svelte.js";
@@ -1,5 +1,5 @@
1
1
  import type { Attachment } from "svelte/attachments";
2
- import { type CollectionViewport, type CollectionViewportOptions } from "@runic-artifex/views/experimental";
2
+ import { type CollectionViewport, type CollectionViewportOptions } from "@runic-artifex/views";
3
3
  export interface CollectionViewportHandle {
4
4
  /** The rows to request and the sizes to render. */
5
5
  readonly viewport: CollectionViewport;
@@ -1,5 +1,5 @@
1
1
  import { untrack } from "svelte";
2
- import { createCollectionViewportController } from "@runic-artifex/views/experimental";
2
+ import { createCollectionViewportController } from "@runic-artifex/views";
3
3
  /**
4
4
  * Follows a fixed-row-height scroll container and returns the rows to request
5
5
  * from .NET. Call it during component initialization with a getter, such as
@@ -0,0 +1,13 @@
1
+ import { type LatestOperationController, type LatestOperationState } from "@runic-artifex/views";
2
+ export interface LatestOperationHandle<TResult, TFailure = never> extends LatestOperationState<TResult, TFailure>, Pick<LatestOperationController<TResult, TFailure>, "run" | "clear"> {
3
+ }
4
+ /**
5
+ * Admits only the newest selection, for reads such as "load the selected item": each
6
+ * `run(intent)` replaces the queued intent and cancels the active read, and the next read
7
+ * starts only after the previous one has finished (including `waitForCompletion`). The
8
+ * state fields are reactive properties. `blocked` means admission is uncertain; only
9
+ * `clear("replace")`, after the application has established a fresh session, clears it.
10
+ * Call during component initialization. Owner destruction detaches observation and
11
+ * settles run promises without cancelling accepted work.
12
+ */
13
+ export declare function useLatestOperation<TResult = void, TFailure = never>(): LatestOperationHandle<TResult, TFailure>;
@@ -0,0 +1,34 @@
1
+ import { createLatestOperationController, } from "@runic-artifex/views";
2
+ /**
3
+ * Admits only the newest selection, for reads such as "load the selected item": each
4
+ * `run(intent)` replaces the queued intent and cancels the active read, and the next read
5
+ * starts only after the previous one has finished (including `waitForCompletion`). The
6
+ * state fields are reactive properties. `blocked` means admission is uncertain; only
7
+ * `clear("replace")`, after the application has established a fresh session, clears it.
8
+ * Call during component initialization. Owner destruction detaches observation and
9
+ * settles run promises without cancelling accepted work.
10
+ */
11
+ export function useLatestOperation() {
12
+ const controller = createLatestOperationController();
13
+ let current = $state.raw(controller.current);
14
+ const unsubscribe = controller.subscribe(() => { current = controller.current; });
15
+ // Registered before the first flush, so a destroyed owner never leaks the controller (see useOperation).
16
+ $effect.pre(() => () => { unsubscribe(); controller.dispose(); });
17
+ return {
18
+ run: controller.run,
19
+ 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 outcome() { return current.outcome; },
25
+ get failure() { return current.failure; },
26
+ get error() { return current.error; },
27
+ get cancelled() { return current.cancelled; },
28
+ get cancellationRequested() { return current.cancellationRequested; },
29
+ get cancelling() { return current.cancelling; },
30
+ get cancellation() { return current.cancellation; },
31
+ get cancelError() { return current.cancelError; },
32
+ get blocked() { return current.blocked; },
33
+ };
34
+ }
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "Svelte 5 Application Views helpers for Runic",
5
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.0/packages/web/svelte#readme",
5
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/svelte#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
8
8
  },
@@ -24,12 +24,6 @@
24
24
  "import": "./dist/index.js",
25
25
  "default": "./dist/index.js"
26
26
  },
27
- "./experimental": {
28
- "types": "./dist/experimental.d.ts",
29
- "svelte": "./dist/experimental.js",
30
- "import": "./dist/experimental.js",
31
- "default": "./dist/experimental.js"
32
- },
33
27
  "./package.json": "./package.json"
34
28
  },
35
29
  "files": [
@@ -41,12 +35,12 @@
41
35
  "clean": "bun -e \"import('node:fs').then(({rmSync}) => rmSync('dist', { recursive: true, force: true }))\"",
42
36
  "build": "bun run --bun clean && svelte-package -i src -o dist",
43
37
  "check": "svelte-check --tsconfig ./tsconfig.json",
44
- "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/lifecycle.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",
45
39
  "pack:check": "bun pm pack --dry-run"
46
40
  },
47
41
  "peerDependencies": {
48
42
  "svelte": ">=5.57.1 <6",
49
- "@runic-artifex/views": "0.9.0"
43
+ "@runic-artifex/views": "0.10.0"
50
44
  },
51
45
  "publishConfig": {
52
46
  "access": "public",
@@ -59,7 +53,7 @@
59
53
  },
60
54
  "packageManager": "bun@1.4.2",
61
55
  "devDependencies": {
62
- "@runic-artifex/views": "0.9.0",
56
+ "@runic-artifex/views": "0.10.0",
63
57
  "@sveltejs/adapter-static": "4.0.0",
64
58
  "@sveltejs/kit": "3.0.0",
65
59
  "@sveltejs/package": "3.0.0",
@@ -70,7 +64,7 @@
70
64
  "svelte-check": "4.7.6",
71
65
  "typescript": "6.0.3",
72
66
  "vitest": "5.0.3",
73
- "vite": "8.3.2"
67
+ "vite": "8.3.4"
74
68
  },
75
- "gitHead": "6793f99c726af8b1d05067108761905aa5e8d0d6"
69
+ "gitHead": "fcc71ba13aa56c8f1a720909c1074825a1f5dd6f"
76
70
  }
@@ -1 +0,0 @@
1
- export { useCollectionViewport, type CollectionViewportHandle } from "./views/use-collection-viewport.svelte.js";
@@ -1,3 +0,0 @@
1
- // `@runic-artifex/svelte/experimental`: helpers whose shape may still change in a minor release
2
- // (docs/experimental.md). Graduation moves an export to `@runic-artifex/svelte`.
3
- export { useCollectionViewport } from "./views/use-collection-viewport.svelte.js";