@runic-artifex/svelte 0.17.0 → 0.18.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
@@ -86,7 +86,7 @@ the failure. Await it with `{#await}`:
86
86
  The source is read once: wrap the component in `{#key page}` to follow another
87
87
  reference. Do not `{#await page.connect()}` directly: nothing would dispose
88
88
  that client. In SvelteKit, connect in a `load` function instead
89
- ([`@runic-artifex/sveltekit`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/svelte/../sveltekit/README.md#connecting-in-load)).
89
+ ([`@runic-artifex/sveltekit`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.18.0/packages/web/svelte/../sveltekit/README.md#connecting-in-load)).
90
90
 
91
91
  ### Selecting state: `$derived`
92
92
 
@@ -182,10 +182,10 @@ handle also has `value` and `text`, which `bind:value={title.value}` reads and s
182
182
  `errors` holds the member's validation messages from the descriptor (`[]` when valid), `error` why the latest write
183
183
  or text failed (a `BridgeError` or a `FieldError`, whose `kind` is `rejected`, `conflict`, `committed-with-error` or
184
184
  `invalid-text`). `FieldError`, `FieldOptions`, `FieldState` and `BridgeField` are exported from this package. See the
185
- [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#fields) for the receipts
185
+ [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#fields) for the receipts
186
186
  and text forms. An `invalid-text` error has a `reason` and `arguments`: render `useText(() => name.error).current` after
187
187
  `configureFieldErrorText` to show your own text for it in the window's language
188
- ([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#translating-field-errors)).
188
+ ([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#translating-field-errors)).
189
189
 
190
190
  #### Row cells and nested members
191
191
 
@@ -194,7 +194,7 @@ Since 0.16, `InvoiceFields.address.street` and `InvoiceFields.lines.at(line.id).
194
194
  `useField(() => view, InvoiceFields.lines.at(line.id).quantity)` in the row's component and `{@attach quantity.attach}`
195
195
  its input; `at(key)` returns the same descriptor for the same key. Such a field always writes checked, conflicts only
196
196
  when another writer changed the same cell, and shows the messages .NET reports at the cell's validation path. See
197
- [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/svelte/../views/README.md#fields-below-a-member-and-row-cells).
197
+ [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.18.0/packages/web/svelte/../views/README.md#fields-below-a-member-and-row-cells).
198
198
 
199
199
  ### Forms: `useForm(() => fields, options?)`
200
200
 
@@ -210,7 +210,7 @@ const form = useForm(() => ({ title, step }), { dirty: () => editor.state?.isDir
210
210
 
211
211
  Call during component initialization to bind a text input to a member through the
212
212
  framework-neutral
213
- [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#text-inputs):
213
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#text-inputs):
214
214
 
215
215
  ```svelte
216
216
  <script lang="ts">
@@ -270,7 +270,7 @@ the reference as its `page` prop:
270
270
  The outlet is generic over the reference union, so the registry must have a
271
271
  component for every kind with a matching `page` prop. A component whose `page`
272
272
  is a shared page reference, such as `ResultPagePageReference` of a .NET
273
- [`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/svelte/../../dotnet/Runic.Application.Views/README.md#shared-clients)
273
+ [`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.18.0/packages/web/svelte/../../dotnet/Runic.Application.Views/README.md#shared-clients)
274
274
  interface, registers for each of its kinds:
275
275
  `{ ...registryEntries(resultPageKinds, ResultPage), settings: Settings }`. A different reference
276
276
  remounts the component, and the optional `fallback` snippet renders while
@@ -420,7 +420,7 @@ Cancel and other callbacks responsive during observation.
420
420
  ## `useLatestOperation()`
421
421
 
422
422
  For rapid read selection, `useLatestOperation()` wraps the framework-neutral
423
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#operation-feedback-and-latest-selection)
423
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#operation-feedback-and-latest-selection)
424
424
  for the component's lifetime. It coalesces the latest intent across delayed receipts
425
425
  and orders the next admission after terminal observation and any application drain
426
426
  barrier:
@@ -451,7 +451,7 @@ establish that replacement boundary and own the old work's drain. Lost terminal
451
451
  observation blocks further Starts instead of retrying blindly, with its reason in
452
452
  `error`; ordinary Cancel does not clear this block. Component destruction settles
453
453
  observation without cancelling accepted work. The
454
- [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/tests/fixtures/application/operations-consumer)
454
+ [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/tests/fixtures/application/operations-consumer)
455
455
  runs this hook against the packed packages and the desktop transport.
456
456
 
457
457
  ## `useBridgeConnection(options?)`
@@ -461,7 +461,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
461
461
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a reactive
462
462
  `BridgeConnectionState`: `connecting`, `connected`, `reconnecting`, `lost` or `closed` (the
463
463
  application closed the window, since 0.15; a closed set, see
464
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#connection-state)):
464
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#connection-state)):
465
465
 
466
466
  ```svelte
467
467
  <script lang="ts">
@@ -483,7 +483,7 @@ server render does not observe, and destroying the owner unsubscribes. An invali
483
483
  Follows the declared menu bar of a Runic Desktop window that leaves it to the
484
484
  page (`DesktopMenuBarPresentation.Page`) while its owner lives. It wraps
485
485
  `createMenuBarController` from `@runic-artifex/views` (see
486
- [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`, where `state` is a
486
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`, where `state` is a
487
487
  reactive `MenuBarState` property. The bar is rendered by the menubar component
488
488
  of the application's own UI library. Runic ships no menubar component.
489
489
 
@@ -512,7 +512,7 @@ the `shortcuts: "app"` lease.
512
512
  ### With Bits UI
513
513
 
514
514
  Bits UI's `Menubar.Root bind:value`; the
515
- [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
515
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
516
516
  items and is tested with real keys:
517
517
 
518
518
  ```svelte
@@ -568,7 +568,7 @@ Shows a text reference that a ViewModel produced, such as a status line or a
568
568
  validation error's `text`, in the window's language, and renders again when the
569
569
  language changes. A string shows as it is; `null` and `undefined` show
570
570
  `fallback`. Connect the page's Translations runtime once with
571
- `configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
571
+ `configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.18.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
572
572
  `useWindowLocale()` reads the window's locale.
573
573
 
574
574
  `useTextLocale().current` is the locale that text is shown in, as a reactive
@@ -599,7 +599,7 @@ const status = useText(() => view.state?.status);
599
599
  Follows the page's appearance while its owner lives, as the reactive property
600
600
  `current`: the colour scheme, contrast and reduced motion of the page's engine,
601
601
  combined with the desktop's text scale, accent colour, forced-colours palette,
602
- contrast and motion that a Runic host pushes ([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/views/README.md#appearance)).
602
+ contrast and motion that a Runic host pushes ([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.18.0/packages/web/views/README.md#appearance)).
603
603
  Every member is `null` under server rendering, so a SvelteKit page renders the
604
604
  same on the server and in the browser until the browser's first effect.
605
605
 
@@ -616,7 +616,7 @@ same on the server and in the browser until the browser's first effect.
616
616
  The `error` of `useView` and of a command or operation helper is typed
617
617
  `unknown`: it holds whatever the connection or the call rejected with. A Bridge
618
618
  failure is a `BridgeError` from `@runic-artifex/views`. Show it with
619
- `describeBridgeError(error)`, one English sentence, instead of `String(error)`,
619
+ `describeBridgeError(error)`, one sentence (in the window's language with `configureRunicViewsText()`), instead of `String(error)`,
620
620
  and narrow it with `isBridgeError` (or `instanceof`) before reading `kind`,
621
621
  `route` or `detail`:
622
622
 
@@ -628,7 +628,7 @@ const message = $derived(describeBridgeError(view.error));
628
628
  ```
629
629
 
630
630
  `instanceof` holds for errors from every copy of the package on the page.
631
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#errors-and-diagnostics)
631
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#errors-and-diagnostics)
632
632
  lists the kinds. Any other value, such as an exception that your own connect
633
633
  function or command callback throws, arrives unchanged.
634
634
 
@@ -667,10 +667,10 @@ application's own dialog.
667
667
  departure before that is answered by the ViewModel's .NET fallback handler, or
668
668
  fails closed without one.
669
669
 
670
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
670
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.18.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
671
671
  has the .NET side and which View answers which departure. In a frontend test,
672
672
  the generated mock's `interactions.<name>.request(input)` resolves with the
673
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#testing).
673
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#testing).
674
674
 
675
675
  ## View requests
676
676
 
@@ -702,14 +702,14 @@ the page painted the state the request was raised with, so the field of that
702
702
  state is rendered; `signal` aborts when the handler is replaced or removed, the
703
703
  client is disposed or the connection is lost. A request is never replayed: one
704
704
  raised before the effect ran, or while the page is disconnected, is not
705
- delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#view-requests) for the rules, and in a frontend
705
+ delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#view-requests) for the rules, and in a frontend
706
706
  test raise one with the generated mock's `requests.<name>.raise(input)` (the
707
- [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#testing)).
707
+ [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#testing)).
708
708
 
709
709
  ## `useCollectionViewport(options)`
710
710
 
711
711
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
712
- `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#collectionviewportoptions)
712
+ `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#collectionviewportoptions)
713
713
  range; `attach` is an attachment for the container. Call it during component
714
714
  initialization and send the range to the ViewModel from an effect:
715
715
 
@@ -734,7 +734,7 @@ Import them from there instead of `@runic-artifex/svelte`.
734
734
 
735
735
  ## `useQueryCollection(collection, options)`
736
736
 
737
- Follows a scroll container for a [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it
737
+ Follows a scroll container for a [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it
738
738
  loads the rows the container shows, with placeholders until they arrive, and lays them out with variable heights. Pass
739
739
  getters of the collection and the options. `viewport` is the `QueryViewport` (`items` with `top` and `size`,
740
740
  `totalSize`, `total`, `query`, `loading`, `error`); attach `attach` to the container and `measure(index)` to each row.
@@ -760,4 +760,19 @@ The package re-exports `installBackNavigation`, `installNavigationPath`,
760
760
  `@runic-artifex/views` (since 0.16). Call the installs once where the page
761
761
  starts, before or after mounting: the mouse's Back button and Alt+Left then go
762
762
  back in the .NET window, and `#/customers/42` follows its path region. See
763
- [Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/views/README.md#back-and-the-url).
763
+ [Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.18.0/packages/web/views/README.md#back-and-the-url).
764
+
765
+ ## Hosted regions (experimental)
766
+
767
+ `RunicHostedRegion` from `@runic-artifex/svelte/experimental` renders
768
+ `<runic-hosted-region>`, a region where the host application shows a hosted guest's
769
+ Window ([hosted regions](https://github.com/Runic-Artifex/runic-sdk/blob/v0.18.0/packages/web/svelte/../views/README.md#hosted-regions-experimental)). Its `fallback` snippet takes the region's state and
770
+ shows while no guest page shows in it:
771
+
772
+ ```svelte
773
+ <RunicHostedRegion name="check" style="height: 420px" onstatechange={onState}>
774
+ {#snippet fallback(state)}
775
+ {#if state === "ended"}<RunAgain />{:else}<p>Starting the check…</p>{/if}
776
+ {/snippet}
777
+ </RunicHostedRegion>
778
+ ```
@@ -0,0 +1,2 @@
1
+ export { default as RunicHostedRegion } from "./views/RunicHostedRegion.svelte";
2
+ export type { HostedRegionSizing, HostedRegionState, RunicHostedRegionElement } from "@runic-artifex/views/experimental";
@@ -0,0 +1,3 @@
1
+ // The experimental entry (docs/experimental.md, "npm packages"): importing it is the opt-in. Hosted regions (0.18): the
2
+ // .NET side is the experimental family RUNICDESK103.
3
+ export { default as RunicHostedRegion } from "./views/RunicHostedRegion.svelte";
@@ -0,0 +1,38 @@
1
+ <script lang="ts">
2
+ // Hosted regions (experimental, 0.18): a region where the host application shows a hosted guest's Window.
3
+ import type { Snippet } from "svelte";
4
+ import type { HTMLAttributes } from "svelte/elements";
5
+ import {
6
+ defineHostedRegion,
7
+ type HostedRegionSizing,
8
+ type HostedRegionState,
9
+ type HostedRegionStateChangeDetail,
10
+ type HostedRegionTitleChangeDetail,
11
+ } from "@runic-artifex/views/experimental";
12
+
13
+ let { name, sizing, label, fallback, onstatechange, ontitlechange, ...attributes }: Omit<HTMLAttributes<HTMLElement>, "title" | "children"> & {
14
+ /** The region's name, which the host application's policy embeds a guest's Window in. */
15
+ name: string;
16
+ /** `fill` (the default): the page's layout sets the height. `content-height`: the guest's page does. */
17
+ sizing?: HostedRegionSizing;
18
+ /** The region's accessible name; without it, the guest page's title. */
19
+ label?: string;
20
+ /** Rendered while no guest page shows in the region, with the region's state. */
21
+ fallback?: Snippet<[HostedRegionState]>;
22
+ onstatechange?: (state: HostedRegionState, previous: HostedRegionState) => void;
23
+ /** The guest page's title as the host passed it on, or `null`. */
24
+ ontitlechange?: (title: string | null) => void;
25
+ } = $props();
26
+
27
+ defineHostedRegion();
28
+ let state = $state<HostedRegionState>("waiting");
29
+ const stateChanged = (event: CustomEvent<HostedRegionStateChangeDetail>) => {
30
+ state = event.detail.state;
31
+ onstatechange?.(event.detail.state, event.detail.previous);
32
+ };
33
+ const titleChanged = (event: CustomEvent<HostedRegionTitleChangeDetail>) => ontitlechange?.(event.detail.title);
34
+ </script>
35
+
36
+ <runic-hosted-region {...attributes} {name} {sizing} {label} onrunicregionstatechange={stateChanged} onrunicregiontitlechange={titleChanged}>
37
+ {#if fallback}<div slot="fallback" style="display: contents">{@render fallback(state)}</div>{/if}
38
+ </runic-hosted-region>
@@ -0,0 +1,19 @@
1
+ import type { Snippet } from "svelte";
2
+ import type { HTMLAttributes } from "svelte/elements";
3
+ import { type HostedRegionSizing, type HostedRegionState } from "@runic-artifex/views/experimental";
4
+ type $$ComponentProps = Omit<HTMLAttributes<HTMLElement>, "title" | "children"> & {
5
+ /** The region's name, which the host application's policy embeds a guest's Window in. */
6
+ name: string;
7
+ /** `fill` (the default): the page's layout sets the height. `content-height`: the guest's page does. */
8
+ sizing?: HostedRegionSizing;
9
+ /** The region's accessible name; without it, the guest page's title. */
10
+ label?: string;
11
+ /** Rendered while no guest page shows in the region, with the region's state. */
12
+ fallback?: Snippet<[HostedRegionState]>;
13
+ onstatechange?: (state: HostedRegionState, previous: HostedRegionState) => void;
14
+ /** The guest page's title as the host passed it on, or `null`. */
15
+ ontitlechange?: (title: string | null) => void;
16
+ };
17
+ declare const RunicHostedRegion: import("svelte").Component<$$ComponentProps, {}, "">;
18
+ type RunicHostedRegion = ReturnType<typeof RunicHostedRegion>;
19
+ export default RunicHostedRegion;
@@ -3,6 +3,7 @@
3
3
  import type { PageReference } from "@runic-artifex/views";
4
4
  import { missingViewMessage, reportMissingView } from "@runic-artifex/views/bindings";
5
5
  import { isDevelopment } from "./development.js";
6
+ import { getRunicInstance } from "./instance.js";
6
7
  import type { ViewRegistry } from "./view-registry.js";
7
8
 
8
9
  let { content, registry, fallback, missing }: {
@@ -19,8 +20,11 @@
19
20
  } = $props();
20
21
  let Resolved = $derived(content ? registry[content.kind as R["kind"]] as Component<{ page: R }> | undefined : undefined);
21
22
  const development = isDevelopment();
23
+ // A missing kind is reported to the component's Runic instance.
24
+ const instance = getRunicInstance();
22
25
  $effect.pre(() => {
23
- if (content && !Resolved && !missing && !development) reportMissingView(content.kind);
26
+ const kind = content && !Resolved && !missing && !development ? content.kind : undefined;
27
+ if (kind !== undefined) instance.run(() => reportMissingView(kind));
24
28
  });
25
29
  </script>
26
30
 
@@ -17,6 +17,8 @@ export { useBridgeConnection, type BridgeConnectionHandle } from "./use-bridge-c
17
17
  export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
18
18
  export { useText, useTextLocale, useWindowLocale, type TextHandle, type TextLocaleHandle, type WindowLocaleHandle, } from "./use-text.svelte.js";
19
19
  export { useAppearance, type AppearanceHandle } from "./use-appearance.svelte.js";
20
+ export { getRunicInstance, setRunicInstance } from "./instance.js";
21
+ export { createRunicInstance, pageInstance, type RunicInstance, type RunicInstanceOptions } from "@runic-artifex/views";
20
22
  export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, type DocumentLocaleOptions, type FieldErrorArguments, type FieldErrorReason, type FieldErrorText, type TextReference, type TextTranslations, } from "@runic-artifex/views";
21
23
  export { appearance, onAppearance, type Appearance, type AppearanceColorScheme, type AppearanceContrast, type AppearanceSystemColors, type HostAppearance, } from "@runic-artifex/views";
22
24
  export { upload, type BlobRef, type RunicBlob, type UploadOptions, type UploadProgress } from "@runic-artifex/views";
@@ -15,6 +15,8 @@ export { useBridgeConnection } from "./use-bridge-connection.svelte.js";
15
15
  export { onBridgeConnection } from "@runic-artifex/views";
16
16
  export { useText, useTextLocale, useWindowLocale, } from "./use-text.svelte.js";
17
17
  export { useAppearance } from "./use-appearance.svelte.js";
18
+ export { getRunicInstance, setRunicInstance } from "./instance.js";
19
+ export { createRunicInstance, pageInstance } from "@runic-artifex/views";
18
20
  export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, } from "@runic-artifex/views";
19
21
  export { appearance, onAppearance, } from "@runic-artifex/views";
20
22
  // blobs/1: uploads from the page and the blob values of state.
@@ -0,0 +1,22 @@
1
+ import { type RunicInstance } from "@runic-artifex/views";
2
+ /**
3
+ * Makes `instance` the Runic instance of the calling component and its children: `useView`, `useField`, `useText`,
4
+ * `useBridgeConnection`, `useAppearance`, `ViewOutlet` and the other helpers below it connect and read through it
5
+ * instead of the page instance. Call it during component initialization, before those helpers. A guest that renders
6
+ * inside another page, such as an embedded component, calls it in its root component.
7
+ *
8
+ * ```svelte
9
+ * <script lang="ts">
10
+ * let { bridge } = $props();
11
+ * const instance = setRunicInstance(createRunicInstance({ bridge }));
12
+ * onDestroy(() => instance.dispose());
13
+ * </script>
14
+ * ```
15
+ */
16
+ export declare function setRunicInstance(instance: RunicInstance): RunicInstance;
17
+ /**
18
+ * The Runic instance of the calling component: the one the nearest `setRunicInstance` set, or the default instance
19
+ * (`defaultInstance()`: the page instance, or in a component bundle its element's). Outside component initialization,
20
+ * where Svelte has no context, it is the default instance.
21
+ */
22
+ export declare function getRunicInstance(): RunicInstance;
@@ -0,0 +1,38 @@
1
+ import { getContext, setContext } from "svelte";
2
+ import { defaultInstance } from "@runic-artifex/views";
3
+ // The Runic instance of a component subtree (`createRunicInstance` in @runic-artifex/views). Without one set it is the
4
+ // default instance: the page instance, on `globalThis.__runicBridge`, as before instances existed, or in a component
5
+ // bundle its element's.
6
+ const instanceKey = Symbol("runic.svelte.instance");
7
+ /**
8
+ * Makes `instance` the Runic instance of the calling component and its children: `useView`, `useField`, `useText`,
9
+ * `useBridgeConnection`, `useAppearance`, `ViewOutlet` and the other helpers below it connect and read through it
10
+ * instead of the page instance. Call it during component initialization, before those helpers. A guest that renders
11
+ * inside another page, such as an embedded component, calls it in its root component.
12
+ *
13
+ * ```svelte
14
+ * <script lang="ts">
15
+ * let { bridge } = $props();
16
+ * const instance = setRunicInstance(createRunicInstance({ bridge }));
17
+ * onDestroy(() => instance.dispose());
18
+ * </script>
19
+ * ```
20
+ */
21
+ export function setRunicInstance(instance) {
22
+ return setContext(instanceKey, instance);
23
+ }
24
+ /**
25
+ * The Runic instance of the calling component: the one the nearest `setRunicInstance` set, or the default instance
26
+ * (`defaultInstance()`: the page instance, or in a component bundle its element's). Outside component initialization,
27
+ * where Svelte has no context, it is the default instance.
28
+ */
29
+ export function getRunicInstance() {
30
+ let instance;
31
+ try {
32
+ instance = getContext(instanceKey);
33
+ }
34
+ catch {
35
+ instance = undefined;
36
+ }
37
+ return instance ?? defaultInstance();
38
+ }
@@ -1,4 +1,5 @@
1
1
  import { appearance, onAppearance, unknownAppearance } from "@runic-artifex/views";
2
+ import { getRunicInstance } from "./instance.js";
2
3
  /**
3
4
  * Follows the page's appearance (`appearance` from `@runic-artifex/views`) while its owner lives: the colour scheme,
4
5
  * contrast and reduced motion of the page's engine combined with the desktop's values that a Runic host pushes
@@ -12,11 +13,12 @@ import { appearance, onAppearance, unknownAppearance } from "@runic-artifex/view
12
13
  * ```
13
14
  */
14
15
  export function useAppearance() {
15
- let current = $state.raw(typeof window === "undefined" ? unknownAppearance : appearance());
16
- $effect.pre(() => {
16
+ const instance = getRunicInstance();
17
+ let current = $state.raw(typeof window === "undefined" ? unknownAppearance : instance.run(appearance));
18
+ $effect.pre(() => instance.run(() => {
17
19
  const stop = onAppearance(next => { current = next; });
18
20
  current = appearance();
19
21
  return stop;
20
- });
22
+ }));
21
23
  return { get current() { return current; } };
22
24
  }
@@ -4,7 +4,7 @@ export interface BridgeConnectionHandle {
4
4
  readonly state: BridgeConnectionState;
5
5
  }
6
6
  /**
7
- * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`,
7
+ * Follows the connection of the component's Runic instance (the page's, by default) to its .NET host (`connecting`, `connected`, `reconnecting`,
8
8
  * `lost` or `closed`) through `onBridgeConnection` while its owner lives. `state` holds the current state at
9
9
  * once; the subscription starts with the owner's effects, so server rendering never observes.
10
10
  * Call during component initialization (or in `$effect.root`); owner destruction unsubscribes.
@@ -1,6 +1,7 @@
1
1
  import { onBridgeConnection } from "@runic-artifex/views";
2
+ import { getRunicInstance } from "./instance.js";
2
3
  /**
3
- * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`,
4
+ * Follows the connection of the component's Runic instance (the page's, by default) to its .NET host (`connecting`, `connected`, `reconnecting`,
4
5
  * `lost` or `closed`) through `onBridgeConnection` while its owner lives. `state` holds the current state at
5
6
  * once; the subscription starts with the owner's effects, so server rendering never observes.
6
7
  * Call during component initialization (or in `$effect.root`); owner destruction unsubscribes.
@@ -12,9 +13,10 @@ import { onBridgeConnection } from "@runic-artifex/views";
12
13
  */
13
14
  export function useBridgeConnection(options = {}) {
14
15
  // The subscription reports the current state at once; reading it validates `lostAfter` too.
16
+ const instance = getRunicInstance();
15
17
  let initial = "connecting";
16
- onBridgeConnection(next => { initial = next; }, options)();
18
+ instance.run(() => onBridgeConnection(next => { initial = next; }, options))();
17
19
  let state = $state(initial);
18
- $effect.pre(() => onBridgeConnection(next => { state = next; }, options));
20
+ $effect.pre(() => instance.run(() => onBridgeConnection(next => { state = next; }, options)));
19
21
  return { get state() { return state; } };
20
22
  }
@@ -1,5 +1,6 @@
1
1
  import { createCommandController } from "@runic-artifex/views";
2
2
  import { derivedFields } from "./derived-fields.svelte.js";
3
+ import { getRunicInstance } from "./instance.js";
3
4
  /**
4
5
  * Tracks a command's pending state and failure as reactive properties. Called
5
6
  * during component initialization (or in `$effect.root`), owner destruction
@@ -13,7 +14,7 @@ import { derivedFields } from "./derived-fields.svelte.js";
13
14
  * ```
14
15
  */
15
16
  export function useCommand(command) {
16
- const controller = createCommandController(command);
17
+ const controller = getRunicInstance().run(() => createCommandController(command));
17
18
  let current = $state.raw(controller.current);
18
19
  const unsubscribe = controller.subscribe(() => { current = controller.current; });
19
20
  // Registered before the first flush, so a destroyed owner never leaks the controller (see useOperation).
@@ -1,6 +1,7 @@
1
1
  import { untrack } from "svelte";
2
2
  import { createFieldController, } from "@runic-artifex/views";
3
3
  import { derivedFields } from "./derived-fields.svelte.js";
4
+ import { getRunicInstance } from "./instance.js";
4
5
  /**
5
6
  * Binds an element to one View member while the calling component is mounted, through `createFieldController`: pass a
6
7
  * generated descriptor such as `EditorFields.title`, or any definition with `read` and `write`. Call it during
@@ -18,7 +19,7 @@ import { derivedFields } from "./derived-fields.svelte.js";
18
19
  * conflict holds further writes until `retry()` or `reset()`. Unmounting writes a value that waits to be written.
19
20
  */
20
21
  export function useField(view, field, options = {}) {
21
- const controller = createFieldController(field, options);
22
+ const controller = getRunicInstance().run(() => createFieldController(field, options));
22
23
  let current = $state.raw(controller.current);
23
24
  const unsubscribe = controller.subscribe(() => { current = controller.current; });
24
25
  // A pre effect runs when it is created, so the teardown exists even if the owner is destroyed before its first
@@ -1,5 +1,6 @@
1
1
  import { createLatestOperationController, } from "@runic-artifex/views";
2
2
  import { derivedFields } from "./derived-fields.svelte.js";
3
+ import { getRunicInstance } from "./instance.js";
3
4
  /**
4
5
  * Admits only the newest selection, for reads such as "load the selected item": each
5
6
  * `run(intent)` replaces the queued intent and cancels the active read, and the next read
@@ -10,7 +11,7 @@ import { derivedFields } from "./derived-fields.svelte.js";
10
11
  * settles run promises without cancelling accepted work.
11
12
  */
12
13
  export function useLatestOperation() {
13
- const controller = createLatestOperationController();
14
+ const controller = getRunicInstance().run(() => createLatestOperationController());
14
15
  let current = $state.raw(controller.current);
15
16
  const unsubscribe = controller.subscribe(() => { current = controller.current; });
16
17
  // Registered before the first flush, so a destroyed owner never leaks the controller (see useOperation).
@@ -1,4 +1,5 @@
1
1
  import { untrack } from "svelte";
2
+ import { getRunicInstance } from "./instance.js";
2
3
  import { BridgeError, createMenuBarController, } from "@runic-artifex/views";
3
4
  /**
4
5
  * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) while its owner lives,
@@ -19,8 +20,10 @@ export function useMenuBar(options = {}) {
19
20
  accessKeyHints: false, revision: 0, menus: Object.freeze([]),
20
21
  }));
21
22
  let controller;
23
+ const instance = getRunicInstance();
22
24
  $effect.pre(() => untrack(() => {
23
- const created = createMenuBarController(controllerOptions);
25
+ // The menu bar of the component's Runic instance.
26
+ const created = instance.run(() => createMenuBarController(controllerOptions));
24
27
  controller = created;
25
28
  state = created.current;
26
29
  created.subscribe(() => { state = created.current; });
@@ -1,5 +1,6 @@
1
1
  import { createOperationController, } from "@runic-artifex/views";
2
2
  import { derivedFields } from "./derived-fields.svelte.js";
3
+ import { getRunicInstance } from "./instance.js";
3
4
  /**
4
5
  * Tracks Start admission, pending work, cancellation and terminal feedback as
5
6
  * reactive properties. Call during component initialization. Owner destruction
@@ -7,7 +8,7 @@ import { derivedFields } from "./derived-fields.svelte.js";
7
8
  * `progress` follows the running operation (`BridgeOperation.subscribe`).
8
9
  */
9
10
  export function useOperation(start, options = {}) {
10
- const controller = createOperationController(start, options);
11
+ const controller = getRunicInstance().run(() => createOperationController(start, options));
11
12
  let current = $state.raw(controller.current);
12
13
  const unsubscribe = controller.subscribe(() => { current = controller.current; });
13
14
  // Svelte runs a pre effect when it is created, during owner initialization,
@@ -1,6 +1,7 @@
1
1
  import { untrack } from "svelte";
2
2
  import { createTextFieldController } from "@runic-artifex/views";
3
3
  import { derivedFields } from "./derived-fields.svelte.js";
4
+ import { getRunicInstance } from "./instance.js";
4
5
  function textOf(event) {
5
6
  if (typeof event === "string")
6
7
  return event;
@@ -25,7 +26,7 @@ function textOf(event) {
25
26
  * `useField` with its `{View}Fields` descriptor.
26
27
  */
27
28
  export function useTextField(view, read, write, options = {}) {
28
- const controller = createTextFieldController({ read, write, ...options });
29
+ const controller = getRunicInstance().run(() => createTextFieldController({ read, write, ...options }));
29
30
  let current = $state.raw(controller.current);
30
31
  const unsubscribe = controller.subscribe(() => { current = controller.current; });
31
32
  // A pre effect runs when it is created, so the teardown exists even if the owner is destroyed before its first
@@ -30,8 +30,8 @@ export declare function useWindowLocale(): WindowLocaleHandle;
30
30
  /**
31
31
  * Follows the locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's
32
32
  * locale). Reading `current` in a template, `$derived` or `$effect` runs it again when the locale changes. It is one
33
- * handle for the page and needs no component, so the page's locale resolver can read it: a template that calls
34
- * `m.*()` then renders again on a language switch. `undefined` while the page has no Translations runtime and the
33
+ * handle for each Runic instance and needs no component (outside one it is the page instance's), so the page's locale
34
+ * resolver can read it: a template that calls `m.*()` then renders again on a language switch. `undefined` while the page has no Translations runtime and the
35
35
  * application sets no window locale.
36
36
  *
37
37
  * ```ts
@@ -1,5 +1,6 @@
1
1
  import { createSubscriber } from "svelte/reactivity";
2
- import { onWindowLocale, resolveText, subscribeText, textLocale, windowLocale } from "@runic-artifex/views";
2
+ import { onWindowLocale, resolveText, subscribeText, textLocale, windowLocale, } from "@runic-artifex/views";
3
+ import { getRunicInstance } from "./instance.js";
3
4
  /**
4
5
  * Follows a text reference that a ViewModel produced, such as a status line or a validation message's `text`, in the
5
6
  * window's language (`resolveText`), while its owner lives. `source` and `fallback` are read reactively, so pass
@@ -14,32 +15,43 @@ import { onWindowLocale, resolveText, subscribeText, textLocale, windowLocale }
14
15
  * ```
15
16
  */
16
17
  export function useText(source, fallback) {
18
+ const instance = getRunicInstance();
17
19
  let version = $state(0);
18
- $effect.pre(() => subscribeText(() => { version++; }));
20
+ $effect.pre(() => instance.run(() => subscribeText(() => { version++; })));
19
21
  const current = $derived.by(() => {
20
22
  void version;
21
- return resolveText(source(), fallback?.());
23
+ const value = source(), text = fallback?.();
24
+ return instance.run(() => resolveText(value, text));
22
25
  });
23
26
  return { get current() { return current; } };
24
27
  }
25
28
  /** Follows the window's locale (`windowLocale`) while its owner lives, for example to set `lang`. */
26
29
  export function useWindowLocale() {
27
- let current = $state(windowLocale());
28
- $effect.pre(() => onWindowLocale(next => { current = next; }));
30
+ const instance = getRunicInstance();
31
+ let current = $state(instance.run(windowLocale));
32
+ $effect.pre(() => instance.run(() => onWindowLocale(next => { current = next; })));
29
33
  return { get current() { return current; } };
30
34
  }
31
- const subscribeTextLocale = createSubscriber(update => subscribeText(update));
32
- const textLocaleHandle = {
33
- get current() {
34
- subscribeTextLocale();
35
- return textLocale();
36
- },
37
- };
35
+ // One handle per Runic instance, created when it is first asked for.
36
+ const textLocaleHandles = new WeakMap();
37
+ function textLocaleHandle(instance) {
38
+ let handle = textLocaleHandles.get(instance);
39
+ if (!handle) {
40
+ const subscribe = createSubscriber(update => instance.run(() => subscribeText(update)));
41
+ textLocaleHandles.set(instance, handle = {
42
+ get current() {
43
+ subscribe();
44
+ return instance.run(textLocale);
45
+ },
46
+ });
47
+ }
48
+ return handle;
49
+ }
38
50
  /**
39
51
  * Follows the locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's
40
52
  * locale). Reading `current` in a template, `$derived` or `$effect` runs it again when the locale changes. It is one
41
- * handle for the page and needs no component, so the page's locale resolver can read it: a template that calls
42
- * `m.*()` then renders again on a language switch. `undefined` while the page has no Translations runtime and the
53
+ * handle for each Runic instance and needs no component (outside one it is the page instance's), so the page's locale
54
+ * resolver can read it: a template that calls `m.*()` then renders again on a language switch. `undefined` while the page has no Translations runtime and the
43
55
  * application sets no window locale.
44
56
  *
45
57
  * ```ts
@@ -48,5 +60,5 @@ const textLocaleHandle = {
48
60
  * ```
49
61
  */
50
62
  export function useTextLocale() {
51
- return textLocaleHandle;
63
+ return textLocaleHandle(getRunicInstance());
52
64
  }
@@ -1,11 +1,14 @@
1
1
  import { untrack } from "svelte";
2
2
  import { createViewController } from "@runic-artifex/views";
3
3
  import { isViewClient, viewSourceIdentity, viewSourcePreview } from "@runic-artifex/views/bindings";
4
+ import { getRunicInstance } from "./instance.js";
4
5
  export function useView(source, options = {}) {
5
- const controller = createViewController({
6
+ const instance = getRunicInstance();
7
+ // The controller connects in the component's Runic instance, also when it retries.
8
+ const controller = instance.run(() => createViewController({
6
9
  ...(options.release ? { release: options.release } : {}),
7
10
  ...(options.keepAlive === undefined ? {} : { keepAlive: options.keepAlive }),
8
- });
11
+ }));
9
12
  let current = $state.raw(controller.current);
10
13
  const unsubscribe = controller.subscribe(() => { current = controller.current; });
11
14
  // A pre effect runs when it is created, so the teardown exists even if the
@@ -24,8 +27,8 @@ export function useView(source, options = {}) {
24
27
  const preview = () => {
25
28
  const value = source();
26
29
  if (value && isViewClient(value))
27
- return value === current.client ? undefined : viewSourcePreview(value);
28
- return fresh() ? undefined : viewSourcePreview(value);
30
+ return value === current.client ? undefined : instance.run(() => viewSourcePreview(value));
31
+ return fresh() ? undefined : instance.run(() => viewSourcePreview(value));
29
32
  };
30
33
  const fresh = () => viewSourceIdentity(current.source) === identity;
31
34
  // `current` is replaced with every published state, which only `state` follows. The other members are derived, so
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.17.0",
3
+ "version": "0.18.0",
4
4
  "description": "Svelte 5 Application Views helpers for Runic",
5
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/svelte#readme",
5
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.18.0/packages/web/svelte#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
8
8
  },
@@ -24,6 +24,12 @@
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
+ },
27
33
  "./package.json": "./package.json"
28
34
  },
29
35
  "files": [
@@ -35,12 +41,12 @@
35
41
  "clean": "bun -e \"import('node:fs').then(({rmSync}) => rmSync('dist', { recursive: true, force: true }))\"",
36
42
  "build": "bun run --bun clean && svelte-package -i src -o dist",
37
43
  "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/keep-alive.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 test/use-text-field.svelte.test.ts test/use-field.svelte.test.ts test/use-query-collection.svelte.test.ts test/use-text.svelte.test.ts test/use-appearance.svelte.test.ts test/text-field.browser.test.ts test/field.browser.test.ts",
44
+ "test": "bun run --bun build && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && vitest run test/use-view.svelte.test.ts test/keep-alive.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 test/use-text-field.svelte.test.ts test/use-field.svelte.test.ts test/use-query-collection.svelte.test.ts test/use-text.svelte.test.ts test/use-appearance.svelte.test.ts test/instances.svelte.test.ts test/hosted-region.svelte.test.ts test/text-field.browser.test.ts test/field.browser.test.ts",
39
45
  "pack:check": "bun pm pack --dry-run"
40
46
  },
41
47
  "peerDependencies": {
42
48
  "svelte": ">=5.57.1 <6",
43
- "@runic-artifex/views": "0.17.0"
49
+ "@runic-artifex/views": "0.18.0"
44
50
  },
45
51
  "publishConfig": {
46
52
  "access": "public",
@@ -53,7 +59,7 @@
53
59
  },
54
60
  "packageManager": "bun@1.4.4",
55
61
  "devDependencies": {
56
- "@runic-artifex/views": "0.17.0",
62
+ "@runic-artifex/views": "0.18.0",
57
63
  "@sveltejs/adapter-static": "4.0.0",
58
64
  "@sveltejs/kit": "3.0.0",
59
65
  "@sveltejs/package": "3.0.0",
@@ -67,5 +73,5 @@
67
73
  "vitest": "5.0.3",
68
74
  "vite": "8.3.4"
69
75
  },
70
- "gitHead": "daeb17e5c3fb0b625d5d988d359cd12ffa51f8c6"
76
+ "gitHead": "e025c0ab74aa76547e2d0307de223c43d5271228"
71
77
  }