@djangocfg/widget-code 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Reforms.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @djangocfg/widget-code
+
+Code surfaces: an editor, a diff, a highlighted listing, a JSON editor, and the
+markdown renderer that embeds them.
+
+## Install
+
+```bash
+pnpm add @djangocfg/widget-code @djangocfg/ui-core @djangocfg/i18n
+```
+
+| Subpath | What | Weight |
+|---|---|---|
+| `./editor` | Monaco, single file or diff | ~550 KB, lazy |
+| `./json-editor` | an editable JSON tree | `json-edit-react` |
+| `./pretty-code` | a read-only listing with a panel header | Prism |
+| `./diff-viewer` | unified or split diff, virtualised | Prism + virtuoso |
+| `./diff-viewer/full` | the same, eagerly | |
+| `./markdown-message` | markdown with embedded code, diagrams and chips | |
+| `./role-tokens` | the `ANCHOR` / `TOGGLE` class contracts | |
+
+## No root barrel worth importing
+
+Monaco alone is ~550 KB, and Prism and `json-edit-react` sit behind their own
+subpaths. The root exports the role tokens and nothing else, on purpose.
+
+## Read-only code elsewhere
+
+`@djangocfg/widget-media/code` renders a listing with **shiki**, and a console
+should pick one highlighter rather than match two themes by hand. Prefer it for
+a new surface; this package's Prism stack stays because `DiffViewer` and
+`MarkdownMessage` are built on it.
+
+## Verify
+
+```bash
+pnpm --filter @djangocfg/widget-code check-types test
+```

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@djangocfg/widget-code",
+  "version": "0.1.1",
+  "description": "Code surfaces: a Monaco editor, a diff viewer, a Prism listing, a JSON editor and the markdown renderer that embeds them",
+  "keywords": [
+    "code-editor",
+    "monaco",
+    "diff",
+    "syntax-highlighting",
+    "markdown",
+    "react",
+    "typescript"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "widgets/code"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./editor": {
+      "types": "./src/editor/lazy.tsx",
+      "default": "./src/editor/lazy.tsx"
+    },
+    "./json-editor": {
+      "types": "./src/json-editor/lazy.tsx",
+      "default": "./src/json-editor/lazy.tsx"
+    },
+    "./pretty-code": {
+      "types": "./src/pretty-code/lazy.tsx",
+      "default": "./src/pretty-code/lazy.tsx"
+    },
+    "./diff-viewer": {
+      "types": "./src/diff-viewer/lazy.tsx",
+      "default": "./src/diff-viewer/lazy.tsx"
+    },
+    "./diff-viewer/full": {
+      "types": "./src/diff-viewer/index.ts",
+      "default": "./src/diff-viewer/index.ts"
+    },
+    "./markdown-message": {
+      "types": "./src/markdown-message/index.ts",
+      "default": "./src/markdown-message/index.ts"
+    },
+    "./role-tokens": {
+      "types": "./src/role-tokens.ts",
+      "default": "./src/role-tokens.ts"
+    }
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@djangocfg/widget-data": "^0.1.1",
+    "@djangocfg/widget-diagram": "^0.1.1",
+    "@djangocfg/widget-editor": "^0.1.1",
+    "@djangocfg/widget-kit": "^0.1.1",
+    "json-edit-react": "^1.30.2",
+    "monaco-editor": "^0.55.1",
+    "prism-react-renderer": "^2.4.1",
+    "prismjs": "^1.30.0",
+    "react-markdown": "10.1.0",
+    "react-virtuoso": "^4.18.10",
+    "rehype-external-links": "^3.0.0",
+    "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
+    "remark-breaks": "^4.0.0",
+    "remark-emoji": "^5.0.2",
+    "remark-gfm": "4.0.1",
+    "remark-smartypants": "^3.0.2"
+  },
+  "peerDependencies": {
+    "@djangocfg/i18n": "^2.1.542",
+    "@djangocfg/ui-core": "^2.1.542",
+    "lucide-react": "^0.545.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@djangocfg/i18n": "^2.1.542",
+    "@djangocfg/typescript-config": "^2.1.542",
+    "@djangocfg/ui-core": "^2.1.542",
+    "@storybook/react-vite": "^10.5.0",
+    "@types/node": "^25.9.5",
+    "@types/react": "19.2.15",
+    "@types/react-dom": "19.2.3",
+    "lucide-react": "0.545.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "storybook": "^10.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/diff-viewer/DiffViewer.tsx

@@ -0,0 +1,168 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Line-by-line code diff viewer. Supports unified (single column) and
+// split (side-by-side) layouts. Syntax highlighting reuses the same
+// `prism-react-renderer` bundle that the `PrettyCode` tool already
+// pulls in — no second highlighter is loaded.
+//
+// Requires <UiProviders> at the host root (no nested providers here).
+// See CONTRACT.md §5.
+//
+// Unlike `PrettyCode` (intentionally always-dark), DiffViewer adapts to
+// the host theme. Diffs are commonly embedded in documentation pages
+// where forcing a dark surface on a light page reads as a bug. The
+// Prism theme is picked per host theme (`themes.vsDark` for dark,
+// `themes.github` for light) and surface chrome uses semantic tokens.
+
+'use client';
+
+import * as React from 'react';
+import { themes, type PrismTheme } from 'prism-react-renderer';
+import { cn } from '@djangocfg/ui-core/lib';
+import { useResolvedTheme } from '@djangocfg/ui-core/hooks';
+import { CopyButton } from './components/CopyButton';
+import { SplitView } from './components/SplitView';
+import { UnifiedView } from './components/UnifiedView';
+import { useDiff } from './hooks/useDiff';
+import { useDiffLanguage } from './hooks/useHighlighter';
+import {
+  DIFF_TONE_CLASSES,
+  type DiffInput,
+  type DiffViewerProps,
+} from './types';
+
+export function DiffViewer({
+  layout = 'unified',
+  language,
+  oldTitle,
+  newTitle,
+  copyable = true,
+  context = 3,
+  hostScrolls = false,
+  className,
+  ...allProps
+}: DiffViewerProps) {
+  // Split the diff-input keys off the DOM rest props so we don't spread
+  // `oldCode` / `newCode` / `patch` onto the wrapping <div>.
+  const { oldCode, newCode, patch, ...divProps } =
+    allProps as DiffViewerProps & Record<string, unknown>;
+  const input: DiffInput =
+    patch !== undefined
+      ? ({ patch: patch as string } as DiffInput)
+      : ({
+          oldCode: (oldCode as string) ?? '',
+          newCode: (newCode as string) ?? '',
+        } as DiffInput);
+
+  const { lines, numWidth, stats } = useDiff({ input, context });
+
+  // Longest content line in ch — the shared minimum width of the content
+  // column in BOTH layouts. A single global value (like `numWidth`) keeps
+  // every row the same width, so the whole block scrolls as one unit inside
+  // the outer `overflow-x-auto` wrapper below, and split-view columns stay
+  // aligned across rows. Tabs render 8ch wide under `whitespace-pre`, so
+  // they count as 8.
+  const maxContentCh = React.useMemo(() => {
+    let max = 0;
+    for (const l of lines) {
+      const tabs = (l.content.match(/\t/g) ?? []).length;
+      // CJK / fullwidth glyphs are one UTF-16 unit but render two columns
+      // wide in monospace — count them twice. (Emoji are already two units.)
+      const wide = (l.content.match(/[\u2E80-\u9FFF\uF900-\uFAFF\uFF01-\uFF60]/g) ?? []).length;
+      const len = l.content.length + tabs * 7 + wide;
+      if (len > max) max = len;
+    }
+    return max;
+  }, [lines]);
+
+  // Pass `null` when no language → cheap plain-text render path.
+  const prismLang = useDiffLanguage(language);
+  const resolvedLanguage = language ? prismLang : null;
+
+  // Pick a Prism palette to match the host theme. Resolved once at the
+  // viewer root, then forwarded to every line — keeps the hook out of
+  // per-line render paths (could be thousands of rows on big diffs).
+  const resolved = useResolvedTheme();
+  const prismTheme: PrismTheme =
+    resolved === 'dark' ? themes.vsDark : themes.github;
+
+  // Full text used for the copy button — concatenates current lines as
+  // displayed, including removed ones. Mirrors jalcoui's behavior.
+  const fullCode = React.useMemo(
+    () => lines.map((l) => l.content).join('\n'),
+    [lines],
+  );
+
+  const showHeader = Boolean(oldTitle || newTitle);
+  const addedTone = DIFF_TONE_CLASSES.added.stat;
+  const removedTone = DIFF_TONE_CLASSES.removed.stat;
+
+  return (
+    <div
+      data-slot="diff-viewer"
+      data-layout={layout}
+      className={cn(
+        'relative overflow-hidden rounded-xl border border-border/60 bg-card text-foreground shadow-sm',
+        className,
+      )}
+      {...(divProps as React.ComponentProps<'div'>)}
+    >
+      {showHeader && (
+        <div className="flex items-center justify-between gap-3 border-b border-border/60 bg-muted/40 px-4 py-2.5">
+          <div className="flex items-center gap-3 text-sm">
+            {oldTitle && (
+              <span className="text-muted-foreground">{oldTitle}</span>
+            )}
+            {oldTitle && newTitle && (
+              <span className="text-muted-foreground/60" aria-hidden="true">
+                →
+              </span>
+            )}
+            {newTitle && (
+              <span className="font-medium text-foreground">{newTitle}</span>
+            )}
+          </div>
+          <div className="flex items-center gap-3">
+            <div className="flex items-center gap-2 text-xs tabular-nums">
+              {stats.added > 0 && (
+                <span className={addedTone}>+{stats.added}</span>
+              )}
+              {stats.removed > 0 && (
+                <span className={removedTone}>-{stats.removed}</span>
+              )}
+            </div>
+            {copyable && <CopyButton value={fullCode} />}
+          </div>
+        </div>
+      )}
+
+      {!showHeader && copyable && (
+        <div className="absolute right-2 top-2 z-10">
+          <CopyButton value={fullCode} />
+        </div>
+      )}
+
+      <div className="overflow-x-auto">
+        {layout === 'split' ? (
+          <SplitView
+            lines={lines}
+            numWidth={numWidth}
+            maxContentCh={maxContentCh}
+            language={resolvedLanguage}
+            prismTheme={prismTheme}
+            hostScrolls={hostScrolls}
+          />
+        ) : (
+          <UnifiedView
+            lines={lines}
+            numWidth={numWidth}
+            maxContentCh={maxContentCh}
+            language={resolvedLanguage}
+            prismTheme={prismTheme}
+            hostScrolls={hostScrolls}
+          />
+        )}
+      </div>
+    </div>
+  );
+}

package/src/diff-viewer/README.md

@@ -0,0 +1,33 @@
+# DiffViewer
+
+Line-by-line diff viewer with unified or split layout. Reuses the `prism-react-renderer` instance from `PrettyCode` for optional syntax highlighting — no second highlighter is loaded.
+
+Pass either `oldCode` + `newCode` (computed diff) or a pre-built `patch` string (unified format).
+
+```tsx
+import { DiffViewer } from '@djangocfg/widget-code/diff-viewer';
+
+<DiffViewer
+  oldCode="const x = 1;"
+  newCode="const x = 2;\nconst y = 3;"
+  language="ts"
+  layout="unified"
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `oldCode` / `newCode` | `string` | — | Source pair to diff. Mutually exclusive with `patch`. |
+| `patch` | `string` | — | Pre-computed unified diff. Mutually exclusive with `oldCode`/`newCode`. |
+| `layout` | `'unified' \| 'split'` | `'unified'` | Single column vs side-by-side. |
+| `language` | `Language \| string` | — | Prism language key for highlighting. Omit for plain monospace. |
+| `oldTitle` | `string` | — | LHS file header label. |
+| `newTitle` | `string` | — | RHS file header label. |
+
+Storybook: `apps/storybook/stories/ui-tools/dev/DiffViewer.stories.tsx`
+
+---
+
+Adapted from jalcoui (MIT).

package/src/diff-viewer/components/CopyButton.tsx

@@ -0,0 +1,49 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import { Check, Copy } from 'lucide-react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+interface CopyButtonProps extends Omit<React.ComponentProps<'button'>, 'value'> {
+  value: string;
+}
+
+/**
+ * Tiny copy-to-clipboard button used in the DiffViewer header. Local
+ * component (not a hoist of `CopyAction` from `FloatingToolbar`) so the
+ * viewer can render without any provider context.
+ *
+ * Uses semantic tokens — the diff viewer adapts to the host theme,
+ * unlike `PrettyCode` which forces dark.
+ */
+export function CopyButton({ value, className, ...props }: CopyButtonProps) {
+  const [copied, setCopied] = React.useState(false);
+
+  const handleCopy = React.useCallback(() => {
+    void navigator.clipboard.writeText(value).then(() => {
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1500);
+    });
+  }, [value]);
+
+  return (
+    <button
+      type="button"
+      onClick={handleCopy}
+      data-slot="diff-viewer-copy-button"
+      className={cn(
+        'inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs transition-colors',
+        'text-muted-foreground hover:text-foreground hover:bg-muted',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50',
+        className,
+      )}
+      aria-label={copied ? 'Copied' : 'Copy code'}
+      {...props}
+    >
+      {copied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
+      {copied ? 'Copied' : 'Copy'}
+    </button>
+  );
+}

package/src/diff-viewer/components/DiffLineContent.tsx

@@ -0,0 +1,48 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import { Highlight, type Language, type PrismTheme } from 'prism-react-renderer';
+
+interface DiffLineContentProps {
+  content: string;
+  language: Language | null;
+  /**
+   * Prism palette resolved by the parent `DiffViewer` against the host
+   * theme. Forwarded here so we don't run a theme-detection hook on
+   * every line (a big diff can be thousands of rows).
+   */
+  prismTheme: PrismTheme;
+}
+
+/**
+ * Single-line content cell. When `language` is non-null the line is
+ * tokenized by `prism-react-renderer` (the same instance PrettyCode
+ * uses). When null we render plain text — cheap path for `language`-less
+ * diffs and very large lists.
+ *
+ * Each line tokenizes independently. For diffs > a few thousand lines
+ * this can get warm; in practice the LCS already drops to context lines
+ * before we get there.
+ */
+export const DiffLineContent = React.memo(function DiffLineContent({
+  content,
+  language,
+  prismTheme,
+}: DiffLineContentProps) {
+  if (!language) {
+    return <>{content || ' '}</>;
+  }
+  return (
+    <Highlight theme={prismTheme} code={content || ' '} language={language}>
+      {({ tokens, getTokenProps }) => (
+        <>
+          {tokens[0]?.map((token, key) => (
+            <span key={key} {...getTokenProps({ token })} />
+          ))}
+        </>
+      )}
+    </Highlight>
+  );
+});