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

package/src/components/trace-viewer/components/trace-shortcut-helper.module.css

@@ -0,0 +1,20 @@
+/* Only one hint is in the DOM at a time; it is remounted on each rotation
+   (keyed by index in React) so this short fade-in plays as a crossfade. */
+.hint {
+  animation: trace-shortcut-hint-fade 150ms ease-in-out;
+}
+
+@keyframes trace-shortcut-hint-fade {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hint {
+    animation: none;
+  }
+}

package/src/components/trace-viewer/components/trace-shortcut-helper.tsx

@@ -0,0 +1,116 @@
+'use client';
+
+import { X } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { Kbd } from '../../ui/kbd';
+import styles from './trace-shortcut-helper.module.css';
+
+const DISMISSALS_KEY = 'workflow-step-shortcut-helper-dismissals';
+const DISMISSAL_LIMIT = 3;
+const HINT_ROTATION_MS = 8000;
+
+function getAltKeyLabel(): 'Alt' | 'Option' {
+  if (typeof navigator === 'undefined') return 'Alt';
+  return navigator.platform.toLowerCase().includes('mac') ? 'Option' : 'Alt';
+}
+
+function readDismissals(): number {
+  try {
+    const dismissals = Number.parseInt(
+      window.localStorage.getItem(DISMISSALS_KEY) ?? '0',
+      10
+    );
+    return Number.isNaN(dismissals) ? 0 : dismissals;
+  } catch {
+    return 0;
+  }
+}
+
+function AltHint() {
+  return (
+    <>
+      Hold
+      <Kbd variant="outline" size="compact" className="mx-1">
+        {getAltKeyLabel()}
+      </Kbd>
+      to see delta between spans
+    </>
+  );
+}
+
+function NavHint() {
+  return (
+    <>
+      Use
+      <Kbd variant="outline" size="compact" className="ml-1">
+        J
+      </Kbd>
+      <span className="mx-1">/</span>
+      <Kbd variant="outline" size="compact" className="mr-1">
+        K
+      </Kbd>
+      to move between spans
+    </>
+  );
+}
+
+export function TraceShortcutHelper({
+  hasMultipleSpans,
+  reducedMotion,
+}: {
+  hasMultipleSpans: boolean;
+  reducedMotion: boolean;
+}) {
+  const [visible, setVisible] = useState(false);
+  const [index, setIndex] = useState(0);
+
+  useEffect(() => {
+    setVisible(readDismissals() < DISMISSAL_LIMIT);
+  }, []);
+
+  useEffect(() => {
+    if (reducedMotion) return;
+    const id = setInterval(() => {
+      setIndex((i) => (i === 0 ? 1 : 0));
+    }, HINT_ROTATION_MS);
+    return () => clearInterval(id);
+  }, [reducedMotion]);
+
+  if (!visible || !hasMultipleSpans) return null;
+
+  const dismiss = () => {
+    try {
+      window.localStorage.setItem(DISMISSALS_KEY, String(readDismissals() + 1));
+    } catch {}
+    setVisible(false);
+  };
+
+  return (
+    <div className="group pointer-events-auto hidden h-8 w-fit items-center gap-1 text-label-12 leading-none text-gray-900 @min-[480px]:flex">
+      <span
+        aria-live="polite"
+        aria-atomic="true"
+        className="inline-flex items-center whitespace-nowrap"
+      >
+        {reducedMotion ? (
+          <AltHint />
+        ) : (
+          <span
+            key={index}
+            className={`inline-flex items-center ${styles.hint}`}
+          >
+            {index === 0 ? <AltHint /> : <NavHint />}
+          </span>
+        )}
+      </span>
+      <button
+        type="button"
+        className="inline-flex h-5 w-5 items-center justify-center rounded text-muted-foreground opacity-0 transition-opacity hover:bg-accent hover:text-foreground group-hover:opacity-100 focus-visible:opacity-100 motion-reduce:transition-none"
+        onClick={dismiss}
+        aria-label="Dismiss trace shortcuts helper"
+      >
+        <X className="h-3 w-3" />
+      </button>
+    </div>
+  );
+}

package/src/components/trace-viewer/components/trace-viewer-skeleton.tsx

