@runic-artifex/svelte 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
@@ -86,7 +86,7 @@ the failure. Await it with `{#await}`:
86
86
  The source is read once: wrap the component in `{#key page}` to follow another
87
87
  reference. Do not `{#await page.connect()}` directly: nothing would dispose
88
88
  that client. In SvelteKit, connect in a `load` function instead
89
- ([`@runic-artifex/sveltekit`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.16.0/packages/web/svelte/../sveltekit/README.md#connecting-in-load)).
89
+ ([`@runic-artifex/sveltekit`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/svelte/../sveltekit/README.md#connecting-in-load)).
90
90
 
91
91
  ### Selecting state: `$derived`
92
92
 
@@ -182,8 +182,10 @@ handle also has `value` and `text`, which `bind:value={title.value}` reads and s
182
182
  `errors` holds the member's validation messages from the descriptor (`[]` when valid), `error` why the latest write
183
183
  or text failed (a `BridgeError` or a `FieldError`, whose `kind` is `rejected`, `conflict`, `committed-with-error` or
184
184
  `invalid-text`). `FieldError`, `FieldOptions`, `FieldState` and `BridgeField` are exported from this package. See the
185
- [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#fields) for the receipts
186
- and text forms.
185
+ [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#fields) for the receipts
186
+ and text forms. An `invalid-text` error has a `reason` and `arguments`: render `useText(() => name.error).current` after
187
+ `configureFieldErrorText` to show your own text for it in the window's language
188
+ ([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#translating-field-errors)).
187
189
 
188
190
  #### Row cells and nested members
189
191
 
@@ -192,7 +194,7 @@ Since 0.16, `InvoiceFields.address.street` and `InvoiceFields.lines.at(line.id).
192
194
  `useField(() => view, InvoiceFields.lines.at(line.id).quantity)` in the row's component and `{@attach quantity.attach}`
193
195
  its input; `at(key)` returns the same descriptor for the same key. Such a field always writes checked, conflicts only
194
196
  when another writer changed the same cell, and shows the messages .NET reports at the cell's validation path. See
195
- [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.16.0/packages/web/svelte/../views/README.md#fields-below-a-member-and-row-cells).
197
+ [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/svelte/../views/README.md#fields-below-a-member-and-row-cells).
196
198
 
197
199
  ### Forms: `useForm(() => fields, options?)`
198
200
 
@@ -208,7 +210,7 @@ const form = useForm(() => ({ title, step }), { dirty: () => editor.state?.isDir
208
210
 
209
211
  Call during component initialization to bind a text input to a member through the
210
212
  framework-neutral
211
- [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#text-inputs):
213
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#text-inputs):
212
214
 
213
215
  ```svelte
214
216
  <script lang="ts">
@@ -266,9 +268,17 @@ the reference as its `page` prop:
266
268
  ```
267
269
 
268
270
  The outlet is generic over the reference union, so the registry must have a
269
- component for every kind with a matching `page` prop. A different reference
270
- remounts the component, a kind without a component renders an English
271
- `<p role="alert">`, and the optional `fallback` snippet renders while `content` is empty.
271
+ component for every kind with a matching `page` prop. A component whose `page`
272
+ is a shared page reference, such as `ResultPagePageReference` of a .NET
273
+ [`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/svelte/../../dotnet/Runic.Application.Views/README.md#shared-clients)
274
+ interface, registers for each of its kinds:
275
+ `{ ...registryEntries(resultPageKinds, ResultPage), settings: Settings }`. A different reference
276
+ remounts the component, and the optional `fallback` snippet renders while
277
+ `content` is empty. A kind without a component renders an English
278
+ `<p role="alert">` in a development build (`process.env.NODE_ENV`, which Vite
279
+ sets, is not `production`); a production build renders nothing and reports the
280
+ kind once through the page's error reporting (`installErrorReporting`,
281
+ `onBridgeDiagnostic`).
272
282
 
273
283
  The optional `missing` snippet replaces that alert, for example with localized
274
284
  text. It receives the reference whose kind has no component, and its markup
@@ -410,7 +420,7 @@ Cancel and other callbacks responsive during observation.
410
420
  ## `useLatestOperation()`
411
421
 
412
422
  For rapid read selection, `useLatestOperation()` wraps the framework-neutral
413
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#operation-feedback-and-latest-selection)
423
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#operation-feedback-and-latest-selection)
414
424
  for the component's lifetime. It coalesces the latest intent across delayed receipts
415
425
  and orders the next admission after terminal observation and any application drain
416
426
  barrier:
@@ -441,7 +451,7 @@ establish that replacement boundary and own the old work's drain. Lost terminal
441
451
  observation blocks further Starts instead of retrying blindly, with its reason in
442
452
  `error`; ordinary Cancel does not clear this block. Component destruction settles
443
453
  observation without cancelling accepted work. The
444
- [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/tests/fixtures/application/operations-consumer)
454
+ [operations package consumer](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/tests/fixtures/application/operations-consumer)
445
455
  runs this hook against the packed packages and the desktop transport.
446
456
 
447
457
  ## `useBridgeConnection(options?)`
@@ -451,7 +461,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
451
461
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a reactive
452
462
  `BridgeConnectionState`: `connecting`, `connected`, `reconnecting`, `lost` or `closed` (the
453
463
  application closed the window, since 0.15; a closed set, see
454
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#connection-state)):
464
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#connection-state)):
455
465
 
456
466
  ```svelte
457
467
  <script lang="ts">
@@ -473,7 +483,7 @@ server render does not observe, and destroying the owner unsubscribes. An invali
473
483
  Follows the declared menu bar of a Runic Desktop window that leaves it to the
474
484
  page (`DesktopMenuBarPresentation.Page`) while its owner lives. It wraps
475
485
  `createMenuBarController` from `@runic-artifex/views` (see
476
- [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 }`, where `state` is a
486
+ [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 }`, where `state` is a
477
487
  reactive `MenuBarState` property. The bar is rendered by the menubar component
478
488
  of the application's own UI library. Runic ships no menubar component.
479
489
 
@@ -502,7 +512,7 @@ the `shortcuts: "app"` lease.
502
512
  ### With Bits UI
503
513
 
504
514
  Bits UI's `Menubar.Root bind:value`; the
505
- [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
515
+ [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
506
516
  items and is tested with real keys:
507
517
 
508
518
  ```svelte
@@ -558,8 +568,23 @@ Shows a text reference that a ViewModel produced, such as a status line or a
558
568
  validation error's `text`, in the window's language, and renders again when the
559
569
  language changes. A string shows as it is; `null` and `undefined` show
560
570
  `fallback`. Connect the page's Translations runtime once with
561
- `configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.16.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
562
- `useWindowLocale()` reads the window's locale. With SvelteKit server
571
+ `configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
572
+ `useWindowLocale()` reads the window's locale.
573
+
574
+ `useTextLocale().current` is the locale that text is shown in, as a reactive
575
+ property. It is one handle for the page and needs no component, so the locale
576
+ resolver can read it; templates that call `m.*()` then render again on a
577
+ language switch. `syncDocumentLocale()` keeps `<html lang dir>` on that locale:
578
+
579
+ ```ts
580
+ // main.ts
581
+ const textLocale = useTextLocale();
582
+ configureLocaleResolver(() => textLocale.current ?? locale.getLocale());
583
+ configureTranslatedText({ ...locale, resolve, direction: localeDirection });
584
+ syncDocumentLocale();
585
+ ```
586
+
587
+ With SvelteKit server
563
588
  rendering, call `configureTranslatedText` in the browser only (for example in
564
589
  `onMount`), or render on the server with `resolveTextReference` and the
565
590
  request's locale.
@@ -569,6 +594,23 @@ const status = useText(() => view.state?.status);
569
594
  <p>{status.current}</p>
570
595
  ```
571
596
 
597
+ ## `useAppearance()`
598
+
599
+ Follows the page's appearance while its owner lives, as the reactive property
600
+ `current`: the colour scheme, contrast and reduced motion of the page's engine,
601
+ combined with the desktop's text scale, accent colour, forced-colours palette,
602
+ contrast and motion that a Runic host pushes ([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/views/README.md#appearance)).
603
+ Every member is `null` under server rendering, so a SvelteKit page renders the
604
+ same on the server and in the browser until the browser's first effect.
605
+
606
+ ```svelte
607
+ <script lang="ts">
608
+ import { useAppearance } from "@runic-artifex/svelte";
609
+ const look = useAppearance();
610
+ </script>
611
+ <main style:font-size="{look.current.textScale ?? 1}rem">…</main>
612
+ ```
613
+
572
614
  ## Errors
573
615
 
574
616
  The `error` of `useView` and of a command or operation helper is typed
@@ -586,7 +628,7 @@ const message = $derived(describeBridgeError(view.error));
586
628
  ```
587
629
 
588
630
  `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)
631
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#errors-and-diagnostics)
590
632
  lists the kinds. Any other value, such as an exception that your own connect
591
633
  function or command callback throws, arrives unchanged.
592
634
 
@@ -625,10 +667,10 @@ application's own dialog.
625
667
  departure before that is answered by the ViewModel's .NET fallback handler, or
626
668
  fails closed without one.
627
669
 
628
- 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)
670
+ 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)
629
671
  has the .NET side and which View answers which departure. In a frontend test,
630
672
  the generated mock's `interactions.<name>.request(input)` resolves with the
631
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#testing).
673
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#testing).
632
674
 
633
675
  ## View requests
634
676
 
@@ -660,14 +702,14 @@ the page painted the state the request was raised with, so the field of that
660
702
  state is rendered; `signal` aborts when the handler is replaced or removed, the
661
703
  client is disposed or the connection is lost. A request is never replayed: one
662
704
  raised before the effect ran, or while the page is disconnected, is not
663
- 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
705
+ 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
664
706
  test raise one with the generated mock's `requests.<name>.raise(input)` (the
665
- [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#testing)).
707
+ [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#testing)).
666
708
 
667
709
  ## `useCollectionViewport(options)`
668
710
 
669
711
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
670
- `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/views#collectionviewportoptions)
712
+ `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/views#collectionviewportoptions)
671
713
  range; `attach` is an attachment for the container. Call it during component
672
714
  initialization and send the range to the ViewModel from an effect:
673
715
 
@@ -692,7 +734,7 @@ Import them from there instead of `@runic-artifex/svelte`.
692
734
 
693
735
  ## `useQueryCollection(collection, options)`
694
736
 
695
- 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
737
+ 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
696
738
  loads the rows the container shows, with placeholders until they arrive, and lays them out with variable heights. Pass
697
739
  getters of the collection and the options. `viewport` is the `QueryViewport` (`items` with `top` and `size`,
698
740
  `totalSize`, `total`, `query`, `loading`, `error`); attach `attach` to the container and `measure(index)` to each row.
@@ -718,4 +760,4 @@ The package re-exports `installBackNavigation`, `installNavigationPath`,
718
760
  `@runic-artifex/views` (since 0.16). Call the installs once where the page
719
761
  starts, before or after mounting: the mouse's Back button and Alt+Left then go
720
762
  back in the .NET window, and `#/customers/42` follows its path region. See
721
- [Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.16.0/packages/web/views/README.md#back-and-the-url).
763
+ [Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.1/packages/web/views/README.md#back-and-the-url).
@@ -1,6 +1,8 @@
1
1
  <script lang="ts" generics="R extends PageReference">
2
2
  import type { Component, Snippet } from "svelte";
3
3
  import type { PageReference } from "@runic-artifex/views";
4
+ import { missingViewMessage, reportMissingView } from "@runic-artifex/views/bindings";
5
+ import { isDevelopment } from "./development.js";
4
6
  import type { ViewRegistry } from "./view-registry.js";
5
7
 
6
8
  let { content, registry, fallback, missing }: {
@@ -9,20 +11,25 @@
9
11
  /** Rendered while there is no content. */
10
12
  fallback?: Snippet;
11
13
  /**
12
- * Renders a reference whose kind has no registered component, for example localized text.
13
- * Defaults to an English `<p role="alert">`.
14
+ * Renders a reference whose kind has no registered component, for example localized text. Without it, a
15
+ * development build renders an English `<p role="alert">`, and a production build renders nothing and reports
16
+ * the kind through the page's error reporting.
14
17
  */
15
18
  missing?: Snippet<[R]>;
16
19
  } = $props();
17
20
  let Resolved = $derived(content ? registry[content.kind as R["kind"]] as Component<{ page: R }> | undefined : undefined);
21
+ const development = isDevelopment();
22
+ $effect.pre(() => {
23
+ if (content && !Resolved && !missing && !development) reportMissingView(content.kind);
24
+ });
18
25
  </script>
19
26
 
20
27
  {#if content && Resolved}
21
28
  {#key content}<Resolved page={content} />{/key}
22
29
  {:else if content && missing}
23
30
  {@render missing(content)}
24
- {:else if content}
25
- <p role="alert">No web component is registered for {content.kind}.</p>
26
- {:else}
31
+ {:else if content && development}
32
+ <p role="alert">{missingViewMessage(content.kind)}</p>
33
+ {:else if !content}
27
34
  {@render fallback?.()}
28
35
  {/if}
@@ -8,8 +8,9 @@ declare function $$render<R extends PageReference>(): {
8
8
  /** Rendered while there is no content. */
9
9
  fallback?: Snippet;
10
10
  /**
11
- * Renders a reference whose kind has no registered component, for example localized text.
12
- * Defaults to an English `<p role="alert">`.
11
+ * Renders a reference whose kind has no registered component, for example localized text. Without it, a
12
+ * development build renders an English `<p role="alert">`, and a production build renders nothing and reports
13
+ * the kind through the page's error reporting.
13
14
  */
14
15
  missing?: Snippet<[R]>;
15
16
  };
@@ -0,0 +1,2 @@
1
+ /** Whether the page is a development build. A page whose bundler does not replace NODE_ENV counts as production. */
2
+ export declare function isDevelopment(): boolean;
@@ -0,0 +1,9 @@
1
+ /** Whether the page is a development build. A page whose bundler does not replace NODE_ENV counts as production. */
2
+ export function isDevelopment() {
3
+ try {
4
+ return process.env.NODE_ENV !== "production";
5
+ }
6
+ catch {
7
+ return false;
8
+ }
9
+ }
@@ -15,8 +15,10 @@ export { useCollectionViewport, type CollectionViewportHandle } from "./use-coll
15
15
  export { useQueryCollection, type QueryCollectionHandle } from "./use-query-collection.svelte.js";
16
16
  export { useBridgeConnection, type BridgeConnectionHandle } from "./use-bridge-connection.svelte.js";
17
17
  export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
18
- export { useText, useWindowLocale, type TextHandle, type WindowLocaleHandle } from "./use-text.svelte.js";
19
- export { configureTranslatedText, resolveText, windowLocale, type TextReference, type TextTranslations, } from "@runic-artifex/views";
18
+ export { useText, useTextLocale, useWindowLocale, type TextHandle, type TextLocaleHandle, type WindowLocaleHandle, } from "./use-text.svelte.js";
19
+ export { useAppearance, type AppearanceHandle } from "./use-appearance.svelte.js";
20
+ export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, type DocumentLocaleOptions, type FieldErrorArguments, type FieldErrorReason, type FieldErrorText, type TextReference, type TextTranslations, } from "@runic-artifex/views";
21
+ export { appearance, onAppearance, type Appearance, type AppearanceColorScheme, type AppearanceContrast, type AppearanceSystemColors, type HostAppearance, } from "@runic-artifex/views";
20
22
  export { upload, type BlobRef, type RunicBlob, type UploadOptions, type UploadProgress } from "@runic-artifex/views";
21
23
  export { regionEntries, selectedRegion, type RegionCollection, type RegionEntry, type RegionOutcome, type RegionSlot, } from "@runic-artifex/views";
22
24
  export { installBackNavigation, installNavigationPath, navigateBack, onNavigationPath, openNavigationPath, type NavigationPathChange, type NavigationPathOptions, type NavigationReply, } from "@runic-artifex/views";
@@ -13,8 +13,10 @@ export { useCollectionViewport } from "./use-collection-viewport.svelte.js";
13
13
  export { useQueryCollection } from "./use-query-collection.svelte.js";
14
14
  export { useBridgeConnection } from "./use-bridge-connection.svelte.js";
15
15
  export { onBridgeConnection } from "@runic-artifex/views";
16
- export { useText, useWindowLocale } from "./use-text.svelte.js";
17
- export { configureTranslatedText, resolveText, windowLocale, } from "@runic-artifex/views";
16
+ export { useText, useTextLocale, useWindowLocale, } from "./use-text.svelte.js";
17
+ export { useAppearance } from "./use-appearance.svelte.js";
18
+ export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, } from "@runic-artifex/views";
19
+ export { appearance, onAppearance, } from "@runic-artifex/views";
18
20
  // blobs/1: uploads from the page and the blob values of state.
19
21
  export { upload } from "@runic-artifex/views";
20
22
  export { regionEntries, selectedRegion, } from "@runic-artifex/views";
@@ -0,0 +1,18 @@
1
+ import { type Appearance } from "@runic-artifex/views";
2
+ export interface AppearanceHandle {
3
+ /** The page's appearance. A reactive property; every member is `null` under server rendering. */
4
+ readonly current: Appearance;
5
+ }
6
+ /**
7
+ * Follows the page's appearance (`appearance` from `@runic-artifex/views`) while its owner lives: the colour scheme,
8
+ * contrast and reduced motion of the page's engine combined with the desktop's values that a Runic host pushes
9
+ * (`appearance/1`), which also carry the text scale, the accent colour and the forced-colours palette.
10
+ *
11
+ * ```svelte
12
+ * <script lang="ts">
13
+ * const look = useAppearance();
14
+ * </script>
15
+ * <main style:font-size="{look.current.textScale ?? 1}rem">…</main>
16
+ * ```
17
+ */
18
+ export declare function useAppearance(): AppearanceHandle;
@@ -0,0 +1,22 @@
1
+ import { appearance, onAppearance, unknownAppearance } from "@runic-artifex/views";
2
+ /**
3
+ * Follows the page's appearance (`appearance` from `@runic-artifex/views`) while its owner lives: the colour scheme,
4
+ * contrast and reduced motion of the page's engine combined with the desktop's values that a Runic host pushes
5
+ * (`appearance/1`), which also carry the text scale, the accent colour and the forced-colours palette.
6
+ *
7
+ * ```svelte
8
+ * <script lang="ts">
9
+ * const look = useAppearance();
10
+ * </script>
11
+ * <main style:font-size="{look.current.textScale ?? 1}rem">…</main>
12
+ * ```
13
+ */
14
+ export function useAppearance() {
15
+ let current = $state.raw(typeof window === "undefined" ? unknownAppearance : appearance());
16
+ $effect.pre(() => {
17
+ const stop = onAppearance(next => { current = next; });
18
+ current = appearance();
19
+ return stop;
20
+ });
21
+ return { get current() { return current; } };
22
+ }
@@ -1,8 +1,12 @@
1
- import { type TextReference } from "@runic-artifex/views";
1
+ import { type FieldError, type TextReference } from "@runic-artifex/views";
2
2
  export interface TextHandle {
3
3
  /** The text in the window's language. A reactive property. */
4
4
  readonly current: string;
5
5
  }
6
+ export interface TextLocaleHandle {
7
+ /** The locale that text is shown in, or `undefined` before there is one. A reactive property. */
8
+ readonly current: string | undefined;
9
+ }
6
10
  export interface WindowLocaleHandle {
7
11
  /** The window's locale that the application set, or `null` while it sets none. A reactive property. */
8
12
  readonly current: string | null;
@@ -12,13 +16,27 @@ export interface WindowLocaleHandle {
12
16
  * window's language (`resolveText`), while its owner lives. `source` and `fallback` are read reactively, so pass
13
17
  * functions: `useText(() => view.state?.status)`. A string shows as it is; `null` and `undefined` show `fallback`.
14
18
  * Configure the page's Translations runtime once with `configureTranslatedText`; without one, a reference shows its
15
- * fallback text. Call during component initialization (or in `$effect.root`).
19
+ * fallback text. A field's `FieldError` shows the application's text for it (`configureFieldErrorText`), or its English
20
+ * message: `useText(() => name.error)`. Call during component initialization (or in `$effect.root`).
16
21
  *
17
22
  * ```svelte
18
23
  * const status = useText(() => view.state?.status);
19
24
  * <p>{status.current}</p>
20
25
  * ```
21
26
  */
22
- export declare function useText(source: () => TextReference | string | null | undefined, fallback?: () => string | undefined): TextHandle;
27
+ export declare function useText(source: () => TextReference | FieldError | string | null | undefined, fallback?: () => string | undefined): TextHandle;
23
28
  /** Follows the window's locale (`windowLocale`) while its owner lives, for example to set `lang`. */
24
29
  export declare function useWindowLocale(): WindowLocaleHandle;
30
+ /**
31
+ * Follows the locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's
32
+ * locale). Reading `current` in a template, `$derived` or `$effect` runs it again when the locale changes. It is one
33
+ * handle for the page and needs no component, so the page's locale resolver can read it: a template that calls
34
+ * `m.*()` then renders again on a language switch. `undefined` while the page has no Translations runtime and the
35
+ * application sets no window locale.
36
+ *
37
+ * ```ts
38
+ * const textLocale = useTextLocale();
39
+ * configureLocaleResolver(() => textLocale.current ?? locale.getLocale());
40
+ * ```
41
+ */
42
+ export declare function useTextLocale(): TextLocaleHandle;
@@ -1,10 +1,12 @@
1
- import { onWindowLocale, resolveText, subscribeText, windowLocale } from "@runic-artifex/views";
1
+ import { createSubscriber } from "svelte/reactivity";
2
+ import { onWindowLocale, resolveText, subscribeText, textLocale, windowLocale } from "@runic-artifex/views";
2
3
  /**
3
4
  * Follows a text reference that a ViewModel produced, such as a status line or a validation message's `text`, in the
4
5
  * window's language (`resolveText`), while its owner lives. `source` and `fallback` are read reactively, so pass
5
6
  * functions: `useText(() => view.state?.status)`. A string shows as it is; `null` and `undefined` show `fallback`.
6
7
  * Configure the page's Translations runtime once with `configureTranslatedText`; without one, a reference shows its
7
- * fallback text. Call during component initialization (or in `$effect.root`).
8
+ * fallback text. A field's `FieldError` shows the application's text for it (`configureFieldErrorText`), or its English
9
+ * message: `useText(() => name.error)`. Call during component initialization (or in `$effect.root`).
8
10
  *
9
11
  * ```svelte
10
12
  * const status = useText(() => view.state?.status);
@@ -26,3 +28,25 @@ export function useWindowLocale() {
26
28
  $effect.pre(() => onWindowLocale(next => { current = next; }));
27
29
  return { get current() { return current; } };
28
30
  }
31
+ const subscribeTextLocale = createSubscriber(update => subscribeText(update));
32
+ const textLocaleHandle = {
33
+ get current() {
34
+ subscribeTextLocale();
35
+ return textLocale();
36
+ },
37
+ };
38
+ /**
39
+ * Follows the locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's
40
+ * locale). Reading `current` in a template, `$derived` or `$effect` runs it again when the locale changes. It is one
41
+ * handle for the page and needs no component, so the page's locale resolver can read it: a template that calls
42
+ * `m.*()` then renders again on a language switch. `undefined` while the page has no Translations runtime and the
43
+ * application sets no window locale.
44
+ *
45
+ * ```ts
46
+ * const textLocale = useTextLocale();
47
+ * configureLocaleResolver(() => textLocale.current ?? locale.getLocale());
48
+ * ```
49
+ */
50
+ export function useTextLocale() {
51
+ return textLocaleHandle;
52
+ }
@@ -1,13 +1,14 @@
1
1
  import type { Component } from "svelte";
2
- import type { PageReference } from "@runic-artifex/views";
2
+ import type { PageReference, ViewRegistryPage } from "@runic-artifex/views";
3
3
  /**
4
4
  * Compile-time check that every View kind has a component with a matching page prop. A nullable
5
- * reference, such as a region slot's `State["main"]`, checks its non-null kinds.
5
+ * reference, such as a region slot's `State["main"]`, checks its non-null kinds. A component whose `page` is a shared
6
+ * page reference (`[RunicSharedClient]`), such as `ResultPagePageReference`, registers for each of its kinds.
6
7
  */
7
8
  export type ViewRegistry<R extends PageReference | null | undefined> = {
8
- readonly [K in NonNullable<R>["kind"]]: Component<{
9
- page: Extract<NonNullable<R>, {
10
- readonly kind: K;
11
- }>;
12
- }>;
9
+ readonly [K in NonNullable<R>["kind"]]: PageComponent<ViewRegistryPage<R, K>>;
13
10
  };
11
+ type PageComponent<P> = P extends unknown ? Component<{
12
+ page: P;
13
+ }> : never;
14
+ export {};
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.16.0",
3
+ "version": "0.17.1",
4
4
  "description": "Svelte 5 Application Views helpers for Runic",
5
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.16.0/packages/web/svelte#readme",
5
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.1/packages/web/svelte#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
8
8
  },
@@ -35,12 +35,12 @@
35
35
  "clean": "bun -e \"import('node:fs').then(({rmSync}) => rmSync('dist', { recursive: true, force: true }))\"",
36
36
  "build": "bun run --bun clean && svelte-package -i src -o dist",
37
37
  "check": "svelte-check --tsconfig ./tsconfig.json",
38
- "test": "bun run --bun build && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && vitest run test/use-view.svelte.test.ts test/keep-alive.svelte.test.ts test/glue.svelte.test.ts test/use-operation.svelte.test.ts test/use-latest-operation.svelte.test.ts test/lifecycle.svelte.test.ts test/use-bridge-connection.svelte.test.ts test/use-menu-bar.svelte.test.ts test/use-text-field.svelte.test.ts test/use-field.svelte.test.ts test/use-query-collection.svelte.test.ts test/text-field.browser.test.ts test/field.browser.test.ts",
38
+ "test": "bun run --bun build && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && vitest run test/use-view.svelte.test.ts test/keep-alive.svelte.test.ts test/glue.svelte.test.ts test/use-operation.svelte.test.ts test/use-latest-operation.svelte.test.ts test/lifecycle.svelte.test.ts test/use-bridge-connection.svelte.test.ts test/use-menu-bar.svelte.test.ts test/use-text-field.svelte.test.ts test/use-field.svelte.test.ts test/use-query-collection.svelte.test.ts test/use-text.svelte.test.ts test/use-appearance.svelte.test.ts test/text-field.browser.test.ts test/field.browser.test.ts",
39
39
  "pack:check": "bun pm pack --dry-run"
40
40
  },
41
41
  "peerDependencies": {
42
42
  "svelte": ">=5.57.1 <6",
43
- "@runic-artifex/views": "0.16.0"
43
+ "@runic-artifex/views": "0.17.1"
44
44
  },
45
45
  "publishConfig": {
46
46
  "access": "public",
@@ -53,7 +53,7 @@
53
53
  },
54
54
  "packageManager": "bun@1.4.4",
55
55
  "devDependencies": {
56
- "@runic-artifex/views": "0.16.0",
56
+ "@runic-artifex/views": "0.17.1",
57
57
  "@sveltejs/adapter-static": "4.0.0",
58
58
  "@sveltejs/kit": "3.0.0",
59
59
  "@sveltejs/package": "3.0.0",
@@ -67,5 +67,5 @@
67
67
  "vitest": "5.0.3",
68
68
  "vite": "8.3.4"
69
69
  },
70
- "gitHead": "ff96e52727212344c407489283a9cafc614f0270"
70
+ "gitHead": "4f200eadd987eab9a2e38db6e8841849b743b615"
71
71
  }