@runic-artifex/svelte 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
@@ -1,10 +1,11 @@
1
1
  # `@runic-artifex/svelte`
2
2
 
3
3
  Svelte 5 Application Views helpers. `@runic-artifex/svelte` exports `useView`,
4
- `ViewOutlet`, `ViewRegistry`, `useCommand` and `useOperation` for generated
5
- Window/View clients, and `@runic-artifex/svelte/experimental` exports
6
- `useCollectionViewport`. The `@runic-artifex/svelte/views` entry of earlier
7
- previews is gone: import from `@runic-artifex/svelte`.
4
+ `ViewOutlet`, `ViewRegistry`, `useCommand`, `useOperation`, `useLatestOperation`
5
+ and `useCollectionViewport` for generated Window/View clients. The
6
+ `@runic-artifex/svelte/views` entry of earlier previews and the
7
+ `@runic-artifex/svelte/experimental` entry of 0.9 are gone: import from
8
+ `@runic-artifex/svelte`.
8
9
 
9
10
  Generated View clients import `@runic-artifex/views`, which this package also
10
11
  builds on, so a Views application installs both packages:
@@ -94,8 +95,18 @@ the reference as its `page` prop:
94
95
 
95
96
  The outlet is generic over the reference union, so the registry must have a
96
97
  component for every kind with a matching `page` prop. A different reference
97
- remounts the component, a kind without a component renders an alert, and the
98
- optional `fallback` snippet renders while `content` is empty.
98
+ remounts the component, a kind without a component renders an English
99
+ `<p role="alert">`, and the optional `fallback` snippet renders while `content` is empty.
100
+
101
+ The optional `missing` snippet replaces that alert, for example with localized
102
+ text. It receives the reference whose kind has no component, and its markup
103
+ (including any `role`) is yours:
104
+
105
+ ```svelte
106
+ <ViewOutlet content={workspace.state?.main} registry={pages}>
107
+ {#snippet missing(page)}<p role="alert">{t("missingView", { kind: page.kind })}</p>{/snippet}
108
+ </ViewOutlet>
109
+ ```
99
110
 
100
111
  ## `useCommand(command)`
101
112
 
@@ -155,32 +166,150 @@ or command availability that outlives the invocation wrapper. By default the hel
155
166
  uses the operation's public `wait()` and `outcome()`; the desktop transport keeps
156
167
  Cancel and other callbacks responsive during observation.
157
168
 
