@miragon/modeler-api 1.0.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
@@ -13,7 +14,9 @@ import { CollaborativeModeler } from './index.js';
  * assertion-library dependency. A case that CANNOT (fully) run because the
  * harness left an optional field undefined resolves with `{ skipped }` and
  * registerConformance reports it (console.warn by default) — a law the kit
- * did not verify is never a silent green.
+ * did not verify is never a silent green. A RECOMMENDATION the modeler does
+ * not follow resolves with `{ advisories }`, reported the same way and never
+ * a failure: a recommendation becomes a law only in a major release.
  */
 
 interface UserMutation {
@@ -27,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
@@ -51,10 +55,23 @@ interface ConformanceHarness {
      * NON-importable inputs (half-typed peer text, wrong notation) — the kit
      * verifies importText REJECTS, leaves no trace and stays usable (L7).
      * `undefined` = not provided (the L7 cases report a SKIP); `[]` = the
-     * deliberate statement that this notation has no non-importable text
-     * (the lenient line DSLs keep every line, so nothing rejects)
+     * deliberate statement that this notation has no LISTED non-importable
+     * text (the lenient line DSLs keep every line, so nothing rejects). The
+     * probes below run either way, so a parser that does reject some input
+     * is held to L7 on it
      */
     invalidTexts?: string[];
+    /**
+     * extra inputs for the L7 probe case, on top of the probes the kit derives
+     * from every canonical text: its first half, its first third, the text
+     * without its last character and the text followed by a NUL character.
+     * Unlike `invalidTexts`, a probe need not reject: one that imports must
+     * be silent (L1) with `exportText` total (L6), one that rejects must leave
+     * no trace (L7). Add the damaged forms your parser is likely to meet (a
+     * cut-off JSON object, an unclosed block). `undefined` and `[]` both mean
+     * "the derived probes only" — the probe case never skips
+     */
+    probeTexts?: string[];
     /**
      * importable documents carrying content the modeler does NOT understand
      * (vendor extensions, unknown lines, unknown JSON keys), each with the
@@ -80,8 +97,19 @@ interface ConformanceHarness {
     /**
      * perform ONE user-visible atomic ELEMENT command through the modeler's
      * own commands: ADD an element — never rename or delete one (the elements
-     * case treats it as an edit unrelated to the existing elements, and L4
-     * builds undo history from it, so it must be undoable)
+     * cases treat it as an edit unrelated to the existing elements and compare
+     * the ids two instances allocate for it, and L4 builds undo history from
+     * it, so it must be undoable). Let each call's element differ in content
+     * from the previous one (a counter the harness shares across instances,
+     * as the reference harness does): the collision case compares the ids two
+     * fresh instances allocate for one new element each, and an id derived
+     * from identical content (one that spells out the element's name)
+     * collides by design. The kit also runs it once on a
+     * fresh instance BEFORE the first import; a throw there is tolerated, and
+     * so is a call that never settles (a mutate waiting for the change event
+     * of a command the modeler ignores without a document): the kit stops
+     * waiting after 2 s — what a command does without a document is the
+     * modeler's choice
      */
     mutate(modeler: CollaborativeModeler): Promise<void> | void;
     /**
@@ -99,12 +127,65 @@ 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 (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;
+    /**
+     * the interaction open right now — the element it edits and its
+     * uncommitted input — or `undefined` when none is open. The kit reads it
+     * before and after a re-import of the same text to check the RECOMMENDED
+     * keep-and-reopen (an advisory, never a failure). `undefined` = that half
+     * 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 {
+    /** the stable id of the element the interaction edits (ElementInfo.id) */
+    elementId: string;
+    /** the uncommitted input, when the interaction has one */
+    text?: string;
 }
 interface CaseOutcome {
     /** the case could not (fully) verify its law — the harness left the field
      *  it needs undefined, or the modeler has no such optional surface; the
      *  reason names which */
     skipped?: string;
+    /**
+     * RECOMMENDED behaviour the modeler does not show. The case passed — the
+     * contract only recommends what is missing (a candidate for a law in the
+     * next major) — and registerConformance reports each advice through
+     * `onAdvisory`, never as a failure
+     */
+    advisories?: string[];
 }
 interface ConformanceCase {
     name: string;
@@ -117,18 +198,17 @@ 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
      *  because the harness left its field undefined. Default: console.warn */
     onSkip?: (caseName: string, reason: string) => void;
+    /** how an ADVISORY is reported — a RECOMMENDED behaviour the modeler does
+     *  not show; the case still passes. Called once per advice. Default:
+     *  console.warn */
+    onAdvisory?: (caseName: string, advice: string) => void;
 }
 /** 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 RegisterOptions, type UserMutation, apiVersionsCompatible, attachedHost, conformanceCases, registerConformance };
+export { type CaseOutcome, type ConformanceCase, type ConformanceHarness, type InteractionState, type RegisterOptions, type UserMutation, attachedHost, conformanceCases, registerConformance };