Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
17.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file LogStream.tsx
 * @input Uses React, StyleX, theme tokens (color/spacing/radius/typography vars)
 * @output Exports LogStream component, LogStreamProps, LogEntry, LogStreamLevel
 * @position Lab implementation; experimental streaming log viewer
 *
 * Mono grid rows (timestamp | level | source? | message) with level color
 * accents, expandable detail panels, a follow-scroll live-tail mode, and an
 * always-dark "terminal" variant.
 *
 * Known limit: rows are plain DOM (content-visibility: auto for offscreen
 * skip) — there is NO virtualization. Streams beyond a few thousand rows
 * should be windowed by the caller.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/lab/src/LogStream/LogStream.doc.mjs (props table, notes)
 * - /packages/lab/src/LogStream/LogStream.test.tsx (behavior tests)
 * - /packages/lab/src/LogStream/index.ts (exports if types change)
 * - /apps/storybook/stories/LogStream.stories.tsx (examples and visual coverage)
 */

'use client';

import {
  Fragment,
  useEffect,
  useMemo,
  useRef,
  useState,
  type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';

import type {BaseProps} from '@astryxdesign/core';
import {
  focusOutlineStyles,
  mergeProps,
  themeProps,
} from '@astryxdesign/core/utils';
import {
  borderVars,
  colorVars,
  durationVars,
  fontWeightVars,
  radiusVars,
  shadowVars,
  spacingVars,
  textSizeVars,
  typographyVars,
} from '@astryxdesign/core/theme/tokens.stylex';

/** Severity of one log entry. */
export type LogStreamLevel = 'info' | 'warn' | 'error' | 'debug';

/** One row in the stream; all strings are pre-formatted by the caller. */
export interface LogEntry {
  /** Stable unique key, e.g. `"req-1042"`. */
  id: string;
  /** Pre-formatted timestamp, e.g. `"14:02:11.482"`. Deterministic. */
  timestamp: string;
  level: LogStreamLevel;
  message: string;
  /** Emitting service/component, e.g. `"api-gateway"`. */
  source?: string;
  /** When set, the row becomes a disclosure button for this panel. */
  detail?: ReactNode;
}

export interface LogStreamProps extends Omit<
  BaseProps<HTMLDivElement>,
  'children'
> {
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLDivElement>;
  /** Log rows, oldest first (live tails append at the end). */
  entries: LogEntry[];
  /**
   * Visual treatment. `'terminal'` renders dark chrome regardless of the
   * active color scheme (terminal output is a brand surface, like a real
   * shell — light-mode terminals read as broken builds).
   * @default 'default'
   */
  variant?: 'default' | 'terminal';
  /**
   * Pin scroll to the newest entry as entries append. Unpins when the user
   * scrolls up; re-pin via the "Jump to latest" affordance. Controlled when
   * provided; uncontrolled (initially unpinned) otherwise.
   */
  isFollowing?: boolean;
  /** Called when follow-pinning changes (user scroll-up or "Jump to latest"). */
  onFollowChange?: (following: boolean) => void;
  /** Max height of the scroll area before it scrolls. */
  maxHeight?: number | string;
  /** Show the timestamp column. @default true */
  hasTimestamps?: boolean;
  /** Accessible label for the log region. @default 'Log stream' */
  label?: string;
  /** Escape hatch: fully replace the default row for an entry. */
  renderEntry?: (entry: LogEntry) => ReactNode;
}

/** User counts as "scrolled away" beyond this distance from the bottom. */
const FOLLOW_THRESHOLD_PX = 24;

const REDUCE = '@media (prefers-reduced-motion: reduce)';
const HOVER = '@media (hover: hover)';

// The terminal variant is intentionally always-dark (terminal chrome is a
// brand surface, mirroring real shells), so it uses fixed near-black grays
// rather than light-dark() theme tokens, which would flip with the scheme.
const TERM = {
  surface: '#0a0a0a',
  surfaceRaised: '#141417',
  border: '#26262a',
  textDim: '#8b8b94',
  text: '#b9b9c0',
  textBright: '#e8e8ea',
  warn: '#f2c00b',
  error: '#ff6166',
};

const styles = stylex.create({
  root: {
    position: 'relative',
    display: 'flex',
    flexDirection: 'column',
    borderRadius: radiusVars['--radius-element'],
    borderWidth: borderVars['--border-width'],
    borderStyle: 'solid',
    borderColor: colorVars['--color-border'],
    backgroundColor: colorVars['--color-background-surface'],
    overflow: 'hidden',
    fontFamily: typographyVars['--font-family-code'],
    fontSize: textSizeVars['--font-size-sm'],
  },
  rootTerminal: {
    borderColor: TERM.border,
    backgroundColor: TERM.surface,
  },
  scroller: (maxHeight: number | string | null) => ({
    overflowY: 'auto',
    maxHeight,
    scrollbarWidth: 'thin',
    overscrollBehavior: 'contain',
  }),
  row: {
    display: 'grid',
    alignItems: 'baseline',
    columnGap: spacingVars['--spacing-3'],
    paddingBlock: spacingVars['--spacing-1'],
    paddingInline: spacingVars['--spacing-3'],
    lineHeight: 1.7,
    color: colorVars['--color-text-primary'],
    borderBottomWidth: {
      default: borderVars['--border-width'],
      ':last-child': 0,
    },
    borderBottomStyle: 'solid',
    borderBottomColor: colorVars['--color-border'],
    // Offscreen rows skip layout/paint; the intrinsic size keeps the
    // scrollbar stable. No virtualization — see the file header.
    contentVisibility: 'auto',
    containIntrinsicBlockSize: 'auto 28px',
    // Appended tail lines fade in; opacity-only, instant under reduced motion.
    opacity: 1,
    transitionProperty: 'opacity',
    transitionDuration: {
      default: durationVars['--duration-fast-min'],
      [REDUCE]: '0.01ms',
    },
    transitionTimingFunction: 'ease-out',
    '@starting-style': {opacity: 0},
  },
  rowTerminal: {
    color: TERM.text,
    borderBottomWidth: 0,
    paddingBlock: 1,
  },
  // Grid templates per visible column set (timestamp / source optional).
  colsFull: {gridTemplateColumns: '96px 52px 128px minmax(0, 1fr)'},
  colsNoSource: {gridTemplateColumns: '96px 52px minmax(0, 1fr)'},
  colsNoTimestamp: {gridTemplateColumns: '52px 128px minmax(0, 1fr)'},
  colsMessageOnly: {gridTemplateColumns: '52px minmax(0, 1fr)'},
  rowButton: {
    width: '100%',
    textAlign: 'left',
    borderTopWidth: 0,
    borderInlineWidth: 0,
    fontFamily: typographyVars['--font-family-code'],
    fontSize: textSizeVars['--font-size-sm'],
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    backgroundColor: {
      default: 'transparent',
      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
        [HOVER]: colorVars['--color-overlay-hover'],
      },
    },
  },
  rowButtonTerminal: {
    backgroundColor: {
      default: 'transparent',
      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
        [HOVER]: TERM.surfaceRaised,
      },
    },
  },
  // Level tints: faint full-row wash for error/warn (color-mix keeps the
  // tint derived from the theme token instead of a parallel palette).
  rowError: {
    backgroundColor: `color-mix(in srgb, ${colorVars['--color-error']} 6%, transparent)`,
  },
  rowWarn: {
    backgroundColor: `color-mix(in srgb, ${colorVars['--color-warning']} 5%, transparent)`,
  },
  timestamp: {
    color: colorVars['--color-text-secondary'],
    whiteSpace: 'nowrap',
    fontVariantNumeric: 'tabular-nums',
  },
  timestampTerminal: {
    color: TERM.textDim,
  },
  level: {
    fontSize: textSizeVars['--font-size-xs'],
    fontWeight: fontWeightVars['--font-weight-semibold'],
    letterSpacing: '0.08em',
    textTransform: 'uppercase',
  },
  levelInfo: {color: colorVars['--color-text-secondary']},
  levelDebug: {color: colorVars['--color-text-disabled']},
  // Plain-surface warning/error labels use the dedicated foreground roles.
  levelWarn: {
    color: colorVars['--color-text-warning'],
  },
  levelError: {
    color: colorVars['--color-text-error'],
  },
  levelInfoTerminal: {color: TERM.text},
  levelDebugTerminal: {color: TERM.textDim},
  levelWarnTerminal: {color: TERM.warn},
  levelErrorTerminal: {color: TERM.error},
  source: {
    color: colorVars['--color-text-secondary'],
    overflow: 'hidden',
    textOverflow: 'ellipsis',
    whiteSpace: 'nowrap',
    minWidth: 0,
  },
  sourceTerminal: {
    color: TERM.textDim,
  },
  message: {
    minWidth: 0,
    overflowWrap: 'anywhere',
    // Text inside keeps `anywhere` too (Text FR3).
    '--_astryx-text-overflow-wrap': 'anywhere',
    whiteSpace: 'pre-wrap',
  },
  messageTerminal: {
    color: TERM.text,
  },
  messageErrorTerminal: {color: TERM.error},
  messageWarnTerminal: {color: TERM.warn},
  detail: {
    paddingBlock: spacingVars['--spacing-3'],
    paddingInline: spacingVars['--spacing-3'],
    backgroundColor: colorVars['--color-background-muted'],
    borderBottomWidth: borderVars['--border-width'],
    borderBottomStyle: 'solid',
    borderBottomColor: colorVars['--color-border'],
  },
  detailTerminal: {
    backgroundColor: '#0e0e10',
    borderBottomColor: TERM.border,
    color: TERM.text,
  },
  jumpToLatest: {
    position: 'absolute',
    bottom: spacingVars['--spacing-3'],
    insetInlineEnd: spacingVars['--spacing-3'],
    paddingBlock: spacingVars['--spacing-1'],
    paddingInline: spacingVars['--spacing-3'],
    borderRadius: radiusVars['--radius-full'],
    borderWidth: borderVars['--border-width'],
    borderStyle: 'solid',
    borderColor: colorVars['--color-border-emphasized'],
    backgroundColor: {
      default: colorVars['--color-background-surface'],
      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
        [HOVER]: colorVars['--color-background-muted'],
      },
    },
    color: colorVars['--color-text-primary'],
    fontFamily: typographyVars['--font-family-code'],
    fontSize: textSizeVars['--font-size-sm'],
    fontWeight: fontWeightVars['--font-weight-medium'],
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    boxShadow: shadowVars['--shadow-med'],
  },
  jumpToLatestTerminal: {
    borderColor: TERM.border,
    backgroundColor: {
      default: TERM.surfaceRaised,
      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
        [HOVER]: '#1d1d21',
      },
    },
    color: TERM.textBright,
  },
});

