@djangocfg/widget-code 0.1.1

package/src/editor/lazy.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+/**
+ * `@djangocfg/widget-code/editor` subpath entrypoint.
+ *
+ * Monaco itself weighs ~550 KB minified — we must never pay that cost
+ * unless the editor actually mounts. The `Lazy*` wrappers here dynamically
+ * import the `Editor` and `DiffEditor` components, which transitively pull
+ * in `monaco-editor` and the worker setup.
+ *
+ * The rest of the surface (types, EditorProvider, useMonaco hook, helpers)
+ * is light:
+ *   - `monaco-editor` is referenced only as a TS type (`type *`) — erased
+ *     at compile time.
+ *   - `useMonaco` performs a dynamic `import('monaco-editor')` itself, so
+ *     importing the hook is free until the caller actually invokes it.
+ *
+ * That means consumers can wire up keyboard shortcuts, theme toggles, or
+ * file-state hooks at the top of their tree without paying Monaco's cost,
+ * and only render `<LazyEditor>` lower in the tree where it's needed.
+ */
+
+import { createLazyComponent, LoadingFallback } from '@djangocfg/widget-kit/lazy';
+import type { EditorProps, DiffEditorProps } from './types';
+
+// ============================================================================
+// Lazy components
+// ============================================================================
+
+export const LazyEditor = createLazyComponent<EditorProps>(
+  () => import('./components/Editor').then((m) => ({ default: m.Editor })),
+  {
+    displayName: 'LazyEditor',
+    fallback: <LoadingFallback minHeight={320} text="Loading editor…" />,
+  },
+);
+
+export const LazyDiffEditor = createLazyComponent<DiffEditorProps>(
+  () => import('./components/DiffEditor').then((m) => ({ default: m.DiffEditor })),
+  {
+    displayName: 'LazyDiffEditor',
+    fallback: <LoadingFallback minHeight={320} text="Loading diff editor…" />,
+  },
+);
+
+// `Editor` / `DiffEditor` are the plain named exports — same lazy components,
+// kept so callers can `import { Editor } from '@djangocfg/widget-code/editor'`
+// without knowing about the `Lazy*` naming.
+export { LazyEditor as Editor };
+export { LazyDiffEditor as DiffEditor };
+
+// ============================================================================
+// Light surface
+// ============================================================================
+
+// Hooks — `useMonaco` does its own dynamic import; the others are pure.
+export {
+  useMonaco,
+  useEditor,
+  useLanguage,
+  useEditorTheme,
+} from './hooks';
+
+// Provider + context hook
+export { EditorProvider, useEditorContext } from './context';
+
+// All types
+export type {
+  EditorFile,
+  EditorOptions,
+  EditorProps,
+  EditorContextValue,
+  UseEditorReturn,
+  UseMonacoReturn,
+  DiffEditorProps,
+} from './types';

package/src/editor/lib/index.ts

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

package/src/editor/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/editor/lib/themes.ts

@@ -0,0 +1,42 @@
+/**
+ * Editor Themes
+ *
+ * The editor is always dark (devtool-style), so only dark themes are exposed.
+ */
+
+export type EditorTheme = 'vs-dark' | 'hc-black' | 'cmdop-dark';
+
+export const EDITOR_THEMES = {
+  // Built-in themes
+  'vs-dark': 'Dark (VS Code)',
+  'hc-black': 'High Contrast Dark',
+  // Custom themes
+  'cmdop-dark': 'CMDOP Dark',
+} as const;
+
+/**
+ * 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',
+  },
+};

package/src/editor/types/index.ts

@@ -0,0 +1,137 @@
+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;
+  /** Focus the editor once Monaco mounts. Pair with `key={path}` upstream
+   *  for per-file focus reset. */
+  autoFocus?: boolean;
+  /** Bound to Cmd/Ctrl+S inside the editor via Monaco's command palette.
+   *  Receives the current value. The browser default is suppressed by
+   *  Monaco when a command is registered for that chord. */
+  onSave?: (value: string) => void;
+}
+
+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/editor/workers/index.ts

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

package/src/editor/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/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Code surfaces: an editor, a diff, a highlighted listing, a JSON editor and
+ * the markdown renderer that embeds them.
+ *
+ * No root barrel worth importing — Monaco alone is ~550 KB and `json-edit-react`
+ * and Prism sit behind their own subpaths. Import the one you want:
+ * `@djangocfg/widget-code/editor`, `/pretty-code`, `/diff-viewer`,
+ * `/json-editor`, `/markdown-message`.
+ */
+export { ANCHOR, TOGGLE } from './role-tokens';

