@runic-artifex/vue 0.9.1 → 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 +158 -11
- package/dist/index.d.ts +50 -3
- package/dist/index.js +64 -4
- package/dist/menu-bar.d.ts +31 -0
- package/dist/menu-bar.js +37 -0
- package/dist/viewport.d.ts +1 -1
- package/dist/viewport.js +1 -1
- package/package.json +5 -10
- package/dist/experimental.d.ts +0 -1
- package/dist/experimental.js +0 -3
package/README.md
CHANGED
|
@@ -89,8 +89,8 @@ const step = computed({ get: () => state.value?.step ?? 1, set: value => void se
|
|
|
89
89
|
|
|
90
90
|
Renders the component registered for a generated reference's `kind` and
|
|
91
91
|
passes the reference as its `page` prop. A different reference remounts the
|
|
92
|
-
component, a kind without a component renders an
|
|
93
|
-
renders while `content` is empty:
|
|
92
|
+
component, a kind without a component renders an English `<p role="alert">`
|
|
93
|
+
(or the `missing` slot), and the default slot renders while `content` is empty:
|
|
94
94
|
|
|
95
95
|
```vue
|
|
96
96
|
<script setup lang="ts">
|
|
@@ -111,6 +111,16 @@ const { state } = useView({ connect: connectWorkspace });
|
|
|
111
111
|
`satisfies ViewRegistry<…>` checks that every kind has a component whose `page`
|
|
112
112
|
prop accepts that reference.
|
|
113
113
|
|
|
114
|
+
The `missing` slot replaces the English alert, for example with localized text.
|
|
115
|
+
It receives `{ content }`, the reference whose kind has no component, and its
|
|
116
|
+
markup (including any `role`) is yours:
|
|
117
|
+
|
|
118
|
+
```vue
|
|
119
|
+
<ViewOutlet :content="state?.main" :registry="pages">
|
|
120
|
+
<template #missing="{ content }"><p role="alert">{{ t("missingView", { kind: content.kind }) }}</p></template>
|
|
121
|
+
</ViewOutlet>
|
|
122
|
+
```
|
|
123
|
+
|
|
114
124
|
## `useCommand(command)`
|
|
115
125
|
|
|
116
126
|
Returns `{ run, pending, error, failure, reset }`, with `pending`, `error` and
|
|
@@ -133,7 +143,7 @@ neither.
|
|
|
133
143
|
## `useOperation(start, options?)`
|
|
134
144
|
|
|
135
145
|
Observes a generated `start<Command>()` operation through the framework-neutral
|
|
136
|
-
[operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
146
|
+
[operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#operation-feedback-and-latest-selection)
|
|
137
147
|
and returns each state field as a shallow ref, with `run`, `cancel` and `reset`:
|
|
138
148
|
|
|
139
149
|
```vue
|
|
@@ -158,6 +168,146 @@ without an `error`; `failed` and `timed-out` statuses are still `error`. `pendin
|
|
|
158
168
|
stays true after a Cancel response until the operation reaches its terminal status.
|
|
159
169
|
Disposing the effect scope settles run promises without cancelling accepted work.
|
|
160
170
|
|
|
171
|
+
## `useLatestOperation()`
|
|
172
|
+
|
|
173
|
+
Admits only the newest of several reads, for example loading the item the user
|
|
174
|
+
selected last, through the framework-neutral
|
|
175
|
+
[latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#operation-feedback-and-latest-selection),
|
|
176
|
+
and returns each state field as a shallow ref, with `run` and `clear`. Each
|
|
177
|
+
`run(intent)` replaces the queued intent and cancels the active read; the next read
|
|
178
|
+
starts only after the previous one reaches its terminal status and the intent's
|
|
179
|
+
optional `waitForCompletion` barrier:
|
|
180
|
+
|
|
181
|
+
```vue
|
|
182
|
+
<script setup lang="ts">
|
|
183
|
+
const { run: load, outcome, blocked } = useLatestOperation<Item>();
|
|
184
|
+
function select(id: string) {
|
|
185
|
+
const current = client.value;
|
|
186
|
+
if (current) void load({ start: () => current.startLoad(id), isCurrent: () => client.value === current });
|
|
187
|
+
}
|
|
188
|
+
</script>
|
|
189
|
+
|
|
190
|
+
<template>
|
|
191
|
+
<ItemView v-if="outcome?.ok" :item="outcome.value" />
|
|
192
|
+
<p v-if="blocked" role="alert">Reconnect before selecting again.</p>
|
|
193
|
+
</template>
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
The result has the `useOperation` fields plus `blocked`, with `run(intent)` and
|
|
197
|
+
`clear(mode?)`, which never reject. The intent carries `start` and the optional
|
|
198
|
+
`cancel`, `waitForCompletion` and `isCurrent` callbacks, so it captures the client or
|
|
199
|
+
session it belongs to. `blocked` means admission is uncertain, for example after a
|
|
200
|
+
lost Start reply; only `clear("replace")`, called after the application has
|
|
201
|
+
established a fresh session, clears it. `clear()` drops the queued intent and cancels
|
|
202
|
+
the active read. Disposing the effect scope settles run promises without cancelling
|
|
203
|
+
accepted work.
|
|
204
|
+
|
|
205
|
+
## `useBridgeConnection(options?)`
|
|
206
|
+
|
|
207
|
+
Follows the page's connection to its .NET host. It wraps `onBridgeConnection`
|
|
208
|
+
from `@runic-artifex/views` (re-exported here since 0.11, with the
|
|
209
|
+
`BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a shallow ref holding a
|
|
210
|
+
`BridgeConnectionState`: `connecting`, `connected`, `reconnecting` or `lost` (a
|
|
211
|
+
closed set, see
|
|
212
|
+
[Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#connection-state)):
|
|
213
|
+
|
|
214
|
+
```vue
|
|
215
|
+
<script setup lang="ts">
|
|
216
|
+
import { useBridgeConnection } from "@runic-artifex/vue";
|
|
217
|
+
|
|
218
|
+
const { state: connection } = useBridgeConnection({ lostAfter: 5_000 });
|
|
219
|
+
</script>
|
|
220
|
+
|
|
221
|
+
<template>
|
|
222
|
+
<p v-if="connection === 'lost'" role="alert">The application stopped responding.</p>
|
|
223
|
+
</template>
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Disposing the effect scope (unmounting the component) unsubscribes. Call it in
|
|
227
|
+
`setup()` or `effectScope().run()`: outside an effect scope nothing stops it, and
|
|
228
|
+
development builds warn. An invalid `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`) until the current effect scope is
|
|
234
|
+
disposed. It wraps `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 }`: `state` is a shallow ref
|
|
236
|
+
of a `MenuBarState`, and the bar is rendered by the menubar component of the
|
|
237
|
+
application's own UI library. Runic ships no menubar component.
|
|
238
|
+
|
|
239
|
+
```vue
|
|
240
|
+
<script setup lang="ts">
|
|
241
|
+
import { ref } from "vue";
|
|
242
|
+
import { useMenuBar } from "@runic-artifex/vue";
|
|
243
|
+
|
|
244
|
+
const open = ref("");
|
|
245
|
+
const { state: menuBar, invoke } = useMenuBar({
|
|
246
|
+
onRequest: request => { if (request.kind === "open") open.value = request.menu.key; else focusFirstTrigger(); },
|
|
247
|
+
});
|
|
248
|
+
</script>
|
|
249
|
+
|
|
250
|
+
<template>
|
|
251
|
+
<!-- On macOS the application menu bar keeps the menus ("global"): render nothing. -->
|
|
252
|
+
<nav v-if="menuBar.placement === 'page'"><!-- the menubar component; an item's select handler calls invoke(item) --></nav>
|
|
253
|
+
</template>
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Options are those of `createMenuBarController` (`shortcuts`, `keyboard`)
|
|
257
|
+
without `signal`, plus `onRequest`, which receives the `focus` and `open`
|
|
258
|
+
requests. Stopping the scope disposes the controller, which also returns the
|
|
259
|
+
`shortcuts: "app"` lease. Call it in `setup()` or `effectScope().run()`;
|
|
260
|
+
outside an effect scope it is never released (development builds warn). Server
|
|
261
|
+
rendering creates no controller: `state` stays `connecting`.
|
|
262
|
+
|
|
263
|
+
### With Reka UI
|
|
264
|
+
|
|
265
|
+
Reka UI's `MenubarRoot` with `v-model` of the open menu; the
|
|
266
|
+
[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
|
|
267
|
+
items and is tested with real keys:
|
|
268
|
+
|
|
269
|
+
```vue
|
|
270
|
+
<script setup lang="ts">
|
|
271
|
+
import { ref } from "vue";
|
|
272
|
+
import { MenubarContent, MenubarItem, MenubarMenu, MenubarPortal, MenubarRoot, MenubarSeparator, MenubarTrigger } from "reka-ui";
|
|
273
|
+
import { splitAccessKey } from "@runic-artifex/views";
|
|
274
|
+
import { useMenuBar } from "@runic-artifex/vue";
|
|
275
|
+
|
|
276
|
+
const bar = ref<{ $el: HTMLElement }>();
|
|
277
|
+
const open = ref("");
|
|
278
|
+
const { state: menuBar, invoke } = useMenuBar({
|
|
279
|
+
onRequest: request => {
|
|
280
|
+
if (request.kind === "open") open.value = request.menu.key;
|
|
281
|
+
else bar.value?.$el.querySelector<HTMLElement>("[role=menuitem]")?.focus();
|
|
282
|
+
},
|
|
283
|
+
});
|
|
284
|
+
</script>
|
|
285
|
+
|
|
286
|
+
<template>
|
|
287
|
+
<MenubarRoot v-if="menuBar.placement === 'page'" ref="bar" v-model="open" aria-label="Application">
|
|
288
|
+
<MenubarMenu v-for="menu in menuBar.menus" :key="menu.key" :value="menu.key">
|
|
289
|
+
<MenubarTrigger :disabled="!menu.enabled">
|
|
290
|
+
<template v-for="(part, index) in splitAccessKey(menu)" :key="index">
|
|
291
|
+
<u v-if="index === 1 && menuBar.accessKeyHints">{{ part }}</u><template v-else>{{ part }}</template>
|
|
292
|
+
</template>
|
|
293
|
+
</MenubarTrigger>
|
|
294
|
+
<MenubarPortal>
|
|
295
|
+
<MenubarContent align="start">
|
|
296
|
+
<template v-for="entry in menu.entries" :key="entry.key">
|
|
297
|
+
<MenubarSeparator v-if="entry.kind === 'separator'" />
|
|
298
|
+
<MenubarItem v-else-if="entry.kind === 'item'" :disabled="!entry.enabled"
|
|
299
|
+
:aria-keyshortcuts="entry.ariaKeyShortcuts" @select="invoke(entry)">
|
|
300
|
+
{{ entry.label }} <kbd aria-hidden="true">{{ entry.shortcutText }}</kbd>
|
|
301
|
+
</MenubarItem>
|
|
302
|
+
<!-- a submenu: MenubarSub; check and radio items: MenubarCheckboxItem, MenubarRadioGroup -->
|
|
303
|
+
</template>
|
|
304
|
+
</MenubarContent>
|
|
305
|
+
</MenubarPortal>
|
|
306
|
+
</MenubarMenu>
|
|
307
|
+
</MenubarRoot>
|
|
308
|
+
</template>
|
|
309
|
+
```
|
|
310
|
+
|
|
161
311
|
## Errors
|
|
162
312
|
|
|
163
313
|
The `error` of `useView` and of a command or operation handle is typed
|
|
@@ -172,7 +322,7 @@ const offline = error.value instanceof BridgeError && error.value.kind === "disc
|
|
|
172
322
|
```
|
|
173
323
|
|
|
174
324
|
`instanceof` holds for errors from every copy of the package on the page.
|
|
175
|
-
[Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
325
|
+
[Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#errors-and-diagnostics)
|
|
176
326
|
lists the kinds. Any other value, such as an exception that your own connect
|
|
177
327
|
function or command callback throws, arrives unchanged.
|
|
178
328
|
|
|
@@ -219,18 +369,15 @@ application's own dialog.
|
|
|
219
369
|
departure before that is answered by the ViewModel's .NET fallback handler, or
|
|
220
370
|
fails closed without one.
|
|
221
371
|
|
|
222
|
-
The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
372
|
+
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)
|
|
223
373
|
has the .NET side and which View answers which departure. In a frontend test,
|
|
224
374
|
the generated mock's `interactions.<name>.request(input)` resolves with the
|
|
225
|
-
registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
226
|
-
|
|
227
|
-
## `useCollectionViewport(options)` (experimental)
|
|
375
|
+
registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#testing).
|
|
228
376
|
|
|
229
|
-
|
|
230
|
-
`@runic-artifex/views/experimental` controller it wraps.
|
|
377
|
+
## `useCollectionViewport(options)`
|
|
231
378
|
|
|
232
379
|
Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
|
|
233
|
-
`viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
380
|
+
`viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#collectionviewportoptions)
|
|
234
381
|
range; `attach` is a function ref for the container. Bind it to a native element
|
|
235
382
|
such as a `<div>`: a component instance (`:ref="attach"` on a component) or a
|
|
236
383
|
non-HTML element detaches the viewport, and development builds warn. Pass a getter for the
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type Component, type MaybeRefOrGetter, type Ref } from "vue";
|
|
2
|
-
import { type BridgeOperation, type BridgeOutcomeFailure, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type ViewClient, type ViewSource } from "@runic-artifex/views";
|
|
2
|
+
import { type BridgeConnectionOptions, type BridgeConnectionState, type BridgeOperation, type BridgeOutcomeFailure, type LatestOperationController, type LatestOperationState, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type ViewClient, type ViewSource } from "@runic-artifex/views";
|
|
3
3
|
export interface ViewHandle<TClient extends ViewClient> {
|
|
4
4
|
/** The latest state, or undefined until the client connects. */
|
|
5
5
|
readonly state: Readonly<Ref<TClient["snapshot"] | undefined>>;
|
|
@@ -47,8 +47,15 @@ export interface ViewOutletProps<R extends PageReference> {
|
|
|
47
47
|
/**
|
|
48
48
|
* Renders the registered component for a generated View reference and passes
|
|
49
49
|
* the reference as its `page` prop. A different reference remounts the
|
|
50
|
-
* component.
|
|
51
|
-
* renders
|
|
50
|
+
* component. The default slot renders while there is no content. A kind without
|
|
51
|
+
* a component renders the `missing` slot, which receives `{ content }`, for example
|
|
52
|
+
* for localized text, or an English alert without it:
|
|
53
|
+
*
|
|
54
|
+
* ```vue
|
|
55
|
+
* <ViewOutlet :content="state?.main" :registry="pages">
|
|
56
|
+
* <template #missing="{ content }"><p role="alert">{{ t("missingView", content.kind) }}</p></template>
|
|
57
|
+
* </ViewOutlet>
|
|
58
|
+
* ```
|
|
52
59
|
*/
|
|
53
60
|
export declare const ViewOutlet: new <R extends PageReference>(props: (ViewOutletProps<R> & ({
|
|
54
61
|
[x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
|
|
@@ -119,3 +126,43 @@ export type OperationHandle<TArgs extends readonly unknown[], TResult, TFailure
|
|
|
119
126
|
* ```
|
|
120
127
|
*/
|
|
121
128
|
export declare function useOperation<TArgs extends readonly unknown[], TResult, TFailure = never>(start: (...args: TArgs) => BridgeOperation<TResult, TFailure> | undefined | PromiseLike<BridgeOperation<TResult, TFailure> | undefined>, options?: OperationControllerOptions<TResult, TFailure>): OperationHandle<TArgs, TResult, TFailure>;
|
|
129
|
+
/** Each {@link LatestOperationState} field as a shallow ref, with the controller's `run` and `clear`. */
|
|
130
|
+
export type LatestOperationHandle<TResult, TFailure = never> = {
|
|
131
|
+
readonly [K in keyof LatestOperationState<TResult, TFailure>]-?: Readonly<Ref<LatestOperationState<TResult, TFailure>[K]>>;
|
|
132
|
+
} & Pick<LatestOperationController<TResult, TFailure>, "run" | "clear">;
|
|
133
|
+
/**
|
|
134
|
+
* Admits only the newest selection, for reads such as "load the selected item": each
|
|
135
|
+
* `run(intent)` replaces the queued intent and cancels the active read, and the next read
|
|
136
|
+
* starts only after the previous one has finished (including `waitForCompletion`). Each
|
|
137
|
+
* state field is a shallow ref, so the handle can be destructured. `blocked` means
|
|
138
|
+
* admission is uncertain; only `clear("replace")`, after the application has established a
|
|
139
|
+
* fresh session, clears it. Scope disposal settles run promises without cancelling accepted
|
|
140
|
+
* work. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never
|
|
141
|
+
* released (development builds warn).
|
|
142
|
+
*
|
|
143
|
+
* ```vue
|
|
144
|
+
* const load = useLatestOperation<Item>();
|
|
145
|
+
* <li @click="load.run({ start: () => client.value?.startLoad(id) })">…</li>
|
|
146
|
+
* <ItemView v-if="load.outcome.value?.ok" :item="load.outcome.value.value" />
|
|
147
|
+
* ```
|
|
148
|
+
*/
|
|
149
|
+
export declare function useLatestOperation<TResult = void, TFailure = never>(): LatestOperationHandle<TResult, TFailure>;
|
|
150
|
+
export interface BridgeConnectionHandle {
|
|
151
|
+
/** The connection to the .NET host, as `onBridgeConnection` reports it. */
|
|
152
|
+
readonly state: Readonly<Ref<BridgeConnectionState>>;
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`
|
|
156
|
+
* or `lost`) as a shallow ref through `onBridgeConnection`, until the current effect scope is
|
|
157
|
+
* disposed. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never
|
|
158
|
+
* released (development builds warn).
|
|
159
|
+
*
|
|
160
|
+
* ```vue
|
|
161
|
+
* const { state: connection } = useBridgeConnection();
|
|
162
|
+
* <p v-if="connection === 'lost'" role="alert">The application stopped responding.</p>
|
|
163
|
+
* ```
|
|
164
|
+
*/
|
|
165
|
+
export declare function useBridgeConnection(options?: BridgeConnectionOptions): BridgeConnectionHandle;
|
|
166
|
+
export { useCollectionViewport, type CollectionViewportHandle } from "./viewport.js";
|
|
167
|
+
export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
|
|
168
|
+
export { useMenuBar, type MenuBarEntry, type MenuBarHandle, type MenuBarInvokeResult, type MenuBarItem, type MenuBarMenu, type MenuBarRequest, type MenuBarSeparator, type MenuBarState, type UseMenuBarOptions, } from "./menu-bar.js";
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { defineComponent, h, shallowRef, toValue, watch, } from "vue";
|
|
2
|
-
import { createCommandController, createOperationController, createViewController, } from "@runic-artifex/views";
|
|
2
|
+
import { createCommandController, createLatestOperationController, createOperationController, createViewController, onBridgeConnection, } from "@runic-artifex/views";
|
|
3
3
|
import { viewSourceIdentity } from "@runic-artifex/views/bindings";
|
|
4
4
|
import { releaseWithScope } from "./scope.js";
|
|
5
5
|
export function useView(source, options = {}) {
|
|
@@ -34,16 +34,26 @@ function referenceKey(reference) {
|
|
|
34
34
|
/**
|
|
35
35
|
* Renders the registered component for a generated View reference and passes
|
|
36
36
|
* the reference as its `page` prop. A different reference remounts the
|
|
37
|
-
* component.
|
|
38
|
-
* renders
|
|
37
|
+
* component. The default slot renders while there is no content. A kind without
|
|
38
|
+
* a component renders the `missing` slot, which receives `{ content }`, for example
|
|
39
|
+
* for localized text, or an English alert without it:
|
|
40
|
+
*
|
|
41
|
+
* ```vue
|
|
42
|
+
* <ViewOutlet :content="state?.main" :registry="pages">
|
|
43
|
+
* <template #missing="{ content }"><p role="alert">{{ t("missingView", content.kind) }}</p></template>
|
|
44
|
+
* </ViewOutlet>
|
|
45
|
+
* ```
|
|
39
46
|
*/
|
|
40
47
|
export const ViewOutlet = defineComponent((props, { slots }) => () => {
|
|
41
48
|
const content = props.content;
|
|
42
49
|
if (!content)
|
|
43
50
|
return slots.default?.();
|
|
44
51
|
const component = props.registry[content.kind];
|
|
45
|
-
if (!component)
|
|
52
|
+
if (!component) {
|
|
53
|
+
if (slots["missing"])
|
|
54
|
+
return slots["missing"]({ content });
|
|
46
55
|
return h("p", { role: "alert" }, `No web component is registered for ${content.kind}.`);
|
|
56
|
+
}
|
|
47
57
|
return h(component, { key: referenceKey(content), page: content });
|
|
48
58
|
}, { name: "ViewOutlet", props: ["content", "registry"] });
|
|
49
59
|
/**
|
|
@@ -98,3 +108,53 @@ export function useOperation(start, options = {}) {
|
|
|
98
108
|
releaseWithScope("useOperation", () => controller.dispose());
|
|
99
109
|
return { ...refs, run: controller.run, cancel: controller.cancel, reset: controller.reset };
|
|
100
110
|
}
|
|
111
|
+
/**
|
|
112
|
+
* Admits only the newest selection, for reads such as "load the selected item": each
|
|
113
|
+
* `run(intent)` replaces the queued intent and cancels the active read, and the next read
|
|
114
|
+
* starts only after the previous one has finished (including `waitForCompletion`). Each
|
|
115
|
+
* state field is a shallow ref, so the handle can be destructured. `blocked` means
|
|
116
|
+
* admission is uncertain; only `clear("replace")`, after the application has established a
|
|
117
|
+
* fresh session, clears it. Scope disposal settles run promises without cancelling accepted
|
|
118
|
+
* work. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never
|
|
119
|
+
* released (development builds warn).
|
|
120
|
+
*
|
|
121
|
+
* ```vue
|
|
122
|
+
* const load = useLatestOperation<Item>();
|
|
123
|
+
* <li @click="load.run({ start: () => client.value?.startLoad(id) })">…</li>
|
|
124
|
+
* <ItemView v-if="load.outcome.value?.ok" :item="load.outcome.value.value" />
|
|
125
|
+
* ```
|
|
126
|
+
*/
|
|
127
|
+
export function useLatestOperation() {
|
|
128
|
+
const controller = createLatestOperationController();
|
|
129
|
+
const refs = {};
|
|
130
|
+
const keys = Object.keys(controller.current);
|
|
131
|
+
for (const key of keys)
|
|
132
|
+
refs[key] = shallowRef(controller.current[key]);
|
|
133
|
+
controller.subscribe(() => {
|
|
134
|
+
const current = controller.current;
|
|
135
|
+
for (const key of keys)
|
|
136
|
+
refs[key].value = current[key];
|
|
137
|
+
});
|
|
138
|
+
releaseWithScope("useLatestOperation", () => controller.dispose());
|
|
139
|
+
return { ...refs, run: controller.run, clear: controller.clear };
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`
|
|
143
|
+
* or `lost`) as a shallow ref through `onBridgeConnection`, until the current effect scope is
|
|
144
|
+
* disposed. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never
|
|
145
|
+
* released (development builds warn).
|
|
146
|
+
*
|
|
147
|
+
* ```vue
|
|
148
|
+
* const { state: connection } = useBridgeConnection();
|
|
149
|
+
* <p v-if="connection === 'lost'" role="alert">The application stopped responding.</p>
|
|
150
|
+
* ```
|
|
151
|
+
*/
|
|
152
|
+
export function useBridgeConnection(options = {}) {
|
|
153
|
+
const state = shallowRef("connecting");
|
|
154
|
+
const stop = onBridgeConnection(next => { state.value = next; }, options);
|
|
155
|
+
releaseWithScope("useBridgeConnection", stop);
|
|
156
|
+
return { state };
|
|
157
|
+
}
|
|
158
|
+
export { useCollectionViewport } from "./viewport.js";
|
|
159
|
+
export { onBridgeConnection } from "@runic-artifex/views";
|
|
160
|
+
export { useMenuBar, } from "./menu-bar.js";
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { type ShallowRef } from "vue";
|
|
2
|
+
import { type MenuBarController, type MenuBarControllerOptions, type MenuBarRequest, type MenuBarState } from "@runic-artifex/views";
|
|
3
|
+
export type { MenuBarEntry, MenuBarInvokeResult, MenuBarItem, MenuBarMenu, MenuBarRequest, MenuBarSeparator, MenuBarState, } from "@runic-artifex/views";
|
|
4
|
+
export interface UseMenuBarOptions extends Omit<MenuBarControllerOptions, "signal"> {
|
|
5
|
+
/**
|
|
6
|
+
* Receives the `focus` (Alt tap, F10) and `open` (Alt plus a menu's access key) requests: focus the first trigger
|
|
7
|
+
* or set the menubar component's open menu.
|
|
8
|
+
*/
|
|
9
|
+
readonly onRequest?: (request: MenuBarRequest) => void;
|
|
10
|
+
}
|
|
11
|
+
export interface MenuBarHandle {
|
|
12
|
+
/** The menu bar as the page renders it; render a bar only when `placement` is `"page"`. */
|
|
13
|
+
readonly state: Readonly<ShallowRef<MenuBarState>>;
|
|
14
|
+
/** Runs an item through the native bar's command path. */
|
|
15
|
+
readonly invoke: MenuBarController["invoke"];
|
|
16
|
+
/** Matches a `keydown` event against the items' shortcuts, for the `shortcuts: "app"` option. */
|
|
17
|
+
readonly handleKeyDown: MenuBarController["handleKeyDown"];
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) as a shallow ref, as
|
|
21
|
+
* headless state for the application's own menubar component, through `createMenuBarController`, until the current
|
|
22
|
+
* effect scope is disposed. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never
|
|
23
|
+
* released (development builds warn). Server rendering creates no controller and stays `connecting`.
|
|
24
|
+
*
|
|
25
|
+
* ```vue
|
|
26
|
+
* const open = ref("");
|
|
27
|
+
* const { state: menuBar, invoke } = useMenuBar({ onRequest: request => { if (request.kind === "open") open.value = request.menu.key; } });
|
|
28
|
+
* <MenubarRoot v-if="menuBar.placement === 'page'" v-model="open">…<MenubarItem @select="invoke(item)">
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
export declare function useMenuBar(options?: UseMenuBarOptions): MenuBarHandle;
|
package/dist/menu-bar.js
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { hasInjectionContext, inject, shallowRef, ssrContextKey } from "vue";
|
|
2
|
+
import { BridgeError, createMenuBarController, } from "@runic-artifex/views";
|
|
3
|
+
import { releaseWithScope } from "./scope.js";
|
|
4
|
+
/**
|
|
5
|
+
* Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) as a shallow ref, as
|
|
6
|
+
* headless state for the application's own menubar component, through `createMenuBarController`, until the current
|
|
7
|
+
* effect scope is disposed. Call it in `setup()` or `effectScope().run()`: outside an effect scope it is never
|
|
8
|
+
* released (development builds warn). Server rendering creates no controller and stays `connecting`.
|
|
9
|
+
*
|
|
10
|
+
* ```vue
|
|
11
|
+
* const open = ref("");
|
|
12
|
+
* const { state: menuBar, invoke } = useMenuBar({ onRequest: request => { if (request.kind === "open") open.value = request.menu.key; } });
|
|
13
|
+
* <MenubarRoot v-if="menuBar.placement === 'page'" v-model="open">…<MenubarItem @select="invoke(item)">
|
|
14
|
+
* ```
|
|
15
|
+
*/
|
|
16
|
+
export function useMenuBar(options = {}) {
|
|
17
|
+
const { onRequest, ...controllerOptions } = options;
|
|
18
|
+
// Server rendering never stops a component's scope, so it would never release a controller.
|
|
19
|
+
if (hasInjectionContext() && inject(ssrContextKey, null) !== null) {
|
|
20
|
+
const state = shallowRef(Object.freeze({
|
|
21
|
+
status: "connecting", placement: "none", shortcuts: controllerOptions.shortcuts === "app" ? "app" : "host",
|
|
22
|
+
accessKeyHints: false, revision: 0, menus: Object.freeze([]),
|
|
23
|
+
}));
|
|
24
|
+
return {
|
|
25
|
+
state,
|
|
26
|
+
invoke: () => Promise.reject(new BridgeError("unavailable", "The menu bar is not followed during server rendering.", { route: "__runicMenuBarInvoke" })),
|
|
27
|
+
handleKeyDown: () => false,
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
const controller = createMenuBarController(controllerOptions);
|
|
31
|
+
const state = shallowRef(controller.current);
|
|
32
|
+
controller.subscribe(() => { state.value = controller.current; });
|
|
33
|
+
if (onRequest)
|
|
34
|
+
controller.onRequest(onRequest);
|
|
35
|
+
releaseWithScope("useMenuBar", () => controller.dispose());
|
|
36
|
+
return { state, invoke: controller.invoke, handleKeyDown: controller.handleKeyDown };
|
|
37
|
+
}
|
package/dist/viewport.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type ComponentPublicInstance, type MaybeRefOrGetter, type Ref } from "vue";
|
|
2
|
-
import { type CollectionViewport, type CollectionViewportOptions } from "@runic-artifex/views
|
|
2
|
+
import { type CollectionViewport, type CollectionViewportOptions } from "@runic-artifex/views";
|
|
3
3
|
export interface CollectionViewportHandle {
|
|
4
4
|
/** The rows to request and the sizes to render. */
|
|
5
5
|
readonly viewport: Readonly<Ref<CollectionViewport>>;
|
package/dist/viewport.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { shallowRef, toValue, watch } from "vue";
|
|
2
|
-
import { createCollectionViewportController, } from "@runic-artifex/views
|
|
2
|
+
import { createCollectionViewportController, } from "@runic-artifex/views";
|
|
3
3
|
import { releaseWithScope } from "./scope.js";
|
|
4
4
|
/**
|
|
5
5
|
* Follows a fixed-row-height scroll container and returns the rows to request
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@runic-artifex/vue",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"description": "Vue composables for generated Runic Views clients",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -19,11 +19,6 @@
|
|
|
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
|
-
},
|
|
27
22
|
"./package.json": "./package.json"
|
|
28
23
|
},
|
|
29
24
|
"scripts": {
|
|
@@ -35,10 +30,10 @@
|
|
|
35
30
|
},
|
|
36
31
|
"peerDependencies": {
|
|
37
32
|
"vue": ">=3.5.30 <4",
|
|
38
|
-
"@runic-artifex/views": "0.
|
|
33
|
+
"@runic-artifex/views": "0.11.0"
|
|
39
34
|
},
|
|
40
35
|
"devDependencies": {
|
|
41
|
-
"@runic-artifex/views": "0.
|
|
36
|
+
"@runic-artifex/views": "0.11.0",
|
|
42
37
|
"happy-dom": "20.14.5",
|
|
43
38
|
"typescript": "6.0.3",
|
|
44
39
|
"vitest": "5.0.3",
|
|
@@ -53,7 +48,7 @@
|
|
|
53
48
|
"url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
|
|
54
49
|
"directory": "packages/web/vue"
|
|
55
50
|
},
|
|
56
|
-
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
51
|
+
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/vue#readme",
|
|
57
52
|
"bugs": {
|
|
58
53
|
"url": "https://github.com/Runic-Artifex/runic-sdk/issues"
|
|
59
54
|
},
|
|
@@ -63,5 +58,5 @@
|
|
|
63
58
|
"views",
|
|
64
59
|
"vue"
|
|
65
60
|
],
|
|
66
|
-
"gitHead": "
|
|
61
|
+
"gitHead": "318762a9d5dcdd74303ca30b095fed355a1ab21f"
|
|
67
62
|
}
|
package/dist/experimental.d.ts
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
export { useCollectionViewport, type CollectionViewportHandle } from "./viewport.js";
|
package/dist/experimental.js
DELETED