@sentropic/diagram-core 0.4.1 → 0.6.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 CHANGED
@@ -374,3 +374,16 @@ if a compiler reads them. Remove the brand from `Ref<K>` and `check` reports 42
374
374
  and scenarios. Relation refinements resolve through `relationBaseType` and
375
375
  `relationSchema`, preserving inherited roles and constraints. See
376
376
  [the authoring contract and mapping examples](../../docs/DC2C_NUMBERED_FLOWS.md).
377
+
378
+ ## Diagram conventions (DE-2)
379
+
380
+ - **Arrow direction (`source` = initiator of the action):** directed relations
381
+ declare the initiator of the action as the `source` endpoint and the receiver
382
+ as the `target` endpoint. Scenes that declare initiator metadata (via
383
+ `relation.attributes.initiator` or caller-supplied initiator maps) can run the
384
+ opt-in `arrow-direction-convention` lint in `@sentropic/diagram-canvas`.
385
+ - **Zone tags (`kicker`):** bare opaque acronyms without a descriptive label
386
+ should be avoided; acronyms belong with their label (e.g. `"IAM — Identity &
387
+ Access Management"`). `@sentropic/diagram-canvas` provides the opt-in
388
+ non-blocking `zone-tag-opaque-acronym` lint with an allowlist for `DLR-315`
389
+ product kickers.
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Closed connector presentation registries (DE-2): dash patterns, arrowhead
3
+ * kinds (ready for ArchiMate later), and link emphasis.
4
+ *
5
+ * Connectors are selected strictly by closed vocabulary words from the view /
6
+ * presentation layer — never by raw SVG geometry, dash-array strings, marker
7
+ * path data, or colour/width literals. Emphasis is a distinct colour + width
8
+ * axis and is NEVER a dash style (`dashed` continues to mean "proposed").
9
+ *
10
+ * Pure deeply-frozen data, zero runtime dependencies, zero DOM.
11
+ */
12
+ export declare const STROKE_STYLES: readonly ["solid", "dashed", "dotted"];
13
+ export type StrokeStyle = (typeof STROKE_STYLES)[number];
14
+ export interface DashPatternDescriptor {
15
+ readonly style: StrokeStyle;
16
+ /** Semantic meaning of the pattern (`dashed` already means "proposed"). */
17
+ readonly meaning: "default" | "proposed" | "dotted";
18
+ /** World-unit dash/gap fallback pattern when CSS tokens are absent. */
19
+ readonly dashArray: readonly number[];
20
+ /** Component token key under `diagramScene.*`, omitted for solid strokes. */
21
+ readonly tokenName?: "linkDashDashed" | "linkDashDotted";
22
+ }
23
+ export declare const ARROWHEAD_KINDS: readonly ["arrow", "none"];
24
+ export type ArrowheadKind = (typeof ARROWHEAD_KINDS)[number];
25
+ export type CanonicalArrowheadKind = "arrow" | "none";
26
+ export interface ArrowheadDescriptor {
27
+ readonly kind: ArrowheadKind;
28
+ /** Normalized visual head kind (`"arrow"` or `"none"` in `@4`; further heads reserved for N2). */
29
+ readonly canonicalKind: CanonicalArrowheadKind;
30
+ readonly shape: "triangle" | "none";
31
+ readonly fill: "stroke" | "none";
32
+ readonly outlined: false;
33
+ }
34
+ export declare const LINK_EMPHASIS_KINDS: readonly ["default", "emphasis"];
35
+ export type LinkEmphasis = (typeof LINK_EMPHASIS_KINDS)[number];
36
+ export interface LinkEmphasisDescriptor {
37
+ readonly emphasis: LinkEmphasis;
38
+ readonly strokeToken: "edgeStroke" | "linkEmphasisStroke";
39
+ readonly widthToken: "linkStrokeWidth" | "linkEmphasisStrokeWidth";
40
+ /** Emphasis is strictly a colour + width axis, never a dash style. */
41
+ readonly changesDash: false;
42
+ }
43
+ /**
44
+ * Word-addressed connector presentation for a relation occurrence.
45
+ * Every field is a closed registry word; raw geometry is refused.
46
+ */
47
+ export interface RelationPresentation {
48
+ readonly strokeStyle?: StrokeStyle;
49
+ readonly arrowhead?: ArrowheadKind;
50
+ readonly emphasis?: LinkEmphasis;
51
+ }
52
+ export declare const DASH_PATTERN_REGISTRY: Readonly<Record<StrokeStyle, DashPatternDescriptor>>;
53
+ export declare const ARROWHEAD_REGISTRY: Readonly<Record<ArrowheadKind, ArrowheadDescriptor>>;
54
+ export declare const LINK_EMPHASIS_REGISTRY: Readonly<Record<LinkEmphasis, LinkEmphasisDescriptor>>;
55
+ export declare function isStrokeStyle(value: unknown): value is StrokeStyle;
56
+ export declare function isArrowheadKind(value: unknown): value is ArrowheadKind;
57
+ export declare function isLinkEmphasis(value: unknown): value is LinkEmphasis;
58
+ export declare function resolveDashPattern(style: StrokeStyle | undefined): DashPatternDescriptor;
59
+ export declare function resolveDashPattern(style: string | undefined): DashPatternDescriptor | undefined;
60
+ export declare function resolveArrowhead(kind: ArrowheadKind | undefined): ArrowheadDescriptor;
61
+ export declare function resolveArrowhead(kind: string | undefined): ArrowheadDescriptor | undefined;
62
+ export declare function resolveLinkEmphasis(emphasis: LinkEmphasis | undefined): LinkEmphasisDescriptor;
63
+ export declare function resolveLinkEmphasis(emphasis: string | undefined): LinkEmphasisDescriptor | undefined;
64
+ //# sourceMappingURL=connector-registry.d.ts.map
@@ -0,0 +1,98 @@
1
+ /**
2
+ * Closed connector presentation registries (DE-2): dash patterns, arrowhead
3
+ * kinds (ready for ArchiMate later), and link emphasis.
4
+ *
5
+ * Connectors are selected strictly by closed vocabulary words from the view /
6
+ * presentation layer — never by raw SVG geometry, dash-array strings, marker
7
+ * path data, or colour/width literals. Emphasis is a distinct colour + width
8
+ * axis and is NEVER a dash style (`dashed` continues to mean "proposed").
9
+ *
10
+ * Pure deeply-frozen data, zero runtime dependencies, zero DOM.
11
+ */
12
+ export const STROKE_STYLES = ["solid", "dashed", "dotted"];
13
+ export const ARROWHEAD_KINDS = ["arrow", "none"];
14
+ export const LINK_EMPHASIS_KINDS = ["default", "emphasis"];
15
+ function deepFreeze(value) {
16
+ if (value === null || typeof value !== "object" || Object.isFrozen(value))
17
+ return value;
18
+ for (const child of Object.values(value))
19
+ deepFreeze(child);
20
+ return Object.freeze(value);
21
+ }
22
+ export const DASH_PATTERN_REGISTRY = deepFreeze({
23
+ solid: {
24
+ style: "solid",
25
+ meaning: "default",
26
+ dashArray: [],
27
+ },
28
+ dashed: {
29
+ style: "dashed",
30
+ meaning: "proposed",
31
+ dashArray: [8, 6],
32
+ tokenName: "linkDashDashed",
33
+ },
34
+ dotted: {
35
+ style: "dotted",
36
+ meaning: "dotted",
37
+ dashArray: [2, 5],
38
+ tokenName: "linkDashDotted",
39
+ },
40
+ });
41
+ export const ARROWHEAD_REGISTRY = deepFreeze({
42
+ arrow: {
43
+ kind: "arrow",
44
+ canonicalKind: "arrow",
45
+ shape: "triangle",
46
+ fill: "stroke",
47
+ outlined: false,
48
+ },
49
+ none: {
50
+ kind: "none",
51
+ canonicalKind: "none",
52
+ shape: "none",
53
+ fill: "none",
54
+ outlined: false,
55
+ },
56
+ });
57
+ export const LINK_EMPHASIS_REGISTRY = deepFreeze({
58
+ default: {
59
+ emphasis: "default",
60
+ strokeToken: "edgeStroke",
61
+ widthToken: "linkStrokeWidth",
62
+ changesDash: false,
63
+ },
64
+ emphasis: {
65
+ emphasis: "emphasis",
66
+ strokeToken: "linkEmphasisStroke",
67
+ widthToken: "linkEmphasisStrokeWidth",
68
+ changesDash: false,
69
+ },
70
+ });
71
+ const STROKE_STYLE_SET = new Set(STROKE_STYLES);
72
+ const ARROWHEAD_KIND_SET = new Set(ARROWHEAD_KINDS);
73
+ const LINK_EMPHASIS_SET = new Set(LINK_EMPHASIS_KINDS);
74
+ export function isStrokeStyle(value) {
75
+ return typeof value === "string" && STROKE_STYLE_SET.has(value);
76
+ }
77
+ export function isArrowheadKind(value) {
78
+ return typeof value === "string" && ARROWHEAD_KIND_SET.has(value);
79
+ }
80
+ export function isLinkEmphasis(value) {
81
+ return typeof value === "string" && LINK_EMPHASIS_SET.has(value);
82
+ }
83
+ export function resolveDashPattern(style) {
84
+ if (style === undefined)
85
+ return DASH_PATTERN_REGISTRY.solid;
86
+ return isStrokeStyle(style) ? DASH_PATTERN_REGISTRY[style] : undefined;
87
+ }
88
+ export function resolveArrowhead(kind) {
89
+ if (kind === undefined)
90
+ return ARROWHEAD_REGISTRY.arrow;
91
+ return isArrowheadKind(kind) ? ARROWHEAD_REGISTRY[kind] : undefined;
92
+ }
93
+ export function resolveLinkEmphasis(emphasis) {
94
+ if (emphasis === undefined)
95
+ return LINK_EMPHASIS_REGISTRY.default;
96
+ return isLinkEmphasis(emphasis) ? LINK_EMPHASIS_REGISTRY[emphasis] : undefined;
97
+ }
98
+ //# sourceMappingURL=connector-registry.js.map
package/dist/fold.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { StrokeStyle } from "./connector-registry.js";
1
2
  import type { SemanticDocument } from "./document.js";
