@djangocfg/ui-tools 2.1.239 → 2.1.240

package/src/tools/CodeEditor/hooks/useMonaco.ts

@@ -0,0 +1,64 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import type * as MonacoEditor from 'monaco-editor';
+
+import { setupMonacoWorkers } from '../workers/setup';
+import type { UseMonacoReturn } from '../types';
+
+/**
+ * Hook to load and access Monaco Editor instance
+ *
+ * Handles:
+ * - Dynamic import of Monaco (client-side only)
+ * - Web worker configuration
+ * - Loading state management
+ *
+ * @example
+ * ```tsx
+ * const { monaco, isLoading, error } = useMonaco();
+ *
+ * if (isLoading) return <Spinner />;
+ * if (error) return <Error message={error.message} />;
+ *
+ * // Use monaco API
+ * monaco.editor.create(...)
+ * ```
+ */
+export function useMonaco(): UseMonacoReturn {
+  const [monaco, setMonaco] = useState<typeof MonacoEditor | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let mounted = true;
+
+    async function loadMonaco() {
+      try {
+        // Setup workers first
+        setupMonacoWorkers();
+
+        // Dynamic import Monaco
+        const monacoModule = await import('monaco-editor');
+
+        if (mounted) {
+          setMonaco(monacoModule);
+          setIsLoading(false);
+        }
+      } catch (err) {
+        if (mounted) {
+          setError(err instanceof Error ? err : new Error('Failed to load Monaco Editor'));
+          setIsLoading(false);
+        }
+      }
+    }
+
+    loadMonaco();
+
+    return () => {
+      mounted = false;
+    };
+  }, []);
+
+  return { monaco, isLoading, error };
+}

package/src/tools/CodeEditor/index.ts

@@ -0,0 +1,16 @@
+// ============================================================================
+// CodeEditor - Monaco Editor Integration (~550KB)
+// Code editor components with Next.js support
+// ============================================================================
+
+// Components
+export * from './components';
+
+// Hooks
+export * from './hooks';
+
+// Context
+export * from './context';
+
+// Types
+export * from './types';

package/src/tools/CodeEditor/lib/index.ts

@@ -0,0 +1,2 @@
+export { getLanguageByExtension, getLanguageByFilename, LANGUAGE_MAP } from './languages';
+export { EDITOR_THEMES, getDefaultTheme } from './themes';

package/src/tools/CodeEditor/lib/languages.ts

