@shipfox/client-workflows 0.2.0

package/src/components/job-graph/job-duration-format.ts

@@ -0,0 +1,54 @@
+import {humanDuration} from '@shipfox/react-ui/utils';
+import type {JobDisplayDuration, JobExecutionTime} from '#core/workflow-run.js';
+
+export function formatJobExecutionTimeLabel(time: JobExecutionTime): string {
+  switch (time.state) {
+    case 'live':
+      return humanDuration(time.fromIso);
+    case 'fixed':
+      return formatFixedDurationLabel(time.elapsed);
+    default: {
+      const exhaustive: never = time;
+      return exhaustive;
+    }
+  }
+}
+
+export function formatJobDurationAccessibleLabel(
+  duration: JobDisplayDuration | null,
+): string | undefined {
+  if (duration === null) return undefined;
+
+  const label = formatJobExecutionTimeLabel(duration);
+  switch (duration.kind) {
+    case 'queue':
+      return duration.state === 'live' ? `queueing ${label}` : `queued ${label}`;
+    case 'run':
+      return duration.state === 'live' ? `running ${label}` : `ran ${label}`;
+    default: {
+      const exhaustive: never = duration;
+      return exhaustive;
+    }
+  }
+}
+
+function formatFixedDurationLabel({
+  years = 0,
+  months = 0,
+  weeks = 0,
+  days = 0,
+  hours = 0,
+  minutes = 0,
+  seconds = 0,
+}: Extract<JobExecutionTime, {state: 'fixed'}>['elapsed']): string {
+  const totalDays = years * 365 + months * 30 + weeks * 7 + days;
+  const totalHours = totalDays * 24 + hours;
+
+  if (totalHours > 0) return `${totalHours}h ${pad2(minutes)}m`;
+  if (minutes > 0) return `${minutes}m ${pad2(seconds)}s`;
+  return `${seconds}s`;
+}
+
+function pad2(value: number): string {
+  return value.toString().padStart(2, '0');
+}

package/src/components/job-graph/job-duration-label.tsx

@@ -0,0 +1,29 @@
+import {useTimeTick} from '@shipfox/react-ui/time-ticker';
+import {Code} from '@shipfox/react-ui/typography';
+import {humanDuration} from '@shipfox/react-ui/utils';
+import type {JobDisplayDuration} from '#core/workflow-run.js';
+import {formatJobExecutionTimeLabel} from './job-duration-format.js';
+
+export function JobDurationLabel({duration}: {duration: JobDisplayDuration | null}) {
+  if (duration === null) return null;
+
+  if (duration.state === 'live') {
+    return <LiveDurationText fromIso={duration.fromIso} />;
+  }
+
+  return <DurationText>{formatJobExecutionTimeLabel(duration)}</DurationText>;
+}
+
+function LiveDurationText({fromIso}: {fromIso: string}) {
+  useTimeTick();
+  return <DurationText>{humanDuration(fromIso)}</DurationText>;
+}
+
+function DurationText({children}: {children: string}) {
+  // The status icon names the state; the node aria-label carries the verb.
+  return (
+    <Code as="span" variant="label" className="shrink-0 tabular-nums text-foreground-neutral-muted">
+      {children}
+    </Code>
+  );
+}

package/src/components/job-graph/job-graph-content.tsx