2
3
  import type { ProfileRegistry } from "./profile.js";
3
4
  import type { RelationOccurrence, ViewDocument } from "./view.js";
@@ -101,7 +102,7 @@ export interface ActiveSummary {
101
102
  interface SummaryCandidate {
102
103
  readonly occurrence: OccurrenceRef;
103
104
  readonly relation: RelationRef;
104
- readonly style: "solid" | "dashed";
105
+ readonly style: StrokeStyle;
105
106
  }
106
107
  export interface SummaryResolutionOptions {
107
108
  /** Evaluated filter exclusions feeding aggregate resolution (§4.4.6). */
@@ -110,7 +111,7 @@ export interface SummaryResolutionOptions {
110
111
  readonly registry: ProfileRegistry;
111
112
  }
112
113
  /** Binary candidate occurrences whose oriented endpoints lie in the two scopes. */
113
- export declare function summaryCandidates(view: ViewDocument, document: SemanticDocument, registry: ProfileRegistry, source: OccurrenceRef, target: OccurrenceRef, style: "solid" | "dashed"): SummaryCandidate[];
114
+ export declare function summaryCandidates(view: ViewDocument, document: SemanticDocument, registry: ProfileRegistry, source: OccurrenceRef, target: OccurrenceRef, style: StrokeStyle): SummaryCandidate[];
114
115
  export type SummaryCheck = "summary-constituents-mismatch" | "summary-duplicate-key" | "summary-occurrence-ambiguous" | "summary-active-key-conflict";
115
116
  export interface SummaryIssue {
116
117
  readonly id: string;
package/dist/fold.js CHANGED
@@ -205,6 +205,8 @@ export function projectRelationOccurrences(sourceView, document, collapsed) {
205
205
  ? {}
206
206
  : { waypoints: occurrence.waypoints.map((point) => ({ ...point })) }),
207
207
  ...(occurrence.strokeStyle === undefined ? {} : { strokeStyle: occurrence.strokeStyle }),
208
+ ...(occurrence.arrowhead === undefined ? {} : { arrowhead: occurrence.arrowhead }),
209
+ ...(occurrence.emphasis === undefined ? {} : { emphasis: occurrence.emphasis }),
208
210
  };
209
211
  continue;
210
212
  }
@@ -240,6 +242,8 @@ export function projectRelationOccurrences(sourceView, document, collapsed) {
240
242
  ? {}
241
243
  : { waypoints: occurrence.waypoints.map((point) => ({ ...point })) }),
242
244
  ...(occurrence.strokeStyle === undefined ? {} : { strokeStyle: occurrence.strokeStyle }),
245
+ ...(occurrence.arrowhead === undefined ? {} : { arrowhead: occurrence.arrowhead }),
246
+ ...(occurrence.emphasis === undefined ? {} : { emphasis: occurrence.emphasis }),
243
247
  };
