@bquery/bquery 1.6.0 → 1.7.0

package/src/testing/types.ts

@@ -0,0 +1,170 @@
+/**
+ * Types for the bQuery testing utilities module.
+ * @module bquery/testing
+ */
+
+import type { Signal } from '../reactive/index';
+// ---------------------------------------------------------------------------
+// routing / mockRouter route types
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal route shape accepted by the testing mock router.
+ */
+export interface MockRouteDefinition {
+  path: string;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// renderComponent
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for mounting a bQuery component in tests.
+ */
+export interface RenderComponentOptions {
+  /**
+   * Attributes (props) to set on the custom element.
+   * Keys are attribute names; values are stringified automatically.
+   *
+   * @example
+   * ```ts
+   * renderComponent('my-counter', { props: { start: 5 } });
+   * ```
+   */
+  props?: Record<string, unknown>;
+
+  /**
+   * Named or default slot content to inject inside the host element
+   * **before** it is connected to the DOM.
+   *
+   * - A plain string sets the default (unnamed) slot.
+   * - An object maps slot names to HTML strings.
+   *
+   * @example
+   * ```ts
+   * renderComponent('my-card', {
+   *   slots: { default: '<p>Body</p>', header: '<h2>Title</h2>' },
+   * });
+   * ```
+   */
+  slots?: string | Record<string, string>;
+
+  /**
+   * Parent element to attach to. Defaults to `document.body`.
+   */
+  container?: HTMLElement;
+}
+
+/**
+ * Return value of {@link renderComponent}.
+ */
+export interface RenderResult {
+  /** The mounted custom element instance. */
+  el: HTMLElement;
+  /** Remove the element and run cleanup. */
+  unmount: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// mockSignal
+// ---------------------------------------------------------------------------
+
+/**
+ * A controllable signal for use in tests.
+ *
+ * Extends the regular Signal with explicit `set()` and `reset()` helpers
+ * that make test intent clearer.
+ */
+export interface MockSignal<T> extends Signal<T> {
+  /**
+   * Explicitly set the signal value (alias for `.value = v`).
+   */
+  set(value: T): void;
+
+  /**
+   * Reset the signal back to its initial value.
+   */
+  reset(): void;
+
+  /**
+   * The initial value this mock was created with.
+   */
+  readonly initialValue: T;
+}
+
+// ---------------------------------------------------------------------------
+// mockRouter
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for creating a mock router.
+ */
+export interface MockRouterOptions {
+  /** Route definitions. Defaults to a single catch-all route. */
+  routes?: MockRouteDefinition[];
+  /** Initial path. Defaults to '/'. */
+  initialPath?: string;
+  /** Base path. Defaults to ''. */
+  base?: string;
+}
+
+/**
+ * A lightweight mock router for tests that doesn't touch the History API.
+ */
+export interface MockRouter {
+  /** Navigate to a path (synchronous, no guards). */
+  push(path: string): void;
+  /** Replace the current path. */
+  replace(path: string): void;
+  /** The current route (reactive signal). */
+  readonly currentRoute: Signal<TestRoute>;
+  /** Registered routes. */
+  readonly routes: MockRouteDefinition[];
+  /** Destroy and clean up. */
+  destroy(): void;
+}
+
+/**
+ * Minimal route shape for the mock router.
+ */
+export interface TestRoute {
+  path: string;
+  params: Record<string, string>;
+  query: Record<string, string | string[]>;
+  matched: MockRouteDefinition | null;
+  hash: string;
+}
+
+// ---------------------------------------------------------------------------
+// fireEvent
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for dispatching a synthetic event.
+ */
+export interface FireEventOptions {
+  /** Whether the event bubbles. Defaults to `true`. */
+  bubbles?: boolean;
+  /** Whether the event is cancelable. Defaults to `true`. */
+  cancelable?: boolean;
+  /** Whether the event crosses shadow DOM boundaries. Defaults to `true`. */
+  composed?: boolean;
+  /** Extra detail data for CustomEvent. */
+  detail?: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// waitFor
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for the async `waitFor` helper.
+ */
+export interface WaitForOptions {
+  /** Maximum time (ms) to wait before timing out. Defaults to 1000. */
+  timeout?: number;
+  /** Polling interval (ms). Defaults to 10. */
+  interval?: number;
+}

package/src/view/custom-directives.ts

@@ -0,0 +1,30 @@
+import type { DirectiveHandler } from './types';
+
+/**
+ * Function signature used to resolve custom directives without coupling the
+ * view pipeline directly to the plugin module.
+ * @internal
+ */
+export type CustomDirectiveResolver = (name: string) => DirectiveHandler | undefined;
+
+let customDirectiveResolver: CustomDirectiveResolver | null = null;
+
+/**
+ * Registers the resolver used by the view pipeline for custom directives.
+ *
+ * Pass `null` to unregister the current resolver and reset to the default behavior.
+ * @internal
+ */
+export const registerCustomDirectiveResolver = (
+  resolver: CustomDirectiveResolver | null
+): void => {
+  customDirectiveResolver = resolver;
+};
+
+/**
+ * Returns a custom directive handler when one is registered.
+ * @internal
+ */
+export const getCustomDirective = (name: string): DirectiveHandler | undefined => {
+  return customDirectiveResolver ? customDirectiveResolver(name) : undefined;
+};