@bquery/bquery 1.6.0 → 1.8.1

package/src/security/sanitize.ts

@@ -1,70 +1,70 @@
-/**
- * Security utilities for HTML sanitization.
- * All DOM writes are sanitized by default to prevent XSS attacks.
- *
- * @module bquery/security
- */
-
-import { sanitizeHtmlCore } from './sanitize-core';
-import { toSanitizedHtml } from './trusted-html';
-import type { SanitizedHtml } from './trusted-html';
-import type { SanitizeOptions } from './types';
-export { generateNonce } from './csp';
-export { isTrustedTypesSupported } from './trusted-types';
-export { trusted } from './trusted-html';
-export type { SanitizedHtml, TrustedHtml } from './trusted-html';
-
-/**
- * Sanitize HTML string, removing dangerous elements and attributes.
- * Uses Trusted Types when available for CSP compliance.
- *
- * @param html - The HTML string to sanitize
- * @param options - Sanitization options
- * @returns Sanitized HTML string
- *
- * @example
- * ```ts
- * const safe = sanitizeHtml('<div onclick="alert(1)">Hello</div>');
- * // Returns: '<div>Hello</div>'
- * ```
- */
-export const sanitizeHtml = (html: string, options: SanitizeOptions = {}): SanitizedHtml => {
-  return toSanitizedHtml(sanitizeHtmlCore(html, options));
-};
-
-/**
- * Escape HTML entities to prevent XSS.
- * Use this for displaying user content as text.
- *
- * @param text - The text to escape
- * @returns Escaped HTML string
- *
- * @example
- * ```ts
- * escapeHtml('<script>alert(1)</script>');
- * // Returns: '&lt;script&gt;alert(1)&lt;/script&gt;'
- * ```
- */
-export const escapeHtml = (text: string): string => {
-  const escapeMap: Record<string, string> = {
-    '&': '&amp;',
-    '<': '&lt;',
-    '>': '&gt;',
-    '"': '&quot;',
-    "'": '&#x27;',
-    '`': '&#x60;',
-  };
-  return text.replace(/[&<>"'`]/g, (char) => escapeMap[char]);
-};
-
-/**
- * Strip all HTML tags and return plain text.
- *
- * @param html - The HTML string to strip
- * @returns Plain text content
- */
-export const stripTags = (html: string): string => {
-  return sanitizeHtmlCore(html, { stripAllTags: true });
-};
-
-export type { SanitizeOptions } from './types';
+/**
+ * Security utilities for HTML sanitization.
+ * All DOM writes are sanitized by default to prevent XSS attacks.
+ *
+ * @module bquery/security
+ */
+
+import { sanitizeHtmlCore } from './sanitize-core';
+import { toSanitizedHtml } from './trusted-html';
+import type { SanitizedHtml } from './trusted-html';
+import type { SanitizeOptions } from './types';
+export { generateNonce } from './csp';
+export { isTrustedTypesSupported } from './trusted-types';
+export { trusted } from './trusted-html';
+export type { SanitizedHtml, TrustedHtml } from './trusted-html';
+
+/**
+ * Sanitize HTML string, removing dangerous elements and attributes.
+ * Uses Trusted Types when available for CSP compliance.
+ *
+ * @param html - The HTML string to sanitize
+ * @param options - Sanitization options
+ * @returns Sanitized HTML string
+ *
+ * @example
+ * ```ts
+ * const safe = sanitizeHtml('<div onclick="alert(1)">Hello</div>');
+ * // Returns: '<div>Hello</div>'
+ * ```
+ */
+export const sanitizeHtml = (html: string, options: SanitizeOptions = {}): SanitizedHtml => {
+  return toSanitizedHtml(sanitizeHtmlCore(html, options));
+};
+
+/**
+ * Escape HTML entities to prevent XSS.
+ * Use this for displaying user content as text.
+ *
+ * @param text - The text to escape
+ * @returns Escaped HTML string
+ *
+ * @example
+ * ```ts
+ * escapeHtml('<script>alert(1)</script>');
+ * // Returns: '&lt;script&gt;alert(1)&lt;/script&gt;'
+ * ```
+ */
+export const escapeHtml = (text: string): string => {
+  const escapeMap: Record<string, string> = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#x27;',
+    '`': '&#x60;',
+  };
+  return text.replace(/[&<>"'`]/g, (char) => escapeMap[char]);
+};
+
+/**
+ * Strip all HTML tags and return plain text.
+ *
+ * @param html - The HTML string to strip
+ * @returns Plain text content
+ */
+export const stripTags = (html: string): string => {
+  return sanitizeHtmlCore(html, { stripAllTags: true });
+};
+
+export type { SanitizeOptions } from './types';

package/src/security/trusted-html.ts

@@ -1,71 +1,71 @@
-declare const sanitizedHtmlBrand: unique symbol;
-const trustedHtmlBrand: unique symbol = Symbol('bquery.trusted-html.brand');
-const TRUSTED_HTML_VALUE = Symbol('bquery.trusted-html');
-
-/**
- * Branded HTML string produced by bQuery's sanitization or escaping template helpers.
- *
- * Values returned from {@link sanitizeHtml} carry sanitized markup. Values returned from
- * {@link safeHtml} preserve the template's static markup while escaping normal interpolations
- * and splicing {@link trusted} fragments verbatim. This brand is not intended for arbitrary
- * strings or manual concatenation outside those helpers.
- */
-export type SanitizedHtml = string & { readonly [sanitizedHtmlBrand]: true };
-
-/**
- * Marker object that safeHtml can splice into templates without escaping again.
- */
-export type TrustedHtml = { readonly [trustedHtmlBrand]: true; toString(): string };
-
-type TrustedHtmlValue = TrustedHtml & { readonly [TRUSTED_HTML_VALUE]: string };
-
-/**
- * Apply the internal {@link SanitizedHtml} brand to helper output.
- *
- * @internal
- */
-export const toSanitizedHtml = (html: string): SanitizedHtml => html as SanitizedHtml;
-
-/**
- * Mark a sanitized HTML string for verbatim splicing into safeHtml templates.
- *
- * @param html - HTML previously produced by sanitizeHtml, safeHtml, or another trusted bQuery helper
- * @returns Trusted HTML marker object for safeHtml interpolations
- *
- * @example
- * ```ts
- * const badge = trusted(sanitizeHtml('<strong onclick="alert(1)">New</strong>'));
- * const markup = safeHtml`<span>${badge}</span>`;
- * ```
- */
-export const trusted = (html: SanitizedHtml): TrustedHtml => {
-  const value = String(html);
-  return Object.freeze({
-    [trustedHtmlBrand]: true as const,
-    [TRUSTED_HTML_VALUE]: value,
-    toString: () => value,
-  });
-};
-
-/**
- * Check whether a value is a trusted HTML marker created by trusted().
- *
- * @internal
- */
-export const isTrustedHtml = (value: unknown): value is TrustedHtml => {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    trustedHtmlBrand in value &&
-    TRUSTED_HTML_VALUE in value
-  );
-};
-
-/**
- * Unwrap the raw HTML string stored inside a trusted HTML marker.
- *
- * @internal
- */
-export const unwrapTrustedHtml = (value: TrustedHtml): string => {
-  return (value as TrustedHtmlValue)[TRUSTED_HTML_VALUE];
-};
+declare const sanitizedHtmlBrand: unique symbol;
+const trustedHtmlBrand: unique symbol = Symbol('bquery.trusted-html.brand');
+const TRUSTED_HTML_VALUE = Symbol('bquery.trusted-html');
+
+/**
+ * Branded HTML string produced by bQuery's sanitization or escaping template helpers.
+ *
+ * Values returned from {@link sanitizeHtml} carry sanitized markup. Values returned from
+ * {@link safeHtml} preserve the template's static markup while escaping normal interpolations
+ * and splicing {@link trusted} fragments verbatim. This brand is not intended for arbitrary
+ * strings or manual concatenation outside those helpers.
+ */
+export type SanitizedHtml = string & { readonly [sanitizedHtmlBrand]: true };
+
+/**
+ * Marker object that safeHtml can splice into templates without escaping again.
+ */
+export type TrustedHtml = { readonly [trustedHtmlBrand]: true; toString(): string };
+
+type TrustedHtmlValue = TrustedHtml & { readonly [TRUSTED_HTML_VALUE]: string };
+
+/**
+ * Apply the internal {@link SanitizedHtml} brand to helper output.
+ *
+ * @internal
+ */
+export const toSanitizedHtml = (html: string): SanitizedHtml => html as SanitizedHtml;
+
+/**
+ * Mark a sanitized HTML string for verbatim splicing into safeHtml templates.
+ *
+ * @param html - HTML previously produced by sanitizeHtml, safeHtml, or another trusted bQuery helper
+ * @returns Trusted HTML marker object for safeHtml interpolations
+ *
+ * @example
+ * ```ts
+ * const badge = trusted(sanitizeHtml('<strong onclick="alert(1)">New</strong>'));
+ * const markup = safeHtml`<span>${badge}</span>`;
+ * ```
+ */
+export const trusted = (html: SanitizedHtml): TrustedHtml => {
+  const value = String(html);
+  return Object.freeze({
+    [trustedHtmlBrand]: true as const,
+    [TRUSTED_HTML_VALUE]: value,
+    toString: () => value,
+  });
+};
+
+/**
+ * Check whether a value is a trusted HTML marker created by trusted().
+ *
+ * @internal
+ */
+export const isTrustedHtml = (value: unknown): value is TrustedHtml => {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    trustedHtmlBrand in value &&
+    TRUSTED_HTML_VALUE in value
+  );
+};
+
+/**
+ * Unwrap the raw HTML string stored inside a trusted HTML marker.
+ *
+ * @internal
+ */
+export const unwrapTrustedHtml = (value: TrustedHtml): string => {
+  return (value as TrustedHtmlValue)[TRUSTED_HTML_VALUE];
+};

package/src/ssr/hydrate.ts

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

package/src/ssr/index.ts

@@ -0,0 +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';