ngx-emfular-diagram 1.0.0

package/README.md

@@ -0,0 +1,33 @@
+# EMFular-diagram
+
+This project supplies components and services for the easier creation of ***svg-based*** diagrams.
+To support such components, the library provides and uses explicit contracts of ***graphical identity*** (`interface Identifiable`) and ***position*** (`interface Positionable`), that using code should implement.
+Diagram currently offers text alignment, drag-and-drop-support and arrow components that can attach to explicit points, bounding boxes, or identifiable objects.
+Further contributions are welcome.
+
+## Getting started
+
+Install the library via `npm`:
+```
+npm install ngx-emfular-diagram
+```
+or adapt your package.json manually to the required version:
+```
+"ngx-emfular-diagram": "^1.0.0",
+```
+older versions are available under the old package name, `ngx-svg-graphics`. The latest old version is:
+```
+"ngx-svg-graphics": "^3.0.0",
+```
+
+## Support
+Support is currently offered by the main developer, Susanne Göbel under goebel@uni-koblenz.de.
+
+## Contributing
+We are open to contributors. Maybe you would like to write your bachelor's or master's thesis on EMFular? Read our [arXiv-paper](https://arxiv.org/abs/2606.11442) and get in touch with Susanne Göbel goebel@uni-koblenz.de.
+
+## License
+EMFular-diagram is subject to (C) 2026, SoftLang Research Team, University of Koblenz, Faculty of CS, contact Susanne Göbel or Ralf Lämmel.
+It is provided under the ***CC BY 4.0 license***.
+Basically, you are free to share and adapt the material as long as you give proper credit to us and our project.
+Feel free to include EMFular into your research but please cite us.

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "./node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "dist",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "ngx-emfular-diagram",
+  "version": "1.0.0",
+  "description": "Small svg library to link components or svg elements with arrows and allow to drag components.",
+  "keywords": [
+    "Drag",
+    "Arrows",
+    "SVG",
+    "Angular",
+    "EMF"
+  ],
+  "author": {
+    "name": "Susanne Göbel",
+    "email": "goebel@uni-koblenz.de"
+  },
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json",
+    "test": "vitest --config vitest.config.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/softlang/EMFular-diagram"
+  },
+  "peerDependencies": {
+    "@angular/cdk": "^19.2.7",
+    "@angular/common": "^19.2.7",
+    "@angular/core": "^19.2.7",
+    "@angular/forms": "^19.2.7",
+    "@types/uuid": "^10.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@analogjs/vite-plugin-angular": "^1.19.2",
+    "@angular-devkit/build-angular": "^19.2.25",
+    "@angular/build": "^19.2.25",
+    "@angular/compiler": "^19.2.7",
+    "@angular/platform-browser": "^19.2.7",
+    "@angular/platform-browser-dynamic": "^19.2.7",
+    "@testing-library/dom": "^10.4.1",
+    "@vitest/browser": "^4.1.10",
+    "@vitest/browser-playwright": "^4.1.10",
+    "jsdom": "^29.1.1",
+    "ng-packagr": "^19.2.2",
+    "playwright": "^1.61.1",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
+  }
+}

package/src/lib/components/arrows/arrow-between-boxes/arrow-between-boxes.component.svg

@@ -0,0 +1,12 @@
+<svg:g>
+  <g arrow-between-points
+     [startX]="x1"
+     [startY]="y1"
+     [endX]="x2"
+     [endY]="y2"
+     [text]="text"
+     [arrowType]="arrowType"
+     [style]="style"
+  >
+  </g>
+</svg:g>

package/src/lib/components/arrows/arrow-between-boxes/arrow-between-boxes.component.ts

