@djangocfg/widget-code 0.1.1

package/src/editor/editor.stories.tsx

@@ -0,0 +1,397 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Editor, DiffEditor } from './lazy';
+
+// ---------------------------------------------------------------------------
+// Samples
+// ---------------------------------------------------------------------------
+
+const TS_SAMPLE = `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 };
+}
+`;
+
+const JS_SAMPLE = `export function debounce(fn, ms = 200) {
+  let t;
+  return (...args) => {
+    clearTimeout(t);
+    t = setTimeout(() => fn(...args), ms);
+  };
+}
+`;
+
+const PY_SAMPLE = `from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Iterable
+
+
+@dataclass
+class User:
+    id: str
+    name: str
+    email: str
+    role: str = "user"
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+
+def admins(users: Iterable[User]) -> list[User]:
+    return [u for u in users if u.role == "admin"]
+`;
+
+const JSON_SAMPLE = `{
+  "name": "@djangocfg/ui-tools",
+  "version": "2.1.0",
+  "dependencies": {
+    "monaco-editor": "^0.55.1",
+    "react": "^19.1.0"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./code-editor": "./src/tools/CodeEditor/index.ts"
+  }
+}
+`;
+
+const CSS_SAMPLE = `: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 var(--border);
+  overflow: hidden;
+}
+
+.editor-container:focus-within {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+`;
+
+const HTML_SAMPLE = `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Hello</title>
+  </head>
+  <body>
+    <main>
+      <h1>Hello world</h1>
+    </main>
+  </body>
+</html>
+`;
+
+const MARKDOWN_SAMPLE = `# CodeEditor
+
+Monaco-based editor wrapped for React.
+
+- Syntax highlighting
+- Diff view
+- Auto-height
+
+\`\`\`ts
+const x: number = 1;
+\`\`\`
+`;
+
+const SQL_SAMPLE = `SELECT u.id, u.name, count(o.id) AS orders
+FROM users AS u
+LEFT JOIN orders AS o ON o.user_id = u.id
+WHERE u.created_at > now() - interval '30 days'
+GROUP BY u.id, u.name
+ORDER BY orders DESC
+LIMIT 50;
+`;
+
+const YAML_SAMPLE = `version: "3.9"
+services:
+  api:
+    image: ghcr.io/djangocfg/api:latest
+    ports:
+      - "8000:8000"
+    environment:
+      DATABASE_URL: postgres://app:app@db:5432/app
+  db:
+    image: postgres:16
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+volumes:
+  pgdata: {}
+`;
+
+const DOCKERFILE_SAMPLE = `FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+CMD ["pnpm", "start"]
+`;
+
+const SAMPLES: Record<string, string> = {
+  typescript: TS_SAMPLE,
+  javascript: JS_SAMPLE,
+  python: PY_SAMPLE,
+  json: JSON_SAMPLE,
+  css: CSS_SAMPLE,
+  html: HTML_SAMPLE,
+  markdown: MARKDOWN_SAMPLE,
+  sql: SQL_SAMPLE,
+  yaml: YAML_SAMPLE,
+  dockerfile: DOCKERFILE_SAMPLE,
+};
+
+// 200+ line sample for LargeFile preset.
+const LARGE_SAMPLE = Array.from({ length: 220 }, (_, i) => {
+  const n = i + 1;
+  if (n % 20 === 0) return `// ── section ${n / 20} ──────────────────────────────`;
+  if (n % 5 === 0) return `export const value${n} = computeValue(${n});`;
+  return `const line${n} = ${n} * Math.PI; // line ${n}`;
+}).join('\n');
+
+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");
+`;
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+/**
+ * The playground flattens Monaco's nested `options` into top-level controls —
+ * Storybook cannot drive a nested object with radios and number inputs. Those
+ * knobs are therefore the props of a real harness component rather than a
+ * story-only args type, so `satisfies Meta<typeof EditorPlayground>` checks them.
+ */
+interface EditorPlaygroundProps {
+  language: keyof typeof SAMPLES;
+  theme: 'vs-dark' | 'vs-light';
+  readOnly: boolean;
+  minimap: boolean;
+  lineNumbers: 'on' | 'off' | 'relative' | 'interval';
+  wordWrap: 'off' | 'on' | 'wordWrapColumn' | 'bounded';
+  fontSize: number;
+}
+
+function EditorPlayground({
+  language,
+  theme,
+  readOnly,
+  minimap,
+  lineNumbers,
+  wordWrap,
+  fontSize,
+}: EditorPlaygroundProps) {
+  return (
+    <div className="h-[460px] w-[760px] overflow-hidden rounded-md border">
+      <Editor
+        language={language}
+        value={SAMPLES[language]}
+        options={{ theme, readOnly, minimap, lineNumbers, wordWrap, fontSize }}
+      />
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Widgets/Code/Editor',
+  component: EditorPlayground,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Monaco-based code editor (~550KB). Heavy — load behind a route or lazy boundary in real apps. Wrap in a fixed-height container unless `autoHeight` is set.',
+      },
+    },
+  },
+  argTypes: {
+    language: {
+      control: 'select',
+      options: Object.keys(SAMPLES),
+      table: { category: 'Content' },
+    },
+    theme: {
+      control: 'inline-radio',
+      options: ['vs-dark', 'vs-light'],
+      table: { category: 'Appearance' },
+    },
+    fontSize: {
+      control: { type: 'number', min: 10, max: 24, step: 1 },
+      table: { category: 'Appearance' },
+    },
+    minimap: { control: 'boolean', table: { category: 'Appearance' } },
+    lineNumbers: {
+      control: 'inline-radio',
+      options: ['on', 'off', 'relative', 'interval'],
+      table: { category: 'Appearance' },
+    },
+    wordWrap: {
+      control: 'inline-radio',
+      options: ['off', 'on', 'wordWrapColumn', 'bounded'],
+      table: { category: 'Behaviour' },
+    },
+    readOnly: { control: 'boolean', table: { category: 'Behaviour' } },
+  },
+  args: {
+    language: 'typescript',
+    theme: 'vs-dark',
+    readOnly: false,
+    minimap: true,
+    lineNumbers: 'on',
+    wordWrap: 'on',
+    fontSize: 14,
+  },
+} satisfies Meta<typeof EditorPlayground>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Playground
+// ---------------------------------------------------------------------------
+
+export const Playground: Story = {};
+
+// ---------------------------------------------------------------------------
+// Curated presets
+// ---------------------------------------------------------------------------
+
+export const TypeScript: Story = {
+  render: () => (
+    <div className="h-[420px] w-[760px] overflow-hidden rounded-md border">
+      <Editor language="typescript" value={TS_SAMPLE} />
+    </div>
+  ),
+};
+
+export const Json: Story = {
+  render: () => (
+    <div className="h-[360px] w-[760px] overflow-hidden rounded-md border">
+      <Editor language="json" value={JSON_SAMPLE} />
+    </div>
+  ),
+};
+
+export const Python: Story = {
+  render: () => (
+    <div className="h-[420px] w-[760px] overflow-hidden rounded-md border">
+      <Editor language="python" value={PY_SAMPLE} />
+    </div>
+  ),
+};
+
+export const ReadOnly: Story = {
+  render: () => (
+    <div className="h-[420px] w-[760px] overflow-hidden rounded-md border">
+      <Editor
+        language="typescript"
+        value={TS_SAMPLE}
+        options={{ readOnly: true, lineNumbers: 'on' }}
+      />
+    </div>
+  ),
+};
+
+export const LargeFile: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: '220-line file — minimap and scroll behaviour become relevant.',
+      },
+    },
+  },
+  render: () => (
+    <div className="h-[520px] w-[760px] overflow-hidden rounded-md border">
+      <Editor
+        language="typescript"
+        value={LARGE_SAMPLE}
+        options={{ minimap: true, lineNumbers: 'on' }}
+      />
+    </div>
+  ),
+};
+
+export const Diff: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Side-by-side diff view via `DiffEditor`. Always read-only.',
+      },
+    },
+  },
+  render: () => (
+    <div className="h-[420px] w-[920px] overflow-hidden rounded-md border">
+      <DiffEditor
+        original={DIFF_ORIGINAL}
+        modified={DIFF_MODIFIED}
+        language="typescript"
+      />
+    </div>
+  ),
+};
+
+export const Minimal: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'No minimap, no line numbers, no word-wrap — minimal chrome for embeds.',
+      },
+    },
+  },
+  render: () => (
+    <div className="h-[300px] w-[640px] overflow-hidden rounded-md border">
+      <Editor
+        language="markdown"
+        value={MARKDOWN_SAMPLE}
+        options={{
+          minimap: false,
+          lineNumbers: 'off',
+          wordWrap: 'off',
+        }}
+      />
+    </div>
+  ),
+};

package/src/editor/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useMonaco } from './useMonaco';
+export { useEditor } from './useEditor';
+export { useLanguage } from './useLanguage';
+export { useEditorTheme } from './useEditorTheme';

package/src/editor/hooks/useEditor.ts

@@ -0,0 +1,36 @@
+'use client';
+
+import { useState, useCallback } from 'react';
+import type * as monaco from 'monaco-editor';
+
+import type { UseEditorReturn } from '../types';
+
+/**
+ * Hook to manage editor instance reference
+ *
+ * @example
+ * ```tsx
+ * const { editor, isReady, setEditor } = useEditor();
+ *
+ * // Pass setEditor to Editor component's onMount
+ * <Editor onMount={setEditor} />
+ *
+ * // Use editor when ready
+ * if (isReady) {
+ *   editor.getModel()?.getValue();
+ * }
+ * ```
+ */
+export function useEditor(): UseEditorReturn {
+  const [editor, setEditorState] = useState<monaco.editor.IStandaloneCodeEditor | null>(null);
+
+  const setEditor = useCallback((editorInstance: monaco.editor.IStandaloneCodeEditor | null) => {
+    setEditorState(editorInstance);
+  }, []);
+
+  return {
+    editor,
+    isReady: editor !== null,
+    setEditor,
+  };
+}

package/src/editor/hooks/useEditorTheme.ts

@@ -0,0 +1,91 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/** Background used for the editor and its loading/error placeholders. */
+export const EDITOR_BACKGROUND = '#0a0a0a';
+
+/**
+ * Hook that registers and returns the Monaco editor theme.
+ *
+ * The editor is always dark (Chrome devtools / VSCode convention) — its
+ * palette does not follow the host app theme. Pass `themeOverride` only
+ * if you need a specific Monaco built-in (e.g. `'hc-black'`).
+ *
+ * @param monaco - Monaco namespace (null during loading)
+ * @param themeOverride - Optional explicit theme name
+ * @returns Resolved Monaco theme name to pass to editor options
+ */
+export function useEditorTheme(
+  monaco: typeof import('monaco-editor') | null,
+  themeOverride?: string,
+): string {
+  // State (not ref) so consumers re-render once the custom theme is registered.
+  const [registered, setRegistered] = useState(false);
+
+  useEffect(() => {
+    if (!monaco) return;
+
+    try {
+      const colors = readEditorColors();
+
+      monaco.editor.defineTheme('app-dark', {
+        base: 'vs-dark',
+        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': colors.background,
+          'editor.foreground': colors.foreground,
+          'editor.lineHighlightBackground': colors.lineHighlight,
+          'editor.selectionBackground': colors.selection,
+          'editorCursor.foreground': colors.foreground,
+          'editorLineNumber.foreground': colors.mutedForeground,
+          'editorWidget.background': colors.card,
+          'editorWidget.border': colors.border,
+          'input.background': colors.card,
+          'dropdown.background': colors.card,
+        },
+      });
+
+      setRegistered(true);
+    } catch {
+      // Fallback — use the built-in dark theme.
+      setRegistered(false);
+    }
+  }, [monaco]);
+
+  if (themeOverride) return themeOverride;
+  return registered ? 'app-dark' : 'vs-dark';
+}
+
+/**
+ * Editor colors — hard-coded dark palette.
+ *
+ * Previously we resolved against CSS variables (`--background`, `--card`,
+ * …) so the editor matched the host theme, but the editor MUST be dark
+ * regardless of host theme (Chrome devtools / VSCode / Insomnia
+ * convention). On a light-themed app `--background` resolves to white,
+ * which Monaco then paints under `base: 'vs-dark'` — giving the broken
+ * "white Monaco" look. Hard-coding keeps the dark contract honest and
+ * removes a layout-time DOM probe.
+ */
+function readEditorColors() {
+  return {
+    background: EDITOR_BACKGROUND,
+    foreground: '#f5f5f5',
+    card: '#141414',
+    border: '#262626',
+    mutedForeground: '#858585',
+    lineHighlight: '#1a1a1a',
+    selection: '#264F78',
+  };
+}
+

package/src/editor/hooks/useLanguage.ts

@@ -0,0 +1,29 @@
+'use client';
+
+import { useMemo } from 'react';
+import { getLanguageByFilename } from '../lib/languages';
+
+/**
+ * Hook to detect language from filename
+ *
+ * @param filename - File name or path
+ * @returns Monaco language ID
+ *
+ * @example
+ * ```tsx
+ * const language = useLanguage('app.tsx');
+ * // Returns: 'typescript'
+ *
+ * const language2 = useLanguage('/path/to/Dockerfile');
+ * // Returns: 'dockerfile'
+ * ```
+ */
+export function useLanguage(filename: string | undefined): string {
+  return useMemo(() => {
+    if (!filename) return 'plaintext';
+
+    // Extract basename from path
+    const basename = filename.split('/').pop() || filename;
+    return getLanguageByFilename(basename);
+  }, [filename]);
+}

package/src/editor/hooks/useMonaco.ts

@@ -0,0 +1,79 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import type * as MonacoEditor from 'monaco-editor';
+
+import { setupMonacoWorkers } from '../workers/setup';
+import type { UseMonacoReturn } from '../types';
+
+/**
+ * Shared, module-level Monaco loader.
+ *
+ * Monaco is ~550KB — we load it exactly once per page and hand the same
+ * module to every `useMonaco()` consumer. Without this each Editor /
+ * DiffEditor / EditorProvider would manage its own loading state and
+ * briefly flash a spinner even though the module is already in memory.
+ */
+let monacoPromise: Promise<typeof MonacoEditor> | null = null;
+
+function loadMonaco(): Promise<typeof MonacoEditor> {
+  if (!monacoPromise) {
+    monacoPromise = (async () => {
+      setupMonacoWorkers();
+      return import('monaco-editor');
+    })().catch((err) => {
+      // Reset so a later mount can retry instead of being stuck on a
+      // permanently-rejected promise.
+      monacoPromise = null;
+      throw err;
+    });
+  }
+  return monacoPromise;
+}
+
+/**
+ * Hook to load and access Monaco Editor instance
+ *
+ * Handles:
+ * - Dynamic import of Monaco (client-side only, loaded once and shared)
+ * - 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;
+
+    loadMonaco()
+      .then((monacoModule) => {
+        if (!mounted) return;
+        setMonaco(monacoModule);
+        setIsLoading(false);
+      })
+      .catch((err) => {
+        if (!mounted) return;
+        setError(err instanceof Error ? err : new Error('Failed to load Monaco Editor'));
+        setIsLoading(false);
+      });
+
+    return () => {
+      mounted = false;
+    };
+  }, []);
+
+  return { monaco, isLoading, error };
+}

package/src/editor/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';