@djangocfg/ui-tools 2.1.417 → 2.1.419

package/src/tools/dev/ops/EnvTable/hooks/useEnvMask.ts

@@ -0,0 +1,121 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import type { EnvVariable } from '../types';
+
+const COPY_FEEDBACK_MS = 1500;
+
+/**
+ * Mask the value for display. Reveals the first 4 chars only when the value
+ * is long enough — the raw `value` never leaks to the DOM in masked state.
+ */
+export function maskValue(value: string): string {
+  if (value.length <= 4) return '••••••••';
+  return value.slice(0, 4) + '••••••••';
+}
+
+export interface UseEnvMaskOptions {
+  variables: EnvVariable[];
+  defaultRevealed?: boolean;
+}
+
+export interface UseEnvMaskReturn {
+  /** Set of indices currently revealed. */
+  revealed: Set<number>;
+  /** Whether every row is revealed. */
+  allRevealed: boolean;
+  /** Toggle a single row by index. */
+  toggleIndex: (index: number) => void;
+  /** Reveal-all / hide-all toggle. */
+  toggleAll: () => void;
+  /** Last-copied row index (or `'all'`) — null when feedback expired. */
+  copiedTarget: number | 'all' | null;
+  /** Copy a single value to clipboard, marking the row as copied. */
+  copyValue: (index: number, value: string) => void;
+  /** Copy every variable as a `.env`-style block. */
+  copyAllAsEnv: () => void;
+}
+
+/**
+ * Mask / reveal / copy state for {@link EnvTable}. The hook owns per-row
+ * reveal state and short-lived "copied!" feedback flags.
+ */
+export function useEnvMask({
+  variables,
+  defaultRevealed = false,
+}: UseEnvMaskOptions): UseEnvMaskReturn {
+  const [revealed, setRevealed] = React.useState<Set<number>>(() =>
+    defaultRevealed ? new Set(variables.map((_, i) => i)) : new Set(),
+  );
+  const [copiedTarget, setCopiedTarget] = React.useState<number | 'all' | null>(
+    null,
+  );
+  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  React.useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    },
+    [],
+  );
+
+  const flagCopied = React.useCallback((target: number | 'all') => {
+    setCopiedTarget(target);
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => setCopiedTarget(null), COPY_FEEDBACK_MS);
+  }, []);
+
+  const allRevealed =
+    variables.length > 0 && revealed.size === variables.length;
+
+  const toggleIndex = React.useCallback((index: number) => {
+    setRevealed((prev) => {
+      const next = new Set(prev);
+      if (next.has(index)) next.delete(index);
+      else next.add(index);
+      return next;
+    });
+  }, []);
+
+  const toggleAll = React.useCallback(() => {
+    setRevealed((prev) =>
+      prev.size === variables.length
+        ? new Set()
+        : new Set(variables.map((_, i) => i)),
+    );
+  }, [variables]);
+
+  const copyValue = React.useCallback(
+    (index: number, value: string) => {
+      void navigator.clipboard
+        .writeText(value)
+        .then(() => flagCopied(index))
+        .catch(() => {
+          /* clipboard rejection — swallow, no feedback */
+        });
+    },
+    [flagCopied],
+  );
+
+  const copyAllAsEnv = React.useCallback(() => {
+    const text = variables.map((v) => `${v.key}=${v.value}`).join('\n');
+    void navigator.clipboard
+      .writeText(text)
+      .then(() => flagCopied('all'))
+      .catch(() => {
+        /* swallow */
+      });
+  }, [variables, flagCopied]);
+
+  return {
+    revealed,
+    allRevealed,
+    toggleIndex,
+    toggleAll,
+    copiedTarget,
+    copyValue,
+    copyAllAsEnv,
+  };
+}

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