@@ -0,0 +1,60 @@
+import { AfterViewInit, ChangeDetectorRef, Component, Input, OnChanges,} from '@angular/core';
+import { Point } from "@angular/cdk/drag-drop";
+import {v4 as uuidv4} from "uuid";
+import {BoundingBox} from "../../../models/bounding-box";
+import {PathLayouter} from "../../../utils/path-layouter";
+import {ArrowBetweenPointsComponent} from "../arrow-between-points/arrow-between-points.component";
+
+@Component({
+    selector: '[arrow-between-boxes]',
+    templateUrl: './arrow-between-boxes.component.svg',
+    styleUrl: './arrow-between-boxes.component.css',
+    imports: [ArrowBetweenPointsComponent]
+})
+export class ArrowBetweenBoxesComponent implements OnChanges, AfterViewInit {
+  @Input() start!: BoundingBox;
+  @Input() end!: BoundingBox;
+  @Input() arrowType?: string;
+  @Input() text?: string;
+  @Input() style?: string;
+
+
+  x1: number = 0;
+  y1: number = 0;
+  x2: number = 5;
+  y2: number = 5;
+
+  id = uuidv4();
+
+  positioned= false;
+
+  constructor(
+    private cdr: ChangeDetectorRef,
+    ) {}
+
+  ngAfterViewInit() {
+    this.computePositions()
+    this.positioned = true;
+    this.cdr.detectChanges();
+  }
+
+  ngOnChanges() {
+    if(this.positioned) {
+      this.computePositions()
+    }
+  }
+
+
+  private computePositions() {
+    let res = PathLayouter.bestPoints(this.start, this.end);
+    this.applyBestPoints(res)
+  }
+
+  private applyBestPoints(res: Point[]) {
+    this.x1 = res[0].x;
+    this.y1 = res[0].y;
+    this.x2 = res[1].x;
+    this.y2 = res[1].y;
+  }
+
+}

package/src/lib/components/arrows/arrow-between-elems/arrow-between-elems.component.svg

@@ -0,0 +1,9 @@
+<svg:g #arrow>
+  <g arrow-between-boxes *ngIf="start && end"
+       [start]="start"
+       [end]="end"
+       [arrowType]="arrowType"
+       [text]="text"
+       [style]="style">
+  </g>
+></svg:g>

package/src/lib/components/arrows/arrow-between-elems/arrow-between-elems.component.ts

@@ -0,0 +1,96 @@
+import {
+  AfterViewInit,
+  ChangeDetectorRef,
+  Component, ElementRef,
+  Input, OnChanges, OnDestroy,
+  OnInit, SimpleChanges,
+  ViewChild
+} from '@angular/core';
+import {Observable, Subscription} from "rxjs";
+import { NgIf } from '@angular/common';
+import {BoundingBox} from "../../../models/bounding-box";
+import {ArrowBetweenBoxesComponent} from "../arrow-between-boxes/arrow-between-boxes.component";
+import {SVGAccessService} from "../../../services/svg-access.service";
+
+@Component({
+    selector: '[arrowElems]',
+    templateUrl: './arrow-between-elems.component.svg',
+    styleUrl: './arrow-between-elems.component.css',
+    imports: [NgIf, ArrowBetweenBoxesComponent]
+})
+export class ArrowBetweenElemsComponent implements OnInit, AfterViewInit, OnChanges, OnDestroy {
+
+  @Input() startGID!: string;
+  @Input() startSuffix!: string;
+  @Input() endGID!: string;
+  @Input() endSuffix!: string;
+  @Input() arrowType?: string;
+
+  @Input() breaks: BoundingBox[] = [];
+  @Input() text?: string;
+  @Input() style?: string; //todo move into ArrowStyleConfig?
+
+  startId!: string;
+  endId!: string;
+
+  start?: BoundingBox;
+  end?: BoundingBox;
+
+  positioned= false;
+  @ViewChild('arrow') node!: ElementRef<SVGGraphicsElement>;
+
+  changeNotifier: Observable<string>;
+  changeSubscription: Subscription;
+
+  //idea: compute the two input positions as relative to the current elem
+  constructor(
+    private svgAccessService: SVGAccessService,
+    private cdr: ChangeDetectorRef) {
+    this.changeNotifier = this.svgAccessService.listenToPositionChange()
+    this.changeSubscription = this.changeNotifier.subscribe(nextString => {
+      if (nextString == this.startGID || nextString == this.endGID) {
+        setTimeout(() => {
+          this.computePositionsByIds()
+          this.cdr.detectChanges()
+        }, 0)
+      }
+    })
+  }
+
+  ngOnInit() {
+    this.startId = this.startGID+this.startSuffix;
+    this.endId = this.endGID+this.endSuffix;
+  }
+
+  ngOnChanges(_: SimpleChanges) {
+    this.startId = this.startGID+this.startSuffix;
+    this.endId = this.endGID+this.endSuffix;
+    this.computePositionsByIds()
+    this.cdr.detectChanges()
+  }
+
+  ngAfterViewInit() {
+    this.positioned = true;
+    this.computePositionsByIds()
+    this.cdr.detectChanges()
+  }
+
+  private computePositionsByIds() {
+    if (this.node?.nativeElement){
+      let rel = this.node.nativeElement as SVGGraphicsElement
+      let startOpt = this.svgAccessService.getRelativePosition(this.startId, rel)
+      if (startOpt) {
+        this.start = startOpt
+      }
+      let endOpt = this.svgAccessService.getRelativePosition(this.endId, rel)
+      if (endOpt) {
+        this.end = endOpt
+      }
+    } else console.log('No native element yet')
+  }
+
+  ngOnDestroy() {
+    this.changeSubscription.unsubscribe();
+  }
+
+}