@@ -0,0 +1,227 @@
+/**
+ * Language Detection & Mapping
+ *
+ * Maps file extensions to Monaco Editor language IDs.
+ * Monaco supports 80+ languages out of the box.
+ */
+
+/**
+ * File extension to Monaco language ID mapping
+ */
+export const LANGUAGE_MAP: Record<string, string> = {
+  // Web
+  '.html': 'html',
+  '.htm': 'html',
+  '.xhtml': 'html',
+  '.vue': 'html',
+  '.svelte': 'html',
+
+  // CSS
+  '.css': 'css',
+  '.scss': 'scss',
+  '.sass': 'scss',
+  '.less': 'less',
+
+  // JavaScript/TypeScript
+  '.js': 'javascript',
+  '.mjs': 'javascript',
+  '.cjs': 'javascript',
+  '.jsx': 'javascript',
+  '.ts': 'typescript',
+  '.tsx': 'typescript',
+  '.mts': 'typescript',
+  '.cts': 'typescript',
+
+  // Data formats
+  '.json': 'json',
+  '.jsonc': 'json',
+  '.json5': 'json',
+  '.yaml': 'yaml',
+  '.yml': 'yaml',
+  '.toml': 'ini',
+  '.xml': 'xml',
+  '.svg': 'xml',
+  '.xsl': 'xml',
+  '.xsd': 'xml',
+
+  // Markdown & Documentation
+  '.md': 'markdown',
+  '.mdx': 'markdown',
+  '.markdown': 'markdown',
+  '.rst': 'restructuredtext',
+  '.txt': 'plaintext',
+  '.text': 'plaintext',
+
+  // Programming languages
+  '.py': 'python',
+  '.pyw': 'python',
+  '.pyi': 'python',
+  '.rb': 'ruby',
+  '.rake': 'ruby',
+  '.gemspec': 'ruby',
+  '.php': 'php',
+  '.phtml': 'php',
+  '.java': 'java',
+  '.kt': 'kotlin',
+  '.kts': 'kotlin',
+  '.scala': 'scala',
+  '.go': 'go',
+  '.rs': 'rust',
+  '.swift': 'swift',
+  '.c': 'c',
+  '.h': 'c',
+  '.cpp': 'cpp',
+  '.cc': 'cpp',
+  '.cxx': 'cpp',
+  '.hpp': 'cpp',
+  '.hxx': 'cpp',
+  '.cs': 'csharp',
+  '.fs': 'fsharp',
+  '.fsx': 'fsharp',
+  '.vb': 'vb',
+  '.lua': 'lua',
+  '.r': 'r',
+  '.R': 'r',
+  '.m': 'objective-c',
+  '.mm': 'objective-c',
+  '.pl': 'perl',
+  '.pm': 'perl',
+  '.ex': 'elixir',
+  '.exs': 'elixir',
+  '.erl': 'erlang',
+  '.hrl': 'erlang',
+  '.clj': 'clojure',
+  '.cljs': 'clojure',
+  '.cljc': 'clojure',
+  '.hs': 'haskell',
+  '.lhs': 'haskell',
+  '.ml': 'fsharp',
+  '.mli': 'fsharp',
+  '.dart': 'dart',
+  '.groovy': 'groovy',
+  '.gradle': 'groovy',
+  '.jl': 'julia',
+
+  // Shell & Scripts
+  '.sh': 'shell',
+  '.bash': 'shell',
+  '.zsh': 'shell',
+  '.fish': 'shell',
+  '.ps1': 'powershell',
+  '.psm1': 'powershell',
+  '.psd1': 'powershell',
+  '.bat': 'bat',
+  '.cmd': 'bat',
+
+  // Config files
+  '.ini': 'ini',
+  '.cfg': 'ini',
+  '.conf': 'ini',
+  '.properties': 'ini',
+  '.env': 'ini',
+  '.gitignore': 'ini',
+  '.gitattributes': 'ini',
+  '.editorconfig': 'ini',
+  '.npmrc': 'ini',
+
+  // Database
+  '.sql': 'sql',
+  '.mysql': 'mysql',
+  '.pgsql': 'pgsql',
+  '.plsql': 'plsql',
+  '.redis': 'redis',
+
+  // Templates
+  '.hbs': 'handlebars',
+  '.handlebars': 'handlebars',
+  '.mustache': 'handlebars',
+  '.ejs': 'html',
+  '.pug': 'pug',
+  '.jade': 'pug',
+  '.twig': 'twig',
+  '.liquid': 'liquid',
+
+  // GraphQL
+  '.graphql': 'graphql',
+  '.gql': 'graphql',
+
+  // Docker
+  '.dockerfile': 'dockerfile',
+
+  // Other
+  '.diff': 'diff',
+  '.patch': 'diff',
+  '.log': 'log',
+  '.tex': 'latex',
+  '.cls': 'latex',
+  '.sty': 'latex',
+  '.proto': 'protobuf',
+  '.sol': 'sol',
+  '.asm': 'mips',
+  '.s': 'mips',
+  '.wasm': 'wasm',
+};
+
+/**
+ * Special filename mappings (without extension)
+ */
+const FILENAME_MAP: Record<string, string> = {
+  Dockerfile: 'dockerfile',
+  'docker-compose.yml': 'yaml',
+  'docker-compose.yaml': 'yaml',
+  Makefile: 'makefile',
+  makefile: 'makefile',
+  Gemfile: 'ruby',
+  Rakefile: 'ruby',
+  Jenkinsfile: 'groovy',
+  Vagrantfile: 'ruby',
+  '.bashrc': 'shell',
+  '.bash_profile': 'shell',
+  '.zshrc': 'shell',
+  '.profile': 'shell',
+  '.vimrc': 'plaintext',
+  '.gitconfig': 'ini',
+  '.htaccess': 'ini',
+  'nginx.conf': 'ini',
+  'package.json': 'json',
+  'tsconfig.json': 'json',
+  'jsconfig.json': 'json',
+  '.prettierrc': 'json',
+  '.eslintrc': 'json',
+  'composer.json': 'json',
+  'Cargo.toml': 'ini',
+  'go.mod': 'go',
+  'go.sum': 'plaintext',
+  'requirements.txt': 'plaintext',
+  'pyproject.toml': 'ini',
+  'setup.py': 'python',
+  'setup.cfg': 'ini',
+};
+
+/**
+ * Get Monaco language ID from file extension
+ */
+export function getLanguageByExtension(extension: string): string {
+  const ext = extension.startsWith('.') ? extension.toLowerCase() : `.${extension.toLowerCase()}`;
+  return LANGUAGE_MAP[ext] || 'plaintext';
+}
+
+/**
+ * Get Monaco language ID from filename
+ * Checks special filenames first, then falls back to extension
+ */
+export function getLanguageByFilename(filename: string): string {
+  // Check special filenames first
+  if (FILENAME_MAP[filename]) {
+    return FILENAME_MAP[filename];
+  }
+
+  // Extract extension
+  const lastDot = filename.lastIndexOf('.');
+  if (lastDot === -1) {
+    return 'plaintext';
+  }
+
+  const extension = filename.slice(lastDot).toLowerCase();
+  return LANGUAGE_MAP[extension] || 'plaintext';
+}

