@civitai/blocks-react 0.59.0 → 0.60.0

package/README.md

@@ -1445,6 +1445,7 @@ what went stale in [#334](https://github.com/civitai/civitai-app-starters/issues
 | `createMockHost` | A framework-agnostic fake of the embedding host — answers every `*_RESULT` message, with knobs for generation cost/latency/failure, Buzz balance, app + shared storage, consent, maturity. Returns a `MockHost`; call `.install()` and keep the returned teardown. **No network, no Buzz.** |
 | `readMockHostUrlOptions` | Reads the harness URL toggles (`?viewer` `?consent` `?fail` `?theme` `?pick` `?balance` `?latency` `?seed` …) into a `Partial<MockHostOptions>`. `Harness` applies it for you; call it directly only in a hand-rolled harness. |
 | `Harness` | The React wrapper: installs a `createMockHost` on mount, tears it down on unmount, and renders an optional on-screen outbound-message log. Takes every `MockHostOptions` field plus `applyUrlToggles` and `showLog`. |
+| `installPopoverShim` | Stands in for the HTML popover API, which neither `jsdom` nor `happy-dom` implements at any version. Needed only if your own code calls `showPopover`/`hidePopover`/`togglePopover` or queries `:popover-open` — `@civitai/components`' own elements do not. Returns a `PopoverShimHandle`; inert (`installed: false`) in a real browser. **Read [Testing overlay elements](#testing-overlay-elements) first: it does not make trigger clicks work.** |
 
 <!-- TESTING-SURFACE:VALUES:END -->
 
@@ -1472,6 +1473,8 @@ MockHostScenarioPatch
 MockSharedScenario
 MockSharedSeed
 MockStorageScenario
+PopoverShimHandle
+PopoverShimOptions
 ```
 
 <!-- TESTING-SURFACE:TYPES:END -->
@@ -1501,6 +1504,57 @@ host.setScenario({ failMode: 'none' });   // live-tune mid-test
 uninstall();
 ```
 
+### Testing overlay elements
+
+`<civitai-menu>`, and anything else that opens a panel, live in an environment
+that is **incomplete** rather than merely different. Two facts, both measured on
+happy-dom 20.9.0; neither is a bug in the components.
+
+**1. There is no popover API.** `showPopover`, `hidePopover` and `togglePopover`
+are `undefined` on happy-dom 20.x and on jsdom 25 and 30 alike. `:popover-open`
+is worse than absent: it is **unreliable**, and the unreliability is not a
+property of your runner's version. It resolves through `nwsapi` under jsdom, so
+the same jsdom 25.0.1 both throws `DOMException: unknown pseudo-class selector`
+and returns `false` depending on which `nwsapi` your lockfile pulled in
+(measured: `false` on nwsapi 2.2.28). `@civitai/components`' own elements no
+longer read it, which is what takes that variable off the table for them. Install
+the shim if **your** code touches the API:
+
+```ts
+import { installPopoverShim } from '@civitai/blocks-react/testing';
+
+const shim = installPopoverShim();
+// …
+shim.uninstall();
+```
+
+It is inert in a real browser (`installed: false`), so it is safe to call from a
+setup file shared between a happy-dom project and a browser-mode project.
+
+**2. 🔴 UNDER happy-dom A TRIGGER CLICK DOES NOTHING, and the shim does not change
+that.** A click on light-DOM content assigned to a `<slot>` reaches the **host** (a
+listener there fires once) but **not** a listener on the `<slot>` element — and
+that is the node Lit binds `@click` to. So the click dispatches, bubbles, and
+then the handler is never called: no throw, no state change, a test that quietly
+does nothing. jsdom (25 and 30) *does* deliver it, so this one is happy-dom's
+alone — which is exactly why the shim **measures** it rather than asserting it:
+`installPopoverShim` probes on install, reports the answer as
+`handle.slottedClicksReachSlots`, and `console.warn`s when it is `false`.
+
+**Drive overlay elements through their methods:**
+
+```ts
+menu.show();                 // ✅ works in every DOM
+await menu.updateComplete;
+
+triggerButton.click();       // ❌ silently does nothing under happy-dom
+```
+
+Also absent, because they need layout and a hit-testing event path: the top
+layer, anchor positioning, and **light dismiss** (a click outside a shown panel
+does not close it). If what you are testing is one of those, use a real browser —
+this repo's own `browser` vitest project is the worked example.
+
 ### In a dev harness
 
 ```tsx

package/dist/internal/popoverShim.d.ts

@@ -0,0 +1,94 @@
+/**
+ * A minimal stand-in for the HTML popover API, for NON-BROWSER DOMs.
+ *
+ * WHY IT EXISTS (#485). `jsdom` and `happy-dom` do not implement the popover
+ * API at ANY version we could find: `showPopover`, `hidePopover` and
+ * `togglePopover` are `undefined` on happy-dom 20.x and on jsdom 25 and 30 alike.
+ * `:popover-open` is worse than absent — it is unreliable in a way that is NOT a
+ * property of the runner's version: under jsdom it resolves through `nwsapi`, so
+ * the same jsdom 25.0.1 both throws `DOMException: unknown pseudo-class selector`
+ * and returns `false` depending on which `nwsapi` a lockfile pulled in (measured
+ * `false` on nwsapi 2.2.28). Anything that calls into that API therefore explodes,
+ * or lies, in the one environment an App Block's own test suite runs in.
+ *
+ * 🔴 WHAT THIS DOES **NOT** DO, and you must read this before using it.
+ *
+ * It does not make a shadow-DOM component fully driveable under happy-dom.
+ * Measured on happy-dom 20.9.0: a click on a light-DOM child assigned to a
+ * `<slot>` bubbles to the HOST (a listener there fires 1x) but a listener on the
+ * `<slot>` ELEMENT ITSELF fires **0x**. Lit binds `@click` to the `<slot>`, so
+ * `<civitai-menu>`'s trigger click is SILENT there: no throw, no open, nothing.
+ * That is a property of happy-dom's event path through the flattened tree and
+ * this shim cannot fix it — installing it changes the count from 0 to 0. (jsdom
+ * 25 and 30 both DO deliver it, which is why this is probed rather than asserted.)
+ *
+ * So under a shimmed DOM you must drive overlay elements through their METHODS
+ * (`menu.show()` / `menu.hide()`), never by clicking the trigger. {@link
+ * installPopoverShim} PROBES for this on install and returns the result as
+ * {@link PopoverShimHandle.slottedClicksReachSlots}, warning loudly when it is
+ * false, because a shim that quietly made `show()` work while `click()` no-ops
+ * would read as "this element is testable now" while delivering half of it.
+ *
+ * Other deliberate deviations from the platform, all of them narrow:
+ *   - `toggle` is dispatched in a MICROTASK, where the platform queues a task.
+ *     A microtask flushes before the next `await`, which is what makes it
+ *     observable after `await el.updateComplete` in a test; a real task would
+ *     need a `setTimeout` round-trip. `beforetoggle` is not dispatched at all.
+ *   - There is no top layer, no anchor positioning, and no LIGHT DISMISS: a
+ *     click outside a shown popover does not close it. Those need layout and a
+ *     hit-testing event path, neither of which a non-browser DOM has. Light
+ *     dismiss is one of the two reasons `<civitai-menu>` uses popover at all, so
+ *     if that is what you are testing, use a real browser.
+ *   - `popover="manual"` vs `"auto"` is not distinguished (there being no light
+ *     dismiss to distinguish them by).
+ */
+/** What {@link installPopoverShim} hands back. */
+export interface PopoverShimHandle {
+    /**
+     * `true` when this shim was needed — i.e. the DOM did not already have a
+     * popover API. `false` means nothing was patched, which is the correct result
+     * in a real browser, and makes the call safe to make unconditionally in a
+     * setup file shared between a happy-dom project and a browser-mode project.
+     */
+    installed: boolean;
+    /**
+     * 🔴 Whether a click on a slotted light-DOM element reaches a listener on the
+     * `<slot>` it is assigned to — measured, on install, with a throwaway element.
+     *
+     * `true` in a real browser. `false` on happy-dom 20.9.0, and while it is
+     * `false` an element that binds its handlers to a `<slot>` (every Lit
+     * component that does, `<civitai-menu>`'s trigger included) cannot be driven
+     * by clicking. Drive it through its methods instead.
+     */
+    slottedClicksReachSlots: boolean;
+    /** Restores whatever was on the prototypes before. Idempotent. */
+    uninstall(): void;
+}
+/** Options for {@link installPopoverShim}. */
+export interface PopoverShimOptions {
+    /**
+     * Suppress the `console.warn` fired when slotted clicks do not reach slot
+     * listeners. The measurement is still returned on the handle. Default `false`
+     * — the warning is the point, so silence it only once you have read it.
+     */
+    quiet?: boolean;
+}
+/**
+ * Install the popover shim on the current global DOM. Call it once, in a vitest
+ * `setupFiles` entry or at the top of a test file, BEFORE the elements render.
+ *
+ * Safe and inert in a real browser: it detects a working popover API and patches
+ * nothing (`installed: false`).
+ *
+ * @example
+ * ```ts
+ * import { installPopoverShim } from '@civitai/blocks-react/testing';
+ *
+ * const shim = installPopoverShim();
+ * // Drive overlay elements through their methods — NOT by clicking the trigger.
+ * menu.show();
+ * await menu.updateComplete;
+ * ```
+ */
+export declare function installPopoverShim(options?: PopoverShimOptions): PopoverShimHandle;
+//# sourceMappingURL=popoverShim.d.ts.map

package/dist/internal/popoverShim.js

@@ -0,0 +1,181 @@
+/**
+ * A minimal stand-in for the HTML popover API, for NON-BROWSER DOMs.
+ *
+ * WHY IT EXISTS (#485). `jsdom` and `happy-dom` do not implement the popover
+ * API at ANY version we could find: `showPopover`, `hidePopover` and
+ * `togglePopover` are `undefined` on happy-dom 20.x and on jsdom 25 and 30 alike.
+ * `:popover-open` is worse than absent — it is unreliable in a way that is NOT a
+ * property of the runner's version: under jsdom it resolves through `nwsapi`, so
+ * the same jsdom 25.0.1 both throws `DOMException: unknown pseudo-class selector`
+ * and returns `false` depending on which `nwsapi` a lockfile pulled in (measured
+ * `false` on nwsapi 2.2.28). Anything that calls into that API therefore explodes,
+ * or lies, in the one environment an App Block's own test suite runs in.
+ *
+ * 🔴 WHAT THIS DOES **NOT** DO, and you must read this before using it.
+ *
+ * It does not make a shadow-DOM component fully driveable under happy-dom.
+ * Measured on happy-dom 20.9.0: a click on a light-DOM child assigned to a
+ * `<slot>` bubbles to the HOST (a listener there fires 1x) but a listener on the
+ * `<slot>` ELEMENT ITSELF fires **0x**. Lit binds `@click` to the `<slot>`, so
+ * `<civitai-menu>`'s trigger click is SILENT there: no throw, no open, nothing.
+ * That is a property of happy-dom's event path through the flattened tree and
+ * this shim cannot fix it — installing it changes the count from 0 to 0. (jsdom
+ * 25 and 30 both DO deliver it, which is why this is probed rather than asserted.)
+ *
+ * So under a shimmed DOM you must drive overlay elements through their METHODS
+ * (`menu.show()` / `menu.hide()`), never by clicking the trigger. {@link
+ * installPopoverShim} PROBES for this on install and returns the result as
+ * {@link PopoverShimHandle.slottedClicksReachSlots}, warning loudly when it is
+ * false, because a shim that quietly made `show()` work while `click()` no-ops
+ * would read as "this element is testable now" while delivering half of it.
+ *
+ * Other deliberate deviations from the platform, all of them narrow:
+ *   - `toggle` is dispatched in a MICROTASK, where the platform queues a task.
+ *     A microtask flushes before the next `await`, which is what makes it
+ *     observable after `await el.updateComplete` in a test; a real task would
+ *     need a `setTimeout` round-trip. `beforetoggle` is not dispatched at all.
+ *   - There is no top layer, no anchor positioning, and no LIGHT DISMISS: a
+ *     click outside a shown popover does not close it. Those need layout and a
+ *     hit-testing event path, neither of which a non-browser DOM has. Light
+ *     dismiss is one of the two reasons `<civitai-menu>` uses popover at all, so
+ *     if that is what you are testing, use a real browser.
+ *   - `popover="manual"` vs `"auto"` is not distinguished (there being no light
+ *     dismiss to distinguish them by).
+ */
+/** The marker attribute a shown popover carries. Internal to the shim. */
+const SHOWN_ATTR = 'data-civitai-popover-open';
+/**
+ * Does a click on a slotted child reach a listener bound to the `<slot>`?
+ *
+ * Built as its own throwaway tree rather than asked of the component under test,
+ * so the answer is about the DOM implementation and not about one element's
+ * wiring. Returns `false` if anything in the probe is unsupported — an
+ * environment that cannot even run the probe certainly cannot deliver the event.
+ */
+function probeSlottedClickReachesSlot(doc) {
+    let host;
+    try {
+        host = doc.createElement('div');
+        const root = host.attachShadow({ mode: 'open' });
+        const slot = doc.createElement('slot');
+        root.append(slot);
+        const child = doc.createElement('button');
+        host.append(child);
+        doc.body.append(host);
+        let slotSaw = 0;
+        slot.addEventListener('click', () => {
+            slotSaw += 1;
+        });
+        child.click();
+        return slotSaw > 0;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        host?.remove();
+    }
+}
+/**
+ * Install the popover shim on the current global DOM. Call it once, in a vitest
+ * `setupFiles` entry or at the top of a test file, BEFORE the elements render.
+ *
+ * Safe and inert in a real browser: it detects a working popover API and patches
+ * nothing (`installed: false`).
+ *
+ * @example
+ * ```ts
+ * import { installPopoverShim } from '@civitai/blocks-react/testing';
+ *
+ * const shim = installPopoverShim();
+ * // Drive overlay elements through their methods — NOT by clicking the trigger.
+ * menu.show();
+ * await menu.updateComplete;
+ * ```
+ */
+export function installPopoverShim(options = {}) {
+    const doc = globalThis.document;
+    const win = globalThis;
+    if (!doc || !win.Element || !win.HTMLElement) {
+        throw new Error('installPopoverShim() needs a DOM. Run it under a vitest `environment` of ' +
+            '`happy-dom` or `jsdom`, not `node`.');
+    }
+    const slottedClicksReachSlots = probeSlottedClickReachesSlot(doc);
+    if (!slottedClicksReachSlots && !options.quiet) {
+        // Loud on purpose. The popover half being fixed is what makes this the
+        // remaining reason a test "does nothing", and a silent no-op click is a far
+        // worse diagnostic than a throw.
+        console.warn('[civitai] popover shim installed, but THIS DOM DOES NOT DELIVER CLICKS ON SLOTTED ' +
+            'CONTENT TO LISTENERS ON THE <slot> (measured on install; happy-dom 20.x behaves this ' +
+            'way). Clicking a component\'s trigger will do nothing at all — no throw, no state ' +
+            'change. Drive overlay elements through their methods instead: `menu.show()` / ' +
+            '`menu.hide()`. See @civitai/blocks-react README § "Testing overlay elements".');
+    }
+    const proto = win.HTMLElement.prototype;
+    const already = typeof proto.showPopover === 'function';
+    if (already) {
+        return { installed: false, slottedClicksReachSlots, uninstall: () => { } };
+    }
+    const shown = new WeakSet();
+    const fireToggle = (el, from, to) => {
+        queueMicrotask(() => {
+            // `ToggleEvent` is undefined in both jsdom and happy-dom, so the two state
+            // fields are attached to a plain Event. Consumers read `event.newState`,
+            // which is what `<civitai-menu>`'s own handler does.
+            const event = new Event('toggle', { bubbles: false, cancelable: false });
+            event.oldState = from;
+            event.newState = to;
+            el.dispatchEvent(event);
+        });
+    };
+    function assertPopover(el) {
+        if (!el.hasAttribute('popover')) {
+            throw new Error('InvalidStateError: showPopover/hidePopover called on an element without a `popover` attribute');
+        }
+    }
+    proto.showPopover = function showPopover() {
+        assertPopover(this);
+        if (shown.has(this))
+            throw new Error('InvalidStateError: popover is already showing');
+        shown.add(this);
+        this.setAttribute(SHOWN_ATTR, '');
+        fireToggle(this, 'closed', 'open');
+    };
+    proto.hidePopover = function hidePopover() {
+        assertPopover(this);
+        if (!shown.has(this))
+            throw new Error('InvalidStateError: popover is not showing');
+        shown.delete(this);
+        this.removeAttribute(SHOWN_ATTR);
+        fireToggle(this, 'open', 'closed');
+    };
+    proto.togglePopover = function togglePopover(force) {
+        const want = force ?? !shown.has(this);
+        if (want && !shown.has(this))
+            this.showPopover();
+        else if (!want && shown.has(this))
+            this.hidePopover();
+        return shown.has(this);
+    };
+    // `:popover-open` is a SELECTOR, so it cannot be shimmed by adding a method —
+    // it has to be rewritten before the engine sees it. `matches` is the entry
+    // point the pseudo-class is reached through in practice; the marker attribute
+    // the two methods above maintain is what it rewrites to, which makes
+    // `:not(:popover-open)` work for free.
+    const nativeMatches = win.Element.prototype.matches;
+    const POPOVER_OPEN = /:popover-open\b/g;
+    win.Element.prototype.matches = function matches(selector) {
+        return nativeMatches.call(this, selector.replace(POPOVER_OPEN, `[${SHOWN_ATTR}]`));
+    };
+    return {
+        installed: true,
+        slottedClicksReachSlots,
+        uninstall() {
+            delete proto.showPopover;
+            delete proto.hidePopover;
+            delete proto.togglePopover;
+            win.Element.prototype.matches = nativeMatches;
+        },
+    };
+}
+//# sourceMappingURL=popoverShim.js.map

package/dist/testing.d.ts

@@ -20,6 +20,7 @@ import { type ReactNode } from 'react';
 import { __resetTransport } from './transport/singleton.js';
 import { type MockHostOptions } from './internal/mockHost.js';
 export { __resetTransport as resetTransport };
+export { installPopoverShim, type PopoverShimHandle, type PopoverShimOptions, } from './internal/popoverShim.js';
 export { createMockHost, readMockHostUrlOptions, type MockHost, type MockHostOptions, type MockHostFailMode, type MockHostScenarioPatch, type MockGenerationScenario, type MockBuzzScenario, type MockBuzzBalance, type MockBuzzHandle, type MockStorageScenario, type MockSharedScenario, type MockSharedSeed, type MockCannedImageScan, type CostSpec, type ImageSpec, type CannedPick, } from './internal/mockHost.js';
 /**
  * Props for the dev {@link Harness}.

package/dist/testing.js

@@ -21,6 +21,7 @@ import { useEffect, useRef, useState } from 'react';
 import { __resetTransport } from './transport/singleton.js';
 import { createMockHost, readMockHostUrlOptions, } from './internal/mockHost.js';
 export { __resetTransport as resetTransport };
+export { installPopoverShim, } from './internal/popoverShim.js';
 export { createMockHost, readMockHostUrlOptions, } from './internal/mockHost.js';
 /**
  * What the harness chrome's `consent=` readout says, from the TWO INDEPENDENT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "React hooks and iframe transport for Civitai Apps. Pairs with @civitai/app-sdk/blocks.",
   "license": "MIT",
   "type": "module",
@@ -37,8 +37,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@civitai/theme": "^0.4.0",
-    "@civitai/components": "^0.8.1"
+    "@civitai/components": "^0.9.0",
+    "@civitai/theme": "^0.4.0"
   },
   "comment-peerDependencies": "This floor is DERIVED, not chosen — the lowest published app-sdk that exports every symbol this package imports. Do not edit it without reading ./PEER_FLOOR.md (in-repo, unpublished) and tests/guards/blocks-react-peer-floor.test.mjs.",
   "peerDependencies": {
@@ -58,7 +58,7 @@
     "typescript": "^5.9.2",
     "vite": "^8.0.14",
     "vitest": "^4.1.11",
-    "@civitai/app-sdk": "^0.52.0"
+    "@civitai/app-sdk": "^0.53.0"
   },
   "publishConfig": {
     "access": "public"