@deviltea/widget-core 0.0.6 → 0.1.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.
- package/README.md +244 -64
- package/dist/{dep-DKbvAjPb.d.mts → dep-BXcdMm-M.d.mts} +298 -89
- package/dist/event-Bk-mkL1E.mjs +956 -0
- package/dist/index.d.mts +93 -12
- package/dist/index.mjs +1735 -596
- package/dist/inspection/index.d.mts +35 -3
- package/dist/inspection/index.mjs +23 -2
- package/dist/integration/index.d.mts +8 -2
- package/dist/integration/index.mjs +11 -3
- package/dist/internals-CVKUQDIN.mjs +388 -0
- package/package.json +3 -2
- package/dist/event-BMif_vRJ.mjs +0 -192
- package/dist/internals-L391flXY.mjs +0 -199
|
@@ -10,13 +10,30 @@ interface JsonObject {
|
|
|
10
10
|
readonly [key: string]: JsonValue;
|
|
11
11
|
}
|
|
12
12
|
type JsonValue = JsonPrimitive | JsonArray | JsonObject;
|
|
13
|
+
/**
|
|
14
|
+
* The maximum JSON nesting depth of authored source and SourcePatch operands: the number of containers
|
|
15
|
+
* (objects and arrays) a value may be nested inside, counting the value's own container. A value nested
|
|
16
|
+
* deeper is outside the JSON domain (`json-incompatible-value`, reason `max-depth-exceeded`) and is never
|
|
17
|
+
* descended into, so arbitrarily deep input yields a diagnostic or an operation failure instead of exhausting
|
|
18
|
+
* the call stack. A widget node nests three containers per tree level (node, `slots`, slot Array), so the
|
|
19
|
+
* limit allows widget trees about 85 levels deep. The value leaves a wide margin below the call-stack limit of
|
|
20
|
+
* Node 22/24 and of smaller-stack embedded engines, and is part of the public contract.
|
|
21
|
+
*/
|
|
22
|
+
declare const MAX_JSON_DEPTH = 256;
|
|
23
|
+
declare function isJsonValue(value: unknown): value is JsonValue;
|
|
13
24
|
/**
|
|
14
25
|
* Type-level diagnostic for a RawConfig that is not statically within JsonValue. Optional properties
|
|
15
26
|
* are allowed to be omitted, but an explicitly required `undefined` remains outside the domain.
|
|
16
27
|
*/
|
|
17
|
-
type IsAny$
|
|
28
|
+
type IsAny$2<T> = 0 extends 1 & T ? true : false;
|
|
18
29
|
type OptionalKeys<T extends object> = { [Key in keyof T]-?: Record<never, never> extends Pick<T, Key> ? Key : never; }[keyof T];
|
|
19
|
-
|
|
30
|
+
/**
|
|
31
|
+
* Well-known-symbol members that only class instances carry (`Date`, `Map`, `Set`, iterables, ...).
|
|
32
|
+
* Checked before the string-key rule, so such a value reports the non-plain-object reason instead of
|
|
33
|
+
* "may only have string keys".
|
|
34
|
+
*/
|
|
35
|
+
type ClassInstanceSymbolKey = typeof Symbol.iterator | typeof Symbol.asyncIterator | typeof Symbol.toPrimitive | typeof Symbol.toStringTag;
|
|
36
|
+
type JsonDomainViolation<Value> = IsAny$2<Value> extends true ? 'authored JSON values cannot contain any' : [Value] extends [never] ? never : [Value] extends [JsonValue] ? never : Value extends string | number | boolean | null ? never : Value extends ((...args: any[]) => any) ? 'authored values must be JSON-compatible' : Value extends readonly (infer Element)[] ? JsonDomainViolation<Element> : Value extends object ? [Extract<keyof Value, ClassInstanceSymbolKey>] extends [never] ? Exclude<keyof Value, string> extends never ? { [Key in keyof Value]-?: Key extends OptionalKeys<Value> ? JsonDomainViolation<Exclude<Value[Key], undefined>> : JsonDomainViolation<Value[Key]>; }[keyof Value] : 'authored JSON objects may only have string keys' : 'authored JSON objects must be plain objects, not class instances such as Date, Map or Set' : 'authored values must be JSON-compatible';
|
|
20
37
|
//#endregion
|
|
21
38
|
//#region src/types.d.ts
|
|
22
39
|
/**
|
|
@@ -53,7 +70,7 @@ interface WidgetInterfaces {
|
|
|
53
70
|
* A readonly array that is non-empty when present. Used by every optional `related` collection.
|
|
54
71
|
*/
|
|
55
72
|
type NonEmptyReadonlyArray<T> = readonly [T, ...T[]];
|
|
56
|
-
type IsAny<T> = 0 extends 1 & T ? true : false;
|
|
73
|
+
type IsAny$1<T> = 0 extends 1 & T ? true : false;
|
|
57
74
|
/**
|
|
58
75
|
* Reads one declared capability. Returns `never` when the capability is absent.
|
|
59
76
|
*
|
|
@@ -104,7 +121,7 @@ type WidgetMethodOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemb
|
|
|
104
121
|
type WidgetMethodArgsOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = Parameters<WidgetMethodOf<Interfaces, Name>>;
|
|
105
122
|
type WidgetMethodReturnOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = ReturnType<WidgetMethodOf<Interfaces, Name>>;
|
|
106
123
|
type WidgetEventArgsOf<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey> = Extract<WidgetMemberValueOf<WidgetEventsOf<Interfaces>, Name>, readonly any[]>;
|
|
107
|
-
type ContainsPromiseLike<Value> = IsAny<Value> extends true ? false : [Extract<Value, PromiseLike<unknown>>] extends [never] ? false : true;
|
|
124
|
+
type ContainsPromiseLike<Value> = IsAny$1<Value> extends true ? false : [Extract<Value, PromiseLike<unknown>>] extends [never] ? false : true;
|
|
108
125
|
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`;
|
|
109
126
|
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;
|
|
110
127
|
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;
|
|
@@ -151,11 +168,18 @@ declare const widgetValueContractType: unique symbol;
|
|
|
151
168
|
*
|
|
152
169
|
* The generic parameter exists only for Plugin-author type safety. Runtime/integration identity is the
|
|
153
170
|
* stable string `id`; descriptor object identity has no semantic meaning.
|
|
171
|
+
*
|
|
172
|
+
* A contract for `Value` describes every value of that type, so it can be attached to a Property whose
|
|
173
|
+
* value type is the same or narrower (every value the Property produces satisfies the contract):
|
|
174
|
+
* `WidgetValueContract<string>` fits a `'small' | 'large'` Property, but not a `string | null` one.
|
|
154
175
|
*/
|
|
155
176
|
interface WidgetValueContract<Value> {
|
|
156
177
|
readonly id: string;
|
|
157
|
-
/**
|
|
158
|
-
|
|
178
|
+
/**
|
|
179
|
+
* Type-only contravariant brand (`WidgetValueContract<Wide>` is assignable to
|
|
180
|
+
* `WidgetValueContract<Narrow>`); the factory-created runtime descriptor contains only `id`.
|
|
181
|
+
*/
|
|
182
|
+
readonly [widgetValueContractType]: (value: Value) => void;
|
|
159
183
|
}
|
|
160
184
|
/**
|
|
161
185
|
* Declares a stable semantic value-contract id while retaining the associated TypeScript value type for
|
|
@@ -190,6 +214,8 @@ interface ErasedWidgetPropertyDefinition {
|
|
|
190
214
|
interface ErasedWidgetMethodDefinition {
|
|
191
215
|
readonly registerDeps?: (ctx: any) => RegisteredDeps;
|
|
192
216
|
readonly validateArgs: (args: readonly unknown[], ctx: any) => boolean;
|
|
217
|
+
/** The declared Events, a frozen copy; checked against the events section by `done()`. */
|
|
218
|
+
readonly emits?: readonly WidgetMemberKey[];
|
|
193
219
|
readonly execute: (ctx: any) => unknown;
|
|
194
220
|
}
|
|
195
221
|
interface ErasedWidgetEventDefinition {
|
|
@@ -234,14 +260,19 @@ interface WidgetPluginCapabilities {
|
|
|
234
260
|
readonly methods: boolean;
|
|
235
261
|
readonly events: boolean;
|
|
236
262
|
}
|
|
237
|
-
/**
|
|
238
|
-
* A completed plugin. Plugin-specific integration options are captured by the plugin factory's
|
|
239
|
-
* closure; there is no `pluginConfig` / `globalConfig`.
|
|
240
|
-
*/
|
|
263
|
+
/** Passive RawConfig authoring metadata of a plugin with a config capability. */
|
|
241
264
|
interface WidgetPluginConfigMetadata {
|
|
242
265
|
readonly description: string;
|
|
243
266
|
readonly schema: WidgetConfigJsonSchema | null;
|
|
244
267
|
}
|
|
268
|
+
/**
|
|
269
|
+
* A completed plugin. Plugin-specific integration options are captured by the plugin factory's
|
|
270
|
+
* closure; there is no `pluginConfig` / `globalConfig`.
|
|
271
|
+
*
|
|
272
|
+
* A completed plugin is immutable: `done()` freezes it, every section builder is sealed once its build
|
|
273
|
+
* callback returns, and every config, slot and member definition was captured by value when declared,
|
|
274
|
+
* so neither a retained builder section nor later mutation of the author's definition objects changes it.
|
|
275
|
+
*/
|
|
245
276
|
interface WidgetPlugin<Type extends string = string, Interfaces extends WidgetInterfaces = WidgetInterfaces> {
|
|
246
277
|
readonly type: Type;
|
|
247
278
|
readonly description: string;
|
|
@@ -291,19 +322,60 @@ type WidgetRegisterDepsContext<Interfaces extends WidgetInterfaces, Consumer ext
|
|
|
291
322
|
} & WidgetResolvedConfigContext<Interfaces>;
|
|
292
323
|
type WidgetPropertyComputeContext<Interfaces extends WidgetInterfaces, Deps extends RegisteredDeps> = {
|
|
293
324
|
readonly widget: SelfBlueprintWidgetNode<Interfaces>;
|
|
294
|
-
readonly blueprint:
|
|
325
|
+
readonly blueprint: BlueprintRuntimeView;
|
|
295
326
|
readonly deps: ToExecutedDeps<Deps, 'property'>;
|
|
296
327
|
} & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces>;
|
|
297
328
|
type WidgetEventEmitter<Interfaces extends WidgetInterfaces> = { readonly [Name in WidgetEventKeyOf<Interfaces>]: (...args: WidgetEventArgsOf<Interfaces, Name>) => void; };
|
|
298
|
-
|
|
299
|
-
|
|
329
|
+
/** The `emit` one Method receives carries exactly the Events it declares in `emits`. */
|
|
330
|
+
type WidgetMethodEventEmitter<Interfaces extends WidgetInterfaces, Emits extends WidgetEventKeyOf<Interfaces>> = { readonly [Name in Emits]: (...args: WidgetEventArgsOf<Interfaces, Name>) => void; };
|
|
331
|
+
type WidgetEventEmitterContext<Interfaces extends WidgetInterfaces, Emits extends WidgetEventKeyOf<Interfaces> = never> = HasWidgetCapability<Interfaces, 'events'> extends true ? {
|
|
332
|
+
readonly emit: WidgetMethodEventEmitter<Interfaces, Emits>;
|
|
300
333
|
} : unknown;
|
|
301
|
-
type WidgetMethodExecuteContext<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps> = {
|
|
334
|
+
type WidgetMethodExecuteContext<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps, Emits extends WidgetEventKeyOf<Interfaces> = never> = {
|
|
302
335
|
readonly args: WidgetMethodArgsOf<Interfaces, Name>;
|
|
303
336
|
readonly widget: SelfBlueprintWidgetNode<Interfaces>;
|
|
304
|
-
readonly blueprint:
|
|
337
|
+
readonly blueprint: BlueprintRuntimeView;
|
|
305
338
|
readonly deps: ToExecutedDeps<Deps, 'method'>;
|
|
306
|
-
} & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces> & WidgetEventEmitterContext<Interfaces>;
|
|
339
|
+
} & DiagnosticCollector<RelativeValueDiagnosticInput> & WidgetResolvedConfigContext<Interfaces> & WidgetEventEmitterContext<Interfaces, Emits>;
|
|
340
|
+
type IsAny<T> = 0 extends 1 & T ? true : false;
|
|
341
|
+
type IsExactlyVoid<T> = (<X>() => X extends T ? 1 : 2) extends (<X>() => X extends void ? 1 : 2) ? true : false;
|
|
342
|
+
/**
|
|
343
|
+
* Whether `Value` can be a thenable: anything with a callable `then`, which is what the runtime guard
|
|
344
|
+
* rejects (not only a native `PromiseLike`). An object whose `then` is not a function is not one. For a
|
|
345
|
+
* value of a type parameter the check stays deferred, which TypeScript accepts.
|
|
346
|
+
*/
|
|
347
|
+
type MayBeThenable<Value> = [Extract<Value, {
|
|
348
|
+
readonly then: (...args: never) => unknown;
|
|
349
|
+
}>] extends [never] ? false : true;
|
|
350
|
+
/**
|
|
351
|
+
* What a thenable result is checked against. The `then` text is the compile-error message; no callable
|
|
352
|
+
* `then` satisfies it.
|
|
353
|
+
*/
|
|
354
|
+
interface WidgetSynchronousResultViolation {
|
|
355
|
+
readonly then: 'widget-core: semantic callbacks are synchronous; returning a PromiseLike/thenable is a contract violation';
|
|
356
|
+
}
|
|
357
|
+
/**
|
|
358
|
+
* The return type a semantic callback is checked against, given `Result`, the callback's own return type:
|
|
359
|
+
* `Result` itself unless it can be a thenable. A `void` (or `unknown`) return type cannot do this on its own:
|
|
360
|
+
* TypeScript lets a `void`-returning function type accept any function, an `async` one included, and every
|
|
361
|
+
* value is assignable to `unknown`. Gating on the callback's own return type rejects a thenable while every
|
|
362
|
+
* synchronous value — an `unknown`-typed expression, a value of a type parameter, an object whose `then` is
|
|
363
|
+
* not a function — still type-checks.
|
|
364
|
+
*
|
|
365
|
+
* `Result` is inferred where the callback is written into the builder (a Method's `execute`, a slot's or the
|
|
366
|
+
* plugin's `validateStructure`) or into `createWidgetSystem`'s options. A standalone definition type has no
|
|
367
|
+
* callback to infer from, so `Result` defaults to `unknown` and it accepts any return: a thenable reaching
|
|
368
|
+
* Core through a callback typed only by such an annotation is caught by the runtime guard instead, which
|
|
369
|
+
* throws a `TypeError`.
|
|
370
|
+
*/
|
|
371
|
+
type WidgetSynchronousResult<Result> = Result & (MayBeThenable<Result> extends true ? WidgetSynchronousResultViolation : unknown);
|
|
372
|
+
/**
|
|
373
|
+
* `execute`'s return type for the declared Method return `Declared`. A declared type a thenable is
|
|
374
|
+
* assignable to — exactly `void`, `unknown`, `{}`, `object` — gates on the `execute`'s own return type
|
|
375
|
+
* `Result` (see {@link WidgetSynchronousResult}); any other declared type already rejects a PromiseLike (see
|
|
376
|
+
* `WidgetInterfacesViolationOf`). `any` stays unchecked.
|
|
377
|
+
*/
|
|
378
|
+
type WidgetMethodExecuteResult<Declared, Result> = IsAny<Declared> extends true ? Declared : IsExactlyVoid<Declared> extends true ? WidgetSynchronousResult<Result> : PromiseLike<unknown> extends Declared ? Declared & WidgetSynchronousResult<Result> : Declared;
|
|
307
379
|
interface WidgetConfigDefinition<Interfaces extends WidgetInterfaces> {
|
|
308
380
|
readonly description: string;
|
|
309
381
|
/** Passive Draft 2020-12 authoring metadata. Core does not validate or execute this schema. */
|
|
@@ -311,17 +383,24 @@ interface WidgetConfigDefinition<Interfaces extends WidgetInterfaces> {
|
|
|
311
383
|
readonly validate: (input: unknown, ctx: WidgetConfigValidateContext) => input is WidgetRawConfigOf<Interfaces>;
|
|
312
384
|
readonly resolve: (rawConfig: WidgetRawConfigOf<Interfaces> | null) => WidgetResolvedConfigOf<Interfaces>;
|
|
313
385
|
}
|
|
314
|
-
|
|
386
|
+
/** `Result` is the slot validator's own return type (see {@link WidgetSynchronousResult}). */
|
|
387
|
+
interface WidgetSlotDefinition<Interfaces extends WidgetInterfaces, SlotName extends WidgetMemberKey, Result = unknown> {
|
|
315
388
|
readonly description: string;
|
|
316
|
-
readonly validateStructure?: (ctx: WidgetSlotValidateStructureContext<Interfaces, SlotName>) =>
|
|
389
|
+
readonly validateStructure?: (ctx: WidgetSlotValidateStructureContext<Interfaces, SlotName>) => WidgetSynchronousResult<Result>;
|
|
317
390
|
}
|
|
318
391
|
type WidgetSlotDefinitions<Interfaces extends WidgetInterfaces> = { readonly [Name in WidgetSlotNameOf<Interfaces>]: WidgetSlotDefinition<Interfaces, Name>; };
|
|
392
|
+
/** The return type of the `validateStructure` a slots object declares for `Name`, or `unknown`. */
|
|
393
|
+
type WidgetSlotStructureResultOf<Definitions, Name extends PropertyKey> = Definitions extends { readonly [Key in Name]: {
|
|
394
|
+
readonly validateStructure?: (...args: never) => infer Result;
|
|
395
|
+
}; } ? Result : unknown;
|
|
319
396
|
/**
|
|
320
397
|
* Rejects a slots object that carries a slot the interfaces never declared, including when the
|
|
321
|
-
* object is supplied through a variable instead of a fresh object literal
|
|
398
|
+
* object is supplied through a variable instead of a fresh object literal, and a slot validator that
|
|
399
|
+
* returns a thenable.
|
|
322
400
|
*/
|
|
323
|
-
type ExactWidgetSlotDefinitions<Interfaces extends WidgetInterfaces, Definitions> =
|
|
324
|
-
|
|
401
|
+
type ExactWidgetSlotDefinitions<Interfaces extends WidgetInterfaces, Definitions> = { readonly [Name in WidgetSlotNameOf<Interfaces>]: WidgetSlotDefinition<Interfaces, Name, WidgetSlotStructureResultOf<Definitions, Name>>; } & { readonly [Name in keyof Definitions as Name extends WidgetSlotNameOf<Interfaces> ? never : Name]: never; };
|
|
402
|
+
/** `Result` is the validator's own return type (see {@link WidgetSynchronousResult}). */
|
|
403
|
+
type WidgetPluginValidateStructure<Interfaces extends WidgetInterfaces, Result = unknown> = (ctx: WidgetPluginValidateStructureContext<Interfaces>) => WidgetSynchronousResult<Result>;
|
|
325
404
|
interface WidgetStateMemberDefinition<Interfaces extends WidgetInterfaces, Key extends WidgetMemberKey> {
|
|
326
405
|
/** Passive authoring policy. Omitted means this State member is not author-writable. */
|
|
327
406
|
readonly authorWritable?: boolean;
|
|
@@ -334,11 +413,25 @@ interface WidgetPropertyDefinition<Interfaces extends WidgetInterfaces, Name ext
|
|
|
334
413
|
readonly registerDeps?: (ctx: WidgetRegisterDepsContext<Interfaces, 'property'>) => Deps;
|
|
335
414
|
readonly compute: (ctx: WidgetPropertyComputeContext<Interfaces, Deps>) => WidgetPropertyValueOf<Interfaces, Name>;
|
|
336
415
|
}
|
|
337
|
-
interface
|
|
416
|
+
interface WidgetMethodDefinitionFields<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps, Result, Emits extends WidgetEventKeyOf<Interfaces>> {
|
|
338
417
|
readonly registerDeps?: (ctx: WidgetRegisterDepsContext<Interfaces, 'method'>) => Deps;
|
|
339
418
|
readonly validateArgs: (args: readonly unknown[], ctx: WidgetMethodValidateArgsContext<Interfaces>) => args is WidgetMethodArgsOf<Interfaces, Name>;
|
|
340
|
-
|
|
419
|
+
/**
|
|
420
|
+
* The Events this Method may emit. Omitted or empty means none. A Method that emits an Event, itself or
|
|
421
|
+
* through the Methods it invokes, is not read-only, so no Property may depend on it.
|
|
422
|
+
*/
|
|
423
|
+
readonly emits?: readonly Emits[];
|
|
424
|
+
readonly execute: (ctx: WidgetMethodExecuteContext<Interfaces, Name, Deps, Emits>) => WidgetMethodExecuteResult<WidgetMethodReturnOf<Interfaces, Name>, Result>;
|
|
341
425
|
}
|
|
426
|
+
/**
|
|
427
|
+
* `Result` is `execute`'s own return type (see {@link WidgetMethodExecuteResult}). `Emits` is the union of
|
|
428
|
+
* the Events the Method declares: whenever it is not `never`, `execute` receives an `emit` with those
|
|
429
|
+
* Events, so `emits` is required (a definition that types `emit` without declaring it would throw at its
|
|
430
|
+
* first emit).
|
|
431
|
+
*/
|
|
432
|
+
type WidgetMethodDefinition<Interfaces extends WidgetInterfaces, Name extends WidgetMemberKey, Deps extends RegisteredDeps, Result = unknown, Emits extends WidgetEventKeyOf<Interfaces> = never> = WidgetMethodDefinitionFields<Interfaces, Name, Deps, Result, Emits> & ([Emits] extends [never] ? unknown : {
|
|
433
|
+
readonly emits: readonly Emits[];
|
|
434
|
+
});
|
|
342
435
|
interface WidgetEventDefinition {
|
|
343
436
|
readonly description: string;
|
|
344
437
|
}
|
|
@@ -352,7 +445,7 @@ interface WidgetSectionMarker<Kind extends string, Remaining extends WidgetMembe
|
|
|
352
445
|
}
|
|
353
446
|
type WidgetStateSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetStateKeyOf<Interfaces>> = WidgetSectionMarker<'state', Remaining> & { [Key in Remaining]: (definition: WidgetStateMemberDefinition<Interfaces, Key>) => WidgetStateSection<Interfaces, Exclude<Remaining, Key>>; };
|
|
354
447
|
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>>; };
|
|
355
|
-
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>>; };
|
|
448
|
+
type WidgetMethodsSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetMethodKeyOf<Interfaces>> = WidgetSectionMarker<'methods', Remaining> & { [Name in Remaining]: <const Deps extends RegisteredDeps = EmptyRegisteredDeps, Result = unknown, const Emits extends WidgetEventKeyOf<Interfaces> = never>(definition: WidgetMethodDefinition<Interfaces, Name, Deps, Result, Emits>) => WidgetMethodsSection<Interfaces, Exclude<Remaining, Name>>; };
|
|
356
449
|
type WidgetEventsSection<Interfaces extends WidgetInterfaces, Remaining extends WidgetEventKeyOf<Interfaces>> = WidgetSectionMarker<'events', Remaining> & { [Name in Remaining]: (definition: WidgetEventDefinition) => WidgetEventsSection<Interfaces, Exclude<Remaining, Name>>; };
|
|
357
450
|
/**
|
|
358
451
|
* Returned instead of the next builder phase when the supplied `WidgetInterfaces` is outside the
|
|
@@ -365,16 +458,21 @@ interface WidgetPluginDonePhase<Type extends string, Interfaces extends WidgetIn
|
|
|
365
458
|
done: () => WidgetPlugin<Type, Interfaces>;
|
|
366
459
|
}
|
|
367
460
|
/**
|
|
368
|
-
* Outer
|
|
369
|
-
* the
|
|
461
|
+
* Outer builder phases in their fixed call order: every capability phase plus the optional,
|
|
462
|
+
* capability-independent `structure` phase. Part of the type-level order diagnostics only; the runtime
|
|
463
|
+
* builder is order-agnostic.
|
|
370
464
|
*/
|
|
371
|
-
type WidgetPluginPhaseOrder = readonly ['config', 'slots', 'state', 'properties', 'methods', 'events'];
|
|
465
|
+
type WidgetPluginPhaseOrder = readonly ['config', 'slots', 'structure', 'state', 'properties', 'methods', 'events'];
|
|
372
466
|
type WidgetPluginPhaseName = WidgetPluginPhaseOrder[number];
|
|
373
|
-
|
|
374
|
-
|
|
467
|
+
type WidgetPluginCapabilityPhaseName = Exclude<WidgetPluginPhaseName, 'structure'>;
|
|
468
|
+
/**
|
|
469
|
+
* The phases available for `Interfaces`: every phase whose capability was declared, plus `structure`,
|
|
470
|
+
* which every plugin may call (at most once) regardless of its capabilities.
|
|
471
|
+
*/
|
|
472
|
+
type WidgetPluginAvailablePhaseName<Interfaces extends WidgetInterfaces> = 'structure' | { [Phase in WidgetPluginCapabilityPhaseName]: HasWidgetCapability<Interfaces, Phase> extends true ? Phase : never; }[WidgetPluginCapabilityPhaseName];
|
|
375
473
|
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;
|
|
376
474
|
/**
|
|
377
|
-
* Type-only order marker: the message of the compile error raised when
|
|
475
|
+
* Type-only order marker: the message of the compile error raised when an available phase is called at
|
|
378
476
|
* the wrong position. The marker name and reason text are diagnostics, not protocol.
|
|
379
477
|
*/
|
|
380
478
|
interface WidgetPluginPhaseOrderViolation<Reason extends string> {
|
|
@@ -386,39 +484,58 @@ interface WidgetPluginPhaseOrderViolation<Reason extends string> {
|
|
|
386
484
|
* reason) in the message, while the function constituent keeps callbacks contextually typed, so no
|
|
387
485
|
* implicit-`any` follow-on errors appear. Section builders may return anything.
|
|
388
486
|
*/
|
|
389
|
-
type WidgetPluginMisplacedArguments<Interfaces extends WidgetInterfaces, Phase extends WidgetPluginPhaseName, Violation> = Phase extends 'config' ? [definition: Violation & WidgetConfigDefinition<Interfaces>] : Phase extends 'slots' ? [definitions: Violation & WidgetSlotDefinitions<Interfaces
|
|
390
|
-
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()`;
|
|
487
|
+
type WidgetPluginMisplacedArguments<Interfaces extends WidgetInterfaces, Phase extends WidgetPluginPhaseName, Violation> = Phase extends 'config' ? [definition: Violation & WidgetConfigDefinition<Interfaces>] : Phase extends 'slots' ? [definitions: Violation & WidgetSlotDefinitions<Interfaces>] : Phase extends 'structure' ? [validateStructure: Violation & 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)];
|
|
488
|
+
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? -> structure? -> state? -> properties? -> methods? -> events? -> done()` : `'.${Phase}()' is called too early; call '.${Stage}()' first. Order: description -> interfaces -> config? -> slots? -> structure? -> 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? -> structure? -> state? -> properties? -> methods? -> events? -> done()`;
|
|
391
489
|
/**
|
|
392
|
-
* Adds type-only order markers for every
|
|
393
|
-
*
|
|
490
|
+
* Adds type-only order markers for every available phase that is not in `Callable` (by default just
|
|
491
|
+
* `Stage`, the next phase; the `structure` stage also keeps the optional `structure` phase callable).
|
|
492
|
+
* A marker takes the real phase's arguments with the first one intersected with
|
|
394
493
|
* `WidgetPluginPhaseOrderViolation`, so no real value satisfies it and the call fails with an
|
|
395
|
-
* order-specific diagnostic (the function constituent keeps a callback passed to it
|
|
396
|
-
* so no implicit-`any` follow-on errors appear). It returns the same phase, so a
|
|
397
|
-
* advances the chain.
|
|
494
|
+
* order-specific diagnostic relative to `Stage` (the function constituent keeps a callback passed to it
|
|
495
|
+
* contextually typed, so no implicit-`any` follow-on errors appear). It returns the same phase, so a
|
|
496
|
+
* misplaced call never advances the chain.
|
|
398
497
|
*/
|
|
399
|
-
type WidgetPluginOrderedPhase<Phase, Interfaces extends WidgetInterfaces, Stage extends WidgetPluginPhaseName | 'done'> = [Exclude<
|
|
400
|
-
|
|
498
|
+
type WidgetPluginOrderedPhase<Phase, Interfaces extends WidgetInterfaces, Stage extends WidgetPluginPhaseName | 'done', Callable extends WidgetPluginPhaseName | 'done' = Stage> = [Exclude<WidgetPluginAvailablePhaseName<Interfaces>, Callable>] extends [never] ? Phase : Phase & { [Misplaced in Exclude<WidgetPluginAvailablePhaseName<Interfaces>, Callable>]: (...args: WidgetPluginMisplacedArguments<Interfaces, Misplaced, WidgetPluginPhaseOrderViolation<WidgetPluginPhaseOrderReason<Misplaced, Stage>>>) => WidgetPluginOrderedPhase<Phase, Interfaces, Stage, Callable>; };
|
|
499
|
+
interface WidgetPluginEventsPhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
|
|
401
500
|
events: (build: (section: WidgetEventsSection<Interfaces, WidgetEventKeyOf<Interfaces>>) => WidgetEventsSection<Interfaces, never>) => WidgetPluginOrderedPhase<WidgetPluginDonePhase<Type, Interfaces>, Interfaces, 'done'>;
|
|
402
|
-
}
|
|
403
|
-
|
|
501
|
+
}
|
|
502
|
+
interface WidgetPluginMethodsPhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
|
|
404
503
|
methods: (build: (section: WidgetMethodsSection<Interfaces, WidgetMethodKeyOf<Interfaces>>) => WidgetMethodsSection<Interfaces, never>) => WidgetPluginEventsPhase<Type, Interfaces>;
|
|
405
|
-
}
|
|
406
|
-
|
|
504
|
+
}
|
|
505
|
+
interface WidgetPluginPropertiesPhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
|
|
407
506
|
properties: (build: (section: WidgetPropertiesSection<Interfaces, WidgetPropertyKeyOf<Interfaces>>) => WidgetPropertiesSection<Interfaces, never>) => WidgetPluginMethodsPhase<Type, Interfaces>;
|
|
408
|
-
}
|
|
409
|
-
|
|
507
|
+
}
|
|
508
|
+
interface WidgetPluginStatePhaseMembers<Type extends string, Interfaces extends WidgetInterfaces> {
|
|
410
509
|
state: (build: (section: WidgetStateSection<Interfaces, WidgetStateKeyOf<Interfaces>>) => WidgetStateSection<Interfaces, never>) => WidgetPluginPropertiesPhase<Type, Interfaces>;
|
|
411
|
-
}
|
|
510
|
+
}
|
|
511
|
+
type WidgetPluginEventsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'events'> extends true ? WidgetPluginOrderedPhase<WidgetPluginEventsPhaseMembers<Type, Interfaces>, Interfaces, 'events'> : WidgetPluginOrderedPhase<WidgetPluginDonePhase<Type, Interfaces>, Interfaces, 'done'>;
|
|
512
|
+
type WidgetPluginMethodsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'methods'> extends true ? WidgetPluginOrderedPhase<WidgetPluginMethodsPhaseMembers<Type, Interfaces>, Interfaces, 'methods'> : WidgetPluginEventsPhase<Type, Interfaces>;
|
|
513
|
+
type WidgetPluginPropertiesPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'properties'> extends true ? WidgetPluginOrderedPhase<WidgetPluginPropertiesPhaseMembers<Type, Interfaces>, Interfaces, 'properties'> : WidgetPluginMethodsPhase<Type, Interfaces>;
|
|
514
|
+
type WidgetPluginStatePhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? WidgetPluginOrderedPhase<WidgetPluginStatePhaseMembers<Type, Interfaces>, Interfaces, 'state'> : WidgetPluginPropertiesPhase<Type, Interfaces>;
|
|
515
|
+
/**
|
|
516
|
+
* The `structure` stage: the optional `.structure()` call and the first declared phase after it (or
|
|
517
|
+
* `.done()`) are both callable. Order markers report relative to that next phase, since `structure` may
|
|
518
|
+
* be skipped.
|
|
519
|
+
*/
|
|
520
|
+
type WidgetPluginStructureStage<Type extends string, Interfaces extends WidgetInterfaces, Next extends WidgetPluginPhaseName | 'done', NextMembers> = WidgetPluginOrderedPhase<{
|
|
521
|
+
structure: <Result = unknown>(validateStructure: WidgetPluginValidateStructure<Interfaces, Result>) => WidgetPluginStatePhase<Type, Interfaces>;
|
|
522
|
+
} & NextMembers, Interfaces, Next, 'structure' | Next>;
|
|
523
|
+
/**
|
|
524
|
+
* The optional plugin-level structure validator phase. It is not a capability: every plugin may call
|
|
525
|
+
* `.structure(validateStructure)` at most once, after `slots?` and before `state?`, and it changes
|
|
526
|
+
* neither `plugin.capabilities`, the catalog, nor inspection.
|
|
527
|
+
*/
|
|
528
|
+
type WidgetPluginStructurePhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'state', WidgetPluginStatePhaseMembers<Type, Interfaces>> : HasWidgetCapability<Interfaces, 'properties'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'properties', WidgetPluginPropertiesPhaseMembers<Type, Interfaces>> : HasWidgetCapability<Interfaces, 'methods'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'methods', WidgetPluginMethodsPhaseMembers<Type, Interfaces>> : HasWidgetCapability<Interfaces, 'events'> extends true ? WidgetPluginStructureStage<Type, Interfaces, 'events', WidgetPluginEventsPhaseMembers<Type, Interfaces>> : WidgetPluginStructureStage<Type, Interfaces, 'done', WidgetPluginDonePhase<Type, Interfaces>>;
|
|
412
529
|
/**
|
|
413
530
|
* `slots: never` is the canonical explicit-empty slots declaration (diagnostic #10 amendment
|
|
414
531
|
* "declaration-presence semantics and public `WidgetPlugin.capabilities`"): the phase still exists —
|
|
415
532
|
* gated on `HasWidgetCapability`, never on whether `WidgetCapabilityOf<Interfaces, 'slots'>` happens to
|
|
416
533
|
* be `never` — and completes as `.slots({})`, since `ExactWidgetSlotDefinitions` for zero slot names is
|
|
417
|
-
* exactly `{}`.
|
|
534
|
+
* exactly `{}`. A plugin-level structure validator is declared with the following `.structure()` phase.
|
|
418
535
|
*/
|
|
419
536
|
type WidgetPluginSlotsPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'slots'> extends true ? WidgetPluginOrderedPhase<{
|
|
420
|
-
slots: <const Definitions extends ExactWidgetSlotDefinitions<Interfaces, Definitions>>(definitions: Definitions
|
|
421
|
-
}, Interfaces, 'slots'> :
|
|
537
|
+
slots: <const Definitions extends ExactWidgetSlotDefinitions<Interfaces, Definitions>>(definitions: Definitions) => WidgetPluginStructurePhase<Type, Interfaces>;
|
|
538
|
+
}, Interfaces, 'slots'> : WidgetPluginStructurePhase<Type, Interfaces>;
|
|
422
539
|
type WidgetPluginConfigPhase<Type extends string, Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'config'> extends true ? WidgetPluginOrderedPhase<{
|
|
423
540
|
config: (definition: WidgetConfigDefinition<Interfaces>) => WidgetPluginSlotsPhase<Type, Interfaces>;
|
|
424
541
|
}, Interfaces, 'config'> : WidgetPluginSlotsPhase<Type, Interfaces>;
|
|
@@ -431,8 +548,9 @@ interface WidgetPluginDescriptionPhase<Type extends string> {
|
|
|
431
548
|
/**
|
|
432
549
|
* Starts the plugin builder for one plugin `type`.
|
|
433
550
|
*
|
|
434
|
-
* Phase order is `description -> interfaces -> config? -> slots? -> state? -> properties? -> methods? -> events? -> done()`;
|
|
435
|
-
* a phase exists only when its capability is declared
|
|
551
|
+
* Phase order is `description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()`;
|
|
552
|
+
* a capability phase exists only when its capability is declared, while the optional `structure` phase
|
|
553
|
+
* (the plugin-level structure validator) is available to every plugin. Calling a phase out of order (or
|
|
436
554
|
* repeating it) fails type-checking with an order-specific diagnostic; the runtime builder itself is
|
|
437
555
|
* order-agnostic.
|
|
438
556
|
*/
|
|
@@ -455,10 +573,11 @@ interface WidgetCatalog {
|
|
|
455
573
|
type WidgetSystemValidateStructureContext<Plugins extends AnyWidgetPluginTuple> = {
|
|
456
574
|
readonly blueprint: BlueprintCompileView<Plugins>;
|
|
457
575
|
} & DiagnosticCollector<RelativeSystemStructureDiagnosticInput<Plugins>>;
|
|
458
|
-
|
|
459
|
-
|
|
576
|
+
/** `Result` is the validator's own return type (see `WidgetSynchronousResult`). */
|
|
577
|
+
type WidgetSystemValidateStructure<Plugins extends AnyWidgetPluginTuple, Result = unknown> = (ctx: WidgetSystemValidateStructureContext<Plugins>) => WidgetSynchronousResult<Result>;
|
|
578
|
+
interface CreateWidgetSystemOptions<Plugins extends AnyWidgetPluginTuple, Result = unknown> {
|
|
460
579
|
readonly plugins: Plugins;
|
|
461
|
-
readonly validateStructure?: WidgetSystemValidateStructure<Plugins>;
|
|
580
|
+
readonly validateStructure?: WidgetSystemValidateStructure<Plugins, Result>;
|
|
462
581
|
}
|
|
463
582
|
/**
|
|
464
583
|
* Selects one registered plugin by its `type` discriminator.
|
|
@@ -466,6 +585,20 @@ interface CreateWidgetSystemOptions<Plugins extends AnyWidgetPluginTuple> {
|
|
|
466
585
|
type WidgetPluginOf<Plugins extends AnyWidgetPluginTuple, Type extends string> = Extract<Plugins[number], {
|
|
467
586
|
readonly type: Type;
|
|
468
587
|
}>;
|
|
588
|
+
/** The registered plugin types that are string literals; a plugin typed with a broad `string` adds none. */
|
|
589
|
+
type WidgetPluginLiteralTypeOf<Plugins extends AnyWidgetPluginTuple> = WidgetPluginTypeOf<Plugins[number]> extends (infer Type) ? Type extends string ? (string extends Type ? never : Type) : never : never;
|
|
590
|
+
/**
|
|
591
|
+
* `getPlugin` overloads. `Plugins` appears only in type-parameter constraints and in `WidgetPluginOf`, so
|
|
592
|
+
* a precisely typed System stays assignable to a loosely typed one (`WidgetSystem`).
|
|
593
|
+
*/
|
|
594
|
+
interface WidgetSystemGetPlugin<Plugins extends AnyWidgetPluginTuple> {
|
|
595
|
+
/** A registered literal type (or a union of them): that exact plugin. */
|
|
596
|
+
<Type extends WidgetPluginLiteralTypeOf<Plugins>>(type: Type): WidgetPluginOf<Plugins, Type>;
|
|
597
|
+
/** Any type on a loosely typed System (one with a broad `string` plugin type), which may be unregistered. */
|
|
598
|
+
<Type extends WidgetPluginTypeOf<Plugins[number]>>(type: Type): AnyWidgetPlugin | null;
|
|
599
|
+
/** A broad `string`, which may name no registered plugin. An unregistered literal on a precisely typed System stays a type error. */
|
|
600
|
+
<Type extends string>(type: string extends Type ? Type : never): AnyWidgetPlugin | null;
|
|
601
|
+
}
|
|
469
602
|
interface WidgetSystem<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
|
|
470
603
|
/**
|
|
471
604
|
* The registered plugin tuple. It defines this instance's TypeScript universe; there is no
|
|
@@ -474,7 +607,8 @@ interface WidgetSystem<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTup
|
|
|
474
607
|
readonly plugins: Plugins;
|
|
475
608
|
readonly validateStructure: WidgetSystemValidateStructure<Plugins> | null;
|
|
476
609
|
readonly catalog: WidgetCatalog;
|
|
477
|
-
|
|
610
|
+
/** The registered plugin of `type`, or `null` when no plugin of that type is registered. */
|
|
611
|
+
getPlugin: WidgetSystemGetPlugin<Plugins>;
|
|
478
612
|
/**
|
|
479
613
|
* The compilation boundary. The input is `unknown` because JSON-parsed/untrusted document data is
|
|
480
614
|
* the real boundary; malformed input still produces an inspectable Blueprint.
|
|
@@ -488,19 +622,26 @@ interface WidgetSystem<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTup
|
|
|
488
622
|
*/
|
|
489
623
|
createBlueprint: (definition: unknown) => WidgetSystemBlueprint<Plugins>;
|
|
490
624
|
/**
|
|
491
|
-
* Parses `text` with `JSON.parse` and compiles the result.
|
|
492
|
-
* `createBlueprint(JSON.parse(text))`,
|
|
493
|
-
*
|
|
494
|
-
*
|
|
495
|
-
*
|
|
625
|
+
* Parses `text` with `JSON.parse` and compiles the result. Equivalent to
|
|
626
|
+
* `createBlueprint(JSON.parse(text))`, including its diagnostics: a value Core parsed itself can only
|
|
627
|
+
* leave the authored JSON domain through a non-finite number (`1e400` parses to `Infinity`, diagnosed as
|
|
628
|
+
* `json-incompatible-value` / `non-finite-number`) or through nesting deeper than `MAX_JSON_DEPTH`, so Core
|
|
629
|
+
* replaces the descriptor-level JSON-domain inspection with a cheaper scan for exactly those two cases and
|
|
630
|
+
* runs the full inspection when the scan finds either. `sourceJsonCompatible` is `true` only when that
|
|
631
|
+
* proof succeeds. Invalid JSON text throws the `SyntaxError` from `JSON.parse`, unchanged. The parsed
|
|
632
|
+
* source is referenced by nothing but the Blueprint.
|
|
496
633
|
*/
|
|
497
634
|
createBlueprintFromJson: (text: string) => WidgetSystemBlueprint<Plugins>;
|
|
498
635
|
}
|
|
499
|
-
type WidgetSystemConfigurationErrorCode = 'foreign-plugin' | 'duplicate-plugin-type';
|
|
636
|
+
type WidgetSystemConfigurationErrorCode = 'invalid-options' | 'foreign-plugin' | 'duplicate-plugin-type';
|
|
500
637
|
/**
|
|
501
|
-
* Thrown by `createWidgetSystem` for an invalid plugin registration. Discriminate by
|
|
502
|
-
* `message` is not protocol.
|
|
638
|
+
* Thrown by `createWidgetSystem` for invalid options or an invalid plugin registration. Discriminate by
|
|
639
|
+
* class and `code`; `message` is not protocol. The options shape is checked first, then the plugin
|
|
640
|
+
* entries in tuple order.
|
|
503
641
|
*
|
|
642
|
+
* - `invalid-options`: `options` is not an object, `options.plugins` is not an array, or
|
|
643
|
+
* `options.validateStructure` is present (neither `undefined` nor `null`) but not a function.
|
|
644
|
+
* `pluginIndex`, `pluginType` and `firstPluginIndex` are `null`.
|
|
504
645
|
* - `foreign-plugin`: the entry at `pluginIndex` was not completed by this loaded module instance
|
|
505
646
|
* (another module instance or a structural look-alike). `pluginType` is its `type` when a string,
|
|
506
647
|
* else `null`. `firstPluginIndex` is `null`.
|
|
@@ -509,19 +650,26 @@ type WidgetSystemConfigurationErrorCode = 'foreign-plugin' | 'duplicate-plugin-t
|
|
|
509
650
|
*/
|
|
510
651
|
declare class WidgetSystemConfigurationError extends Error {
|
|
511
652
|
readonly code: WidgetSystemConfigurationErrorCode;
|
|
512
|
-
readonly pluginIndex: number;
|
|
653
|
+
readonly pluginIndex: number | null;
|
|
513
654
|
readonly pluginType: string | null;
|
|
514
655
|
readonly firstPluginIndex: number | null;
|
|
515
656
|
readonly name = "WidgetSystemConfigurationError";
|
|
516
|
-
constructor(code: WidgetSystemConfigurationErrorCode, pluginIndex: number, pluginType: string | null, firstPluginIndex?: number | null, message?: string);
|
|
657
|
+
constructor(code: WidgetSystemConfigurationErrorCode, pluginIndex: number | null, pluginType: string | null, firstPluginIndex?: number | null, message?: string);
|
|
517
658
|
}
|
|
518
659
|
/**
|
|
519
|
-
* Creates an instance-scoped, immutable widget system.
|
|
660
|
+
* Creates an instance-scoped, immutable widget system. Malformed options, foreign plugins and duplicate
|
|
661
|
+
* `plugin.type` are rejected with a `WidgetSystemConfigurationError`.
|
|
520
662
|
*/
|
|
521
|
-
declare function createWidgetSystem<const Plugins extends AnyWidgetPluginTuple>(options: CreateWidgetSystemOptions<Plugins>): WidgetSystem<Plugins>;
|
|
663
|
+
declare function createWidgetSystem<const Plugins extends AnyWidgetPluginTuple, Result = unknown>(options: CreateWidgetSystemOptions<Plugins, Result>): WidgetSystem<Plugins>;
|
|
522
664
|
//#endregion
|
|
523
665
|
//#region src/internal/contract.d.ts
|
|
524
666
|
type WidgetSystemBlueprintStatus = 'valid' | 'invalid';
|
|
667
|
+
/**
|
|
668
|
+
* The structured (array form) `SourcePath` of one Blueprint node's authored object within `blueprint.source`,
|
|
669
|
+
* e.g. `[]` for the root and `['slots', 'children', 0]` for its first child. Used verbatim as a `SourcePatch`
|
|
670
|
+
* path against the same source it addresses exactly that node.
|
|
671
|
+
*/
|
|
672
|
+
type BlueprintSourcePath = readonly (string | number)[];
|
|
525
673
|
interface BlueprintWidgetNodeBase<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple, Source = unknown> {
|
|
526
674
|
/**
|
|
527
675
|
* The exact source fragment for this recovered node. Never mutated, cloned or frozen by the core.
|
|
@@ -535,6 +683,10 @@ interface BlueprintWidgetNodeBase<Plugins extends AnyWidgetPluginTuple = AnyWidg
|
|
|
535
683
|
*/
|
|
536
684
|
interface UnresolvedBlueprintWidgetNode<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple, Source = unknown> extends BlueprintWidgetNodeBase<Plugins, Source> {
|
|
537
685
|
readonly resolved: false;
|
|
686
|
+
/** Best-effort identity hint: the authored `id` when it is a string, else `null`. */
|
|
687
|
+
readonly id: string | null;
|
|
688
|
+
/** Best-effort identity hint: the authored `type` when it is a string (even an unknown one), else `null`. */
|
|
689
|
+
readonly type: string | null;
|
|
538
690
|
}
|
|
539
691
|
/**
|
|
540
692
|
* Complete declared semantic slot map. Only declared slots appear, every declared slot exists, and an
|
|
@@ -659,7 +811,7 @@ interface BlueprintCompileView<Plugins extends AnyWidgetPluginTuple = AnyWidgetP
|
|
|
659
811
|
/**
|
|
660
812
|
* Read-only valid-Blueprint view handed to runtime semantic callbacks (`compute`, `execute`).
|
|
661
813
|
*/
|
|
662
|
-
interface
|
|
814
|
+
interface BlueprintRuntimeView<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
|
|
663
815
|
readonly root: ResolvedBlueprintWidgetNode<Plugins, JsonValue>;
|
|
664
816
|
getWidget: (id: WidgetId) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
|
|
665
817
|
getParent: (node: ResolvedBlueprintWidgetNode<Plugins>) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
|
|
@@ -674,6 +826,11 @@ interface ValidBlueprintView<Plugins extends AnyWidgetPluginTuple = AnyWidgetPlu
|
|
|
674
826
|
type WidgetSourceFor<Plugin extends AnyWidgetPlugin, Plugins extends AnyWidgetPluginTuple> = {
|
|
675
827
|
readonly id: WidgetId;
|
|
676
828
|
readonly type: WidgetPluginTypeOf<Plugin>;
|
|
829
|
+
/**
|
|
830
|
+
* The reserved extension key: any JSON value, preserved in `source` and never interpreted by
|
|
831
|
+
* Core. Every other unrecognized own key is diagnosed as `unexpected-widget-field`.
|
|
832
|
+
*/
|
|
833
|
+
readonly meta?: JsonValue;
|
|
677
834
|
} & (HasWidgetCapability<WidgetInterfacesOf<Plugin>, 'config'> extends true ? [null] extends [WidgetRawConfigOf<WidgetInterfacesOf<Plugin>>] ? {
|
|
678
835
|
readonly config?: WidgetRawConfigOf<WidgetInterfacesOf<Plugin>>;
|
|
679
836
|
} : {
|
|
@@ -697,13 +854,14 @@ interface WidgetSystemBlueprintBase<Plugins extends AnyWidgetPluginTuple, Source
|
|
|
697
854
|
*/
|
|
698
855
|
recompile: (definition: unknown) => WidgetSystemBlueprint<Plugins>;
|
|
699
856
|
}
|
|
700
|
-
interface ValidWidgetSystemBlueprint<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> extends WidgetSystemBlueprintBase<Plugins,
|
|
857
|
+
interface ValidWidgetSystemBlueprint<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> extends WidgetSystemBlueprintBase<Plugins, WidgetSource<Plugins>> {
|
|
701
858
|
readonly status: 'valid';
|
|
702
859
|
readonly sourceJsonCompatible: true;
|
|
703
860
|
readonly root: ResolvedBlueprintWidgetNode<Plugins, JsonValue>;
|
|
704
861
|
getWidget: (id: WidgetId) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
|
|
705
862
|
getParent: (node: BlueprintWidgetNode<Plugins>) => ResolvedBlueprintWidgetNode<Plugins, JsonValue> | null;
|
|
706
863
|
getLocation: (node: BlueprintWidgetNode<Plugins>) => WidgetLocation<Plugins, JsonValue> | null;
|
|
864
|
+
getSourcePath: (node: BlueprintWidgetNode<Plugins>) => BlueprintSourcePath | null;
|
|
707
865
|
getChildren: (node: BlueprintWidgetNode<Plugins>) => readonly ResolvedBlueprintWidgetNode<Plugins, JsonValue>[];
|
|
708
866
|
getChildrenAt: (node: BlueprintWidgetNode<Plugins>, slot: WidgetMemberKey) => readonly ResolvedBlueprintWidgetNode<Plugins, JsonValue>[];
|
|
709
867
|
readonly diagnostics: readonly never[];
|
|
@@ -716,6 +874,7 @@ interface InvalidWidgetSystemBlueprint<Plugins extends AnyWidgetPluginTuple = An
|
|
|
716
874
|
getWidget: (id: WidgetId) => BlueprintWidgetNode<Plugins, Source> | null;
|
|
717
875
|
getParent: (node: BlueprintWidgetNode<Plugins>) => BlueprintWidgetNode<Plugins, Source> | null;
|
|
718
876
|
getLocation: (node: BlueprintWidgetNode<Plugins>) => WidgetLocation<Plugins, Source> | null;
|
|
877
|
+
getSourcePath: (node: BlueprintWidgetNode<Plugins>) => BlueprintSourcePath | null;
|
|
719
878
|
getChildren: (node: BlueprintWidgetNode<Plugins>) => readonly BlueprintWidgetNode<Plugins, Source>[];
|
|
720
879
|
getChildrenAt: (node: BlueprintWidgetNode<Plugins>, slot: WidgetMemberKey) => readonly BlueprintWidgetNode<Plugins, Source>[];
|
|
721
880
|
readonly diagnostics: readonly BlueprintDiagnostic<Plugins>[];
|
|
@@ -741,14 +900,16 @@ interface RuntimeState<T> {
|
|
|
741
900
|
getDiagnostics: () => readonly RuntimeStateDiagnostic[];
|
|
742
901
|
subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeStateDiagnostic[]) => void) => () => void;
|
|
743
902
|
}
|
|
903
|
+
/** A completed result's ok value is exactly what `compute` returned (never an added `null`). */
|
|
744
904
|
interface RuntimeProperty<T> {
|
|
745
|
-
get: () => ExecutionResult<T
|
|
746
|
-
subscribe: (listener: (result: ExecutionResult<T
|
|
905
|
+
get: () => ExecutionResult<T, RuntimePropertyDiagnostic>;
|
|
906
|
+
subscribe: (listener: (result: ExecutionResult<T, RuntimePropertyDiagnostic>) => void) => () => void;
|
|
747
907
|
getDiagnostics: () => readonly RuntimePropertyDiagnostic[];
|
|
748
908
|
subscribeDiagnostics: (listener: (diagnostics: readonly RuntimePropertyDiagnostic[]) => void) => () => void;
|
|
749
909
|
}
|
|
910
|
+
/** A successful invocation's ok value is exactly what `execute` returned (never an added `null`). */
|
|
750
911
|
interface RuntimeMethod<Fn extends (...args: any[]) => any> {
|
|
751
|
-
(...args: Parameters<Fn>): ExecutionResult<ReturnType<Fn
|
|
912
|
+
(...args: Parameters<Fn>): ExecutionResult<ReturnType<Fn>, RuntimeMethodDiagnostic>;
|
|
752
913
|
getDiagnostics: () => readonly RuntimeMethodDiagnostic[];
|
|
753
914
|
subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeMethodDiagnostic[]) => void) => () => void;
|
|
754
915
|
}
|
|
@@ -757,6 +918,12 @@ interface RuntimeEvent<Args extends readonly unknown[]> {
|
|
|
757
918
|
}
|
|
758
919
|
type RuntimeStateSurface<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'state'> extends true ? {
|
|
759
920
|
readonly state: { readonly [Key in WidgetStateKeyOf<Interfaces>]: RuntimeState<WidgetStateValueOf<Interfaces, Key>>; };
|
|
921
|
+
/**
|
|
922
|
+
* `WidgetSystemRuntime.resetState()` scoped to this widget: restores its State members to their
|
|
923
|
+
* initialization outcome without running `validate`, in one batch; Property/Method diagnostic
|
|
924
|
+
* snapshots are not reset. Throws `WidgetSystemRuntimeDisposedError` after dispose.
|
|
925
|
+
*/
|
|
926
|
+
resetState: () => void;
|
|
760
927
|
} : unknown;
|
|
761
928
|
type RuntimePropertySurface<Interfaces extends WidgetInterfaces> = HasWidgetCapability<Interfaces, 'properties'> extends true ? {
|
|
762
929
|
readonly properties: { readonly [Name in WidgetPropertyKeyOf<Interfaces>]: RuntimeProperty<WidgetPropertyValueOf<Interfaces, Name>>; };
|
|
@@ -778,7 +945,7 @@ type RuntimeMethodSurface<Interfaces extends WidgetInterfaces> = HasWidgetCapabi
|
|
|
778
945
|
type RuntimeWidgetFor<Plugin extends AnyWidgetPlugin, Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> = {
|
|
779
946
|
readonly id: WidgetId;
|
|
780
947
|
readonly type: WidgetPluginTypeOf<Plugin>;
|
|
781
|
-
readonly
|
|
948
|
+
readonly blueprintNode: ResolvedBlueprintWidgetNodeFor<Plugin, Plugins>;
|
|
782
949
|
/**
|
|
783
950
|
* This widget's own aggregate diagnostic snapshot: state members -> property members -> method
|
|
784
951
|
* members, declaration order within each capability, each primitive's own local diagnostic order.
|
|
@@ -793,7 +960,8 @@ type RuntimeWidget<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple>
|
|
|
793
960
|
* Executable instance of a valid Blueprint.
|
|
794
961
|
*
|
|
795
962
|
* After `dispose()`, `isDisposed` and `blueprint` stay readable while every live query/operation and
|
|
796
|
-
* every new subscription throws `WidgetSystemRuntimeDisposedError`.
|
|
963
|
+
* every new subscription throws `WidgetSystemRuntimeDisposedError`. Disposal notifies only the listeners
|
|
964
|
+
* registered with `subscribeDisposal()`; it emits no State, Property, Event or diagnostic notification.
|
|
797
965
|
*/
|
|
798
966
|
interface WidgetSystemRuntime<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
|
|
799
967
|
readonly blueprint: ValidWidgetSystemBlueprint<Plugins>;
|
|
@@ -807,12 +975,35 @@ interface WidgetSystemRuntime<Plugins extends AnyWidgetPluginTuple = AnyWidgetPl
|
|
|
807
975
|
* through ordinary invalidation.
|
|
808
976
|
*/
|
|
809
977
|
resetState: () => void;
|
|
978
|
+
/**
|
|
979
|
+
* The current value of every State member, keyed by widget id and then member key, in exactly the
|
|
980
|
+
* shape `overrideStateDefaults` accepts: `blueprint.createRuntime({ overrideStateDefaults:
|
|
981
|
+
* runtime.snapshotState() })` reproduces every non-null value. Members whose value is `null` are
|
|
982
|
+
* omitted, and so are widgets left with no entry. Returns a fresh plain object owned by the caller;
|
|
983
|
+
* the values themselves are passed by reference, not cloned.
|
|
984
|
+
*/
|
|
985
|
+
snapshotState: () => Record<WidgetId, Record<WidgetMemberKey, unknown>>;
|
|
810
986
|
/**
|
|
811
987
|
* Runtime-level diagnostics plus the current state/property/method diagnostic snapshots, in deterministic
|
|
812
988
|
* order. Never history, and never activates property evaluation.
|
|
813
989
|
*/
|
|
814
|
-
getDiagnostics: () => readonly
|
|
815
|
-
subscribeDiagnostics: (listener: (diagnostics: readonly
|
|
990
|
+
getDiagnostics: () => readonly RuntimeDiagnostic[];
|
|
991
|
+
subscribeDiagnostics: (listener: (diagnostics: readonly RuntimeDiagnostic[]) => void) => () => void;
|
|
992
|
+
/**
|
|
993
|
+
* Registers a listener that runs exactly once, synchronously, inside the first `dispose()` call, with no
|
|
994
|
+
* arguments — for a host to cancel the asynchronous work it owns. By then the Runtime is already fully
|
|
995
|
+
* disposed: `isDisposed` is `true`, every Runtime-owned subscription is torn down, a live operation throws
|
|
996
|
+
* `WidgetSystemRuntimeDisposedError`, `dispose()` is a no-op, and `blueprint` and a widget's `id`,
|
|
997
|
+
* `type` and `blueprintNode` stay readable. Listeners run in subscription order, like Event listeners from
|
|
998
|
+
* a list fixed when delivery starts: one removed meanwhile still runs, and none can be added meanwhile,
|
|
999
|
+
* because subscribing to a disposed Runtime throws `WidgetSystemRuntimeDisposedError`, as it does after
|
|
1000
|
+
* disposal in general (the listener is never invoked immediately). A throwing listener never reaches the
|
|
1001
|
+
* `dispose()` caller or stops the remaining listeners; it is reported asynchronously like any other
|
|
1002
|
+
* isolated listener exception. Registering the same function twice makes two independent registrations.
|
|
1003
|
+
* The returned unsubscribe function is idempotent and safe to call before or after disposal; once the
|
|
1004
|
+
* listener has run it does nothing, and the Runtime keeps no reference to the listener.
|
|
1005
|
+
*/
|
|
1006
|
+
subscribeDisposal: (listener: () => void) => () => void;
|
|
816
1007
|
dispose: () => void;
|
|
817
1008
|
}
|
|
818
1009
|
//#endregion
|
|
@@ -823,14 +1014,23 @@ interface DiagnosticBase<Code extends string = string, Location = unknown> {
|
|
|
823
1014
|
readonly location: Location;
|
|
824
1015
|
readonly message: string;
|
|
825
1016
|
}
|
|
826
|
-
/** General structural diagnostic shape for code which does not need a narrower union. */
|
|
827
|
-
type Diagnostic<Code extends string = string, Location = unknown> = DiagnosticBase<Code, Location>;
|
|
828
1017
|
declare const EMPTY_DIAGNOSTICS: readonly never[];
|
|
829
1018
|
declare class WidgetSystemRuntimeDisposedError extends Error {
|
|
830
1019
|
readonly name = "WidgetSystemRuntimeDisposedError";
|
|
831
1020
|
readonly code: "runtime-disposed";
|
|
832
1021
|
constructor(message?: string);
|
|
833
1022
|
}
|
|
1023
|
+
/**
|
|
1024
|
+
* Thrown when one Runtime's event emits nest deeper than its re-entrancy limit: an event listener keeps
|
|
1025
|
+
* re-invoking a Method that emits again. A non-semantic safety guard against runaway re-entrancy (a
|
|
1026
|
+
* `RangeError`, like any other runaway recursion), never a Diagnostic. Event-listener isolation does not
|
|
1027
|
+
* swallow it, so it unwinds every nested emit to the operation that started the loop.
|
|
1028
|
+
*/
|
|
1029
|
+
declare class WidgetSystemRuntimeReentrancyError extends RangeError {
|
|
1030
|
+
readonly name = "WidgetSystemRuntimeReentrancyError";
|
|
1031
|
+
readonly code: "emit-depth-exceeded";
|
|
1032
|
+
constructor(message?: string);
|
|
1033
|
+
}
|
|
834
1034
|
interface RelativeValueDiagnosticInput {
|
|
835
1035
|
readonly message: string;
|
|
836
1036
|
readonly path?: DiagnosticPath;
|
|
@@ -941,7 +1141,9 @@ type BlueprintDependencyOperation = BlueprintDependencyReference['operation'];
|
|
|
941
1141
|
type BlueprintDiagnosticRelated<Plugins extends AnyWidgetPluginTuple> = NonEmptyReadonlyArray<BlueprintNodeDiagnosticLocation<Plugins>>;
|
|
942
1142
|
type BlueprintDefinitionDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> = DiagnosticBase<'invalid-widget-definition', BlueprintWidgetDiagnosticLocation<Plugins>> | (DiagnosticBase<'invalid-widget-id', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
943
1143
|
readonly path: DiagnosticPath;
|
|
944
|
-
|
|
1144
|
+
}) | (DiagnosticBase<'duplicate-widget-id', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
1145
|
+
readonly path: DiagnosticPath;
|
|
1146
|
+
readonly related: BlueprintDiagnosticRelated<Plugins>;
|
|
945
1147
|
}) | (DiagnosticBase<'invalid-widget-type', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
946
1148
|
readonly path: DiagnosticPath;
|
|
947
1149
|
}) | (DiagnosticBase<'unknown-widget-type', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
@@ -956,6 +1158,8 @@ type BlueprintDefinitionDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWid
|
|
|
956
1158
|
readonly path: DiagnosticPath;
|
|
957
1159
|
}) | (DiagnosticBase<'invalid-widget-slot', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
958
1160
|
readonly path: DiagnosticPath;
|
|
1161
|
+
}) | (DiagnosticBase<'unexpected-widget-field', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
1162
|
+
readonly path: DiagnosticPath;
|
|
959
1163
|
});
|
|
960
1164
|
type BlueprintConfigDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> = DiagnosticBase<'invalid-widget-config', BlueprintWidgetDiagnosticLocation<Plugins>> & {
|
|
961
1165
|
readonly path?: DiagnosticPath;
|
|
@@ -971,13 +1175,14 @@ type BlueprintDependencyDiagnostic<Plugins extends AnyWidgetPluginTuple = AnyWid
|
|
|
971
1175
|
}) | (DiagnosticBase<'ambiguous-dependency-target', BlueprintDependencyDiagnosticLocation<Plugins>> & {
|
|
972
1176
|
readonly dependency: BlueprintDependencyReference;
|
|
973
1177
|
readonly related: NonEmptyReadonlyArray<BlueprintDependencyDiagnosticLocation<Plugins>>;
|
|
974
|
-
}) | (DiagnosticBase<'property-dependency-has-
|
|
1178
|
+
}) | (DiagnosticBase<'property-dependency-has-side-effects', BlueprintDependencyDiagnosticLocation<Plugins>> & {
|
|
975
1179
|
readonly dependency: BlueprintDependencyReference;
|
|
976
1180
|
readonly related: NonEmptyReadonlyArray<BlueprintDependencyDiagnosticLocation<Plugins>>;
|
|
977
1181
|
}) | (DiagnosticBase<'property-evaluation-cycle', BlueprintDependencyDiagnosticLocation<Plugins>> & {
|
|
978
|
-
|
|
1182
|
+
/** Every member of the cycle, the subject included, in member order; one array shared by all diagnostics of the cycle. */
|
|
1183
|
+
readonly related: NonEmptyReadonlyArray<BlueprintDependencyDiagnosticLocation<Plugins>>;
|
|
979
1184
|
});
|
|
980
|
-
type JsonCompatibilityReason = 'undefined' | 'non-finite-number' | 'bigint' | 'symbol' | 'function' | 'unsupported-object-prototype' | 'symbol-key' | 'accessor-property' | 'sparse-array' | 'array-extra-property' | 'cyclic-reference';
|
|
1185
|
+
type JsonCompatibilityReason = 'undefined' | 'non-finite-number' | 'bigint' | 'symbol' | 'function' | 'unsupported-object-prototype' | 'symbol-key' | 'accessor-property' | 'sparse-array' | 'array-extra-property' | 'cyclic-reference' | 'max-depth-exceeded';
|
|
981
1186
|
type JsonCompatibilityDiagnostic = DiagnosticBase<'json-incompatible-value', BlueprintSourceDiagnosticLocation> & {
|
|
982
1187
|
readonly path: DiagnosticPath;
|
|
983
1188
|
readonly reason: JsonCompatibilityReason;
|
|
@@ -1004,7 +1209,7 @@ type RuntimePrimitiveDiagnosticLocation = {
|
|
|
1004
1209
|
interface RuntimeLevelDiagnosticLocation {
|
|
1005
1210
|
readonly type: 'runtime';
|
|
1006
1211
|
}
|
|
1007
|
-
type RuntimeDiagnosticLocation = RuntimePrimitiveDiagnosticLocation;
|
|
1212
|
+
type RuntimeDiagnosticLocation = RuntimePrimitiveDiagnosticLocation | RuntimeLevelDiagnosticLocation;
|
|
1008
1213
|
type RuntimeStateDiagnostic = DiagnosticBase<'invalid-state-value', Extract<RuntimePrimitiveDiagnosticLocation, {
|
|
1009
1214
|
type: 'state';
|
|
1010
1215
|
}>> & {
|
|
@@ -1036,7 +1241,7 @@ type RuntimeMethodResultDiagnostic = DiagnosticBase<'invalid-method-result', Ext
|
|
|
1036
1241
|
type RuntimeDependencyTargetFailedDiagnostic = DiagnosticBase<'dependency-target-failed', RuntimePrimitiveDiagnosticLocation> & {
|
|
1037
1242
|
readonly dependency: BlueprintDependencyReference;
|
|
1038
1243
|
readonly related: NonEmptyReadonlyArray<RuntimePrimitiveDiagnosticLocation>;
|
|
1039
|
-
readonly cause:
|
|
1244
|
+
readonly cause: RuntimeWidgetDiagnostic;
|
|
1040
1245
|
};
|
|
1041
1246
|
type RuntimeDependencyValueRejectedDiagnostic = DiagnosticBase<'dependency-value-rejected', RuntimePrimitiveDiagnosticLocation> & {
|
|
1042
1247
|
readonly dependency: BlueprintDependencyReference;
|
|
@@ -1055,7 +1260,6 @@ type RuntimeMethodDependencyDiagnostic = (RuntimeDependencyTargetFailedDiagnosti
|
|
|
1055
1260
|
};
|
|
1056
1261
|
type RuntimePropertyDiagnostic = RuntimePropertyResultDiagnostic | RuntimePropertyDependencyDiagnostic;
|
|
1057
1262
|
type RuntimeMethodDiagnostic = RuntimeMethodArgsDiagnostic | RuntimeMethodResultDiagnostic | RuntimeMethodDependencyDiagnostic;
|
|
1058
|
-
type RuntimeDiagnostic = RuntimeStateDiagnostic | RuntimePropertyDiagnostic | RuntimeMethodDiagnostic;
|
|
1059
1263
|
type RuntimeLevelDiagnostic = (DiagnosticBase<'invalid-state-overrides', RuntimeLevelDiagnosticLocation> & {
|
|
1060
1264
|
readonly path?: DiagnosticPath;
|
|
1061
1265
|
readonly reason?: string;
|
|
@@ -1073,7 +1277,7 @@ type RuntimeLevelDiagnostic = (DiagnosticBase<'invalid-state-overrides', Runtime
|
|
|
1073
1277
|
readonly reason?: string;
|
|
1074
1278
|
});
|
|
1075
1279
|
type RuntimeWidgetDiagnostic = RuntimeStateDiagnostic | RuntimePropertyDiagnostic | RuntimeMethodDiagnostic;
|
|
1076
|
-
type
|
|
1280
|
+
type RuntimeDiagnostic = RuntimeLevelDiagnostic | RuntimeWidgetDiagnostic;
|
|
1077
1281
|
//#endregion
|
|
1078
1282
|
//#region src/dep.d.ts
|
|
1079
1283
|
/**
|
|
@@ -1227,11 +1431,16 @@ type SelfStateDependencyOperations<Interfaces extends WidgetInterfaces, Consumer
|
|
|
1227
1431
|
} & (Consumer extends 'method' ? {
|
|
1228
1432
|
set: <Key extends WidgetStateKeyOf<Interfaces>>(key: Key) => StateSetDepExpression<WidgetStateValueOf<Interfaces, Key>, false>;
|
|
1229
1433
|
} : unknown);
|
|
1434
|
+
/**
|
|
1435
|
+
* A self Property read yields exactly what its `compute` returned: a self target is never absent, so no
|
|
1436
|
+
* `null` is added (unlike a State read, whose member may hold `null`).
|
|
1437
|
+
*/
|
|
1230
1438
|
interface SelfPropertyDependencyOperations<Interfaces extends WidgetInterfaces> {
|
|
1231
|
-
get: <Name extends WidgetPropertyKeyOf<Interfaces>>(name: Name) => PropertyGetDepExpression<WidgetPropertyValueOf<Interfaces, Name
|
|
1439
|
+
get: <Name extends WidgetPropertyKeyOf<Interfaces>>(name: Name) => PropertyGetDepExpression<WidgetPropertyValueOf<Interfaces, Name>, false>;
|
|
1232
1440
|
}
|
|
1441
|
+
/** A self Method invocation yields exactly what its `execute` returned; see {@link SelfPropertyDependencyOperations}. */
|
|
1233
1442
|
interface SelfMethodDependencyOperations<Interfaces extends WidgetInterfaces> {
|
|
1234
|
-
invoke: <Name extends WidgetMethodKeyOf<Interfaces>>(name: Name) => MethodInvokeDepExpression<WidgetMethodArgsOf<Interfaces, Name>, WidgetMethodReturnOf<Interfaces, Name
|
|
1443
|
+
invoke: <Name extends WidgetMethodKeyOf<Interfaces>>(name: Name) => MethodInvokeDepExpression<WidgetMethodArgsOf<Interfaces, Name>, WidgetMethodReturnOf<Interfaces, Name>, false>;
|
|
1235
1444
|
}
|
|
1236
1445
|
/**
|
|
1237
1446
|
* `self` target stage: guaranteed target, strongly typed, and capability-aware.
|
|
@@ -1260,4 +1469,4 @@ interface DependencyBuilder<Interfaces extends WidgetInterfaces, Consumer extend
|
|
|
1260
1469
|
widget: (widgetId: WidgetId) => OptionalizableDependencyTarget<Consumer>;
|
|
1261
1470
|
}
|
|
1262
1471
|
//#endregion
|
|
1263
|
-
export {
|
|
1472
|
+
export { RuntimeDiagnostic as $, WidgetStateValidateContext as $n, WidgetCatalog as $t, BlueprintNodeDiagnostic as A, WidgetPluginDonePhase as An, WidgetStateValueOf as Ar, ResolvedBlueprintWidgetNodeViewFor as At, DiagnosticBase as B, WidgetPluginValidateStructure as Bn, RuntimeWidgetFor as Bt, BlueprintDependencyDiagnosticLocation as C, WidgetMethodValidateArgsContext as Cn, WidgetPropertyKeyOf as Cr, BlueprintWidgetNodeBase as Ct, BlueprintDiagnostic as D, WidgetPluginConfigMetadata as Dn, WidgetSlotNameOf as Dr, ResolvedBlueprintWidgetNode as Dt, BlueprintDependencyTarget as E, WidgetPluginCapabilities as En, WidgetResolvedConfigOf as Er, InvalidWidgetSystemBlueprint as Et, BlueprintSourceDiagnostic as F, WidgetPluginPropertiesPhase as Fn, MAX_JSON_DEPTH as Fr, RuntimeProperty as Ft, JsonCompatibilityReason as G, WidgetRegisterDepsContext as Gn, WidgetLocation as Gt, DiagnosticPath as H, WidgetPropertiesSection as Hn, SelfBlueprintWidgetNodeView as Ht, BlueprintSourceDiagnosticLocation as I, WidgetPluginSlotsPhase as In, isJsonValue as Ir, RuntimePropertySurface as It, RelativeStructureDiagnosticLocation as J, WidgetSlotDefinitions as Jn, WidgetSourceFor as Jt, RelativePluginStructureDiagnosticInput as K, WidgetResolvedConfigContext as Kn, WidgetLocationView as Kt, BlueprintStructureDiagnostic as L, WidgetPluginStatePhase as Ln, RuntimeState as Lt, BlueprintPropertyDiagnosticLocation as M, WidgetPluginInterfacesPhase as Mn, JsonObject as Mr, RuntimeEventSurface as Mt, BlueprintSlotChildDiagnosticLocation as N, WidgetPluginMethodsPhase as Nn, JsonPrimitive as Nr, RuntimeMethod as Nt, BlueprintDiagnosticLocation as O, WidgetPluginConfigPhase as On, WidgetStateKeyOf as Or, ResolvedBlueprintWidgetNodeFor as Ot, BlueprintSlotDiagnosticLocation as P, WidgetPluginPhaseOrderViolation as Pn, JsonValue as Pr, RuntimeMethodSurface as Pt, RuntimeDependencyValueRejectedDiagnostic as Q, WidgetStateSection as Qn, CreateWidgetSystemOptions as Qt, BlueprintStructureDiagnosticLocation as R, WidgetPluginStructurePhase as Rn, RuntimeStateSurface as Rt, BlueprintDependencyDiagnostic as S, WidgetMethodExecuteContext as Sn, WidgetPropertiesOf as Sr, BlueprintWidgetNode as St, BlueprintDependencyReference as T, WidgetPlugin as Tn, WidgetRawConfigOf as Tr, CreateWidgetSystemRuntimeOptions as Tt, EMPTY_DIAGNOSTICS as U, WidgetPropertyComputeContext as Un, UnresolvedBlueprintWidgetNode as Ut, DiagnosticCollector as V, WidgetPluginValidateStructureContext as Vn, SelfBlueprintWidgetNode as Vt, JsonCompatibilityDiagnostic as W, WidgetPropertyDefinition as Wn, ValidWidgetSystemBlueprint as Wt, RelativeValueDiagnosticInput as X, WidgetStateDefaultContext as Xn, WidgetSystemBlueprintStatus as Xt, RelativeSystemStructureDiagnosticInput as Y, WidgetSlotValidateStructureContext as Yn, WidgetSystemBlueprint as Yt, RuntimeDependencyTargetFailedDiagnostic as Z, WidgetStateMemberDefinition as Zn, WidgetSystemRuntime as Zt, ToExecutedDeps as _, WidgetEventsSection as _n, WidgetMethodArgsOf as _r, BlueprintNodeConfigFields as _t, MaybeOptional as a, WidgetSystemValidateStructure as an, HasWidgetCapability as ar, RuntimeMethodDiagnostic as at, BlueprintConfigDiagnostic as b, WidgetMethodDefinition as bn, WidgetMethodReturnOf as br, BlueprintSemanticSlotsView as bt, PropertyGetDepExpression as c, AnyWidgetPlugin as cn, WidgetEventArgsOf as cr, RuntimePropertyDependencyDiagnostic as ct, SelfMethodDependencyOperations as d, WidgetConfigDefinition as dn, WidgetId as dr, RuntimeStateDiagnostic as dt, WidgetCatalogEntry as en, WidgetValueContract as er, RuntimeDiagnosticLocation as et, SelfPropertyDependencyOperations as f, WidgetConfigJsonSchema as fn, WidgetInterfaces as fr, RuntimeWidgetDiagnostic as ft, ToExecutedDep as g, WidgetEventEmitterContext as gn, WidgetMemberValueOf as gr, BlueprintCompileView as gt, StateSetDepExpression as h, WidgetEventEmitter as hn, WidgetMemberKeysOf as hr, WidgetSystemRuntimeReentrancyError as ht, EmptyRegisteredDeps as i, WidgetSystemConfigurationErrorCode as in, ExecutionResult as ir, RuntimeMethodDependencyDiagnostic as it, BlueprintNodeDiagnosticLocation as j, WidgetPluginEventsPhase as jn, JsonArray as jr, RuntimeEvent as jt, BlueprintMethodDiagnosticLocation as k, WidgetPluginDescriptionPhase as kn, WidgetStateOf as kr, ResolvedBlueprintWidgetNodeView as kt, RegisteredDeps as l, AnyWidgetPluginTuple as ln, WidgetEventKeyOf as lr, RuntimePropertyDiagnostic as lt, StateGetDepExpression as m, WidgetEventDefinition as mn, WidgetMemberKey as mr, WidgetSystemRuntimeDisposedError as mt, DependencyBuilder as n, WidgetSystem as nn, createWidgetValueContract as nr, RuntimeLevelDiagnosticLocation as nt, MethodInvokeDepExpression as o, WidgetSystemValidateStructureContext as on, NonEmptyReadonlyArray as or, RuntimeMethodResultDiagnostic as ot, SelfStateDependencyOperations as p, WidgetConfigValidateContext as pn, WidgetInterfacesViolationOf as pr, SourceAccessDiagnostic as pt, RelativeSlotStructureDiagnosticInput as q, WidgetSlotDefinition as qn, WidgetSource as qt, DependencyConsumer as r, WidgetSystemConfigurationError as rn, ExecutionFailure as rr, RuntimeMethodArgsDiagnostic as rt, OptionalizableDependencyTarget as s, createWidgetSystem as sn, WidgetCapabilityOf as sr, RuntimePrimitiveDiagnosticLocation as st, AnyDepExpression as t, WidgetPluginOf as tn, createWidgetPlugin as tr, RuntimeLevelDiagnostic as tt, SelfDependencyTarget as u, WIDGET_CONFIG_JSON_SCHEMA_DIALECT as un, WidgetEventsOf as ur, RuntimePropertyResultDiagnostic as ut, UnknownTargetDependencyOperations as v, WidgetInterfacesOf as vn, WidgetMethodKeyOf as vr, BlueprintRuntimeView as vt, BlueprintDependencyOperation as w, WidgetMethodsSection as wn, WidgetPropertyValueOf as wr, BlueprintWidgetNodeView as wt, BlueprintDefinitionDiagnostic as x, WidgetMethodEventEmitter as xn, WidgetMethodsOf as xr, BlueprintSourcePath as xt, UnknownTargetStateDependencyOperations as y, WidgetInterfacesViolation as yn, WidgetMethodOf as yr, BlueprintSemanticSlots as yt, BlueprintWidgetDiagnosticLocation as z, WidgetPluginTypeOf as zn, RuntimeWidget as zt };
|