@runic-artifex/svelte 0.5.0-preview.3 → 0.6.0-preview.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
@@ -12,8 +12,41 @@ The browser-safe `@runic-artifex/svelte/translations/testing` entry point
12
12
  provides pseudo-localization, RTL isolation, plural boundary values, and
13
13
  accessibility stress fixtures. `@runic-artifex/svelte/inline` exports
14
14
  `LocalizedInline` and `inlineFactory` for localized structured content.
15
- `@runic-artifex/svelte/views` exports `ViewOutlet`, `ViewReference`, and
16
- `ViewRegistry` for generated Window/View clients.
15
+ `@runic-artifex/svelte/views` exports `ViewOutlet`, `ViewReference`,
16
+ `ViewRegistry` and `useView` for generated Window/View clients.
17
+
18
+ Generated View clients import `@runic-artifex/views`, so a Views application
19
+ installs both packages:
20
+
21
+ ```sh
22
+ npm install @runic-artifex/svelte@preview @runic-artifex/views@preview
23
+ pnpm add @runic-artifex/svelte@preview @runic-artifex/views@preview
24
+ bun add @runic-artifex/svelte@preview @runic-artifex/views@preview
25
+ ```
26
+
27
+ Previews are published under the `preview` dist-tag. Install the versions that
28
+ match your Runic SDK packages.
29
+
30
+ ```svelte
31
+ <script lang="ts">
32
+ import { useView } from "@runic-artifex/svelte/views";
33
+ import type { CounterPageReference } from "./generated/counter.js";
34
+
35
+ let { page }: { page: CounterPageReference } = $props();
36
+ const counter = useView(() => page);
37
+ </script>
38
+
39
+ <button disabled={!counter.client} onclick={() => counter.client?.increment()}>
40
+ {counter.state?.count ?? "…"}
41
+ </button>
42
+ ```
43
+
44
+ Call `useView` during component initialization. It connects a generated page
45
+ reference, or `{ connect: connect<Name> }` for a root ViewModel, while the
46
+ component is mounted and disposes it on destroy or when the getter returns a
47
+ reference with a different `connect` function. An already connected client is
48
+ observed and left to its owner. The result exposes reactive `state`, `client`
49
+ and `error` properties and `retry()`.
17
50
 
