@runic-artifex/svelte 0.10.0 → 0.12.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
@@ -95,8 +95,18 @@ the reference as its `page` prop:
95
95
 
96
96
  The outlet is generic over the reference union, so the registry must have a
97
97
  component for every kind with a matching `page` prop. A different reference
98
- remounts the component, a kind without a component renders an alert, and the
99
- optional `fallback` snippet renders while `content` is empty.
98
+ remounts the component, a kind without a component renders an English
99
+ `<p role="alert">`, and the optional `fallback` snippet renders while `content` is empty.
100
+
101
+ The optional `missing` snippet replaces that alert, for example with localized
102
+ text. It receives the reference whose kind has no component, and its markup
103
+ (including any `role`) is yours:
104
+
105
+ ```svelte
106
+ <ViewOutlet content={workspace.state?.main} registry={pages}>
107
+ {#snippet missing(page)}<p role="alert">{t("missingView", { kind: page.kind })}</p>{/snippet}
108
+ </ViewOutlet>
109
+ ```
100
110
 
101
111
  ## `useCommand(command)`
102
112
 
@@ -110,6 +120,11 @@ and `navigate.run("showWelcome")`. Called during component initialization, it
110
120
  stops publishing state when the component is destroyed, even before its first
111
121
  effect flush; a run in flight is not cancelled and its promise still settles.
112
122
 
123
+ `pending` covers only this component's run. Whether .NET can run the command is
124
+ the View's state: a command without an argument publishes `can<Name>` (such as
125
+ `state.canSave`), so disable a button while either says no. A command with an
126
+ argument has the `can<Name>(input)` query on the client instead.
127
+
113
128
  For a command that declares a failure (`[RunicFailure]` in .NET), `run` resolves the
114
129
  `BridgeOutcome`, and `failure` holds the declared failure of the latest run, typed
115
130
  from the outcome, while `error` keeps unexpected failures. Starting a run and
@@ -159,7 +174,7 @@ Cancel and other callbacks responsive during observation.
159
174
  ## `useLatestOperation()`
160
175
 
161
176
  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)
177
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#operation-feedback-and-latest-selection)
163
178
  for the component's lifetime. It coalesces the latest intent across delayed receipts
164
179
  and orders the next admission after terminal observation and any application drain
165
180
  barrier:
@@ -190,9 +205,117 @@ establish that replacement boundary and own the old work's drain. Lost terminal
190
205
  observation blocks further Starts instead of retrying blindly, with its reason in
191
206
  `error`; ordinary Cancel does not clear this block. Component destruction settles
192
207
  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)
208
+ [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/tests/fixtures/application/operations-consumer)
194
209
  runs this hook against the packed packages and the desktop transport.
195
210
 