package/src/lib/components/arrows/arrow-between-points/arrow-between-points.component.svg

@@ -0,0 +1,15 @@
+<svg:g>
+    <path [attr.id]="id+'-path'"
+          [attr.d]="'M '+startX+','+startY+' L '+endX+','+endY"
+          [attr.stroke]="arrowStyleConfiguration.color"
+          [attr.stroke-dasharray]="arrowStyleConfiguration.dashed"
+          [attr.marker-start]='"url(#"+arrowStyleConfiguration.startPointer+")"'
+          [attr.marker-end]='"url(#"+arrowStyleConfiguration.endPointer+")"'
+          style="{{style}}">
+    </path>
+    <text *ngIf="text">
+        <textPath [attr.href]="'#'+id+'-path'">
+            {{text}}
+        </textPath>
+    </text>
+</svg:g>

package/src/lib/components/arrows/arrow-between-points/arrow-between-points.component.ts

@@ -0,0 +1,39 @@
+import {Component, Input, OnChanges} from '@angular/core';
+import {NgIf} from "@angular/common";
+import {ArrowStyleConfigurationService} from "../../../services/arrow-style-configuration.service";
+import {ArrowStyleConfiguration} from "../../../models/arrow-style-configuration";
+import {v4 as uuidv4} from "uuid";
+
+@Component({
+  selector: '[arrow-between-points]',
+  imports: [
+    NgIf
+  ],
+  templateUrl: './arrow-between-points.component.svg',
+  styleUrl: './arrow-between-points.component.css'
+})
+export class ArrowBetweenPointsComponent implements OnChanges {
+
+  @Input() startX!: number;
+  @Input() startY!: number;
+  @Input() endX!: number;
+  @Input() endY!: number;
+  @Input() text?: string;
+  @Input() style?: string;
+
+  @Input() arrowType?: string;
+
+  arrowStyleConfiguration: ArrowStyleConfiguration;
+  id = uuidv4();
+
+  constructor(
+      private arrowStyleConfigService: ArrowStyleConfigurationService,) {
+
+    this.arrowStyleConfiguration = this.arrowStyleConfigService.styleArrow()
+  }
+
+  ngOnChanges() {
+    this.arrowStyleConfiguration = this.arrowStyleConfigService.styleArrow(this.arrowType)
+  }
+
+}

package/src/lib/components/draggable/draggable.component.svg

@@ -0,0 +1,8 @@
+<svg:g>
+  <g [attr.id]="elem.$gId"
+     (mousedown)="startDrag($event)"
+     (mousemove)="drag($event)"
+     (mouseup)="endDrag($event)"
+     (click)="clickElem($event)">
+  </g>
+</svg:g>

package/src/lib/components/draggable/draggable.component.ts

@@ -0,0 +1,49 @@
+import {AfterViewInit, Component, EventEmitter, Output} from '@angular/core';
+import {SVGAccessService} from '../../services/svg-access.service';
+import { Draggable } from '../../models/positionable';
+import {Dragger} from "../../models/dragger";
+
+@Component({
+  imports: [],
+  selector: '[draggable]',
+  templateUrl: './draggable.component.svg',
+  styleUrl: './draggable.component.css'
+})
+export abstract class DraggableComponent<T extends Draggable> implements AfterViewInit {
+
+  @Output() chooseElem = new EventEmitter<T>();
+  //the caller must initialize both required elements (elem and elementDragger) either in the constructor
+  // (or if they are inputs) in the ngOnInit life cycle hook
+  elem!: T;
+  elemDragger!: Dragger<T>;
+
+  protected constructor(
+    protected svgAccessService: SVGAccessService
+  ) {}
+
+
+  ngAfterViewInit() {
+    this.svgAccessService.notifyPositionChange(this.elem.$gId)
+  }
+
+  startDrag(event: MouseEvent) {
+    this.elemDragger.startDrag(event);
+  }
+
+  drag(event: MouseEvent) {
+    if (this.elemDragger.drag(event)) {
+      this.svgAccessService.notifyPositionChange(this.elem.$gId)
+    }
+  }
+
+  endDrag(event: MouseEvent) {
+    this.elemDragger.endDrag(event);
+  }
+
+  clickElem(event: MouseEvent) {
+    if (this.elemDragger.clickElem(event)) {
+      this.chooseElem.emit(this.elem);
+    }
+  }
+
+}

