@shipfox/client-workflows 0.2.0

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@shipfox/client-workflows",
+  "license": "MIT",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/client/workflows"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#*": {
+      "types": "./src/*",
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    },
+    "#test/*": "./test/*"
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./feature": {
+      "development": {
+        "types": "./src/feature.ts",
+        "default": "./src/feature.ts"
+      },
+      "default": {
+        "types": "./dist/feature.d.ts",
+        "default": "./dist/feature.js"
+      }
+    },
+    "./routes/*": {
+      "development": {
+        "types": "./src/routes/*.tsx",
+        "default": "./src/routes/*.tsx"
+      },
+      "default": {
+        "types": "./dist/routes/*.d.ts",
+        "default": "./dist/routes/*.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@swc/helpers": "^0.5.17",
+    "date-fns": "^4.1.0",
+    "@shipfox/api-workflows-dto": "2.0.0",
+    "@shipfox/client-logs": "0.2.0",
+    "@shipfox/client-shell": "0.2.0",
+    "@shipfox/client-api": "0.2.0",
+    "@shipfox/client-triggers": "0.2.0",
+    "@shipfox/client-ui": "0.2.0",
+    "@shipfox/react-ui": "0.3.1"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/react-router": "^1.170.16",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@argos-ci/cli": "^5.0.0",
+    "@argos-ci/storybook": "^6.0.0",
+    "@storybook/addon-vitest": "^10.3.6",
+    "@storybook/react": "^10.0.0",
+    "@storybook/react-vite": "^10.0.0",
+    "@tailwindcss/vite": "^4.1.13",
+    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/react-router": "^1.170.16",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.1.11",
+    "@types/react-dom": "^19.1.7",
+    "@vitejs/plugin-react": "^6.0.0",
+    "@vitest/browser-playwright": "^4.1.5",
+    "happy-dom": "^20.8.3",
+    "jsdom": "^29.0.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "storybook": "^10.0.0",
+    "storybook-addon-pseudo-states": "^10.0.0",
+    "tailwindcss": "^4.1.13",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.5",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/client-test-setup": "0.0.2"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "storybook": "storybook dev -p 6007",
+    "storybook:build": "storybook build -o storybook-static",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/components/identifier/identifier.tsx

@@ -0,0 +1,178 @@
+import {useCopyToClipboard} from '@shipfox/react-ui/hooks';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Tooltip, TooltipContent, TooltipTrigger} from '@shipfox/react-ui/tooltip';
+import {Code} from '@shipfox/react-ui/typography';
+import {cn} from '@shipfox/react-ui/utils';
+import {useCallback, useEffect, useLayoutEffect, useRef, useState} from 'react';
+import {createPortal} from 'react-dom';
+
+const COPY_FEEDBACK_OFFSET_PX = 8;
+
+type CopyState = 'idle' | 'copied' | 'failed';
+
+interface FeedbackAnchor {
+  bottom: number;
+  left: number;
+  top: number;
+}
+
+export function Identifier({
+  display,
+  value,
+  label = 'identifier',
+}: {
+  display: string;
+  value: string;
+  label?: string | undefined;
+}) {
+  const [copyState, setCopyState] = useState<CopyState>('idle');
+  const [tooltipOpen, setTooltipOpen] = useState(false);
+  const [feedbackAnchor, setFeedbackAnchor] = useState<FeedbackAnchor | null>(null);
+  const buttonRef = useRef<HTMLButtonElement | null>(null);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const {copy} = useCopyToClipboard({
+    text: value,
+    onCopy: () => {
+      setTemporaryCopyState('copied', 2500);
+    },
+  });
+
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    };
+  }, []);
+
+  const resetCopyFeedback = useCallback(() => {
+    if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    setCopyState('idle');
+    setTooltipOpen(false);
+    setFeedbackAnchor(null);
+  }, []);
+
+  useEffect(() => {
+    if (copyState === 'idle') return;
+
+    window.addEventListener('scroll', resetCopyFeedback, true);
+    window.addEventListener('resize', resetCopyFeedback);
+
+    return () => {
+      window.removeEventListener('scroll', resetCopyFeedback, true);
+      window.removeEventListener('resize', resetCopyFeedback);
+    };
+  }, [copyState, resetCopyFeedback]);
+
+  function setTemporaryCopyState(state: Exclude<CopyState, 'idle'>, timeout: number) {
+    const rect = buttonRef.current?.getBoundingClientRect();
+    setCopyState(state);
+    setTooltipOpen(false);
+    setFeedbackAnchor(
+      rect
+        ? {
+            left: rect.left + rect.width / 2,
+            top: rect.top,
+            bottom: rect.bottom,
+          }
+        : null,
+    );
+    if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    timeoutRef.current = setTimeout(resetCopyFeedback, timeout);
+  }
+
+  async function handleCopy() {
+    try {
+      await copy();
+    } catch {
+      setTemporaryCopyState('failed', 2500);
+    }
+  }
+
+  const ariaLabel =
+    copyState === 'copied'
+      ? `Copied ${label} ${value}`
+      : copyState === 'failed'
+        ? `Could not copy ${label} ${value}`
+        : `Copy ${label} ${value}`;
+
+  const feedback =
+    copyState === 'copied'
+      ? {kind: copyState, label: 'Copied'}
+      : copyState === 'failed'
+        ? {kind: copyState, label: 'Could not copy'}
+        : null;
+
+  return (
+    <>
+      <Tooltip open={copyState === 'idle' ? tooltipOpen : false} onOpenChange={setTooltipOpen}>
+        <TooltipTrigger asChild>
+          <button
+            ref={buttonRef}
+            type="button"
+            aria-label={ariaLabel}
+            onClick={() => {
+              void handleCopy();
+            }}
+            className="inline-flex h-20 min-w-0 shrink-0 items-center gap-4 rounded-4 px-2 text-foreground-neutral-muted outline-none transition-colors hover:bg-background-components-hover hover:text-foreground-neutral-base focus-visible:shadow-border-interactive-with-active"
+          >
+            <Icon name="copy" aria-hidden="true" className="size-12 shrink-0" />
+            <Code as="span" variant="label" className="truncate">
+              {display}
+            </Code>
+          </button>
+        </TooltipTrigger>
+        <TooltipContent>
+          <Code as="span" variant="label" className="block max-w-[360px] truncate">
+            {value}
+          </Code>
+        </TooltipContent>
+      </Tooltip>
+      {feedback && feedbackAnchor ? (
+        <CopyFeedbackPortal anchor={feedbackAnchor} kind={feedback.kind}>
+          {feedback.label}
+        </CopyFeedbackPortal>
+      ) : null}
+    </>
+  );
+}
+
+function CopyFeedbackPortal({
+  anchor,
+  children,
+  kind,
+}: {
+  anchor: FeedbackAnchor;
+  children: string;
+  kind: Exclude<CopyState, 'idle'>;
+}) {
+  const feedbackRef = useRef<HTMLSpanElement | null>(null);
+  const [placement, setPlacement] = useState<'top' | 'bottom'>('bottom');
+
+  useLayoutEffect(() => {
+    const height = feedbackRef.current?.offsetHeight ?? 0;
+    setPlacement(anchor.top >= height + COPY_FEEDBACK_OFFSET_PX ? 'top' : 'bottom');
+  }, [anchor.top]);
+
+  if (typeof document === 'undefined') return null;
+
+  return createPortal(
+    <span
+      ref={feedbackRef}
+      role="status"
+      style={{
+        left: anchor.left,
+        top: placement === 'top' ? anchor.top : anchor.bottom,
+        transform:
+          placement === 'top'
+            ? `translate(-50%, calc(-100% - ${COPY_FEEDBACK_OFFSET_PX}px))`
+            : `translate(-50%, ${COPY_FEEDBACK_OFFSET_PX}px)`,
+      }}
+      className={cn(
+        'pointer-events-none fixed z-50 whitespace-nowrap rounded-8 bg-background-components-base px-8 py-4 text-xs font-display font-medium leading-20 shadow-tooltip',
+        kind === 'failed' ? 'text-foreground-highlight-error' : 'text-foreground-neutral-base',
+      )}
+    >
+      {children}
+    </span>,
+    document.body,
+  );
+}

