feat(webapp): live-reload the runs list with a new-runs banner

The runs index now live-updates the statuses of visible runs in place (live
fields fetched via RunsRepository) and shows a "N new runs / 99+ new runs"
refresh banner with a fade-in, via a /live polling endpoint and the
useRunsLiveReload hook. The new-runs count comes from listRunIds (capped at
99+), polling pauses while the tab is hidden and stops once the cap is hit.

Author: Ekaterina Bulatova

.server-changes/runs-list-live-reload.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+The runs index live-reloads visible run statuses and shows a "new runs created" refresh banner. Polling pauses while the browser tab is hidden.

apps/webapp/app/components/primitives/Buttons.tsx

@@ -318,12 +318,12 @@ export function ButtonContent(props: ButtonContentPropsType) {
 
 type ButtonPropsType = Pick<
   JSX.IntrinsicElements["button"],
-  "type" | "disabled" | "onClick" | "name" | "value" | "form" | "autoFocus"
+  "type" | "disabled" | "onClick" | "name" | "value" | "form" | "autoFocus" | "aria-label"
 > &
   React.ComponentProps<typeof ButtonContent>;
 
 export const Button = forwardRef<HTMLButtonElement, ButtonPropsType>(
-  ({ type, disabled, autoFocus, onClick, ...props }, ref) => {
+  ({ type, disabled, autoFocus, onClick, "aria-label": ariaLabel, ...props }, ref) => {
     const innerRef = useRef<HTMLButtonElement>(null);
     useImperativeHandle(ref, () => innerRef.current as HTMLButtonElement);
 
@@ -352,6 +352,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonPropsType>(
         ref={innerRef}
         form={props.form}
         autoFocus={autoFocus}
+        aria-label={ariaLabel}
       >
         <ButtonContent
           {...props}

apps/webapp/app/components/primitives/PulsingDot.tsx

@@ -0,0 +1,23 @@
+import { cn } from "~/utils/cn";
+
+export function PulsingDot({
+  className,
+  ringClassName,
+  dotClassName,
+}: {
+  className?: string;
+  ringClassName?: string;
+  dotClassName?: string;
+}) {
+  return (
+    <span className={cn("relative flex size-2", className)}>
+      <span
+        className={cn(
+          "absolute h-full w-full animate-ping rounded-full border border-blue-500 opacity-100 duration-1000",
+          ringClassName
+        )}
+      />
+      <span className={cn("size-2 rounded-full bg-blue-500", dotClassName)} />
+    </span>
+  );
+}

apps/webapp/app/hooks/useInterval.ts

@@ -6,6 +6,8 @@ type UseIntervalOptions = {
   onLoad?: boolean;
   onFocus?: boolean;
   disabled?: boolean;
+  /** Skip interval ticks while the document tab is hidden */
+  pauseWhenHidden?: boolean;
   callback: () => void;
 };
 
@@ -14,6 +16,7 @@ export function useInterval({
   onLoad = true,
   onFocus = true,
   disabled = false,
+  pauseWhenHidden = false,
   callback,
 }: UseIntervalOptions) {
   // Always keep the latest callback in a ref so the effects below
@@ -28,11 +31,14 @@ export function useInterval({
     if (!interval || interval <= 0 || disabled) return;
 
     const intervalId = setInterval(() => {
+      if (pauseWhenHidden && document.visibilityState !== "visible") {
+        return;
+      }
       latestCallback.current();
     }, interval);
 
     return () => clearInterval(intervalId);
-  }, [interval, disabled]);
+  }, [interval, disabled, pauseWhenHidden]);
 
   // On focus
   useEffect(() => {

apps/webapp/app/presenters/v3/mapRunToLiveFields.server.ts

@@ -0,0 +1,21 @@
+import { isCancellableRunStatus, isFinalRunStatus, isPendingRunStatus } from "~/v3/taskStatus";
+import type { ListedRun } from "~/services/runsRepository/runsRepository.server";
+
+export function mapRunToLiveFields(run: ListedRun) {
+  const hasFinished = isFinalRunStatus(run.status);
+  const startedAt = run.startedAt ?? run.lockedAt;
+
+  return {
+    friendlyId: run.friendlyId,
+    status: run.status,
+    updatedAt: run.updatedAt.toISOString(),
+    startedAt: startedAt?.toISOString(),
+    finishedAt: hasFinished ? run.completedAt?.toISOString() ?? run.updatedAt.toISOString() : undefined,
+    hasFinished,
+    isCancellable: isCancellableRunStatus(run.status),
+    isPending: isPendingRunStatus(run.status),
+    usageDurationMs: Number(run.usageDurationMs),
+    costInCents: run.costInCents,
+    baseCostInCents: run.baseCostInCents,
+  };
+}

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.runs._index/route.tsx

@@ -1,5 +1,5 @@
 import { BeakerIcon, BookOpenIcon } from "@heroicons/react/24/solid";
-import { type MetaFunction, useNavigation } from "@remix-run/react";
+import { type MetaFunction, useNavigation, useRevalidator } from "@remix-run/react";
 import { type LoaderFunctionArgs } from "@remix-run/server-runtime";
 import { Suspense } from "react";
 import {
@@ -14,11 +14,12 @@ import { DevDisconnectedBanner, useDevPresence } from "~/components/DevPresence"
 import { StepContentContainer } from "~/components/StepContentContainer";
 import { MainCenteredContainer, PageBody } from "~/components/layout/AppLayout";
 import { Badge } from "~/components/primitives/Badge";
-import { LinkButton } from "~/components/primitives/Buttons";
+import { Button, LinkButton } from "~/components/primitives/Buttons";
 import { Header1 } from "~/components/primitives/Headers";
 import { InfoPanel } from "~/components/primitives/InfoPanel";
 import { NavBar, PageAccessories, PageTitle } from "~/components/primitives/PageHeader";
 import { Paragraph } from "~/components/primitives/Paragraph";
+import { PulsingDot } from "~/components/primitives/PulsingDot";
 import {
   RESIZABLE_PANEL_ANIMATION,
   ResizableHandle,
@@ -64,6 +65,7 @@ import { throwNotFound } from "~/utils/httpErrors";
 import { ListPagination } from "../../components/ListPagination";
 import { CreateBulkActionInspector } from "../resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.runs.bulkaction";
 import { Callout } from "~/components/primitives/Callout";
+import { useRunsLiveReload } from "./useRunsLiveReload";
 
 export const meta: MetaFunction = () => {
   return [
@@ -89,7 +91,10 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
 
   const filters = await getRunFiltersFromRequest(request);
 
-  const clickhouse = await clickhouseFactory.getClickhouseForOrganization(project.organizationId, "standard");
+  const clickhouse = await clickhouseFactory.getClickhouseForOrganization(
+    project.organizationId,
+    "standard"
+  );
   const presenter = new NextRunListPresenter($replica, clickhouse);
   const list = presenter.call(project.organizationId, environment.id, {
     userId,
@@ -203,12 +208,36 @@ function RunsList({
   rootOnlyDefault: boolean;
   filters: TaskRunListSearchFilters;
 }) {
+  const revalidator = useRevalidator();
   const navigation = useNavigation();
   const isLoading = navigation.state !== "idle";
   const organization = useOrganization();
   const project = useProject();
   const environment = useEnvironment();
   const { has, replace } = useSearchParams();
+  const { visibleRuns, showNewRunsBanner, newRunsCount, dismissNewRuns, childrenStatusesBasePath } =
+    useRunsLiveReload({
+      runs: list.runs,
+      hasAnyRuns: list.hasAnyRuns,
+      isLoading,
+      organizationSlug: organization.slug,
+      projectSlug: project.slug,
+      environmentSlug: environment.slug,
+    });
+
+  const onClickShowNewRuns = () => {
+    const isPaginated = has("cursor") || has("direction");
+    dismissNewRuns();
+    if (isPaginated) {
+      replace({
+        cursor: undefined,
+        direction: undefined,
+      });
+      return;
+    }
+
+    revalidator.revalidate();
+  };
 
   // Shortcut keys for bulk actions
   useShortcutKeys({
@@ -265,6 +294,20 @@ function RunsList({
                     rootOnlyDefault={rootOnlyDefault}
                   />
                   <div className="flex items-center justify-end gap-x-2">
+                    {showNewRunsBanner && (
+                      <span className="flex duration-150 animate-in fade-in-0">
+                        <Button
+                          variant="secondary/small"
+                          className="text-text-bright"
+                          onClick={onClickShowNewRuns}
+                          LeadingIcon={<PulsingDot className="h-2 w-2" />}
+                          tooltip="Refresh to see new runs"
+                          aria-label="New runs created. Refresh to see new runs."
+                        >
+                          {newRunsCount >= 100 ? "99+ new runs" : `${newRunsCount} new runs`}
+                        </Button>
+                      </span>
+                    )}
                     {!isShowingBulkActionInspector && (
                       <LinkButton
                         variant="secondary/small"
@@ -303,10 +346,11 @@ function RunsList({
                 </div>
 
                 <TaskRunsTable
-                  total={list.runs.length}
+                  total={visibleRuns.length}
                   hasFilters={list.hasFilters}
                   filters={list.filters}
-                  runs={list.runs}
+                  runs={visibleRuns}
+                  childrenStatusesBasePath={childrenStatusesBasePath}
                   isLoading={isLoading}
                   allowSelection
                   rootOnlyDefault={rootOnlyDefault}