streetui 1.7.0 → 1.9.0

package/dist/testing.d.cts

@@ -1,6 +1,6 @@
-import { S as StreetApp } from './compile-Cte0nf06.cjs';
-export { V as VERSION } from './compile-Cte0nf06.cjs';
-import { R as RenderHandle, H as HydrationDiagnostic } from './hydration-diagnostics-zK-fihvd.cjs';
+import { S as StreetApp, a as ComponentDefinition, b as ContainerBuilder } from './compile-DqsMQVJk.cjs';
+export { V as VERSION } from './compile-DqsMQVJk.cjs';
+import { R as RenderHandle, H as HydrationDiagnostic } from './hydration-diagnostics-4pwt6v7b.cjs';
 export * from 'streetui/diagnostics';
 
 /**
@@ -71,6 +71,44 @@ interface WaitForOptions {
  * deadline. Use for assertions that become true only after async work settles.
  */
 declare function waitFor<T>(check: () => T, options?: WaitForOptions): Promise<T>;
+/** A minimal writable-boolean seam (an overlay `open` signal, typically). */
+interface BooleanControl {
+    set(value: boolean): void;
+}
+/** Focus `el` (no-op if it exposes no `focus`). Intentful wrapper for tests. */
+declare function focus(el: Element): void;
+/** Blur `el` (no-op if it exposes no `blur`). */
+declare function blur(el: Element): void;
+/**
+ * Dispatch a bubbling, cancelable `keydown` for `key` on `el` (defaulting to the
+ * currently-focused element). Extra `init` fields (e.g. `{ shiftKey: true }`)
+ * are forwarded. Use for keyboard-interaction assertions (Escape, Tab, arrows).
+ */
+declare function pressKey(key: string, el?: Element | null, init?: KeyboardEventInit): void;
+/**
+ * Simulate a pointer interaction OUTSIDE `container` — a `mousedown` + `click`
+ * on `document.body` (or `target` if given). Drives "click-away to dismiss"
+ * behaviour without the test constructing events by hand. If `target` is inside
+ * `container` this throws, so a mistake is loud rather than a silent no-op.
+ */
+declare function clickOutside(container: Element, target?: Element): void;
+/**
+ * Open an overlay by flipping its `open` control to `true`, then flush so the
+ * panel mounts and its enter/focus wiring runs. Overlay visibility is app-owned
+ * state (§18) — a plain signal — so this is a thin, intentful wrapper over
+ * `set(true)` + {@link flushUpdates}.
+ */
+declare function openOverlay(open: BooleanControl): Promise<void>;
+/** Close an overlay by flipping its `open` control to `false`, then flush. */
+declare function closeOverlay(open: BooleanControl): Promise<void>;
+/**
+ * Settle a CSS transition on `el` deterministically: dispatch the
+ * `transitionend` the controller listens for (happy-dom fires none of its own),
+ * then flush pending work so any deferred leave-teardown (DOM removal, dispose,
+ * detach) completes. Await this after toggling a transitioned element to assert
+ * its post-animation state without depending on the fallback timeout.
+ */
+declare function waitForTransition(el: Element): Promise<void>;
 /** Find the first leaf element whose text content includes `text`. */
 declare function findByText(container: Element, text: string): Element;
 interface ByRoleOptions {
@@ -111,4 +149,63 @@ interface HydrateTestResult {
  */
 declare function renderServerThenHydrate(build: () => StreetApp, options?: HydrateTestOptions): HydrateTestResult;
 
-export { type ByRoleOptions, type HydrateTestOptions, type HydrateTestResult, type RenderResult, type WaitForOptions, findAllByRole, findByRole, findByText, flushUpdates, render, renderOnce, renderServerThenHydrate, waitFor };
+/**
+ * Component-focused testing helpers (§22).
+ *
+ * These extend `streetui/testing` for the component model. Following the spec's
+ * "add only the ones that are actually useful" directive, this module ships the
+ * helpers that remove real boilerplate and OMITS the ones that would be
+ * misleading in this architecture:
+ *
+ *   • renderComponent   — mount a single component in a throwaway host app.
+ *   • hydrateComponent  — SSR-then-hydrate that same host (the §11/§12 seam).
+ *   • findComponent / findAllComponents / getComponentName — locate component
+ *     instances by their inspectable `data-streetui-component` name.
+ *   • trigger           — dispatch a bubbling DOM event (click/input/keydown…).
+ *
+ * Deliberately NOT provided:
+ *   • getComponentProps — props are passed to `setup` and captured by closure;
+ *     they are not reified on the node (only the definition *name* is), so a
+ *     prop-reading helper would either lie or require a private-graph backdoor.
+ *     Assert on rendered output (or a signal you own) instead.
+ *   • awaitResource     — `waitFor(...)` and `flushUpdates()` already settle
+ *     async resource state; a resource-specific alias would be redundant.
+ */
+
+interface RenderComponentResult extends RenderResult {
+    /** The component's root `<div>` wrapper element. */
+    readonly component: HTMLElement;
+}
+/**
+ * Build a throwaway single-page host app whose only content is `def` rendered
+ * with `props` (and optional `children`), mount it, and return the usual
+ * `RenderResult` plus the component's root element. Use for unit-testing one
+ * component without hand-writing an app+page wrapper each time.
+ */
+declare function renderComponent<P>(def: ComponentDefinition<P>, props: P, children?: ContainerBuilder): RenderComponentResult;
+/**
+ * SSR-render then hydrate a single component in a host app — the production
+ * server→client seam (§11/§12). `build` must return `{ def, props, children? }`;
+ * it is invoked twice (server then client) with id-counter reset between, so a
+ * component that owns per-instance signals lines up positionally on hydration.
+ */
+declare function hydrateComponent<P>(build: () => {
+    def: ComponentDefinition<P>;
+    props: P;
+    children?: ContainerBuilder;
+}, options?: HydrateTestOptions): HydrateTestResult;
+/** All component instances under `container`, optionally filtered by name. */
+declare function findAllComponents(container: Element, name?: string): HTMLElement[];
+/** The single component instance under `container` (throws if none/ambiguous). */
+declare function findComponent(container: Element, name?: string): HTMLElement;
+/** Read a component element's definition name, or `null` if `el` is not one. */
+declare function getComponentName(el: Element): string | null;
+/**
+ * Dispatch a bubbling, cancelable DOM event of `type` on `el`. Thin wrapper over
+ * `dispatchEvent` so tests read intentfully (`trigger(btn, 'click')`) without
+ * constructing `Event`/`KeyboardEvent` objects by hand. Extra `init` fields
+ * (e.g. `{ key: 'Escape' }`) are forwarded to the appropriate event ctor.
+ */
+declare function trigger(el: Element, type: string, init?: Record<string, unknown>): void;
+
+export { type BooleanControl, type ByRoleOptions, type HydrateTestOptions, type HydrateTestResult, type RenderComponentResult, type RenderResult, type WaitForOptions, blur, clickOutside, closeOverlay, findAllByRole, findAllComponents, findByRole, findByText, findComponent, flushUpdates, focus, getComponentName, hydrateComponent, openOverlay, pressKey, render, renderComponent, renderOnce, renderServerThenHydrate, trigger, waitFor, waitForTransition };

package/dist/testing.d.ts

@@ -1,6 +1,6 @@
-import { S as StreetApp } from './compile-Cte0nf06.js';
-export { V as VERSION } from './compile-Cte0nf06.js';
-import { R as RenderHandle, H as HydrationDiagnostic } from './hydration-diagnostics-Ddgs3Puu.js';
+import { S as StreetApp, a as ComponentDefinition, b as ContainerBuilder } from './compile-DqsMQVJk.js';
+export { V as VERSION } from './compile-DqsMQVJk.js';
+import { R as RenderHandle, H as HydrationDiagnostic } from './hydration-diagnostics-B2FmY05M.js';
 export * from 'streetui/diagnostics';
 
 /**
@@ -71,6 +71,44 @@ interface WaitForOptions {
  * deadline. Use for assertions that become true only after async work settles.
  */
 declare function waitFor<T>(check: () => T, options?: WaitForOptions): Promise<T>;
+/** A minimal writable-boolean seam (an overlay `open` signal, typically). */
+interface BooleanControl {
+    set(value: boolean): void;
+}
+/** Focus `el` (no-op if it exposes no `focus`). Intentful wrapper for tests. */
+declare function focus(el: Element): void;
+/** Blur `el` (no-op if it exposes no `blur`). */
+declare function blur(el: Element): void;
+/**
+ * Dispatch a bubbling, cancelable `keydown` for `key` on `el` (defaulting to the
+ * currently-focused element). Extra `init` fields (e.g. `{ shiftKey: true }`)
+ * are forwarded. Use for keyboard-interaction assertions (Escape, Tab, arrows).
+ */
+declare function pressKey(key: string, el?: Element | null, init?: KeyboardEventInit): void;
+/**
+ * Simulate a pointer interaction OUTSIDE `container` — a `mousedown` + `click`
+ * on `document.body` (or `target` if given). Drives "click-away to dismiss"
+ * behaviour without the test constructing events by hand. If `target` is inside
+ * `container` this throws, so a mistake is loud rather than a silent no-op.
+ */
+declare function clickOutside(container: Element, target?: Element): void;
+/**
+ * Open an overlay by flipping its `open` control to `true`, then flush so the
+ * panel mounts and its enter/focus wiring runs. Overlay visibility is app-owned
+ * state (§18) — a plain signal — so this is a thin, intentful wrapper over
+ * `set(true)` + {@link flushUpdates}.
+ */
+declare function openOverlay(open: BooleanControl): Promise<void>;
+/** Close an overlay by flipping its `open` control to `false`, then flush. */
+declare function closeOverlay(open: BooleanControl): Promise<void>;
+/**
+ * Settle a CSS transition on `el` deterministically: dispatch the
+ * `transitionend` the controller listens for (happy-dom fires none of its own),
+ * then flush pending work so any deferred leave-teardown (DOM removal, dispose,
+ * detach) completes. Await this after toggling a transitioned element to assert
+ * its post-animation state without depending on the fallback timeout.
+ */
+declare function waitForTransition(el: Element): Promise<void>;
 /** Find the first leaf element whose text content includes `text`. */
 declare function findByText(container: Element, text: string): Element;
 interface ByRoleOptions {
@@ -111,4 +149,63 @@ interface HydrateTestResult {
  */
 declare function renderServerThenHydrate(build: () => StreetApp, options?: HydrateTestOptions): HydrateTestResult;
 
-export { type ByRoleOptions, type HydrateTestOptions, type HydrateTestResult, type RenderResult, type WaitForOptions, findAllByRole, findByRole, findByText, flushUpdates, render, renderOnce, renderServerThenHydrate, waitFor };
+/**
+ * Component-focused testing helpers (§22).
+ *
+ * These extend `streetui/testing` for the component model. Following the spec's
+ * "add only the ones that are actually useful" directive, this module ships the
+ * helpers that remove real boilerplate and OMITS the ones that would be
+ * misleading in this architecture:
+ *
+ *   • renderComponent   — mount a single component in a throwaway host app.
+ *   • hydrateComponent  — SSR-then-hydrate that same host (the §11/§12 seam).
+ *   • findComponent / findAllComponents / getComponentName — locate component
+ *     instances by their inspectable `data-streetui-component` name.
+ *   • trigger           — dispatch a bubbling DOM event (click/input/keydown…).
+ *
+ * Deliberately NOT provided:
+ *   • getComponentProps — props are passed to `setup` and captured by closure;
+ *     they are not reified on the node (only the definition *name* is), so a
+ *     prop-reading helper would either lie or require a private-graph backdoor.
+ *     Assert on rendered output (or a signal you own) instead.
+ *   • awaitResource     — `waitFor(...)` and `flushUpdates()` already settle
+ *     async resource state; a resource-specific alias would be redundant.
+ */
+
+interface RenderComponentResult extends RenderResult {
+    /** The component's root `<div>` wrapper element. */
+    readonly component: HTMLElement;
+}
+/**
+ * Build a throwaway single-page host app whose only content is `def` rendered
+ * with `props` (and optional `children`), mount it, and return the usual
+ * `RenderResult` plus the component's root element. Use for unit-testing one
+ * component without hand-writing an app+page wrapper each time.
+ */
+declare function renderComponent<P>(def: ComponentDefinition<P>, props: P, children?: ContainerBuilder): RenderComponentResult;
+/**
+ * SSR-render then hydrate a single component in a host app — the production
+ * server→client seam (§11/§12). `build` must return `{ def, props, children? }`;
+ * it is invoked twice (server then client) with id-counter reset between, so a
+ * component that owns per-instance signals lines up positionally on hydration.
+ */
+declare function hydrateComponent<P>(build: () => {
+    def: ComponentDefinition<P>;
+    props: P;
+    children?: ContainerBuilder;
+}, options?: HydrateTestOptions): HydrateTestResult;
+/** All component instances under `container`, optionally filtered by name. */
+declare function findAllComponents(container: Element, name?: string): HTMLElement[];
+/** The single component instance under `container` (throws if none/ambiguous). */
+declare function findComponent(container: Element, name?: string): HTMLElement;
+/** Read a component element's definition name, or `null` if `el` is not one. */
+declare function getComponentName(el: Element): string | null;
+/**
+ * Dispatch a bubbling, cancelable DOM event of `type` on `el`. Thin wrapper over
+ * `dispatchEvent` so tests read intentfully (`trigger(btn, 'click')`) without
+ * constructing `Event`/`KeyboardEvent` objects by hand. Extra `init` fields
+ * (e.g. `{ key: 'Escape' }`) are forwarded to the appropriate event ctor.
+ */
+declare function trigger(el: Element, type: string, init?: Record<string, unknown>): void;
+
+export { type BooleanControl, type ByRoleOptions, type HydrateTestOptions, type HydrateTestResult, type RenderComponentResult, type RenderResult, type WaitForOptions, blur, clickOutside, closeOverlay, findAllByRole, findAllComponents, findByRole, findByText, findComponent, flushUpdates, focus, getComponentName, hydrateComponent, openOverlay, pressKey, render, renderComponent, renderOnce, renderServerThenHydrate, trigger, waitFor, waitForTransition };