@kekonic/diagrams-layout 1.0.0-rc.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kekonic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @kekonic/diagrams-layout
+
+Measurement and ELK layered layout for KDiagram diagrams.
+
+## Scope
+
+- Shared `TextMeasurer` (bundled Inter metrics for CLI/browser parity)
+- Node/group measurement from `GraphModel`
+- ELK layered layout + orthogonal edge paths (`elk-layered-v1` / `elk-orthogonal-v1`)
+- Region arrange (`stack` / `row` / `grid`) with obstacle-aware stubs
+- Topology helpers and silhouette endpoint snap
+
+## Install
+
+```bash
+pnpm add @kekonic/diagrams-layout
+```
+
+Most apps should use `@kekonic/diagrams` instead and call `KDiagram.layout` / `renderToSvg`.
+
+## Related
+
+- Routing post-process: `@kekonic/diagrams-routing`
+- Geometry / ports: `@kekonic/diagrams-geometry`
+- Pipeline boundaries: [`docs/architecture/pipeline.md`](../../docs/architecture/pipeline.md)

package/dist/index.d.mts

@@ -0,0 +1,272 @@
+import { BoxPadding, Direction, GraphModel, GraphNode, LayoutOptions, Point, Rect, SequenceFragment, SequenceIR, TableColumn } from "@kekonic/diagrams-core";
+
+//#region src/measure/text-measurer.d.ts
+/** Shared font metrics — browser canvas and approximate server fallback. */
+type TextStyle = {
+  fontSize: number;
+  fontFamily: string;
+  fontWeight?: string;
+};
+type TextMetrics = {
+  width: number;
+  height: number;
+  ascent: number;
+  descent: number;
+};
+type WrapOptions = {
+  maxWidth: number;
+  style: TextStyle;
+};
+type WrappedText = {
+  lines: string[];
+  width: number;
+  height: number;
+};
+type TextMeasurer = {
+  measureText(text: string, style: TextStyle): TextMetrics;
+  wrapText(text: string, options: WrapOptions): WrappedText;
+};
+declare const DEFAULT_FONT_FAMILY = "\"Inter\", \"Segoe UI\", system-ui, sans-serif";
+declare function measurerUsedApproximationFallback(): boolean;
+declare function createCanvasMeasurer(canvas?: HTMLCanvasElement): TextMeasurer;
+declare function resetDefaultMeasurer(): void;
+declare const defaultMeasurer: TextMeasurer;
+//#endregion
+//#region src/measure/measure.d.ts
+type MeasuredNode = {
+  nodeId: string;
+  width: number;
+  height: number;
+  contentBox: Rect;
+  labelLines: string[]; /** C4 technology tag lines (usually one). */
+  technologyLines?: string[]; /** Wrapped C4 / architecture description body. */
+  descriptionLines?: string[];
+};
+type MeasureOptions = {
+  /** Reserve vertical space for kind subtitles when presentation opts into them. */reserveKindSubtitles?: boolean;
+};
+type MeasureResult = {
+  nodes: MeasuredNode[];
+  measureMs: number;
+};
+/** Left icon column width for card nodes (matches SVG placement). */
+declare function cardIconColumnWidth(iconId: string, scale?: number): number;
+declare function measureGraph(graph: GraphModel, measurer?: TextMeasurer, options?: MeasureOptions): MeasureResult;
+//#endregion
+//#region src/layout/sequence/layout-sequence.d.ts
+type SequenceLayoutRouteResult = {
+  layout: LayoutResult;
+  edges: LayoutEdgePath[];
+  routerAlgorithm: string;
+};
+declare const SEQUENCE_LAYOUT_ALGORITHM = "sequence-v1";
+declare const SEQUENCE_ROUTER_ALGORITHM = "sequence-direct-v1";
+type SequenceLifelineLayout = {
+  participantId: string; /** Vertical line from below header to diagram bottom. */
+  x: number;
+  y0: number;
+  y1: number;
+};
+type SequenceActivationLayout = {
+  id: string;
+  participantId: string;
+  startOrder: number;
+  endOrder: number;
+  bounds: Rect;
+};
+type SequenceFragmentLayout = {
+  id: string;
+  operator: SequenceFragment["operator"];
+  label?: string;
+  styleRefs: string[];
+  unresolvedVars: Record<string, string>;
+  bounds: Rect;
+  startOrder: number;
+  endOrder: number; /** Horizontal separators between operands (alternate/else, parallel/and). */
+  separators: number[];
+  operandLabels: Array<{
+    text: string;
+    x: number;
+    y: number;
+  }>; /** Per-operand tint bands (success vs danger, etc.). */
+  operandBands: Array<{
+    startOrder: number;
+    endOrder: number;
+    styleRefs: string[];
+    bounds: Rect;
+  }>;
+};
+type SequenceNoteLayout = {
+  id: string;
+  bounds: Rect;
+  text: string;
+};
+type SequenceDividerLayout = {
+  id: string;
+  y: number;
+  x0: number;
+  x1: number;
+  label?: string;
+};
+type SequenceMessageLayout = {
+  messageId: string;
+  kind: NonNullable<SequenceIR["messages"][number]["kind"]>;
+  points: Point[];
+  label?: string;
+  labelCenter?: Point;
+  number?: number;
+};
+type SequenceLayoutArtifacts = {
+  lifelines: SequenceLifelineLayout[];
+  activations: SequenceActivationLayout[];
+  fragments: SequenceFragmentLayout[];
+  notes: SequenceNoteLayout[];
+  dividers: SequenceDividerLayout[];
+  messages: SequenceMessageLayout[];
+};
+/**
+ * Time-axis sequence layout: participants on X, messages ordered on Y.
+ */
+declare function layoutSequence(graph: GraphModel, measured: MeasuredNode[], options?: LayoutOptions): SequenceLayoutRouteResult;
+declare function isSequenceGraph(graph: GraphModel): boolean;
+//#endregion
+//#region src/layout/types.d.ts
+type LaidOutNode = {
+  nodeId: string;
+  bounds: Rect;
+  rank: number;
+  order: number;
+};
+type LaidOutGroup = {
+  groupId: string;
+  bounds: Rect;
+  labelBox: Rect;
+  padding: BoxPadding;
+};
+/** Orthogonal polyline produced by ELK for one edge. */
+type LayoutEdgePath = {
+  edgeId: string;
+  points: Point[];
+};
+/** Edge label position from ELK (absolute). */
+type LayoutEdgeLabel = {
+  edgeId: string;
+  text: string;
+  bounds: Rect;
+  anchor: Point;
+};
+/**
+ * ELK owns node placement and edge geometry together.
+ * `edgePaths` / `edgeLabels` come from the same layout call as `nodes`/`groups`.
+ * Sequence diagrams attach optional `sequence` artifacts (lifelines, activations, …).
+ */
+type LayoutResult = {
+  nodes: LaidOutNode[];
+  groups: LaidOutGroup[];
+  edgePaths: LayoutEdgePath[];
+  edgeLabels: LayoutEdgeLabel[];
+  direction: Direction;
+  algorithmVersion: string;
+  layoutMs: number;
+  width: number;
+  height: number; /** Present when layout ran the sequence time-axis engine. */
+  sequence?: SequenceLayoutArtifacts;
+};
+//#endregion
+//#region src/layout-from-graph.d.ts
+declare function layoutFromGraph(graph: GraphModel, layoutOpts?: LayoutOptions): Promise<LayoutResult>;
+//#endregion
+//#region src/measure/browser-font.d.ts
+/** Load bundled Inter via FontFace so canvas metrics match CLI opentype measurer. */
+declare function browserFontsReady(): boolean;
+declare function ensureBrowserFonts(fontUrl: string): Promise<void>;
+//#endregion
+//#region src/measure/table-measure.d.ts
+/** Dense ERD chrome — flatter and tighter than architecture cards. */
+declare const TABLE_PAD_X = 10;
+declare const TABLE_HEADER_H = 28;
+declare const TABLE_ROW_H = 20;
+/** Badge chip width — must match SVG render. */
+declare const TABLE_BADGE_W = 18;
+declare const TABLE_BADGE_GAP = 3;
+/**
+ * Fixed key-badge gutter (fits PK+FK, or empty spacer).
+ * Names always start at padX + KEY_COL regardless of how many key chips are present.
+ */
+declare const TABLE_KEY_COL: number;
+declare const TABLE_RX = 4;
+/** Gap between type / NN / note in the right-side attrs cluster. */
+declare const TABLE_ATTR_GAP = 6;
+declare function isErdTableNode(node: GraphNode): boolean;
+declare function columnAnchorY(tableTop: number, rowIndex: number, scale?: number): number;
+/** SQL-ish type only — muted mono on the right (flags/notes are separate). */
+declare function columnTypeLabel(col: TableColumn): string;
+/** Enum / comment secondary text — never joined into the type with bullets. */
+declare function columnNoteLabel(col: TableColumn): string;
+/** Key chips only (PK/FK/UK) — fixed left gutter; NN is not a key. */
+declare function tableKeyBadges(col: TableColumn): string[];
+//#endregion
+//#region src/layout/elk/layout-with-elk.d.ts
+type ElkLayoutAndRouteResult = {
+  layout: LayoutResult; /** Same as `layout.edgePaths`. */
+  edges: LayoutEdgePath[];
+  routerAlgorithm: string;
+};
+/**
+ * Layout + orthogonal edge routes via ELK (elkjs API; elk-rs drop-in when published).
+ */
+declare function layoutAndRouteWithElk(graph: GraphModel, measured: MeasuredNode[], options?: LayoutOptions): Promise<ElkLayoutAndRouteResult>;
+//#endregion
+//#region src/layout/elk/elk-engine.d.ts
+declare const ELK_LAYOUT_ALGORITHM = "elk-layered-v1";
+declare const ELK_ROUTER_ALGORITHM = "elk-orthogonal-v1";
+//#endregion
+//#region src/layout/group-bounds.d.ts
+declare const GROUP_ICON_SIZE = 14;
+declare const GROUP_ICON_GAP = 6;
+declare function computeGroupBounds(graph: GraphModel, laidOut: LaidOutNode[]): LaidOutGroup[];
+//#endregion
+//#region src/layout/erd-snap.d.ts
+/**
+ * Snap ERD edge endpoints to column midlines while preserving orthogonal routes.
+ * Runs after ELK; before crossing treatment / trim.
+ */
+declare function snapErdEdgeEndpoints(graph: GraphModel, layout: LayoutResult, edgePaths: LayoutEdgePath[]): LayoutEdgePath[];
+declare function erdRelationshipLabel(edge: {
+  fromColumn?: string;
+  toColumn?: string;
+  label?: string;
+}): string | undefined;
+//#endregion
+//#region src/layout/attach-endpoints.d.ts
+/**
+ * Replace path termini with shape-perimeter hits.
+ * Attach rays are forced orthogonal; a corner is inserted when needed so the
+ * final stub never becomes a diagonal shortcut.
+ */
+declare function snapEdgeEndpointsToGeometry(graph: GraphModel, nodes: LaidOutNode[], edgePaths: LayoutEdgePath[]): LayoutEdgePath[];
+//#endregion
+//#region src/topology/analyze.d.ts
+type DiagramTopology = {
+  direction: Direction;
+  isWorkflowTD: boolean;
+  choiceNodes: string[];
+  mergeNodes: string[];
+  fanOutNodes: string[];
+  choiceBranches: Set<string>;
+  incoming: Map<string, number>;
+  outgoing: Map<string, number>;
+};
+declare function analyzeDiagramTopology(graph: GraphModel, direction: Direction): DiagramTopology;
+declare function incomingCount(topology: DiagramTopology, nodeId: string): number;
+declare function outgoingCount(topology: DiagramTopology, nodeId: string): number;
+declare function isChoiceBranch(topology: DiagramTopology, nodeId: string): boolean;
+//#endregion
+//#region src/direction/index.d.ts
+/** True for left↔right flow (`LR` / `RL`). */
+declare function isHorizontal(direction: Direction): boolean;
+/** True for top↔bottom flow (`TD` / `BT`). */
+declare function isVertical(direction: Direction): boolean;
+//#endregion
+export { DEFAULT_FONT_FAMILY, type DiagramTopology, ELK_LAYOUT_ALGORITHM, ELK_ROUTER_ALGORITHM, type ElkLayoutAndRouteResult, GROUP_ICON_GAP, GROUP_ICON_SIZE, type LaidOutGroup, type LaidOutNode, type LayoutEdgeLabel, type LayoutEdgePath, type LayoutResult, type MeasureOptions, type MeasureResult, type MeasuredNode, SEQUENCE_LAYOUT_ALGORITHM, SEQUENCE_ROUTER_ALGORITHM, type SequenceLayoutArtifacts, TABLE_ATTR_GAP, TABLE_BADGE_GAP, TABLE_BADGE_W, TABLE_HEADER_H, TABLE_KEY_COL, TABLE_PAD_X, TABLE_ROW_H, TABLE_RX, type TextMeasurer, type TextStyle, type WrapOptions, analyzeDiagramTopology, browserFontsReady, cardIconColumnWidth, columnAnchorY, columnNoteLabel, columnTypeLabel, computeGroupBounds, createCanvasMeasurer, defaultMeasurer, ensureBrowserFonts, erdRelationshipLabel, incomingCount, isChoiceBranch, isErdTableNode, isHorizontal, isSequenceGraph, isVertical, layoutAndRouteWithElk, layoutFromGraph, layoutSequence, measureGraph, measurerUsedApproximationFallback, outgoingCount, resetDefaultMeasurer, snapEdgeEndpointsToGeometry, snapErdEdgeEndpoints, tableKeyBadges };
+//# sourceMappingURL=index.d.mts.map