@djangocfg/ui-tools 2.1.239 → 2.1.240

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.239",
+  "version": "2.1.240",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -14,7 +14,9 @@
     "gallery",
     "lightbox",
     "map",
-    "maplibre"
+    "maplibre",
+    "monaco-editor",
+    "code-editor"
   ],
   "author": {
     "name": "DjangoCFG",
@@ -62,6 +64,11 @@
       "import": "./src/tools/Tour/index.ts",
       "require": "./src/tools/Tour/index.ts"
     },
+    "./code-editor": {
+      "types": "./src/tools/CodeEditor/index.ts",
+      "import": "./src/tools/CodeEditor/index.ts",
+      "require": "./src/tools/CodeEditor/index.ts"
+    },
     "./styles": "./src/styles/index.css"
   },
   "files": [
@@ -78,8 +85,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.239",
-    "@djangocfg/ui-core": "^2.1.239",
+    "@djangocfg/i18n": "^2.1.240",
+    "@djangocfg/ui-core": "^2.1.240",
     "lucide-react": "^0.545.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
@@ -94,6 +101,7 @@
     "@rjsf/validator-ajv8": "^6.1.2",
     "@vidstack/react": "next",
     "@wavesurfer/react": "^1.0.12",
+    "monaco-editor": "^0.55.1",
     "maplibre-gl": "^4.7.1",
     "media-icons": "next",
     "mermaid": "^11.12.0",
@@ -112,10 +120,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.239",
+    "@djangocfg/i18n": "^2.1.240",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.239",
-    "@djangocfg/ui-core": "^2.1.239",
+    "@djangocfg/typescript-config": "^2.1.240",
+    "@djangocfg/ui-core": "^2.1.240",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",

package/src/tools/CodeEditor/CodeEditor.story.tsx

@@ -0,0 +1,202 @@
+import { defineStory, useSelect, useBoolean } from '@djangocfg/playground';
+import { Editor, DiffEditor } from './components';
+
+export default defineStory({
+  title: 'Tools/Code Editor',
+  component: Editor,
+  description: 'Monaco-based code editor with syntax highlighting, diff view, and full IDE features.',
+});
+
+const SAMPLE_CODE = {
+  typescript: `import { useState, useCallback, useMemo } from 'react';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'user' | 'viewer';
+}
+
+export function useUsers() {
+  const [users, setUsers] = useState<User[]>([]);
+
+  const addUser = useCallback((user: Omit<User, 'id'>) => {
+    setUsers(prev => [...prev, { ...user, id: crypto.randomUUID() }]);
+  }, []);
+
+  const admins = useMemo(
+    () => users.filter(u => u.role === 'admin'),
+    [users],
+  );
+
+  return { users, admins, addUser };
+}`,
+
+  python: `from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import AsyncIterator
+
+import httpx
+from pydantic import BaseModel, Field
+
+
+class User(BaseModel):
+    id: str
+    name: str
+    email: str
+    role: str = "user"
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+@dataclass
+class UserService:
+    base_url: str
+    client: httpx.AsyncClient | None = None
+
+    async def list_users(self, page: int = 1) -> list[User]:
+        async with httpx.AsyncClient(base_url=self.base_url) as client:
+            response = await client.get("/users", params={"page": page})
+            response.raise_for_status()
+            return [User(**u) for u in response.json()["data"]]`,
+
+  json: `{
+  "name": "@djangocfg/ui-tools",
+  "version": "2.1.0",
+  "description": "Heavy React tools with lazy loading",
+  "dependencies": {
+    "monaco-editor": "^0.55.1",
+    "react": "^19.1.0"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./code-editor": "./src/tools/CodeEditor/index.ts"
+  }
+}`,
+
+  css: `/* Design tokens */
+:root {
+  --radius: 0.5rem;
+  --shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+}
+
+.editor-container {
+  position: relative;
+  border-radius: var(--radius);
+  border: 1px solid hsl(var(--border));
+  overflow: hidden;
+
+  &:focus-within {
+    outline: 2px solid hsl(var(--ring));
+    outline-offset: 2px;
+  }
+}`,
+};
+
+const DIFF_ORIGINAL = `function greet(name: string) {
+  console.log("Hello, " + name);
+}
+
+greet("World");`;
+
+const DIFF_MODIFIED = `function greet(name: string, greeting = "Hello") {
+  console.log(\`\${greeting}, \${name}!\`);
+}
+
+function farewell(name: string) {
+  console.log(\`Goodbye, \${name}!\`);
+}
+
+greet("World");
+farewell("World");`;
+
+export const Interactive = () => {
+  const [language] = useSelect('language', {
+    options: ['typescript', 'python', 'json', 'css'] as const,
+    defaultValue: 'typescript',
+    label: 'Language',
+  });
+
+  const [readOnly] = useBoolean('readOnly', {
+    defaultValue: false,
+    label: 'Read Only',
+  });
+
+  const [minimap] = useBoolean('minimap', {
+    defaultValue: false,
+    label: 'Minimap',
+  });
+
+  const [autoHeight] = useBoolean('autoHeight', {
+    defaultValue: false,
+    label: 'Auto Height',
+    description: 'Resize editor to fit content',
+  });
+
+  return autoHeight ? (
+    <Editor
+      value={SAMPLE_CODE[language]}
+      language={language}
+      autoHeight
+      minHeight={100}
+      maxHeight={500}
+      options={{ readOnly, minimap, fontSize: 14 }}
+    />
+  ) : (
+    <div style={{ height: 400 }}>
+      <Editor
+        value={SAMPLE_CODE[language]}
+        language={language}
+        options={{ readOnly, minimap, fontSize: 14 }}
+      />
+    </div>
+  );
+};
+
+export const TypeScript = () => (
+  <div style={{ height: 350 }}>
+    <Editor value={SAMPLE_CODE.typescript} language="typescript" />
+  </div>
+);
+
+export const Python = () => (
+  <div style={{ height: 350 }}>
+    <Editor value={SAMPLE_CODE.python} language="python" />
+  </div>
+);
+
+export const ReadOnly = () => (
+  <div style={{ height: 300 }}>
+    <Editor
+      value={SAMPLE_CODE.json}
+      language="json"
+      options={{ readOnly: true, lineNumbers: 'on' }}
+    />
+  </div>
+);
+
+export const AutoHeight = () => (
+  <div className="flex flex-col gap-4 max-w-3xl">
+    <p className="text-sm text-muted-foreground">
+      Editor grows with content (min 100px, max 400px). Try typing new lines.
+    </p>
+    <Editor
+      value={`const x = 1;\nconst y = 2;\nconst z = x + y;`}
+      language="typescript"
+      autoHeight
+      minHeight={100}
+      maxHeight={400}
+    />
+  </div>
+);
+
+export const DiffView = () => (
+  <div style={{ height: 400 }}>
+    <DiffEditor
+      original={DIFF_ORIGINAL}
+      modified={DIFF_MODIFIED}
+      language="typescript"
+    />
+  </div>
+);

package/src/tools/CodeEditor/README.md

@@ -0,0 +1,189 @@
+# CodeEditor
+
+Monaco-based code editor for React. Full IDE features: syntax highlighting, IntelliSense, diff view, multi-file editing.
+
+## Components
+
+### Editor
+
+Full-featured code editor with ref forwarding.
+
+```tsx
+import { Editor } from '@djangocfg/ui-tools/code-editor';
+
+<Editor
+  value="const x = 42;"
+  language="typescript"
+  onChange={(value) => console.log(value)}
+  options={{
+    theme: 'vs-dark',
+    fontSize: 14,
+    minimap: false,
+    readOnly: false,
+    wordWrap: 'on',
+    lineNumbers: 'on',
+    tabSize: 2,
+  }}
+/>
+```
+
+**Sizing:**
+
+```tsx
+// Fixed height (default)
+<Editor height={400} />
+
+// Fill container (default: height="100%")
+<div style={{ height: 500 }}>
+  <Editor />
+</div>
+
+// Auto-resize to fit content
+<Editor autoHeight minHeight={100} maxHeight={600} />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `height` | `string \| number` | `'100%'` | Fixed height. Ignored when `autoHeight` |
+| `width` | `string \| number` | `'100%'` | Width |
+| `autoHeight` | `boolean` | `false` | Grow/shrink with content |
+| `minHeight` | `number` | `100` | Min height in px (autoHeight only) |
+| `maxHeight` | `number` | `600` | Max height in px (autoHeight only) |
+
+**Ref API:**
+
+```tsx
+const ref = useRef<EditorRef>(null);
+<Editor ref={ref} value="..." language="typescript" />
+
+ref.current?.getValue();       // get current content
+ref.current?.setValue('...');   // set content
+ref.current?.focus();           // focus editor
+```
+
+### DiffEditor
+
+Side-by-side code comparison.
+
+```tsx
+import { DiffEditor } from '@djangocfg/ui-tools/code-editor';
+
+<DiffEditor
+  original="const x = 1;"
+  modified="const x = 42;"
+  language="typescript"
+/>
+```
+
+## Context
+
+Multi-file editor state management.
+
+```tsx
+import { EditorProvider, useEditorContext } from '@djangocfg/ui-tools/code-editor';
+
+<EditorProvider onSave={async (path) => { /* save */ }}>
+  <MyEditor />
+</EditorProvider>
+
+// In child components:
+const {
+  openFiles,          // currently open files
+  activeFile,         // active file
+  openFile,           // (path, content, language?) => void
+  closeFile,          // (path) => void
+  setActiveFile,      // (path) => void
+  updateContent,      // (path, content) => void
+  saveFile,           // (path) => Promise<void>
+  isDirty,            // (path) => boolean
+  getContent,         // (path) => string | null
+} = useEditorContext();
+```
+
+## Theme
+
+Editor automatically follows the app theme (dark/light) via `useResolvedTheme()` from `@djangocfg/ui-core`. No configuration needed — just works with `next-themes` or any setup that toggles `.dark` class on `<html>`.
+
+Custom Monaco themes (`app-dark`, `app-light`) are registered automatically with colors derived from CSS variables (`--background`, `--foreground`, `--card`, `--border`).
+
+Override with explicit theme:
+
+```tsx
+<Editor options={{ theme: 'vs-dark' }} />   {/* force dark */}
+<Editor options={{ theme: 'hc-black' }} />  {/* high contrast */}
+```
+
+## Hooks
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useMonaco()` | `{ monaco, isLoading, error }` | Load Monaco namespace |
+| `useEditor()` | `{ editor, isReady, setEditor }` | Editor instance management |
+| `useLanguage(filename)` | `string` | Detect language from file extension |
+| `useEditorTheme(monaco, override?)` | `string` | Resolved Monaco theme name (auto dark/light) |
+
+## Types
+
+```tsx
+import type {
+  EditorFile,
+  EditorOptions,
+  EditorProps,
+  DiffEditorProps,
+  EditorContextValue,
+  UseEditorReturn,
+  UseMonacoReturn,
+} from '@djangocfg/ui-tools/code-editor';
+```
+
+## Workers
+
+Monaco runs language services (TypeScript, JSON, CSS) in Web Workers for performance. Workers require bundler-specific setup. Without workers, Monaco falls back to main-thread execution (fully functional, but slower for large files).
+
+### Next.js (Webpack)
+
+```bash
+pnpm add monaco-editor-webpack-plugin
+```
+
+```js
+// next.config.js
+const MonacoWebpackPlugin = require('monaco-editor-webpack-plugin');
+
+module.exports = {
+  webpack: (config) => {
+    config.plugins.push(new MonacoWebpackPlugin({
+      languages: ['typescript', 'javascript', 'json', 'css', 'html', 'python'],
+    }));
+    return config;
+  },
+};
+```
+
+### Vite
+
+```ts
+// Call once in app entry (e.g. main.tsx)
+import { setupMonacoWorkers } from '@djangocfg/ui-tools/code-editor';
+import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker';
+import tsWorker from 'monaco-editor/esm/vs/language/typescript/ts.worker?worker';
+import jsonWorker from 'monaco-editor/esm/vs/language/json/json.worker?worker';
+
+setupMonacoWorkers((label) => {
+  if (label === 'typescript' || label === 'javascript') return new tsWorker();
+  if (label === 'json') return new jsonWorker();
+  return new editorWorker();
+});
+```
+
+### No config
+
+Just use the Editor — Monaco works without workers. You'll see a console warning which can be ignored.
+
+## Bundle
+
+~550KB (Monaco Editor). Loaded only when component is rendered — use tree-shakeable import:
+
+```tsx
+import { Editor } from '@djangocfg/ui-tools/code-editor';
+```

package/src/tools/CodeEditor/components/DiffEditor.tsx

@@ -0,0 +1,123 @@
+'use client';
+
+import { useRef, useEffect } from 'react';
+import type * as monaco from 'monaco-editor';
+
+import { useMonaco } from '../hooks/useMonaco';
+import { useEditorTheme } from '../hooks/useEditorTheme';
+import type { DiffEditorProps } from '../types';
+
+/**
+ * Monaco Diff Editor Component
+ *
+ * Side-by-side or inline diff view for comparing two versions of content.
+ *
+ * @example
+ * ```tsx
+ * <DiffEditor
+ *   original={originalCode}
+ *   modified={modifiedCode}
+ *   language="typescript"
+ * />
+ * ```
+ */
+export function DiffEditor({
+  original,
+  modified,
+  language = 'plaintext',
+  options = {},
+  className = '',
+  height = '100%',
+}: DiffEditorProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const editorRef = useRef<monaco.editor.IStandaloneDiffEditor | null>(null);
+  const { monaco, isLoading } = useMonaco();
+  const resolvedTheme = useEditorTheme(monaco, options.theme);
+
+  // Create diff editor
+  useEffect(() => {
+    if (!monaco || !containerRef.current || editorRef.current) return;
+
+    const editor = monaco.editor.createDiffEditor(containerRef.current, {
+      theme: resolvedTheme,
+      fontSize: options.fontSize || 14,
+      fontFamily: options.fontFamily || "'Fira Code', 'Consolas', monospace",
+      readOnly: true,
+      automaticLayout: true,
+      renderSideBySide: true,
+      scrollBeyondLastLine: false,
+      minimap: { enabled: false },
+    });
+
+    const originalModel = monaco.editor.createModel(original, language);
+    const modifiedModel = monaco.editor.createModel(modified, language);
+
+    editor.setModel({
+      original: originalModel,
+      modified: modifiedModel,
+    });
+
+    editorRef.current = editor;
+
+    return () => {
+      originalModel.dispose();
+      modifiedModel.dispose();
+      editor.dispose();
+      editorRef.current = null;
+    };
+  }, [monaco]);
+
+  // Update models when content changes
+  useEffect(() => {
+    const editor = editorRef.current;
+    if (!editor || !monaco) return;
+
+    const model = editor.getModel();
+    if (model) {
+      model.original.setValue(original);
+      model.modified.setValue(modified);
+    }
+  }, [original, modified, monaco]);
+
+  // Update language
+  useEffect(() => {
+    const editor = editorRef.current;
+    if (!editor || !monaco) return;
+
+    const model = editor.getModel();
+    if (model) {
+      monaco.editor.setModelLanguage(model.original, language);
+      monaco.editor.setModelLanguage(model.modified, language);
+    }
+  }, [language, monaco]);
+
+  if (isLoading) {
+    return (
+      <div
+        className={className}
+        style={{
+          width: '100%',
+          height,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          backgroundColor: '#1e1e1e',
+          color: '#666',
+        }}
+      >
+        Loading diff editor...
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className={className}
+      style={{
+        width: '100%',
+        height,
+      }}
+    />
+  );
+}