feat: build the Elements page: the design, the search, the results and Load more

backend/src/catalog/search.test.ts

@@ -12,6 +12,7 @@ import {
   BadUserInputError,
   type CatalogSearchArgs,
   listElementGroups,
+  MAX_TOTAL_COUNT,
   searchCatalog,
   searchTerms,
 } from './search.js'
@@ -502,4 +503,54 @@ describe.runIf(hasDatabase)('searchCatalog on the seeded catalog', () => {
     const page = await searchCatalog(prisma, { first: 1 })
     expect(page.totalCount).toBeUndefined()
   })
+
+  describe('the count stops at the most that is counted', () => {
+    const count = async (maxTotalCount?: number, search?: string) =>
+      (
+        await searchCatalog(prisma, {
+          first: 1,
+          search,
+          withTotalCount: true,
+          maxTotalCount,
+        })
+      ).totalCount
+
+    it('counts up to 1000 as it is, and the catalog is smaller than that', async () => {
+      expect(MAX_TOTAL_COUNT).toBe(1000)
+      expect(totalEntries).toBeLessThanOrEqual(MAX_TOTAL_COUNT)
+      expect(await count()).toBe(totalEntries)
+    })
+
+    it('stops at one more than the most, so a count above it means "more than that"', async () => {
+      expect(totalEntries).toBeGreaterThan(10)
+      expect(await count(10)).toBe(11)
+      expect(await count(1)).toBe(2)
+    })
+
+    it('is not capped when the most is as big as the number of matches, or bigger', async () => {
+      expect(await count(totalEntries)).toBe(totalEntries)
+      expect(await count(totalEntries + 500)).toBe(totalEntries)
+      // The most that is one less than the number of matches: one more than it is the
+      // number of matches, which is above the most.
+      expect(await count(totalEntries - 1)).toBe(totalEntries)
+    })
+
+    it('caps a search too, and a search with fewer matches than the most is counted as it is', async () => {
+      const all = await searchCatalog(prisma, {
+        first: 100,
+        search: 'handspring',
+        withTotalCount: true,
+      })
+      expect(all.totalCount).toBeGreaterThan(5)
+
+      expect(await count(5, 'handspring')).toBe(6)
+      expect(await count(all.totalCount! + 10, 'handspring')).toBe(
+        all.totalCount,
+      )
+    })
+
+    it('counts nothing for text with no searchable words, also with a cap', async () => {
+      expect(await count(10, '%')).toBe(0)
+    })
+  })
 })

backend/src/catalog/search.ts

@@ -36,19 +36,33 @@ export type CatalogSearchArgs = {
   /** Page size, 1–100. */
   first?: number | null
   after?: string | null
-  /** Count all matches. Only set it when the client asks for totalCount. */
+  /** Count the matches. Only set it when the client asks for totalCount. */
   withTotalCount?: boolean
+  /**
+   * The most matches that are counted, MAX_TOTAL_COUNT if it is left out. The count
+   * stops at one more than this, so a count above it means "more than this many".
+   */
+  maxTotalCount?: number
 }
 
 export type CatalogSearchResult = {
   edges: { cursor: string; node: CatalogEntry }[]
   pageInfo: { hasNextPage: boolean; endCursor: string | null }
-  /** Only set when withTotalCount was true. */
+  /**
+   * Only set when withTotalCount was true. At most maxTotalCount + 1: a value above
+   * maxTotalCount means that there are more matches than that.
+   */
   totalCount?: number
 }
 
 const DIRECTIONS: readonly SortDirection[] = ['ASC', 'DESC']
 const MAX_PAGE_SIZE = 100
+/**
+ * How many matches `totalCount` counts. A search that has more matches gets one more
+ * than this (1001), which the interface shows as "1000+". The database stops counting
+ * there, so the cost of the count does not grow with the catalog.
+ */
+export const MAX_TOTAL_COUNT = 1000
 /** Limits for the search text. Far more than anyone types, and each word adds a condition to the query. */
 export const MAX_SEARCH_LENGTH = 80
 export const MAX_SEARCH_WORDS = 8
