@djangocfg/widget-code 0.1.1

package/src/diff-viewer/hooks/useHighlighter.ts

@@ -0,0 +1,54 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Shared tokenizer for DiffViewer. Reuses the same `prism-react-renderer`
+// bundle that `PrettyCode` ships — no second highlighter is loaded. We
+// also re-import `PrettyCode`'s grammar-registration hook so `bash`,
+// `ruby`, `java`, `php` work in diffs without duplicating the dynamic
+// imports.
+
+import { useMemo } from 'react';
+import type { Language } from 'prism-react-renderer';
+import { useEnsurePrismLanguages } from '../../pretty-code/registerPrismLanguages';
+
+/**
+ * Normalize a free-form language string into a Prism language key. Falls
+ * back to `text` when the key isn't one Prism knows about.
+ */
+export function normalizeLanguage(language: string | undefined): Language {
+  if (!language) return 'text' as Language;
+  const lang = language.toLowerCase();
+  switch (lang) {
+    case 'js':
+      return 'javascript' as Language;
+    case 'ts':
+      return 'typescript' as Language;
+    case 'py':
+      return 'python' as Language;
+    case 'rb':
+      return 'ruby' as Language;
+    case 'sh':
+    case 'shell':
+      return 'bash' as Language;
+    case 'html':
+    case 'xml':
+      return 'markup' as Language;
+    case 'md':
+      return 'markdown' as Language;
+    case 'yml':
+      return 'yaml' as Language;
+    case 'golang':
+      return 'go' as Language;
+    default:
+      return lang as Language;
+  }
+}
+
+/**
+ * Subscribe to PrettyCode's extra-grammar loader and return the resolved
+ * Prism language key. The component re-renders once `bash`/`ruby`/… are
+ * registered so the first paint isn't stuck on plain text.
+ */
+export function useDiffLanguage(language: string | undefined): Language {
+  useEnsurePrismLanguages();
+  return useMemo(() => normalizeLanguage(language), [language]);
+}

package/src/diff-viewer/index.ts

@@ -0,0 +1,22 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { DiffViewer } from './DiffViewer';
+export { DIFF_TONE_CLASSES } from './types';
+export {
+  diffLines,
+  parseUnifiedPatch,
+  computeStats as computeDiffStats,
+  lineNumberWidth as diffLineNumberWidth,
+} from './utils/computeDiff';
+export { useDiff } from './hooks/useDiff';
+export { normalizeLanguage as normalizeDiffLanguage } from './hooks/useHighlighter';
+
+export type {
+  DiffLayout,
+  DiffLine,
+  DiffLineType,
+  DiffStats,
+  DiffInput,
+  DiffToneClasses,
+  DiffViewerProps,
+} from './types';

package/src/diff-viewer/lazy.tsx

@@ -0,0 +1,25 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { createLazyComponent } from '@djangocfg/widget-kit/lazy';
+import type { DiffViewerProps } from './types';
+
+export const LazyDiffViewer = createLazyComponent<DiffViewerProps>(
+  () =>
+    import('./DiffViewer').then((mod) => ({ default: mod.DiffViewer })),
+  {
+    displayName: 'LazyDiffViewer',
+    fallback: (
+      <div
+        data-slot="diff-viewer-skeleton"
+        className="h-48 w-full animate-pulse rounded-xl border border-border/60 bg-muted"
+      />
+    ),
+  },
+);
+
+// `DiffLayout` rides the public subpath too: a consumer that sets the
+// viewer's `layout` needs to name the type, and reaching into
+// `DiffViewer/types` directly would make a private path public by habit.
+export type { DiffViewerProps, DiffLayout } from './types';

package/src/diff-viewer/types.ts

