feat(layout-elk): ELK layout package, with audit fixes and API alignment

.changeset/defaults-undefined-sources.md

@@ -0,0 +1,5 @@
+---
+"@joint/core": patch
+---
+
+util - accept `undefined` source objects in the `defaults()`, `defaultsDeep()`, `supplement()` and `deepSupplement()` typings, which the implementations already skip

.changeset/layout-elk-new-package.md

@@ -0,0 +1,5 @@
+---
+"@joint/layout-elk": minor
+---
+
+new package - automatic layout for JointJS graphs using the Eclipse Layout Kernel (ELK), including layout of embedded elements as containers and of element ports

.changeset/port-label-position-type.md

@@ -0,0 +1,5 @@
+---
+"@joint/core": patch
+---
+
+dia.Element - fix `PortLabelPositionType` type to use `PortLabelPositionJSON` for a port label's position

.changeset/port-prop-overloads.md

@@ -0,0 +1,5 @@
+---
+"@joint/core": patch
+---
+
+dia.Element - fix types to allow `portProp(portId)` and `portProp(portId, object, opt)`

examples/layout-elk-ts/.gitignore → examples/layout-elk-containers-and-ports-ts/.gitignore

@@ -1,3 +1,2 @@
-build/
 dist/
 node_modules/

examples/layout-elk-containers-and-ports-ts/README.md