package/src/tools/CodeEditor/lib/themes.ts

@@ -0,0 +1,78 @@
+/**
+ * Editor Themes
+ *
+ * Built-in Monaco themes and custom CMDOP themes
+ */
+
+export type EditorTheme = 'vs' | 'vs-dark' | 'hc-black' | 'hc-light' | 'cmdop-dark' | 'cmdop-light';
+
+export const EDITOR_THEMES = {
+  // Built-in themes
+  'vs': 'Light (VS Code)',
+  'vs-dark': 'Dark (VS Code)',
+  'hc-black': 'High Contrast Dark',
+  'hc-light': 'High Contrast Light',
+  // Custom themes (to be defined)
+  'cmdop-dark': 'CMDOP Dark',
+  'cmdop-light': 'CMDOP Light',
+} as const;
+
+/**
+ * Get default theme based on system preference
+ */
+export function getDefaultTheme(): EditorTheme {
+  if (typeof window === 'undefined') return 'vs-dark';
+
+  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+  return prefersDark ? 'vs-dark' : 'vs';
+}
+
+/**
+ * CMDOP Dark Theme Definition
+ * Can be registered with monaco.editor.defineTheme()
+ */
+export const cmdopDarkTheme = {
+  base: 'vs-dark' as const,
+  inherit: true,
+  rules: [
+    { token: 'comment', foreground: '6A9955', fontStyle: 'italic' },
+    { token: 'keyword', foreground: 'C586C0' },
+    { token: 'string', foreground: 'CE9178' },
+    { token: 'number', foreground: 'B5CEA8' },
+    { token: 'type', foreground: '4EC9B0' },
+    { token: 'function', foreground: 'DCDCAA' },
+    { token: 'variable', foreground: '9CDCFE' },
+  ],
+  colors: {
+    'editor.background': '#1a1a1a',
+    'editor.foreground': '#D4D4D4',
+    'editor.lineHighlightBackground': '#2d2d2d',
+    'editor.selectionBackground': '#264F78',
+    'editorCursor.foreground': '#AEAFAD',
+    'editorLineNumber.foreground': '#858585',
+    'editorLineNumber.activeForeground': '#C6C6C6',
+  },
+};
+
+/**
+ * CMDOP Light Theme Definition
+ */
+export const cmdopLightTheme = {
+  base: 'vs' as const,
+  inherit: true,
+  rules: [
+    { token: 'comment', foreground: '008000', fontStyle: 'italic' },
+    { token: 'keyword', foreground: 'AF00DB' },
+    { token: 'string', foreground: 'A31515' },
+    { token: 'number', foreground: '098658' },
+    { token: 'type', foreground: '267F99' },
+    { token: 'function', foreground: '795E26' },
+    { token: 'variable', foreground: '001080' },
+  ],
+  colors: {
+    'editor.background': '#FFFFFF',
+    'editor.foreground': '#000000',
+    'editor.lineHighlightBackground': '#F5F5F5',
+    'editor.selectionBackground': '#ADD6FF',
+  },
+};

