@deviltea/widget-core 0.0.1 → 0.0.3
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 +73 -12
- package/dist/{internals-DXFEmv8H.mjs → contract-CRpMqCY2.mjs} +8 -12
- package/dist/{dep-DKQpJwdW.d.mts → dep-DAoSoLhi.d.mts} +156 -26
- package/dist/event-BMif_vRJ.mjs +192 -0
- package/dist/index.d.mts +11 -2
- package/dist/index.mjs +149 -360
- package/dist/inspection/index.d.mts +79 -2
- package/dist/inspection/index.mjs +112 -10
- package/dist/integration/index.d.mts +12 -0
- package/dist/integration/index.mjs +26 -0
- package/dist/internals-L391flXY.mjs +199 -0
- package/package.json +12 -6
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# @deviltea/widget-core
|
|
2
2
|
|
|
3
3
|
Cross-cutting Diagnostic/Result/Failure/Error conventions are maintained in
|
|
4
|
-
[Widget API conventions](
|
|
4
|
+
[Widget API conventions](https://github.com/DevilTea/widget/blob/main/docs/architecture/widget-api-conventions.md).
|
|
5
5
|
|
|
6
6
|
> ESM-only package.
|
|
7
7
|
|
|
@@ -52,7 +52,7 @@ A renderer/integration layer consumes the Runtime; the core itself knows
|
|
|
52
52
|
nothing about rendering, persistence versioning, or metadata. Source editing
|
|
53
53
|
is limited to the revisioned `WidgetDocument` and JSON-domain `SourcePatch`
|
|
54
54
|
contract described below. See
|
|
55
|
-
[Design constraints](https://deviltea.github.io/
|
|
55
|
+
[Design constraints](https://deviltea.github.io/widget/packages/widget-core#design-constraints)
|
|
56
56
|
in the full guide for the exact boundary.
|
|
57
57
|
|
|
58
58
|
Capability presence (`config`/`slots`/`state`/`properties`/`methods`) is
|
|
@@ -60,7 +60,19 @@ declaration presence, independent of whether a capability's own domain is
|
|
|
60
60
|
empty — a completed plugin exposes these facts at runtime as
|
|
61
61
|
`plugin.capabilities: { config, slots, state, properties, methods }`
|
|
62
62
|
(all `boolean`, immutable). See
|
|
63
|
-
[Reading capability presence at runtime](https://deviltea.github.io/
|
|
63
|
+
[Reading capability presence at runtime](https://deviltea.github.io/widget/packages/widget-core#reading-capability-presence-at-runtime-plugin-capabilities)
|
|
64
|
+
in the full guide.
|
|
65
|
+
|
|
66
|
+
`createWidgetSystem` rejects invalid plugin registration with the coded
|
|
67
|
+
`WidgetSystemConfigurationError`: `foreign-plugin` (entry not created by this
|
|
68
|
+
loaded module instance; fields `pluginIndex`, `pluginType`, with
|
|
69
|
+
`firstPluginIndex` always `null`) and `duplicate-plugin-type` (fields
|
|
70
|
+
`pluginIndex`, `pluginType`, `firstPluginIndex`).
|
|
71
|
+
Inspection entries throw `WidgetInspectionError` (`@deviltea/widget-core/inspection`)
|
|
72
|
+
and `getWidgetEventEmitter` throws `WidgetIntegrationError`
|
|
73
|
+
(`@deviltea/widget-core/integration`, code `foreign-runtime`) for foreign inputs.
|
|
74
|
+
See
|
|
75
|
+
[Plugin registration errors](https://deviltea.github.io/widget/packages/widget-core#plugin-registration-errors)
|
|
64
76
|
in the full guide.
|
|
65
77
|
|
|
66
78
|
Plugin, config, and slot descriptions are required intrinsic metadata. The
|
|
@@ -234,6 +246,46 @@ if (result.ok && result.changed)
|
|
|
234
246
|
console.log(document.getSnapshot().revision) // 1
|
|
235
247
|
```
|
|
236
248
|
|
|
249
|
+
Authored source is handed to Core **by reference**: `createBlueprint`,
|
|
250
|
+
`recompile` and `createWidgetDocument` keep `source` as given, so
|
|
251
|
+
`blueprint.source` is the exact input and Core never clones or freezes it.
|
|
252
|
+
Passing source transfers ownership; do not mutate it afterwards (behavior is
|
|
253
|
+
unspecified), and pass a copy such as `structuredClone` if you keep editing
|
|
254
|
+
your own object. "Immutable" Blueprint describes Core's API, not a defensive
|
|
255
|
+
copy. `applyPatch` never mutates the accepted source, but copy-on-write
|
|
256
|
+
revisions share untouched subtrees with the previous revision and so with the
|
|
257
|
+
original input. See the
|
|
258
|
+
[Core model](https://deviltea.github.io/widget/packages/widget-core#core-model)
|
|
259
|
+
ownership rules.
|
|
260
|
+
|
|
261
|
+
`applyPatch(patch, options?)` returns `{ ok: true, changed }` or
|
|
262
|
+
`{ ok: false, failure }`. A patch that leaves the source structurally equal
|
|
263
|
+
returns `{ ok: true, changed: false }`: the revision does not advance and
|
|
264
|
+
subscribers are not notified. A changing patch compiles the next Blueprint once
|
|
265
|
+
after all operations succeed, commits it at `revision + 1`, then notifies
|
|
266
|
+
subscribers. `failure.code` is one of:
|
|
267
|
+
|
|
268
|
+
- `reentrant-apply`: `applyPatch()` was called while the Document was applying
|
|
269
|
+
or notifying (for example from a subscriber). It is checked first.
|
|
270
|
+
- `document-revision-conflict`: `options.expectedRevision` was supplied and
|
|
271
|
+
differs from the current revision. The failure carries `expectedRevision` and
|
|
272
|
+
`actualRevision`. Omitting `options` skips this check, and the check runs
|
|
273
|
+
before any operation is evaluated.
|
|
274
|
+
- An operation failure `{ code, operationIndex, message }`, where `code` is
|
|
275
|
+
`invalid-path`, `path-not-found`, `path-not-traversable`,
|
|
276
|
+
`invalid-array-index`, `invalid-move-target`, `test-failed`, or
|
|
277
|
+
`source-access-failed`, and `operationIndex` is the failing operation's
|
|
278
|
+
position in the patch. A failed patch leaves the committed source and revision
|
|
279
|
+
unchanged.
|
|
280
|
+
|
|
281
|
+
`document.subscribe(listener)` registers `listener` and returns an idempotent
|
|
282
|
+
unsubscribe function. The listener is not called on subscription; it receives
|
|
283
|
+
the new snapshot after each committed (`changed: true`) patch, in subscription
|
|
284
|
+
order, over the subscriber list as it stood when notification began. An
|
|
285
|
+
exception thrown by a listener does not fail `applyPatch()` or stop the
|
|
286
|
+
remaining listeners, and it is reported outside `applyPatch()`; the reporting
|
|
287
|
+
mechanism is not part of the contract.
|
|
288
|
+
|
|
237
289
|
### SeparatedWidgetSource tooling
|
|
238
290
|
|
|
239
291
|
`WidgetSource` is the only canonical nested authored representation. The explicit
|
|
@@ -261,6 +313,12 @@ later occurrence is de-identified with its available subtree preserved.
|
|
|
261
313
|
|
|
262
314
|
### Runtime semantics
|
|
263
315
|
|
|
316
|
+
- Declared `events` are public notifications: subscribe through
|
|
317
|
+
`widget.events[name].subscribe(listener)`. Delivery is synchronous and
|
|
318
|
+
depth-first for nested emits; a throwing public listener propagates to the
|
|
319
|
+
emit caller and stops the remaining public listeners. Emit authority belongs
|
|
320
|
+
to Method `execute` (`emit`) and, for renderers, `@deviltea/widget-core/integration`.
|
|
321
|
+
See [Events](https://deviltea.github.io/widget/packages/widget-core#events).
|
|
264
322
|
- `widget.state[key].get()` returns `T | null` directly — it is not an
|
|
265
323
|
`ExecutionResult`.
|
|
266
324
|
- `widget.properties[name].get()` / `.subscribe(listener)` and
|
|
@@ -292,28 +350,31 @@ later occurrence is de-identified with its available subtree preserved.
|
|
|
292
350
|
`WidgetSystemRuntimeDisposedError`; unsubscribe functions obtained before
|
|
293
351
|
disposal remain safe idempotent no-ops.
|
|
294
352
|
|
|
295
|
-
### Inspection
|
|
353
|
+
### Inspection
|
|
296
354
|
|
|
297
|
-
A dedicated, strictly readonly subpath
|
|
298
|
-
|
|
299
|
-
|
|
355
|
+
A dedicated, strictly readonly subpath is a supported observation surface for
|
|
356
|
+
any host (DevTools, prototype players, test harnesses). It exposes
|
|
357
|
+
compiler/runtime facts, including passive Event occurrence observation through
|
|
358
|
+
`getEvent(name).subscribe(...)`, and never mutates state, invokes methods, or
|
|
359
|
+
forces Property evaluation:
|
|
300
360
|
|
|
301
361
|
```typescript
|
|
302
362
|
import { inspectBlueprint, inspectRuntime } from '@deviltea/widget-core/inspection'
|
|
303
363
|
```
|
|
304
364
|
|
|
305
365
|
`@deviltea/widget-core`'s root entrypoint does not export this surface. See
|
|
306
|
-
[Inspection](https://deviltea.github.io/
|
|
307
|
-
in the full guide for the exact contract
|
|
366
|
+
[Inspection](https://deviltea.github.io/widget/packages/widget-core#inspection)
|
|
367
|
+
in the full guide for the exact contract, including the Event inspection
|
|
368
|
+
delivery guarantees.
|
|
308
369
|
|
|
309
370
|
The full guide at
|
|
310
|
-
[docs/site/packages/widget-core.md](https://deviltea.github.io/
|
|
371
|
+
[docs/site/packages/widget-core.md](https://deviltea.github.io/widget/packages/widget-core)
|
|
311
372
|
covers the dependency grammar, the compile pipeline, and every Runtime
|
|
312
373
|
primitive in detail.
|
|
313
374
|
|
|
314
375
|
## License
|
|
315
376
|
|
|
316
|
-
[MIT](https://github.com/DevilTea/
|
|
377
|
+
[MIT](https://github.com/DevilTea/widget/blob/main/LICENSE) License © 2023-PRESENT [DevilTea](https://github.com/DevilTea)
|
|
317
378
|
|
|
318
379
|
<!-- Badges -->
|
|
319
380
|
|
|
@@ -324,4 +385,4 @@ primitive in detail.
|
|
|
324
385
|
[bundle-src]: https://img.shields.io/bundlephobia/minzip/@deviltea/widget-core?style=flat&colorA=080f12&colorB=1fa669&label=minzip
|
|
325
386
|
[bundle-href]: https://bundlephobia.com/result?p=@deviltea/widget-core
|
|
326
387
|
[license-src]: https://img.shields.io/github/license/DevilTea/deviltea-labs.svg?style=flat&colorA=080f12&colorB=1fa669
|
|
327
|
-
[license-href]: https://github.com/DevilTea/
|
|
388
|
+
[license-href]: https://github.com/DevilTea/widget/blob/main/LICENSE
|
|
@@ -5,6 +5,13 @@ function isCompiledDependency(value) {
|
|
|
5
5
|
}
|
|
6
6
|
const blueprintInternals = Symbol("@deviltea/widget-core:blueprint-internals");
|
|
7
7
|
/**
|
|
8
|
+
* Provenance probe: true only for Blueprints produced by this loaded module instance.
|
|
9
|
+
*/
|
|
10
|
+
function isCoreBlueprint(value) {
|
|
11
|
+
if (typeof value !== "object" || value === null) return false;
|
|
12
|
+
return value[blueprintInternals] !== void 0;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
8
15
|
* Reads the compiled snapshot carried by a Blueprint.
|
|
9
16
|
*/
|
|
10
17
|
function readCompiledBlueprint(blueprint) {
|
|
@@ -13,15 +20,4 @@ function readCompiledBlueprint(blueprint) {
|
|
|
13
20
|
return compiled;
|
|
14
21
|
}
|
|
15
22
|
//#endregion
|
|
16
|
-
|
|
17
|
-
const runtimeInternals = Symbol("@deviltea/widget-core:runtime-internals");
|
|
18
|
-
/**
|
|
19
|
-
* Reads the internals carried by a Runtime produced by `createWidgetSystemRuntime`.
|
|
20
|
-
*/
|
|
21
|
-
function readRuntimeInternals(runtime) {
|
|
22
|
-
const internals = runtime[runtimeInternals];
|
|
23
|
-
if (internals === void 0) throw new Error("The runtime was not produced by this widget core build.");
|
|
24
|
-
return internals;
|
|
25
|
-
}
|
|
26
|
-
//#endregion
|
|
27
|
-
export { isCompiledDependency as a, compiledDependencyBrand as i, runtimeInternals as n, readCompiledBlueprint as o, blueprintInternals as r, readRuntimeInternals as t };
|
|
23
|
+
export { readCompiledBlueprint as a, isCoreBlueprint as i, compiledDependencyBrand as n, isCompiledDependency as r, blueprintInternals as t };
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { JSONSchema } from "json-schema-typed/draft-2020-12";
|
|
1
2
|
//#region src/json.d.ts
|
|
2
3
|
/**
|
|
3
4
|
* The authored value domain. Runtime/config-resolved values intentionally use `unknown` instead;
|
|
@@ -41,6 +42,7 @@ interface WidgetInterfaces {
|
|
|
41
42
|
state?: Record<any, any>;
|
|
42
43
|
properties?: Record<any, any>;
|
|
43
44
|
methods?: Record<any, (...args: any[]) => any>;
|
|
45
|
+
events?: Record<any, readonly any[]>;
|
|
44
46
|
}
|
|
45
47
|
/**
|
|
46
48
|
* A readonly array that is non-empty when present. Used by every optional `related` collection.
|
|
@@ -82,6 +84,7 @@ type WidgetSlotNameOf<Interfaces extends WidgetInterfaces> = Extract<WidgetCapab
|
|
|
82
84
|
type WidgetStateOf<Interfaces extends WidgetInterfaces> = WidgetCapabilityOf<Interfaces, 'state'>;
|
|
83
85
|
type WidgetPropertiesOf<Interfaces extends WidgetInterfaces> = WidgetCapabilityOf<Interfaces, 'properties'>;
|
|
84
86
|
type WidgetMethodsOf<Interfaces extends WidgetInterfaces> = WidgetCapabilityOf<Interfaces, 'methods'> extends (infer Methods extends Record<WidgetMemberKey, (...args: any[]) => any>) ? Methods : never;
|
|
87
|
+
type WidgetEventsOf<Interfaces extends WidgetInterfaces> = WidgetCapabilityOf<Interfaces, 'events'> extends (infer Events extends Record<WidgetMemberKey, readonly any[]>) ? Events : never;
|
|
85
88
|
/**
|
|
86
89
|
* Declared member keys of one section, or `never` when the capability is absent.
|
|
87
90
|
*/
|
|
@@ -89,15 +92,18 @@ type WidgetMemberKeysOf<Members> = [Members] extends [never] ? never : Extract<k
|
|
|
89
92
|
type WidgetStateKeyOf<Interfaces extends WidgetInterfaces> = WidgetMemberKeysOf<WidgetStateOf<Interfaces>>;
|
|
90
93
|
type WidgetPropertyKeyOf<Interfaces extends WidgetInterfaces> = WidgetMemberKeysOf<WidgetPropertiesOf<Interfaces>>;
|
|
91
94
|
type WidgetMethodKeyOf<Interfaces extends WidgetInterfaces> = WidgetMemberKeysOf<WidgetMethodsOf<Interfaces>>;
|
|
95
|
+
type WidgetEventKeyOf<Interfaces extends WidgetInterfaces> = WidgetMemberKeysOf<WidgetEventsOf<Interfaces>>;
|
|
92
96
|
type WidgetStateValueOf<Interfaces extends WidgetInterfaces, Key extends WidgetMemberKey> = WidgetMemberValueOf<WidgetStateOf<Interfaces>, Key>;
|
|
93
97
|
type WidgetPropertyValueOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = WidgetMemberValueOf<WidgetPropertiesOf<Interfaces>, Name>;
|
|
94
98
|
type WidgetMethodOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = Extract<WidgetMemberValueOf<WidgetMethodsOf<Interfaces>, Name>, (...args: any[]) => any>;
|
|
95
99
|
type WidgetMethodArgsOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = Parameters<WidgetMethodOf<Interfaces, Name>>;
|
|
96
100
|
type WidgetMethodReturnOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = ReturnType<WidgetMethodOf<Interfaces, Name>>;
|
|
101
|
+
type WidgetEventArgsOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = Extract<WidgetMemberValueOf<WidgetEventsOf<Interfaces>, Name>, readonly any[]>;
|
|
97
102
|
type ContainsPromiseLike<Value> = IsAny<Value> extends true ? false : [Extract<Value, PromiseLike<unknown>>] extends [never] ? false : true;
|
|
98
103
|
type MemberKeyDomainViolation<Section extends string, Members> = [Members] extends [never] ? never : [keyof Members] extends [never] ? never : [keyof Members] extends [WidgetMemberKey] ? WidgetMemberKey extends keyof Members ? `'${Section}' must not be declared with a broad string index signature` : never : `'${Section}' member keys must be finite string literals`;
|
|
99
104
|
type SyncValueDomainViolation<Section extends string, Members> = [Members] extends [never] ? never : true extends { [Key in keyof Members]-?: ContainsPromiseLike<Members[Key]>; }[keyof Members] ? `'${Section}' values must not be PromiseLike; the core semantic boundary is synchronous` : never;
|
|
100
105
|
type SyncMethodReturnViolation<Interfaces extends WidgetInterfaces> = WidgetMethodsOf<Interfaces> extends (infer Methods) ? [Methods] extends [never] ? never : true extends { [Key in keyof Methods]-?: ContainsPromiseLike<ReturnType<Extract<Methods[Key], (...args: any[]) => any>>>; }[keyof Methods] ? `'methods' return types must not be PromiseLike; the core semantic boundary is synchronous` : never : never;
|
|
106
|
+
type EventArgsDomainViolation<Interfaces extends WidgetInterfaces> = WidgetEventsOf<Interfaces> extends (infer Events) ? [Events] extends [never] ? never : { [Key in keyof Events]-?: Events[Key] extends readonly any[] ? number extends Events[Key]['length'] ? '\'events\' arguments must be declared as tuples' : never : '\'events\' arguments must be declared as tuples'; }[keyof Events] : never;
|
|
101
107
|
type SlotDomainViolation<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'slots'> extends false ? never : WidgetMemberKey extends WidgetCapabilityOf<Interfaces, 'slots'> ? `'slots' must be a finite union of string literals` : never;
|
|
102
108
|
type RawConfigDomainViolation<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'config'> extends true ? JsonDomainViolation<WidgetRawConfigOf<Interfaces>> : never;
|
|
103
109
|
/**
|
|
@@ -106,7 +112,7 @@ type RawConfigDomainViolation<Interfaces extends WidgetInterfaces> = HasWidgetCa
|
|
|
106
112
|
* Rejection happens at the `.interfaces()` boundary so that a section can never start with an
|
|
107
113
|
* unfinishable `Remaining` such as `string`.
|
|
108
114
|
*/
|
|
109
|
-
type WidgetInterfacesViolationOf<Interfaces extends WidgetInterfaces> = MemberKeyDomainViolation<'state', WidgetStateOf<Interfaces>> | MemberKeyDomainViolation<'properties', WidgetPropertiesOf<Interfaces>> | MemberKeyDomainViolation<'methods', WidgetMethodsOf<Interfaces>> | SlotDomainViolation<Interfaces> | RawConfigDomainViolation<Interfaces> | SyncValueDomainViolation<'state', WidgetStateOf<Interfaces>> | SyncValueDomainViolation<'properties', WidgetPropertiesOf<Interfaces>> | SyncMethodReturnViolation<Interfaces>;
|
|
115
|
+
type WidgetInterfacesViolationOf<Interfaces extends WidgetInterfaces> = MemberKeyDomainViolation<'state', WidgetStateOf<Interfaces>> | MemberKeyDomainViolation<'properties', WidgetPropertiesOf<Interfaces>> | MemberKeyDomainViolation<'methods', WidgetMethodsOf<Interfaces>> | MemberKeyDomainViolation<'events', WidgetEventsOf<Interfaces>> | EventArgsDomainViolation<Interfaces> | SlotDomainViolation<Interfaces> | RawConfigDomainViolation<Interfaces> | SyncValueDomainViolation<'state', WidgetStateOf<Interfaces>> | SyncValueDomainViolation<'properties', WidgetPropertiesOf<Interfaces>> | SyncMethodReturnViolation<Interfaces>;
|
|
110
116
|
//#endregion
|
|
111
117
|
//#region src/execution-result.d.ts
|
|
112
118
|
interface ExecutionFailure<Diagnostic> {
|
|
@@ -134,8 +140,29 @@ declare const widgetPluginBrand: unique symbol;
|
|
|
134
140
|
*/
|
|
135
141
|
declare const widgetSectionKind: unique symbol;
|
|
136
142
|
declare const widgetSectionRemaining: unique symbol;
|
|
143
|
+
declare const widgetValueContractType: unique symbol;
|
|
144
|
+
/**
|
|
145
|
+
* Passive, runtime-readable semantic value-contract descriptor.
|
|
146
|
+
*
|
|
147
|
+
* The generic parameter exists only for Plugin-author type safety. Runtime/integration identity is the
|
|
148
|
+
* stable string `id`; descriptor object identity has no semantic meaning.
|
|
149
|
+
*/
|
|
150
|
+
interface WidgetValueContract<Value> {
|
|
151
|
+
readonly id: string;
|
|
152
|
+
/** Type-only invariant brand; the factory-created runtime descriptor contains only `id`. */
|
|
153
|
+
readonly [widgetValueContractType]: (value: Value) => Value;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Declares a stable semantic value-contract id while retaining the associated TypeScript value type for
|
|
157
|
+
* Plugin-author checking. Core does not interpret, register, validate, or schema-check contract ids.
|
|
158
|
+
*/
|
|
159
|
+
declare function createWidgetValueContract<Value>(id: string): WidgetValueContract<Value>;
|
|
160
|
+
type DeepReadonlySchema<T> = T extends readonly (infer Item)[] ? readonly DeepReadonlySchema<Item>[] : T extends object ? { readonly [Key in keyof T]: DeepReadonlySchema<T[Key]>; } : T;
|
|
161
|
+
type WidgetConfigJsonSchema = DeepReadonlySchema<JSONSchema>;
|
|
162
|
+
declare const WIDGET_CONFIG_JSON_SCHEMA_DIALECT: "https://json-schema.org/draft/2020-12/schema";
|
|
137
163
|
interface ErasedWidgetConfigDefinition {
|
|
138
164
|
readonly description: string;
|
|
165
|
+
readonly schema: WidgetConfigJsonSchema | null;
|
|
139
166
|
readonly validate: (input: unknown, ctx: any) => boolean;
|
|
140
167
|
readonly resolve: (rawConfig: any) => unknown;
|
|
141
168
|
}
|
|
@@ -144,10 +171,14 @@ interface ErasedWidgetSlotDefinition {
|
|
|
144
171
|
readonly validateStructure?: (ctx: any) => void;
|
|
145
172
|
}
|
|
146
173
|
interface ErasedWidgetStateMemberDefinition {
|
|
174
|
+
readonly authorWritable?: boolean;
|
|
147
175
|
readonly validate: (input: unknown, ctx: any) => boolean;
|
|
148
176
|
readonly default?: (ctx: any) => unknown;
|
|
149
177
|
}
|
|
150
178
|
interface ErasedWidgetPropertyDefinition {
|
|
179
|
+
readonly valueContract?: {
|
|
180
|
+
readonly id: string;
|
|
181
|
+
};
|
|
151
182
|
readonly registerDeps?: (ctx: any) => RegisteredDeps;
|
|
152
183
|
readonly compute: (ctx: any) => unknown;
|
|
153
184
|
}
|
|
@@ -156,6 +187,9 @@ interface ErasedWidgetMethodDefinition {
|
|
|
156
187
|
readonly validateArgs: (args: readonly unknown[], ctx: any) => boolean;
|
|
157
188
|
readonly execute: (ctx: any) => unknown;
|
|
158
189
|
}
|
|
190
|
+
interface ErasedWidgetEventDefinition {
|
|
191
|
+
readonly description: string;
|
|
192
|
+
}
|
|
159
193
|
/**
|
|
160
194
|
* Erased plugin definition record.
|
|
161
195
|
*
|
|
@@ -171,6 +205,7 @@ interface WidgetPluginDefinition {
|
|
|
171
205
|
readonly state: ReadonlyMap<WidgetMemberKey, ErasedWidgetStateMemberDefinition> | null;
|
|
172
206
|
readonly properties: ReadonlyMap<WidgetMemberKey, ErasedWidgetPropertyDefinition> | null;
|
|
173
207
|
readonly methods: ReadonlyMap<WidgetMemberKey, ErasedWidgetMethodDefinition> | null;
|
|
208
|
+
readonly events: ReadonlyMap<WidgetMemberKey, ErasedWidgetEventDefinition> | null;
|
|
174
209
|
}
|
|
175
210
|
interface WidgetPluginBrand<Interfaces extends WidgetInterfaces> {
|
|
176
211
|
readonly interfaces?: Interfaces;
|
|
@@ -192,16 +227,23 @@ interface WidgetPluginCapabilities {
|
|
|
192
227
|
readonly state: boolean;
|
|
193
228
|
readonly properties: boolean;
|
|
194
229
|
readonly methods: boolean;
|
|
230
|
+
readonly events: boolean;
|
|
195
231
|
}
|
|
196
232
|
/**
|
|
197
233
|
* A completed plugin. Plugin-specific integration options are captured by the plugin factory's
|
|
198
234
|
* closure; there is no `pluginConfig` / `globalConfig`.
|
|
199
235
|
*/
|
|
236
|
+
interface WidgetPluginConfigMetadata {
|
|
237
|
+
readonly description: string;
|
|
238
|
+
readonly schema: WidgetConfigJsonSchema | null;
|
|
239
|
+
}
|
|
200
240
|
interface WidgetPlugin<Type extends string = string, Interfaces extends WidgetInterfaces = WidgetInterfaces> {
|
|
201
241
|
readonly type: Type;
|
|
202
242
|
readonly description: string;
|
|
203
243
|
/** Compiler/plugin-builder-authoritative declaration-presence facts. Immutable, stable for the plugin's lifetime. */
|
|
204
244
|
readonly capabilities: WidgetPluginCapabilities;
|
|
245
|
+
/** Passive RawConfig authoring metadata. Null means no config capability. */
|
|
246
|
+
readonly config: WidgetPluginConfigMetadata | null;
|
|
205
247
|
readonly descriptions: {
|
|
206
248
|
readonly config: string | null;
|
|
207
249
|
readonly slots: ReadonlyMap<WidgetMemberKey, string> | null;
|
|
@@ -247,14 +289,20 @@ type WidgetPropertyComputeContext<Interfaces extends WidgetInterfaces, Deps exte
|
|
|
247
289
|
readonly blueprint: ValidBlueprintView;
|
|
248
290
|
readonly deps: ToExecutedDeps<Deps, 'property'>;
|
|
249
291
|
} & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces>;
|
|
292
|
+
type WidgetEventEmitter<Interfaces extends WidgetInterfaces> = { readonly [Name in WidgetEventKeyOf<Interfaces>]: (...args: WidgetEventArgsOf<Interfaces, Name>) => void; };
|
|
293
|
+
type WidgetEventEmitterContext<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'events'> extends true ? {
|
|
294
|
+
readonly emit: WidgetEventEmitter<Interfaces>;
|
|
295
|
+
} : unknown;
|
|
250
296
|
type WidgetMethodExecuteContext<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps> = {
|
|
251
297
|
readonly args: WidgetMethodArgsOf<Interfaces, Name>;
|
|
252
298
|
readonly widget: SelfBlueprintWidgetNode<Interfaces>;
|
|
253
299
|
readonly blueprint: ValidBlueprintView;
|
|
254
300
|
readonly deps: ToExecutedDeps<Deps, 'method'>;
|
|
255
|
-
} & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces>;
|
|
301
|
+
} & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces> & WidgetEventEmitterContext<Interfaces>;
|
|
256
302
|
interface WidgetConfigDefinition<Interfaces extends WidgetInterfaces> {
|
|
257
303
|
readonly description: string;
|
|
304
|
+
/** Passive Draft 2020-12 authoring metadata. Core does not validate or execute this schema. */
|
|
305
|
+
readonly schema?: WidgetConfigJsonSchema;
|
|
258
306
|
readonly validate: (input: unknown, ctx: WidgetConfigValidateContext) => input is WidgetRawConfigOf<Interfaces>;
|
|
259
307
|
readonly resolve: (rawConfig: WidgetRawConfigOf<Interfaces> | null) => WidgetResolvedConfigOf<Interfaces>;
|
|
260
308
|
}
|
|
@@ -270,10 +318,14 @@ type WidgetSlotDefinitions<Interfaces extends WidgetInterfaces> = { readonly [Na
|
|
|
270
318
|
type ExactWidgetSlotDefinitions<Interfaces extends WidgetInterfaces, Definitions> = WidgetSlotDefinitions<Interfaces> & { readonly [Name in keyof Definitions as Name extends WidgetSlotNameOf<Interfaces> ? never : Name]: never; };
|
|
271
319
|
type WidgetPluginValidateStructure<Interfaces extends WidgetInterfaces> = (ctx: WidgetPluginValidateStructureContext<Interfaces>) => void;
|
|
272
320
|
interface WidgetStateMemberDefinition<Interfaces extends WidgetInterfaces, Key extends WidgetMemberKey> {
|
|
321
|
+
/** Passive authoring policy. Omitted means this State member is not author-writable. */
|
|
322
|
+
readonly authorWritable?: boolean;
|
|
273
323
|
readonly validate: (input: unknown, ctx: WidgetStateValidateContext<Interfaces>) => input is WidgetStateValueOf<Interfaces, Key>;
|
|
274
324
|
readonly default?: (ctx: WidgetStateDefaultContext<Interfaces>) => WidgetStateValueOf<Interfaces, Key>;
|
|
275
325
|
}
|
|
276
326
|
interface WidgetPropertyDefinition<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps> {
|
|
327
|
+
/** Passive semantic value contract for integration/tooling inspection. */
|
|
328
|
+
readonly valueContract?: WidgetValueContract<WidgetPropertyValueOf<Interfaces, Name>>;
|
|
277
329
|
readonly registerDeps?: (ctx: WidgetRegisterDepsContext<Interfaces, 'property'>) => Deps;
|
|
278
330
|
readonly compute: (ctx: WidgetPropertyComputeContext<Interfaces, Deps>) => WidgetPropertyValueOf<Interfaces, Name>;
|
|
279
331
|
}
|
|
@@ -282,6 +334,9 @@ interface WidgetMethodDefinition<Interfaces extends WidgetInterfaces, Name exten
|
|
|
282
334
|
readonly validateArgs: (args: readonly unknown[], ctx: WidgetMethodValidateArgsContext<Interfaces>) => args is WidgetMethodArgsOf<Interfaces, Name>;
|
|
283
335
|
readonly execute: (ctx: WidgetMethodExecuteContext<Interfaces, Name, Deps>) => WidgetMethodReturnOf<Interfaces, Name>;
|
|
284
336
|
}
|
|
337
|
+
interface WidgetEventDefinition {
|
|
338
|
+
readonly description: string;
|
|
339
|
+
}
|
|
285
340
|
/**
|
|
286
341
|
* Phantom section typestate. `Remaining` is part of the marker type, so a section is complete only
|
|
287
342
|
* when `Remaining` has been reduced to `never`.
|
|
@@ -293,6 +348,7 @@ interface WidgetSectionMarker<Kind extends string, Remaining extends WidgetMembe
|
|
|
293
348
|
type WidgetStateSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetStateKeyOf<Interfaces>> = WidgetSectionMarker<'state', Remaining> & { [Key in Remaining]: (definition: WidgetStateMemberDefinition<Interfaces, Key>) => WidgetStateSection<Interfaces, Exclude<Remaining, Key>>; };
|
|
294
349
|
type WidgetPropertiesSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetPropertyKeyOf<Interfaces>> = WidgetSectionMarker<'properties', Remaining> & { [Name in Remaining]: <const Deps extends RegisteredDeps = EmptyRegisteredDeps>(definition: WidgetPropertyDefinition<Interfaces, Name, Deps>) => WidgetPropertiesSection<Interfaces, Exclude<Remaining, Name>>; };
|
|
295
350
|
type WidgetMethodsSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetMethodKeyOf<Interfaces>> = WidgetSectionMarker<'methods', Remaining> & { [Name in Remaining]: <const Deps extends RegisteredDeps = EmptyRegisteredDeps>(definition: WidgetMethodDefinition<Interfaces, Name, Deps>) => WidgetMethodsSection<Interfaces, Exclude<Remaining, Name>>; };
|
|
351
|
+
type WidgetEventsSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetEventKeyOf<Interfaces>> = WidgetSectionMarker<'events', Remaining> & { [Name in Remaining]: (definition: WidgetEventDefinition) => WidgetEventsSection<Interfaces, Exclude<Remaining, Name>>; };
|
|
296
352
|
/**
|
|
297
353
|
* Returned instead of the next builder phase when the supplied `WidgetInterfaces` is outside the
|
|
298
354
|
* supported declaration domain. It exposes no builder operation, so the chain cannot continue.
|
|
@@ -303,15 +359,51 @@ interface WidgetInterfacesViolation<Reason extends string> {
|
|
|
303
359
|
interface WidgetPluginDonePhase<Type extends string, Interfaces extends WidgetInterfaces> {
|
|
304
360
|
done: () => WidgetPlugin<Type, Interfaces>;
|
|
305
361
|
}
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
362
|
+
/**
|
|
363
|
+
* Outer capability phases in their fixed call order. Part of the type-level order diagnostics only;
|
|
364
|
+
* the runtime builder is order-agnostic.
|
|
365
|
+
*/
|
|
366
|
+
type WidgetPluginPhaseOrder = readonly ['config', 'slots', 'state', 'properties', 'methods', 'events'];
|
|
367
|
+
type WidgetPluginPhaseName = WidgetPluginPhaseOrder[number];
|
|
368
|
+
/** The phases whose capability was declared in `Interfaces`. */
|
|
369
|
+
type WidgetPluginDeclaredPhaseName<Interfaces extends WidgetInterfaces> = { [Phase in WidgetPluginPhaseName]: HasWidgetCapability<Interfaces, Phase> extends true ? Phase : never; }[WidgetPluginPhaseName];
|
|
370
|
+
type WidgetPluginPhaseIsBefore<A extends WidgetPluginPhaseName, B extends WidgetPluginPhaseName, Order extends readonly WidgetPluginPhaseName[] = WidgetPluginPhaseOrder> = Order extends readonly [infer Head, ...infer Tail extends readonly WidgetPluginPhaseName[]] ? Head extends A ? true : Head extends B ? false : WidgetPluginPhaseIsBefore<A, B, Tail> : false;
|
|
371
|
+
/**
|
|
372
|
+
* Type-only order marker: the message of the compile error raised when a declared phase is called at
|
|
373
|
+
* the wrong position. The marker name and reason text are diagnostics, not protocol.
|
|
374
|
+
*/
|
|
375
|
+
interface WidgetPluginPhaseOrderViolation<Reason extends string> {
|
|
376
|
+
readonly 'widget-core: builder phase order violation': Reason;
|
|
377
|
+
}
|
|
378
|
+
/**
|
|
379
|
+
* Argument list of a misplaced marker: the real phase's arguments, with the first one intersected with
|
|
380
|
+
* the order violation. The call therefore fails at its first argument with the violation (and its
|
|
381
|
+
* reason) in the message, while the function constituent keeps callbacks contextually typed, so no
|
|
382
|
+
* implicit-`any` follow-on errors appear. Section builders may return anything.
|
|
383
|
+
*/
|
|
384
|
+
type WidgetPluginMisplacedArguments<Interfaces extends WidgetInterfaces, Phase extends WidgetPluginPhaseName, Violation> = Phase extends 'config' ? [definition: Violation & WidgetConfigDefinition<Interfaces>] : Phase extends 'slots' ? [definitions: Violation & WidgetSlotDefinitions<Interfaces>, validateStructure?: WidgetPluginValidateStructure<Interfaces>] : Phase extends 'state' ? [build: Violation & ((section: WidgetStateSection<Interfaces, WidgetStateKeyOf<Interfaces>>) => unknown)] : Phase extends 'properties' ? [build: Violation & ((section: WidgetPropertiesSection<Interfaces, WidgetPropertyKeyOf<Interfaces>>) => unknown)] : Phase extends 'methods' ? [build: Violation & ((section: WidgetMethodsSection<Interfaces, WidgetMethodKeyOf<Interfaces>>) => unknown)] : [build: Violation & ((section: WidgetEventsSection<Interfaces, WidgetEventKeyOf<Interfaces>>) => unknown)];
|
|
385
|
+
type WidgetPluginPhaseOrderReason<Phase extends WidgetPluginPhaseName, Stage extends WidgetPluginPhaseName | 'done'> = Stage extends WidgetPluginPhaseName ? WidgetPluginPhaseIsBefore<Phase, Stage> extends true ? `'.${Phase}()' was already called or must be called earlier; the next phase is '.${Stage}()'. Order: description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' is called too early; call '.${Stage}()' first. Order: description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' cannot be called here; the declared phases are already complete, so only '.done()' remains. Order: description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()`;
|
|
386
|
+
/**
|
|
387
|
+
* Adds type-only order markers for every declared phase that is not callable at `Stage`. A marker
|
|
388
|
+
* takes the real phase's arguments with the first one intersected with
|
|
389
|
+
* `WidgetPluginPhaseOrderViolation`, so no real value satisfies it and the call fails with an
|
|
390
|
+
* order-specific diagnostic (the function constituent keeps a callback passed to it contextually typed,
|
|
391
|
+
* so no implicit-`any` follow-on errors appear). It returns the same phase, so a misplaced call never
|
|
392
|
+
* advances the chain.
|
|
393
|
+
*/
|
|
394
|
+
type WidgetPluginOrderedPhase<Phase, Interfaces extends WidgetInterfaces, Stage extends WidgetPluginPhaseName | 'done'> = [Exclude<WidgetPluginDeclaredPhaseName<Interfaces>, Stage>] extends [never] ? Phase : Phase & { [Misplaced in Exclude<WidgetPluginDeclaredPhaseName<Interfaces>, Stage>]: (...args: WidgetPluginMisplacedArguments<Interfaces, Misplaced, WidgetPluginPhaseOrderViolation<WidgetPluginPhaseOrderReason<Misplaced, Stage>>>) => WidgetPluginOrderedPhase<Phase, Interfaces, Stage>; };
|
|
395
|
+
type WidgetPluginEventsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'events'> extends true ? WidgetPluginOrderedPhase<{
|
|
396
|
+
events: (build: (section: WidgetEventsSection<Interfaces, WidgetEventKeyOf<Interfaces>>) => WidgetEventsSection<Interfaces, never>) => WidgetPluginOrderedPhase<WidgetPluginDonePhase<Type, Interfaces>, Interfaces, 'done'>;
|
|
397
|
+
}, Interfaces, 'events'> : WidgetPluginOrderedPhase<WidgetPluginDonePhase<Type, Interfaces>, Interfaces, 'done'>;
|
|
398
|
+
type WidgetPluginMethodsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'methods'> extends true ? WidgetPluginOrderedPhase<{
|
|
399
|
+
methods: (build: (section: WidgetMethodsSection<Interfaces, WidgetMethodKeyOf<Interfaces>>) => WidgetMethodsSection<Interfaces, never>) => WidgetPluginEventsPhase<Type, Interfaces>;
|
|
400
|
+
}, Interfaces, 'methods'> : WidgetPluginEventsPhase<Type, Interfaces>;
|
|
401
|
+
type WidgetPluginPropertiesPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'properties'> extends true ? WidgetPluginOrderedPhase<{
|
|
310
402
|
properties: (build: (section: WidgetPropertiesSection<Interfaces, WidgetPropertyKeyOf<Interfaces>>) => WidgetPropertiesSection<Interfaces, never>) => WidgetPluginMethodsPhase<Type, Interfaces>;
|
|
311
|
-
} : WidgetPluginMethodsPhase<Type, Interfaces>;
|
|
312
|
-
type WidgetPluginStatePhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? {
|
|
403
|
+
}, Interfaces, 'properties'> : WidgetPluginMethodsPhase<Type, Interfaces>;
|
|
404
|
+
type WidgetPluginStatePhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? WidgetPluginOrderedPhase<{
|
|
313
405
|
state: (build: (section: WidgetStateSection<Interfaces, WidgetStateKeyOf<Interfaces>>) => WidgetStateSection<Interfaces, never>) => WidgetPluginPropertiesPhase<Type, Interfaces>;
|
|
314
|
-
} : WidgetPluginPropertiesPhase<Type, Interfaces>;
|
|
406
|
+
}, Interfaces, 'state'> : WidgetPluginPropertiesPhase<Type, Interfaces>;
|
|
315
407
|
/**
|
|
316
408
|
* `slots: never` is the canonical explicit-empty slots declaration (diagnostic #10 amendment
|
|
317
409
|
* "declaration-presence semantics and public `WidgetPlugin.capabilities`"): the phase still exists —
|
|
@@ -319,12 +411,12 @@ type WidgetPluginStatePhase<Type extends string, Interfaces extends WidgetInterf
|
|
|
319
411
|
* be `never` — and completes as `.slots({})`, since `ExactWidgetSlotDefinitions` for zero slot names is
|
|
320
412
|
* exactly `{}`.
|
|
321
413
|
*/
|
|
322
|
-
type WidgetPluginSlotsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'slots'> extends true ? {
|
|
414
|
+
type WidgetPluginSlotsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'slots'> extends true ? WidgetPluginOrderedPhase<{
|
|
323
415
|
slots: <const Definitions extends ExactWidgetSlotDefinitions<Interfaces, Definitions>>(definitions: Definitions, validateStructure?: WidgetPluginValidateStructure<Interfaces>) => WidgetPluginStatePhase<Type, Interfaces>;
|
|
324
|
-
} : WidgetPluginStatePhase<Type, Interfaces>;
|
|
325
|
-
type WidgetPluginConfigPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'config'> extends true ? {
|
|
416
|
+
}, Interfaces, 'slots'> : WidgetPluginStatePhase<Type, Interfaces>;
|
|
417
|
+
type WidgetPluginConfigPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'config'> extends true ? WidgetPluginOrderedPhase<{
|
|
326
418
|
config: (definition: WidgetConfigDefinition<Interfaces>) => WidgetPluginSlotsPhase<Type, Interfaces>;
|
|
327
|
-
} : WidgetPluginSlotsPhase<Type, Interfaces>;
|
|
419
|
+
}, Interfaces, 'config'> : WidgetPluginSlotsPhase<Type, Interfaces>;
|
|
328
420
|
interface WidgetPluginInterfacesPhase<Type extends string> {
|
|
329
421
|
interfaces: <Interfaces extends WidgetInterfaces>() => [WidgetInterfacesViolationOf<Interfaces>] extends [never] ? WidgetPluginConfigPhase<Type, Interfaces> : WidgetInterfacesViolation<WidgetInterfacesViolationOf<Interfaces>>;
|
|
330
422
|
}
|
|
@@ -334,8 +426,10 @@ interface WidgetPluginDescriptionPhase<Type extends string> {
|
|
|
334
426
|
/**
|
|
335
427
|
* Starts the plugin builder for one plugin `type`.
|
|
336
428
|
*
|
|
337
|
-
* Phase order is `interfaces -> config? -> slots? -> state? -> properties? -> methods? -> done()`;
|
|
338
|
-
* a phase exists only when its capability is declared.
|
|
429
|
+
* Phase order is `description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()`;
|
|
430
|
+
* a phase exists only when its capability is declared. Calling a declared phase out of order (or
|
|
431
|
+
* repeating it) fails type-checking with an order-specific diagnostic; the runtime builder itself is
|
|
432
|
+
* order-agnostic.
|
|
339
433
|
*/
|
|
340
434
|
declare function createWidgetPlugin<const Type extends string>(type: Type): WidgetPluginDescriptionPhase<Type>;
|
|
341
435
|
//#endregion
|
|
@@ -343,6 +437,8 @@ declare function createWidgetPlugin<const Type extends string>(type: Type): Widg
|
|
|
343
437
|
interface WidgetCatalogEntry {
|
|
344
438
|
readonly type: string;
|
|
345
439
|
readonly description: string;
|
|
440
|
+
/** Null means no config capability; otherwise schema may itself be null. */
|
|
441
|
+
readonly config: WidgetPluginConfigMetadata | null;
|
|
346
442
|
readonly descriptions: {
|
|
347
443
|
readonly config: string | null;
|
|
348
444
|
readonly slots: ReadonlyMap<string, string> | null;
|
|
@@ -377,9 +473,35 @@ interface WidgetSystem<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTup
|
|
|
377
473
|
/**
|
|
378
474
|
* The compilation boundary. The input is `unknown` because JSON-parsed/untrusted document data is
|
|
379
475
|
* the real boundary; malformed input still produces an inspectable Blueprint.
|
|
476
|
+
*
|
|
477
|
+
* Ownership: `definition` is retained **by reference**. `blueprint.source` is that exact value and
|
|
478
|
+
* each recovered node's `source` is a reference into the same graph; Core never clones, freezes or
|
|
479
|
+
* Proxy-wraps it. Passing it here transfers semantic ownership: neither the caller nor any reader of
|
|
480
|
+
* `blueprint.source` may mutate it (or anything inside it) afterwards, and behavior after such a
|
|
481
|
+
* mutation is unspecified. Pass a copy (for example `structuredClone` for JSON-domain data) to keep
|
|
482
|
+
* editing your own object.
|
|
380
483
|
*/
|
|
381
484
|
createBlueprint: (definition: unknown) => WidgetSystemBlueprint<Plugins>;
|
|
382
485
|
}
|
|
486
|
+
type WidgetSystemConfigurationErrorCode = 'foreign-plugin' | 'duplicate-plugin-type';
|
|
487
|
+
/**
|
|
488
|
+
* Thrown by `createWidgetSystem` for an invalid plugin registration. Discriminate by class and `code`;
|
|
489
|
+
* `message` is not protocol.
|
|
490
|
+
*
|
|
491
|
+
* - `foreign-plugin`: the entry at `pluginIndex` was not completed by this loaded module instance
|
|
492
|
+
* (another module instance or a structural look-alike). `pluginType` is its `type` when a string,
|
|
493
|
+
* else `null`. `firstPluginIndex` is `null`.
|
|
494
|
+
* - `duplicate-plugin-type`: the entry at `pluginIndex` repeats `pluginType`, first registered at
|
|
495
|
+
* `firstPluginIndex`.
|
|
496
|
+
*/
|
|
497
|
+
declare class WidgetSystemConfigurationError extends Error {
|
|
498
|
+
readonly code: WidgetSystemConfigurationErrorCode;
|
|
499
|
+
readonly pluginIndex: number;
|
|
500
|
+
readonly pluginType: string | null;
|
|
501
|
+
readonly firstPluginIndex: number | null;
|
|
502
|
+
readonly name = "WidgetSystemConfigurationError";
|
|
503
|
+
constructor(code: WidgetSystemConfigurationErrorCode, pluginIndex: number, pluginType: string | null, firstPluginIndex?: number | null, message?: string);
|
|
504
|
+
}
|
|
383
505
|
/**
|
|
384
506
|
* Creates an instance-scoped, immutable widget system. Duplicate `plugin.type` is rejected.
|
|
385
507
|
*/
|
|
@@ -548,12 +670,15 @@ type WidgetSource<Plugins extends AnyWidgetPluginTuple> = Plugins[number] extend
|
|
|
548
670
|
interface WidgetSystemBlueprintBase<Plugins extends AnyWidgetPluginTuple, Source = unknown> {
|
|
549
671
|
readonly system: WidgetSystem<Plugins>;
|
|
550
672
|
/**
|
|
551
|
-
* The exact entire unknown input this Blueprint was compiled from
|
|
673
|
+
* The exact entire unknown input this Blueprint was compiled from: the same reference that was
|
|
674
|
+
* passed in, never cloned or frozen by Core. Callers and readers must not mutate it; ownership of
|
|
675
|
+
* the graph transferred to Core when it was handed over (behavior after mutation is unspecified).
|
|
552
676
|
*/
|
|
553
677
|
readonly source: Source;
|
|
554
678
|
readonly sourceJsonCompatible: boolean;
|
|
555
679
|
/**
|
|
556
|
-
* Observably equivalent to `blueprint.system.createBlueprint(next)`.
|
|
680
|
+
* Observably equivalent to `blueprint.system.createBlueprint(next)`. `definition` is retained by
|
|
681
|
+
* reference and ownership transfers exactly as for `createBlueprint`.
|
|
557
682
|
*/
|
|
558
683
|
recompile: (definition: unknown) => WidgetSystemBlueprint<Plugins>;
|
|
559
684
|
}
|
|
@@ -612,6 +737,9 @@ interface RuntimeMethod<Fn extends (...args: any[]) => any> {
|
|
|
612
737
|
getDiagnostics: () => readonly RuntimeMethodDiagnostic[];
|
|
613
738
|
subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeMethodDiagnostic[]) => void) => () => void;
|
|
614
739
|
}
|
|
740
|
+
interface RuntimeEvent<Args extends readonly unknown[]> {
|
|
741
|
+
subscribe: (listener: (...args: Args) => void) => () => void;
|
|
742
|
+
}
|
|
615
743
|
type RuntimeStateSurface<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? {
|
|
616
744
|
readonly state: { readonly [Key in WidgetStateKeyOf<Interfaces>]: RuntimeState<WidgetStateValueOf<Interfaces, Key>>; };
|
|
617
745
|
} : unknown;
|
|
@@ -619,13 +747,15 @@ type RuntimePropertySurface<Interfaces extends WidgetInterfaces> = HasWidgetCapa
|
|
|
619
747
|
readonly properties: { readonly [Name in WidgetPropertyKeyOf<Interfaces>]: RuntimeProperty<WidgetPropertyValueOf<Interfaces, Name>>; };
|
|
620
748
|
} : unknown;
|
|
621
749
|
/**
|
|
622
|
-
* Gated on
|
|
623
|
-
*
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
750
|
+
* Gated on declaration presence so an explicitly empty events capability remains observable as an
|
|
751
|
+
* empty `events` surface, distinct from an absent events capability.
|
|
752
|
+
*/
|
|
753
|
+
type RuntimeEventSurface<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'events'> extends true ? {
|
|
754
|
+
readonly events: { readonly [Name in WidgetEventKeyOf<Interfaces>]: RuntimeEvent<WidgetEventArgsOf<Interfaces, Name>>; };
|
|
755
|
+
} : unknown;
|
|
756
|
+
/**
|
|
757
|
+
* Gated on declaration presence so an explicitly empty methods capability remains observable as an
|
|
758
|
+
* empty `methods` surface, distinct from an absent methods capability.
|
|
629
759
|
*/
|
|
630
760
|
type RuntimeMethodSurface<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'methods'> extends true ? {
|
|
631
761
|
readonly methods: { readonly [Name in WidgetMethodKeyOf<Interfaces>]: RuntimeMethod<WidgetMethodOf<Interfaces, Name>>; };
|
|
@@ -642,7 +772,7 @@ type RuntimeWidgetFor<Plugin extends AnyWidgetPlugin, Plugins extends AnyWidgetP
|
|
|
642
772
|
*/
|
|
643
773
|
getDiagnostics: () => readonly RuntimeWidgetDiagnostic[];
|
|
644
774
|
subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeWidgetDiagnostic[]) => void) => () => void;
|
|
645
|
-
} & RuntimeStateSurface<WidgetInterfacesOf<Plugin>> & RuntimePropertySurface<WidgetInterfacesOf<Plugin>> & RuntimeMethodSurface<WidgetInterfacesOf<Plugin>>;
|
|
775
|
+
} & RuntimeStateSurface<WidgetInterfacesOf<Plugin>> & RuntimePropertySurface<WidgetInterfacesOf<Plugin>> & RuntimeMethodSurface<WidgetInterfacesOf<Plugin>> & RuntimeEventSurface<WidgetInterfacesOf<Plugin>>;
|
|
646
776
|
type RuntimeWidget<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> = Plugins[number] extends (infer Plugin) ? Plugin extends AnyWidgetPlugin ? RuntimeWidgetFor<Plugin, Plugins> : never : never;
|
|
647
777
|
/**
|
|
648
778
|
* Executable instance of a valid Blueprint.
|
|
@@ -1107,4 +1237,4 @@ interface DependencyBuilder<Interfaces extends WidgetInterfaces, Consumer extend
|
|
|
1107
1237
|
widget: (widgetId: WidgetId) => OptionalizableDependencyTarget<Consumer>;
|
|
1108
1238
|
}
|
|
1109
1239
|
//#endregion
|
|
1110
|
-
export { RuntimeDependencyValueRejectedDiagnostic as $,
|
|
1240
|
+
export { RuntimeDependencyValueRejectedDiagnostic as $, createWidgetValueContract as $n, WidgetCatalogEntry as $t, BlueprintNodeDiagnostic as A, WidgetPluginInterfacesPhase as An, JsonPrimitive as Ar, RuntimeEventSurface as At, Diagnostic as B, WidgetPropertyComputeContext as Bn, SelfBlueprintWidgetNodeView as Bt, BlueprintDependencyDiagnosticLocation as C, WidgetPlugin as Cn, WidgetResolvedConfigOf as Cr, CreateWidgetSystemRuntimeOptions as Ct, BlueprintDiagnostic as D, WidgetPluginDescriptionPhase as Dn, WidgetStateValueOf as Dr, ResolvedBlueprintWidgetNodeView as Dt, BlueprintDependencyTarget as E, WidgetPluginConfigPhase as En, WidgetStateOf as Er, ResolvedBlueprintWidgetNodeFor as Et, BlueprintSourceDiagnostic as F, WidgetPluginStatePhase as Fn, RuntimeState as Ft, JsonCompatibilityDiagnostic as G, WidgetSlotDefinitions as Gn, WidgetLocationView as Gt, DiagnosticCollector as H, WidgetRegisterDepsContext as Hn, ValidBlueprintView as Ht, BlueprintSourceDiagnosticLocation as I, WidgetPluginTypeOf as In, RuntimeStateSurface as It, RelativeSlotStructureDiagnosticInput as J, WidgetStateMemberDefinition as Jn, WidgetSystemBlueprint as Jt, JsonCompatibilityReason as K, WidgetSlotValidateStructureContext as Kn, WidgetSource as Kt, BlueprintStructureDiagnostic as L, WidgetPluginValidateStructure as Ln, RuntimeWidget as Lt, BlueprintPropertyDiagnosticLocation as M, WidgetPluginPhaseOrderViolation as Mn, RuntimeMethodSurface as Mt, BlueprintSlotChildDiagnosticLocation as N, WidgetPluginPropertiesPhase as Nn, RuntimeProperty as Nt, BlueprintDiagnosticLocation as O, WidgetPluginDonePhase as On, JsonArray as Or, ResolvedBlueprintWidgetNodeViewFor as Ot, BlueprintSlotDiagnosticLocation as P, WidgetPluginSlotsPhase as Pn, RuntimePropertySurface as Pt, RuntimeDependencyTargetFailedDiagnostic as Q, createWidgetPlugin as Qn, WidgetCatalog as Qt, BlueprintStructureDiagnosticLocation as R, WidgetPluginValidateStructureContext as Rn, RuntimeWidgetFor as Rt, BlueprintDependencyDiagnostic as S, WidgetMethodsSection as Sn, WidgetRawConfigOf as Sr, BlueprintWidgetNodeView as St, BlueprintDependencyReference as T, WidgetPluginConfigMetadata as Tn, WidgetStateKeyOf as Tr, ResolvedBlueprintWidgetNode as Tt, DiagnosticPath as U, WidgetResolvedConfigContext as Un, ValidWidgetSystemBlueprint as Ut, DiagnosticBase as V, WidgetPropertyDefinition as Vn, UnresolvedBlueprintWidgetNode as Vt, EMPTY_DIAGNOSTICS as W, WidgetSlotDefinition as Wn, WidgetLocation as Wt, RelativeSystemStructureDiagnosticInput as X, WidgetStateValidateContext as Xn, WidgetSystemRuntime as Xt, RelativeStructureDiagnosticLocation as Y, WidgetStateSection as Yn, WidgetSystemBlueprintStatus as Yt, RelativeValueDiagnosticInput as Z, WidgetValueContract as Zn, CreateWidgetSystemOptions as Zt, ToExecutedDeps as _, WidgetInterfacesOf as _n, WidgetMethodReturnOf as _r, BlueprintNodeConfigFields as _t, MaybeOptional as a, WidgetSystemValidateStructureContext as an, WidgetEventArgsOf as ar, RuntimeMethodDependencyDiagnostic as at, BlueprintConfigDiagnostic as b, WidgetMethodExecuteContext as bn, WidgetPropertyKeyOf as br, BlueprintWidgetNode as bt, PropertyGetDepExpression as c, AnyWidgetPluginTuple as cn, WidgetId as cr, RuntimePropertyDependencyDiagnostic as ct, SelfMethodDependencyOperations as d, WidgetConfigJsonSchema as dn, WidgetMemberKey as dr, RuntimeStateDiagnostic as dt, WidgetPluginOf as en, ExecutionFailure as er, RuntimeDiagnostic as et, SelfPropertyDependencyOperations as f, WidgetConfigValidateContext as fn, WidgetMemberKeysOf as fr, RuntimeWidgetDiagnostic as ft, ToExecutedDep as g, WidgetEventsSection as gn, WidgetMethodOf as gr, BlueprintCompileView as gt, StateSetDepExpression as h, WidgetEventEmitterContext as hn, WidgetMethodKeyOf as hr, WidgetSystemRuntimeDisposedError as ht, EmptyRegisteredDeps as i, WidgetSystemValidateStructure as in, WidgetCapabilityOf as ir, RuntimeMethodArgsDiagnostic as it, BlueprintNodeDiagnosticLocation as j, WidgetPluginMethodsPhase as jn, JsonValue as jr, RuntimeMethod as jt, BlueprintMethodDiagnosticLocation as k, WidgetPluginEventsPhase as kn, JsonObject as kr, RuntimeEvent as kt, RegisteredDeps as l, WIDGET_CONFIG_JSON_SCHEMA_DIALECT as ln, WidgetInterfaces as lr, RuntimePropertyDiagnostic as lt, StateGetDepExpression as m, WidgetEventEmitter as mn, WidgetMethodArgsOf as mr, WidgetSystemRuntimeDiagnostic as mt, DependencyBuilder as n, WidgetSystemConfigurationError as nn, HasWidgetCapability as nr, RuntimeLevelDiagnostic as nt, MethodInvokeDepExpression as o, createWidgetSystem as on, WidgetEventKeyOf as or, RuntimeMethodDiagnostic as ot, SelfStateDependencyOperations as p, WidgetEventDefinition as pn, WidgetMemberValueOf as pr, SourceAccessDiagnostic as pt, RelativePluginStructureDiagnosticInput as q, WidgetStateDefaultContext as qn, WidgetSourceFor as qt, DependencyConsumer as r, WidgetSystemConfigurationErrorCode as rn, NonEmptyReadonlyArray as rr, RuntimeLevelDiagnosticLocation as rt, OptionalizableDependencyTarget as s, AnyWidgetPlugin as sn, WidgetEventsOf as sr, RuntimeMethodResultDiagnostic as st, AnyDepExpression as t, WidgetSystem as tn, ExecutionResult as tr, RuntimeDiagnosticLocation as tt, SelfDependencyTarget as u, WidgetConfigDefinition as un, WidgetInterfacesViolationOf as ur, RuntimePropertyResultDiagnostic as ut, UnknownTargetDependencyOperations as v, WidgetInterfacesViolation as vn, WidgetMethodsOf as vr, BlueprintSemanticSlots as vt, BlueprintDependencyOperation as w, WidgetPluginCapabilities as wn, WidgetSlotNameOf as wr, InvalidWidgetSystemBlueprint as wt, BlueprintDefinitionDiagnostic as x, WidgetMethodValidateArgsContext as xn, WidgetPropertyValueOf as xr, BlueprintWidgetNodeBase as xt, UnknownTargetStateDependencyOperations as y, WidgetMethodDefinition as yn, WidgetPropertiesOf as yr, BlueprintSemanticSlotsView as yt, BlueprintWidgetDiagnosticLocation as z, WidgetPropertiesSection as zn, SelfBlueprintWidgetNode as zt };
|