@runic-artifex/vue 0.16.0 → 0.17.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
@@ -196,8 +196,10 @@ is written. A string set on `value` of a field that is not text is taken as its
196
196
  `errors` holds the member's validation messages from the descriptor (`[]` when valid), `error` why the latest write
197
197
  or text failed (a `BridgeError` or a `FieldError`, whose `kind` is `rejected`, `conflict`, `committed-with-error` or
198
198
  `invalid-text`). `FieldError`, `FieldOptions`, `FieldState` and `BridgeField` are exported from this package. See the
199
- [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#fields) for the receipts
200
- and text forms.
199
+ [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#fields) for the receipts
200
+ and text forms. An `invalid-text` error has a `reason` and `arguments`: render `useText(() => title.error)` after
201
+ `configureFieldErrorText` to show your own text for it in the window's language
202
+ ([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#translating-field-errors)).
201
203
 
202
204
  #### Row cells and nested members
203
205
 
@@ -206,7 +208,7 @@ Since 0.16, `InvoiceFields.address.street` and `InvoiceFields.lines.at(line.id).
206
208
  `useField` in the row's component (`v-model="quantity.text"`); `at(key)` returns the same descriptor for the same
207
209
  key. Such a field always writes checked, conflicts only when another writer changed the same cell, and shows the
208
210
  messages .NET reports at the cell's validation path. See
209
- [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.16.0/packages/web/vue/../views/README.md#fields-below-a-member-and-row-cells).
211
+ [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/vue/../views/README.md#fields-below-a-member-and-row-cells).
210
212
 
211
213
  ### Forms: `useForm(fields, options?)`
212
214
 
@@ -221,7 +223,7 @@ const form = useForm({ title, step }, { dirty: () => editor.state.value?.isDirty
221
223
  ### Text inputs: `useTextField(view, read, write, options?)`
222
224
 
223
225
  Binds a text input to a member through the framework-neutral
224
- [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#text-inputs)
226
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#text-inputs)
225
227
  while the effect scope is active. Each field is a ref, so the handle can be destructured:
226
228
 
227
229
  ```vue
@@ -264,8 +266,11 @@ text at once and hides the race.
264
266
 
265
267
  Renders the component registered for a generated reference's `kind` and
266
268
  passes the reference as its `page` prop. A different reference remounts the
267
- component, a kind without a component renders an English `<p role="alert">`
268
- (or the `missing` slot), and the default slot renders while `content` is empty:
269
+ component, a kind without a component renders the `missing` slot, and the
270
+ default slot renders while `content` is empty. Without the slot, a development
271
+ build (`process.env.NODE_ENV` is not `production`) renders an English
272
+ `<p role="alert">`; a production build renders nothing and reports the kind once
273
+ through the page's error reporting (`installErrorReporting`, `onBridgeDiagnostic`):
269
274
 
270
275
  ```vue
271
276
  <script setup lang="ts">
@@ -284,7 +289,11 @@ const { state } = useView({ connect: connectWorkspace });
284
289
  ```
285
290
 
286
291
  `satisfies ViewRegistry<…>` checks that every kind has a component whose `page`
287
- prop accepts that reference.
292
+ prop accepts that reference. A component whose `page` is a shared page
293
+ reference, such as `ResultPagePageReference` of a .NET
294
+ [`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/vue/../../dotnet/Runic.Application.Views/README.md#shared-clients)
295
+ interface, registers for each of its kinds:
296
+ `{ ...registryEntries(resultPageKinds, ResultPage), settings: Settings }`.
288
297
 
289
298
  The `missing` slot replaces the English alert, for example with localized text.
290
299
  It receives `{ content }`, the reference whose kind has no component, and its
@@ -387,7 +396,7 @@ neither.
387
396
  ## `useOperation(start, options?)`
388
397
 
389
398
  Observes a generated `start<Command>()` operation through the framework-neutral
390
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#operation-feedback-and-latest-selection)
399
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#operation-feedback-and-latest-selection)
391
400
  and returns each state field as a shallow ref, with `run`, `cancel` and `reset`:
392
401
 
393
402
  ```vue
@@ -419,7 +428,7 @@ Disposing the effect scope settles run promises without cancelling accepted work
419
428
 
420
429
  Admits only the newest of several reads, for example loading the item the user
421
430
  selected last, through the framework-neutral
422
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#operation-feedback-and-latest-selection),
431
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#operation-feedback-and-latest-selection),
423
432
  and returns each state field as a shallow ref, with `run` and `clear`. Each
424
433
  `run(intent)` replaces the queued intent and cancels the active read; the next read
425
434
  starts only after the previous one reaches its terminal status and the intent's
@@ -456,7 +465,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
456
465
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a shallow ref holding a
457
466
  `BridgeConnectionState`: `connecting`, `connected`, `reconnecting`, `lost` or `closed` (the
458
467
  application closed the window, since 0.15; a closed set, see
459
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#connection-state)):
468
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#connection-state)):
460
469
 
461
470
  ```vue
462
471
  <script setup lang="ts">
@@ -479,7 +488,7 @@ development builds warn. An invalid `lostAfter` throws a `RangeError`.
479
488
  Follows the declared menu bar of a Runic Desktop window that leaves it to the
480
489
  page (`DesktopMenuBarPresentation.Page`) until the current effect scope is
481
490
  disposed. It wraps `createMenuBarController` from `@runic-artifex/views` (see
482
- [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 shallow ref
491
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a shallow ref
483
492
  of a `MenuBarState`, and the bar is rendered by the menubar component of the
484
493
  application's own UI library. Runic ships no menubar component.
485
494
 
@@ -510,7 +519,7 @@ rendering creates no controller: `state` stays `connecting`.
510
519
  ### With Reka UI
511
520
 
512
521
  Reka UI's `MenubarRoot` with `v-model` of the open menu; the
513
- [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
522
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
514
523
  items and is tested with real keys:
515
524
 
516
525
  ```vue
@@ -561,14 +570,41 @@ Shows a text reference that a ViewModel produced, such as a status line or a
561
570
  validation error's `text`, in the window's language, and renders again when the
562
571
  language changes. A string shows as it is; `null` and `undefined` show
563
572
  `fallback`. Connect the page's Translations runtime once with
564
- `configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.16.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
573
+ `configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
565
574
  `useWindowLocale()` reads the window's locale.
566
575
 
576
+ `useTextLocale()` is the locale that text is shown in, as a ref. It is one ref
577
+ for the page and needs no effect scope, so the locale resolver can read it;
578
+ templates that call `m.*()` then render again on a language switch.
579
+ `syncDocumentLocale()` keeps `<html lang dir>` on that locale:
580
+
581
+ ```ts
582
+ // main.ts
583
+ const textLocale = useTextLocale();
584
+ configureLocaleResolver(() => textLocale.value ?? locale.getLocale());
585
+ configureTranslatedText({ ...locale, resolve, direction: localeDirection });
586
+ syncDocumentLocale();
587
+ ```
588
+
567
589
  ```ts
568
590
  const status = useText(() => view.state.value?.status);
569
591
  // <p>{{ status }}</p>
570
592
  ```
571
593
 
594
+ ## `useAppearance()`
595
+
596
+ The page's appearance as a ref that renders, computes and watches again when it
597
+ changes, while the calling component or effect scope lives: the colour scheme,
598
+ contrast and reduced motion of the page's engine, combined with the desktop's
599
+ text scale, accent colour, forced-colours palette, contrast and motion that a
600
+ Runic host pushes ([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/views/README.md#appearance)). Every member is `null` under
601
+ server rendering.
602
+
603
+ ```ts
604
+ const look = useAppearance();
605
+ const fontSize = computed(() => `${look.value.textScale ?? 1}rem`);
606
+ ```
607
+
572
608
  ## Errors
573
609
 
574
610
  The `error` of `useView` and of a command or operation handle is typed
@@ -586,7 +622,7 @@ const message = computed(() => describeBridgeError(error.value));
586
622
  ```
587
623
 
588
624
  `instanceof` holds for errors from every copy of the package on the page.
589
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#errors-and-diagnostics)
625
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#errors-and-diagnostics)
590
626
  lists the kinds. Any other value, such as an exception that your own connect
591
627
  function or command callback throws, arrives unchanged.
592
628
 
@@ -633,10 +669,10 @@ application's own dialog.
633
669
  departure before that is answered by the ViewModel's .NET fallback handler, or
634
670
  fails closed without one.
635
671
 
636
- 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)
672
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
637
673
  has the .NET side and which View answers which departure. In a frontend test,
638
674
  the generated mock's `interactions.<name>.request(input)` resolves with the
639
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#testing).
675
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#testing).
640
676
 
641
677
  ## View requests
642
678
 
@@ -672,14 +708,14 @@ the page painted the state the request was raised with, so the field of that
672
708
  state is rendered; `signal` aborts when the handler is replaced or removed, the
673
709
  client is disposed or the connection is lost. A request is never replayed: one
674
710
  raised before the effect ran, or while the page is disconnected, is not
675
- 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
711
+ delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#view-requests) for the rules, and in a frontend
676
712
  test raise one with the generated mock's `requests.<name>.raise(input)` (the
677
- [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#testing)).
713
+ [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#testing)).
678
714
 
679
715
  ## `useCollectionViewport(options)`
680
716
 
681
717
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
682
- `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#collectionviewportoptions)
718
+ `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#collectionviewportoptions)
683
719
  range; `attach` is a function ref for the container. Bind it to a native element
684
720
  such as a `<div>`: a component instance (`:ref="attach"` on a component) or a
685
721
  non-HTML element detaches the viewport, and development builds warn. Pass a getter for the
@@ -703,7 +739,7 @@ watch(() => [viewport.value.start, viewport.value.size] as const, ([start, size]
703
739
 
704
740
  ## `useQueryCollection(collection, options)`
705
741
 
706
- 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
742
+ Follows a scroll container for a [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it
707
743
  loads the rows the container shows, with placeholders until they arrive, and lays them out with variable heights.
708
744
  Pass the collection or a getter (`() => client.value?.queries.rows`) and the options. `viewport` is a ref of the
709
745
  `QueryViewport` (`items` with `top` and `size`, `totalSize`, `total`, `query`, `loading`, `error`); bind `attach` to the
@@ -730,4 +766,4 @@ The package re-exports `installBackNavigation`, `installNavigationPath`,
730
766
  `@runic-artifex/views` (since 0.16). Call the installs once where the page
731
767
  starts, before or after mounting: the mouse's Back button and Alt+Left then go
732
768
  back in the .NET window, and `#/customers/42` follows its path region. See
733
- [Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.16.0/packages/web/views/README.md#back-and-the-url).
769
+ [Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/views/README.md#back-and-the-url).
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Whether the page is a development build. A page whose bundler does not replace NODE_ENV, such as Vue's esm-browser
3
+ * build through an import map, counts as production instead of throwing `process is not defined`.
4
+ */
5
+ export declare function isDevelopment(): boolean;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Whether the page is a development build. A page whose bundler does not replace NODE_ENV, such as Vue's esm-browser
3
+ * build through an import map, counts as production instead of throwing `process is not defined`.
4
+ */
5
+ export function isDevelopment() {
6
+ try {
7
+ return process.env.NODE_ENV !== "production";
8
+ }
9
+ catch {
10
+ return false;
11
+ }
12
+ }
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { type Component, type ComputedRef, type HTMLAttributes, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from "vue";
2
- import { type BridgeConnectionOptions, type BridgeConnectionState, type BridgeField, type BridgeOperation, type BridgeOutcomeFailure, type FieldBaseline, type FieldDefinition, type FieldState, type FieldOptions, type LatestOperationController, type LatestOperationState, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type TextReference, type RegionCollection, type RegionEntry, type ViewClient, type ViewConnector, type ViewSource } from "@runic-artifex/views";
2
+ import { type Appearance, type BridgeConnectionOptions, type BridgeConnectionState, type BridgeField, type BridgeOperation, type BridgeOutcomeFailure, type FieldBaseline, type FieldDefinition, type FieldState, type FieldOptions, 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 ViewConnector, type ViewSource } from "@runic-artifex/views";
3
3
  export interface ViewHandle<TClient extends ViewClient> {
4
4
  /** The latest state, or undefined until the client connects. */
5
5
  readonly state: Readonly<Ref<TClient["snapshot"] | undefined>>;
@@ -60,15 +60,15 @@ export interface SuspenseViewHandle<TClient extends ViewClient> {
60
60
  export declare function useSuspenseView<TClient extends ViewClient>(source: ViewConnector<TClient> | TClient, options?: UseViewOptions<TClient>): Promise<SuspenseViewHandle<TClient>>;
61
61
  /**
62
62
  * A build-known map checks each generated reference kind against its component's `page` prop. A nullable
63
- * reference, such as a region slot's `State["main"]`, checks its non-null kinds.
63
+ * reference, such as a region slot's `State["main"]`, checks its non-null kinds. A component whose `page` is a shared
64
+ * page reference (`[RunicSharedClient]`), such as `ResultPagePageReference`, registers for each of its kinds.
64
65
  */
65
66
  export type ViewRegistry<R extends PageReference | null | undefined> = {
66
- readonly [K in NonNullable<R>["kind"]]: Component<{
67
- page: Extract<NonNullable<R>, {
68
- readonly kind: K;
69
- }>;
70
- }>;
67
+ readonly [K in NonNullable<R>["kind"]]: PageComponent<ViewRegistryPage<R, K>>;
71
68
  };
69
+ type PageComponent<P> = P extends unknown ? Component<{
70
+ page: P;
71
+ }> : never;
72
72
  export interface ViewOutletProps<R extends PageReference> {
73
73
  /** The presented reference, such as `state.main`. */
74
74
  content: R | null | undefined;
@@ -79,7 +79,8 @@ export interface ViewOutletProps<R extends PageReference> {
79
79
  * the reference as its `page` prop. A different reference remounts the
80
80
  * component. The default slot renders while there is no content. A kind without
81
81
  * a component renders the `missing` slot, which receives `{ content }`, for example
82
- * for localized text, or an English alert without it:
82
+ * for localized text. Without the slot, a development build renders an English alert, and a production build
83
+ * renders nothing and reports the kind (`installErrorReporting`, `onBridgeDiagnostic`):
83
84
  *
84
85
  * ```vue
85
86
  * <ViewOutlet :content="state?.main" :registry="pages">
@@ -368,20 +369,47 @@ export declare function useBridgeConnection(options?: BridgeConnectionOptions):
368
369
  * language (`resolveText`), as a computed ref that follows a language switch until the effect scope stops. `source` and
369
370
  * `fallback` may be refs or getters: `useText(() => view.state.value?.status)`. A string shows as it is; `null` and
370
371
  * `undefined` show `fallback`. Configure the page's Translations runtime once with `configureTranslatedText`; without
371
- * one, a reference shows its fallback text.
372
+ * one, a reference shows its fallback text. A field's `FieldError` shows the application's text for it
373
+ * (`configureFieldErrorText`), or its English message: `useText(() => title.error)`.
372
374
  *
373
375
  * ```vue
374
376
  * const status = useText(() => view.state.value?.status);
375
377
  * <p>{{ status }}</p>
376
378
  * ```
377
379
  */
378
- export declare function useText(source: MaybeRefOrGetter<TextReference | string | null | undefined>, fallback?: MaybeRefOrGetter<string | undefined>): ComputedRef<string>;
380
+ export declare function useText(source: MaybeRefOrGetter<TextReference | FieldError | string | null | undefined>, fallback?: MaybeRefOrGetter<string | undefined>): ComputedRef<string>;
379
381
  /** The window's locale that the application set, or `null` while it sets none, as a ref, until the effect scope stops. */
380
382
  export declare function useWindowLocale(): Readonly<Ref<string | null>>;
383
+ /**
384
+ * The page's appearance (`appearance` from `@runic-artifex/views`) as a ref that renders, computes and watches again
385
+ * when it changes: the colour scheme, contrast and reduced motion of the page's engine combined with the desktop's values
386
+ * that a Runic host pushes (`appearance/1`), which also carry the text scale, the accent colour and the forced-colours
387
+ * palette. Follows them while the calling component or effect scope lives; every member is `null` under server
388
+ * rendering.
389
+ *
390
+ * ```ts
391
+ * const look = useAppearance();
392
+ * const animate = computed(() => look.value.reducedMotion !== true);
393
+ * ```
394
+ */
395
+ export declare function useAppearance(): Readonly<Ref<Appearance>>;
396
+ /**
397
+ * The locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's locale),
398
+ * as a ref that renders, computes and watches again when it changes. It is one ref for the page and needs no effect
399
+ * scope, so the page's locale resolver can read it: a template that calls `m.*()` then renders again on a language
400
+ * switch. `undefined` while the page has no Translations runtime and the application sets no window locale.
401
+ *
402
+ * ```ts
403
+ * const textLocale = useTextLocale();
404
+ * configureLocaleResolver(() => textLocale.value ?? locale.getLocale());
405
+ * ```
406
+ */
407
+ export declare function useTextLocale(): Readonly<Ref<string | undefined>>;
381
408
  export { useCollectionViewport, type CollectionViewportHandle } from "./viewport.js";
382
409
  export { useForm, type FormFieldHandle, type FormHandle, type UseFormOptions } from "./form.js";
383
410
  export { commitAllFields, type FormState, type FormSubmitOptions, type FormSubmitResult } from "@runic-artifex/views";
384
- export { configureTranslatedText, resolveText, windowLocale, type TextReference, type TextTranslations, } from "@runic-artifex/views";
411
+ export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, type DocumentLocaleOptions, type FieldErrorArguments, type FieldErrorReason, type FieldErrorText, type TextReference, type TextTranslations, } from "@runic-artifex/views";
412
+ export { appearance, onAppearance, type Appearance, type AppearanceColorScheme, type AppearanceContrast, type AppearanceSystemColors, type HostAppearance, } from "@runic-artifex/views";
385
413
  export { useQueryCollection, type QueryCollectionHandle } from "./query.js";
386
414
  export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
387
415
  export { upload, type BlobRef, type RunicBlob, type UploadOptions, type UploadProgress } from "@runic-artifex/views";
package/dist/index.js CHANGED
@@ -1,6 +1,7 @@
1
- import { computed, defineComponent, h, reactive, shallowRef, toValue, watch, } from "vue";
2
- import { createCommandController, createLatestOperationController, createOperationController, createFieldController, createTextFieldController, createViewController, onBridgeConnection, onWindowLocale, resolveText, subscribeText, windowLocale, regionEntries, } from "@runic-artifex/views";
3
- import { viewSourceIdentity } from "@runic-artifex/views/bindings";
1
+ import { computed, customRef, defineComponent, h, reactive, shallowRef, toValue, watch, } from "vue";
2
+ import { createCommandController, createLatestOperationController, createOperationController, createFieldController, createTextFieldController, createViewController, onBridgeConnection, onWindowLocale, appearance, onAppearance, resolveText, subscribeText, textLocale, windowLocale, regionEntries, } from "@runic-artifex/views";
3
+ import { missingViewMessage, reportMissingView, viewSourceIdentity } from "@runic-artifex/views/bindings";
4
+ import { isDevelopment } from "./development.js";
4
5
  import { releaseWithScope } from "./scope.js";
5
6
  function controllerOptions(options) {
6
7
  return { ...(options.release ? { release: options.release } : {}), ...(options.keepAlive === undefined ? {} : { keepAlive: options.keepAlive }) };
@@ -70,7 +71,8 @@ function referenceKey(reference) {
70
71
  * the reference as its `page` prop. A different reference remounts the
71
72
  * component. The default slot renders while there is no content. A kind without
72
73
  * a component renders the `missing` slot, which receives `{ content }`, for example
73
- * for localized text, or an English alert without it:
74
+ * for localized text. Without the slot, a development build renders an English alert, and a production build
75
+ * renders nothing and reports the kind (`installErrorReporting`, `onBridgeDiagnostic`):
74
76
  *
75
77
  * ```vue
76
78
  * <ViewOutlet :content="state?.main" :registry="pages">
@@ -86,7 +88,10 @@ export const ViewOutlet = defineComponent((props, { slots }) => () => {
86
88
  if (!component) {
87
89
  if (slots["missing"])
88
90
  return slots["missing"]({ content });
89
- return h("p", { role: "alert" }, `No web component is registered for ${content.kind}.`);
91
+ if (isDevelopment())
92
+ return h("p", { role: "alert" }, missingViewMessage(content.kind));
93
+ reportMissingView(content.kind);
94
+ return null;
90
95
  }
91
96
  return h(component, { key: referenceKey(content), page: content });
92
97
  }, { name: "ViewOutlet", props: ["content", "registry"] });
@@ -311,7 +316,8 @@ export function useBridgeConnection(options = {}) {
311
316
  * language (`resolveText`), as a computed ref that follows a language switch until the effect scope stops. `source` and
312
317
  * `fallback` may be refs or getters: `useText(() => view.state.value?.status)`. A string shows as it is; `null` and
313
318
  * `undefined` show `fallback`. Configure the page's Translations runtime once with `configureTranslatedText`; without
314
- * one, a reference shows its fallback text.
319
+ * one, a reference shows its fallback text. A field's `FieldError` shows the application's text for it
320
+ * (`configureFieldErrorText`), or its English message: `useText(() => title.error)`.
315
321
  *
316
322
  * ```vue
317
323
  * const status = useText(() => view.state.value?.status);
@@ -332,10 +338,57 @@ export function useWindowLocale() {
332
338
  releaseWithScope("useWindowLocale", onWindowLocale(next => { locale.value = next; }));
333
339
  return locale;
334
340
  }
341
+ /**
342
+ * The page's appearance (`appearance` from `@runic-artifex/views`) as a ref that renders, computes and watches again
343
+ * when it changes: the colour scheme, contrast and reduced motion of the page's engine combined with the desktop's values
344
+ * that a Runic host pushes (`appearance/1`), which also carry the text scale, the accent colour and the forced-colours
345
+ * palette. Follows them while the calling component or effect scope lives; every member is `null` under server
346
+ * rendering.
347
+ *
348
+ * ```ts
349
+ * const look = useAppearance();
350
+ * const animate = computed(() => look.value.reducedMotion !== true);
351
+ * ```
352
+ */
353
+ export function useAppearance() {
354
+ const current = shallowRef(appearance());
355
+ releaseWithScope("useAppearance", onAppearance(next => { current.value = next; }));
356
+ current.value = appearance();
357
+ return current;
358
+ }
359
+ let pageTextLocale;
360
+ /**
361
+ * The locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's locale),
362
+ * as a ref that renders, computes and watches again when it changes. It is one ref for the page and needs no effect
363
+ * scope, so the page's locale resolver can read it: a template that calls `m.*()` then renders again on a language
364
+ * switch. `undefined` while the page has no Translations runtime and the application sets no window locale.
365
+ *
366
+ * ```ts
367
+ * const textLocale = useTextLocale();
368
+ * configureLocaleResolver(() => textLocale.value ?? locale.getLocale());
369
+ * ```
370
+ */
371
+ export function useTextLocale() {
372
+ return pageTextLocale ??= customRef((track, trigger) => {
373
+ let subscribed = false;
374
+ return {
375
+ get() {
376
+ if (!subscribed) {
377
+ subscribed = true;
378
+ subscribeText(trigger);
379
+ }
380
+ track();
381
+ return textLocale();
382
+ },
383
+ set() { },
384
+ };
385
+ });
386
+ }
335
387
  export { useCollectionViewport } from "./viewport.js";
336
388
  export { useForm } from "./form.js";
337
389
  export { commitAllFields } from "@runic-artifex/views";
338
- export { configureTranslatedText, resolveText, windowLocale, } from "@runic-artifex/views";
390
+ export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, } from "@runic-artifex/views";
391
+ export { appearance, onAppearance, } from "@runic-artifex/views";
339
392
  export { useQueryCollection } from "./query.js";
340
393
  export { onBridgeConnection } from "@runic-artifex/views";
341
394
  // blobs/1: uploads from the page and the blob values of state.
package/dist/scope.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { getCurrentScope, onScopeDispose } from "vue";
2
+ import { isDevelopment } from "./development.js";
2
3
  // Ties a composable's controller to the current effect scope. Outside one (not
3
4
  // in setup() or effectScope().run()) nothing ever releases it, so development
4
5
  // builds say so.
@@ -7,7 +8,7 @@ export function releaseWithScope(composable, release) {
7
8
  onScopeDispose(release);
8
9
  return;
9
10
  }
10
- if (process.env.NODE_ENV !== "production")
11
+ if (isDevelopment())
11
12
  console.warn(`${composable} was called outside an active effect scope, so nothing releases it: ` +
12
13
  "call it in a component's setup() or inside effectScope().run(), and stop that scope to release it.");
13
14
  }
package/dist/viewport.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { shallowRef, toValue, watch } from "vue";
2
2
  import { createCollectionViewportController, } from "@runic-artifex/views";
3
3
  import { releaseWithScope } from "./scope.js";
4
+ import { isDevelopment } from "./development.js";
4
5
  /**
5
6
  * Follows a fixed-row-height scroll container and returns the rows to request
6
7
  * from .NET. Pass a getter such as `() => ({ totalCount: state.value?.totalCount ?? 0, rowHeight: 32 })`
@@ -26,7 +27,7 @@ export function useCollectionViewport(options) {
26
27
  if (typeof HTMLElement === "undefined")
27
28
  return controller.attach(null);
28
29
  const container = element instanceof HTMLElement ? element : null;
29
- if (process.env.NODE_ENV !== "production" && element !== null && container === null && !warned) {
30
+ if (isDevelopment() && element !== null && container === null && !warned) {
30
31
  warned = true;
31
32
  console.warn("useCollectionViewport's attach received a component instance or a non-HTML element, so the viewport " +
32
33
  "is detached: bind `:ref=\"attach\"` to a native scroll container such as a <div>.");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/vue",
3
- "version": "0.16.0",
3
+ "version": "0.17.0",
4
4
  "description": "Vue composables for generated Runic Views clients",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -30,10 +30,10 @@
30
30
  },
31
31
  "peerDependencies": {
32
32
  "vue": ">=3.5.30 <4",
33
- "@runic-artifex/views": "0.16.0"
33
+ "@runic-artifex/views": "0.17.0"
34
34
  },
35
35
  "devDependencies": {
36
- "@runic-artifex/views": "0.16.0",
36
+ "@runic-artifex/views": "0.17.0",
37
37
  "esbuild": "0.28.2",
38
38
  "happy-dom": "21.0.4",
39
39
  "playwright-core": "1.63.0",
@@ -50,7 +50,7 @@
50
50
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
51
51
  "directory": "packages/web/vue"
52
52
  },
53
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/vue#readme",
53
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/vue#readme",
54
54
  "bugs": {
55
55
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
56
56
  },
@@ -60,5 +60,5 @@
60
60
  "views",
61
61
  "vue"
62
62
  ],
63
- "gitHead": "ff96e52727212344c407489283a9cafc614f0270"
63
+ "gitHead": "daeb17e5c3fb0b625d5d988d359cd12ffa51f8c6"
64
64
  }