158
- For rapid read selection, compose the framework-neutral
159
- [`createLatestOperationController`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#operation-feedback-and-latest-selection)
160
- with Svelte state. It coalesces latest intent across delayed receipts and orders
161
- the next admission after terminal observation and any application drain barrier:
169
+ ## `useLatestOperation()`
170
+
171
+ For rapid read selection, `useLatestOperation()` wraps the framework-neutral
172
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#operation-feedback-and-latest-selection)
173
+ for the component's lifetime. It coalesces the latest intent across delayed receipts
174
+ and orders the next admission after terminal observation and any application drain
175
+ barrier:
162
176
 
163
177
  ```svelte
164
178
  <script lang="ts">
165
- import { createLatestOperationController } from "@runic-artifex/views/experimental";
166
-
167
- const selections = createLatestOperationController<void>();
168
- let selection = $state.raw(selections.current);
169
- const unsubscribe = selections.subscribe(() => { selection = selections.current; });
170
- $effect.pre(() => () => { unsubscribe(); selections.dispose(); });
171
- // Event handlers call selections.run({ start, cancel, isCurrent, waitForCompletion? }).
172
- // Capture the original client/session in each intent. On application-owned
173
- // session replacement, call selections.clear("replace") to detach old intent.
179
+ import { useLatestOperation, useView } from "@runic-artifex/svelte";
180
+ import { connectCatalog } from "./generated/catalog.js";
181
+
182
+ const catalog = useView(() => ({ connect: connectCatalog }));
183
+ const load = useLatestOperation<Item>();
184
+ function select(id: string) {
185
+ const client = catalog.client;
186
+ if (client) void load.run({ start: () => client.startLoad(id), isCurrent: () => catalog.client === client });
187
+ }
174
188
  </script>
175
189
 
176
- {#if selection.blocked}<p role="alert">Selection completion is uncertain. Reconnect or replace the session before retrying.</p>{/if}
190
+ {#if load.outcome?.ok}<ItemView item={load.outcome.value} />{/if}
191
+ {#if load.blocked}<p role="alert">Selection completion is uncertain. Reconnect or replace the session before retrying.</p>{/if}
177
192
  ```
178
193
 
194
+ The result has the `useOperation` properties plus `blocked`, with `run(intent)` and
195
+ `clear(mode?)`, which never reject. Capture the original client/session in each intent
196
+ (`start`, and optionally `cancel`, `waitForCompletion` and `isCurrent`).
179
197
  `clear()` drops queued input and cancels the captured read; `clear("replace")`
180
198
  detaches it without cancellation and permits fresh admission. The application must
181
199
  establish that replacement boundary and own the old work's drain. Lost terminal
182
200
  observation blocks further Starts instead of retrying blindly, with its reason in
183
- `current.error`; ordinary Cancel does not clear this block.
201
+ `error`; ordinary Cancel does not clear this block. Component destruction settles
202
+ observation without cancelling accepted work. The
203
+ [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/tests/fixtures/application/operations-consumer)
204
+ runs this hook against the packed packages and the desktop transport.
205
+
206
+ ## `useBridgeConnection(options?)`
207
+
208
+ Follows the page's connection to its .NET host. It wraps `onBridgeConnection`
209
+ from `@runic-artifex/views` (re-exported here since 0.11, with the
210
+ `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a reactive
211
+ `BridgeConnectionState`: `connecting`, `connected`, `reconnecting` or `lost` (a
212
+ closed set, see
213
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#connection-state)):
214
+
215
+ ```svelte
216
+ <script lang="ts">
217
+ import { useBridgeConnection } from "@runic-artifex/svelte";
218
+
219
+ const connection = useBridgeConnection({ lostAfter: 5_000 });
220
+ </script>
221
+
222
+ {#if connection.state === "lost"}<p role="alert">The application stopped responding.</p>{/if}
223
+ ```
224
+
225
+ Call it during component initialization (or in `$effect.root`). `state` holds
226
+ the current state at once; observing starts with the owner's effects, so a
227
+ server render does not observe, and destroying the owner unsubscribes. An invalid
228
+ `lostAfter` throws a `RangeError`.
229
+
230
+ ## `useMenuBar(options?)`
231
+
232
+ Follows the declared menu bar of a Runic Desktop window that leaves it to the
233
+ page (`DesktopMenuBarPresentation.Page`) while its owner lives. It wraps
234
+ `createMenuBarController` from `@runic-artifex/views` (see
235
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`, where `state` is a
236
+ reactive `MenuBarState` property. The bar is rendered by the menubar component
237
+ of the application's own UI library. Runic ships no menubar component.
238
+
239
+ ```svelte
240
+ <script lang="ts">
241
+ import { useMenuBar } from "@runic-artifex/svelte";
242
+
243
+ let open = $state("");
244
+ const menuBar = useMenuBar({
245
+ onRequest: request => { if (request.kind === "open") open = request.menu.key; else focusFirstTrigger(); },
246
+ });
247
+ </script>
248
+
249
+ <!-- On macOS the application menu bar keeps the menus ("global"): render nothing. -->
250
+ {#if menuBar.state.placement === "page"}<!-- the menubar component; an item's select handler calls menuBar.invoke(item) -->{/if}
251
+ ```
252
+
253
+ Options are those of `createMenuBarController` (`shortcuts`, `keyboard`)
254
+ without `signal`, plus `onRequest`, which receives the `focus` and `open`
255
+ requests. Call it during component initialization (or in `$effect.root`). The
256
+ controller starts with the owner's effects, so server rendering creates none
257
+ and `state` stays `connecting`; `invoke` rejects with a `BridgeError`
258
+ (`disconnected`) until then. Owner destruction disposes it, which also returns
259
+ the `shortcuts: "app"` lease.
260
+
261
+ ### With Bits UI
262
+
263
+ Bits UI's `Menubar.Root bind:value`; the
264
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
265
+ items and is tested with real keys:
266
+
267
+ ```svelte
268
+ <script lang="ts">
269
+ import { Menubar } from "bits-ui";
270
+ import { splitAccessKey, type MenuBarItem, type MenuBarMenu } from "@runic-artifex/views";
271
+ import { useMenuBar } from "@runic-artifex/svelte";
272
+
273
+ let bar = $state<HTMLElement | null>(null);
274
+ let open = $state("");
275
+ const menuBar = useMenuBar({
276
+ onRequest: request => {
277
+ if (request.kind === "open") open = request.menu.key;
278
+ else bar?.querySelector<HTMLElement>("[role=menuitem]")?.focus();
279
+ },
280
+ });
281
+ </script>
282
+
283
+ {#snippet label(entry: MenuBarMenu | MenuBarItem)}
284
+ {@const [before, key, after] = splitAccessKey(entry)}
285
+ {before}{#if menuBar.state.accessKeyHints}<u>{key}</u>{:else}{key}{/if}{after}
286
+ {/snippet}
287
+
288
+ {#if menuBar.state.placement === "page"}
289
+ <Menubar.Root aria-label="Application" bind:ref={bar} bind:value={open}>
290
+ {#each menuBar.state.menus as menu (menu.key)}
291
+ <Menubar.Menu value={menu.key}>
292
+ <Menubar.Trigger disabled={!menu.enabled}>{@render label(menu)}</Menubar.Trigger>
293
+ <Menubar.Portal>
294
+ <Menubar.Content align="start">
295
+ {#each menu.entries as entry (entry.key)}
296
+ {#if entry.kind === "separator"}<Menubar.Separator />
297
+ {:else if entry.kind === "item"}
298
+ <Menubar.Item disabled={!entry.enabled} aria-keyshortcuts={entry.ariaKeyShortcuts} onSelect={() => menuBar.invoke(entry)}>
299
+ {@render label(entry)} <kbd aria-hidden="true">{entry.shortcutText}</kbd>
300
+ </Menubar.Item>
301
+ {/if}<!-- a submenu: Menubar.Sub; check and radio items: Menubar.CheckboxItem, Menubar.RadioGroup -->
302
+ {/each}
303
+ </Menubar.Content>
304
+ </Menubar.Portal>
305
+ </Menubar.Menu>
306
+ {/each}
307
+ </Menubar.Root>
308
+ {/if}
309
+ ```
310
+
311
+ The host owns `checked`: bind it one way, as
312
+ `bind:checked={() => item.checked ?? false, () => {}}`.
184
313
 
185
314
  ## Errors
186
315
 
@@ -196,7 +325,7 @@ const offline = view.error instanceof BridgeError && view.error.kind === "discon
196
325
  ```
197
326
 
198
327
  `instanceof` holds for errors from every copy of the package on the page.
199
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#errors-and-diagnostics)
328
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#errors-and-diagnostics)
200
329
  lists the kinds. Any other value, such as an exception that your own connect
201
330
  function or command callback throws, arrives unchanged.
202
331
 
@@ -235,18 +364,15 @@ application's own dialog.
235
364
  departure before that is answered by the ViewModel's .NET fallback handler, or
236
365
  fails closed without one.
237
366
 
238
- 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)
367
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.11.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
239
368
  has the .NET side and which View answers which departure. In a frontend test,
240
369
  the generated mock's `interactions.<name>.request(input)` resolves with the
241
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#testing).
242
-
243
- ## `useCollectionViewport(options)` (experimental)
370
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#testing).
244
371
 
245
- Exported from `@runic-artifex/svelte/experimental`, like the
246
- `@runic-artifex/views/experimental` controller it wraps.
372
+ ## `useCollectionViewport(options)`
247
373
 
248
374
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
249
- `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/views#collectionviewportoptions-experimental)
375
+ `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/views#collectionviewportoptions)
250
376
  range; `attach` is an attachment for the container. Call it during component
251
377
  initialization and send the range to the ViewModel from an effect:
252
378
 
@@ -3,17 +3,24 @@
3
3
  import type { PageReference } from "@runic-artifex/views";
4
4
  import type { ViewRegistry } from "./view-registry.js";
5
5
 
6
- let { content, registry, fallback }: {
6
+ let { content, registry, fallback, missing }: {
7
7
  content: R | null | undefined;
8
8
  registry: ViewRegistry<R>;
9
9
  /** Rendered while there is no content. */
10
10
  fallback?: Snippet;
11
+ /**
12
+ * Renders a reference whose kind has no registered component, for example localized text.
13
+ * Defaults to an English `<p role="alert">`.
14
+ */
15
+ missing?: Snippet<[R]>;
11
16
  } = $props();
12
17
  let Resolved = $derived(content ? registry[content.kind as R["kind"]] as Component<{ page: R }> | undefined : undefined);
13
18
  </script>
14
19
 
15
20
  {#if content && Resolved}
16
21
  {#key content}<Resolved page={content} />{/key}
22
+ {:else if content && missing}
23
+ {@render missing(content)}
17
24
  {:else if content}
18
25
  <p role="alert">No web component is registered for {content.kind}.</p>
19
26
  {:else}
@@ -7,6 +7,11 @@ declare function $$render<R extends PageReference>(): {
7
7
  registry: ViewRegistry<R>;
8
8
  /** Rendered while there is no content. */
9
9
  fallback?: Snippet;
10
+ /**
11
+ * Renders a reference whose kind has no registered component, for example localized text.
12
+ * Defaults to an English `<p role="alert">`.
13
+ */
14
+ missing?: Snippet<[R]>;
10
15
  };
11
16
  exports: {};
12
17
  bindings: "";
@@ -3,3 +3,9 @@ export type { ViewRegistry } from "./view-registry.js";
3
3
  export { useView, type UseViewOptions, type ViewHandle } from "./use-view.svelte.js";
4
4
  export { useCommand, type CommandHandle } from "./use-command.svelte.js";
5
5
  export { useOperation, type OperationHandle } from "./use-operation.svelte.js";
6
+ export { useLatestOperation, type LatestOperationHandle } from "./use-latest-operation.svelte.js";
7
+ export { useCollectionViewport, type CollectionViewportHandle } from "./use-collection-viewport.svelte.js";
8
+ export { useBridgeConnection, type BridgeConnectionHandle } from "./use-bridge-connection.svelte.js";
9
+ export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
10
+ export { useMenuBar, type MenuBarHandle, type UseMenuBarOptions } from "./use-menu-bar.svelte.js";
11
+ export type { MenuBarEntry, MenuBarInvokeResult, MenuBarItem, MenuBarMenu, MenuBarRequest, MenuBarSeparator, MenuBarState, } from "@runic-artifex/views";
@@ -2,3 +2,8 @@ export { default as ViewOutlet } from "./ViewOutlet.svelte";
2
2
  export { useView } from "./use-view.svelte.js";
3
3
  export { useCommand } from "./use-command.svelte.js";
4
4
  export { useOperation } from "./use-operation.svelte.js";
5
+ export { useLatestOperation } from "./use-latest-operation.svelte.js";
6
+ export { useCollectionViewport } from "./use-collection-viewport.svelte.js";
7
+ export { useBridgeConnection } from "./use-bridge-connection.svelte.js";
8
+ export { onBridgeConnection } from "@runic-artifex/views";
9
+ export { useMenuBar } from "./use-menu-bar.svelte.js";
@@ -0,0 +1,17 @@
1
+ import { type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
2
+ export interface BridgeConnectionHandle {
3
+ /** The connection to the .NET host, as `onBridgeConnection` reports it. A reactive property. */
4
+ readonly state: BridgeConnectionState;
5
+ }
6
+ /**
7
+ * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting` or
8
+ * `lost`) through `onBridgeConnection` while its owner lives. `state` holds the current state at
9
+ * once; the subscription starts with the owner's effects, so server rendering never observes.
10
+ * Call during component initialization (or in `$effect.root`); owner destruction unsubscribes.
11
+ *
12
+ * ```svelte
13
+ * const connection = useBridgeConnection();
14
+ * {#if connection.state === "lost"}<p role="alert">The application stopped responding.</p>{/if}
15
+ * ```
16
+ */
17
+ export declare function useBridgeConnection(options?: BridgeConnectionOptions): BridgeConnectionHandle;
@@ -0,0 +1,20 @@
1
+ import { onBridgeConnection } from "@runic-artifex/views";
2
+ /**
3
+ * Follows the page's connection to its .NET host (`connecting`, `connected`, `reconnecting` or
4
+ * `lost`) through `onBridgeConnection` while its owner lives. `state` holds the current state at
5
+ * once; the subscription starts with the owner's effects, so server rendering never observes.
6
+ * Call during component initialization (or in `$effect.root`); owner destruction unsubscribes.
7
+ *
8
+ * ```svelte
9
+ * const connection = useBridgeConnection();
10
+ * {#if connection.state === "lost"}<p role="alert">The application stopped responding.</p>{/if}
11
+ * ```
12
+ */
13
+ export function useBridgeConnection(options = {}) {
14
+ // The subscription reports the current state at once; reading it validates `lostAfter` too.
15
+ let initial = "connecting";
16
+ onBridgeConnection(next => { initial = next; }, options)();
17
+ let state = $state(initial);
18
+ $effect.pre(() => onBridgeConnection(next => { state = next; }, options));
19
+ return { get state() { return state; } };
20
+ }
@@ -1,5 +1,5 @@
1
1
  import type { Attachment } from "svelte/attachments";
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: CollectionViewport;
@@ -1,5 +1,5 @@
1
1
  import { untrack } from "svelte";
2
- import { createCollectionViewportController } from "@runic-artifex/views/experimental";
2
+ import { createCollectionViewportController } from "@runic-artifex/views";
3
3
  /**
4
4
  * Follows a fixed-row-height scroll container and returns the rows to request
5
5
  * from .NET. Call it during component initialization with a getter, such as
@@ -0,0 +1,13 @@
1
+ import { type LatestOperationController, type LatestOperationState } from "@runic-artifex/views";
2
+ export interface LatestOperationHandle<TResult, TFailure = never> extends LatestOperationState<TResult, TFailure>, Pick<LatestOperationController<TResult, TFailure>, "run" | "clear"> {
3
+ }
4
+ /**
5
+ * Admits only the newest selection, for reads such as "load the selected item": each
6
+ * `run(intent)` replaces the queued intent and cancels the active read, and the next read
7
+ * starts only after the previous one has finished (including `waitForCompletion`). The
8
+ * state fields are reactive properties. `blocked` means admission is uncertain; only
9
+ * `clear("replace")`, after the application has established a fresh session, clears it.
10
+ * Call during component initialization. Owner destruction detaches observation and
11
+ * settles run promises without cancelling accepted work.
12
+ */
13
+ export declare function useLatestOperation<TResult = void, TFailure = never>(): LatestOperationHandle<TResult, TFailure>;
@@ -0,0 +1,34 @@
1
+ import { createLatestOperationController, } from "@runic-artifex/views";
2
+ /**
3
+ * Admits only the newest selection, for reads such as "load the selected item": each
4
+ * `run(intent)` replaces the queued intent and cancels the active read, and the next read
5
+ * starts only after the previous one has finished (including `waitForCompletion`). The
6
+ * state fields are reactive properties. `blocked` means admission is uncertain; only
7
+ * `clear("replace")`, after the application has established a fresh session, clears it.
8
+ * Call during component initialization. Owner destruction detaches observation and
9
+ * settles run promises without cancelling accepted work.
10
+ */
11
+ export function useLatestOperation() {
12
+ const controller = createLatestOperationController();
13
+ let current = $state.raw(controller.current);
14
+ const unsubscribe = controller.subscribe(() => { current = controller.current; });
15
+ // Registered before the first flush, so a destroyed owner never leaks the controller (see useOperation).
16
+ $effect.pre(() => () => { unsubscribe(); controller.dispose(); });
17
+ return {
18
+ run: controller.run,
19
+ clear: controller.clear,
20
+ get pending() { return current.pending; },
21
+ get admitting() { return current.admitting; },
22
+ get operation() { return current.operation; },
23
+ get status() { return current.status; },
24
+ get outcome() { return current.outcome; },
25
+ get failure() { return current.failure; },
26
+ get error() { return current.error; },
27
+ get cancelled() { return current.cancelled; },
28
+ get cancellationRequested() { return current.cancellationRequested; },
29
+ get cancelling() { return current.cancelling; },
30
+ get cancellation() { return current.cancellation; },
31
+ get cancelError() { return current.cancelError; },
32
+ get blocked() { return current.blocked; },
33
+ };
34
+ }
@@ -0,0 +1,29 @@
1
+ import { type MenuBarController, type MenuBarControllerOptions, type MenuBarRequest, type MenuBarState } from "@runic-artifex/views";
2
+ export interface UseMenuBarOptions extends Omit<MenuBarControllerOptions, "signal"> {
3
+ /**
4
+ * Receives the `focus` (Alt tap, F10) and `open` (Alt plus a menu's access key) requests: focus the first trigger
5
+ * or set the menubar component's open menu.
6
+ */
7
+ readonly onRequest?: (request: MenuBarRequest) => void;
8
+ }
9
+ export interface MenuBarHandle {
10
+ /** The menu bar as the page renders it; render a bar only when `placement` is `"page"`. A reactive property. */
11
+ readonly state: MenuBarState;
12
+ /** Runs an item through the native bar's command path. Rejects with a BridgeError before the owner's effects ran. */
13
+ readonly invoke: MenuBarController["invoke"];
14
+ /** Matches a `keydown` event against the items' shortcuts, for the `shortcuts: "app"` option. */
15
+ readonly handleKeyDown: MenuBarController["handleKeyDown"];
16
+ }
17
+ /**
18
+ * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) while its owner lives,
19
+ * as headless state for the application's own menubar component, through `createMenuBarController`. The controller
20
+ * starts with the owner's effects, so server rendering never creates one and `state` stays `connecting`. Call during
21
+ * component initialization (or in `$effect.root`); owner destruction disposes the controller.
22
+ *
23
+ * ```svelte
24
+ * let open = $state("");
25
+ * const menuBar = useMenuBar({ onRequest: request => { if (request.kind === "open") open = request.menu.key; } });
26
+ * {#if menuBar.state.placement === "page"}<Menubar.Root bind:value={open}>…{/if}
27
+ * ```
28
+ */
29
+ export declare function useMenuBar(options?: UseMenuBarOptions): MenuBarHandle;
@@ -0,0 +1,42 @@
1
+ import { untrack } from "svelte";
2
+ import { BridgeError, createMenuBarController, } from "@runic-artifex/views";
3
+ /**
4
+ * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) while its owner lives,
5
+ * as headless state for the application's own menubar component, through `createMenuBarController`. The controller
6
+ * starts with the owner's effects, so server rendering never creates one and `state` stays `connecting`. Call during
7
+ * component initialization (or in `$effect.root`); owner destruction disposes the controller.
8
+ *
9
+ * ```svelte
10
+ * let open = $state("");
11
+ * const menuBar = useMenuBar({ onRequest: request => { if (request.kind === "open") open = request.menu.key; } });
12
+ * {#if menuBar.state.placement === "page"}<Menubar.Root bind:value={open}>…{/if}
13
+ * ```
14
+ */
15
+ export function useMenuBar(options = {}) {
16
+ const { onRequest, ...controllerOptions } = options;
17
+ let state = $state.raw(Object.freeze({
18
+ status: "connecting", placement: "none", shortcuts: controllerOptions.shortcuts === "app" ? "app" : "host",
19
+ accessKeyHints: false, revision: 0, menus: Object.freeze([]),
20
+ }));
21
+ let controller;
22
+ $effect.pre(() => untrack(() => {
23
+ const created = createMenuBarController(controllerOptions);
24
+ controller = created;
25
+ state = created.current;
26
+ created.subscribe(() => { state = created.current; });
27
+ if (onRequest)
28
+ created.onRequest(onRequest);
29
+ return () => {
30
+ if (controller === created)
31
+ controller = undefined;
32
+ created.dispose();
33
+ };
34
+ }));
35
+ return {
36
+ get state() { return state; },
37
+ invoke: item => controller
38
+ ? controller.invoke(item)
39
+ : Promise.reject(new BridgeError("disconnected", "The menu bar is not connected yet.", { route: "__runicMenuBarInvoke" })),
40
+ handleKeyDown: event => controller?.handleKeyDown(event) ?? false,
41
+ };
42
+ }
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.9.1",
3
+ "version": "0.11.0",
4
4
  "description": "Svelte 5 Application Views helpers for Runic",
5
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.9.1/packages/web/svelte#readme",
5
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/svelte#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
8
8
  },
@@ -24,12 +24,6 @@
24
24
  "import": "./dist/index.js",
25
25
  "default": "./dist/index.js"
26
26
  },
