@shipfox/client-workflows 12.0.1 → 13.0.0

package/src/routes/inputs.test.ts

@@ -1,22 +1,203 @@
-import {validateWorkflowRunsSearch, workflowRouteParams} from './inputs.js';
+import {parseAppSearch, stringifyAppSearch} from '@shipfox/client-shell/runtime';
+import {
+  applyWorkflowRunFilterPatch,
+  clearWorkflowRunFilters,
+  hasWorkflowRunFilters,
+  validateWorkflowRunsSearch,
+  type WorkflowRunsSearch,
+  workflowRouteParams,
+  workflowRunSearchParams,
+} from './inputs.js';
 
-describe('workflow route inputs', () => {
-  it('normalizes malformed search values to safe defaults', () => {
-    expect(validateWorkflowRunsSearch({search: ['unexpected'], status: 'unknown'})).toEqual({});
-    expect(validateWorkflowRunsSearch({status: 'failed', runAttempt: '2'})).toEqual({
-      status: 'failed',
+/** Everything a filter change writes, then reads back, exactly as the router would. */
+function roundTrip(search: WorkflowRunsSearch): WorkflowRunsSearch {
+  const query = stringifyAppSearch(workflowRunSearchParams(search, {}));
+  return validateWorkflowRunsSearch(parseAppSearch(query));
+}
+
+describe('validateWorkflowRunsSearch', () => {
+  test('drops malformed values instead of rejecting the URL', () => {
+    expect(
+      validateWorkflowRunsSearch({
+        search: ['unexpected'],
+        status: 'unknown',
+        after: 'yesterday',
+        before: '2026-13-01',
+      }),
+    ).toEqual({});
+  });
+
+  test('ignores parameters it does not recognize', () => {
+    expect(validateWorkflowRunsSearch({search: 'deploy', page: '3', sort: 'name'})).toEqual({
+      search: 'deploy',
+    });
+  });
+
+  test('reads a single repeated key as a one-element list', () => {
+    expect(validateWorkflowRunsSearch({status: 'failed'})).toEqual({status: ['failed']});
+  });
+
+  test('keeps only the statuses it knows out of a mixed list', () => {
+    expect(validateWorkflowRunsSearch({status: ['failed', 'nonsense', 'running']})).toEqual({
+      status: ['failed', 'running'],
+    });
+  });
+
+  test('coerces a numeric-looking branch back to a string', () => {
+    expect(validateWorkflowRunsSearch({branch: 2024})).toEqual({branch: ['2024']});
+  });
+
+  test('deduplicates a repeated value', () => {
+    expect(validateWorkflowRunsSearch({branch: ['main', 'main', 'next']})).toEqual({
+      branch: ['main', 'next'],
+    });
+  });
+
+  test('rejects a well-shaped but impossible date', () => {
+    expect(validateWorkflowRunsSearch({after: '2026-02-31'})).toEqual({});
+    expect(validateWorkflowRunsSearch({after: '2026-02-28'})).toEqual({after: '2026-02-28'});
+  });
+
+  test('keeps the run selection parameters the detail route owns', () => {
+    expect(validateWorkflowRunsSearch({status: 'failed', runAttempt: '2', job: 'job-1'})).toEqual({
+      status: ['failed'],
+      runAttempt: 2,
+      jobId: 'job-1',
+    });
+  });
+});
+
+describe('the run list URL contract', () => {
+  test.each([
+    ['search', {search: 'deploy-web'}],
+    ['status', {status: ['failed' as const, 'running' as const]}],
+    ['branch', {branch: ['main', 'release/v2']}],
+    ['actor', {actor: ['octocat', 'hubot']}],
+    ['event', {event: ['push', 'pull_request']}],
+    ['after and before', {after: '2026-05-01', before: '2026-05-31'}],
+  ])('round-trips %s through the URL', (_param, search) => {
+    expect(roundTrip(search)).toEqual(search);
+  });
+
+  test('round-trips every parameter at once', () => {
+    const search: WorkflowRunsSearch = {
+      search: 'deploy',
+      status: ['failed', 'cancelled'],
+      branch: ['main'],
+      actor: ['octocat'],
+      event: ['push'],
+      after: '2026-05-01',
+      before: '2026-05-31',
+    };
+
+    expect(roundTrip(search)).toEqual(search);
+  });
+
+  test('repeats the key rather than comma-joining a multi-select', () => {
+    const query = stringifyAppSearch(workflowRunSearchParams({status: ['failed', 'running']}, {}));
+
+    expect(query).toBe('?status=failed&status=running');
+  });
+
+  test('survives a branch name containing a comma', () => {
+    expect(roundTrip({branch: ['release,v2', 'main']})).toEqual({branch: ['release,v2', 'main']});
+  });
+
+  // A branch named for a year, a release train called `false`: names that happen to be valid
+  // JSON have to come back as themselves, or the filter matches nothing and the shared link
+  // is broken for good.
+  test.each([
+    ['a numeric branch beside a plain one', {branch: ['2024', 'main']}],
+    ['two numeric branches', {branch: ['2024', '2025']}],
+    ['a boolean-looking branch', {branch: ['false', 'main']}],
+    ['numeric actors', {actor: ['123', '456']}],
+  ])('survives %s', (_case, search) => {
+    expect(roundTrip(search)).toEqual(search);
+  });
+
+  test('writes nothing for an unfiltered list', () => {
+    expect(stringifyAppSearch(workflowRunSearchParams({}, {}))).toBe('');
+  });
+
+  test('has no page or cursor parameter to carry', () => {
+    const query = stringifyAppSearch(workflowRunSearchParams({search: 'deploy'}, {}));
+
+    expect(query).not.toContain('page');
+    expect(query).not.toContain('cursor');
+  });
+});
+
+describe('applyWorkflowRunFilterPatch', () => {
+  test('replaces only the dimensions the patch names', () => {
+    const next = applyWorkflowRunFilterPatch(
+      {search: 'deploy', status: ['failed']},
+      {
+        branch: ['main'],
+      },
+    );
+
+    expect(next).toEqual({search: 'deploy', status: ['failed'], branch: ['main']});
+  });
+
+  test('deletes a dimension set to undefined, an empty string, or an empty list', () => {
+    const search: WorkflowRunsSearch = {search: 'deploy', status: ['failed'], after: '2026-05-01'};
+
+    expect(applyWorkflowRunFilterPatch(search, {search: '', status: [], after: undefined})).toEqual(
+      {},
+    );
+  });
+
+  test('leaves the run selection parameters alone', () => {
+    const next = applyWorkflowRunFilterPatch({runAttempt: 2, jobId: 'job-1'}, {search: 'deploy'});
+
+    expect(next).toEqual({runAttempt: 2, jobId: 'job-1', search: 'deploy'});
+  });
+});
+
+describe('clearWorkflowRunFilters', () => {
+  test('drops every filter and keeps the selection parameters', () => {
+    const cleared = clearWorkflowRunFilters({
+      search: 'deploy',
+      status: ['failed'],
+      branch: ['main'],
+      actor: ['octocat'],
+      event: ['push'],
+      after: '2026-05-01',
+      before: '2026-05-31',
       runAttempt: 2,
     });
+
+    expect(cleared).toEqual({runAttempt: 2});
+  });
+});
+
+describe('hasWorkflowRunFilters', () => {
+  test.each([
+    ['search', {search: 'deploy'}],
+    ['status', {status: ['failed' as const]}],
+    ['branch', {branch: ['main']}],
+    ['actor', {actor: ['octocat']}],
+    ['event', {event: ['push']}],
+    ['after', {after: '2026-05-01'}],
+    ['before', {before: '2026-05-31'}],
+  ])('reports %s as an active filter', (_dimension, search) => {
+    expect(hasWorkflowRunFilters(search)).toBe(true);
   });
 
-  it('requires workspace and project path parameters', () => {
-    expect(workflowRouteParams({wid: 'workspace-1', pid: 'project-1'})).toEqual({
-      wid: 'workspace-1',
-      pid: 'project-1',
+  test('does not count a run selection parameter as a filter', () => {
+    expect(hasWorkflowRunFilters({runAttempt: 2, jobId: 'job-1'})).toBe(false);
+  });
+});
+
+describe('workflowRouteParams', () => {
+  test('requires workspace and project path parameters', () => {
+    expect(workflowRouteParams({workspaceSlug: 'workspace-1', projectSlug: 'project-1'})).toEqual({
+      workspaceSlug: 'workspace-1',
+      projectSlug: 'project-1',
     });
-    expect(() => workflowRouteParams({wid: 'workspace-1'})).toThrow(
+    expect(() => workflowRouteParams({workspaceSlug: 'workspace-1'})).toThrow(
       'Workflow route is missing required path parameters.',
     );
-    expect(() => workflowRouteParams({wid: 'workspace-1', pid: null})).toThrow();
+    expect(() => workflowRouteParams({workspaceSlug: 'workspace-1', projectSlug: null})).toThrow();
   });
 });

package/src/routes/inputs.ts

@@ -1,18 +1,53 @@
-import type {WorkflowRunListStatusFilter} from '#components/workflow-run-list/types.js';
 import type {WorkflowRunSelectionInput} from '#core/workflow-run-url-state.js';
 
+/**
+ * Statuses the run list can filter by. Absent means all; there is deliberately no `all`
+ * value, so "no filter" and "every filter" are the same URL rather than two.
+ */
+export const WORKFLOW_RUN_LIST_STATUSES = ['succeeded', 'failed', 'running', 'cancelled'] as const;
+
+export type WorkflowRunListStatus = (typeof WORKFLOW_RUN_LIST_STATUSES)[number];
+
 export interface WorkflowRunsSearch extends WorkflowRunSelectionInput {
   search?: string;
-  status?: WorkflowRunListStatusFilter;
+  status?: WorkflowRunListStatus[];
+  branch?: string[];
+  actor?: string[];
+  event?: string[];
+  /** Inclusive lower bound on the run's local calendar date, `YYYY-MM-DD`. */
+  after?: string;
+  /** Inclusive upper bound on the run's local calendar date, `YYYY-MM-DD`. */
+  before?: string;
 }
 
+const STATUS_VALUES = new Set<string>(WORKFLOW_RUN_LIST_STATUSES);
+const CALENDAR_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
+
+/**
+ * Reads the run list and run detail query string.
+ *
+ * Every value is dropped rather than rejected when it does not fit: a truncated or
+ * hand-edited URL should degrade to a sensible page, never to an error screen. Unknown
+ * parameters are ignored for the same reason.
+ */
 export function validateWorkflowRunsSearch(input: Record<string, unknown>): WorkflowRunsSearch {
   const search = string(input.search);
-  const status = input.status === 'failed' || input.status === 'running' ? input.status : 'all';
+  const status = repeatable(input.status).filter(isWorkflowRunListStatus);
+  const branch = repeatable(input.branch);
+  const actor = repeatable(input.actor);
+  const event = repeatable(input.event);
+  const after = calendarDate(input.after);
+  const before = calendarDate(input.before);
   const runAttempt = positiveInteger(input.runAttempt);
+
   return {
     ...(search ? {search} : {}),
-    ...(status === 'all' ? {} : {status}),
+    ...(status.length > 0 ? {status} : {}),
+    ...(branch.length > 0 ? {branch} : {}),
+    ...(actor.length > 0 ? {actor} : {}),
+    ...(event.length > 0 ? {event} : {}),
+    ...(after ? {after} : {}),
+    ...(before ? {before} : {}),
     ...(string(input.job) ? {jobId: string(input.job)} : {}),
     ...(string(input.jobExecution) ? {jobExecutionId: string(input.jobExecution)} : {}),
     ...(string(input.step) ? {stepId: string(input.step)} : {}),
@@ -21,13 +56,24 @@ export function validateWorkflowRunsSearch(input: Record<string, unknown>): Work
   };
 }
 
+/**
+ * Writes the query string back.
+ *
+ * Array values reach the router as arrays and the app's `stringifySearch` expands each into
+ * repeated keys; joining them here would defeat that and break on branch names with commas.
+ */
 export function workflowRunSearchParams(
   search: WorkflowRunsSearch,
   selection: WorkflowRunSelectionInput = search,
 ) {
   return {
     ...(search.search ? {search: search.search} : {}),
-    ...(search.status && search.status !== 'all' ? {status: search.status} : {}),
+    ...(search.status?.length ? {status: search.status} : {}),
+    ...(search.branch?.length ? {branch: search.branch} : {}),
+    ...(search.actor?.length ? {actor: search.actor} : {}),
+    ...(search.event?.length ? {event: search.event} : {}),
+    ...(search.after ? {after: search.after} : {}),
+    ...(search.before ? {before: search.before} : {}),
     ...(selection.jobId ? {job: selection.jobId} : {}),
     ...(selection.jobExecutionId ? {jobExecution: selection.jobExecutionId} : {}),
     ...(selection.stepId ? {step: selection.stepId} : {}),
@@ -36,16 +82,129 @@ export function workflowRunSearchParams(
   };
 }
 
+/**
+ * A filter change. Each member is explicitly optional-or-undefined so that "present and
+ * undefined" (clear this filter) stays distinguishable from "absent" (leave it alone) under
+ * `exactOptionalPropertyTypes`.
+ */
+export interface WorkflowRunFilterPatch {
+  search?: string | undefined;
+  status?: WorkflowRunListStatus[] | undefined;
+  branch?: string[] | undefined;
+  actor?: string[] | undefined;
+  event?: string[] | undefined;
+  after?: string | undefined;
+  before?: string | undefined;
+}
+
+/**
+ * Applies a filter change.
+ *
+ * A key present with `undefined`, an empty string, or an empty array clears that filter; a
+ * key left out is untouched. Cleared filters are deleted rather than stored empty, so "no
+ * filter" is one URL instead of several that render the same list.
+ */
+export function applyWorkflowRunFilterPatch(
+  search: WorkflowRunsSearch,
+  patch: WorkflowRunFilterPatch,
+): WorkflowRunsSearch {
+  const next: WorkflowRunsSearch = {...search};
+  if ('search' in patch) setOrDelete(next, 'search', patch.search || undefined);
+  if ('status' in patch) setOrDelete(next, 'status', nonEmptyList(patch.status));
+  if ('branch' in patch) setOrDelete(next, 'branch', nonEmptyList(patch.branch));
+  if ('actor' in patch) setOrDelete(next, 'actor', nonEmptyList(patch.actor));
+  if ('event' in patch) setOrDelete(next, 'event', nonEmptyList(patch.event));
+  if ('after' in patch) setOrDelete(next, 'after', patch.after || undefined);
+  if ('before' in patch) setOrDelete(next, 'before', patch.before || undefined);
+  return next;
+}
+
+/** Drops every filter while keeping the run-selection parameters the detail route owns. */
+export function clearWorkflowRunFilters(search: WorkflowRunsSearch): WorkflowRunsSearch {
+  return applyWorkflowRunFilterPatch(search, {
+    search: undefined,
+    status: undefined,
+    branch: undefined,
+    actor: undefined,
+    event: undefined,
+    after: undefined,
+    before: undefined,
+  });
+}
+
+/** True when any list filter is active, which separates "no matches" from "no runs". */
+export function hasWorkflowRunFilters(search: WorkflowRunsSearch): boolean {
+  return Boolean(
+    search.search ||
+      search.status?.length ||
+      search.branch?.length ||
+      search.actor?.length ||
+      search.event?.length ||
+      search.after ||
+      search.before,
+  );
+}
+
 export function workflowRouteParams(input: Record<string, unknown>): {
-  wid: string;
-  pid: string;
+  workspaceSlug: string;
+  projectSlug: string;
   workflowRunId?: string;
 } {
-  const wid = string(input.wid);
-  const pid = string(input.pid);
-  if (!wid || !pid) throw new Error('Workflow route is missing required path parameters.');
+  const workspaceSlug = string(input.workspaceSlug);
+  const projectSlug = string(input.projectSlug);
+  if (!workspaceSlug || !projectSlug)
+    throw new Error('Workflow route is missing required path parameters.');
   const workflowRunId = string(input.workflowRunId);
-  return workflowRunId ? {wid, pid, workflowRunId} : {wid, pid};
+  return workflowRunId ? {workspaceSlug, projectSlug, workflowRunId} : {workspaceSlug, projectSlug};
+}
+
+function setOrDelete<TKey extends keyof WorkflowRunsSearch>(
+  target: WorkflowRunsSearch,
+  key: TKey,
+  value: WorkflowRunsSearch[TKey] | undefined,
+): void {
+  if (value === undefined) delete target[key];
+  else target[key] = value;
+}
+
+function nonEmptyList<TValue>(value: readonly TValue[] | undefined): TValue[] | undefined {
+  return value && value.length > 0 ? [...value] : undefined;
+}
+
+function isWorkflowRunListStatus(value: string): value is WorkflowRunListStatus {
+  return STATUS_VALUES.has(value);
+}
+
+/**
+ * Normalizes a repeatable parameter into a deduplicated list.
+ *
+ * A single occurrence parses as a scalar rather than a one-element array, and the parser
+ * coerces bare digits to numbers, so `?branch=2024` has to survive as the string `"2024"`.
+ */
+function repeatable(value: unknown): string[] {
+  const values = Array.isArray(value) ? value : [value];
+  const normalized = values.flatMap((entry) => {
+    if (typeof entry === 'string') return entry.length > 0 ? [entry] : [];
+    if (typeof entry === 'number' && Number.isFinite(entry)) return [String(entry)];
+    if (typeof entry === 'boolean') return [String(entry)];
+    return [];
+  });
+  return [...new Set(normalized)];
+}
+
+function calendarDate(value: unknown): string | undefined {
+  if (typeof value !== 'string' || !CALENDAR_DATE_PATTERN.test(value)) return undefined;
+  // Rejects a well-shaped but impossible date such as 2026-02-31, which Date rolls forward.
+  // Parsed as UTC: whether `2026-05-01` is a real date does not depend on the reader's zone,
+  // and a local-time parse would reject a day the reader's zone skipped outright.
+  const [year, month, day] = value.split('-').map(Number) as [number, number, number];
+  const parsed = new Date(`${value}T00:00:00.000Z`);
+  const isRealDate =
+    !Number.isNaN(parsed.getTime()) &&
+    parsed.getUTCFullYear() === year &&
+    parsed.getUTCMonth() === month - 1 &&
+    parsed.getUTCDate() === day;
+  return isRealDate ? value : undefined;
 }
 
 function string(value: unknown): string | undefined {

package/src/routes/project-route.tsx

@@ -0,0 +1,25 @@
+import {type Project, useMaybeActiveProjectQuery} from '@shipfox/client-projects';
+import {QueryLoadError} from '@shipfox/client-ui';
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+import {FullPageLoader} from '@shipfox/react-ui/loader';
+import type {ReactNode} from 'react';
+
+export function ProjectRoute({children}: {children: (project: Project) => ReactNode}) {
+  const projectQuery = useMaybeActiveProjectQuery();
+
+  if (projectQuery.isPending) return <FullPageLoader />;
+  if (projectQuery.isError && projectQuery.data === undefined) {
+    return <QueryLoadError query={projectQuery} subject="project" />;
+  }
+  if (!projectQuery.data) {
+    return (
+      <EmptyState
+        icon="errorWarningLine"
+        title="Project not found"
+        description="This project doesn't exist, or you don't have access to it."
+      />
+    );
+  }
+
+  return children(projectQuery.data);
+}

package/src/routes/run-detail.tsx

@@ -1,19 +1,26 @@
 import {defineRoute, useRouteParams, useRouteSearch} from '@shipfox/client-shell/runtime';
-import {WorkflowRunPage} from '#pages/workflow-run-page.js';
+import {WorkflowRunDetailPage} from '#pages/workflow-run-detail-page.js';
 import {validateWorkflowRunsSearch, workflowRouteParams} from './inputs.js';
+import {ProjectRoute} from './project-route.js';
 
 export default defineRoute({
   staticData: {layout: 'full-bleed'},
   validateSearch: validateWorkflowRunsSearch,
   component: () => {
-    const {wid, pid, workflowRunId} = useRouteParams(workflowRouteParams);
+    const {workspaceSlug, projectSlug, workflowRunId} = useRouteParams(workflowRouteParams);
+    const search = useRouteSearch(validateWorkflowRunsSearch);
     return (
-      <WorkflowRunPage
-        workspaceId={wid}
-        projectId={pid}
-        workflowRunId={workflowRunId}
-        search={useRouteSearch(validateWorkflowRunsSearch)}
-      />
+      <ProjectRoute>
+        {(project) => (
+          <WorkflowRunDetailPage
+            projectId={project.id}
+            workspaceSlug={workspaceSlug}
+            projectSlug={projectSlug}
+            workflowRunId={workflowRunId}
+            search={search}
+          />
+        )}
+      </ProjectRoute>
     );
   },
 });

package/src/routes/runs.tsx

@@ -1,18 +1,25 @@
 import {defineRoute, useRouteParams, useRouteSearch} from '@shipfox/client-shell/runtime';
-import {WorkflowRunPage} from '#pages/workflow-run-page.js';
+import {WorkflowRunsPage} from '#pages/workflow-run-list-page.js';
 import {validateWorkflowRunsSearch, workflowRouteParams} from './inputs.js';
+import {ProjectRoute} from './project-route.js';
 
 export default defineRoute({
   staticData: {layout: 'full-bleed'},
   validateSearch: validateWorkflowRunsSearch,
   component: () => {
-    const {wid, pid} = useRouteParams(workflowRouteParams);
+    const {workspaceSlug, projectSlug} = useRouteParams(workflowRouteParams);
+    const search = useRouteSearch(validateWorkflowRunsSearch);
     return (
-      <WorkflowRunPage
-        workspaceId={wid}
-        projectId={pid}
-        search={useRouteSearch(validateWorkflowRunsSearch)}
-      />
+      <ProjectRoute>
+        {(project) => (
+          <WorkflowRunsPage
+            projectId={project.id}
+            workspaceSlug={workspaceSlug}
+            projectSlug={projectSlug}
+            search={search}
+          />
+        )}
+      </ProjectRoute>
     );
   },
 });

package/src/routes/workflows.tsx

@@ -1,10 +1,11 @@
-import {defineRoute, useRouteParams} from '@shipfox/client-shell/runtime';
+import {defineRoute} from '@shipfox/client-shell/runtime';
 import {ProjectWorkflowsPage} from '#pages/project-workflows-page.js';
-import {workflowRouteParams} from './inputs.js';
+import {ProjectRoute} from './project-route.js';
 
 export default defineRoute({
   component: () => {
-    const {pid} = useRouteParams(workflowRouteParams);
-    return <ProjectWorkflowsPage projectId={pid} />;
+    return (
+      <ProjectRoute>{(project) => <ProjectWorkflowsPage projectId={project.id} />}</ProjectRoute>
+    );
   },
 });