project-portfolio 2.0.1 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # project-portfolio
 
-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 on the server with zero client-side waterfall requests.
+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.
 
 ## Requirements
 
@@ -17,39 +17,97 @@ npm install project-portfolio
 
 ---
 
-## Components
-
-### `ProjectPortfolio`
+## Quick Start
 
-A full project grid page. Fetches all projects for a client and renders them as responsive cards (1 column on mobile, 2 on tablet, 3 on desktop).
+Here is the most common full setup — a projects grid page, a detail page with similar projects, and a megamenu in the nav.
 
 ```tsx
 // app/projects/page.tsx
 import { ProjectPortfolio } from "project-portfolio"
 
-// Must be a Server Component — do NOT add "use client"
-export default async function ProjectsPage() {
+export default async function ProjectsPage({
+  searchParams,
+}: {
+  searchParams: { [key: string]: string | string[] | undefined }
+}) {
   return (
     <ProjectPortfolio
       clientSlug="your-client-slug"
       apiBase="https://your-api.com"
       basePath="/projects"
+      searchParams={searchParams}
     />
   )
 }
 ```
 
-| 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) |
+```tsx
+// app/projects/[slug]/page.tsx
+import { ProjectDetail, SimilarProjects } from "project-portfolio"
+
+export default async function ProjectPage({ params }: { params: { slug: string } }) {
+  return (
+    <>
+      <ProjectDetail
+        slug={params.slug}
+        clientSlug="your-client-slug"
+        apiBase="https://your-api.com"
+        backPath="/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}
+        clientSlug="your-client-slug"
+        apiBase="https://your-api.com"
+        basePath="/projects"
+      />
+    </>
+  )
+}
+```
 
-#### URL-driven filter integration
+```ts
+// app/api/chisel-menu/route.ts
+import { createMenuHandler } from "project-portfolio"
 
-`ProjectPortfolio` works together with `ProjectMenu` to form a complete filter flow. When a user clicks a filter link in the megamenu, they are navigated to the project grid with filter query params appended to the URL. Pass Next.js `searchParams` to `ProjectPortfolio` so it can forward them to the API:
+export const GET = createMenuHandler({
+  clientSlug: "your-client-slug",
+  apiBase: "https://your-api.com",
+})
+```
+
+```tsx
+// components/Nav.tsx — "use client" component in your header
+"use client"
+import { ProjectMenuClient } from "project-portfolio"
+
+export function Nav() {
+  return (
+    <nav>
+      {/* ... other nav items ... */}
+      <ProjectMenuClient
+        dataUrl="/api/chisel-menu"
+        basePath="/projects"
+        viewAllPath="/projects"
+      />
+    </nav>
+  )
+}
+```
+
+---
+
+## Components
+
+### `ProjectPortfolio`
+
+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`.
 
 ```tsx
 // app/projects/page.tsx
@@ -71,12 +129,23 @@ 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
+
+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.
+
 Filter URLs follow this pattern — the key matches the custom field key in the schema:
 
 ```
-/projects?type=commercial
-/projects?type=educational-facilities
-/projects?system=spacematic
+/projects?filter[type]=commercial
+/projects?filter[type]=educational-facilities
 ```
 
 When active filters are applied, a filter banner is shown above the grid with a "Clear filters" link back to `basePath`.
@@ -85,7 +154,7 @@ When active filters are applied, a filter banner is shown above the grid with a
 
 ### `ProjectPortfolioClient`
 
-A `"use client"` component that fetches all projects once on mount (module-level cached — no re-fetch on remount) and filters them locally in memory. It ships with **no filter UI** — build your own dropdowns, buttons, or search inputs and drive the component with the `filters` prop.
+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
@@ -102,7 +171,9 @@ export default function ProjectsPage() {
 }
 ```
 
-Wire up your own filter UI with the `filters` prop:
+#### With a custom filter UI
+
+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.
 
 ```tsx
 "use client"
@@ -121,7 +192,6 @@ export default function ProjectsPage() {
         <option value="educational-facilities">Educational</option>
       </select>
 
-      {/* Component receives filters and applies them in memory */}
       <ProjectPortfolioClient
         clientSlug="your-client-slug"
         apiBase="https://your-api.com"
@@ -142,19 +212,16 @@ export default function ProjectsPage() {
 | `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 |
 
-**How filtering works:** Pass any `Record<string, string>` of field key/value pairs and the component filters the already-fetched project list in memory. All filter logic uses AND matching with case-insensitive comparison. The field keys must match the custom field keys in the API schema.
-
 ---
 
 ### `ProjectDetail`
 
-A full project detail page. Fetches a single project by slug and renders its gallery, custom fields, related projects, and a back link.
+A full server-rendered project detail page. Fetches a single project by slug and renders its image gallery, custom fields, and a back link.
 
 ```tsx
 // app/projects/[slug]/page.tsx
 import { ProjectDetail } from "project-portfolio"
 
-// Must be a Server Component — do NOT add "use client"
 export default async function ProjectPage({ params }: { params: { slug: string } }) {
   return (
     <ProjectDetail
@@ -179,47 +246,48 @@ export default async function ProjectPage({ params }: { params: { slug: string }
 
 ---
 
-### `ProjectMenu`
+### `GalleryCarousel`
 
-A compact megamenu component. Shows featured projects as list-style cards on the left and "Browse By" filter links on the right. Designed to be dropped directly into a navigation megamenu dropdown.
+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.
 
 ```tsx
-// components/navigation/MegaMenu.tsx
-import { ProjectMenu } from "project-portfolio"
+"use client"
+import { GalleryCarousel } from "project-portfolio"
 
-// Must be a Server Component — do NOT add "use client"
-export async function ProjectsMegaMenu() {
+// `media` is the array of image objects returned by the projects API
+export function ProjectGallery({ media, title }: { media: Media[]; title: string }) {
   return (
-    <ProjectMenu
-      clientSlug="your-client-slug"
-      apiBase="https://your-api.com"
-      basePath="/projects"
-      subtitle="Our systems are installed in every geographic region of the U.S. and in a variety of applications."
-      maxProjects={6}
+    <GalleryCarousel
+      images={media}
+      projectTitle={title}
     />
   )
 }
 ```
 
+The parent component is responsible for injecting the `.chisel-gallery-main-img` CSS class to control the main image height:
+
+```css
+.chisel-gallery-main-img {
+  height: 400px; /* adjust to your layout */
+}
+@media (min-width: 768px) {
+  .chisel-gallery-main-img {
+    height: 560px;
+  }
+}
+```
+
 | 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 |
-| `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 |
-| `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` | Disable caching entirely — useful for development |
-
-The filter options in the right sidebar are driven automatically by the `is_filterable` fields returned from the API schema — no manual configuration needed.
+| `images` | `Media[]` | Yes | — | Array of media objects from the projects API |
+| `projectTitle` | `string` | Yes | — | Used as the alt text fallback for the main image |
 
 ---
 
 ### `SimilarProjects`
 
-A standalone similar projects section. Fetches all projects for a client, filters to the same type as the current project, and renders up to 3 matching cards. Designed to be placed after `ProjectDetail` on a project detail page.
+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.
 
 ```tsx
 // app/projects/[slug]/page.tsx
@@ -245,32 +313,176 @@ export default async function ProjectPage({ params }: { params: { slug: string }
 }
 ```
 
-`filters` accepts any combination of custom field key/value pairs — all must match (AND logic). `excludeSlug` optionally removes the current project from results.
+#### Deriving filters from the current project
+
+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:
+
+```tsx
+// app/projects/[slug]/page.tsx
+import { ProjectDetail, SimilarProjects } from "project-portfolio"
+
+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
+}
+
+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"
+        />
+      )}
+    </>
+  )
+}
+```
+
+#### Manually specifying projects (recommended for quick setup)
+
+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.
+
+```tsx
+// app/projects/[slug]/page.tsx
+import { ProjectDetail, SimilarProjects } from "project-portfolio"
+
+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"
+      />
+    </>
+  )
+}
+```
+
+> `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:
+
+```tsx
+<SimilarProjects
+  filters={{ type: "commercial" }}
+  excludeSlug={params.slug}
+  clientSlug="your-client-slug"
+  apiBase="https://your-api.com"
+  basePath="/projects"
+  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) |
+| `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"]` |
+| `maxItems` | `number` | No | `3` | Maximum number of projects to show |
+| `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) |
+
+---
+
+### `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.
+
+```tsx
+// components/MegaMenu.tsx
+import { ProjectMenu } from "project-portfolio"
+
+// 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"
+      basePath="/projects"
+      subtitle="Our systems are installed in every geographic region of the U.S."
+      maxProjects={6}
+    />
+  )
+}
+```
+
+#### With a curated menu
+
+Pass `menuId` to show a specific curated set of projects instead of all projects. The Browse By filters on the right always reflect the full schema regardless of which menu is active. Available menu IDs can be retrieved from `GET /api/v1/clients/{clientSlug}/menus`.
+
+```tsx
+<ProjectMenu
+  clientSlug="your-client-slug"
+  apiBase="https://your-api.com"
+  menuId="main-nav"
+  basePath="/projects"
+/>
+```
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
 | `clientSlug` | `string` | Yes | — | Identifies which client's projects to load |
 | `apiBase` | `string` | Yes | — | Base URL of the projects API |
