@chiselandco/nexus 2.2.7 → 2.5.0

package/README.md

@@ -1,6 +1,10 @@
 # @chiselandco/nexus
 
-A suite of self-contained project portfolio components for Next.js App Router. Drop in a `clientSlug` and `apiBase` — each component fetches, caches, and renders everything it needs with zero client-side waterfall requests.
+Self-contained project portfolio components for Next.js App Router. Pass a `clientSlug`, `apiBase`, and `apiKey` — each component fetches, caches, and renders everything it needs with no client-side waterfall requests.
+
+**Version:** 2.4.0
+
+---
 
 ## Requirements
 
@@ -9,6 +13,8 @@ A suite of self-contained project portfolio components for Next.js App Router. D
 
 No other dependencies required.
 
+---
+
 ## Installation
 
 ```bash
@@ -19,23 +25,24 @@ npm install @chiselandco/nexus
 
 ## Quick Start
 
-Here is the most common full setup — a projects grid page, a detail page with similar projects, and a megamenu in the nav.
+The most common full setup — a filterable projects grid, a detail page with similar projects, and a megamenu in the nav.
 
 ```tsx
 // app/projects/page.tsx
-import { ProjectPortfolio } from "@chiselandco/nexus"
+import { FilteredPortfolio } from "@chiselandco/nexus"
 
 export default async function ProjectsPage({
   searchParams,
 }: {
-  searchParams: { [key: string]: string | string[] | undefined }
+  searchParams: Promise<Record<string, string | string[] | undefined>>
 }) {
   return (
-    <ProjectPortfolio
+    <FilteredPortfolio
       clientSlug="your-client-slug"
       apiBase="https://your-api.com"
+      apiKey={process.env.YOUR_CLIENT_API_KEY!}
       basePath="/projects"
-      searchParams={searchParams}
+      searchParams={await searchParams}
     />
   )
 }