@@ -0,0 +1,27 @@
+# JointJS ELK Containers & Ports Demo
+
+A fixed (non-random) web platform reference architecture laid out automatically with `@joint/layout-elk`: nested containers ("Client Layer" > "Edge", "Core Services" > "Data Layer", "Observability") grouping services that connect through ports, plus a couple of links connecting containers directly - including one that crosses from one container into another. Styled with Material Design, via JointJS's theme mechanism and CSS.
+
+## Setup
+
+Use Yarn to run this demo.
+
+You need to build *JointJS* first. Navigate to the root folder and run:
+```bash
+yarn install
+yarn run build
+```
+
+Navigate to this directory, then run:
+```bash
+yarn dev
+```
+
+Then open the URL printed in the terminal (usually `http://localhost:5173`). `yarn build`
+makes a production build in `dist/`, `yarn preview` serves it.
+
+## License
+
+The *JointJS* library is licensed under the [Mozilla Public License 2.0](https://github.com/clientIO/joint/blob/master/LICENSE).
+
+Copyright © 2013-2026 client IO

examples/layout-elk-containers-and-ports-ts/index.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description"
+        content="An automatic layout demo of a fixed graph with containers and ports, using JointJS and ELK.">
+    <title>ELK Containers & Ports Layout | JointJS</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap" rel="stylesheet">
+</head>
+
+<body>
+    <div class="toolbar">
+        <span id="zoom-out" class="toolbar-button">Zoom Out</span>
+        <span id="zoom-in" class="toolbar-button">Zoom In</span>
+    </div>
+    <div id="canvas" class="canvas"></div>
+    <script type="module" src="/src/index.ts"></script>
+
+</body>
+
+</html>

examples/layout-elk-ts/package.json → examples/layout-elk-containers-and-ports-ts/package.json

@@ -1,8 +1,8 @@
 {
-  "name": "@joint/demo-layout-elk-ts",
+  "name": "@joint/demo-layout-elk-containers-and-ports-ts",
   "version": "4.3.1",
-  "description": "JointJS - ELK Layout Demo",
-  "main": "dist/bundle.js",
+  "type": "module",
+  "description": "JointJS - ELK Layout Containers & Ports Demo",
   "homepage": "https://jointjs.com",
   "author": {
     "name": "client IO",
@@ -14,22 +14,18 @@
     "hoistingLimits": "workspaces"
   },
   "scripts": {
-    "start": "webpack-dev-server",
-    "build": "webpack"
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
   },
   "dependencies": {
     "@joint/core": "workspace:^",
-    "elkjs": "^0.11.0"
+    "@joint/layout-elk": "workspace:^"
   },
   "devDependencies": {
-    "css-loader": "3.5.3",
-    "sass-loader": "8.0.2",
-    "style-loader": "1.2.1",
-    "ts-loader": "^9.2.5",
+    "sass": "^1.93.2",
     "typescript": "5.8.2",
-    "webpack": "5.98.0",
-    "webpack-cli": "6.0.1",
-    "webpack-dev-server": "5.2.0"
+    "vite": "^7.3.1"
   },
   "volta": {
     "node": "22.14.0",

examples/layout-elk-containers-and-ports-ts/src/example.ts

@@ -0,0 +1,208 @@
+import { dia } from '@joint/core';
+
+// A fixed (non-random) system diagram: three top-level containers, two of
+// them with a nested container of their own, grouping eight services that
+// communicate over ports - plus a couple of links that connect two
+// containers directly, rather than a pair of ports, including one that
+// crosses container boundaries. A recognizable, if simplified, web platform
+// reference architecture: a client layer talking through an edge (load
+// balancer + API gateway) to core services (auth, guarding a data layer of
+// cache + database), with logs/metrics/analytics flowing to observability.
+// Every plain `example.Service` has exactly one 'in' and one 'out' port; the
+// four "hub" services (Load Balancer, API Gateway, Auth Service, Monitoring)
+// are `example.HubService` instead, with a custom number of ports and ELK's
+// `FIXED_SIDE` port constraint, so it can reorder them to minimize crossings
+// (see `index.ts`).
+export const graphJSON: dia.Graph.JSON = {
+    cells: [
+        // Containers
+        {
+            id: 'frontend',
+            type: 'example.Container',
+            attrs: { label: { text: 'Client Layer' } }
+        },
+        {
+            id: 'edge',
+            type: 'example.Container',
+            parent: 'frontend',
+            attrs: { label: { text: 'Edge' } }
+        },
+        {
+            id: 'backend',
+            type: 'example.Container',
+            attrs: { label: { text: 'Core Services' } }
+        },
+        {
+            id: 'storage',
+            type: 'example.Container',
+            parent: 'backend',
+            attrs: { label: { text: 'Data Layer' } }
+        },
+        {
+            id: 'observability',
+            type: 'example.Container',
+            attrs: { label: { text: 'Observability' } }
+        },
+
+        // Client Layer
+        {
+            id: 'webui',
+            type: 'example.Service',
+            parent: 'frontend',
+            attrs: { label: { text: 'Web App' } }
+        },
+        {
+            id: 'mobileui',
+            type: 'example.Service',
+            parent: 'frontend',
+            attrs: { label: { text: 'Mobile App' } }
+        },
+        {
+            id: 'lb',
+            type: 'example.HubService',
+            parent: 'edge',
+            size: { width: 130, height: 80 },
+            attrs: { label: { text: 'Load Balancer' } },
+            ports: {
+                items: [
+                    { id: 'in1', group: 'in', attrs: { text: { text: 'in1' } } },
+                    { id: 'in2', group: 'in', attrs: { text: { text: 'in2' } } },
+                    { id: 'out', group: 'out', attrs: { text: { text: 'out' } } }
+                ]
+            }
+        },
+        {
+            id: 'gateway',
+            type: 'example.HubService',
+            parent: 'edge',
+            size: { width: 130, height: 80 },
+            attrs: { label: { text: 'API Gateway' } },
+            ports: {
+                items: [
+                    { id: 'in', group: 'in', attrs: { text: { text: 'in' } } },
+                    { id: 'out1', group: 'out', attrs: { text: { text: 'out1' } } },
+                    { id: 'out2', group: 'out', attrs: { text: { text: 'out2' } } }
+                ]
+            }
+        },
+
+        // Core Services
+        {
+            id: 'auth',
+            type: 'example.HubService',
+            parent: 'backend',
+            size: { width: 130, height: 80 },
+            attrs: { label: { text: 'Auth Service' } },
+            ports: {
+                items: [
+                    { id: 'in', group: 'in', attrs: { text: { text: 'in' } } },
+                    { id: 'out1', group: 'out', attrs: { text: { text: 'out1' } } },
+                    { id: 'out2', group: 'out', attrs: { text: { text: 'out2' } } }
+                ]
+            }
+        },
+        {
+            id: 'cache',
+            type: 'example.Service',
+            parent: 'storage',
+            attrs: { label: { text: 'Redis Cache' } }
+        },
+        {
+            id: 'db',
+            type: 'example.Service',
+            parent: 'storage',
+            attrs: { label: { text: 'PostgreSQL' } }
+        },
+
+        // Observability
+        {
+            id: 'monitoring',
+            type: 'example.HubService',
+            parent: 'observability',
+            size: { width: 130, height: 80 },
+            attrs: { label: { text: 'Monitoring' } },
+            ports: {
+                items: [
+                    { id: 'in1', group: 'in', attrs: { text: { text: 'in1' } } },
+                    { id: 'in2', group: 'in', attrs: { text: { text: 'in2' } } }
+                ]
+            }
+        },
+
+        // Links
+        {
+            id: 'l1',
+            type: 'example.InteractionLink',
+            source: { id: 'webui', port: 'out' },
+            target: { id: 'lb', port: 'in1' },
+            labels: [{ attrs: { text: { text: 'request' } } }]
+        },
+        {
+            id: 'l2',
+            type: 'example.InteractionLink',
+            source: { id: 'mobileui', port: 'out' },
+            target: { id: 'lb', port: 'in2' },
+            labels: [{ attrs: { text: { text: 'request' } } }]
+        },
+        {
+            id: 'l3',
+            type: 'example.InteractionLink',
+            source: { id: 'lb', port: 'out' },
+            target: { id: 'gateway', port: 'in' },
+            labels: [{ attrs: { text: { text: 'route' } } }]
+        },
+        {
+            id: 'l4',
+            type: 'example.InteractionLink',
+            source: { id: 'gateway', port: 'out1' },
+            target: { id: 'auth', port: 'in' },
+            labels: [{ attrs: { text: { text: 'authenticate' } } }]
+        },
+        {
+            id: 'l5',
+            type: 'example.InteractionLink',
+            source: { id: 'gateway', port: 'out2' },
+            target: { id: 'monitoring', port: 'in1' },
+            labels: [{ attrs: { text: { text: 'metrics' } } }]
+        },
+        {
+            id: 'l6',
+            type: 'example.InteractionLink',
+            source: { id: 'auth', port: 'out1' },
+            target: { id: 'cache', port: 'in' },
+            labels: [{ attrs: { text: { text: 'lookup' } } }]
+        },
+        {
+            id: 'l7',
+            type: 'example.InteractionLink',
+            source: { id: 'auth', port: 'out2' },
+            target: { id: 'monitoring', port: 'in2' },
+            labels: [{ attrs: { text: { text: 'logs' } } }]
+        },
+        {
+            id: 'l8',
+            type: 'example.InteractionLink',
+            source: { id: 'cache', port: 'out' },
+            target: { id: 'db', port: 'in' },
+            labels: [{ attrs: { text: { text: 'query' } } }]
+        },
+
+        // Container-to-container links - connected to a `example.Container` cell
+        // itself rather than to one of its ports, aggregating what the individual
+        // service-to-service links above already carry.
+        {
+            id: 'l9',
+            type: 'example.InteractionLink',
+            source: { id: 'backend' },
+            target: { id: 'observability' },
+            labels: [{ attrs: { text: { text: 'metrics' } } }]
+        },
+        {
+            id: 'l10',
+            type: 'example.InteractionLink',
+            source: { id: 'frontend' },
+            target: { id: 'observability' },
+            labels: [{ attrs: { text: { text: 'analytics' } } }]
+        }
+    ]
+};