@runic-artifex/svelte 0.6.0-preview.1 → 0.7.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
@@ -1,22 +1,11 @@
1
1
  # `@runic-artifex/svelte`
2
2
 
3
- Svelte 5 helpers for Runic Translations, inline content, and Application Views.
3
+ Svelte 5 Application Views helpers. `@runic-artifex/svelte` and
4
+ `@runic-artifex/svelte/views` export `useView`, `ViewOutlet`, `ViewRegistry`,
5
+ `useCommand` and `useCollectionViewport` for generated Window/View clients.
4
6
 
5
- For locale context in a Svelte tree:
6
-
7
- ```ts
8
- import { createLocaleContext } from "@runic-artifex/svelte/translations";
9
- ```
10
-
11
- The browser-safe `@runic-artifex/svelte/translations/testing` entry point
12
- provides pseudo-localization, RTL isolation, plural boundary values, and
13
- accessibility stress fixtures. `@runic-artifex/svelte/inline` exports
14
- `LocalizedInline` and `inlineFactory` for localized structured content.
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:
7
+ Generated View clients import `@runic-artifex/views`, which this package also
8
+ builds on, so a Views application installs both packages:
20
9
 
21
10
  ```sh
22
11
  npm install @runic-artifex/svelte@preview @runic-artifex/views@preview
@@ -29,24 +18,93 @@ match your Runic SDK packages.
29
18
 
30
19
  ```svelte
31
20
  <script lang="ts">
32
- import { useView } from "@runic-artifex/svelte/views";
21
+ import { useCommand, useView } from "@runic-artifex/svelte/views";
33
22
  import type { CounterPageReference } from "./generated/counter.js";
34
23
 
35
24
  let { page }: { page: CounterPageReference } = $props();
36
25
  const counter = useView(() => page);
26
+ const increment = useCommand(() => counter.client?.increment());
37
27
  </script>
38
28
 
39
- <button disabled={!counter.client} onclick={() => counter.client?.increment()}>
29
+ <button disabled={!counter.client || increment.pending} onclick={() => increment.run()}>
40
30
  {counter.state?.count ?? "…"}
41
31
  </button>
