@runic-artifex/vite-plugin-runic 0.18.0 → 0.20.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.
@@ -0,0 +1,268 @@
1
+ import type { RunicSourceMap, RunicSourceMember, RunicSourceMemberKind, RunicSourceViewModel } from "./sources.js";
2
+ import type { SourceBindings } from "./inspect-handlers.js";
3
+ /**
4
+ * A source location of the overview, with how "open in editor" opens it: `runic` posts the source map entry's `id` to
5
+ * `/__runic/open`; `translations` posts the `message` to `/__runic/open`, which asks the Translations dev server where
6
+ * it is; `vite` posts the frontend file's path to it, which opens only a file Vite serves.
7
+ */
8
+ export interface RunicInspectLocation {
9
+ readonly file: string;
10
+ /** 1-based. */
11
+ readonly line: number;
12
+ /** 1-based. */
13
+ readonly column: number;
14
+ readonly editor: "runic" | "translations" | "vite";
15
+ /** The source map entry, for `editor: "runic"`. */
16
+ readonly id?: string;
17
+ /** The message, for `editor: "translations"`. */
18
+ readonly message?: {
19
+ readonly catalog: string;
20
+ readonly key: string;
21
+ readonly locale: string;
22
+ };
23
+ }
24
+ /** The element's framework component, as the framework's own development metadata gives it. */
25
+ export interface RunicInspectComponent {
26
+ readonly framework: "react" | "vue" | "svelte" | "angular";
27
+ readonly name: string;
28
+ /** The components around it, innermost first. */
29
+ readonly owners: readonly string[];
30
+ /**
31
+ * React: where the element's JSX is (from `_debugStack` through the module's source map); Svelte: where the element
32
+ * is in the component; Vue: the component's file (line 1); Angular: the component class.
33
+ */
34
+ readonly location?: RunicInspectLocation;
35
+ }
36
+ /** A ViewModel the element is connected to. */
37
+ export interface RunicInspectViewModel {
38
+ readonly route: string;
39
+ /** The C# type: the source map's ViewModel id. */
40
+ readonly id?: string;
41
+ readonly name?: string;
42
+ readonly contract?: string;
43
+ readonly location?: RunicInspectLocation;
44
+ }
45
+ /**
46
+ * How the overview knows a member belongs to the element: `call` (the element made a Bridge call to it), `text` (the
47
+ * element's text is the member's value), `value` (a form control's value is the member's value). `text` and `value`
48
+ * are matches, not proof.
49
+ */
50
+ export type RunicInspectEvidence = "call" | "text" | "value";
51
+ /** A ViewModel member the element binds, with its current value and its C# member. */
52
+ export interface RunicInspectMember {
53
+ readonly route: string;
54
+ readonly viewModel?: string;
55
+ readonly member: string;
56
+ readonly kind: RunicSourceMemberKind;
57
+ readonly evidence: RunicInspectEvidence;
58
+ /** The member's current value in the View's state, shortened. */
59
+ readonly value?: unknown;
60
+ /** The C# member that runs, such as `Demo.CounterViewModel.Step.set`. */
61
+ readonly symbol?: string;
62
+ readonly location?: RunicInspectLocation;
63
+ }
64
+ /** A command the element calls, with its C# handler. */
65
+ export interface RunicInspectCommand {
66
+ readonly route: string;
67
+ readonly viewModel?: string;
68
+ readonly member: string;
69
+ /**
70
+ * How the overview knows it: `call` (the element made a Bridge call to it) or `source` (its event handler reaches
71
+ * the client call in the component's file, found before any click).
72
+ */
73
+ readonly evidence: "call" | "source";
74
+ /** Where the handler reaches the client call (`client.increment()`), when the source shows it. */
75
+ readonly frontend?: RunicInspectLocation;
76
+ /** `direct`: in the handler; `helper`: through `useCommand`/`injectCommand`-style helpers; `local`: through another declaration of the file. */
77
+ readonly via?: "direct" | "helper" | "local";
78
+ /** The handler, such as `Demo.CounterViewModel.Increment()`, and the command property. */
79
+ readonly symbol?: string;
80
+ readonly property?: string;
81
+ readonly location?: RunicInspectLocation;
82
+ /** The value of the command's availability state (`canIncrement`) when the ViewModel has one. */
83
+ readonly canExecute?: unknown;
84
+ /** How many calls of it the element made in this page. */
85
+ readonly calls: number;
86
+ }
87
+ /** A Bridge call the element made. Times are `performance.now()` milliseconds. */
88
+ export interface RunicInspectCall {
89
+ readonly id: number;
90
+ readonly kind: string;
91
+ readonly request: string;
92
+ readonly route: string;
93
+ readonly member: string;
94
+ readonly start: number;
95
+ readonly duration?: number;
96
+ readonly outcome?: string;
97
+ readonly reason?: string;
98
+ readonly revision?: number;
99
+ }
100
+ /** A text the ViewModel sent as a Runic Translations text reference, which the element shows. */
101
+ export interface RunicInspectText {
102
+ readonly route: string;
103
+ /** Where the reference is in the state: `status`, `items.2.label`. */
104
+ readonly path: string;
105
+ readonly catalog: string;
106
+ readonly key: string;
107
+ readonly locale?: string;
108
+ readonly text: string;
109
+ readonly arguments: unknown;
110
+ }
111
+ /**
112
+ * A message of a generated `m.*()` call that the element shows. Runic Translations marks the text of these calls while
113
+ * select mode is on (the `markers` of its text-change channel), so they are known only then.
114
+ */
115
+ export interface RunicInspectMessage {
116
+ readonly catalog: string;
117
+ readonly key: string;
118
+ /** The locale whose text the element shows (a fallback names the fallback locale). */
119
+ readonly locale: string;
120
+ /** Where the element shows it: `text` (its text or a descendant's), or an attribute such as `title` or `aria-label`. */
121
+ readonly in: readonly string[];
122
+ /** The message in that locale as authored (MF2), from the Translations dev server. */
123
+ readonly source?: string;
124
+ /** Where that text is defined, in its `.rmf2`/`.mf2` source. */
125
+ readonly location?: RunicInspectLocation;
126
+ /**
127
+ * Whether the Translations dev server's in-page editing API can write the message in some locale, so the overview
128
+ * offers "Edit" (the API's `locales[].editable`). Absent when the API did not answer.
129
+ */
130
+ readonly editable?: boolean;
131
+ }
132
+ /** What Runic Inspect and `describe(element)` report for an element. */
133
+ export interface RunicInspectDescription {
134
+ readonly element: {
135
+ readonly tag: string;
136
+ readonly id?: string;
137
+ readonly classes: readonly string[];
138
+ readonly role?: string;
139
+ /** The element's text, whitespace collapsed, shortened. */
140
+ readonly text: string;
141
+ };
142
+ readonly component?: RunicInspectComponent;
143
+ readonly viewModels: readonly RunicInspectViewModel[];
144
+ readonly members: readonly RunicInspectMember[];
145
+ readonly commands: readonly RunicInspectCommand[];
146
+ /** The element's recent Bridge calls, newest first. */
147
+ readonly calls: readonly RunicInspectCall[];
148
+ readonly texts: readonly RunicInspectText[];
149
+ /** The messages of generated `m.*()` calls it shows (select mode only). */
150
+ readonly messages: readonly RunicInspectMessage[];
151
+ /** What the overview cannot tell, and why. */
152
+ readonly notes: readonly string[];
153
+ }
154
+ /** A Bridge call kind as the call channel reports it, which the element was seen making. */
155
+ export interface LearnedBinding {
156
+ readonly route: string;
157
+ readonly contract: string;
158
+ readonly kind: string;
159
+ readonly member: string;
160
+ }
161
+ /** What inspect.ts read from the page for one element. */
162
+ export interface InspectInput {
163
+ readonly element: RunicInspectDescription["element"] & {
164
+ /** The element's own text (its text nodes), for matching state values. */
165
+ readonly ownText: string;
166
+ /** A form control's value. */
167
+ readonly value?: string;
168
+ /** Whether it is a control that makes Bridge calls when used (a button, link, form field). */
169
+ readonly interactive: boolean;
170
+ };
171
+ readonly learned: readonly LearnedBinding[];
172
+ readonly calls: readonly RunicInspectCall[];
173
+ /** Each open route's latest state, from the state inspector channel. */
174
+ readonly states: ReadonlyMap<string, unknown>;
175
+ /** Each route's contract, from the Bridge calls seen. */
176
+ readonly contracts: ReadonlyMap<string, string>;
177
+ readonly sourceMap?: RunicSourceMap | undefined;
178
+ /** Why there is no source map, for the notes: `forbidden` when the server refused this client (another machine). */
179
+ readonly sourceMapStatus?: "missing" | "unavailable" | "forbidden";
180
+ /** `forbidden` when the server refused this client the handler analysis (`/__runic/handlers`). */
181
+ readonly handlersStatus?: "forbidden" | undefined;
182
+ /**
183
+ * Whether the page is opened from another machine than the development server's (its address is not localhost), so
184
+ * `/__runic/open`, which launches the editor on the development machine, refuses it.
185
+ */
186
+ readonly remote?: boolean | undefined;
187
+ readonly component?: RunicInspectComponent | undefined;
188
+ /** The element's event bindings in its components' source and the client calls they reach (handlers.ts). */
189
+ readonly source?: SourceBindings | undefined;
190
+ /** The messages the element's markers name, with their sources where the Translations dev server knows them. */
191
+ readonly messages?: readonly RunicInspectMessage[] | undefined;
192
+ /**
193
+ * Whether message markers were readable: `on` (select mode had them on), `off` (the page has them, but not on now),
194
+ * `unsupported` (the page's Runic Translations has no markers), `none` (no Runic Translations text on the page).
195
+ */
196
+ readonly markerStatus?: "on" | "off" | "unsupported" | "none" | undefined;
197
+ /**
198
+ * Why the messages have no source locations: the Translations dev server's message API did not answer, or refused
199
+ * this client (`forbidden`).
200
+ */
201
+ readonly messageSourcesStatus?: "unavailable" | "forbidden" | undefined;
202
+ /** Formats a text reference as the page shows it, with the locale it used. */
203
+ readonly resolveText?: ((reference: TextReferenceLike) => {
204
+ readonly text: string;
205
+ readonly locale?: string;
206
+ } | undefined) | undefined;
207
+ }
208
+ /** A Runic Translations text reference on the wire (`@runic-artifex/views` `TextReference`). */
209
+ export interface TextReferenceLike {
210
+ readonly version: number;
211
+ readonly catalog: string;
212
+ readonly contractFingerprint: string;
213
+ readonly key: string;
214
+ readonly arguments: Readonly<Record<string, unknown>>;
215
+ readonly fallbackText?: string | null;
216
+ }
217
+ /** Text without Runic Translations message markers. */
218
+ export declare function stripMarkers(text: string): string;
219
+ /** Collapses whitespace and shortens text for the overview. */
220
+ export declare function normalizeText(text: string, maximum?: number): string;
221
+ /** A message a marker names, as the Translations channel's `markers.decode` returns it. */
222
+ export interface MarkedMessage {
223
+ readonly catalog: string;
224
+ readonly key: string;
225
+ readonly locale: string;
226
+ }
227
+ /**
228
+ * The messages that markers name, once each per catalog, key and locale, in the order they appear, with where each
229
+ * appears (`text` or an attribute name); at most 20.
230
+ */
231
+ export declare function groupMessages(found: readonly {
232
+ readonly message: unknown;
233
+ readonly in: string;
234
+ }[]): RunicInspectMessage[];
235
+ /**
236
+ * A message's text and source location in its locale, from the Runic Translations dev server's
237
+ * `GET /__runic-translations/message` reply (`{ message: { locales: [{ locale, text, source: { path, line, column } }] } }`).
238
+ * A message without a locale (a runtime that does not tell it) takes the base locale, which the reply lists first.
239
+ */
240
+ export declare function messageSource(reply: unknown, message: MarkedMessage): Pick<RunicInspectMessage, "source" | "location" | "editable">;
241
+ /** A JSON-safe, shortened copy of a state value for the overview. */
242
+ export declare function previewValue(value: unknown, depth?: number): unknown;
243
+ /** Whether a value has the shape of a text reference, as `@runic-artifex/views` checks it. */
244
+ export declare function isTextReference(value: unknown): value is TextReferenceLike;
245
+ /** The text references in a state, with their paths, at most 4 levels and 200 references deep. */
246
+ export declare function findTextReferences(state: unknown): {
247
+ readonly path: string;
248
+ readonly reference: TextReferenceLike;
249
+ }[];
250
+ /** The member kind a Bridge call kind reaches in the source map, in the order to look it up. */
251
+ export declare function memberKinds(callKind: string): readonly RunicSourceMemberKind[];
252
+ /** Indexes of a source map for the lookups of an overview. */
253
+ export interface SourceIndex {
254
+ readonly viewModels: ReadonlyMap<string, RunicSourceViewModel>;
255
+ readonly members: ReadonlyMap<string, RunicSourceMember>;
256
+ /** A ViewModel's state and command-state member names. */
257
+ readonly stateMembers: ReadonlyMap<string, ReadonlySet<string>>;
258
+ readonly map: RunicSourceMap;
259
+ }
260
+ export declare function indexSourceMap(map: RunicSourceMap): SourceIndex;
261
+ /**
262
+ * The ViewModel of a route: by the contract its calls carried, else by the route `connect<Name>()` connects, else the
263
+ * one ViewModel whose state members are exactly the route's state keys (a View presented as content connects a route
264
+ * of its own, such as `content1`).
265
+ */
266
+ export declare function viewModelForRoute(index: SourceIndex, route: string, contract: string | undefined, state: unknown): RunicSourceViewModel | undefined;
267
+ /** Assembles the overview of an element from what was read for it. */
268
+ export declare function assembleDescription(input: InspectInput): RunicInspectDescription;