package/src/json-editor/JsonEditor.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+/**
+ * JsonEditor — editable JSON tree.
+ *
+ * Thin wrapper over `json-edit-react` (MIT, CarlosNZ). The library
+ * handles the hard parts (inline editing, drag-reorder, JSON-Schema
+ * validation, undo/redo, keyboard nav, copy-to-clipboard) — we apply
+ * our theme tokens and a sane default surface, nothing more.
+ *
+ * When to use:
+ *   - User is *editing* JSON live (debug Store panel, config UI).
+ *   - You need schema validation or controlled mutations with
+ *     `onUpdate`.
+ *
+ * When NOT to use:
+ *   - Read-only display → use `@djangocfg/widget-data/json-tree` (≈ 10×
+ *     lighter bundle, search + copy-path included).
+ */
+
+import { JsonEditor as RawEditor, type JsonEditorProps as RawProps } from 'json-edit-react';
+import { useMemo } from 'react';
+import { useResolvedTheme } from '@djangocfg/ui-core/hooks';
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface JsonEditorProps extends Omit<RawProps, 'theme'> {
+  /** Extra class on the root container. */
+  className?: string;
+  /**
+   * Hide chrome the host already provides. When `false`, no border /
+   * background — the editor sits flush in the surrounding pane.
+   * Default `true`.
+   */
+  bordered?: boolean;
+}
+
+/**
+ * Hand-rolled theme bridge: maps our semantic CSS vars onto
+ * json-edit-react's theme slots. Light/dark resolution lives in our
+ * `useResolvedTheme`; the library only sees concrete colours.
+ *
+ * We keep this minimal — most slots inherit `currentColor`, only the
+ * data-typed tokens get explicit Tailwind palette values so the
+ * keys/strings/numbers stay legible on every host surface.
+ */
+function useEditorTheme(): RawProps['theme'] {
+  const resolved = useResolvedTheme();
+  return useMemo(
+    () => ({
+      displayName: 'djangocfg',
+      styles: {
+        container: {
+          backgroundColor: 'transparent',
+          fontFamily:
+            "'SF Mono', ui-monospace, 'JetBrains Mono', Menlo, Consolas, monospace",
+          fontSize: '12px',
+        },
+        property:
+          resolved === 'dark' ? 'rgb(167 139 250)' : 'rgb(124 58 237)', // violet-400 / violet-600
+        bracket:
+          resolved === 'dark' ? 'rgb(148 163 184)' : 'rgb(100 116 139)', // slate-400 / slate-500
+        itemCount:
+          resolved === 'dark' ? 'rgb(100 116 139)' : 'rgb(148 163 184)',
+        string:
+          resolved === 'dark' ? 'rgb(52 211 153)' : 'rgb(5 150 105)', // emerald-400 / emerald-600
+        number:
+          resolved === 'dark' ? 'rgb(56 189 248)' : 'rgb(2 132 199)', // sky-400 / sky-600
+        boolean:
+          resolved === 'dark' ? 'rgb(251 191 36)' : 'rgb(217 119 6)', // amber-400 / amber-600
+        null: {
+          color: resolved === 'dark' ? 'rgb(100 116 139)' : 'rgb(148 163 184)',
+          fontStyle: 'italic',
+        },
+        input: {
+          backgroundColor:
+            resolved === 'dark' ? 'rgb(30 41 59)' : 'rgb(241 245 249)',
+          color: resolved === 'dark' ? 'white' : 'rgb(15 23 42)',
+          borderRadius: 4,
+          padding: '2px 6px',
+        },
+        inputHighlight:
+          resolved === 'dark' ? 'rgba(96, 165, 250, 0.25)' : 'rgba(59, 130, 246, 0.15)',
+        iconCollection:
+          resolved === 'dark' ? 'rgb(148 163 184)' : 'rgb(100 116 139)',
+        iconEdit: 'currentColor',
+        iconDelete: 'rgb(239 68 68)',
+        iconAdd: 'rgb(34 197 94)',
+        iconCopy: 'currentColor',
+        iconOk: 'rgb(34 197 94)',
+        iconCancel: 'rgb(239 68 68)',
+      },
+    }),
+    [resolved],
+  );
+}
+
+export function JsonEditor({
+  className,
+  bordered = true,
+  ...props
+}: JsonEditorProps) {
+  const theme = useEditorTheme();
+  return (
+    <div
+      className={cn(
+        'json-editor-host w-full',
+        bordered &&
+          'overflow-hidden rounded-md border border-border/60 bg-card px-3 py-2',
+        className,
+      )}
+    >
+      <RawEditor theme={theme} {...props} />
+    </div>
+  );
+}

package/src/json-editor/index.ts

@@ -0,0 +1 @@
+export * from './lazy';