244
248
  }
245
249
  return relationOccurrences;
package/dist/index.d.ts CHANGED
@@ -14,6 +14,7 @@ export * from "./bindings.js";
14
14
  export * from "./multiplicity.js";
15
15
  export * from "./archimate-cases.js";
16
16
  export * from "./profile-migrations.js";
17
+ export * from "./connector-registry.js";
17
18
  export * from "./presentation.js";
18
19
  export * from "./presentation-relations.js";
19
20
  export * from "./presentation-apply.js";
@@ -33,5 +34,6 @@ export { relationBaseType, relationSchema } from "./relation-types.js";
33
34
  export { withFlowTypes, validateFlows, flowIndex, type FlowStep, type FlowScenario, type FlowIndex } from "./flows.js";
34
35
  export * from "./erd.js";
35
36
  export * from "./layout-hints.js";
37
+ export * from "./layout-hints-v2.js";
36
38
  export * from "./notation.js";
37
39
  //# sourceMappingURL=index.d.ts.map
package/dist/index.js CHANGED
@@ -14,6 +14,7 @@ export * from "./bindings.js";
14
14
  export * from "./multiplicity.js";
15
15
  export * from "./archimate-cases.js";
16
16
  export * from "./profile-migrations.js";
17
+ export * from "./connector-registry.js";
17
18
  export * from "./presentation.js";
