legend-state-dev-tools 0.0.2 → 0.0.4

package/README.md

@@ -1,142 +0,0 @@
-# legend-state-dev-tools
-
-> **Early-stage project** -- I discovered Legend State recently and chose it for a project I was working on. It had everything I needed from a state manager, but I couldn't live without dev tools, so I built this. It appears to work, but it hasn't been thoroughly tested yet -- consider it a proof of concept for now.
-
-[![npm version](https://img.shields.io/npm/v/legend-state-dev-tools)](https://www.npmjs.com/package/legend-state-dev-tools)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
-
-Visual dev tools for Legend State v3 -- inspect and edit observable state in real time.
-
-<!-- screenshot -->
-
-## Features
-
-- Real-time state tree view powered by `json-edit-react`
-- Inline editing of observable values
-- Multiple color themes (dark and light variants)
-- Draggable toolbar
-- Configurable panel positioning (left or right)
-- Read-only mode
-- Clean teardown via `destroy()`
-
-## Installation
-
-```bash
-npm install legend-state-dev-tools
-```
-
-```bash
-pnpm add legend-state-dev-tools
-```
-
-```bash
-yarn add legend-state-dev-tools
-```
-
-### Peer dependencies
-
-| Package | Version |
-|---------|---------|
-| `@legendapp/state` | `>= 3.0.0-beta.0` |
-| `react` | `>= 18.0.0` |
-| `react-dom` | `>= 18.0.0` |
-
-## Quick Start
-
-```ts
-import { observable } from '@legendapp/state';
-import { init } from 'legend-state-dev-tools';
-import 'legend-state-dev-tools/dist/styles.css';
-
-const state$ = observable({ count: 0, user: { name: 'Alice' } });
-
-const devtools = init(state$);
-
-// Later, to clean up:
-// devtools.destroy();
-```
-
-## API Reference
-
-### `init(observable$, options?)`
-
-Mounts the dev tools UI and returns a handle for cleanup.
-
-**Parameters**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `observable$` | `ObservableParam<any>` | The Legend State observable to inspect |
-| `options` | `DevToolsOptions` | Optional configuration (see below) |
-
-**Options**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | `boolean` | `true` | Enable or disable the dev tools |
-| `readOnly` | `boolean` | `false` | Prevent editing of state values |
-| `theme` | `string` | `'githubDark'` | Color theme for the JSON editor |
-| `rootName` | `string` | `'state$'` | Label shown as the root node name |
-| `position` | `'left' \| 'right'` | `'right'` | Side of the screen for the panel |
-
-**Returns**
-
-```ts
-{ destroy: () => void }
-```
-
-Call `destroy()` to unmount the toolbar, panel, and state subscription.
-
-## Themes
-
-The following themes are available (provided by `json-edit-react`):
-
-| Theme key | Description |
-|-----------|-------------|
-| `githubDark` | GitHub dark (default) |
-| `githubLight` | GitHub light |
-| `monoDark` | Monochrome dark |
-| `monoLight` | Monochrome light |
-
-## Example
-
-A working example is included in `examples/basic/`. To run it:
-
-```bash
-npm install
-npm run dev
-```
-
-This builds the core package and starts the Vite dev server for the example app.
-
-## Development
-
-```bash
-git clone <repo-url>
-cd legend-state-dev-tools
-npm install
-npm run build   # build the core package
-npm run dev     # build + start example dev server
-```
-
-## Architecture
-
-The project is a monorepo with the main package in `packages/core/` and examples in `examples/`.
-
-| Module | Path | Role |
-|--------|------|------|
-| `index` | `packages/core/src/index.ts` | Public API (`init`, options, lifecycle) |
-| `state-bridge` | `packages/core/src/state-bridge.ts` | Subscribes to observables, produces snapshots, writes back edits |
-| `json-editor-mount` | `packages/core/src/ui/json-editor-mount.tsx` | Mounts the `json-edit-react` editor with theme resolution |
-| `panel` | `packages/core/src/ui/panel.ts` | Slide-out panel DOM management |
-| `toolbar` | `packages/core/src/ui/toolbar.ts` | Draggable floating toolbar |
-| `template-engine` | `packages/core/src/ui/template-engine.ts` | Lightweight HTML templating (Eta) |
-| `styles` | `packages/core/src/styles.css` | Panel and toolbar CSS |
-
-## Acknowledgments
-
-A huge thank you to [Carlos](https://github.com/CarlosNZ) for creating [`json-edit-react`](https://github.com/CarlosNZ/json-edit-react) -- the excellent React component that powers the state tree viewer and editor in this project. Without it, these dev tools simply wouldn't exist.
-
-## License
-
-MIT

package/examples/basic/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Legend State Dev Tools - Example</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>

package/examples/basic/package.json

@@ -1,24 +0,0 @@
-{
-  "name": "legend-state-dev-tools-example",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build"
-  },
-  "dependencies": {
-    "@legendapp/state": "^3.0.0-beta.43",
-    "react": "^18.3.0",
-    "react-dom": "^18.3.0",
-    "json-edit-react": "^1.16.0",
-    "legend-state-dev-tools": "*"
-  },
-  "devDependencies": {
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
-    "@vitejs/plugin-react": "^4.3.0",
-    "typescript": "^5.3.0",
-    "vite": "^6.0.0"
-  }
-}

package/examples/basic/src/App.tsx

@@ -1,50 +0,0 @@
-import React from 'react';
-import { observer } from '@legendapp/state/react';
-import { state$ } from './state';
-
-export const App = observer(function App() {
-  // In Legend State v3, use .get() to subscribe to values
-  const count = (state$.count as any).get();
-  const userName = (state$.user.name as any).get();
-
-  return (
-    <div style={{ padding: 40, fontFamily: 'sans-serif', maxWidth: 600 }}>
-      <h1>Legend State Dev Tools Demo</h1>
-      <p>Open the dev tools panel using the floating button at the bottom-right.</p>
-
-      <div style={{ marginTop: 24, padding: 16, background: '#f5f5f5', borderRadius: 8, color: '#1a1a1a' }}>
-        <h2>Counter: {count}</h2>
-        <button onClick={() => (state$.count as any).set((c: number) => c + 1)}>
-          Increment
-        </button>
-        <button onClick={() => (state$.count as any).set(0)} style={{ marginLeft: 8 }}>
-          Reset
-        </button>
-      </div>
-
-      <div style={{ marginTop: 24, padding: 16, background: '#f5f5f5', borderRadius: 8, color: '#1a1a1a' }}>
-        <h2>User: {userName}</h2>
-        <input
-          value={userName}
-          onChange={(e) => (state$.user.name as any).set(e.target.value)}
-          style={{ padding: '4px 8px', fontSize: 14 }}
-        />
-      </div>
-
-      <div style={{ marginTop: 24, padding: 16, background: '#f5f5f5', borderRadius: 8, color: '#1a1a1a' }}>
-        <h2>Todos</h2>
-        <button
-          onClick={() =>
-            (state$.todos as any).push({
-              id: Date.now(),
-              text: `New todo ${Date.now()}`,
-              done: false,
-            })
-          }
-        >
-          Add Todo
-        </button>
-      </div>
-    </div>
-  );
-});

package/examples/basic/src/main.tsx

@@ -1,16 +0,0 @@
-import React from 'react';
-import { createRoot } from 'react-dom/client';
-import { init } from 'legend-state-dev-tools';
-import 'legend-state-dev-tools/dist/styles.css';
-import { state$ } from './state';
-import { App } from './App';
-
-// Initialize dev tools
-init(state$, {
-  rootName: 'state$',
-  theme: 'githubDark',
-  readOnly: false,
-});
-
-const root = createRoot(document.getElementById('root')!);
-root.render(<App />);

package/examples/basic/src/state.ts

@@ -1,17 +0,0 @@
-import { observable } from '@legendapp/state';
-
-export const state$ = observable({
-  count: 0,
-  user: {
-    name: 'Alice',
-    email: 'alice@example.com',
-    preferences: {
-      darkMode: true,
-      notifications: true,
-    },
-  },
-  todos: [
-    { id: 1, text: 'Learn Legend State', done: true },
-    { id: 2, text: 'Try dev tools', done: false },
-  ],
-});

package/examples/basic/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "lib": ["ES2020", "DOM", "DOM.Iterable"],
-    "moduleResolution": "bundler",
-    "strict": true,
-    "skipLibCheck": true,
-    "esModuleInterop": true,
-    "jsx": "react-jsx",
-    "resolveJsonModule": true,
-    "isolatedModules": true
-  },
-  "include": ["src"]
-}