211
+ ## `useBridgeConnection(options?)`
212
+
213
+ Follows the page's connection to its .NET host. It wraps `onBridgeConnection`
214
+ from `@runic-artifex/views` (re-exported here since 0.11, with the
215
+ `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a reactive
216
+ `BridgeConnectionState`: `connecting`, `connected`, `reconnecting` or `lost` (a
217
+ closed set, see
218
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#connection-state)):
219
+
220
+ ```svelte
221
+ <script lang="ts">
222
+ import { useBridgeConnection } from "@runic-artifex/svelte";
223
+
224
+ const connection = useBridgeConnection({ lostAfter: 5_000 });
225
+ </script>
226
+
227
+ {#if connection.state === "lost"}<p role="alert">The application stopped responding.</p>{/if}
228
+ ```
229
+
230
+ Call it during component initialization (or in `$effect.root`). `state` holds
231
+ the current state at once; observing starts with the owner's effects, so a
232
+ server render does not observe, and destroying the owner unsubscribes. An invalid
233
+ `lostAfter` throws a `RangeError`.
234
+
235
+ ## `useMenuBar(options?)`
236
+
237
+ Follows the declared menu bar of a Runic Desktop window that leaves it to the
238
+ page (`DesktopMenuBarPresentation.Page`) while its owner lives. It wraps
239
+ `createMenuBarController` from `@runic-artifex/views` (see
240
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`, where `state` is a
241
+ reactive `MenuBarState` property. The bar is rendered by the menubar component
242
+ of the application's own UI library. Runic ships no menubar component.
243
+
244
+ ```svelte
245
+ <script lang="ts">
246
+ import { useMenuBar } from "@runic-artifex/svelte";
247
+
248
+ let open = $state("");
249
+ const menuBar = useMenuBar({
250
+ onRequest: request => { if (request.kind === "open") open = request.menu.key; else focusFirstTrigger(); },
251
+ });
252
+ </script>
253
+
254
+ <!-- On macOS the application menu bar keeps the menus ("global"): render nothing. -->
255
+ {#if menuBar.state.placement === "page"}<!-- the menubar component; an item's select handler calls menuBar.invoke(item) -->{/if}
256
+ ```
257
+
258
+ Options are those of `createMenuBarController` (`shortcuts`, `keyboard`)
259
+ without `signal`, plus `onRequest`, which receives the `focus` and `open`
260
+ requests. Call it during component initialization (or in `$effect.root`). The
261
+ controller starts with the owner's effects, so server rendering creates none
262
+ and `state` stays `connecting`; `invoke` rejects with a `BridgeError`
263
+ (`disconnected`) until then. Owner destruction disposes it, which also returns
264
+ the `shortcuts: "app"` lease.
265
+
266
+ ### With Bits UI
267
+
268
+ Bits UI's `Menubar.Root bind:value`; the
269
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
270
+ items and is tested with real keys:
271
+
272
+ ```svelte
273
+ <script lang="ts">
274
+ import { Menubar } from "bits-ui";
275
+ import { splitAccessKey, type MenuBarItem, type MenuBarMenu } from "@runic-artifex/views";
276
+ import { useMenuBar } from "@runic-artifex/svelte";
277
+
278
+ let bar = $state<HTMLElement | null>(null);
279
+ let open = $state("");
280
+ const menuBar = useMenuBar({
281
+ onRequest: request => {
282
+ if (request.kind === "open") open = request.menu.key;
283
+ else bar?.querySelector<HTMLElement>("[role=menuitem]")?.focus();
284
+ },
285
+ });
286
+ </script>
287
+
288
+ {#snippet label(entry: MenuBarMenu | MenuBarItem)}
289
+ {@const [before, key, after] = splitAccessKey(entry)}
290
+ {before}{#if menuBar.state.accessKeyHints}<u>{key}</u>{:else}{key}{/if}{after}
291
+ {/snippet}
292
+
293
+ {#if menuBar.state.placement === "page"}
294
+ <Menubar.Root aria-label="Application" bind:ref={bar} bind:value={open}>
295
+ {#each menuBar.state.menus as menu (menu.key)}
296
+ <Menubar.Menu value={menu.key}>
297
+ <Menubar.Trigger disabled={!menu.enabled}>{@render label(menu)}</Menubar.Trigger>
298
+ <Menubar.Portal>
299
+ <Menubar.Content align="start">
300
+ {#each menu.entries as entry (entry.key)}
301
+ {#if entry.kind === "separator"}<Menubar.Separator />
302
+ {:else if entry.kind === "item"}
303
+ <Menubar.Item disabled={!entry.enabled} aria-keyshortcuts={entry.ariaKeyShortcuts} onSelect={() => menuBar.invoke(entry)}>
304
+ {@render label(entry)} <kbd aria-hidden="true">{entry.shortcutText}</kbd>
305
+ </Menubar.Item>
306
+ {/if}<!-- a submenu: Menubar.Sub; check and radio items: Menubar.CheckboxItem, Menubar.RadioGroup -->
307
+ {/each}
308
+ </Menubar.Content>
309
+ </Menubar.Portal>
310
+ </Menubar.Menu>
311
+ {/each}
312
+ </Menubar.Root>
313
+ {/if}
314
+ ```
315
+
316
+ The host owns `checked`: bind it one way, as
317
+ `bind:checked={() => item.checked ?? false, () => {}}`.
318
+
196
319
  ## Errors
197
320
 
198
321
  The `error` of `useView` and of a command or operation helper is typed
@@ -207,7 +330,7 @@ const offline = view.error instanceof BridgeError && view.error.kind === "discon
207
330
  ```
208
331
 
209
332
  `instanceof` holds for errors from every copy of the package on the page.
210
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#errors-and-diagnostics)
333
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#errors-and-diagnostics)
211
334
  lists the kinds. Any other value, such as an exception that your own connect
212
335
  function or command callback throws, arrives unchanged.
213
336
 
@@ -246,15 +369,15 @@ application's own dialog.
246
369
  departure before that is answered by the ViewModel's .NET fallback handler, or
247
370
  fails closed without one.
248
371
 
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)
372
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.12.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
250
373
  has the .NET side and which View answers which departure. In a frontend test,
251
374
  the generated mock's `interactions.<name>.request(input)` resolves with the
252
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#testing).
375
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#testing).
253
376
 
254
377
  ## `useCollectionViewport(options)`
255
378
 
256
379
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
257
- `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#collectionviewportoptions)
380
+ `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#collectionviewportoptions)
258
381
  range; `attach` is an attachment for the container. Call it during component
259
382
  initialization and send the range to the ViewModel from an effect:
260
383
 
@@ -3,17 +3,24 @@
3
3
  import type { PageReference } from "@runic-artifex/views";
4
4
  import type { ViewRegistry } from "./view-registry.js";
5
5
 
6
- let { content, registry, fallback }: {
6
+ let { content, registry, fallback, missing }: {
7
7
  content: R | null | undefined;
8
8
  registry: ViewRegistry<R>;
9
9
  /** Rendered while there is no content. */
10
10
  fallback?: Snippet;
11
+ /**
12
+ * Renders a reference whose kind has no registered component, for example localized text.
13
+ * Defaults to an English `<p role="alert">`.
14
+ */
15
+ missing?: Snippet<[R]>;
11
16
  } = $props();
12
17
  let Resolved = $derived(content ? registry[content.kind as R["kind"]] as Component<{ page: R }> | undefined : undefined);
13
18
  </script>
14
19
 
15
20
  {#if content && Resolved}
16
21
  {#key content}<Resolved page={content} />{/key}
22
+ {:else if content && missing}
23
+ {@render missing(content)}
17
24
  {:else if content}
18
25
  <p role="alert">No web component is registered for {content.kind}.</p>
19
26
  {:else}
@@ -7,6 +7,11 @@ declare function $$render<R extends PageReference>(): {
7
7
  registry: ViewRegistry<R>;
8
8
  /** Rendered while there is no content. */
9
9
  fallback?: Snippet;
10
+ /**
11
+ * Renders a reference whose kind has no registered component, for example localized text.
12
+ * Defaults to an English `<p role="alert">`.
13
+ */
14
+ missing?: Snippet<[R]>;
10
15
  };
11
16
  exports: {};
12
17
  bindings: "";
@@ -5,3 +5,7 @@ export { useCommand, type CommandHandle } from "./use-command.svelte.js";
5
5
  export { useOperation, type OperationHandle } from "./use-operation.svelte.js";
6
6
  export { useLatestOperation, type LatestOperationHandle } from "./use-latest-operation.svelte.js";
7
7
  export { useCollectionViewport, type CollectionViewportHandle } from "./use-collection-viewport.svelte.js";
8
+ export { useBridgeConnection, type BridgeConnectionHandle } from "./use-bridge-connection.svelte.js";
9
+ export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
10
+ export { useMenuBar, type MenuBarHandle, type UseMenuBarOptions } from "./use-menu-bar.svelte.js";
11
+ export type { MenuBarEntry, MenuBarInvokeResult, MenuBarItem, MenuBarMenu, MenuBarRequest, MenuBarSeparator, MenuBarState, } from "@runic-artifex/views";
@@ -4,3 +4,6 @@ export { useCommand } from "./use-command.svelte.js";
4
4
  export { useOperation } from "./use-operation.svelte.js";
5
5
  export { useLatestOperation } from "./use-latest-operation.svelte.js";
6
6
  export { useCollectionViewport } from "./use-collection-viewport.svelte.js";
7
+ export { useBridgeConnection } from "./use-bridge-connection.svelte.js";
8
+ export { onBridgeConnection } from "@runic-artifex/views";
9
+ export { useMenuBar } from "./use-menu-bar.svelte.js";
@@ -0,0 +1,17 @@
1
+ import { type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
2
+ export interface BridgeConnectionHandle {
3
+ /** The connection to the .NET host, as `onBridgeConnection` reports it. A reactive property. */
4
+ readonly state: BridgeConnectionState;
5
+ }
6
+ /**
7
+ * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting` or
8
+ * `lost`) through `onBridgeConnection` while its owner lives. `state` holds the current state at
9
+ * once; the subscription starts with the owner's effects, so server rendering never observes.
10
+ * Call during component initialization (or in `$effect.root`); owner destruction unsubscribes.
11
+ *
12
+ * ```svelte
13
+ * const connection = useBridgeConnection();
14
+ * {#if connection.state === "lost"}<p role="alert">The application stopped responding.</p>{/if}
15
+ * ```
16
+ */
17
+ export declare function useBridgeConnection(options?: BridgeConnectionOptions): BridgeConnectionHandle;
@@ -0,0 +1,20 @@
1
+ import { onBridgeConnection } from "@runic-artifex/views";
2
+ /**
3
+ * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting` or
4
+ * `lost`) through `onBridgeConnection` while its owner lives. `state` holds the current state at
5
+ * once; the subscription starts with the owner's effects, so server rendering never observes.
6
+ * Call during component initialization (or in `$effect.root`); owner destruction unsubscribes.
7
+ *
8
+ * ```svelte
9
+ * const connection = useBridgeConnection();
10
+ * {#if connection.state === "lost"}<p role="alert">The application stopped responding.</p>{/if}
11
+ * ```
12
+ */
13
+ export function useBridgeConnection(options = {}) {
14
+ // The subscription reports the current state at once; reading it validates `lostAfter` too.
15
+ let initial = "connecting";
16
+ onBridgeConnection(next => { initial = next; }, options)();
17
+ let state = $state(initial);
18
+ $effect.pre(() => onBridgeConnection(next => { state = next; }, options));
19
+ return { get state() { return state; } };
20
+ }
@@ -0,0 +1,29 @@
1
+ import { type MenuBarController, type MenuBarControllerOptions, type MenuBarRequest, type MenuBarState } from "@runic-artifex/views";
2
+ export interface UseMenuBarOptions extends Omit<MenuBarControllerOptions, "signal"> {
3
+ /**
4
+ * Receives the `focus` (Alt tap, F10) and `open` (Alt plus a menu's access key) requests: focus the first trigger
5
+ * or set the menubar component's open menu.
6
+ */
7
+ readonly onRequest?: (request: MenuBarRequest) => void;
8
+ }
9
+ export interface MenuBarHandle {
10
+ /** The menu bar as the page renders it; render a bar only when `placement` is `"page"`. A reactive property. */
11
+ readonly state: MenuBarState;
12
+ /** Runs an item through the native bar's command path. Rejects with a BridgeError before the owner's effects ran. */
13
+ readonly invoke: MenuBarController["invoke"];
14
+ /** Matches a `keydown` event against the items' shortcuts, for the `shortcuts: "app"` option. */
15
+ readonly handleKeyDown: MenuBarController["handleKeyDown"];
16
+ }
17
+ /**
18
+ * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) while its owner lives,
19
+ * as headless state for the application's own menubar component, through `createMenuBarController`. The controller
20
+ * starts with the owner's effects, so server rendering never creates one and `state` stays `connecting`. Call during
21
+ * component initialization (or in `$effect.root`); owner destruction disposes the controller.
22
+ *
23
+ * ```svelte
24
+ * let open = $state("");
25
+ * const menuBar = useMenuBar({ onRequest: request => { if (request.kind === "open") open = request.menu.key; } });
26
+ * {#if menuBar.state.placement === "page"}<Menubar.Root bind:value={open}>…{/if}
27
+ * ```
28
+ */
29
+ export declare function useMenuBar(options?: UseMenuBarOptions): MenuBarHandle;
@@ -0,0 +1,42 @@
1
+ import { untrack } from "svelte";
2
+ import { BridgeError, createMenuBarController, } from "@runic-artifex/views";
3
+ /**
4
+ * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) while its owner lives,
5
+ * as headless state for the application's own menubar component, through `createMenuBarController`. The controller
6
+ * starts with the owner's effects, so server rendering never creates one and `state` stays `connecting`. Call during
7
+ * component initialization (or in `$effect.root`); owner destruction disposes the controller.
8
+ *
9
+ * ```svelte
10
+ * let open = $state("");
11
+ * const menuBar = useMenuBar({ onRequest: request => { if (request.kind === "open") open = request.menu.key; } });
12
+ * {#if menuBar.state.placement === "page"}<Menubar.Root bind:value={open}>…{/if}
13
+ * ```
14
+ */
15
+ export function useMenuBar(options = {}) {
16
+ const { onRequest, ...controllerOptions } = options;
17
+ let state = $state.raw(Object.freeze({
18
+ status: "connecting", placement: "none", shortcuts: controllerOptions.shortcuts === "app" ? "app" : "host",
19
+ accessKeyHints: false, revision: 0, menus: Object.freeze([]),
20
+ }));
21
+ let controller;
22
+ $effect.pre(() => untrack(() => {
23
+ const created = createMenuBarController(controllerOptions);
24
+ controller = created;
25
+ state = created.current;
26
+ created.subscribe(() => { state = created.current; });
27
+ if (onRequest)
28
+ created.onRequest(onRequest);
29
+ return () => {
30
+ if (controller === created)
31
+ controller = undefined;
32
+ created.dispose();
33
+ };
34
+ }));
35
+ return {
36
+ get state() { return state; },
37
+ invoke: item => controller
38
+ ? controller.invoke(item)
39
+ : Promise.reject(new BridgeError("disconnected", "The menu bar is not connected yet.", { route: "__runicMenuBarInvoke" })),
40
+ handleKeyDown: event => controller?.handleKeyDown(event) ?? false,
41
+ };
42
+ }
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.10.0",
3
+ "version": "0.12.0",
4
4
  "description": "Svelte 5 Application Views helpers for Runic",
5
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/svelte#readme",
5
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/svelte#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
8
8
  },
