hyper-element 1.1.0 → 2.0.0

package/index.d.ts

@@ -133,21 +133,40 @@ export type SetupFunction = (
  */
 export type MethodFunction = (ctx: ElementContext, ...args: any[]) => any;
 
+/**
+ * SSR hydration lifecycle hook for functional components.
+ * Called before buffered events are replayed.
+ */
+export type OnBeforeHydrateFunction = (
+  ctx: ElementContext,
+  events: BufferedEvent[]
+) => BufferedEvent[];
+
+/**
+ * SSR hydration lifecycle hook for functional components.
+ * Called after event replay completes.
+ */
+export type OnAfterHydrateFunction = (ctx: ElementContext) => void;
+
 /**
  * Functional component definition object.
+ * Note: observedAttributes is not needed - all attributes are automatically reactive via MutationObserver.
  */
 export interface FunctionalDefinition {
-  /** Attributes to observe for changes */
-  observedAttributes?: string[];
   /** Setup lifecycle function */
   setup?: SetupFunction;
   /** Render function (required) */
   render: RenderFunction;
+  /** SSR hydration hook - filter events before replay */
+  onBeforeHydrate?: OnBeforeHydrateFunction;
+  /** SSR hydration hook - called after replay completes */
+  onAfterHydrate?: OnAfterHydrateFunction;
   /** Additional methods */
   [key: string]:
-    | string[]
     | SetupFunction
     | RenderFunction
+    | OnBeforeHydrateFunction
+    | OnAfterHydrateFunction
     | MethodFunction
     | undefined;
 }
@@ -189,6 +208,9 @@ export interface HyperElementFactory {
 
   /** Prototype for class inheritance */
   prototype: hyperElement;
+
+  /** Configure SSR hydration settings */
+  configureSSR(options: SSRConfig): void;
 }
 
 /**
@@ -273,6 +295,35 @@ export class hyperElement extends HTMLElement {
    * ```
    */
   render(Html: HtmlFunction, ...data: any[]): void;
+
+  /**
+   * SSR hydration lifecycle hook. Called before buffered events are replayed.
+   * Override to filter or modify events before replay.
+   *
+   * @param events - Buffered events captured during SSR
+   * @returns Filtered events to replay
+   *
+   * @example
+   * ```javascript
+   * onBeforeHydrate(events) {
+   *   return events.filter(e => e.type !== 'focus');
+   * }
+   * ```
+   */
+  onBeforeHydrate?(events: BufferedEvent[]): BufferedEvent[];
+
+  /**
+   * SSR hydration lifecycle hook. Called after event replay completes.
+   * Override to perform post-hydration setup.
+   *
+   * @example
+   * ```javascript
+   * onAfterHydrate() {
+   *   console.log('Component hydrated');
+   * }
+   * ```
+   */
+  onAfterHydrate?(): void;
 }
 
 /**
@@ -294,3 +345,293 @@ declare global {
 
 export { hyperElement };
 export default hyperElement;
+
+// ============================================================================
+// Signals API - Fine-grained reactivity primitives
+// ============================================================================
+
+/**
+ * A reactive signal that holds a value and notifies subscribers when it changes.
+ */
+export interface Signal<T> {
+  /** Get or set the current value. Reading tracks dependencies. */
+  value: T;
+  /** Read the current value without tracking dependencies. */
+  peek(): T;
+  /** Subscribe to value changes. Returns an unsubscribe function. */
+  subscribe(fn: () => void): () => void;
+}
+
+/**
+ * A computed signal that derives its value from other signals.
+ */
+export interface Computed<T> {
+  /** Get the computed value. Automatically tracks dependencies and recomputes when they change. */
+  readonly value: T;
+  /** Read the computed value without tracking dependencies. */
+  peek(): T;
+}
+
+/**
+ * Creates a reactive signal.
+ * @param initialValue - The initial value of the signal
+ * @returns A signal object with value getter/setter, peek(), and subscribe()
+ *
+ * @example
+ * ```javascript
+ * const count = signal(0);
+ * count.value; // 0
+ * count.value = 1; // Updates and notifies subscribers
+ * count.peek(); // Read without tracking
+ * ```
+ */
+export function signal<T>(initialValue: T): Signal<T>;
+
+/**
+ * Creates a computed signal that derives from other signals.
+ * The computation is lazy and cached until dependencies change.
+ * @param fn - Computation function that reads other signals
+ * @returns A computed signal object with value getter and peek()
+ *
+ * @example
+ * ```javascript
+ * const count = signal(0);
+ * const doubled = computed(() => count.value * 2);
+ * doubled.value; // 0
+ * count.value = 5;
+ * doubled.value; // 10
+ * ```
+ */
+export function computed<T>(fn: () => T): Computed<T>;
+
+/**
+ * Creates an effect that runs when its dependencies change.
+ * The effect runs immediately and re-runs whenever any signal it reads changes.
+ * @param fn - Effect function. Can return a cleanup function.
+ * @returns Cleanup function to stop the effect
+ *
+ * @example
+ * ```javascript
+ * const count = signal(0);
+ * const cleanup = effect(() => {
+ *   console.log('Count:', count.value);
+ *   return () => console.log('Cleanup');
+ * });
+ * // Logs: "Count: 0"
+ * count.value = 1;
+ * // Logs: "Cleanup", then "Count: 1"
+ * cleanup(); // Stop the effect
+ * ```
+ */
+export function effect(fn: () => void | (() => void)): () => void;
+
+/**
+ * Batches multiple signal updates into a single notification.
+ * Effects are deferred until the batch completes.
+ * @param fn - Function containing signal updates
+ *
+ * @example
+ * ```javascript
+ * const a = signal(0);
+ * const b = signal(0);
+ * batch(() => {
+ *   a.value = 1;
+ *   b.value = 2;
+ * }); // Effects run once after both updates
+ * ```
+ */
+export function batch(fn: () => void): void;
+
+/**
+ * Runs a function without tracking signal dependencies.
+ * Useful for reading signals without creating subscriptions.
+ * @param fn - Function to run untracked
+ * @returns The return value of fn
+ *
+ * @example
+ * ```javascript
+ * const count = signal(0);
+ * effect(() => {
+ *   const val = untracked(() => count.value);
+ *   // This effect won't re-run when count changes
+ * });
+ * ```
+ */
+export function untracked<T>(fn: () => T): T;
+
+// ============================================================================
+// SSR Hydration API
+// ============================================================================
+
+/**
+ * Buffered event captured during SSR hydration.
+ */
+export interface BufferedEvent {
+  /** Event type (e.g., 'click', 'input') */
+  type: string;
+  /** Path from custom element to target (e.g., "DIV:0/BUTTON:1") */
+  targetPath: string;
+  /** Timestamp when event was captured */
+  timestamp: number;
+  /** Event-specific details */
+  detail: Record<string, any>;
+}
+
+/**
+ * SSR configuration options.
+ */
+export interface SSRConfig {
+  /** Event types to capture during SSR hydration (default: all interactive events) */
+  events?: string[];
+  /** Show visual indicator in development mode (default: false) */
+  devMode?: boolean;
+}
+
+/**
+ * Configure SSR hydration settings.
+ * Call this before any custom elements are defined to customize behavior.
+ *
+ * @param options - Configuration options
+ *
+ * @example
+ * ```javascript
+ * // Enable dev mode indicator
+ * hyperElement.configureSSR({ devMode: true });
+ *
+ * // Customize captured events
+ * hyperElement.configureSSR({
+ *   events: ['click', 'input', 'submit'],
+ *   devMode: true
+ * });
+ * ```
+ */
+export function configureSSR(options: SSRConfig): void;
+
+// ============================================================================
+// SSR String Rendering API (Node.js/Server-side)
+// ============================================================================
+
+/**
+ * Options for renderElement function.
+ */
+export interface RenderElementOptions<T = any> {
+  /** Attributes to pass to the component */
+  attrs?: Record<string, unknown>;
+  /** Store data for render context */
+  store?: T;
+  /** Wrap content in Declarative Shadow DOM template (default: false) */
+  shadowDOM?: boolean;
+  /** Fragment functions for the component */
+  fragments?: Record<string, (data: any) => any>;
+  /** Render function (Html, ctx) => void */
+  render: (Html: HtmlFunction, ctx: ElementContext) => void;
+}
+
+/**
+ * Renders a component definition to an HTML string.
+ * Use this in Node.js/Deno/Bun for server-side rendering.
+ *
+ * @param tagName - Custom element tag name (e.g., 'my-component')
+ * @param options - Render options
+ * @returns Promise resolving to HTML string
+ *
+ * @example
+ * ```javascript
+ * const { renderElement } = require('hyper-element/ssr/server');
+ *
+ * const html = await renderElement('my-greeting', {
+ *   attrs: { name: 'World' },
+ *   render: (Html, ctx) => Html`<div>Hello ${ctx.attrs.name}!</div>`
+ * });
+ * // Returns: '<my-greeting name="World"><div>Hello World!</div></my-greeting>'
+ *
+ * // With Declarative Shadow DOM
+ * const shadowHtml = await renderElement('my-greeting', {
+ *   attrs: { name: 'World' },
+ *   shadowDOM: true,
+ *   render: (Html, ctx) => Html`<div>Hello ${ctx.attrs.name}!</div>`
+ * });
+ * // Returns: '<my-greeting name="World"><template shadowrootmode="open"><div>Hello World!</div></template></my-greeting>'
+ * ```
+ */
+export function renderElement<T = any>(
+  tagName: string,
+  options: RenderElementOptions<T>
+): Promise<string>;
+
+/**
+ * Renders multiple elements in parallel.
+ * Useful for batch SSR rendering.
+ *
+ * @param elements - Array of elements to render
+ * @returns Promise resolving to array of HTML strings
+ */
+export function renderElements(
+  elements: Array<{ tagName: string; options: RenderElementOptions }>
+): Promise<string[]>;
+
+/**
+ * Creates a reusable component renderer.
+ * Useful for rendering the same component multiple times with different data.
+ *
+ * @param tagName - Custom element tag name
+ * @param render - Render function
+ * @param baseOptions - Base options merged with each render
+ * @returns Renderer function
+ */
+export function createRenderer<T = any>(
+  tagName: string,
+  render: (Html: HtmlFunction, ctx: ElementContext) => void,
+  baseOptions?: Partial<RenderElementOptions<T>>
+): (attrs?: Record<string, unknown>, store?: T) => Promise<string>;
+
+/**
+ * Renders a tagged template literal to an HTML string.
+ * Lower-level API for direct template rendering.
+ *
+ * @param template - Template strings array
+ * @param values - Interpolated values
+ * @param xml - SVG/XML mode (default: false)
+ * @returns HTML string
+ */
+export function renderToString(
+  template: TemplateStringsArray,
+  values: unknown[],
+  xml?: boolean
+): string;
+
+/**
+ * Creates an SSR Html tagged template function.
+ * Use this for custom SSR rendering scenarios.
+ *
+ * @param context - Render context with attrs, store, fragments
+ * @returns Html function with wire, raw, lite methods
+ */
+export function createSSRHtml(context?: {
+  attrs?: Record<string, unknown>;
+  store?: any;
+  fragments?: Record<string, (data: any) => any>;
+}): HtmlFunction;
+
+/**
+ * SSR HTML tagged template function.
+ * Renders directly to string without any component wrapper.
+ */
+export const ssrHtml: (
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+) => string;
+
+/**
+ * Escapes HTML special characters to prevent XSS.
+ * @param str - String to escape
+ * @returns Escaped string
+ */
+export function escapeHtml(str: string): string;
+
+/**
+ * Marks a string as safe HTML that should not be escaped.
+ * @param html - HTML string to mark as safe
+ * @returns Safe HTML object
+ */
+export function safeHtml(html: string): { value: string };

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.0",
+  "version": "2.0.0",
   "name": "hyper-element",
   "author": "Brian Shannon (github.com/codemeasandwich)",
   "description": "Fast, lightweight web components",