package/src/components/identifier/index.ts

@@ -0,0 +1 @@
+export {Identifier} from './identifier.js';

package/src/components/job-graph/graph-model.test.ts

@@ -0,0 +1,189 @@
+import type {WorkflowRunJobDetailDto} from '@shipfox/api-workflows-dto';
+import type {Job, WorkflowRunDetail} from '#core/workflow-run.js';
+import {workflowJob, workflowRunDetail} from '#test/fixtures/workflow-run.js';
+import {buildJobGraphModel, nextJobGraphNodeId} from './graph-model.js';
+
+describe('buildJobGraphModel', () => {
+  test('returns an empty model', () => {
+    const run = makeRun({jobs: []});
+
+    const result = buildJobGraphModel({run});
+
+    expect(result.nodes).toEqual([]);
+    expect(result.edges).toEqual([]);
+    expect(result.columns).toEqual([]);
+  });
+
+  test('maps a single job with a trigger edge', () => {
+    const run = makeRun({jobs: [makeJob({name: 'build'})]});
+
+    const result = buildJobGraphModel({run});
+
+    expect(result.nodes).toMatchObject([{name: 'build', column: 0, row: 0}]);
+    expect(result.edges).toMatchObject([
+      {from: 'trigger', to: result.nodes[0]?.id, kind: 'trigger'},
+    ]);
+  });
+
+  test('resolves dependencies by job key', () => {
+    const build = makeJob({name: 'build', position: 0});
+    const deploy = makeJob({name: 'deploy', position: 1, dependencies: ['build']});
+    const run = makeRun({jobs: [deploy, build]});
+
+    const result = buildJobGraphModel({run});
+
+    expect(nodeByName(result, 'build')).toMatchObject({column: 0});
+    expect(nodeByName(result, 'deploy')).toMatchObject({column: 1, dependencies: ['build']});
+    expect(result.edges).toContainEqual(
+      expect.objectContaining({from: build.id, to: deploy.id, kind: 'dependency'}),
+    );
+  });
+
+  test('emits one trigger edge for each root job in parallel fan-out', () => {
+    const jobs = Array.from({length: 10}, (_, index) =>
+      makeJob({name: `job-${String(index + 1).padStart(2, '0')}`, position: index}),
+    );
+    const run = makeRun({jobs});
+
+    const result = buildJobGraphModel({run});
+
+    expect(result.columns).toHaveLength(1);
+    expect(result.columns[0]).toHaveLength(10);
+    expect(result.edges.filter((edge) => edge.kind === 'trigger')).toHaveLength(10);
+  });
+
+  test('orders parallel jobs by position inside a column', () => {
+    const run = makeRun({
+      jobs: [
+        makeJob({name: 'zeta', position: 2}),
+        makeJob({name: 'alpha', position: 1}),
+        makeJob({name: 'middle', position: 3}),
+      ],
+    });
+
+    const result = buildJobGraphModel({run});
+
+    expect(result.columns[0]?.map((node) => node.name)).toEqual(['alpha', 'zeta', 'middle']);
+  });
+
+  test('lays out a ten-job sequence across ten columns', () => {
+    const jobs = Array.from({length: 10}, (_, index) =>
+      makeJob({
+        name: `job-${String(index + 1).padStart(2, '0')}`,
+        position: index,
+        dependencies: index === 0 ? [] : [`job-${String(index).padStart(2, '0')}`],
+      }),
+    );
+    const run = makeRun({jobs});
+
+    const result = buildJobGraphModel({run});
+
+    expect(result.columns).toHaveLength(10);
+    expect(nodeByName(result, 'job-10')).toMatchObject({column: 9});
+  });
+
+  test('places branch siblings in the same column and a join after them', () => {
+    const build = makeJob({name: 'build', position: 0});
+    const lint = makeJob({name: 'lint', position: 1, dependencies: ['build']});
+    const testJob = makeJob({name: 'test', position: 2, dependencies: ['build']});
+    const deploy = makeJob({name: 'deploy', position: 3, dependencies: ['lint', 'test']});
+    const run = makeRun({jobs: [deploy, testJob, lint, build]});
+
+    const result = buildJobGraphModel({run});
+
+    expect(nodeByName(result, 'lint')).toMatchObject({column: 1});
+    expect(nodeByName(result, 'test')).toMatchObject({column: 1});
+    expect(nodeByName(result, 'deploy')).toMatchObject({column: 2});
+    expect(nodeByName(result, 'deploy')?.dependencies).toEqual(['lint', 'test']);
+  });
+
+  test('moves keyboard navigation across columns and rows', () => {
+    const build = makeJob({name: 'build', position: 0});
+    const lint = makeJob({name: 'lint', position: 1, dependencies: ['build']});
+    const testJob = makeJob({name: 'test', position: 2, dependencies: ['build']});
+    const deploy = makeJob({name: 'deploy', position: 3, dependencies: ['lint', 'test']});
+    const run = makeRun({jobs: [build, lint, testJob, deploy]});
+    const model = buildJobGraphModel({run});
+
+    const nextFromBuild = nextJobGraphNodeId({
+      model,
+      currentNodeId: build.id,
+      key: 'ArrowRight',
+    });
+    const downFromLint = nextJobGraphNodeId({
+      model,
+      currentNodeId: lint.id,
+      key: 'ArrowDown',
+    });
+    const rightFromTest = nextJobGraphNodeId({
+      model,
+      currentNodeId: testJob.id,
+      key: 'ArrowRight',
+    });
+
+    expect(nextFromBuild).toBe(lint.id);
+    expect(downFromLint).toBe(testJob.id);
+    expect(rightFromTest).toBe(deploy.id);
+  });
+
+  test('keeps downstream skipped status as the persisted status', () => {
+    const build = makeJob({name: 'build', status: 'failed'});
+    const deploy = makeJob({
+      name: 'deploy',
+      status: 'skipped',
+      status_reason: 'dependency_not_completed',
+      position: 1,
+      dependencies: ['build'],
+    });
+    const run = makeRun({jobs: [build, deploy]});
+
+    const result = buildJobGraphModel({run});
+
+    expect(nodeByName(result, 'deploy')).toMatchObject({
+      status: 'skipped',
+    });
+  });
+
+  test('counts only pending and running known dependencies as current', () => {
+    const pending = makeJob({name: 'build', status: 'pending'});
+    const running = makeJob({name: 'test', status: 'running', position: 1});
+    const succeeded = makeJob({name: 'lint', status: 'succeeded', position: 2});
+    const failed = makeJob({name: 'security', status: 'failed', position: 3});
+    const cancelled = makeJob({name: 'docs', status: 'cancelled', position: 4});
+    const skipped = makeJob({name: 'deploy-preview', status: 'skipped', position: 5});
+    const deploy = makeJob({
+      name: 'deploy',
+      position: 6,
+      dependencies: ['build', 'test', 'lint', 'security', 'docs', 'deploy-preview', 'missing'],
+    });
+    const run = makeRun({jobs: [deploy, skipped, cancelled, failed, succeeded, running, pending]});
+
+    const result = buildJobGraphModel({run});
+
+    expect(nodeByName(result, 'deploy')).toMatchObject({
+      currentDependencyCount: 2,
+    });
+  });
+});
+
+function nodeByName(result: ReturnType<typeof buildJobGraphModel>, name: string) {
+  return result.nodes.find((node) => node.name === name);
+}
+
+function makeRun(overrides: Partial<WorkflowRunDetail> = {}): WorkflowRunDetail {
+  return {
+    ...workflowRunDetail({
+      name: 'Deploy',
+      trigger_provider: 'github',
+      trigger_source: 'github_acme',
+      trigger_event: 'push',
+      started_at: '2026-06-21T12:00:10.000Z',
+      jobs: [],
+    }),
+    ...overrides,
+  };
+}
+
+function makeJob(overrides: Partial<WorkflowRunJobDetailDto> & {name: string}): Job {
+  return workflowJob({key: overrides.key ?? overrides.name, ...overrides});
+}

