feat(evaluators): extend project empty state

js/app/src/GlobalStyles.tsx

@@ -88,6 +88,9 @@ const staticCSS = css`
     --global-button-height-s: var(--global-input-height-s);
     --global-button-height-m: var(--global-input-height-m);
     --global-button-height-l: var(--global-input-height-l);
+
+    // layout sizing
+    --global-text-content-max-width: 800px;
   }
 `;
 

js/app/src/Routes.tsx

@@ -500,7 +500,7 @@ export const appRouteObjects = createRoutesFromElements(
                   agentRoute: {
                     label: "Project Evaluators",
                     description:
-                      "Create and manage project evaluators — online evals that automatically run against live spans.",
+                      "Browse templates, create, and manage project evaluators — online evals that automatically run against live spans.",
                   },
                 }}
               >

js/app/src/constants/searchParams.ts

@@ -60,3 +60,14 @@ export const LABEL_ID_PARAM = "labelId";
 export const CREATE_CODE_EVALUATOR_PARAM = "createCodeEvaluator";
 
 export const CREATE_LLM_EVALUATOR_PARAM = "createLlmEvaluator";
+
+/**
+ * The evaluator template category selected in the project evaluator gallery.
+ * Uses the stable GraphQL enum value rather than the display label.
+ */
+export const PROJECT_EVALUATOR_CATEGORY_PARAM = "category";
+
+/**
+ * The evaluator template selected in the project evaluator gallery.
+ */
+export const PROJECT_EVALUATOR_TEMPLATE_PARAM = "template";

js/app/src/pages/project/ProjectConfigPage.tsx

@@ -53,7 +53,7 @@ const projectConfigPageCSS = css`
 
 const projectConfigPageInnerCSS = css`
   padding: var(--global-dimension-size-400);
-  max-width: 800px;
+  max-width: var(--global-text-content-max-width);
   min-width: 500px;
   box-sizing: border-box;
   width: 100%;

js/app/src/pages/project/evaluators/AddProjectEvaluatorMenu.tsx

@@ -20,6 +20,7 @@ import {
   MenuSectionTitle,
   MenuTrigger,
 } from "@phoenix/components/core/menu";
+import { Truncate } from "@phoenix/components/core/utility/Truncate";
 import { View } from "@phoenix/components/core/view";
 import type { projectEvaluatorOptionsQuery } from "@phoenix/pages/project/evaluators/__generated__/projectEvaluatorOptionsQuery.graphql";
 import { projectEvaluatorOptionsQuery as projectEvaluatorOptionsQueryNode } from "@phoenix/pages/project/evaluators/projectEvaluatorOptions";
@@ -28,30 +29,81 @@ import { useProjectEvaluatorPaths } from "@phoenix/pages/project/evaluators/proj
 export const AddProjectEvaluatorMenu = ({
   size,
   ...props
-}: {
+}: ProjectEvaluatorMenuTriggerProps) => {
+  return (
+    <ProjectEvaluatorMenu
+      size={size}
+      buttonLabel="Add evaluator"
+      buttonVariant="primary"
+      buttonLeadingVisual={<Icon svg={<Icons.Plus />} />}
+      shouldShowGalleryLink
+      {...props}
+    />
+  );
+};
+
+export const BuildProjectEvaluatorMenu = ({
+  size,
+  ...props
+}: ProjectEvaluatorMenuTriggerProps) => {
+  return (
+    <ProjectEvaluatorMenu
+      size={size}
+      buttonLabel="Build from scratch"
+      buttonVariant="default"
+      shouldShowGalleryLink={false}
+      {...props}
+    />
+  );
+};
+
+type ProjectEvaluatorMenuTriggerProps = {
   size: ButtonProps["size"];
-} & Omit<MenuTriggerProps, "children">) => {
+} & Omit<MenuTriggerProps, "children">;
+
+function ProjectEvaluatorMenu({
+  size,
+  buttonLabel,
+  buttonVariant,
+  buttonLeadingVisual,
+  shouldShowGalleryLink,
+  ...props
+}: ProjectEvaluatorMenuTriggerProps & {
+  buttonLabel: string;
+  buttonVariant: ButtonProps["variant"];
+  buttonLeadingVisual?: ButtonProps["leadingVisual"];
+  shouldShowGalleryLink: boolean;
+}) {
   return (
     <MenuTrigger {...props}>
       <Button
-        variant="primary"
+        variant={buttonVariant}
         size={size}
-        leadingVisual={<Icon svg={<Icons.Plus />} />}
+        leadingVisual={buttonLeadingVisual}
       >
-        Add evaluator
+        {buttonLabel}
       </Button>
       {/* Keep the query inside the popover so the evaluator list is fetched
           only when the menu opens. */}
       <MenuContainer minHeight="auto">
         <Suspense fallback={<Loading />}>
-          <AddProjectEvaluatorMenuItems />
+          <ProjectEvaluatorMenuItems
+            menuLabel={buttonLabel}
+            shouldShowGalleryLink={shouldShowGalleryLink}
+          />
         </Suspense>
       </MenuContainer>
     </MenuTrigger>
   );
-};
+}
 
