@deviltea/widget-core 0.0.5 → 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 +250 -62
- package/dist/{dep-Cvv2QPKi.d.mts → dep-BXcdMm-M.d.mts} +309 -84
- package/dist/event-Bk-mkL1E.mjs +956 -0
- package/dist/index.d.mts +93 -12
- package/dist/index.mjs +1921 -659
- 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
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { Dn as WidgetPluginConfigMetadata, Dt as ResolvedBlueprintWidgetNode, En as WidgetPluginCapabilities, St as BlueprintWidgetNode, T as BlueprintDependencyReference, Ut as UnresolvedBlueprintWidgetNode, Yt as WidgetSystemBlueprint, Zt as WidgetSystemRuntime, cn as AnyWidgetPlugin, ir as ExecutionResult, ln as AnyWidgetPluginTuple, lt as RuntimePropertyDiagnostic, mr as WidgetMemberKey, xt as BlueprintSourcePath } from "../dep-BXcdMm-M.mjs";
|
|
2
2
|
//#region src/inspection/types.d.ts
|
|
3
3
|
declare const inspectionNodeIdBrand: unique symbol;
|
|
4
4
|
/**
|
|
@@ -26,7 +26,28 @@ interface PluginInspectionEventMember {
|
|
|
26
26
|
readonly name: WidgetMemberKey;
|
|
27
27
|
readonly description: string;
|
|
28
28
|
}
|
|
29
|
+
interface PluginInspectionSlot {
|
|
30
|
+
readonly type: 'slot';
|
|
31
|
+
readonly name: WidgetMemberKey;
|
|
32
|
+
readonly description: string;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Everything passive one completed plugin declares, in one call: a superset of its `system.catalog`
|
|
36
|
+
* entry (`type`, `description`, config metadata, slot descriptions) plus capability presence and the
|
|
37
|
+
* State/Property/Event member facts.
|
|
38
|
+
*/
|
|
29
39
|
interface PluginInspection {
|
|
40
|
+
readonly type: string;
|
|
41
|
+
readonly description: string;
|
|
42
|
+
/** Authoritative capability presence (absent vs explicitly declared empty); same facts as `plugin.capabilities`. */
|
|
43
|
+
readonly capabilities: WidgetPluginCapabilities;
|
|
44
|
+
/** Passive config authoring metadata. Null means no config capability. */
|
|
45
|
+
readonly config: WidgetPluginConfigMetadata | null;
|
|
46
|
+
/**
|
|
47
|
+
* Slot descriptions in declaration order. Null means the Slots capability was not declared; an empty
|
|
48
|
+
* map means explicitly declared empty.
|
|
49
|
+
*/
|
|
50
|
+
readonly slots: ReadonlyMap<WidgetMemberKey, PluginInspectionSlot> | null;
|
|
30
51
|
/** Null means the State capability was not declared; an empty map means explicitly declared empty. */
|
|
31
52
|
readonly state: ReadonlyMap<WidgetMemberKey, PluginInspectionStateMember> | null;
|
|
32
53
|
/** Null means the Properties capability was not declared; an empty map means explicitly declared empty. */
|
|
@@ -112,6 +133,8 @@ interface BlueprintInspectionMethodMember {
|
|
|
112
133
|
readonly name: WidgetMemberKey;
|
|
113
134
|
/** Compiler-authoritative transitive write-effect fact. */
|
|
114
135
|
readonly transitivelyWrites: boolean;
|
|
136
|
+
/** Compiler-authoritative transitive emit-effect fact: the Method declares an Event in `emits`, or invokes a Method that does. */
|
|
137
|
+
readonly transitivelyEmits: boolean;
|
|
115
138
|
readonly dependencies: readonly BlueprintInspectionDependency[];
|
|
116
139
|
}
|
|
117
140
|
interface BlueprintInspectionNodeBase<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> {
|
|
@@ -123,10 +146,19 @@ interface BlueprintInspectionNodeBase<Plugins extends AnyWidgetPluginTuple = Any
|
|
|
123
146
|
readonly node: BlueprintWidgetNode<Plugins>;
|
|
124
147
|
/** Best-effort recovered source topology (not a raw `slots` mirror). */
|
|
125
148
|
readonly sourceSlots: readonly BlueprintInspectionSourceSlot[];
|
|
149
|
+
/**
|
|
150
|
+
* The structured `SourcePath` of this node's authored object within `blueprint.source`, computed by the
|
|
151
|
+
* compiler; identical to `blueprint.getSourcePath(node)`.
|
|
152
|
+
*/
|
|
153
|
+
readonly sourcePath: BlueprintSourcePath;
|
|
126
154
|
}
|
|
127
155
|
interface UnresolvedBlueprintInspectionNode<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> extends BlueprintInspectionNodeBase<Plugins> {
|
|
128
156
|
readonly resolved: false;
|
|
129
157
|
readonly node: UnresolvedBlueprintWidgetNode<Plugins>;
|
|
158
|
+
/** Best-effort identity hint: the authored `id` when it is a string, else `null`. */
|
|
159
|
+
readonly id: string | null;
|
|
160
|
+
/** Best-effort identity hint: the authored `type` when it is a string, else `null`. */
|
|
161
|
+
readonly type: string | null;
|
|
130
162
|
}
|
|
131
163
|
interface ResolvedBlueprintInspectionNode<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple> extends BlueprintInspectionNodeBase<Plugins> {
|
|
132
164
|
readonly resolved: true;
|
|
@@ -180,7 +212,7 @@ type RuntimePropertyInspectionSnapshot<T> = {
|
|
|
180
212
|
readonly status: 'never-evaluated';
|
|
181
213
|
} | {
|
|
182
214
|
readonly status: 'completed';
|
|
183
|
-
readonly result: ExecutionResult<T
|
|
215
|
+
readonly result: ExecutionResult<T, RuntimePropertyDiagnostic>;
|
|
184
216
|
};
|
|
185
217
|
interface RuntimePropertyInspection<T> extends InspectionObservable<RuntimePropertyInspectionSnapshot<T>> {}
|
|
186
218
|
/**
|
|
@@ -264,4 +296,4 @@ declare function inspectPlugin(plugin: AnyWidgetPlugin): PluginInspection;
|
|
|
264
296
|
*/
|
|
265
297
|
declare function inspectRuntime<Plugins extends AnyWidgetPluginTuple = AnyWidgetPluginTuple>(runtime: WidgetSystemRuntime<Plugins>): RuntimeInspection<Plugins>;
|
|
266
298
|
//#endregion
|
|
267
|
-
export { type AbsentBlueprintInspectionDependency, type BlueprintInspection, type BlueprintInspectionCapabilities, type BlueprintInspectionDependency, type BlueprintInspectionDependencyBase, type BlueprintInspectionEvaluationMemberRef, type BlueprintInspectionEventMember, type BlueprintInspectionInvalidCycle, type BlueprintInspectionMemberRef, type BlueprintInspectionMethodMember, type BlueprintInspectionNode, type BlueprintInspectionNodeBase, type BlueprintInspectionPropertyMember, type BlueprintInspectionSemanticSlot, type BlueprintInspectionSourceSlot, type BlueprintInspectionStateMember, type InspectionNodeId, type InspectionObservable, type InvalidBlueprintInspectionDependency, type PluginInspection, type PluginInspectionEventMember, type PluginInspectionPropertyMember, type PluginInspectionStateMember, type ResolvedBlueprintInspectionDependency, type ResolvedBlueprintInspectionNode, type RuntimeEventInspection, type RuntimeInspection, type RuntimePropertyInspection, type RuntimePropertyInspectionSnapshot, type RuntimeStateInspection, type RuntimeStateInspectionSnapshot, type RuntimeWidgetInspection, type UnresolvedBlueprintInspectionNode, WidgetInspectionError, type WidgetInspectionErrorCode, inspectBlueprint, inspectPlugin, inspectRuntime };
|
|
299
|
+
export { type AbsentBlueprintInspectionDependency, type BlueprintInspection, type BlueprintInspectionCapabilities, type BlueprintInspectionDependency, type BlueprintInspectionDependencyBase, type BlueprintInspectionEvaluationMemberRef, type BlueprintInspectionEventMember, type BlueprintInspectionInvalidCycle, type BlueprintInspectionMemberRef, type BlueprintInspectionMethodMember, type BlueprintInspectionNode, type BlueprintInspectionNodeBase, type BlueprintInspectionPropertyMember, type BlueprintInspectionSemanticSlot, type BlueprintInspectionSourceSlot, type BlueprintInspectionStateMember, type InspectionNodeId, type InspectionObservable, type InvalidBlueprintInspectionDependency, type PluginInspection, type PluginInspectionEventMember, type PluginInspectionPropertyMember, type PluginInspectionSlot, type PluginInspectionStateMember, type ResolvedBlueprintInspectionDependency, type ResolvedBlueprintInspectionNode, type RuntimeEventInspection, type RuntimeInspection, type RuntimePropertyInspection, type RuntimePropertyInspectionSnapshot, type RuntimeStateInspection, type RuntimeStateInspectionSnapshot, type RuntimeWidgetInspection, type UnresolvedBlueprintInspectionNode, WidgetInspectionError, type WidgetInspectionErrorCode, inspectBlueprint, inspectPlugin, inspectRuntime };
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { c as readWidgetPluginDefinition, l as createReadonlyMap, n as readRuntimeInternals, s as isCoreWidgetPlugin, t as isCoreRuntime } from "../internals-
|
|
1
|
+
import { c as readWidgetPluginDefinition, l as createReadonlyMap, n as readRuntimeInternals, s as isCoreWidgetPlugin, t as isCoreRuntime } from "../internals-CVKUQDIN.mjs";
|
|
2
2
|
import { a as readCompiledBlueprint, i as isCoreBlueprint, r as isCompiledDependency } from "../contract-CRpMqCY2.mjs";
|
|
3
3
|
//#region src/inspection/errors.ts
|
|
4
4
|
/**
|
|
@@ -145,6 +145,7 @@ function buildMethodMembers(compiledNode) {
|
|
|
145
145
|
type: "method",
|
|
146
146
|
name,
|
|
147
147
|
transitivelyWrites: member.transitivelyWrites,
|
|
148
|
+
transitivelyEmits: member.transitivelyEmits,
|
|
148
149
|
dependencies: flattenDependencies(member.deps)
|
|
149
150
|
}));
|
|
150
151
|
return Object.freeze(result);
|
|
@@ -166,12 +167,16 @@ function buildNode(compiledNode, nodeId) {
|
|
|
166
167
|
nodeId,
|
|
167
168
|
node: compiledNode.publicNode,
|
|
168
169
|
sourceSlots,
|
|
169
|
-
|
|
170
|
+
sourcePath: compiledNode.sourcePath,
|
|
171
|
+
resolved: false,
|
|
172
|
+
id: compiledNode.id,
|
|
173
|
+
type: compiledNode.type
|
|
170
174
|
});
|
|
171
175
|
return Object.freeze({
|
|
172
176
|
nodeId,
|
|
173
177
|
node: compiledNode.publicNode,
|
|
174
178
|
sourceSlots,
|
|
179
|
+
sourcePath: compiledNode.sourcePath,
|
|
175
180
|
resolved: true,
|
|
176
181
|
capabilities: buildCapabilities(compiledNode),
|
|
177
182
|
config: compiledNode.plugin.config,
|
|
@@ -241,6 +246,17 @@ function inspectBlueprint(blueprint) {
|
|
|
241
246
|
//#endregion
|
|
242
247
|
//#region src/inspection/plugin.ts
|
|
243
248
|
const inspectionCache = /* @__PURE__ */ new WeakMap();
|
|
249
|
+
function buildSlots(plugin) {
|
|
250
|
+
const definitions = readWidgetPluginDefinition(plugin).slots;
|
|
251
|
+
if (definitions === null) return null;
|
|
252
|
+
const slots = [];
|
|
253
|
+
for (const [name, definition] of definitions) slots.push([name, Object.freeze({
|
|
254
|
+
type: "slot",
|
|
255
|
+
name,
|
|
256
|
+
description: definition.description
|
|
257
|
+
})]);
|
|
258
|
+
return createReadonlyMap(slots);
|
|
259
|
+
}
|
|
244
260
|
function buildStateMembers(plugin) {
|
|
245
261
|
const definitions = readWidgetPluginDefinition(plugin).state;
|
|
246
262
|
if (definitions === null) return null;
|
|
@@ -282,6 +298,11 @@ function inspectPlugin(plugin) {
|
|
|
282
298
|
const existing = inspectionCache.get(plugin);
|
|
283
299
|
if (existing !== void 0) return existing;
|
|
284
300
|
const inspection = Object.freeze({
|
|
301
|
+
type: plugin.type,
|
|
302
|
+
description: plugin.description,
|
|
303
|
+
capabilities: plugin.capabilities,
|
|
304
|
+
config: plugin.config,
|
|
305
|
+
slots: buildSlots(plugin),
|
|
285
306
|
state: buildStateMembers(plugin),
|
|
286
307
|
properties: buildPropertyMembers(plugin),
|
|
287
308
|
events: buildEventMembers(plugin)
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { Zt as WidgetSystemRuntime, ln as AnyWidgetPluginTuple, mr as WidgetMemberKey, zt as RuntimeWidget } from "../dep-BXcdMm-M.mjs";
|
|
2
2
|
//#region src/integration/index.d.ts
|
|
3
3
|
type WidgetIntegrationErrorCode = 'runtime-widget-mismatch' | 'foreign-runtime';
|
|
4
4
|
declare class WidgetIntegrationError extends Error {
|
|
@@ -6,7 +6,13 @@ declare class WidgetIntegrationError extends Error {
|
|
|
6
6
|
readonly name = "WidgetIntegrationError";
|
|
7
7
|
constructor(code: WidgetIntegrationErrorCode, message?: string);
|
|
8
8
|
}
|
|
9
|
+
/**
|
|
10
|
+
* Passive provenance assertion: throws `WidgetIntegrationError('foreign-runtime')` unless `runtime` was
|
|
11
|
+
* produced by this loaded core instance. It reads no Runtime state and acquires no emit authority, so a
|
|
12
|
+
* renderer adapter can verify at mount that the app and the adapter share one core copy.
|
|
13
|
+
*/
|
|
14
|
+
declare function assertCoreRuntime(runtime: unknown): void;
|
|
9
15
|
type WidgetIntegrationEventEmitter = Readonly<Record<WidgetMemberKey, (...args: readonly unknown[]) => void>>;
|
|
10
16
|
declare function getWidgetEventEmitter<Plugins extends AnyWidgetPluginTuple>(runtime: WidgetSystemRuntime<Plugins>, widget: RuntimeWidget<Plugins>): WidgetIntegrationEventEmitter | null;
|
|
11
17
|
//#endregion
|
|
12
|
-
export { WidgetIntegrationError, WidgetIntegrationErrorCode, WidgetIntegrationEventEmitter, getWidgetEventEmitter };
|
|
18
|
+
export { WidgetIntegrationError, WidgetIntegrationErrorCode, WidgetIntegrationEventEmitter, assertCoreRuntime, getWidgetEventEmitter };
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { t as buildEventEmitter } from "../event-
|
|
2
|
-
import { c as readWidgetPluginDefinition, n as readRuntimeInternals, t as isCoreRuntime } from "../internals-
|
|
1
|
+
import { t as buildEventEmitter } from "../event-Bk-mkL1E.mjs";
|
|
2
|
+
import { c as readWidgetPluginDefinition, n as readRuntimeInternals, t as isCoreRuntime } from "../internals-CVKUQDIN.mjs";
|
|
3
3
|
//#region src/integration/index.ts
|
|
4
4
|
var WidgetIntegrationError = class extends Error {
|
|
5
5
|
code;
|
|
@@ -9,6 +9,14 @@ var WidgetIntegrationError = class extends Error {
|
|
|
9
9
|
this.code = code;
|
|
10
10
|
}
|
|
11
11
|
};
|
|
12
|
+
/**
|
|
13
|
+
* Passive provenance assertion: throws `WidgetIntegrationError('foreign-runtime')` unless `runtime` was
|
|
14
|
+
* produced by this loaded core instance. It reads no Runtime state and acquires no emit authority, so a
|
|
15
|
+
* renderer adapter can verify at mount that the app and the adapter share one core copy.
|
|
16
|
+
*/
|
|
17
|
+
function assertCoreRuntime(runtime) {
|
|
18
|
+
if (!isCoreRuntime(runtime)) throw new WidgetIntegrationError("foreign-runtime");
|
|
19
|
+
}
|
|
12
20
|
function getWidgetEventEmitter(runtime, widget) {
|
|
13
21
|
if (!isCoreRuntime(runtime)) throw new WidgetIntegrationError("foreign-runtime");
|
|
14
22
|
const internals = readRuntimeInternals(runtime);
|
|
@@ -23,4 +31,4 @@ function getWidgetEventEmitter(runtime, widget) {
|
|
|
23
31
|
return buildEventEmitter(entry.events);
|
|
24
32
|
}
|
|
25
33
|
//#endregion
|
|
26
|
-
export { WidgetIntegrationError, getWidgetEventEmitter };
|
|
34
|
+
export { WidgetIntegrationError, assertCoreRuntime, getWidgetEventEmitter };
|
|
@@ -0,0 +1,388 @@
|
|
|
1
|
+
//#region src/readonly-map.ts
|
|
2
|
+
/** Creates a map-shaped, runtime immutable projection without exposing mutating Map methods. */
|
|
3
|
+
function createReadonlyMap(entries) {
|
|
4
|
+
const map = new Map(entries);
|
|
5
|
+
const result = {
|
|
6
|
+
get size() {
|
|
7
|
+
return map.size;
|
|
8
|
+
},
|
|
9
|
+
get(key) {
|
|
10
|
+
return map.get(key);
|
|
11
|
+
},
|
|
12
|
+
has(key) {
|
|
13
|
+
return map.has(key);
|
|
14
|
+
},
|
|
15
|
+
keys() {
|
|
16
|
+
return map.keys();
|
|
17
|
+
},
|
|
18
|
+
values() {
|
|
19
|
+
return map.values();
|
|
20
|
+
},
|
|
21
|
+
entries() {
|
|
22
|
+
return map.entries();
|
|
23
|
+
},
|
|
24
|
+
forEach(callbackfn, thisArg) {
|
|
25
|
+
map.forEach((value, key) => callbackfn.call(thisArg, value, key, result));
|
|
26
|
+
},
|
|
27
|
+
[Symbol.iterator]() {
|
|
28
|
+
return map[Symbol.iterator]();
|
|
29
|
+
}
|
|
30
|
+
};
|
|
31
|
+
return Object.freeze(result);
|
|
32
|
+
}
|
|
33
|
+
//#endregion
|
|
34
|
+
//#region src/plugin.ts
|
|
35
|
+
/**
|
|
36
|
+
* Framework-private brand carrying the plugin's phantom interfaces and its erased definition record.
|
|
37
|
+
*/
|
|
38
|
+
const widgetPluginBrand = Symbol("@deviltea/widget-core:widget-plugin");
|
|
39
|
+
/**
|
|
40
|
+
* Declares a stable semantic value-contract id while retaining the associated TypeScript value type for
|
|
41
|
+
* Plugin-author checking. Core does not interpret, register, validate, or schema-check contract ids.
|
|
42
|
+
*/
|
|
43
|
+
function createWidgetValueContract(id) {
|
|
44
|
+
return Object.freeze({ id });
|
|
45
|
+
}
|
|
46
|
+
const WIDGET_CONFIG_JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
|
|
47
|
+
/**
|
|
48
|
+
* Provenance probe: true only for plugins completed by this loaded module instance. A plugin from
|
|
49
|
+
* another module instance (its brand is a different Symbol) or a structural look-alike is foreign.
|
|
50
|
+
* Capability separation, not a security sandbox.
|
|
51
|
+
*/
|
|
52
|
+
function isCoreWidgetPlugin(value) {
|
|
53
|
+
if (typeof value !== "object" || value === null) return false;
|
|
54
|
+
const brand = value[widgetPluginBrand];
|
|
55
|
+
return typeof brand === "object" && brand !== null && typeof brand.definition === "object" && brand.definition !== null;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Reads the erased definition record of a plugin.
|
|
59
|
+
*/
|
|
60
|
+
function readWidgetPluginDefinition(plugin) {
|
|
61
|
+
return plugin[widgetPluginBrand].definition;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* The callbacks and description fields each section's definition type requires, plus its optional
|
|
65
|
+
* fields. Untyped (JavaScript / dynamically loaded) plugins are checked against these at registration,
|
|
66
|
+
* so a malformed plugin fails before `done()` returns instead of at its first interaction.
|
|
67
|
+
*/
|
|
68
|
+
const definitionFieldRules = {
|
|
69
|
+
config: [
|
|
70
|
+
[
|
|
71
|
+
"description",
|
|
72
|
+
"string",
|
|
73
|
+
true
|
|
74
|
+
],
|
|
75
|
+
[
|
|
76
|
+
"validate",
|
|
77
|
+
"function",
|
|
78
|
+
true
|
|
79
|
+
],
|
|
80
|
+
[
|
|
81
|
+
"resolve",
|
|
82
|
+
"function",
|
|
83
|
+
true
|
|
84
|
+
],
|
|
85
|
+
[
|
|
86
|
+
"schema",
|
|
87
|
+
"schema",
|
|
88
|
+
false
|
|
89
|
+
]
|
|
90
|
+
],
|
|
91
|
+
slots: [[
|
|
92
|
+
"description",
|
|
93
|
+
"string",
|
|
94
|
+
true
|
|
95
|
+
], [
|
|
96
|
+
"validateStructure",
|
|
97
|
+
"function",
|
|
98
|
+
false
|
|
99
|
+
]],
|
|
100
|
+
state: [
|
|
101
|
+
[
|
|
102
|
+
"validate",
|
|
103
|
+
"function",
|
|
104
|
+
true
|
|
105
|
+
],
|
|
106
|
+
[
|
|
107
|
+
"default",
|
|
108
|
+
"function",
|
|
109
|
+
false
|
|
110
|
+
],
|
|
111
|
+
[
|
|
112
|
+
"authorWritable",
|
|
113
|
+
"boolean",
|
|
114
|
+
false
|
|
115
|
+
]
|
|
116
|
+
],
|
|
117
|
+
properties: [
|
|
118
|
+
[
|
|
119
|
+
"compute",
|
|
120
|
+
"function",
|
|
121
|
+
true
|
|
122
|
+
],
|
|
123
|
+
[
|
|
124
|
+
"registerDeps",
|
|
125
|
+
"function",
|
|
126
|
+
false
|
|
127
|
+
],
|
|
128
|
+
[
|
|
129
|
+
"valueContract",
|
|
130
|
+
"value-contract",
|
|
131
|
+
false
|
|
132
|
+
]
|
|
133
|
+
],
|
|
134
|
+
methods: [
|
|
135
|
+
[
|
|
136
|
+
"validateArgs",
|
|
137
|
+
"function",
|
|
138
|
+
true
|
|
139
|
+
],
|
|
140
|
+
[
|
|
141
|
+
"execute",
|
|
142
|
+
"function",
|
|
143
|
+
true
|
|
144
|
+
],
|
|
145
|
+
[
|
|
146
|
+
"registerDeps",
|
|
147
|
+
"function",
|
|
148
|
+
false
|
|
149
|
+
]
|
|
150
|
+
],
|
|
151
|
+
events: [[
|
|
152
|
+
"description",
|
|
153
|
+
"string",
|
|
154
|
+
true
|
|
155
|
+
]]
|
|
156
|
+
};
|
|
157
|
+
const fieldKindExpectations = {
|
|
158
|
+
"function": "a function",
|
|
159
|
+
"string": "a string",
|
|
160
|
+
"boolean": "a boolean",
|
|
161
|
+
"schema": "a JSON Schema (a boolean or an object)",
|
|
162
|
+
"value-contract": "a value contract created by createWidgetValueContract()"
|
|
163
|
+
};
|
|
164
|
+
/** A dense array of strings (a hole or a non-string entry is not a name). */
|
|
165
|
+
function isNameArray(value) {
|
|
166
|
+
if (!Array.isArray(value)) return false;
|
|
167
|
+
for (let index = 0; index < value.length; index++) if (!(index in value) || typeof value[index] !== "string") return false;
|
|
168
|
+
return true;
|
|
169
|
+
}
|
|
170
|
+
function matchesFieldKind(value, kind) {
|
|
171
|
+
switch (kind) {
|
|
172
|
+
case "function": return typeof value === "function";
|
|
173
|
+
case "string": return typeof value === "string";
|
|
174
|
+
case "boolean": return typeof value === "boolean";
|
|
175
|
+
case "schema": return value === null || typeof value === "boolean" || typeof value === "object" && !Array.isArray(value);
|
|
176
|
+
case "value-contract": return typeof value === "object" && value !== null && typeof value.id === "string";
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
function describeValue(value) {
|
|
180
|
+
return value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
|
|
181
|
+
}
|
|
182
|
+
function memberSubject(section, key) {
|
|
183
|
+
return `member "${key}" of section "${section}"`;
|
|
184
|
+
}
|
|
185
|
+
/** Plugin contract violations throw uncoded `TypeError`s. */
|
|
186
|
+
function pluginContractViolation(pluginType, subject, problem) {
|
|
187
|
+
return /* @__PURE__ */ new TypeError(`Widget plugin "${pluginType}": ${subject} ${problem}. This is a plugin implementation bug.`);
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Captures one definition by value (shallow copy, frozen), the same way for config, slots and members,
|
|
191
|
+
* after checking that it is an object carrying the fields its section requires. Optional fields are
|
|
192
|
+
* type-checked only when present (not `undefined`).
|
|
193
|
+
*/
|
|
194
|
+
function captureDefinition(pluginType, section, subject, definition) {
|
|
195
|
+
if (typeof definition !== "object" || definition === null) throw pluginContractViolation(pluginType, subject, `must be declared with a definition object, got ${describeValue(definition)}`);
|
|
196
|
+
const captured = Object.freeze({ ...definition });
|
|
197
|
+
for (const [field, kind, required] of definitionFieldRules[section]) {
|
|
198
|
+
const value = captured[field];
|
|
199
|
+
if (value === void 0) {
|
|
200
|
+
if (required) throw pluginContractViolation(pluginType, subject, `is missing the required "${field}" field (expected ${fieldKindExpectations[kind]})`);
|
|
201
|
+
continue;
|
|
202
|
+
}
|
|
203
|
+
if (!matchesFieldKind(value, kind)) throw pluginContractViolation(pluginType, subject, `has an invalid "${field}" field (expected ${fieldKindExpectations[kind]}, got ${describeValue(value)})`);
|
|
204
|
+
}
|
|
205
|
+
if (section === "methods") {
|
|
206
|
+
const emits = captured.emits;
|
|
207
|
+
if (emits !== void 0) {
|
|
208
|
+
if (!isNameArray(emits)) throw pluginContractViolation(pluginType, subject, `has an invalid "emits" field (expected an array of Event names, got ${describeValue(emits)})`);
|
|
209
|
+
return Object.freeze({
|
|
210
|
+
...captured,
|
|
211
|
+
emits: Object.freeze([...emits])
|
|
212
|
+
});
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
return captured;
|
|
216
|
+
}
|
|
217
|
+
/**
|
|
218
|
+
* Runs one section build callback against the section keyed-chain object, registering its members into
|
|
219
|
+
* `members` in declaration order.
|
|
220
|
+
*
|
|
221
|
+
* Declared member keys exist only at the type level, so every string member access resolves to a
|
|
222
|
+
* registrar; the returned chain object is the same object by identity. A registrar accepts only a
|
|
223
|
+
* definition object, which it validates and captures by value, so probing the section
|
|
224
|
+
* (`JSON.stringify`, string coercion, thenable detection) registers nothing. The section is sealed once
|
|
225
|
+
* the build callback returns or throws: a later registrar call (from a retained section) throws and
|
|
226
|
+
* changes nothing.
|
|
227
|
+
*/
|
|
228
|
+
function buildSection(pluginType, sectionName, members, build, onDeclaresEmits) {
|
|
229
|
+
let sealed = false;
|
|
230
|
+
const section = new Proxy({}, { get(_target, key) {
|
|
231
|
+
if (typeof key !== "string") return void 0;
|
|
232
|
+
return (definition) => {
|
|
233
|
+
const subject = memberSubject(sectionName, key);
|
|
234
|
+
if (sealed) throw pluginContractViolation(pluginType, subject, "was declared after the section's build callback returned");
|
|
235
|
+
const captured = captureDefinition(pluginType, sectionName, subject, definition);
|
|
236
|
+
members.set(key, captured);
|
|
237
|
+
if (onDeclaresEmits !== void 0 && captured.emits !== void 0) onDeclaresEmits(key);
|
|
238
|
+
return section;
|
|
239
|
+
};
|
|
240
|
+
} });
|
|
241
|
+
try {
|
|
242
|
+
build(section);
|
|
243
|
+
} finally {
|
|
244
|
+
sealed = true;
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
/**
|
|
248
|
+
* Starts the plugin builder for one plugin `type`.
|
|
249
|
+
*
|
|
250
|
+
* Phase order is `description -> interfaces -> config? -> slots? -> structure? -> state? -> properties? -> methods? -> events? -> done()`;
|
|
251
|
+
* a capability phase exists only when its capability is declared, while the optional `structure` phase
|
|
252
|
+
* (the plugin-level structure validator) is available to every plugin. Calling a phase out of order (or
|
|
253
|
+
* repeating it) fails type-checking with an order-specific diagnostic; the runtime builder itself is
|
|
254
|
+
* order-agnostic.
|
|
255
|
+
*/
|
|
256
|
+
function createWidgetPlugin(type) {
|
|
257
|
+
const draft = {
|
|
258
|
+
description: "",
|
|
259
|
+
config: null,
|
|
260
|
+
slots: null,
|
|
261
|
+
validateStructure: null,
|
|
262
|
+
state: null,
|
|
263
|
+
properties: null,
|
|
264
|
+
methods: null,
|
|
265
|
+
emittingMethods: null,
|
|
266
|
+
events: null
|
|
267
|
+
};
|
|
268
|
+
const builder = {
|
|
269
|
+
description(description) {
|
|
270
|
+
draft.description = description;
|
|
271
|
+
return builder;
|
|
272
|
+
},
|
|
273
|
+
interfaces: () => builder,
|
|
274
|
+
config(definition) {
|
|
275
|
+
const captured = captureDefinition(type, "config", "section \"config\"", definition);
|
|
276
|
+
draft.config = Object.freeze({
|
|
277
|
+
...captured,
|
|
278
|
+
schema: captured.schema ?? null
|
|
279
|
+
});
|
|
280
|
+
return builder;
|
|
281
|
+
},
|
|
282
|
+
slots(definitions, ...removedArguments) {
|
|
283
|
+
if (typeof definitions !== "object" || definitions === null) throw pluginContractViolation(type, "section \"slots\"", `must be declared with a slot definitions object, got ${describeValue(definitions)}`);
|
|
284
|
+
if (removedArguments.some((argument) => argument !== void 0)) throw pluginContractViolation(type, "section \"slots\"", "takes only the slot definitions; declare a plugin-level validateStructure with \".structure()\"");
|
|
285
|
+
draft.slots = new Map(Object.entries(definitions).map(([name, slot]) => [name, captureDefinition(type, "slots", memberSubject("slots", name), slot)]));
|
|
286
|
+
return builder;
|
|
287
|
+
},
|
|
288
|
+
structure(validateStructure) {
|
|
289
|
+
if (typeof validateStructure !== "function") throw pluginContractViolation(type, "phase \"structure\"", `must be given a validateStructure function, got ${describeValue(validateStructure)}`);
|
|
290
|
+
draft.validateStructure = validateStructure;
|
|
291
|
+
return builder;
|
|
292
|
+
},
|
|
293
|
+
state(build) {
|
|
294
|
+
const members = /* @__PURE__ */ new Map();
|
|
295
|
+
draft.state = members;
|
|
296
|
+
buildSection(type, "state", members, build);
|
|
297
|
+
return builder;
|
|
298
|
+
},
|
|
299
|
+
properties(build) {
|
|
300
|
+
const members = /* @__PURE__ */ new Map();
|
|
301
|
+
draft.properties = members;
|
|
302
|
+
buildSection(type, "properties", members, build);
|
|
303
|
+
return builder;
|
|
304
|
+
},
|
|
305
|
+
methods(build) {
|
|
306
|
+
const members = /* @__PURE__ */ new Map();
|
|
307
|
+
draft.methods = members;
|
|
308
|
+
draft.emittingMethods = null;
|
|
309
|
+
buildSection(type, "methods", members, build, (key) => {
|
|
310
|
+
(draft.emittingMethods ??= []).push(key);
|
|
311
|
+
});
|
|
312
|
+
return builder;
|
|
313
|
+
},
|
|
314
|
+
events(build) {
|
|
315
|
+
const members = /* @__PURE__ */ new Map();
|
|
316
|
+
draft.events = members;
|
|
317
|
+
buildSection(type, "events", members, build);
|
|
318
|
+
return builder;
|
|
319
|
+
},
|
|
320
|
+
done() {
|
|
321
|
+
if (draft.emittingMethods !== null) for (const name of draft.emittingMethods) {
|
|
322
|
+
const emits = draft.methods?.get(name)?.emits;
|
|
323
|
+
if (emits === void 0) continue;
|
|
324
|
+
for (let index = 0; index < emits.length; index++) {
|
|
325
|
+
const event = emits[index];
|
|
326
|
+
if (draft.events === null || !draft.events.has(event)) throw pluginContractViolation(type, memberSubject("methods", name), `has an invalid "emits" field (Event "${event}" is not declared in section "events")`);
|
|
327
|
+
if (emits.indexOf(event) !== index) throw pluginContractViolation(type, memberSubject("methods", name), `has an invalid "emits" field (Event "${event}" is listed more than once)`);
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
const definition = Object.freeze({
|
|
331
|
+
type,
|
|
332
|
+
description: draft.description,
|
|
333
|
+
config: draft.config,
|
|
334
|
+
slots: draft.slots,
|
|
335
|
+
validateStructure: draft.validateStructure,
|
|
336
|
+
state: draft.state,
|
|
337
|
+
properties: draft.properties,
|
|
338
|
+
methods: draft.methods,
|
|
339
|
+
events: draft.events
|
|
340
|
+
});
|
|
341
|
+
const capabilities = Object.freeze({
|
|
342
|
+
config: definition.config !== null,
|
|
343
|
+
slots: definition.slots !== null,
|
|
344
|
+
state: definition.state !== null,
|
|
345
|
+
properties: definition.properties !== null,
|
|
346
|
+
methods: definition.methods !== null,
|
|
347
|
+
events: definition.events !== null
|
|
348
|
+
});
|
|
349
|
+
const config = definition.config === null ? null : Object.freeze({
|
|
350
|
+
description: definition.config.description,
|
|
351
|
+
schema: definition.config.schema
|
|
352
|
+
});
|
|
353
|
+
const descriptions = Object.freeze({
|
|
354
|
+
config: config?.description ?? null,
|
|
355
|
+
slots: definition.slots === null ? null : createReadonlyMap([...definition.slots].map(([key, slot]) => [key, slot.description]))
|
|
356
|
+
});
|
|
357
|
+
return Object.freeze({
|
|
358
|
+
type,
|
|
359
|
+
description: draft.description,
|
|
360
|
+
capabilities,
|
|
361
|
+
config,
|
|
362
|
+
descriptions,
|
|
363
|
+
[widgetPluginBrand]: Object.freeze({ definition })
|
|
364
|
+
});
|
|
365
|
+
}
|
|
366
|
+
};
|
|
367
|
+
return builder;
|
|
368
|
+
}
|
|
369
|
+
//#endregion
|
|
370
|
+
//#region src/runtime/internals.ts
|
|
371
|
+
const runtimeInternals = Symbol("@deviltea/widget-core:runtime-internals");
|
|
372
|
+
/**
|
|
373
|
+
* Provenance probe: true only for Runtimes produced by this loaded module instance.
|
|
374
|
+
*/
|
|
375
|
+
function isCoreRuntime(value) {
|
|
376
|
+
if (typeof value !== "object" || value === null) return false;
|
|
377
|
+
return value[runtimeInternals] !== void 0;
|
|
378
|
+
}
|
|
379
|
+
/**
|
|
380
|
+
* Reads the internals carried by a Runtime produced by `createWidgetSystemRuntime`.
|
|
381
|
+
*/
|
|
382
|
+
function readRuntimeInternals(runtime) {
|
|
383
|
+
const internals = runtime[runtimeInternals];
|
|
384
|
+
if (internals === void 0) throw new Error("The runtime was not produced by this widget core build.");
|
|
385
|
+
return internals;
|
|
386
|
+
}
|
|
387
|
+
//#endregion
|
|
388
|
+
export { createWidgetPlugin as a, readWidgetPluginDefinition as c, WIDGET_CONFIG_JSON_SCHEMA_DIALECT as i, createReadonlyMap as l, readRuntimeInternals as n, createWidgetValueContract as o, runtimeInternals as r, isCoreWidgetPlugin as s, isCoreRuntime as t };
|
package/package.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
7
|
-
"version": "0.0
|
|
7
|
+
"version": "0.1.0",
|
|
8
8
|
"author": "DevilTea <ch19980814@gmail.com>",
|
|
9
9
|
"license": "MIT",
|
|
10
10
|
"homepage": "https://github.com/DevilTea/widget/tree/main/packages/core#readme",
|
|
@@ -24,6 +24,7 @@
|
|
|
24
24
|
"runtime",
|
|
25
25
|
"signals"
|
|
26
26
|
],
|
|
27
|
+
"sideEffects": false,
|
|
27
28
|
"exports": {
|
|
28
29
|
".": {
|
|
29
30
|
"types": "./dist/index.d.mts",
|
|
@@ -45,7 +46,7 @@
|
|
|
45
46
|
"dist"
|
|
46
47
|
],
|
|
47
48
|
"engines": {
|
|
48
|
-
"node": "
|
|
49
|
+
"node": ">=22.14.0"
|
|
49
50
|
},
|
|
50
51
|
"dependencies": {
|
|
51
52
|
"alien-signals": "3.2.1",
|