@shipfox/client-workflows 14.0.1 → 16.0.0

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

@@ -0,0 +1,258 @@
+import {QueryLoadError, 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';
+import {useState} from 'react';
+import type {RunAnnotationEntry} from '#core/run-annotation.js';
+import {RunAnnotationItem} from './run-annotation-item.js';
+import {RunAnnotationsEmpty} from './run-annotations-empty.js';
+
+export interface RunAnnotationListQuery extends QueryLoadErrorQuery {
+  isPending: boolean;
+  hasNextPage: boolean;
+  isFetchingNextPage: boolean;
+  fetchNextPage: () => unknown;
+}
+
+export interface RunAnnotationListProps {
+  query: RunAnnotationListQuery;
+  entries: RunAnnotationEntry[] | undefined;
+  workflowRunId: string;
+  workspaceSlug?: string | undefined;
+  projectSlug?: string | undefined;
+  runAttempt?: number | undefined;
+  /** Name of the job the list is filtered to, used only for empty-state copy. */
+  filteredJobName?: string | undefined;
+  /** Active severity filter, named in the empty state so the reader knows what to clear. */
+  filteredSeverity?: string | undefined;
+  filtered: boolean;
+  onClearFilters?: (() => void) | undefined;
+  /** Annotation id from `?annotation=`, which the matching card scrolls to and focuses. */
+  selectedAnnotationId?: string | undefined;
+}
+
+/**
+ * How many annotations render at once.
+ *
+ * A page holds up to 500 rows and each one mounts a Markdown pipeline, so the fetch budget is
+ * not a render budget. The window grows on demand and the server page only loads once the
+ * reader has actually seen everything already fetched.
+ */
+const RENDER_WINDOW = 25;
+
+/**
+ * The annotations list.
+ *
+ * Loading, empty, error, and stale are four distinct renderings on purpose: coalescing a failed
+ * fetch into an empty result tells a reader their run is clean when the truth is unknown.
+ */
+export function RunAnnotationList({
+  query,
+  entries,
+  workflowRunId,
+  workspaceSlug,
+  projectSlug,
+  runAttempt,
+  filteredJobName,
+  filteredSeverity,
+  filtered,
+  onClearFilters,
+  selectedAnnotationId,
+}: RunAnnotationListProps) {
+  const [visibleCount, setVisibleCount] = useState(RENDER_WINDOW);
+
+  // A deep-linked annotation past the window would otherwise be unreachable: it is in the data,
+  // absent from the DOM, and nothing on screen says so.
+  const selectedIndex = selectedAnnotationId
+    ? (entries?.findIndex((entry) => entry.annotation.id === selectedAnnotationId) ?? -1)
+    : -1;
+  const renderCount = Math.max(visibleCount, selectedIndex + 1);
+
+  if (query.isPending) return <RunAnnotationListSkeleton />;
+
+  if (query.isError && entries === undefined) {
+    return <QueryLoadError query={query} subject="annotations" icon="fileDamageLine" />;
+  }
+
+  if (entries === undefined) return <RunAnnotationListSkeleton />;
+
+  const visible = entries.slice(0, renderCount);
+  const hiddenCount = entries.length - visible.length;
+
+  return (
+    <div className="flex min-w-0 flex-col gap-12">
+      {query.isError ? <RunAnnotationStaleError query={query} /> : null}
+
+      {entries.length === 0 ? (
+        filtered ? (
+          <RunAnnotationsFilteredEmpty
+            jobName={filteredJobName}
+            severity={filteredSeverity}
+            incomplete={query.hasNextPage}
+            onClearFilters={onClearFilters}
+          />
+        ) : (
+          <RunAnnotationsEmpty />
+        )
+      ) : (
+        <ol className="flex min-w-0 flex-col gap-12">
+          {visible.map((entry) => (
+            <RunAnnotationItem
+              key={entry.annotation.id}
+              entry={entry}
+              workspaceSlug={workspaceSlug}
+              projectSlug={projectSlug}
+              workflowRunId={workflowRunId}
+              runAttempt={runAttempt}
+              selected={entry.annotation.id === selectedAnnotationId}
+            />
+          ))}
+        </ol>
+      )}
+
+      {hiddenCount > 0 ? (
+        <Button
+          type="button"
+          size="sm"
+          variant="secondary"
+          className="self-start [@media(pointer:coarse)]:min-h-44"
+          onClick={() => setVisibleCount((current) => current + RENDER_WINDOW)}
+        >
+          Show {Math.min(hiddenCount, RENDER_WINDOW)} more of {entries.length}
+        </Button>
+      ) : query.hasNextPage ? (
+        <Button
+          type="button"
+          size="sm"
+          variant="secondary"
+          className="self-start [@media(pointer:coarse)]:min-h-44"
+          isLoading={query.isFetchingNextPage}
+          onClick={() => {
+            void query.fetchNextPage();
+          }}
+        >
+          Load more annotations
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * Names the filters that are actually active.
+ *
+ * Blaming severity for a job-only filter sends the reader to change the wrong control, which
+ * is worse than saying nothing.
+ */
+function filteredEmptyDescription({
+  jobName,
+  severity,
+  incomplete,
+}: {
+  jobName: string | undefined;
+  severity: string | undefined;
+  incomplete: boolean;
+}): string {
+  if (incomplete) {
+    if (jobName && severity) {
+      return `None of the loaded annotations are from ${jobName} at ${severity} severity. Load more annotations to continue searching.`;
+    }
+    if (jobName) {
+      return `None of the loaded annotations are from ${jobName}. Load more annotations to continue searching.`;
+    }
+    if (severity) {
+      return `None of the loaded annotations are at ${severity} severity. Load more annotations to continue searching.`;
+    }
+    return 'None of the loaded annotations match the current filters. Load more annotations to continue searching.';
+  }
+  if (jobName && severity) {
+    return `This run has annotations, but none from ${jobName} at ${severity} severity.`;
+  }
+  if (jobName) return `This run has annotations, but none from ${jobName}.`;
+  if (severity) return `This run has annotations, but none at ${severity} severity.`;
+  return 'This run has annotations, but none match the current filters.';
+}
+
+function RunAnnotationsFilteredEmpty({
+  jobName,
+  severity,
+  incomplete,
+  onClearFilters,
+}: {
+  jobName: string | undefined;
+  severity: string | undefined;
+  incomplete: boolean;
+  onClearFilters: (() => void) | undefined;
+}) {
+  return (
+    <div className="flex flex-col items-center gap-12">
+      <EmptyState
+        icon="fileDamageLine"
+        title={incomplete ? 'No matches in loaded annotations' : 'No matching annotations'}
+        description={filteredEmptyDescription({jobName, severity, incomplete})}
+      />
+      {onClearFilters ? (
+        <Button
+          type="button"
+          size="sm"
+          variant="secondary"
+          className="[@media(pointer:coarse)]:min-h-44"
+          onClick={onClearFilters}
+        >
+          Clear filters
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * A failed poll keeps the annotations already on screen and marks them stale rather than
+ * clearing. Polite rather than assertive: the poll runs every 4s and a flapping API would
+ * otherwise interrupt a screen reader on every cycle.
+ */
+function RunAnnotationStaleError({query}: {query: QueryLoadErrorQuery}) {
+  return (
+    <Callout role="status" aria-live="polite" type="error">
+      <div className="flex w-full items-center justify-between gap-8">
+        <Text size="xs">Could not refresh annotations.</Text>
+        <Button
+          type="button"
+          size="2xs"
+          variant="secondary"
+          className="[@media(pointer:coarse)]:min-h-44"
+          isLoading={query.isFetching}
+          onClick={() => {
+            void query.refetch();
+          }}
+        >
+          Retry
+        </Button>
+      </div>
+    </Callout>
+  );
+}
+
+const ANNOTATION_SKELETON_ROWS = ['first', 'second', 'third'];
+
+function RunAnnotationListSkeleton() {
+  return (
+    <section aria-label="Loading annotations" className="flex flex-col gap-12">
+      {ANNOTATION_SKELETON_ROWS.map((row) => (
+        <div
+          key={row}
+          className="flex gap-12 rounded-8 border border-border-neutral-base bg-background-components-base px-12 py-8"
+        >
+          <Skeleton className="h-40 w-4 rounded-full" />
+          <div className="flex min-w-0 flex-1 flex-col gap-6">
+            <Skeleton className="h-20 w-160 rounded-4" />
+            <Skeleton className="h-16 w-240 rounded-4" />
+            <Skeleton className="h-40 w-full rounded-4" />
+          </div>
+        </div>
+      ))}
+    </section>
+  );
+}

package/src/components/workflow-run-tabs/run-annotation-summary-line.test.tsx

@@ -7,7 +7,7 @@ import {
   RouterProvider,
 } from '@tanstack/react-router';
 import {act, render, screen} from '@testing-library/react';
-import type {RunAnnotationSummary} from '#core/workflow-run-tabs.js';
+import type {RunAnnotationSummary} from '#core/run-annotation.js';
 import type {WorkflowRunsSearch} from '#routes/inputs.js';
 import {RunAnnotationSummaryLine} from './run-annotation-summary-line.js';
 
@@ -17,8 +17,12 @@ const ANNOTATION_SUMMARY: RunAnnotationSummary = {
   warning: 1,
   info: 2,
   success: 0,
+  truncated: false,
 };
 
+const INFO_OR_SUCCESS_PATTERN = /info|success/;
+const SHOW_ALL_PATTERN = /Show all/;
+
 describe('RunAnnotationSummaryLine', () => {
   test('links the severity breakdown into the Annotations panel', async () => {
     await renderSummaryLine();
@@ -30,6 +34,66 @@ describe('RunAnnotationSummaryLine', () => {
     );
   });
 
+  test('renders every count at one type scale', async () => {
+    // The severity counts previously bypassed `Text` and inherited the ambient 14px, so they
+    // rendered a step larger and heavier than the total they sit beside.
+    await renderSummaryLine();
+
+    const total = screen.getByText('5 annotations');
+    const errors = screen.getByText('2 errors');
+
+    expect(total).toHaveClass('text-xs', 'font-display');
+    expect(errors).toHaveClass('text-xs', 'font-display');
+    expect(errors).not.toHaveClass('text-foreground-highlight-interactive');
+  });
+
+  test('distinguishes severities by glyph rather than by label colour', async () => {
+    const {container} = await renderSummaryLine();
+
+    const tones = [...container.querySelectorAll('svg')].map((glyph) =>
+      glyph.getAttribute('class'),
+    );
+
+    expect(tones.some((tone) => tone?.includes('text-tag-error-icon'))).toBe(true);
+    expect(tones.some((tone) => tone?.includes('text-tag-warning-icon'))).toBe(true);
+  });
+
+  test('names only the severities that need attention', async () => {
+    await renderSummaryLine();
+
+    expect(screen.getByRole('link', {name: '2 errors'})).toBeInTheDocument();
+    expect(screen.getByRole('link', {name: '1 warning'})).toBeInTheDocument();
+    // The 2 info annotations are inside the total; naming them again would give a clean
+    // result the same weight and the same accent as a failure.
+    expect(screen.queryByRole('link', {name: '2 infos'})).not.toBeInTheDocument();
+    expect(screen.queryByText(INFO_OR_SUCCESS_PATTERN)).not.toBeInTheDocument();
+  });
+
+  test('turns the total into the way out of an active severity filter', async () => {
+    await renderSummaryLine({severity: 'error'});
+
+    expect(screen.getByRole('link', {name: 'Show all 5 annotations'})).toHaveAttribute(
+      'href',
+      '/w/acme/p/project/runs/run-1?tab=annotations',
+    );
+  });
+
+  test('leaves the total as plain text when no severity filter is active', async () => {
+    await renderSummaryLine();
+
+    expect(screen.queryByRole('link', {name: SHOW_ALL_PATTERN})).not.toBeInTheDocument();
+  });
+
+  test('falls back to the bare total when nothing needs attention', async () => {
+    await renderSummaryLine(
+      {},
+      {total: 3, error: 0, warning: 0, info: 3, success: 0, truncated: false},
+    );
+
+    expect(screen.getByText('3 annotations')).toBeInTheDocument();
+    expect(screen.queryByRole('link')).not.toBeInTheDocument();
+  });
+
   test('clears a stale annotation when linking to a severity', async () => {
     await renderSummaryLine({annotation: 'annotation-old'});
 
@@ -38,16 +102,26 @@ describe('RunAnnotationSummaryLine', () => {
       '/w/acme/p/project/runs/run-1?tab=annotations&severity=error',
     );
   });
+
+  test('marks a truncated read as a lower bound', async () => {
+    await renderSummaryLine({}, {...ANNOTATION_SUMMARY, truncated: true});
+
+    expect(screen.getByText('5+ annotations')).toBeInTheDocument();
+    expect(screen.getByRole('link', {name: '2+ errors'})).toBeInTheDocument();
+  });
 });
 
-async function renderSummaryLine(search: WorkflowRunsSearch = {}) {
+async function renderSummaryLine(
+  search: WorkflowRunsSearch = {},
+  summary: RunAnnotationSummary = ANNOTATION_SUMMARY,
+) {
   const rootRoute = createRootRoute({component: Outlet});
   const runRoute = createRoute({
     getParentRoute: () => rootRoute,
     path: '/w/$workspaceSlug/p/$projectSlug/runs/$workflowRunId',
     component: () => (
       <RunAnnotationSummaryLine
-        summary={ANNOTATION_SUMMARY}
+        summary={summary}
         workspaceSlug="acme"
         projectSlug="project"
         workflowRunId="run-1"

package/src/components/workflow-run-tabs/run-annotation-summary-line.tsx

@@ -1,13 +1,28 @@
+import {Icon} from '@shipfox/react-ui/icon';
 import {Text} from '@shipfox/react-ui/typography';
+import {cn} from '@shipfox/react-ui/utils';
 import {Link} from '@tanstack/react-router';
-import type {RunAnnotationSummary} from '#core/workflow-run-tabs.js';
+import type {RunAnnotationSummary} from '#core/run-annotation.js';
 import {
-  WORKFLOW_RUN_ANNOTATION_SEVERITIES,
   type WorkflowRunAnnotationSeverity,
   type WorkflowRunsSearch,
   workflowRunSearchParams,
 } from '#routes/inputs.js';
 import {MetadataSeparator} from '../workflow-run-summary/workflow-run-summary.js';
+import {SEVERITY_ICON, SEVERITY_ICON_TONE} from './severity-visuals.js';
+
+/**
+ * The severities this line names.
+ *
+ * The line exists so a failing run cannot look clean while the explanation sits behind an
+ * inactive section, which makes its subject "what needs attention", not "what happened".
+ * `info` and `success` are already inside the total, and repeating them gives "nothing is
+ * wrong" the same weight and the same accent as "something failed".
+ */
+const ATTENTION_SEVERITIES = [
+  'error',
+  'warning',
+] as const satisfies readonly WorkflowRunAnnotationSeverity[];
 
 export interface RunAnnotationSummaryLineProps {
   summary?: RunAnnotationSummary | undefined;
@@ -24,22 +39,49 @@ export function RunAnnotationSummaryLine({
   workflowRunId,
   search = {},
 }: RunAnnotationSummaryLineProps) {
-  if (!summary) return null;
+  // A run with no annotations says so in its empty state; a "0 annotations" line beside it is
+  // the same fact twice.
+  if (!summary || summary.total === 0) return null;
 
-  const visibleSeverities = WORKFLOW_RUN_ANNOTATION_SEVERITIES.filter(
-    (severity) => summary[severity] > 0,
-  );
+  const visibleSeverities = ATTENTION_SEVERITIES.filter((severity) => summary[severity] > 0);
+
+  const totalLabel = countLabel(summary.total, 'annotation', summary.truncated);
 
   return (
     <div className="flex flex-wrap items-center gap-x-8 gap-y-4 text-foreground-neutral-subtle">
-      <Text as="span" size="xs" className="shrink-0 text-foreground-neutral-subtle">
-        {summary.total} {pluralize('annotation', summary.total)}
-      </Text>
+      {search.severity && workspaceSlug && projectSlug && workflowRunId ? (
+        // The severity filter has no control of its own, so while one is active the total is
+        // the way back out. Unfiltered it stays plain text: a link to where you already are
+        // is noise.
+        <Link
+          to="/w/$workspaceSlug/p/$projectSlug/runs/$workflowRunId"
+          params={{workspaceSlug, projectSlug, workflowRunId}}
+          search={
+            workflowRunSearchParams(
+              {...withoutSeverity(search), tab: 'annotations'},
+              search,
+            ) as never
+          }
+          aria-label={`Show all ${totalLabel}`}
+          className="shrink-0 rounded-4 outline-none focus-visible:shadow-border-interactive-with-active"
+        >
+          {/* Underlined rather than accented: the escape hatch has to read as a link without
+              becoming the loudest thing on a line whose job is to be scannable. */}
+          <Text as="span" size="xs" className="text-foreground-neutral-subtle underline">
+            {totalLabel}
+          </Text>
+        </Link>
+      ) : (
+        <Text as="span" size="xs" className="shrink-0 text-foreground-neutral-subtle">
+          {totalLabel}
+        </Text>
+      )}
       {visibleSeverities.map((severity) => (
         <span key={severity} className="inline-flex shrink-0 items-center gap-8">
           <MetadataSeparator />
           <SeverityLink
             count={summary[severity]}
+            truncated={summary.truncated}
             severity={severity}
             workspaceSlug={workspaceSlug}
             projectSlug={projectSlug}
@@ -54,6 +96,7 @@ export function RunAnnotationSummaryLine({
 
 function SeverityLink({
   count,
+  truncated,
   severity,
   workspaceSlug,
   projectSlug,
@@ -61,19 +104,33 @@ function SeverityLink({
   search,
 }: {
   count: number;
+  truncated: boolean;
   severity: WorkflowRunAnnotationSeverity;
   workspaceSlug?: string | undefined;
   projectSlug?: string | undefined;
   workflowRunId?: string | undefined;
   search: WorkflowRunsSearch;
 }) {
-  const label = `${count} ${pluralize(severity, count)}`;
+  const label = countLabel(count, severity, truncated);
+  const content = (
+    <>
+      <Icon
+        name={SEVERITY_ICON[severity]}
+        size={12}
+        aria-hidden="true"
+        className={cn('shrink-0', SEVERITY_ICON_TONE[severity])}
+      />
+      <Text as="span" size="xs" className="text-foreground-neutral-subtle">
+        {label}
+      </Text>
+    </>
+  );
+
   if (!workspaceSlug || !projectSlug || !workflowRunId) {
-    return <span className="text-foreground-highlight-interactive">{label}</span>;
+    return <span className="inline-flex items-center gap-4">{content}</span>;
   }
 
-  const searchWithoutAnnotation = {...search};
-  delete searchWithoutAnnotation.annotation;
+  const searchWithoutAnnotation = withoutAnnotation(search);
 
   return (
     <Link
@@ -85,13 +142,31 @@ function SeverityLink({
           search,
         ) as never
       }
-      className="text-foreground-highlight-interactive outline-none hover:underline focus-visible:shadow-border-interactive-with-active"
+      className="inline-flex items-center gap-4 rounded-4 outline-none hover:underline focus-visible:shadow-border-interactive-with-active"
     >
-      {label}
+      {content}
     </Link>
   );
 }
 
-function pluralize(word: string, count: number): string {
-  return count === 1 ? word : `${word}s`;
+/** A selected annotation is stale the moment the list it was chosen from is refiltered. */
+function withoutAnnotation(search: WorkflowRunsSearch): WorkflowRunsSearch {
+  const next = {...search};
+  delete next.annotation;
+  return next;
+}
+
+function withoutSeverity(search: WorkflowRunsSearch): WorkflowRunsSearch {
+  const next = withoutAnnotation(search);
+  delete next.severity;
+  return next;
+}
+
+/**
+ * A truncated read renders `500+ annotations`: the counts are a lower bound once the page budget
+ * is hit, and presenting them as exact would understate a run the reader is trying to trust.
+ */
+function countLabel(count: number, word: string, truncated: boolean): string {
+  const plural = count === 1 && !truncated ? word : `${word}s`;
+  return `${count}${truncated ? '+' : ''} ${plural}`;
 }

package/src/components/workflow-run-tabs/run-annotations-empty.tsx

@@ -1,11 +1,15 @@
 import {EmptyState} from '@shipfox/react-ui/empty-state';
 
-export function RunAnnotationsEmpty() {
+export function RunAnnotationsEmpty({jobName}: {jobName?: string | undefined} = {}) {
   return (
     <EmptyState
       icon="fileDamageLine"
       title="No annotations"
-      description="This run has no annotations to show."
+      description={
+        jobName
+          ? `${jobName} has no annotations to show in this run.`
+          : 'This run has no annotations to show.'
+      }
     />
   );
 }