package/examples/basic/vite.config.ts

@@ -1,6 +0,0 @@
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-
-export default defineConfig({
-  plugins: [react()],
-});

package/packages/core/package.json

@@ -1,40 +0,0 @@
-{
-  "name": "legend-state-dev-tools",
-  "version": "0.1.0",
-  "description": "Dev tools for Legend State v3 - view and edit observable state",
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "default": "./dist/index.mjs"
-    },
-    "./dist/styles.css": "./dist/styles.css"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "vite build",
-    "dev": "vite build --watch"
-  },
-  "devDependencies": {
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
-    "typescript": "^5.3.0",
-    "vite": "^6.0.0",
-    "vite-plugin-dts": "^4.0.0"
-  },
-  "peerDependencies": {
-    "@legendapp/state": ">=3.0.0-beta.0",
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0"
-  },
-  "dependencies": {
-    "eta": "^3.5.0",
-    "json-edit-react": "^1.16.0"
-  }
-}

package/packages/core/src/eta.d.ts

@@ -1,4 +0,0 @@
-declare module '*.eta' {
-  const content: string;
-  export default content;
-}

package/packages/core/src/index.ts

@@ -1,130 +0,0 @@
-import type { ObservableParam } from '@legendapp/state';
-import { Toolbar } from './ui/toolbar';
-import { Panel } from './ui/panel';
-import { createStateBridge, type StateBridge } from './state-bridge';
-import { mountJsonEditor, type JsonEditorBridge } from './ui/json-editor-mount';
-import { createCleanup } from './ui/shared-utils';
-
-export interface DevToolsOptions {
-  enabled?: boolean;
-  readOnly?: boolean;
-  theme?: string;
-  rootName?: string;
-  position?: 'left' | 'right';
-}
-
-export interface DevTools {
-  destroy: () => void;
-}
-
-export function init(
-  observable$: ObservableParam<any>,
-  options: DevToolsOptions = {}
-): DevTools {
-  const {
-    enabled = true,
-    readOnly = false,
-    theme = 'githubDark',
-    rootName = 'state$',
-    position = 'right',
-  } = options;
-
-  if (!enabled) {
-    return { destroy: () => {} };
-  }
-
-  const cleanup = createCleanup();
-  let panel: Panel | null = null;
-  let toolbar: Toolbar | null = null;
-  let bridge: StateBridge | null = null;
-  let editorBridge: JsonEditorBridge | null = null;
-
-  // Create panel
-  panel = new Panel({
-    rootName,
-    readOnly,
-    position,
-    onClose: () => {
-      hidePanel();
-    },
-  });
-
-  const showPanel = () => {
-    if (!panel) return;
-    panel.show();
-    toolbar?.setPanelVisible(true);
-
-    // Poll for editor root element (innerHTML may not be ready immediately)
-    const tryMount = (retries = 10) => {
-      const editorRoot = panel?.getEditorRoot();
-      if (!editorRoot) {
-        if (retries > 0) {
-          setTimeout(() => tryMount(retries - 1), 16);
-        } else {
-          console.warn('[Legend State DevTools] Could not find #lsdt-json-editor-root after retries');
-        }
-        return;
-      }
-      if (editorBridge) return;
-
-      const initialData = bridge?.getSnapshot() ?? {};
-
-      editorBridge = mountJsonEditor(editorRoot, {
-        initialData,
-        onEdit: (newData: unknown) => {
-          bridge?.setData(newData);
-        },
-        readOnly,
-        theme,
-        rootName,
-      });
-    };
-    tryMount();
-  };
-
-  const hidePanel = () => {
-    if (editorBridge) {
-      editorBridge.destroy();
-      editorBridge = null;
-    }
-    panel?.hide();
-    toolbar?.setPanelVisible(false);
-  };
-
-  const togglePanel = () => {
-    if (panel?.isVisible()) {
-      hidePanel();
-    } else {
-      showPanel();
-    }
-  };
-
-  // Create toolbar
-  toolbar = new Toolbar({
-    onTogglePanel: togglePanel,
-    rootName,
-  });
-  toolbar.mount();
-  cleanup.add(() => toolbar?.unmount());
-
-  // Create state bridge
-  bridge = createStateBridge(observable$, {
-    onSnapshot: (snapshot) => {
-      editorBridge?.updateData(snapshot);
-    },
-  });
-  cleanup.add(() => bridge?.destroy());
-  cleanup.add(() => {
-    if (editorBridge) {
-      editorBridge.destroy();
-      editorBridge = null;
-    }
-  });
-  cleanup.add(() => panel?.unmount());
-
-  return {
-    destroy: () => {
-      cleanup.run();
-    },
-  };
-}

