@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 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 alert, and the default slot
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.9.1/packages/web/views#operation-feedback-and-latest-selection)
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.9.1/packages/web/views#errors-and-diagnostics)
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.9.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
372
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.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.9.1/packages/web/views#testing).
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
- Exported from `@runic-artifex/vue/experimental`, like the
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.9.1/packages/web/views#collectionviewportoptions-experimental)
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. A kind without a component renders an alert; the default slot
51
- * renders while there is no content.
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. A kind without a component renders an alert; the default slot
38
- * renders while there is no content.
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;
@@ -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
+ }
@@ -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/experimental";
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/experimental";
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.9.1",
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.9.1"
33
+ "@runic-artifex/views": "0.11.0"
39
34
  },
40
35
  "devDependencies": {
41
- "@runic-artifex/views": "0.9.1",
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.9.1/packages/web/vue#readme",
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": "7df2f00a9800c180e266ca545d4d6a03bf78dc89"
61
+ "gitHead": "318762a9d5dcdd74303ca30b095fed355a1ab21f"
67
62
  }
@@ -1 +0,0 @@
1
- export { useCollectionViewport, type CollectionViewportHandle } from "./viewport.js";
@@ -1,3 +0,0 @@
1
- // `@runic-artifex/vue/experimental`: composables whose shape may still change in a minor release
2
- // (docs/experimental.md). Graduation moves an export to `@runic-artifex/vue`.
3
- export { useCollectionViewport } from "./viewport.js";