@shipfox/client-projects 0.2.0

package/src/pages/projects-hub-page.test.tsx

@@ -0,0 +1,313 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {fireEvent, screen, waitFor} from '@testing-library/react';
+import {jsonResponse, PROJECT_TEST_WID, renderProjectPage} from '#test/pages.js';
+import {ProjectsHubPage} from './projects-hub-page.js';
+
+const NEW_PROJECT_REGEX = /New project/i;
+const WORKSPACE_PROJECTS_NEW_HREF = `/workspaces/${PROJECT_TEST_WID}/projects/new`;
+const CONNECTION_ID = '33333333-3333-4333-8333-333333333333';
+
+describe('ProjectsHubPage', () => {
+  beforeEach(() => {
+    window.sessionStorage.clear();
+  });
+
+  test('renders Projects H2 + New project button + empty state with create CTA', async () => {
+    configureApiClient({
+      fetchImpl: createHubFetch({
+        projects: jsonResponse({projects: [], next_cursor: null}),
+        modelProviders: jsonResponse(modelProviderConfigsDto()),
+      }),
+    });
+
+    renderProjectPage(`/workspaces/${PROJECT_TEST_WID}`, <ProjectsHubPage />);
+
+    expect(await screen.findByText('Create your first project')).toBeInTheDocument();
+    // The page-level "Projects" title belongs in content because the top nav owns
+    // workspace identity.
+    expect(screen.getByRole('heading', {name: 'Projects'})).toBeInTheDocument();
+    expect(screen.getByRole('link', {name: NEW_PROJECT_REGEX})).toHaveAttribute(
+      'href',
+      WORKSPACE_PROJECTS_NEW_HREF,
+    );
+    expect(
+      (screen.getAllByRole('link', {name: 'Create project'})[0] as HTMLAnchorElement).getAttribute(
+        'href',
+      ),
+    ).toBe(WORKSPACE_PROJECTS_NEW_HREF);
+  });
+
+  test('shows and dismisses the model provider reminder when no provider is configured', async () => {
+    const fetchImpl = createHubFetch({
+      projects: jsonResponse({projects: [], next_cursor: null}),
+      modelProviders: jsonResponse({configs: [], default_provider_id: null}),
+    });
+    configureApiClient({fetchImpl});
+
+    renderProjectPage(`/workspaces/${PROJECT_TEST_WID}`, <ProjectsHubPage />);
+
+    expect(await screen.findByText('Finish setting up a model provider')).toBeInTheDocument();
+    expect(screen.getByRole('link', {name: 'Agents'})).toHaveAttribute(
+      'href',
+      `/workspaces/${PROJECT_TEST_WID}/settings/agents`,
+    );
+    fireEvent.click(screen.getByRole('button', {name: 'Close'}));
+
+    await waitFor(() => {
+      expect(screen.queryByText('Finish setting up a model provider')).not.toBeInTheDocument();
+    });
+  });
+
+  test('hides the model provider reminder when a provider is configured', async () => {
+    const fetchImpl = createHubFetch({
+      projects: jsonResponse({projects: [], next_cursor: null}),
+      modelProviders: jsonResponse(modelProviderConfigsDto()),
+    });
+    configureApiClient({fetchImpl});
+
+    renderProjectPage(`/workspaces/${PROJECT_TEST_WID}`, <ProjectsHubPage />);
+
+    expect(await screen.findByText('Create your first project')).toBeInTheDocument();
+    expect(screen.queryByText('Finish setting up a model provider')).not.toBeInTheDocument();
+  });
+
+  test('renders projects and loads the next cursor page', async () => {
+    const fetchImpl = vi.fn((input: RequestInfo | URL) => {
+      const url = new URL(requestInputUrl(input));
+      if (url.pathname.endsWith('/agent/model-providers')) {
+        return Promise.resolve(jsonResponse(modelProviderConfigsDto()));
+      }
+      if (url.pathname === '/integration-connections') {
+        return Promise.resolve(jsonResponse(connectionsDto()));
+      }
+      if (url.pathname === '/projects') {
+        if (url.searchParams.get('cursor') === 'cursor-1') {
+          return Promise.resolve(
+            jsonResponse({
+              projects: [projectDto({id: 'project-2', name: 'API'})],
+              next_cursor: null,
+            }),
+          );
+        }
+        return Promise.resolve(
+          jsonResponse({
+            projects: [projectDto({id: 'project-1', name: 'Platform'})],
+            next_cursor: 'cursor-1',
+          }),
+        );
+      }
+      return Promise.resolve(jsonResponse({code: 'not-found'}, {status: 404}));
+    });
+    configureApiClient({fetchImpl});
+
+    renderProjectPage(`/workspaces/${PROJECT_TEST_WID}`, <ProjectsHubPage />);
+    expect(await screen.findByText('Platform')).toBeInTheDocument();
+    const projectLink = screen.getByText('Platform').closest('a');
+    // The whole card is the link, carrying the neutral focus ring (matching the
+    // integration gallery cards).
+    expect(projectLink).toHaveClass('focus-visible:shadow-button-neutral-focus');
+    expect(projectLink?.className).not.toContain('shadow-button-secondary');
+
+    fireEvent.click(screen.getByRole('button', {name: 'Load more'}));
+
+    expect(await screen.findByText('API')).toBeInTheDocument();
+  });
+
+  test('renders an error alert with retry', async () => {
+    configureApiClient({
+      fetchImpl: createHubFetch({
+        projects: jsonResponse({code: 'server-error'}, {status: 500}),
+      }),
+    });
+
+    renderProjectPage(`/workspaces/${PROJECT_TEST_WID}`, <ProjectsHubPage />);
+
+    expect(await screen.findByText("Couldn't load projects")).toBeInTheDocument();
+    expect(screen.getByRole('button', {name: 'Retry loading projects'})).toBeInTheDocument();
+  });
+
+  test('shows no status pill or repository id for a connected source', async () => {
+    configureApiClient({
+      fetchImpl: createHubFetch({
+        projects: jsonResponse({
+          projects: [
+            projectDto({
+              id: 'project-1',
+              name: 'Platform',
+              externalRepositoryId: 'github:octo/platform',
+            }),
+          ],
+          next_cursor: null,
+        }),
+        connections: jsonResponse(connectionsDto()),
+      }),
+    });
+
+    renderProjectPage(`/workspaces/${PROJECT_TEST_WID}`, <ProjectsHubPage />);
+
+    expect(await screen.findByText('Platform')).toBeInTheDocument();
+
+    // The provider logo resolves to a real icon, not the neutral fallback
+    // (componentLine is the only icon with a 25x24 viewBox).
+    await waitFor(() => {
+      const card = screen.getByText('Platform').closest('li');
+      expect(card?.querySelector('[data-slot="skeleton"]')).toBeNull();
+      expect(card?.querySelector('svg')).toBeInTheDocument();
+      expect(card?.querySelector('svg[viewBox="0 0 25 24"]')).toBeNull();
+    });
+
+    // "active" is the expected state, so it stays unbadged; the raw repository
+    // id is dropped because it is meaningless to end users.
+    expect(screen.queryByText('Connected')).not.toBeInTheDocument();
+    expect(screen.queryByText('Disabled')).not.toBeInTheDocument();
+    expect(screen.queryByText('Error')).not.toBeInTheDocument();
+    expect(screen.queryByText('github:octo/platform')).not.toBeInTheDocument();
+  });
+
+  test.each([
+    ['error', 'Error'],
+    ['disabled', 'Disabled'],
+  ] as const)('flags a %s source with the matching status pill', async (lifecycleStatus, label) => {
+    configureApiClient({
+      fetchImpl: createHubFetch({
+        projects: jsonResponse({
+          projects: [projectDto({id: 'project-1', name: 'Platform'})],
+          next_cursor: null,
+        }),
+        connections: jsonResponse(connectionsDto({lifecycleStatus})),
+      }),
+    });
+
+    renderProjectPage(`/workspaces/${PROJECT_TEST_WID}`, <ProjectsHubPage />);
+
+    expect(await screen.findByText('Platform')).toBeInTheDocument();
+    expect(await screen.findByText(label)).toBeInTheDocument();
+    // The aligned card carries no CTA.
+    expect(screen.queryByRole('link', {name: 'Reconnect'})).not.toBeInTheDocument();
+  });
+
+  test('keeps cards usable and unflagged when the connections request fails', async () => {
+    configureApiClient({
+      fetchImpl: createHubFetch({
+        projects: jsonResponse({
+          projects: [projectDto({id: 'project-1', name: 'Platform'})],
+          next_cursor: null,
+        }),
+        connections: jsonResponse({code: 'server-error'}, {status: 500}),
+      }),
+    });
+
+    renderProjectPage(`/workspaces/${PROJECT_TEST_WID}`, <ProjectsHubPage />);
+
+    expect(await screen.findByText('Platform')).toBeInTheDocument();
+
+    // The icon settles to the neutral fallback rather than spinning on the
+    // loading skeleton forever when the connections fetch errors.
+    await waitFor(() => {
+      const card = screen.getByText('Platform').closest('li');
+      expect(card?.querySelector('[data-slot="skeleton"]')).toBeNull();
+      expect(card?.querySelector('svg')).toBeInTheDocument();
+    });
+
+    // A failed connections fetch is not mistaken for a disconnected source.
+    expect(screen.queryByText('Disabled')).not.toBeInTheDocument();
+    expect(screen.queryByText('Error')).not.toBeInTheDocument();
+    expect(screen.queryByText('Connected')).not.toBeInTheDocument();
+  });
+});
+
+function createHubFetch({
+  projects = jsonResponse({
+    projects: [projectDto({id: 'project-1', name: 'Platform'})],
+    next_cursor: null,
+  }),
+  connections = jsonResponse(connectionsDto()),
+  modelProviders = jsonResponse(modelProviderConfigsDto()),
+}: {
+  projects?: Response;
+  connections?: Response;
+  modelProviders?: Response;
+} = {}) {
+  return vi.fn((input: RequestInfo | URL) => {
+    const url = new URL(requestInputUrl(input));
+    if (url.pathname.endsWith('/agent/model-providers')) {
+      return Promise.resolve(modelProviders.clone());
+    }
+    if (url.pathname === '/integration-connections') {
+      return Promise.resolve(connections.clone());
+    }
+    if (url.pathname === '/projects') {
+      return Promise.resolve(projects.clone());
+    }
+    return Promise.resolve(jsonResponse({code: 'not-found'}, {status: 404}));
+  });
+}
+
+function requestInputUrl(input: RequestInfo | URL) {
+  if (input instanceof Request) return input.url;
+  return String(input);
+}
+
+function projectDto({
+  id,
+  name,
+  connectionId = CONNECTION_ID,
+  externalRepositoryId = 'github:octo/platform',
+}: {
+  id: string;
+  name: string;
+  connectionId?: string;
+  externalRepositoryId?: string;
+}) {
+  return {
+    id,
+    workspace_id: PROJECT_TEST_WID,
+    name,
+    source: {
+      connection_id: connectionId,
+      external_repository_id: externalRepositoryId,
+    },
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+  };
+}
+
+function modelProviderConfigsDto() {
+  return {
+    configs: [
+      {
+        provider_id: 'anthropic',
+        default_model: null,
+        key_fingerprints: {'credential:api_key': '...abcd'},
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+      },
+    ],
+    default_provider_id: 'anthropic',
+  };
+}
+
+function connectionsDto({
+  lifecycleStatus = 'active',
+  id = CONNECTION_ID,
+}: {
+  lifecycleStatus?: 'active' | 'disabled' | 'error';
+  id?: string;
+} = {}) {
+  return {
+    connections: [
+      {
+        id,
+        workspace_id: PROJECT_TEST_WID,
+        provider: 'github',
+        external_account_id: 'octo',
+        slug: 'github_octo',
+        display_name: 'Acme GitHub',
+        lifecycle_status: lifecycleStatus,
+        capabilities: ['source_control'],
+        created_at: '2026-05-07T00:00:00.000Z',
+        updated_at: '2026-05-07T00:00:00.000Z',
+      },
+    ],
+  };
+}

