@miragon/modeler-api 1.1.0 → 1.2.0

package/dist/conformance.d.ts

@@ -1,4 +1,5 @@
 import { CollaborativeModeler } from './index.js';
+export { apiVersionsCompatible } from './index.js';
 
 /**
  * The conformance test kit — every law of the CollaborativeModeler contract
@@ -29,7 +30,8 @@ interface ConformanceHarness {
      * document with a non-zero size (`attachedHost()` below) — diagram-js
      * engines compute viewboxes from the host's client size, so a detached
      * or 0×0 host yields NaN view state; they also need a real browser
-     * (vitest browser mode / Playwright), jsdom has no getBBox
+     * (vitest browser mode / Playwright), jsdom has no getBBox. Keep
+     * `fitOnImport` at its default: the L5 cases check the modeler's own fit
      */
     create(): Promise<CollaborativeModeler>;
     /** a fresh READ-ONLY instance (`meta.editable === false`) — the viewer
@@ -125,12 +127,26 @@ interface ConformanceHarness {
     /** trigger the modeler's redo; `undefined` with `undo` defined = the redo
      *  half of the undo/redo case is reported as skipped */
     redo?(modeler: CollaborativeModeler): Promise<void> | void;
+    /**
+     * move ONE element read from `canonicalTexts[0]` (imported, then one
+     * `mutate` added an element) through the modeler's own commands, the way
+     * a user drags it, far enough that its box changes position after any
+     * snapping, rounding or clamping — and return that element's id
+     * (ElementInfo.id). The bounds case requires `elements.bounds` to report
+     * the moved box. `undefined` = that half of the bounds case is reported as
+     * skipped (only when the modeler has `bounds`)
+     */
+    moveElement?(modeler: CollaborativeModeler): Promise<string> | string;
     /**
      * open an INTERACTION on an element of `canonicalTexts[0]` (already
      * imported) the way a user does — its label editor, or a popup with an
      * input — and type input WITHOUT committing it (no Enter, no blur). The
-     * kit then imports over it, which must never commit it (L1). `undefined`
-     * = the L1 interaction case is reported as skipped
+     * kit then imports over it (L1) and changes the view over it (L5), and
+     * neither may commit it. Type the same input on every call, one the
+     * serializer writes verbatim: the L5 case looks for it in the export and
+     * compares what a commit writes with and without a view change in
+     * between. `undefined` = the L1 and L5 interaction cases are reported as
+     * skipped
      */
     openInteraction?(modeler: CollaborativeModeler): Promise<void> | void;
     /**
@@ -141,6 +157,15 @@ interface ConformanceHarness {
      * of the L1 interaction case is reported as skipped
      */
     interactionState?(modeler: CollaborativeModeler): InteractionState | undefined;