27
- "./experimental": {
28
- "types": "./dist/experimental.d.ts",
29
- "svelte": "./dist/experimental.js",
30
- "import": "./dist/experimental.js",
31
- "default": "./dist/experimental.js"
32
- },
33
27
  "./package.json": "./package.json"
34
28
  },
35
29
  "files": [
@@ -41,12 +35,12 @@
41
35
  "clean": "bun -e \"import('node:fs').then(({rmSync}) => rmSync('dist', { recursive: true, force: true }))\"",
42
36
  "build": "bun run --bun clean && svelte-package -i src -o dist",
43
37
  "check": "svelte-check --tsconfig ./tsconfig.json",
44
- "test": "bun run --bun build && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && vitest run test/use-view.svelte.test.ts test/glue.svelte.test.ts test/use-operation.svelte.test.ts test/lifecycle.svelte.test.ts",
38
+ "test": "bun run --bun build && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && vitest run test/use-view.svelte.test.ts test/glue.svelte.test.ts test/use-operation.svelte.test.ts test/use-latest-operation.svelte.test.ts test/lifecycle.svelte.test.ts test/use-bridge-connection.svelte.test.ts test/use-menu-bar.svelte.test.ts",
45
39
  "pack:check": "bun pm pack --dry-run"
46
40
  },
