@djangocfg/ui-tools 2.1.417 → 2.1.419

package/src/tools/dev/code/DiffViewer/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/ui-tools/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/tools/dev/code/DiffViewer/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/tools/dev/code/DiffViewer/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>
+  );
+});

package/src/tools/dev/code/DiffViewer/components/SplitView.tsx

@@ -0,0 +1,220 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import type { Language, PrismTheme } from 'prism-react-renderer';
+import { Virtuoso } from 'react-virtuoso';
+import { cn } from '@djangocfg/ui-core/lib';
+import { DIFF_TONE_CLASSES, type DiffLine } from '../types';
+import { DiffLineContent } from './DiffLineContent';
+
+interface SplitViewProps {
+  lines: DiffLine[];
+  numWidth: number;
+  language: Language | null;
+  prismTheme: PrismTheme;
+}
+
+// See UnifiedView for context — same threshold + viewport size keeps both
+// layouts behaviorally aligned.
+const VIRTUALIZE_THRESHOLD = 100;
+const VIRTUAL_VIEWPORT_HEIGHT = 480;
+
+/**
+ * Align consecutive `removed` / `added` runs into a pair of columns.
+ * Pure-add rows leave the left column empty; pure-remove rows leave the
+ * right column empty. Context rows duplicate on both sides.
+ *
+ * The pairing is the same shape jalcoui ships — we keep it so downstream
+ * consumers' visual baseline doesn't move.
+ */
+function pairLines(lines: DiffLine[]): Array<{
+  left: DiffLine | null;
+  right: DiffLine | null;
+}> {
+  const pairs: Array<{ left: DiffLine | null; right: DiffLine | null }> = [];
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.type === 'context') {
+      pairs.push({ left: line, right: line });
+      i++;
+      continue;
+    }
+    if (line.type === 'removed') {
+      const removed: DiffLine[] = [];
+      while (i < lines.length && lines[i].type === 'removed') {
+        removed.push(lines[i]);
+        i++;
+      }
+      const added: DiffLine[] = [];
+      while (i < lines.length && lines[i].type === 'added') {
+        added.push(lines[i]);
+        i++;
+      }
+      const maxLen = Math.max(removed.length, added.length);
+      for (let j = 0; j < maxLen; j++) {
+        pairs.push({
+          left: j < removed.length ? removed[j] : null,
+          right: j < added.length ? added[j] : null,
+        });
+      }
+      continue;
+    }
+    // line.type === 'added' with no preceding removed run
+    pairs.push({ left: null, right: line });
+    i++;
+  }
+
+  return pairs;
+}
+
+function sidePrefix(side: 'old' | 'new', type: DiffLine['type'] | undefined) {
+  if (!type || type === 'context') return ' ';
+  if (side === 'old' && type === 'removed') return '-';
+  if (side === 'new' && type === 'added') return '+';
+  return ' ';
+}
+
+interface HalfProps {
+  line: DiffLine | null;
+  side: 'old' | 'new';
+  numWidth: number;
+  language: Language | null;
+  prismTheme: PrismTheme;
+}
+
+function Half({ line, side, numWidth, language, prismTheme }: HalfProps) {
+  const tone = line ? DIFF_TONE_CLASSES[line.type] : DIFF_TONE_CLASSES.context;
+  const gutterCh = `calc(${numWidth}ch + 1rem)`;
+  return (
+    <div
+      className={cn('grid items-start min-w-0', tone.row)}
+      style={{
+        gridTemplateColumns: `${gutterCh} 1.5rem minmax(0, 1fr)`,
+      }}
+    >
+      <div
+        className={cn(
+          'select-none px-2 text-right tabular-nums whitespace-nowrap',
+          tone.num,
+        )}
+      >
+        {(side === 'old' ? line?.oldNumber : line?.newNumber) ?? ''}
+      </div>
+      <div
+        className={cn(
+          'select-none text-center whitespace-nowrap',
+          tone.num,
+        )}
+      >
+        {sidePrefix(side, line?.type)}
+      </div>
+      <div
+        className={cn(
+          'whitespace-pre px-3 overflow-x-auto',
+          line ? tone.text : 'text-muted-foreground/40',
+        )}
+      >
+        {line ? (
+          <DiffLineContent
+            content={line.content}
+            language={language}
+            prismTheme={prismTheme}
+          />
+        ) : (
+          ' '
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface PairRowProps {
+  pair: { left: DiffLine | null; right: DiffLine | null };
+  numWidth: number;
+  language: Language | null;
+  prismTheme: PrismTheme;
+}
+
+function PairRow({ pair, numWidth, language, prismTheme }: PairRowProps) {
+  return (
+    <div className="grid grid-cols-2 font-mono text-[13px] leading-relaxed">
+      <div className="border-r border-border/40 min-w-0">
+        <Half
+          line={pair.left}
+          side="old"
+          numWidth={numWidth}
+          language={language}
+          prismTheme={prismTheme}
+        />
+      </div>
+      <div className="min-w-0">
+        <Half
+          line={pair.right}
+          side="new"
+          numWidth={numWidth}
+          language={language}
+          prismTheme={prismTheme}
+        />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Side-by-side diff. Left half = old, right half = new. Each row is a
+ * single grid wrapping two `<Half>` halves so a `<Virtuoso>` list can
+ * virtualize the whole stack with naturally synchronized scrolling.
+ *
+ * Both halves receive the SAME globally-computed `numWidth` so the two
+ * gutter columns are pixel-identical regardless of which side has the
+ * longer line numbers.
+ */
+export function SplitView({
+  lines,
+  numWidth,
+  language,
+  prismTheme,
+}: SplitViewProps) {
+  const pairs = React.useMemo(() => pairLines(lines), [lines]);
+
+  if (pairs.length > VIRTUALIZE_THRESHOLD) {
+    return (
+      <div data-slot="diff-viewer-split">
+        <Virtuoso
+          data={pairs}
+          style={{ height: VIRTUAL_VIEWPORT_HEIGHT }}
+          // See UnifiedView for why `initialItemCount` is required —
+          // without it, embedded iframes start with a zero-height list.
+          initialItemCount={Math.min(pairs.length, 30)}
+          itemContent={(_, pair) => (
+            <PairRow
+              pair={pair}
+              numWidth={numWidth}
+              language={language}
+              prismTheme={prismTheme}
+            />
+          )}
+          increaseViewportBy={{ top: 200, bottom: 400 }}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div data-slot="diff-viewer-split">
+      {pairs.map((pair, idx) => (
+        <PairRow
+          key={idx}
+          pair={pair}
+          numWidth={numWidth}
+          language={language}
+          prismTheme={prismTheme}
+        />
+      ))}
+    </div>
+  );
+}

package/src/tools/dev/code/DiffViewer/components/UnifiedView.tsx

@@ -0,0 +1,154 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import type { Language, PrismTheme } from 'prism-react-renderer';
+import { Virtuoso } from 'react-virtuoso';
+import { cn } from '@djangocfg/ui-core/lib';
+import { DIFF_TONE_CLASSES, type DiffLine } from '../types';
+import { DiffLineContent } from './DiffLineContent';
+
+interface UnifiedViewProps {
+  lines: DiffLine[];
+  numWidth: number;
+  language: Language | null;
+  prismTheme: PrismTheme;
+}
+
+function linePrefix(type: DiffLine['type']) {
+  if (type === 'added') return '+';
+  if (type === 'removed') return '-';
+  return ' ';
+}
+
+// Threshold above which we switch from a plain DOM table to a virtualized
+// list. Mirrors LogViewer — under this size the DOM stays debuggable;
+// above it tokenization + layout of thousands of rows starts to dominate
+// scroll.
+const VIRTUALIZE_THRESHOLD = 100;
+// Height of the scrolling viewport when virtualized. Kept here (not a prop)
+// because every existing consumer expects the viewer to expand to its
+// content; only the >100-line path needs a fixed window to virtualize.
+const VIRTUAL_VIEWPORT_HEIGHT = 480;
+
+interface RowProps {
+  line: DiffLine;
+  numWidth: number;
+  language: Language | null;
+  prismTheme: PrismTheme;
+}
+
+/**
+ * One unified-diff row. CSS grid (not a table cell) so a `<Virtuoso>`
+ * list can virtualize identical rows without a host `<table>` (the
+ * `display: table-row-group` virtual scrollers force on `<tbody>` doesn't
+ * play with arbitrary row heights).
+ */
+function Row({ line, numWidth, language, prismTheme }: RowProps) {
+  const tone = DIFF_TONE_CLASSES[line.type];
+  const gutterCh = `calc(${numWidth}ch + 1rem)`;
+  return (
+    <div
+      className={cn(
+        'grid items-start font-mono text-[13px] leading-relaxed',
+        tone.row,
+      )}
+      style={{
+        gridTemplateColumns: `${gutterCh} ${gutterCh} 1.5rem 1fr`,
+      }}
+    >
+      <div
+        className={cn(
+          'select-none px-2 text-right tabular-nums whitespace-nowrap',
+          tone.num,
+        )}
+      >
+        {line.oldNumber ?? ''}
+      </div>
+      <div
+        className={cn(
+          'select-none px-2 text-right tabular-nums whitespace-nowrap',
+          tone.num,
+        )}
+      >
+        {line.newNumber ?? ''}
+      </div>
+      <div
+        className={cn(
+          'select-none text-center whitespace-nowrap',
+          tone.num,
+        )}
+      >
+        {linePrefix(line.type)}
+      </div>
+      <div className={cn('whitespace-pre px-3', tone.text)}>
+        <DiffLineContent
+          content={line.content}
+          language={language}
+          prismTheme={prismTheme}
+        />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Single-column unified diff. Two gutters on the left carry the old / new
+ * line numbers, the third (narrow) column is the +/-/space prefix, then
+ * the content. Background tint per row signals the change kind.
+ *
+ * The gutter widths come from the globally-computed `numWidth` (passed
+ * down from the viewer root). Using CSS grid with the same explicit
+ * `gridTemplateColumns` on every row guarantees pixel-identical gutters
+ * across all rows, even when content sizes vary.
+ *
+ * Diffs above {@link VIRTUALIZE_THRESHOLD} lines render through
+ * `<Virtuoso>` so 1k–10k-line diffs don't lock the main thread.
+ */
+export function UnifiedView({
+  lines,
+  numWidth,
+  language,
+  prismTheme,
+}: UnifiedViewProps) {
+  if (lines.length > VIRTUALIZE_THRESHOLD) {
+    return (
+      <div data-slot="diff-viewer-unified">
+        <Virtuoso
+          data={lines}
+          style={{ height: VIRTUAL_VIEWPORT_HEIGHT }}
+          // `initialItemCount` forces SSR-style initial render so rows
+          // appear immediately on first paint instead of waiting for
+          // ResizeObserver — without it, embedded iframes (Storybook,
+          // docs sites) sometimes start at zero height and the list
+          // stays empty until a window resize.
+          initialItemCount={Math.min(lines.length, 30)}
+          itemContent={(_, line) => (
+            <Row
+              line={line}
+              numWidth={numWidth}
+              language={language}
+              prismTheme={prismTheme}
+            />
+          )}
+          increaseViewportBy={{ top: 200, bottom: 400 }}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div data-slot="diff-viewer-unified">
+      {lines.map((line, i) => (
+        <Row
+          key={i}
+          line={line}
+          numWidth={numWidth}
+          language={language}
+          prismTheme={prismTheme}
+        />
+      ))}
+    </div>
+  );
+}

package/src/tools/dev/code/DiffViewer/hooks/useDiff.ts

@@ -0,0 +1,47 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import { useMemo } from 'react';
+import {
+  computeStats,
+  diffLines,
+  lineNumberWidth,
+  parseUnifiedPatch,
+} from '../utils/computeDiff';
+import type { DiffInput, DiffLine, DiffStats } from '../types';
+
+interface UseDiffOptions {
+  input: DiffInput;
+  /** Context lines around each change-hunk. @default 3 */
+  context?: number;
+}
+
+interface UseDiffResult {
+  lines: DiffLine[];
+  numWidth: number;
+  stats: DiffStats;
+}
+
+/**
+ * Memoize the diff computation so a re-render of the viewer (e.g. tab
+ * switch, header copy click) doesn't re-run the LCS. The dependency
+ * surface intentionally narrows to the two input strings / patch — the
+ * `context` knob too, since a different window emits a different line
+ * list.
+ */
+export function useDiff({ input, context = 3 }: UseDiffOptions): UseDiffResult {
+  const isPatch = 'patch' in input && typeof input.patch === 'string';
+  const oldCode = isPatch ? '' : input.oldCode;
+  const newCode = isPatch ? '' : input.newCode;
+  const patch = isPatch ? (input as { patch: string }).patch : '';
+
+  return useMemo(() => {
+    const lines = isPatch
+      ? parseUnifiedPatch(patch)
+      : diffLines(oldCode, newCode, context);
+    return {
+      lines,
+      numWidth: lineNumberWidth(lines),
+      stats: computeStats(lines),
+    };
+  }, [isPatch, patch, oldCode, newCode, context]);
+}

package/src/tools/dev/code/DiffViewer/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 '../../PrettyCode/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/tools/dev/code/DiffViewer/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/tools/dev/code/DiffViewer/lazy.tsx

@@ -0,0 +1,22 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { createLazyComponent } from '../../../../common/lazy-wrapper';
+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"
+      />
+    ),
+  },
+);
+
+export type { DiffViewerProps } from './types';