@@ -12,11 +12,14 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "npm run build && npm run test:coverage && npm run test:minified; rm -rf build",
-    "test:coverage": "playwright test",
-    "test:minified": "TEST_BUNDLE=min playwright test",
-    "test:ui": "npm run build && playwright test --ui; rm -rf build",
-    "test:headed": "npm run build && playwright test --headed; rm -rf build",
+    "test": "npm run test:src && npm run test:bundle",
+    "test:src": "rm -rf coverage && playwright test --project=source-coverage && npm run test:ssr-coverage && npm run test:coverage-report",
+    "test:bundle": "npm run build && playwright test --project=bundle-verify; rm -rf build",
+    "test:ssr": "node test/ssr.test.mjs",
+    "test:ssr-coverage": "node test/ssr-with-coverage.mjs",
+    "test:coverage-report": "node test/coverage-report.mjs",
+    "test:ui": "playwright test --project=source-coverage --ui",
+    "test:headed": "playwright test --project=source-coverage --headed",
     "kitchensink": "npm run build && cp -r build kitchensink/ && (sleep 1 && open http://localhost:3000) & npx serve ./kitchensink",
     "release": "bash scripts/publish.sh",
     "hooks:install": "cp .hooks/pre-commit .git/hooks/ && cp .hooks/commit-msg .git/hooks/ && cp -r .hooks/pre-commit.d .git/hooks/ && chmod +x .git/hooks/pre-commit .git/hooks/commit-msg .git/hooks/pre-commit.d/*.sh",
@@ -50,14 +53,16 @@
     "eslint-config-prettier": "^9.1.2",
     "eslint-plugin-prettier": "^5.5.5",
     "husky": "^9.1.7",
+    "istanbul-lib-coverage": "^3.2.2",
+    "istanbul-lib-report": "^3.0.1",
+    "istanbul-reports": "^3.2.0",
     "lint-staged": "^15.5.2",
-    "lodash": "^4.17.21",
     "minimist": "^1.2.8",
     "mkdirp": "^1.0.4",
     "prettier": "^3.8.0",
     "serve": "^14.2.5",
     "set-value": "^2.0.1",
-    "typescript": "^5.9.3",
+    "source-map": "^0.7.6",
     "union-value": "^2.0.1",
     "v8-to-istanbul": "^9.3.0"
   }