@workflow/web-shared 5.0.0-beta.4 → 5.0.0-beta.41

package/src/components/trace-viewer/components/detail-panel-width.ts

@@ -0,0 +1,76 @@
+/**
+ * Width model for the span detail panel: the stored value is the user's
+ * preferred width (absolute px, persisted to localStorage on explicit
+ * interaction only), while the container-relative maximum is applied at
+ * render time — so a width preferred on a wide screen survives a narrower
+ * session and restores when the viewer grows again.
+ */
+
+/** Floor for the detail panel — matches the previous `clamp(280px, …)` floor. */
+export const PANEL_MIN_WIDTH = 280;
+
+/**
+ * Absolute ceiling enforced at the storage layer so a corrupt or stale stored
+ * value can never wedge the layout open.
+ */
+export const PANEL_HARD_MAX_WIDTH = 1300;
+
+/** Default width — matches the previous fixed 360px column. */
+export const PANEL_DEFAULT_WIDTH = 360;
+
+/**
+ * Width the main (event list + timeline) area keeps while the panel is
+ * resized or the container shrinks. Below `PANEL_MIN_WIDTH + MAIN_MIN_WIDTH`
+ * of container the panel gives way first, compressing below its own floor —
+ * the list and timeline stay usable at the panel's expense.
+ */
+export const MAIN_MIN_WIDTH = 400;
+
+export const PANEL_WIDTH_STORAGE_KEY = 'workflow-trace-detail-panel-width';
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+export function computeMaxPanelWidth(availableWidth: number): number {
+  if (availableWidth <= 0) return PANEL_HARD_MAX_WIDTH;
+  return Math.min(
+    Math.max(availableWidth - MAIN_MIN_WIDTH, 0),
+    PANEL_HARD_MAX_WIDTH
+  );
+}
+
+/**
+ * Note: when the container is too small to honor both floors
+ * (`availableWidth < PANEL_MIN_WIDTH + MAIN_MIN_WIDTH`), the max wins and the
+ * panel compresses below `PANEL_MIN_WIDTH`.
+ */
+export function clampPanelWidth(width: number, availableWidth: number): number {
+  return clamp(width, PANEL_MIN_WIDTH, computeMaxPanelWidth(availableWidth));
+}
+
+export function readStoredPanelWidth(): number {
+  if (typeof window === 'undefined') return PANEL_DEFAULT_WIDTH;
+  try {
+    const raw = window.localStorage.getItem(PANEL_WIDTH_STORAGE_KEY);
+    const value = raw ? Number(raw) : Number.NaN;
+    if (!Number.isFinite(value)) return PANEL_DEFAULT_WIDTH;
+    // Only enforce absolute bounds at the storage layer; the container-relative
+    // max is applied at render time (see module docs).
+    return clamp(value, PANEL_MIN_WIDTH, PANEL_HARD_MAX_WIDTH);
+  } catch {
+    return PANEL_DEFAULT_WIDTH;
+  }
+}
+
+export function writeStoredPanelWidth(width: number): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(
+      PANEL_WIDTH_STORAGE_KEY,
+      String(Math.round(width))
+    );
+  } catch {
+    // Best-effort (private mode, quota).
+  }
+}

package/src/components/trace-viewer/components/detail-panel.tsx

