ngx-emfular-tool 1.0.0 → 1.1.0

package/.github/workflows/cd.yml

@@ -0,0 +1,64 @@
+name: CD
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Publish package
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify tag is on main
+        run: |
+          git fetch origin main
+
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "You may only create releases from main."
+            echo "The tagged commit $GITHUB_SHA is not part of origin/main."
+            exit 1
+          fi
+
+          echo "Tag points to a commit on main"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - run: npm ci
+
+      - name: Install Playwright browsers (for vitest browser tests)
+        run: npx playwright install --with-deps chromium
+
+      - name: test
+        run: npm run test
+
+      - run: npm run build
+
+      - name: Check package version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          TAG=${GITHUB_REF#refs/tags/v}
+          
+          if [ "$VERSION" != "$TAG" ]; then
+            echo "Version mismatch!"
+            echo "package.json contains version $VERSION"
+            echo "but the tag is v$TAG"
+            exit 1
+          fi
+          echo "Versions match: $VERSION"
+
+      - name: Publish
+        run: npm publish --provenance --access public
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2

package/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+on:
+  pull_request:
+  push:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test and package library
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers (for vitest browser tests)
+        run: npx playwright install --with-deps chromium
+
+      - name: Run tests
+        run: npm run test
+
+      - name: Build library
+        run: npm run build

package/README.md

@@ -1,63 +1,93 @@
-# NgxEmfularHelper
+# EMFular-Tool
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 19.2.0.
+This project supplies model-agnostic Angular utilities for building EMFular editors.
+In the EMFular megamodel, Tool is the layer for editor functionality that is not part of the model semantics of `EMFular-Core` and not part of the SVG rendering contracts of `EMFular-Diagram`.
+It provides browser-side facilities for history, file input/output, export, input normalization, and alert dialogs.
 
-## Code scaffolding
+## Concepts
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+The EMFular megamodel identifies three Tool concepts: ***Graphical-File Management***, ***JSON-History Management***, and ***JSON-File Management***.
+They map to the code as follows.
 
-```bash
-ng generate component component-name
-```
+### Graphical-File Management
+
+Graphical-file management is implemented by the SVG export part of `IoService`.
+It receives an `SVGElement`, removes Angular runtime artifacts from a cloned SVG, serializes the SVG, and saves it either as SVG directly or as PNG/JPEG through an intermediate canvas.
+
+Code sections:
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+- `projects/tool/src/lib/io/io.service.ts`: `cleanCopySVGAsBlob`, `saveSVG`, `saveSvgAsPng`, `saveSvgAsJpeg`
+- `projects/tool/src/lib/io/io.service.ts`: private conversion helpers `convertSvgBlobToPngOrJpegAndDownload`, `loadImgToCanvas`, `canvasToPng`, `canvasToJpeg`
 
-```bash
-ng generate --help
+```ts
+export class IoService {
+  cleanCopySVGAsBlob(svg: SVGElement): Blob;
+  saveSVG(svgContent: SVGElement, title: string): void;
+  saveSvgAsPng(svgContent: SVGElement, title: string): void;
+  saveSvgAsJpeg(svgContent: SVGElement, title: string): void;
+}
 ```
 
-## Building
+### JSON-History Management
 
-To build the library, run:
+JSON-history management is implemented by `HistoryService<T>`.
+The service is generic, but in an EMFular editor it is normally instantiated as `HistoryService<JsonOf<M>>`, so each history entry is the JSON representation of a model state.
+The states are stored in a circular `localStorage` buffer and exposed through `state$` for undo, redo, and session recovery.
 
-```bash
-ng build tool
-```
+Code sections:
+
+- `projects/tool/src/lib/history/history.service.ts`: circular history buffer, `state$`, `save`, `undo`, `redo`, `clearHistory`
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+```ts
+export class HistoryService<T> {
+  state$: Observable<T | null>;
 
-### Publishing the Library
+  constructor(prefix?: string, bufferSize?: number, platformId?: Object);
 
-Once the project is built, you can publish your library by following these steps:
+  clearHistory(): void;
+  save(elem: T): void;
+  undo(): T | null;
+  redo(): T | null;
+  isUndoNotPossible(): boolean;
+  isRedoNotPossible(): boolean;
+}
+```
 
-1. Navigate to the `dist` directory:
-   ```bash
-   cd dist/tool
-   ```
+### JSON-File Management
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+JSON-file management is split between Tool and Integration.
+Tool provides the browser file primitives in `IoService`: reading a selected file as text and saving a JSON string as a `.json` download.
 
-## Running unit tests
+Code sections:
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+- `projects/tool/src/lib/io/io.service.ts`: `loadStringFromFile`, `saveJson`, `saveFile`
 
-```bash
-ng test
+```ts
+export class IoService {
+  loadStringFromFile(event: Event): Promise<string>;
+  saveFile(contentBlob: Blob, fileName: string): void;
+  saveJson(json: string, title: string): void;
+}
 ```
 
-## Running end-to-end tests
+### Additional Tool Helpers
 
-For end-to-end (e2e) testing, run:
+The package also exports small helper APIs that are not separate Tool concepts in the megamodel:
 
-```bash
-ng e2e
-```
+- `InputHandler` normalizes browser input events, especially numeric input and repeated file selections.
+- `AlertService` and `AlertComponent` provide a minimal CDK-based alerting via pop-ups.
+
+## Support
+
+Support is currently offered by the main developer, Susanne Göbel under goebel@uni-koblenz.de.
+
+## Contributing
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+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.
 
-## Additional Resources
+## License
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+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

@@ -1,13 +1,8 @@
 {
   "name": "ngx-emfular-tool",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Small Angular library with helper schematics for EMFular, currently alerting, history, and io facilities",
-  "keywords": [
-    "EMFular",
-    "Angular",
-    "IO",
-    "alert"
-  ],
+  "keywords": ["EMFular","Angular", "IO", "alert"],
   "author": {
     "name": "Susanne Göbel",
     "email": "goebel@uni-koblenz.de"
@@ -16,27 +11,35 @@
     "type": "git",
     "url": "https://github.com/softlang/EMFular-tool"
   },
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json",
+    "test": "vitest --config vitest.config.ts"
+  },
   "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",
-    "@angular/material": "^19.2.7"
+    "@types/uuid": "^10.0.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"
   },
   "sideEffects": false,
