@describe-me/core 0.5.4 → 0.6.1

package/README.md

@@ -15,7 +15,7 @@ story, and each step is a frame you can scrub through. Stories cannot rot,
 because they are tests. If one drifts from the component, CI goes red.
 
 Status: prototype. React 18 and 19, Vitest 4 and 5 in browser mode or jsdom,
-static snapshots.
+recorded frames and Live in the viewer.
 
 ## Which package do I need
 
@@ -53,12 +53,13 @@ The framework-agnostic heart of describe-me. Snapshots are serialized DOM via
 `rrweb-snapshot`, so nothing here knows about React. You need it directly only
 to write an adapter for another framework or to read the output yourself.
 
-| Entry point                                                                                                    | What it holds                                           |
-| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| [`@describe-me/core`](https://grzehub.github.io/describe-me/api.html#entry-core)                               | `step()`, `recorder` and `elementLabel()`, for adapters |
-| [`@describe-me/core/types`](https://grzehub.github.io/describe-me/api.html#entry-core-types)                   | the types of `.describe-me/manifest.json`               |
-| [`@describe-me/core/diagnostics`](https://grzehub.github.io/describe-me/api.html#entry-core-diagnostics)       | what a manifest could not document                      |
-| [`@describe-me/core/css-references`](https://grzehub.github.io/describe-me/api.html#entry-core-css-references) | the `url()` and `@import` references in CSS text        |
+| Entry point                                                                                                    | What it holds                                                              |
+| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [`@describe-me/core`](https://grzehub.github.io/describe-me/api.html#entry-core)                               | `step()`, `recorder` and `elementLabel()`, for adapters                    |
+| [`@describe-me/core/types`](https://grzehub.github.io/describe-me/api.html#entry-core-types)                   | the types of `.describe-me/manifest.json`                                  |
+| [`@describe-me/core/diagnostics`](https://grzehub.github.io/describe-me/api.html#entry-core-diagnostics)       | what a manifest could not document                                         |
+| [`@describe-me/core/css-references`](https://grzehub.github.io/describe-me/api.html#entry-core-css-references) | the `url()` and `@import` references in CSS text                           |
+| [`@describe-me/core/live`](https://grzehub.github.io/describe-me/api.html#entry-core-live)                     | the live page's state and its messages to the viewer, for the live preview |
 
 [How it works](https://grzehub.github.io/describe-me/how-it-works.html) explains
 the recorder and the output directory.

package/dist/is-live-stop.d.ts

@@ -0,0 +1,2 @@
+/** Whether a thrown value is the live page's stop signal rather than a failure. */
+export declare function isLiveStop(value: unknown): boolean;

package/dist/is-live-stop.js

@@ -0,0 +1,5 @@
+import { liveState } from './live-state.js';
+/** Whether a thrown value is the live page's stop signal rather than a failure. */
+export function isLiveStop(value) {
+    return value === liveState().stop;
+}

package/dist/live-inert.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A value that takes any property access, call or `new` and gives back an
+ * inert value again. Test code after the first render never runs, but it must
+ * import, and hooks may call it. `await` ends on it, because it has no `then`.
+ */
+export declare function liveInert(): unknown;

package/dist/live-inert.js

@@ -0,0 +1,34 @@
+let inert;
+function createInert() {
+    // A plain function, so the value can be called and constructed.
+    const value = new Proxy(function inertTarget() { }, {
+        get(_target, key) {
+            if (key === 'then') {
+                return undefined;
+            }
+            if (key === Symbol.toPrimitive) {
+                return () => '';
+            }
+            if (key === Symbol.iterator) {
+                return () => [][Symbol.iterator]();
+            }
+            return value;
+        },
+        apply() {
+            return value;
+        },
+        construct() {
+            return value;
+        },
+    });
+    return value;
+}
+/**
+ * A value that takes any property access, call or `new` and gives back an
+ * inert value again. Test code after the first render never runs, but it must
+ * import, and hooks may call it. `await` ends on it, because it has no `then`.
+ */
+export function liveInert() {
+    inert ??= createInert();
+    return inert;
+}

package/dist/live-state.d.ts

@@ -0,0 +1,20 @@
+import type { LiveStatus } from './types.js';
+/** What the height observer keeps between animation frames. */
+interface LiveHeightState {
+    observing: boolean;
+    queued: boolean;
+    reported: number | null;
+}
+/** Everything one live page shares, whichever copy of core reads it. */
+export interface LiveState {
+    status: LiveStatus | null;
+    stop: Error;
+    height: LiveHeightState;
+}
+/**
+ * The state of the live page. Vite can serve two copies of core, one bundled
+ * with an adapter and one from source, so the state lives on `globalThis`,
+ * like the recorder.
+ */
+export declare function liveState(): LiveState;
+export {};

package/dist/live-state.js

@@ -0,0 +1,20 @@
+const LIVE_KEY = Symbol.for('describe-me.live');
+function createStop() {
+    const stop = new Error('describe-me: the live preview stops the test at its first render');
+    stop.name = 'LiveStop';
+    return stop;
+}
+/**
+ * The state of the live page. Vite can serve two copies of core, one bundled
+ * with an adapter and one from source, so the state lives on `globalThis`,
+ * like the recorder.
+ */
+export function liveState() {
+    const scope = globalThis;
+    scope[LIVE_KEY] ??= {
+        status: null,
+        stop: createStop(),
+        height: { observing: false, queued: false, reported: null },
+    };
+    return scope[LIVE_KEY];
+}

package/dist/live-status.d.ts

@@ -0,0 +1,3 @@
+import type { LiveStatus } from './types.js';
+/** The status the live page reported so far, or null before the first one. */
+export declare function liveStatus(): LiveStatus | null;

package/dist/live-status.js

@@ -0,0 +1,5 @@
+import { liveState } from './live-state.js';
+/** The status the live page reported so far, or null before the first one. */
+export function liveStatus() {
+    return liveState().status;
+}

package/dist/live-stop.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The page's one stop signal. The live render throws it to end the test at
+ * its first render, and the runner tells it apart from a failure.
+ */
+export declare function liveStop(): Error;

package/dist/live-stop.js

@@ -0,0 +1,8 @@
+import { liveState } from './live-state.js';
+/**
+ * The page's one stop signal. The live render throws it to end the test at
+ * its first render, and the runner tells it apart from a failure.
+ */
+export function liveStop() {
+    return liveState().stop;
+}

package/dist/live.d.ts

@@ -0,0 +1,7 @@
+export { isLiveStop } from './is-live-stop.js';
+export { liveInert } from './live-inert.js';
+export { liveStatus } from './live-status.js';
+export { liveStop } from './live-stop.js';
+export { observeLiveHeight } from './observe-live-height.js';
+export { postLiveMessage } from './post-live-message.js';
+export { reportLiveStatus } from './report-live-status.js';

package/dist/live.js

@@ -0,0 +1,8 @@
+// For the live preview page, not for tests: its status, messages, stop signal and height.
+export { isLiveStop } from './is-live-stop.js';
+export { liveInert } from './live-inert.js';
+export { liveStatus } from './live-status.js';
+export { liveStop } from './live-stop.js';
+export { observeLiveHeight } from './observe-live-height.js';
+export { postLiveMessage } from './post-live-message.js';
+export { reportLiveStatus } from './report-live-status.js';

package/dist/observe-live-height.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reports the height of the page's content now and whenever it changes, so
+ * the viewer can fit its frame. `scrollHeight` would never drop below the
+ * height of the frame itself. Runs once per page.
+ */
+export declare function observeLiveHeight(): void;

package/dist/observe-live-height.js

@@ -0,0 +1,83 @@
+import { liveState } from './live-state.js';
+import { postLiveMessage } from './post-live-message.js';
+/** Room under the lowest box, as the viewer leaves under a recorded frame. */
+const BOTTOM_MARGIN = 20;
+const SKIPPED_TAGS = new Set(['SCRIPT', 'NOSCRIPT', 'STYLE', 'LINK', 'META', 'TITLE', 'TEMPLATE']);
+function hasOwnText(element) {
+    return Array.from(element.childNodes).some((node) => node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '');
+}
+/**
+ * Whether an element draws something itself. Layout wrappers can stretch to
+ * the height of the frame, and would keep the height from ever shrinking.
+ */
+function paints(element) {
+    if (element.children.length === 0 || hasOwnText(element)) {
+        return true;
+    }
+    const style = getComputedStyle(element);
+    const hasBackground = style.backgroundColor !== 'rgba(0, 0, 0, 0)' && style.backgroundColor !== 'transparent';
+    const hasBorder = parseFloat(style.borderTopWidth) > 0 || parseFloat(style.borderBottomWidth) > 0;
+    return hasBackground || hasBorder || style.boxShadow !== 'none';
+}
+function* elementsIn(root) {
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+        yield node;
+    }
+}
+/** The bottom of the lowest painted element in page pixels, plus the margin, or 0 for none. */
+function contentHeight() {
+    let bottom = 0;
+    for (const element of elementsIn(document.body)) {
+        if (SKIPPED_TAGS.has(element.tagName) || !paints(element)) {
+            continue;
+        }
+        const rect = element.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0) {
+            bottom = Math.max(bottom, rect.bottom + window.scrollY);
+        }
+    }
+    return bottom > 0 ? Math.ceil(bottom + BOTTOM_MARGIN) : 0;
+}
+function postHeight() {
+    const height = liveState().height;
+    const measured = contentHeight();
+    if (measured === height.reported) {
+        return;
+    }
+    height.reported = measured;
+    postLiveMessage({ type: 'size', height: measured });
+}
+function schedule() {
+    const height = liveState().height;
+    if (height.queued) {
+        return;
+    }
+    height.queued = true;
+    requestAnimationFrame(() => {
+        height.queued = false;
+        postHeight();
+    });
+}
+/**
+ * Reports the height of the page's content now and whenever it changes, so
+ * the viewer can fit its frame. `scrollHeight` would never drop below the
+ * height of the frame itself. Runs once per page.
+ */
+export function observeLiveHeight() {
+    const height = liveState().height;
+    if (height.observing) {
+        return;
+    }
+    height.observing = true;
+    new ResizeObserver(schedule).observe(document.body);
+    new MutationObserver(schedule).observe(document.body, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        characterData: true,
+    });
+    window.addEventListener('resize', schedule);
+    void document.fonts.ready.then(schedule);
+    postHeight();
+}

package/dist/post-live-message.d.ts

@@ -0,0 +1,7 @@
+import { type LiveReport } from './types.js';
+/**
+ * Posts a report to the viewer that frames the live page. It goes only to the
+ * origin the page URL names, so another site that frames the page learns
+ * nothing.
+ */
+export declare function postLiveMessage(report: LiveReport): void;

package/dist/post-live-message.js

@@ -0,0 +1,32 @@
+import { LIVE_MESSAGE_SOURCE } from './types.js';
+/** The viewer's origin from the page URL, when it is exactly the origin of an http(s) URL. */
+function viewerOrigin() {
+    const origin = new URLSearchParams(window.location.search).get('origin');
+    if (origin === null) {
+        return null;
+    }
+    try {
+        const url = new URL(origin);
+        const web = url.protocol === 'http:' || url.protocol === 'https:';
+        return web && url.origin === origin ? origin : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Posts a report to the viewer that frames the live page. It goes only to the
+ * origin the page URL names, so another site that frames the page learns
+ * nothing.
+ */
+export function postLiveMessage(report) {
+    if (window.parent === window) {
+        return;
+    }
+    const origin = viewerOrigin();
+    if (origin === null) {
+        return;
+    }
+    const message = { source: LIVE_MESSAGE_SOURCE, ...report };
+    window.parent.postMessage(message, origin);
+}

package/dist/report-live-status.d.ts

@@ -0,0 +1,6 @@
+import type { LiveStatus } from './types.js';
+/**
+ * Reports how the live page ended up, on `<html data-describe-me-live>` and to
+ * the viewer. The first status of a page is final, so later calls do nothing.
+ */
+export declare function reportLiveStatus(status: LiveStatus, detail?: string): void;

package/dist/report-live-status.js

@@ -0,0 +1,28 @@
+import { liveState } from './live-state.js';
+import { observeLiveHeight } from './observe-live-height.js';
+import { postLiveMessage } from './post-live-message.js';
+/** Writes the status on the page itself, so the page is never blank and the viewer can fit it. */
+function showStatus(status, detail) {
+    const note = document.createElement('p');
+    note.textContent = detail === undefined ? status : `${status}: ${detail}`;
+    note.style.whiteSpace = 'pre-wrap';
+    document.body.append(note);
+}
+/**
+ * Reports how the live page ended up, on `<html data-describe-me-live>` and to
+ * the viewer. The first status of a page is final, so later calls do nothing.
+ */
+export function reportLiveStatus(status, detail) {
+    const state = liveState();
+    if (state.status !== null) {
+        return;
+    }
+    state.status = status;
+    document.documentElement.dataset.describeMeLive = status;
+    const report = detail === undefined ? { type: 'status', status } : { type: 'status', status, detail };
+    postLiveMessage(report);
+    if (status !== 'mounted') {
+        showStatus(status, detail);
+    }
+    observeLiveHeight();
+}

package/dist/types.d.ts

@@ -178,6 +178,11 @@ export interface Manifest {
     generator?: ManifestGenerator;
     generatedAt: string;
     root: string;
+    /**
+     * The Vitest config file of the run, relative to `root`, with `/` separators.
+     * Absent when the run had no config file, and in manifests written before 0.6.
+     */
+    configFile?: string;
     modules: ManifestModule[];
     /** Keyed by component name, as reported by the framework adapter. */
     components: Record<string, ComponentDoc>;
@@ -249,3 +254,32 @@ export interface ManifestDiagnostics {
     /** Problems in the project's setup that can make tests fail. */
     setupWarnings: string[];
 }
+/** How the live preview page ended up. */
+export type LiveStatus = 'mounted' | 'no-render' | 'not-found' | 'import-failed' | 'setup-failed' | 'failed';
+/** The `source` of every message the live preview page posts. */
+export declare const LIVE_MESSAGE_SOURCE: "describe-me-live";
+/** The version of the contract between the viewer, the plugin's live mode and the live page. */
+export declare const LIVE_PROTOCOL: 1;
+/** What the live page reports, without the `source` field. */
+export type LiveReport = {
+    type: 'status';
+    status: LiveStatus;
+    detail?: string;
+} | {
+    type: 'size';
+    height: number;
+} | {
+    type: 'action';
+    name: string;
+    args: string[];
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'notice';
+    message: string;
+};
+/** A message the live page posts to the viewer around it. */
+export type LiveMessage = LiveReport & {
+    source: typeof LIVE_MESSAGE_SOURCE;
+};

package/dist/types.js

@@ -23,3 +23,7 @@ export const STYLE_URL_PREFIX = 'describe-me-style:';
 export const META_KEY = 'describeMe';
 /** The name adapters fall back to when a component has no usable name. */
 export const ANONYMOUS_COMPONENT = 'Anonymous';
+/** The `source` of every message the live preview page posts. */
+export const LIVE_MESSAGE_SOURCE = 'describe-me-live';
+/** The version of the contract between the viewer, the plugin's live mode and the live page. */
+export const LIVE_PROTOCOL = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/core",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "Living component documentation from your Vitest tests: the recorder and manifest types of describe-me",
   "keywords": [
     "vitest",
@@ -45,6 +45,10 @@
     "./css-references": {
       "types": "./dist/css-references.d.ts",
       "default": "./dist/css-references.js"
+    },
+    "./live": {
+      "types": "./dist/live.d.ts",
+      "default": "./dist/live.js"
     }
   },
   "files": [