feat(details): lazy-loaded JSON viewer for large JSON-shaped string fields

martin-castro-laminr-ai · claude · martin-castro-laminr-ai · commit 2987c39629b7 · 2026-05-28T20:17:42.000+02:00
ModelAdmins frequently surface structured payloads (parser outputs, audit blobs, webhook bodies, debug snapshots) as TextField / JSONField values whose string representation is large JSON. The detail page used to render those as raw monospace text — no highlighting, no collapse, no copy affordance. Operators select-all-copied with surrounding chrome and a 50 KB blob filled the entire viewport. Adds a small (3.6 KB) recursive JSON tree viewer in @dar/details, mounted via FieldValueView only when: 1. The field's value is a string. 2. The trimmed value's first character is { or [. 3. JSON.parse succeeds. 4. The string is at least 1024 chars (the issue-acceptance threshold). Behaviour: - Syntax-highlights keys, strings, numbers, booleans, null using the existing design-token palette (text-rose / text-green / text-blue / text-purple); dark mode covered with the matching dark: variants — no new theme rules introduced. - Collapsible objects + arrays via a chevron toggle; collapsed nodes show their item count ({…} N keys / [...] N items). Top-level + the next level start open; deeper levels start collapsed so a deeply nested blob does not fill the viewport on first paint. - Copy button anchored top-right writes the ORIGINAL string (not a re-formatted variant) to the clipboard; shows "Copied" check for 2s. - Renders inside the existing field-grid container so it inherits the card padding + border tokens — no novel chrome. - React.lazy + Suspense: the viewer ships as its own ~3.6 KB chunk (JsonViewer-*.js) that is loaded on demand. Detail pages without any JSON-shaped field never fetch the chunk. Verified via the vite build manifest — the main JS bundle gains ~1.8 KB for the lazy / Suspense plumbing, which is the only fixed cost; the rest of the feature is gated behind the lazy import. Fallback: a small JSON snippet (< 1024 chars), a string that fails JSON.parse, or any non-string value goes through renderValue unchanged — zero regression on the plain-text path. No new runtime dependency (the viewer is hand-rolled JSX; recursion is bounded by the JSON itself, which has no cycles after JSON.parse). No API contract change. Closes #576. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/frontend/packages/details/src/FieldValueView.tsx b/frontend/packages/details/src/FieldValueView.tsx
@@ -8,6 +8,7 @@
 // text (e.g. a `CharField` holding `<script>`) stays inert. The trust
 // boundary is identical to Django's `mark_safe`. See SECURITY.md + #172.
 
+import { Suspense, lazy } from 'react';
 import { Check, X } from 'lucide-react';
 import { Link } from 'react-router-dom';
 
@@ -20,6 +21,37 @@ import {
   type FieldValue,
 } from '@dar/data';
 
+// Lazy-loaded so detail pages whose models hold no large JSON-shaped
+// strings pay zero bundle weight for the viewer (#576). Vite splits the
+// import boundary into its own chunk; the fallback below is the same
+// monospace block we render below the threshold, so the transition is
+// imperceptible when the chunk arrives.
+const JsonViewer = lazy(() => import('./JsonViewer'));
+
+// Threshold below which we don't bother with the viewer — a small JSON
+// blob renders fine as plain text and any chrome is overkill (#576).
+// 1 KB is the issue-acceptance threshold.
+const JSON_VIEWER_THRESHOLD = 1024;
+
+// Cheap detection: a string field whose trimmed value starts with `{`
+// or `[` AND parses as JSON. We only call `JSON.parse` after the
+// length + bracket-shape gate to keep the read path cheap for every
+// detail-page render.
+function tryParseLargeJson(value: unknown): { raw: string; parsed: unknown } | null {
+  if (typeof value !== 'string') return null;
+  if (value.length < JSON_VIEWER_THRESHOLD) return null;
+  const trimmed = value.trimStart();
+  if (trimmed.length === 0) return null;
+  const first = trimmed[0];
+  if (first !== '{' && first !== '[') return null;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return { raw: value, parsed };
+  } catch {
+    return null;
+  }
+}
+
 interface FieldValueViewProps {
   value: FieldValue | undefined;
   /** The field's wire type — when `datetime`/`date`/`time`, the value is
@@ -65,6 +97,22 @@ export function FieldValueView({ value, type }: FieldValueViewProps) {
     }
     return <span className="font-medium text-gray-700">{value.label}</span>;
   }
+  // JSON-shaped string fields (#576): a TextField / JSONField whose
+  // string value parses as JSON and exceeds the threshold renders
+  // through the syntax-highlighted, collapsible viewer with a
+  // copy-the-original-string button. Below the threshold, or for
+  // non-JSON strings, fall through to the plain `renderValue` path
+  // — small snippets are fine as monospace text and any chrome would
+  // be overkill (CLAUDE.md §7, no redundant chrome). The viewer is
+  // lazy-loaded so detail pages without JSON fields pay nothing.
+  const json = tryParseLargeJson(value);
+  if (json) {
+    return (
+      <Suspense fallback={<pre className="whitespace-pre-wrap font-mono text-xs">{json.raw}</pre>}>
+        <JsonViewer raw={json.raw} parsed={json.parsed} />
+      </Suspense>
+    );
+  }
   // FileField / ImageField: a download link to the stored file (matching
   // Django admin's "Currently: <a>" affordance). No URL → plain name.
   if (isFileValue(value)) {
diff --git a/frontend/packages/details/src/JsonViewer.tsx b/frontend/packages/details/src/JsonViewer.tsx
@@ -0,0 +1,190 @@
+// JsonViewer (#576) — syntax-highlighted, collapsible JSON tree with a
+// copy-the-original-string button. Mounts inside the detail page's
+// existing field-value container, so it inherits the card padding +
+// dark-mode tokens (no novel chrome).
+//
+// Default export so the consumer can `React.lazy(() => import('./JsonViewer'))`
+// — anything that doesn't have a JSON field on screen does not pay the
+// bundle weight.
+//
+// No runtime dependency: this is ~2 KB of recursive JSX. The recursion
+// is bounded by the parsed structure itself, which the caller has
+// already `JSON.parse`d successfully — JSON has no cycles so the tree
+// is naturally finite.
+
+import { useState, type ReactNode } from 'react';
+import { Check, ChevronRight, Copy } from 'lucide-react';
+
+interface JsonViewerProps {
+  /** The raw JSON string — copied verbatim by the copy button so the
+   *  operator never gets a re-formatted variant on the clipboard. */
+  raw: string;
+  /** The parsed value (call sites already `JSON.parse`d for detection;
+   *  pass it back so we don't re-parse). */
+  parsed: unknown;
+}
+
+export default function JsonViewer({ raw, parsed }: JsonViewerProps) {
+  const [copied, setCopied] = useState(false);
+
+  async function copy(): Promise<void> {
+    try {
+      await navigator.clipboard.writeText(raw);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Clipboard write can fail on iframes / non-secure contexts —
+      // ignore silently rather than surfacing a toast for a paste op.
+    }
+  }
+
+  return (
+    <div className="relative w-full overflow-x-auto rounded border border-gray-200 bg-gray-50 p-3 font-mono text-xs leading-relaxed text-gray-800 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-200">
+      <button
+        type="button"
+        onClick={copy}
+        aria-label="Copy JSON"
+        title={copied ? 'Copied' : 'Copy'}
+        className="absolute right-2 top-2 inline-flex h-6 w-6 items-center justify-center rounded border border-gray-300 bg-white text-gray-600 hover:bg-gray-100 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700"
+      >
+        {copied ? (
+          <Check className="h-3.5 w-3.5 text-green-600" aria-hidden />
+        ) : (
+          <Copy className="h-3.5 w-3.5" aria-hidden />
+        )}
+      </button>
+      <Node value={parsed} depth={0} />
+    </div>
+  );
+}
+
+// One JSON value — primitive, object, or array — rendered with the right
+// syntax-highlight class. Containers (object/array) carry a clickable
+// toggle that collapses to `{…} N keys` or `[…] N items`.
+function Node({ value, depth }: { value: unknown; depth: number }) {
+  if (value === null) return <span className="text-purple-600 dark:text-purple-400">null</span>;
+  if (typeof value === 'boolean')
+    return (
+      <span className="text-purple-600 dark:text-purple-400">{value ? 'true' : 'false'}</span>
+    );
+  if (typeof value === 'number')
+    return <span className="text-blue-600 dark:text-blue-400">{String(value)}</span>;
+  if (typeof value === 'string')
+    return (
+      <span className="text-green-700 dark:text-green-400">
+        "{escapeForDisplay(value)}"
+      </span>
+    );
+  if (Array.isArray(value)) return <ArrayNode value={value} depth={depth} />;
+  if (typeof value === 'object') return <ObjectNode value={value as Record<string, unknown>} depth={depth} />;
+  // Unknown type (shouldn't happen after JSON.parse — but render safely).
+  return <span className="text-gray-500">{String(value)}</span>;
+}
+
+function ObjectNode({ value, depth }: { value: Record<string, unknown>; depth: number }) {
+  const keys = Object.keys(value);
+  // Top-level + the next level open by default; deeper levels start
+  // collapsed so a 50 KB blob doesn't fill the viewport on first paint.
+  const [open, setOpen] = useState(depth < 2);
+  if (keys.length === 0) return <span className="text-gray-500">{'{}'}</span>;
+  return (
+    <Block
+      open={open}
+      onToggle={() => setOpen((o) => !o)}
+      collapsedLabel={`{…} ${keys.length} ${keys.length === 1 ? 'key' : 'keys'}`}
+      openBracket="{"
+      closeBracket="}"
+      depth={depth}
+    >
+      {keys.map((k, i) => (
+        <div key={k} className="pl-4">
+          <span className="text-rose-700 dark:text-rose-400">"{escapeForDisplay(k)}"</span>
+          <span className="text-gray-500">: </span>
+          <Node value={value[k]} depth={depth + 1} />
+          {i < keys.length - 1 ? <span className="text-gray-500">,</span> : null}
+        </div>
+      ))}
+    </Block>
+  );
+}
+
+function ArrayNode({ value, depth }: { value: unknown[]; depth: number }) {
+  const [open, setOpen] = useState(depth < 2);
+  if (value.length === 0) return <span className="text-gray-500">[]</span>;
+  return (
+    <Block
+      open={open}
+      onToggle={() => setOpen((o) => !o)}
+      collapsedLabel={`[…] ${value.length} ${value.length === 1 ? 'item' : 'items'}`}
+      openBracket="["
+      closeBracket="]"
+      depth={depth}
+    >
+      {value.map((v, i) => (
+        <div key={i} className="pl-4">
+          <Node value={v} depth={depth + 1} />
+          {i < value.length - 1 ? <span className="text-gray-500">,</span> : null}
+        </div>
+      ))}
+    </Block>
+  );
+}
+
+// Shared open/close-with-toggle scaffolding for objects + arrays.
+function Block({
+  open,
+  onToggle,
+  collapsedLabel,
+  openBracket,
+  closeBracket,
+  depth,
+  children,
+}: {
+  open: boolean;
+  onToggle: () => void;
+  collapsedLabel: string;
+  openBracket: string;
+  closeBracket: string;
+  depth: number;
+  children: ReactNode;
+}) {
+  return (
+    <span>
+      <button
+        type="button"
+        onClick={onToggle}
+        aria-expanded={open}
+        // Aligns the chevron baseline with the bracket character.
+        className="inline-flex items-center align-baseline text-gray-500 hover:text-gray-800 dark:hover:text-gray-200"
+      >
+        <ChevronRight
+          className={`h-3 w-3 shrink-0 transition-transform ${open ? 'rotate-90' : ''}`}
+          aria-hidden
+        />
+      </button>
+      <span className="text-gray-500">{openBracket}</span>
+      {open ? (
+        <>
+          {children}
+          <div className={depth === 0 ? '' : 'pl-0'}>
+            <span className="text-gray-500">{closeBracket}</span>
+          </div>
+        </>
+      ) : (
+        <>
+          <span className="px-1 text-gray-500">{collapsedLabel}</span>
+          <span className="text-gray-500">{closeBracket}</span>
+        </>
+      )}
+    </span>
+  );
+}
+
+// JSON's stringification rules are strict — render the content as text
+// (no inner markup) so a value like `<script>` stays inert.
+function escapeForDisplay(s: string): string {
+  // Show the string contents as-is; React already escapes < / > / & in
+  // text children, so this is a no-op transform that exists as a
+  // semantic marker — DO NOT switch to dangerouslySetInnerHTML here.
+  return s;
+}
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-admin-react"
-version = "1.0.3"
+version = "1.0.4"
 description = "A drop-in React single-page admin for Django, driven entirely by ModelAdmin."
 authors = ["django-admin-react contributors"]
 license = "MIT"
