@miragon/modeler-shell 0.0.0-stage → 0.2.0

package/dist/testing.d.cts

@@ -0,0 +1,231 @@
+import { e as Size, P as PaletteRow, b as ChromeIsland, d as ShellHost, k as ToastStatus } from './toasts-Bp0REqdq.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>;
+    /**
+     * Playwright's `page.emulateMedia`; the web-host cases need it for the system's mode and contrast
+     * (`appearance`) and report a skip with `hook: "open"` without it.
+     */
+    emulateMedia?(options: {
+        colorScheme?: "light" | "dark" | "no-preference" | null;
+        contrast?: "more" | "no-preference" | null;
+        reducedMotion?: "reduce" | "no-preference" | null;
+        forcedColors?: "active" | "none" | null;
+    }): 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>>;
+    /**
+     * State attributes of the root: `[data-legend="open"]`, `[data-inspector="open"]`,
+     * `[data-problems="shown"]`, and in the web host `[data-empty-state="shown"]`,
+     * `[data-primary="collapsed"]` and `[data-zoom-row="raised"]`.
+     */
+    open: {
+        legend: boolean;
+        inspector: boolean;
+        problems: boolean;
+        emptyState: boolean;
+        primaryCollapsed: boolean;
+        zoomRaised: boolean;
+    };
+    /** Width of the widest visible toast card (`[data-status]` in the stack); absent without a toast. */
+    toastCardWidth?: number;
+}
+/** 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;
+    /** Vertical centre relative to the root (the web app's empty-state card). */
+    centerY?: 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. In the web host the
+     * system's preference without a stored choice: the kit emulates `prefers-color-scheme` and
+     * `prefers-contrast` (`PageLike.emulateMedia`) before `open`, and `open` loads the page with an
+     * empty `localStorage` entry `miragon.darstellung`.
+     */
+    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;
+    /**
+     * Web host: puts the page on its start screen, the way a fresh visit without a document shows
+     * it (`shell.setEmptyState(true)`); `open` itself loads a document.
+     */
+    emptyState?: ((page: P) => Promise<void>) | undefined;
+    /**
+     * Web and embedded hosts: shows `toast` through the modeler's `shell.toast`, with
+     * `{ label: toast.actionLabel, onSelect() {} }` as its action when `actionLabel` is given.
+     */
+    toast?: ((page: P, toast: ToastFixture) => Promise<void>) | undefined;
+}
+/** A toast the kit asks the `toast` hook to show (cases `toasts`, `geometry`). */
+interface ToastFixture {
+    status: ToastStatus;
+    text: string;
+    actionLabel?: string | undefined;
+}
+/** A file the kit drops on the page (case `dropZone`), built in the page as `new File([text], name, { type })`. */
+interface DropFixture {
+    name: string;
+    type: string;
+    text: string;
+}
+interface DropFixtures {
+    /** A file `DropZoneOptions.accept` takes; dropping it on the start screen opens it (the card goes). */
+    accepted: DropFixture;
+    /** A file outside `accept`; dropping it opens nothing and shows a danger toast (or the modeler's `onReject`). */
+    rejected?: DropFixture | undefined;
+    /** `DropZoneOptions.multiple` of the modeler; default `false`, so a drag of two files is forbidden. */
+    multiple?: boolean | undefined;
+}
+/**
+ * A show hook by name: the islands `legend`, `inspector`, `problems`, `status`, the state
+ * `invalid`, and in the web column `emptyState` and `toast`.
+ */
+type ShowHook = keyof ShowHooks;
+/**
+ * What a harness can lack: a show hook, the web app's drop zone (`drop`), or problems that point at
+ * an element (`problemSelection`: the modeler's diagnostics only name lines, so no row selects).
+ */
+type AbsentFeature = ShowHook | "drop" | "problemSelection";
+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;
+    /** Web host: the files the `dropZone` case drops; without them (and not `absent`) it is skipped with `hook: "drop"`. */
+    drop?: DropFixtures | 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 AbsentFeature[] | 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 | "drop" | "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; the web app's mode
+ * and its Appearance group) and `cleanup` (after `destroy` no shell element, class, attribute or
+ * key handling remains); then the web column's `webChrome`, `emptyState`, `toasts`,
+ * `problemsList` and `dropZone`, which assert in the other hosts that nothing of them shows.
+ */
+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 AbsentFeature, type ChromeMeasurement, type DropFixture, type DropFixtures, 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, type ToastFixture, expectedChromeBoxes, measureChrome, registerShellConformance, shellConformanceCases, vsCodeStubSearch };