package/packages/core/src/state-bridge.ts

@@ -1,56 +0,0 @@
-import type { ObservableParam } from '@legendapp/state';
-
-export interface StateBridgeOptions {
-  onSnapshot: (snapshot: unknown) => void;
-}
-
-export interface StateBridge {
-  getSnapshot: () => unknown;
-  setData: (newData: unknown) => void;
-  destroy: () => void;
-}
-
-export function createStateBridge(
-  observable$: ObservableParam<any>,
-  options: StateBridgeOptions
-): StateBridge {
-  // Get initial snapshot
-  const getSnapshot = () => {
-    try {
-      return JSON.parse(JSON.stringify((observable$ as any).peek()));
-    } catch {
-      return undefined;
-    }
-  };
-
-  // Subscribe to changes using onChange
-  let dispose: (() => void) | null = null;
-  try {
-    dispose = (observable$ as any).onChange(
-      () => {
-        const snapshot = getSnapshot();
-        options.onSnapshot(snapshot);
-      },
-      { trackingType: false }
-    );
-  } catch {
-    console.warn('[Legend State DevTools] Could not subscribe to observable changes via onChange');
-  }
-
-  return {
-    getSnapshot,
-    setData: (newData: unknown) => {
-      try {
-        (observable$ as any).set(newData);
-      } catch (e) {
-        console.error('[Legend State DevTools] Failed to set data:', e);
-      }
-    },
-    destroy: () => {
-      if (dispose) {
-        dispose();
-        dispose = null;
-      }
-    },
-  };
-}

