@runic-artifex/svelte 0.10.0 → 0.11.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
 
@@ -159,7 +169,7 @@ Cancel and other callbacks responsive during observation.
159
169
  ## `useLatestOperation()`
160
170
 
161
171
  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)
172
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#operation-feedback-and-latest-selection)
163
173
  for the component's lifetime. It coalesces the latest intent across delayed receipts
164
174
  and orders the next admission after terminal observation and any application drain
165
175
  barrier:
@@ -190,9 +200,117 @@ establish that replacement boundary and own the old work's drain. Lost terminal
190
200
  observation blocks further Starts instead of retrying blindly, with its reason in
191
201
  `error`; ordinary Cancel does not clear this block. Component destruction settles
192
202
  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)
203
+ [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/tests/fixtures/application/operations-consumer)
194
204
  runs this hook against the packed packages and the desktop transport.
195
205
 
206
+ ## `useBridgeConnection(options?)`
207
+
208
+ Follows the page's connection to its .NET host. It wraps `onBridgeConnection`
209
+ from `@runic-artifex/views` (re-exported here since 0.11, with the
210
+ `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a reactive
211
+ `BridgeConnectionState`: `connecting`, `connected`, `reconnecting` or `lost` (a
212
+ closed set, see
213
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#connection-state)):
214
+
215
+ ```svelte
216
+ <script lang="ts">
217
+ import { useBridgeConnection } from "@runic-artifex/svelte";
218
+
219
+ const connection = useBridgeConnection({ lostAfter: 5_000 });
220
+ </script>
221
+
222
+ {#if connection.state === "lost"}<p role="alert">The application stopped responding.</p>{/if}
223
+ ```
224
+
225
+ Call it during component initialization (or in `$effect.root`). `state` holds
226
+ the current state at once; observing starts with the owner's effects, so a
227
+ server render does not observe, and destroying the owner unsubscribes. An invalid
228
+ `lostAfter` throws a `RangeError`.
229
+
230
+ ## `useMenuBar(options?)`
231
+
232
+ Follows the declared menu bar of a Runic Desktop window that leaves it to the
233
+ page (`DesktopMenuBarPresentation.Page`) while its owner lives. It wraps
234
+ `createMenuBarController` from `@runic-artifex/views` (see
235
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`, where `state` is a
236
+ reactive `MenuBarState` property. The bar is rendered by the menubar component
237
+ of the application's own UI library. Runic ships no menubar component.
238
+
239
+ ```svelte
240
+ <script lang="ts">
241
+ import { useMenuBar } from "@runic-artifex/svelte";
242
+
243
+ let open = $state("");
244
+ const menuBar = useMenuBar({
245
+ onRequest: request => { if (request.kind === "open") open = request.menu.key; else focusFirstTrigger(); },
246
+ });
247
+ </script>
248
+
249
+ <!-- On macOS the application menu bar keeps the menus ("global"): render nothing. -->
250
+ {#if menuBar.state.placement === "page"}<!-- the menubar component; an item's select handler calls menuBar.invoke(item) -->{/if}
251
+ ```
252
+
253
+ Options are those of `createMenuBarController` (`shortcuts`, `keyboard`)
254
+ without `signal`, plus `onRequest`, which receives the `focus` and `open`
255
+ requests. Call it during component initialization (or in `$effect.root`). The
256
+ controller starts with the owner's effects, so server rendering creates none
257
+ and `state` stays `connecting`; `invoke` rejects with a `BridgeError`
258
+ (`disconnected`) until then. Owner destruction disposes it, which also returns
259
+ the `shortcuts: "app"` lease.
260
+
261
+ ### With Bits UI
262
+
263
+ Bits UI's `Menubar.Root bind:value`; the
264
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
265
+ items and is tested with real keys:
266
+
267
+ ```svelte
268
+ <script lang="ts">
269
+ import { Menubar } from "bits-ui";
270
+ import { splitAccessKey, type MenuBarItem, type MenuBarMenu } from "@runic-artifex/views";
271
+ import { useMenuBar } from "@runic-artifex/svelte";
272
+
273
+ let bar = $state<HTMLElement | null>(null);
274
+ let open = $state("");
275
+ const menuBar = useMenuBar({
276
+ onRequest: request => {
277
+ if (request.kind === "open") open = request.menu.key;
278
+ else bar?.querySelector<HTMLElement>("[role=menuitem]")?.focus();
279
+ },
280
+ });
281
+ </script>
282
+
283
+ {#snippet label(entry: MenuBarMenu | MenuBarItem)}
284
+ {@const [before, key, after] = splitAccessKey(entry)}
285
+ {before}{#if menuBar.state.accessKeyHints}<u>{key}</u>{:else}{key}{/if}{after}
286
+ {/snippet}
287
+
288
+ {#if menuBar.state.placement === "page"}
289
+ <Menubar.Root aria-label="Application" bind:ref={bar} bind:value={open}>
290
+ {#each menuBar.state.menus as menu (menu.key)}
291
+ <Menubar.Menu value={menu.key}>
292
+ <Menubar.Trigger disabled={!menu.enabled}>{@render label(menu)}</Menubar.Trigger>
293
+ <Menubar.Portal>
294
+ <Menubar.Content align="start">
295
+ {#each menu.entries as entry (entry.key)}
296
+ {#if entry.kind === "separator"}<Menubar.Separator />
297
+ {:else if entry.kind === "item"}
298
+ <Menubar.Item disabled={!entry.enabled} aria-keyshortcuts={entry.ariaKeyShortcuts} onSelect={() => menuBar.invoke(entry)}>
299
+ {@render label(entry)} <kbd aria-hidden="true">{entry.shortcutText}</kbd>
300
+ </Menubar.Item>
301
+ {/if}<!-- a submenu: Menubar.Sub; check and radio items: Menubar.CheckboxItem, Menubar.RadioGroup -->
302
+ {/each}
303
+ </Menubar.Content>
304
+ </Menubar.Portal>
305
+ </Menubar.Menu>
306
+ {/each}
307
+ </Menubar.Root>
308
+ {/if}
309
+ ```
310
+
311
+ The host owns `checked`: bind it one way, as
312
+ `bind:checked={() => item.checked ?? false, () => {}}`.
313
+
196
314
  ## Errors
197
315
 
198
316
  The `error` of `useView` and of a command or operation helper is typed
@@ -207,7 +325,7 @@ const offline = view.error instanceof BridgeError && view.error.kind === "discon
207
325
  ```
208
326
 
209
327
  `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)
328
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#errors-and-diagnostics)
211
329
  lists the kinds. Any other value, such as an exception that your own connect
212
330
  function or command callback throws, arrives unchanged.
213
331
 
@@ -246,15 +364,15 @@ application's own dialog.
246
364
  departure before that is answered by the ViewModel's .NET fallback handler, or
247
365
  fails closed without one.
248
366
 
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)
367
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.11.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
250
368
  has the .NET side and which View answers which departure. In a frontend test,
251
369
  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).
370
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#testing).
253
371
 
254
372
  ## `useCollectionViewport(options)`
255
373
 
256
374
  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)
375
+ `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#collectionviewportoptions)
258
376
  range; `attach` is an attachment for the container. Call it during component
259
377
  initialization and send the range to the ViewModel from an effect:
260
378
 
@@ -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.11.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.11.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.11.0"
44
44
  },
45
45
  "publishConfig": {
46
46
  "access": "public",
@@ -53,7 +53,7 @@
53
53
  },
54
54
  "packageManager": "bun@1.4.2",
55
55
  "devDependencies": {
56
- "@runic-artifex/views": "0.10.0",
56
+ "@runic-artifex/views": "0.11.0",
57
57
  "@sveltejs/adapter-static": "4.0.0",
58
58
  "@sveltejs/kit": "3.0.0",
59
59
  "@sveltejs/package": "3.0.0",
@@ -66,5 +66,5 @@
66
66
  "vitest": "5.0.3",
67
67
  "vite": "8.3.4"
68
68
  },
69
- "gitHead": "fcc71ba13aa56c8f1a720909c1074825a1f5dd6f"
69
+ "gitHead": "318762a9d5dcdd74303ca30b095fed355a1ab21f"
70
70
  }