18
51
  See the [Translations guide](https://github.com/Runic-Artifex/runic-sdk/tree/main/docs/guides/translations)
19
52
  for catalog generation and the SvelteKit locale routing helpers.
@@ -1,2 +1,3 @@
1
1
  export { default as ViewOutlet } from "./ViewOutlet.svelte";
2
2
  export type { ViewReference, ViewRegistry } from "./view-registry.js";
3
+ export { useView, type ViewClient, type ViewHandle, type ViewSource } from "./use-view.svelte.js";
@@ -1 +1,2 @@
1
1
  export { default as ViewOutlet } from "./ViewOutlet.svelte";
2
+ export { useView } from "./use-view.svelte.js";
@@ -0,0 +1,34 @@
1
+ /** The framework-neutral surface of a generated `<Name>Client`. */
2
+ export interface ViewClient<TState = unknown> {
3
+ readonly snapshot: TState;
4
+ subscribe(listener: (state: TState) => void): () => void;
5
+ dispose(): void;
6
+ }
7
+ /**
8
+ * A generated content reference or `{ connect: connect<Name> }` for a root
9
+ * ViewModel, which the helper connects and disposes, or an already connected
10
+ * client, which it only observes.
11
+ */
12
+ export type ViewSource<TClient extends ViewClient> = {
13
+ connect(): Promise<TClient>;
14
+ } | TClient | null | undefined;
15
+ export interface ViewHandle<TClient extends ViewClient> {
16
+ /** The latest state, or undefined until the client connects. */
17
+ readonly state: TClient["snapshot"] | undefined;
18
+ /** The connected client for commands, or undefined until it connects. */
19
+ readonly client: TClient | undefined;
20
+ /** The connection failure, if any. */
21
+ readonly error: unknown;
22
+ /** Connects a reference again after a failure. */
23
+ retry(): void;
24
+ }
25
+ /**
26
+ * Connects a generated View reference while the calling component is mounted
27
+ * and exposes its state as reactive properties. Call it during component
28
+ * initialization with a getter, such as `useView(() => page)`, so a changed
29
+ * prop disposes the previous client and connects the new one.
30
+ *
31
+ * A reference is identified by its `connect` function, so a getter returning a
32
+ * new `{ connect: connectShell }` object does not reconnect.
33
+ */
34
+ export declare function useView<TClient extends ViewClient>(source: () => ViewSource<TClient>): ViewHandle<TClient>;
@@ -0,0 +1,72 @@
1
+ import { untrack } from "svelte";
2
+ function isClient(source) {
3
+ return typeof source.subscribe === "function";
4
+ }
5
+ /**
6
+ * Connects a generated View reference while the calling component is mounted
7
+ * and exposes its state as reactive properties. Call it during component
8
+ * initialization with a getter, such as `useView(() => page)`, so a changed
9
+ * prop disposes the previous client and connects the new one.
10
+ *
11
+ * A reference is identified by its `connect` function, so a getter returning a
12
+ * new `{ connect: connectShell }` object does not reconnect.
13
+ */
14
+ export function useView(source) {
15
+ let state = $state.raw(undefined);
16
+ let client = $state.raw(undefined);
17
+ let error = $state.raw(undefined);
18
+ let attempt = $state(0);
19
+ const identity = $derived.by(() => {
20
+ const value = source();
21
+ return value ? isClient(value) ? value : value.connect : undefined;
22
+ });
23
+ $effect(() => {
24
+ void identity;
25
+ void attempt;
26
+ const value = untrack(source);
27
+ state = undefined;
28
+ client = undefined;
29
+ error = undefined;
30
+ if (!value)
31
+ return;
32
+ let active = true;
33
+ let connected;
34
+ let unsubscribe;
35
+ const observe = (next) => {
36
+ client = next;
37
+ unsubscribe = next.subscribe(update => { if (active)
38
+ state = update; });
39
+ };
40
+ if (isClient(value))
41
+ observe(value);
42
+ else
43
+ value.connect().then(next => {
44
+ if (!active) {
45
+ next.dispose();
46
+ return;
47
+ }
48
+ connected = next;
49
+ observe(next);
50
+ }, cause => { if (active)
51
+ error = cause; });
52
+ return () => {
53
+ active = false;
54
+ unsubscribe?.();
55
+ connected?.dispose();
56
+ };
57
+ });
58
+ // A connected client is readable before the effect subscribes to it.
59
+ const observed = () => {
60
+ const value = source();
61
+ return value && isClient(value) ? value : undefined;
62
+ };
63
+ return {
64
+ get state() {
65
+ const value = observed();
66
+ return value && value !== client ? value.snapshot : state;
67
+ },
68
+ get client() { return observed() ?? client; },
69
+ get error() { return error; },
70
+ retry() { attempt++; },
71
+ };
72
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.5.0-preview.3",
4
- "description": "Svelte 5 localization and inline content helpers for Runic",
3
+ "version": "0.6.0-preview.1",
4
+ "description": "Svelte 5 localization, inline content and Views helpers for Runic",
5
5
  "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/main/packages/web/svelte#readme",
6
6
  "bugs": {
7
7
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
@@ -50,7 +50,7 @@
50
50
  "scripts": {
51
51
  "build": "svelte-package -i src -o dist",
52
52
  "check": "svelte-check --tsconfig ./tsconfig.json",
53
- "test": "bun run --bun build && vitest run test/locale.svelte.test.ts test/locale-hydration.svelte.test.ts test/localization-stress.test.ts && node test/verify-inline-ssr.mjs",
53
+ "test": "bun run --bun build && vitest run test/locale.svelte.test.ts test/locale-hydration.svelte.test.ts test/localization-stress.test.ts test/use-view.svelte.test.ts && node test/verify-inline-ssr.mjs",
54
54
  "pack:check": "bun pm pack --dry-run",
55
55
  "test:inline-browser": "node test/verify-inline-ssr.mjs && node test/verify-inline-hydration.mjs"
56
56
  },
@@ -71,17 +71,17 @@
71
71
  "node": ">=24.18.0 <25"
72
72
  },
73
73
  "devDependencies": {
74
- "@sveltejs/adapter-static": "3.0.10",
75
- "@sveltejs/kit": "2.70.3",
76
- "@sveltejs/package": "2.5.8",
77
- "@sveltejs/vite-plugin-svelte": "7.3.0",
78
- "@types/node": "24.13.3",
79
- "happy-dom": "^20.14.0",
80
- "svelte": "5.57.0",
74
+ "@sveltejs/adapter-static": "4.0.0",
75
+ "@sveltejs/kit": "3.0.0",
76
+ "@sveltejs/package": "3.0.0",
77
+ "@sveltejs/vite-plugin-svelte": "7.3.1",
78
+ "@types/node": "24.19.1",
79
+ "happy-dom": "^20.14.5",
80
+ "svelte": "5.57.1",
81
81
  "svelte-check": "4.7.6",
82
82
  "typescript": "6.0.3",
83
- "vitest": "5.0.0",
84
- "vite": "8.2.2"
83
+ "vitest": "5.0.3",
84
+ "vite": "8.3.2"
85
85
  },
86
- "gitHead": "29265e112d21ee807f62327f42d61eb44d8dc5c8"
86
+ "gitHead": "3026ada4e531cf58ba5081d8ee53b32b60f1ab6a"
87
87
  }