@sentropic/diagram-canvas 0.2.5 → 0.3.1

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.
@@ -23,6 +23,14 @@
23
23
  * 22 px kicker and the 32 px title at their own size (cf. the frozen SVG:
24
24
  * kicker baseline `headerY + 16 + 22`, title `+ 32`, subtitle `+ 22`).
25
25
  */
26
+ /**
27
+ * Versioned card anatomy (DE-1). `"v1"` is the frozen `460 × 200` box every
28
+ * existing view keeps; `"v2"` is the compact `352 × 154` default new views
29
+ * pin. A view pins one anatomy; geometry is selected per box, never patched
30
+ * in place. The engine default stays `"v1"` so unpinned views do not move;
31
+ * `createView` pins `"v2"` for genuinely new views.
32
+ */
33
+ export type DiagramAnatomy = "v1" | "v2";
26
34
  /** Frozen card geometry, in card pixels (spec §5.3, Appendix A). */
27
35
  export declare const CARD_GEOMETRY: {
28
36
  readonly width: 460;
@@ -100,6 +108,112 @@ export declare const CARD_GEOMETRY: {
100
108
  readonly footer: 1;
101
109
  };
102
110
  };
111
+ /**
112
+ * Compact card geometry (`diagram-anatomy/v2`): `352 × 154` with padding
113
+ * `6`, header inset `12`, accent `6`, icon `52` / gap `4`. Type scale is
114
+ * unchanged (`22 / 32 / 24`). Unlisted leaves keep their v1 values. Title is
115
+ * one line first (owner addendum 8): over-long titles report `card-overflow`
116
+ * instead of growing the box. The folded header width is derived, not
117
+ * pinned: `352 − border 2 − padding 6 − toggle 66 − headerText 68 = 210`.
118
+ */
119
+ export declare const CARD_GEOMETRY_V2: {
120
+ readonly width: 352;
121
+ readonly height: 154;
122
+ readonly padding: 6;
123
+ readonly accentWidth: 6;
124
+ readonly headerInset: 12;
125
+ readonly iconSize: 52;
126
+ readonly iconTextGap: 4;
127
+ /** Preserves v1's −2 px body-vs-header offset (`10 − 12 = −2`, matching `14 − 16`). */
128
+ readonly bodyInsetFromBar: 10;
129
+ readonly foldedHeaderTextWidth: 210;
130
+ /** Title on one line first (addendum 8); v1 keeps two lines. */
131
+ readonly allocatedLines: {
132
+ readonly kicker: 1;
133
+ readonly title: 1;
134
+ readonly body: 2;
135
+ readonly footer: 1;
136
+ };
137
+ readonly borderWidth: 2;
138
+ readonly kicker: {
139
+ readonly size: 22;
140
+ readonly weight: 400;
141
+ readonly lineHeight: 1.3;
142
+ readonly letterSpacingEm: 0.04;
143
+ };
144
+ readonly title: {
145
+ readonly size: 32;
146
+ readonly weight: 700;
147
+ readonly lineHeight: 1.3;
148
+ };
149
+ /** Header row → body block. */
150
+ readonly gap: 6;
151
+ readonly body: {
152
+ readonly size: 24;
153
+ readonly weight: 400;
154
+ readonly lineHeight: 1.3;
155
+ };
156
+ /**
157
+ * Edge-label text (BF-6): 18px so one line plus margins fits the 32px
158
+ * gutter cap (22 + 2 × 4 = 30 ≤ 32). Mirrors the
159
+ * `diagramScene.edgeLabelFontSize` / `edgeLabelLineHeight` tokens;
160
+ * additive, frozen card sizes unchanged.
161
+ */
162
+ readonly edgeLabel: {
163
+ readonly size: 18;
164
+ readonly weight: 400;
165
+ readonly lineHeight: number;
166
+ };
167
+ readonly ruleHeight: 1;
168
+ readonly ruleMargin: 4;
169
+ readonly ruleInsetStart: 16;
170
+ readonly ruleInsetEnd: 10;
171
+ readonly footer: {
172
+ readonly size: 24;
173
+ readonly weight: 700;
174
+ readonly lineHeight: 1.3;
175
+ };
176
+ /** Footer text-box bottom → inner edge of the bottom border. */
177
+ readonly footerBottomInset: 9.25;
178
+ /**
179
+ * Title/kicker width reservation when the toggle slot is present
180
+ * (hrpn tints.css `header { padding-right: 66px }`: the 66 px the +/−
181
+ * control needs in the header's inline-end).
182
+ */
183
+ readonly toggleAllocation: 66;
184
+ /** The toggle slot box itself: the 32 px DS IconButton (sm) square. */
185
+ readonly toggleBoxSize: 32;
186
+ readonly toggleInset: 8;
187
+ };
188
+ /** Select the card geometry for a pinned anatomy (default `"v1"`). */
189
+ export declare function anatomyCardGeometry(anatomy: DiagramAnatomy | undefined): typeof CARD_GEOMETRY | typeof CARD_GEOMETRY_V2;
190
+ /**
191
+ * Additive per-entity pin carried alongside a governed `EntityPresentation`
192
+ * (structural, never persisted in the governed fragment): the pinned
193
+ * `diagram-anatomy/v1 | v2` for this box. Absent means `"v1"`.
194
+ */
195
+ export interface AnatomyPinned {
196
+ readonly anatomy?: DiagramAnatomy;
197
+ }
198
+ /**
199
+ * Additive alignment pin (DE-1 step 2), same carrying pattern as
200
+ * `AnatomyPinned`: structural, never persisted in the governed fragment.
201
+ * `"left"` keeps the frozen behaviour; `"center"` centres title and body
202
+ * on both axes. Absent means `"left"`.
203
+ */
204
+ export interface AlignPinned {
205
+ readonly align?: "left" | "center";
206
+ }
207
+ /**
208
+ * Effective header/footer alignment for a card or zone:
209
+ * - Absent `align` is always `"left"` (compact `v2` never centres implicitly).
210
+ * - Explicit `"v1"` anatomy (including `fallback-v1`) keeps the frozen 0.41.5
211
+ * alignment (`"left"`); view-driven centring applies only when a view
212
+ * explicitly asks `align: "center"` on compact `v2`.
213
+ * - Direct unpinned calls (`anatomy === undefined`) preserve 0.41.5's
214
+ * `props.align ?? "left"` behaviour.
215
+ */
216
+ export declare function resolveDiagramAlign(anatomy: DiagramAnatomy | undefined, align: "left" | "center" | undefined): "left" | "center";
103
217
  /**
104
218
  * Edge label typography (DC-2a, tokens `diagramScene.edgeLabelFontSize` /
105
219
  * `diagramScene.edgeLabelLineHeight`): 18 px on a 22 px line box. One line
@@ -139,6 +253,16 @@ export interface CardPresentationInput {
139
253
  readonly categoryRef?: string;
140
254
  /** Neutral status prop: drawn as a dashed border, independent of tint. */