@@ -0,0 +1,225 @@
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+import {TimeTickerProvider} from '@shipfox/react-ui/time-ticker';
+import {cn} from '@shipfox/react-ui/utils';
+import type {KeyboardEvent} from 'react';
+import {useRef, useState} from 'react';
+import type {WorkflowRunDetail} from '#core/workflow-run.js';
+import type {JobGraphModel, JobGraphNavigationKey} from './graph-model.js';
+import {nextJobGraphNodeId} from './graph-model.js';
+import {JobNode, TriggerNode} from './job-node.js';
+
+const NODE_WIDTH = 208;
+const NODE_HEIGHT = 48;
+const COLUMN_GAP = 64;
+const ROW_GAP = 20;
+const TRIGGER_WIDTH = 36;
+const PADDING = 16;
+
+export function JobGraphContent({
+  model,
+  trigger,
+  selectedJobId,
+  onSelectJob,
+}: {
+  model: JobGraphModel;
+  trigger: Pick<
+    WorkflowRunDetail,
+    'triggerDisplayLabel' | 'triggerLabel' | 'triggerProvider' | 'triggerSource'
+  >;
+  selectedJobId?: string | undefined;
+  onSelectJob: (jobId: string | undefined) => void;
+}) {
+  const nodeRefs = useRef(new Map<string, HTMLButtonElement>());
+  const [hoveredJobId, setHoveredJobId] = useState<string | undefined>();
+
+  if (model.nodes.length === 0) {
+    return (
+      <EmptyState
+        className="min-h-160 px-16 py-24"
+        icon="componentLine"
+        title="No jobs yet"
+        description="This run has not materialized jobs."
+        variant="compact"
+      />
+    );
+  }
+
+  const maxRows = Math.max(1, ...model.columns.map((column) => column.length));
+  const contentWidth =
+    PADDING * 2 +
+    TRIGGER_WIDTH +
+    COLUMN_GAP +
+    model.columns.length * NODE_WIDTH +
+    Math.max(0, model.columns.length - 1) * COLUMN_GAP;
+  const contentHeight = PADDING * 2 + maxRows * NODE_HEIGHT + Math.max(0, maxRows - 1) * ROW_GAP;
+
+  function setNodeRef(jobId: string) {
+    return (element: HTMLButtonElement | null) => {
+      if (element) {
+        nodeRefs.current.set(jobId, element);
+      } else {
+        nodeRefs.current.delete(jobId);
+      }
+    };
+  }
+
+  function handleKeyDown(event: KeyboardEvent<HTMLButtonElement>) {
+    const key = navigationKey(event.key);
+    if (!key) return;
+
+    const currentNodeId = event.currentTarget.dataset.jobId;
+    if (!currentNodeId) return;
+
+    const nextNodeId = nextJobGraphNodeId({model, currentNodeId, key});
+    if (!nextNodeId) return;
+
+    event.preventDefault();
+    onSelectJob(nextNodeId);
+    nodeRefs.current.get(nextNodeId)?.focus();
+  }
+
+  return (
+    <TimeTickerProvider intervalMs={1000} reducedMotionIntervalMs={10_000}>
+      <div className="min-h-0 overflow-auto bg-background-neutral-base">
+        <div className="relative" style={{width: contentWidth, minHeight: contentHeight}}>
+          <GraphEdges model={model} hoveredJobId={hoveredJobId} />
+          <div
+            className="absolute"
+            style={{left: PADDING, top: PADDING + (NODE_HEIGHT - TRIGGER_WIDTH) / 2}}
+          >
+            <TriggerNode trigger={trigger} />
+          </div>
+          {model.columns.map((column, columnIndex) => (
+            <div
+              key={column.map((node) => node.id).join(':')}
+              className="absolute flex flex-col gap-20"
+              style={{left: jobLeft(columnIndex), top: PADDING}}
+            >
+              {column.map((node) => (
+                <JobNode
+                  key={node.id}
+                  node={node}
+                  selected={node.id === selectedJobId}
+                  ref={setNodeRef(node.id)}
+                  onSelect={() => onSelectJob(node.id === selectedJobId ? undefined : node.id)}
+                  onKeyDown={handleKeyDown}
+                  onHoverStart={() => setHoveredJobId(node.id)}
+                  onHoverEnd={() =>
+                    setHoveredJobId((current) => (current === node.id ? undefined : current))
+                  }
+                />
+              ))}
+            </div>
+          ))}
+        </div>
+      </div>
+    </TimeTickerProvider>
+  );
+}
+
+function navigationKey(key: string): JobGraphNavigationKey | undefined {
+  if (
+    key === 'ArrowRight' ||
+    key === 'ArrowLeft' ||
+    key === 'ArrowDown' ||
+    key === 'ArrowUp' ||
+    key === 'j' ||
+    key === 'k'
+  ) {
+    return key;
+  }
+  return undefined;
+}
+
+function GraphEdges({
+  model,
+  hoveredJobId,
+}: {
+  model: JobGraphModel;
+  hoveredJobId?: string | undefined;
+}) {
+  const byId = new Map(model.nodes.map((node) => [node.id, node]));
+  const edgeViews = model.edges
+    .map((edge) => {
+      const fromNode = byId.get(edge.from);
+      const toNode = byId.get(edge.to);
+      const from = edge.from === 'trigger' ? triggerPoint() : jobRightPoint(fromNode);
+      const to = jobLeftPoint(toNode);
+      if (!from || !to) return undefined;
+
+      return {
+        id: edge.id,
+        highlighted: edge.from === hoveredJobId || edge.to === hoveredJobId,
+        path: edgePath({from, fromNode, to, toNode}),
+      };
+    })
+    .filter((edgeView): edgeView is NonNullable<typeof edgeView> => edgeView !== undefined)
+    .sort((left, right) => Number(left.highlighted) - Number(right.highlighted));
+
+  return (
+    <svg className="pointer-events-none absolute inset-0 size-full" aria-hidden="true">
+      {edgeViews.map((edge) => {
+        return (
+          <g
+            key={edge.id}
+            className={cn(
+              'text-foreground-neutral-muted transition-colors',
+              edge.highlighted && 'text-foreground-neutral-base',
+            )}
+          >
+            <path
+              data-edge-id={edge.id}
+              d={edge.path}
+              fill="none"
+              stroke="currentColor"
+              strokeWidth={edge.highlighted ? 1.5 : 1}
+            />
+          </g>
+        );
+      })}
+    </svg>
+  );
+}
+
+function edgePath({
+  from,
+  fromNode,
+  to,
+  toNode,
+}: {
+  from: {x: number; y: number};
+  fromNode: {column: number} | undefined;
+  to: {x: number; y: number};
+  toNode: {column: number} | undefined;
+}) {
+  if (fromNode && toNode && toNode.column - fromNode.column > 1 && from.y !== to.y) {
+    const targetLaneX = to.x - COLUMN_GAP / 2;
+    return `M ${from.x} ${from.y} H ${targetLaneX} V ${to.y} H ${to.x}`;
+  }
+
+  const midX = from.x + (to.x - from.x) / 2;
+  return `M ${from.x} ${from.y} H ${midX} V ${to.y} H ${to.x}`;
+}
+
+function triggerPoint() {
+  return {x: PADDING + TRIGGER_WIDTH, y: PADDING + NODE_HEIGHT / 2};
+}
+
+function jobLeft(column: number): number {
+  // Dependency depths are contiguous, so a node's depth matches its rendered column index.
+  return PADDING + TRIGGER_WIDTH + COLUMN_GAP + column * (NODE_WIDTH + COLUMN_GAP);
+}
+
+function jobTop(row: number): number {
+  return PADDING + row * (NODE_HEIGHT + ROW_GAP);
+}
+
+function jobLeftPoint(node: {column: number; row: number} | undefined) {
+  if (!node) return undefined;
+  return {x: jobLeft(node.column), y: jobTop(node.row) + NODE_HEIGHT / 2};
+}
+
+function jobRightPoint(node: {column: number; row: number} | undefined) {
+  if (!node) return undefined;
+  return {x: jobLeft(node.column) + NODE_WIDTH, y: jobTop(node.row) + NODE_HEIGHT / 2};
+}

