@sentropic/diagram-core 0.2.0 → 0.4.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 +101 -5
- package/dist/diagnostics.d.ts +17 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.js +3 -1
- package/dist/layout-hints.d.ts +158 -0
- package/dist/layout-hints.js +459 -0
- package/dist/notation.d.ts +121 -0
- package/dist/notation.js +225 -0
- package/dist/presentation-relations.d.ts +0 -1
- package/dist/presentation-relations.js +47 -2
- package/dist/presentation.d.ts +23 -0
- package/dist/presentation.js +74 -1
- package/dist/validate.js +26 -10
- package/dist/view.d.ts +4 -0
- package/dist/view.js +1 -1
- package/package.json +4 -2
- package/schemas/ds-layout-hints-1.json +1 -0
- package/schemas/ds-layout-hints-1.sha256 +1 -0
|
@@ -0,0 +1,459 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `ds-layout-hints@1` — the closed layout-hint vocabulary of the Design System.
|
|
3
|
+
*
|
|
4
|
+
* A view declaration (engram `MetamodelViewDecl.layout`) names a layout by this
|
|
5
|
+
* vocabulary and never by a table of its own. The vocabulary is authored,
|
|
6
|
+
* versioned and pinned here, and nowhere else.
|
|
7
|
+
*
|
|
8
|
+
* Scope rule of `@1`: it admits only what the layout engine of
|
|
9
|
+
* `@sentropic/diagram-canvas` executes at this version.
|
|
10
|
+
* - `auto-pack` = `layoutMeasured` (measured, row-packed views);
|
|
11
|
+
* - `layered-flow` = `layoutDocument` (ranked flow), on `generic@1` views
|
|
12
|
+
* without a typed presentation only.
|
|
13
|
+
* A mode or a hint that is specified but not executed yet (`lane-stack`,
|
|
14
|
+
* `matrix-grid`, `tree`, `direction`, `rotate_labels`) is REFUSED with its own
|
|
15
|
+
* code, never coerced to another mode: a template that validates against `@1`
|
|
16
|
+
* must render. Spacing overrides and coordinates are forbidden outright.
|
|
17
|
+
*
|
|
18
|
+
* Three layers, one source:
|
|
19
|
+
* - `DS_LAYOUT_HINTS_SCHEMA` JSON Schema 2020-12, closed. Its `$defs` also
|
|
20
|
+
* carry the refusal classification, so the pinned bytes cover it.
|
|
21
|
+
* - `DS_LAYOUT_HINTS_RULES` frozen data read from the schema `$defs`.
|
|
22
|
+
* - `validateLayoutHints()` pure; structural and semantic; diagnostics.
|
|
23
|
+
*
|
|
24
|
+
* Any change to the schema is `ds-layout-hints@2`: the pin digest is the
|
|
25
|
+
* SHA-256 of the RFC 8785 bytes of the schema.
|
|
26
|
+
*/
|
|
27
|
+
import { diagnostic } from "./diagnostics.js";
|
|
28
|
+
import { canonicalBytes, sha256Hex } from "./sha256.js";
|
|
29
|
+
export const DS_LAYOUT_VOCABULARY = "ds-layout-hints@1";
|
|
30
|
+
export const DS_LAYOUT_HINTS_SCHEMA_ID = "https://sentropic.dev/schemas/diagram/layout-hints/v1";
|
|
31
|
+
/** Modes the layout engine executes at this version. */
|
|
32
|
+
export const DS_LAYOUT_MODES = ["auto-pack", "layered-flow"];
|
|
33
|
+
/** Modes specified for a later vocabulary: refused in `@1`. */
|
|
34
|
+
export const DS_LAYOUT_FUTURE_MODES = ["lane-stack", "matrix-grid", "tree"];
|
|
35
|
+
/** Hints specified for a later vocabulary: refused in `@1`. */
|
|
36
|
+
export const DS_LAYOUT_FUTURE_HINTS = ["direction", "rotate_labels"];
|
|
37
|
+
/** Spacing overrides and coordinates: refused in every version (one gap law, no authored geometry). */
|
|
38
|
+
export const DS_LAYOUT_FORBIDDEN_HINTS = [
|
|
39
|
+
"cardGapX",
|
|
40
|
+
"cardGapY",
|
|
41
|
+
"density",
|
|
42
|
+
"edge_label_orientation",
|
|
43
|
+
"gapAfter",
|
|
44
|
+
"height",
|
|
45
|
+
"rankGap",
|
|
46
|
+
"width",
|
|
47
|
+
"x",
|
|
48
|
+
"y",
|
|
49
|
+
"zoneGapX",
|
|
50
|
+
"zoneGapY",
|
|
51
|
+
];
|
|
52
|
+
/** Hints read by the measured path only: refused under `layered-flow`. */
|
|
53
|
+
export const DS_LAYOUT_MEASURED_HINTS = ["grouping", "grouping_axis", "ordering", "rootOrder", "stretch"];
|
|
54
|
+
export const DS_LAYOUT_AXES = ["rows", "columns"];
|
|
55
|
+
const ENTITY_REF_PATTERN = "^entity:[A-Za-z0-9][A-Za-z0-9._-]*$";
|
|
56
|
+
const ENTITY_REF = new RegExp(ENTITY_REF_PATTERN);
|
|
57
|
+
const GROUP_ID_MAX = 80;
|
|
58
|
+
const LAYERED_FLOW_PROFILE = "generic@1";
|
|
59
|
+
const PRIVATE_SCHEMA = {
|
|
60
|
+
$schema: "https://json-schema.org/draft/2020-12/schema",
|
|
61
|
+
$id: DS_LAYOUT_HINTS_SCHEMA_ID,
|
|
62
|
+
title: "ds-layout-hints@1",
|
|
63
|
+
type: "object",
|
|
64
|
+
properties: {
|
|
65
|
+
vocabulary: { const: DS_LAYOUT_VOCABULARY },
|
|
66
|
+
mode: { $ref: "#/$defs/mode" },
|
|
67
|
+
ordering: {
|
|
68
|
+
type: "object",
|
|
69
|
+
propertyNames: { $ref: "#/$defs/entityRef" },
|
|
70
|
+
additionalProperties: { $ref: "#/$defs/entityRefList" },
|
|
71
|
+
},
|
|
72
|
+
rootOrder: { $ref: "#/$defs/entityRefList" },
|
|
73
|
+
grouping: { type: "array", items: { $ref: "#/$defs/group" } },
|
|
74
|
+
grouping_axis: { $ref: "#/$defs/axis" },
|
|
75
|
+
stretch: { type: "boolean" },
|
|
76
|
+
},
|
|
77
|
+
required: ["vocabulary", "mode"],
|
|
78
|
+
additionalProperties: false,
|
|
79
|
+
dependentSchemas: { grouping: { properties: { grouping_axis: false } } },
|
|
80
|
+
if: { properties: { mode: { const: "layered-flow" } }, required: ["mode"] },
|
|
81
|
+
then: {
|
|
82
|
+
properties: { grouping: false, grouping_axis: false, ordering: false, rootOrder: false, stretch: false },
|
|
83
|
+
},
|
|
84
|
+
$defs: {
|
|
85
|
+
mode: { enum: [...DS_LAYOUT_MODES] },
|
|
86
|
+
futureMode: { enum: [...DS_LAYOUT_FUTURE_MODES] },
|
|
87
|
+
futureHint: { enum: [...DS_LAYOUT_FUTURE_HINTS] },
|
|
88
|
+
forbiddenHint: { enum: [...DS_LAYOUT_FORBIDDEN_HINTS] },
|
|
89
|
+
measuredHint: { enum: [...DS_LAYOUT_MEASURED_HINTS] },
|
|
90
|
+
layeredFlowScope: {
|
|
91
|
+
type: "object",
|
|
92
|
+
properties: {
|
|
93
|
+
profiles: { type: "array", minItems: 1, items: { const: LAYERED_FLOW_PROFILE } },
|
|
94
|
+
diagramPresentation: { const: false },
|
|
95
|
+
presentationVocabulary: false,
|
|
96
|
+
},
|
|
97
|
+
required: ["profiles", "diagramPresentation"],
|
|
98
|
+
},
|
|
99
|
+
axis: { enum: [...DS_LAYOUT_AXES] },
|
|
100
|
+
entityRef: { type: "string", pattern: ENTITY_REF_PATTERN },
|
|
101
|
+
entityRefList: { type: "array", items: { $ref: "#/$defs/entityRef" }, uniqueItems: true },
|
|
102
|
+
group: {
|
|
103
|
+
type: "object",
|
|
104
|
+
properties: {
|
|
105
|
+
id: { type: "string", minLength: 1, maxLength: GROUP_ID_MAX },
|
|
106
|
+
direction: { $ref: "#/$defs/axis" },
|
|
107
|
+
items: {
|
|
108
|
+
type: "array",
|
|
109
|
+
minItems: 1,
|
|
110
|
+
items: { anyOf: [{ $ref: "#/$defs/entityRef" }, { $ref: "#/$defs/group" }] },
|
|
111
|
+
},
|
|
112
|
+
stretch: { type: "boolean" },
|
|
113
|
+
},
|
|
114
|
+
required: ["id", "direction", "items"],
|
|
115
|
+
additionalProperties: false,
|
|
116
|
+
},
|
|
117
|
+
},
|
|
118
|
+
};
|
|
119
|
+
function deepClone(value) {
|
|
120
|
+
if (value === null || typeof value !== "object")
|
|
121
|
+
return value;
|
|
122
|
+
if (Array.isArray(value))
|
|
123
|
+
return value.map((item) => deepClone(item));
|
|
124
|
+
const out = {};
|
|
125
|
+
for (const key of Object.keys(value)) {
|
|
126
|
+
out[key] = deepClone(value[key]);
|
|
127
|
+
}
|
|
128
|
+
return out;
|
|
129
|
+
}
|
|
130
|
+
function deepFreeze(value) {
|
|
131
|
+
if (value === null || typeof value !== "object" || Object.isFrozen(value))
|
|
132
|
+
return value;
|
|
133
|
+
for (const child of Object.values(value))
|
|
134
|
+
deepFreeze(child);
|
|
135
|
+
return Object.freeze(value);
|
|
136
|
+
}
|
|
137
|
+
deepFreeze(PRIVATE_SCHEMA);
|
|
138
|
+
/** The canonical JSON Schema of `ds-layout-hints@1`, deeply frozen. Also shipped as `schemas/ds-layout-hints-1.json`. */
|
|
139
|
+
export const DS_LAYOUT_HINTS_SCHEMA = deepFreeze(deepClone(PRIVATE_SCHEMA));
|
|
140
|
+
/** SHA-256 (64 lowercase hex) of the RFC 8785 bytes of the schema. */
|
|
141
|
+
export const DS_LAYOUT_HINTS_SCHEMA_DIGEST = sha256Hex(canonicalBytes(PRIVATE_SCHEMA));
|
|
142
|
+
/** The pin a view declaration references. Equality is equality of the three fields. */
|
|
143
|
+
export const DS_LAYOUT_VOCABULARY_PIN = deepFreeze({
|
|
144
|
+
id: DS_LAYOUT_HINTS_SCHEMA_ID,
|
|
145
|
+
version: DS_LAYOUT_VOCABULARY,
|
|
146
|
+
contentDigest: DS_LAYOUT_HINTS_SCHEMA_DIGEST,
|
|
147
|
+
});
|
|
148
|
+
/** The semantic rules of `ds-layout-hints@1`, as data. Every list equals the matching schema `$defs` enum. */
|
|
149
|
+
export const DS_LAYOUT_HINTS_RULES = deepFreeze({
|
|
150
|
+
vocabulary: DS_LAYOUT_VOCABULARY,
|
|
151
|
+
modes: {
|
|
152
|
+
implemented: [...DS_LAYOUT_MODES],
|
|
153
|
+
future: [...DS_LAYOUT_FUTURE_MODES],
|
|
154
|
+
futureVocabulary: "ds-layout-hints@2",
|
|
155
|
+
},
|
|
156
|
+
layeredFlowScope: {
|
|
157
|
+
profiles: [LAYERED_FLOW_PROFILE],
|
|
158
|
+
diagramPresentation: false,
|
|
159
|
+
presentationVocabulary: "absent",
|
|
160
|
+
},
|
|
161
|
+
hints: {
|
|
162
|
+
measuredOnly: [...DS_LAYOUT_MEASURED_HINTS],
|
|
163
|
+
future: [...DS_LAYOUT_FUTURE_HINTS],
|
|
164
|
+
forbidden: [...DS_LAYOUT_FORBIDDEN_HINTS],
|
|
165
|
+
exclusive: [["grouping", "grouping_axis"]],
|
|
166
|
+
},
|
|
167
|
+
identity: ["group-id-unique", "group-leaf-once", "ordering-member-single-parent", "ordering-parent-not-member"],
|
|
168
|
+
});
|
|
169
|
+
const ROOT_KEYS = ["vocabulary", "mode", "ordering", "rootOrder", "grouping", "grouping_axis", "stretch"];
|
|
170
|
+
const GROUP_KEYS = ["id", "direction", "items", "stretch"];
|
|
171
|
+
function isRecord(value) {
|
|
172
|
+
if (value === null || typeof value !== "object" || Array.isArray(value))
|
|
173
|
+
return false;
|
|
174
|
+
const proto = Object.getPrototypeOf(value);
|
|
175
|
+
return proto === Object.prototype || proto === null;
|
|
176
|
+
}
|
|
177
|
+
function includes(list, value) {
|
|
178
|
+
return typeof value === "string" && list.includes(value);
|
|
179
|
+
}
|
|
180
|
+
function describe(value) {
|
|
181
|
+
if (value === null)
|
|
182
|
+
return "null";
|
|
183
|
+
if (Array.isArray(value))
|
|
184
|
+
return "array";
|
|
185
|
+
return typeof value;
|
|
186
|
+
}
|
|
187
|
+
/** One property name outside the admitted set, classified. */
|
|
188
|
+
function refuseKey(key, path, push) {
|
|
189
|
+
if (includes(DS_LAYOUT_FORBIDDEN_HINTS, key)) {
|
|
190
|
+
push("layout-hint-forbidden", path, `${key} is a spacing or coordinate override: ${DS_LAYOUT_VOCABULARY} admits none`, {
|
|
191
|
+
details: { hint: key },
|
|
192
|
+
});
|
|
193
|
+
}
|
|
194
|
+
else if (includes(DS_LAYOUT_FUTURE_HINTS, key)) {
|
|
195
|
+
push("layout-hint-not-implemented", path, `${key} is not executed by the layout engine at ${DS_LAYOUT_VOCABULARY}`, {
|
|
196
|
+
details: { hint: key, vocabulary: DS_LAYOUT_HINTS_RULES.modes.futureVocabulary },
|
|
197
|
+
});
|
|
198
|
+
}
|
|
199
|
+
else {
|
|
200
|
+
push("layout-hint-unknown", path, `${key} is not a property of ${DS_LAYOUT_VOCABULARY}`, { details: { hint: key } });
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
function checkEntityRef(value, path, push) {
|
|
204
|
+
if (typeof value === "string" && ENTITY_REF.test(value))
|
|
205
|
+
return true;
|
|
206
|
+
push("layout-hints-invalid", path, `expected an entity reference, got ${typeof value === "string" ? JSON.stringify(value) : describe(value)}`);
|
|
207
|
+
return false;
|
|
208
|
+
}
|
|
209
|
+
function checkEntityRefList(value, path, push) {
|
|
210
|
+
if (!Array.isArray(value)) {
|
|
211
|
+
push("layout-hints-invalid", path, `expected an array of entity references, got ${describe(value)}`);
|
|
212
|
+
return [];
|
|
213
|
+
}
|
|
214
|
+
const out = [];
|
|
215
|
+
const seen = new Set();
|
|
216
|
+
value.forEach((member, index) => {
|
|
217
|
+
if (!checkEntityRef(member, `${path}.${index}`, push))
|
|
218
|
+
return;
|
|
219
|
+
if (seen.has(member)) {
|
|
220
|
+
push("layout-hint-conflict", `${path}.${index}`, `${member} is listed twice`, { refs: [member] });
|
|
221
|
+
return;
|
|
222
|
+
}
|
|
223
|
+
seen.add(member);
|
|
224
|
+
out.push(member);
|
|
225
|
+
});
|
|
226
|
+
return out;
|
|
227
|
+
}
|
|
228
|
+
function checkAxis(value, path, push) {
|
|
229
|
+
if (includes(DS_LAYOUT_AXES, value))
|
|
230
|
+
return true;
|
|
231
|
+
push("layout-hints-invalid", path, `expected "rows" or "columns", got ${typeof value === "string" ? JSON.stringify(value) : describe(value)}`);
|
|
232
|
+
return false;
|
|
233
|
+
}
|
|
234
|
+
function checkGroup(value, path, ledger, ancestors, push) {
|
|
235
|
+
if (!isRecord(value)) {
|
|
236
|
+
push("layout-hints-invalid", path, `expected a group object, got ${describe(value)}`);
|
|
237
|
+
return;
|
|
238
|
+
}
|
|
239
|
+
if (ancestors.has(value)) {
|
|
240
|
+
push("layout-hints-invalid", path, "a group cannot contain itself");
|
|
241
|
+
return;
|
|
242
|
+
}
|
|
243
|
+
for (const key of Object.keys(value)) {
|
|
244
|
+
if (!GROUP_KEYS.includes(key))
|
|
245
|
+
refuseKey(key, `${path}.${key}`, push);
|
|
246
|
+
}
|
|
247
|
+
const id = value["id"];
|
|
248
|
+
if (typeof id !== "string" || id.length < 1 || id.length > GROUP_ID_MAX) {
|
|
249
|
+
push("layout-hints-invalid", `${path}.id`, `a group id is a string of 1 to ${GROUP_ID_MAX} characters`);
|
|
250
|
+
}
|
|
251
|
+
else {
|
|
252
|
+
const first = ledger.ids.get(id);
|
|
253
|
+
if (first !== undefined) {
|
|
254
|
+
push("layout-hint-conflict", `${path}.id`, `group id ${JSON.stringify(id)} is already used at ${first}`, { details: { group: id } });
|
|
255
|
+
}
|
|
256
|
+
else {
|
|
257
|
+
ledger.ids.set(id, path);
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
checkAxis(value["direction"], `${path}.direction`, push);
|
|
261
|
+
if ("stretch" in value && typeof value["stretch"] !== "boolean") {
|
|
262
|
+
push("layout-hints-invalid", `${path}.stretch`, `expected a boolean, got ${describe(value["stretch"])}`);
|
|
263
|
+
}
|
|
264
|
+
const items = value["items"];
|
|
265
|
+
if (!Array.isArray(items) || items.length === 0) {
|
|
266
|
+
push("layout-hints-invalid", `${path}.items`, "a group lists at least one item");
|
|
267
|
+
return;
|
|
268
|
+
}
|
|
269
|
+
const nested = new Set(ancestors).add(value);
|
|
270
|
+
items.forEach((item, index) => {
|
|
271
|
+
const itemPath = `${path}.items.${index}`;
|
|
272
|
+
if (typeof item === "string") {
|
|
273
|
+
if (!checkEntityRef(item, itemPath, push))
|
|
274
|
+
return;
|
|
275
|
+
const owner = ledger.leaves.get(item);
|
|
276
|
+
if (owner !== undefined) {
|
|
277
|
+
push("layout-hint-conflict", itemPath, `${item} is already placed by ${owner}`, { refs: [item] });
|
|
278
|
+
}
|
|
279
|
+
else {
|
|
280
|
+
ledger.leaves.set(item, itemPath);
|
|
281
|
+
}
|
|
282
|
+
return;
|
|
283
|
+
}
|
|
284
|
+
checkGroup(item, itemPath, ledger, nested, push);
|
|
285
|
+
});
|
|
286
|
+
}
|
|
287
|
+
function checkLayeredFlowScope(context, push) {
|
|
288
|
+
const refuse = (message, details) => {
|
|
289
|
+
push("layout-mode-out-of-scope", "mode", `layered-flow is admitted on ${LAYERED_FLOW_PROFILE} views without a typed presentation only: ${message}`, {
|
|
290
|
+
details: { mode: "layered-flow", ...details },
|
|
291
|
+
});
|
|
292
|
+
};
|
|
293
|
+
const profiles = context?.profiles;
|
|
294
|
+
if (profiles === undefined || profiles.length === 0) {
|
|
295
|
+
refuse("the view's profiles are not stated", { reason: "profiles-unstated" });
|
|
296
|
+
return;
|
|
297
|
+
}
|
|
298
|
+
const foreign = profiles.filter((profile) => profile !== LAYERED_FLOW_PROFILE);
|
|
299
|
+
if (foreign.length > 0) {
|
|
300
|
+
refuse(`the view uses ${foreign.join(", ")}`, { reason: "profile", profile: foreign[0] });
|
|
301
|
+
}
|
|
302
|
+
if (context?.diagramPresentation !== false) {
|
|
303
|
+
refuse(context?.diagramPresentation === true ? "the view carries a typed presentation" : "the absence of a typed presentation is not stated", { reason: context?.diagramPresentation === true ? "diagram-presentation" : "diagram-presentation-unstated" });
|
|
304
|
+
}
|
|
305
|
+
if (context?.presentationVocabulary !== undefined) {
|
|
306
|
+
refuse(`the profile declares ${context.presentationVocabulary}`, {
|
|
307
|
+
reason: "presentation-vocabulary",
|
|
308
|
+
presentationVocabulary: context.presentationVocabulary,
|
|
309
|
+
});
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
/**
|
|
313
|
+
* Validate a layout-hint payload against `ds-layout-hints@1`: structure and
|
|
314
|
+
* semantics, in one pass. Pure; never throws; an empty result means valid.
|
|
315
|
+
* Diagnostics are sorted by (path, code).
|
|
316
|
+
*
|
|
317
|
+
* What it cannot see: whether a reference exists in the document and whether
|
|
318
|
+
* the members of a group are siblings. Those need the document and stay with
|
|
319
|
+
* the layout engine (`validateHints` in `@sentropic/diagram-canvas`).
|
|
320
|
+
*/
|
|
321
|
+
export function validateLayoutHints(value, context) {
|
|
322
|
+
const found = [];
|
|
323
|
+
const push = (code, path, message, extra) => {
|
|
324
|
+
found.push(diagnostic({ code, path: path === "" ? "layout" : `layout.${path}`, message, ...extra }));
|
|
325
|
+
};
|
|
326
|
+
const done = () => found.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : a.code < b.code ? -1 : a.code > b.code ? 1 : 0));
|
|
327
|
+
if (!isRecord(value)) {
|
|
328
|
+
push("layout-hints-invalid", "", `expected a layout-hint object, got ${describe(value)}`);
|
|
329
|
+
return done();
|
|
330
|
+
}
|
|
331
|
+
const vocabulary = value["vocabulary"];
|
|
332
|
+
if (vocabulary !== DS_LAYOUT_VOCABULARY) {
|
|
333
|
+
// Fail closed: nothing else is read from a payload of another vocabulary.
|
|
334
|
+
push("layout-vocabulary-unknown", "vocabulary", vocabulary === undefined
|
|
335
|
+
? `vocabulary is required and must be ${JSON.stringify(DS_LAYOUT_VOCABULARY)}`
|
|
336
|
+
: `vocabulary ${typeof vocabulary === "string" ? JSON.stringify(vocabulary) : describe(vocabulary)} is not ${JSON.stringify(DS_LAYOUT_VOCABULARY)}`, typeof vocabulary === "string" ? { details: { vocabulary } } : undefined);
|
|
337
|
+
return done();
|
|
338
|
+
}
|
|
339
|
+
for (const key of Object.keys(value)) {
|
|
340
|
+
if (!ROOT_KEYS.includes(key))
|
|
341
|
+
refuseKey(key, key, push);
|
|
342
|
+
}
|
|
343
|
+
const mode = value["mode"];
|
|
344
|
+
let admitted;
|
|
345
|
+
if (mode === undefined) {
|
|
346
|
+
push("layout-hints-invalid", "mode", "mode is required: an absent mode is never read as auto-pack");
|
|
347
|
+
}
|
|
348
|
+
else if (includes(DS_LAYOUT_MODES, mode)) {
|
|
349
|
+
admitted = mode;
|
|
350
|
+
}
|
|
351
|
+
else if (includes(DS_LAYOUT_FUTURE_MODES, mode)) {
|
|
352
|
+
push("layout-mode-not-implemented", "mode", `${String(mode)} is not executed by the layout engine at ${DS_LAYOUT_VOCABULARY}`, {
|
|
353
|
+
details: { mode: mode, vocabulary: DS_LAYOUT_HINTS_RULES.modes.futureVocabulary },
|
|
354
|
+
});
|
|
355
|
+
}
|
|
356
|
+
else {
|
|
357
|
+
push("layout-mode-unknown", "mode", `mode ${typeof mode === "string" ? JSON.stringify(mode) : describe(mode)} is not a mode of ${DS_LAYOUT_VOCABULARY}`, typeof mode === "string" ? { details: { mode } } : undefined);
|
|
358
|
+
}
|
|
359
|
+
if (admitted === "layered-flow") {
|
|
360
|
+
checkLayeredFlowScope(context, push);
|
|
361
|
+
for (const key of DS_LAYOUT_MEASURED_HINTS) {
|
|
362
|
+
if (key in value) {
|
|
363
|
+
push("layout-hint-out-of-scope", key, `${key} is read by auto-pack only; layered-flow takes no authored hint`, {
|
|
364
|
+
details: { hint: key, mode: "layered-flow" },
|
|
365
|
+
});
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
if ("stretch" in value && typeof value["stretch"] !== "boolean") {
|
|
370
|
+
push("layout-hints-invalid", "stretch", `expected a boolean, got ${describe(value["stretch"])}`);
|
|
371
|
+
}
|
|
372
|
+
if ("rootOrder" in value)
|
|
373
|
+
checkEntityRefList(value["rootOrder"], "rootOrder", push);
|
|
374
|
+
if ("ordering" in value) {
|
|
375
|
+
const ordering = value["ordering"];
|
|
376
|
+
if (!isRecord(ordering)) {
|
|
377
|
+
push("layout-hints-invalid", "ordering", `expected an object keyed by parent entity, got ${describe(ordering)}`);
|
|
378
|
+
}
|
|
379
|
+
else {
|
|
380
|
+
const parentOf = new Map();
|
|
381
|
+
for (const parent of Object.keys(ordering)) {
|
|
382
|
+
const path = `ordering.${parent}`;
|
|
383
|
+
const parentValid = checkEntityRef(parent, path, push);
|
|
384
|
+
for (const member of checkEntityRefList(ordering[parent], path, push)) {
|
|
385
|
+
if (parentValid && member === parent) {
|
|
386
|
+
push("layout-hint-conflict", path, `${member} cannot be ordered under itself`, { refs: [member] });
|
|
387
|
+
continue;
|
|
388
|
+
}
|
|
389
|
+
const first = parentOf.get(member);
|
|
390
|
+
if (first !== undefined && first !== parent) {
|
|
391
|
+
push("layout-hint-conflict", path, `${member} is already ordered under ${first}`, { refs: [member, first, parent] });
|
|
392
|
+
continue;
|
|
393
|
+
}
|
|
394
|
+
parentOf.set(member, parent);
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
if ("grouping" in value && "grouping_axis" in value) {
|
|
400
|
+
push("layout-hint-conflict", "grouping_axis", "grouping and grouping_axis cannot be authored together", {
|
|
401
|
+
details: { hint: "grouping_axis", other: "grouping" },
|
|
402
|
+
});
|
|
403
|
+
}
|
|
404
|
+
if ("grouping_axis" in value)
|
|
405
|
+
checkAxis(value["grouping_axis"], "grouping_axis", push);
|
|
406
|
+
if ("grouping" in value) {
|
|
407
|
+
const grouping = value["grouping"];
|
|
408
|
+
if (!Array.isArray(grouping)) {
|
|
409
|
+
push("layout-hints-invalid", "grouping", `expected an array of groups, got ${describe(grouping)}`);
|
|
410
|
+
}
|
|
411
|
+
else {
|
|
412
|
+
const ledger = { ids: new Map(), leaves: new Map() };
|
|
413
|
+
grouping.forEach((group, index) => checkGroup(group, `grouping.${index}`, ledger, new Set(), push));
|
|
414
|
+
}
|
|
415
|
+
}
|
|
416
|
+
return done();
|
|
417
|
+
}
|
|
418
|
+
/** Type guard: true iff `validateLayoutHints` raises nothing. */
|
|
419
|
+
export function isLayoutHints(value, context) {
|
|
420
|
+
return validateLayoutHints(value, context).length === 0;
|
|
421
|
+
}
|
|
422
|
+
/** The id of the root group `grouping_axis` lowers to. */
|
|
423
|
+
export const DS_LAYOUT_ROOT_GROUP_ID = "ds-layout-hints.root";
|
|
424
|
+
function lowerGroup(group) {
|
|
425
|
+
return {
|
|
426
|
+
id: group.id,
|
|
427
|
+
direction: group.direction,
|
|
428
|
+
items: group.items.map((item) => (typeof item === "string" ? item : lowerGroup(item))),
|
|
429
|
+
...(group.stretch === undefined ? {} : { stretch: group.stretch }),
|
|
430
|
+
};
|
|
431
|
+
}
|
|
432
|
+
/**
|
|
433
|
+
* Lower a VALID payload to the hints the layout engine takes. `mode` selects
|
|
434
|
+
* the engine entry and is not part of the result; `layered-flow` lowers to no
|
|
435
|
+
* hint at all.
|
|
436
|
+
*
|
|
437
|
+
* `grouping_axis` is a shorthand for one group over the root level: it needs
|
|
438
|
+
* the visible root entities, which only the caller knows. Listed roots come
|
|
439
|
+
* first in `rootOrder`, the others after in UTF-16 order (the engine's own
|
|
440
|
+
* rule). Without roots the shorthand lowers to nothing.
|
|
441
|
+
*/
|
|
442
|
+
export function lowerLayoutHints(hints, roots = []) {
|
|
443
|
+
if (hints.mode !== "auto-pack")
|
|
444
|
+
return {};
|
|
445
|
+
let grouping = hints.grouping?.map(lowerGroup);
|
|
446
|
+
if (hints.grouping_axis !== undefined && roots.length > 0) {
|
|
447
|
+
const members = new Set(roots);
|
|
448
|
+
const listed = (hints.rootOrder ?? []).filter((member) => members.has(member));
|
|
449
|
+
const rest = [...members].filter((member) => !listed.includes(member)).sort();
|
|
450
|
+
grouping = [{ id: DS_LAYOUT_ROOT_GROUP_ID, direction: hints.grouping_axis, items: [...listed, ...rest] }];
|
|
451
|
+
}
|
|
452
|
+
return {
|
|
453
|
+
...(hints.ordering === undefined ? {} : { ordering: hints.ordering }),
|
|
454
|
+
...(hints.rootOrder === undefined ? {} : { rootOrder: hints.rootOrder }),
|
|
455
|
+
...(grouping === undefined ? {} : { grouping }),
|
|
456
|
+
...(hints.stretch === undefined ? {} : { stretch: hints.stretch }),
|
|
457
|
+
};
|
|
458
|
+
}
|
|
459
|
+
//# sourceMappingURL=layout-hints.js.map
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `diagram-notation@1` — the closed notation vocabulary and its pin.
|
|
3
|
+
*
|
|
4
|
+
* A profile maps its types onto this vocabulary (which role draws an entity
|
|
5
|
+
* type, which encoding draws a relation type). The vocabulary is DS-owned;
|
|
6
|
+
* the mapping is profile data and holds no place here.
|
|
7
|
+
*
|
|
8
|
+
* Two layers, both data, both pinned:
|
|
9
|
+
* - `DIAGRAM_NOTATION_SCHEMA` JSON Schema 2020-12, structural only: closed
|
|
10
|
+
* objects, enums, string bounds, required `role`, `nature`, `encoding`,
|
|
11
|
+
* slot shape.
|
|
12
|
+
* - `DIAGRAM_NOTATION_RULES` every conditional the schema does not state:
|
|
13
|
+
* the role table, the variants of each nature, the property list of each
|
|
14
|
+
* encoding, slot ownership.
|
|
15
|
+
*
|
|
16
|
+
* `DIAGRAM_NOTATION_PIN.contentDigest` is the SHA-256 of the RFC 8785 bytes of
|
|
17
|
+
* `{ schema, rules }`. Any change to either is `diagram-notation@2`.
|
|
18
|
+
*
|
|
19
|
+
* NOT here: `validateNotation`, `validateViewNotation` and `resolveNotation`.
|
|
20
|
+
* This module freezes the vocabulary a consumer pins; the executor that reads
|
|
21
|
+
* it is a later lot, and until it ships nothing in this package enforces the
|
|
22
|
+
* rules below.
|
|
23
|
+
*/
|
|
24
|
+
import type { PresentationPin } from "./presentation.js";
|
|
25
|
+
export declare const DIAGRAM_NOTATION_VOCABULARY: "diagram-notation@1";
|
|
26
|
+
export declare const DIAGRAM_NOTATION_MODES: readonly ["strict", "metadata"];
|
|
27
|
+
export declare const DIAGRAM_NOTATION_ROLES: readonly ["card", "container", "lane", "entity-table", "flow-node"];
|
|
28
|
+
export declare const DIAGRAM_NOTATION_NATURES: readonly ["component", "responsibility", "data", "activity"];
|
|
29
|
+
export declare const DIAGRAM_NOTATION_VARIANTS: readonly ["task", "start", "end", "decision", "subprocess", "data", "document", "participant"];
|
|
30
|
+
export declare const DIAGRAM_NOTATION_ENCODINGS: readonly ["arrow", "containment", "detail", "footer"];
|
|
31
|
+
export declare const DIAGRAM_NOTATION_ENDS: readonly ["none", "arrow", "cardinality"];
|
|
32
|
+
export type NotationMode = (typeof DIAGRAM_NOTATION_MODES)[number];
|
|
33
|
+
export type NotationRole = (typeof DIAGRAM_NOTATION_ROLES)[number];
|
|
34
|
+
export type NotationNature = (typeof DIAGRAM_NOTATION_NATURES)[number];
|
|
35
|
+
export type NotationVariant = (typeof DIAGRAM_NOTATION_VARIANTS)[number];
|
|
36
|
+
export type NotationEncoding = (typeof DIAGRAM_NOTATION_ENCODINGS)[number];
|
|
37
|
+
export type NotationEnds = (typeof DIAGRAM_NOTATION_ENDS)[number];
|
|
38
|
+
/** A slot is a literal text, or a lookup on an attribute of the instance. */
|
|
39
|
+
export type NotationSlot = string | {
|
|
40
|
+
readonly attribute: string;
|
|
41
|
+
readonly values: Readonly<Record<string, string>>;
|
|
42
|
+
readonly default: string;
|
|
43
|
+
};
|
|
44
|
+
export interface NotationTypeRef {
|
|
45
|
+
readonly profile: string;
|
|
46
|
+
readonly type: string;
|
|
47
|
+
}
|
|
48
|
+
export interface NotationNode {
|
|
49
|
+
readonly role: NotationRole;
|
|
50
|
+
readonly nature: NotationNature;
|
|
51
|
+
readonly variant?: NotationSlot;
|
|
52
|
+
readonly icon?: NotationSlot;
|
|
53
|
+
readonly kicker?: NotationSlot;
|
|
54
|
+
/** Roles of DIRECT containment children. */
|
|
55
|
+
readonly holds?: readonly NotationRole[];
|
|
56
|
+
}
|
|
57
|
+
export interface NotationRelation {
|
|
58
|
+
readonly encoding: NotationEncoding;
|
|
59
|
+
readonly ends?: NotationEnds;
|
|
60
|
+
readonly provisional?: {
|
|
61
|
+
readonly attribute: string;
|
|
62
|
+
readonly equals: string;
|
|
63
|
+
};
|
|
64
|
+
readonly lift?: {
|
|
65
|
+
readonly via: NotationTypeRef;
|
|
66
|
+
readonly ancestors: readonly NotationTypeRef[];
|
|
67
|
+
};
|
|
68
|
+
readonly fallback?: {
|
|
69
|
+
readonly encoding: "detail" | "footer";
|
|
70
|
+
readonly on: string;
|
|
71
|
+
readonly label: string;
|
|
72
|
+
};
|
|
73
|
+
readonly on?: string;
|
|
74
|
+
readonly label?: string;
|
|
75
|
+
}
|
|
76
|
+
export interface NotationBlock {
|
|
77
|
+
readonly vocabulary: typeof DIAGRAM_NOTATION_VOCABULARY;
|
|
78
|
+
readonly mode?: NotationMode;
|
|
79
|
+
readonly entityTypes: Readonly<Record<string, NotationNode>>;
|
|
80
|
+
readonly relationTypes: Readonly<Record<string, NotationRelation>>;
|
|
81
|
+
}
|
|
82
|
+
/** How a role treats one slot. `participant-only`: admitted when the effective variant is `participant`. */
|
|
83
|
+
export type NotationSlotRule = "required" | "optional" | "refused" | "participant-only";
|
|
84
|
+
export interface NotationRoleRule {
|
|
85
|
+
readonly natures: readonly NotationNature[];
|
|
86
|
+
readonly icon: NotationSlotRule;
|
|
87
|
+
readonly kicker: NotationSlotRule;
|
|
88
|
+
/** `by-nature`: the variant is one of `variants[nature]`. */
|
|
89
|
+
readonly variant: "refused" | "by-nature";
|
|
90
|
+
/** Roles a type of this role may list in `holds`. */
|
|
91
|
+
readonly holds: readonly NotationRole[];
|
|
92
|
+
/** When set, `holds` counts only for this effective variant. */
|
|
93
|
+
readonly holdsEffectiveFor?: NotationVariant;
|
|
94
|
+
}
|
|
95
|
+
export interface DiagramNotationRules {
|
|
96
|
+
readonly vocabulary: typeof DIAGRAM_NOTATION_VOCABULARY;
|
|
97
|
+
readonly defaultMode: NotationMode;
|
|
98
|
+
readonly roles: Readonly<Record<NotationRole, NotationRoleRule>>;
|
|
99
|
+
readonly variants: Readonly<Record<NotationNature, readonly NotationVariant[]>>;
|
|
100
|
+
readonly iconPattern: string;
|
|
101
|
+
readonly encodings: Readonly<Record<NotationEncoding, {
|
|
102
|
+
readonly properties: readonly string[];
|
|
103
|
+
readonly required: readonly string[];
|
|
104
|
+
}>>;
|
|
105
|
+
readonly endsDefault: {
|
|
106
|
+
readonly directed: NotationEnds;
|
|
107
|
+
readonly undirected: NotationEnds;
|
|
108
|
+
};
|
|
109
|
+
readonly slotOwners: Readonly<Record<"detail" | "footer", readonly NotationRole[]>>;
|
|
110
|
+
readonly liftAncestorRoles: readonly NotationRole[];
|
|
111
|
+
readonly containmentHierarchyShape: "tree";
|
|
112
|
+
}
|
|
113
|
+
/** The structural JSON Schema of a `diagram-notation@1` block, deeply frozen. */
|
|
114
|
+
export declare const DIAGRAM_NOTATION_SCHEMA: Readonly<Record<string, unknown>>;
|
|
115
|
+
/** The semantic rules of `diagram-notation@1`, as data, deeply frozen. */
|
|
116
|
+
export declare const DIAGRAM_NOTATION_RULES: DiagramNotationRules;
|
|
117
|
+
/** SHA-256 (64 lowercase hex) of the RFC 8785 bytes of `{ schema, rules }`. */
|
|
118
|
+
export declare const DIAGRAM_NOTATION_DIGEST: string;
|
|
119
|
+
/** The pin of the notation vocabulary. Equality is equality of the three fields. */
|
|
120
|
+
export declare const DIAGRAM_NOTATION_PIN: PresentationPin;
|
|
121
|
+
//# sourceMappingURL=notation.d.ts.map
|