package/src/lib/components/rectangle/rectangle.component.svg

@@ -0,0 +1,3 @@
+<svg:g>
+    <rect [attr.x]="position.x" [attr.y]="position.y" [attr.width]="position.w" [attr.height]="position.h" [attr.fill]="color"></rect>
+</svg:g>

package/src/lib/components/rectangle/rectangle.component.ts

@@ -0,0 +1,14 @@
+import {Component, Input} from '@angular/core';
+import {BoundingBox} from "../../models/bounding-box";
+
+@Component({
+  selector: '[rectangleG]',
+  imports: [],
+  templateUrl: './rectangle.component.svg',
+  styleUrl: './rectangle.component.css'
+})
+export class RectangleComponent {
+  @Input() position!: BoundingBox
+  @Input() color?: string = '#ccffff';
+
+}

package/src/lib/components/rectangle-with-text/rectangle-with-text.component.svg

@@ -0,0 +1,14 @@
+<svg:g [attr.id]="id">
+    <g rectangleG
+       [position]="position"
+       [color]="color">
+    </g>
+    <!-- class name -->
+    <g text-area-svg
+       [(text)]="text"
+       [x]="position.x"
+       [y]="position.y"
+       [w]="position.w"
+       [h]="position.h">
+    </g>
+</svg:g>

package/src/lib/components/rectangle-with-text/rectangle-with-text.component.ts

@@ -0,0 +1,22 @@
+import {Component, EventEmitter, Input, Output} from '@angular/core';
+import {BoundingBox} from "../../models/bounding-box";
+import {RectangleComponent} from "../rectangle/rectangle.component";
+import {TextAreaSvgComponent} from "../text-area-svg/text-area-svg.component";
+
+@Component({
+  selector: '[rectangle-with-text]',
+  imports: [
+    TextAreaSvgComponent,
+    RectangleComponent
+  ],
+  templateUrl: './rectangle-with-text.component.svg',
+  styleUrl: './rectangle-with-text.component.css'
+})
+export class RectangleWithTextComponent {
+  @Input() id!: string;
+  @Input() text!: string;
+  @Output() textChange = new EventEmitter<string>();
+
+  @Input() position!: BoundingBox
+  @Input() color?: string;
+}

package/src/lib/components/text-area-svg/text-area-svg.component.spec.ts

