@bquery/bquery 1.6.0 → 1.8.1

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,28 @@
+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;
+};

package/src/view/evaluate.ts

@@ -1,3 +1,4 @@
+import { isPrototypePollutionKey } from '../core/utils/object';
 import { isComputed, isSignal, type Signal } from '../reactive/index';
 import type { BindingContext } from './types';
 
@@ -281,6 +282,7 @@ export const parseObjectExpression = (expression: string): Record<string, string
         .slice(0, colonIndex)
         .trim()
         .replace(/^['"]|['"]$/g, '');
+      if (isPrototypePollutionKey(key)) continue;
       const value = part.slice(colonIndex + 1).trim();
       result[key] = value;
     }

package/src/view/process.ts

@@ -1,4 +1,6 @@
 import type { CleanupFn } from '../reactive/index';
+import { detectDevEnvironment } from '../core/env';
+import { getCustomDirective } from './custom-directives';
 import type { BindingContext, DirectiveHandler } from './types';
 
 export type DirectiveHandlers = {
@@ -29,11 +31,11 @@ export const processElement = (
   const attributes = Array.from(el.attributes);
 
   for (const attr of attributes) {
-    const { name, value } = attr;
+    const { name: attributeName, value } = attr;
 
-    if (!name.startsWith(`${prefix}-`)) continue;
+    if (!attributeName.startsWith(`${prefix}-`)) continue;
 
-    const directive = name.slice(prefix.length + 1); // Remove prefix and dash
+    const directive = attributeName.slice(prefix.length + 1); // Remove prefix and dash
 
     // Handle bq-for specially (creates new scope)
     if (directive === 'for') {
@@ -64,6 +66,20 @@ export const processElement = (
     } else if (directive.startsWith('on:')) {
       const eventName = directive.slice(3);
       handlers.on(eventName)(el, value, context, cleanups);
+    } else {
+      // Check for custom directives registered via plugins
+      const customHandler = getCustomDirective(directive);
+      if (customHandler) {
+        customHandler(el, value, context, cleanups);
+      } else if (
+        detectDevEnvironment() &&
+        typeof console !== 'undefined' &&
+        typeof console.warn === 'function'
+      ) {
+        console.warn(
+          `[bQuery][view] Unknown directive "${attributeName}" (parsed as "${directive}") on <${el.tagName.toLowerCase()}>. This may be a typo or a missing custom directive registration.`
+        );
+      }
     }
   }
 };