package/src/components/job-graph/graph-model.ts

@@ -0,0 +1,178 @@
+import type {Job, WorkflowRunDetail} from '#core/workflow-run.js';
+
+export type JobGraphNode = Job & {
+  column: number;
+  row: number;
+  currentDependencyCount: number;
+};
+
+export type JobGraphNavigationKey =
+  | 'ArrowRight'
+  | 'ArrowLeft'
+  | 'ArrowDown'
+  | 'ArrowUp'
+  | 'j'
+  | 'k';
+
+export interface JobGraphEdge {
+  id: string;
+  from: string;
+  to: string;
+  kind: 'trigger' | 'dependency';
+}
+
+export interface JobGraphModel {
+  nodes: JobGraphNode[];
+  edges: JobGraphEdge[];
+  columns: JobGraphNode[][];
+}
+
+export function buildJobGraphModel({run}: {run: WorkflowRunDetail}): JobGraphModel {
+  const sortedJobs = [...run.jobs].sort(compareJobs);
+  const byKey = new Map(sortedJobs.map((job) => [job.key, job]));
+  const columnMemo = new Map<string, number>();
+
+  function columnFor(job: Job, visiting = new Set<string>()): number {
+    const cached = columnMemo.get(job.id);
+    if (cached !== undefined) return cached;
+    if (visiting.has(job.id)) return 0;
+
+    const nextVisiting = new Set(visiting);
+    nextVisiting.add(job.id);
+
+    const dependencyColumns = job.dependencies
+      .map((dependencyKey) => byKey.get(dependencyKey))
+      .filter((dependency): dependency is Job => dependency !== undefined)
+      .map((dependency) => columnFor(dependency, nextVisiting));
+
+    const column = dependencyColumns.length === 0 ? 0 : Math.max(...dependencyColumns) + 1;
+    columnMemo.set(job.id, column);
+    return column;
+  }
+
+  const nodesWithoutRows = sortedJobs.map((job) =>
+    jobGraphNode(job, {
+      column: columnFor(job),
+      row: 0,
+      currentDependencyCount: currentDependencyCount(job, byKey),
+    }),
+  );
+
+  const grouped = groupColumns(nodesWithoutRows);
+  const nodes = grouped.flat();
+  const edges = buildEdges(sortedJobs, byKey);
+
+  return {
+    nodes,
+    edges,
+    columns: grouped,
+  };
+}
+
+function compareJobs(left: Job, right: Job): number {
+  return (
+    left.position - right.position ||
+    (left.name ?? left.key).localeCompare(right.name ?? right.key) ||
+    left.id.localeCompare(right.id)
+  );
+}
+
+function groupColumns(nodes: JobGraphNode[]): JobGraphNode[][] {
+  const byColumn = new Map<number, JobGraphNode[]>();
+  for (const node of nodes) {
+    const column = byColumn.get(node.column) ?? [];
+    column.push(node);
+    byColumn.set(node.column, column);
+  }
+
+  return [...byColumn.entries()]
+    .sort(([left], [right]) => left - right)
+    .map(([, column]) =>
+      column
+        .sort(
+          (left, right) =>
+            left.position - right.position ||
+            (left.name ?? left.key).localeCompare(right.name ?? right.key) ||
+            left.id.localeCompare(right.id),
+        )
+        .map((node, row) => jobGraphNode(node, {...node, row})),
+    );
+}
+
+function buildEdges(jobs: readonly Job[], byKey: ReadonlyMap<string, Job>): JobGraphEdge[] {
+  const triggerEdges = jobs
+    .filter((job) => job.dependencies.length === 0)
+    .map((job) => ({
+      id: `trigger:${job.id}`,
+      from: 'trigger',
+      to: job.id,
+      kind: 'trigger' as const,
+    }));
+
+  const dependencyEdges = jobs.flatMap((job) =>
+    job.dependencies.flatMap((dependencyKey) => {
+      const dependency = byKey.get(dependencyKey);
+      if (!dependency) return [];
+      return [
+        {
+          id: `${dependency.id}:${job.id}`,
+          from: dependency.id,
+          to: job.id,
+          kind: 'dependency' as const,
+        },
+      ];
+    }),
+  );
+
+  return [...triggerEdges, ...dependencyEdges];
+}
+
+function currentDependencyCount(job: Job, byKey: ReadonlyMap<string, Job>): number {
+  return job.dependencies.filter((dependencyKey) => {
+    const dependency = byKey.get(dependencyKey);
+    return dependency?.status === 'pending' || dependency?.status === 'running';
+  }).length;
+}
+
+function jobGraphNode(
+  job: Job,
+  layout: Pick<JobGraphNode, 'column' | 'row' | 'currentDependencyCount'>,
+): JobGraphNode {
+  return Object.assign(Object.create(Object.getPrototypeOf(job)), job, layout);
+}
+
+export function nextJobGraphNodeId({
+  model,
+  currentNodeId,
+  key,
+}: {
+  model: JobGraphModel;
+  currentNodeId: string;
+  key: JobGraphNavigationKey;
+}): string | undefined {
+  const current = model.nodes.find((node) => node.id === currentNodeId);
+  if (!current) return undefined;
+
+  switch (key) {
+    case 'ArrowRight':
+      return nodeInAdjacentColumn(model, current, 1)?.id;
+    case 'ArrowLeft':
+      return nodeInAdjacentColumn(model, current, -1)?.id;
+    case 'ArrowDown':
+    case 'j':
+      return model.columns[current.column]?.[current.row + 1]?.id;
+    case 'ArrowUp':
+    case 'k':
+      return model.columns[current.column]?.[current.row - 1]?.id;
+  }
+}
+
+function nodeInAdjacentColumn(
+  model: JobGraphModel,
+  current: JobGraphNode,
+  offset: -1 | 1,
+): JobGraphNode | undefined {
+  const column = model.columns[current.column + offset];
+  if (!column || column.length === 0) return undefined;
+  return column[Math.min(current.row, column.length - 1)];
+}

package/src/components/job-graph/index.ts

@@ -0,0 +1,2 @@
+export {JobGraph} from './job-graph.js';
+export type {JobGraphProps} from './types.js';