-  "module": "fesm2022/ngx-emfular-tool.mjs",
-  "typings": "index.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./fesm2022/ngx-emfular-tool.mjs"
-    }
+  "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/alerting/alert/alert.component.css

@@ -0,0 +1,18 @@
+.tool-button-text{
+  margin: 1rem;
+  text-align: center;
+  vertical-align: middle;
+  color: orange;
+  height: 3rem;
+  width: 6rem;
+  background: white;
+  border: 2px solid orange;
+  border-radius: 4px;
+}
+.tool-button-text:hover {
+  box-shadow: 0 12px 16px 0 rgba(0,0,0,0.24), 0 17px 50px 0 rgba(0,0,0,0.19);
+}
+
+.p {
+
+}

package/src/lib/alerting/alert/alert.component.html

@@ -0,0 +1,7 @@
+<div style="text-align: center">
+  <h3>Warning</h3>
+  <p>{{message}}</p>
+  <button class="tool-button-text" (click)="closeMe()">
+    Ok
+  </button>
+</div>

package/src/lib/alerting/alert/alert.component.spec.ts

@@ -0,0 +1,41 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { AlertComponent } from './alert.component';
+import { OverlayRef } from '@angular/cdk/overlay';
+
+describe('AlertComponent', () => {
+  let component: AlertComponent;
+  let fixture: ComponentFixture<AlertComponent>;
+  let overlayRef: OverlayRef;
+
+  beforeEach(async () => {
+    overlayRef = {
+      dispose: vi.fn()
+    } as unknown as OverlayRef;
+
+    await TestBed.configureTestingModule({
+      imports: [AlertComponent],
+      providers: [
+        { provide: OverlayRef, useValue: overlayRef }
+      ]
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(AlertComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  afterEach(() => {
+    TestBed.resetTestingModule();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+
+  it('closes the overlay', () => {
+    component.closeMe();
+    expect(overlayRef.dispose).toHaveBeenCalled();
+  });
+});

package/src/lib/alerting/alert/alert.component.ts

@@ -0,0 +1,21 @@
+import { Component } from '@angular/core';
+import {OverlayRef} from "@angular/cdk/overlay";
+
+@Component({
+  selector: 'alert-component',
+  imports: [],
+  templateUrl: './alert.component.html',
+  styleUrl: './alert.component.css'
+})
+export class AlertComponent {
+
+  public message!: string;
+
+  constructor(
+      private readonly overlayRef: OverlayRef
+  ) {}
+
+  closeMe(): void {
+    this.overlayRef.dispose();
+  }
+}

package/src/lib/alerting/alert.service.spec.ts

@@ -0,0 +1,64 @@
+import {describe, expect, it, vi} from 'vitest';
+
+import {AlertService} from './alert.service';
+import {AlertComponent} from './alert/alert.component';
+import {ModalService} from '../modal/modal.service';
+import {ModalInstance} from '../modal/modal-instance';
+import {ModalRef} from '../modal/modal-ref';
+
+describe('AlertService', () => {
+
+  function createModalInstance(): ModalInstance<AlertComponent, void> {
+    return {
+      ref: {} as ModalRef<void>,
+      componentRef: {
+        instance: {} as AlertComponent
+      } as any
+    };
+  }
+
+  it('creates an alert with the given message', () => {
+    const modalInstance = createModalInstance();
+    const modalService = {
+      createModal: vi.fn(() => modalInstance)
+    } as unknown as ModalService;
+
+    const service = new AlertService(modalService);
+    service.alert('Hello');
+    expect(modalService.createModal).toHaveBeenCalledWith(
+        AlertComponent,
+        {
+          width: '20%',
+          height: '30%',
+          hasBackdrop: true,
+          backdropClass: 'cdk-overlay-dark-backdrop',
+          panelClass: 'alert-overlay'
+        }
+    );
+    expect(modalInstance.componentRef.instance.message)
+        .toBe('Hello');
+  });
+
+  it('creates a separate modal for each alert', () => {
+    const first = createModalInstance();
+    const second = createModalInstance();
+
+    const modalService = {
+      createModal: vi.fn()
+          .mockReturnValueOnce(first)
+          .mockReturnValueOnce(second)
+    } as unknown as ModalService;
+
+    const service = new AlertService(modalService);
+    service.alert('First');
+    service.alert('Second');
+
+    expect(modalService.createModal).toHaveBeenCalledTimes(2);
+    expect(first.componentRef.instance.message)
+        .toBe('First');
+    expect(second.componentRef.instance.message)
+        .toBe('Second');
+    expect(first).not.toBe(second);
+  });
+
+});

package/src/lib/alerting/alert.service.ts

@@ -0,0 +1,28 @@
+import { Injectable } from '@angular/core';
+import {AlertComponent} from "./alert/alert.component";
+import {ModalService} from "../modal/modal.service";
+import {ModalInstance} from "../modal/modal-instance";
+
+@Injectable({
+  providedIn: 'root'
+})
+export class AlertService {
+
+  constructor(
+      private readonly modalService: ModalService
+  ) {}
+
+  alert(msg: string): void {
+    const modalInstance: ModalInstance<AlertComponent, void> = this.modalService.createModal<AlertComponent, void>(
+        AlertComponent,
+        {
+          width: '20%',
+          height: '30%',
+          hasBackdrop: true,
+          backdropClass: 'cdk-overlay-dark-backdrop',
+          panelClass: 'alert-overlay'
+        }
+    );
+    modalInstance.componentRef.instance.message = msg;
+  }
+}