@@ -237,9 +251,15 @@ export async function searchCatalog(
       endCursor: edges.at(-1)?.cursor ?? null,
     },
   }
-  // Counting reads every match, so it only runs when the client asks for it.
-  if (args.withTotalCount)
-    result.totalCount = await prisma.catalogEntry.count({ where })
+  // Counting reads the matches, so it only runs when the client asks for it, and it
+  // stops after one more than the most that is counted (take).
+  if (args.withTotalCount) {
+    const max = args.maxTotalCount ?? MAX_TOTAL_COUNT
+    result.totalCount = await prisma.catalogEntry.count({
+      where,
+      take: max + 1,
+    })
+  }
   return result
 }
 

backend/src/schema.graphql

@@ -205,7 +205,8 @@ type CatalogConnection {
   """
   Number of matches in the whole result set, not only this page. Counting is
   expensive on a large result, so the server only counts when the client asks
-  for this field.
+  for this field, and it stops at 1001: a value above 1000 means that there are
+  more than 1000 matches (the interface shows "1000+").
   """
   totalCount: Int!
 }

docs/AI_USAGE.md

@@ -447,6 +447,19 @@
   id, a stopped server and "Try again" work. The JavaScript bundle went from
   665 kB to 522 kB.
 
+## The Elements page (`src/components/elements/ElementsPage.tsx`, `ResultsTable.tsx`)
+
+- **Tool:** Claude Code
+- **What the team did:** Drew the page in a design (`elements_page.png`) and
+  chose that it should look exactly like it, without lines between the rows. Decided that this pull request is only the
+  design, and that the search, filters, sort and paging are connected in #110.
+- **What Claude did:** Measured the colors in the design and used the existing
+  tokens for all of them but the purple of every other row (new:
+  `--table-row-alt`). Wrote the page and the table with the existing badge for
+  the circle. Checked the page at 390, 768, 927 and 1440 pixels wide in a
+  browser, and chose how the table becomes cards on a phone and how the whole
+  row is one link. Wrote the tests.
+
 ## Tests for the element page (`src/components/elements/ElementDetailPage.test.tsx`, `src/tests/apollo.ts`)
 
 - **Tool:** Claude Code
@@ -460,3 +473,21 @@
   page one at a time (the drawing, the warning, the disabled buttons, the
   not-found page, "Try again", "Trying again…", keeping the current element and
   the variant link) and checked that a test failed each time.
