@sentropic/diagram-core 0.1.0 → 0.3.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 +164 -1
- package/dist/bindings.js +1 -0
- package/dist/chain-profile.d.ts +4 -0
- package/dist/chain-profile.js +85 -0
- package/dist/chain.d.ts +11 -0
- package/dist/chain.js +284 -0
- package/dist/commands.js +5 -3
- package/dist/diagnostics.d.ts +20 -4
- package/dist/erd-validate.d.ts +5 -0
- package/dist/erd-validate.js +33 -0
- package/dist/erd.d.ts +69 -0
- package/dist/erd.js +72 -0
- package/dist/flows.d.ts +36 -0
- package/dist/flows.js +144 -0
- package/dist/fold.d.ts +0 -9
- package/dist/fold.js +16 -19
- package/dist/index.d.ts +7 -2
- package/dist/index.js +7 -2
- 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 +4 -0
- package/dist/presentation-relations.js +17 -0
- package/dist/profile.d.ts +39 -0
- package/dist/profile.js +2 -0
- package/dist/profiles/erd.d.ts +6 -0
- package/dist/profiles/erd.js +29 -0
- package/dist/profiles/index.d.ts +1 -0
- package/dist/profiles/index.js +5 -0
- package/dist/relation-types.d.ts +6 -0
- package/dist/relation-types.js +16 -0
- package/dist/validate.d.ts +0 -13
- package/dist/validate.js +63 -18
- package/dist/view-schema-pin.d.ts +9 -6
- package/dist/view-schema-pin.js +17 -7
- package/dist/view.d.ts +12 -3
- package/package.json +8 -3
- package/schemas/diagram-view-schema-3.json +1 -0
- package/schemas/diagram-view-schema-3.sha256 +1 -0
- package/schemas/ds-layout-hints-1.json +1 -0
- package/schemas/ds-layout-hints-1.sha256 +1 -0
|
@@ -0,0 +1,158 @@
|
|
|
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 { type Diagnostic, type DiagnosticCode } from "./diagnostics.js";
|
|
28
|
+
import type { PresentationPin } from "./presentation.js";
|
|
29
|
+
import type { EntityRef } from "./refs.js";
|
|
30
|
+
export declare const DS_LAYOUT_VOCABULARY: "ds-layout-hints@1";
|
|
31
|
+
export declare const DS_LAYOUT_HINTS_SCHEMA_ID: "https://sentropic.dev/schemas/diagram/layout-hints/v1";
|
|
32
|
+
/** Modes the layout engine executes at this version. */
|
|
33
|
+
export declare const DS_LAYOUT_MODES: readonly ["auto-pack", "layered-flow"];
|
|
34
|
+
/** Modes specified for a later vocabulary: refused in `@1`. */
|
|
35
|
+
export declare const DS_LAYOUT_FUTURE_MODES: readonly ["lane-stack", "matrix-grid", "tree"];
|
|
36
|
+
/** Hints specified for a later vocabulary: refused in `@1`. */
|
|
37
|
+
export declare const DS_LAYOUT_FUTURE_HINTS: readonly ["direction", "rotate_labels"];
|
|
38
|
+
/** Spacing overrides and coordinates: refused in every version (one gap law, no authored geometry). */
|
|
39
|
+
export declare const DS_LAYOUT_FORBIDDEN_HINTS: readonly ["cardGapX", "cardGapY", "density", "edge_label_orientation", "gapAfter", "height", "rankGap", "width", "x", "y", "zoneGapX", "zoneGapY"];
|
|
40
|
+
/** Hints read by the measured path only: refused under `layered-flow`. */
|
|
41
|
+
export declare const DS_LAYOUT_MEASURED_HINTS: readonly ["grouping", "grouping_axis", "ordering", "rootOrder", "stretch"];
|
|
42
|
+
export declare const DS_LAYOUT_AXES: readonly ["rows", "columns"];
|
|
43
|
+
export type DsLayoutMode = (typeof DS_LAYOUT_MODES)[number];
|
|
44
|
+
export type DsLayoutFutureMode = (typeof DS_LAYOUT_FUTURE_MODES)[number];
|
|
45
|
+
export type DsLayoutAxis = (typeof DS_LAYOUT_AXES)[number];
|
|
46
|
+
/** A recursive authored group: references and subgroups interleave in `items`. */
|
|
47
|
+
export interface DsLayoutGroup {
|
|
48
|
+
readonly id: string;
|
|
49
|
+
readonly direction: DsLayoutAxis;
|
|
50
|
+
readonly items: readonly (EntityRef | DsLayoutGroup)[];
|
|
51
|
+
readonly stretch?: boolean;
|
|
52
|
+
}
|
|
53
|
+
/** A valid `ds-layout-hints@1` payload. */
|
|
54
|
+
export interface DsLayoutHints {
|
|
55
|
+
readonly vocabulary: typeof DS_LAYOUT_VOCABULARY;
|
|
56
|
+
readonly mode: DsLayoutMode;
|
|
57
|
+
/** Sibling order per semantic parent. */
|
|
58
|
+
readonly ordering?: Readonly<Record<EntityRef, readonly EntityRef[]>>;
|
|
59
|
+
/** Declaration order of the root level. */
|
|
60
|
+
readonly rootOrder?: readonly EntityRef[];
|
|
61
|
+
/** Authored groups. Exclusive with `grouping_axis`. */
|
|
62
|
+
readonly grouping?: readonly DsLayoutGroup[];
|
|
63
|
+
/** Shorthand: one group over the root level, packed along this axis. Exclusive with `grouping`. */
|
|
64
|
+
readonly grouping_axis?: DsLayoutAxis;
|
|
65
|
+
readonly stretch?: boolean;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* What the validator must know about the view to judge a mode. Absent facts
|
|
69
|
+
* never widen a scope: `layered-flow` without a context is refused.
|
|
70
|
+
*/
|
|
71
|
+
export interface LayoutHintsContext {
|
|
72
|
+
/** Profile references of the view's document (`generic@1`, `archimate@2`, …). */
|
|
73
|
+
readonly profiles?: readonly string[];
|
|
74
|
+
/** True when the view carries a typed presentation (`presentation.diagram`). */
|
|
75
|
+
readonly diagramPresentation?: boolean;
|
|
76
|
+
/** The presentation vocabulary of the declaring profile, when it has one (`diagram-notation@1`). */
|
|
77
|
+
readonly presentationVocabulary?: string;
|
|
78
|
+
}
|
|
79
|
+
declare const LAYERED_FLOW_PROFILE = "generic@1";
|
|
80
|
+
/** The canonical JSON Schema of `ds-layout-hints@1`, deeply frozen. Also shipped as `schemas/ds-layout-hints-1.json`. */
|
|
81
|
+
export declare const DS_LAYOUT_HINTS_SCHEMA: Readonly<Record<string, unknown>>;
|
|
82
|
+
/** SHA-256 (64 lowercase hex) of the RFC 8785 bytes of the schema. */
|
|
83
|
+
export declare const DS_LAYOUT_HINTS_SCHEMA_DIGEST: string;
|
|
84
|
+
/** The pin a view declaration references. Equality is equality of the three fields. */
|
|
85
|
+
export declare const DS_LAYOUT_VOCABULARY_PIN: PresentationPin;
|
|
86
|
+
export type LayoutHintsDiagnosticCode = Extract<DiagnosticCode, `layout-${string}`>;
|
|
87
|
+
export interface DsLayoutHintsRules {
|
|
88
|
+
readonly vocabulary: typeof DS_LAYOUT_VOCABULARY;
|
|
89
|
+
/** Admitted modes, and the code raised for everything else. */
|
|
90
|
+
readonly modes: {
|
|
91
|
+
readonly implemented: readonly DsLayoutMode[];
|
|
92
|
+
/** Refused with `layout-mode-not-implemented`. */
|
|
93
|
+
readonly future: readonly DsLayoutFutureMode[];
|
|
94
|
+
/** The vocabulary a future mode waits for. */
|
|
95
|
+
readonly futureVocabulary: "ds-layout-hints@2";
|
|
96
|
+
};
|
|
97
|
+
/** `layered-flow` is admitted only on a view matching every fact below. */
|
|
98
|
+
readonly layeredFlowScope: {
|
|
99
|
+
readonly profiles: readonly [typeof LAYERED_FLOW_PROFILE];
|
|
100
|
+
readonly diagramPresentation: false;
|
|
101
|
+
readonly presentationVocabulary: "absent";
|
|
102
|
+
};
|
|
103
|
+
readonly hints: {
|
|
104
|
+
/** Read by the measured path; refused under `layered-flow` with `layout-hint-out-of-scope`. */
|
|
105
|
+
readonly measuredOnly: readonly string[];
|
|
106
|
+
/** Refused with `layout-hint-not-implemented`. */
|
|
107
|
+
readonly future: readonly string[];
|
|
108
|
+
/** Refused with `layout-hint-forbidden`. */
|
|
109
|
+
readonly forbidden: readonly string[];
|
|
110
|
+
/** Pairs that cannot be authored together (`layout-hint-conflict`). */
|
|
111
|
+
readonly exclusive: readonly (readonly [string, string])[];
|
|
112
|
+
};
|
|
113
|
+
/** Identity rules checked on a structurally valid payload (`layout-hint-conflict`). */
|
|
114
|
+
readonly identity: readonly ["group-id-unique", "group-leaf-once", "ordering-member-single-parent", "ordering-parent-not-member"];
|
|
115
|
+
}
|
|
116
|
+
/** The semantic rules of `ds-layout-hints@1`, as data. Every list equals the matching schema `$defs` enum. */
|
|
117
|
+
export declare const DS_LAYOUT_HINTS_RULES: DsLayoutHintsRules;
|
|
118
|
+
/**
|
|
119
|
+
* Validate a layout-hint payload against `ds-layout-hints@1`: structure and
|
|
120
|
+
* semantics, in one pass. Pure; never throws; an empty result means valid.
|
|
121
|
+
* Diagnostics are sorted by (path, code).
|
|
122
|
+
*
|
|
123
|
+
* What it cannot see: whether a reference exists in the document and whether
|
|
124
|
+
* the members of a group are siblings. Those need the document and stay with
|
|
125
|
+
* the layout engine (`validateHints` in `@sentropic/diagram-canvas`).
|
|
126
|
+
*/
|
|
127
|
+
export declare function validateLayoutHints(value: unknown, context?: LayoutHintsContext): readonly Diagnostic[];
|
|
128
|
+
/** Type guard: true iff `validateLayoutHints` raises nothing. */
|
|
129
|
+
export declare function isLayoutHints(value: unknown, context?: LayoutHintsContext): value is DsLayoutHints;
|
|
130
|
+
/** The engine-side group shape (`LayoutGroup` of `@sentropic/diagram-canvas`), stated structurally. */
|
|
131
|
+
export interface LoweredLayoutGroup {
|
|
132
|
+
readonly id: string;
|
|
133
|
+
readonly direction: DsLayoutAxis;
|
|
134
|
+
readonly items: readonly (EntityRef | LoweredLayoutGroup)[];
|
|
135
|
+
readonly stretch?: boolean;
|
|
136
|
+
}
|
|
137
|
+
/** The engine-side hints (`LayoutHints` of `@sentropic/diagram-canvas`), stated structurally: no gap, no coordinate. */
|
|
138
|
+
export interface LoweredLayoutHints {
|
|
139
|
+
readonly ordering?: Readonly<Record<EntityRef, readonly EntityRef[]>>;
|
|
140
|
+
readonly rootOrder?: readonly EntityRef[];
|
|
141
|
+
readonly grouping?: readonly LoweredLayoutGroup[];
|
|
142
|
+
readonly stretch?: boolean;
|
|
143
|
+
}
|
|
144
|
+
/** The id of the root group `grouping_axis` lowers to. */
|
|
145
|
+
export declare const DS_LAYOUT_ROOT_GROUP_ID: "ds-layout-hints.root";
|
|
146
|
+
/**
|
|
147
|
+
* Lower a VALID payload to the hints the layout engine takes. `mode` selects
|
|
148
|
+
* the engine entry and is not part of the result; `layered-flow` lowers to no
|
|
149
|
+
* hint at all.
|
|
150
|
+
*
|
|
151
|
+
* `grouping_axis` is a shorthand for one group over the root level: it needs
|
|
152
|
+
* the visible root entities, which only the caller knows. Listed roots come
|
|
153
|
+
* first in `rootOrder`, the others after in UTF-16 order (the engine's own
|
|
154
|
+
* rule). Without roots the shorthand lowers to nothing.
|
|
155
|
+
*/
|
|
156
|
+
export declare function lowerLayoutHints(hints: DsLayoutHints, roots?: readonly EntityRef[]): LoweredLayoutHints;
|
|
157
|
+
export {};
|
|
158
|
+
//# sourceMappingURL=layout-hints.d.ts.map
|
|
@@ -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
|