@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
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@ The typed semantic core of the diagram programme: versioned documents and
|
|
|
4
4
|
profiles, views with occurrences, and transactional commands that return their
|
|
5
5
|
logical inverse. No runtime dependency, no DOM, no framework, no renderer.
|
|
6
6
|
|
|
7
|
-
This package is public as `@sentropic/diagram-core`
|
|
7
|
+
This package is public as `@sentropic/diagram-core`, at version `0.3.0`.
|
|
8
8
|
Pin the exact version — never a range, never `latest`. Publication is CI-only
|
|
9
9
|
through `.github/workflows/diagram-core-publish.yml` on tags `diagram-core-v<version>`.
|
|
10
10
|
|
|
@@ -131,10 +131,8 @@ changing the presentation pin. The package includes
|
|
|
131
131
|
[`schemas/diagram-view-schema-3.json`](schemas/diagram-view-schema-3.json) and its
|
|
132
132
|
[canonical SHA-256](schemas/diagram-view-schema-3.sha256):
|
|
133
133
|
`b415c05197692baa5f74ab35e3150ce58079cf9f06201df5e581d222a8d2c0df`.
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
remain `0.1.0`. The release conductor owns that version/pin/lockfile update and
|
|
137
|
-
the owner-confirmed tag; schema inclusion does not certify downstream adoption.
|
|
134
|
+
The `@3` schema shipped with `0.2.0`. `@sentropic/diagram-canvas` pins this
|
|
135
|
+
package by exact version; schema inclusion does not certify downstream adoption.
|
|
138
136
|
|
|
139
137
|
### Commands are transactions
|
|
140
138
|
|
|
@@ -188,6 +186,98 @@ so a migrated document may still be unwritable — for instance when a value tha
|
|
|
188
186
|
failed to convert was a **required** attribute. The report names the element; the
|
|
189
187
|
decision is the host's.
|
|
190
188
|
|
|
189
|
+
## Layout-hint vocabulary (`ds-layout-hints@1`)
|
|
190
|
+
|
|
191
|
+
A view declaration names its layout through one closed vocabulary, authored,
|
|
192
|
+
versioned and pinned here. A consumer (engram's view mechanism) references the
|
|
193
|
+
pin and calls the validator; it never keeps a mode table of its own.
|
|
194
|
+
|
|
195
|
+
```ts
|
|
196
|
+
import { DS_LAYOUT_VOCABULARY_PIN, validateLayoutHints, lowerLayoutHints } from "@sentropic/diagram-core";
|
|
197
|
+
|
|
198
|
+
const layout = { vocabulary: "ds-layout-hints@1", mode: "auto-pack", grouping_axis: "rows" };
|
|
199
|
+
const diagnostics = validateLayoutHints(layout); // [] means valid
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
| Export | What it is |
|
|
203
|
+
|---|---|
|
|
204
|
+
| `DS_LAYOUT_HINTS_SCHEMA` | JSON Schema 2020-12, closed, deeply frozen. Also shipped as [`schemas/ds-layout-hints-1.json`](schemas/ds-layout-hints-1.json) (canonical bytes) with its [SHA-256](schemas/ds-layout-hints-1.sha256). |
|
|
205
|
+
| `DS_LAYOUT_HINTS_RULES` | The semantic rules as frozen data. Every list equals an enum of the schema's `$defs`. |
|
|
206
|
+
| `validateLayoutHints(value, context?)` | Pure, never throws. Structure and semantics in one pass; diagnostics sorted by (path, code). |
|
|
207
|
+
| `DS_LAYOUT_VOCABULARY_PIN` | `PresentationPin` `{ id, version, contentDigest }`. |
|
|
208
|
+
| `lowerLayoutHints(hints, roots?)` | A valid payload lowered to the hints the layout engine takes. |
|
|
209
|
+
|
|
210
|
+
The pin:
|
|
211
|
+
|
|
212
|
+
```
|
|
213
|
+
id https://sentropic.dev/schemas/diagram/layout-hints/v1
|
|
214
|
+
version ds-layout-hints@1
|
|
215
|
+
contentDigest e72fd3f3446e19585b2992071f57c3777685f27087165c932806e12354ced42c
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
`contentDigest` is the SHA-256 (bare 64 lowercase hex) of the RFC 8785 bytes of
|
|
219
|
+
the schema: `sha256Hex(canonicalBytes(DS_LAYOUT_HINTS_SCHEMA))`. The refusal
|
|
220
|
+
classification lives in the schema's `$defs`, so the digest covers it. Any
|
|
221
|
+
change to the schema is `ds-layout-hints@2`; `tests/layout-hints.test.ts`
|
|
222
|
+
recomputes the digest and fails on an edit in place.
|
|
223
|
+
|
|
224
|
+
**Scope rule of `@1`: a payload that validates must render.** The vocabulary
|
|
225
|
+
admits only what the layout engine of `@sentropic/diagram-canvas` executes at
|
|
226
|
+
this version.
|
|
227
|
+
|
|
228
|
+
| `mode` | Engine entry | Admitted on |
|
|
229
|
+
|---|---|---|
|
|
230
|
+
| `auto-pack` | `layoutMeasured` | every view |
|
|
231
|
+
| `layered-flow` | `layoutDocument` | `generic@1` views without a typed presentation, stated through `context` |
|
|
232
|
+
|
|
233
|
+
Hints, read by `auto-pack` only: `ordering`, `rootOrder`, `grouping`
|
|
234
|
+
(recursive groups `{ id, direction, items, stretch? }`), `grouping_axis`
|
|
235
|
+
(`"rows" | "columns"`, a shorthand for one group over the root level, exclusive
|
|
236
|
+
with `grouping`) and `stretch`. `mode` is required: an absent mode is never
|
|
237
|
+
read as `auto-pack`.
|
|
238
|
+
|
|
239
|
+
Refusals are typed, and nothing is coerced to another mode:
|
|
240
|
+
|
|
241
|
+
| Code | Raised when |
|
|
242
|
+
|---|---|
|
|
243
|
+
| `layout-vocabulary-unknown` | `vocabulary` is absent or is not `ds-layout-hints@1`. Nothing else is read. |
|
|
244
|
+
| `layout-hints-invalid` | Structural failure: wrong type, malformed entity reference, missing member. |
|
|
245
|
+
| `layout-mode-not-implemented` | `lane-stack`, `matrix-grid`, `tree`: specified, not executed yet. `details.vocabulary` names `ds-layout-hints@2`. |
|
|
246
|
+
| `layout-mode-unknown` | Any other mode. |
|
|
247
|
+
| `layout-mode-out-of-scope` | `layered-flow` on a view that is not `generic@1`, that carries a typed presentation, that declares a presentation vocabulary, or whose `context` is not stated. |
|
|
248
|
+
| `layout-hint-forbidden` | A spacing override or a coordinate: `density`, `cardGapX`, `cardGapY`, `zoneGapX`, `zoneGapY`, `rankGap`, `gapAfter`, `x`, `y`, `width`, `height`, `edge_label_orientation`. |
|
|
249
|
+
| `layout-hint-not-implemented` | `direction`, `rotate_labels`: specified, not executed yet. |
|
|
250
|
+
| `layout-hint-out-of-scope` | A hint under `layered-flow`, which takes none. |
|
|
251
|
+
| `layout-hint-unknown` | Any other property. |
|
|
252
|
+
| `layout-hint-conflict` | `grouping` with `grouping_axis`; a group id used twice; a leaf placed twice; a member listed twice, ordered under two parents or under itself. |
|
|
253
|
+
|
|
254
|
+
What the validator cannot see: whether a reference exists in the document and
|
|
255
|
+
whether the members of a group are siblings. Both need the document and stay
|
|
256
|
+
with the layout engine (`validateHints` in `@sentropic/diagram-canvas`).
|
|
257
|
+
Whether a view kind takes a layout at all is the declaring grammar's rule.
|
|
258
|
+
|
|
259
|
+
## Notation pin (`diagram-notation@1`)
|
|
260
|
+
|
|
261
|
+
`DIAGRAM_NOTATION_PIN` is exported beside the layout pin:
|
|
262
|
+
|
|
263
|
+
```
|
|
264
|
+
id diagram-notation
|
|
265
|
+
version 1
|
|
266
|
+
contentDigest b4bfa7174a7a53ec23b8a8d7580d6bdfc3bab7f29deb1204aa2e4ce12424909f
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
`contentDigest` is the SHA-256 of the RFC 8785 bytes of
|
|
270
|
+
`{ schema: DIAGRAM_NOTATION_SCHEMA, rules: DIAGRAM_NOTATION_RULES }`. The schema
|
|
271
|
+
(`$id` `engram:diagram-notation-schema/1`) is structural only: closed objects,
|
|
272
|
+
enums, string bounds, required `role`, `nature` and `encoding`, slot shape. The
|
|
273
|
+
rules are frozen data: the role table (nature, `icon`, `kicker`, `variant`,
|
|
274
|
+
`holds`), the variants of each nature, the property list of each encoding,
|
|
275
|
+
slot ownership. Any change to either is `diagram-notation@2`.
|
|
276
|
+
|
|
277
|
+
Not covered: `validateNotation`, `validateViewNotation` and `resolveNotation`.
|
|
278
|
+
This version freezes the vocabulary a consumer pins and ships no executor for
|
|
279
|
+
it; `Profile` has no `notation` member yet.
|
|
280
|
+
|
|
191
281
|
## What this package does not import
|
|
192
282
|
|
|
193
283
|
Nothing. Not one specifier that is not a relative module of its own source, which
|
|
@@ -221,6 +311,10 @@ a test asserts by scanning every file. In particular:
|
|
|
221
311
|
- **Codecs, source text, AST/CST and conversion reports**: GD-M4. Nothing here
|
|
222
312
|
parses, fetches or executes imported content, a URI or markup.
|
|
223
313
|
- **Native BPMN / ArchiMate / UML profiles**: GD-M3. See the skeletons' `notes`.
|
|
314
|
+
- **The notation executor**: `diagram-notation@1` is pinned as data only.
|
|
315
|
+
- **Layout modes `lane-stack`, `matrix-grid`, `tree` and the hints `direction`,
|
|
316
|
+
`rotate_labels`**: refused by `ds-layout-hints@1` until the layout engine
|
|
317
|
+
executes them.
|
|
224
318
|
- **A reference disposition in the delete policy.** The policy governs
|
|
225
319
|
occurrences, relations and ports. An entity a typed reference attribute still
|
|
226
320
|
points at cannot be deleted: the transaction refuses itself on the final state
|
|
@@ -253,6 +347,8 @@ src/hash.ts fnv1a64, dependency-free, non-cryptographic
|
|
|
253
347
|
src/validate.ts every refusal, including the nine named rejected cases
|
|
254
348
|
src/commands.ts 18 commands, transactions, effects, inverses
|
|
255
349
|
src/migrate.ts registered migrations and their reports
|
|
350
|
+
src/layout-hints.ts ds-layout-hints@1: schema, rules, validator, pin, lowering
|
|
351
|
+
src/notation.ts diagram-notation@1: schema, rules, pin (no executor)
|
|
256
352
|
fixtures/ valid documents, a divergent-revision state, a command
|
|
257
353
|
sequence, the nine rejected cases, a 1.0 stored document
|
|
258
354
|
tests/ 10 suites; `refs-nominal.test.ts` is a COMPILER test
|
package/dist/diagnostics.d.ts
CHANGED
|
@@ -29,7 +29,23 @@ export type DiagnosticCode = "erd-missing-pk" | "erd-multiple-pk" | "erd-danglin
|
|
|
29
29
|
/** An extension at validation level `unsupported`: preserved on import, never promoted. */
|
|
30
30
|
| "extension-unsupported" | "malformed-ref" | "duplicate-id" | "record-key-mismatch" | "schema-version-malformed" | "schema-migration-required" | "document-not-an-object" | "unknown-profile" | "profile-not-declared" | "unknown-entity-type" | "unknown-relation-type" | "unknown-port-type" | "flow-types-conflict" | "flow-step-missing" | "flow-step-duplicate" | "flow-branch-overflow" | "flow-scenario-unknown" | "flow-scenario-misused" | "flow-step-end-invalid" | "flow-branch-without-sibling" | "flow-step-gap" | "type-definition-conflict" | "type-definition-reserved" | "type-definition-ambiguous" | "attribute-type-mismatch" | "attribute-required-missing" | "enum-value-not-allowed" | "quantity-unit-not-allowed" | "text-too-long" | "date-not-iso8601" | "unique-attribute-violation" | "endpoint-role-unknown" | "endpoint-cardinality-violation" | "endpoint-target-not-allowed" | "hierarchy-multiple-parents" | "port-direction-not-allowed" | "port-owner-mismatch" | "view-document-mismatch" | "revision-divergence" | "occurrence-endpoint-mismatch" | "value-not-finite" | "value-not-serialisable" | "limit-exceeded"
|
|
31
31
|
/** A hierarchy endpoint targets a foreign-profile entity with no admitted semantic join (M3 §3.2.3). */
|
|
32
|
-
| "endpoint-without-join" | "legend-key-parent-invalid" | "tone-category-unknown" | "text-pattern-mismatch" | "quantity-not-integer" | "quantity-below-min" | "quantity-above-max" | "relationship-matrix-violation" | "multiplicity-invalid" | "stereotype-application-invalid" | "reference-target-type" | "struct-type-unknown" | "struct-field-not-in-schema" | "struct-type-not-allowed" | "supertype-unknown" | "supertype-cycle" | "attribute-conflict" | "abstract-instantiated" | "unknown-command" | "target-already-exists" | "target-missing" | "delete-policy-required" | "delete-policy-refused" | "placement-kind-mismatch" | "inverse-budget-exceeded" | "extension-hash-mismatch" | "extension-source-not-retained" | "view-already-exists"
|
|
32
|
+
| "endpoint-without-join" | "legend-key-parent-invalid" | "tone-category-unknown" | "text-pattern-mismatch" | "quantity-not-integer" | "quantity-below-min" | "quantity-above-max" | "relationship-matrix-violation" | "multiplicity-invalid" | "stereotype-application-invalid" | "reference-target-type" | "struct-type-unknown" | "struct-field-not-in-schema" | "struct-type-not-allowed" | "supertype-unknown" | "supertype-cycle" | "attribute-conflict" | "abstract-instantiated" | "unknown-command" | "target-already-exists" | "target-missing" | "delete-policy-required" | "delete-policy-refused" | "placement-kind-mismatch" | "inverse-budget-exceeded" | "extension-hash-mismatch" | "extension-source-not-retained" | "view-already-exists"
|
|
33
|
+
/** `vocabulary` absent or not the pinned one: nothing else is read. */
|
|
34
|
+
| "layout-vocabulary-unknown"
|
|
35
|
+
/** Structural failure: wrong type, malformed reference, missing required member. */
|
|
36
|
+
| "layout-hints-invalid" | "layout-mode-unknown"
|
|
37
|
+
/** A mode specified for a later vocabulary: refused, never coerced. */
|
|
38
|
+
| "layout-mode-not-implemented"
|
|
39
|
+
/** A mode outside the views it is admitted on. */
|
|
40
|
+
| "layout-mode-out-of-scope" | "layout-hint-unknown"
|
|
41
|
+
/** A spacing override or a coordinate. */
|
|
42
|
+
| "layout-hint-forbidden"
|
|
43
|
+
/** A hint specified for a later vocabulary. */
|
|
44
|
+
| "layout-hint-not-implemented"
|
|
45
|
+
/** A hint the selected mode does not read. */
|
|
46
|
+
| "layout-hint-out-of-scope"
|
|
47
|
+
/** Two authored statements that cannot both hold. */
|
|
48
|
+
| "layout-hint-conflict";
|
|
33
49
|
export type DiagnosticSeverity = "error" | "warning";
|
|
34
50
|
export interface Diagnostic {
|
|
35
51
|
readonly code: DiagnosticCode;
|
package/dist/index.d.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* `@sentropic/diagram-core` - the typed semantic core.
|
|
3
3
|
*
|
|
4
4
|
* No runtime dependency, no DOM, no framework, no renderer. The package is
|
|
5
|
-
*
|
|
5
|
+
* public as `@sentropic/diagram-core`.
|
|
6
6
|
*
|
|
7
7
|
* Read `README.md` for the model, its limits and what is not covered yet.
|
|
8
8
|
*/
|
|
@@ -32,4 +32,6 @@ export * from "./migrate.js";
|
|
|
32
32
|
export { relationBaseType, relationSchema } from "./relation-types.js";
|
|
33
33
|
export { withFlowTypes, validateFlows, flowIndex, type FlowStep, type FlowScenario, type FlowIndex } from "./flows.js";
|
|
34
34
|
export * from "./erd.js";
|
|
35
|
+
export * from "./layout-hints.js";
|
|
36
|
+
export * from "./notation.js";
|
|
35
37
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* `@sentropic/diagram-core` - the typed semantic core.
|
|
3
3
|
*
|
|
4
4
|
* No runtime dependency, no DOM, no framework, no renderer. The package is
|
|
5
|
-
*
|
|
5
|
+
* public as `@sentropic/diagram-core`.
|
|
6
6
|
*
|
|
7
7
|
* Read `README.md` for the model, its limits and what is not covered yet.
|
|
8
8
|
*/
|
|
@@ -32,4 +32,6 @@ export * from "./migrate.js";
|
|
|
32
32
|
export { relationBaseType, relationSchema } from "./relation-types.js";
|
|
33
33
|
export { withFlowTypes, validateFlows, flowIndex } from "./flows.js";
|
|
34
34
|
export * from "./erd.js";
|
|
35
|
+
export * from "./layout-hints.js";
|
|
36
|
+
export * from "./notation.js";
|
|
35
37
|
//# sourceMappingURL=index.js.map
|
|
@@ -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
|