package/dist/testing.d.ts

@@ -0,0 +1,231 @@
+import { e as Size, P as PaletteRow, b as ChromeIsland, d as ShellHost, k as ToastStatus } from './toasts-Bp0REqdq.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>;
+    /**
+     * Playwright's `page.emulateMedia`; the web-host cases need it for the system's mode and contrast
+     * (`appearance`) and report a skip with `hook: "open"` without it.
+     */
+    emulateMedia?(options: {
+        colorScheme?: "light" | "dark" | "no-preference" | null;
+        contrast?: "more" | "no-preference" | null;
+        reducedMotion?: "reduce" | "no-preference" | null;
+        forcedColors?: "active" | "none" | null;
+    }): 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>>;
+    /**
+     * State attributes of the root: `[data-legend="open"]`, `[data-inspector="open"]`,
+     * `[data-problems="shown"]`, and in the web host `[data-empty-state="shown"]`,
+     * `[data-primary="collapsed"]` and `[data-zoom-row="raised"]`.
+     */
+    open: {
+        legend: boolean;
+        inspector: boolean;
+        problems: boolean;
+        emptyState: boolean;
+        primaryCollapsed: boolean;
+        zoomRaised: boolean;
+    };
+    /** Width of the widest visible toast card (`[data-status]` in the stack); absent without a toast. */
+    toastCardWidth?: number;
+}
+/** 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;
+    /** Vertical centre relative to the root (the web app's empty-state card). */
+    centerY?: 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. In the web host the
+     * system's preference without a stored choice: the kit emulates `prefers-color-scheme` and
+     * `prefers-contrast` (`PageLike.emulateMedia`) before `open`, and `open` loads the page with an
+     * empty `localStorage` entry `miragon.darstellung`.
+     */
+    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;
+    /**
+     * Web host: puts the page on its start screen, the way a fresh visit without a document shows
+     * it (`shell.setEmptyState(true)`); `open` itself loads a document.
+     */
+    emptyState?: ((page: P) => Promise<void>) | undefined;
+    /**
+     * Web and embedded hosts: shows `toast` through the modeler's `shell.toast`, with
+     * `{ label: toast.actionLabel, onSelect() {} }` as its action when `actionLabel` is given.
+     */
+    toast?: ((page: P, toast: ToastFixture) => Promise<void>) | undefined;
+}
+/** A toast the kit asks the `toast` hook to show (cases `toasts`, `geometry`). */
+interface ToastFixture {
+    status: ToastStatus;
+    text: string;
+    actionLabel?: string | undefined;
+}
+/** A file the kit drops on the page (case `dropZone`), built in the page as `new File([text], name, { type })`. */
+interface DropFixture {
+    name: string;
+    type: string;
+    text: string;
+}
+interface DropFixtures {
+    /** A file `DropZoneOptions.accept` takes; dropping it on the start screen opens it (the card goes). */
+    accepted: DropFixture;
+    /** A file outside `accept`; dropping it opens nothing and shows a danger toast (or the modeler's `onReject`). */
+    rejected?: DropFixture | undefined;
+    /** `DropZoneOptions.multiple` of the modeler; default `false`, so a drag of two files is forbidden. */
+    multiple?: boolean | undefined;
+}
+/**
+ * A show hook by name: the islands `legend`, `inspector`, `problems`, `status`, the state
+ * `invalid`, and in the web column `emptyState` and `toast`.
+ */
+type ShowHook = keyof ShowHooks;
+/**
+ * What a harness can lack: a show hook, the web app's drop zone (`drop`), or problems that point at
+ * an element (`problemSelection`: the modeler's diagnostics only name lines, so no row selects).
+ */
+type AbsentFeature = ShowHook | "drop" | "problemSelection";
+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;
+    /** Web host: the files the `dropZone` case drops; without them (and not `absent`) it is skipped with `hook: "drop"`. */
+    drop?: DropFixtures | 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 AbsentFeature[] | 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 | "drop" | "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; the web app's mode
+ * and its Appearance group) and `cleanup` (after `destroy` no shell element, class, attribute or
+ * key handling remains); then the web column's `webChrome`, `emptyState`, `toasts`,
+ * `problemsList` and `dropZone`, which assert in the other hosts that nothing of them shows.
+ */
+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 AbsentFeature, type ChromeMeasurement, type DropFixture, type DropFixtures, 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, type ToastFixture, expectedChromeBoxes, measureChrome, registerShellConformance, shellConformanceCases, vsCodeStubSearch };