-function AddProjectEvaluatorMenuItems() {
+function ProjectEvaluatorMenuItems({
+  menuLabel,
+  shouldShowGalleryLink,
+}: {
+  menuLabel: string;
+  shouldShowGalleryLink: boolean;
+}) {
   const navigate = useNavigate();
   const paths = useProjectEvaluatorPaths();
   const galleryHref = useHref(paths.gallery);
@@ -71,7 +123,7 @@ function AddProjectEvaluatorMenuItems() {
   return (
     <>
       <Menu
-        aria-label="Add evaluator"
+        aria-label={menuLabel}
         onAction={(action) => {
           if (action === "createEvaluator") {
             navigate(paths.newLlm);
@@ -80,15 +132,17 @@ function AddProjectEvaluatorMenuItems() {
           }
         }}
       >
-        <MenuSection>
-          <MenuItem
-            leadingContent={<Icon svg={<Icons.Grid />} />}
-            id="browseGallery"
-            href={galleryHref}
-          >
-            Browse the whole library
-          </MenuItem>
-        </MenuSection>
+        {shouldShowGalleryLink ? (
+          <MenuSection>
+            <MenuItem
+              leadingContent={<Icon svg={<Icons.Grid />} />}
+              id="browseGallery"
+              href={galleryHref}
+            >
+              Browse the whole library
+            </MenuItem>
+          </MenuSection>
+        ) : null}
         <MenuSection>
           <MenuSectionTitle title="LLM evaluator" />
           <MenuItem
@@ -167,10 +221,16 @@ function EvaluatorSubmenu({
               <Flex direction="column" gap="size-50">
                 <Text weight="heavy">{evaluator.name}</Text>
                 {evaluator.description ? (
-                  <Text size="S" color="text-700">
-                    {evaluator.description}
+                  <Truncate maxLines={3} title={evaluator.description}>
+                    <Text size="S" color="text-700">
+                      {evaluator.description}
+                    </Text>
+                  </Truncate>
+                ) : (
+                  <Text size="S" color="text-500" fontStyle="italic">
+                    No description
                   </Text>
-                ) : null}
+                )}
               </Flex>
             </MenuItem>
           )}

js/app/src/pages/project/evaluators/ProjectEvaluatorGalleryPage.tsx

@@ -1,8 +1,8 @@
 import { css } from "@emotion/react";
-import { Suspense, useState } from "react";
+import { Suspense } from "react";
 import { Header, ListBoxSection } from "react-aria-components";
 import { useLazyLoadQuery } from "react-relay";
-import { Outlet, useNavigate } from "react-router";
+import { Outlet, useNavigate, useSearchParams } from "react-router";
 
 import {
   Badge,
@@ -28,7 +28,14 @@ import {
 } from "@phoenix/components/annotation/optimizationUtils";
 import { LineClamp } from "@phoenix/components/core/utility/LineClamp";
 import { ErrorBoundary } from "@phoenix/components/exception";
-import type { projectEvaluatorTemplatesQuery as ProjectEvaluatorTemplatesQueryType } from "@phoenix/pages/project/evaluators/__generated__/projectEvaluatorTemplatesQuery.graphql";
+import {
+  PROJECT_EVALUATOR_CATEGORY_PARAM,
+  PROJECT_EVALUATOR_TEMPLATE_PARAM,
+} from "@phoenix/constants/searchParams";
+import type {
+  EvaluatorCategory,
+  projectEvaluatorTemplatesQuery as ProjectEvaluatorTemplatesQueryType,
+} from "@phoenix/pages/project/evaluators/__generated__/projectEvaluatorTemplatesQuery.graphql";
 import { useProjectEvaluatorPaths } from "@phoenix/pages/project/evaluators/projectEvaluatorPaths";
 import {
   getProjectEvaluatorTemplateCategoryLabel,
@@ -37,12 +44,25 @@ import {
   projectEvaluatorTemplatesQuery,
 } from "@phoenix/pages/project/evaluators/projectEvaluatorTemplates";
 
-const ALL_EVALUATORS_CATEGORY = "All evaluators";
-const RECOMMENDED_CATEGORY = "Recommended";
+const ALL_EVALUATORS_CATEGORY = "all" as const;
+const RECOMMENDED_CATEGORY = "recommended" as const;
+const OTHER_CATEGORY = "other" as const;
 const GALLERY_SKELETON_HEIGHT = 440;
 /** The combined minimum width of the category, template, and details columns. */
 const GALLERY_EXPANDED_MIN_WIDTH = 960;
 
+type TemplateCategory = EvaluatorCategory | typeof OTHER_CATEGORY;
+type GalleryCategory =
+  | TemplateCategory
+  | typeof ALL_EVALUATORS_CATEGORY
+  | typeof RECOMMENDED_CATEGORY;
+
+function getGalleryCategory(
+  category: EvaluatorCategory | null
+): TemplateCategory {
+  return category ?? OTHER_CATEGORY;
+}
+
 export function ProjectEvaluatorGalleryPage() {
   return (
     <main css={galleryContainerCSS}>
@@ -61,76 +81,102 @@ export function ProjectEvaluatorGalleryPage() {
 function EvaluatorGallery() {
   const navigate = useNavigate();
   const paths = useProjectEvaluatorPaths();
-  const [selectedCategory, setSelectedCategory] =
-    useState(RECOMMENDED_CATEGORY);
-  const [selectedTemplateName, setSelectedTemplateName] = useState<
-    string | null
-  >(null);
+  const [searchParams, setSearchParams] = useSearchParams();
   const data = useLazyLoadQuery<ProjectEvaluatorTemplatesQueryType>(
     projectEvaluatorTemplatesQuery,
     {},
     { fetchPolicy: "store-and-network" }
   );
   const templates = data.evaluatorGalleryConfigs;
   const categories = Array.from(
-    new Set(
-      templates.map(({ category }) =>
-        getProjectEvaluatorTemplateCategoryLabel(category)
-      )
-    )
+    new Set(templates.map(({ category }) => getGalleryCategory(category)))
   );
   const recommendedTemplateCount = templates.filter(
     ({ recommended }) => recommended
   ).length;
   const quickStartItems = [
     {
-      name: ALL_EVALUATORS_CATEGORY,
+      id: ALL_EVALUATORS_CATEGORY,
+      name: "All evaluators",
       count: templates.length,
     },
     {
-      name: RECOMMENDED_CATEGORY,
+      id: RECOMMENDED_CATEGORY,
+      name: "Recommended",
       count: recommendedTemplateCount,
     },
   ];
   const useCaseItems = categories.map((category) => ({
-    name: category,
+    id: category,
+    name:
+      category === OTHER_CATEGORY
+        ? "Other"
+        : getProjectEvaluatorTemplateCategoryLabel(category),
     count: templates.filter(
       ({ category: templateCategory }) =>
-        getProjectEvaluatorTemplateCategoryLabel(templateCategory) === category
+        getGalleryCategory(templateCategory) === category
     ).length,
   }));
   const categoryItems = [...quickStartItems, ...useCaseItems];
-  const activeCategory = categoryItems.some(
-    ({ name }) => name === selectedCategory
-  )
-    ? selectedCategory
-    : ALL_EVALUATORS_CATEGORY;
+  const requestedCategory = searchParams.get(PROJECT_EVALUATOR_CATEGORY_PARAM);
+  // Shared or stale URLs can contain an unknown category; Recommended is the
+  // gallery's stable fallback.
+  const activeCategoryItem = categoryItems.find(
+    ({ id }) => id === requestedCategory
+  );
+  const activeCategory: GalleryCategory =
+    activeCategoryItem?.id ?? RECOMMENDED_CATEGORY;
+  const activeCategoryLabel = activeCategoryItem?.name ?? "Recommended";
   const visibleTemplates = templates.filter(({ recommended, category }) => {
     if (activeCategory === ALL_EVALUATORS_CATEGORY) {
       return true;
     }
     if (activeCategory === RECOMMENDED_CATEGORY) {
       return recommended;
     }
-    return (
-      getProjectEvaluatorTemplateCategoryLabel(category) === activeCategory
-    );
+    return getGalleryCategory(category) === activeCategory;
   });
+  const requestedTemplateName = searchParams.get(
+    PROJECT_EVALUATOR_TEMPLATE_PARAM
+  );
+  // Fall back to the first visible template if a saved selection is no longer
+  // part of the active category.
   const selectedTemplate =
-    visibleTemplates.find(({ name }) => name === selectedTemplateName) ??
+    visibleTemplates.find(({ name }) => name === requestedTemplateName) ??
     visibleTemplates[0];
   const renderCategoryItem = ({
+    id,
     name,
     count,
   }: {
+    id: GalleryCategory;
     name: string;
     count: number;
   }) => (
-    <ListBoxItem key={name} id={name} textValue={name}>
+    <ListBoxItem key={id} id={id} textValue={name}>
       <Text size="S">{name}</Text>
       <Counter variant="quiet">{count}</Counter>
     </ListBoxItem>
   );
+  const setSelectedCategory = (category: string) => {
+    setSearchParams((currentSearchParams) => {
+      const nextSearchParams = new URLSearchParams(currentSearchParams);
+      if (category === RECOMMENDED_CATEGORY) {
+        nextSearchParams.delete(PROJECT_EVALUATOR_CATEGORY_PARAM);
+      } else {
+        nextSearchParams.set(PROJECT_EVALUATOR_CATEGORY_PARAM, category);
+      }
+      nextSearchParams.delete(PROJECT_EVALUATOR_TEMPLATE_PARAM);
+      return nextSearchParams;
+    });
+  };
+  const setSelectedTemplate = (templateName: string) => {
+    setSearchParams((currentSearchParams) => {
+      const nextSearchParams = new URLSearchParams(currentSearchParams);
+      nextSearchParams.set(PROJECT_EVALUATOR_TEMPLATE_PARAM, templateName);
+      return nextSearchParams;
+    });
+  };
 
   return (
     <div css={galleryCSS} className="project-evaluator-gallery">
@@ -233,7 +279,7 @@ function EvaluatorGallery() {
           size="S"
           weight="heavy"
         >
-          {activeCategory}
+          {activeCategoryLabel}
         </Text>
         <ListBox
           aria-labelledby="evaluator-template-list-title"
@@ -248,7 +294,7 @@ function EvaluatorGallery() {
             if (selection === "all") return;
             const templateName = selection.keys().next().value;
             if (typeof templateName === "string") {
-              setSelectedTemplateName(templateName);
+              setSelectedTemplate(templateName);
             }
           }}
         >