@djangocfg/ui-tools 2.1.418 → 2.1.419

package/src/tools/dev/api/RequestViewer/RequestViewer.tsx

@@ -0,0 +1,121 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Lightweight HTTP inspector — headers / body / timing in tabs. Renders an
+// already-executed request/response object; never fetches. For an
+// interactive request playground, use OpenapiViewer instead.
+//
+// Requires <UiProviders> mounted at the host root (Tabs use Radix primitives).
+
+'use client';
+
+import * as React from 'react';
+import { Clock, FileText, Globe, Activity } from 'lucide-react';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@djangocfg/ui-core';
+import { cn } from '@djangocfg/ui-core/lib';
+import { methodColor, statusColor } from '../../../../lib/http';
+import {
+  METHOD_TONE_TEXT,
+  STATUS_TONE_PILL,
+  type RequestViewerProps,
+  type RequestViewerTab,
+} from './types';
+import { HeadersTab } from './components/HeadersTab';
+import { BodyTab } from './components/BodyTab';
+import { TimingTab } from './components/TimingTab';
+import { formatDuration } from './components/utils';
+
+export function RequestViewer({
+  request,
+  defaultTab = 'headers',
+  className,
+  ...props
+}: RequestViewerProps) {
+  const headerCount =
+    (request.requestHeaders?.length ?? 0) +
+    (request.responseHeaders?.length ?? 0);
+  const timingCount = request.timing?.length ?? 0;
+
+  const methodToneCls = METHOD_TONE_TEXT[methodColor(request.method)];
+  const statusToneCls = STATUS_TONE_PILL[statusColor(request.status)];
+
+  return (
+    <div
+      data-slot="request-viewer"
+      className={cn(
+        'overflow-hidden rounded-xl border border-border/60 bg-card shadow-sm',
+        className,
+      )}
+      {...props}
+    >
+      {/* Request summary */}
+      <div className="flex flex-wrap items-center gap-3 border-b border-border/40 px-4 py-3">
+        <span
+          className={cn(
+            'font-mono text-sm font-bold uppercase',
+            methodToneCls,
+          )}
+        >
+          {request.method}
+        </span>
+        <span className="min-w-0 flex-1 truncate font-mono text-sm text-muted-foreground">
+          {request.url}
+        </span>
+        <span
+          className={cn(
+            'inline-flex items-center rounded-md px-2.5 py-0.5 font-mono text-xs font-semibold',
+            statusToneCls,
+          )}
+        >
+          {request.status}
+          {request.statusText ? ` ${request.statusText}` : null}
+        </span>
+        {request.duration !== undefined && (
+          <span className="inline-flex items-center gap-1 text-xs text-muted-foreground">
+            <Clock className="size-3" />
+            {formatDuration(request.duration)}
+          </span>
+        )}
+      </div>
+
+      {/* Tabs */}
+      <Tabs defaultValue={defaultTab satisfies RequestViewerTab}>
+        <div className="border-b border-border/40 bg-muted/20 px-2 pt-2">
+          <TabsList variant="underline">
+            <TabsTrigger value="headers">
+              <FileText className="size-3.5 mr-1.5" />
+              Headers
+              {headerCount > 0 && (
+                <span className="ml-1.5 rounded-full bg-muted px-1.5 py-0.5 text-[10px] font-semibold leading-none">
+                  {headerCount}
+                </span>
+              )}
+            </TabsTrigger>
+            <TabsTrigger value="body">
+              <Globe className="size-3.5 mr-1.5" />
+              Body
+            </TabsTrigger>
+            <TabsTrigger value="timing">
+              <Activity className="size-3.5 mr-1.5" />
+              Timing
+              {timingCount > 0 && (
+                <span className="ml-1.5 rounded-full bg-muted px-1.5 py-0.5 text-[10px] font-semibold leading-none">
+                  {timingCount}
+                </span>
+              )}
+            </TabsTrigger>
+          </TabsList>
+        </div>
+
+        <TabsContent value="headers" className="mt-0">
+          <HeadersTab request={request} />
+        </TabsContent>
+        <TabsContent value="body" className="mt-0">
+          <BodyTab request={request} />
+        </TabsContent>
+        <TabsContent value="timing" className="mt-0">
+          <TimingTab request={request} />
+        </TabsContent>
+      </Tabs>
+    </div>
+  );
+}