@@ -35,12 +35,12 @@
35
35
  "clean": "bun -e \"import('node:fs').then(({rmSync}) => rmSync('dist', { recursive: true, force: true }))\"",
36
36
  "build": "bun run --bun clean && svelte-package -i src -o dist",
37
37
  "check": "svelte-check --tsconfig ./tsconfig.json",
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",
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 test/use-bridge-connection.svelte.test.ts test/use-menu-bar.svelte.test.ts",
39
39
  "pack:check": "bun pm pack --dry-run"
40
40
  },
41
41
  "peerDependencies": {
42
42
  "svelte": ">=5.57.1 <6",
43
- "@runic-artifex/views": "0.10.0"
43
+ "@runic-artifex/views": "0.12.0"
44
44
  },
45
45
  "publishConfig": {
46
46
  "access": "public",
@@ -53,18 +53,18 @@
53
53
  },
54
54
  "packageManager": "bun@1.4.2",
55
55
  "devDependencies": {
56
- "@runic-artifex/views": "0.10.0",
56
+ "@runic-artifex/views": "0.12.0",
57
57
  "@sveltejs/adapter-static": "4.0.0",
58
58
  "@sveltejs/kit": "3.0.0",
59
59
  "@sveltejs/package": "3.0.0",
60
60
  "@sveltejs/vite-plugin-svelte": "7.3.1",
61
61
  "@types/node": "24.19.1",
62
- "happy-dom": "^20.14.5",
62
+ "happy-dom": "^21.0.4",
63
63
  "svelte": "5.57.1",
64
64
  "svelte-check": "4.7.6",
65
65
  "typescript": "6.0.3",
66
66
  "vitest": "5.0.3",
67
67
  "vite": "8.3.4"
68
68
  },
69
- "gitHead": "fcc71ba13aa56c8f1a720909c1074825a1f5dd6f"
69
+ "gitHead": "cb95ea2838ba61c7a24b9cda05bf5f0bd6fcc2d7"
70
70
  }