@shipfox/client-workflows 0.2.0

package/src/components/workflow-run-list/types.ts

@@ -0,0 +1,22 @@
+import type {QueryLoadErrorQuery} from '@shipfox/client-ui';
+import type {WorkflowRunListItem} from '#core/workflow-run.js';
+
+export type WorkflowRunListStatusFilter = 'all' | 'failed' | 'running';
+
+export interface WorkflowRunListProps {
+  workspaceId: string;
+  projectId: string;
+  selectedWorkflowRunId?: string | undefined;
+  className?: string | undefined;
+}
+
+export type WorkflowRunListQuery = QueryLoadErrorQuery & {isPending: boolean};
+
+export interface WorkflowRunListViewProps {
+  runs: WorkflowRunListItem[];
+  query: WorkflowRunListQuery;
+  workspaceId: string;
+  projectId: string;
+  selectedWorkflowRunId?: string | undefined;
+  className?: string | undefined;
+}

package/src/components/workflow-run-list/workflow-run-list-content.tsx

@@ -0,0 +1,58 @@
+import {QueryLoadError} from '@shipfox/client-ui';
+import type {WorkflowRunListItem} from '#core/workflow-run.js';
+import type {WorkflowRunListQuery} from './types.js';
+import {
+  WorkflowRunListEmpty,
+  WorkflowRunListNoMatches,
+  WorkflowRunListSkeleton,
+  WorkflowRunListStaleError,
+} from './workflow-run-list-states.js';
+import {WorkflowRunRowList} from './workflow-run-row.js';
+
+interface WorkflowRunListContentProps {
+  query: WorkflowRunListQuery;
+  totalRuns: number;
+  runs: WorkflowRunListItem[];
+  workspaceId: string;
+  projectId: string;
+  selectedWorkflowRunId?: string | undefined;
+  onClearFilters: () => void;
+}
+
+export function WorkflowRunListContent({
+  query,
+  totalRuns,
+  runs,
+  workspaceId,
+  projectId,
+  selectedWorkflowRunId,
+  onClearFilters,
+}: WorkflowRunListContentProps) {
+  const {isPending, isError} = query;
+  // A refetch that fails after a prior success keeps the rows on screen behind a slim
+  // banner. QueryLoadError owns the inverse case (errored before anything loaded) and
+  // self-gates to nothing here once data exists.
+  const refreshFailed = isError && query.data !== undefined;
+
+  return (
+    <div className="min-h-0 flex-1 overflow-y-auto">
+      {isPending ? <WorkflowRunListSkeleton /> : null}
+      {!isPending ? (
+        <QueryLoadError query={query} subject="workflow runs" icon="pulseLine" />
+      ) : null}
+      {!isPending && refreshFailed ? <WorkflowRunListStaleError query={query} /> : null}
+      {!isPending && !isError && totalRuns === 0 ? <WorkflowRunListEmpty /> : null}
+      {!isPending && totalRuns > 0 && runs.length === 0 ? (
+        <WorkflowRunListNoMatches onClear={onClearFilters} />
+      ) : null}
+      {!isPending && runs.length > 0 ? (
+        <WorkflowRunRowList
+          runs={runs}
+          workspaceId={workspaceId}
+          projectId={projectId}
+          selectedWorkflowRunId={selectedWorkflowRunId}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/components/workflow-run-list/workflow-run-list-header.tsx

@@ -0,0 +1,53 @@
+import {Button} from '@shipfox/react-ui/button';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Input} from '@shipfox/react-ui/input';
+import type {WorkflowRunListStatusFilter} from './types.js';
+
+const STATUS_FILTERS: Array<{value: WorkflowRunListStatusFilter; label: string}> = [
+  {value: 'all', label: 'All'},
+  {value: 'failed', label: 'Failed'},
+  {value: 'running', label: 'Running'},
+];
+
+interface WorkflowRunListHeaderProps {
+  query: string;
+  onQueryChange: (value: string) => void;
+  statusFilter: WorkflowRunListStatusFilter;
+  onStatusFilterChange: (value: WorkflowRunListStatusFilter) => void;
+}
+
+export function WorkflowRunListHeader({
+  query,
+  onQueryChange,
+  statusFilter,
+  onStatusFilterChange,
+}: WorkflowRunListHeaderProps) {
+  return (
+    <div className="flex flex-col gap-8 border-b border-border-neutral-base px-12 py-12">
+      <Input
+        value={query}
+        onChange={(event) => onQueryChange(event.target.value)}
+        placeholder="Run id or trigger..."
+        aria-label="Search runs"
+        size="small"
+        iconLeft={<Icon name="searchLine" className="size-14 text-foreground-neutral-muted" />}
+      />
+
+      <fieldset className="flex items-center gap-8">
+        <legend className="sr-only">Run status filter</legend>
+        {STATUS_FILTERS.map((filter) => (
+          <Button
+            key={filter.value}
+            type="button"
+            size="2xs"
+            variant={statusFilter === filter.value ? 'primary' : 'transparent'}
+            aria-pressed={statusFilter === filter.value}
+            onClick={() => onStatusFilterChange(filter.value)}
+          >
+            {filter.label}
+          </Button>
+        ))}
+      </fieldset>
+    </div>
+  );
+}

package/src/components/workflow-run-list/workflow-run-list-states.tsx

@@ -0,0 +1,86 @@
+import type {QueryLoadErrorQuery} from '@shipfox/client-ui';
+import {Button} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+import {Skeleton} from '@shipfox/react-ui/skeleton';
+import {Text} from '@shipfox/react-ui/typography';
+
+export function WorkflowRunListSkeleton() {
+  return (
+    <div className="flex flex-col gap-4 p-8" role="status" aria-label="Loading runs">
+      {Array.from({length: 6}).map((_, index) => (
+        <div
+          // biome-ignore lint/suspicious/noArrayIndexKey: skeleton row, stable position
+          key={index}
+          className="flex flex-col gap-3 rounded-8 border border-transparent px-10 py-7"
+        >
+          <div className="flex h-20 items-center gap-7">
+            <Skeleton className="size-6 shrink-0 rounded-full" />
+            <Skeleton className="h-12 w-1/3" />
+          </div>
+          <div className="flex h-20 items-center gap-6 pl-13">
+            <Skeleton className="h-12 flex-1" />
+            <Skeleton className="h-12 w-40" />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Slim non-blocking banner shown when a background refetch fails after a prior success,
+ * so the already-loaded rows stay on screen with the retry inline rather than being
+ * replaced by a full-placeholder error.
+ */
+export function WorkflowRunListStaleError({query}: {query: QueryLoadErrorQuery}) {
+  return (
+    <div className="border-b border-border-neutral-base p-8">
+      <Callout role="alert" type="error">
+        <div className="flex items-center justify-between gap-8">
+          <Text size="xs">Could not refresh workflow runs.</Text>
+          <Button
+            type="button"
+            size="2xs"
+            variant="secondary"
+            isLoading={query.isFetching}
+            onClick={() => {
+              void query.refetch();
+            }}
+          >
+            Retry
+          </Button>
+        </div>
+      </Callout>
+    </div>
+  );
+}
+
+export function WorkflowRunListEmpty() {
+  return (
+    <div className="p-16">
+      <EmptyState
+        icon="pulseLine"
+        title="No runs yet"
+        description="Runs from this project's workflows will appear here as soon as one is launched."
+      />
+    </div>
+  );
+}
+
+export function WorkflowRunListNoMatches({onClear}: {onClear: () => void}) {
+  return (
+    <div className="p-16">
+      <EmptyState
+        icon="filterOffLine"
+        title="No matching runs"
+        description="No runs match your current search or status filter."
+        action={
+          <Button type="button" size="sm" variant="secondary" onClick={onClear}>
+            Clear filters
+          </Button>
+        }
+      />
+    </div>
+  );
+}

package/src/components/workflow-run-list/workflow-run-list-view.test.tsx

@@ -0,0 +1,178 @@
+import {screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type {WorkflowRunListItem, WorkflowRunStatus} from '#core/workflow-run.js';
+import {workflowRunListItem} from '#test/fixtures/workflow-run.js';
+import {renderWithRouter} from '#test/render.js';
+import type {WorkflowRunListQuery} from './types.js';
+import {WorkflowRunListView} from './workflow-run-list-view.js';
+
+const WORKSPACE_ID = '11111111-1111-4111-8111-111111111111';
+const PROJECT_ID = '44444444-4444-4444-8444-444444444444';
+
+function loadedQuery(): WorkflowRunListQuery {
+  return {
+    isPending: false,
+    isError: false,
+    isFetching: false,
+    data: {pages: [], pageParams: []},
+    error: null,
+    refetch: () => undefined,
+  };
+}
+
+describe('WorkflowRunListView', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  test('narrows the list to the selected status filter', async () => {
+    const user = userEvent.setup();
+    renderListView([
+      run('running', 'deploy-web'),
+      run('failed', 'integration-tests'),
+      run('succeeded', 'build-image'),
+    ]);
+
+    await user.click(await screen.findByRole('button', {name: 'Failed'}));
+
+    expect(screen.getByText('integration-tests')).toBeInTheDocument();
+    expect(screen.queryByText('deploy-web')).not.toBeInTheDocument();
+    expect(screen.queryByText('build-image')).not.toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'Failed'})).toHaveAttribute('aria-pressed', 'true');
+  });
+
+  test('the Running filter keeps in-progress pending runs alongside running ones', async () => {
+    const user = userEvent.setup();
+    renderListView([
+      run('running', 'deploy-web'),
+      run('pending', 'queued-build'),
+      run('succeeded', 'build-image'),
+    ]);
+
+    await user.click(await screen.findByRole('button', {name: 'Running'}));
+
+    expect(screen.getByText('deploy-web')).toBeInTheDocument();
+    expect(screen.getByText('queued-build')).toBeInTheDocument();
+    expect(screen.queryByText('build-image')).not.toBeInTheDocument();
+  });
+
+  test('renders optimistic temp runs without a navigable link', async () => {
+    renderListView([run('pending', 'queued-build', 'temp-1234'), run('running', 'deploy-web')]);
+
+    // The canonical run is a link to its detail page; the optimistic temp run is shown but
+    // not yet navigable (its detail page does not exist until the canonical row replaces it).
+    const links = await screen.findAllByRole('link');
+    expect(links.some((link) => link.textContent?.includes('deploy-web'))).toBe(true);
+    expect(links.some((link) => link.textContent?.includes('queued-build'))).toBe(false);
+    expect(screen.getByText('queued-build')).toBeInTheDocument();
+  });
+
+  test('shows a finished run duration in the row metadata', async () => {
+    renderListView([
+      run('succeeded', 'build-image', 'run-build-image', {
+        started_at: '2026-05-07T01:00:00.000Z',
+        finished_at: '2026-05-07T01:02:14.000Z',
+      }),
+    ]);
+
+    const duration = await screen.findByText('2m 14s');
+    expect(duration).toBeInTheDocument();
+    expect(duration).toHaveAttribute('aria-label', 'ran 2m 14s');
+    expect(
+      screen.getByRole('link', {
+        name: (name) => name.includes('build-image') && name.includes('ran 2m 14s'),
+      }),
+    ).toBeInTheDocument();
+  });
+
+  test('shows a live running run duration in the row metadata', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(Date.parse('2026-05-07T01:02:14.000Z'));
+
+    renderListView([
+      run('running', 'deploy-web', 'run-deploy-web', {
+        started_at: '2026-05-07T01:00:00.000Z',
+        finished_at: null,
+      }),
+    ]);
+
+    const duration = await screen.findByText('2m 14s');
+    expect(duration).toBeInTheDocument();
+    expect(duration).toHaveAttribute('aria-label', 'running 2m 14s');
+    expect(
+      screen.getByRole('link', {
+        name: (name) => name.includes('deploy-web') && name.includes('running 2m 14s'),
+      }),
+    ).toBeInTheDocument();
+  });
+
+  test('scopes the trigger tooltip to the trigger label', async () => {
+    const user = userEvent.setup();
+    renderListView([run('failed', 'integration-tests')]);
+
+    await user.hover(
+      await screen.findByRole('link', {
+        name: (name) =>
+          name.includes('integration-tests') && name.includes('github') && name.includes('push'),
+      }),
+    );
+
+    expect(screen.queryByRole('tooltip')).not.toBeInTheDocument();
+
+    await user.hover(screen.getByText('push'));
+
+    expect(await screen.findByRole('tooltip')).toHaveTextContent('github_acme · push');
+  });
+
+  test('restores every row after the filters are cleared', async () => {
+    const user = userEvent.setup();
+    renderListView([
+      run('running', 'deploy-web'),
+      run('failed', 'integration-tests'),
+      run('succeeded', 'build-image'),
+    ]);
+    await user.type(await screen.findByLabelText('Search runs'), 'no-such-run');
+
+    expect(screen.getByText('No matching runs')).toBeInTheDocument();
+
+    await user.click(await screen.findByRole('button', {name: 'Clear filters'}));
+
+    expect(screen.getByText('deploy-web')).toBeInTheDocument();
+    expect(screen.getByText('integration-tests')).toBeInTheDocument();
+    expect(screen.getByText('build-image')).toBeInTheDocument();
+    expect(screen.getByLabelText('Search runs')).toHaveValue('');
+  });
+});
+
+function renderListView(runs: WorkflowRunListItem[]) {
+  // Row links need router context; the query and data stay injected by props.
+  renderWithRouter(
+    <WorkflowRunListView
+      runs={runs}
+      query={loadedQuery()}
+      workspaceId={WORKSPACE_ID}
+      projectId={PROJECT_ID}
+    />,
+  );
+}
+
+function run(
+  status: WorkflowRunStatus,
+  name: string,
+  id = `run-${name}`,
+  overrides: NonNullable<Parameters<typeof workflowRunListItem>[0]> = {},
+): WorkflowRunListItem {
+  return workflowRunListItem({
+    id,
+    project_id: PROJECT_ID,
+    definition_id: '55555555-5555-4555-8555-555555555555',
+    name,
+    status,
+    trigger_provider: 'github',
+    trigger_source: 'github_acme',
+    trigger_event: 'push',
+    created_at: '2026-05-07T01:01:00.000Z',
+    updated_at: '2026-05-07T01:02:00.000Z',
+    ...overrides,
+  });
+}

package/src/components/workflow-run-list/workflow-run-list-view.tsx

@@ -0,0 +1,57 @@
+import {TimeTickerProvider} from '@shipfox/react-ui/time-ticker';
+import {cn} from '@shipfox/react-ui/utils';
+import {useState} from 'react';
+import {runMatchesSearch, runMatchesStatusFilter} from './run-display.js';
+import type {WorkflowRunListStatusFilter, WorkflowRunListViewProps} from './types.js';
+import {WorkflowRunListContent} from './workflow-run-list-content.js';
+import {WorkflowRunListHeader} from './workflow-run-list-header.js';
+
+export function WorkflowRunListView({
+  runs,
+  query,
+  workspaceId,
+  projectId,
+  selectedWorkflowRunId,
+  className,
+}: WorkflowRunListViewProps) {
+  const [search, setSearch] = useState('');
+  const [statusFilter, setStatusFilter] = useState<WorkflowRunListStatusFilter>('all');
+
+  const filteredRuns = runs.filter((run) => {
+    if (!runMatchesStatusFilter(run.status, statusFilter)) return false;
+    return runMatchesSearch(run, search);
+  });
+
+  function handleClearFilters() {
+    setSearch('');
+    setStatusFilter('all');
+  }
+
+  return (
+    <TimeTickerProvider intervalMs={1000} reducedMotionIntervalMs={10_000}>
+      <aside
+        className={cn(
+          'flex w-304 shrink-0 flex-col border-r border-border-neutral-base bg-background-subtle-base',
+          className,
+        )}
+        aria-label="Workflow runs"
+      >
+        <WorkflowRunListHeader
+          query={search}
+          onQueryChange={setSearch}
+          statusFilter={statusFilter}
+          onStatusFilterChange={setStatusFilter}
+        />
+        <WorkflowRunListContent
+          query={query}
+          totalRuns={runs.length}
+          runs={filteredRuns}
+          workspaceId={workspaceId}
+          projectId={projectId}
+          selectedWorkflowRunId={selectedWorkflowRunId}
+          onClearFilters={handleClearFilters}
+        />
+      </aside>
+    </TimeTickerProvider>
+  );
+}

package/src/components/workflow-run-list/workflow-run-list.stories.tsx

@@ -0,0 +1,111 @@
+import {Code} from '@shipfox/react-ui/typography';
+import type {Meta, StoryObj} from '@storybook/react';
+import type {ReactNode} from 'react';
+import {expect, userEvent, within} from 'storybook/test';
+import type {WorkflowRunListItem, WorkflowRunStatus} from '#core/workflow-run.js';
+import {sequencedWorkflowRunListItem} from '#test/fixtures/workflow-run.js';
+import type {WorkflowRunListQuery} from './types.js';
+import {WorkflowRunListView} from './workflow-run-list-view.js';
+
+// Stand-in for the react-query result the view reads. `data !== undefined` is the
+// "loaded at least once" signal that splits a fresh load error from a stale refresh.
+function makeQuery(overrides: Partial<WorkflowRunListQuery> = {}): WorkflowRunListQuery {
+  return {
+    isPending: false,
+    isError: false,
+    isFetching: false,
+    data: {pages: [], pageParams: []},
+    error: null,
+    refetch: () => undefined,
+    ...overrides,
+  };
+}
+
+function makeRun(status: WorkflowRunStatus, name: string, minutesAgo: number): WorkflowRunListItem {
+  return sequencedWorkflowRunListItem(status, name, minutesAgo);
+}
+
+const SAMPLE_RUNS: WorkflowRunListItem[] = [
+  makeRun('running', 'deploy-web', 1),
+  makeRun('failed', 'integration-tests', 4),
+  makeRun('succeeded', 'build-image', 12),
+  makeRun('cancelled', 'lint-and-type', 38),
+  makeRun('pending', 'release-prod', 0),
+  makeRun('succeeded', 'release-production-multi-region-with-canary-and-smoke-tests', 95),
+];
+
+// One story on the full rail. The data states (loading / empty / errors / runs) are
+// driven by args; search, status filter, "clear filters" and "no matches" are live in
+// the rendered toolbar since the view owns that state. The decorator gives the rail a
+// real height so `flex-1` content scrolls the way it does in the app shell.
+const meta = {
+  title: 'Workflows/WorkflowRunList',
+  component: WorkflowRunListView,
+  parameters: {layout: 'centered'},
+  decorators: [
+    (Story) => (
+      <div className="flex h-600">
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    runs: SAMPLE_RUNS,
+    query: makeQuery(),
+    workspaceId: 'ws-demo',
+    projectId: 'proj-demo',
+  },
+} satisfies Meta<typeof WorkflowRunListView>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {};
+
+export const Selected: Story = {
+  args: {selectedWorkflowRunId: SAMPLE_RUNS[1].id},
+};
+
+export const DataStates: Story = {
+  render: (args) => (
+    <div className="grid grid-cols-2 gap-24">
+      <StateExample label="Loading">
+        <WorkflowRunListView {...args} query={makeQuery({isPending: true, data: undefined})} />
+      </StateExample>
+      <StateExample label="Empty">
+        <WorkflowRunListView {...args} runs={[]} />
+      </StateExample>
+      <StateExample label="Load error">
+        <WorkflowRunListView
+          {...args}
+          runs={[]}
+          query={makeQuery({isError: true, data: undefined})}
+        />
+      </StateExample>
+      <StateExample label="Stale error">
+        <WorkflowRunListView {...args} query={makeQuery({isError: true})} />
+      </StateExample>
+    </div>
+  ),
+};
+
+export const TestNoMatches: Story = {
+  play: async ({canvasElement}) => {
+    const canvas = within(canvasElement);
+    await userEvent.type(canvas.getByLabelText('Search runs'), 'no-such-run');
+    await expect(await canvas.findByText('No matching runs')).toBeInTheDocument();
+  },
+};
+
+function StateExample({label, children}: {label: string; children: ReactNode}) {
+  return (
+    <div className="flex w-304 flex-col gap-8">
+      <Code variant="label" className="text-foreground-neutral-subtle">
+        {label}
+      </Code>
+      <div className="flex h-560 rounded-8 border border-border-neutral-base bg-background-neutral-base">
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/components/workflow-run-list/workflow-run-list.tsx

@@ -0,0 +1,29 @@
+import {useMemo} from 'react';
+import type {WorkflowRunListItem} from '#core/workflow-run.js';
+import {useWorkflowRunsInfiniteQuery} from '#hooks/api/workflow-runs.js';
+import type {WorkflowRunListProps} from './types.js';
+import {WorkflowRunListView} from './workflow-run-list-view.js';
+
+export function WorkflowRunList({
+  workspaceId,
+  projectId,
+  selectedWorkflowRunId,
+  className,
+}: WorkflowRunListProps) {
+  const query = useWorkflowRunsInfiniteQuery(projectId, {});
+  const runs = useMemo<WorkflowRunListItem[]>(
+    () => query.data?.pages.flatMap((page) => page.runs) ?? [],
+    [query.data],
+  );
+
+  return (
+    <WorkflowRunListView
+      runs={runs}
+      query={query}
+      workspaceId={workspaceId}
+      projectId={projectId}
+      selectedWorkflowRunId={selectedWorkflowRunId}
+      className={className}
+    />
+  );
+}