@coherent.js/client 1.1.1 → 2.0.0-rc.0

package/README.md

@@ -2,14 +2,17 @@
 
 [![npm version](https://img.shields.io/npm/v/@coherent.js/client.svg)](https://www.npmjs.com/package/@coherent.js/client)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
-[![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![Node >= 22.12](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen)](https://nodejs.org)
 
-Client-side hydration and HMR utilities for Coherent.js applications.
+Client-side hydration, event delegation, routing and HMR for Coherent.js
+applications.
 
-- ESM-only, Node 20+
-- Progressive enhancement for server-rendered HTML
-- Lightweight event system and instance lifecycle helpers
-- Optional HMR support for dev workflows
+- ESM-only
+- Hydrates HTML rendered by `@coherent.js/core` with the same component
+- Document-level event delegation that survives re-renders
+- DOM patching on `setState()` / `rerender()`
+- Router with `:param` patterns and browser history
+- HMR client for development
 
 For a high-level overview and repository-wide instructions, see the root README: ../../README.md
 
@@ -19,103 +22,160 @@ For a high-level overview and repository-wide instructions, see the root README:
 pnpm add @coherent.js/client
 ```
 
-Requirements:
-- Node.js >= 20
-- ESM module system
+## Entry points
 
+| Import | Contents |
+| --- | --- |
+| `@coherent.js/client` | `hydrate`, event delegation, state serialization, mismatch detection, HMR client |
+| `@coherent.js/client/events` | `EventDelegation`, `eventDelegation`, `HandlerRegistry`, `handlerRegistry`, `wrapEvent` |
+| `@coherent.js/client/router` | `createRouter`, `router` |
+| `@coherent.js/client/hmr` | The HMR client API on its own (no side effects on import) |
 
-## Exports
+## Hydration
 
-Client-side hydration and HMR utilities
+Render on the server with `@coherent.js/core`, then hydrate the same component
+on the client:
 
-### Modular Imports (Tree-Shakable)
+```js
+import { hydrate } from '@coherent.js/client';
+
+function Counter({ count = 0 }) {
+  return {
+    div: {
+      className: 'counter',
+      children: [
+        { span: { text: `Count: ${count}` } },
+        {
+          button: {
+            text: '+1',
+            onClick: (event) => event.setState({ count: event.state.count + 1 })
+          }
+        }
+      ]
+    }
+  };
+}
+
+const app = hydrate(Counter, document.querySelector('.counter'), {
+  initialState: { count: 0 }   // defaults to the container's data-state attribute
+});
 
-- Hydration utilities: `@coherent.js/client`
-- Client router: `@coherent.js/client/router`
-- HMR support: `@coherent.js/client/hmr`
+app.setState({ count: 5 });  // patches the DOM
+app.getState();              // { count: 5 }
+app.rerender({ label: 'x' }); // re-render with extra props
+app.unmount();               // releases handlers; later setState() does nothing
+```
 
-### Example Usage
+`hydrate(component, container, options)` options:
 
-```javascript
-import { hydrateComponent } from '@coherent.js/client';
-import { createClientRouter } from '@coherent.js/client/router';
-```
+| Option | Default | |
+| --- | --- | --- |
+| `initialState` | `data-state` of the container | State to hydrate with |
+| `props` | `{}` | Extra props passed to the component |
+| `detectMismatch` | on in development (`process.env.NODE_ENV === 'development'`), or when `strict`/`onMismatch` is set | Compare the server DOM with the component's output |
+| `strict` | `false` | Throw on mismatch instead of warning |
+| `onMismatch` | — | Receive the mismatches instead of the console warning |
 
-> **Note**: All exports are tree-shakable. Import only what you need for optimal bundle size.
-## Quick start
+Hydrating the same container again replaces the previous hydration.
 
-The client package pairs with server-rendered HTML produced by `@coherent.js/core`.
+### Event handlers
 
-JavaScript (ESM):
-```js
-import { autoHydrate } from '@coherent.js/client';
+`on*` props become delegated handlers: `onClick` → `click`, `onDoubleClick` →
+`dblclick`, `onPointerDown` → `pointerdown`, and so on — any DOM event works.
+A handler receives a wrapped event:
 
-// Hydrate elements that were marked as hydratable on the server
-autoHydrate();
+```js
+onClick: (event) => {
+  event.preventDefault();       // works: listeners are not passive
+  event.stopPropagation();      // stops ancestor handlers
+  event.originalEvent;          // the native event
+  event.target;                 // the element carrying this handler
+  event.state;                  // component state when the event fired
+  event.setState({ open: true });
+  event.props;                  // props the component rendered with
+}
 ```
 
-TypeScript:
-```ts
-import { autoHydrate } from '@coherent.js/client';
+Handlers run from the target outwards through every ancestor that has one,
+like native bubbling. Non-bubbling events (`mouseenter`, `load`, ...) only run
+the handler on their own element. Scroll-blocking events (`touchstart`,
+`touchmove`, `wheel`, `scroll`) are delegated passively, so `preventDefault()`
+has no effect on them.
 
-document.addEventListener('DOMContentLoaded', () => {
-  autoHydrate();
-});
-```
+### Re-rendering
 
-### Attaching custom handlers
+`setState()` and `rerender()` diff the previous output against the new one:
+children are added, removed or replaced (matched by `key` when every sibling
+has one), attributes follow the server's rules (`style` objects, function
+values, `true`/`false`), `html` content is updated, and `value`, `checked` and
+`selected` are written to the element's properties too, so they are
+controlled by state.
 
-The client exposes an event registry you can populate during hydration.
+### State serialization and mismatches
 
 ```js
-import { registerEventHandler } from '@coherent.js/client';
+import { serializeState, extractState, detectMismatch, reportMismatches } from '@coherent.js/client';
 
-registerEventHandler('increment', (el, evt, ctx) => {
-  // custom logic using element, DOM event, and context
-});
+serializeState({ count: 1 });            // base64 string for data-state (null if empty)
+extractState(element);                   // parsed data-state, or null
+reportMismatches(detectMismatch(element, Counter({ count: 1 })), { componentName: 'Counter' });
 ```
 
-TypeScript:
-```ts
-import { registerEventHandler } from '@coherent.js/client';
+## Router
+
+```js
+import { createRouter } from '@coherent.js/client/router';
 
-type Ctx = { state?: unknown };
+const router = createRouter({ base: '/app' });   // or { mode: 'hash' }
 
-registerEventHandler('increment', (el: HTMLElement, evt: Event, ctx: Ctx) => {
-  console.log('clicked', el, ctx);
+router.addRoute('/', { component: () => Home });  // a function is a loader
+router.addRoute('/users/:id', {
+  component: () => import('./UserPage.js'),      // lazy: resolves to the module
+  beforeEnter: (to) => to.params.id !== 'blocked' // false cancels
 });
+
+await router.start();          // resolve the current URL, follow back/forward,
+                               // intercept clicks on links to registered routes
+await router.push('/users/42?tab=posts');
+router.getCurrentRoute();      // { path: '/users/42', params: { id: '42' }, query: { tab: 'posts' }, component, ... }
+router.back();
+router.stop();
 ```
 
-## Notes on testing
+The router resolves routes and tracks the current one; rendering the matched
+component is up to the application. A function `component` is called once,
+without arguments, and its awaited result becomes the route's component, so
+wrap component functions: `component: () => Home`. The last navigation wins: a slow lazy
+route that resolves after a later `push()` is dropped.
 
-When testing client-side utilities in Node, provide light DOM shims (see repository tests under `packages/client/test/`). Example:
+## HMR
 
 ```js
-import { vi } from 'vitest';
+import { hmrClient, createHotContext } from '@coherent.js/client';
+
+hmrClient.initialize();  // connects to the dev server's WebSocket
 
-global.window = { __coherentEventRegistry: {}, addEventListener: vi.fn() };
-global.document = { querySelector: vi.fn(), querySelectorAll: vi.fn(() => []) };
+const hot = createHotContext(import.meta.url);
+hot.accept((newModule) => { /* apply the update */ });
+hot.dispose((data) => { data.saved = currentState; });
 ```
 
-## Development
+A changed module without `accept()` reloads the page. Form values (including
+radio groups) and scroll positions are preserved across updates; timers,
+listeners and fetches created through `cleanupTracker.createContext(id)` are
+released when the module is replaced.
 
-Run tests for this package:
-```bash
-pnpm --filter @coherent.js/client run test
-```
+## Notes on testing
 
-Watch mode:
-```bash
-pnpm --filter @coherent.js/client run test:watch
-```
+The package's own tests run in Node against a small DOM (see
+`packages/client/test/helpers/dom.js`): it parses server HTML, dispatches
+events with capture and bubbling, and models form properties.
 
-Type check:
-```bash
-pnpm --filter @coherent.js/client run typecheck
-```
+## Development
 
-Build:
 ```bash
+pnpm --filter @coherent.js/client run test
+pnpm --filter @coherent.js/client run typecheck
 pnpm --filter @coherent.js/client run build
 ```