@miragon/modeler-api 1.2.0 → 1.4.0

package/dist/conformance.d.cts

@@ -10,6 +10,11 @@ export { apiVersionsCompatible } from './index.cjs';
  *   import { conformanceCases, registerConformance } from "@miragon/modeler-api/conformance";
  *   registerConformance(harness, test);            // node:test, vitest, jest — any (name, fn) runner
  *
+ * The runner must run the cases one after another, as node:test, vitest and
+ * jest do within a file unless told otherwise (no `test.concurrent`): the
+ * keys case moves the focus and dispatches keys in the one document every
+ * mounted instance listens to.
+ *
  * Cases throw plain Errors on violation, so the kit has no runner or
  * assertion-library dependency. A case that CANNOT (fully) run because the
  * harness left an optional field undefined resolves with `{ skipped }` and
@@ -31,13 +36,28 @@ interface ConformanceHarness {
      * 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. Keep
-     * `fitOnImport` at its default: the L5 cases check the modeler's own fit
+     * `fitOnImport` at its default: the L5 cases check the modeler's own fit.
+     * The keys case finds the canvas in the host `attachedHost()` made during
+     * this call (or takes the one `canvasElement` names): mount into one, or
+     * that case reports a skip
      */
     create(): Promise<CollaborativeModeler>;
     /** a fresh READ-ONLY instance (`meta.editable === false`) — the viewer
      *  mount hosts use on read-only surfaces; absent = the package ships no
-     *  viewer and the viewer case is reported as skipped */
+     *  viewer and the viewer case is reported as skipped. The keys case aims
+     *  its keys at the viewer too: mount it as `create()` does */
     createReadonly?(): Promise<CollaborativeModeler>;
+    /**
+     * the focusable element `modeler` (from `create()` or `createReadonly()`)
+     * placed in its host to take its keys: the keys case aims the keys that
+     * must act at it, and the host's controls it puts next to it and into the
+     * `attachedHost()` it lies in. `undefined` = the focusable `<svg>` (one
+     * with a `tabindex`, diagram-js's canvas) in the one `attachedHost()` the
+     * call mounted into. A modeler that takes its keys on another element (a
+     * `<div>`, a `<canvas>`) names it here; `null` or `undefined` returned, or
+     * an element outside every `attachedHost()`, is reported as a skip
+     */
+    canvasElement?(modeler: CollaborativeModeler): Element | null | undefined;
     /**
      * CANONICAL sample documents of the notation (>= 2, distinct, at least one
      * rendering an element, ideally several covering config/axis content too)
@@ -208,7 +228,15 @@ interface RegisterOptions {
      *  console.warn */
     onAdvisory?: (caseName: string, advice: string) => void;
 }
-/** bind every case to a (name, fn) test runner — node:test, vitest, jest */
+/**
+ * bind every case to a (name, fn) test runner — node:test, vitest, jest —
+ * that runs them one after another: the keys case moves the focus and
+ * dispatches keys in the one document every mounted instance listens to, so
+ * a case running beside it would see its keys or lose its focus. A case's
+ * advisories are reported before its skip, so an `onSkip` that throws does
+ * not hide them
+ */
 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, attachedHost, conformanceCases, registerConformance };
+export { attachedHost, conformanceCases, registerConformance };
+export type { CaseOutcome, ConformanceCase, ConformanceHarness, InteractionState, RegisterOptions, UserMutation };

package/dist/conformance.d.ts

@@ -10,6 +10,11 @@ export { apiVersionsCompatible } from './index.js';
  *   import { conformanceCases, registerConformance } from "@miragon/modeler-api/conformance";
  *   registerConformance(harness, test);            // node:test, vitest, jest — any (name, fn) runner
  *
+ * The runner must run the cases one after another, as node:test, vitest and
+ * jest do within a file unless told otherwise (no `test.concurrent`): the
+ * keys case moves the focus and dispatches keys in the one document every
+ * mounted instance listens to.
+ *
  * Cases throw plain Errors on violation, so the kit has no runner or
  * assertion-library dependency. A case that CANNOT (fully) run because the
  * harness left an optional field undefined resolves with `{ skipped }` and
@@ -31,13 +36,28 @@ interface ConformanceHarness {
      * 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. Keep
-     * `fitOnImport` at its default: the L5 cases check the modeler's own fit
+     * `fitOnImport` at its default: the L5 cases check the modeler's own fit.
+     * The keys case finds the canvas in the host `attachedHost()` made during
+     * this call (or takes the one `canvasElement` names): mount into one, or
+     * that case reports a skip
      */
     create(): Promise<CollaborativeModeler>;
     /** a fresh READ-ONLY instance (`meta.editable === false`) — the viewer
      *  mount hosts use on read-only surfaces; absent = the package ships no
-     *  viewer and the viewer case is reported as skipped */
+     *  viewer and the viewer case is reported as skipped. The keys case aims
+     *  its keys at the viewer too: mount it as `create()` does */
     createReadonly?(): Promise<CollaborativeModeler>;
+    /**
+     * the focusable element `modeler` (from `create()` or `createReadonly()`)
+     * placed in its host to take its keys: the keys case aims the keys that
+     * must act at it, and the host's controls it puts next to it and into the
+     * `attachedHost()` it lies in. `undefined` = the focusable `<svg>` (one
+     * with a `tabindex`, diagram-js's canvas) in the one `attachedHost()` the
+     * call mounted into. A modeler that takes its keys on another element (a
+     * `<div>`, a `<canvas>`) names it here; `null` or `undefined` returned, or
+     * an element outside every `attachedHost()`, is reported as a skip
+     */
+    canvasElement?(modeler: CollaborativeModeler): Element | null | undefined;
     /**
      * CANONICAL sample documents of the notation (>= 2, distinct, at least one
      * rendering an element, ideally several covering config/axis content too)
@@ -208,7 +228,15 @@ interface RegisterOptions {
      *  console.warn */
     onAdvisory?: (caseName: string, advice: string) => void;
 }
-/** bind every case to a (name, fn) test runner — node:test, vitest, jest */
+/**
+ * bind every case to a (name, fn) test runner — node:test, vitest, jest —
+ * that runs them one after another: the keys case moves the focus and
+ * dispatches keys in the one document every mounted instance listens to, so
+ * a case running beside it would see its keys or lose its focus. A case's
+ * advisories are reported before its skip, so an `onSkip` that throws does
+ * not hide them
+ */
 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, attachedHost, conformanceCases, registerConformance };
+export { attachedHost, conformanceCases, registerConformance };
+export type { CaseOutcome, ConformanceCase, ConformanceHarness, InteractionState, RegisterOptions, UserMutation };