@bquery/bquery 1.7.0 → 1.8.1

package/src/router/utils.ts

@@ -1,157 +1,157 @@
-/**
- * Router utilities.
- * @module bquery/router
- */
-
-import { computed, type ReadonlySignal } from '../reactive/index';
-import { getRouteConstraintRegex } from './constraints';
-import { isParamChar, isParamStart, readConstraint } from './path-pattern';
-import { getActiveRouter, routeSignal } from './state';
-import type { RouteDefinition } from './types';
-
-// ============================================================================
-// Utilities
-// ============================================================================
-
-/**
- * Flattens nested routes into a single array with full paths.
- * Does NOT include the router base - base is only for browser history.
- * @internal
- */
-export const flattenRoutes = (routes: RouteDefinition[], parentPath = ''): RouteDefinition[] => {
-  const result: RouteDefinition[] = [];
-
-  for (const route of routes) {
-    const fullPath = route.path === '*' ? '*' : `${parentPath}${route.path}`.replace(/\/+/g, '/');
-
-    result.push({
-      ...route,
-      path: fullPath,
-    });
-
-    if (route.children) {
-      result.push(...flattenRoutes(route.children, fullPath));
-    }
-  }
-
-  return result;
-};
-
-/**
- * Resolves a route by name and params.
- *
- * @param name - The route name
- * @param params - Route params to interpolate
- * @returns The resolved path
- * @throws {Error} If no router is initialized, the route name is unknown,
- * a required path param is missing from `params`, a param value does not satisfy
- * its route regex constraint, or a route param constraint has invalid syntax
- *
- * @example
- * ```ts
- * import { resolve } from 'bquery/router';
- *
- * const path = resolve('user', { id: '42' });
- * // Returns '/user/42' if route is defined as { name: 'user', path: '/user/:id' }
- * ```
- */
-export const resolve = (name: string, params: Record<string, string> = {}): string => {
-  const activeRouter = getActiveRouter();
-  if (!activeRouter) {
-    throw new Error('bQuery router: No router initialized.');
-  }
-
-  const route = activeRouter.routes.find((r) => r.name === name);
-  if (!route) {
-    throw new Error(`bQuery router: Route "${name}" not found.`);
-  }
-
-  let path = '';
-  for (let i = 0; i < route.path.length; ) {
-    if (route.path[i] === ':' && isParamStart(route.path[i + 1])) {
-      let nameEnd = i + 2;
-      while (nameEnd < route.path.length && isParamChar(route.path[nameEnd])) {
-        nameEnd++;
-      }
-
-      let nextIndex = nameEnd;
-      let constraint: string | null = null;
-      if (route.path[nameEnd] === '(') {
-        const parsedConstraint = readConstraint(route.path, nameEnd);
-        if (!parsedConstraint) {
-          throw new Error(
-            `bQuery router: Invalid constraint syntax in path "${route.path}" for route "${name}".`
-          );
-        }
-        constraint = parsedConstraint.constraint;
-        nextIndex = parsedConstraint.endIndex;
-      }
-
-      const key = route.path.slice(i + 1, nameEnd);
-      const value = params[key];
-      if (value === undefined) {
-        throw new Error(`bQuery router: Missing required param "${key}" for route "${name}".`);
-      }
-      if (constraint && !getRouteConstraintRegex(constraint).test(value)) {
-        throw new Error(
-          `bQuery router: Param "${key}" with value "${value}" does not satisfy the route constraint "${constraint}" for route "${name}".`
-        );
-      }
-
-      path += encodeURIComponent(value);
-      i = nextIndex;
-      continue;
-    }
-
-    path += route.path[i];
-    i++;
-  }
-
-  return path;
-};
-
-/**
- * Checks if a path matches the current route.
- *
- * @param path - Path to check
- * @param exact - Whether to match exactly (default: false)
- * @returns True if the path matches
- *
- * @example
- * ```ts
- * import { isActive } from 'bquery/router';
- *
- * if (isActive('/dashboard')) {
- *   // Highlight nav item
- * }
- * ```
- */
-export const isActive = (path: string, exact = false): boolean => {
-  const current = routeSignal.value.path;
-  return exact ? current === path : current.startsWith(path);
-};
-
-/**
- * Creates a computed signal that checks if a path is active.
- *
- * @param path - Path to check
- * @param exact - Whether to match exactly
- * @returns A reactive signal
- *
- * @example
- * ```ts
- * import { isActiveSignal } from 'bquery/router';
- * import { effect } from 'bquery/reactive';
- *
- * const dashboardActive = isActiveSignal('/dashboard');
- * effect(() => {
- *   navItem.classList.toggle('active', dashboardActive.value);
- * });
- * ```
- */
-export const isActiveSignal = (path: string, exact = false): ReadonlySignal<boolean> => {
-  return computed(() => {
-    const current = routeSignal.value.path;
-    return exact ? current === path : current.startsWith(path);
-  });
-};
+/**
+ * Router utilities.
+ * @module bquery/router
+ */
+
+import { computed, type ReadonlySignal } from '../reactive/index';
+import { getRouteConstraintRegex } from './constraints';
+import { isParamChar, isParamStart, readConstraint } from './path-pattern';
+import { getActiveRouter, routeSignal } from './state';
+import type { RouteDefinition } from './types';
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Flattens nested routes into a single array with full paths.
+ * Does NOT include the router base - base is only for browser history.
+ * @internal
+ */
+export const flattenRoutes = (routes: RouteDefinition[], parentPath = ''): RouteDefinition[] => {
+  const result: RouteDefinition[] = [];
+
+  for (const route of routes) {
+    const fullPath = route.path === '*' ? '*' : `${parentPath}${route.path}`.replace(/\/+/g, '/');
+
+    result.push({
+      ...route,
+      path: fullPath,
+    });
+
+    if (route.children) {
+      result.push(...flattenRoutes(route.children, fullPath));
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Resolves a route by name and params.
+ *
+ * @param name - The route name
+ * @param params - Route params to interpolate
+ * @returns The resolved path
+ * @throws {Error} If no router is initialized, the route name is unknown,
+ * a required path param is missing from `params`, a param value does not satisfy
+ * its route regex constraint, or a route param constraint has invalid syntax
+ *
+ * @example
+ * ```ts
+ * import { resolve } from 'bquery/router';
+ *
+ * const path = resolve('user', { id: '42' });
+ * // Returns '/user/42' if route is defined as { name: 'user', path: '/user/:id' }
+ * ```
+ */
+export const resolve = (name: string, params: Record<string, string> = {}): string => {
+  const activeRouter = getActiveRouter();
+  if (!activeRouter) {
+    throw new Error('bQuery router: No router initialized.');
+  }
+
+  const route = activeRouter.routes.find((r) => r.name === name);
+  if (!route) {
+    throw new Error(`bQuery router: Route "${name}" not found.`);
+  }
+
+  let path = '';
+  for (let i = 0; i < route.path.length; ) {
+    if (route.path[i] === ':' && isParamStart(route.path[i + 1])) {
+      let nameEnd = i + 2;
+      while (nameEnd < route.path.length && isParamChar(route.path[nameEnd])) {
+        nameEnd++;
+      }
+
+      let nextIndex = nameEnd;
+      let constraint: string | null = null;
+      if (route.path[nameEnd] === '(') {
+        const parsedConstraint = readConstraint(route.path, nameEnd);
+        if (!parsedConstraint) {
+          throw new Error(
+            `bQuery router: Invalid constraint syntax in path "${route.path}" for route "${name}".`
+          );
+        }
+        constraint = parsedConstraint.constraint;
+        nextIndex = parsedConstraint.endIndex;
+      }
+
+      const key = route.path.slice(i + 1, nameEnd);
+      const value = params[key];
+      if (value === undefined) {
+        throw new Error(`bQuery router: Missing required param "${key}" for route "${name}".`);
+      }
+      if (constraint && !getRouteConstraintRegex(constraint).test(value)) {
+        throw new Error(
+          `bQuery router: Param "${key}" with value "${value}" does not satisfy the route constraint "${constraint}" for route "${name}".`
+        );
+      }
+
+      path += encodeURIComponent(value);
+      i = nextIndex;
+      continue;
+    }
+
+    path += route.path[i];
+    i++;
+  }
+
+  return path;
+};
+
+/**
+ * Checks if a path matches the current route.
+ *
+ * @param path - Path to check
+ * @param exact - Whether to match exactly (default: false)
+ * @returns True if the path matches
+ *
+ * @example
+ * ```ts
+ * import { isActive } from 'bquery/router';
+ *
+ * if (isActive('/dashboard')) {
+ *   // Highlight nav item
+ * }
+ * ```
+ */
+export const isActive = (path: string, exact = false): boolean => {
+  const current = routeSignal.value.path;
+  return exact ? current === path : current.startsWith(path);
+};
+
+/**
+ * Creates a computed signal that checks if a path is active.
+ *
+ * @param path - Path to check
+ * @param exact - Whether to match exactly
+ * @returns A reactive signal
+ *
+ * @example
+ * ```ts
+ * import { isActiveSignal } from 'bquery/router';
+ * import { effect } from 'bquery/reactive';
+ *
+ * const dashboardActive = isActiveSignal('/dashboard');
+ * effect(() => {
+ *   navItem.classList.toggle('active', dashboardActive.value);
+ * });
+ * ```
+ */
+export const isActiveSignal = (path: string, exact = false): ReadonlySignal<boolean> => {
+  return computed(() => {
+    const current = routeSignal.value.path;
+    return exact ? current === path : current.startsWith(path);
+  });
+};

package/src/security/index.ts

@@ -1,12 +1,12 @@
-/**
- * Security module providing sanitization, CSP compatibility, and Trusted Types.
- *
- * @module bquery/security
- */
-
-export { generateNonce, hasCSPDirective } from './csp';
-export { escapeHtml, sanitizeHtml as sanitize, sanitizeHtml, stripTags } from './sanitize';
-export { trusted } from './trusted-html';
-export { createTrustedHtml, getTrustedTypesPolicy, isTrustedTypesSupported } from './trusted-types';
-export type { SanitizedHtml, TrustedHtml } from './trusted-html';
-export type { SanitizeOptions } from './types';
+/**
+ * Security module providing sanitization, CSP compatibility, and Trusted Types.
+ *
+ * @module bquery/security
+ */
+
+export { generateNonce, hasCSPDirective } from './csp';
+export { escapeHtml, sanitizeHtml as sanitize, sanitizeHtml, stripTags } from './sanitize';
+export { trusted } from './trusted-html';
+export { createTrustedHtml, getTrustedTypesPolicy, isTrustedTypesSupported } from './trusted-types';
+export type { SanitizedHtml, TrustedHtml } from './trusted-html';
+export type { SanitizeOptions } from './types';

package/src/ssr/hydrate.ts

@@ -1,82 +1,84 @@
-/**
- * Hydration support for server-rendered DOM.
- *
- * Enables the client-side view system to reuse existing server-rendered DOM
- * elements instead of re-rendering them, by attaching reactive bindings
- * to the pre-existing DOM structure.
- *
- * @module bquery/ssr
- */
-
-import type { BindingContext, MountOptions, View } from '../view/types';
-import { mount } from '../view/mount';
-
-/**
- * Extended mount options that include hydration mode.
- */
-export type HydrateMountOptions = MountOptions & {
-  /**
-   * When present, must be `true` so the mount operation reuses existing DOM elements
-   * instead of re-rendering them. Reactive bindings (effects) are
-   * still attached so the DOM updates reactively from that point on.
-   *
-   * @default true
-   */
-  hydrate?: true;
-};
-
-/**
- * Mounts a reactive view with optional hydration support.
- *
- * When `hydrate: true` is set, the existing server-rendered DOM is preserved
- * and reactive bindings are attached on top. The DOM is NOT re-rendered;
- * instead, effects begin tracking signals so future changes update the DOM.
- *
- * This is the client-side counterpart to `renderToString()`. The typical flow:
- * 1. Server: `renderToString(template, data)` → send HTML to client
- * 2. Client: `hydrateMount('#app', reactiveContext, { hydrate: true })`
- *
- * Under the hood, `hydrateMount` simply delegates to the standard `mount()`
- * function. The `mount()` function already processes existing DOM elements
- * and attaches reactive effects to them — it does not clear/replace content.
- * The `hydrate` flag is a semantic marker indicating developer intent and
- * ensures the existing DOM structure is preserved.
- *
- * @param selector - CSS selector or Element to hydrate
- * @param context - Binding context with signals, computed values, and functions
- * @param options - Mount options with `hydrate: true`
- * @returns The mounted View instance
- *
- * @example
- * ```ts
- * import { hydrateMount } from '@bquery/bquery/ssr';
- * import { signal, computed } from '@bquery/bquery/reactive';
- *
- * // Server rendered:
- * // <div id="app"><h1>Welcome</h1><p>Hello, World!</p></div>
- *
- * // Client hydration — attaches reactivity to existing DOM:
- * const name = signal('World');
- * const greeting = computed(() => `Hello, ${name.value}!`);
- *
- * const view = hydrateMount('#app', { name, greeting }, { hydrate: true });
- *
- * // Now updating `name.value` will reactively update the DOM
- * name.value = 'Alice'; // <p> updates to "Hello, Alice!"
- * ```
- */
-export const hydrateMount = (
-  selector: string | Element,
-  context: BindingContext,
-  options: HydrateMountOptions = {}
-): View => {
-  const { hydrate = true, ...mountOptions } = options;
-
-  if (!hydrate) {
-    throw new Error('bQuery ssr: hydrateMount() requires { hydrate: true } when options are provided.');
-  }
-
-  // Hydration uses the standard mount which processes existing DOM
-  // and attaches reactive effects without clearing content.
-  return mount(selector, context, mountOptions);
-};
+/**
+ * Hydration support for server-rendered DOM.
+ *
+ * Enables the client-side view system to reuse existing server-rendered DOM
+ * elements instead of re-rendering them, by attaching reactive bindings
+ * to the pre-existing DOM structure.
+ *
+ * @module bquery/ssr
+ */
+
+import type { BindingContext, MountOptions, View } from '../view/types';
+import { mount } from '../view/mount';
+
+/**
+ * Extended mount options that include hydration mode.
+ */
+export type HydrateMountOptions = MountOptions & {
+  /**
+   * When present, must be `true` so the mount operation reuses existing DOM elements
+   * instead of re-rendering them. Reactive bindings (effects) are
+   * still attached so the DOM updates reactively from that point on.
+   *
+   * @default true
+   */
+  hydrate?: true;
+};
+
+/**
+ * Mounts a reactive view with optional hydration support.
+ *
+ * When `hydrate: true` is set, the existing server-rendered DOM is preserved
+ * and reactive bindings are attached on top. The DOM is NOT re-rendered;
+ * instead, effects begin tracking signals so future changes update the DOM.
+ *
+ * This is the client-side counterpart to `renderToString()`. The typical flow:
+ * 1. Server: `renderToString(template, data)` → send HTML to client
+ * 2. Client: `hydrateMount('#app', reactiveContext, { hydrate: true })`
+ *
+ * Under the hood, `hydrateMount` simply delegates to the standard `mount()`
+ * function. The `mount()` function already processes existing DOM elements
+ * and attaches reactive effects to them — it does not clear/replace content.
+ * The `hydrate` flag is a semantic marker indicating developer intent and
+ * ensures the existing DOM structure is preserved.
+ *
+ * @param selector - CSS selector or Element to hydrate
+ * @param context - Binding context with signals, computed values, and functions
+ * @param options - Mount options with `hydrate: true`
+ * @returns The mounted View instance
+ *
+ * @example
+ * ```ts
+ * import { hydrateMount } from '@bquery/bquery/ssr';
+ * import { signal, computed } from '@bquery/bquery/reactive';
+ *
+ * // Server rendered:
+ * // <div id="app"><h1>Welcome</h1><p>Hello, World!</p></div>
+ *
+ * // Client hydration — attaches reactivity to existing DOM:
+ * const name = signal('World');
+ * const greeting = computed(() => `Hello, ${name.value}!`);
+ *
+ * const view = hydrateMount('#app', { name, greeting }, { hydrate: true });
+ *
+ * // Now updating `name.value` will reactively update the DOM
+ * name.value = 'Alice'; // <p> updates to "Hello, Alice!"
+ * ```
+ */
+export const hydrateMount = (
+  selector: string | Element,
+  context: BindingContext,
+  options: HydrateMountOptions = {}
+): View => {
+  const { hydrate = true, ...mountOptions } = options;
+
+  if (!hydrate) {
+    throw new Error(
+      'bQuery ssr: hydrateMount() requires { hydrate: true } when options are provided.'
+    );
+  }
+
+  // Hydration uses the standard mount which processes existing DOM
+  // and attaches reactive effects without clearing content.
+  return mount(selector, context, mountOptions);
+};

package/src/ssr/index.ts

@@ -1,70 +1,70 @@
-/**
- * SSR / Pre-rendering module for bQuery.js.
- *
- * Provides server-side rendering, hydration, and store state serialization
- * utilities for bQuery applications. Enables rendering bQuery templates
- * to HTML strings on the server, serializing store state for client pickup,
- * and hydrating the pre-rendered DOM on the client.
- *
- * ## Features
- *
- * - **`renderToString(template, data)`** — Server-side render a bQuery
- *   template to an `SSRResult` containing an `html` string with directive evaluation.
- * - **`hydrateMount(selector, context, { hydrate: true })`** — Reuse
- *   existing server-rendered DOM and attach reactive bindings.
- * - **`serializeStoreState(options?)`** — Serialize store state into a
- *   `<script>` tag for client-side pickup.
- * - **`deserializeStoreState()`** — Read serialized state on the client.
- * - **`hydrateStore(id, state)` / `hydrateStores(stateMap)`** — Apply
- *   server state to client stores.
- *
- * ## Usage
- *
- * ### Server
- * ```ts
- * import { renderToString, serializeStoreState } from '@bquery/bquery/ssr';
- *
- * const { html } = renderToString(
- *   '<div id="app"><h1 bq-text="title"></h1></div>',
- *   { title: 'Welcome' }
- * );
- *
- * const { scriptTag } = serializeStoreState();
- *
- * // Send to client: html + scriptTag
- * ```
- *
- * ### Client
- * ```ts
- * import { hydrateMount, deserializeStoreState, hydrateStores } from '@bquery/bquery/ssr';
- * import { signal } from '@bquery/bquery/reactive';
- *
- * // Restore store state from SSR
- * const ssrState = deserializeStoreState();
- * hydrateStores(ssrState);
- *
- * // Hydrate the DOM with reactive bindings
- * const title = signal('Welcome');
- * hydrateMount('#app', { title }, { hydrate: true });
- * ```
- *
- * @module bquery/ssr
- */
-
-export { hydrateMount } from './hydrate';
-export type { HydrateMountOptions } from './hydrate';
-export { renderToString } from './render';
-export {
-  deserializeStoreState,
-  hydrateStore,
-  hydrateStores,
-  serializeStoreState,
-} from './serialize';
-export type { SerializeResult } from './serialize';
-export type {
-  DeserializedStoreState,
-  HydrationOptions,
-  RenderOptions,
-  SSRResult,
-  SerializeOptions,
-} from './types';
+/**
+ * SSR / Pre-rendering module for bQuery.js.
+ *
+ * Provides server-side rendering, hydration, and store state serialization
+ * utilities for bQuery applications. Enables rendering bQuery templates
+ * to HTML strings on the server, serializing store state for client pickup,
+ * and hydrating the pre-rendered DOM on the client.
+ *
+ * ## Features
+ *
+ * - **`renderToString(template, data)`** — Server-side render a bQuery
+ *   template to an `SSRResult` containing an `html` string with directive evaluation.
+ * - **`hydrateMount(selector, context, { hydrate: true })`** — Reuse
+ *   existing server-rendered DOM and attach reactive bindings.
+ * - **`serializeStoreState(options?)`** — Serialize store state into a
+ *   `<script>` tag for client-side pickup.
+ * - **`deserializeStoreState()`** — Read serialized state on the client.
+ * - **`hydrateStore(id, state)` / `hydrateStores(stateMap)`** — Apply
+ *   server state to client stores.
+ *
+ * ## Usage
+ *
+ * ### Server
+ * ```ts
+ * import { renderToString, serializeStoreState } from '@bquery/bquery/ssr';
+ *
+ * const { html } = renderToString(
+ *   '<div id="app"><h1 bq-text="title"></h1></div>',
+ *   { title: 'Welcome' }
+ * );
+ *
+ * const { scriptTag } = serializeStoreState();
+ *
+ * // Send to client: html + scriptTag
+ * ```
+ *
+ * ### Client
+ * ```ts
+ * import { hydrateMount, deserializeStoreState, hydrateStores } from '@bquery/bquery/ssr';
+ * import { signal } from '@bquery/bquery/reactive';
+ *
+ * // Restore store state from SSR
+ * const ssrState = deserializeStoreState();
+ * hydrateStores(ssrState);
+ *
+ * // Hydrate the DOM with reactive bindings
+ * const title = signal('Welcome');
+ * hydrateMount('#app', { title }, { hydrate: true });
+ * ```
+ *
+ * @module bquery/ssr
+ */
+
+export { hydrateMount } from './hydrate';
+export type { HydrateMountOptions } from './hydrate';
+export { renderToString } from './render';
+export {
+  deserializeStoreState,
+  hydrateStore,
+  hydrateStores,
+  serializeStoreState,
+} from './serialize';
+export type { SerializeResult } from './serialize';
+export type {
+  DeserializedStoreState,
+  HydrationOptions,
+  RenderOptions,
+  SSRResult,
+  SerializeOptions,
+} from './types';