@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 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.16.0/packages/web/views#fields) for the receipts
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.16.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.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.16.0/packages/web/views#text-inputs)
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 different reference
316
- remounts the component; a kind without a component renders an English
317
- `<p role="alert">`, and `fallback` renders while `content` is empty.
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.16.0/packages/web/views#operation-feedback-and-latest-selection).
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.16.0/packages/web/views#operation-feedback-and-latest-selection).
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.16.0/packages/web/views#connection-state)):
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.16.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.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.16.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.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.16.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
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.16.0/packages/web/views#errors-and-diagnostics)
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.16.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
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.16.0/packages/web/views#testing).
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.16.0/packages/web/views#view-requests) for the rules, and in a frontend
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.16.0/packages/web/views#testing)).
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.16.0/packages/web/views#collectionviewportoptions)
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.16.0/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it
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.16.0/packages/web/views/README.md#back-and-the-url).
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"]]: ComponentType<{
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
- * Defaults to an English `<p role="alert">`.
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`, or an English alert without it.
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`, or an English alert without it.
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
- return createElement("p", { role: "alert" }, `No web component is registered for ${content.kind}.`);
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.16.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.16.0"
33
+ "@runic-artifex/views": "0.17.1"
34
34
  },
35
35
  "devDependencies": {
36
- "@runic-artifex/views": "0.16.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.16.0/packages/web/react#readme",
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": "ff96e52727212344c407489283a9cafc614f0270"
66
+ "gitHead": "4f200eadd987eab9a2e38db6e8841849b743b615"
67
67
  }