package/src/components/job-graph/job-graph-view.test.tsx

@@ -0,0 +1,298 @@
+import type {WorkflowRunJobDetailDto} from '@shipfox/api-workflows-dto';
+import {fireEvent, render, screen, within} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type {Job, WorkflowRunDetail} from '#core/workflow-run.js';
+import {
+  workflowJob,
+  workflowJobExecutionDto,
+  workflowRunDetail,
+} from '#test/fixtures/workflow-run.js';
+import {JobGraph} from './job-graph.js';
+
+describe('JobGraph', () => {
+  test('renders a graph region and trigger', () => {
+    render(<JobGraph run={makeRun({jobs: [makeJob({name: 'build'})]})} />);
+
+    expect(screen.getByRole('region', {name: 'Workflow jobs'})).toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'fire'})).toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'build, Pending'})).toBeInTheDocument();
+  });
+
+  test('selects and unselects a job locally', async () => {
+    const user = userEvent.setup();
+    render(<JobGraph run={makeRun({jobs: [makeJob({name: 'build'})]})} />);
+    const build = screen.getByRole('button', {name: 'build, Pending'});
+
+    await user.click(build);
+
+    expect(build).toHaveAttribute('aria-pressed', 'true');
+
+    await user.click(build);
+
+    expect(build).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  test('supports an initially selected job', () => {
+    const buildJob = makeJob({name: 'build'});
+    render(<JobGraph run={makeRun({jobs: [buildJob]})} defaultSelectedJobId={buildJob.id} />);
+
+    expect(screen.getByRole('button', {name: 'build, Pending'})).toHaveAttribute(
+      'aria-pressed',
+      'true',
+    );
+  });
+
+  test('renders two running jobs at the same time', () => {
+    render(
+      <JobGraph
+        run={makeRun({
+          jobs: [
+            makeJob({name: 'linux', status: 'running'}),
+            makeJob({name: 'macos', status: 'running', position: 1}),
+          ],
+        })}
+      />,
+    );
+
+    expect(screen.getByRole('button', {name: 'linux, Running'})).toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'macos, Running'})).toBeInTheDocument();
+  });
+
+  test('renders a downstream job skipped after an upstream failure', () => {
+    render(
+      <JobGraph
+        run={makeRun({
+          jobs: [
+            makeJob({name: 'build', status: 'failed'}),
+            makeJob({
+              name: 'deploy',
+              status: 'skipped',
+              status_reason: 'dependency_not_completed',
+              position: 1,
+              dependencies: ['build'],
+            }),
+          ],
+        })}
+      />,
+    );
+
+    expect(screen.getByRole('button', {name: 'build, Failed'})).toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'deploy, Skipped'})).toBeInTheDocument();
+  });
+
+  test('renders an empty state', () => {
+    render(<JobGraph run={makeRun({jobs: []})} />);
+
+    expect(screen.getByText('No jobs yet')).toBeInTheDocument();
+  });
+
+  test('keeps long names accessible while truncating visually', () => {
+    const name = 'release-production-multi-region-with-canary-and-smoke-tests';
+    render(<JobGraph run={makeRun({jobs: [makeJob({name})]})} />);
+
+    expect(screen.getByRole('button', {name: `${name}, Pending`})).toBeInTheDocument();
+  });
+
+  test('does not show dependency counts in the job node label', () => {
+    render(
+      <JobGraph
+        run={makeRun({
+          jobs: [
+            makeJob({name: 'build'}),
+            makeJob({name: 'deploy', position: 1, dependencies: ['build'], status: 'running'}),
+          ],
+        })}
+      />,
+    );
+
+    expect(screen.getByRole('button', {name: 'deploy, Running'})).toBeInTheDocument();
+    expect(screen.queryByText('1')).not.toBeInTheDocument();
+  });
+
+  test('does not show multiple pending dependency counts', () => {
+    render(
+      <JobGraph
+        run={makeRun({
+          jobs: [
+            makeJob({name: 'build'}),
+            makeJob({name: 'lint', position: 1}),
+            makeJob({name: 'deploy', position: 2, dependencies: ['build', 'lint']}),
+          ],
+        })}
+      />,
+    );
+
+    const deploy = screen.getByRole('button', {name: 'deploy, Pending'});
+    expect(deploy).toBeInTheDocument();
+    expect(within(deploy).queryByText('2')).not.toBeInTheDocument();
+  });
+
+  test('hides the dependency pill when upstream jobs are resolved', () => {
+    render(
+      <JobGraph
+        run={makeRun({
+          jobs: [
+            makeJob({name: 'build', status: 'succeeded'}),
+            makeJob({name: 'deploy', position: 1, dependencies: ['build']}),
+          ],
+        })}
+      />,
+    );
+
+    const deploy = screen.getByRole('button', {name: 'deploy, Pending'});
+    expect(within(deploy).queryByText('1')).not.toBeInTheDocument();
+  });
+
+  test('marks jobs with multiple executions without showing dependency counts', () => {
+    render(
+      <JobGraph
+        run={makeRun({
+          jobs: [
+            makeJob({
+              name: 'build',
+              job_executions: [
+                workflowJobExecutionDto({sequence: 1, status: 'failed'}),
+                workflowJobExecutionDto({sequence: 2, status: 'succeeded'}),
+              ],
+            }),
+            makeJob({name: 'deploy', position: 1, dependencies: ['build']}),
+          ],
+        })}
+      />,
+    );
+
+    const build = screen.getByRole('button', {name: 'build, Pending, 2 executions'});
+    const deploy = screen.getByRole('button', {name: 'deploy, Pending'});
+    expect(within(build).getByText('2')).toBeInTheDocument();
+    expect(within(build).queryByText('2 exec')).not.toBeInTheDocument();
+    expect(within(deploy).queryByText('1')).not.toBeInTheDocument();
+  });
+
+  test('moves selection and focus with graph keyboard navigation', async () => {
+    const user = userEvent.setup();
+    render(
+      <JobGraph
+        run={makeRun({
+          jobs: [
+            makeJob({name: 'build'}),
+            makeJob({name: 'deploy', position: 1, dependencies: ['build']}),
+          ],
+        })}
+      />,
+    );
+
+    const build = screen.getByRole('button', {name: 'build, Pending'});
+    const deploy = screen.getByRole('button', {name: 'deploy, Pending'});
+    build.focus();
+
+    await user.keyboard('{ArrowRight}');
+
+    expect(deploy).toHaveFocus();
+    expect(deploy).toHaveAttribute('aria-pressed', 'true');
+    expect(build).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  test('highlights adjacent edges only while hovering a job', async () => {
+    const user = userEvent.setup();
+    const build = makeJob({name: 'build'});
+    const deploy = makeJob({name: 'deploy', position: 1, dependencies: ['build']});
+    const {container} = render(<JobGraph run={makeRun({jobs: [build, deploy]})} />);
+    const triggerEdge = container.querySelector(`[data-edge-id="trigger:${build.id}"]`);
+    const deployEdge = container.querySelector(`[data-edge-id="${build.id}:${deploy.id}"]`);
+    const deployNode = screen.getByRole('button', {name: 'deploy, Pending'});
+
+    fireEvent.click(deployNode);
+
+    expect(deployEdge).toHaveAttribute('stroke-width', '1');
+
+    await user.hover(deployNode);
+
+    expect(deployEdge).toHaveAttribute('stroke-width', '1.5');
+    expect(triggerEdge).toHaveAttribute('stroke-width', '1');
+
+    await user.unhover(deployNode);
+
+    expect(deployEdge).toHaveAttribute('stroke-width', '1');
+  });
+
+  test('draws highlighted edges above overlapping normal edges', async () => {
+    const user = userEvent.setup();
+    const build = makeJob({name: 'build', status: 'succeeded'});
+    const lint = makeJob({
+      name: 'lint',
+      position: 1,
+      dependencies: ['build'],
+      status: 'succeeded',
+    });
+    const testJob = makeJob({
+      name: 'test',
+      position: 2,
+      dependencies: ['build'],
+      status: 'running',
+    });
+    const deploy = makeJob({
+      name: 'deploy',
+      position: 3,
+      dependencies: ['lint', 'test'],
+    });
+    const {container} = render(<JobGraph run={makeRun({jobs: [build, lint, testJob, deploy]})} />);
+    const buildToLintEdge = container.querySelector(`[data-edge-id="${build.id}:${lint.id}"]`);
+    const buildToTestEdge = container.querySelector(`[data-edge-id="${build.id}:${testJob.id}"]`);
+    const testNode = screen.getByRole('button', {
+      name: 'test, Running',
+    });
+
+    await user.hover(testNode);
+
+    expect(buildToTestEdge).toHaveAttribute('stroke-width', '1.5');
+    expect(buildToLintEdge).toHaveAttribute('stroke-width', '1');
+    if (!buildToLintEdge || !buildToTestEdge) {
+      throw new Error('Expected branch edges to render');
+    }
+    expect(buildToLintEdge.compareDocumentPosition(buildToTestEdge)).toBe(
+      Node.DOCUMENT_POSITION_FOLLOWING,
+    );
+  });
+
+  test('routes skipped-column join edges away from intermediate nodes', () => {
+    const packageJob = makeJob({name: 'package', position: 0, status: 'succeeded'});
+    const securityScan = makeJob({name: 'security-scan', position: 1, status: 'succeeded'});
+    const smokeTests = makeJob({
+      name: 'smoke-tests',
+      position: 2,
+      dependencies: ['package'],
+      status: 'running',
+    });
+    const deploy = makeJob({
+      name: 'deploy',
+      position: 3,
+      dependencies: ['smoke-tests', 'security-scan'],
+    });
+
+    const {container} = render(
+      <JobGraph run={makeRun({jobs: [packageJob, securityScan, smokeTests, deploy]})} />,
+    );
+
+    const skippedJoinEdge = container.querySelector(
+      `[data-edge-id="${securityScan.id}:${deploy.id}"]`,
+    );
+    expect(skippedJoinEdge).toHaveAttribute('d', 'M 324 108 H 628 V 40 H 660');
+  });
+});
+
+function makeRun(overrides: Partial<WorkflowRunDetail> = {}): WorkflowRunDetail {
+  return {
+    ...workflowRunDetail({
+      name: 'Deploy',
+      trigger_source: 'manual',
+      trigger_event: 'fire',
+      started_at: '2026-06-21T12:00:10.000Z',
+      jobs: [],
+    }),
+    ...overrides,
+  };
+}
+
+function makeJob(overrides: Partial<WorkflowRunJobDetailDto> & {name: string}): Job {
+  return workflowJob(overrides);
+}