const LEVEL_STYLE: Record<LogStreamLevel, stylex.StyleXStyles> = {
  info: styles.levelInfo,
  warn: styles.levelWarn,
  error: styles.levelError,
  debug: styles.levelDebug,
};

const LEVEL_STYLE_TERMINAL: Record<LogStreamLevel, stylex.StyleXStyles> = {
  info: styles.levelInfoTerminal,
  warn: styles.levelWarnTerminal,
  error: styles.levelErrorTerminal,
  debug: styles.levelDebugTerminal,
};

/**
 * Experimental streaming log viewer: mono grid rows
 * (timestamp | level | source | message) with token-derived level accents,
 * expandable per-row detail panels, follow-scroll live tailing with a
 * "Jump to latest" affordance, and an always-dark terminal variant.
 *
 * Appended rows fade in via `@starting-style` (instant under
 * prefers-reduced-motion). Follow pinning uses a scroll listener — no
 * polling; rows use `content-visibility: auto` for offscreen skip but are
 * NOT virtualized (window large streams in the caller).
 *
 * Live announcements are tied to follow pinning: the `role="log"` region is
 * `aria-live="polite"` only while following the tail and `aria-live="off"`
 * while unfollowed, so appends never flood assistive tech.
 *
 * @example
 * ```
 * <LogStream
 *   entries={entries}
 *   maxHeight={480}
 *   isFollowing={isFollowing}
 *   onFollowChange={setIsFollowing}
 * />
 * ```
 */
