@runic-artifex/react 0.10.0 → 0.12.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
@@ -35,7 +35,7 @@ export function CounterPage({ page }: { page: CounterPageReference }) {
35
35
  const { state, client } = useView(page);
36
36
  const increment = useCommand(() => client?.increment());
37
37
  return <>
38
- <button disabled={!client || increment.pending} onClick={() => void increment.run()}>{state?.count ?? "…"}</button>
38
+ <button disabled={!state?.canIncrement || increment.pending} onClick={() => void increment.run()}>{state?.count ?? "…"}</button>
39
39
  {increment.error !== undefined && <p role="alert">{String(increment.error)}</p>}
40
40
  </>;
41
41
  }
@@ -131,8 +131,16 @@ const { state } = useSuspenseView(page, { releaseTimeout: 30_000 });
131
131
  component registered for `reference.kind` with the reference as its `page`
132
132
  prop. Declare the registry with `satisfies ViewRegistry<State["main"]>` so each
133
133
  kind has a component whose `page` prop matches. A different reference
134
- remounts the component; a kind without a component renders an alert, and
135
- `fallback` renders while `content` is empty.
134
+ remounts the component; a kind without a component renders an English
135
+ `<p role="alert">`, and `fallback` renders while `content` is empty.
136
+
137
+ `missing` replaces that alert, for example with localized text. It receives the
138
+ reference whose kind has no component, and its markup (including any `role`) is yours:
139
+
140
+ ```tsx
141
+ <ViewOutlet content={state?.main} registry={pages}
142
+ missing={page => <p role="alert">{t("missingView", { kind: page.kind })}</p>} />
143
+ ```
136
144
 
137
145
  ## `useCommand(command)`
138
146
 