47
41
  "peerDependencies": {
48
42
  "svelte": ">=5.57.1 <6",
49
- "@runic-artifex/views": "0.9.1"
43
+ "@runic-artifex/views": "0.11.0"
50
44
  },
51
45
  "publishConfig": {
52
46
  "access": "public",
@@ -59,7 +53,7 @@
59
53
  },
60
54
  "packageManager": "bun@1.4.2",
61
55
  "devDependencies": {
62
- "@runic-artifex/views": "0.9.1",
56
+ "@runic-artifex/views": "0.11.0",
63
57
  "@sveltejs/adapter-static": "4.0.0",
64
58
  "@sveltejs/kit": "3.0.0",
65
59
  "@sveltejs/package": "3.0.0",
@@ -72,5 +66,5 @@
72
66
  "vitest": "5.0.3",
73
67
  "vite": "8.3.4"
74
68
  },
75
- "gitHead": "7df2f00a9800c180e266ca545d4d6a03bf78dc89"
69
+ "gitHead": "318762a9d5dcdd74303ca30b095fed355a1ab21f"
76
70
  }
@@ -1 +0,0 @@
1
- export { useCollectionViewport, type CollectionViewportHandle } from "./views/use-collection-viewport.svelte.js";
@@ -1,3 +0,0 @@
1
- // `@runic-artifex/svelte/experimental`: helpers whose shape may still change in a minor release
2
- // (docs/experimental.md). Graduation moves an export to `@runic-artifex/svelte`.
3
- export { useCollectionViewport } from "./views/use-collection-viewport.svelte.js";