@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 +132 -9
- package/dist/index.d.ts +25 -3
- package/dist/index.js +37 -4
- package/dist/menu-bar.d.ts +30 -0
- package/dist/menu-bar.js +76 -0
- package/package.json +6 -6
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={!
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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;
|
package/dist/menu-bar.js
ADDED
|
@@ -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.
|
|
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.
|
|
33
|
+
"@runic-artifex/views": "0.12.0"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
|
-
"@runic-artifex/views": "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": "
|
|
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.
|
|
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": "
|
|
64
|
+
"gitHead": "cb95ea2838ba61c7a24b9cda05bf5f0bd6fcc2d7"
|
|
65
65
|
}
|