@miragon/modeler-shell 0.0.0-stage → 0.1.0

package/dist/testing.d.cts

@@ -0,0 +1,165 @@
+import { d as Size, P as PaletteRow, a as ChromeIsland, c as ShellHost } from './types-B6NfkiUG.cjs';
+import { A as Appearance, T as Theme, C as ColorThemeSetting } from './appearance-D3FUcbu6.cjs';
+
+/**
+ * The part of Playwright's `Page` the kit drives, typed structurally: the kit has no runtime
+ * dependency on Playwright, the consumer's e2e suite passes its own `page`.
+ */
+interface PageLike {
+    evaluate<R, Arg>(pageFunction: (arg: Arg) => R | Promise<R>, arg: Arg): Promise<R>;
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    keyboard: {
+        press(key: string): Promise<void>;
+    };
+    mouse: {
+        click(x: number, y: number): Promise<void>;
+        dblclick(x: number, y: number): Promise<void>;
+        move(x: number, y: number): Promise<void>;
+        down(): Promise<void>;
+        up(): Promise<void>;
+    };
+    waitForTimeout(timeout: number): Promise<void>;
+}
+
+/** Every island box must match within this many pixels (guide §13.4). */
+declare const GEOMETRY_TOLERANCE_PX = 1;
+/**
+ * `getBoundingClientRect()` relative to the shell root's padding box, where its absolutely
+ * positioned islands anchor (a border on the root, as in a framed foreign page, does not count).
+ */
+interface IslandBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+interface ChromeMeasurement {
+    container: Size;
+    /** From the root's `data-palette` attribute. */
+    paletteRow: PaletteRow;
+    /** The visible islands, found by `[data-chrome]`. */
+    islands: Partial<Record<ChromeIsland, IslandBox>>;
+    /** `[data-legend="open"]`, `[data-inspector="open"]`, `[data-problems="shown"]` on the root. */
+    open: {
+        legend: boolean;
+        inspector: boolean;
+        problems: boolean;
+    };
+}
+/** Constraints of one island; every given field must hold within `GEOMETRY_TOLERANCE_PX`. */
+interface ExpectedBox {
+    left?: number;
+    top?: number;
+    right?: number;
+    bottom?: number;
+    width?: number;
+    height?: number;
+    /** Horizontal centre relative to the root. */
+    centerX?: number;
+}
+/** Measures the islands of the shell under `root` (default `.cd-shell`) in the page. */
+declare function measureChrome(page: PageLike, root?: string): Promise<ChromeMeasurement>;
+/** The boxes guide §5.2–§5.12 expects for what was measured (anchors per host and breakpoint). */
+declare function expectedChromeBoxes(measurement: ChromeMeasurement, host: ShellHost): Partial<Record<ChromeIsland, ExpectedBox>>;
+
+interface OpenContext {
+    /** The page's viewport, which is the modeler's container in an own document. */
+    size: Size;
+    /**
+     * What the host requests before the modeler resolves it: in an IDE host the VS Code color theme
+     * (`vsCodeStubSearch` hands it to a page with the VS Code stub). For an embedded host the kit
+     * itself puts the foreign page's `<html>` in this mode once `open` resolved.
+     */
+    requested: Appearance;
+}
+/**
+ * How the kit makes the optional islands visible (`geometry`, `aria`) and puts the modeler into its
+ * invalid-file state (`readOnly`).
+ */
+interface ShowHooks<P extends PageLike = PageLike> {
+    problems?: ((page: P) => Promise<void>) | undefined;
+    status?: ((page: P) => Promise<void>) | undefined;
+    legend?: ((page: P) => Promise<void>) | undefined;
+    inspector?: ((page: P) => Promise<void>) | undefined;
+    /**
+     * Puts the modeler into its invalid-file state the way its host does (an invalid import): a
+     * read-only canvas and the status box. The kit waits `INVALID_STATUS_DELAY_MS` afterwards.
+     */
+    invalid?: ((page: P) => Promise<void>) | undefined;
+}
+/** A show hook by name: the islands `legend`, `inspector`, `problems`, `status` and the state `invalid`. */
+type ShowHook = keyof ShowHooks;
+interface ShellConformanceHarness<P extends PageLike = PageLike> {
+    host: ShellHost;
+    /** The modes the modeler declares (static); the appearance case requests dark from `["light"]`. */
+    themes: readonly Theme[];
+    /** Load the modeler with the shell at `size`, as the host would with `requested`; resolve once the first import is done. */
+    open(page: P, context: OpenContext): Promise<void>;
+    /** Tear modeler and shell down through the page's own path; `undefined` skips the cleanup case. */
+    destroy?: ((page: P) => Promise<void>) | undefined;
+    /** CSS selector of the shell root; default `.cd-shell`. */
+    root?: string | undefined;
+    /** Hooks for the islands and states the modeler has; one that is neither given nor `absent` is reported as skipped. */
+    show?: ShowHooks<P> | undefined;
+    /**
+     * The islands and states the modeler does not have. An absent hook is not reported as skipped,
+     * and `geometry` and `aria` assert that its island is never visible. Listing a hook that `show`
+     * also gives fails every case that uses it.
+     */
+    absent?: readonly ShowHook[] | undefined;
+    /** Container sizes of the geometry case; default wide 1280 × 900, narrow 720 × 700, very narrow 420 × 700. */
+    sizes?: readonly Size[] | undefined;
+}
+/** One part of a case the harness could not feed. */
+interface ShellSkip {
+    /**
+     * The harness field that would feed it: a show hook, `destroy`, or `open` when the document it
+     * opens lacks what the case needs (a shape on the canvas).
+     */
+    hook: ShowHook | "destroy" | "open";
+    reason: string;
+}
+interface ShellCaseOutcome {
+    /** What the case could not (fully) run, one entry per missing harness field. */
+    skipped?: readonly ShellSkip[];
+}
+interface ShellConformanceCase {
+    name: string;
+    run<P extends PageLike>(page: P, harness: ShellConformanceHarness<P>): Promise<ShellCaseOutcome | void>;
+}
+/**
+ * The cases: `geometry` (every `data-chrome` island ±1px, per host and breakpoint), `aria`
+ * (roles, names, `aria-expanded`/`-controls`/`-keyshortcuts`/`-disabled`, DOM order, no positive
+ * tabindex), `keys` (each chrome key acts exactly once; in the IDE host a `keydown` listener on
+ * `window` never fires for a handled key; unmodified `+`/`-` never zoom; select all acts on the
+ * canvas only), `create` (Enter on the first creating palette entry places one selected element in
+ * the free rectangle and focuses the canvas), `readOnly` (the invalid-file lock of guide §13.5),
+ * `appearance` (dark requested from a light-only modeler: nothing turns dark, `color-scheme` light
+ * everywhere, the canvas surround and the palette's tool colours from the roles) and `cleanup` (after
+ * `destroy` no shell element, class, attribute or key handling remains).
+ */
+declare function shellConformanceCases(): ShellConformanceCase[];
+/** Playwright's `test` (or any runner whose body receives `{ page }`). */
+type ShellConformanceTest<P extends PageLike = PageLike> = (name: string, body: (fixtures: {
+    page: P;
+}) => Promise<void>) => unknown;
+interface RegisterShellConformanceOptions {
+    /** Default: `console.warn`, one line per case with its skips joined by "; ". */
+    onSkip?: ((caseName: string, skips: readonly ShellSkip[]) => void) | undefined;
+}
+/**
+ * The query string for a test page that installs the VS Code stub of
+ * `@miragon/modeler-shell/testing/vscode-stub` with `stubOptionsFromSearch(location.search)`:
+ * `theme=dark&kontrast=hoch`, plus the `colorTheme` setting and VS Code's reduce motion.
+ */
+declare function vsCodeStubSearch(requested: Appearance, extra?: {
+    colorTheme?: ColorThemeSetting | undefined;
+    reduceMotion?: boolean | undefined;
+}): string;
+/** Registers every case as `shell conformance: <name>`. */
+declare function registerShellConformance<P extends PageLike>(harness: ShellConformanceHarness<P>, test: ShellConformanceTest<P>, options?: RegisterShellConformanceOptions): void;
+
+export { type ChromeMeasurement, type ExpectedBox, GEOMETRY_TOLERANCE_PX, type IslandBox, type OpenContext, type PageLike, type RegisterShellConformanceOptions, type ShellCaseOutcome, type ShellConformanceCase, type ShellConformanceHarness, type ShellConformanceTest, type ShellSkip, type ShowHook, type ShowHooks, expectedChromeBoxes, measureChrome, registerShellConformance, shellConformanceCases, vsCodeStubSearch };

