@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 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.19.0/packages/web/views#fields) for the receipts
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.19.0/packages/web/views#translating-field-errors)).
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.19.0/packages/web/react/../views/README.md#fields-below-a-member-and-row-cells).
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.19.0/packages/web/views#text-inputs)
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.19.0/packages/web/react/../../dotnet/Runic.Application.Views/README.md#shared-clients)
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.19.0/packages/web/views#operation-feedback-and-latest-selection).
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.19.0/packages/web/views#operation-feedback-and-latest-selection).
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.19.0/packages/web/views#connection-state)):
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.19.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a
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.19.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
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.19.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
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.19.0/packages/web/views/README.md#appearance)). The server snapshot
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.19.0/packages/web/views#errors-and-diagnostics)
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.19.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
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.19.0/packages/web/views#testing).
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.19.0/packages/web/views#view-requests) for the rules, and in a frontend
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.19.0/packages/web/views#testing)).
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.19.0/packages/web/views#collectionviewportoptions)
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.19.0/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it
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.19.0/packages/web/views/README.md#back-and-the-url).
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.19.0/packages/web/react/../views/README.md#hosted-regions-experimental)). `fallback` is content, or a function of the region's
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
- import { isViewClient, missingViewMessage, reportMissingView, viewSourceIdentity, viewSourcePreview } from "@runic-artifex/views/bindings";
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
- return useSyncExternalStore(text.subscribe, text.locale, text.locale);
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.19.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.19.0"
38
+ "@runic-artifex/views": "0.20.0"
39
39
  },
40
40
  "devDependencies": {
41
- "@runic-artifex/views": "0.19.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.19.0/packages/web/react#readme",
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": "9a09c23055f09f7505552d236c8acf69bdeeb02e"
71
+ "gitHead": "8288005e35e9cc377ca280db1ab44b91582cd705"
72
72
  }