@runic-artifex/vue 0.17.1 → 0.19.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
@@ -196,10 +196,10 @@ is written. A string set on `value` of a field that is not text is taken as its
196
196
  `errors` holds the member's validation messages from the descriptor (`[]` when valid), `error` why the latest write
197
197
  or text failed (a `BridgeError` or a `FieldError`, whose `kind` is `rejected`, `conflict`, `committed-with-error` or
198
198
  `invalid-text`). `FieldError`, `FieldOptions`, `FieldState` and `BridgeField` are exported from this package. See the
199
- [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#fields) for the receipts
199
+ [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#fields) for the receipts
200
200
  and text forms. An `invalid-text` error has a `reason` and `arguments`: render `useText(() => title.error)` after
201
201
  `configureFieldErrorText` to show your own text for it in the window's language
202
- ([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#translating-field-errors)).
202
+ ([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#translating-field-errors)).
203
203
 
204
204
  #### Row cells and nested members
205
205
 
@@ -208,7 +208,7 @@ Since 0.16, `InvoiceFields.address.street` and `InvoiceFields.lines.at(line.id).
208
208
  `useField` in the row's component (`v-model="quantity.text"`); `at(key)` returns the same descriptor for the same
209
209
  key. Such a field always writes checked, conflicts only when another writer changed the same cell, and shows the
210
210
  messages .NET reports at the cell's validation path. See
211
- [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/vue/../views/README.md#fields-below-a-member-and-row-cells).
211
+ [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/packages/web/vue/../views/README.md#fields-below-a-member-and-row-cells).
212
212
 
213
213
  ### Forms: `useForm(fields, options?)`
214
214
 
@@ -223,7 +223,7 @@ const form = useForm({ title, step }, { dirty: () => editor.state.value?.isDirty
223
223
  ### Text inputs: `useTextField(view, read, write, options?)`
224
224
 
225
225
  Binds a text input to a member through the framework-neutral
226
- [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#text-inputs)
226
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#text-inputs)
227
227
  while the effect scope is active. Each field is a ref, so the handle can be destructured:
228
228
 
229
229
  ```vue
@@ -291,7 +291,7 @@ const { state } = useView({ connect: connectWorkspace });
291
291
  `satisfies ViewRegistry<…>` checks that every kind has a component whose `page`
292
292
  prop accepts that reference. A component whose `page` is a shared page
293
293
  reference, such as `ResultPagePageReference` of a .NET
294
- [`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/vue/../../dotnet/Runic.Application.Views/README.md#shared-clients)
294
+ [`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/packages/web/vue/../../dotnet/Runic.Application.Views/README.md#shared-clients)
295
295
  interface, registers for each of its kinds:
296
296
  `{ ...registryEntries(resultPageKinds, ResultPage), settings: Settings }`.
297
297
 
@@ -396,7 +396,7 @@ neither.
396
396
  ## `useOperation(start, options?)`
397
397
 
398
398
  Observes a generated `start<Command>()` operation through the framework-neutral
399
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#operation-feedback-and-latest-selection)
399
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#operation-feedback-and-latest-selection)
400
400
  and returns each state field as a shallow ref, with `run`, `cancel` and `reset`:
401
401
 
402
402
  ```vue
@@ -428,7 +428,7 @@ Disposing the effect scope settles run promises without cancelling accepted work
428
428
 
429
429
  Admits only the newest of several reads, for example loading the item the user
430
430
  selected last, through the framework-neutral
431
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#operation-feedback-and-latest-selection),
431
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#operation-feedback-and-latest-selection),
432
432
  and returns each state field as a shallow ref, with `run` and `clear`. Each
433
433
  `run(intent)` replaces the queued intent and cancels the active read; the next read
434
434
  starts only after the previous one reaches its terminal status and the intent's
@@ -465,7 +465,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
465
465
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a shallow ref holding a
466
466
  `BridgeConnectionState`: `connecting`, `connected`, `reconnecting`, `lost` or `closed` (the
467
467
  application closed the window, since 0.15; a closed set, see
468
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#connection-state)):
468
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#connection-state)):
469
469
 
470
470
  ```vue
471
471
  <script setup lang="ts">
@@ -488,7 +488,7 @@ development builds warn. An invalid `lostAfter` throws a `RangeError`.
488
488
  Follows the declared menu bar of a Runic Desktop window that leaves it to the
489
489
  page (`DesktopMenuBarPresentation.Page`) until the current effect scope is
490
490
  disposed. It wraps `createMenuBarController` from `@runic-artifex/views` (see
491
- [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a shallow ref
491
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a shallow ref
492
492
  of a `MenuBarState`, and the bar is rendered by the menubar component of the
493
493
  application's own UI library. Runic ships no menubar component.
494
494
 
@@ -519,7 +519,7 @@ rendering creates no controller: `state` stays `connecting`.
519
519
  ### With Reka UI
520
520
 
521
521
  Reka UI's `MenubarRoot` with `v-model` of the open menu; the
522
- [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
522
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
523
523
  items and is tested with real keys:
524
524
 
525
525
  ```vue
@@ -570,7 +570,7 @@ Shows a text reference that a ViewModel produced, such as a status line or a
570
570
  validation error's `text`, in the window's language, and renders again when the
571
571
  language changes. A string shows as it is; `null` and `undefined` show
572
572
  `fallback`. Connect the page's Translations runtime once with
573
- `configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
573
+ `configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
574
574
  `useWindowLocale()` reads the window's locale.
575
575
 
576
576
  `useTextLocale()` is the locale that text is shown in, as a ref. It is one ref
@@ -597,7 +597,7 @@ The page's appearance as a ref that renders, computes and watches again when it
597
597
  changes, while the calling component or effect scope lives: the colour scheme,
598
598
  contrast and reduced motion of the page's engine, combined with the desktop's
599
599
  text scale, accent colour, forced-colours palette, contrast and motion that a
600
- Runic host pushes ([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/views/README.md#appearance)). Every member is `null` under
600
+ Runic host pushes ([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/packages/web/views/README.md#appearance)). Every member is `null` under
601
601
  server rendering.
602
602
 
603
603
  ```ts
@@ -610,7 +610,7 @@ const fontSize = computed(() => `${look.value.textScale ?? 1}rem`);
610
610
  The `error` of `useView` and of a command or operation handle is typed
611
611
  `unknown`: it holds whatever the connection or the call rejected with. A Bridge
612
612
  failure is a `BridgeError` from `@runic-artifex/views`. Show it with
613
- `describeBridgeError(error)`, one English sentence, instead of `String(error)`,
613
+ `describeBridgeError(error)`, one sentence (in the window's language with `configureRunicViewsText()`), instead of `String(error)`,
614
614
  and narrow it with `isBridgeError` (or `instanceof`) before reading `kind`,
615
615
  `route` or `detail`:
616
616
 
@@ -622,7 +622,7 @@ const message = computed(() => describeBridgeError(error.value));
622
622
  ```
623
623
 
624
624
  `instanceof` holds for errors from every copy of the package on the page.
625
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#errors-and-diagnostics)
625
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#errors-and-diagnostics)
626
626
  lists the kinds. Any other value, such as an exception that your own connect
627
627
  function or command callback throws, arrives unchanged.
628
628
 
@@ -669,10 +669,10 @@ application's own dialog.
669
669
  departure before that is answered by the ViewModel's .NET fallback handler, or
670
670
  fails closed without one.
671
671
 
672
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
672
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
673
673
  has the .NET side and which View answers which departure. In a frontend test,
674
674
  the generated mock's `interactions.<name>.request(input)` resolves with the
675
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#testing).
675
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#testing).
676
676
 
677
677
  ## View requests
678
678
 
@@ -708,14 +708,14 @@ the page painted the state the request was raised with, so the field of that
708
708
  state is rendered; `signal` aborts when the handler is replaced or removed, the
709
709
  client is disposed or the connection is lost. A request is never replayed: one
710
710
  raised before the effect ran, or while the page is disconnected, is not
711
- delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#view-requests) for the rules, and in a frontend
711
+ delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#view-requests) for the rules, and in a frontend
712
712
  test raise one with the generated mock's `requests.<name>.raise(input)` (the
713
- [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#testing)).
713
+ [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#testing)).
714
714
 
715
715
  ## `useCollectionViewport(options)`
716
716
 
717
717
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
718
- `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#collectionviewportoptions)
718
+ `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#collectionviewportoptions)
719
719
  range; `attach` is a function ref for the container. Bind it to a native element
720
720
  such as a `<div>`: a component instance (`:ref="attach"` on a component) or a
721
721
  non-HTML element detaches the viewport, and development builds warn. Pass a getter for the
@@ -739,7 +739,7 @@ watch(() => [viewport.value.start, viewport.value.size] as const, ([start, size]
739
739
 
740
740
  ## `useQueryCollection(collection, options)`
741
741
 
742
- Follows a scroll container for a [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it
742
+ Follows a scroll container for a [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it
743
743
  loads the rows the container shows, with placeholders until they arrive, and lays them out with variable heights.
744
744
  Pass the collection or a getter (`() => client.value?.queries.rows`) and the options. `viewport` is a ref of the
745
745
  `QueryViewport` (`items` with `top` and `size`, `totalSize`, `total`, `query`, `loading`, `error`); bind `attach` to the
@@ -766,4 +766,19 @@ The package re-exports `installBackNavigation`, `installNavigationPath`,
766
766
  `@runic-artifex/views` (since 0.16). Call the installs once where the page
767
767
  starts, before or after mounting: the mouse's Back button and Alt+Left then go
768
768
  back in the .NET window, and `#/customers/42` follows its path region. See
769
- [Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/views/README.md#back-and-the-url).
769
+ [Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/packages/web/views/README.md#back-and-the-url).
770
+
771
+ ## Hosted regions (experimental)
772
+
773
+ `RunicHostedRegion` from `@runic-artifex/vue/experimental` renders
774
+ `<runic-hosted-region>`, a region where the host application shows a hosted guest's
775
+ Window ([hosted regions](https://github.com/Runic-Artifex/runic-sdk/blob/v0.19.0/packages/web/vue/../views/README.md#hosted-regions-experimental)). Its `fallback` slot, scoped with the region's
776
+ `state`, shows while no guest page shows in it:
777
+
778
+ ```vue
779
+ <RunicHostedRegion name="check" style="height: 420px" @state-change="onState">
780
+ <template #fallback="{ state }">
781
+ <RunAgain v-if="state === 'ended'" /><p v-else>Starting the check…</p>
782
+ </template>
783
+ </RunicHostedRegion>
784
+ ```
@@ -0,0 +1,62 @@
1
+ import { type PropType, type SlotsType, type VNodeChild } from "vue";
2
+ import { type HostedRegionSizing, type HostedRegionState } from "@runic-artifex/views/experimental";
3
+ export type { HostedRegionSizing, HostedRegionState, RunicHostedRegionElement } from "@runic-artifex/views/experimental";
4
+ /**
5
+ * A region where the host application shows a hosted guest's Window (`<runic-hosted-region>`), in a frame the page never
6
+ * gets a reference to. The `fallback` slot, scoped with the region's `state`, shows while no guest page shows in it:
7
+ *
8
+ * ```vue
9
+ * <RunicHostedRegion name="check" style="height: 420px" @state-change="onState">
10
+ * <template #fallback="{ state }"><RunAgain v-if="state === 'ended'" /><p v-else>Starting the check…</p></template>
11
+ * </RunicHostedRegion>
12
+ * ```
13
+ */
14
+ export declare const RunicHostedRegion: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
15
+ /** The region's name, which the host application's policy embeds a guest's Window in. */
16
+ name: {
17
+ type: StringConstructor;
18
+ required: true;
19
+ };
20
+ /** `fill` (the default): the page's layout sets the height. `content-height`: the guest's page does. */
21
+ sizing: {
22
+ type: PropType<HostedRegionSizing>;
23
+ default: undefined;
24
+ };
25
+ /** The region's accessible name; without it, the guest page's title. */
26
+ label: {
27
+ type: StringConstructor;
28
+ default: undefined;
29
+ };
30
+ }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
31
+ [key: string]: any;
32
+ }>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
33
+ stateChange: (_state: HostedRegionState, _previous: HostedRegionState) => true;
34
+ /** The guest page's title as the host passed it on, or `null`. */
35
+ titleChange: (_title: string | null) => true;
36
+ }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
37
+ /** The region's name, which the host application's policy embeds a guest's Window in. */
38
+ name: {
39
+ type: StringConstructor;
40
+ required: true;
41
+ };
42
+ /** `fill` (the default): the page's layout sets the height. `content-height`: the guest's page does. */
43
+ sizing: {
44
+ type: PropType<HostedRegionSizing>;
45
+ default: undefined;
46
+ };
47
+ /** The region's accessible name; without it, the guest page's title. */
48
+ label: {
49
+ type: StringConstructor;
50
+ default: undefined;
51
+ };
52
+ }>> & Readonly<{
53
+ onStateChange?: (_state: HostedRegionState, _previous: HostedRegionState) => any;
54
+ onTitleChange?: (_title: string | null) => any;
55
+ }>, {
56
+ sizing: HostedRegionSizing;
57
+ label: string;
58
+ }, SlotsType<{
59
+ fallback?: (props: {
60
+ readonly state: HostedRegionState;
61
+ }) => VNodeChild;
62
+ }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
@@ -0,0 +1,50 @@
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
+ import { defineComponent, h, ref } from "vue";
4
+ import { defineHostedRegion, hostedRegionTag, } from "@runic-artifex/views/experimental";
5
+ /**
6
+ * A region where the host application shows a hosted guest's Window (`<runic-hosted-region>`), in a frame the page never
7
+ * gets a reference to. The `fallback` slot, scoped with the region's `state`, shows while no guest page shows in it:
8
+ *
9
+ * ```vue
10
+ * <RunicHostedRegion name="check" style="height: 420px" @state-change="onState">
11
+ * <template #fallback="{ state }"><RunAgain v-if="state === 'ended'" /><p v-else>Starting the check…</p></template>
12
+ * </RunicHostedRegion>
13
+ * ```
14
+ */
15
+ export const RunicHostedRegion = defineComponent({
16
+ name: "RunicHostedRegion",
17
+ props: {
18
+ /** The region's name, which the host application's policy embeds a guest's Window in. */
19
+ name: { type: String, required: true },
20
+ /** `fill` (the default): the page's layout sets the height. `content-height`: the guest's page does. */
21
+ sizing: { type: String, default: undefined },
22
+ /** The region's accessible name; without it, the guest page's title. */
23
+ label: { type: String, default: undefined },
24
+ },
25
+ emits: {
26
+ stateChange: (_state, _previous) => true,
27
+ /** The guest page's title as the host passed it on, or `null`. */
28
+ titleChange: (_title) => true,
29
+ },
30
+ slots: Object,
31
+ setup(props, { emit, slots }) {
32
+ defineHostedRegion();
33
+ const state = ref("waiting");
34
+ const stateChanged = (event) => {
35
+ state.value = event.detail.state;
36
+ emit("stateChange", event.detail.state, event.detail.previous);
37
+ };
38
+ const titleChanged = (event) => emit("titleChange", event.detail.title);
39
+ return () => {
40
+ const fallback = slots.fallback?.({ state: state.value });
41
+ return h(hostedRegionTag, {
42
+ name: props.name,
43
+ ...(props.sizing === undefined ? {} : { sizing: props.sizing }),
44
+ ...(props.label === undefined ? {} : { label: props.label }),
45
+ onRunicregionstatechange: stateChanged,
46
+ onRunicregiontitlechange: titleChanged,
47
+ }, fallback === undefined ? [] : [h("div", { slot: "fallback", style: { display: "contents" } }, [fallback])]);
48
+ };
49
+ },
50
+ });
package/dist/index.d.ts CHANGED
@@ -89,13 +89,13 @@ export interface ViewOutletProps<R extends PageReference> {
89
89
  * ```
90
90
  */
91
91
  export declare const ViewOutlet: new <R extends PageReference>(props: (ViewOutletProps<R> & ({
92
- [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
93
- } | {
94
92
  [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
95
- })) & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps) => import("vue").CreateComponentPublicInstanceWithMixins<ViewOutletProps<R> & ({
96
- [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
97
93
  } | {
94
+ [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
95
+ })) & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps) => import("vue").CreateComponentPublicInstanceWithMixins<ViewOutletProps<R> & ({
98
96
  [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
97
+ } | {
98
+ [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
99
99
  }), {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, import("vue").EmitsOptions, import("vue").PublicProps, {}, false, {}, {}, {}, {}, string, {}, any, import("vue").ComponentProvideOptions, {
100
100
  P: {};
101
101
  B: {};
@@ -104,9 +104,9 @@ export declare const ViewOutlet: new <R extends PageReference>(props: (ViewOutle
104
104
  M: {};
105
105
  Defaults: {};
106
106
  }, (ViewOutletProps<R> & {
107
- [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
108
- }) | (ViewOutletProps<R> & {
109
107
  [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
108
+ }) | (ViewOutletProps<R> & {
109
+ [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
110
110
  }), {}, {}, {}, {}, {}>;
111
111
  /** How {@link RegionOutlets} renders the regions of a collection. */
112
112
  export type RegionOutletsMode = "keep-mounted" | "selected";
@@ -144,13 +144,13 @@ export interface RegionOutletsProps<R extends PageReference> {
144
144
  * ```
145
145
  */
146
146
  export declare const RegionOutlets: new <R extends PageReference>(props: (RegionOutletsProps<R> & ({
147
- [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
148
- } | {
149
147
  [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
150
- })) & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps) => import("vue").CreateComponentPublicInstanceWithMixins<RegionOutletsProps<R> & ({
151
- [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
152
148
  } | {
149
+ [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
150
+ })) & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps) => import("vue").CreateComponentPublicInstanceWithMixins<RegionOutletsProps<R> & ({
153
151
  [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
152
+ } | {
153
+ [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
154
154
  }), {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, import("vue").EmitsOptions, import("vue").PublicProps, {}, false, {}, {}, {}, {}, string, {}, any, import("vue").ComponentProvideOptions, {
155
155
  P: {};
156
156
  B: {};
@@ -159,9 +159,9 @@ export declare const RegionOutlets: new <R extends PageReference>(props: (Region
159
159
  M: {};
160
160
  Defaults: {};
161
161
  }, (RegionOutletsProps<R> & {
162
- [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
163
- }) | (RegionOutletsProps<R> & {
164
162
  [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
163
+ }) | (RegionOutletsProps<R> & {
164
+ [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
165
165
  }), {}, {}, {}, {}, {}>;
166
166
  export interface CommandHandle<TArgs extends readonly unknown[], TResult, TFailure = BridgeOutcomeFailure<TResult>> {
167
167
  /**
@@ -395,8 +395,8 @@ export declare function useWindowLocale(): Readonly<Ref<string | null>>;
395
395
  export declare function useAppearance(): Readonly<Ref<Appearance>>;
396
396
  /**
397
397
  * The locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's locale),
398
- * as a ref that renders, computes and watches again when it changes. It is one ref for the page and needs no effect
399
- * scope, so the page's locale resolver can read it: a template that calls `m.*()` then renders again on a language
398
+ * as a ref that renders, computes and watches again when it changes. It is one ref for the page (for each Runic instance)
399
+ * and needs no effect scope, so the page's locale resolver can read it: a template that calls `m.*()` then renders again on a language
400
400
  * switch. `undefined` while the page has no Translations runtime and the application sets no window locale.
401
401
  *
402
402
  * ```ts
@@ -405,6 +405,8 @@ export declare function useAppearance(): Readonly<Ref<Appearance>>;
405
405
  * ```
406
406
  */
407
407
  export declare function useTextLocale(): Readonly<Ref<string | undefined>>;
408
+ export { provideRunicInstance, runicInstanceKey, useRunicInstance } from "./instance.js";
409
+ export { createRunicInstance, pageInstance, type RunicInstance, type RunicInstanceOptions } from "@runic-artifex/views";
408
410
  export { useCollectionViewport, type CollectionViewportHandle } from "./viewport.js";
409
411
  export { useForm, type FormFieldHandle, type FormHandle, type UseFormOptions } from "./form.js";
410
412
  export { commitAllFields, type FormState, type FormSubmitOptions, type FormSubmitResult } from "@runic-artifex/views";
package/dist/index.js CHANGED
@@ -3,11 +3,13 @@ import { createCommandController, createLatestOperationController, createOperati
3
3
  import { missingViewMessage, reportMissingView, viewSourceIdentity } from "@runic-artifex/views/bindings";
4
4
  import { isDevelopment } from "./development.js";
5
5
  import { releaseWithScope } from "./scope.js";
6
+ import { useRunicInstance } from "./instance.js";
6
7
  function controllerOptions(options) {
7
8
  return { ...(options.release ? { release: options.release } : {}), ...(options.keepAlive === undefined ? {} : { keepAlive: options.keepAlive }) };
8
9
  }
9
10
  export function useView(source, options = {}) {
10
- const controller = createViewController(controllerOptions(options));
11
+ // The controller connects in the component's Runic instance, also when its source changes or it retries.
12
+ const controller = useRunicInstance().run(() => createViewController(controllerOptions(options)));
11
13
  const state = shallowRef();
12
14
  const client = shallowRef();
13
15
  const error = shallowRef();
@@ -80,7 +82,11 @@ function referenceKey(reference) {
80
82
  * </ViewOutlet>
81
83
  * ```
82
84
  */
83
- export const ViewOutlet = defineComponent((props, { slots }) => () => {
85
+ export const ViewOutlet = defineComponent((props, { slots }) => {
86
+ const instance = useRunicInstance();
87
+ return () => outletContent(instance, props, slots);
88
+ }, { name: "ViewOutlet", props: ["content", "registry"] });
89
+ function outletContent(instance, props, slots) {
84
90
  const content = props.content;
85
91
  if (!content)
86
92
  return slots.default?.();
@@ -90,11 +96,11 @@ export const ViewOutlet = defineComponent((props, { slots }) => () => {
90
96
  return slots["missing"]({ content });
91
97
  if (isDevelopment())
92
98
  return h("p", { role: "alert" }, missingViewMessage(content.kind));
93
- reportMissingView(content.kind);
99
+ instance.run(() => reportMissingView(content.kind));
94
100
  return null;
95
101
  }
96
102
  return h(component, { key: referenceKey(content), page: content });
97
- }, { name: "ViewOutlet", props: ["content", "registry"] });
103
+ }
98
104
  /**
99
105
  * Renders a {@link ViewOutlet} for the regions of a region collection, each in a `<div data-region-key>` keyed by
100
106
  * the region's key. A region that is not selected is rendered with `hidden` and an inline `display: none`, which
@@ -129,7 +135,7 @@ export const RegionOutlets = defineComponent((props, { slots }) => () => {
129
135
  * ```
130
136
  */
131
137
  export function useCommand(command) {
132
- const controller = createCommandController(command);
138
+ const controller = useRunicInstance().run(() => createCommandController(command));
133
139
  const pending = shallowRef(controller.current.pending);
134
140
  const error = shallowRef(controller.current.error);
135
141
  // A conditional failure type does not distribute through shallowRef's overloads.
@@ -157,7 +163,7 @@ export function useCommand(command) {
157
163
  * ```
158
164
  */
159
165
  export function useOperation(start, options = {}) {
160
- const controller = createOperationController(start, options);
166
+ const controller = useRunicInstance().run(() => createOperationController(start, options));
161
167
  const refs = {};
162
168
  const keys = Object.keys(controller.current);
163
169
  for (const key of keys)
@@ -187,7 +193,7 @@ export function useOperation(start, options = {}) {
187
193
  * ```
188
194
  */
189
195
  export function useLatestOperation() {
190
- const controller = createLatestOperationController();
196
+ const controller = useRunicInstance().run(() => createLatestOperationController());
191
197
  const refs = {};
192
198
  const keys = Object.keys(controller.current);
193
199
  for (const key of keys)
@@ -219,7 +225,7 @@ export function useLatestOperation() {
219
225
  * `useField` with its `{View}Fields` descriptor.
220
226
  */
221
227
  export function useTextField(view, read, write, options = {}) {
222
- const controller = createTextFieldController({ read, write, ...options });
228
+ const controller = useRunicInstance().run(() => createTextFieldController({ read, write, ...options }));
223
229
  const current = shallowRef(controller.current);
224
230
  controller.subscribe(() => { current.value = controller.current; });
225
231
  watch([view.state, view.client], ([state, client]) => {
@@ -254,7 +260,7 @@ export function useTextField(view, read, write, options = {}) {
254
260
  * written.
255
261
  */
256
262
  export function useField(view, field, options = {}) {
257
- const controller = createFieldController(field, options);
263
+ const controller = useRunicInstance().run(() => createFieldController(field, options));
258
264
  const current = shallowRef(controller.current);
259
265
  controller.subscribe(() => { current.value = controller.current; });
260
266
  watch([view.state, view.client], ([state, client]) => {
@@ -307,7 +313,7 @@ export function useField(view, field, options = {}) {
307
313
  */
308
314
  export function useBridgeConnection(options = {}) {
309
315
  const state = shallowRef("connecting");
310
- const stop = onBridgeConnection(next => { state.value = next; }, options);
316
+ const stop = useRunicInstance().run(() => onBridgeConnection(next => { state.value = next; }, options));
311
317
  releaseWithScope("useBridgeConnection", stop);
312
318
  return { state };
313
319
  }
@@ -325,17 +331,20 @@ export function useBridgeConnection(options = {}) {
325
331
  * ```
326
332
  */
327
333
  export function useText(source, fallback) {
334
+ const instance = useRunicInstance();
328
335
  const version = shallowRef(0);
329
- releaseWithScope("useText", subscribeText(() => { version.value++; }));
336
+ releaseWithScope("useText", instance.run(() => subscribeText(() => { version.value++; })));
330
337
  return computed(() => {
331
338
  void version.value;
332
- return resolveText(toValue(source), toValue(fallback));
339
+ const value = toValue(source), fallbackText = toValue(fallback);
340
+ return instance.run(() => resolveText(value, fallbackText));
333
341
  });
334
342
  }
335
343
  /** The window's locale that the application set, or `null` while it sets none, as a ref, until the effect scope stops. */
336
344
  export function useWindowLocale() {
337
- const locale = shallowRef(windowLocale());
338
- releaseWithScope("useWindowLocale", onWindowLocale(next => { locale.value = next; }));
345
+ const instance = useRunicInstance();
346
+ const locale = shallowRef(instance.run(windowLocale));
347
+ releaseWithScope("useWindowLocale", instance.run(() => onWindowLocale(next => { locale.value = next; })));
339
348
  return locale;
340
349
  }
341
350
  /**
@@ -351,16 +360,18 @@ export function useWindowLocale() {
351
360
  * ```
352
361
  */
353
362
  export function useAppearance() {
354
- const current = shallowRef(appearance());
355
- releaseWithScope("useAppearance", onAppearance(next => { current.value = next; }));
356
- current.value = appearance();
363
+ const instance = useRunicInstance();
364
+ const current = shallowRef(instance.run(appearance));
365
+ releaseWithScope("useAppearance", instance.run(() => onAppearance(next => { current.value = next; })));
366
+ current.value = instance.run(appearance);
357
367
  return current;
358
368
  }
359
- let pageTextLocale;
369
+ // One text locale ref per Runic instance.
370
+ const textLocales = new WeakMap();
360
371
  /**
361
372
  * The locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's locale),
362
- * as a ref that renders, computes and watches again when it changes. It is one ref for the page and needs no effect
363
- * scope, so the page's locale resolver can read it: a template that calls `m.*()` then renders again on a language
373
+ * as a ref that renders, computes and watches again when it changes. It is one ref for the page (for each Runic instance)
374
+ * and needs no effect scope, so the page's locale resolver can read it: a template that calls `m.*()` then renders again on a language
364
375
  * switch. `undefined` while the page has no Translations runtime and the application sets no window locale.
365
376
  *
366
377
  * ```ts
@@ -369,21 +380,27 @@ let pageTextLocale;
369
380
  * ```
370
381
  */
371
382
  export function useTextLocale() {
372
- return pageTextLocale ??= customRef((track, trigger) => {
373
- let subscribed = false;
374
- return {
375
- get() {
376
- if (!subscribed) {
377
- subscribed = true;
378
- subscribeText(trigger);
379
- }
380
- track();
381
- return textLocale();
382
- },
383
- set() { },
384
- };
385
- });
383
+ const instance = useRunicInstance();
384
+ let locale = textLocales.get(instance);
385
+ if (!locale)
386
+ textLocales.set(instance, locale = customRef((track, trigger) => {
387
+ let subscribed = false;
388
+ return {
389
+ get() {
390
+ if (!subscribed) {
391
+ subscribed = true;
392
+ instance.run(() => subscribeText(trigger));
393
+ }
394
+ track();
395
+ return instance.run(textLocale);
396
+ },
397
+ set() { },
398
+ };
399
+ }));
400
+ return locale;
386
401
  }
402
+ export { provideRunicInstance, runicInstanceKey, useRunicInstance } from "./instance.js";
403
+ export { createRunicInstance, pageInstance } from "@runic-artifex/views";
387
404
  export { useCollectionViewport } from "./viewport.js";
388
405
  export { useForm } from "./form.js";
389
406
  export { commitAllFields } from "@runic-artifex/views";
@@ -0,0 +1,25 @@
1
+ import { type InjectionKey } from "vue";
2
+ import { type RunicInstance } from "@runic-artifex/views";
3
+ /**
4
+ * The injection key of the Runic instance (`createRunicInstance` in @runic-artifex/views), for `app.provide`:
5
+ * `createApp(App).provide(runicInstanceKey, instance)` makes it the instance of the whole app.
6
+ */
7
+ export declare const runicInstanceKey: InjectionKey<RunicInstance>;
8
+ /**
9
+ * Makes `instance` the Runic instance of the calling component and its descendants: `useView`, `useField`, `useText`,
10
+ * `useBridgeConnection`, `useAppearance` and the other composables below it connect and read through it instead of
11
+ * the page instance. Call it in `setup()`. A guest that renders inside another page, such as an embedded component,
12
+ * calls it in its root component (or provides `runicInstanceKey` on its app).
13
+ *
14
+ * ```ts
15
+ * const instance = createRunicInstance({ bridge });
16
+ * createApp(defineComponent({ setup() { provideRunicInstance(instance); return () => h(App); } })).mount(element);
17
+ * ```
18
+ */
19
+ export declare function provideRunicInstance(instance: RunicInstance): void;
20
+ /**
21
+ * The Runic instance of the calling component: that of the nearest `provideRunicInstance` (or `runicInstanceKey` on
22
+ * the app). Without one, and outside a component's `setup()`, it is the current instance: that of an enclosing
23
+ * `instance.run`, otherwise the page instance.
24
+ */
25
+ export declare function useRunicInstance(): RunicInstance;
@@ -0,0 +1,30 @@
1
+ import { hasInjectionContext, inject, provide } from "vue";
2
+ import { currentInstance } from "@runic-artifex/views";
3
+ /**
4
+ * The injection key of the Runic instance (`createRunicInstance` in @runic-artifex/views), for `app.provide`:
5
+ * `createApp(App).provide(runicInstanceKey, instance)` makes it the instance of the whole app.
6
+ */
7
+ export const runicInstanceKey = Symbol("runic.instance");
8
+ /**
9
+ * Makes `instance` the Runic instance of the calling component and its descendants: `useView`, `useField`, `useText`,
10
+ * `useBridgeConnection`, `useAppearance` and the other composables below it connect and read through it instead of
11
+ * the page instance. Call it in `setup()`. A guest that renders inside another page, such as an embedded component,
12
+ * calls it in its root component (or provides `runicInstanceKey` on its app).
13
+ *
14
+ * ```ts
15
+ * const instance = createRunicInstance({ bridge });
16
+ * createApp(defineComponent({ setup() { provideRunicInstance(instance); return () => h(App); } })).mount(element);
17
+ * ```
18
+ */
19
+ export function provideRunicInstance(instance) {
20
+ provide(runicInstanceKey, instance);
21
+ }
22
+ /**
23
+ * The Runic instance of the calling component: that of the nearest `provideRunicInstance` (or `runicInstanceKey` on
24
+ * the app). Without one, and outside a component's `setup()`, it is the current instance: that of an enclosing
25
+ * `instance.run`, otherwise the page instance.
26
+ */
27
+ export function useRunicInstance() {
28
+ const provided = hasInjectionContext() ? inject(runicInstanceKey, undefined) : undefined;
29
+ return provided ?? currentInstance();
30
+ }
package/dist/menu-bar.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { hasInjectionContext, inject, shallowRef, ssrContextKey } from "vue";
2
2
  import { BridgeError, createMenuBarController, } from "@runic-artifex/views";
3
3
  import { releaseWithScope } from "./scope.js";
4
+ import { useRunicInstance } from "./instance.js";
4
5
  /**
5
6
  * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) as a shallow ref, as
6
7
  * headless state for the application's own menubar component, through `createMenuBarController`, until the current
@@ -27,7 +28,8 @@ export function useMenuBar(options = {}) {
27
28
  handleKeyDown: () => false,
28
29
  };
29
30
  }
30
- const controller = createMenuBarController(controllerOptions);
31
+ // The menu bar of the component's Runic instance.
32
+ const controller = useRunicInstance().run(() => createMenuBarController(controllerOptions));
31
33
  const state = shallowRef(controller.current);
32
34
  controller.subscribe(() => { state.value = controller.current; });
33
35
  if (onRequest)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/vue",
3
- "version": "0.17.1",
3
+ "version": "0.19.0",
4
4
  "description": "Vue composables for generated Runic Views clients",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -19,6 +19,11 @@
19
19
  "import": "./dist/index.js",
20
20
  "default": "./dist/index.js"
21
21
  },
22
+ "./experimental": {
23
+ "types": "./dist/experimental.d.ts",
24
+ "import": "./dist/experimental.js",
25
+ "default": "./dist/experimental.js"
26
+ },
22
27
  "./package.json": "./package.json"
23
28
  },
24
29
  "scripts": {
@@ -30,10 +35,10 @@
30
35
  },
31
36
  "peerDependencies": {
32
37
  "vue": ">=3.5.30 <4",
33
- "@runic-artifex/views": "0.17.1"
38
+ "@runic-artifex/views": "0.19.0"
34
39
  },
35
40
  "devDependencies": {
36
- "@runic-artifex/views": "0.17.1",
41
+ "@runic-artifex/views": "0.19.0",
37
42
  "esbuild": "0.28.2",
38
43
  "happy-dom": "21.0.4",
39
44
  "playwright-core": "1.63.0",
@@ -50,7 +55,7 @@
50
55
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
51
56
  "directory": "packages/web/vue"
52
57
  },
53
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/vue#readme",
58
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.19.0/packages/web/vue#readme",
54
59
  "bugs": {
55
60
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
56
61
  },
@@ -60,5 +65,5 @@
60
65
  "views",
61
66
  "vue"
62
67
  ],
63
- "gitHead": "4f200eadd987eab9a2e38db6e8841849b743b615"
68
+ "gitHead": "9a09c23055f09f7505552d236c8acf69bdeeb02e"
64
69
  }