@runic-artifex/react 0.16.0 → 0.17.1
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 +58 -21
- package/dist/index.d.ts +42 -13
- package/dist/index.js +43 -6
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -199,8 +199,10 @@ same on every render. `aria-invalid` is true while the field has `errors` or an
|
|
|
199
199
|
`errors` holds the member's validation messages from the descriptor (`[]` when valid), `error` why the latest write
|
|
200
200
|
or text failed (a `BridgeError` or a `FieldError`, whose `kind` is `rejected`, `conflict`, `committed-with-error` or
|
|
201
201
|
`invalid-text`). `FieldError`, `FieldOptions`, `FieldState` and `BridgeField` are exported from this package. See the
|
|
202
|
-
[field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
203
|
-
and text forms.
|
|
202
|
+
[field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#fields) for the receipts
|
|
203
|
+
and text forms. An `invalid-text` error has a `reason` and `arguments`: render `useText(name.error)` after
|
|
204
|
+
`configureFieldErrorText` to show your own text for it in the window's language
|
|
205
|
+
([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#translating-field-errors)).
|
|
204
206
|
|
|
205
207
|
#### Row cells and nested members
|
|
206
208
|
|
|
@@ -217,7 +219,7 @@ function LineRow({ invoice, line }: { invoice: InvoiceView; line: InvoiceLine })
|
|
|
217
219
|
```
|
|
218
220
|
|
|
219
221
|
Such a field always writes checked, conflicts only when another writer changed the same cell, and shows the messages
|
|
220
|
-
.NET reports at the cell's validation path. See [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
222
|
+
.NET reports at the cell's validation path. See [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/react/../views/README.md#fields-below-a-member-and-row-cells).
|
|
221
223
|
|
|
222
224
|
### Forms: `useForm(fields, options?)`
|
|
223
225
|
|
|
@@ -233,7 +235,7 @@ const form = useForm({ title, step }, { dirty: editor.state?.isDirty });
|
|
|
233
235
|
### Text inputs: `useTextField(view, read, write, options?)`
|
|
234
236
|
|
|
235
237
|
Binds a controlled text input to a member through the framework-neutral
|
|
236
|
-
[text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
238
|
+
[text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#text-inputs)
|
|
237
239
|
while the component is mounted. `read` and `write` may close over render values:
|
|
238
240
|
|
|
239
241
|
```tsx
|
|
@@ -312,9 +314,16 @@ const { state } = useSuspenseView(page, { releaseTimeout: 30_000 });
|
|
|
312
314
|
`<ViewOutlet content={reference} registry={pages} fallback={…} />` renders the
|
|
313
315
|
component registered for `reference.kind` with the reference as its `page`
|
|
314
316
|
prop. Declare the registry with `satisfies ViewRegistry<State["main"]>` so each
|
|
315
|
-
kind has a component whose `page` prop matches. A
|
|
316
|
-
|
|
317
|
-
|
|
317
|
+
kind has a component whose `page` prop matches. A component whose `page` is a
|
|
318
|
+
shared page reference, such as `ResultPagePageReference` of a .NET
|
|
319
|
+
[`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/react/../../dotnet/Runic.Application.Views/README.md#shared-clients)
|
|
320
|
+
interface, registers for each of its kinds:
|
|
321
|
+
`{ ...registryEntries(resultPageKinds, ResultPage), settings: Settings }`. A different reference
|
|
322
|
+
remounts the component, and `fallback` renders while `content` is empty. A kind
|
|
323
|
+
without a component renders an English `<p role="alert">` in a development build
|
|
324
|
+
(`process.env.NODE_ENV` is not `production`); a production build renders nothing
|
|
325
|
+
and reports the kind once through the page's error reporting
|
|
326
|
+
(`installErrorReporting`, `onBridgeDiagnostic`).
|
|
318
327
|
|
|
319
328
|
`missing` replaces that alert, for example with localized text. It receives the
|
|
320
329
|
reference whose kind has no component, and its markup (including any `role`) is yours:
|
|
@@ -416,7 +425,7 @@ neither.
|
|
|
416
425
|
## `useOperation(start, options?)`
|
|
417
426
|
|
|
418
427
|
Observes a generated `start<Command>()` operation through the framework-neutral
|
|
419
|
-
[operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
428
|
+
[operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#operation-feedback-and-latest-selection).
|
|
420
429
|
`run(...args)` calls the latest `start`, so it may close over the current client:
|
|
421
430
|
|
|
422
431
|
```tsx
|
|
@@ -448,7 +457,7 @@ controller's options.
|
|
|
448
457
|
|
|
449
458
|
Admits only the newest of several reads, for example loading the item the user
|
|
450
459
|
selected last, through the framework-neutral
|
|
451
|
-
[latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
460
|
+
[latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#operation-feedback-and-latest-selection).
|
|
452
461
|
Each `run(intent)` replaces the queued intent and cancels the active read; the next
|
|
453
462
|
read starts only after the previous one reaches its terminal status and the intent's
|
|
454
463
|
optional `waitForCompletion` barrier:
|
|
@@ -479,7 +488,7 @@ It wraps `onBridgeConnection` from `@runic-artifex/views` (re-exported here sinc
|
|
|
479
488
|
`{ state }`, where `state` is a `BridgeConnectionState`: `connecting`,
|
|
480
489
|
`connected`, `reconnecting`, `lost` or `closed` (the application closed the
|
|
481
490
|
window, since 0.15; a closed set, see
|
|
482
|
-
[Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
491
|
+
[Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#connection-state)):
|
|
483
492
|
|
|
484
493
|
```tsx
|
|
485
494
|
import { useBridgeConnection } from "@runic-artifex/react";
|
|
@@ -500,7 +509,7 @@ subscribes again; an invalid one throws a `RangeError`. A server render reads
|
|
|
500
509
|
Follows the declared menu bar of a Runic Desktop window that leaves it to the
|
|
501
510
|
page (`DesktopMenuBarPresentation.Page`) while the component is mounted. It
|
|
502
511
|
wraps `createMenuBarController` from `@runic-artifex/views` (see
|
|
503
|
-
[In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
512
|
+
[In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a
|
|
504
513
|
`MenuBarState`, and the bar is rendered by the menubar component of the
|
|
505
514
|
application's own UI library. Runic ships no menubar component.
|
|
506
515
|
|
|
@@ -530,7 +539,7 @@ The controller starts in an effect, so a server render reads `connecting`, and
|
|
|
530
539
|
|
|
531
540
|
Base UI's `Menubar` (`@base-ui/react`, the base of shadcn/ui's Base UI
|
|
532
541
|
Menubar) with a controlled open menu; the
|
|
533
|
-
[Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
542
|
+
[Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
|
|
534
543
|
items and is tested with real keys:
|
|
535
544
|
|
|
536
545
|
```tsx
|
|
@@ -587,9 +596,22 @@ Shows a text reference that a ViewModel produced, such as a status line or a
|
|
|
587
596
|
validation error's `text`, in the window's language, and renders again when the
|
|
588
597
|
language changes. A string shows as it is; `null` and `undefined` show
|
|
589
598
|
`fallback`. Connect the page's Translations runtime once with
|
|
590
|
-
`configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
599
|
+
`configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
|
|
591
600
|
`useWindowLocale()` reads the window's locale.
|
|
592
601
|
|
|
602
|
+
`useTextLocale()` renders the locale that text is shown in, and renders again
|
|
603
|
+
when it changes. Call it in a component that renders the page's own messages,
|
|
604
|
+
so `m.*()` runs again after a language switch; the component's children render
|
|
605
|
+
with it, except memoized ones. `syncDocumentLocale()`, once in `main.tsx`, keeps
|
|
606
|
+
`<html lang dir>` on that locale.
|
|
607
|
+
|
|
608
|
+
```tsx
|
|
609
|
+
function Toolbar() {
|
|
610
|
+
useTextLocale();
|
|
611
|
+
return <button>{m.save()}</button>;
|
|
612
|
+
}
|
|
613
|
+
```
|
|
614
|
+
|
|
593
615
|
```tsx
|
|
594
616
|
const status = useText(view.state?.status);
|
|
595
617
|
<p>{status}</p>
|
|
@@ -598,6 +620,21 @@ function ErrorLine({ error }: { error: BridgeValidationMessage }) {
|
|
|
598
620
|
}
|
|
599
621
|
```
|
|
600
622
|
|
|
623
|
+
## `useAppearance()`
|
|
624
|
+
|
|
625
|
+
Renders the page's appearance and renders again when it changes: the colour
|
|
626
|
+
scheme, contrast and reduced motion of the page's engine, combined with the
|
|
627
|
+
desktop's text scale, accent colour, forced-colours palette, contrast and motion
|
|
628
|
+
that a Runic host pushes ([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/views/README.md#appearance)). The server snapshot
|
|
629
|
+
has every member `null`.
|
|
630
|
+
|
|
631
|
+
```tsx
|
|
632
|
+
function Shell({ children }: { readonly children: ReactNode }) {
|
|
633
|
+
const { textScale, reducedMotion } = useAppearance();
|
|
634
|
+
return <main style={{ fontSize: `${textScale ?? 1}rem` }} data-motion={reducedMotion ? "reduce" : "full"}>{children}</main>;
|
|
635
|
+
}
|
|
636
|
+
```
|
|
637
|
+
|
|
601
638
|
## Errors
|
|
602
639
|
|
|
603
640
|
The `error` of `useView` and of a command or operation handle is typed
|
|
@@ -615,7 +652,7 @@ const offline = isBridgeError(error, "disconnected");
|
|
|
615
652
|
```
|
|
616
653
|
|
|
617
654
|
`instanceof` holds for errors from every copy of the package on the page.
|
|
618
|
-
[Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
655
|
+
[Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#errors-and-diagnostics)
|
|
619
656
|
lists the kinds. Any other value, such as an exception that your own connect
|
|
620
657
|
function or command callback throws, arrives unchanged.
|
|
621
658
|
|
|
@@ -657,11 +694,11 @@ the application's own dialog.
|
|
|
657
694
|
such as a close during the page's first render, is answered by the
|
|
658
695
|
ViewModel's .NET fallback handler, or fails closed without one.
|
|
659
696
|
|
|
660
|
-
The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
697
|
+
The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
|
|
661
698
|
has the .NET side and which View answers which departure. In a frontend test,
|
|
662
699
|
the generated mock's `interactions.<name>.request(input)` resolves with the
|
|
663
700
|
registered handler's answer; see the
|
|
664
|
-
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
701
|
+
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#testing).
|
|
665
702
|
|
|
666
703
|
## View requests
|
|
667
704
|
|
|
@@ -688,14 +725,14 @@ the page painted the state the request was raised with, so the field of that
|
|
|
688
725
|
state is rendered; `signal` aborts when the handler is replaced or removed, the
|
|
689
726
|
client is disposed or the connection is lost. A request is never replayed: one
|
|
690
727
|
raised before the effect ran, or while the page is disconnected, is not
|
|
691
|
-
delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
728
|
+
delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#view-requests) for the rules, and in a frontend
|
|
692
729
|
test raise one with the generated mock's `requests.<name>.raise(input)` (the
|
|
693
|
-
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
730
|
+
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#testing)).
|
|
694
731
|
|
|
695
732
|
## `useCollectionViewport(options)`
|
|
696
733
|
|
|
697
734
|
Follows a fixed-row-height scroll container and returns `{ viewport, ref }`.
|
|
698
|
-
`viewport` is the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
735
|
+
`viewport` is the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#collectionviewportoptions)
|
|
699
736
|
range for the container; it changes only when the range or sizes change. Send
|
|
700
737
|
the range to the ViewModel from an effect:
|
|
701
738
|
|
|
@@ -714,7 +751,7 @@ return <div ref={ref} style={{ height: 480, overflow: "auto" }}>
|
|
|
714
751
|
|
|
715
752
|
## `useQueryCollection(collection, options)`
|
|
716
753
|
|
|
717
|
-
Follows a scroll container for a [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
754
|
+
Follows a scroll container for a [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it
|
|
718
755
|
loads the rows the container shows, with placeholders until they arrive, and lays them out with variable heights
|
|
719
756
|
(`estimateSize` for rows not measured yet). It returns the `QueryViewport` (`items` with `top` and `size`, `totalSize`,
|
|
720
757
|
`total`, `query`, `loading`, `error`), `ref` for the container, `measure(index)` for each row, and `scrollToKey`,
|
|
@@ -738,4 +775,4 @@ The package re-exports `installBackNavigation`, `installNavigationPath`,
|
|
|
738
775
|
`@runic-artifex/views` (since 0.16). Call the installs once where the page
|
|
739
776
|
starts, before or after mounting: the mouse's Back button and Alt+Left then go
|
|
740
777
|
back in the .NET window, and `#/customers/42` follows its path region. See
|
|
741
|
-
[Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
778
|
+
[Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/views/README.md#back-and-the-url).
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type ComponentType, type HTMLAttributes, type ReactNode } from "react";
|
|
2
|
-
import { type BridgeConnectionOptions, type BridgeConnectionState, type BridgeField, type BridgeOperation, type BridgeOutcomeFailure, type FieldDefinition, type FieldOptions, type FieldState, type LatestOperationController, type LatestOperationState, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type TextReference, type RegionCollection, type RegionEntry, type ViewClient, type ViewSource } from "@runic-artifex/views";
|
|
2
|
+
import { type Appearance, type BridgeConnectionOptions, type BridgeConnectionState, type BridgeField, type BridgeOperation, type BridgeOutcomeFailure, type FieldDefinition, type FieldOptions, type FieldState, type LatestOperationController, type LatestOperationState, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type ViewRegistryPage, type FieldError, type TextReference, type RegionCollection, type RegionEntry, 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. While the same reference connects again it stays the last state. */
|
|
5
5
|
readonly state: TClient["snapshot"] | undefined;
|
|
@@ -61,15 +61,15 @@ export declare function useView<TClient extends ViewClient>(source: ViewSource<T
|
|
|
61
61
|
export declare function useViewState<TClient extends ViewClient, TSelected>(view: ViewHandle<TClient> | TClient | null | undefined, selector: (state: TClient["snapshot"]) => TSelected, isEqual?: (left: TSelected, right: TSelected) => boolean): TSelected | undefined;
|
|
62
62
|
/**
|
|
63
63
|
* A build-known map checks each generated reference kind against its component's `page` prop. A nullable
|
|
64
|
-
* reference, such as a region slot's `State["main"]`, checks its non-null kinds.
|
|
64
|
+
* reference, such as a region slot's `State["main"]`, checks its non-null kinds. A component whose `page` is a shared
|
|
65
|
+
* page reference (`[RunicSharedClient]`), such as `ResultPagePageReference`, registers for each of its kinds.
|
|
65
66
|
*/
|
|
66
67
|
export type ViewRegistry<R extends PageReference | null | undefined> = {
|
|
67
|
-
readonly [K in NonNullable<R>["kind"]]:
|
|
68
|
-
readonly page: Extract<NonNullable<R>, {
|
|
69
|
-
readonly kind: K;
|
|
70
|
-
}>;
|
|
71
|
-
}>;
|
|
68
|
+
readonly [K in NonNullable<R>["kind"]]: PageComponent<ViewRegistryPage<R, K>>;
|
|
72
69
|
};
|
|
70
|
+
type PageComponent<P> = P extends unknown ? ComponentType<{
|
|
71
|
+
readonly page: P;
|
|
72
|
+
}> : never;
|
|
73
73
|
export interface ViewOutletProps<R extends PageReference> {
|
|
74
74
|
/** The presented reference, such as `state.main`. */
|
|
75
75
|
readonly content: R | null | undefined;
|
|
@@ -77,15 +77,17 @@ export interface ViewOutletProps<R extends PageReference> {
|
|
|
77
77
|
/** Rendered while there is no content. Defaults to nothing. */
|
|
78
78
|
readonly fallback?: ReactNode;
|
|
79
79
|
/**
|
|
80
|
-
* Renders a reference whose kind has no registered component, for example localized text.
|
|
81
|
-
*
|
|
80
|
+
* Renders a reference whose kind has no registered component, for example localized text. Without it, a
|
|
81
|
+
* development build renders an English `<p role="alert">` and a production build renders nothing and reports the
|
|
82
|
+
* kind through the page's error reporting.
|
|
82
83
|
*/
|
|
83
84
|
readonly missing?: (content: R) => ReactNode;
|
|
84
85
|
}
|
|
85
86
|
/**
|
|
86
87
|
* Renders the registered component for a generated View reference and passes
|
|
87
88
|
* the reference as its `page` prop. A different reference remounts the
|
|
88
|
-
* component. A kind without a component renders `missing
|
|
89
|
+
* component. A kind without a component renders `missing`; without it, an English alert in development, and
|
|
90
|
+
* nothing in production, where the kind is reported (`installErrorReporting`, `onBridgeDiagnostic`).
|
|
89
91
|
*/
|
|
90
92
|
export declare function ViewOutlet<R extends PageReference>({ content, registry, fallback, missing }: ViewOutletProps<R>): ReactNode;
|
|
91
93
|
/** How {@link RegionOutlets} renders the regions of a collection. */
|
|
@@ -353,7 +355,8 @@ export declare function useBridgeConnection(options?: BridgeConnectionOptions):
|
|
|
353
355
|
* Renders a text reference that a ViewModel produced, such as a status line or a validation message's `text`, in the
|
|
354
356
|
* window's language (`resolveText`), and renders again when the language changes. A string renders as it is;
|
|
355
357
|
* `null` and `undefined` render `fallback`. Configure the page's Translations runtime once with
|
|
356
|
-
* `configureTranslatedText`; without one, a reference shows its fallback text.
|
|
358
|
+
* `configureTranslatedText`; without one, a reference shows its fallback text. A field's `FieldError` renders the
|
|
359
|
+
* application's text for it (`configureFieldErrorText`), or its English message: `useText(name.error)`.
|
|
357
360
|
*
|
|
358
361
|
* ```tsx
|
|
359
362
|
* const status = useText(view.state?.status);
|
|
@@ -362,12 +365,37 @@ export declare function useBridgeConnection(options?: BridgeConnectionOptions):
|
|
|
362
365
|
* function ErrorLine({ error }) { return <li>{useText(error.text, error.message)}</li>; }
|
|
363
366
|
* ```
|
|
364
367
|
*/
|
|
365
|
-
export declare function useText(value: TextReference | string | null | undefined, fallback?: string): string;
|
|
368
|
+
export declare function useText(value: TextReference | FieldError | string | null | undefined, fallback?: string): string;
|
|
366
369
|
/**
|
|
367
370
|
* Renders the window's locale that the application set (`IRunicWindowLocale` in .NET), or `null` while it sets none,
|
|
368
371
|
* for example to set `lang` on an element. The server snapshot is `null`.
|
|
369
372
|
*/
|
|
370
373
|
export declare function useWindowLocale(): string | null;
|
|
374
|
+
/**
|
|
375
|
+
* Renders the page's appearance (`appearance` from `@runic-artifex/views`): the colour scheme, contrast and reduced
|
|
376
|
+
* motion of the page's engine combined with the desktop's values that a Runic host pushes (`appearance/1`), which also
|
|
377
|
+
* carry the text scale, the accent colour and the forced-colours palette. Renders again when any of them changes. The
|
|
378
|
+
* server snapshot has every member `null`.
|
|
379
|
+
*
|
|
380
|
+
* ```tsx
|
|
381
|
+
* const { textScale, reducedMotion } = useAppearance();
|
|
382
|
+
* ```
|
|
383
|
+
*/
|
|
384
|
+
export declare function useAppearance(): Appearance;
|
|
385
|
+
/**
|
|
386
|
+
* Renders the locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's
|
|
387
|
+
* locale), and renders again when it changes. Call it in a component that renders the page's own messages, so that
|
|
388
|
+
* `m.*()` runs again after a language switch; the component's children render with it, except memoized ones.
|
|
389
|
+
* `undefined` while the page has no Translations runtime and the application sets no window locale.
|
|
390
|
+
*
|
|
391
|
+
* ```tsx
|
|
392
|
+
* function Toolbar() {
|
|
393
|
+
* useTextLocale();
|
|
394
|
+
* return <button>{m.save()}</button>;
|
|
395
|
+
* }
|
|
396
|
+
* ```
|
|
397
|
+
*/
|
|
398
|
+
export declare function useTextLocale(): string | undefined;
|
|
371
399
|
export { retrySuspenseView, useSuspenseView, type SuspenseViewHandle, type SuspenseViewOptions } from "./suspense.js";
|
|
372
400
|
export { useCollectionViewport, type CollectionViewportHandle } from "./viewport.js";
|
|
373
401
|
export { useForm, type FormFieldHandle, type FormHandle, type UseFormOptions } from "./form.js";
|
|
@@ -377,6 +405,7 @@ export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnection
|
|
|
377
405
|
export { upload, type BlobRef, type RunicBlob, type UploadOptions, type UploadProgress } from "@runic-artifex/views";
|
|
378
406
|
export { regionEntries, selectedRegion, type RegionCollection, type RegionEntry, type RegionOutcome, type RegionSlot, } from "@runic-artifex/views";
|
|
379
407
|
export { installBackNavigation, installNavigationPath, navigateBack, onNavigationPath, openNavigationPath, type NavigationPathChange, type NavigationPathOptions, type NavigationReply, } from "@runic-artifex/views";
|
|
380
|
-
export { configureTranslatedText, resolveText, windowLocale, type TextReference, type TextTranslations, } from "@runic-artifex/views";
|
|
408
|
+
export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, type DocumentLocaleOptions, type FieldErrorArguments, type FieldErrorReason, type FieldErrorText, type TextReference, type TextTranslations, } from "@runic-artifex/views";
|
|
409
|
+
export { appearance, onAppearance, type Appearance, type AppearanceColorScheme, type AppearanceContrast, type AppearanceSystemColors, type HostAppearance, } from "@runic-artifex/views";
|
|
381
410
|
export { FieldError, type BridgeField, type BridgeFieldConstraints, type BridgeFieldKind, type FieldBaseline, type FieldDefinition, type FieldErrorKind, type FieldOptions, type FieldState, } from "@runic-artifex/views";
|
|
382
411
|
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,6 +1,6 @@
|
|
|
1
1
|
import { createElement, useCallback, useEffect, useInsertionEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore, } from "react";
|
|
2
|
-
import { createCommandController, createLatestOperationController, createOperationController, createFieldController, createTextFieldController, createViewController, onBridgeConnection, onWindowLocale, resolveText, subscribeText, textVersion, windowLocale, regionEntries, } from "@runic-artifex/views";
|
|
3
|
-
import { isViewClient, viewSourceIdentity, viewSourcePreview } from "@runic-artifex/views/bindings";
|
|
2
|
+
import { createCommandController, createLatestOperationController, createOperationController, createFieldController, createTextFieldController, createViewController, onBridgeConnection, onWindowLocale, appearance, onAppearance, unknownAppearance, resolveText, subscribeText, textLocale, textVersion, windowLocale, regionEntries, } from "@runic-artifex/views";
|
|
3
|
+
import { isViewClient, missingViewMessage, reportMissingView, viewSourceIdentity, viewSourcePreview } 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.
|
|
6
6
|
function warnInlineConnect(tracker, connect) {
|
|
@@ -161,7 +161,8 @@ function referenceKey(reference) {
|
|
|
161
161
|
/**
|
|
162
162
|
* Renders the registered component for a generated View reference and passes
|
|
163
163
|
* the reference as its `page` prop. A different reference remounts the
|
|
164
|
-
* component. A kind without a component renders `missing
|
|
164
|
+
* component. A kind without a component renders `missing`; without it, an English alert in development, and
|
|
165
|
+
* nothing in production, where the kind is reported (`installErrorReporting`, `onBridgeDiagnostic`).
|
|
165
166
|
*/
|
|
166
167
|
export function ViewOutlet({ content, registry, fallback = null, missing }) {
|
|
167
168
|
if (!content)
|
|
@@ -170,7 +171,10 @@ export function ViewOutlet({ content, registry, fallback = null, missing }) {
|
|
|
170
171
|
if (!component) {
|
|
171
172
|
if (missing)
|
|
172
173
|
return missing(content);
|
|
173
|
-
|
|
174
|
+
if (process.env.NODE_ENV !== "production")
|
|
175
|
+
return createElement("p", { role: "alert" }, missingViewMessage(content.kind));
|
|
176
|
+
reportMissingView(content.kind);
|
|
177
|
+
return null;
|
|
174
178
|
}
|
|
175
179
|
return createElement(component, { key: referenceKey(content), page: content });
|
|
176
180
|
}
|
|
@@ -435,7 +439,8 @@ const serverConnectionState = () => "connecting";
|
|
|
435
439
|
* Renders a text reference that a ViewModel produced, such as a status line or a validation message's `text`, in the
|
|
436
440
|
* window's language (`resolveText`), and renders again when the language changes. A string renders as it is;
|
|
437
441
|
* `null` and `undefined` render `fallback`. Configure the page's Translations runtime once with
|
|
438
|
-
* `configureTranslatedText`; without one, a reference shows its fallback text.
|
|
442
|
+
* `configureTranslatedText`; without one, a reference shows its fallback text. A field's `FieldError` renders the
|
|
443
|
+
* application's text for it (`configureFieldErrorText`), or its English message: `useText(name.error)`.
|
|
439
444
|
*
|
|
440
445
|
* ```tsx
|
|
441
446
|
* const status = useText(view.state?.status);
|
|
@@ -458,6 +463,37 @@ export function useWindowLocale() {
|
|
|
458
463
|
}
|
|
459
464
|
const subscribeWindowLocale = (onChange) => onWindowLocale(() => onChange());
|
|
460
465
|
const serverWindowLocale = () => null;
|
|
466
|
+
/**
|
|
467
|
+
* Renders the page's appearance (`appearance` from `@runic-artifex/views`): the colour scheme, contrast and reduced
|
|
468
|
+
* motion of the page's engine combined with the desktop's values that a Runic host pushes (`appearance/1`), which also
|
|
469
|
+
* carry the text scale, the accent colour and the forced-colours palette. Renders again when any of them changes. The
|
|
470
|
+
* server snapshot has every member `null`.
|
|
471
|
+
*
|
|
472
|
+
* ```tsx
|
|
473
|
+
* const { textScale, reducedMotion } = useAppearance();
|
|
474
|
+
* ```
|
|
475
|
+
*/
|
|
476
|
+
export function useAppearance() {
|
|
477
|
+
return useSyncExternalStore(subscribeAppearance, appearance, serverAppearance);
|
|
478
|
+
}
|
|
479
|
+
const subscribeAppearance = (onChange) => onAppearance(() => onChange());
|
|
480
|
+
const serverAppearance = () => unknownAppearance;
|
|
481
|
+
/**
|
|
482
|
+
* Renders the locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's
|
|
483
|
+
* locale), and renders again when it changes. Call it in a component that renders the page's own messages, so that
|
|
484
|
+
* `m.*()` runs again after a language switch; the component's children render with it, except memoized ones.
|
|
485
|
+
* `undefined` while the page has no Translations runtime and the application sets no window locale.
|
|
486
|
+
*
|
|
487
|
+
* ```tsx
|
|
488
|
+
* function Toolbar() {
|
|
489
|
+
* useTextLocale();
|
|
490
|
+
* return <button>{m.save()}</button>;
|
|
491
|
+
* }
|
|
492
|
+
* ```
|
|
493
|
+
*/
|
|
494
|
+
export function useTextLocale() {
|
|
495
|
+
return useSyncExternalStore(subscribeText, textLocale, textLocale);
|
|
496
|
+
}
|
|
461
497
|
export { retrySuspenseView, useSuspenseView } from "./suspense.js";
|
|
462
498
|
export { useCollectionViewport } from "./viewport.js";
|
|
463
499
|
export { useForm } from "./form.js";
|
|
@@ -468,6 +504,7 @@ export { onBridgeConnection } from "@runic-artifex/views";
|
|
|
468
504
|
export { upload } from "@runic-artifex/views";
|
|
469
505
|
export { regionEntries, selectedRegion, } from "@runic-artifex/views";
|
|
470
506
|
export { installBackNavigation, installNavigationPath, navigateBack, onNavigationPath, openNavigationPath, } from "@runic-artifex/views";
|
|
471
|
-
export { configureTranslatedText, resolveText, windowLocale, } from "@runic-artifex/views";
|
|
507
|
+
export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, } from "@runic-artifex/views";
|
|
508
|
+
export { appearance, onAppearance, } from "@runic-artifex/views";
|
|
472
509
|
export { FieldError, } from "@runic-artifex/views";
|
|
473
510
|
export { useMenuBar, } from "./menu-bar.js";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@runic-artifex/react",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.17.1",
|
|
4
4
|
"description": "React hooks for generated Runic Views clients",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -30,10 +30,10 @@
|
|
|
30
30
|
},
|
|
31
31
|
"peerDependencies": {
|
|
32
32
|
"react": ">=18.3.0 <20",
|
|
33
|
-
"@runic-artifex/views": "0.
|
|
33
|
+
"@runic-artifex/views": "0.17.1"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
|
-
"@runic-artifex/views": "0.
|
|
36
|
+
"@runic-artifex/views": "0.17.1",
|
|
37
37
|
"@types/react": "19.3.0",
|
|
38
38
|
"@types/react-dom": "19.3.0",
|
|
39
39
|
"esbuild": "0.28.2",
|
|
@@ -53,7 +53,7 @@
|
|
|
53
53
|
"url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
|
|
54
54
|
"directory": "packages/web/react"
|
|
55
55
|
},
|
|
56
|
-
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
56
|
+
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/react#readme",
|
|
57
57
|
"bugs": {
|
|
58
58
|
"url": "https://github.com/Runic-Artifex/runic-sdk/issues"
|
|
59
59
|
},
|
|
@@ -63,5 +63,5 @@
|
|
|
63
63
|
"views",
|
|
64
64
|
"react"
|
|
65
65
|
],
|
|
66
|
-
"gitHead": "
|
|
66
|
+
"gitHead": "4f200eadd987eab9a2e38db6e8841849b743b615"
|
|
67
67
|
}
|