package/src/tools/CodeEditor/types/index.ts

@@ -0,0 +1,130 @@
+import type * as monaco from 'monaco-editor';
+
+// ============================================================================
+// Editor Types
+// ============================================================================
+
+export interface EditorFile {
+  /** Unique file path */
+  path: string;
+  /** File content */
+  content: string;
+  /** Detected or specified language */
+  language: string;
+  /** Whether file has unsaved changes */
+  isDirty: boolean;
+  /** Monaco model reference */
+  model?: monaco.editor.ITextModel;
+}
+
+export interface EditorOptions {
+  /** Editor theme: 'vs' | 'vs-dark' | 'hc-black' | custom */
+  theme?: string;
+  /** Font size in pixels */
+  fontSize?: number;
+  /** Font family */
+  fontFamily?: string;
+  /** Tab size */
+  tabSize?: number;
+  /** Insert spaces instead of tabs */
+  insertSpaces?: boolean;
+  /** Word wrap mode */
+  wordWrap?: 'off' | 'on' | 'wordWrapColumn' | 'bounded';
+  /** Show minimap */
+  minimap?: boolean;
+  /** Show line numbers */
+  lineNumbers?: 'on' | 'off' | 'relative' | 'interval';
+  /** Read-only mode */
+  readOnly?: boolean;
+}
+
+export interface EditorProps {
+  /** File content */
+  value?: string;
+  /** Programming language for syntax highlighting */
+  language?: string;
+  /** Called when content changes */
+  onChange?: (value: string) => void;
+  /** Called when editor is mounted */
+  onMount?: (editor: monaco.editor.IStandaloneCodeEditor) => void;
+  /** Editor options */
+  options?: EditorOptions;
+  /** CSS class name */
+  className?: string;
+  /** Height — fixed px, CSS string, or '100%' (default: '100%'). Ignored when autoHeight=true */
+  height?: string | number;
+  /** Width (default: '100%') */
+  width?: string | number;
+  /** Auto-resize height to fit content. Editor grows/shrinks with content lines */
+  autoHeight?: boolean;
+  /** Min height in px when autoHeight is enabled (default: 100) */
+  minHeight?: number;
+  /** Max height in px when autoHeight is enabled (default: 600) */
+  maxHeight?: number;
+}
+
+export interface DiffEditorProps {
+  /** Original content (left side) */
+  original: string;
+  /** Modified content (right side) */
+  modified: string;
+  /** Programming language */
+  language?: string;
+  /** Editor options */
+  options?: EditorOptions;
+  /** CSS class name */
+  className?: string;
+  /** Height (default: '100%') */
+  height?: string | number;
+}
+
+// ============================================================================
+// Context Types
+// ============================================================================
+
+export interface EditorContextValue {
+  /** Currently open files */
+  openFiles: EditorFile[];
+  /** Currently active file */
+  activeFile: EditorFile | null;
+  /** Monaco instance (null during SSR) */
+  monaco: typeof monaco | null;
+  /** Editor instance */
+  editor: monaco.editor.IStandaloneCodeEditor | null;
+  /** Whether editor is ready */
+  isReady: boolean;
+
+  // File operations
+  openFile: (path: string, content: string, language?: string) => void;
+  closeFile: (path: string) => void;
+  setActiveFile: (path: string) => void;
+  updateContent: (path: string, content: string) => void;
+  saveFile: (path: string) => Promise<void>;
+
+  // State queries
+  isDirty: (path: string) => boolean;
+  getContent: (path: string) => string | null;
+  getFile: (path: string) => EditorFile | null;
+}
+
+// ============================================================================
+// Hook Return Types
+// ============================================================================
+
+export interface UseEditorReturn {
+  /** Editor instance */
+  editor: monaco.editor.IStandaloneCodeEditor | null;
+  /** Whether editor is mounted and ready */
+  isReady: boolean;
+  /** Set editor reference */
+  setEditor: (editor: monaco.editor.IStandaloneCodeEditor | null) => void;
+}
+
+export interface UseMonacoReturn {
+  /** Monaco namespace */
+  monaco: typeof monaco | null;
+  /** Whether Monaco is loaded */
+  isLoading: boolean;
+  /** Loading error if any */
+  error: Error | null;
+}