export function LogStream({
  entries,
  variant = 'default',
  isFollowing,
  onFollowChange,
  maxHeight,
  hasTimestamps = true,
  label = 'Log stream',
  renderEntry,
  xstyle,
  className,
  style,
  ref,
  ...rest
}: LogStreamProps) {
  const isTerminal = variant === 'terminal';
  const scrollerRef = useRef<HTMLDivElement | null>(null);

  // Follow pinning: controlled when the prop is provided, else internal.
  const [internalFollowing, setInternalFollowing] = useState(
    isFollowing ?? false,
  );
  const following = isFollowing ?? internalFollowing;
  const setFollowing = (next: boolean) => {
    if (next === following) {
      return;
    }
    if (isFollowing == null) {
      setInternalFollowing(next);
    }
    onFollowChange?.(next);
  };

  // Whether the viewport currently sits at the bottom; drives the
  // "Jump to latest" affordance. Updated from scroll events only.
  const [isAtBottom, setIsAtBottom] = useState(true);

  const [expandedIds, setExpandedIds] = useState<ReadonlySet<string>>(
    () => new Set(),
  );
  const toggleExpanded = (id: string) => {
    setExpandedIds(prev => {
      const next = new Set(prev);
      if (next.has(id)) {
        next.delete(id);
      } else {
        next.add(id);
      }
      return next;
    });
  };

  const hasSource = useMemo(
    () => entries.some(entry => entry.source != null),
    [entries],
  );

  // Pin to the newest row while following. Direct scrollTop assignment (not
  // smooth scrollTo) so rapid appends never queue competing animations.
  useEffect(() => {
    const el = scrollerRef.current;
    if (!following || el == null) {
      return;
    }
    el.scrollTop = el.scrollHeight;
    setIsAtBottom(true);
  }, [following, entries.length]);

  // No programmatic-scroll guard is needed: pinning always lands the
  // viewport at the bottom, and the unpin branch below only fires when the
  // viewport is AWAY from the bottom — a programmatic echo is a no-op.
  const handleScroll = (event: React.UIEvent<HTMLDivElement>) => {
    const el = event.currentTarget;
    const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
    const atBottom = distanceFromBottom <= FOLLOW_THRESHOLD_PX;
    setIsAtBottom(atBottom);
    // User scrolled away from the tail: unpin. Re-pinning is explicit via
    // the "Jump to latest" affordance (never implicit on scroll-down).
    if (following && !atBottom) {
      setFollowing(false);
    }
  };

  const handleJumpToLatest = () => {
    setFollowing(true);
    const el = scrollerRef.current;
    if (el != null) {
      el.scrollTop = el.scrollHeight;
      setIsAtBottom(true);
    }
  };

  const colsStyle = hasTimestamps
    ? hasSource
      ? styles.colsFull
      : styles.colsNoSource
    : hasSource
      ? styles.colsNoTimestamp
      : styles.colsMessageOnly;

  const renderDefaultRow = (entry: LogEntry) => {
    const isExpandable = entry.detail != null;
    const isExpanded = isExpandable && expandedIds.has(entry.id);
    const cells = (
      <>
        {hasTimestamps && (
          <span
            {...stylex.props(
              styles.timestamp,
              isTerminal && styles.timestampTerminal,
            )}>
            {entry.timestamp}
          </span>
        )}
        <span
          {...stylex.props(
            styles.level,
            (isTerminal ? LEVEL_STYLE_TERMINAL : LEVEL_STYLE)[entry.level],
          )}>
          {entry.level}
        </span>
        {hasSource && (
          <span
            {...stylex.props(
              styles.source,
              isTerminal && styles.sourceTerminal,
            )}
            title={entry.source}>
            {entry.source}
          </span>
        )}
        <span
          {...stylex.props(
            styles.message,
            isTerminal && styles.messageTerminal,
            isTerminal &&
              entry.level === 'error' &&
              styles.messageErrorTerminal,
            isTerminal && entry.level === 'warn' && styles.messageWarnTerminal,
          )}>
          {entry.message}
        </span>
      </>
    );
    const rowStyles = [
      styles.row,
      colsStyle,
      isTerminal && styles.rowTerminal,
      !isTerminal && entry.level === 'error' && styles.rowError,
      !isTerminal && entry.level === 'warn' && styles.rowWarn,
    ] as const;
    if (!isExpandable) {
      return (
        <div data-level={entry.level} {...stylex.props(...rowStyles)}>
          {cells}
        </div>
      );
    }
    return (
      <>
        <button
          type="button"
          aria-expanded={isExpanded}
          data-level={entry.level}
          onClick={() => toggleExpanded(entry.id)}
          {...stylex.props(
            ...rowStyles,
            styles.rowButton,
            isTerminal && styles.rowButtonTerminal,
          )}>
          {cells}
        </button>
        {isExpanded && (
          <div
            {...stylex.props(
              styles.detail,
              isTerminal && styles.detailTerminal,
            )}>
            {entry.detail}
          </div>
        )}
      </>
    );
  };

  return (
    <div
      ref={ref}
      {...rest}
      {...mergeProps(
        themeProps('log-stream', {variant}),
        stylex.props(styles.root, isTerminal && styles.rootTerminal, xstyle),
        className,
        style,
      )}>
      <div
        ref={scrollerRef}
        role="log"
        aria-label={label}
        // role="log" is implicitly aria-live="polite" — on a busy stream that
        // floods assistive tech with every appended row (WCAG 2.2.2 / 4.1.3).
        // Follow-pinning doubles as the mute switch: while the user is away
        // from the tail (unfollowed), the region is aria-live="off"; resuming
        // follow ("Jump to latest") restores polite announcements.
        aria-live={following ? 'polite' : 'off'}
        onScroll={handleScroll}
        {...stylex.props(styles.scroller(maxHeight ?? null))}>
        {entries.map(entry => (
          <Fragment key={entry.id}>
            {renderEntry != null ? renderEntry(entry) : renderDefaultRow(entry)}
          </Fragment>
        ))}
      </div>
      {!following && !isAtBottom && entries.length > 0 && (
        <button
          type="button"
          onClick={handleJumpToLatest}
          {...stylex.props(
            focusOutlineStyles.focusVisible,
            styles.jumpToLatest,
            isTerminal && styles.jumpToLatestTerminal,
          )}>
          Jump to latest ↓
        </button>
      )}
    </div>
  );
}

LogStream.displayName = 'LogStream';