+
+## The search and the results of the Elements page (`src/components/elements/ElementsPage.tsx`, `src/lib/searchOperations.ts`)
+
+- **Tool:** Claude Code
+- **What the team did:** Decided that making the page work is done in parts, each with its own issue and pull request, and that the first part is the search field and the results (#117). Chose that the pull request is stacked on the design (#114) until that is merged.
+- **What Claude did:** Wrote the query `searchCatalog` and the page with the results, the loading, error and empty states, the debounce and the search in the address. Moved the example rows to a fixture for the tests. Wrote the tests on the real Apollo Client with a stub for `fetch`, and checked them by breaking five behaviors one at a time (the tests fail without each of them). Checked in a browser against the real backend: the first 20 of 562, a search, no result, a search from the address, and 9 words.
+
+## Load more elements (`src/components/elements/ElementsPage.tsx`, `src/lib/searchOperations.ts`)
+
+- **Tool:** Claude Code
+- **What the team did:** Decided that "Load more elements" is disabled when everything is shown ("Showing N of N"), and that all the work to make the page work is one issue (#110), in several pull requests.
+- **What Claude did:** Wrote the query for the next page (without `totalCount`, which the API counts only when it is asked), the button with its states (loading, disabled when everything is shown, error with a new try) and the tests, and checked the tests by breaking six behaviors one at a time. Checked in a browser against the real backend: 20, 40 and 60 of 562, one result (disabled at once), and 36 of 36 for a search that has two pages.
+
+## The count of the search stops at 1001 (`backend/src/catalog/search.ts`)
+
+- **Tool:** Claude Code
+- **What the team did:** Decided that the page says "1000+" when there are more than 1000 results, and that the server must not count more than that.
+- **What Claude did:** Made the database stop counting at 1001 (`count` with `take`), kept the schema the same (a `totalCount` above 1000 means more than 1000), wrote the tests (the count stops at one more than the most, it is not capped below that, and a search is capped too) and broke the cap to check that they fail without it.

docs/API.md

@@ -158,7 +158,7 @@ The requirement is that the solution works with any amount of data. The catalog
 - **Filter and sort need indexes.** `schema.prisma` declares an index for each sort field combined with `id` (`codeSort`, `difficulty`, and `hasName` with `nameSort`), and for the filter columns (apparatus, group). Without them the database sorts the whole catalog for every request. The name sort puts named items first in both directions (`hasName` descending), so ascending and descending each have their own index. The apparatus filter is often combined with a sort, so there are also indexes on apparatus with `difficulty` and with `codeSort`. The difficulty sort always has an apparatus filter, so it uses the index on apparatus and `difficulty`. The difficulty filter without an apparatus uses the index on `difficulty`. Without them, a filtered page walks past the rows of the other apparatus first, which is slow in one direction (for example vault sorted by ascending difficulty).
 - **Sort by name needs a rule for items without a name.** Most items have no name. A cursor does not accept `nulls` placement, so the sort uses a plain `hasName` field and a `nameSort` field that is never `null` (see Search without raw SQL).
 - **The text search must not scan the table.** A search for `%word%` cannot use an ordinary index. The search uses a word table with a B-tree index and a prefix match, which finds the rows that have a word starting with the search term without reading every row. A search that is correct but reads every row works on 500 rows and not on 5 million.
-- **`totalCount` is only calculated when the client asks for it.** Counting a large result takes time: about 30 ms for the whole catalog and about 100 ms for a search in a test with 225 000 entries, and the cost grows with the catalog. The resolver for the field runs only if `totalCount` is in the query, so a client that scrolls without showing a total does not pay for it. The client should therefore ask for `totalCount` only with the first page of a new search or filter, and not with the pages that are loaded while scrolling. Together with the debounce on the search field, this keeps the count from running on every keystroke. If the count is still too slow, it can be capped (for example "1000+"), which needs a change in the schema.
+- **`totalCount` is only calculated when the client asks for it.** Counting a large result takes time: about 30 ms for the whole catalog and about 100 ms for a search in a test with 225 000 entries, and the cost grows with the catalog. The resolver for the field runs only if `totalCount` is in the query, so a client that scrolls without showing a total does not pay for it. The client should therefore ask for `totalCount` only with the first page of a new search or filter, and not with the pages that are loaded while scrolling. Together with the debounce on the search field, this keeps the count from running on every keystroke. **The count is capped:** it stops at 1001 (`MAX_TOTAL_COUNT` is 1000, and the database counts one more), so the cost does not grow with the catalog. A `totalCount` above 1000 means that there are more than 1000 matches, and the interface shows "1000+". The schema is the same (`Int!`), only the meaning of a value above 1000 is new.
 - **Elements and vaults are different tables, but one list.** A query cannot combine two tables into one sorted and paged result. The data model keeps them apart because they work differently, so the list is read from `CatalogEntry`, a read-only table with the shared columns that the seed script fills. It never gets out of date because the catalog never changes between seed runs.
 - **Variants are few.** A variant group has two or three members, so `variants` does not need paging.
 

index.html

@@ -7,7 +7,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link
-      href="https://fonts.googleapis.com/css2?family=Faustina:wght@400;500;600;700&family=Inter:wght@400;500;600;700&display=swap"
+      href="https://fonts.googleapis.com/css2?family=Faustina:wght@400;500;600;700;800&family=Inter:wght@400;500;600;700&display=swap"
       rel="stylesheet"
     />
     <title>t29-project-2</title>

src/App.test.tsx

@@ -84,14 +84,30 @@ describe('App', () => {
     expect(screen.getAllByRole('main')).toHaveLength(1);
   });
 
+  it('opens the search page from the start address, the logo and the Search link', () => {
+    renderApp();
+    expect(window.location.pathname).toBe(`${import.meta.env.BASE_URL}elements`);
+    expect(screen.getByRole('heading', { level: 1, name: 'Elements' })).toBeTruthy();
+
+    for (const link of [
+      () => screen.getByRole('link', { name: /wag cop planner home/i }),
+      () => screen.getByRole('link', { name: 'Search' }),
+    ]) {
+      fireEvent.click(screen.getByRole('link', { name: 'About' }));
+      expect(screen.getByRole('heading', { name: 'About' })).toBeTruthy();
+
+      fireEvent.click(link());
+      expect(window.location.pathname).toBe(`${import.meta.env.BASE_URL}elements`);
+      expect(screen.getByRole('heading', { level: 1, name: 'Elements' })).toBeTruthy();
+    }
+  });
+
   it('guards the Gymnasts route and makes it available after login', () => {
     window.history.replaceState({}, '', `${import.meta.env.BASE_URL}gymnasts`);
     renderApp();
 
-    // Logged out, /gymnasts goes to the start page, which shows an element.
-    expect(window.location.pathname).toBe(
-      `${import.meta.env.BASE_URL}elements/UB-1.101-a`,
-    );
+    // Logged out, /gymnasts goes to the start page, which is the Elements page.
+    expect(window.location.pathname).toBe(`${import.meta.env.BASE_URL}elements`);
     expect(screen.queryByRole('link', { name: 'Gymnasts' })).toBeNull();
 
     fireEvent.click(screen.getByRole('button', { name: 'Log in' }));

src/App.tsx

@@ -5,6 +5,7 @@ import { SkipLink } from './components/skipLink/SkipLink';
 import { ProtectedRoute } from './components/ProtectedRoute';
 
 import ElementDetailPage from './components/elements/ElementDetailPage';
+import ElementsPage from './components/elements/ElementsPage';
 import YourGymnastsPage from './components/gymnasts/YourGymnastsPage';
 
 import './index.css';
@@ -14,17 +15,17 @@ import './styles/global.css';
 // Placeholder pages for routes without full implementations yet. Each page
 // has its own <main>, like the real pages.
 const CalculatorPage = () => (
-  <main>
+  <main className="px-5 py-8 text-left sm:px-8 lg:px-12">
     <h1>Calculator</h1>
   </main>
 );
 const AboutPage = () => (
-  <main>
+  <main className="px-5 py-8 text-left sm:px-8 lg:px-12">
     <h1>About</h1>
   </main>
 );
 const NotFoundPage = () => (
-  <main>
+  <main className="px-5 py-8 text-left sm:px-8 lg:px-12">
     <h1>404 - Page not found</h1>
   </main>
 );
@@ -56,10 +57,8 @@ export function App() {
       {/* The pages have their own <main>, so this is only the target of the skip link. */}
       <div id="main-content" tabIndex={-1} className="outline-none">
         <Routes>
-          <Route
-            path="/"
-            element={<Navigate to="/elements/UB-1.101-a" replace />}
-          />
+          <Route path="/" element={<Navigate to="/elements" replace />} />
+          <Route path="/elements" element={<ElementsPage />} />
           <Route path="/elements/:elementId" element={<ElementDetailPage />} />
 
           <Route path="/calculator" element={<CalculatorPage />} />

src/components/elements/ElementDetailPage.tsx

@@ -38,8 +38,8 @@ export default function ElementDetailPage() {
   if (problem) {
     const { message, retryable } = problem
     return (
-      <main className="element-detail-page min-h-svh bg-(--secondary-color) px-4 py-12 text-left">
-        <div className="mx-auto max-w-3xl space-y-3">
+      <main className="element-detail-page min-h-svh bg-(--secondary-color) px-5 py-12 text-left sm:px-8 lg:px-12">
+        <div className="space-y-3">
           <h1 className="text-3xl font-bold">Element details unavailable</h1>
           <p role="alert" className="text-(--text-color-dark)">
             {message}
@@ -63,12 +63,12 @@ export default function ElementDetailPage() {
     return (
       <main
         aria-busy="true"
-        className="element-detail-page min-h-svh bg-(--secondary-color) px-4 py-8 text-left"
+        className="element-detail-page min-h-svh bg-(--secondary-color) px-5 py-8 text-left sm:px-8 lg:px-12"
       >
         <p role="status" className="sr-only">
           Loading element details
         </p>
-        <div className="mx-auto max-w-3xl animate-pulse space-y-5 motion-reduce:animate-none">
+        <div className="animate-pulse space-y-5 motion-reduce:animate-none">
           <div className="h-16 rounded-xl bg-(--background-color-element)" />
           <div className="h-24 rounded-xl bg-(--background-color-element)" />
           <div className="h-80 rounded-xl bg-(--background-color-element)" />
@@ -79,8 +79,8 @@ export default function ElementDetailPage() {
 
   if (!item) {
     return (
-      <main className="element-detail-page min-h-svh bg-(--secondary-color) px-4 py-12 text-left">
-        <div className="mx-auto max-w-3xl space-y-3">
+      <main className="element-detail-page min-h-svh bg-(--secondary-color) px-5 py-12 text-left sm:px-8 lg:px-12">
+        <div className="space-y-3">
           <h1 className="text-3xl font-bold">Element not found</h1>
           <p className="text-(--text-color-dark)">
             No catalog item matches this address.
@@ -101,9 +101,9 @@ export default function ElementDetailPage() {
   return (
     <main
       aria-busy={loading}
-      className="element-detail-page min-h-svh bg-(--secondary-color) px-4 py-6 text-left sm:py-10"
+      className="element-detail-page min-h-svh bg-(--secondary-color) px-5 py-6 text-left sm:px-8 sm:py-10 lg:px-12"
     >
-      <div className="mx-auto flex max-w-3xl flex-col gap-5 sm:gap-6">
+      <div className="flex flex-col gap-5 sm:gap-6">
         <ElementDetailHeader element={element} />
         {element.removed && (
           <p

src/components/elements/ElementDiagram.tsx

@@ -13,7 +13,7 @@ export default function ElementDiagram({
           <img
             src={element.imageUrl}
             alt={`Illustration for ${displayCode(element, element.variants.length > 0)}${element.name ? `: ${element.name}` : ''}`}
-            className="block h-auto w-full object-contain"
+            className="block h-auto max-h-[75svh] w-full object-contain"
           />
         </CardContent>
       </Card>

src/components/elements/ElementMetadataCard.tsx

@@ -38,10 +38,10 @@ export default function ElementMetadataCard({
       <Card className="w-full bg-(--background-color-element)">
         <CardContent className="p-0">
           <dl className="grid grid-cols-1 gap-5 px-5 py-4 text-center sm:grid-cols-3 sm:gap-8">
-            <MetadataItem label={element.isVault ? 'D-value' : 'Difficulty'}>
+            <MetadataItem label="Difficulty">
               {element.isVault || !difficulty ? (
                 <ElementValueBadge
-                  label={element.isVault ? 'D-value' : 'Difficulty'}
+                  label="Difficulty"
                   value={element.value}
                 />
               ) : (