@@ -0,0 +1,125 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type * as React from 'react';
+import type { Language } from 'prism-react-renderer';
+
+/** Layout of the diff: single-column unified vs. side-by-side split. */
+export type DiffLayout = 'unified' | 'split';
+
+/** Per-line kind in a computed diff. */
+export type DiffLineType = 'added' | 'removed' | 'context';
+
+/**
+ * One rendered line in the diff. Old / new line numbers are independent:
+ * an added line has no `oldNumber`, a removed line has no `newNumber`.
+ */
+export interface DiffLine {
+  type: DiffLineType;
+  content: string;
+  oldNumber: number | null;
+  newNumber: number | null;
+}
+
+/** Diff stats — rendered in the header pill. */
+export interface DiffStats {
+  added: number;
+  removed: number;
+}
+
+interface WithStrings {
+  /** Original code (LHS). */
+  oldCode: string;
+  /** Updated code (RHS). */
+  newCode: string;
+  patch?: never;
+}
+
+interface WithPatch {
+  /** Pre-computed unified diff string (alternative to oldCode / newCode). */
+  patch: string;
+  oldCode?: never;
+  newCode?: never;
+}
+
+export type DiffInput = WithStrings | WithPatch;
+
+/**
+ * Tone classes for a single diff line. Tailwind class strings backed by
+ * semantic tokens — the diff viewer adapts to the host theme (light or
+ * dark) unlike `PrettyCode`, which is intentionally always-dark. Diffs
+ * are commonly embedded in documentation pages, where forcing a dark
+ * surface on a light page looks like a bug.
+ */
+export interface DiffToneClasses {
+  /** Row background tint. */
+  row: string;
+  /** Gutter / line-number column foreground. */
+  num: string;
+  /** Body text color. */
+  text: string;
+  /** Header stat pill color (e.g. `+12`). */
+  stat: string;
+}
+
+/**
+ * Mapping from line type to tone class bundle. Semantic tokens —
+ * resolved by the host theme (light surfaces in light mode, dark in
+ * dark mode).
+ */
+export const DIFF_TONE_CLASSES: Record<DiffLineType, DiffToneClasses> = {
+  added: {
+    row: 'bg-success/10',
+    num: 'text-success/80',
+    text: 'text-success',
+    stat: 'text-success',
+  },
+  removed: {
+    row: 'bg-destructive/15',
+    num: 'text-destructive/80',
+    text: 'text-destructive',
+    stat: 'text-destructive',
+  },
+  context: {
+    row: '',
+    num: 'text-muted-foreground/60',
+    text: 'text-foreground',
+    stat: 'text-muted-foreground',
+  },
+};
+
+export type DiffViewerProps = DiffInput &
+  Omit<React.ComponentProps<'div'>, 'children'> & {
+    /** Layout. @default `'unified'` */
+    layout?: DiffLayout;
+    /**
+     * Prism language key for optional syntax highlighting. When omitted,
+     * lines render as plain monospace. Highlighting reuses the same
+     * `prism-react-renderer` instance as the `PrettyCode` tool — no
+     * second highlighter is loaded.
+     */
+    language?: Language | string;
+    /** Label for the LHS file header. */
+    oldTitle?: string;
+    /** Label for the RHS file header. */
+    newTitle?: string;
+    /** Show the copy-to-clipboard button. @default `true` */
+    copyable?: boolean;
+    /** Number of context lines around each hunk when diffing strings. @default `3` */
+    context?: number;
+    /**
+     * The HOST caps this viewer's height and owns the scroller (e.g. a chat
+     * bubble with `maxHeight` + `overflowY:auto`). Set it and the >100-line
+     * virtualized path is skipped, because Virtuoso would otherwise open its
+     * own fixed-height scroller INSIDE the host's — two scrollers of the same
+     * size, neither owning the scroll position Virtuoso measures against,
+     * leaving blank bands between consecutively-numbered rows.
+     *
+     * Not a styling hint and not a performance knob: it answers "who owns the
+     * height", which has exactly one right answer per embedding. Leave it false
+     * (the default) wherever the viewer is free to grow — documentation embeds
+     * expect that, and they are the case virtualization exists for.
+     *
+     * @default `false`
+     */
+    hostScrolls?: boolean;
+  };

package/src/diff-viewer/utils/computeDiff.ts