package/src/pages/projects-hub-page.tsx

@@ -0,0 +1,246 @@
+import type {IntegrationConnectionDto} from '@shipfox/api-integration-core-dto';
+import type {ProjectResponseDto} from '@shipfox/api-projects-dto';
+import {useActiveWorkspace} from '@shipfox/client-auth';
+import {
+  ConnectionStatusBadge,
+  IntegrationIcon,
+  useIntegrationConnectionsQuery,
+} from '@shipfox/client-integrations';
+import {QueryLoadError} from '@shipfox/client-ui';
+import {Button} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {Card} from '@shipfox/react-ui/card';
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Input} from '@shipfox/react-ui/input';
+import {Skeleton} from '@shipfox/react-ui/skeleton';
+import {Header, Text} from '@shipfox/react-ui/typography';
+import {Link} from '@tanstack/react-router';
+import {useEffect, useState} from 'react';
+import {ModelProviderReminderBanner} from '#components/model-provider-reminder-banner.js';
+import {useProjectsInfiniteQuery} from '#hooks/api/projects.js';
+
+export function ProjectsHubPage() {
+  const workspace = useActiveWorkspace();
+  const [searchInput, setSearchInput] = useState('');
+  const trimmedInput = searchInput.trim();
+  const debouncedSearch = useDebouncedValue(trimmedInput, 250);
+  const query = useProjectsInfiniteQuery(workspace.id, debouncedSearch || undefined);
+  const projects = query.data?.pages.flatMap((page) => page.projects) ?? [];
+
+  // The provider logo and connection health live on the integration connection,
+  // not the project, so resolve them once for the whole list and index by id.
+  // Skip the fetch when there are no cards to annotate.
+  const connectionsQuery = useIntegrationConnectionsQuery(
+    projects.length > 0 ? workspace.id : undefined,
+  );
+  const connectionsById = new Map(
+    (connectionsQuery.data?.connections ?? []).map((connection) => [connection.id, connection]),
+  );
+
+  const isInitialLoading = query.isPending;
+  const isDebouncePending = trimmedInput !== debouncedSearch;
+  const isSearching =
+    Boolean(trimmedInput) && (isDebouncePending || (query.isFetching && !query.isFetchingNextPage));
+  const hasNoData = !query.data;
+
+  return (
+    <div className="flex w-full flex-col gap-24">
+      <header className="flex flex-col gap-16">
+        <div className="flex items-start justify-between gap-24 max-[640px]:flex-col">
+          <Header variant="h2">Projects</Header>
+        </div>
+        <div className="flex items-center gap-12 max-[640px]:flex-col max-[640px]:items-stretch">
+          <Input
+            type="search"
+            value={searchInput}
+            onChange={(event) => setSearchInput(event.target.value)}
+            placeholder="Search projects…"
+            aria-label="Search projects"
+            className="flex-1"
+            iconLeft={<Icon name="searchLine" className="size-16" />}
+            iconRight={
+              isSearching ? (
+                <Icon
+                  name="spinner"
+                  size={16}
+                  className="text-foreground-neutral-muted"
+                  aria-hidden="true"
+                />
+              ) : undefined
+            }
+          />
+          <Button asChild iconLeft="addLine" className="shrink-0 max-[640px]:w-full">
+            <Link to="/workspaces/$wid/projects/new" params={{wid: workspace.id}}>
+              New project
+            </Link>
+          </Button>
+        </div>
+      </header>
+
+      <ModelProviderReminderBanner workspaceId={workspace.id} />
+
+      {isInitialLoading || (debouncedSearch && hasNoData && query.isFetching) ? (
+        <ProjectsSkeleton />
+      ) : null}
+
+      {query.isError && hasNoData ? <QueryLoadError query={query} subject="projects" /> : null}
+
+      {!isInitialLoading && !query.isError && projects.length === 0 && !debouncedSearch ? (
+        <EmptyProjects workspaceId={workspace.id} />
+      ) : null}
+
+      {!query.isFetching && !query.isError && projects.length === 0 && debouncedSearch ? (
+        <NoSearchResults search={debouncedSearch} onClear={() => setSearchInput('')} />
+      ) : null}
+
+      {projects.length > 0 ? (
+        <section aria-label="Projects list">
+          <ul className="grid grid-cols-2 gap-12 max-[760px]:grid-cols-1">
+            {projects.map((project) => (
+              <ProjectCard
+                project={project}
+                connection={connectionsById.get(project.source.connection_id)}
+                connectionsResolved={connectionsQuery.isSuccess}
+                connectionsSettled={connectionsQuery.isSuccess || connectionsQuery.isError}
+                key={project.id}
+                workspaceId={workspace.id}
+              />
+            ))}
+          </ul>
+          {query.error && query.data ? (
+            <Callout role="alert" type="error" className="mt-16">
+              <Text size="sm">
+                Could not load the next page. Existing projects are still shown.
+              </Text>
+            </Callout>
+          ) : null}
+          {query.hasNextPage ? (
+            <div className="mt-16 flex justify-center">
+              <Button
+                variant="secondary"
+                isLoading={query.isFetchingNextPage}
+                onClick={() => query.fetchNextPage()}
+              >
+                Load more
+              </Button>
+            </div>
+          ) : null}
+        </section>
+      ) : null}
+    </div>
+  );
+}
+
+function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const handle = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(handle);
+  }, [value, delayMs]);
+  return debounced;
+}
+
+function ProjectsSkeleton() {
+  return (
+    <ul
+      role="status"
+      aria-label="Loading projects"
+      className="grid grid-cols-2 gap-12 max-[760px]:grid-cols-1"
+    >
+      {[0, 1, 2, 3, 4, 5].map((row) => (
+        <li key={row}>
+          <Card className="h-full p-16">
+            <div className="flex items-center gap-12">
+              <Skeleton className="size-24 shrink-0" />
+              <Skeleton className="h-16 w-1/2" />
+            </div>
+          </Card>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function EmptyProjects({workspaceId}: {workspaceId: string}) {
+  return (
+    <EmptyState
+      icon="folderLine"
+      title="Create your first project"
+      description="Connect a repository-backed project to start building workflows."
+      action={
+        <Button asChild iconRight="chevronRight">
+          <Link to="/workspaces/$wid/projects/new" params={{wid: workspaceId}}>
+            Create project
+          </Link>
+        </Button>
+      }
+    />
+  );
+}
+
+function NoSearchResults({search, onClear}: {search: string; onClear: () => void}) {
+  return (
+    <EmptyState
+      icon="searchLine"
+      title={`No projects match “${search}”`}
+      description="Try a different search, or clear it to see all projects."
+      action={
+        <Button size="sm" variant="secondary" onClick={onClear}>
+          Clear search
+        </Button>
+      }
+    />
+  );
+}
+
+function ProjectCard({
+  project,
+  connection,
+  connectionsResolved,
+  connectionsSettled,
+  workspaceId,
+}: {
+  project: ProjectResponseDto;
+  connection: IntegrationConnectionDto | undefined;
+  connectionsResolved: boolean;
+  connectionsSettled: boolean;
+  workspaceId: string;
+}) {
+  // On a resolved fetch, `active` carries no badge while a missing connection
+  // reads as an error so a broken source is still flagged. An unresolved or
+  // failed fetch shows nothing, so a fetch failure never flags every card.
+  const status = connectionsResolved ? (connection?.lifecycle_status ?? 'error') : undefined;
+
+  return (
+    <li>
+      <Link
+        to="/workspaces/$wid/projects/$pid"
+        params={{wid: workspaceId, pid: project.id}}
+        className="block h-full rounded-8 focus-visible:shadow-button-neutral-focus focus-visible:outline-none"
+      >
+        <Card className="h-full p-16 transition-colors hover:bg-background-components-hover">
+          <div className="flex min-w-0 items-center gap-12">
+            {/* Settle on success or error: a failed fetch falls back to the
+                neutral provider icon rather than spinning forever. */}
+            {connectionsSettled ? (
+              <IntegrationIcon
+                source={connection?.provider}
+                aria-hidden
+                className="size-24 shrink-0 text-foreground-neutral-base"
+              />
+            ) : (
+              <Skeleton className="size-24 shrink-0" />
+            )}
+            <div className="flex min-w-0 flex-1 items-center gap-8">
+              <Text size="md" bold className="truncate">
+                {project.name}
+              </Text>
+              {status ? <ConnectionStatusBadge status={status} className="shrink-0" /> : null}
+            </div>
+          </div>
+        </Card>
+      </Link>
+    </li>
+  );
+}

package/src/project-error.test.ts

@@ -0,0 +1,59 @@
+import {ApiError} from '@shipfox/client-api';
+import {projectErrorCopy} from './project-error.js';
+
+function apiError(code: string, details?: unknown) {
+  return new ApiError({
+    code,
+    status: 400,
+    message: code,
+    details: details === undefined ? {code} : {code, details},
+  });
+}
+
+describe('projectErrorCopy', () => {
+  test.each([
+    ['repository-not-found', 'Repository not found'],
+    ['access-denied', 'Repository access denied'],
+    ['timeout', 'Provider timed out'],
+    ['provider-unavailable', 'Provider unavailable'],
+    ['malformed-provider-response', 'Provider response changed'],
+    ['source-connection-not-found', 'Source connection not found'],
+    ['source-connection-inactive', 'Source connection inactive'],
+  ])('maps %s', (code, title) => {
+    const result = projectErrorCopy(apiError(code));
+
+    expect(result.title).toBe(title);
+    expect(result.message).not.toBe('');
+  });
+
+  test('includes retry-after copy for rate limits', () => {
+    const result = projectErrorCopy(apiError('rate-limited', {retry_after_seconds: 60}));
+
+    expect(result.title).toBe('Provider rate limited');
+    expect(result.message).toContain('60 seconds');
+  });
+
+  test('surfaces duplicate project recovery id', () => {
+    const result = projectErrorCopy(
+      apiError('project-already-exists', {existing_project_id: 'project-1'}),
+    );
+
+    expect(result.title).toBe('Project already exists');
+    expect(result.existingProjectId).toBe('project-1');
+  });
+
+  test('ignores malformed details payloads', () => {
+    const result = projectErrorCopy(apiError('project-already-exists', 'bad-details'));
+
+    expect(result.title).toBe('Project already exists');
+    expect(result.existingProjectId).toBeUndefined();
+  });
+
+  test('maps network and unknown errors', () => {
+    const network = projectErrorCopy(apiError('network-error'));
+    const unknown = projectErrorCopy(new Error('boom'));
+
+    expect(network.title).toBe('Network problem');
+    expect(unknown.title).toBe('Something went wrong');
+  });
+});