+| `menuId` | `string` | No | — | ID of a curated menu. When provided, fetches from `/menus/{menuId}` instead of all projects. Filters always shown regardless. |
 | `basePath` | `string` | No | `"/projects"` | Base path for project detail links |
-| `maxItems` | `number` | No | `3` | Maximum number of projects to show |
+| `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 |
-| `revalidate` | `number` | No | `60` | Cache revalidation period in seconds |
+| `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` | Disable caching entirely — useful for development |
 
 ---
 
 ### `ProjectMenuClient` + `createMenuHandler`
 
-`ProjectMenuClient` is a `"use client"` component that works in any React tree — no RSC, no `Suspense` wrapper, no server file needed. It fetches its own data and caches it in memory for the lifetime of the page session so the API is never called twice on a hover/re-hover.
+`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.
 
-There are two ways to use it:
+There are two ways to set it up:
 
 ---
 
-**Option 1 — `dataUrl` + `createMenuHandler` (recommended for production)**
+#### Option 1 — `dataUrl` + `createMenuHandler` (recommended for production)
 
-Set up 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 once. The data is server-cached for 24 hours — most users never trigger a call to the upstream API at all.
 
 ```ts
 // app/api/chisel-menu/route.ts
@@ -282,29 +494,66 @@ export const GET = createMenuHandler({
 })
 ```
 
+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
-// In your nav/header — works in any "use client" component
+// components/Nav.tsx
+"use client"
 import { ProjectMenuClient } from "project-portfolio"
 
-<ProjectMenuClient
-  dataUrl="/api/chisel-menu"
-  basePath="/projects"
-  viewAllPath="/projects"
-/>
+export function Nav() {
+  return (
+    <ProjectMenuClient
+      dataUrl="/api/chisel-menu"
+      basePath="/projects"
+      viewAllPath="/projects"
+      subtitle="Explore our portfolio of projects."
+      maxProjects={6}
+    />
+  )
+}
 ```
 
 ---
 
-**Option 2 — Direct fetch (quick setup / non-Next.js environments)**
+#### Option 2 — Direct fetch (quick setup / non-Next.js environments)
 
-No API route needed. The component fetches directly from the upstream API on first mount and caches the result in memory for the session.
+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.
 
 ```tsx
+"use client"
 import { ProjectMenuClient } from "project-portfolio"
 
+export function Nav() {
+  return (
+    <ProjectMenuClient
+      clientSlug="your-client-slug"
+      apiBase="https://your-api.com"
+      basePath="/projects"
+      viewAllPath="/projects"
+    />
+  )
+}
+```
+
+With a curated menu:
+
+```tsx
 <ProjectMenuClient
   clientSlug="your-client-slug"
   apiBase="https://your-api.com"
+  menuId="main-nav"
   basePath="/projects"
   viewAllPath="/projects"
 />
@@ -314,22 +563,23 @@ import { ProjectMenuClient } from "project-portfolio"
 
 | 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 | — | ID of a curated menu. Fetches from `/menus/{menuId}` for projects. Filters are always shown regardless. |
 | `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) |
 | `font` | `string` | No | System font stack | Font family string |
 | `maxProjects` | `number` | No | `6` | Maximum number of projects to display (capped at 3 on mobile) |
 
-*One of `dataUrl` or `clientSlug + apiBase` must be provided. Pre-fetched `projects`, `schema`, `filterOptions`, `filterFieldKey`, and `fieldOptionsMap` can also be passed directly for SSR usage.
+*One of `dataUrl` or `clientSlug + apiBase` must be provided.
 
 ---
 
-## Important: Server Component Usage
+## Server vs Client Components
 
-All top-level components (`ProjectPortfolio`, `ProjectDetail`, `ProjectMenu`, `SimilarProjects`) are **async Server Components**. They must be rendered in a server context:
+All top-level components except `ProjectMenuClient`, `ProjectPortfolioClient`, and `GalleryCarousel` are **async Server Components**. They must be rendered in a server context:
 
 ```tsx
 // CORRECT
@@ -337,58 +587,63 @@ export default async function Page() {
   return <ProjectPortfolio clientSlug="..." apiBase="..." />
 }
 
-// WRONG — causes infinite client-side fetch loop
+// WRONG — causes a runtime error
 "use client"
 export default function Page() {
   return <ProjectPortfolio clientSlug="..." apiBase="..." />
 }
 ```
 
-If a parent component uses `"use client"`, these components cannot be rendered inside it directly. Pass them as children from a server component instead.
+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.
+
+| Component | Type | Use when |
+|---|---|---|
+| `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 |
+| `SimilarProjects` | Server | After `ProjectDetail` on detail pages |
 
 ---
 
 ## Caching
 
-Data is cached at multiple levels depending on which component is used.
-
-**Server Components (`ProjectMenu`, `ProjectPortfolio`, `ProjectDetail`, `SimilarProjects`)**
-1. **Per-render** — `React.cache()` deduplicates duplicate calls within the same render pass
-2. **Cross-request** — `next: { revalidate: 86400 }` (24 hours) caches responses in Next.js's Data Cache across all users and sessions
-
-**`ProjectMenuClient` with `createMenuHandler` (recommended)**
-3. **Server-side route cache** — the `/api/chisel-menu` route is cached by Next.js for 24 hours. The upstream API is called at most once per day regardless of traffic
-4. **Module-level client cache** — after the first fetch within a session, the result is held in memory. Re-hovering the menu or remounting the component never triggers another network request
-
-**`ProjectMenuClient` with direct fetch / `ProjectPortfolioClient`**
-4. **Module-level client cache only** — the upstream API is called once per session per user (on first mount), then cached in memory for the rest of that page session. Filter changes on `ProjectPortfolioClient` never trigger a fetch — filtering is done entirely in memory
+| Component | Server Cache | Client Cache |
+|---|---|---|
+| `ProjectMenu` (RSC) | 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**
+#### 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 only | CMS webhook on content publish |
+| `revalidateTag("chisel-menu-{clientSlug}")` | Server cache | CMS webhook on content publish |
 | `noCache: true` on `ProjectMenu` | Single render | Debug during development |
 
 ```ts
-// CMS webhook example — invalidate server cache immediately on publish
+// CMS webhook — invalidate server cache on publish
 import { revalidateTag } from "next/cache"
 revalidateTag("chisel-menu-your-client-slug")
-```
 