package/dist/testing.d.ts

@@ -0,0 +1,165 @@
+import { d as Size, P as PaletteRow, a as ChromeIsland, c as ShellHost } from './types-B6NfkiUG.js';
+import { A as Appearance, T as Theme, C as ColorThemeSetting } from './appearance-D3FUcbu6.js';
+
+/**
+ * The part of Playwright's `Page` the kit drives, typed structurally: the kit has no runtime
+ * dependency on Playwright, the consumer's e2e suite passes its own `page`.
+ */
+interface PageLike {
+    evaluate<R, Arg>(pageFunction: (arg: Arg) => R | Promise<R>, arg: Arg): Promise<R>;
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    keyboard: {
+        press(key: string): Promise<void>;
+    };
+    mouse: {
+        click(x: number, y: number): Promise<void>;
+        dblclick(x: number, y: number): Promise<void>;
+        move(x: number, y: number): Promise<void>;
+        down(): Promise<void>;
+        up(): Promise<void>;
+    };
+    waitForTimeout(timeout: number): Promise<void>;
+}
+
+/** Every island box must match within this many pixels (guide §13.4). */
+declare const GEOMETRY_TOLERANCE_PX = 1;
+/**
+ * `getBoundingClientRect()` relative to the shell root's padding box, where its absolutely
+ * positioned islands anchor (a border on the root, as in a framed foreign page, does not count).
+ */
+interface IslandBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+interface ChromeMeasurement {
+    container: Size;
+    /** From the root's `data-palette` attribute. */
+    paletteRow: PaletteRow;
+    /** The visible islands, found by `[data-chrome]`. */
+    islands: Partial<Record<ChromeIsland, IslandBox>>;
+    /** `[data-legend="open"]`, `[data-inspector="open"]`, `[data-problems="shown"]` on the root. */
+    open: {
+        legend: boolean;
+        inspector: boolean;
+        problems: boolean;
+    };
+}
+/** Constraints of one island; every given field must hold within `GEOMETRY_TOLERANCE_PX`. */
+interface ExpectedBox {
+    left?: number;
+    top?: number;
+    right?: number;
+    bottom?: number;
+    width?: number;
+    height?: number;
+    /** Horizontal centre relative to the root. */
+    centerX?: number;
+}
+/** Measures the islands of the shell under `root` (default `.cd-shell`) in the page. */
+declare function measureChrome(page: PageLike, root?: string): Promise<ChromeMeasurement>;
+/** The boxes guide §5.2–§5.12 expects for what was measured (anchors per host and breakpoint). */
+declare function expectedChromeBoxes(measurement: ChromeMeasurement, host: ShellHost): Partial<Record<ChromeIsland, ExpectedBox>>;
+
+interface OpenContext {
+    /** The page's viewport, which is the modeler's container in an own document. */
+    size: Size;
+    /**
+     * What the host requests before the modeler resolves it: in an IDE host the VS Code color theme
+     * (`vsCodeStubSearch` hands it to a page with the VS Code stub). For an embedded host the kit
+     * itself puts the foreign page's `<html>` in this mode once `open` resolved.
+     */
+    requested: Appearance;
+}
+/**
+ * How the kit makes the optional islands visible (`geometry`, `aria`) and puts the modeler into its
+ * invalid-file state (`readOnly`).
+ */
+interface ShowHooks<P extends PageLike = PageLike> {
+    problems?: ((page: P) => Promise<void>) | undefined;
+    status?: ((page: P) => Promise<void>) | undefined;
+    legend?: ((page: P) => Promise<void>) | undefined;
+    inspector?: ((page: P) => Promise<void>) | undefined;
+    /**
+     * Puts the modeler into its invalid-file state the way its host does (an invalid import): a
+     * read-only canvas and the status box. The kit waits `INVALID_STATUS_DELAY_MS` afterwards.
+     */
+    invalid?: ((page: P) => Promise<void>) | undefined;
+}
+/** A show hook by name: the islands `legend`, `inspector`, `problems`, `status` and the state `invalid`. */
+type ShowHook = keyof ShowHooks;
+interface ShellConformanceHarness<P extends PageLike = PageLike> {
+    host: ShellHost;
+    /** The modes the modeler declares (static); the appearance case requests dark from `["light"]`. */
+    themes: readonly Theme[];
+    /** Load the modeler with the shell at `size`, as the host would with `requested`; resolve once the first import is done. */
+    open(page: P, context: OpenContext): Promise<void>;
+    /** Tear modeler and shell down through the page's own path; `undefined` skips the cleanup case. */
+    destroy?: ((page: P) => Promise<void>) | undefined;
+    /** CSS selector of the shell root; default `.cd-shell`. */
+    root?: string | undefined;
+    /** Hooks for the islands and states the modeler has; one that is neither given nor `absent` is reported as skipped. */
+    show?: ShowHooks<P> | undefined;
+    /**
+     * The islands and states the modeler does not have. An absent hook is not reported as skipped,
+     * and `geometry` and `aria` assert that its island is never visible. Listing a hook that `show`
+     * also gives fails every case that uses it.
+     */
+    absent?: readonly ShowHook[] | undefined;
+    /** Container sizes of the geometry case; default wide 1280 × 900, narrow 720 × 700, very narrow 420 × 700. */
+    sizes?: readonly Size[] | undefined;
+}
+/** One part of a case the harness could not feed. */
+interface ShellSkip {
+    /**
+     * The harness field that would feed it: a show hook, `destroy`, or `open` when the document it
+     * opens lacks what the case needs (a shape on the canvas).
+     */
+    hook: ShowHook | "destroy" | "open";
+    reason: string;
+}
+interface ShellCaseOutcome {
+    /** What the case could not (fully) run, one entry per missing harness field. */
+    skipped?: readonly ShellSkip[];
+}
+interface ShellConformanceCase {
+    name: string;
+    run<P extends PageLike>(page: P, harness: ShellConformanceHarness<P>): Promise<ShellCaseOutcome | void>;
+}
+/**
+ * The cases: `geometry` (every `data-chrome` island ±1px, per host and breakpoint), `aria`
+ * (roles, names, `aria-expanded`/`-controls`/`-keyshortcuts`/`-disabled`, DOM order, no positive
+ * tabindex), `keys` (each chrome key acts exactly once; in the IDE host a `keydown` listener on
+ * `window` never fires for a handled key; unmodified `+`/`-` never zoom; select all acts on the
+ * canvas only), `create` (Enter on the first creating palette entry places one selected element in
+ * the free rectangle and focuses the canvas), `readOnly` (the invalid-file lock of guide §13.5),
+ * `appearance` (dark requested from a light-only modeler: nothing turns dark, `color-scheme` light
+ * everywhere, the canvas surround and the palette's tool colours from the roles) and `cleanup` (after
+ * `destroy` no shell element, class, attribute or key handling remains).
+ */
+declare function shellConformanceCases(): ShellConformanceCase[];
+/** Playwright's `test` (or any runner whose body receives `{ page }`). */
+type ShellConformanceTest<P extends PageLike = PageLike> = (name: string, body: (fixtures: {
+    page: P;
+}) => Promise<void>) => unknown;
+interface RegisterShellConformanceOptions {
+    /** Default: `console.warn`, one line per case with its skips joined by "; ". */
+    onSkip?: ((caseName: string, skips: readonly ShellSkip[]) => void) | undefined;
+}
+/**
+ * The query string for a test page that installs the VS Code stub of
+ * `@miragon/modeler-shell/testing/vscode-stub` with `stubOptionsFromSearch(location.search)`:
+ * `theme=dark&kontrast=hoch`, plus the `colorTheme` setting and VS Code's reduce motion.
+ */
+declare function vsCodeStubSearch(requested: Appearance, extra?: {
+    colorTheme?: ColorThemeSetting | undefined;
+    reduceMotion?: boolean | undefined;
+}): string;
+/** Registers every case as `shell conformance: <name>`. */
+declare function registerShellConformance<P extends PageLike>(harness: ShellConformanceHarness<P>, test: ShellConformanceTest<P>, options?: RegisterShellConformanceOptions): void;
+
+export { type ChromeMeasurement, type ExpectedBox, GEOMETRY_TOLERANCE_PX, type IslandBox, type OpenContext, type PageLike, type RegisterShellConformanceOptions, type ShellCaseOutcome, type ShellConformanceCase, type ShellConformanceHarness, type ShellConformanceTest, type ShellSkip, type ShowHook, type ShowHooks, expectedChromeBoxes, measureChrome, registerShellConformance, shellConformanceCases, vsCodeStubSearch };