@@ -0,0 +1,273 @@
+'use client';
+
+import { parseStepName, parseWorkflowName } from '@workflow/utils/parse-name';
+import { ChevronDown, ChevronUp, X } from 'lucide-react';
+import {
+  type ReactNode,
+  type RefObject,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { filterSpanRawEvents } from '../../../lib/trace-builder';
+import { ErrorBoundary } from '../../error-boundary';
+import {
+  EntityDetailPanel,
+  type SelectedSpanInfo,
+} from '../../sidebar/entity-detail-panel';
+import { useSidebarData } from '../../sidebar/sidebar-data-context';
+import { IconButton } from '../../ui/icon-button';
+import { Kbd } from '../../ui/kbd';
+import { Tooltip, TooltipContent, TooltipTrigger } from '../../ui/tooltip';
+import { useActiveSpan } from '../context';
+import {
+  clampPanelWidth,
+  computeMaxPanelWidth,
+  PANEL_DEFAULT_WIDTH,
+  PANEL_MIN_WIDTH,
+  readStoredPanelWidth,
+  writeStoredPanelWidth,
+} from './detail-panel-width';
+import { DraggableBorder } from './draggable-border';
+import { useElementWidth } from './use-element-width';
+
+const DETAIL_PANEL_ID = 'trace-detail-panel';
+
+/** Bridge ActiveSpanContext + SidebarDataContext → SelectedSpanInfo. */
+function useSelectedSpanInfo(): SelectedSpanInfo | null {
+  const { activeSpan } = useActiveSpan();
+  const sidebar = useSidebarData();
+
+  return useMemo(() => {
+    if (!activeSpan) return null;
+
+    const resource = activeSpan.attributes?.resource as string | undefined;
+    const rawEvents = filterSpanRawEvents(
+      sidebar.events,
+      resource,
+      activeSpan.spanId
+    );
+
+    return {
+      data: activeSpan.attributes?.data,
+      resource,
+      spanId: activeSpan.spanId,
+      rawEvents,
+    };
+  }, [activeSpan, sidebar]);
+}
+
+/**
+ * The span detail aside: content, prev/next/close header, J/K navigation, and
+ * the resizable left border with its width model (see detail-panel-width.ts).
+ *
+ * Always mounted — it renders null without a selection — so the panel width
+ * survives closing and reopening within a session.
+ */
+export function TraceDetailPanel({
+  containerRef,
+  onNavigateToSpan,
+  onClose,
+}: {
+  containerRef: RefObject<HTMLDivElement | null>;
+  onNavigateToSpan: (spanId: string) => void;
+  onClose: () => void;
+}): ReactNode {
+  const { activeSpan, activeSpanId, spans } = useActiveSpan();
+  const sidebar = useSidebarData();
+  const selectedSpan = useSelectedSpanInfo();
+  const isOpen = Boolean(activeSpan);
+
+  const [storedWidth, setStoredWidth] = useState<number>(() =>
+    readStoredPanelWidth()
+  );
+  const containerWidth = useElementWidth(containerRef, isOpen);
+  const asideRef = useRef<HTMLDivElement | null>(null);
+
+  const handleResize = useCallback(
+    (next: number) => {
+      const clamped = clampPanelWidth(next, containerWidth);
+      setStoredWidth(clamped);
+      writeStoredPanelWidth(clamped);
+    },
+    [containerWidth]
+  );
+
+  const panelWidth = clampPanelWidth(storedWidth, containerWidth);
+  const panelMaxWidth = Math.max(
+    PANEL_MIN_WIDTH,
+    computeMaxPanelWidth(containerWidth)
+  );
+
+  const { prevSpanId, nextSpanId } = useMemo(() => {
+    if (!activeSpanId) return { prevSpanId: null, nextSpanId: null };
+    const i = spans.findIndex((s) => s.spanId === activeSpanId);
+    if (i === -1) return { prevSpanId: null, nextSpanId: null };
+    return {
+      prevSpanId: spans[i - 1]?.spanId ?? null,
+      nextSpanId: spans[i + 1]?.spanId ?? null,
+    };
+  }, [activeSpanId, spans]);
+
+  const handleSelectPrev = useCallback(() => {
+    if (prevSpanId) onNavigateToSpan(prevSpanId);
+  }, [prevSpanId, onNavigateToSpan]);
+
+  const handleSelectNext = useCallback(() => {
+    if (nextSpanId) onNavigateToSpan(nextSpanId);
+  }, [nextSpanId, onNavigateToSpan]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const onKeyDown = (e: KeyboardEvent): void => {
+      if (
+        e.key !== 'j' &&
+        e.key !== 'k' &&
+        e.key !== 'ArrowDown' &&
+        e.key !== 'ArrowUp'
+      ) {
+        return;
+      }
+      const target = e.target as HTMLElement | null;
+      if (
+        target instanceof HTMLInputElement ||
+        target instanceof HTMLTextAreaElement ||
+        target?.isContentEditable
+      ) {
+        return;
+      }
+      const targetId =
+        e.key === 'k' || e.key === 'ArrowUp' ? prevSpanId : nextSpanId;
+      if (targetId) {
+        e.preventDefault();
+        onNavigateToSpan(targetId);
+      }
+    };
+
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [isOpen, prevSpanId, nextSpanId, onNavigateToSpan]);
+
+  // Derive the selected span name for the panel header
+  const selectedSpanName = useMemo(() => {
+    if (!selectedSpan?.data) return 'Details';
+    const data = selectedSpan.data as Record<string, unknown>;
+    if (selectedSpan.resource === 'hook') {
+      return (data.token as string | undefined) ?? (data.hookId as string);
+    }
+
+    const stepName = data.stepName as string | undefined;
+    const workflowName = data.workflowName as string | undefined;
+    return (
+      (stepName ? parseStepName(stepName)?.shortName : undefined) ??
+      (workflowName ? parseWorkflowName(workflowName)?.shortName : undefined) ??
+      stepName ??
+      workflowName ??
+      (data.hookId as string) ??
+      'Details'
+    );
+  }, [selectedSpan?.data, selectedSpan?.resource]);
+
+  if (!activeSpan) return null;
+
+  return (
+    <aside
+      ref={asideRef}
+      id={DETAIL_PANEL_ID}
+      className="relative flex flex-col h-full max-h-full shrink-0 bg-background-100 border-l border-gray-alpha-400"
+      style={{ width: panelWidth }}
+    >
+      <DraggableBorder
+        element={asideRef}
+        position="left"
+        onWidthChange={handleResize}
+        onReset={() => handleResize(PANEL_DEFAULT_WIDTH)}
+        aria-label="Resize span details panel"
+        aria-controls={DETAIL_PANEL_ID}
+        aria-valuemin={PANEL_MIN_WIDTH}
+        aria-valuemax={panelMaxWidth}
+        aria-valuenow={Math.min(
+          Math.max(Math.round(panelWidth), PANEL_MIN_WIDTH),
+          panelMaxWidth
+        )}
+      />
+      {/* Panel header */}
+      <div className="flex items-center justify-between gap-2 shrink-0 px-4 py-[7.5px]">
+        <span className="text-label-14 font-medium text-gray-1000 truncate block">
+          {selectedSpanName}
+        </span>
+        <div className="flex items-center gap-0.5 shrink-0">
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <IconButton
+                aria-label="Navigate up"
+                aria-keyshortcuts="K"
+                onClick={handleSelectPrev}
+                disabled={!prevSpanId}
+              >
+                <ChevronUp className="w-4 h-4" />
+              </IconButton>
+            </TooltipTrigger>
+            {prevSpanId ? (
+              <TooltipContent>
+                Navigate up
+                <Kbd>K</Kbd>
+              </TooltipContent>
+            ) : null}
+          </Tooltip>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <IconButton
+                aria-label="Navigate down"
+                aria-keyshortcuts="J"
+                onClick={handleSelectNext}
+                disabled={!nextSpanId}
+              >
+                <ChevronDown className="w-4 h-4" />
+              </IconButton>
+            </TooltipTrigger>
+            {nextSpanId ? (
+              <TooltipContent>
+                Navigate down
+                <Kbd>J</Kbd>
+              </TooltipContent>
+            ) : null}
+          </Tooltip>
+          <div aria-hidden className="w-px h-4 bg-gray-alpha-400 mx-1" />
+          <IconButton
+            aria-label="Close span details"
+            aria-keyshortcuts="Escape"
+            onClick={onClose}
+          >
+            <X className="w-4 h-4" />
+          </IconButton>
+        </div>
+      </div>
+      {/* Panel body */}
+      <div className="flex-1 overflow-y-auto">
+        <ErrorBoundary>
+          <EntityDetailPanel
+            run={sidebar.run}
+            onStreamClick={sidebar.onStreamClick}
+            onRunClick={sidebar.onRunClick}
+            fetchSpanDetail={sidebar.fetchSpanDetail}
+            onWakeUpSleep={sidebar.onWakeUpSleep}
+            onLoadEventData={sidebar.onLoadEventData}
+            onResolveHook={sidebar.onResolveHook}
+            encryptionKey={sidebar.encryptionKey}
+            onDecrypt={sidebar.onDecrypt}
+            isDecrypting={sidebar.isDecrypting}
+            selectedSpan={selectedSpan}
+            showSeparateEventOccurrenceTimestamps={
+              sidebar.showSeparateEventOccurrenceTimestamps
+            }
+            getModuleSourceUrl={sidebar.getModuleSourceUrl}
+          />
+        </ErrorBoundary>
+      </div>
+    </aside>
+  );
+}

package/src/components/trace-viewer/components/draggable-border.tsx

@@ -0,0 +1,216 @@
+'use client';
+
+import {
+  type KeyboardEvent as ReactKeyboardEvent,
+  type PointerEvent as ReactPointerEvent,
+  type RefObject,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import { cn } from '../../../lib/cn';
+
+interface DraggableBorderProps {
+  /** The panel whose width this border adjusts (measured on interaction). */
+  element: RefObject<HTMLElement | null>;
+  /** Which edge of the panel the border sits on. */
+  position: 'left' | 'right';
+  /**
+   * Called with the next width (px) while dragging or keyboard-resizing.
+   * The owner is responsible for clamping.
+   */
+  onWidthChange: (width: number) => void;
+  /** Double-click reset. */
+  onReset?: () => void;
+  'aria-label': string;
+  'aria-controls'?: string;
+  'aria-valuemin'?: number;
+  'aria-valuemax'?: number;
+  'aria-valuenow'?: number;
+}
+
+/**
+ * Overlay drag handle straddling a panel edge: an invisible strip over the
+ * panel's border whose center line highlights on hover/drag, with
+ * double-click reset, pointer-capture dragging (works with touch/pen, no
+ * ghost image), and keyboard/ARIA window-splitter support.
+ *
+ * The panel's positioning ancestor must not clip overflow — the strip hangs
+ * ~8px past the panel edge.
+ */
+export function DraggableBorder({
+  element,
+  position,
+  onWidthChange,
+  onReset,
+  'aria-label': ariaLabel,
+  'aria-controls': ariaControls,
+  'aria-valuemin': ariaValueMin,
+  'aria-valuemax': ariaValueMax,
+  'aria-valuenow': ariaValueNow,
+}: DraggableBorderProps) {
+  const [isDragging, setIsDragging] = useState(false);
+  const pointerIdRef = useRef<number | null>(null);
+  const startXRef = useRef(0);
+  const startWidthRef = useRef(0);
+  const pendingWidthRef = useRef(0);
+  const rafRef = useRef<number | null>(null);
+  const movedRef = useRef(false);
+  const lastDragEndAtRef = useRef(0);
+
+  useEffect(() => {
+    return () => {
+      if (rafRef.current) cancelAnimationFrame(rafRef.current);
+    };
+  }, []);
+
+  // Suppress text selection for the duration of a drag. Effect cleanup also
+  // covers the handle unmounting mid-drag (e.g. Escape closing the panel).
+  useEffect(() => {
+    if (!isDragging) return;
+    const previous = document.body.style.userSelect;
+    document.body.style.userSelect = 'none';
+    return () => {
+      document.body.style.userSelect = previous;
+    };
+  }, [isDragging]);
+
+  const stopDrag = () => {
+    pointerIdRef.current = null;
+    setIsDragging(false);
+    if (rafRef.current) {
+      cancelAnimationFrame(rafRef.current);
+      rafRef.current = null;
+      // Flush the final position that was still waiting on the next frame.
+      if (movedRef.current) onWidthChange(pendingWidthRef.current);
+    }
+    if (movedRef.current) {
+      movedRef.current = false;
+      lastDragEndAtRef.current = performance.now();
+    }
+  };
+
+  const handlePointerDown = (e: ReactPointerEvent<HTMLDivElement>) => {
+    // Ignore secondary pointers (e.g. a second finger) while a drag is active
+    // so they can't re-baseline the gesture.
+    if (pointerIdRef.current !== null) return;
+    const el = element.current;
+    if (!el) return;
+    if (e.pointerType === 'mouse' && e.button !== 0) return;
+    e.currentTarget.setPointerCapture(e.pointerId);
+    pointerIdRef.current = e.pointerId;
+    startXRef.current = e.clientX;
+    startWidthRef.current = el.offsetWidth;
+    movedRef.current = false;
+    setIsDragging(true);
+  };
+
+  // Pointer capture routes move/up events to the strip itself, so no
+  // document-level listeners are needed.
+  const handlePointerMove = (e: ReactPointerEvent<HTMLDivElement>) => {
+    if (pointerIdRef.current !== e.pointerId) return;
+    if (Math.abs(e.clientX - startXRef.current) > 4) {
+      movedRef.current = true;
+    }
+    const delta =
+      position === 'left'
+        ? startXRef.current - e.clientX
+        : e.clientX - startXRef.current;
+    pendingWidthRef.current = startWidthRef.current + delta;
+    if (!rafRef.current) {
+      rafRef.current = requestAnimationFrame(() => {
+        rafRef.current = null;
+        onWidthChange(pendingWidthRef.current);
+      });
+    }
+  };
+
+  const handlePointerEnd = (e: ReactPointerEvent<HTMLDivElement>) => {
+    if (pointerIdRef.current !== e.pointerId) return;
+    stopDrag();
+  };
+
+  const handleLostPointerCapture = (e: ReactPointerEvent<HTMLDivElement>) => {
+    if (pointerIdRef.current !== null && e.pointerId !== pointerIdRef.current) {
+      return;
+    }
+    stopDrag();
+  };
+
+  const handleDoubleClick = () => {
+    // Pointer-capture drags still emit click/dblclick (unlike HTML5 drag), so
+    // a dblclick during or right after a real drag is two resize nudges, not
+    // a reset request.
+    if (
+      movedRef.current ||
+      performance.now() - lastDragEndAtRef.current < 500
+    ) {
+      return;
+    }
+    onReset?.();
+  };
+
+  const handleKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {
+    const el = element.current;
+    if (!el) return;
+    const step = e.shiftKey ? 64 : 16;
+    // Arrows move the border in screen direction: for a left-edge border,
+    // ArrowLeft grows the panel.
+    const grow = position === 'left' ? 1 : -1;
+    let next: number | null = null;
+    if (e.key === 'ArrowLeft') {
+      next = el.offsetWidth + grow * step;
+    } else if (e.key === 'ArrowRight') {
+      next = el.offsetWidth - grow * step;
+    } else if (e.key === 'Home' && ariaValueMin !== undefined) {
+      next = ariaValueMin;
+    } else if (e.key === 'End' && ariaValueMax !== undefined) {
+      next = ariaValueMax;
+    }
+    if (next === null) return;
+    e.preventDefault();
+    onWidthChange(next);
+  };
+
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: the WAI-ARIA window-splitter pattern requires a focusable div with role=separator; <hr> cannot receive focus or drag interactions
+    <div
+      role="separator"
+      aria-orientation="vertical"
+      aria-label={ariaLabel}
+      aria-controls={ariaControls}
+      aria-valuemin={ariaValueMin}
+      aria-valuemax={ariaValueMax}
+      aria-valuenow={ariaValueNow}
+      tabIndex={0}
+      className={cn(
+        'group absolute inset-y-0 z-10 w-[17px] cursor-col-resize touch-none outline-none',
+        position === 'left' ? '-left-2' : '-right-2'
+      )}
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerEnd}
+      onPointerCancel={handlePointerEnd}
+      onLostPointerCapture={handleLostPointerCapture}
+      onDoubleClick={handleDoubleClick}
+      onKeyDown={handleKeyDown}
+    >
+      {/* Center line: sits exactly over the panel's 1px border and highlights
+          on hover/drag/focus (delayed so incidental mouse-overs don't flash).
+          pointer-events-none is load-bearing: without it this 1px line is a
+          hit target, so a double-click aimed at the line lands one click on
+          the line and (after sub-pixel jitter) the other on the strip. A
+          native dblclick only fires when both clicks share a target, so the
+          reset silently fails on the line but works just beside it. Keeping
+          the line inert makes the separator div the sole target everywhere. */}
+      <span
+        aria-hidden
+        className={cn(
+          'pointer-events-none absolute inset-y-0 left-1/2 w-px -translate-x-1/2 bg-transparent transition-colors delay-75 duration-100',
+          'group-hover:bg-gray-500 group-focus-visible:bg-[var(--ds-focus-color)]',
+          isDragging && 'bg-gray-500'
+        )}
+      />
+    </div>
+  );
+}