package/src/tools/CodeEditor/workers/index.ts

@@ -0,0 +1 @@
+export { setupMonacoWorkers } from './setup';

package/src/tools/CodeEditor/workers/setup.ts

@@ -0,0 +1,58 @@
+'use client';
+
+/**
+ * Monaco Editor Web Worker Setup
+ *
+ * Workers improve performance for language services (TypeScript type-checking,
+ * JSON validation, etc.) but require bundler-specific configuration:
+ *
+ * **Vite**: Use `?worker` imports (see example below)
+ * **Next.js/Webpack**: Use `monaco-editor-webpack-plugin`
+ * **No config**: Monaco falls back to main-thread execution (fully functional)
+ *
+ * @example Vite setup (call once in app entry):
+ * ```ts
+ * 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'
+ * import cssWorker from 'monaco-editor/esm/vs/language/css/css.worker?worker'
+ * import htmlWorker from 'monaco-editor/esm/vs/language/html/html.worker?worker'
+ *
+ * setupMonacoWorkers((label) => {
+ *   switch (label) {
+ *     case 'typescript': case 'javascript': return new tsWorker()
+ *     case 'json': return new jsonWorker()
+ *     case 'css': case 'scss': case 'less': return new cssWorker()
+ *     case 'html': case 'handlebars': case 'razor': return new htmlWorker()
+ *     default: return new editorWorker()
+ *   }
+ * })
+ * ```
+ *
+ * @example Next.js setup:
+ * ```ts
+ * // next.config.js — add monaco-editor-webpack-plugin
+ * // Then just call setupMonacoWorkers() without arguments
+ * setupMonacoWorkers()
+ * ```
+ */
+
+type GetWorkerFn = (label: string) => Worker;
+
+let isSetup = false;
+
+export function setupMonacoWorkers(getWorker?: GetWorkerFn): void {
+  if (isSetup || typeof window === 'undefined') return;
+
+  if (getWorker) {
+    // App provides bundler-specific worker factory
+    (self as unknown as { MonacoEnvironment: object }).MonacoEnvironment = {
+      getWorker: (_workerId: string, label: string) => getWorker(label),
+    };
+  }
+  // else: don't set MonacoEnvironment at all.
+  // - If webpack plugin is installed, it sets MonacoEnvironment automatically.
+  // - If nothing sets it, Monaco falls back to main-thread execution.
+
+  isSetup = true;
+}

package/src/tools/index.ts

@@ -197,6 +197,31 @@ export type {
   CronSchedulerContextValue,
 } from './CronScheduler';
 
+// Export CodeEditor (Monaco ~550KB)
+export {
+  Editor,
+  DiffEditor,
+} from './CodeEditor/components';
+export type { EditorRef } from './CodeEditor/components/Editor';
+export {
+  EditorProvider,
+  useEditorContext,
+} from './CodeEditor/context';
+export {
+  useMonaco,
+  useEditor,
+  useLanguage,
+} from './CodeEditor/hooks';
+export type {
+  EditorFile,
+  EditorOptions,
+  EditorProps,
+  DiffEditorProps,
+  EditorContextValue,
+  UseEditorReturn,
+  UseMonacoReturn,
+} from './CodeEditor/types';
+
 // Export Media Cache Store
 export {
   useMediaCacheStore,