@@ -0,0 +1,171 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Line-level diff via Longest Common Subsequence. The jalcoui original
+// uses the `diff` npm package (Myers diff + unified patches). We don't
+// pull that dependency: a 60-line LCS in TS handles up to ~5k lines
+// fast enough for the viewer's use case (small/medium code reviews) and
+// keeps the bundle lean. For pre-computed patches the caller can pass
+// `patch` and we parse the unified-diff text directly — no algorithm
+// runs at all.
+
+import type { DiffLine } from '../types';
+
+/**
+ * Compute line-level diff between two strings. Returns a flat sequence
+ * of `DiffLine`s in display order. `context` controls how many unchanged
+ * lines are emitted around each change-hunk; pass `Infinity` to keep the
+ * full file.
+ */
+export function diffLines(
+  oldCode: string,
+  newCode: string,
+  context = 3,
+): DiffLine[] {
+  const oldLines = oldCode.split('\n');
+  const newLines = newCode.split('\n');
+
+  // Build LCS table (rows = oldLines + 1, cols = newLines + 1).
+  // For each cell, store the length of the longest common subsequence
+  // of `oldLines[0..i]` and `newLines[0..j]`.
+  const m = oldLines.length;
+  const n = newLines.length;
+  // Use a single flat Int32Array for cache friendliness.
+  const lcs = new Int32Array((m + 1) * (n + 1));
+  const cols = n + 1;
+  // Every `lcs` index below is derived from the loop bounds and is therefore
+  // in range; `at()` would cost a bounds re-check per cell in the hot loop, so
+  // read through a helper that keeps the `number` type without changing the
+  // arithmetic.
+  const cell = (index: number): number => lcs[index] ?? 0;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const idx = i * cols + j;
+      if (oldLines[i - 1] === newLines[j - 1]) {
+        lcs[idx] = cell((i - 1) * cols + (j - 1)) + 1;
+      } else {
+        const up = cell((i - 1) * cols + j);
+        const left = cell(i * cols + (j - 1));
+        lcs[idx] = up >= left ? up : left;
+      }
+    }
+  }
+
+  // Walk back from (m, n) to (0, 0) emitting tagged lines.
+  type Tagged = { type: DiffLine['type']; oldNum: number | null; newNum: number | null; content: string };
+  const tagged: Tagged[] = [];
+  let i = m;
+  let j = n;
+  while (i > 0 || j > 0) {
+    // `i`/`j` are > 0 in each branch that indexes, so the reads are in range;
+    // the `?? ''` only satisfies noUncheckedIndexedAccess.
+    if (i > 0 && j > 0 && oldLines[i - 1] === newLines[j - 1]) {
+      tagged.push({ type: 'context', oldNum: i, newNum: j, content: oldLines[i - 1] ?? '' });
+      i--;
+      j--;
+    } else if (j > 0 && (i === 0 || cell(i * cols + (j - 1)) >= cell((i - 1) * cols + j))) {
+      tagged.push({ type: 'added', oldNum: null, newNum: j, content: newLines[j - 1] ?? '' });
+      j--;
+    } else if (i > 0) {
+      tagged.push({ type: 'removed', oldNum: i, newNum: null, content: oldLines[i - 1] ?? '' });
+      i--;
+    }
+  }
+  tagged.reverse();
+
+  // Apply context window — drop runs of `context`-only lines that are
+  // farther than `context` from any change. `Infinity` keeps every line.
+  if (!Number.isFinite(context)) {
+    return tagged.map((t) => ({
+      type: t.type,
+      content: t.content,
+      oldNumber: t.oldNum,
+      newNumber: t.newNum,
+    }));
+  }
+
+  // Mark indices that are within `context` of a change.
+  const keep = new Array<boolean>(tagged.length).fill(false);
+  for (let k = 0; k < tagged.length; k++) {
+    const t = tagged[k];
+    if (t === undefined) continue;
+    if (t.type !== 'context') {
+      const from = Math.max(0, k - context);
+      const to = Math.min(tagged.length - 1, k + context);
+      for (let s = from; s <= to; s++) keep[s] = true;
+    }
+  }
+
+  // Drop unkept context lines. We don't render hunk separators (`@@`) —
+  // the viewer is meant for compact diffs, not full-file patches.
+  const out: DiffLine[] = [];
+  for (let k = 0; k < tagged.length; k++) {
+    if (!keep[k]) continue;
+    const t = tagged[k];
+    if (t === undefined) continue;
+    out.push({
+      type: t.type,
+      content: t.content,
+      oldNumber: t.oldNum,
+      newNumber: t.newNum,
+    });
+  }
+  return out;
+}
+
+/**
+ * Parse a unified diff patch (`@@ -a,b +c,d @@` hunks) into the same
+ * `DiffLine[]` shape `diffLines()` produces. Only the line tags and
+ * numbers from the hunk headers are honored — file headers
+ * (`--- a/file`, `+++ b/file`) are skipped.
+ */
+export function parseUnifiedPatch(patch: string): DiffLine[] {
+  const lines: DiffLine[] = [];
+  const HUNK = /^@@\s+-(\d+)(?:,\d+)?\s+\+(\d+)(?:,\d+)?\s+@@/;
+  let oldNum = 0;
+  let newNum = 0;
+  let inHunk = false;
+
+  for (const raw of patch.split('\n')) {
+    const hunk = HUNK.exec(raw);
+    if (hunk) {
+      // Both groups are non-optional in HUNK, so a match always fills them.
+      oldNum = parseInt(hunk[1] ?? '0', 10);
+      newNum = parseInt(hunk[2] ?? '0', 10);
+      inHunk = true;
+      continue;
+    }
+    if (!inHunk) continue;
+    if (raw.startsWith('--- ') || raw.startsWith('+++ ') || raw.startsWith('\\')) continue;
+
+    if (raw.startsWith('+')) {
+      lines.push({ type: 'added', content: raw.slice(1), oldNumber: null, newNumber: newNum++ });
+    } else if (raw.startsWith('-')) {
+      lines.push({ type: 'removed', content: raw.slice(1), oldNumber: oldNum++, newNumber: null });
+    } else {
+      const content = raw.startsWith(' ') ? raw.slice(1) : raw;
+      lines.push({ type: 'context', content, oldNumber: oldNum++, newNumber: newNum++ });
+    }
+  }
+  return lines;
+}
+
+/** Widest gutter required for the line numbers, in characters. */
+export function lineNumberWidth(lines: DiffLine[]): number {
+  let max = 0;
+  for (const line of lines) {
+    if (line.oldNumber && line.oldNumber > max) max = line.oldNumber;
+    if (line.newNumber && line.newNumber > max) max = line.newNumber;
+  }
+  return Math.max(String(max).length, 2);
+}
+
+/** Count `+` and `-` lines for the header stat pill. */
+export function computeStats(lines: DiffLine[]): { added: number; removed: number } {
+  let added = 0;
+  let removed = 0;
+  for (const line of lines) {
+    if (line.type === 'added') added++;
+    else if (line.type === 'removed') removed++;
+  }
+  return { added, removed };
+}

package/src/editor/README.md

@@ -0,0 +1,187 @@
+# 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/widget-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/widget-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/widget-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
+
+The editor is always dark (devtool-style), regardless of the app theme. The custom `app-dark` Monaco theme is registered automatically with colors derived from CSS variables (`--background`, `--foreground`, `--card`, `--border`).
+
+Override with an explicit theme:
+
+```tsx
+<Editor options={{ theme: 'vs-dark' }} />   {/* built-in 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 (always dark) |
+
+## Types
+
+```tsx
+import type {
+  EditorFile,
+  EditorOptions,
+  EditorProps,
+  DiffEditorProps,
+  EditorContextValue,
+  UseEditorReturn,
+  UseMonacoReturn,
+} from '@djangocfg/widget-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/widget-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/widget-code/editor';
+```