@@ -0,0 +1,60 @@
+import { TestBed, ComponentFixture } from '@angular/core/testing';
+import {afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { TextAreaSvgComponent } from './text-area-svg.component';
+
+describe('TextAreaSvgComponent', () => {
+  let component: TextAreaSvgComponent;
+  let fixture: ComponentFixture<TextAreaSvgComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [TextAreaSvgComponent]
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(TextAreaSvgComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  afterEach(() => {
+    TestBed.resetTestingModule();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+
+  function initializeDistributedText() {
+    component.x = 20;
+    component.y = 40;
+    component.h = 50;
+    component.w = 200;
+  }
+
+  function verifyDistributedText(text: string, distributedText: string[]) {
+    component.text = text;
+    component.distributeText();
+    expect(component.distributedText).toEqual(distributedText);
+  }
+
+  it('should set a two line distributed text', () => {
+    initializeDistributedText();
+
+    verifyDistributedText(
+        'Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam',
+        ['Lorem ipsum dolor sit', 'amet, consetetur ...']
+    );
+  });
+
+  it('should set a short distributed text after setting a longer one', () => {
+    initializeDistributedText();
+
+    verifyDistributedText(
+        'Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam',
+        ['Lorem ipsum dolor sit', 'amet, consetetur ...']
+    );
+
+    verifyDistributedText('Short', ['Short']);
+  });
+});

package/src/lib/components/text-area-svg/text-area-svg.component.svg

@@ -0,0 +1,6 @@
+<svg:text [attr.x]="x" [attr.y]="y" [attr.width]="w" [attr.height]="h" dy="0" [attr.style]="" (click)="handleClick()">
+  <tspan dy="1.2em" [attr.x]="x" *ngFor="let line of distributedText">{{line}}</tspan>
+</svg:text>
+<svg:foreignObject  *ngIf="isActive" [attr.x]="x" [attr.y]="y" [attr.width]="w" [attr.height]="h">
+  <input id="text-area" type="text" [(ngModel)]="this.text" (focusout)="leaveTextInput()"/>
+</svg:foreignObject>

package/src/lib/components/text-area-svg/text-area-svg.component.ts

@@ -0,0 +1,57 @@
+import {
+  Component,
+  EventEmitter,
+  Input,
+  OnChanges,
+  Output,
+} from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { NgFor, NgIf } from '@angular/common';
+import {TextDistributor} from "../../utils/text-distributor";
+
+@Component({
+    selector: '[text-area-svg]',
+    templateUrl: './text-area-svg.component.svg',
+    styleUrl: './text-area-svg.component.css',
+    imports: [NgFor, NgIf, FormsModule]
+})
+export class TextAreaSvgComponent implements OnChanges {
+  /*
+  a fixed size svg. If the text exceeds the possible size, we will do a ... for now
+   */
+
+  @Input() text!: string
+  @Input() x!: number
+  @Input() y!: number
+  @Input() w!: number
+  @Input() h!: number
+  @Input() singleEdit: boolean = false
+  @Output() textChange = new EventEmitter<string>();
+  //only with singleEdit since that opens an overlay where one can change the text in place
+
+  distributedText: string[] = []
+  isActive: boolean = false;
+
+
+  ngOnChanges() {
+    this.distributeText();
+  }
+
+  handleClick() {
+    if(this.singleEdit) {
+      this.isActive = true
+    }
+  }
+
+  leaveTextInput() {
+    this.textChange.emit(this.text)
+    this.isActive = false;
+  }
+
+  distributeText(){
+    this.distributedText = TextDistributor.distributeText(
+      this.text, this.w, this.h
+    )
+  }
+
+}

package/src/lib/models/arrow-style-configuration.ts

@@ -0,0 +1,8 @@
+export interface ArrowStyleConfiguration {
+  color: string;
+  dashed: number[];
+  //style?: string
+
+  startPointer?: string;
+  endPointer?: string;
+}

package/src/lib/models/bounding-box.ts

@@ -0,0 +1,7 @@
+export interface BoundingBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+
+}

package/src/lib/models/dragger.ts

@@ -0,0 +1,54 @@
+import {Positionable} from './positionable';
+
+export class Dragger<T extends Positionable> {
+  elem: T;
+
+  dragActive = false;
+  wasReallyDragged = false;
+  dragStartX: number = 0;
+  dragStartY: number = 0;
+
+  constructor(element: T) {
+    this.elem = element;
+  }
+
+  startDrag(event: MouseEvent) {
+    this.dragStartX = event.clientX;
+    this.dragStartY = event.clientY;
+    this.dragActive = true;
+  }
+
+  // returns true in the case of a real drag event, false otherwise
+  drag(event: MouseEvent): boolean {
+    if (this.dragActive) {
+      this.wasReallyDragged = true;
+      event.preventDefault();
+      const dragX = event.clientX;
+      this.elem.position.x+= (dragX - this.dragStartX);
+      this.dragStartX = dragX;
+      const dragY = event.clientY;
+      this.elem.position.y+= (dragY - this.dragStartY);
+      this.dragStartY = dragY;
+      return true;
+    }
+    return false;
+  }
+
+  endDrag(event: MouseEvent) {
+    this.dragActive = false;
+    // todo was working for click vs drag, not now setTimeout(() => {this.dragActive = false;}, 50);
+    event.preventDefault();
+  }
+
+  //returns true if the click should be treated as click, false if it was from drag
+  clickElem(event: MouseEvent): boolean {
+    if (this.wasReallyDragged) {
+      this.wasReallyDragged = false;
+      return false;
+    } else {
+      event.preventDefault();
+      return true;
+    }
+  }
+
+}

package/src/lib/models/identifiable.ts

@@ -0,0 +1,3 @@
+export interface Identifiable {
+  $gId: string;
+}