@djangocfg/ui-tools 2.1.418 → 2.1.419

package/src/tools/dev/ops/LogViewer/components/Toolbar.tsx

@@ -0,0 +1,199 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import {
+  ArrowDownToLine,
+  Circle,
+  Pause,
+  Play,
+  Search,
+  Terminal,
+  Trash2,
+  X,
+} from 'lucide-react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { LogLevel } from '../types';
+import { LEVEL_LABELS, getLevelToneClasses } from '../types';
+
+interface ToolbarButtonProps {
+  onClick: () => void;
+  label: string;
+  active?: boolean;
+  children: React.ReactNode;
+}
+
+function ToolbarButton({ onClick, label, active, children }: ToolbarButtonProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label={label}
+      aria-pressed={active}
+      className={cn(
+        'inline-flex size-7 items-center justify-center rounded-md outline-none transition-colors',
+        'text-muted-foreground hover:bg-accent hover:text-accent-foreground',
+        'focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+        active && 'bg-accent text-accent-foreground',
+      )}
+    >
+      {children}
+    </button>
+  );
+}
+
+export interface ToolbarProps {
+  title: string;
+  totalCount: number;
+  filteredCount: number;
+  levels: LogLevel[];
+  activeLevels: Set<LogLevel>;
+  toggleLevel: (level: LogLevel) => void;
+  levelCounts: Partial<Record<LogLevel, number>>;
+  searchQuery: string;
+  setSearchQuery: (q: string) => void;
+  autoScrollEnabled: boolean;
+  paused: boolean;
+  setPaused: (p: boolean) => void;
+  onClear?: () => void;
+}
+
+/**
+ * Header + filter row for the LogViewer. The level chips also serve as
+ * the count badges — clicking strikes them out and removes the level
+ * from the active set. The search input is always visible (no expand /
+ * collapse toggle) because filter and search are the two main jobs of
+ * the toolbar; hiding either is friction.
+ */
+export function Toolbar({
+  title,
+  totalCount,
+  filteredCount,
+  levels,
+  activeLevels,
+  toggleLevel,
+  levelCounts,
+  searchQuery,
+  setSearchQuery,
+  autoScrollEnabled,
+  paused,
+  setPaused,
+  onClear,
+}: ToolbarProps) {
+  return (
+    <div className="flex flex-col gap-2 border-b border-border/40 bg-muted/30 px-3 py-2">
+      <div className="flex items-center gap-2">
+        <Terminal className="size-3.5 shrink-0 text-muted-foreground" />
+        <span className="flex-1 truncate text-sm font-medium text-foreground">
+          {title}
+        </span>
+
+        <span className="mr-1 text-[10px] tabular-nums text-muted-foreground">
+          {filteredCount}
+          {filteredCount !== totalCount && ` / ${totalCount}`} lines
+        </span>
+
+        <div className="flex items-center gap-0.5">
+          {autoScrollEnabled && (
+            <ToolbarButton
+              onClick={() => setPaused(!paused)}
+              label={paused ? 'Resume auto-scroll' : 'Pause auto-scroll'}
+              active={paused}
+            >
+              {paused ? (
+                <Play className="size-3.5" />
+              ) : (
+                <Pause className="size-3.5" />
+              )}
+            </ToolbarButton>
+          )}
+
+          {onClear && (
+            <ToolbarButton onClick={onClear} label="Clear logs">
+              <Trash2 className="size-3.5" />
+            </ToolbarButton>
+          )}
+        </div>
+      </div>
+
+      <div className="flex flex-wrap items-center gap-2">
+        <div className="flex flex-wrap items-center gap-1">
+          {levels.map((level) => {
+            const tone = getLevelToneClasses(level);
+            const isActive = activeLevels.has(level);
+            const count = levelCounts[level] ?? 0;
+            return (
+              <button
+                key={level}
+                type="button"
+                onClick={() => toggleLevel(level)}
+                role="checkbox"
+                aria-checked={isActive}
+                aria-label={`${isActive ? 'Hide' : 'Show'} ${level} logs`}
+                className={cn(
+                  'inline-flex items-center gap-1 rounded-md px-2 py-1 text-[11px] font-medium outline-none transition-colors',
+                  'focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+                  isActive
+                    ? tone.badge
+                    : 'bg-muted/50 text-muted-foreground/60 line-through',
+                )}
+              >
+                <Circle
+                  className={cn(
+                    'size-1.5 fill-current',
+                    isActive ? tone.text : 'text-muted-foreground/40',
+                  )}
+                />
+                {LEVEL_LABELS[level]}
+                {count > 0 && <span className="tabular-nums">{count}</span>}
+              </button>
+            );
+          })}
+        </div>
+
+        <div className="ml-auto flex items-center gap-1.5 rounded-md border border-border/40 bg-background px-2 py-1">
+          <Search className="size-3 text-muted-foreground" />
+          <input
+            type="text"
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
+            placeholder="Filter…"
+            aria-label="Filter logs"
+            className="w-32 bg-transparent text-xs text-foreground outline-none placeholder:text-muted-foreground sm:w-40"
+          />
+          {searchQuery && (
+            <button
+              type="button"
+              onClick={() => setSearchQuery('')}
+              className="inline-flex size-4 items-center justify-center rounded text-muted-foreground hover:text-foreground"
+              aria-label="Clear search"
+            >
+              <X className="size-3" />
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export interface ScrollToBottomPillProps {
+  visible: boolean;
+  onClick: () => void;
+}
+
+export function ScrollToBottomPill({ visible, onClick }: ScrollToBottomPillProps) {
+  if (!visible) return null;
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="flex w-full items-center justify-center gap-1.5 border-t border-border/40 bg-muted/30 py-1.5 text-[10px] font-medium text-muted-foreground transition-colors hover:bg-muted/50 hover:text-foreground"
+      aria-label="Scroll to latest"
+    >
+      <ArrowDownToLine className="size-3" />
+      New logs below
+    </button>
+  );
+}

package/src/tools/dev/ops/LogViewer/hooks/useAutoScroll.ts

@@ -0,0 +1,68 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import type { VirtuosoHandle } from 'react-virtuoso';
+
+/**
+ * Sticky-bottom controller for the virtualized log list. Tracks whether
+ * the viewport is pinned to the latest entry; when it is and a new entry
+ * arrives, jumps to the end via Virtuoso's `scrollToIndex`. When the
+ * user has scrolled up, the controller stays out of the way and exposes
+ * `scrollToBottom` so the UI can offer a "Jump to latest" pill.
+ *
+ * The previous (DOM-scroll) implementation set `scrollTop = scrollHeight`
+ * inside an effect. That works for a non-virtualized list but fights
+ * Virtuoso, which owns the scroller. We instead use Virtuoso's
+ * `atBottomStateChange` callback (fired with hysteresis) and call
+ * `scrollToIndex` when new entries land while we're pinned.
+ */
+export interface UseAutoScrollResult {
+  virtuosoRef: React.RefObject<VirtuosoHandle | null>;
+  isAtBottom: boolean;
+  /** Wire to Virtuoso's `atBottomStateChange`. */
+  onAtBottomChange: (atBottom: boolean) => void;
+  /** Jump to the end of the list. Used by the "New logs below" pill. */
+  scrollToBottom: () => void;
+}
+
+export function useAutoScroll(
+  entryCount: number,
+  enabled: boolean,
+): UseAutoScrollResult {
+  const virtuosoRef = React.useRef<VirtuosoHandle | null>(null);
+  const [isAtBottom, setIsAtBottom] = React.useState(true);
+  const isAtBottomRef = React.useRef(true);
+  const lastCountRef = React.useRef(entryCount);
+
+  const onAtBottomChange = React.useCallback((atBottom: boolean) => {
+    isAtBottomRef.current = atBottom;
+    setIsAtBottom(atBottom);
+  }, []);
+
+  const scrollToBottom = React.useCallback(() => {
+    const handle = virtuosoRef.current;
+    if (!handle) return;
+    // `LAST` is Virtuoso's sentinel for "bottom".
+    handle.scrollToIndex({ index: 'LAST', behavior: 'auto' });
+    isAtBottomRef.current = true;
+    setIsAtBottom(true);
+  }, []);
+
+  React.useEffect(() => {
+    const prev = lastCountRef.current;
+    lastCountRef.current = entryCount;
+    if (!enabled) return;
+    if (entryCount <= prev) return; // shrink / no-op
+    if (!isAtBottomRef.current) return;
+    // Defer one frame so Virtuoso settles the new row's height first;
+    // otherwise the jump lands one row short on the very first append.
+    const id = requestAnimationFrame(() => {
+      virtuosoRef.current?.scrollToIndex({ index: 'LAST', behavior: 'auto' });
+    });
+    return () => cancelAnimationFrame(id);
+  }, [entryCount, enabled]);
+
+  return { virtuosoRef, isAtBottom, onAtBottomChange, scrollToBottom };
+}

package/src/tools/dev/ops/LogViewer/hooks/useLogFilter.ts

@@ -0,0 +1,58 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import type { LogEntry, LogLevel } from '../types';
+import { stripAnsi } from '../utils/ansi';
+
+interface UseLogFilterArgs {
+  entries: LogEntry[];
+  activeLevels: Set<LogLevel>;
+  searchQuery: string;
+}
+
+interface UseLogFilterResult {
+  filtered: LogEntry[];
+  /** Counts per level for the **unfiltered** entries — feeds the filter
+   * chip badges. */
+  counts: Partial<Record<LogLevel, number>>;
+}
+
+/**
+ * Filter + search the entry list. Both operations route through one
+ * pass over `entries` so a 10k-entry list with both filters active
+ * costs one iteration, not two. The result is memoized on the input
+ * identity — callers that only append to `entries` get an incremental
+ * O(n) re-derivation (acceptable for 10k+; if it ever bites, switch
+ * to a streaming filter that reuses the prior result).
+ *
+ * Search is case-insensitive and strips ANSI escapes from the haystack
+ * — a search for `"port 3000"` matches `\x1b[32mport 3000\x1b[0m` too.
+ */
+export function useLogFilter({
+  entries,
+  activeLevels,
+  searchQuery,
+}: UseLogFilterArgs): UseLogFilterResult {
+  return React.useMemo(() => {
+    const counts: Partial<Record<LogLevel, number>> = {};
+    const filtered: LogEntry[] = [];
+    const needle = searchQuery.trim().toLowerCase();
+    const hasSearch = needle.length > 0;
+
+    for (let i = 0; i < entries.length; i += 1) {
+      const entry = entries[i];
+      counts[entry.level] = (counts[entry.level] ?? 0) + 1;
+
+      if (!activeLevels.has(entry.level)) continue;
+      if (hasSearch) {
+        const haystack = stripAnsi(entry.message).toLowerCase();
+        if (!haystack.includes(needle)) continue;
+      }
+      filtered.push(entry);
+    }
+
+    return { filtered, counts };
+  }, [entries, activeLevels, searchQuery]);
+}

package/src/tools/dev/ops/LogViewer/index.ts

@@ -0,0 +1,18 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { LogViewer } from './LogViewer';
+export {
+  LEVEL_LABELS,
+  LEVEL_TONE,
+  TONE_CLASSES as LOG_TONE_CLASSES,
+  getLevelToneClasses,
+} from './types';
+export type {
+  LogEntry,
+  LogLevel,
+  LogTone,
+  LogToneClasses,
+  LogViewerProps,
+} from './types';
+export { parseAnsi, stripAnsi } from './utils/ansi';
+export type { AnsiSegment } from './utils/ansi';

package/src/tools/dev/ops/LogViewer/lazy.tsx

@@ -0,0 +1,25 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { createLazyComponent } from '../../../../common/lazy-wrapper';
+import type { LogViewerProps } from './types';
+
+export const LazyLogViewer = createLazyComponent<LogViewerProps>(
+  () => import('./LogViewer').then((mod) => ({ default: mod.LogViewer })),
+  {
+    displayName: 'LazyLogViewer',
+    fallback: (
+      <div
+        data-slot="log-viewer-skeleton"
+        className="flex h-[400px] w-full animate-pulse flex-col gap-2 rounded-xl border border-border/60 bg-card p-3"
+      >
+        <div className="h-7 w-1/3 rounded bg-muted" />
+        <div className="h-5 w-2/3 rounded bg-muted" />
+        <div className="flex-1 rounded bg-muted/60" />
+      </div>
+    ),
+  },
+);
+
+export type { LogViewerProps } from './types';

package/src/tools/dev/ops/LogViewer/types.ts

@@ -0,0 +1,142 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type * as React from 'react';
+
+/**
+ * Severity level of a log entry. Five canonical levels — `error`, `warn`,
+ * `info`, `debug` route to status / categorical semantic tokens; `verbose`
+ * collapses to muted.
+ */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'verbose';
+
+/**
+ * Tone bucket each level resolves to. `debug` is intentionally **not** a
+ * status — it routes through a categorical preset color so themes can
+ * rotate it without polluting the destructive/warning/info/success
+ * palette.
+ */
+export type LogTone = 'destructive' | 'warning' | 'info' | 'debug' | 'muted';
+
+export interface LogEntry {
+  /** Severity. */
+  level: LogLevel;
+  /** Log message text. May contain ANSI escape sequences. */
+  message: string;
+  /** ISO timestamp string. When omitted, the current time is used for display. */
+  timestamp?: string;
+}
+
+/**
+ * Tone CSS class bundle per `LogTone`. Every class resolves to a semantic
+ * token (no raw color scales). `dot` and `text` ride on opacity-derived
+ * surfaces so they survive every preset that overrides only the base
+ * `--{status}` token.
+ */
+export interface LogToneClasses {
+  /** Text color for the level label / icon. */
+  text: string;
+  /** Background for the filled dot. */
+  dot: string;
+  /** Badge surface when the level filter is active. */
+  badge: string;
+}
+
+/**
+ * Mapping from {@link LogLevel} to {@link LogTone}. `debug` collapses to
+ * the categorical `debug` tone — it is not a status.
+ */
+export const LEVEL_TONE: Record<LogLevel, LogTone> = {
+  error: 'destructive',
+  warn: 'warning',
+  info: 'info',
+  debug: 'debug',
+  verbose: 'muted',
+};
+
+/**
+ * Short 3-letter labels rendered in monospace gutters. Matches `ERR`,
+ * `WRN`, `INF`, `DBG`, `VRB` so columns align on screen.
+ */
+export const LEVEL_LABELS: Record<LogLevel, string> = {
+  error: 'ERR',
+  warn: 'WRN',
+  info: 'INF',
+  debug: 'DBG',
+  verbose: 'VRB',
+};
+
+/**
+ * Semantic-token class bundle per {@link LogTone}. All `bg-` / `text-`
+ * values resolve through ui-core tokens — themes can swap them without
+ * touching this file. `debug` uses a violet-ish categorical via the
+ * `--chart-4`/`--chart-5` fallbacks already shipped in ui-core (we keep
+ * it on the `muted` family for surface and lean on opacity for
+ * differentiation; the actual debug color comes from the level dot in
+ * the source).
+ */
+export const TONE_CLASSES: Record<LogTone, LogToneClasses> = {
+  destructive: {
+    text: 'text-destructive',
+    dot: 'bg-destructive',
+    badge: 'bg-destructive/15 text-destructive',
+  },
+  warning: {
+    text: 'text-warning',
+    dot: 'bg-warning',
+    badge: 'bg-warning/15 text-warning',
+  },
+  info: {
+    text: 'text-info',
+    dot: 'bg-info',
+    badge: 'bg-info/15 text-info',
+  },
+  // `debug` is categorical, not status — render via primary token tinted
+  // for legibility; themes that recolour `--primary` get a free debug
+  // shift without touching this file.
+  debug: {
+    text: 'text-primary',
+    dot: 'bg-primary',
+    badge: 'bg-primary/15 text-primary',
+  },
+  muted: {
+    text: 'text-muted-foreground',
+    dot: 'bg-muted-foreground/60',
+    badge: 'bg-muted text-muted-foreground',
+  },
+};
+
+/**
+ * Resolve the tone class bundle for a level.
+ */
+export function getLevelToneClasses(level: LogLevel): LogToneClasses {
+  return TONE_CLASSES[LEVEL_TONE[level]];
+}
+
+export interface LogViewerProps
+  extends Omit<React.ComponentProps<'div'>, 'children' | 'title'> {
+  /** Log entries to render. */
+  entries: LogEntry[];
+  /** Header title. @default "Logs" */
+  title?: string;
+  /** Maximum visible height in pixels. @default 400 */
+  maxHeight?: number;
+  /** Show monospace line numbers. @default true */
+  lineNumbers?: boolean;
+  /** Show timestamps. @default true */
+  timestamps?: boolean;
+  /** Auto-scroll to bottom when new entries arrive (and the user is
+   * already pinned to the bottom). @default true */
+  autoScroll?: boolean;
+  /** Levels exposed in the toolbar filter chips. @default all five */
+  levels?: LogLevel[];
+  /** Interpret ANSI escape sequences (`\x1b[31m…`) in `message`.
+   * @default true */
+  ansi?: boolean;
+  /** Optional callback wired to the "Clear" toolbar button — when
+   * omitted, the button is hidden. */
+  onClear?: () => void;
+  /** Force-disable virtualization (small / Storybook usage). The
+   * virtualized path uses `react-virtuoso` and handles 10k+ entries
+   * without lag. @default false */
+  noVirtualize?: boolean;
+}