@ksp-gonogo/ui-kit 0.1.0 → 0.2.0-rc.12

package/dist/testing.d.ts

@@ -0,0 +1,471 @@
+import { F as FormatQuantityOptions } from './units-Cl-8ZdJc.js';
+import { RenderHookOptions, RenderHookResult, RenderOptions, RenderResult } from '@ksp-gonogo/sitrep-sdk/testing';
+import { ReactElement, JSXElementConstructor, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentDefinition } from '@ksp-gonogo/sitrep-sdk';
+
+/**
+ * A checkered-flag test for framed pictures: paint a pattern of square cells
+ * into a box and ask what a cell looks like on screen, with no pixels involved.
+ *
+ * Three different faults make a framed picture look wrong, and they are easy to
+ * mistake for each other by eye:
+ *
+ * - **distortion**: the picture is scaled by different amounts per axis, so a
+ *   square cell renders as a rectangle
+ * - **cropping**: cells stay square, but some of them are painted outside the
+ *   box and lost off its edge
+ * - **field of view**: cells stay square and nothing is cut off, but the source
+ *   was rendered showing a different grid than the one intended, so more or
+ *   fewer cells are visible
+ *
+ * jsdom lays nothing out, so this is geometry rather than measurement: the
+ * caller supplies the box it gave the picture, and the fit comes from the
+ * element (see {@link fitOf}) or is stated.
+ */
+/**
+ * A pattern of square cells, `cols` wide and `rows` high. Either may be fractional.
+ *
+ * @category Testing
+ */
+interface CheckerGrid {
+    cols: number;
+    rows: number;
+}
+/**
+ * The `object-fit` values that scale a picture to its box.
+ *
+ * @category Testing
+ */
+type CheckerFit = "fill" | "contain" | "cover";
+/**
+ * How a {@link CheckerGrid} lands in a box under a given fit, in CSS px.
+ *
+ * @category Testing
+ */
+interface CheckerPaint {
+    /** The grid the source picture carries. */
+    grid: CheckerGrid;
+    fit: CheckerFit;
+    box: {
+        width: number;
+        height: number;
+    };
+    /** The painted picture's own size, which exceeds `box` on a cropped axis and falls short of it on a letterboxed one. */
+    painted: {
+        width: number;
+        height: number;
+    };
+    cellWidth: number;
+    cellHeight: number;
+    /** Cells visible inside the box per axis, never more than the grid holds. */
+    visible: CheckerGrid;
+}
+/**
+ * One of the three ways a framed picture goes wrong. `distortion` renders a
+ * square cell as a rectangle; `cropping` keeps cells square and loses some
+ * off the box's edge; `field-of-view` keeps cells square and whole but shows a
+ * different grid from the one intended.
+ *
+ * @category Testing
+ */
+type FramingFault = "distortion" | "cropping" | "field-of-view";
+/**
+ * Relative slack on every comparison, 1%. A box floored to whole pixels to fit a
+ * feed's aspect sits a fraction of a percent off it, which is not a fault; a
+ * real distortion is far larger.
+ *
+ * @category Testing
+ */
+declare const CHECKER_TOLERANCE = 0.01;
+/**
+ * Paint `grid` into `box` under `fit`, centred as `object-position` defaults.
+ * The source's pixel size never matters: every supported fit scales it to the
+ * box, so only its shape does, and that is the grid's.
+ *
+ * @category Testing
+ */
+declare function paintChecker(grid: CheckerGrid, box: {
+    width: number;
+    height: number;
+}, fit: CheckerFit): CheckerPaint;
+/**
+ * Every {@link FramingFault} `paint` shows.
+ * `intended` is the grid the picture was meant to carry (a camera's own
+ * aspect, say); without it a field-of-view change cannot be told from a
+ * faithful picture, so it is never reported.
+ *
+ * @category Testing
+ */
+declare function framingFaults(paint: CheckerPaint, intended?: CheckerGrid): FramingFault[];
+/**
+ * The fit an element paints its picture with. An `<svg>` takes it from its
+ * `preserveAspectRatio` (`none` fills, `slice` covers, anything else
+ * contains); every other element from its `object-fit`, which is `fill` unless
+ * set, and `contain` on a `<video>`, whose user-agent style says so. Throws for
+ * an `<svg>` with no `viewBox`, which does not scale its content at all, and
+ * for `none` or `scale-down`, which depend on a pixel size the checker does not
+ * have.
+ *
+ * @category Testing
+ */
+declare function fitOf(element: Element): CheckerFit;
+
+/**
+ * Asserts that a component's live region is in the document, empty, before its
+ * first message, and that the same element is still there holding the message
+ * afterwards.
+ *
+ * Assistive tech announces a CHANGE to a region it already knows. A region
+ * inserted together with its words is often never announced, and a test that
+ * only looks at the final DOM cannot see that: the words are there either way.
+ * Call this with `container` rendered in the state that has nothing to say, and
+ * `reveal` doing whatever makes the component say something (a rerender, a
+ * store write, a click). Rendering the region only once it has content, as
+ * `{message && <span role="status">{message}</span>}` does, fails the first
+ * check; keeping the region mounted for as long as the thing it reports on is
+ * on screen passes.
+ *
+ * `region` narrows which live region is under test when a component carries
+ * several, as a selector. It defaults to every `aria-live` element and every
+ * `status`, `log` and `alert` role under `container`.
+ *
+ * @example
+ * ```tsx
+ * const { container, rerender } = render(<Outcome entries={[]} />);
+ * await expectLiveRegionPrimed(container, () =>
+ *   rerender(<Outcome entries={[sent]} />),
+ * );
+ * ```
+ *
+ * @category Testing
+ */
+declare function expectLiveRegionPrimed(container: HTMLElement, reveal: () => void | Promise<void>, region?: string): Promise<HTMLElement[]>;
+
+/**
+ * The accessibility smoke assertion for a widget test: runs `axe` over
+ * `container` (an element or a selector) and fails on any violation.
+ *
+ * The whole check runs inside `act`, so a widget with a clock or a
+ * subscription that keeps updating while `axe` walks the DOM raises no act
+ * warning. Call this rather than `axe` directly. Needs `jest-axe` installed as
+ * a dev dependency of your own; it is loaded on first use.
+ *
+ * @example
+ * ```tsx
+ * import { expectNoA11yViolations, renderWidget } from "@ksp-gonogo/ui-kit/testing";
+ *
+ * it("has no accessibility violations", async () => {
+ *   const { container } = renderWidget("my-gauge");
+ *   await expectNoA11yViolations(container);
+ * });
+ * ```
+ *
+ * @category Testing
+ */
+declare function expectNoA11yViolations(container: Element | string): Promise<void>;
+
+/**
+ * Why a drawn held mark fails to tell an operator what it means:
+ * `silent` where nothing a screen reader hears names its grade, `no-hover`
+ * where the hover does not, and `no-as-of` where the hover leaves out the
+ * instant the spoken words give.
+ *
+ * @category Testing
+ */
+type HeldMarkFault = "silent" | "no-hover" | "no-as-of";
+/**
+ * One held mark that does not announce itself, with a short description of
+ * where it was drawn.
+ *
+ * @category Testing
+ */
+interface UnannouncedHeldMark {
+    mark: Element;
+    fault: HeldMarkFault;
+    where: string;
+}
+/**
+ * Every held mark (`[data-held-mark]`) under `root` that does not say what it
+ * means: its grade's word to a screen reader and on hover, with the hover
+ * naming the same "as of" instant the spoken words do.
+ *
+ * Keyed on the mark rather than the figure, so a mark drawn by hand outside any
+ * kit primitive is still asked about.
+ *
+ * @category Testing
+ */
+declare function unannouncedHeldMarks(root?: ParentNode): UnannouncedHeldMark[];
+
+/**
+ * The sdk's themed `render` (from `@ksp-gonogo/sitrep-sdk/testing`), with a
+ * command rail mounted above it, for a component under test that dispatches
+ * through `useCommand` but is not a registered widget. A dev build throws on a
+ * dispatch with no rail mounted. A caller's own `wrapper` nests inside the
+ * rail. For a registered widget use {@link renderWidget}, which carries one.
+ *
+ * @category Testing
+ */
+declare function renderWithRail(ui: ReactElement, options?: RenderOptions): RenderResult;
+/**
+ * The sdk's `renderHook`, with the same command rail as {@link renderWithRail},
+ * for a hook under test that calls `useCommand`.
+ *
+ * @category Testing
+ */
+declare function renderHookWithRail<Result, Props>(callback: (initialProps: Props) => Result, options?: RenderHookOptions<Props>): RenderHookResult<Result, Props>;
+
+/**
+ * Options for {@link renderWidget}.
+ *
+ * @category Testing
+ */
+interface RenderWidgetOptions {
+    /**
+     * The dashboard instance id, what the widget sees as
+     * `DashboardItemContext`'s `instanceId` and as its own `id` prop.
+     */
+    instanceId?: string;
+    /** Per-instance config, the widget's `config` prop. */
+    config?: Record<string, unknown>;
+    /** Grid units, the `w`/`h` props a responsive widget reads. */
+    w?: number;
+    /** Grid units, the widget's `h` prop. */
+    h?: number;
+    /** The widget's `onConfigChange`. Defaults to a no-op. */
+    onConfigChange?: (config: Record<string, unknown>) => void;
+    /**
+     * Mounted outside the dashboard stack, where the app mounts the equivalent:
+     * a stream fixture's `Provider` belongs above the widget host, because the
+     * host's own hooks read telemetry through it.
+     */
+    wrapper?: JSXElementConstructor<{
+        children: ReactNode;
+    }>;
+}
+/**
+ * The provider stack the dashboard puts around every widget, in the same
+ * order, for a registered widget id: the command rail, the panel status store,
+ * the widget's instance and metadata, augment settings and contributions.
+ * {@link renderWidget} uses it; use it directly to wrap a tree of your own.
+ *
+ * It omits three things the dashboard also wraps a widget in, because each
+ * would make a test quieter rather than truer:
+ *
+ * - an error boundary, which turns a throw into a fallback UI. In a test a
+ *   throw should reach the test
+ * - the requires guard, which hides a widget whose `requires` domain is absent.
+ *   A test asserting on a widget's contents wants the widget, not the gate;
+ *   test the gate by asserting on `def.requires` directly
+ * - the alarm-status bridge, which folds firing alarms into the status store.
+ *   It needs an alarm host, which is app-side, and it renders nothing
+ *
+ * @category Testing
+ */
+declare function WidgetHost({ widgetId, instanceId, children, }: {
+    /** The registered widget id, which the stack is built from. */
+    widgetId: string;
+    /** Defaults to `<widgetId>-test`, matching `renderWidget`. */
+    instanceId?: string;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * The same stack as {@link WidgetHost}, given the component definition rather
+ * than an id to look one up by: for a harness previewing an augment against a
+ * synthetic host definition.
+ *
+ * @category Testing
+ */
+declare function WidgetHostFor({ def, instanceId, children, }: {
+    def: ComponentDefinition;
+    instanceId: string;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Render a widget the way the dashboard does: by its registered id, inside the
+ * provider stack the dashboard puts around one ({@link WidgetHost}). A bare
+ * `render` omits that stack, so for instance a `Panel` status badge would never
+ * appear. The widget must already be registered, which a widget's module does
+ * when it is loaded by calling the sdk's `registerComponent`, so import that
+ * module first; an unknown id throws and lists the registered ones.
+ *
+ * Returns the `RenderResult` of `@ksp-gonogo/sitrep-sdk/testing`'s `render`. A
+ * widget with unusual needs drops to `render` and builds its own scaffolding.
+ *
+ * @example
+ * ```tsx
+ * import { screen } from "@ksp-gonogo/sitrep-sdk/testing";
+ * import { renderWidget } from "@ksp-gonogo/ui-kit/testing";
+ * import { expect, it } from "vitest";
+ * import "./MyGauge"; // registers "my-gauge" on load
+ *
+ * it("shows its label", () => {
+ *   renderWidget("my-gauge", { config: { label: "Apoapsis" }, w: 4, h: 3 });
+ *   expect(screen.getByText("Apoapsis")).toBeTruthy();
+ * });
+ * ```
+ *
+ * @category Testing
+ */
+declare function renderWidget(widgetId: string, options?: RenderWidgetOptions): RenderResult;
+
+/**
+ * Testing helpers for the readouts this kit renders, published as
+ * `@ksp-gonogo/ui-kit/testing` (separate from the root so a runtime bundle
+ * never pulls testing code in). `<Unit>` splits a readout into a number, a
+ * symbol and a hidden spoken word, so `getByText("12.4 km")` finds nothing;
+ * these read it back.
+ *
+ * `renderWidget` mounts a widget inside the dashboard's provider stack, which is
+ * made of this package's providers. `renderWithRail`/`renderHookWithRail` are
+ * the bare equivalent, the sdk's themed `render`/`renderHook` with a command
+ * rail mounted above it, for a component or hook under test that is not a
+ * registered widget but still dispatches through `useCommand`. Named apart
+ * from the sdk's own `render`/`renderHook` rather than shadowing them, since
+ * both packages are published. Neither re-exports the sdk's testing entry
+ * wholesale: an Uplink's setup takes a host from the sdk and a provider stack
+ * from here.
+ */
+/**
+ * What a sighted reader sees, with the screen-reader words removed:
+ * `textContent` of a `<Unit>` reads "12.4 km kilometres", this reads
+ * "12.4 km". Assert on `textContent`, or `getByText("kilometres")`, when the
+ * announcement is under test.
+ *
+ * Defaults to `document.body`. The thin space between a number and its symbol
+ * is normalised to an ordinary space.
+ *
+ * @category Testing
+ */
+declare function visibleText(container?: HTMLElement): string;
+/** The shape a matcher reports back to its test framework. */
+interface MatcherResult {
+    pass: boolean;
+    message: () => string;
+}
+/**
+ * `expect(container).toShowQuantity(value("m", 12400))`.
+ *
+ * Asserts that a quantity is on screen without naming how it is spelled: it
+ * formats through `writeQuantity`, the same ladder `<Unit>` renders with, so it
+ * survives a change to where metres hand off to kilometres. For the same
+ * reason it cannot catch a formatting bug. To pin the exact spelling, assert
+ * the literal:
+ *
+ * ```ts
+ * expect(visibleText()).toContain("12.4 km");
+ * ```
+ *
+ * Register it once, in a setup file:
+ *
+ * ```ts
+ * import { expect } from "vitest";
+ * import { unitMatchers } from "@ksp-gonogo/ui-kit/testing";
+ * expect.extend(unitMatchers);
+ * ```
+ *
+ * @category Testing
+ */
+declare const unitMatchers: {
+    toShowQuantity(received: HTMLElement | undefined, quantity: {
+        magnitude: number;
+        unit: string;
+    } | null | undefined, opts?: FormatQuantityOptions): MatcherResult;
+};
+/**
+ * Type augmentation for the matcher above, for a Vitest consumer to merge
+ * explicitly (importing this module never changes `expect` types on its own):
+ *
+ * ```ts
+ * declare module "vitest" {
+ *   interface Assertion<T> extends UnitMatchers<T> {}
+ * }
+ * ```
+ *
+ * @category Testing
+ */
+interface UnitMatchers<Result = unknown> {
+    toShowQuantity(quantity: {
+        magnitude: number;
+        unit: string;
+    } | null | undefined, opts?: FormatQuantityOptions): Result;
+}
+
+/**
+ * Every element under `container` that carries the kit's {@link Tooltip} with
+ * this text, a string matched whole or a pattern matched anywhere. The tip is
+ * the `data-tooltip` attribute, present whether or not the tip is open, so a
+ * test reads what an element would say without hovering it.
+ *
+ * @category Testing
+ */
+declare function getAllByTip(container: ParentNode, text: string | RegExp): HTMLElement[];
+/**
+ * The one element under `container` carrying this tip, or `null`; throws when
+ * more than one does.
+ *
+ * @category Testing
+ */
+declare function queryByTip(container: ParentNode, text: string | RegExp): HTMLElement | null;
+/**
+ * The one element under `container` carrying this tip; throws when there is
+ * none or more than one.
+ *
+ * @category Testing
+ */
+declare function getByTip(container: ParentNode, text: string | RegExp): HTMLElement;
+
+/**
+ * One observation of `target` at the given size, as a complete
+ * `ResizeObserverEntry` with every box filled. jsdom lays nothing out, so a
+ * self-sizing component otherwise renders at zero.
+ *
+ * @category Testing
+ */
+declare function resizeObservation(target: Element, size: {
+    width: number;
+    height: number;
+}): ResizeObserverEntry;
+/**
+ * Install a `ResizeObserver` that reports one fixed size to everything observed,
+ * and return the uninstall. `deliver` fires the callback during `observe`
+ * (`"sync"`, the default), or on a macrotask for a component that must not see
+ * a size during its own mount.
+ *
+ * The returned function is the only way to uninstall: `vi.unstubAllGlobals()`
+ * does not undo it, and installing either observer while one is live throws.
+ * Installing once at module scope and never restoring is fine.
+ *
+ * @category Testing
+ */
+declare function installFixedSizeResizeObserver(options: {
+    width: number;
+    height: number;
+    deliver?: "sync" | "macrotask";
+}): () => void;
+/**
+ * A `ResizeObserver` a test drives by hand: see {@link installDrivableResizeObserver}.
+ *
+ * @category Testing
+ */
+interface DrivableResizeObservers {
+    /** Deliver one observation of `target` at `size` to every observer watching it. */
+    resize(target: Element, size: {
+        width: number;
+        height: number;
+    }): void;
+    /** Restore the previous `ResizeObserver`. The only way to uninstall. */
+    uninstall(): void;
+}
+/**
+ * Install a `ResizeObserver` whose observations a test delivers itself, for a
+ * component whose behaviour is the response to a size change. `resize` reaches
+ * only observers watching the element, so a component that never subscribed
+ * cannot pass. Installing either observer while one is live throws; call
+ * `uninstall` when done, or install once at module scope.
+ *
+ * @category Testing
+ */
+declare function installDrivableResizeObserver(): DrivableResizeObservers;
+
+export { CHECKER_TOLERANCE, type CheckerFit, type CheckerGrid, type CheckerPaint, type DrivableResizeObservers, type FramingFault, type HeldMarkFault, type RenderWidgetOptions, type UnannouncedHeldMark, type UnitMatchers, WidgetHost, WidgetHostFor, expectLiveRegionPrimed, expectNoA11yViolations, fitOf, framingFaults, getAllByTip, getByTip, installDrivableResizeObserver, installFixedSizeResizeObserver, paintChecker, queryByTip, renderHookWithRail, renderWidget, renderWithRail, resizeObservation, unannouncedHeldMarks, unitMatchers, visibleText };