141
255
  readonly proposed?: boolean;
256
+ /**
257
+ * Pinned card anatomy (`diagram-anatomy/v1 | v2`). Absent means `"v1"`;
258
+ * a view pins `"v2"` for the compact box.
259
+ */
260
+ readonly anatomy?: DiagramAnatomy;
261
+ /**
262
+ * Additive alignment pin (DE-1 step 2, `AnatomyPinned` pattern):
263
+ * `"center"` centres title and body on both axes. Absent means `"left"`.
264
+ */
265
+ readonly align?: "left" | "center";
142
266
  }
143
267
  /** Resolved glyph path data (structural twin of the `diagram-icons`
144
268
  * registry record — no import so the barrel never resolves that graph). */
@@ -148,7 +272,7 @@ export interface DiagramGlyphPaths {
148
272
  readonly darkLine?: true;
149
273
  readonly text?: string;
150
274
  readonly severity?: "info";
151
- readonly reason?: "truncated";
275
+ readonly reason?: "truncated" | "fallback-v1";
152
276
  readonly hiddenLength?: number;
153
277
  }
154
278
  export interface DiagramCardToggle {
@@ -197,6 +321,17 @@ export interface DiagramCardProps {
197
321
  * area (§6.2.1).
198
322
  */
199
323
  readonly bodyMode?: "leaf" | "subtitle";
324
+ /**
325
+ * Pinned card anatomy (`diagram-anatomy/v1 | v2`). Absent means `"v1"`;
326
+ * `"v2"` selects the compact `352 × 154` box.
327
+ */
328
+ readonly anatomy?: DiagramAnatomy;
329
+ /**
330
+ * Zone depth surface, set only for zone-collapsed cards (a folded zone
331
+ * keeps its depth background). Leaf cards never set it: their semantic
332
+ * tints are unchanged. Hosts paint the matching zone surface token.
333
+ */
334
+ readonly surface?: ZoneDepthSurface;
200
335
  }
201
336
  export type CardResolveResult = {
202
337
  readonly kind: "card";
@@ -208,6 +343,16 @@ export interface ProjectCardOptions {
208
343
  readonly entityId: string;
209
344
  readonly toggle?: DiagramCardToggle;
210
345
  readonly resolveGlyph?: (name: string) => DiagramGlyphPaths | undefined;
346
+ /**
347
+ * Fallback anatomy when the presentation pins none. Absent means `"v1"`;
348
+ * scene entry points for new views pass `"v2"`.
349
+ */
350
+ readonly anatomy?: DiagramAnatomy;
351
+ /**
352
+ * Fallback alignment when the presentation pins none. Absent means
353
+ * `"left"`; centred scenes pass `"center"`.
354
+ */
355
+ readonly align?: "left" | "center";
211
356
  }
212
357
  /**
213
358
  * Shared `EntityPresentation` → props projection (§4.2), consumed by both
@@ -311,7 +456,7 @@ export interface CardDiagnostic {
311
456
  */
312
457
  readonly text?: string;
313
458
  readonly severity?: "info";
314
- readonly reason?: "truncated";
459
+ readonly reason?: "truncated" | "fallback-v1";
315
460
  readonly hiddenLength?: number;
316
461
  }
317
462
  /** First content diagnostic, for reporting only; renderers retain every slot. */
@@ -344,6 +489,8 @@ export declare function headerSlotGeometry(opts: {
344
489
  readonly hasIcon: boolean;
345
490
  readonly kickerLines: number;
346
491
  readonly titleLines: number;
492
+ /** Icon floor for the block height; defaults to the v1 `70`. */
493
+ readonly iconSize?: number;
347
494
  }): HeaderSlotGeometry;
348
495
  /** Fixed-slot truncation shared by cards and zones (owner A14). */
349
496
  export declare function truncateSlot(text: string, role: "kicker" | "title" | "body" | "footer", width: number, budget: number, measure: CardLineMeasure, report: (diagnostic: {
@@ -414,12 +561,18 @@ export interface CardLayout {
414
561
  readonly y: number;
415
562
  readonly size: number;
416
563
  };
564
+ /** Present when a `v2` compact card overflowed and fell back per box to frozen `v1` (`460 × 200`). */
565
+ readonly anatomyFallback?: "v1";
417
566
  readonly diagnostics: readonly CardDiagnostic[];
418
567
  }
419
568
  /**
420
569
  * Lay out fixed card slots with measured ellipses and a pinned footer.
421
570
  * Informational diagnostics retain the original text and hidden length.
422
571
  * Missing glyphs use the visible unknown icon (owner A2/A11).
572
+ * Compact `v2` cards default to `"left"` alignment (centring only when
573
+ * `align: "center"` is explicitly requested on compact `v2`) and fall back
574
+ * per box to frozen `v1` (`460 × 200`, `"left"` header/footer alignment as in
575
+ * 0.41.5) on overflow instead of dropping slots.
423
576
  */
424
577
  export declare function layoutCard(props: DiagramCardProps, measure: CardLineMeasure): CardLayout;
425
578
  /**
@@ -496,6 +649,91 @@ export declare const ZONE_GEOMETRY: {
496
649
  readonly footer: 1;
497
650
  };
498
651
  };
652
+ /**
653
+ * Compact zone geometry (`diagram-anatomy/v2`): the collapsed zone IS the
654
+ * compact card (`352 × 154`, collapsed subtitle measure `352 − 2 × 24 = 304`,
655
+ * preserving v1's ~86 % width ratio); expanded chrome follows the compact
656
+ * insets (header `12`, icon `52`, gap `4`). Unlisted leaves keep v1 values;
657
+ * type scale unchanged.
658
+ */
659
+ export declare const ZONE_GEOMETRY_V2: {
660
+ readonly headerInset: 12;
661
+ readonly iconSize: 52;
662
+ readonly iconTextGap: 4;
663
+ /**
664
+ * Expanded header text inset for v2: `12 + 52 + 4 + 86 = 154` so the
665
+ * inline-end toggle reserve stays `86 px` (matching v1) instead of
666
+ * growing to `110 px`.
667
+ */
668
+ readonly headerTextInset: 154;
669
+ readonly collapsedWidth: 352;
670
+ readonly collapsedHeight: 154;
671
+ readonly collapsedInset: 12;
672
+ readonly collapsedSubtitleMarginInline: 12;
673
+ readonly allocatedLines: {
674
+ readonly kicker: 1;
675
+ readonly title: 1;
676
+ readonly subtitle: 2;
677
+ readonly footer: 1;
678
+ };
679
+ readonly radius: 0;
680
+ readonly borderWidth: 1.5;
681
+ readonly kicker: {
682
+ readonly size: 22;
683
+ readonly weight: 400;
684
+ readonly lineHeight: 1.3;
685
+ readonly letterSpacingEm: 0.04;
686
+ };
687
+ readonly title: {
688
+ readonly size: 32;
689
+ readonly weight: 700;
690
+ readonly lineHeight: 1.3;
691
+ };
692
+ readonly subtitle: {
693
+ readonly size: 24;
694
+ readonly weight: 400;
695
+ readonly lineHeight: 1.3;
696
+ };
697
+ /** Rendered title → subtitle gap: alias of the card `gap` (§6.4). */
698
+ readonly subtitleGap: 6;
699
+ readonly headerRuleGap: 4;
700
+ readonly contentInsetTop: 16;
701
+ readonly contentInsetBottom: 16;
702
+ readonly contentInsetInline: 16;
703
+ readonly ruleHeight: 1;
704
+ readonly ruleMargin: 4;
705
+ readonly ruleInsetStart: 16;
706
+ readonly ruleInsetEnd: 10;
707
+ readonly footer: {
708
+ readonly size: 24;
709
+ readonly weight: 700;
710
+ readonly lineHeight: 1.3;
711
+ };
712
+ readonly footerBottomInset: 9.25;
713
+ readonly toggleAllocation: 66;
714
+ readonly toggleBoxSize: 32;
715
+ /**
716
+ * Expanded toggle top inset: the frozen SVG places every zone toggle at
717
+ * `y + 10` (flush under the frame's top edge), while the header band
718
+ * starts at `y + 16`.
719
+ */
720
+ readonly toggleTopInset: 8;
721
+ readonly toggleInset: 8;
722
+ };
723
+ /** Select the zone geometry for a pinned anatomy (default `"v1"`). */
724
+ export declare function anatomyZoneGeometry(anatomy: DiagramAnatomy | undefined): typeof ZONE_GEOMETRY | typeof ZONE_GEOMETRY_V2;
725
+ /**
726
+ * Owner addendum 1 — one engine rule for alternating zone backgrounds by
727
+ * nesting depth. Even depths (top level first) paint `surface1`, odd depths
728
+ * paint `surface2`; `startParity` is selectable per scene and flips which
729
+ * parity the top level takes. Depth normalises to a non-negative integer;
730
+ * card semantic tints are untouched (leaf cards never read this rule).
731
+ */
732
+ export type ZoneDepthSurface = "surface1" | "surface2";
733
+ /** Nesting depth of a zone: `0` is the top level. */
734
+ export declare function normalizeZoneDepth(depth: number | undefined): number;
735
+ /** Resolve the depth surface for a zone (default start parity `0`). */
736
+ export declare function zoneDepthSurface(depth: number | undefined, startParity?: 0 | 1): ZoneDepthSurface;
499
737
  /** Centred collapsed-subtitle measure (§6.2.1): 460 − 2 × (16 + 16). */
500
738
  export declare const COLLAPSED_SUBTITLE_MEASURE: number;
501
739
  export interface DiagramZoneToggle {
@@ -506,6 +744,11 @@ export interface DiagramZoneToggle {
506
744
  export interface DiagramZoneProps {
507
745
  readonly containerPadding?: number;
508
746
  readonly autoSize?: boolean;
747
+ /**
748
+ * Pinned zone anatomy (`diagram-anatomy/v1 | v2`). Absent means `"v1"`;
749
+ * `"v2"` selects the compact collapsed `352 × 154` box.
750
+ */
751
+ readonly anatomy?: DiagramAnatomy;
509
752
  readonly entityId: string;
510
753
  readonly kicker?: string;
511
754
  readonly title: string;
@@ -524,6 +767,23 @@ export interface DiagramZoneProps {
524
767
  readonly toggleLabel?: string;
525
768
  /** Owner variant: `"center"` centres every text slot, both states. */
526
769
  readonly align?: "left" | "center";
770
+ /**
771
+ * Nesting depth of the zone (owner addendum 1): `0` is the top level.
772
+ * The frame — and the folded card — paint the depth surface from the
773
+ * engine rule. Absent means `0`.
774
+ */
775
+ readonly depth?: number;
776
+ /**
777
+ * Opt-in informational diagnostic (owner addendum 1): when true, a leaf
778
+ * card on a same-colour zone surface reports `zone-surface-same`. Off by
779
+ * default — a fitting child renders with no diagnostics.
780
+ */
781
+ readonly reportSurfaceSame?: boolean;
782
+ /**
783
+ * Selectable start parity for the depth rule: `1` flips which parity the
784
+ * top level takes. Scene-global; absent means `0`.
785
+ */
786
+ readonly depthParityStart?: 0 | 1;
527
787
  /**
528
788
  * Occurrence box supplied by the host layout (§6.1: the component paints
529
789
  * around the box it is given). Collapsed, the box is the frozen
@@ -546,8 +806,11 @@ export interface ZoneDiagnostic {
546
806
  * `zone-overflow` / `zone-icon-unknown` are the zone's own; a descendant
547
807
  * card or nested zone keeps its own `card-overflow` / `card-icon-unknown`
548
808
  * code with its own `entityId` when `renderZoneSvg` aggregates them.
809
+ * `zone-surface-same` is informational and opt-in (owner addendum 1):
810
+ * a leaf card on a same-colour zone, reported only for explicitly
811
+ * composed children when the zone sets `reportSurfaceSame`.
549
812
  */
550
- readonly code: "zone-overflow" | "zone-icon-unknown" | "card-icon-missing" | "zone-grown" | "card-overflow" | "card-icon-unknown" | "card-grown";
813
+ readonly code: "zone-overflow" | "zone-icon-unknown" | "card-icon-missing" | "zone-grown" | "card-overflow" | "card-icon-unknown" | "card-grown" | "zone-surface-same";
551
814
  readonly slot: string;
552
815
  readonly entityId: string;
553
816
  readonly neededPx: number;
@@ -555,7 +818,7 @@ export interface ZoneDiagnostic {
555
818
  /** Original, unwrapped slot text retained with the diagnostic. */
556
819
  readonly text?: string;
557
820
  readonly severity?: "info";
558
- readonly reason?: "truncated";
821
+ readonly reason?: "truncated" | "fallback-v1";
559
822
  readonly hiddenLength?: number;
560
823
  }
561
824
  export interface ZoneChildSpec {
@@ -578,6 +841,14 @@ export interface ZoneLayout {
578
841
  readonly height: number;
579
842
  };
580
843
  readonly collapsed: boolean;
844
+ /**
845
+ * Owner addendum 1: resolved depth surface (`surface1` at even depths,
846
+ * top level first) and normalised depth. Present only when depth pins
847
+ * are threaded (absent means `surface1` / `0`); hosts paint the matching
848
+ * zone surface token on the frame and on the folded card.
849
+ */
850
+ readonly surface?: ZoneDepthSurface;
851
+ readonly depth?: number;
581
852
  /** Collapsed: the card layout of the folded card (same geometry source). */
582
853
  readonly card?: CardLayout;
583
854
  /** Expanded: header + rule + footer geometry inside the frame. */
@@ -636,6 +907,32 @@ export interface ZonePresentationInput {
636
907
  readonly categoryRef?: string;
637
908
  /** Neutral status prop: drawn as a dashed border, independent of tint. */
638
909
  readonly proposed?: boolean;
910
+ /**
911
+ * Pinned zone anatomy (`diagram-anatomy/v1 | v2`). Absent means `"v1"`.
912
+ */
913
+ readonly anatomy?: DiagramAnatomy;
914
+ /**
915
+ * Additive alignment pin (DE-1 step 2, `AnatomyPinned` pattern):
916
+ * `"center"` centres title and body on both axes. Absent means `"left"`.
917
+ */
918
+ readonly align?: "left" | "center";
919
+ /**
920
+ * Additive depth pins (owner addendum 1, `AnatomyPinned` pattern):
921
+ * nesting depth (`0` top) and selectable start parity. Absent means
922
+ * `0` / `0`; the scene stamps depth from the view groups.
923
+ */
924
+ readonly depth?: number;
925
+ readonly depthParityStart?: 0 | 1;
926
+ }
927
+ /**
928
+ * Additive depth pins (owner addendum 1), same carrying pattern as
929
+ * `AnatomyPinned`: structural, never persisted in the governed fragment.
930
+ * The scene stamps `depth` from the view groups; `depthParityStart`
931
+ * selects which parity the top level takes.
932
+ */
933
+ export interface DepthPinned {
934
+ readonly depth?: number;
935
+ readonly depthParityStart?: 0 | 1;
639
936
  }
640
937
  export type ZoneResolveResult = {
641
938
  readonly kind: "zone";
@@ -645,10 +942,21 @@ export type ZoneResolveResult = {
645
942
  };
646
943
  export interface ProjectZoneOptions {
647
944
  readonly containerPadding?: number;
945
+ /**
946
+ * Fallback anatomy when the presentation pins none. Absent means `"v1"`;
947
+ * scene entry points for new views pass `"v2"`.
948
+ */
949
+ readonly anatomy?: DiagramAnatomy;
648
950
  readonly entityId: string;
649
951
  readonly collapsed: boolean;
650
952
  readonly toggleLabel?: string;
651
953
  readonly align?: "left" | "center";
954
+ /**
955
+ * Fallback depth pins when the presentation pins none. Absent means
956
+ * `0` / `0`; the scene stamps them from the view groups.
957
+ */
958
+ readonly depth?: number;
959
+ readonly depthParityStart?: 0 | 1;
652
960
  readonly x?: number;
653
961
  readonly y?: number;
654
962
  readonly width?: number;