@coderegtech/jsonify-ws 1.0.5

package/README.md

@@ -0,0 +1,226 @@
+# jsonify-ws
+
+Real-time JSON synchronization over WebSocket using Socket.IO. Provides React hooks for the client, a `data-copy` attribute system for inline content editing, and a ready-to-run sync server.
+
+## Install
+
+```bash
+npm install jsonify-ws socket.io-client
+```
+
+## Environment Variable
+
+Set `WSL_URL` to your WebSocket server URL:
+
+```env
+# .env (Vite)
+VITE_WSL_URL=http://localhost:4000
+
+# .env (CRA / Next.js)
+REACT_APP_WSL_URL=http://localhost:4000
+
+# Or set directly
+WSL_URL=http://localhost:4000
+```
+
+> If not set, defaults to `http://localhost:4000`.
+
+## Quick Start
+
+### 1. Start the server
+
+```bash
+# Option A: CLI
+npx jsonify-ws-server
+
+# Option B: Programmatic
+```
+
+```ts
+import { createJsonifyServer } from "jsonify-ws/server";
+
+createJsonifyServer(4000); // port, cors origin
+```
+
+### 2. Use the `useJsonify()` hook
+
+```tsx
+import { useJsonify } from "jsonify-ws";
+
+function App() {
+  const j = useJsonify({
+    autoConnect: true,
+    initialData: { home: { title: "Hello World", subtitle: "Edit me!" } },
+  });
+
+  return (
+    <div>
+      <p>Status: {j.status}</p>
+      <button onClick={j.toggleEditMode}>
+        {j.editMode ? "✅ Editing" : "✏️ Edit Mode"}
+      </button>
+      <h1 data-copy="home.title">{j.data.home?.title}</h1>
+      <p data-copy="home.subtitle">{j.data.home?.subtitle}</p>
+    </div>
+  );
+}
+```
+
+## API
+
+### `useJsonify(options?)`
+
+The primary hook — combines WebSocket sync with `data-copy` attribute scanning and contentEditable.
+
+| Option                | Type                          | Default                | Description                              |
+| --------------------- | ----------------------------- | ---------------------- | ---------------------------------------- |
+| `url`                 | `string`                      | `WSL_URL` env          | WebSocket server URL                     |
+| `autoConnect`         | `boolean`                     | `false`                | Connect on mount                         |
+| `initialData`         | `Record<string, JsonValue>`   | `{}`                   | Initial JSON state                       |
+| `reconnectionDelay`   | `number`                      | `3000`                 | Reconnection delay (ms)                  |
+| `onSync`              | `(data) => void`              | —                      | Callback on remote data received         |
+| `onStatusChange`      | `(status) => void`            | —                      | Callback on connection status change     |
+| `onError`             | `(error) => void`             | —                      | Callback on connection error             |
+| `targetDocument`      | `Document`                    | `window.document`      | Target document for data-copy scan       |
+| `injectToggle`        | `boolean`                     | `true`                 | Auto-inject floating edit button         |
+| `injectStatusIndicator`| `boolean`                    | `false`                | Auto-inject WS status indicator (bottom-left) |
+
+**Returns:**
+
+| Property         | Type                             | Description                    |
+| ---------------- | -------------------------------- | ------------------------------ |
+| `data`           | `Record<string, JsonValue>`      | Current synced JSON data       |
+| `setData`        | `(data) => void`                 | Update all data (broadcasts)   |
+| `setPath`        | `(path, value) => void`          | Update a single dot-path       |
+| `status`         | `WsStatus`                       | Connection status              |
+| `connect`        | `(url?) => void`                 | Connect to server              |
+| `disconnect`     | `() => void`                     | Disconnect from server         |
+| `url`            | `string`                         | Resolved WebSocket URL         |
+| `editMode`       | `boolean`                        | Whether edit mode is active    |
+| `toggleEditMode` | `() => void`                     | Toggle edit mode on/off        |
+| `setEditMode`    | `(active) => void`               | Set edit mode explicitly       |
+| `elements`       | `DataCopyElement[]`              | Scanned data-copy elements     |
+| `rescan`         | `() => void`                     | Re-scan for data-copy elements |
+
+---
+
+### `useJsonifyWs(options?)`
+
+Lower-level hook — WebSocket sync only (no data-copy support).
+
+| Option             | Type                          | Default                | Description                          |
+| ------------------ | ----------------------------- | ---------------------- | ------------------------------------ |
+| `url`              | `string`                      | `WSL_URL` env          | WebSocket server URL                 |
+| `autoConnect`      | `boolean`                     | `false`                | Connect on mount                     |
+| `initialData`      | `JsonValue`                   | `{}`                   | Initial JSON state                   |
+| `reconnectionDelay`| `number`                      | `3000`                 | Reconnection delay (ms)              |
+| `onSync`           | `(data: JsonValue) => void`   | —                      | Callback on remote data received     |
+| `onStatusChange`   | `(status: WsStatus) => void`  | —                      | Callback on connection status change |
+| `onError`          | `(error: Error) => void`      | —                      | Callback on connection error         |
+
+**Returns:**
+
+| Property     | Type                          | Description                    |
+| ------------ | ----------------------------- | ------------------------------ |
+| `data`       | `JsonValue`                   | Current synced JSON data       |
+| `setData`    | `(data: JsonValue) => void`   | Update data (broadcasts)       |
+| `status`     | `WsStatus`                    | `"disconnected" \| "connecting" \| "connected"` |
+| `connect`    | `(url?: string) => void`      | Connect to server              |
+| `disconnect` | `() => void`                  | Disconnect from server         |
+| `url`        | `string`                      | Resolved WebSocket URL         |
+
+---
+
+### `createJsonifyServer(port?, corsOrigin?)`
+
+Creates a Socket.IO server that broadcasts JSON updates between clients.
+
+```ts
+import { createJsonifyServer } from "jsonify-ws/server";
+
+const io = createJsonifyServer(4000, "*");
+```
+
+---
+
+## `data-copy` Attribute System
+
+Add `data-copy` attributes to any HTML element to map it to a JSON path:
+
+```html
+<h1 data-copy="home.hero.title">Welcome</h1>
+<p data-copy="home.hero.subtitle">This is editable</p>
+<span data-copy="footer.copyright">© 2026</span>
+```
+
+When **Edit Mode** is activated:
+1. Elements with `data-copy` get a dashed outline and become `contentEditable`
+2. Text changes are synced to the JSON data in real-time
+3. JSON changes (from other clients) update the element text automatically
+4. A floating "✏️ Edit Mode" button appears (configurable via `injectToggle`)
+
+### WebSocket Status Indicator
+
+Enable `injectStatusIndicator` to show a real-time connection status badge:
+
+```tsx
+const j = useJsonify({
+  autoConnect: true,
+  injectStatusIndicator: true, // Shows status in bottom-left corner
+});
+```
+
+The indicator displays:
+- 🔴 **Red** — Disconnected
+- 🟡 **Yellow (pulsing)** — Connecting
+- 🟢 **Green** — Connected
+
+### Standalone utilities
+
+```ts
+import {
+  scanDataCopyElements,
+  enableEditMode,
+  disableEditMode,
+  syncElementsFromData,
+  getByPath,
+  setByPath,
+  injectEditToggle,
+  injectWsStatusIndicator,
+} from "jsonify-ws";
+
+// Scan for elements
+const elements = scanDataCopyElements(document);
+
+// Enable editing
+enableEditMode(elements);
+
+// Sync JSON data to elements
+syncElementsFromData(elements, { home: { title: "Updated!" } });
+
+// Path utilities
+const val = getByPath({ a: { b: "hello" } }, "a.b"); // "hello"
+const updated = setByPath({ a: { b: "hello" } }, "a.b", "world"); // { a: { b: "world" } }
+
+// Inject floating edit toggle button
+const cleanupToggle = injectEditToggle(document, (active) => {
+  console.log("Edit mode:", active);
+});
+
+// Inject WebSocket status indicator
+const { cleanup, updateStatus } = injectWsStatusIndicator(document);
+updateStatus("connected"); // "disconnected" | "connecting" | "connected"
+```
+
+## How It Works
+
+1. Client connects and pushes its current JSON state
+2. Server stores latest state and syncs to all other clients
+3. Any `setData()` or `setPath()` call broadcasts the update to all peers
+4. New clients receive the latest state on connect
+5. `data-copy` elements are scanned and mapped to JSON paths
+6. In edit mode, contentEditable changes are captured and synced in real-time
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,211 @@
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type WsStatus = "disconnected" | "connecting" | "connected";
+interface JsonifyWsOptions {
+    /**
+     * WebSocket server URL. Defaults to WSL_URL env variable.
+     * Falls back to "http://localhost:4000" if not set.
+     */
+    url?: string;
+    /**
+     * Auto-connect on mount. Default: false
+     */
+    autoConnect?: boolean;
+    /**
+     * Initial JSON data to sync. Default: {}
+     */
+    initialData?: JsonValue;
+    /**
+     * Reconnection delay in ms. Default: 3000
+     */
+    reconnectionDelay?: number;
+    /**
+     * Callback fired when remote data is received.
+     */
+    onSync?: (data: JsonValue) => void;
+    /**
+     * Callback fired when connection status changes.
+     */
+    onStatusChange?: (status: WsStatus) => void;
+    /**
+     * Callback fired on connection error.
+     */
+    onError?: (error: Error) => void;
+}
+interface JsonifyWsReturn {
+    /** Current JSON data state */
+    data: JsonValue;
+    /** Update the JSON data (will broadcast to peers) */
+    setData: (data: JsonValue) => void;
+    /** Current connection status */
+    status: WsStatus;
+    /** Connect to the WebSocket server */
+    connect: (url?: string) => void;
+    /** Disconnect from the WebSocket server */
+    disconnect: () => void;
+    /** The resolved WebSocket URL */
+    url: string;
+}
+
+/**
+ * React hook for real-time JSON synchronization over WebSocket.
+ *
+ * @example
+ * ```tsx
+ * import { useJsonifyWs } from "jsonify-ws";
+ *
+ * function App() {
+ *   const { data, setData, status, connect, disconnect } = useJsonifyWs({
+ *     autoConnect: true,
+ *     initialData: { hello: "world" },
+ *   });
+ *
+ *   return <pre>{JSON.stringify(data, null, 2)}</pre>;
+ * }
+ * ```
+ */
+declare function useJsonifyWs(options?: JsonifyWsOptions): JsonifyWsReturn;
+
+/**
+ * data-copy attribute utilities.
+ *
+ * Scans a document (or iframe) for elements with `data-copy="path.to.key"`
+ * and enables contentEditable on them, syncing edits back to the JSON state.
+ */
+
+interface DataCopyElement {
+    element: HTMLElement;
+    path: string;
+    originalValue: string;
+}
+/**
+ * Get a value from a nested object by dot-path.
+ * e.g. getByPath({ home: { title: "Hi" } }, "home.title") => "Hi"
+ */
+declare function getByPath(obj: Record<string, JsonValue>, path: string): JsonValue | undefined;
+/**
+ * Set a value in a nested object by dot-path (immutable — returns new object).
+ */
+declare function setByPath(obj: Record<string, JsonValue>, path: string, value: JsonValue): Record<string, JsonValue>;
+/**
+ * Scan a document for elements with `data-copy` attribute.
+ */
+declare function scanDataCopyElements(doc: Document): DataCopyElement[];
+/**
+ * Apply contentEditable styling to data-copy elements.
+ */
+declare function enableEditMode(elements: DataCopyElement[]): void;
+/**
+ * Remove contentEditable styling from data-copy elements.
+ */
+declare function disableEditMode(elements: DataCopyElement[]): void;
+/**
+ * Update element text content from JSON data.
+ */
+declare function syncElementsFromData(elements: DataCopyElement[], data: Record<string, JsonValue>): void;
+/**
+ * Inject a floating "Edit Mode" toggle button into the page.
+ * Returns a cleanup function.
+ */
+declare function injectEditToggle(doc: Document, onToggle: (active: boolean) => void): () => void;
+
+interface UseJsonifyOptions {
+    /**
+     * WebSocket server URL. Defaults to WSL_URL env variable.
+     * Falls back to "http://localhost:4000" if not set.
+     */
+    url?: string;
+    /**
+     * Auto-connect on mount. Default: false
+     */
+    autoConnect?: boolean;
+    /**
+     * Initial JSON data. Default: {}
+     */
+    initialData?: Record<string, JsonValue>;
+    /**
+     * Reconnection delay in ms. Default: 3000
+     */
+    reconnectionDelay?: number;
+    /**
+     * Callback fired when remote data is received.
+     */
+    onSync?: (data: Record<string, JsonValue>) => void;
+    /**
+     * Callback fired when connection status changes.
+     */
+    onStatusChange?: (status: WsStatus) => void;
+    /**
+     * Callback fired on connection error.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Target document for data-copy scanning.
+     * Defaults to window.document.
+     * Pass an iframe's contentDocument to scan an iframe.
+     */
+    targetDocument?: Document;
+    /**
+     * Auto-inject the floating edit toggle button. Default: true
+     */
+    injectToggle?: boolean;
+    /**
+     * Auto-inject the WebSocket connection status indicator. Default: false
+     */
+    injectStatusIndicator?: boolean;
+}
+interface UseJsonifyReturn {
+    /** Current JSON data state */
+    data: Record<string, JsonValue>;
+    /** Update the JSON data (will broadcast to peers) */
+    setData: (data: Record<string, JsonValue>) => void;
+    /** Update a single path in the data */
+    setPath: (path: string, value: JsonValue) => void;
+    /** Current connection status */
+    status: WsStatus;
+    /** Connect to the WebSocket server */
+    connect: (url?: string) => void;
+    /** Disconnect from the WebSocket server */
+    disconnect: () => void;
+    /** The resolved WebSocket URL */
+    url: string;
+    /** Whether edit mode is active */
+    editMode: boolean;
+    /** Toggle edit mode on/off */
+    toggleEditMode: () => void;
+    /** Set edit mode explicitly */
+    setEditMode: (active: boolean) => void;
+    /** Scanned data-copy elements */
+    elements: DataCopyElement[];
+    /** Re-scan the document for data-copy elements */
+    rescan: () => void;
+}
+/**
+ * React hook for real-time JSON synchronization with data-copy attribute support.
+ *
+ * @example
+ * ```tsx
+ * import { useJsonify } from "jsonify-ws";
+ *
+ * function App() {
+ *   const j = useJsonify({
+ *     autoConnect: true,
+ *     initialData: { home: { title: "Hello" } },
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <p>Status: {j.status}</p>
+ *       <button onClick={j.toggleEditMode}>
+ *         {j.editMode ? "Stop Editing" : "Edit Mode"}
+ *       </button>
+ *       <h1 data-copy="home.title">{j.data.home?.title}</h1>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useJsonify(options?: UseJsonifyOptions): UseJsonifyReturn;
+
+export { type DataCopyElement, type JsonValue, type JsonifyWsOptions, type JsonifyWsReturn, type UseJsonifyOptions, type UseJsonifyReturn, type WsStatus, disableEditMode, enableEditMode, getByPath, injectEditToggle, scanDataCopyElements, setByPath, syncElementsFromData, useJsonify, useJsonifyWs };

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type WsStatus = "disconnected" | "connecting" | "connected";
+interface JsonifyWsOptions {
+    /**
+     * WebSocket server URL. Defaults to WSL_URL env variable.
+     * Falls back to "http://localhost:4000" if not set.
+     */
+    url?: string;
+    /**
+     * Auto-connect on mount. Default: false
+     */
+    autoConnect?: boolean;
+    /**
+     * Initial JSON data to sync. Default: {}
+     */
+    initialData?: JsonValue;
+    /**
+     * Reconnection delay in ms. Default: 3000
+     */
+    reconnectionDelay?: number;
+    /**
+     * Callback fired when remote data is received.
+     */
+    onSync?: (data: JsonValue) => void;
+    /**
+     * Callback fired when connection status changes.
+     */
+    onStatusChange?: (status: WsStatus) => void;
+    /**
+     * Callback fired on connection error.
+     */
+    onError?: (error: Error) => void;
+}
+interface JsonifyWsReturn {
+    /** Current JSON data state */
+    data: JsonValue;
+    /** Update the JSON data (will broadcast to peers) */
+    setData: (data: JsonValue) => void;
+    /** Current connection status */
+    status: WsStatus;
+    /** Connect to the WebSocket server */
+    connect: (url?: string) => void;
+    /** Disconnect from the WebSocket server */
+    disconnect: () => void;
+    /** The resolved WebSocket URL */
+    url: string;
+}
+
+/**
+ * React hook for real-time JSON synchronization over WebSocket.
+ *
+ * @example
+ * ```tsx
+ * import { useJsonifyWs } from "jsonify-ws";
+ *
+ * function App() {
+ *   const { data, setData, status, connect, disconnect } = useJsonifyWs({
+ *     autoConnect: true,
+ *     initialData: { hello: "world" },
+ *   });
+ *
+ *   return <pre>{JSON.stringify(data, null, 2)}</pre>;
+ * }
+ * ```
+ */
+declare function useJsonifyWs(options?: JsonifyWsOptions): JsonifyWsReturn;
+
+/**
+ * data-copy attribute utilities.
+ *
+ * Scans a document (or iframe) for elements with `data-copy="path.to.key"`
+ * and enables contentEditable on them, syncing edits back to the JSON state.
+ */
+
+interface DataCopyElement {
+    element: HTMLElement;
+    path: string;
+    originalValue: string;
+}
+/**
+ * Get a value from a nested object by dot-path.
+ * e.g. getByPath({ home: { title: "Hi" } }, "home.title") => "Hi"
+ */
+declare function getByPath(obj: Record<string, JsonValue>, path: string): JsonValue | undefined;
+/**
+ * Set a value in a nested object by dot-path (immutable — returns new object).
+ */
+declare function setByPath(obj: Record<string, JsonValue>, path: string, value: JsonValue): Record<string, JsonValue>;
+/**
+ * Scan a document for elements with `data-copy` attribute.
+ */
+declare function scanDataCopyElements(doc: Document): DataCopyElement[];
+/**
+ * Apply contentEditable styling to data-copy elements.
+ */
+declare function enableEditMode(elements: DataCopyElement[]): void;
+/**
+ * Remove contentEditable styling from data-copy elements.
+ */
+declare function disableEditMode(elements: DataCopyElement[]): void;
+/**
+ * Update element text content from JSON data.
+ */
+declare function syncElementsFromData(elements: DataCopyElement[], data: Record<string, JsonValue>): void;
+/**
+ * Inject a floating "Edit Mode" toggle button into the page.
+ * Returns a cleanup function.
+ */
+declare function injectEditToggle(doc: Document, onToggle: (active: boolean) => void): () => void;
+
+interface UseJsonifyOptions {
+    /**
+     * WebSocket server URL. Defaults to WSL_URL env variable.
+     * Falls back to "http://localhost:4000" if not set.
+     */
+    url?: string;
+    /**
+     * Auto-connect on mount. Default: false
+     */
+    autoConnect?: boolean;
+    /**
+     * Initial JSON data. Default: {}
+     */
+    initialData?: Record<string, JsonValue>;
+    /**
+     * Reconnection delay in ms. Default: 3000
+     */
+    reconnectionDelay?: number;
+    /**
+     * Callback fired when remote data is received.
+     */
+    onSync?: (data: Record<string, JsonValue>) => void;
+    /**
+     * Callback fired when connection status changes.
+     */
+    onStatusChange?: (status: WsStatus) => void;
+    /**
+     * Callback fired on connection error.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Target document for data-copy scanning.
+     * Defaults to window.document.
+     * Pass an iframe's contentDocument to scan an iframe.
+     */
+    targetDocument?: Document;
+    /**
+     * Auto-inject the floating edit toggle button. Default: true
+     */
+    injectToggle?: boolean;
+    /**
+     * Auto-inject the WebSocket connection status indicator. Default: false
+     */
+    injectStatusIndicator?: boolean;
+}
+interface UseJsonifyReturn {
+    /** Current JSON data state */
+    data: Record<string, JsonValue>;
+    /** Update the JSON data (will broadcast to peers) */
+    setData: (data: Record<string, JsonValue>) => void;
+    /** Update a single path in the data */
+    setPath: (path: string, value: JsonValue) => void;
+    /** Current connection status */
+    status: WsStatus;
+    /** Connect to the WebSocket server */
+    connect: (url?: string) => void;
+    /** Disconnect from the WebSocket server */
+    disconnect: () => void;
+    /** The resolved WebSocket URL */
+    url: string;
+    /** Whether edit mode is active */
+    editMode: boolean;
+    /** Toggle edit mode on/off */
+    toggleEditMode: () => void;
+    /** Set edit mode explicitly */
+    setEditMode: (active: boolean) => void;
+    /** Scanned data-copy elements */
+    elements: DataCopyElement[];
+    /** Re-scan the document for data-copy elements */
+    rescan: () => void;
+}
+/**
+ * React hook for real-time JSON synchronization with data-copy attribute support.
+ *
+ * @example
+ * ```tsx
+ * import { useJsonify } from "jsonify-ws";
+ *
+ * function App() {
+ *   const j = useJsonify({
+ *     autoConnect: true,
+ *     initialData: { home: { title: "Hello" } },
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <p>Status: {j.status}</p>
+ *       <button onClick={j.toggleEditMode}>
+ *         {j.editMode ? "Stop Editing" : "Edit Mode"}
+ *       </button>
+ *       <h1 data-copy="home.title">{j.data.home?.title}</h1>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useJsonify(options?: UseJsonifyOptions): UseJsonifyReturn;
+
+export { type DataCopyElement, type JsonValue, type JsonifyWsOptions, type JsonifyWsReturn, type UseJsonifyOptions, type UseJsonifyReturn, type WsStatus, disableEditMode, enableEditMode, getByPath, injectEditToggle, scanDataCopyElements, setByPath, syncElementsFromData, useJsonify, useJsonifyWs };