@runic-artifex/react 0.19.0 → 0.20.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 +27 -21
- package/dist/index.d.ts +3 -1
- package/dist/index.js +10 -3
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -199,10 +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.
|
|
202
|
+
[field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#fields) for the receipts
|
|
203
203
|
and text forms. An `invalid-text` error has a `reason` and `arguments`: render `useText(name.error)` after
|
|
204
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.
|
|
205
|
+
([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#translating-field-errors)).
|
|
206
206
|
|
|
207
207
|
#### Row cells and nested members
|
|
208
208
|
|
|
@@ -219,7 +219,7 @@ function LineRow({ invoice, line }: { invoice: InvoiceView; line: InvoiceLine })
|
|
|
219
219
|
```
|
|
220
220
|
|
|
221
221
|
Such a field always writes checked, conflicts only when another writer changed the same cell, and shows the messages
|
|
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.
|
|
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.20.0/packages/web/react/../views/README.md#fields-below-a-member-and-row-cells).
|
|
223
223
|
|
|
224
224
|
### Forms: `useForm(fields, options?)`
|
|
225
225
|
|
|
@@ -235,7 +235,7 @@ const form = useForm({ title, step }, { dirty: editor.state?.isDirty });
|
|
|
235
235
|
### Text inputs: `useTextField(view, read, write, options?)`
|
|
236
236
|
|
|
237
237
|
Binds a controlled text input to a member through the framework-neutral
|
|
238
|
-
[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.20.0/packages/web/views#text-inputs)
|
|
239
239
|
while the component is mounted. `read` and `write` may close over render values:
|
|
240
240
|
|
|
241
241
|
```tsx
|
|
@@ -316,7 +316,7 @@ component registered for `reference.kind` with the reference as its `page`
|
|
|
316
316
|
prop. Declare the registry with `satisfies ViewRegistry<State["main"]>` so each
|
|
317
317
|
kind has a component whose `page` prop matches. A component whose `page` is a
|
|
318
318
|
shared page reference, such as `ResultPagePageReference` of a .NET
|
|
319
|
-
[`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
319
|
+
[`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/react/../../dotnet/Runic.Application.Views/README.md#shared-clients)
|
|
320
320
|
interface, registers for each of its kinds:
|
|
321
321
|
`{ ...registryEntries(resultPageKinds, ResultPage), settings: Settings }`. A different reference
|
|
322
322
|
remounts the component, and `fallback` renders while `content` is empty. A kind
|
|
@@ -425,7 +425,7 @@ neither.
|
|
|
425
425
|
## `useOperation(start, options?)`
|
|
426
426
|
|
|
427
427
|
Observes a generated `start<Command>()` operation through the framework-neutral
|
|
428
|
-
[operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
428
|
+
[operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#operation-feedback-and-latest-selection).
|
|
429
429
|
`run(...args)` calls the latest `start`, so it may close over the current client:
|
|
430
430
|
|
|
431
431
|
```tsx
|
|
@@ -457,7 +457,7 @@ controller's options.
|
|
|
457
457
|
|
|
458
458
|
Admits only the newest of several reads, for example loading the item the user
|
|
459
459
|
selected last, through the framework-neutral
|
|
460
|
-
[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.20.0/packages/web/views#operation-feedback-and-latest-selection).
|
|
461
461
|
Each `run(intent)` replaces the queued intent and cancels the active read; the next
|
|
462
462
|
read starts only after the previous one reaches its terminal status and the intent's
|
|
463
463
|
optional `waitForCompletion` barrier:
|
|
@@ -488,7 +488,7 @@ It wraps `onBridgeConnection` from `@runic-artifex/views` (re-exported here sinc
|
|
|
488
488
|
`{ state }`, where `state` is a `BridgeConnectionState`: `connecting`,
|
|
489
489
|
`connected`, `reconnecting`, `lost` or `closed` (the application closed the
|
|
490
490
|
window, since 0.15; a closed set, see
|
|
491
|
-
[Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
491
|
+
[Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#connection-state)):
|
|
492
492
|
|
|
493
493
|
```tsx
|
|
494
494
|
import { useBridgeConnection } from "@runic-artifex/react";
|
|
@@ -509,7 +509,7 @@ subscribes again; an invalid one throws a `RangeError`. A server render reads
|
|
|
509
509
|
Follows the declared menu bar of a Runic Desktop window that leaves it to the
|
|
510
510
|
page (`DesktopMenuBarPresentation.Page`) while the component is mounted. It
|
|
511
511
|
wraps `createMenuBarController` from `@runic-artifex/views` (see
|
|
512
|
-
[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.20.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a
|
|
513
513
|
`MenuBarState`, and the bar is rendered by the menubar component of the
|
|
514
514
|
application's own UI library. Runic ships no menubar component.
|
|
515
515
|
|
|
@@ -539,7 +539,7 @@ The controller starts in an effect, so a server render reads `connecting`, and
|
|
|
539
539
|
|
|
540
540
|
Base UI's `Menubar` (`@base-ui/react`, the base of shadcn/ui's Base UI
|
|
541
541
|
Menubar) with a controlled open menu; the
|
|
542
|
-
[Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
542
|
+
[Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
|
|
543
543
|
items and is tested with real keys:
|
|
544
544
|
|
|
545
545
|
```tsx
|
|
@@ -596,7 +596,7 @@ Shows a text reference that a ViewModel produced, such as a status line or a
|
|
|
596
596
|
validation error's `text`, in the window's language, and renders again when the
|
|
597
597
|
language changes. A string shows as it is; `null` and `undefined` show
|
|
598
598
|
`fallback`. Connect the page's Translations runtime once with
|
|
599
|
-
`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.20.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
|
|
600
600
|
`useWindowLocale()` reads the window's locale.
|
|
601
601
|
|
|
602
602
|
`useTextLocale()` renders the locale that text is shown in, and renders again
|
|
@@ -605,6 +605,12 @@ so `m.*()` runs again after a language switch; the component's children render
|
|
|
605
605
|
with it, except memoized ones. `syncDocumentLocale()`, once in `main.tsx`, keeps
|
|
606
606
|
`<html lang dir>` on that locale.
|
|
607
607
|
|
|
608
|
+
In `vite dev` with the Translations Vite plugin 0.12.0 or later,
|
|
609
|
+
`useTextLocale()` also renders again when you save an edited message, with the
|
|
610
|
+
same locale, and the component keeps its state: the new text shows in place.
|
|
611
|
+
An added, removed or renamed message, or changed inputs or markup, still reload
|
|
612
|
+
the page ([Edited messages in `vite dev`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
|
|
613
|
+
|
|
608
614
|
```tsx
|
|
609
615
|
function Toolbar() {
|
|
610
616
|
useTextLocale();
|
|
@@ -625,7 +631,7 @@ function ErrorLine({ error }: { error: BridgeValidationMessage }) {
|
|
|
625
631
|
Renders the page's appearance and renders again when it changes: the colour
|
|
626
632
|
scheme, contrast and reduced motion of the page's engine, combined with the
|
|
627
633
|
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.
|
|
634
|
+
that a Runic host pushes ([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/views/README.md#appearance)). The server snapshot
|
|
629
635
|
has every member `null`.
|
|
630
636
|
|
|
631
637
|
```tsx
|
|
@@ -652,7 +658,7 @@ const offline = isBridgeError(error, "disconnected");
|
|
|
652
658
|
```
|
|
653
659
|
|
|
654
660
|
`instanceof` holds for errors from every copy of the package on the page.
|
|
655
|
-
[Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
661
|
+
[Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#errors-and-diagnostics)
|
|
656
662
|
lists the kinds. Any other value, such as an exception that your own connect
|
|
657
663
|
function or command callback throws, arrives unchanged.
|
|
658
664
|
|
|
@@ -694,11 +700,11 @@ the application's own dialog.
|
|
|
694
700
|
such as a close during the page's first render, is answered by the
|
|
695
701
|
ViewModel's .NET fallback handler, or fails closed without one.
|
|
696
702
|
|
|
697
|
-
The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
703
|
+
The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
|
|
698
704
|
has the .NET side and which View answers which departure. In a frontend test,
|
|
699
705
|
the generated mock's `interactions.<name>.request(input)` resolves with the
|
|
700
706
|
registered handler's answer; see the
|
|
701
|
-
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
707
|
+
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#testing).
|
|
702
708
|
|
|
703
709
|
## View requests
|
|
704
710
|
|
|
@@ -725,14 +731,14 @@ the page painted the state the request was raised with, so the field of that
|
|
|
725
731
|
state is rendered; `signal` aborts when the handler is replaced or removed, the
|
|
726
732
|
client is disposed or the connection is lost. A request is never replayed: one
|
|
727
733
|
raised before the effect ran, or while the page is disconnected, is not
|
|
728
|
-
delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
734
|
+
delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#view-requests) for the rules, and in a frontend
|
|
729
735
|
test raise one with the generated mock's `requests.<name>.raise(input)` (the
|
|
730
|
-
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
736
|
+
[Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#testing)).
|
|
731
737
|
|
|
732
738
|
## `useCollectionViewport(options)`
|
|
733
739
|
|
|
734
740
|
Follows a fixed-row-height scroll container and returns `{ viewport, ref }`.
|
|
735
|
-
`viewport` is the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
741
|
+
`viewport` is the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#collectionviewportoptions)
|
|
736
742
|
range for the container; it changes only when the range or sizes change. Send
|
|
737
743
|
the range to the ViewModel from an effect:
|
|
738
744
|
|
|
@@ -751,7 +757,7 @@ return <div ref={ref} style={{ height: 480, overflow: "auto" }}>
|
|
|
751
757
|
|
|
752
758
|
## `useQueryCollection(collection, options)`
|
|
753
759
|
|
|
754
|
-
Follows a scroll container for a [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
760
|
+
Follows a scroll container for a [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it
|
|
755
761
|
loads the rows the container shows, with placeholders until they arrive, and lays them out with variable heights
|
|
756
762
|
(`estimateSize` for rows not measured yet). It returns the `QueryViewport` (`items` with `top` and `size`, `totalSize`,
|
|
757
763
|
`total`, `query`, `loading`, `error`), `ref` for the container, `measure(index)` for each row, and `scrollToKey`,
|
|
@@ -775,13 +781,13 @@ The package re-exports `installBackNavigation`, `installNavigationPath`,
|
|
|
775
781
|
`@runic-artifex/views` (since 0.16). Call the installs once where the page
|
|
776
782
|
starts, before or after mounting: the mouse's Back button and Alt+Left then go
|
|
777
783
|
back in the .NET window, and `#/customers/42` follows its path region. See
|
|
778
|
-
[Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
784
|
+
[Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/views/README.md#back-and-the-url).
|
|
779
785
|
|
|
780
786
|
## Hosted regions (experimental)
|
|
781
787
|
|
|
782
788
|
`RunicHostedRegion` from `@runic-artifex/react/experimental` renders
|
|
783
789
|
`<runic-hosted-region>`, a region where the host application shows a hosted guest's
|
|
784
|
-
Window ([hosted regions](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
790
|
+
Window ([hosted regions](https://github.com/Runic-Artifex/runic-sdk/blob/v0.20.0/packages/web/react/../views/README.md#hosted-regions-experimental)). `fallback` is content, or a function of the region's
|
|
785
791
|
state, shown while no guest page shows in it:
|
|
786
792
|
|
|
787
793
|
```tsx
|
package/dist/index.d.ts
CHANGED
|
@@ -385,7 +385,9 @@ export declare function useAppearance(): Appearance;
|
|
|
385
385
|
/**
|
|
386
386
|
* Renders the locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's
|
|
387
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.
|
|
388
|
+
* `m.*()` runs again after a language switch; the component's children render with it, except memoized ones. During
|
|
389
|
+
* development it also renders again when the Runic Translations Vite plugin (0.12.0 or later) updates an edited
|
|
390
|
+
* message in place, with the component's state kept.
|
|
389
391
|
* `undefined` while the page has no Translations runtime and the application sets no window locale.
|
|
390
392
|
*
|
|
391
393
|
* ```tsx
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
import { createElement, useCallback, useEffect, useInsertionEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore, } from "react";
|
|
2
2
|
import { createCommandController, createLatestOperationController, createOperationController, createFieldController, createTextFieldController, createViewController, onBridgeConnection, onWindowLocale, appearance, onAppearance, unknownAppearance, resolveText, subscribeText, textLocale, textVersion, windowLocale, regionEntries, } from "@runic-artifex/views";
|
|
3
|
-
|
|
3
|
+
// `translationsTextRevision`: the revision of the Runic Translations text-change channel, which the Translations Vite
|
|
4
|
+
// plugin increments during development when it updates an edited message in place; always 0 in the production build of
|
|
5
|
+
// views, which has no channel.
|
|
6
|
+
import { isViewClient, missingViewMessage, reportMissingView, translationsTextRevision, viewSourceIdentity, viewSourcePreview, } from "@runic-artifex/views/bindings";
|
|
4
7
|
import { useRunicInstance } from "./instance.js";
|
|
5
8
|
// An inline `{ connect: () => connectX() }` creates a new function on every
|
|
6
9
|
// render, so every render reconnects and each connection renders again.
|
|
@@ -473,6 +476,7 @@ function instanceText(instance) {
|
|
|
473
476
|
subscribe: onChange => run(() => subscribeText(onChange)),
|
|
474
477
|
version: () => run(textVersion),
|
|
475
478
|
locale: () => run(textLocale),
|
|
479
|
+
localeSnapshot: () => `${translationsTextRevision()}\u0000${run(textLocale) ?? "\u0001"}`,
|
|
476
480
|
subscribeWindowLocale: onChange => run(() => onWindowLocale(() => onChange())),
|
|
477
481
|
windowLocale: () => run(windowLocale),
|
|
478
482
|
subscribeAppearance: onChange => run(() => onAppearance(() => onChange())),
|
|
@@ -508,7 +512,9 @@ const serverAppearance = () => unknownAppearance;
|
|
|
508
512
|
/**
|
|
509
513
|
* Renders the locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's
|
|
510
514
|
* locale), and renders again when it changes. Call it in a component that renders the page's own messages, so that
|
|
511
|
-
* `m.*()` runs again after a language switch; the component's children render with it, except memoized ones.
|
|
515
|
+
* `m.*()` runs again after a language switch; the component's children render with it, except memoized ones. During
|
|
516
|
+
* development it also renders again when the Runic Translations Vite plugin (0.12.0 or later) updates an edited
|
|
517
|
+
* message in place, with the component's state kept.
|
|
512
518
|
* `undefined` while the page has no Translations runtime and the application sets no window locale.
|
|
513
519
|
*
|
|
514
520
|
* ```tsx
|
|
@@ -520,7 +526,8 @@ const serverAppearance = () => unknownAppearance;
|
|
|
520
526
|
*/
|
|
521
527
|
export function useTextLocale() {
|
|
522
528
|
const text = instanceText(useRunicInstance());
|
|
523
|
-
|
|
529
|
+
useSyncExternalStore(text.subscribe, text.localeSnapshot, text.localeSnapshot);
|
|
530
|
+
return text.locale();
|
|
524
531
|
}
|
|
525
532
|
export { RunicInstanceProvider, useRunicInstance } from "./instance.js";
|
|
526
533
|
export { createRunicInstance, pageInstance } from "@runic-artifex/views";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@runic-artifex/react",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.20.0",
|
|
4
4
|
"description": "React hooks for generated Runic Views clients",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -35,10 +35,10 @@
|
|
|
35
35
|
},
|
|
36
36
|
"peerDependencies": {
|
|
37
37
|
"react": ">=18.3.0 <20",
|
|
38
|
-
"@runic-artifex/views": "0.
|
|
38
|
+
"@runic-artifex/views": "0.20.0"
|
|
39
39
|
},
|
|
40
40
|
"devDependencies": {
|
|
41
|
-
"@runic-artifex/views": "0.
|
|
41
|
+
"@runic-artifex/views": "0.20.0",
|
|
42
42
|
"@types/react": "19.3.0",
|
|
43
43
|
"@types/react-dom": "19.3.0",
|
|
44
44
|
"esbuild": "0.28.2",
|
|
@@ -58,7 +58,7 @@
|
|
|
58
58
|
"url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
|
|
59
59
|
"directory": "packages/web/react"
|
|
60
60
|
},
|
|
61
|
-
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
61
|
+
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.20.0/packages/web/react#readme",
|
|
62
62
|
"bugs": {
|
|
63
63
|
"url": "https://github.com/Runic-Artifex/runic-sdk/issues"
|
|
64
64
|
},
|
|
@@ -68,5 +68,5 @@
|
|
|
68
68
|
"views",
|
|
69
69
|
"react"
|
|
70
70
|
],
|
|
71
|
-
"gitHead": "
|
|
71
|
+
"gitHead": "8288005e35e9cc377ca280db1ab44b91582cd705"
|
|
72
72
|
}
|