@@ -45,26 +52,29 @@ export default async function ProjectsPage({
 // app/projects/[slug]/page.tsx
 import { ProjectDetail, SimilarProjects } from "@chiselandco/nexus"
 
-export default async function ProjectPage({ params }: { params: { slug: string } }) {
+export default async function ProjectPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>
+}) {
+  const { slug } = await params
+  const apiKey = process.env.YOUR_CLIENT_API_KEY!
+
   return (
     <>
       <ProjectDetail
-        slug={params.slug}
+        slug={slug}
         clientSlug="your-client-slug"
         apiBase="https://your-api.com"
+        apiKey={apiKey}
         backPath="/projects"
+        backLabel="All Projects"
       />
-
-      {/* Hardcode the slugs you want shown — update per client request */}
       <SimilarProjects
-        projectSlugs={[
-          "jacob-javits-convention-center",
-          "tillamook-bay-community-college",
-          "lcisd-liberty-hill-high-school",
-        ]}
-        excludeSlug={params.slug}
+        excludeSlug={slug}
         clientSlug="your-client-slug"
         apiBase="https://your-api.com"
+        apiKey={apiKey}
         basePath="/projects"
       />
     </>
@@ -79,18 +89,18 @@ import { createMenuHandler } from "@chiselandco/nexus"
 export const GET = createMenuHandler({
   clientSlug: "your-client-slug",
   apiBase: "https://your-api.com",
+  apiKey: process.env.YOUR_CLIENT_API_KEY!,
 })
 ```
 
 ```tsx
-// components/Nav.tsx — "use client" component in your header
+// components/Nav.tsx
 "use client"
 import { ProjectMenuClient } from "@chiselandco/nexus"
 
 export function Nav() {
   return (
     <nav>
-      {/* ... other nav items ... */}
       <ProjectMenuClient
         dataUrl="/api/chisel-menu"
         basePath="/projects"
@@ -105,25 +115,25 @@ export function Nav() {
 
 ## Components
 
-### `ProjectPortfolio`
+### `FilteredPortfolio`
 
-A full server-rendered project grid page. Fetches all projects for a client and renders them as responsive baseball cards (1 column on mobile, 2 on tablet, 3 on desktop). Supports URL-driven filtering via `searchParams`.
+Server component. The recommended primary projects grid. Fetches all projects once, reads `filter[key]=` URL params server-side to narrow results using AND-across-fields / OR-within-field logic, then renders a project count toolbar with a `FilterSidebar` trigger above a responsive card grid.
 
 ```tsx
-// app/projects/page.tsx
-import { ProjectPortfolio } from "@chiselandco/nexus"
+import { FilteredPortfolio } from "@chiselandco/nexus"
 
 export default async function ProjectsPage({
   searchParams,
 }: {
-  searchParams: { [key: string]: string | string[] | undefined }
+  searchParams: Promise<Record<string, string | string[] | undefined>>
 }) {
   return (
-    <ProjectPortfolio
+    <FilteredPortfolio
       clientSlug="your-client-slug"
       apiBase="https://your-api.com"
+      apiKey={process.env.YOUR_CLIENT_API_KEY!}
       basePath="/projects"
-      searchParams={searchParams}
+      searchParams={await searchParams}
     />
   )
 }
@@ -131,103 +141,71 @@ export default async function ProjectsPage({
 
 | Prop | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `clientSlug` | `string` | Yes | — | Identifies which client's projects to load |
-| `apiBase` | `string` | Yes | — | Base URL of the projects API |
-| `basePath` | `string` | No | `"/projects"` | Base path for project detail links |
-| `searchParams` | `Record<string, string \| string[] \| undefined>` | No | `{}` | Filter params forwarded to the API — pass Next.js `searchParams` directly |
-| `revalidate` | `number` | No | `86400` | Cache revalidation period in seconds (24 hours) |
-
-#### URL-driven filtering
+| `clientSlug` | `string` | Yes | — | Client identifier passed to the API |
+| `apiBase` | `string` | Yes | — | Base URL of the Chisel API |
+| `apiKey` | `string` | Yes | — | Client API key — always pass via environment variable, never hardcode |
+| `searchParams` | `Record<string, string \| string[] \| undefined>` | Yes | — | Resolved Next.js `searchParams` — await it before passing in Next.js 16+ |
+| `basePath` | `string` | No | `"/projects"` | Base path for project detail card links |
+| `filterKeys` | `string[]` | No | All eligible fields | Ordered list of field keys to expose in the filter drawer |
+| `font` | `string` | No | System font | Font family string |
+| `noCache` | `boolean` | No | `false` | Sets `cache: "no-store"` — useful during development |
+| `revalidate` | `number` | No | `86400` | Cache revalidation period in seconds |
 
-When a user clicks a "Browse By" filter link in the menu, they land on the grid with query params in the URL. Pass `searchParams` from the page and `ProjectPortfolio` forwards them to the API automatically.
+#### URL param format
 
-Filter URLs follow this pattern — the key matches the custom field key in the schema:
+Filters are written to and read from URL params in the form `filter[fieldKey]=slug1,slug2`. Multiple values within a field are OR'd; multiple fields are AND'd.
 
 ```
-/projects?filter[type]=commercial
-/projects?filter[type]=educational-facilities
+/projects?filter[application]=hospitality,education&filter[systems]=spacematic
 ```
 
-When active filters are applied, a filter banner is shown above the grid with a "Clear filters" link back to `basePath`.
-
 ---
 
-### `ProjectPortfolioClient`
-
-A `"use client"` version of the project grid. Fetches all projects once on mount (module-level cached — no re-fetch on remount) and filters them locally in memory. Use this when you need the grid inside a client component tree, or when you want to build your own custom filter UI.
-
-```tsx
-// Works in any component — no RSC required
-import { ProjectPortfolioClient } from "@chiselandco/nexus"
-
-export default function ProjectsPage() {
-  return (
-    <ProjectPortfolioClient
-      clientSlug="your-client-slug"
-      apiBase="https://your-api.com"
-      basePath="/projects"
-    />
-  )
-}
-```
+### `FilterSidebar`
 
-#### With a custom filter UI
+Client component (`"use client"`). Renders an "Advanced Filters" trigger that opens a right-side drawer with one section per filterable field. Pills are solid black when active and outlined when inactive. Filter state is written to URL params so filtered views are shareable and survive page refresh.
 
-Wire up your own dropdowns, buttons, or search inputs using the `filters` prop. Filter changes are instant — no API call on each change, all filtering happens in memory.
+Used internally by `FilteredPortfolio` — only import it standalone if you need to build a custom layout around it.
 
 ```tsx
-"use client"
-import { useState } from "react"
-import { ProjectPortfolioClient } from "@chiselandco/nexus"
+import { FilterSidebar } from "@chiselandco/nexus"
 
-export default function ProjectsPage() {
-  const [filters, setFilters] = useState<Record<string, string>>({})
-
-  return (
-    <>
-      {/* Your own filter UI */}
-      <select onChange={(e) => setFilters({ type: e.target.value })}>
-        <option value="">All Types</option>
-        <option value="commercial">Commercial</option>
-        <option value="educational-facilities">Educational</option>
-      </select>
-
-      <ProjectPortfolioClient
-        clientSlug="your-client-slug"
-        apiBase="https://your-api.com"
-        basePath="/projects"
-        filters={filters}
-      />
-    </>
-  )
-}
+<FilterSidebar
+  schema={schema}
+  filterKeys={["application", "systems", "material"]}
+  triggerLabel="Advanced Filters"
+/>
 ```
 
 | Prop | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `clientSlug` | `string` | Yes | — | Identifies which client's projects to load |
-| `apiBase` | `string` | Yes | — | Base URL of the projects API |
-| `basePath` | `string` | No | `"/projects"` | Base path for project detail links |
-| `filters` | `Record<string, string>` | No | `{}` | Active filters keyed by custom field key — filtering is instant, no API call on change |
-| `columns` | `2 \| 3` | No | `3` | Number of columns in the project grid |
-| `font` | `string` | No | System font stack | Font family string applied to all text |
+| `schema` | `CustomFieldSchema[]` | Yes | — | Field schema from the API — only `select` and `multi-select` fields with options are used |
+| `filterKeys` | `string[]` | No | All eligible fields | Ordered list of field keys to show in the drawer |
+| `triggerLabel` | `string` | No | `"Advanced Filters"` | Label for the trigger link |
+| `font` | `string` | No | `"inherit"` | Font family string |
 
 ---
 
 ### `ProjectDetail`
 
-A full server-rendered project detail page. Fetches a single project by slug and renders a hero image, a dynamic stats bar, a "Project Overview" section with description and specs sidebar, a photo gallery, and a back link.
+Server component. Fetches a single project by slug and renders a hero image, a stats bar, a project overview section with description and specs sidebar, and a `GalleryCarousel` with filterable media tag pills.
 
 ```tsx
 // app/projects/[slug]/page.tsx
 import { ProjectDetail } from "@chiselandco/nexus"
 
-export default async function ProjectPage({ params }: { params: { slug: string } }) {
+export default async function ProjectPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>
+}) {
+  const { slug } = await params
   return (
     <ProjectDetail
-      slug={params.slug}
+      slug={slug}
       clientSlug="your-client-slug"
       apiBase="https://your-api.com"
+      apiKey={process.env.YOUR_CLIENT_API_KEY!}
       backPath="/projects"
       backLabel="All Projects"
     />
@@ -237,24 +215,22 @@ export default async function ProjectPage({ params }: { params: { slug: string }
 
 #### Stats bar
 
-The stats bar below the hero is driven by an explicit ordered key list. Fields are shown in this order when present in the schema and populated on the project:
+The stats bar below the hero is schema-driven. Fields are shown in this order when present and populated:
 
-| Schema key | Label shown |
+| Schema key | Label |
 |---|---|
 | `location` | Location |
-| `type` (badge field) | field `name` from schema |
+| `type` | field `name` from schema |
 | `coverage` | Coverage |
 | `year-completed` | Completed |
 | `architect` | Architect |
 | `general-contractor` | General Contractor |
 
-If a field doesn't exist in the schema for a given client, or the project has no value for it, that stat is silently omitted. The column count adjusts automatically — 2 columns on mobile, 3 on tablet, up to 6 on desktop.
-
-#### Project Overview specs sidebar
+#### Specs sidebar
 
-The "Project Overview" section renders the project description on the left and a specs sidebar on the right (amber accent border). The sidebar shows the following fields when populated, in this order:
+The "Project Overview" section renders a specs sidebar when any of these fields are populated:
 
-| Schema key | Label shown |
+| Schema key | Label |
 |---|---|
 | `systems-used` | Systems Used |
 | `systems` | Track Systems |
@@ -263,69 +239,93 @@ The "Project Overview" section renders the project description on the left and a
 | `finishes` | Finishes |
 | `specifications` | Specifications |
 
-Each group renders values as outlined pills. Fields with no value for the current project are omitted. Both the stats bar and the specs sidebar are fully schema-driven — if a key doesn't exist in a client's schema it is simply not shown, making `ProjectDetail` safe to reuse across clients with wildly different field configurations.
+Both the stats bar and specs sidebar are fully schema-driven — fields not present in a client's schema are silently omitted, making `ProjectDetail` safe to use across clients with different field configurations.
+
+#### Media enrichment
+
+`ProjectDetail` automatically fetches `custom_field_values` from the list endpoint (where they are available) and merges them onto the single-project media items before passing them to `GalleryCarousel`. No extra work is needed.
 
 | Prop | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `slug` | `string` | Yes | — | The project slug to load |
 | `clientSlug` | `string` | Yes | — | The client slug that owns this project |
 | `apiBase` | `string` | Yes | — | Base URL of the projects API |
+| `apiKey` | `string` | Yes | — | Client API key — always pass via environment variable, never hardcode |
 | `backPath` | `string` | No | `"/projects"` | Path for the back navigation link |
 | `backLabel` | `string` | No | `"All Projects"` | Label for the back navigation link |
-| `revalidate` | `number` | No | `86400` | Cache revalidation period in seconds (24 hours) |
-| `noCache` | `boolean` | No | `false` | Bypasses the Next.js Data Cache and sets `cache: "no-store"`. Useful during development or for frequently updated projects. |
+| `revalidate` | `number` | No | `86400` | Cache revalidation period in seconds |
+| `noCache` | `boolean` | No | `false` | Sets `cache: "no-store"` — useful during development |
 
 ---
 
 ### `GalleryCarousel`
 
-A `"use client"` image carousel with previous/next arrows, a counter badge, and a scrollable thumbnail strip. Used internally by `ProjectDetail` but can also be used standalone if you fetch your own project data.
+Client component (`"use client"`). Image carousel with previous/next arrows, a counter badge, a scrollable thumbnail strip, URL-synced image filters, and automatic media tag pills. Used internally by `ProjectDetail` but can be used standalone.
 
 ```tsx
 "use client"
 import { GalleryCarousel } from "@chiselandco/nexus"
 
-// `media` is the array of image objects returned by the projects API
-export function ProjectGallery({ media, title }: { media: Media[]; title: string }) {
+export function ProjectGallery({ media, schema, title }) {
   return (
     <GalleryCarousel
       images={media}
       projectTitle={title}
+      schema={schema}
     />
   )
 }
 ```
 
-The main image and thumbnails are standardised to a `16/9` aspect ratio — no external CSS required.
+#### Media tag pills
+
+When a media item has `custom_field_values` set, `GalleryCarousel` renders frosted-glass pills in the bottom-left corner of the active image. Each pill shows the field name and resolved value — e.g. `System: Speed-Rail with Mesh Infill`, `Finish: Black Anodized`. Pills update as the user navigates between images.
+
+#### Image filtering
+
+When images have `custom_field_values`, a filter bar appears above the gallery. Each field that appears on at least one image is shown as a row of pill buttons. Selecting a pill narrows both the main image and the thumbnail strip to only matching images. Multiple fields can be filtered simultaneously (AND logic). Filter state is written to the URL so filtered views are shareable:
+
+```
+/projects/jacob-javits?filter[system]=Structural Glass&filter[finish]=Black Anodized
+```
 
 | Prop | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `images` | `Media[]` | Yes | — | Array of media objects from the projects API |
 | `projectTitle` | `string` | Yes | — | Used as the alt text fallback for the main image |
+| `schema` | `CustomFieldSchema[]` | No | `[]` | Client custom fields schema — used to resolve slug values to labels for pills and filter options |
 
 ---
 
 ### `SimilarProjects`
 
-A server-rendered similar projects section. Fetches all projects for a client, filters to those matching the provided field values, excludes the current project, and renders up to 3 matching results. Designed to be placed after `ProjectDetail` on a project detail page.
+Server component. Fetches all projects for a client, optionally filters to those matching provided field values, excludes the current project, and renders a section of matching results.
 
 ```tsx
 // app/projects/[slug]/page.tsx
 import { ProjectDetail, SimilarProjects } from "@chiselandco/nexus"
 
-export default async function ProjectPage({ params }: { params: { slug: string } }) {
+export default async function ProjectPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>
+}) {
+  const { slug } = await params
+  const apiKey = process.env.YOUR_CLIENT_API_KEY!
+
   return (
     <>
       <ProjectDetail
-        slug={params.slug}
+        slug={slug}
         clientSlug="your-client-slug"
         apiBase="https://your-api.com"
+        apiKey={apiKey}
       />
       <SimilarProjects
-        filters={{ type: "commercial" }}
-        excludeSlug={params.slug}
+        excludeSlug={slug}
         clientSlug="your-client-slug"
         apiBase="https://your-api.com"
+        apiKey={apiKey}
         basePath="/projects"
       />
     </>
@@ -333,133 +333,93 @@ export default async function ProjectPage({ params }: { params: { slug: string }
 }
 ```
 
-#### Deriving filters from the current project
+#### Filtering by field value
 
-In most real-world cases you want to match similar projects based on the current project's own field values. Fetch the project first, then pass its field values as filters:
+Pass `filters` to match projects that share a field value with the current project. The field values from the current project can be derived from the API response:
 
 ```tsx
-// app/projects/[slug]/page.tsx
-import { ProjectDetail, SimilarProjects } from "@chiselandco/nexus"
-
-async function getProject(slug: string, clientSlug: string, apiBase: string) {
-  const res = await fetch(
-    `${apiBase}/api/v1/clients/${clientSlug}/projects/${slug}?api_key=YOUR_API_KEY`,
-    { next: { revalidate: 86400 } }
-  )
-  return res.ok ? (await res.json())?.data : null
-}
+const apiKey = process.env.YOUR_CLIENT_API_KEY!
+const res = await fetch(
+  `${apiBase}/api/v1/clients/${clientSlug}/projects/${slug}?api_key=${apiKey}`,
+  { next: { revalidate: 86400 } }
+)
+const project = res.ok ? (await res.json())?.data : null
+// type may be a plain string or single-element array
+const typeVal = project?.custom_field_values?.type
+const projectType = Array.isArray(typeVal) ? typeVal[0] : typeVal ?? null
 
-export default async function ProjectPage({ params }: { params: { slug: string } }) {
-  const project = await getProject(params.slug, "your-client-slug", "https://your-api.com")
-  const projectType = project?.custom_field_values?.type ?? null
-
-  return (
-    <>
-      <ProjectDetail slug={params.slug} clientSlug="your-client-slug" apiBase="https://your-api.com" />
-      {projectType && (
-        <SimilarProjects
-          filters={{ type: projectType }}
-          excludeSlug={params.slug}
-          clientSlug="your-client-slug"
-          apiBase="https://your-api.com"
-          basePath="/projects"
-        />
-      )}
-    </>
-  )
-}
+<SimilarProjects
+  filters={projectType ? { type: projectType } : {}}
+  excludeSlug={slug}
+  clientSlug="your-client-slug"
+  apiBase="https://your-api.com"
+  apiKey={apiKey}
+  basePath="/projects"
+/>
 ```
 
-#### Manually specifying projects (recommended for quick setup)
+#### Manually specifying projects
 
-Pass `projectSlugs` to hand-pick exactly which projects appear, in the order you specify. This overrides `filters` entirely — useful when you want to curate the section rather than rely on field matching, or when you need a reliable result quickly without worrying about field values matching.
-
-This is the recommended approach for most client sites. The slugs are hardcoded in the page file. If a client wants different projects shown, update the slugs and redeploy.
+Pass `projectSlugs` to hand-pick exactly which projects appear. This overrides `filters` entirely and is the simplest approach when you want curated results. `excludeSlug` is still respected.
 
 ```tsx
-// app/projects/[slug]/page.tsx
-import { ProjectDetail, SimilarProjects } from "@chiselandco/nexus"
-
-export default async function ProjectPage({ params }: { params: { slug: string } }) {
-  return (
-    <>
-      {/* All your other page content above */}
-      <ProjectDetail
-        slug={params.slug}
-        clientSlug="your-client-slug"
-        apiBase="https://your-api.com"
-        backPath="/projects"
-      />
-
-      {/* Similar projects hardcoded — update slugs per client request */}
-      <SimilarProjects
-        projectSlugs={[
-          "jacob-javits-convention-center",
-          "tillamook-bay-community-college",
-          "lcisd-liberty-hill-high-school",
-        ]}
-        excludeSlug={params.slug}
-        clientSlug="your-client-slug"
-        apiBase="https://your-api.com"
-        basePath="/projects"
-      />
-    </>
-  )
-}
+<SimilarProjects
+  projectSlugs={[
+    "jacob-javits-convention-center",
+    "tillamook-bay-community-college",
+    "lcisd-liberty-hill-high-school",
+  ]}
+  excludeSlug={slug}
+  clientSlug="your-client-slug"
+  apiBase="https://your-api.com"
+  apiKey={process.env.YOUR_CLIENT_API_KEY!}
+  basePath="/projects"
+/>
 ```
 
-> `excludeSlug` is still respected even in `projectSlugs` mode — if the current page's slug appears in the list it is automatically removed so a project never links to itself.
-
-To update which projects appear, find the `projectSlugs` array in the page file and swap in the new slugs. Project slugs are visible in the URL when browsing the portfolio: `/projects/jacob-javits-convention-center` → slug is `jacob-javits-convention-center`.
-
 #### Card variant
 
-Use `variant="card"` to render the same baseball-card style used in `ProjectPortfolio` instead of the default list style:
+Use `variant="card"` to render baseball-card style instead of the default list style:
 
 ```tsx
-<SimilarProjects
-  filters={{ type: "commercial" }}
-  excludeSlug={params.slug}
-  clientSlug="your-client-slug"
-  apiBase="https://your-api.com"
-  basePath="/projects"
-  variant="card"
-/>
+<SimilarProjects variant="card" ... />
 ```
 
 | Prop | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `clientSlug` | `string` | Yes | — | Identifies which client's projects to load |
 | `apiBase` | `string` | Yes | — | Base URL of the projects API |
-| `filters` | `Record<string, string>` | No | `{}` | Key/value pairs to filter projects by custom field values. All filters must match (AND logic) |
-| `excludeSlug` | `string` | No | — | Slug of a project to exclude from results (e.g. the current project) |
+| `apiKey` | `string` | Yes | — | Client API key — always pass via environment variable, never hardcode |
+| `filters` | `Record<string, string>` | No | `{}` | Key/value pairs to filter by. All filters must match (AND logic) |
+| `excludeSlug` | `string` | No | — | Project slug to exclude from results |
 | `basePath` | `string` | No | `"/projects"` | Base path for project detail links |
-| `projectSlugs` | `string[]` | No | — | Explicit list of project slugs to show, in order. When provided, overrides `filters` entirely. e.g. `["jacob-javits", "tillamook-bay"]` |
+| `projectSlugs` | `string[]` | No | — | Explicit ordered list of slugs to show. Overrides `filters` when provided |
 | `maxItems` | `number` | No | `3` | Maximum number of projects to show |
-| `title` | `string` | No | `"Similar Projects"` | Heading text for the section. e.g. `"Featured Projects"` |
-| `subtitle` | `string` | No | `"More Work"` | Small uppercase label above the heading. e.g. `"Our Work"` |
-| `variant` | `"list" \| "card"` | No | `"list"` | `"list"` uses the border-bottom separator style; `"card"` renders full baseball-card style matching `ProjectPortfolio` |
-| `font` | `string` | No | System font stack | Font family string applied to all inline styles |
-| `revalidate` | `number` | No | `86400` | Cache revalidation period in seconds (24 hours) |
-| `noCache` | `boolean` | No | `false` | Bypasses the Next.js Data Cache and sets `cache: "no-store"`. Useful during development or for frequently updated projects. |
+| `title` | `string` | No | `"Similar Projects"` | Section heading |
+| `subtitle` | `string` | No | `"More Work"` | Small uppercase label above the heading |
+| `variant` | `"list" \| "card"` | No | `"list"` | Display style |
+| `font` | `string` | No | System font stack | Font family string |
+| `revalidate` | `number` | No | `86400` | Cache revalidation period in seconds |
+| `noCache` | `boolean` | No | `false` | Sets `cache: "no-store"` — useful during development |
 
 ---
 
 ### `ProjectMenu`
 
-A server-rendered megamenu component. Shows featured projects as compact cards on the left and "Browse By" filter links on the right. Designed to be dropped directly into a navigation dropdown.
+Server component. Megamenu that shows featured projects as compact cards on the left and "Browse By" filter links on the right. Drop it directly into a navigation dropdown.
 
 ```tsx
-// components/MegaMenu.tsx
+// components/MegaMenu.tsx — must be a Server Component
 import { ProjectMenu } from "@chiselandco/nexus"
 
-// Must be a Server Component — do NOT add "use client"
 export async function ProjectsMegaMenu() {
   return (
     <ProjectMenu
       clientSlug="your-client-slug"
       apiBase="https://your-api.com"
+      apiKey={process.env.YOUR_CLIENT_API_KEY!}
       basePath="/projects"
+      viewAllPath="/projects"
       subtitle="Our systems are installed in every geographic region of the U.S."
       maxProjects={6}
     />
@@ -467,14 +427,13 @@ export async function ProjectsMegaMenu() {
 }
 ```
 
-#### With a curated menu
-
-Pass `menuId` to show a specific curated set of projects instead of all projects. The value should be the menu **slug** (not the UUID) — available slugs can be retrieved from `GET /api/v1/clients/{clientSlug}/menus`. The Browse By filters on the right always reflect the full schema regardless of which menu is active.
+Pass `menuId` to show a specific curated set of projects instead of all projects:
 
 ```tsx
 <ProjectMenu
   clientSlug="your-client-slug"
   apiBase="https://your-api.com"
+  apiKey={process.env.YOUR_CLIENT_API_KEY!}
   menuId="main-nav"
   basePath="/projects"
 />
@@ -484,28 +443,25 @@ Pass `menuId` to show a specific curated set of projects instead of all projects
 |---|---|---|---|---|
 | `clientSlug` | `string` | Yes | — | Identifies which client's projects to load |
 | `apiBase` | `string` | Yes | — | Base URL of the projects API |
-| `menuId` | `string` | No | — | Slug of a curated menu. When provided, fetches from `/menus/{slug}` instead of all projects. Filters always shown regardless. |
+| `apiKey` | `string` | Yes | — | Client API key — always pass via environment variable, never hardcode |
+| `menuId` | `string` | No | — | Slug of a curated menu. When provided fetches from `/menus/{slug}`. Browse By filters always reflect the full schema. |
 | `basePath` | `string` | No | `"/projects"` | Base path for project detail links |
 | `viewAllPath` | `string` | No | Same as `basePath` | Path for the "View All Projects" link |
-| `subtitle` | `string` | No | — | Description paragraph shown above the project cards |
-| `font` | `string` | No | System font stack | Font family string applied to all inline styles |
+| `subtitle` | `string` | No | — | Description shown above the project cards |
+| `font` | `string` | No | System font stack | Font family string |
 | `maxProjects` | `number` | No | `6` | Maximum number of projects to display |
-| `revalidate` | `number` | No | `86400` | Cache revalidation period in seconds (24 hours) |
-| `noCache` | `boolean` | No | `false` | Bypasses the Next.js Data Cache and sets `cache: "no-store"`. Useful during development or for frequently updated projects. |
+| `revalidate` | `number` | No | `86400` | Cache revalidation period in seconds |
+| `noCache` | `boolean` | No | `false` | Sets `cache: "no-store"` — useful during development |
 
 ---
 
 ### `ProjectMenuClient` + `createMenuHandler`
 
-`ProjectMenuClient` is a `"use client"` megamenu component. Use it when your nav or header is a client component. It fetches and caches data on first mount so the API is never called twice on re-hover or remount.
+Client component (`"use client"`). Use when your nav or header is a client component. Fetches and caches data on first mount — the API is never called twice on re-hover or remount.
 
-There are two ways to set it up:
+#### Option 1 — `dataUrl` + `createMenuHandler` (recommended)
 
----
-
-#### Option 1 — `dataUrl` + `createMenuHandler` (recommended for production)
-
-Create one API route once. The data is server-cached for 24 hours — most users never trigger a call to the upstream API at all.
+Create one API route. Data is server-cached for 24 hours.
 
 ```ts
 // app/api/chisel-menu/route.ts
@@ -514,22 +470,10 @@ import { createMenuHandler } from "@chiselandco/nexus"
 export const GET = createMenuHandler({
   clientSlug: "your-client-slug",
   apiBase: "https://your-api.com",
+  apiKey: process.env.YOUR_CLIENT_API_KEY!,
 })
 ```
 
-For a curated menu, pass `menuId` to the handler:
-
-```ts
-// app/api/chisel-menu/route.ts
-export const GET = createMenuHandler({
-  clientSlug: "your-client-slug",
-  apiBase: "https://your-api.com",
-  menuId: "main-nav",
-})
-```
-
-Then pass `dataUrl` to the component:
-
 ```tsx
 // components/Nav.tsx
 "use client"
@@ -541,18 +485,16 @@ export function Nav() {
       dataUrl="/api/chisel-menu"
       basePath="/projects"
       viewAllPath="/projects"
-      subtitle="Explore our portfolio of projects."
+      subtitle="Explore our portfolio."
       maxProjects={6}
     />
   )
 }
 ```
 
----
-
-#### Option 2 — Direct fetch (quick setup / non-Next.js environments)
+#### Option 2 — Direct fetch (quick setup)
 
-No API route needed. The component fetches directly from the upstream API on first mount and caches the result in memory for the session. Note: this exposes the API call to the client browser.
+No API route needed. The component fetches directly from the upstream API on first mount. Note: this exposes the API call to the client browser.
 
 ```tsx
 "use client"
@@ -563,6 +505,7 @@ export function Nav() {
     <ProjectMenuClient
       clientSlug="your-client-slug"
       apiBase="https://your-api.com"
+      apiKey={process.env.YOUR_CLIENT_API_KEY!}
       basePath="/projects"
       viewAllPath="/projects"
     />
@@ -570,101 +513,146 @@ export function Nav() {
 }
 ```
 
-With a curated menu:
-
-```tsx
-<ProjectMenuClient
-  clientSlug="your-client-slug"
-  apiBase="https://your-api.com"
-  menuId="main-nav"
-  basePath="/projects"
-  viewAllPath="/projects"
-/>
-```
-
----
-
 | Prop | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `dataUrl` | `string` | No* | — | URL of a local API route created with `createMenuHandler()`. Recommended for production |
+| `dataUrl` | `string` | No* | — | URL of a local API route created with `createMenuHandler()` — recommended for production |
 | `clientSlug` | `string` | No* | — | Client slug for direct fetch mode |
 | `apiBase` | `string` | No* | — | API base URL for direct fetch mode |
-| `menuId` | `string` | No | — | Slug of a curated menu. Fetches from `/menus/{slug}` for projects. Filters are always shown regardless. |
-| `noCache` | `boolean` | No | `false` | Bypasses the module-level data cache and sets `cache: "no-store"` on all fetch calls. Useful during development or when projects update frequently. |
+| `apiKey` | `string` | No* | — | Client API key for direct fetch mode |
+| `menuId` | `string` | No | — | Slug of a curated menu |
 | `basePath` | `string` | Yes | — | Base path for project detail links |
 | `viewAllPath` | `string` | Yes | — | Path for the "View All Projects" link |
-| `subtitle` | `string` | No | — | Description shown above the project cards (hidden on mobile) |
+| `subtitle` | `string` | No | — | Description shown above the project cards |
 | `font` | `string` | No | System font stack | Font family string |
-| `maxProjects` | `number` | No | `6` | Maximum number of projects to display (capped at 3 on mobile) |
+| `maxProjects` | `number` | No | `6` | Maximum number of projects to display |
+| `noCache` | `boolean` | No | `false` | Bypasses the module-level data cache |
 
-*One of `dataUrl` or `clientSlug + apiBase` must be provided.
+*One of `dataUrl` or `clientSlug + apiBase + apiKey` must be provided.
 
 ---
 
-## Server vs Client Components
+### `ProjectPortfolio`
 
-All top-level components except `ProjectMenuClient`, `ProjectPortfolioClient`, and `GalleryCarousel` are **async Server Components**. They must be rendered in a server context:
+Server component. Fetches all projects and renders a responsive baseball card grid (1 col mobile / 2 col tablet / 3 col desktop). Supports URL-driven filtering via `searchParams`. Prefer `FilteredPortfolio` for new projects — it includes the full filter sidebar and is the recommended default.
 
 ```tsx
-// CORRECT
-export default async function Page() {
-  return <ProjectPortfolio clientSlug="..." apiBase="..." />
+// app/projects/page.tsx
+import { ProjectPortfolio } from "@chiselandco/nexus"
+
+export default async function ProjectsPage({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}) {
+  return (
+    <ProjectPortfolio
+      clientSlug="your-client-slug"
+      apiBase="https://your-api.com"
+      apiKey={process.env.YOUR_CLIENT_API_KEY!}
+      basePath="/projects"
+      searchParams={await searchParams}
+    />
+  )
 }
+```
 
-// WRONG — causes a runtime error
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `clientSlug` | `string` | Yes | — | Identifies which client's projects to load |
+| `apiBase` | `string` | Yes | — | Base URL of the projects API |
+| `apiKey` | `string` | Yes | — | Client API key — always pass via environment variable, never hardcode |
+| `basePath` | `string` | No | `"/projects"` | Base path for project detail links |
+| `searchParams` | `Record<string, string \| string[] \| undefined>` | No | `{}` | Filter params — pass Next.js `searchParams` directly |
+| `revalidate` | `number` | No | `86400` | Cache revalidation period in seconds |
+| `noCache` | `boolean` | No | `false` | Sets `cache: "no-store"` — useful during development |
+
+---
+
+### `ProjectPortfolioClient`
+
+Client component (`"use client"`). Same grid as `ProjectPortfolio` but renders client-side. Fetches all projects once on mount (module-level cached). Use this inside a client component tree or when you want to build a custom filter UI that filters in memory.
+
+```tsx
 "use client"
-export default function Page() {
-  return <ProjectPortfolio clientSlug="..." apiBase="..." />
+import { useState } from "react"
+import { ProjectPortfolioClient } from "@chiselandco/nexus"
+
+export default function ProjectsPage() {
+  const [filters, setFilters] = useState<Record<string, string>>({})
+
+  return (
+    <>
+      <select onChange={(e) => setFilters({ type: e.target.value })}>
+        <option value="">All Types</option>
+        <option value="commercial">Commercial</option>
+      </select>
+      <ProjectPortfolioClient
+        clientSlug="your-client-slug"
+        apiBase="https://your-api.com"
+        apiKey={process.env.YOUR_CLIENT_API_KEY!}
+        basePath="/projects"
+        filters={filters}
+      />
+    </>
+  )
 }
 ```
 
-If your parent component uses `"use client"`, use the client variants instead (`ProjectMenuClient`, `ProjectPortfolioClient`) or pass the server components as `children` from a server parent.
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `clientSlug` | `string` | Yes | — | Identifies which client's projects to load |
+| `apiBase` | `string` | Yes | — | Base URL of the projects API |
+| `apiKey` | `string` | Yes | — | Client API key — always pass via environment variable, never hardcode |
+| `basePath` | `string` | No | `"/projects"` | Base path for project detail links |
+| `filters` | `Record<string, string>` | No | `{}` | Active filters — filtering is instant, no API call on change |
+| `columns` | `2 \| 3` | No | `3` | Number of grid columns |
+| `font` | `string` | No | System font stack | Font family string |
 
-| Component | Type | Use when |
+---
+
+## Server vs Client components
+
+| Component | Type | Notes |
 |---|---|---|
-| `ProjectPortfolio` | Server | Page-level grid, URL-driven filters |
-| `ProjectPortfolioClient` | Client | Inside a client tree, custom filter UI |
-| `ProjectDetail` | Server | Project detail page |
-| `GalleryCarousel` | Client | Standalone image gallery |
-| `ProjectMenu` | Server | Server-rendered nav dropdown |
-| `ProjectMenuClient` | Client | Client-rendered nav/header |
+| `FilteredPortfolio` | Server | Recommended default for project grids |
+| `FilterSidebar` | Client | Used internally by `FilteredPortfolio` |
+| `ProjectPortfolio` | Server | Simpler grid without sidebar |
+| `ProjectPortfolioClient` | Client | For use inside client trees |
+| `ProjectDetail` | Server | Full project detail page |
+| `GalleryCarousel` | Client | Used internally by `ProjectDetail` |
 | `SimilarProjects` | Server | After `ProjectDetail` on detail pages |
+| `ProjectMenu` | Server | Server-rendered nav megamenu |
+| `ProjectMenuClient` | Client | Client-rendered nav megamenu |
+
+All server components must be rendered in a server context. If your parent component uses `"use client"`, use the client variants or pass server components as `children` from a server parent.
 
 ---
 
 ## Caching
 
-| Component | Server Cache | Client Cache |
+| Component | Server cache | Client cache |
 |---|---|---|
-| `ProjectMenu` (RSC) | 24h via `next.revalidate` | — |
+| `FilteredPortfolio` | 24h via `next.revalidate` | — |
+| `ProjectPortfolio` | 24h via `next.revalidate` | — |
+| `ProjectDetail` | 24h via `next.revalidate` | — |
+| `SimilarProjects` | 24h via `next.revalidate` | — |
+| `ProjectMenu` | 24h via `next.revalidate` | — |
 | `ProjectMenuClient` + `createMenuHandler` | 24h (route handler) | Per-session module cache |
 | `ProjectMenuClient` (direct fetch) | None | Per-session module cache |
-| `ProjectPortfolio` (RSC) | 24h via `next.revalidate` | — |
 | `ProjectPortfolioClient` | None | Per-session module cache |
-| `ProjectDetail` (RSC) | 24h via `next.revalidate` | — |
-| `SimilarProjects` (RSC) | 24h via `next.revalidate` | — |
 
-#### Bypassing the cache
-
-| Method | Scope | Use case |
-|---|---|---|
-| `?bust=1` on `/api/chisel-menu` | Single request | Dev/testing after a CMS change |
-| `CHISEL_CACHE_BYPASS=true` env var | Entire deployment | Staging environments |
-| `revalidateTag("chisel-menu-{clientSlug}")` | Server cache | CMS webhook on content publish |
-| `noCache: true` on `ProjectMenu` | Single render | Debug during development |
+Pass `noCache={true}` on any server component to bypass the cache during development. To invalidate the server cache from a CMS webhook:
 
 ```ts
-// CMS webhook — invalidate server cache on publish
 import { revalidateTag } from "next/cache"
 revalidateTag("chisel-menu-your-client-slug")
-
-// For a curated menu, the tag includes the menuId
+// For a curated menu:
 revalidateTag("chisel-menu-your-client-slug-main-nav")
 ```
 
 ---
 
-## Publishing to npm
+## Publishing
 
 ```bash
 npm login