@coherent.js/client 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Drouvin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @coherent.js/client
+
+[![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)
+
+Client-side hydration and HMR utilities 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
+
+For a high-level overview and repository-wide instructions, see the root README: ../../README.md
+
+## Installation
+
+```bash
+pnpm add @coherent.js/client
+```
+
+Requirements:
+- Node.js >= 20
+- ESM module system
+
+## Quick start
+
+The client package pairs with server-rendered HTML produced by `@coherent.js/core`.
+
+JavaScript (ESM):
+```js
+import { autoHydrate } from '@coherent.js/client';
+
+// Hydrate elements that were marked as hydratable on the server
+autoHydrate();
+```
+
+TypeScript:
+```ts
+import { autoHydrate } from '@coherent.js/client';
+
+document.addEventListener('DOMContentLoaded', () => {
+  autoHydrate();
+});
+```
+
+### Attaching custom handlers
+
+The client exposes an event registry you can populate during hydration.
+
+```js
+import { registerEventHandler } from '@coherent.js/client';
+
+registerEventHandler('increment', (el, evt, ctx) => {
+  // custom logic using element, DOM event, and context
+});
+```
+
+TypeScript:
+```ts
+import { registerEventHandler } from '@coherent.js/client';
+
+type Ctx = { state?: unknown };
+
+registerEventHandler('increment', (el: HTMLElement, evt: Event, ctx: Ctx) => {
+  console.log('clicked', el, ctx);
+});
+```
+
+## Notes on testing
+
+When testing client-side utilities in Node, provide light DOM shims (see repository tests under `packages/client/test/`). Example:
+
+```js
+import { vi } from 'vitest';
+
+global.window = { __coherentEventRegistry: {}, addEventListener: vi.fn() };
+global.document = { querySelector: vi.fn(), querySelectorAll: vi.fn(() => []) };
+```
+
+## Development
+
+Run tests for this package:
+```bash
+pnpm --filter @coherent.js/client run test
+```
+
+Watch mode:
+```bash
+pnpm --filter @coherent.js/client run test:watch
+```
+
+Type check:
+```bash
+pnpm --filter @coherent.js/client run typecheck
+```
+
+Build:
+```bash
+pnpm --filter @coherent.js/client run build
+```
+
+## License
+
+MIT © Coherent.js Team

package/dist/client/hmr.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=hmr.d.ts.map

package/dist/client/hmr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmr.d.ts","sourceRoot":"","sources":["../../../../src/client/hmr.js"],"names":[],"mappings":""}

package/dist/client/hmr.js

@@ -0,0 +1,107 @@
+"use strict";
+/*
+ * Coherent.js HMR Client
+ * Auto-connects to the dev server and applies updates.
+ */
+(function initHMR() {
+    if (typeof window === 'undefined')
+        return;
+    if (window.__coherent_hmr_initialized)
+        return;
+    window.__coherent_hmr_initialized = true;
+    const log = (...args) => console.log('[Coherent HMR]', ...args);
+    const warn = (...args) => console.warn('[Coherent HMR]', ...args);
+    const _error = (...args) => console.error('[Coherent HMR]', ...args);
+    let hadDisconnect = false;
+    function connect() {
+        try {
+            const protocol = location.protocol === 'https:' ? 'wss' : 'ws';
+            const wsUrl = `${protocol}://${location.host}`;
+            const ws = new WebSocket(wsUrl);
+            ws.addEventListener('open', () => {
+                log('connected');
+                ws.send(JSON.stringify({ type: 'connected' }));
+                // If the server was restarted, ensure the page HTML is refreshed automatically
+                if (hadDisconnect) {
+                    log('reconnected, reloading page');
+                    setTimeout(() => location.reload(), 200);
+                    return;
+                }
+            });
+            ws.addEventListener('close', () => {
+                hadDisconnect = true;
+                warn('disconnected, retrying in 1s...');
+                setTimeout(connect, 1000);
+            });
+            ws.addEventListener('error', (e) => {
+                error('socket error', e);
+                try {
+                    ws.close();
+                }
+                catch { }
+            });
+            ws.addEventListener('message', async (evt) => {
+                let data;
+                try {
+                    data = JSON.parse(evt.data);
+                }
+                catch {
+                    return;
+                }
+                log('message', data.type, data.filePath || data.webPath || '');
+                switch (data.type) {
+                    case 'connected':
+                        break;
+                    case 'hmr-full-reload':
+                    case 'reload':
+                        warn('server requested full reload');
+                        location.reload();
+                        return;
+                    case 'preview-update':
+                        // No-op here; dashboard uses this for live preview panes
+                        break;
+                    case 'hmr-component-update':
+                    case 'hmr-update':
+                        await handleUpdate(data);
+                        break;
+                    default:
+                        break;
+                }
+            });
+        }
+        catch {
+            // Ignore errors in non-browser environments
+        }
+    }
+    async function handleUpdate(msg) {
+        const filePath = msg.webPath || msg.filePath || '';
+        const ts = Date.now();
+        // Try to re-import changed module to refresh side effects/registrations
+        try {
+            // Prefer absolute path from dev-server, otherwise attempt as-is
+            const importPath = filePath.startsWith('/') ? filePath : `/${filePath}`;
+            await import(`${importPath}?t=${ts}`);
+            log('updated', msg.updateType || 'module', filePath);
+        }
+        catch (err) {
+            warn('module re-import failed, attempting soft hydrate', filePath, err);
+        }
+        // Attempt to re-hydrate if available
+        try {
+            const { autoHydrate } = await import('/src/client/hydration.js');
+            // If examples register a component registry on window, prefer targeted hydrate
+            if (window.componentRegistry) {
+                autoHydrate(window.componentRegistry);
+            }
+            else {
+                autoHydrate();
+            }
+        }
+        catch {
+            warn('autoHydrate failed; falling back to full reload');
+            location.reload();
+        }
+    }
+    connect();
+})();
+//# sourceMappingURL=hmr.js.map

package/dist/client/hmr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmr.js","sourceRoot":"","sources":["../../../../src/client/hmr.js"],"names":[],"mappings":"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"}

package/dist/client/hydration.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Register an event handler for later use
+ * @param {string} id - Unique identifier for the event handler
+ * @param {Function} handler - The event handler function
+ */
+export function registerEventHandler(id: string, handler: Function): void;
+/**
+ * Hydrate a DOM element with a Coherent component
+ *
+ * @param {HTMLElement} element - The DOM element to hydrate
+ * @param {Function} component - The Coherent component function
+ * @param {Object} props - The props to pass to the component
+ * @param {Object} options - Hydration options
+ * @returns {Object} The hydrated component instance
+ */
+export function hydrate(element: HTMLElement, component: Function, props?: Object, options?: Object): Object;
+/**
+ * Hydrate multiple elements with their corresponding components
+ *
+ * @param {Array} elements - Array of DOM elements to hydrate
+ * @param {Array} components - Array of Coherent component functions
+ * @param {Array} propsArray - Array of props for each component
+ * @returns {Array} Array of hydrated component instances
+ */
+export function hydrateAll(elements: any[], components: any[], propsArray?: any[]): any[];
+/**
+ * Find and hydrate elements by CSS selector
+ *
+ * @param {string} selector - CSS selector to find elements
+ * @param {Function} component - The Coherent component function
+ * @param {Object} props - The props to pass to the component
+ * @returns {Array} Array of hydrated component instances
+ */
+export function hydrateBySelector(selector: string, component: Function, props?: Object): any[];
+/**
+ * Enable client-side interactivity for event handlers
+ *
+ * @param {HTMLElement} rootElement - The root element to enable events on
+ */
+export function enableClientEvents(rootElement?: HTMLElement): void;
+/**
+ * Create a hydratable component
+ *
+ * @param {Function} component - The Coherent component function
+ * @param {Object} options - Hydration options
+ * @returns {Function} A component that can be hydrated
+ */
+export function makeHydratable(component: Function, options?: Object): Function;
+/**
+ * Auto-hydrate all components on page load
+ *
+ * @param {Object} componentRegistry - Registry of component functions
+ */
+export function autoHydrate(componentRegistry?: Object): void;
+//# sourceMappingURL=hydration.d.ts.map

package/dist/client/hydration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration.d.ts","sourceRoot":"","sources":["../../../../src/client/hydration.js"],"names":[],"mappings":"AAomBA;;;;GAIG;AACH,yCAHW,MAAM,2BAKhB;AA/hBD;;;;;;;;GAQG;AACH,iCANW,WAAW,+BAEX,MAAM,YACN,MAAM,GACJ,MAAM,CA4gBlB;AA44BD;;;;;;;GAOG;AACH,0FAUC;AAED;;;;;;;GAOG;AACH,4CALW,MAAM,+BAEN,MAAM,SAUhB;AAED;;;;GAIG;AACH,iDAFW,WAAW,QAUrB;AAED;;;;;;GAMG;AACH,8DAHW,MAAM,YAsIhB;AAED;;;;GAIG;AACH,gDAFW,MAAM,QAgFhB"}