package/src/components/job-graph/job-graph-view.tsx

@@ -0,0 +1,45 @@
+import {cn} from '@shipfox/react-ui/utils';
+import {useState} from 'react';
+import type {WorkflowRunDetail} from '#core/workflow-run.js';
+import type {JobGraphModel} from './graph-model.js';
+import {JobGraphContent} from './job-graph-content.js';
+
+export function JobGraphView({
+  model,
+  trigger,
+  selectedJobId,
+  defaultSelectedJobId,
+  onSelectedJobChange,
+  className,
+}: {
+  model: JobGraphModel;
+  trigger: Pick<
+    WorkflowRunDetail,
+    'triggerDisplayLabel' | 'triggerLabel' | 'triggerProvider' | 'triggerSource'
+  >;
+  selectedJobId?: string | undefined;
+  defaultSelectedJobId?: string | undefined;
+  onSelectedJobChange?: ((jobId: string | undefined) => void) | undefined;
+  className?: string | undefined;
+}) {
+  const [localSelectedJobId, setLocalSelectedJobId] = useState<string | undefined>(
+    defaultSelectedJobId,
+  );
+  const selected = selectedJobId ?? localSelectedJobId;
+
+  function selectJob(jobId: string | undefined) {
+    setLocalSelectedJobId(jobId);
+    onSelectedJobChange?.(jobId);
+  }
+
+  return (
+    <section aria-label="Workflow jobs" className={cn('min-h-0', className)}>
+      <JobGraphContent
+        model={model}
+        trigger={trigger}
+        selectedJobId={selected}
+        onSelectJob={selectJob}
+      />
+    </section>
+  );
+}