@@ -0,0 +1,114 @@
+import { Skeleton } from '../../ui/skeleton';
+import { DEFAULT_START_PX, paneColTemplate } from './pane-constants';
+
+// Mirrors SplitPane's initial column template so the skeleton lines up with
+// the real viewer's first paint.
+const COL_TEMPLATE = paneColTemplate(DEFAULT_START_PX);
+
+const ROWS: { id: string; name: number; off: number; bar: number }[] = [
+  { id: 'r0', name: 62, off: 0, bar: 72 },
+  { id: 'r1', name: 78, off: 6, bar: 48 },
+  { id: 'r2', name: 50, off: 10, bar: 55 },
+  { id: 'r3', name: 84, off: 18, bar: 30 },
+  { id: 'r4', name: 45, off: 18, bar: 42 },
+  { id: 'r5', name: 66, off: 34, bar: 38 },
+  { id: 'r6', name: 55, off: 41, bar: 25 },
+  { id: 'r7', name: 40, off: 50, bar: 30 },
+];
+
+const HEADER_MARKERS = ['m0', 'm1', 'm2', 'm3'];
+
+const HeaderDivider = () => (
+  <div className="flex justify-center">
+    <span aria-hidden className="h-full w-px bg-gray-alpha-400" />
+  </div>
+);
+
+export function TraceViewerSkeleton() {
+  return (
+    <output
+      aria-busy="true"
+      aria-label="Loading trace"
+      className="flex flex-col w-full h-full min-h-0 bg-background-100"
+    >
+      <span className="sr-only">Loading trace…</span>
+
+      {/* Minimap strip: thin density lines tracing the same shape as the bars */}
+      <div className="relative h-10 min-h-10 shrink-0 border-b border-gray-alpha-400">
+        <div className="absolute inset-x-4 top-[6px]">
+          {ROWS.map((row, index) => (
+            <Skeleton
+              key={row.id}
+              className="absolute h-[3px] rounded-full"
+              style={{
+                left: `${row.off}%`,
+                width: `${row.bar}%`,
+                top: index * 3.5,
+              }}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Header row: search header | divider | timeline header */}
+      <div
+        className="shrink-0 grid"
+        style={{ gridTemplateColumns: COL_TEMPLATE }}
+      >
+        <div className="h-10 min-h-10 flex items-center border-b border-gray-alpha-400 pl-4 pr-2 gap-1.5">
+          <Skeleton className="w-3.5 h-3.5 shrink-0 rounded-sm" />
+          <Skeleton className="h-3.5 w-40" />
+        </div>
+        <HeaderDivider />
+        <div className="h-10 min-h-10 flex items-end border-b border-gray-alpha-400 px-4 pb-1 gap-2">
+          <div className="relative flex-1 flex items-end justify-between">
+            {HEADER_MARKERS.map((id) => (
+              <Skeleton key={id} className="h-3.5 w-9" />
+            ))}
+          </div>
+        </div>
+      </div>
+
+      {/* Content row: event list | gutter | timeline */}
+      <div
+        className="grid flex-1 min-h-0 overflow-hidden"
+        style={{ gridTemplateColumns: COL_TEMPLATE }}
+      >
+        {/* Sidebar event rows */}
+        <div className="block overflow-visible">
+          <ul className="block divide-y divide-gray-alpha-400 border-b border-gray-alpha-400">
+            {ROWS.map((row) => (
+              <li key={row.id} className="h-10 flex items-center pl-4 pr-2">
+                <div className="flex min-w-0 flex-1 items-center gap-2">
+                  <Skeleton className="w-4 h-4 shrink-0 rounded-sm" />
+                  <Skeleton
+                    className="h-3.5"
+                    style={{ width: `${row.name}%` }}
+                  />
+                </div>
+                <Skeleton className="ml-2 h-3.5 w-10 shrink-0" />
+              </li>
+            ))}
+          </ul>
+        </div>
+
+        {/* Gutter */}
+        <span aria-hidden className="h-full w-px bg-gray-alpha-400" />
+
+        {/* Timeline bars */}
+        <div className="relative min-h-0">
+          {ROWS.map((row) => (
+            <div key={row.id} className="relative h-10">
+              <div className="absolute inset-x-4 inset-y-0">
+                <Skeleton
+                  className="absolute top-1/2 -translate-y-1/2 h-6 rounded-[0.25rem]"
+                  style={{ left: `${row.off}%`, width: `${row.bar}%` }}
+                />
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </output>
+  );
+}

package/src/components/trace-viewer/components/use-element-width.ts

@@ -0,0 +1,29 @@
+'use client';
+
+import { type RefObject, useLayoutEffect, useState } from 'react';
+
+/**
+ * Observed width (px) of `ref`'s element. Measures synchronously before paint
+ * when (re-)enabled, then tracks resizes. While disabled it keeps the last
+ * measured value; re-enabling re-measures before the next paint.
+ */
+export function useElementWidth(
+  ref: RefObject<HTMLElement | null>,
+  enabled = true
+): number {
+  const [width, setWidth] = useState(0);
+
+  useLayoutEffect(() => {
+    if (!enabled) return;
+    const el = ref.current;
+    if (!el) return;
+    setWidth(Math.round(el.getBoundingClientRect().width));
+    const observer = new ResizeObserver(([entry]) => {
+      setWidth(Math.round(entry?.contentRect.width ?? 0));
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [ref, enabled]);
+
+  return width;
+}

package/src/components/trace-viewer/components/use-row-window.ts

@@ -0,0 +1,140 @@
+'use client';
+
+import { type RefObject, useEffect, useState } from 'react';
+
+/** Rows rendered on the first paint, before the container has been measured. */
+const INITIAL_VISIBLE_ROWS = 60;
+
+export interface RowWindow {
+  /** First visible row index (inclusive), already padded by overscan. */
+  start: number;
+  /** Last visible row index (exclusive), already padded by overscan. */
+  end: number;
+}
+
+/** Nearest scrollable ancestor of `el` (the shared `SplitPane` container). */
+function getScrollParent(el: HTMLElement | null): HTMLElement | null {
+  let node = el?.parentElement ?? null;
+  while (node) {
+    const overflowY = getComputedStyle(node).overflowY;
+    if (overflowY === 'auto' || overflowY === 'scroll') return node;
+    node = node.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Fixed-height windowing over a shared scroll container.
+ *
+ * The events list and timeline both render one `rowHeight`-tall row per span
+ * and scroll together inside the same `SplitPane`. Each caller passes a ref to
+ * its own root; the hook walks up to the shared scrollable ancestor, so the
+ * scroll container doesn't have to be threaded through props. Same scroll
+ * position + same row height means both panes window to the same range.
+ */
+export function useRowWindow(
+  ref: RefObject<HTMLElement | null>,
+  rowCount: number,
+  rowHeight: number,
+  overscan = 12
+): RowWindow {
+  // Bound the pre-measurement window so the first paint of a large trace
+  // doesn't render every row before the effect narrows it down.
+  const [range, setRange] = useState<RowWindow>(() => ({
+    start: 0,
+    end: Math.min(rowCount, INITIAL_VISIBLE_ROWS),
+  }));
+
+  useEffect(() => {
+    const self = ref.current;
+    const el = getScrollParent(self);
+    if (!self || !el) return;
+
+    let raf = 0;
+    const measure = () => {
+      raf = 0;
+      // Offset of the list's top within the scroll container's content, so the
+      // window stays correct even if the list isn't flush with the top.
+      const offset =
+        self.getBoundingClientRect().top -
+        el.getBoundingClientRect().top +
+        el.scrollTop;
+      const top = el.scrollTop - offset;
+      const start = Math.max(0, Math.floor(top / rowHeight) - overscan);
+      const end = Math.min(
+        rowCount,
+        Math.ceil((top + el.clientHeight) / rowHeight) + overscan
+      );
+      setRange((prev) =>
+        prev.start === start && prev.end === end ? prev : { start, end }
+      );
+    };
+
+    const onScroll = () => {
+      if (!raf) raf = requestAnimationFrame(measure);
+    };
+
+    measure();
+    el.addEventListener('scroll', onScroll, { passive: true });
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+
+    return () => {
+      el.removeEventListener('scroll', onScroll);
+      ro.disconnect();
+      if (raf) cancelAnimationFrame(raf);
+    };
+  }, [ref, rowCount, rowHeight, overscan]);
+
+  return range;
+}
+
+/** Row height (px) shared by the events list and timeline rows (`h-10`). */
+export const ROW_HEIGHT_PX = 40;
+
+/**
+ * Scroll a windowed row into view by index.
+ *
+ * The list is virtualized (fixed `rowHeight` rows), so an off-screen row has no
+ * DOM node to `scrollIntoView` — its target offset is computed from its index
+ * instead. Walks up from `listEl` to the shared scrollable ancestor (the same
+ * one `useRowWindow` measures against), only scrolls when the row sits outside
+ * the visible area, leaves a one-row `margin` of breathing room past it, and
+ * clamps the result to `[0, scrollHeight - clientHeight]`.
+ */
+export function scrollRowIntoView(
+  listEl: HTMLElement | null,
+  index: number,
+  rowHeight: number,
+  opts?: { margin?: number; behavior?: ScrollBehavior }
+): void {
+  const scroller = listEl ? getScrollParent(listEl) : null;
+  if (!listEl || !scroller) return;
+
+  const margin = opts?.margin ?? rowHeight;
+
+  // Offset of the list's top within the scroll container's content.
+  const listOffset =
+    listEl.getBoundingClientRect().top -
+    scroller.getBoundingClientRect().top +
+    scroller.scrollTop;
+
+  const rowTop = listOffset + index * rowHeight;
+  const rowBottom = rowTop + rowHeight;
+  const viewTop = scroller.scrollTop;
+  const viewBottom = viewTop + scroller.clientHeight;
+
+  let top: number | null = null;
+  if (rowTop < viewTop) {
+    top = rowTop - margin;
+  } else if (rowBottom > viewBottom) {
+    top = rowBottom + margin - scroller.clientHeight;
+  }
+  if (top === null) return;
+
+  const max = scroller.scrollHeight - scroller.clientHeight;
+  scroller.scrollTo({
+    top: Math.max(0, Math.min(top, max)),
+    behavior: opts?.behavior,
+  });
+}