@@ -0,0 +1,12 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { EnvTable } from './EnvTable';
+export { ENV_TONE_CLASSES, getEnvTone } from './types';
+export { maskValue, useEnvMask } from './hooks/useEnvMask';
+export type {
+  EnvVariable,
+  EnvTableProps,
+  EnvEnvironment,
+  EnvBadgeTone,
+} from './types';
+export type { UseEnvMaskOptions, UseEnvMaskReturn } from './hooks/useEnvMask';

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

@@ -0,0 +1,21 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { createLazyComponent } from '../../../../common/lazy-wrapper';
+import type { EnvTableProps } from './types';
+
+export const LazyEnvTable = createLazyComponent<EnvTableProps>(
+  () => import('./EnvTable').then((mod) => ({ default: mod.EnvTable })),
+  {
+    displayName: 'LazyEnvTable',
+    fallback: (
+      <div
+        data-slot="env-table-skeleton"
+        className="h-40 w-full animate-pulse rounded-xl bg-muted"
+      />
+    ),
+  },
+);
+
+export type { EnvTableProps } from './types';

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

@@ -0,0 +1,76 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type * as React from 'react';
+
+/**
+ * Target environment for a variable. Renders as a colored badge next to the
+ * variable name. Custom string values fall back to the muted tone.
+ */
+export type EnvEnvironment =
+  | 'production'
+  | 'preview'
+  | 'development'
+  | (string & {});
+
+/**
+ * Tone mapping for environment badges. Resolves to semantic surface tokens —
+ * never raw color scales.
+ */
+export type EnvBadgeTone = 'success' | 'warning' | 'info' | 'muted';
+
+/**
+ * One environment variable row.
+ */
+export interface EnvVariable {
+  /** Variable name (e.g. DATABASE_URL). */
+  key: string;
+  /** Variable value. Masked by default. */
+  value: string;
+  /** Target environment. When provided, renders as a badge. */
+  environment?: EnvEnvironment;
+  /** Optional description shown below the value. */
+  description?: string;
+  /** Mark the row as required — name renders in `text-destructive`. */
+  required?: boolean;
+}
+
+export interface EnvTableProps
+  extends Omit<React.ComponentProps<'div'>, 'children' | 'title'> {
+  /** Environment variables to display. */
+  variables: EnvVariable[];
+  /** Optional heading above the table. */
+  title?: string;
+  /** Start with all values revealed. Defaults to `false`. */
+  defaultRevealed?: boolean;
+  /** Empty-state text. Defaults to `"No environment variables."`. */
+  emptyLabel?: string;
+}
+
+/**
+ * Map environment string → semantic tone. Unknown strings fall through to
+ * `muted`.
+ */
+export function getEnvTone(env: EnvEnvironment | undefined): EnvBadgeTone {
+  switch (env) {
+    case 'production':
+      return 'success';
+    case 'preview':
+      return 'info';
+    case 'development':
+      return 'warning';
+    default:
+      return 'muted';
+  }
+}
+
+/**
+ * Tailwind classes per env badge tone. All resolve to semantic tokens; opacity-
+ * derived surfaces keep every preset safe even when `*-background` tokens are
+ * not overridden.
+ */
+export const ENV_TONE_CLASSES: Record<EnvBadgeTone, string> = {
+  success: 'bg-success/15 text-success',
+  warning: 'bg-warning/15 text-warning',
+  info: 'bg-info/15 text-info',
+  muted: 'bg-muted text-muted-foreground',
+};

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