32
+ {#if increment.error ?? counter.error}<p role="alert">{String(increment.error ?? counter.error)}</p>{/if}
42
33
  ```
43
34
 
35
+ ## `useView(source)`
36
+
44
37
  Call `useView` during component initialization. It connects a generated page
45
38
  reference, or `{ connect: connect<Name> }` for a root ViewModel, while the
46
39
  component is mounted and disposes it on destroy or when the getter returns a
47
40
  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()`.
41
+ observed and left to its owner. The result exposes reactive `state`, `client`,
42
+ `error` and `pending` properties and `retry()`.
43
+
44
+ ## `ViewOutlet`
45
+
46
+ Renders the component registered for a generated reference's `kind` and passes
47
+ the reference as its `page` prop:
48
+
49
+ ```svelte
50
+ <script lang="ts">
51
+ import { useView, ViewOutlet, type ViewRegistry } from "@runic-artifex/svelte/views";
52
+ import { connectWorkspace, type WorkspaceState } from "./generated/workspace.js";
53
+ import CounterPage from "./pages/CounterPage.svelte";
54
+ import WelcomePage from "./pages/WelcomePage.svelte";
55
+
56
+ const pages = { counter: CounterPage, welcome: WelcomePage } satisfies ViewRegistry<WorkspaceState["main"]>;
57
+ const workspace = useView(() => ({ connect: connectWorkspace }));
58
+ </script>
59
+
60
+ <ViewOutlet content={workspace.state?.main} registry={pages}>
61
+ {#snippet fallback()}<p>Connecting…</p>{/snippet}
62
+ </ViewOutlet>
63
+ ```
64
+
65
+ The outlet is generic over the reference union, so the registry must have a
66
+ component for every kind with a matching `page` prop. A different reference
67
+ remounts the component, a kind without a component renders an alert, and the
68
+ optional `fallback` snippet renders while `content` is empty.
69
+
70
+ ## `useCommand(command)`
71
+
72
+ Returns `{ run, pending, error, failure, reset }` with reactive `pending`, `error`
73
+ and `failure`.
74
+ `run(...args)` resolves to the command's result, or to `undefined` after a
75
+ failure, which `error` then holds until the next run. It never rejects, so
76
+ handlers need no `try`/`catch`. One command can serve several buttons:
77
+ `useCommand((name: "showWelcome" | "showCounter") => workspace.client?.[name]())`
78
+ and `navigate.run("showWelcome")`.
79
+
80
+ For a command that declares a failure (`[RunicFailure]` in .NET), `run` resolves the
81
+ `BridgeOutcome`, and `failure` holds the declared failure of the latest run, typed
82
+ from the outcome, while `error` keeps unexpected failures. Starting a run and
83
+ `reset()` clear both, and a run superseded by a later run or by `reset()` sets
84
+ neither.
85
+
86
+ ## `useCollectionViewport(options)`
87
+
88
+ Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
89
+ `viewport` is the reactive [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/main/packages/web/views#collectionviewportoptions)
90
+ range; `attach` is an attachment for the container. Call it during component
91
+ initialization and send the range to the ViewModel from an effect:
92
+
93
+ ```svelte
94
+ <script lang="ts">
95
+ const rows = useView(() => page);
96
+ const list = useCollectionViewport(() => ({ totalCount: rows.state?.totalCount ?? 0, rowHeight: 32 }));
97
+ $effect(() => {
98
+ const { start, size } = list.viewport;
99
+ if (size !== 0) void rows.client?.setViewport({ start, size });
100
+ });
101
+ </script>
102
+
103
+ <div {@attach list.attach} style="height: 480px; overflow: auto">
104
+ <div style:height="{list.viewport.totalSize}px"><!-- rows.state.rows --></div>
105
+ </div>
106
+ ```
50
107
 
51
- See the [Translations guide](https://github.com/Runic-Artifex/runic-sdk/tree/main/docs/guides/translations)
52
- for catalog generation and the SvelteKit locale routing helpers.
108
+ Translation helpers moved to
109
+ [`@runic-artifex/translations-svelte`](https://github.com/Runic-Artifex/runic-translations-sdk/tree/main/packages/web/translations-svelte).
110
+ Use a prior SDK preview until application imports have been migrated.
package/dist/index.d.ts CHANGED
@@ -1,2 +1 @@
1
- export * from "./translations/index.js";
2
- export * from "./inline/index.js";
1
+ export * from "./views/index.js";
package/dist/index.js CHANGED
@@ -1,2 +1 @@
1
- export * from "./translations/index.js";
2
- export * from "./inline/index.js";
1
+ export * from "./views/index.js";
@@ -1,16 +1,20 @@
1
- <script lang="ts">
2
- import type { Component } from "svelte";
3
- import type { ViewReference } from "./view-registry.js";
1
+ <script lang="ts" generics="R extends ViewReference">
2
+ import type { Component, Snippet } from "svelte";
3
+ import type { ViewReference, ViewRegistry } from "./view-registry.js";
4
4
 
5
- let { content, registry }: {
6
- content: ViewReference | null | undefined;
7
- registry: Readonly<Record<string, Component<{ page: any }>>>;
5
+ let { content, registry, fallback }: {
6
+ content: R | null | undefined;
7
+ registry: ViewRegistry<R>;
8
+ /** Rendered while there is no content. */
9
+ fallback?: Snippet;
8
10
  } = $props();
9
- let Resolved = $derived(content ? registry[content.kind] : undefined);
11
+ let Resolved = $derived(content ? registry[content.kind as R["kind"]] as Component<{ page: R }> | undefined : undefined);
10
12
  </script>
11
13
 
12
14
  {#if content && Resolved}
13
15
  {#key content}<Resolved page={content} />{/key}
14
16
  {:else if content}
15
17
  <p role="alert">No web component is registered for {content.kind}.</p>
18
+ {:else}
19
+ {@render fallback?.()}
16
20
  {/if}
@@ -1,11 +1,31 @@
1
- import type { Component } from "svelte";
2
- import type { ViewReference } from "./view-registry.js";
3
- type $$ComponentProps = {
4
- content: ViewReference | null | undefined;
5
- registry: Readonly<Record<string, Component<{
6
- page: any;
7
- }>>>;
1
+ import type { Snippet } from "svelte";
2
+ import type { ViewReference, ViewRegistry } from "./view-registry.js";
3
+ declare function $$render<R extends ViewReference>(): {
4
+ props: {
5
+ content: R | null | undefined;
6
+ registry: ViewRegistry<R>;
7
+ /** Rendered while there is no content. */
8
+ fallback?: Snippet;
9
+ };
10
+ exports: {};
11
+ bindings: "";
12
+ slots: {};
13
+ events: {};
8
14
  };
9
- declare const ViewOutlet: Component<$$ComponentProps, {}, "">;
10
- type ViewOutlet = ReturnType<typeof ViewOutlet>;
15
+ declare class __sveltets_Render<R extends ViewReference> {
16
+ props(): ReturnType<typeof $$render<R>>['props'];
17
+ events(): ReturnType<typeof $$render<R>>['events'];
18
+ slots(): ReturnType<typeof $$render<R>>['slots'];
19
+ bindings(): "";
20
+ exports(): {};
21
+ }
22
+ interface $$IsomorphicComponent {
23
+ new <R extends ViewReference>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<R>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<R>['props']>, ReturnType<__sveltets_Render<R>['events']>, ReturnType<__sveltets_Render<R>['slots']>> & {
24
+ $$bindings?: ReturnType<__sveltets_Render<R>['bindings']>;
25
+ } & ReturnType<__sveltets_Render<R>['exports']>;
26
+ <R extends ViewReference>(internal: unknown, props: ReturnType<__sveltets_Render<R>['props']> & {}): ReturnType<__sveltets_Render<R>['exports']>;
27
+ z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
28
+ }
29
+ declare const ViewOutlet: $$IsomorphicComponent;
30
+ type ViewOutlet<R extends ViewReference> = InstanceType<typeof ViewOutlet<R>>;
11
31
  export default ViewOutlet;
@@ -1,3 +1,6 @@
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";
3
+ export { useView, type ViewHandle } from "./use-view.svelte.js";
4
+ export { useCommand, type CommandHandle } from "./use-command.svelte.js";
5
+ export { useCollectionViewport, type CollectionViewportHandle } from "./use-collection-viewport.svelte.js";
6
+ export type { CollectionViewport, CollectionViewportOptions, ViewClient, ViewConnector, ViewSource } from "@runic-artifex/views";
@@ -1,2 +1,4 @@
1
1
  export { default as ViewOutlet } from "./ViewOutlet.svelte";
2
2
  export { useView } from "./use-view.svelte.js";
3
+ export { useCommand } from "./use-command.svelte.js";
4
+ export { useCollectionViewport } from "./use-collection-viewport.svelte.js";
@@ -0,0 +1,15 @@
1
+ import type { Attachment } from "svelte/attachments";
2
+ import { type CollectionViewport, type CollectionViewportOptions } from "@runic-artifex/views";
3
+ export interface CollectionViewportHandle {
4
+ /** The rows to request and the sizes to render. */
5
+ readonly viewport: CollectionViewport;
6
+ /** Attach to the scroll container: `<div {@attach list.attach}>`. */
7
+ readonly attach: Attachment<HTMLElement>;
8
+ }
9
+ /**
10
+ * Follows a fixed-row-height scroll container and returns the rows to request
11
+ * from .NET. Call it during component initialization with a getter, such as
12
+ * `useCollectionViewport(() => ({ totalCount: rows.state?.totalCount ?? 0, rowHeight: 32 }))`,
13
+ * and send `viewport.start` and `viewport.size` to the ViewModel from an effect.
14
+ */
15
+ export declare function useCollectionViewport(options: () => CollectionViewportOptions): CollectionViewportHandle;
@@ -0,0 +1,25 @@
1
+ import { untrack } from "svelte";
2
+ import { createCollectionViewportController } from "@runic-artifex/views";
3
+ /**
4
+ * Follows a fixed-row-height scroll container and returns the rows to request
5
+ * from .NET. Call it during component initialization with a getter, such as
6
+ * `useCollectionViewport(() => ({ totalCount: rows.state?.totalCount ?? 0, rowHeight: 32 }))`,
7
+ * and send `viewport.start` and `viewport.size` to the ViewModel from an effect.
8
+ */
9
+ export function useCollectionViewport(options) {
10
+ const controller = createCollectionViewportController(untrack(options));
11
+ let viewport = $state.raw(controller.current);
12
+ controller.subscribe(() => { viewport = controller.current; });
13
+ $effect.pre(() => {
14
+ const { totalCount, rowHeight, overscan } = options();
15
+ controller.update({ totalCount, rowHeight, ...(overscan === undefined ? {} : { overscan }) });
16
+ });
17
+ $effect(() => () => controller.dispose());
18
+ return {
19
+ get viewport() { return viewport; },
20
+ attach(element) {
21
+ controller.attach(element);
22
+ return () => controller.attach(null);
23
+ },
24
+ };
25
+ }
@@ -0,0 +1,30 @@
1
+ import { type BridgeOutcomeFailure } from "@runic-artifex/views";
2
+ export interface CommandHandle<TArgs extends readonly unknown[], TResult, TFailure = BridgeOutcomeFailure<TResult>> {
3
+ /**
4
+ * Runs the command. Resolves to its result, including a `BridgeOutcome` with a
5
+ * declared failure, which `failure` then holds, or to undefined after an
6
+ * unexpected failure, which `error` then holds. Never rejects.
7
+ */
8
+ run(...args: TArgs): Promise<TResult | undefined>;
9
+ /** True while a run is in flight. */
10
+ readonly pending: boolean;
11
+ /** Why the latest run failed unexpectedly, until the next run starts. */
12
+ readonly error: unknown;
13
+ /**
14
+ * The declared failure of the latest run, for a command that resolves a
15
+ * `BridgeOutcome`, until the next run starts. A superseded run sets neither.
16
+ */
17
+ readonly failure: TFailure | undefined;
18
+ /** Clears `error` and `failure`. */
19
+ reset(): void;
20
+ }
21
+ /**
22
+ * Tracks a command's pending state and failure as reactive properties. The
23
+ * command may close over reactive values:
24
+ *
25
+ * ```svelte
26
+ * const increment = useCommand(() => counter.client?.increment());
27
+ * <button disabled={!counter.client || increment.pending} onclick={() => increment.run()}>…</button>
28
+ * ```
29
+ */
30
+ export declare function useCommand<TArgs extends readonly unknown[], TReturn>(command: (...args: TArgs) => TReturn): CommandHandle<TArgs, Awaited<TReturn>>;
@@ -0,0 +1,22 @@
1
+ import { createCommandController } from "@runic-artifex/views";
2
+ /**
3
+ * Tracks a command's pending state and failure as reactive properties. The
4
+ * command may close over reactive values:
5
+ *
6
+ * ```svelte
7
+ * const increment = useCommand(() => counter.client?.increment());
8
+ * <button disabled={!counter.client || increment.pending} onclick={() => increment.run()}>…</button>
9
+ * ```
10
+ */
11
+ export function useCommand(command) {
12
+ const controller = createCommandController(command);
13
+ let current = $state.raw(controller.current);
14
+ controller.subscribe(() => { current = controller.current; });
15
+ return {
16
+ run: controller.run,
17
+ get pending() { return current.pending; },
18
+ get error() { return current.error; },
19
+ get failure() { return current.failure; },
20
+ reset: controller.reset,
21
+ };
22
+ }
@@ -1,17 +1,4 @@
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;
1
+ import { type ViewClient, type ViewSource } from "@runic-artifex/views";
15
2
  export interface ViewHandle<TClient extends ViewClient> {
16
3
  /** The latest state, or undefined until the client connects. */
17
4
  readonly state: TClient["snapshot"] | undefined;
@@ -19,6 +6,8 @@ export interface ViewHandle<TClient extends ViewClient> {
19
6
  readonly client: TClient | undefined;
20
7
  /** The connection failure, if any. */
21
8
  readonly error: unknown;
9
+ /** True while a reference is connecting. */
10
+ readonly pending: boolean;
22
11
  /** Connects a reference again after a failure. */
23
12
  retry(): void;
24
13
  }
@@ -1,7 +1,5 @@
1
1
  import { untrack } from "svelte";
2
- function isClient(source) {
3
- return typeof source.subscribe === "function";
4
- }
2
+ import { createViewController, isViewClient, viewSourceIdentity } from "@runic-artifex/views";
5
3
  /**
6
4
  * Connects a generated View reference while the calling component is mounted
7
5
  * and exposes its state as reactive properties. Call it during component
@@ -12,61 +10,39 @@ function isClient(source) {
12
10
  * new `{ connect: connectShell }` object does not reconnect.
13
11
  */
14
12
  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
- });
13
+ const controller = createViewController();
14
+ let current = $state.raw(controller.current);
15
+ controller.subscribe(() => { current = controller.current; });
16
+ const identity = $derived(viewSourceIdentity(source()));
23
17
  $effect(() => {
24
18
  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
- };
19
+ untrack(() => {
20
+ controller.setSource(source());
21
+ current = controller.current;
22
+ });
57
23
  });
58
- // A connected client is readable before the effect subscribes to it.
24
+ $effect(() => () => controller.dispose());
25
+ // A connected client is readable before the effect observes it, and a
26
+ // changed reference does not show the previous one until the effect follows it.
59
27
  const observed = () => {
60
28
  const value = source();
61
- return value && isClient(value) ? value : undefined;
29
+ return value && isViewClient(value) ? value : undefined;
62
30
  };
31
+ const fresh = () => viewSourceIdentity(current.source) === identity;
63
32
  return {
64
33
  get state() {
65
34
  const value = observed();
66
- return value && value !== client ? value.snapshot : state;
35
+ if (value && value !== current.client)
36
+ return value.snapshot;
37
+ return fresh() ? current.state : undefined;
38
+ },
39
+ get client() { return observed() ?? (fresh() ? current.client : undefined); },
40
+ get error() { return fresh() ? current.error : undefined; },
41
+ get pending() {
42
+ if (observed())
43
+ return false;
44
+ return fresh() ? current.pending : identity !== undefined;
67
45
  },
68
- get client() { return observed() ?? client; },
69
- get error() { return error; },
70
- retry() { attempt++; },
46
+ retry() { controller.retry(); },
71
47
  };
72
48
  }
@@ -1,8 +1,6 @@
1
1
  import type { Component } from "svelte";
2
- export interface ViewReference {
3
- readonly kind: string;
4
- connect(): Promise<unknown>;
5
- }
2
+ import type { ViewReference } from "@runic-artifex/views";
3
+ export type { ViewReference } from "@runic-artifex/views";
6
4
  /** Compile-time check that every View kind has a component with a matching page prop. */
7
5
  export type ViewRegistry<R extends ViewReference> = {
8
6
  readonly [K in R["kind"]]: Component<{
package/package.json CHANGED
@@ -1,19 +1,20 @@
1
1
  {
2
2
  "name": "@runic-artifex/svelte",
3
- "version": "0.6.0-preview.1",
4
- "description": "Svelte 5 localization, inline content and Views helpers for Runic",
3
+ "version": "0.7.0-preview.1",
4
+ "description": "Svelte 5 Application 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"
8
8
  },
9
9
  "keywords": [
10
10
  "runic-artifex",
11
- "translations",
11
+ "views",
12
12
  "svelte",
13
13
  "svelte-5"
14
14
  ],
15
15
  "license": "MIT",
16
16
  "type": "module",
17
+ "sideEffects": false,
17
18
  "svelte": "./dist/index.js",
18
19
  "types": "./dist/index.d.ts",
19
20
  "exports": {
@@ -22,20 +23,6 @@
22
23
  "svelte": "./dist/index.js",
23
24
  "import": "./dist/index.js"
24
25
  },
25
- "./translations": {
26
- "types": "./dist/translations/index.d.ts",
27
- "svelte": "./dist/translations/index.js",
28
- "import": "./dist/translations/index.js"
29
- },
30
- "./translations/testing": {
31
- "types": "./dist/translations/testing.d.ts",
32
- "import": "./dist/translations/testing.js"
33
- },
34
- "./inline": {
35
- "types": "./dist/inline/index.d.ts",
36
- "svelte": "./dist/inline/index.js",
37
- "import": "./dist/inline/index.js"
38
- },
39
26
  "./views": {
40
27
  "types": "./dist/views/index.d.ts",
41
28
  "svelte": "./dist/views/index.js",
@@ -48,14 +35,15 @@
48
35
  "LICENSE"
49
36
  ],
50
37
  "scripts": {
51
- "build": "svelte-package -i src -o dist",
38
+ "clean": "bun -e \"import('node:fs').then(({rmSync}) => rmSync('dist', { recursive: true, force: true }))\"",
39
+ "build": "bun run --bun clean && svelte-package -i src -o dist",
52
40
  "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 test/use-view.svelte.test.ts && node test/verify-inline-ssr.mjs",
54
- "pack:check": "bun pm pack --dry-run",
55
- "test:inline-browser": "node test/verify-inline-ssr.mjs && node test/verify-inline-hydration.mjs"
41
+ "test": "bun run --bun build && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && vitest run test/use-view.svelte.test.ts test/glue.svelte.test.ts",
42
+ "pack:check": "bun pm pack --dry-run"
56
43
  },
57
44
  "peerDependencies": {
58
- "svelte": ">=5.46.4 <6"
45
+ "svelte": ">=5.46.4 <6",
46
+ "@runic-artifex/views": "0.7.0-preview.1"
59
47
  },
60
48
  "publishConfig": {
61
49
  "access": "public",
@@ -71,6 +59,7 @@
71
59
  "node": ">=24.18.0 <25"
72
60
  },
73
61
  "devDependencies": {
62
+ "@runic-artifex/views": "0.7.0-preview.1",
74
63
  "@sveltejs/adapter-static": "4.0.0",
75
64
  "@sveltejs/kit": "3.0.0",
76
65
  "@sveltejs/package": "3.0.0",
@@ -83,5 +72,5 @@
83
72
  "vitest": "5.0.3",
84
73
  "vite": "8.3.2"
85
74
  },
86
- "gitHead": "3026ada4e531cf58ba5081d8ee53b32b60f1ab6a"
75
+ "gitHead": "7bc41a71c8a4d22ff5855e56b51067d6c02699c1"
87
76
  }
@@ -1,61 +0,0 @@
1
- <script lang="ts">
2
- import type { Snippet } from "svelte";
3
- import type { InlineNode, InlineElement, InlineSnippets } from "./types.js";
4
- let { nodes, custom = {} }: { nodes: readonly InlineNode[]; custom?: InlineSnippets } = $props();
5
- const iconLabels = new WeakMap<InlineElement, string>();
6
- function snippet(name: string): Snippet<[InlineElement]> {
7
- const render = custom[name];
8
- if (!render) throw new TypeError(`No Svelte snippet linked for '${name}'.`);
9
- return render;
10
- }
11
- function icon(value: unknown): Snippet {
12
- if (typeof value !== "function") throw new TypeError("Svelte icon assets must be text or snippets.");
13
- return value as Snippet;
14
- }
15
- function iconLabel(node: InlineElement): string | undefined {
16
- if (node.binding?.kind !== "runic:icon" || node.binding.decorative) return undefined;
17
- const cached = iconLabels.get(node);
18
- if (cached !== undefined) return cached;
19
- const label = node.binding.accessibleName?.(node.locale);
20
- if (typeof label !== "string" || !label.trim()) throw new TypeError("Meaningful icon alternate text is empty.");
21
- iconLabels.set(node, label);
22
- return label;
23
- }
24
- </script>
25
-
26
- {#snippet renderNodes(items: readonly InlineNode[])}
27
- {#each items as node (node.kind === "text" ? node : node.occurrence)}
28
- {#if node.kind === "text"}
29
- {node.value}
30
- {:else if node.name === "runic:strong"}
31
- <strong data-runic-occurrence={node.occurrence}>{@render renderNodes(node.children)}</strong>
32
- {:else if node.name === "runic:em"}
33
- <em data-runic-occurrence={node.occurrence}>{@render renderNodes(node.children)}</em>
34
- {:else if node.name === "runic:bold" || node.name === "runic:italic"}
35
- <span class={{ bold: node.name === "runic:bold", italic: node.name === "runic:italic" }} data-runic-occurrence={node.occurrence}>{@render renderNodes(node.children)}</span>
36
- {:else if node.name === "runic:code"}
37
- <code data-runic-occurrence={node.occurrence}>{@render renderNodes(node.children)}</code>
38
- {:else if node.name === "runic:br"}
39
- <br data-runic-occurrence={node.occurrence} />
40
- {:else if node.binding?.kind === "runic:link"}
41
- <a href={node.binding.href} data-runic-occurrence={node.occurrence}>{@render renderNodes(node.children)}</a>
42
- {:else if node.binding?.kind === "runic:action"}
43
- <button type="button" onclick={node.binding.onActivate} data-runic-occurrence={node.occurrence}>{@render renderNodes(node.children)}</button>
44
- {:else if node.binding?.kind === "runic:icon"}
45
- <span role={node.binding.decorative ? undefined : "img"} aria-hidden={node.binding.decorative ? "true" : undefined} aria-label={iconLabel(node)} data-runic-occurrence={node.occurrence}>
46
- {#if typeof node.binding.asset === "string"}{node.binding.asset}{:else}{@render icon(node.binding.asset)()}{/if}
47
- </span>
48
- {:else}
49
- {@render snippet(node.name)(node)}
50
- {/if}
51
- {/each}
52
- {/snippet}
53
-
54
- {@render renderNodes(nodes)}
55
-
56
- <style>
57
- .bold { font-weight: var(--runic-inline-bold-weight, bold); }
58
- .italic { font-style: italic; }
59
- a { color: var(--runic-inline-link-color, LinkText); }
60
- button { font: inherit; }
61
- </style>
@@ -1,8 +0,0 @@
1
- import type { InlineNode, InlineSnippets } from "./types.js";
2
- type $$ComponentProps = {
3
- nodes: readonly InlineNode[];
4
- custom?: InlineSnippets;
5
- };
6
- declare const LocalizedInline: import("svelte").Component<$$ComponentProps, {}, "">;
7
- type LocalizedInline = ReturnType<typeof LocalizedInline>;
8
- export default LocalizedInline;
@@ -1,3 +0,0 @@
1
- export { default as LocalizedInline } from "./LocalizedInline.svelte";
2
- export { inlineFactory } from "./types.js";
3
- export type { InlineBinding, InlineElement, InlineNode, InlineSnippets } from "./types.js";
@@ -1,2 +0,0 @@
1
- export { default as LocalizedInline } from "./LocalizedInline.svelte";
2
- export { inlineFactory } from "./types.js";
@@ -1,34 +0,0 @@
1
- import type { Snippet } from "svelte";
2
- export type InlineBinding = Readonly<{
3
- kind: "runic:link";
4
- href: string;
5
- }> | Readonly<{
6
- kind: "runic:action";
7
- onActivate: () => void;
8
- }> | Readonly<{
9
- kind: "runic:icon";
10
- asset: unknown;
11
- decorative: boolean;
12
- accessibleName?: (locale: string) => string;
13
- }>;
14
- export interface InlineElement {
15
- readonly name: string;
16
- readonly children: readonly InlineNode[];
17
- readonly options: Readonly<Record<string, string>>;
18
- readonly binding?: InlineBinding;
19
- readonly occurrence: string;
20
- readonly locale: string;
21
- readonly standalone?: boolean;
22
- }
23
- export type InlineNode = Readonly<{
24
- kind: "text";
25
- value: string;
26
- }> | Readonly<InlineElement & {
27
- kind: "element";
28
- }>;
29
- export type InlineSnippets = Readonly<Record<string, Snippet<[InlineElement]>>>;
30
- /** Pass this factory to the catalog-generated createInlineRenderer once per application/feature. */
31
- export declare const inlineFactory: Readonly<{
32
- text: (value: string) => InlineNode;
33
- element: (element: InlineElement) => InlineNode;
34
- }>;
@@ -1,5 +0,0 @@
1
- /** Pass this factory to the catalog-generated createInlineRenderer once per application/feature. */
2
- export const inlineFactory = Object.freeze({
3
- text: (value) => Object.freeze({ kind: "text", value }),
4
- element: (element) => Object.freeze({ ...element, kind: "element" }),
5
- });
@@ -1,15 +0,0 @@
1
- import { type LocaleSource, type SvelteLocale, type SvelteLocaleOptions } from "./locale.svelte.js";
2
- export interface LocaleContext<Locale extends string> {
3
- provide(source: LocaleSource<Locale>, options?: SvelteLocaleOptions<Locale> & Readonly<{
4
- dispose?: boolean;
5
- }>): SvelteLocale<Locale>;
6
- provideState(state: SvelteLocale<Locale>, options?: Readonly<{
7
- dispose?: boolean;
8
- }>): SvelteLocale<Locale>;
9
- use(): SvelteLocale<Locale>;
10
- }
11
- /**
12
- * Creates an application-owned typed context. Call this once in a normal module,
13
- * then provide it from a layout/component and consume it below that boundary.
14
- */
15
- export declare function createLocaleContext<Locale extends string = string>(): LocaleContext<Locale>;
@@ -1,25 +0,0 @@
1
- import { createContext, onDestroy } from "svelte";
2
- import { createSvelteLocale, } from "./locale.svelte.js";
3
- /**
4
- * Creates an application-owned typed context. Call this once in a normal module,
5
- * then provide it from a layout/component and consume it below that boundary.
6
- */
7
- export function createLocaleContext() {
8
- const [use, set] = createContext();
9
- function provideState(state, options = {}) {
10
- set(state);
11
- onDestroy(() => {
12
- if (options.dispose ?? true)
13
- state.dispose();
14
- });
15
- return state;
16
- }
17
- return {
18
- provide(source, options = {}) {
19
- const state = createSvelteLocale(source, options);
20
- return provideState(state, options);
21
- },
22
- provideState,
23
- use,
24
- };
25
- }
@@ -1,2 +0,0 @@
1
- export * from "./context.svelte.js";
2
- export * from "./locale.svelte.js";
@@ -1,2 +0,0 @@
1
- export * from "./context.svelte.js";
2
- export * from "./locale.svelte.js";
@@ -1,35 +0,0 @@
1
- /**
2
- * Structural copy of the framework-neutral Runic Translations locale contract.
3
- * Keeping this structural avoids making generated translations a runtime
4
- * dependency of the Svelte adapter.
5
- */
6
- export interface LocaleSource<Locale extends string = string> {
7
- getLocale(): Locale;
8
- subscribe(listener: (locale: Locale) => void): () => void;
9
- }
10
- export interface MutableLocaleSource<Locale extends string = string> extends LocaleSource<Locale> {
11
- setLocale(locale: Locale): void;
12
- }
13
- export interface SvelteLocaleOptions<Locale extends string> {
14
- /**
15
- * Requests a locale change when the source itself is not authoritative.
16
- * A SvelteKit application normally uses this to navigate to a localized URL;
17
- * the navigation then updates the source.
18
- */
19
- readonly requestLocale?: (locale: Locale) => void | Promise<void>;
20
- }
21
- export declare class SvelteLocale<Locale extends string = string> {
22
- #private;
23
- constructor(source: LocaleSource<Locale>, options?: SvelteLocaleOptions<Locale>);
24
- get locale(): Locale;
25
- get disposed(): boolean;
26
- /** A fresh object suitable for the generated message function's options argument. */
27
- get messageOptions(): Readonly<{
28
- locale: Locale;
29
- }>;
30
- /** Pulls the authoritative value after an external settings or navigation change. */
31
- refresh(): Locale;
32
- setLocale(locale: Locale): Promise<void>;
33
- dispose(): void;
34
- }
35
- export declare function createSvelteLocale<Locale extends string>(source: LocaleSource<Locale>, options?: SvelteLocaleOptions<Locale>): SvelteLocale<Locale>;
@@ -1,65 +0,0 @@
1
- export class SvelteLocale {
2
- #locale;
3
- #disposed = $state(false);
4
- #source;
5
- #requestLocale;
6
- #unsubscribe;
7
- constructor(source, options = {}) {
8
- this.#source = source;
9
- this.#requestLocale = options.requestLocale;
10
- this.#locale = $state.raw(source.getLocale());
11
- this.#unsubscribe = source.subscribe((locale) => {
12
- if (!this.#disposed)
13
- this.#locale = locale;
14
- });
15
- }
16
- get locale() {
17
- return this.#locale;
18
- }
19
- get disposed() {
20
- return this.#disposed;
21
- }
22
- /** A fresh object suitable for the generated message function's options argument. */
23
- get messageOptions() {
24
- return { locale: this.#locale };
25
- }
26
- /** Pulls the authoritative value after an external settings or navigation change. */
27
- refresh() {
28
- this.#assertActive();
29
- this.#locale = this.#source.getLocale();
30
- return this.#locale;
31
- }
32
- async setLocale(locale) {
33
- this.#assertActive();
34
- if (this.#requestLocale) {
35
- await this.#requestLocale(locale);
36
- }
37
- else if (isMutableLocaleSource(this.#source)) {
38
- this.#source.setLocale(locale);
39
- }
40
- else {
41
- throw new Error("This locale source is read-only. Provide requestLocale to change it through application settings or navigation.");
42
- }
43
- // Navigation can replace and dispose the providing layout before its
44
- // Promise settles. The destination owns the next locale state in that case.
45
- if (!this.#disposed)
46
- this.refresh();
47
- }
48
- dispose() {
49
- if (this.#disposed)
50
- return;
51
- this.#disposed = true;
52
- this.#unsubscribe?.();
53
- this.#unsubscribe = undefined;
54
- }
55
- #assertActive() {
56
- if (this.#disposed)
57
- throw new Error("The Svelte locale state is disposed.");
58
- }
59
- }
60
- export function createSvelteLocale(source, options = {}) {
61
- return new SvelteLocale(source, options);
62
- }
63
- function isMutableLocaleSource(source) {
64
- return "setLocale" in source && typeof source.setLocale === "function";
65
- }
@@ -1,38 +0,0 @@
1
- /**
2
- * Stable, framework-neutral presentation cases for exercising a localized
3
- * Runic application. They intentionally contain no renderer, catalog, or
4
- * application state: a consumer mounts these values in its own UI tests.
5
- */
6
- export type LocalizationStressDirection = "ltr" | "rtl";
7
- export interface LocalizationStressCase {
8
- readonly id: string;
9
- readonly locale: string;
10
- readonly direction: LocalizationStressDirection;
11
- readonly text: string;
12
- readonly checks: readonly string[];
13
- }
14
- export interface VisualAccessibilityStressScenario {
15
- readonly id: string;
16
- readonly mediaQuery: string;
17
- readonly checks: readonly string[];
18
- }
19
- export declare const pluralStressCounts: readonly [0, 1, 2, 5, 11, 21, 101, 1000];
20
- /** Wraps a value in a first-strong isolate so mixed-direction identifiers stay ordered. */
21
- export declare function isolateBidi(text: string): string;
22
- /**
23
- * Produces an intentionally expanded pseudo-locale while leaving `{placeholders}`
24
- * byte-for-byte intact. Use it to expose clipped labels and hard-coded strings.
25
- */
26
- export declare function pseudoLocalize(text: string): string;
27
- /** Attributes to apply when mounting a case in DOM-oriented test harnesses. */
28
- export declare function localizationStressAttributes(stressCase: LocalizationStressCase): Readonly<{
29
- lang: string;
30
- dir: LocalizationStressDirection;
31
- }>;
32
- export declare const localizationStressCases: readonly LocalizationStressCase[];
33
- /**
34
- * These browser media queries are the canonical minimum visual regression
35
- * matrix. Consumers assert the named properties in their own design system;
36
- * this package cannot author their colors or animation policy for them.
37
- */
38
- export declare const visualAccessibilityStressScenarios: readonly VisualAccessibilityStressScenario[];
@@ -1,68 +0,0 @@
1
- export const pluralStressCounts = [0, 1, 2, 5, 11, 21, 101, 1000];
2
- const pseudoCharacters = {
3
- A: "ÅÅ", B: "ß", C: "Ç", D: "Ð", E: "ÉÉ", F: "Ƒ", G: "Ğ", H: "Ħ", I: "ÏÏ", J: "Ĵ", K: "Ķ", L: "Ŀ", M: "Ḿ", N: "Ń", O: "ØØ", P: "Þ", Q: "Ǫ", R: "Ŕ", S: "Š", T: "Ŧ", U: "ÜÜ", V: "Ṽ", W: "Ŵ", X: "Ẋ", Y: "Ý", Z: "Ž",
4
- a: "áá", b: "ƀ", c: "ç", d: "đ", e: "éé", f: "ƒ", g: "ğ", h: "ħ", i: "ïï", j: "ĵ", k: "ķ", l: "ŀ", m: "ḿ", n: "ń", o: "øø", p: "þ", q: "ǫ", r: "ŕ", s: "š", t: "ŧ", u: "üü", v: "ṽ", w: "ŵ", x: "ẋ", y: "ý", z: "ž",
5
- };
6
- /** Wraps a value in a first-strong isolate so mixed-direction identifiers stay ordered. */
7
- export function isolateBidi(text) {
8
- return `\u2068${text}\u2069`;
9
- }
10
- /**
11
- * Produces an intentionally expanded pseudo-locale while leaving `{placeholders}`
12
- * byte-for-byte intact. Use it to expose clipped labels and hard-coded strings.
13
- */
14
- export function pseudoLocalize(text) {
15
- return `[${text.split(/(\{[^{}]*\})/u).map((part) => part.startsWith("{") && part.endsWith("}") ? part : pseudoLocalizeLiteral(part)).join("")}~]`;
16
- }
17
- /** Attributes to apply when mounting a case in DOM-oriented test harnesses. */
18
- export function localizationStressAttributes(stressCase) {
19
- return { lang: stressCase.locale, dir: stressCase.direction };
20
- }
21
- export const localizationStressCases = [
22
- {
23
- id: "pseudo-locale-long-action",
24
- locale: "en-XA",
25
- direction: "ltr",
26
- text: pseudoLocalize("Synchronize the selected documents before you close this window."),
27
- checks: ["text wraps without clipping", "actions remain identifiable", "no literal bypasses localization"],
28
- },
29
- {
30
- id: "plural-boundaries",
31
- locale: "en-XA",
32
- direction: "ltr",
33
- text: pseudoLocalize("{count} selected documents still need your review."),
34
- checks: ["render every pluralStressCounts value", "plural output stays readable at extreme counts"],
35
- },
36
- {
37
- id: "rtl-mixed-identifier",
38
- locale: "ar-XB",
39
- direction: "rtl",
40
- text: `تم حفظ ${isolateBidi("Setup-2026-08-30.json")} بنجاح.`,
41
- checks: ["mixed-direction identifiers retain order", "layout mirrors without changing semantic order"],
42
- },
43
- ];
44
- /**
45
- * These browser media queries are the canonical minimum visual regression
46
- * matrix. Consumers assert the named properties in their own design system;
47
- * this package cannot author their colors or animation policy for them.
48
- */
49
- export const visualAccessibilityStressScenarios = [
50
- {
51
- id: "forced-colors",
52
- mediaQuery: "(forced-colors: active)",
53
- checks: ["controls remain visible", "focus indicator remains visible", "meaning is not color-only"],
54
- },
55
- {
56
- id: "high-contrast",
57
- mediaQuery: "(prefers-contrast: more)",
58
- checks: ["text and control boundaries remain distinguishable", "status is not color-only"],
59
- },
60
- {
61
- id: "reduced-motion",
62
- mediaQuery: "(prefers-reduced-motion: reduce)",
63
- checks: ["non-essential animation is removed or shortened", "state changes remain understandable"],
64
- },
65
- ];
66
- function pseudoLocalizeLiteral(text) {
67
- return text.replace(/[A-Za-z]/gu, (character) => pseudoCharacters[character] ?? character);
68
- }