18
19
  export * from "./presentation-relations.js";
19
20
  export * from "./presentation-apply.js";
@@ -33,5 +34,6 @@ export { relationBaseType, relationSchema } from "./relation-types.js";
33
34
  export { withFlowTypes, validateFlows, flowIndex } from "./flows.js";
34
35
  export * from "./erd.js";
35
36
  export * from "./layout-hints.js";
37
+ export * from "./layout-hints-v2.js";
36
38
  export * from "./notation.js";
37
39
  //# sourceMappingURL=index.js.map
@@ -0,0 +1,204 @@
1
+ import { type Diagnostic } from "./diagnostics.js";
2
+ import { type DsLayoutHints, type LayoutHintsContext, type LoweredLayoutHints } from "./layout-hints.js";
3
+ import type { EntityRef } from "./refs.js";
4
+ export declare const DS_LAYOUT_V2_VOCABULARY = "ds-layout-hints@2";
5
+ export declare const DS_LAYOUT_HINTS_V2_SCHEMA_ID = "https://sentropic.dev/schemas/diagram/layout-hints/v2";
6
+ declare const alignments: readonly ["start", "center", "end", "stretch"];
7
+ declare const sides: readonly ["start", "end"];
8
+ declare const axes: readonly ["row", "column"];
9
+ declare const aspects: readonly ["16:9", "free"];
10
+ declare const fanModes: readonly ["comb", "separate"];
11
+ declare const legends: readonly ["right", "bottom", "free-cell", "none"];
12
+ export type LayoutCellAlign = (typeof alignments)[number];
13
+ export interface LayoutBand {
14
+ readonly id: string;
15
+ readonly items: readonly EntityRef[];
16
+ }
17
+ export interface LayoutPeripheralColumn {
18
+ readonly id: string;
19
+ readonly side: (typeof sides)[number];
20
+ readonly items: readonly EntityRef[];
21
+ readonly from_band?: string;
22
+ }
23
+ export interface LayoutCell {
24
+ readonly column?: string;
25
+ readonly to_column?: string;
26
+ readonly to_band?: string;
27
+ readonly justify?: LayoutCellAlign;
28
+ readonly align?: LayoutCellAlign;
29
+ }
30
+ export interface LayoutGrid {
31
+ readonly stage_columns?: readonly string[] | "inherit";
32
+ readonly transverse_bands: readonly LayoutBand[];
33
+ readonly peripheral_columns?: readonly LayoutPeripheralColumn[];
34
+ readonly cells?: Readonly<Partial<Record<EntityRef, LayoutCell>>>;
35
+ }
36
+ export interface LayoutStack {
37
+ readonly axis: (typeof axes)[number];
38
+ readonly align?: LayoutCellAlign;
39
+ }
40
+ export interface LayoutComposition {
41
+ readonly grids: {
42
+ readonly root: LayoutGrid;
43
+ } & Readonly<Partial<Record<EntityRef, LayoutGrid>>>;
44
+ readonly stacks: Readonly<Partial<Record<EntityRef, LayoutStack>>>;
45
+ readonly aspect: (typeof aspects)[number];
46
+ readonly fanIn: (typeof fanModes)[number];
47
+ readonly fanOut: (typeof fanModes)[number];
48
+ /** "host" uses the scene option and its default. */
49
+ readonly legend: (typeof legends)[number] | "host";
50
+ }
51
+ type ComposedLayoutHints = Pick<DsLayoutHints, "rootOrder" | "ordering"> & Partial<LayoutComposition> & {
52
+ readonly mode: "stage-columns";
53
+ readonly grids: LayoutComposition["grids"];
54
+ readonly legend?: (typeof legends)[number];
55
+ };
56
+ export type DsLayoutHintsV2 = {
57
+ readonly vocabulary: typeof DS_LAYOUT_V2_VOCABULARY;
58
+ } & (Omit<DsLayoutHints, "vocabulary"> | ComposedLayoutHints);
59
+ export interface LoweredLayoutHintsV2 extends LoweredLayoutHints {
60
+ readonly composition?: LayoutComposition;
61
+ }
62
+ export declare const DS_LAYOUT_HINTS_V2_SCHEMA: {
63
+ dependentSchemas: {
64
+ grouping: {
65
+ properties: {
66
+ grouping_axis: boolean;
67
+ };
68
+ };
69
+ };
70
+ allOf: {
71
+ if: {
72
+ properties: {
73
+ mode: {
74
+ const: "auto-pack" | "layered-flow" | "stage-columns";
75
+ };
76
+ };
77
+ required: string[];
78
+ };
79
+ then: {
80
+ required?: string[];
81
+ properties: {
82
+ grids?: {
83
+ $ref: string;
84
+ };
85
+ };
86
+ };
87
+ }[];
88
+ $defs: {
89
+ mode: {
90
+ enum: readonly ["auto-pack", "layered-flow", "stage-columns"];
91
+ };
92
+ forbiddenHint: {
93
+ enum: readonly ["cardGapX", "cardGapY", "density", "edge_label_orientation", "gapAfter", "height", "rankGap", "width", "x", "y", "zoneGapX", "zoneGapY", "anchor", "bottom", "dc", "dx", "dy", "gap", "gutter", "labelAt", "label_at", "left", "margin", "offset", "padding", "pin", "pins", "points", "position", "right", "scale", "size", "top", "via", "waypoints", "zoom"];
94
+ };
95
+ futureHint: {
96
+ enum: readonly ["compared_panels", "loop_corridor", "foldable", "direction", "rotate_labels"];
97
+ };
98
+ futureBandValue: {
99
+ enum: string[];
100
+ };
101
+ futureMode: {
102
+ enum: readonly ["tree"];
103
+ };
104
+ supersededMode: {
105
+ enum: readonly ["lane-stack", "matrix-grid"];
106
+ };
107
+ modeScope: {
108
+ [k: string]: {
109
+ enum: readonly ["grids", "stacks", "aspect", "fanIn", "fanOut", "legend"] | readonly ["grouping", "grouping_axis", "stretch"] | readonly ["grouping", "grouping_axis", "ordering", "rootOrder", "stretch", "grids", "stacks", "aspect", "fanIn", "fanOut", "legend"];
110
+ };
111
+ };
112
+ id: {
113
+ type: string;
114
+ pattern: string;
115
+ };
116
+ align: {
117
+ enum: readonly ["start", "center", "end", "stretch"];
118
+ };
119
+ grids: {
120
+ properties: {
121
+ root: {
122
+ $ref: string;
123
+ };
124
+ };
125
+ required: string[];
126
+ type: string;
127
+ patternProperties: {
128
+ "^entity:[A-Za-z0-9][A-Za-z0-9._-]*$": {
129
+ $ref: string;
130
+ };
131
+ };
132
+ additionalProperties: boolean;
133
+ };
134
+ grid: {
135
+ additionalProperties: boolean;
136
+ required?: readonly string[];
137
+ type: string;
138
+ properties: Record<string, unknown>;
139
+ };
140
+ band: {
141
+ additionalProperties: boolean;
142
+ required?: readonly string[];
143
+ type: string;
144
+ properties: Record<string, unknown>;
145
+ };
146
+ peripheralColumn: {
147
+ additionalProperties: boolean;
148
+ required?: readonly string[];
149
+ type: string;
150
+ properties: Record<string, unknown>;
151
+ };
152
+ cell: {
153
+ additionalProperties: boolean;
154
+ required?: readonly string[];
155
+ type: string;
156
+ properties: Record<string, unknown>;
157
+ };
158
+ stack: {
159
+ additionalProperties: boolean;
160
+ required?: readonly string[];
161
+ type: string;
162
+ properties: Record<string, unknown>;
163
+ };
164
+ };
165
+ additionalProperties: boolean;
166
+ required?: readonly string[];
167
+ type: string;
168
+ properties: Record<string, unknown>;
169
+ $schema: string;
170
+ $id: string;
171
+ title: string;
172
+ };
173
+ export declare const DS_LAYOUT_HINTS_V2_SCHEMA_DIGEST: string;
174
+ export declare const DS_LAYOUT_V2_VOCABULARY_PIN: {
175
+ id: string;
176
+ version: string;
177
+ contentDigest: string;
178
+ };
179
+ export declare const DS_LAYOUT_HINTS_V2_RULES: {
180
+ vocabulary: string;
181
+ modes: {
182
+ implemented: readonly ["auto-pack", "layered-flow", "stage-columns"];
183
+ future: readonly ["tree"];
184
+ superseded: readonly ["lane-stack", "matrix-grid"];
185
+ futureVocabulary: string;
186
+ };
187
+ hints: {
188
+ forbidden: readonly ["cardGapX", "cardGapY", "density", "edge_label_orientation", "gapAfter", "height", "rankGap", "width", "x", "y", "zoneGapX", "zoneGapY", "anchor", "bottom", "dc", "dx", "dy", "gap", "gutter", "labelAt", "label_at", "left", "margin", "offset", "padding", "pin", "pins", "points", "position", "right", "scale", "size", "top", "via", "waypoints", "zoom"];
189
+ future: readonly ["compared_panels", "loop_corridor", "foldable", "direction", "rotate_labels"];
190
+ futureBandValues: string[];
191
+ };
192
+ modeScope: {
193
+ readonly "auto-pack": readonly ["grids", "stacks", "aspect", "fanIn", "fanOut", "legend"];
194
+ readonly "layered-flow": readonly ["grouping", "grouping_axis", "ordering", "rootOrder", "stretch", "grids", "stacks", "aspect", "fanIn", "fanOut", "legend"];
195
+ readonly "stage-columns": readonly ["grouping", "grouping_axis", "stretch"];
196
+ };
197
+ };
198
+ /** Validate the closed @2 vocabulary, then verify identities and span occupancy. */
199
+ export declare function validateLayoutHintsV2(input: unknown, context?: LayoutHintsContext): readonly Diagnostic[];
200
+ export declare function validateAnyLayoutHints(value: unknown, context?: LayoutHintsContext): readonly Diagnostic[];
201
+ /** Lower a validated @2 declaration. Legacy modes share the @1 lowering. */
202
+ export declare function lowerLayoutHintsV2(hints: DsLayoutHintsV2, roots?: readonly EntityRef[]): LoweredLayoutHintsV2;
203
+ export {};
204
+ //# sourceMappingURL=layout-hints-v2.d.ts.map