@@ -148,6 +156,12 @@ const navigate = useCommand((name: "showWelcome" | "showCounter") => client?.[na
148
156
  <button onClick={() => void navigate.run("showWelcome")}>Welcome</button>
149
157
  ```
150
158
 
159
+ `pending` covers only this component's run. Whether .NET can run the command is
160
+ the View's state: a command without an argument publishes `can<Name>`, so a
161
+ button combines both, as in `disabled={!state?.canSave || save.pending}`, and is
162
+ disabled before the client connects. A command with an argument has the
163
+ `can<Name>(input)` query on the client instead.
164
+
151
165
  For a command that declares a failure (`[RunicFailure]` in .NET), `run` resolves the
152
166
  `BridgeOutcome`, and `failure` holds the declared failure of the latest run, typed
153
167
  from the outcome, while `error` keeps unexpected failures. Starting a run and
@@ -157,7 +171,7 @@ neither.
157
171
  ## `useOperation(start, options?)`
158
172
 
159
173
  Observes a generated `start<Command>()` operation through the framework-neutral
160
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#operation-feedback-and-latest-selection).
174
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#operation-feedback-and-latest-selection).
161
175
  `run(...args)` calls the latest `start`, so it may close over the current client:
162
176
 
163
177
  ```tsx
@@ -186,7 +200,7 @@ controller's options.
186
200
 
187
201
  Admits only the newest of several reads, for example loading the item the user
188
202
  selected last, through the framework-neutral
189
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#operation-feedback-and-latest-selection).
203
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#operation-feedback-and-latest-selection).
190
204
  Each `run(intent)` replaces the queued intent and cancels the active read; the next
191
205
  read starts only after the previous one reaches its terminal status and the intent's
192
206
  optional `waitForCompletion` barrier:
@@ -209,6 +223,115 @@ the active read. Unmounting disposes the controller like `useOperation`: pending
209
223
  resolve to `undefined` and accepted work is never cancelled. StrictMode's simulated
210
224
  unmount starts a fresh controller.
211
225
 
226
+ ## `useBridgeConnection(options?)`
227
+
228
+ Renders the page's connection to its .NET host while the component is mounted.
229
+ It wraps `onBridgeConnection` from `@runic-artifex/views` (re-exported here since 0.11, with the
230
+ `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns
231
+ `{ state }`, where `state` is a `BridgeConnectionState`: `connecting`,
232
+ `connected`, `reconnecting` or `lost` (a closed set, see
233
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#connection-state)):
234
+
235
+ ```tsx
236
+ import { useBridgeConnection } from "@runic-artifex/react";
237
+
238
+ function ConnectionBanner() {
239
+ const connection = useBridgeConnection({ lostAfter: 5_000 });
240
+ return connection.state === "lost" ? <p role="alert">The application stopped responding.</p> : null;
241
+ }
242
+ ```
243
+
244
+ The first render already has the current state. Unmounting unsubscribes, and
245
+ StrictMode's simulated unmount keeps one subscription. A changed `lostAfter`
246
+ subscribes again; an invalid one throws a `RangeError`. A server render reads
247
+ `connecting` and does not observe.
248
+
249
+ ## `useMenuBar(options?)`
250
+
251
+ Follows the declared menu bar of a Runic Desktop window that leaves it to the
252
+ page (`DesktopMenuBarPresentation.Page`) while the component is mounted. It
253
+ wraps `createMenuBarController` from `@runic-artifex/views` (see
254
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a
255
+ `MenuBarState`, and the bar is rendered by the menubar component of the
256
+ application's own UI library. Runic ships no menubar component.
257
+
258
+ ```tsx
259
+ import { useMenuBar } from "@runic-artifex/react";
260
+
261
+ function AppMenuBar() {
262
+ const [open, setOpen] = useState("");
263
+ const menuBar = useMenuBar({
264
+ onRequest: request => request.kind === "open" ? setOpen(request.menu.key) : focusFirstTrigger(),
265
+ });
266
+ // On macOS the application menu bar keeps the menus ("global"): render nothing.
267
+ if (menuBar.state.placement !== "page") return null;
268
+ // Map menuBar.state.menus to the component; an item's select handler calls menuBar.invoke(item).
269
+ }
270
+ ```
271
+
272
+ Options are those of `createMenuBarController` (`shortcuts`, `keyboard`)
273
+ without `signal`, plus `onRequest`, which receives the `focus` and `open`
274
+ requests; the latest function is called. A changed `shortcuts` or `keyboard`
275
+ creates a new controller, and unmounting disposes it, which also returns the
276
+ `shortcuts: "app"` lease. StrictMode's simulated unmount keeps one controller.
277
+ The controller starts in an effect, so a server render reads `connecting`, and
278
+ `invoke` rejects with a `BridgeError` (`disconnected`) until then.
279
+
280
+ ### With Base UI or Radix
281
+
282
+ Base UI's `Menubar` (`@base-ui/react`, the base of shadcn/ui's Base UI
283
+ Menubar) with a controlled open menu; the
284
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
285
+ items and is tested with real keys:
286
+
287
+ ```tsx
288
+ import { Menu } from "@base-ui/react/menu";
289
+ import { Menubar } from "@base-ui/react/menubar";
290
+ import { splitAccessKey, type MenuBarItem, type MenuBarMenu } from "@runic-artifex/views";
291
+ import { useMenuBar } from "@runic-artifex/react";
292
+
293
+ function AppMenuBar() {
294
+ const bar = useRef<HTMLDivElement>(null);
295
+ const [open, setOpen] = useState<string | null>(null);
296
+ const menuBar = useMenuBar({
297
+ onRequest: request => request.kind === "open"
298
+ ? setOpen(request.menu.key)
299
+ : bar.current?.querySelector<HTMLElement>("[role=menuitem]")?.focus(),
300
+ });
301
+ const { placement, menus, accessKeyHints } = menuBar.state;
302
+ if (placement !== "page") return null;
303
+ const label = (entry: MenuBarMenu | MenuBarItem) => {
304
+ const [before, key, after] = splitAccessKey(entry);
305
+ return <>{before}{accessKeyHints ? <u>{key}</u> : key}{after}</>;
306
+ };
307
+ return (
308
+ <Menubar ref={bar} aria-label="Application">
309
+ {menus.map(menu => (
310
+ <Menu.Root key={menu.key} disabled={!menu.enabled} open={open === menu.key}
311
+ onOpenChange={next => setOpen(current => next ? menu.key : current === menu.key ? null : current)}>
312
+ <Menu.Trigger>{label(menu)}</Menu.Trigger>
313
+ <Menu.Portal><Menu.Positioner align="start"><Menu.Popup>
314
+ {menu.entries.map(entry => entry.kind === "separator" ? <Menu.Separator key={entry.key} />
315
+ : entry.kind === "item" ? (
316
+ <Menu.Item key={entry.key} disabled={!entry.enabled} aria-keyshortcuts={entry.ariaKeyShortcuts}
317
+ onClick={() => void menuBar.invoke(entry)}>
318
+ {label(entry)} <kbd aria-hidden>{entry.shortcutText}</kbd>
319
+ </Menu.Item>)
320
+ : null /* a submenu: Menu.SubmenuRoot */)}
321
+ </Menu.Popup></Menu.Positioner></Menu.Portal>
322
+ </Menu.Root>
323
+ ))}
324
+ </Menubar>
325
+ );
326
+ }
327
+ ```
328
+
329
+ With Radix (`@radix-ui/react-menubar`) the open menu is the root's controlled
330
+ `value`: `<Menubar.Root value={open} onValueChange={setOpen}>`, each
331
+ `<Menubar.Menu value={menu.key}>`, and `<Menubar.Item onSelect={() => menuBar.invoke(item)}>`.
332
+ Check items are `Menubar.CheckboxItem checked`, radio groups
333
+ `Menubar.RadioGroup value` with `Menubar.RadioItem`.
334
+
212
335
  ## Errors
213
336
 
214
337
  The `error` of `useView` and of a command or operation handle is typed
@@ -223,7 +346,7 @@ const offline = error instanceof BridgeError && error.kind === "disconnected";
223
346
  ```
224
347
 
225
348
  `instanceof` holds for errors from every copy of the package on the page.
226
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#errors-and-diagnostics)
349
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#errors-and-diagnostics)
227
350
  lists the kinds. Any other value, such as an exception that your own connect
228
351
  function or command callback throws, arrives unchanged.
229
352
 
@@ -265,16 +388,16 @@ the application's own dialog.
265
388
  such as a close during the page's first render, is answered by the
266
389
  ViewModel's .NET fallback handler, or fails closed without one.
267
390
 
268
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.10.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
391
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.12.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
269
392
  has the .NET side and which View answers which departure. In a frontend test,
270
393
  the generated mock's `interactions.<name>.request(input)` resolves with the
271
394
  registered handler's answer; see the
272
- [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#testing).
395
+ [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#testing).
273
396
 
274
397
  ## `useCollectionViewport(options)`
275
398
 
276
399
  Follows a fixed-row-height scroll container and returns `{ viewport, ref }`.
277
- `viewport` is the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/views#collectionviewportoptions)
400
+ `viewport` is the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/views#collectionviewportoptions)
278
401
  range for the container; it changes only when the range or sizes change. Send
279
402
  the range to the ViewModel from an effect:
280
403
 
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { type ComponentType, type ReactNode } from "react";
2
- import { type BridgeOperation, type BridgeOutcomeFailure, type LatestOperationController, type LatestOperationState, 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: TClient["snapshot"] | undefined;
@@ -44,13 +44,18 @@ export interface ViewOutletProps<R extends PageReference> {
44
44
  readonly registry: ViewRegistry<R>;
45
45
  /** Rendered while there is no content. Defaults to nothing. */
46
46
  readonly fallback?: ReactNode;
47
+ /**
48
+ * Renders a reference whose kind has no registered component, for example localized text.
49
+ * Defaults to an English `<p role="alert">`.
50
+ */
51
+ readonly missing?: (content: R) => ReactNode;
47
52
  }
48
53
  /**
49
54
  * Renders the registered component for a generated View reference and passes
50
55
  * the reference as its `page` prop. A different reference remounts the
51
- * component. A kind without a component renders an alert.
56
+ * component. A kind without a component renders `missing`, or an English alert without it.
52
57
  */
53
- export declare function ViewOutlet<R extends PageReference>({ content, registry, fallback }: ViewOutletProps<R>): ReactNode;
58
+ export declare function ViewOutlet<R extends PageReference>({ content, registry, fallback, missing }: ViewOutletProps<R>): ReactNode;
54
59
  export interface CommandHandle<TArgs extends readonly unknown[], TResult, TFailure = BridgeOutcomeFailure<TResult>> {
55
60
  /**
56
61
  * Runs the command. Resolves to its result, including a `BridgeOutcome` with a
@@ -118,5 +123,22 @@ export interface LatestOperationHandle<TResult, TFailure = never> extends Latest
118
123
  * ```
119
124
  */
120
125
  export declare function useLatestOperation<TResult = void, TFailure = never>(): LatestOperationHandle<TResult, TFailure>;
126
+ export interface BridgeConnectionHandle {
127
+ /** The connection to the .NET host, as `onBridgeConnection` reports it. */
128
+ readonly state: BridgeConnectionState;
129
+ }
130
+ /**
131
+ * Renders the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`
132
+ * or `lost`) while the component is mounted, through `onBridgeConnection`. A changed
133
+ * `lostAfter` subscribes again. The server snapshot is `connecting`.
134
+ *
135
+ * ```tsx
136
+ * const connection = useBridgeConnection();
137
+ * {connection.state === "lost" && <p role="alert">The application stopped responding.</p>}
138
+ * ```
139
+ */
140
+ export declare function useBridgeConnection(options?: BridgeConnectionOptions): BridgeConnectionHandle;
121
141
  export { retrySuspenseView, useSuspenseView, type SuspenseViewHandle, type SuspenseViewOptions } from "./suspense.js";
122
142
  export { useCollectionViewport, type CollectionViewportHandle } from "./viewport.js";
143
+ export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
144
+ 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 { createElement, useCallback, useEffect, useInsertionEffect, useReducer, useRef, useState, useSyncExternalStore, } from "react";
2
- import { createCommandController, createLatestOperationController, createOperationController, createViewController, } from "@runic-artifex/views";
2
+ import { createCommandController, createLatestOperationController, createOperationController, createViewController, onBridgeConnection, } from "@runic-artifex/views";
3
3
  import { isViewClient, viewSourceIdentity } from "@runic-artifex/views/bindings";
4
4
  // An inline `{ connect: () => connectX() }` creates a new function on every
5
5
  // render, so every render reconnects and each connection renders again.
@@ -106,14 +106,17 @@ function referenceKey(reference) {
106
106
  /**
107
107
  * Renders the registered component for a generated View reference and passes
108
108
  * the reference as its `page` prop. A different reference remounts the
109
- * component. A kind without a component renders an alert.
109
+ * component. A kind without a component renders `missing`, or an English alert without it.
110
110
  */
111
- export function ViewOutlet({ content, registry, fallback = null }) {
111
+ export function ViewOutlet({ content, registry, fallback = null, missing }) {
112
112
  if (!content)
113
113
  return fallback;
114
114
  const component = registry[content.kind];
115
- if (!component)
115
+ if (!component) {
116
+ if (missing)
117
+ return missing(content);
116
118
  return createElement("p", { role: "alert" }, `No web component is registered for ${content.kind}.`);
119
+ }
117
120
  return createElement(component, { key: referenceKey(content), page: content });
118
121
  }
119
122
  // A command or operation controller lives while its component is mounted: unmounting disposes it,
@@ -206,5 +209,35 @@ export function useLatestOperation() {
206
209
  const current = useSyncExternalStore(controller.subscribe, read, read);
207
210
  return { ...current, run: controller.run, clear: controller.clear };
208
211
  }
212
+ // The state before the component subscribes: a subscription reports it at once.
213
+ function currentBridgeConnection(options) {
214
+ let current = "connecting";
215
+ onBridgeConnection(state => { current = state; }, options)();
216
+ return current;
217
+ }
218
+ /**
219
+ * Renders the page's connection to its .NET host (`connecting`, `connected`, `reconnecting`
220
+ * or `lost`) while the component is mounted, through `onBridgeConnection`. A changed
221
+ * `lostAfter` subscribes again. The server snapshot is `connecting`.
222
+ *
223
+ * ```tsx
224
+ * const connection = useBridgeConnection();
225
+ * {connection.state === "lost" && <p role="alert">The application stopped responding.</p>}
226
+ * ```
227
+ */
228
+ export function useBridgeConnection(options = {}) {
229
+ const { lostAfter } = options;
230
+ const [store] = useState(() => ({ state: undefined }));
231
+ const subscribe = useCallback((onChange) => onBridgeConnection(state => {
232
+ store.state = state;
233
+ onChange();
234
+ }, lostAfter === undefined ? {} : { lostAfter }), [store, lostAfter]);
235
+ const read = useCallback(() => store.state ??= currentBridgeConnection(lostAfter === undefined ? {} : { lostAfter }), [store, lostAfter]);
236
+ const state = useSyncExternalStore(subscribe, read, serverConnectionState);
237
+ return { state };
238
+ }
239
+ const serverConnectionState = () => "connecting";
209
240
  export { retrySuspenseView, useSuspenseView } from "./suspense.js";
210
241
  export { useCollectionViewport } from "./viewport.js";
242
+ export { onBridgeConnection } from "@runic-artifex/views";
243
+ export { useMenuBar, } from "./menu-bar.js";
@@ -0,0 +1,30 @@
1
+ import { type MenuBarController, type MenuBarControllerOptions, type MenuBarRequest, type MenuBarState } from "@runic-artifex/views";
2
+ export type { MenuBarEntry, MenuBarInvokeResult, MenuBarItem, MenuBarMenu, MenuBarRequest, MenuBarSeparator, MenuBarState, } from "@runic-artifex/views";
3
+ export interface UseMenuBarOptions extends Omit<MenuBarControllerOptions, "signal"> {
4
+ /**
5
+ * Receives the `focus` (Alt tap, F10) and `open` (Alt plus a menu's access key) requests: focus the first trigger
6
+ * or open the menu in the menubar component. The latest function is called.
7
+ */
8
+ readonly onRequest?: (request: MenuBarRequest) => void;
9
+ }
10
+ export interface MenuBarHandle {
11
+ /** The menu bar as the page renders it; render a bar only when `placement` is `"page"`. */
12
+ readonly state: MenuBarState;
13
+ /** Runs an item through the native bar's command path. Rejects with a BridgeError before the hook connected. */
14
+ readonly invoke: MenuBarController["invoke"];
15
+ /** Matches a `keydown` event against the items' shortcuts, for the `shortcuts: "app"` option. */
16
+ readonly handleKeyDown: MenuBarController["handleKeyDown"];
17
+ }
18
+ /**
19
+ * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) while the component is
20
+ * mounted, as headless state for the application's own menubar component, through `createMenuBarController`. Pass
21
+ * `invoke` to the component's item `onSelect`/`onClick` and map `onRequest` to it. A changed `shortcuts` or
22
+ * `keyboard` creates a new controller; unmounting disposes it. The server snapshot is `connecting`.
23
+ *
24
+ * ```tsx
25
+ * const menuBar = useMenuBar({ onRequest: request => request.kind === "open" ? setOpen(request.menu.key) : focusBar() });
26
+ * if (menuBar.state.placement !== "page") return null;
27
+ * menuBar.state.menus.map(menu => <Menubar.Menu key={menu.key}>…</Menubar.Menu>)
28
+ * ```
29
+ */
30
+ export declare function useMenuBar(options?: UseMenuBarOptions): MenuBarHandle;
@@ -0,0 +1,76 @@
1
+ import { useEffect, useInsertionEffect, useRef, useState, useSyncExternalStore } from "react";
2
+ import { BridgeError, createMenuBarController, } from "@runic-artifex/views";
3
+ // The state before a controller follows the host, as a new controller starts.
4
+ const connectingState = (shortcuts) => Object.freeze({
5
+ status: "connecting", placement: "none", shortcuts: shortcuts === "app" ? "app" : "host", accessKeyHints: false,
6
+ revision: 0, menus: Object.freeze([]),
7
+ });
8
+ // The controller listens to the window and polls the host from creation, so the effect owns it; render reads a
9
+ // store that mirrors the mounted controller.
10
+ function createMenuBarStore(shortcuts) {
11
+ const initial = connectingState(shortcuts);
12
+ const listeners = new Set();
13
+ let snapshot = initial;
14
+ let controller;
15
+ const publish = (next) => {
16
+ if (next === snapshot)
17
+ return;
18
+ snapshot = next;
19
+ for (const listener of [...listeners])
20
+ listener();
21
+ };
22
+ return {
23
+ initial,
24
+ subscribe(onChange) {
25
+ listeners.add(onChange);
26
+ return () => { listeners.delete(onChange); };
27
+ },
28
+ read: () => snapshot,
29
+ attach(mounted) {
30
+ controller = mounted;
31
+ const stop = mounted.subscribe(() => publish(mounted.current));
32
+ publish(mounted.current);
33
+ return () => {
34
+ stop();
35
+ if (controller === mounted)
36
+ controller = undefined;
37
+ };
38
+ },
39
+ invoke: item => controller
40
+ ? controller.invoke(item)
41
+ : Promise.reject(new BridgeError("disconnected", "The menu bar is not connected yet.", { route: "__runicMenuBarInvoke" })),
42
+ handleKeyDown: event => controller?.handleKeyDown(event) ?? false,
43
+ };
44
+ }
45
+ /**
46
+ * Follows the window's declared menu bar (Runic Desktop's `DesktopMenuBarPresentation.Page`) while the component is
47
+ * mounted, as headless state for the application's own menubar component, through `createMenuBarController`. Pass
48
+ * `invoke` to the component's item `onSelect`/`onClick` and map `onRequest` to it. A changed `shortcuts` or
49
+ * `keyboard` creates a new controller; unmounting disposes it. The server snapshot is `connecting`.
50
+ *
51
+ * ```tsx
52
+ * const menuBar = useMenuBar({ onRequest: request => request.kind === "open" ? setOpen(request.menu.key) : focusBar() });
53
+ * if (menuBar.state.placement !== "page") return null;
54
+ * menuBar.state.menus.map(menu => <Menubar.Menu key={menu.key}>…</Menubar.Menu>)
55
+ * ```
56
+ */
57
+ export function useMenuBar(options = {}) {
58
+ const { shortcuts, keyboard } = options;
59
+ const onRequest = useRef(options.onRequest);
60
+ useInsertionEffect(() => { onRequest.current = options.onRequest; });
61
+ const [store] = useState(() => createMenuBarStore(shortcuts));
62
+ useEffect(() => {
63
+ const controller = createMenuBarController({
64
+ ...(shortcuts === undefined ? {} : { shortcuts }),
65
+ ...(keyboard === undefined ? {} : { keyboard }),
66
+ });
67
+ controller.onRequest(request => onRequest.current?.(request));
68
+ const detach = store.attach(controller);
69
+ return () => {
70
+ detach();
71
+ controller.dispose();
72
+ };
73
+ }, [store, shortcuts, keyboard]);
74
+ const state = useSyncExternalStore(store.subscribe, store.read, () => store.initial);
75
+ return { state, invoke: store.invoke, handleKeyDown: store.handleKeyDown };
76
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/react",
3
- "version": "0.10.0",
3
+ "version": "0.12.0",
4
4
  "description": "React hooks for generated Runic Views clients",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -30,13 +30,13 @@
30
30
  },
31
31
  "peerDependencies": {
32
32
  "react": ">=18.3.0 <20",
33
- "@runic-artifex/views": "0.10.0"
33
+ "@runic-artifex/views": "0.12.0"
34
34
  },
35
35
  "devDependencies": {
36
- "@runic-artifex/views": "0.10.0",
36
+ "@runic-artifex/views": "0.12.0",
37
37
  "@types/react": "19.3.0",
38
38
  "@types/react-dom": "19.3.0",
39
- "happy-dom": "20.14.5",
39
+ "happy-dom": "21.0.4",
40
40
  "react": "19.3.0",
41
41
  "react-dom": "19.3.0",
42
42
  "typescript": "6.0.3",
@@ -51,7 +51,7 @@
51
51
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
52
52
  "directory": "packages/web/react"
53
53
  },
54
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.10.0/packages/web/react#readme",
54
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.12.0/packages/web/react#readme",
55
55
  "bugs": {
56
56
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
57
57
  },
@@ -61,5 +61,5 @@
61
61
  "views",
62
62
  "react"
63
63
  ],
64
- "gitHead": "fcc71ba13aa56c8f1a720909c1074825a1f5dd6f"
64
+ "gitHead": "cb95ea2838ba61c7a24b9cda05bf5f0bd6fcc2d7"
65
65
  }