package/packages/core/src/ui/json-editor-mount.tsx

@@ -1,144 +0,0 @@
-import React, { Component, useEffect, useState, type ErrorInfo, type ReactNode } from 'react';
-import { createRoot, type Root } from 'react-dom/client';
-import { JsonEditor, githubDarkTheme, githubLightTheme, monoDarkTheme, monoLightTheme } from 'json-edit-react';
-
-const themeMap: Record<string, object> = {
-  githubDark: githubDarkTheme,
-  githubLight: githubLightTheme,
-  monoDark: monoDarkTheme,
-  monoLight: monoLightTheme,
-};
-
-class ErrorBoundary extends Component<
-  { children: ReactNode },
-  { error: Error | null }
-> {
-  state = { error: null as Error | null };
-  static getDerivedStateFromError(error: Error) {
-    return { error };
-  }
-  componentDidCatch(error: Error, info: ErrorInfo) {
-    console.error('[Legend State DevTools] React error:', error, info);
-  }
-  render() {
-    if (this.state.error) {
-      return React.createElement(
-        'pre',
-        { style: { color: '#ff6b6b', padding: 16, fontSize: 12 } },
-        `DevTools Error: ${this.state.error.message}\n${this.state.error.stack}`
-      );
-    }
-    return this.props.children;
-  }
-}
-
-interface JsonEditorWrapperProps {
-  data: unknown;
-  onEdit: (newData: unknown) => void;
-  readOnly: boolean;
-  theme: string;
-  rootName: string;
-}
-
-function JsonEditorWrapper({
-  data,
-  onEdit,
-  readOnly,
-  theme,
-  rootName,
-}: JsonEditorWrapperProps) {
-  const resolvedTheme = themeMap[theme] ?? githubDarkTheme;
-  return (
-    <JsonEditor
-      data={data as Record<string, unknown>}
-      setData={onEdit as any}
-      rootName={rootName}
-      theme={resolvedTheme as any}
-      collapse={2}
-      restrictEdit={readOnly}
-      restrictDelete={readOnly}
-      restrictAdd={readOnly}
-      restrictTypeSelection={readOnly ? true : undefined}
-    />
-  );
-}
-
-export interface JsonEditorBridge {
-  updateData: (data: unknown) => void;
-  destroy: () => void;
-}
-
-// Wrapper component that receives data via a callback registration
-function JsonEditorBridgeWrapper(props: {
-  initialData: unknown;
-  onEdit: (newData: unknown) => void;
-  readOnly: boolean;
-  theme: string;
-  rootName: string;
-  registerUpdater: (updater: (data: unknown) => void) => void;
-}) {
-  const [data, setData] = useState<unknown>(props.initialData);
-
-  useEffect(() => {
-    props.registerUpdater((newData: unknown) => {
-      setData(newData);
-    });
-  }, []);
-
-  const handleEdit = (newData: unknown) => {
-    setData(newData);
-    props.onEdit(newData);
-  };
-
-  return (
-    <JsonEditorWrapper
-      data={data}
-      onEdit={handleEdit}
-      readOnly={props.readOnly}
-      theme={props.theme}
-      rootName={props.rootName}
-    />
-  );
-}
-
-export function mountJsonEditor(
-  container: HTMLElement,
-  options: {
-    initialData: unknown;
-    onEdit: (newData: unknown) => void;
-    readOnly: boolean;
-    theme: string;
-    rootName: string;
-  }
-): JsonEditorBridge {
-  let root: Root | null = null;
-  let updaterFn: ((data: unknown) => void) | null = null;
-
-  root = createRoot(container);
-  root.render(
-    <ErrorBoundary>
-    <JsonEditorBridgeWrapper
-      initialData={options.initialData}
-      onEdit={options.onEdit}
-      readOnly={options.readOnly}
-      theme={options.theme}
-      rootName={options.rootName}
-      registerUpdater={(updater) => {
-        updaterFn = updater;
-      }}
-    />
-    </ErrorBoundary>
-  );
-
-  return {
-    updateData: (data: unknown) => {
-      updaterFn?.(data);
-    },
-    destroy: () => {
-      if (root) {
-        root.unmount();
-        root = null;
-      }
-    },
-  };
-}