+    /**
+     * commit the interaction `openInteraction` opened, the way a user does
+     * (Enter, or a click on the canvas). The L5 interaction case commits once
+     * without a view change, proving the typed input changes the document,
+     * and once after a host's view change, checking the RECOMMENDED keep-open
+     * (an advisory, never a failure). `undefined` = both halves are reported
+     * as skipped
+     */
+    commitInteraction?(modeler: CollaborativeModeler): Promise<void> | void;
 }
 /** an interaction in progress, as `ConformanceHarness.interactionState` reports it */
 interface InteractionState {
@@ -173,11 +198,6 @@ interface ConformanceCase {
  * are given to 100% × 100%, which then resolves against the wrapper
  */
 declare function attachedHost(width?: number, height?: number): HTMLElement;
-/**
- * apiVersion compatibility: same major — and, while the contract is 0.x,
- * the same minor too (pre-1.0 minors may break; bump-minor-pre-major)
- */
-declare function apiVersionsCompatible(a: string, b: string): boolean;
 declare function conformanceCases(): ConformanceCase[];
 interface RegisterOptions {
     /** how a SKIPPED case is reported — a law the kit could not (fully) verify
@@ -191,4 +211,4 @@ interface RegisterOptions {
 /** bind every case to a (name, fn) test runner — node:test, vitest, jest */
 declare function registerConformance(harness: ConformanceHarness, test: (name: string, fn: () => Promise<void>) => unknown, options?: RegisterOptions): void;
 
-export { type CaseOutcome, type ConformanceCase, type ConformanceHarness, type InteractionState, type RegisterOptions, type UserMutation, apiVersionsCompatible, attachedHost, conformanceCases, registerConformance };
+export { type CaseOutcome, type ConformanceCase, type ConformanceHarness, type InteractionState, type RegisterOptions, type UserMutation, attachedHost, conformanceCases, registerConformance };

package/dist/conformance.js

@@ -1,6 +1,7 @@
 import {
-  MODELER_API_VERSION
-} from "./chunk-32BMH76T.js";
+  MODELER_API_VERSION,
+  apiVersionsCompatible
+} from "./chunk-E6KJB7QH.js";
 
 // src/conformance.ts
 function attachedHost(width = 800, height = 600) {
@@ -12,12 +13,6 @@ function attachedHost(width = 800, height = 600) {
   document.body.append(wrapper);
   return host;
 }
-function apiVersionsCompatible(a, b) {
-  const [aMajor = "", aMinor = ""] = a.split(".");
-  const [bMajor = "", bMinor = ""] = b.split(".");
-  if (aMajor !== bMajor) return false;
-  return aMajor !== "0" || aMinor === bMinor;
-}
 function fail(message) {
   throw new Error(`modeler-api conformance: ${message}`);
 }
@@ -30,6 +25,22 @@ function exportOrFail(modeler, when) {
   }
 }
 var same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+var hasBounds = (elements) => typeof elements.bounds === "function";
+var isFiniteBox = (box) => box !== void 0 && [box.x, box.y, box.width, box.height].every((n) => typeof n === "number" && Number.isFinite(n)) && box.width >= 0 && box.height >= 0;
+var describeBox = (box) => box === void 0 ? "undefined" : `{ x: ${box.x}, y: ${box.y}, width: ${box.width}, height: ${box.height} }`;
+function boxesOf(elements, when) {
+  const boxes = /* @__PURE__ */ new Map();
+  for (const { id } of elements.list()) {
+    const box = elements.bounds(id);
+    if (!isFiniteBox(box)) {
+      fail(
+        `elements.bounds('${id}') ${when} is ${describeBox(box)} \u2014 every listed id must give a finite box with a non-negative size`
+      );
+    }
+    boxes.set(id, { x: box.x, y: box.y, width: box.width, height: box.height });
+  }
+  return boxes;
+}
 function assertFinite(state, when) {
   const json = JSON.stringify(
     state,
@@ -544,6 +555,97 @@ ${out}`);
         }
       }
     },
+    {
+      name: "L5: a host's view change never commits an open interaction",
+      async run(h) {
+        if (!h.openInteraction) {
+          return skip(
+            "openInteraction is undefined \u2014 a host's view change over an open interaction (a label editor with typed input) was not verified"
+          );
+        }
+        if (h.viewState === void 0) {
+          return skip(
+            "viewState is undefined \u2014 a host's view change over an open interaction was not verified (supply a panned/zoomed state)"
+          );
+        }
+        const openInteraction = h.openInteraction;
+        const commitInteraction = h.commitInteraction;
+        const viewState = h.viewState;
+        const settle = h.settle ?? defaultSettle;
+        const first = h.canonicalTexts[0] ?? "";
+        const m = await h.create();
+        try {
+          await m.importText(first);
+          const doc = exportOrFail(m, "after importing canonicalTexts[0]");
+          const open = async () => {
+            await openInteraction(m);
+            await settle();
+            const opened2 = h.interactionState?.(m);
+            if (h.interactionState && opened2 === void 0) {
+              fail("interactionState reports no interaction after openInteraction \u2014 the case proves nothing");
+            }
+            return opened2;
+          };
+          let committed;
+          if (commitInteraction) {
+            const typed = (await open())?.text;
+            await commitInteraction(m);
+            await settle();
+            committed = exportOrFail(m, "after committing the interaction");
+            if (committed === doc || typed && !committed.includes(typed)) {
+              fail(
+                "committing the interaction openInteraction opened did not write its typed input into the export \u2014 the case proves nothing (commitInteraction must commit the way a user does, openInteraction type input the serializer writes verbatim)"
+              );
+            }
+            await importOrFail(m, first, "re-importing canonicalTexts[0] after the commit rejected");
+          }
+          const opened = await open();
+          const view = m.getViewState();
+          const { calls } = await changeEvents(h, m, () => m.setViewState(viewState));
+          if (calls > 0) {
+            fail(
+              `setViewState over an open interaction fired onContentChanged ${calls}x \u2014 the host's view change committed it (L5; if every setViewState emits, see the L5 round-trip case first)`
+            );
+          }
+          if (exportOrFail(m, "after setViewState over an open interaction") !== doc) {
+            fail(
+              "setViewState over an open interaction changed the export \u2014 the host's view change committed it (L5)"
+            );
+          }
+          if (same(m.getViewState(), view)) {
+            fail(
+              "setViewState(viewState) had no effect over an open interaction \u2014 the case proves nothing (supply a state that differs from the fitted view)"
+            );
+          }
+          const after = h.interactionState?.(m);
+          let advice;
+          if (opened !== void 0 && (after?.elementId !== opened.elementId || after?.text !== opened.text)) {
+            const input = opened.text === void 0 ? "" : ` with the input ${JSON.stringify(opened.text)}`;
+            const what = after === void 0 ? "closed it" : `left ${JSON.stringify(after)} open`;
+            advice = `an interaction on '${opened.elementId}'${input} did not survive a host's view change (setViewState ${what}) \u2014 RECOMMENDED: keep it open with its typed input, so the user's commit afterwards writes what it would have written without the view change`;
+          } else if (commitInteraction && committed !== void 0) {
+            await commitInteraction(m);
+            await settle();
+            const out = exportOrFail(m, "after committing the interaction after a view change");
+            if (out !== committed) {
+              advice = `committing an interaction after a host's view change wrote another document than committing it without one \u2014 RECOMMENDED: keep it open with its typed input across a view change (if openInteraction types different input per call, this advice is the harness's):
+--- committed without a view change
+${committed}
+--- committed after setViewState
+${out}`;
+            }
+          }
+          return {
+            ...commitInteraction ? {} : {
+              skipped: "commitInteraction is undefined \u2014 that the typed input changes the document (without it the case may prove nothing) and that it still commits after the view change were not checked (pass commitInteraction to check both)"
+            },
+            ...advice === void 0 ? {} : { advisories: [advice] }
+          };
+        } finally {
+          m.destroy();
+        }
+      }
+    },
     {
       name: "elements (when present): stable ids across re-imports and unrelated edits, reveal and selection semantics",
       async run(h) {
@@ -723,6 +825,84 @@ ${out}`);
         }
       }
     },
+    {
+      name: "elements.bounds (when present): a finite box in diagram coordinates for every listed id, undefined for an unknown one, live after a new element and a move",
+      async run(h) {
+        const text = h.canonicalTexts[0] ?? "";
+        const settle = h.settle ?? defaultSettle;
+        const m = await h.create();
+        let viewer;
+        try {
+          await m.importText(text);
+          const elements = m.elements;
+          if (!elements)
+            return skip("the modeler exposes no elements surface (optional) \u2014 nothing to verify");
+          if (!hasBounds(elements))
+            return skip("the modeler exposes no elements.bounds (optional) \u2014 nothing to verify");
+          boxesOf(elements, "after an import");
+          if (elements.bounds("__modeler_api_no_such_id__") !== void 0)
+            fail("elements.bounds(unknown id) must return undefined");
+          const imported = new Set(elements.list().map((e) => e.id));
+          await h.mutate(m);
+          await settle();
+          for (const { id } of elements.list().filter((e) => !imported.has(e.id))) {
+            const box = elements.bounds(id);
+            if (!isFiniteBox(box)) {
+              fail(
+                `elements.bounds('${id}') of an element created in the session is ${describeBox(box)} \u2014 bounds must read the live canvas, not the last import`
+              );
+            }
+          }
+          const unverified = [];
+          if (h.moveElement) {
+            const before = boxesOf(elements, "before a move");
+            const movedId = await h.moveElement(m);
+            await settle();
+            const was = before.get(movedId);
+            if (was === void 0)
+              fail(`moveElement returned '${movedId}', an id elements.list() did not report before the move`);
+            const box = boxesOf(elements, "after a move").get(movedId);
+            if (box === void 0)
+              fail(`'${movedId}' is gone from elements.list() after moveElement moved it`);
+            if (box.x === was.x && box.y === was.y) {
+              fail(
+                `elements.bounds('${movedId}') did not follow a move made through the modeler's own commands (still ${describeBox(was)}) \u2014 bounds must read the live canvas, not the last import (or moveElement did not move the element)`
+              );
+            }
+          } else {
+            unverified.push("moveElement is undefined \u2014 that a box follows a move was not verified");
+          }
+          if (h.viewState !== void 0) {
+            const atRest = boxesOf(elements, "before a view change");
+            m.setViewState(h.viewState);
+            for (const [id, box] of boxesOf(elements, "after setViewState")) {
+              if (!same(box, atRest.get(id))) {
+                fail(
+                  `elements.bounds('${id}') changed with the view (${describeBox(atRest.get(id))} \u2192 ${describeBox(box)}) \u2014 boxes are in diagram coordinates, which zoom and scroll leave alone`
+                );
+              }
+            }
+          } else {
+            unverified.push(
+              "viewState is undefined \u2014 that boxes are independent of the view was not verified"
+            );
+          }
+          if (h.createReadonly) {
+            viewer = await h.createReadonly();
+            await importOrFail(viewer, text, "the viewer rejected canonicalTexts[0]");
+            if (viewer.elements && hasBounds(viewer.elements)) {
+              boxesOf(viewer.elements, "on the viewer after an import");
+              if (viewer.elements.bounds("__modeler_api_no_such_id__") !== void 0)
+                fail("the viewer's elements.bounds(unknown id) must return undefined");
+            }
+          }
+          if (unverified.length > 0) return skip(unverified.join("; "));
+        } finally {
+          m.destroy();
+          viewer?.destroy();
+        }
+      }
+    },
     {
       name: "L6: export is total after imports, user mutations and undo",
       async run(h) {