hyper-element 1.1.0 → 2.0.0

package/README.md

@@ -5,6 +5,7 @@
 [![CI](https://github.com/codemeasandwich/hyper-element/actions/workflows/publish.yml/badge.svg)](https://github.com/codemeasandwich/hyper-element/actions/workflows/publish.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/codemeasandwich/hyper-element)
+[![XSS Protected](https://img.shields.io/badge/XSS-Protected-blue.svg)](https://github.com/codemeasandwich/hyper-element)
 [![ES6+](https://img.shields.io/badge/ES6+-supported-blue.svg)](https://caniuse.com/es6)
 
 A lightweight [Custom Elements] library with a fast, built-in render core. Your custom-element will react to tag attribute and store changes with efficient DOM updates.
@@ -24,14 +25,7 @@ npm install hyper-element
 ```js
 import hyperElement from 'hyper-element';
 
-customElements.define(
-  'my-elem',
-  class extends hyperElement {
-    render(Html) {
-      Html`Hello ${this.attrs.who}!`;
-    }
-  }
-);
+hyperElement('my-elem', (Html, ctx) => Html`Hello ${ctx.attrs.who}!`);
 ```
 
 ### CommonJS
@@ -39,14 +33,7 @@ customElements.define(
 ```js
 const hyperElement = require('hyper-element');
 
-customElements.define(
-  'my-elem',
-  class extends hyperElement {
-    render(Html) {
-      Html`Hello ${this.attrs.who}!`;
-    }
-  }
-);
+hyperElement('my-elem', (Html, ctx) => Html`Hello ${ctx.attrs.who}!`);
 ```
 
 ## CDN (Browser)
@@ -65,10 +52,10 @@ hyper-element requires native ES6 class support and the Custom Elements v1 API:
 
 | Browser | Version |
 | ------- | ------- |
-| Chrome  | 67+     |
-| Firefox | 63+     |
-| Safari  | 10.1+   |
-| Edge    | 79+     |
+| Chrome  | 86+     |
+| Firefox | 78+     |
+| Safari  | 14.1+   |
+| Edge    | 86+     |
 
 For older browsers, a [Custom Elements polyfill](https://github.com/webcomponents/polyfills/tree/master/packages/custom-elements) may be required.
 
@@ -81,6 +68,7 @@ For older browsers, a [Custom Elements polyfill](https://github.com/webcomponent
 - Built in [template](#templates) system to customise the rendered output
 - Inline style objects supported (similar to React)
 - First class support for [data stores](#connecting-to-a-data-store)
+- [Server-side rendering](#server-side-rendering-ssr) with progressive hydration
 - Pass `function` to other custom hyper-elements via there tag attribute
 
 # [Live Demo](https://jsfiddle.net/codemeasandwich/k25e6ufv/)
@@ -122,6 +110,16 @@ For older browsers, a [Custom Elements polyfill](https://github.com/webcomponent
   - [Backbone](#backbone)
   - [MobX](#mobx)
   - [Redux](#redux)
+- [Signals](#signals)
+  - [signal](#signal)
+  - [computed](#computed-1)
+  - [effect](#effect)
+  - [batch](#batch)
+  - [untracked](#untracked)
+- [Server-Side Rendering (SSR)](#server-side-rendering-ssr)
+  - [Server-Side API](#server-side-api)
+  - [Client-Side Hydration](#client-side-hydration)
+  - [SSR Configuration](#ssr-configuration)
 - [Best Practices](#best-practices)
 - [Development](#development)
 
@@ -170,7 +168,6 @@ In addition to class-based components, hyper-element supports a functional API t
 ```js
 // 1. Full definition with tag (auto-registers)
 hyperElement('my-counter', {
-  observedAttributes: ['count'],
   setup: (ctx, onNext) => {
     /* ... */
   },
@@ -488,6 +485,33 @@ The `once: true` option ensures the fragment is only generated once, preventing
 
 ---
 
+## Html.raw
+
+Mark a string as trusted HTML that should not be escaped. Use this when you have HTML from a trusted source that you need to render directly.
+
+**Warning:** Only use with trusted content. Never use with user-provided input as it bypasses XSS protection.
+
+```js
+render(Html) {
+  const trustedHtml = '<strong>Bold</strong> and <em>italic</em>';
+  Html`<div>${Html.raw(trustedHtml)}</div>`;
+}
+```
+
+Output:
+
+```html
+<div><strong>Bold</strong> and <em>italic</em></div>
+```
+
+Without `Html.raw()`, the HTML would be escaped:
+
+```html
+<div>&lt;strong&gt;Bold&lt;/strong&gt; and &lt;em&gt;italic&lt;/em&gt;</div>
+```
+
+---
+
 ## setup
 
 The `setup` function wires up an external data-source. This is done with the `attachStore` argument that binds a data source to your renderer.
@@ -573,6 +597,7 @@ Available properties and methods on `this`:
 | `this.wrappedContent` | Text content between your tags. `<my-elem>Hi!</my-elem>` = `"Hi!"`          |
 | `this.element`        | Reference to your created DOM element                                       |
 | `this.dataset`        | Read/write access to all `data-*` attributes                                |
+| `this.innerShadow`    | Get the innerHTML of the element's rendered content                         |
 
 ### this.attrs
 
@@ -959,6 +984,472 @@ customElements.define(
 
 ---
 
+# Signals
+
+hyper-element includes a built-in signals API for fine-grained reactivity, similar to Solid.js or Preact Signals. Signals provide automatic dependency tracking and efficient updates.
+
+```js
+import { signal, computed, effect, batch, untracked } from 'hyper-element';
+```
+
+## signal
+
+Creates a reactive signal that holds a value and notifies subscribers when it changes.
+
+```js
+const count = signal(0);
+
+// Read value (tracks dependencies in effects/computed)
+console.log(count.value); // 0
+
+// Write value (notifies subscribers)
+count.value = 1;
+
+// Read without tracking
+count.peek(); // 1
+
+// Subscribe to changes
+const unsubscribe = count.subscribe(() => {
+  console.log('Count changed:', count.peek());
+});
+```
+
+## computed
+
+Creates a derived signal that automatically recomputes when its dependencies change. Computation is lazy and cached.
+
+```js
+const count = signal(0);
+const doubled = computed(() => count.value * 2);
+
+console.log(doubled.value); // 0
+
+count.value = 5;
+console.log(doubled.value); // 10
+
+// Read without tracking
+doubled.peek(); // 10
+```
+
+## effect
+
+Creates a side effect that runs immediately and re-runs whenever its dependencies change. Can return a cleanup function.
+
+```js
+const count = signal(0);
+
+// Effect runs immediately, then on every change
+const cleanup = effect(() => {
+  console.log('Count is:', count.value);
+
+  // Optional cleanup function
+  return () => {
+    console.log('Cleaning up previous effect');
+  };
+});
+
+count.value = 1;
+// Logs: "Cleaning up previous effect"
+// Logs: "Count is: 1"
+
+// Stop the effect
+cleanup();
+```
+
+## batch
+
+Batches multiple signal updates so effects only run once after all updates complete.
+
+```js
+const firstName = signal('John');
+const lastName = signal('Doe');
+
+effect(() => {
+  console.log(`${firstName.value} ${lastName.value}`);
+});
+// Logs: "John Doe"
+
+// Without batch: effect would run twice
+// With batch: effect runs once after both updates
+batch(() => {
+  firstName.value = 'Jane';
+  lastName.value = 'Smith';
+});
+// Logs: "Jane Smith" (only once)
+```
+
+## untracked
+
+Reads signals without creating dependencies. Useful for reading values in effects without subscribing to changes.
+
+```js
+const count = signal(0);
+const other = signal('hello');
+
+effect(() => {
+  // This dependency IS tracked
+  console.log('Count:', count.value);
+
+  // This read is NOT tracked - effect won't re-run when 'other' changes
+  const otherValue = untracked(() => other.value);
+  console.log('Other:', otherValue);
+});
+
+count.value = 1; // Effect re-runs
+other.value = 'world'; // Effect does NOT re-run
+```
+
+## Using Signals with hyper-element
+
+Signals integrate naturally with hyper-element's setup/render lifecycle:
+
+```js
+import hyperElement, { signal, effect } from 'hyper-element';
+
+hyperElement('counter-app', {
+  setup: (ctx, onNext) => {
+    const count = signal(0);
+
+    // Trigger re-render when count changes
+    const stopEffect = effect(() => {
+      onNext(() => ({ count: count.value }))();
+    });
+
+    // Expose increment method
+    ctx.increment = () => count.value++;
+
+    // Cleanup effect on disconnect
+    return stopEffect;
+  },
+
+  handleClick: (ctx) => ctx.increment(),
+
+  render: (Html, ctx, store) => Html`
+    <button onclick=${ctx.handleClick}>
+      Count: ${store?.count ?? 0}
+    </button>
+  `,
+});
+```
+
+---
+
+# Server-Side Rendering (SSR)
+
+hyper-element supports server-side rendering for faster initial page loads and SEO. The SSR system has two parts:
+
+1. **Server-side API** - Render components to HTML strings in Node.js/Deno/Bun
+2. **Client-side hydration** - Capture user interactions during page load and replay them after components register
+
+## Server-Side API
+
+Import SSR functions from the dedicated server entry point:
+
+```js
+// Node.js / Bun / Deno
+import {
+  renderElement,
+  renderElements,
+  createRenderer,
+  ssrHtml,
+  escapeHtml,
+  safeHtml,
+} from 'hyper-element/ssr/server';
+```
+
+### renderElement
+
+Render a single component to an HTML string:
+
+```js
+const html = await renderElement('user-card', {
+  attrs: { name: 'Alice', role: 'Admin' },
+  store: { lastLogin: '2024-01-15' },
+  render: (Html, ctx) => Html`
+    <div class="card">
+      <h2>${ctx.attrs.name}</h2>
+      <span>${ctx.attrs.role}</span>
+      <small>Last login: ${ctx.store.lastLogin}</small>
+    </div>
+  `,
+});
+
+// Result: <user-card name="Alice" role="Admin"><div class="card">...</div></user-card>
+```
+
+**Options:**
+
+| Option      | Type       | Description                                           |
+| ----------- | ---------- | ----------------------------------------------------- |
+| `attrs`     | `object`   | Attributes to pass to the component                   |
+| `store`     | `object`   | Store data available in render                        |
+| `render`    | `function` | Required render function `(Html, ctx) => Html\`...\`` |
+| `shadowDOM` | `boolean`  | Wrap output in Declarative Shadow DOM template        |
+| `fragments` | `object`   | Fragment functions for async content                  |
+
+### createRenderer
+
+Create a reusable renderer for a component:
+
+```js
+const renderUserCard = createRenderer(
+  'user-card',
+  (Html, ctx) => Html`
+    <div class="card">
+      <h2>${ctx.attrs.name}</h2>
+    </div>
+  `,
+  { shadowDOM: false } // default options
+);
+
+// Use it multiple times
+const html1 = await renderUserCard({ name: 'Alice' });
+const html2 = await renderUserCard({ name: 'Bob' });
+```
+
+### renderElements
+
+Render multiple components in parallel:
+
+```js
+const results = await renderElements([
+  { tagName: 'user-card', attrs: { name: 'Alice' }, render: renderFn },
+  { tagName: 'user-card', attrs: { name: 'Bob' }, render: renderFn },
+]);
+// Returns array of HTML strings
+```
+
+### ssrHtml
+
+Tagged template literal for rendering HTML strings directly. SVG content is auto-detected when using `<svg>` tags:
+
+```js
+const header = ssrHtml`<header><h1>${title}</h1></header>`;
+const icon = ssrHtml`<svg viewBox="0 0 24 24"><path d="${pathData}"/></svg>`;
+```
+
+### escapeHtml / safeHtml
+
+Utility functions for HTML escaping:
+
+```js
+// Escape user input
+const safe = escapeHtml('<script>alert("xss")</script>');
+// Result: &lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;
+
+// Mark trusted HTML as safe (bypasses escaping)
+const trusted = safeHtml('<strong>Bold</strong>');
+```
+
+### Fragments in SSR
+
+Fragments work on the server too for async content:
+
+```js
+const html = await renderElement('user-profile', {
+  attrs: { userId: '123' },
+  fragments: {
+    FriendCount: async (userId) => {
+      const count = await fetchFriendCount(userId);
+      return { text: `${count} friends` };
+    },
+  },
+  render: (Html, ctx) => Html`
+    <div>
+      <h1>Profile</h1>
+      <p>${{ FriendCount: ctx.attrs.userId }}</p>
+    </div>
+  `,
+});
+```
+
+---
+
+## Client-Side Hydration
+
+When SSR HTML arrives in the browser, users can interact with elements before JavaScript loads and components register. hyper-element captures these interactions and replays them after hydration.
+
+### How It Works
+
+```
+1. CAPTURE - hyper-element loads in <head>, starts listening for events
+2. BUFFER  - User interacts with SSR markup, events are stored
+3. REPLAY  - After customElements.define() + first render, events replay
+```
+
+### configureSSR
+
+Configure which events to capture (call before components register):
+
+```js
+import { configureSSR } from 'hyper-element';
+
+configureSSR({
+  events: ['click', 'input', 'change', 'submit'], // Events to capture
+  devMode: true, // Show visual indicator during capture (dev only)
+});
+```
+
+**Default captured events:** `click`, `dblclick`, `input`, `change`, `submit`, `keydown`, `keyup`, `keypress`, `focus`, `blur`, `focusin`, `focusout`, `touchstart`, `touchend`, `touchmove`, `touchcancel`
+
+### Lifecycle Hooks
+
+Components can hook into the hydration process:
+
+```js
+customElements.define(
+  'my-component',
+  class extends hyperElement {
+    // Called before events are replayed
+    // Return filtered/modified events array
+    onBeforeHydrate(bufferedEvents) {
+      console.log('Events captured:', bufferedEvents.length);
+      // Filter out old events
+      return bufferedEvents.filter((e) => Date.now() - e.timestamp < 5000);
+    }
+
+    // Called after all events have been replayed
+    onAfterHydrate() {
+      console.log('Hydration complete!');
+    }
+
+    render(Html) {
+      Html`<button>Click me</button>`;
+    }
+  }
+);
+```
+
+### BufferedEvent Structure
+
+Each captured event contains:
+
+```ts
+interface BufferedEvent {
+  type: string; // 'click', 'input', etc.
+  timestamp: number; // When event occurred
+  targetPath: string; // DOM path like 'DIV:0/BUTTON:1'
+  detail: object; // Event-specific properties
+}
+```
+
+### State Preservation
+
+The hydration system automatically preserves:
+
+- **Form values** - Input, textarea, select values via `input` events
+- **Checkbox/radio state** - Checked state captured and restored
+- **Scroll position** - Scroll positions within components
+
+---
+
+## SSR Configuration
+
+### Full Configuration Reference
+
+```js
+import { configureSSR } from 'hyper-element';
+
+configureSSR({
+  // Events to capture during SSR hydration
+  events: [
+    'click',
+    'dblclick',
+    'input',
+    'change',
+    'submit',
+    'keydown',
+    'keyup',
+    'keypress',
+    'focus',
+    'blur',
+    'focusin',
+    'focusout',
+    'touchstart',
+    'touchend',
+    'touchmove',
+    'touchcancel',
+  ],
+
+  // Show orange "SSR Capture Active" badge (development only)
+  devMode: false,
+});
+```
+
+---
+
+## Complete SSR Example
+
+**Server (Node.js):**
+
+```js
+import { renderElement } from 'hyper-element/ssr/server';
+
+const html = await renderElement('todo-list', {
+  attrs: { title: 'My Tasks' },
+  store: {
+    items: [
+      { id: 1, text: 'Learn SSR', done: false },
+      { id: 2, text: 'Build app', done: false },
+    ],
+  },
+  render: (Html, ctx) => Html`
+    <h1>${ctx.attrs.title}</h1>
+    <ul>
+      {+each ${ctx.store.items}}
+        <li data-id="{id}">{text}</li>
+      {-each}
+    </ul>
+  `,
+});
+
+// Serve full HTML page
+res.send(`
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="/hyper-element.min.js"></script>
+</head>
+<body>
+  ${html}
+  <script src="/app.js"></script>
+</body>
+</html>
+`);
+```
+
+**Client (app.js):**
+
+```js
+import hyperElement, { configureSSR } from 'hyper-element';
+
+// Optional: configure before components register
+configureSSR({ devMode: true });
+
+// Register the component - hydration happens automatically
+hyperElement('todo-list', {
+  onBeforeHydrate(events) {
+    console.log('Replaying', events.length, 'events');
+    return events;
+  },
+
+  onAfterHydrate() {
+    console.log('Todo list hydrated!');
+  },
+
+  render: (Html, ctx, store) => Html`
+    <h1>${ctx.attrs.title}</h1>
+    <ul>
+      {+each ${store.items}}
+        <li data-id="{id}">{text}</li>
+      {-each}
+    </ul>
+  `,
+});
+```
+
+---
+
 # Best Practices
 
 ## Always Use Html.wire for Lists
@@ -1121,6 +1612,54 @@ npm run format:fix
 
 ## Testing
 
+hyper-element uses a **two-phase test workflow** to ensure both source quality and build integrity:
+
+### Phase 1: Source Coverage
+
+```bash
+npm run test:src
+```
+
+- Loads `src/` directly via ES modules + import maps
+- Collects V8 coverage on source files
+- Generates HTML report at `coverage/index.html`
+- Runs SSR tests with coverage
+- **Requires 100% coverage** on all metrics
+
+### Phase 2: Bundle Verification
+
+```bash
+npm run test:bundle
+```
+
+- Loads built `build/hyperElement.min.js`
+- Verifies nothing broke during bundling
+- No coverage collected (just verification)
+
+### Full Test Suite
+
+```bash
+npm test
+```
+
+Runs both phases sequentially: source coverage first, then bundle verification.
+
+### Viewing Coverage Report
+
+After running tests, open the HTML coverage report:
+
+```bash
+open coverage/index.html
+```
+
+This shows:
+
+- File-by-file coverage breakdown
+- Line-by-line highlighting of covered/uncovered code
+- Statement, branch, and function metrics
+
+### Test Files
+
 Tests are located in `kitchensink/` and run via Playwright. See `kitchensink/kitchensink.spec.js` for the test suite.
 
 ## Contributing