@@ -0,0 +1,194 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Streaming log viewer with per-level filtering, search, ANSI rendering,
+// and sticky-bottom auto-scroll. Virtualized via `react-virtuoso` (the
+// same library `chat/messages/MessageList` and `data/DataGrid` build on
+// — no new virt dep). Handles 10k+ entries without lag.
+//
+// Decomposition:
+//   - components/Toolbar      header, level chips, search input
+//   - components/LogRow       single row + ANSI render + search highlight
+//   - hooks/useLogFilter      filter + search single-pass derivation
+//   - hooks/useAutoScroll     sticky-bottom controller wrapping Virtuoso
+//   - utils/ansi              SGR parser → semantic tone segments
+
+'use client';
+
+import * as React from 'react';
+import { Virtuoso } from 'react-virtuoso';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { LogLevel, LogViewerProps } from './types';
+import { useLogFilter } from './hooks/useLogFilter';
+import { useAutoScroll } from './hooks/useAutoScroll';
+import { Toolbar, ScrollToBottomPill } from './components/Toolbar';
+import { LogRow } from './components/LogRow';
+
+const DEFAULT_LEVELS: LogLevel[] = ['error', 'warn', 'info', 'debug', 'verbose'];
+
+// Threshold above which Virtuoso wins outright. Below it, the plain
+// `.map()` path is fine and keeps the DOM debuggable.
+const VIRTUALIZE_THRESHOLD = 100;
+
+export function LogViewer({
+  entries,
+  title = 'Logs',
+  maxHeight = 400,
+  lineNumbers = true,
+  timestamps = true,
+  autoScroll = true,
+  levels = DEFAULT_LEVELS,
+  ansi = true,
+  onClear,
+  noVirtualize = false,
+  className,
+  ...divProps
+}: LogViewerProps) {
+  const [activeLevels, setActiveLevels] = React.useState<Set<LogLevel>>(
+    () => new Set(levels),
+  );
+  const [searchQuery, setSearchQuery] = React.useState('');
+  const [paused, setPaused] = React.useState(false);
+
+  // If the caller changes the available `levels` list (e.g. story
+  // toggles), reseed the active set. Compare by sorted join — a new
+  // array literal of the same levels shouldn't reset user toggles.
+  const levelsKey = React.useMemo(() => [...levels].sort().join(','), [levels]);
+  React.useEffect(() => {
+    setActiveLevels(new Set(levels));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [levelsKey]);
+
+  const toggleLevel = React.useCallback((level: LogLevel) => {
+    setActiveLevels((prev) => {
+      const next = new Set(prev);
+      if (next.has(level)) {
+        next.delete(level);
+      } else {
+        next.add(level);
+      }
+      return next;
+    });
+  }, []);
+
+  const { filtered, counts } = useLogFilter({
+    entries,
+    activeLevels,
+    searchQuery,
+  });
+
+  const { virtuosoRef, isAtBottom, onAtBottomChange, scrollToBottom } =
+    useAutoScroll(filtered.length, autoScroll && !paused);
+
+  // Line-number gutter width — based on total count, not filtered, so the
+  // gutter doesn't reflow when the user toggles a filter.
+  const lineNumberWidth = Math.max(String(entries.length).length, 3);
+
+  const shouldVirtualize = !noVirtualize && filtered.length > VIRTUALIZE_THRESHOLD;
+
+  const renderRow = React.useCallback(
+    (index: number, entry: (typeof filtered)[number]) => (
+      <LogRow
+        entry={entry}
+        index={index}
+        lineNumberWidth={lineNumberWidth}
+        showLineNumbers={lineNumbers}
+        showTimestamps={timestamps}
+        ansi={ansi}
+        searchQuery={searchQuery}
+      />
+    ),
+    [lineNumberWidth, lineNumbers, timestamps, ansi, searchQuery],
+  );
+
+  const isEmpty = filtered.length === 0;
+  const hasActiveFilter =
+    searchQuery.length > 0 || activeLevels.size < levels.length;
+
+  const resetFilters = React.useCallback(() => {
+    setSearchQuery('');
+    setActiveLevels(new Set(levels));
+  }, [levels]);
+
+  return (
+    <div
+      data-slot="log-viewer"
+      className={cn(
+        'flex flex-col overflow-hidden rounded-xl border border-border/60 bg-card shadow-sm',
+        className,
+      )}
+      {...divProps}
+    >
+      <Toolbar
+        title={title}
+        totalCount={entries.length}
+        filteredCount={filtered.length}
+        levels={levels}
+        activeLevels={activeLevels}
+        toggleLevel={toggleLevel}
+        levelCounts={counts}
+        searchQuery={searchQuery}
+        setSearchQuery={setSearchQuery}
+        autoScrollEnabled={autoScroll}
+        paused={paused}
+        setPaused={setPaused}
+        onClear={onClear}
+      />
+
+      <div
+        className="font-mono text-xs leading-relaxed [scrollbar-width:thin]"
+        style={{ height: maxHeight }}
+        role="log"
+        aria-live="polite"
+        aria-label={title}
+      >
+        {isEmpty ? (
+          <div className="flex h-full flex-col items-center justify-center gap-1 text-sm text-muted-foreground">
+            <span>
+              {entries.length === 0
+                ? 'No log entries.'
+                : 'No matching log entries.'}
+            </span>
+            {hasActiveFilter && entries.length > 0 && (
+              <button
+                type="button"
+                onClick={resetFilters}
+                className="text-xs text-muted-foreground underline underline-offset-2 hover:text-foreground"
+              >
+                Reset filters
+              </button>
+            )}
+          </div>
+        ) : shouldVirtualize ? (
+          <Virtuoso
+            ref={virtuosoRef}
+            data={filtered}
+            atBottomStateChange={onAtBottomChange}
+            atBottomThreshold={40}
+            followOutput={autoScroll && !paused ? 'auto' : false}
+            itemContent={renderRow}
+            increaseViewportBy={{ top: 200, bottom: 400 }}
+            style={{ height: '100%' }}
+          />
+        ) : (
+          <div className="h-full overflow-auto [scrollbar-width:thin]">
+            {filtered.map((entry, i) => (
+              <LogRow
+                key={i}
+                entry={entry}
+                index={i}
+                lineNumberWidth={lineNumberWidth}
+                showLineNumbers={lineNumbers}
+                showTimestamps={timestamps}
+                ansi={ansi}
+                searchQuery={searchQuery}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+
+      <ScrollToBottomPill visible={!isAtBottom && !isEmpty} onClick={scrollToBottom} />
+    </div>
+  );
+}

package/src/tools/dev/ops/LogViewer/README.md

@@ -0,0 +1,30 @@
+# LogViewer
+
+Virtualized log stream viewer. Level filter, free-text search, ANSI escape parsing, copy. Tested on 10k+ entries. Level colors route to semantic tokens (`destructive` / `warning` / `info` / `debug` / `muted`).
+
+```tsx
+import { LogViewer } from '@djangocfg/ui-tools/log-viewer';
+
+<LogViewer
+  entries={[
+    { level: 'info',  message: 'Server listening on :3000', timestamp: '2025-01-12T10:00:00Z' },
+    { level: 'error', message: '\x1b[31mDatabase connection failed\x1b[0m' },
+  ]}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `entries` | `LogEntry[]` | — | Each entry: `{ level, message, timestamp? }`. `message` may contain ANSI escapes. |
+| `defaultLevel` | `LogLevel \| 'all'` | `'all'` | Initial level filter. |
+| `defaultSearch` | `string` | `''` | Initial search term. |
+| `showTimestamps` | `boolean` | `true` | Render the timestamp column. |
+| `maxHeight` | `number \| string` | `400` | Viewport height. |
+
+Storybook: `apps/storybook/stories/ui-tools/dev/LogViewer.stories.tsx`
+
+---
+
+Adapted from jalcoui (MIT).

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

@@ -0,0 +1,151 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { LogEntry } from '../types';
+import { LEVEL_LABELS, getLevelToneClasses } from '../types';
+import { parseAnsi, classesForSegment, stripAnsi } from '../utils/ansi';
+
+function formatTimestamp(ts?: string): string {
+  const d = ts ? new Date(ts) : new Date();
+  const ms = d.getMilliseconds().toString().padStart(3, '0');
+  return `${d.toLocaleTimeString('en-US', {
+    hour12: false,
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  })}.${ms}`;
+}
+
+/** Escape a string for use inside a `RegExp` constructor. */
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+interface MessageBodyProps {
+  message: string;
+  ansi: boolean;
+  searchQuery: string;
+}
+
+/**
+ * Render the message body. The render is staged in two passes:
+ *
+ * 1. ANSI parse — produces styled segments. When `ansi` is `false` the
+ *    raw message becomes one segment.
+ * 2. Search highlight — splits each segment's text on the search needle
+ *    and wraps matches in `<mark>` while preserving the segment's tone
+ *    classes.
+ *
+ * The two passes run independently so a needle that crosses an ANSI
+ * boundary still highlights inside each segment.
+ */
+const MessageBody = React.memo(function MessageBody({
+  message,
+  ansi,
+  searchQuery,
+}: MessageBodyProps) {
+  const segments = React.useMemo(
+    () => (ansi ? parseAnsi(message) : [{ text: ansi ? message : stripAnsi(message) }]),
+    [message, ansi],
+  );
+
+  const needle = searchQuery.trim();
+  if (!needle) {
+    return (
+      <>
+        {segments.map((seg, i) => (
+          <span key={i} className={classesForSegment(seg)}>
+            {seg.text}
+          </span>
+        ))}
+      </>
+    );
+  }
+
+  const re = new RegExp(`(${escapeRegex(needle)})`, 'gi');
+  return (
+    <>
+      {segments.map((seg, i) => {
+        const classes = classesForSegment(seg);
+        const parts = seg.text.split(re);
+        return (
+          <span key={i} className={classes}>
+            {parts.map((part, j) =>
+              part.toLowerCase() === needle.toLowerCase() ? (
+                <mark
+                  key={j}
+                  className="rounded-sm bg-warning/30 px-0.5 text-inherit"
+                >
+                  {part}
+                </mark>
+              ) : (
+                <React.Fragment key={j}>{part}</React.Fragment>
+              ),
+            )}
+          </span>
+        );
+      })}
+    </>
+  );
+});
+
+export interface LogRowProps {
+  entry: LogEntry;
+  index: number;
+  /** Width of the line-number gutter in `ch` units (caller-computed
+   * once per render so every row aligns). */
+  lineNumberWidth: number;
+  showLineNumbers: boolean;
+  showTimestamps: boolean;
+  ansi: boolean;
+  searchQuery: string;
+}
+
+export const LogRow = React.memo(function LogRow({
+  entry,
+  index,
+  lineNumberWidth,
+  showLineNumbers,
+  showTimestamps,
+  ansi,
+  searchQuery,
+}: LogRowProps) {
+  const tone = getLevelToneClasses(entry.level);
+
+  return (
+    <div className="flex gap-3 border-b border-border/20 px-3 py-1 transition-colors hover:bg-muted/30">
+      {showLineNumbers && (
+        <span
+          className="shrink-0 select-none text-right text-muted-foreground/50 tabular-nums"
+          style={{ width: `${lineNumberWidth}ch` }}
+          aria-hidden="true"
+        >
+          {index + 1}
+        </span>
+      )}
+      {showTimestamps && (
+        <span className="shrink-0 text-muted-foreground/70 tabular-nums">
+          {formatTimestamp(entry.timestamp)}
+        </span>
+      )}
+      <span
+        className={cn(
+          'w-[3ch] shrink-0 text-right font-semibold tabular-nums',
+          tone.text,
+        )}
+      >
+        {LEVEL_LABELS[entry.level]}
+      </span>
+      <span className="min-w-0 flex-1 whitespace-pre-wrap break-words text-foreground/90">
+        <MessageBody
+          message={entry.message}
+          ansi={ansi}
+          searchQuery={searchQuery}
+        />
+      </span>
+    </div>
+  );
+});