package/src/tools/dev/api/RequestViewer/components/BodyTab.tsx

@@ -0,0 +1,44 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import { JsonTree } from '../../../../data/JsonTree';
+import type { NetworkRequest } from '../types';
+import { byteSize, looksLikeJson, tryParseJson } from './utils';
+import { EmptyState } from './EmptyState';
+
+export function BodyTab({ request }: { request: NetworkRequest }) {
+  if (!request.responseBody) {
+    return <EmptyState message="No response body available." />;
+  }
+
+  const declaredJson = request.contentType?.toLowerCase().includes('json');
+  const isJson = declaredJson || looksLikeJson(request.responseBody);
+  const parsed = isJson ? tryParseJson(request.responseBody) : null;
+
+  return (
+    <div className="flex flex-col gap-2 p-4">
+      {request.contentType && (
+        <div className="flex items-center gap-2">
+          <span className="rounded-md bg-muted px-2 py-0.5 font-mono text-[10px] font-medium text-muted-foreground">
+            {request.contentType}
+          </span>
+          <span className="text-[10px] text-muted-foreground">
+            {byteSize(request.responseBody)}
+          </span>
+        </div>
+      )}
+      {parsed !== null ? (
+        // JsonTree provides collapsible tree + search/copy for structured bodies.
+        <JsonTree data={parsed} bordered toolbar="always" compactHeader />
+      ) : (
+        <div className="overflow-auto rounded-lg border border-border/60 bg-muted/30">
+          <pre className="p-4 text-xs leading-relaxed text-foreground">
+            <code>{request.responseBody}</code>
+          </pre>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/tools/dev/api/RequestViewer/components/EmptyState.tsx

@@ -0,0 +1,13 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+
+export function EmptyState({ message }: { message: string }) {
+  return (
+    <div className="flex items-center justify-center py-10 text-sm text-muted-foreground">
+      {message}
+    </div>
+  );
+}

package/src/tools/dev/api/RequestViewer/components/HeadersTab.tsx

@@ -0,0 +1,78 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import { ArrowDown, ArrowUp, type LucideIcon } from 'lucide-react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { HeaderEntry, NetworkRequest } from '../types';
+import { EmptyState } from './EmptyState';
+
+function HeadersTable({
+  title,
+  headers,
+  icon: Icon,
+}: {
+  title: string;
+  headers: HeaderEntry[];
+  icon: LucideIcon;
+}) {
+  if (headers.length === 0) return null;
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center gap-1.5">
+        <Icon className="size-3.5 text-muted-foreground" />
+        <h4 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+          {title}
+        </h4>
+      </div>
+      <div className="overflow-hidden rounded-lg border border-border/60">
+        {headers.map((header, i) => (
+          <div
+            key={`${header.name}-${i}`}
+            className={cn(
+              'flex gap-4 px-3 py-2 text-sm',
+              i !== headers.length - 1 && 'border-b border-border/40',
+            )}
+          >
+            <span className="w-[200px] shrink-0 truncate font-mono text-xs font-medium text-foreground">
+              {header.name}
+            </span>
+            <span className="min-w-0 flex-1 break-all font-mono text-xs text-muted-foreground">
+              {header.value}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function HeadersTab({ request }: { request: NetworkRequest }) {
+  const hasRequest = (request.requestHeaders?.length ?? 0) > 0;
+  const hasResponse = (request.responseHeaders?.length ?? 0) > 0;
+
+  if (!hasRequest && !hasResponse) {
+    return <EmptyState message="No headers available." />;
+  }
+
+  return (
+    <div className="flex flex-col gap-5 p-4">
+      {hasRequest && (
+        <HeadersTable
+          title="Request Headers"
+          headers={request.requestHeaders!}
+          icon={ArrowUp}
+        />
+      )}
+      {hasResponse && (
+        <HeadersTable
+          title="Response Headers"
+          headers={request.responseHeaders!}
+          icon={ArrowDown}
+        />
+      )}
+    </div>
+  );
+}

package/src/tools/dev/api/RequestViewer/components/TimingTab.tsx

@@ -0,0 +1,113 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import { useStylePresets } from '@djangocfg/ui-core/styles/palette';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { NetworkRequest } from '../types';
+import { EmptyState } from './EmptyState';
+import { formatDuration } from './utils';
+
+/**
+ * Categorical palette for timing phases (DNS, TCP, TLS, …). Stages are not
+ * statuses, so we route through `useStylePresets()` — 8 distinguishable hex
+ * colors that respect the active theme. Indices wrap modulo length.
+ */
+function useStagePalette(): string[] {
+  const presets = useStylePresets();
+  return React.useMemo(
+    () => [
+      presets.primary.fill,
+      presets.success.fill,
+      presets.warning.fill,
+      presets.danger.fill,
+      presets.info.fill,
+      presets.chart3.fill,
+      presets.chart4.fill,
+      presets.chart5.fill,
+    ],
+    [presets],
+  );
+}
+
+export function TimingTab({ request }: { request: NetworkRequest }) {
+  const stagePalette = useStagePalette();
+
+  if (!request.timing || request.timing.length === 0) {
+    return <EmptyState message="No timing data available." />;
+  }
+
+  const timing = request.timing;
+  const maxDuration = Math.max(...timing.map((t) => t.duration));
+  const totalDuration =
+    request.duration ?? timing.reduce((sum, t) => sum + t.duration, 0);
+
+  return (
+    <div className="flex flex-col gap-4 p-4">
+      {/* Total */}
+      <div className="flex items-baseline justify-between">
+        <span className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+          Total Duration
+        </span>
+        <span className="font-mono text-sm font-semibold text-foreground">
+          {formatDuration(totalDuration)}
+        </span>
+      </div>
+
+      {/* Waterfall */}
+      <div className="flex flex-col gap-2.5">
+        {timing.map((entry, i) => {
+          const percentage =
+            maxDuration > 0 ? (entry.duration / maxDuration) * 100 : 0;
+          const color = stagePalette[i % stagePalette.length];
+
+          return (
+            <div
+              key={`${entry.label}-${i}`}
+              className="flex items-center gap-3"
+            >
+              <span className="w-[120px] shrink-0 truncate text-xs text-muted-foreground">
+                {entry.label}
+              </span>
+              <div className="relative h-5 flex-1 overflow-hidden rounded-md bg-muted/50">
+                <div
+                  className={cn('h-full rounded-md transition-all')}
+                  style={{
+                    width: `${Math.max(percentage, 2)}%`,
+                    opacity: percentage === 0 ? 0.3 : 1,
+                    backgroundColor: color,
+                  }}
+                />
+              </div>
+              <span className="w-[64px] shrink-0 text-right font-mono text-xs text-muted-foreground">
+                {formatDuration(entry.duration)}
+              </span>
+            </div>
+          );
+        })}
+      </div>
+
+      {/* Legend */}
+      <div className="flex flex-wrap gap-3 border-t border-border/40 pt-3">
+        {timing.map((entry, i) => {
+          const color = stagePalette[i % stagePalette.length];
+          return (
+            <div
+              key={`legend-${entry.label}-${i}`}
+              className="flex items-center gap-1.5"
+            >
+              <span
+                className="size-2.5 rounded-full"
+                style={{ backgroundColor: color }}
+              />
+              <span className="text-[10px] text-muted-foreground">
+                {entry.label}
+              </span>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/src/tools/dev/api/RequestViewer/components/utils.ts

@@ -0,0 +1,31 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+/** Format milliseconds for human reading: µs / ms / s. */
+export function formatDuration(ms: number): string {
+  if (ms < 1) return `${(ms * 1000).toFixed(0)}µs`;
+  if (ms < 1000) return `${ms.toFixed(ms < 10 ? 1 : 0)}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+export function byteSize(str: string): string {
+  const bytes = new Blob([str]).size;
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export function looksLikeJson(str: string): boolean {
+  const trimmed = str.trim();
+  return (
+    (trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+    (trimmed.startsWith('[') && trimmed.endsWith(']'))
+  );
+}
+
+export function tryParseJson(str: string): unknown | null {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return null;
+  }
+}

package/src/tools/dev/api/RequestViewer/index.ts

@@ -0,0 +1,16 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { RequestViewer } from './RequestViewer';
+export {
+  STATUS_TONE_PILL,
+  METHOD_TONE_TEXT,
+} from './types';
+export type {
+  RequestViewerProps,
+  RequestViewerTab,
+  NetworkRequest,
+  HeaderEntry,
+  TimingEntry,
+  HttpMethodTone,
+  HttpStatusTone,
+} from './types';

package/src/tools/dev/api/RequestViewer/lazy.tsx

@@ -0,0 +1,30 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { createLazyComponent } from '../../../../common/lazy-wrapper';
+import type { RequestViewerProps } from './types';
+
+export const LazyRequestViewer = createLazyComponent<RequestViewerProps>(
+  () =>
+    import('./RequestViewer').then((mod) => ({
+      default: mod.RequestViewer,
+    })),
+  {
+    displayName: 'LazyRequestViewer',
+    fallback: (
+      <div
+        data-slot="request-viewer-skeleton"
+        className="h-64 w-full animate-pulse rounded-xl bg-muted"
+      />
+    ),
+  },
+);
+
+export type {
+  RequestViewerProps,
+  RequestViewerTab,
+  NetworkRequest,
+  HeaderEntry,
+  TimingEntry,
+} from './types';

package/src/tools/dev/api/RequestViewer/types.ts

@@ -0,0 +1,81 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type * as React from 'react';
+import type { HttpMethodTone, HttpStatusTone } from '../../../../lib/http';
+
+/** Single key/value header pair. */
+export interface HeaderEntry {
+  name: string;
+  value: string;
+}
+
+/** A timing phase for the request lifecycle (DNS, TCP, TLS, …). */
+export interface TimingEntry {
+  /** Label for this timing phase (e.g. "DNS Lookup", "TLS Handshake"). */
+  label: string;
+  /** Duration in milliseconds. */
+  duration: number;
+}
+
+/**
+ * A captured network request — already-executed. The viewer never fetches.
+ */
+export interface NetworkRequest {
+  /** HTTP method (GET, POST, etc.). Case-insensitive. */
+  method: string;
+  /** Full request URL. */
+  url: string;
+  /** HTTP status code. */
+  status: number;
+  /** HTTP status text (e.g. "OK", "Not Found"). */
+  statusText?: string;
+  /** Request headers. */
+  requestHeaders?: HeaderEntry[];
+  /** Response headers. */
+  responseHeaders?: HeaderEntry[];
+  /** Response body as a string (raw text or JSON-encoded text). */
+  responseBody?: string;
+  /** Content type of the response (used for display hints). */
+  contentType?: string;
+  /** Timing breakdown for the request lifecycle. */
+  timing?: TimingEntry[];
+  /** Total request duration in milliseconds. */
+  duration?: number;
+}
+
+export type RequestViewerTab = 'headers' | 'body' | 'timing';
+
+export interface RequestViewerProps
+  extends Omit<React.ComponentProps<'div'>, 'children'> {
+  /** Network request data to display. */
+  request: NetworkRequest;
+  /** Initial active tab. Defaults to "headers". */
+  defaultTab?: RequestViewerTab;
+}
+
+// Re-export the HTTP tone types for callers that need them.
+export type { HttpMethodTone, HttpStatusTone };
+
+/**
+ * Map an HTTP status tone → background+text class pair for the status pill.
+ * Uses opacity-derived surfaces so every theme preset renders correctly
+ * even when `--{status}-background` is undefined.
+ */
+export const STATUS_TONE_PILL: Record<HttpStatusTone, string> = {
+  success: 'bg-success/15 text-success',
+  info: 'bg-info/15 text-info',
+  warning: 'bg-warning/15 text-warning',
+  destructive: 'bg-destructive/15 text-destructive',
+  muted: 'bg-muted text-muted-foreground',
+};
+
+/**
+ * Map an HTTP method tone → text-only class. Method label has no background.
+ */
+export const METHOD_TONE_TEXT: Record<HttpMethodTone, string> = {
+  success: 'text-success',
+  info: 'text-info',
+  warning: 'text-warning',
+  destructive: 'text-destructive',
+  muted: 'text-muted-foreground',
+};

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

@@ -0,0 +1,144 @@
+// 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,
+  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 });
+
+  // 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}
+            language={resolvedLanguage}
+            prismTheme={prismTheme}
+          />
+        ) : (
+          <UnifiedView
+            lines={lines}
+            numWidth={numWidth}
+            language={resolvedLanguage}
+            prismTheme={prismTheme}
+          />
+        )}
+      </div>
+    </div>
+  );
+}