-No third-party caching libraries are required.
+// For a curated menu, the tag includes the menuId
+revalidateTag("chisel-menu-your-client-slug-main-nav")
+```
 
 ---
 
 ## Publishing to npm
 
 ```bash
-# Log in to npm
 npm login
-
-# Build and publish
 cd package
 npm run build
 npm publish --access public

package/dist/ProjectMenu.d.ts

@@ -4,6 +4,11 @@ export interface ProjectMenuProps {
     clientSlug: string;
     /** API base URL e.g. "https://nexus.chiselandco.com" */
     apiBase: string;
+    /**
+     * Optional menu ID to fetch a specific curated menu instead of all projects.
+     * When provided, fetches from /api/v1/clients/{clientSlug}/menus/{menuId}
+     */
+    menuId?: string;
     /** Base path for project detail links. Defaults to "/projects" */
     basePath?: string;
     /** Path for the "View All" link. Defaults to basePath */
@@ -46,14 +51,17 @@ export interface ProjectMenuProps {
  * import { revalidateTag } from "next/cache"
  * revalidateTag("chisel-menu-my-client")
  */
-export declare function createMenuHandler({ clientSlug, apiBase, revalidate, }: {
+export declare function createMenuHandler({ clientSlug, apiBase, menuId, revalidate, }: {
     clientSlug: string;
     apiBase: string;
+    /** Optional menu ID to fetch a specific curated menu instead of all projects */
+    menuId?: string;
     revalidate?: number;
 }): (request: Request) => Promise<Response>;
-export declare function fetchProjectMenuData({ apiBase, clientSlug, revalidate, noCache, }: {
+export declare function fetchProjectMenuData({ apiBase, clientSlug, menuId, revalidate, noCache, }: {
     apiBase: string;
     clientSlug: string;
+    menuId?: string;
     revalidate?: number;
     noCache?: boolean;
 }): Promise<{
@@ -67,5 +75,5 @@ export declare function fetchProjectMenuData({ apiBase, clientSlug, revalidate,
     filterFieldName: string;
     fieldOptionsMap: Record<string, Record<string, string>>;
 }>;
-export declare function ProjectMenu({ clientSlug, apiBase, basePath, viewAllPath, subtitle, font, maxProjects, revalidate, noCache, }: ProjectMenuProps): Promise<import("react/jsx-runtime").JSX.Element>;
+export declare function ProjectMenu({ clientSlug, apiBase, menuId, basePath, viewAllPath, subtitle, font, maxProjects, revalidate, noCache, }: ProjectMenuProps): Promise<import("react/jsx-runtime").JSX.Element>;
 //# sourceMappingURL=ProjectMenu.d.ts.map

package/dist/ProjectMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectMenu.d.ts","sourceRoot":"","sources":["../src/ProjectMenu.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAKzD,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,UAAU,EACV,OAAO,EACP,UAAkB,GACnB,EAAE;IACD,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,aACoC,OAAO,uBAsD3C;AAED,wBAAsB,oBAAoB,CAAC,EACzC,OAAO,EACP,UAAU,EACV,UAAkB,EAClB,OAAe,GAChB,EAAE;IACD,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,GAAG,OAAO,CAAC;IACV,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,MAAM,EAAE,iBAAiB,EAAE,CAAA;IAC3B,aAAa,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC9C,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,eAAe,EAAE,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACxD,CAAC,CAqBD;AA6CD,wBAAsB,WAAW,CAAC,EAChC,UAAU,EACV,OAAO,EACP,QAAsB,EACtB,WAAW,EACX,QAAQ,EACR,IAA0E,EAC1E,WAAe,EACf,UAAkB,EAClB,OAAe,GAChB,EAAE,gBAAgB,oDAiClB"}
+{"version":3,"file":"ProjectMenu.d.ts","sourceRoot":"","sources":["../src/ProjectMenu.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAKzD,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,UAAU,EACV,OAAO,EACP,MAAM,EACN,UAAkB,GACnB,EAAE;IACD,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,aACoC,OAAO,uBAsE3C;AAED,wBAAsB,oBAAoB,CAAC,EACzC,OAAO,EACP,UAAU,EACV,MAAM,EACN,UAAkB,EAClB,OAAe,GAChB,EAAE;IACD,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,GAAG,OAAO,CAAC;IACV,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,MAAM,EAAE,iBAAiB,EAAE,CAAA;IAC3B,aAAa,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC9C,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,eAAe,EAAE,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACxD,CAAC,CAqBD;AA8DD,wBAAsB,WAAW,CAAC,EAChC,UAAU,EACV,OAAO,EACP,MAAM,EACN,QAAsB,EACtB,WAAW,EACX,QAAQ,EACR,IAA0E,EAC1E,WAAe,EACf,UAAkB,EAClB,OAAe,GAChB,EAAE,gBAAgB,oDAiClB"}

package/dist/ProjectMenu.js

@@ -26,27 +26,41 @@ const API_KEY = "pk_live_crmsuTIm7NNfb9uEWBCyv88F6kj2YQUR";
  * import { revalidateTag } from "next/cache"
  * revalidateTag("chisel-menu-my-client")
  */
-export function createMenuHandler({ clientSlug, apiBase, revalidate = 86400, }) {
+export function createMenuHandler({ clientSlug, apiBase, menuId, revalidate = 86400, }) {
     return async function GET(request) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
         const bypass = process.env.CHISEL_CACHE_BYPASS === "true" ||
             new URL(request.url).searchParams.has("bust");
+        const cacheTag = menuId ? `chisel-menu-${clientSlug}-${menuId}` : `chisel-menu-${clientSlug}`;
         const fetchOpts = bypass
             ? { cache: "no-store" }
-            : { next: { revalidate, tags: [`chisel-menu-${clientSlug}`] } };
+            : { next: { revalidate, tags: [cacheTag] } };
         try {
-            const [projectsRes, fieldsRes] = await Promise.all([
+            // Always fetch /projects for schema, and /fields for options
+            // If menuId is provided, also fetch the menu endpoint for curated projects
+            const fetches = [
                 fetch(`${apiBase}/api/v1/clients/${clientSlug}/projects?api_key=${API_KEY}`, fetchOpts),
                 fetch(`${apiBase}/api/v1/clients/${clientSlug}/fields?api_key=${API_KEY}`, fetchOpts),
-            ]);
-            const json = projectsRes.ok ? await projectsRes.json() : {};
-            const projects = (_a = json === null || json === void 0 ? void 0 : json.data) !== null && _a !== void 0 ? _a : [];
-            const schema = (_c = (_b = json === null || json === void 0 ? void 0 : json.client) === null || _b === void 0 ? void 0 : _b.custom_fields_schema) !== null && _c !== void 0 ? _c : [];
+            ];
+            if (menuId) {
+                fetches.push(fetch(`${apiBase}/api/v1/clients/${clientSlug}/menus/${menuId}?api_key=${API_KEY}`, fetchOpts));
+            }
+            const responses = await Promise.all(fetches);
+            const [projectsRes, fieldsRes] = responses;
+            const menuRes = menuId ? responses[2] : null;
+            const projectsJson = projectsRes.ok ? await projectsRes.json() : {};
+            const menuJson = menuRes && menuRes.ok ? await menuRes.json() : null;
+            // If menuId provided, use menu projects; otherwise use all projects
+            const projects = menuJson
+                ? ((_b = (_a = menuJson.projects) !== null && _a !== void 0 ? _a : menuJson.data) !== null && _b !== void 0 ? _b : [])
+                : ((_c = projectsJson === null || projectsJson === void 0 ? void 0 : projectsJson.data) !== null && _c !== void 0 ? _c : []);
+            // Always get schema from /projects response
+            const schema = (_e = (_d = projectsJson === null || projectsJson === void 0 ? void 0 : projectsJson.client) === null || _d === void 0 ? void 0 : _d.custom_fields_schema) !== null && _e !== void 0 ? _e : [];
             const fieldsJson = fieldsRes.ok ? await fieldsRes.json() : { fields: [] };
             const fieldOptionsMap = {};
-            for (const field of ((_d = fieldsJson.fields) !== null && _d !== void 0 ? _d : [])) {
+            for (const field of ((_f = fieldsJson.fields) !== null && _f !== void 0 ? _f : [])) {
                 const map = {};
-                for (const opt of ((_e = field.options) !== null && _e !== void 0 ? _e : [])) {
+                for (const opt of ((_g = field.options) !== null && _g !== void 0 ? _g : [])) {
                     if (typeof opt === "object" && opt.id && opt.label) {
                         map[opt.id] = opt.label;
                         map[opt.label] = opt.label;
@@ -54,9 +68,9 @@ export function createMenuHandler({ clientSlug, apiBase, revalidate = 86400, })
                 }
                 fieldOptionsMap[field.key] = map;
             }
-            const filterField = (_f = schema.find((f) => f.is_filterable && (f.type === "select" || f.type === "multi-select"))) !== null && _f !== void 0 ? _f : null;
+            const filterField = (_h = schema.find((f) => f.is_filterable && (f.type === "select" || f.type === "multi-select"))) !== null && _h !== void 0 ? _h : null;
             const filterOptions = filterField
-                ? ((_g = filterField.options) !== null && _g !== void 0 ? _g : []).map((opt) => {
+                ? ((_j = filterField.options) !== null && _j !== void 0 ? _j : []).map((opt) => {
                     var _a, _b;
                     if (typeof opt === "string")
                         return { id: opt.toLowerCase().replace(/\s+/g, "-"), label: opt };
@@ -67,19 +81,19 @@ export function createMenuHandler({ clientSlug, apiBase, revalidate = 86400, })
                 projects,
                 schema,
                 filterOptions,
-                filterFieldKey: (_h = filterField === null || filterField === void 0 ? void 0 : filterField.key) !== null && _h !== void 0 ? _h : null,
-                filterFieldName: (_j = filterField === null || filterField === void 0 ? void 0 : filterField.name) !== null && _j !== void 0 ? _j : "Project Type",
+                filterFieldKey: (_k = filterField === null || filterField === void 0 ? void 0 : filterField.key) !== null && _k !== void 0 ? _k : null,
+                filterFieldName: (_l = filterField === null || filterField === void 0 ? void 0 : filterField.name) !== null && _l !== void 0 ? _l : "Project Type",
                 fieldOptionsMap,
             });
         }
-        catch (_k) {
+        catch (_m) {
             return Response.json({ projects: [], schema: [], filterOptions: [], filterFieldKey: null, filterFieldName: "Project Type", fieldOptionsMap: {} }, { status: 500 });
         }
     };
 }
-export async function fetchProjectMenuData({ apiBase, clientSlug, revalidate = 86400, noCache = false, }) {
+export async function fetchProjectMenuData({ apiBase, clientSlug, menuId, revalidate = 86400, noCache = false, }) {
     var _a, _b, _c, _d;
-    const raw = await _fetchMenuData(apiBase, clientSlug, revalidate, noCache);
+    const raw = await _fetchMenuData(apiBase, clientSlug, menuId, revalidate, noCache);
     const filterField = (_a = raw.schema.find((f) => f.is_filterable && (f.type === "select" || f.type === "multi-select"))) !== null && _a !== void 0 ? _a : null;
     const filterOptions = filterField
         ? ((_b = filterField.options) !== null && _b !== void 0 ? _b : []).map((opt) => {
@@ -99,27 +113,40 @@ export async function fetchProjectMenuData({ apiBase, clientSlug, revalidate = 8
         fieldOptionsMap: raw.fieldOptionsMap,
     };
 }
-const _fetchMenuData = cache(async (apiBase, clientSlug, revalidate, noCache = false) => {
-    var _a, _b, _c, _d, _e;
+const _fetchMenuData = cache(async (apiBase, clientSlug, menuId, revalidate, noCache = false) => {
+    var _a, _b, _c, _d, _e, _f, _g;
     const fetchOpts = noCache
         ? { cache: "no-store" }
         : { next: { revalidate } };
     try {
-        const [res, fieldsRes] = await Promise.all([
+        // Always fetch /projects for schema, and /fields for options
+        // If menuId is provided, also fetch the menu endpoint for curated projects
+        const fetches = [
             fetch(`${apiBase}/api/v1/clients/${clientSlug}/projects?api_key=${API_KEY}`, fetchOpts),
             fetch(`${apiBase}/api/v1/clients/${clientSlug}/fields?api_key=${API_KEY}`, fetchOpts),
-        ]);
-        if (!res.ok)
+        ];
+        if (menuId) {
+            fetches.push(fetch(`${apiBase}/api/v1/clients/${clientSlug}/menus/${menuId}?api_key=${API_KEY}`, fetchOpts));
+        }
+        const responses = await Promise.all(fetches);
+        const [projectsRes, fieldsRes] = responses;
+        const menuRes = menuId ? responses[2] : null;
+        if (!projectsRes.ok)
             return { projects: [], schema: [], fieldOptionsMap: {} };
-        const json = await res.json();
-        const projects = (_a = json === null || json === void 0 ? void 0 : json.data) !== null && _a !== void 0 ? _a : [];
-        const schema = (_c = (_b = json === null || json === void 0 ? void 0 : json.client) === null || _b === void 0 ? void 0 : _b.custom_fields_schema) !== null && _c !== void 0 ? _c : [];
+        const projectsJson = await projectsRes.json();
+        const menuJson = menuRes && menuRes.ok ? await menuRes.json() : null;
+        // If menuId provided, use menu projects; otherwise use all projects
+        const projects = menuJson
+            ? ((_b = (_a = menuJson.projects) !== null && _a !== void 0 ? _a : menuJson.data) !== null && _b !== void 0 ? _b : [])
+            : ((_c = projectsJson === null || projectsJson === void 0 ? void 0 : projectsJson.data) !== null && _c !== void 0 ? _c : []);
+        // Always get schema from /projects response
+        const schema = (_e = (_d = projectsJson === null || projectsJson === void 0 ? void 0 : projectsJson.client) === null || _d === void 0 ? void 0 : _d.custom_fields_schema) !== null && _e !== void 0 ? _e : [];
         // Build fieldOptionsMap: { fieldKey: { id: label, label: label } }
         const fieldsJson = fieldsRes.ok ? await fieldsRes.json() : { fields: [] };
         const fieldOptionsMap = {};
-        for (const field of ((_d = fieldsJson.fields) !== null && _d !== void 0 ? _d : [])) {
+        for (const field of ((_f = fieldsJson.fields) !== null && _f !== void 0 ? _f : [])) {
             const map = {};
-            for (const opt of ((_e = field.options) !== null && _e !== void 0 ? _e : [])) {
+            for (const opt of ((_g = field.options) !== null && _g !== void 0 ? _g : [])) {
                 if (typeof opt === "object" && opt.id && opt.label) {
                     map[opt.id] = opt.label;
                     map[opt.label] = opt.label;
@@ -129,13 +156,13 @@ const _fetchMenuData = cache(async (apiBase, clientSlug, revalidate, noCache = f
         }
         return { projects, schema, fieldOptionsMap };
     }
-    catch (_f) {
+    catch (_h) {
         return { projects: [], schema: [], fieldOptionsMap: {} };
     }
 });
-export async function ProjectMenu({ clientSlug, apiBase, basePath = "/projects", viewAllPath, subtitle, font = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif", maxProjects = 6, revalidate = 86400, noCache = false, }) {
+export async function ProjectMenu({ clientSlug, apiBase, menuId, basePath = "/projects", viewAllPath, subtitle, font = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif", maxProjects = 6, revalidate = 86400, noCache = false, }) {
     var _a, _b, _c, _d;
-    const { projects, schema, fieldOptionsMap } = await _fetchMenuData(apiBase, clientSlug, revalidate, noCache);
+    const { projects, schema, fieldOptionsMap } = await _fetchMenuData(apiBase, clientSlug, menuId, revalidate, noCache);
     // Find the filterable select field (badge_overlay is our category field)
     const filterField = (_a = schema.find((f) => f.is_filterable && (f.type === "select" || f.type === "multi-select"))) !== null && _a !== void 0 ? _a : null;
     // Build filter option list from schema

package/dist/ProjectMenuClient.d.ts

@@ -14,6 +14,11 @@ export interface ProjectMenuClientProps {
      */
     clientSlug?: string;
     apiBase?: string;
+    /**
+     * Optional menu ID to fetch a specific curated menu instead of all projects.
+     * When provided, fetches from /api/v1/clients/{clientSlug}/menus/{menuId}
+     */
+    menuId?: string;
     projects?: Project[];
     schema?: CustomFieldSchema[];
     filterOptions?: {
@@ -29,5 +34,5 @@ export interface ProjectMenuClientProps {
     font?: string;
     maxProjects?: number;
 }
-export declare function ProjectMenuClient({ dataUrl, clientSlug, apiBase, projects: projectsProp, schema: schemaProp, filterOptions: filterOptionsProp, filterFieldKey: filterFieldKeyProp, filterFieldName: filterFieldNameProp, fieldOptionsMap: fieldOptionsMapProp, subtitle, basePath, viewAllPath, font, maxProjects, }: ProjectMenuClientProps): import("react/jsx-runtime").JSX.Element;
+export declare function ProjectMenuClient({ dataUrl, clientSlug, apiBase, menuId, projects: projectsProp, schema: schemaProp, filterOptions: filterOptionsProp, filterFieldKey: filterFieldKeyProp, filterFieldName: filterFieldNameProp, fieldOptionsMap: fieldOptionsMapProp, subtitle, basePath, viewAllPath, font, maxProjects, }: ProjectMenuClientProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ProjectMenuClient.d.ts.map

package/dist/ProjectMenuClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectMenuClient.d.ts","sourceRoot":"","sources":["../src/ProjectMenuClient.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAoB,MAAM,SAAS,CAAA;AAa3E,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;IACpB,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC5B,aAAa,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC/C,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAmBD,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,UAAU,EACV,OAAO,EACP,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,iBAAiB,EAChC,cAAc,EAAE,kBAAkB,EAClC,eAAe,EAAE,mBAAoC,EACrD,eAAe,EAAE,mBAAwB,EACzC,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,IAAmB,EACnB,WAAe,GAChB,EAAE,sBAAsB,2CAqcxB"}
+{"version":3,"file":"ProjectMenuClient.d.ts","sourceRoot":"","sources":["../src/ProjectMenuClient.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAoB,MAAM,SAAS,CAAA;AAa3E,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;IACpB,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC5B,aAAa,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC/C,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAmBD,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,UAAU,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,iBAAiB,EAChC,cAAc,EAAE,kBAAkB,EAClC,eAAe,EAAE,mBAAoC,EACrD,eAAe,EAAE,mBAAwB,EACzC,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,IAAmB,EACnB,WAAe,GAChB,EAAE,sBAAsB,2CAwfxB"}

package/dist/ProjectMenuClient.js

@@ -17,7 +17,7 @@ const ACCENT = "oklch(0.78 0.16 85)";
 const API_KEY = "pk_live_crmsuTIm7NNfb9uEWBCyv88F6kj2YQUR";
 const DEFAULT_FONT = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif";
 const menuDataCache = new Map();
-export function ProjectMenuClient({ dataUrl, clientSlug, apiBase, projects: projectsProp, schema: schemaProp, filterOptions: filterOptionsProp, filterFieldKey: filterFieldKeyProp, filterFieldName: filterFieldNameProp = "Project Type", fieldOptionsMap: fieldOptionsMapProp = {}, subtitle, basePath, viewAllPath, font = DEFAULT_FONT, maxProjects = 6, }) {
+export function ProjectMenuClient({ dataUrl, clientSlug, apiBase, menuId, projects: projectsProp, schema: schemaProp, filterOptions: filterOptionsProp, filterFieldKey: filterFieldKeyProp, filterFieldName: filterFieldNameProp = "Project Type", fieldOptionsMap: fieldOptionsMapProp = {}, subtitle, basePath, viewAllPath, font = DEFAULT_FONT, maxProjects = 6, }) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
     const [filtersOpen, setFiltersOpen] = useState(false);
     const [hoveredCard, setHoveredCard] = useState(null);
@@ -30,9 +30,9 @@ export function ProjectMenuClient({ dataUrl, clientSlug, apiBase, projects: proj
         if (!hasDataUrl && !hasDirectFetch)
             return;
         let cancelled = false;
-        const cacheKey = dataUrl !== null && dataUrl !== void 0 ? dataUrl : `${clientSlug}:${apiBase}`;
+        const cacheKey = dataUrl !== null && dataUrl !== void 0 ? dataUrl : `${clientSlug}:${apiBase}:${menuId !== null && menuId !== void 0 ? menuId : "all"}`;
         async function fetchAndCache() {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3;
             // dataUrl mode: fetch from local API route (server-cached, no API key exposed)
             if (dataUrl) {
                 const res = await fetch(dataUrl);
@@ -46,19 +46,62 @@ export function ProjectMenuClient({ dataUrl, clientSlug, apiBase, projects: proj
                     fieldOptionsMap: (_f = json.fieldOptionsMap) !== null && _f !== void 0 ? _f : {},
                 };
             }
-            // Direct fetch mode: fetch from the upstream API directly
+            // Menu endpoint mode: fetch from /menus/{menuId} when menuId is provided
+            // Also fetch /projects to get schema for filters (menu endpoint may not return it)
+            if (menuId) {
+                const [menuRes, projectsRes, fieldsRes] = await Promise.all([
+                    fetch(`${apiBase}/api/v1/clients/${clientSlug}/menus/${menuId}?api_key=${API_KEY}`),
+                    fetch(`${apiBase}/api/v1/clients/${clientSlug}/projects?api_key=${API_KEY}`),
+                    fetch(`${apiBase}/api/v1/clients/${clientSlug}/fields?api_key=${API_KEY}`),
+                ]);
+                const menuJson = menuRes.ok ? await menuRes.json() : {};
+                const projectsJson = projectsRes.ok ? await projectsRes.json() : {};
+                const projects = (_h = (_g = menuJson === null || menuJson === void 0 ? void 0 : menuJson.projects) !== null && _g !== void 0 ? _g : menuJson === null || menuJson === void 0 ? void 0 : menuJson.data) !== null && _h !== void 0 ? _h : [];
+                // Get schema from menu response first, fallback to projects response
+                const schema = (_o = (_l = (_k = (_j = menuJson === null || menuJson === void 0 ? void 0 : menuJson.client) === null || _j === void 0 ? void 0 : _j.custom_fields_schema) !== null && _k !== void 0 ? _k : menuJson === null || menuJson === void 0 ? void 0 : menuJson.schema) !== null && _l !== void 0 ? _l : (_m = projectsJson === null || projectsJson === void 0 ? void 0 : projectsJson.client) === null || _m === void 0 ? void 0 : _m.custom_fields_schema) !== null && _o !== void 0 ? _o : [];
+                const fieldsJson = fieldsRes.ok ? await fieldsRes.json() : { fields: [] };
+                const fieldOptionsMap = {};
+                for (const field of ((_p = fieldsJson.fields) !== null && _p !== void 0 ? _p : [])) {
+                    const map = {};
+                    for (const opt of ((_q = field.options) !== null && _q !== void 0 ? _q : [])) {
+                        if (typeof opt === "object" && opt.id && opt.label) {
+                            map[opt.id] = opt.label;
+                            map[opt.label] = opt.label;
+                        }
+                    }
+                    fieldOptionsMap[field.key] = map;
+                }
+                const filterField = (_r = schema.find((f) => f.is_filterable && (f.type === "select" || f.type === "multi-select"))) !== null && _r !== void 0 ? _r : null;
+                const filterOptions = filterField
+                    ? ((_s = filterField.options) !== null && _s !== void 0 ? _s : []).map((opt) => {
+                        var _a, _b;
+                        if (typeof opt === "string")
+                            return { id: opt.toLowerCase().replace(/\s+/g, "-"), label: opt };
+                        return { id: (_a = opt.id) !== null && _a !== void 0 ? _a : "", label: (_b = opt.label) !== null && _b !== void 0 ? _b : "" };
+                    })
+                    : [];
+                return {
+                    projects,
+                    schema,
+                    filterOptions,
+                    filterFieldKey: (_t = filterField === null || filterField === void 0 ? void 0 : filterField.key) !== null && _t !== void 0 ? _t : null,
+                    filterFieldName: (_u = filterField === null || filterField === void 0 ? void 0 : filterField.name) !== null && _u !== void 0 ? _u : "Project Type",
+                    fieldOptionsMap,
+                };
+            }
+            // Direct fetch mode: fetch from the upstream API directly (all projects)
             const [projectsRes, fieldsRes] = await Promise.all([
                 fetch(`${apiBase}/api/v1/clients/${clientSlug}/projects?api_key=${API_KEY}`),
                 fetch(`${apiBase}/api/v1/clients/${clientSlug}/fields?api_key=${API_KEY}`),
             ]);
             const json = projectsRes.ok ? await projectsRes.json() : {};
-            const projects = (_g = json === null || json === void 0 ? void 0 : json.data) !== null && _g !== void 0 ? _g : [];
-            const schema = (_j = (_h = json === null || json === void 0 ? void 0 : json.client) === null || _h === void 0 ? void 0 : _h.custom_fields_schema) !== null && _j !== void 0 ? _j : [];
+            const projects = (_v = json === null || json === void 0 ? void 0 : json.data) !== null && _v !== void 0 ? _v : [];
+            const schema = (_x = (_w = json === null || json === void 0 ? void 0 : json.client) === null || _w === void 0 ? void 0 : _w.custom_fields_schema) !== null && _x !== void 0 ? _x : [];
             const fieldsJson = fieldsRes.ok ? await fieldsRes.json() : { fields: [] };
             const fieldOptionsMap = {};
-            for (const field of ((_k = fieldsJson.fields) !== null && _k !== void 0 ? _k : [])) {
+            for (const field of ((_y = fieldsJson.fields) !== null && _y !== void 0 ? _y : [])) {
                 const map = {};
-                for (const opt of ((_l = field.options) !== null && _l !== void 0 ? _l : [])) {
+                for (const opt of ((_z = field.options) !== null && _z !== void 0 ? _z : [])) {
                     if (typeof opt === "object" && opt.id && opt.label) {
                         map[opt.id] = opt.label;
                         map[opt.label] = opt.label;
@@ -66,9 +109,9 @@ export function ProjectMenuClient({ dataUrl, clientSlug, apiBase, projects: proj
                 }
                 fieldOptionsMap[field.key] = map;
             }
-            const filterField = (_m = schema.find((f) => f.is_filterable && (f.type === "select" || f.type === "multi-select"))) !== null && _m !== void 0 ? _m : null;
+            const filterField = (_0 = schema.find((f) => f.is_filterable && (f.type === "select" || f.type === "multi-select"))) !== null && _0 !== void 0 ? _0 : null;
             const filterOptions = filterField
-                ? ((_o = filterField.options) !== null && _o !== void 0 ? _o : []).map((opt) => {
+                ? ((_1 = filterField.options) !== null && _1 !== void 0 ? _1 : []).map((opt) => {
                     var _a, _b;
                     if (typeof opt === "string")
                         return { id: opt.toLowerCase().replace(/\s+/g, "-"), label: opt };
@@ -79,8 +122,8 @@ export function ProjectMenuClient({ dataUrl, clientSlug, apiBase, projects: proj
                 projects,
                 schema,
                 filterOptions,
-                filterFieldKey: (_p = filterField === null || filterField === void 0 ? void 0 : filterField.key) !== null && _p !== void 0 ? _p : null,
-                filterFieldName: (_q = filterField === null || filterField === void 0 ? void 0 : filterField.name) !== null && _q !== void 0 ? _q : "Project Type",
+                filterFieldKey: (_2 = filterField === null || filterField === void 0 ? void 0 : filterField.key) !== null && _2 !== void 0 ? _2 : null,
+                filterFieldName: (_3 = filterField === null || filterField === void 0 ? void 0 : filterField.name) !== null && _3 !== void 0 ? _3 : "Project Type",
                 fieldOptionsMap,
             };
         }
@@ -95,7 +138,7 @@ export function ProjectMenuClient({ dataUrl, clientSlug, apiBase, projects: proj
             // silently fail — render nothing
         });
         return () => { cancelled = true; };
-    }, [dataUrl, clientSlug, apiBase]);
+    }, [dataUrl, clientSlug, apiBase, menuId]);
     // Resolve data: prefer self-fetched, fall back to props
     const projects = (_b = (_a = fetched === null || fetched === void 0 ? void 0 : fetched.projects) !== null && _a !== void 0 ? _a : projectsProp) !== null && _b !== void 0 ? _b : [];
     const schema = (_d = (_c = fetched === null || fetched === void 0 ? void 0 : fetched.schema) !== null && _c !== void 0 ? _c : schemaProp) !== null && _d !== void 0 ? _d : [];
@@ -254,19 +297,13 @@ export function ProjectMenuClient({ dataUrl, clientSlug, apiBase, projects: proj
         .chisel-menu-filter-link {
           all: unset;
           cursor: pointer;
-          display: flex;
-          align-items: center;
-          justify-content: space-between;
+          display: block;
           font-size: 14px;
           color: #52525b;
           font-weight: 400;
           padding: 7px 0;
           text-decoration: none;
           transition: color 0.15s;
-          border-bottom: 1px solid #f4f4f5;
-        }
-        .chisel-menu-filter-link:last-child {
-          border-bottom: none;
         }
         .chisel-menu-filter-link:hover {
           color: #18181b;
@@ -314,18 +351,24 @@ export function ProjectMenuClient({ dataUrl, clientSlug, apiBase, projects: proj
                                                         const tagLabels = tags.map((t) => { var _a; return (_a = optMap[t]) !== null && _a !== void 0 ? _a : t; }).slice(0, 2);
                                                         return (_jsx("p", { style: { fontSize: "11px", color: ACCENT, margin: 0, fontFamily: font, lineHeight: 1.4 }, children: tagLabels.join(" · ") }));
                                                     })()] })] }, project.id));
-                                }) }))] }), _jsx("div", { className: "chisel-menu-divider-v" }), _jsxs("div", { className: "chisel-menu-right", children: [filterOptions.length > 0 && (_jsxs(_Fragment, { children: [_jsxs("p", { style: {
+                                }) }))] }), _jsx("div", { className: "chisel-menu-divider-v" }), _jsxs("div", { className: "chisel-menu-right", children: [filterOptions.length > 0 && (_jsxs(_Fragment, { children: [_jsx("p", { style: {
                                             fontSize: "11px",
                                             fontWeight: 700,
                                             textTransform: "uppercase",
                                             letterSpacing: "0.12em",
                                             color: "#71717a",
+                                            margin: "0 0 10px 0",
+                                        }, children: "Browse By" }), _jsx("p", { style: {
+                                            fontSize: "15px",
+                                            fontWeight: 700,
+                                            color: "#18181b",
                                             margin: "0 0 4px 0",
-                                        }, children: ["Browse By ", filterFieldName] }), _jsx("div", { style: { display: "flex", flexDirection: "column", marginBottom: "20px" }, children: filterOptions.map((opt) => {
+                                            fontFamily: font,
+                                        }, children: filterFieldName }), _jsx("div", { style: { display: "flex", flexDirection: "column", marginBottom: "20px" }, children: filterOptions.map((opt) => {
                                             const href = filterFieldKey
                                                 ? `${basePath}?filter[${filterFieldKey}]=${encodeURIComponent(opt.id)}`
                                                 : basePath;
-                                            return (_jsxs("a", { href: href, className: "chisel-menu-filter-link", style: { fontFamily: font }, children: [opt.label, _jsx("svg", { width: "12", height: "12", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round", style: { flexShrink: 0, opacity: 0.4 }, children: _jsx("path", { d: "M9 18l6-6-6-6" }) })] }, opt.id));
+                                            return (_jsx("a", { href: href, className: "chisel-menu-filter-link", style: { fontFamily: font }, children: opt.label }, opt.id));
                                         }) }), _jsx("div", { style: { height: "1px", backgroundColor: "#e4e4e7", marginBottom: "20px" } })] })), _jsxs("a", { href: viewAllPath, style: {
                                     all: "unset",
                                     cursor: "pointer",

package/dist/SimilarProjects.d.ts

@@ -20,6 +20,18 @@ export interface SimilarProjectsProps {
     maxItems?: number;
     /** Seconds to cache. Defaults to 60 */
     revalidate?: number;
+    /**
+     * Visual layout for the project cards.
+     * - "list" (default) — image + text with border-bottom separator
+     * - "card" — full baseball-card style matching the ProjectPortfolio grid
+     */
+    variant?: "list" | "card";
+    /**
+     * Explicit list of project slugs to display, in order.
+     * When provided, overrides `filters` entirely — only these projects are shown.
+     * e.g. projectSlugs={["jacob-javits", "tillamook-bay-community-college"]}
+     */
+    projectSlugs?: string[];
 }
-export declare function SimilarProjects({ filters, excludeSlug, clientSlug, apiBase, basePath, maxItems, revalidate, }: SimilarProjectsProps): Promise<import("react/jsx-runtime").JSX.Element | null>;
+export declare function SimilarProjects({ filters, excludeSlug, clientSlug, apiBase, basePath, maxItems, revalidate, variant, projectSlugs, }: SimilarProjectsProps): Promise<import("react/jsx-runtime").JSX.Element | null>;
 //# sourceMappingURL=SimilarProjects.d.ts.map

package/dist/SimilarProjects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SimilarProjects.d.ts","sourceRoot":"","sources":["../src/SimilarProjects.tsx"],"names":[],"mappings":"AAKA,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAA;IAClB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AA8CD,wBAAsB,eAAe,CAAC,EACpC,OAAY,EACZ,WAAW,EACX,UAAU,EACV,OAAO,EACP,QAAsB,EACtB,QAAY,EACZ,UAAe,GAChB,EAAE,oBAAoB,2DAgHtB"}
+{"version":3,"file":"SimilarProjects.d.ts","sourceRoot":"","sources":["../src/SimilarProjects.tsx"],"names":[],"mappings":"AAMA,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAA;IAClB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB;AA6DD,wBAAsB,eAAe,CAAC,EACpC,OAAY,EACZ,WAAW,EACX,UAAU,EACV,OAAO,EACP,QAAsB,EACtB,QAAY,EACZ,UAAe,EACf,OAAgB,EAChB,YAAY,GACb,EAAE,oBAAoB,2DA8JtB"}

package/dist/SimilarProjects.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cache } from "react";
+import { ProjectCard } from "./ProjectCard";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 function parseMultiValue(raw) {
     if (Array.isArray(raw))
@@ -19,40 +20,82 @@ function dedupeByKey(arr) {
 }
 // ─── Data fetching ────────────────────────────────────────────────────────────
 const fetchSimilarData = cache(async (apiBase, clientSlug, revalidate) => {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e;
     const fetchOpts = revalidate > 0 ? { next: { revalidate } } : {};
+    const API_KEY = "pk_live_crmsuTIm7NNfb9uEWBCyv88F6kj2YQUR";
     try {
-        const res = await fetch(`${apiBase}/api/v1/clients/${clientSlug}/projects?api_key=pk_live_crmsuTIm7NNfb9uEWBCyv88F6kj2YQUR`, fetchOpts);
+        const [res, fieldsRes] = await Promise.all([
+            fetch(`${apiBase}/api/v1/clients/${clientSlug}/projects?api_key=${API_KEY}`, fetchOpts),
+            fetch(`${apiBase}/api/v1/clients/${clientSlug}/fields?api_key=${API_KEY}`, fetchOpts),
+        ]);
         const json = res.ok ? await res.json() : null;
         const allProjects = (_a = json === null || json === void 0 ? void 0 : json.data) !== null && _a !== void 0 ? _a : [];
         const schema = dedupeByKey((_c = (_b = json === null || json === void 0 ? void 0 : json.client) === null || _b === void 0 ? void 0 : _b.custom_fields_schema) !== null && _c !== void 0 ? _c : []);
-        return { allProjects, schema };
+        const fieldsJson = fieldsRes.ok ? await fieldsRes.json() : { fields: [] };
+        const fieldOptionsMap = {};
+        for (const field of ((_d = fieldsJson.fields) !== null && _d !== void 0 ? _d : [])) {
+            const map = {};
+            for (const opt of ((_e = field.options) !== null && _e !== void 0 ? _e : [])) {
+                if (typeof opt === "object" && opt.id && opt.label) {
+                    map[opt.id] = opt.label;
+                    map[opt.label] = opt.label;
+                }
+            }
+            fieldOptionsMap[field.key] = map;
+        }
+        return { allProjects, schema, fieldOptionsMap };
     }
-    catch (_d) {
-        return { allProjects: [], schema: [] };
+    catch (_f) {
+        return { allProjects: [], schema: [], fieldOptionsMap: {} };
     }
 });
 // ─── Component ────────────────────────────────────────────────────────────────
-export async function SimilarProjects({ filters = {}, excludeSlug, clientSlug, apiBase, basePath = "/projects", maxItems = 3, revalidate = 60, }) {
-    const { allProjects, schema } = await fetchSimilarData(apiBase, clientSlug, revalidate);
+export async function SimilarProjects({ filters = {}, excludeSlug, clientSlug, apiBase, basePath = "/projects", maxItems = 3, revalidate = 60, variant = "list", projectSlugs, }) {
+    const { allProjects, schema, fieldOptionsMap } = await fetchSimilarData(apiBase, clientSlug, revalidate);
     const badgeField = schema.find((f) => f.display_position === "badge_overlay");
     const locationField = schema.find((f) => f.type === "location");
     const font = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif";
-    const filterEntries = Object.entries(filters);
-    const similar = allProjects
-        .filter((p) => {
-        // Exclude the specified slug if provided
-        if (excludeSlug && p.slug === excludeSlug)
-            return false;
-        // Every filter key/value must match the project's custom field values
-        return filterEntries.every(([key, value]) => {
-            const fieldValues = parseMultiValue(p.custom_field_values[key]);
-            return fieldValues.some((v) => v.toLowerCase() === value.toLowerCase());
-        });
-    })
-        .slice(0, maxItems);
+    let similar;
+    if (projectSlugs && projectSlugs.length > 0) {
+        // Manual mode — show exactly these slugs in the order provided
+        const projectMap = new Map(allProjects.map((p) => [p.slug, p]));
+        similar = projectSlugs
+            .filter((slug) => slug !== excludeSlug)
+            .map((slug) => projectMap.get(slug))
+            .filter((p) => p !== undefined)
+            .slice(0, maxItems);
+    }
+    else {
+        // Filter mode — match by custom field values
+        const filterEntries = Object.entries(filters);
+        similar = allProjects
+            .filter((p) => {
+            if (excludeSlug && p.slug === excludeSlug)
+                return false;
+            return filterEntries.every(([key, value]) => {
+                const fieldValues = parseMultiValue(p.custom_field_values[key]);
+                return fieldValues.some((v) => v.toLowerCase() === value.toLowerCase());
+            });
+        })
+            .slice(0, maxItems);
+    }
     if (similar.length === 0)
         return null;
+    const header = (_jsxs("div", { className: "chisel-similar-header", children: [_jsxs("div", { children: [_jsx("p", { style: { fontSize: "11px", fontWeight: 700, textTransform: "uppercase", letterSpacing: "0.12em", color: "oklch(0.78 0.16 85)", margin: "0 0 6px 0" }, children: "More Work" }), _jsx("h2", { style: { color: "#18181b", fontWeight: 700, fontSize: "clamp(20px, 4vw, 28px)", margin: 0, fontFamily: font }, children: "Similar Projects" })] }), _jsxs("a", { href: basePath, style: { color: "#18181b", fontWeight: 600, fontSize: "15px", textDecoration: "none", display: "inline-flex", alignItems: "center", gap: "6px", fontFamily: font, flexShrink: 0 }, children: ["View All", _jsx("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "M9 18l6-6-6-6" }) })] })] }));
+    // ── Card variant ─────────────────────────────────────────────────────────────
+    if (variant === "card") {
+        return (_jsxs("section", { style: { borderTop: "1px solid #e4e4e7", maxWidth: "1280px", margin: "0 auto", padding: "3rem 1rem 2rem", boxSizing: "border-box", fontFamily: font }, children: [_jsx("style", { children: `
+          .chisel-similar-header { display: flex; flex-direction: column; gap: 12px; margin-bottom: 2rem; }
+          @media (min-width: 640px) { .chisel-similar-header { flex-direction: row; align-items: flex-end; justify-content: space-between; } }
+          .chisel-similar-card-grid { display: grid; grid-template-columns: 1fr; gap: 1.5rem; }
+          @media (min-width: 640px)  { .chisel-similar-card-grid { grid-template-columns: repeat(2, 1fr); } }
+          @media (min-width: 1024px) { .chisel-similar-card-grid { grid-template-columns: repeat(3, 1fr); } }
+          .chisel-project-card-img { height: 180px; }
+          @media (min-width: 640px) { .chisel-project-card-img { height: 200px; } }
+          @media (min-width: 1024px) { .chisel-project-card-img { height: 220px; } }
+        ` }), header, _jsx("div", { className: "chisel-similar-card-grid", children: similar.map((p, i) => (_jsx(ProjectCard, { project: p, schema: schema, fieldOptionsMap: fieldOptionsMap, basePath: basePath, priority: i === 0, variant: "card" }, p.id))) })] }));
+    }
+    // ── List variant (default) ────────────────────────────────────────────────────
     return (_jsxs("section", { style: { borderTop: "1px solid #e4e4e7", maxWidth: "1280px", margin: "0 auto", padding: "3rem 1rem 2rem", boxSizing: "border-box", fontFamily: font }, children: [_jsx("style", { children: `
         .chisel-similar-grid { display: grid; grid-template-columns: 1fr; gap: 1.5rem; }
         @media (min-width: 640px)  { .chisel-similar-grid { grid-template-columns: repeat(2, 1fr); } }
@@ -60,7 +103,7 @@ export async function SimilarProjects({ filters = {}, excludeSlug, clientSlug, a
         .chisel-similar-header { display: flex; flex-direction: column; gap: 12px; margin-bottom: 2rem; }
         @media (min-width: 640px) { .chisel-similar-header { flex-direction: row; align-items: flex-end; justify-content: space-between; } }
         .chisel-similar-img { height: 56vw; min-height: 160px; max-height: 220px; }
-      ` }), _jsxs("div", { className: "chisel-similar-header", children: [_jsxs("div", { children: [_jsx("p", { style: { fontSize: "11px", fontWeight: 700, textTransform: "uppercase", letterSpacing: "0.12em", color: "oklch(0.78 0.16 85)", margin: "0 0 6px 0" }, children: "More Work" }), _jsx("h2", { style: { color: "#18181b", fontWeight: 700, fontSize: "clamp(20px, 4vw, 28px)", margin: 0, fontFamily: font }, children: "Similar Projects" })] }), _jsxs("a", { href: basePath, style: { color: "#18181b", fontWeight: 600, fontSize: "15px", textDecoration: "none", display: "inline-flex", alignItems: "center", gap: "6px", fontFamily: font, flexShrink: 0 }, children: ["View All", _jsx("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "M9 18l6-6-6-6" }) })] })] }), _jsx("div", { className: "chisel-similar-grid", children: similar.map((p) => {
+      ` }), header, _jsx("div", { className: "chisel-similar-grid", children: similar.map((p) => {
                     var _a, _b, _c, _d, _e;
                     const imgUrl = (_d = (_a = p.image_url) !== null && _a !== void 0 ? _a : (_c = (_b = p.media) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.url) !== null && _d !== void 0 ? _d : null;
                     const badge = badgeField

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-portfolio",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Self-contained project portfolio components for Next.js App Router. Includes ProjectPortfolio, ProjectPortfolioClient (with built-in filtering), ProjectDetail, SimilarProjects, ProjectMenu, ProjectMenuClient, and GalleryCarousel. Pass a clientSlug and apiBase — done.",
   "keywords": ["nextjs", "react", "portfolio", "projects", "megamenu", "gallery", "filtering"],
   "license": "MIT",