bsmnt 0.13.0 → 0.14.0

package/src/templates/next-pagebuilder/lib/utils/image-sizes.ts

@@ -15,40 +15,55 @@ export type ByBreakpoint<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
 > = { base: T } & Partial<Record<Extract<keyof B, string>, T>>
 
+export type ImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = { breakpoints?: B }
+
+export type GridImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = ImageSizesOptions<B> & {
+  /** The grid container's `max-width` in px, past which columns stop growing. */
+  maxWidth?: number
+}
+
+type Condition<T> = { min: number; value: T }
+
 function columnWidth(columns: number): string {
   return `${Math.round(100 / columns)}vw`
 }
 
+function toConditions<T>(
+  overrides: Readonly<Record<string, T | undefined>>,
+  scale: BreakpointMap
+): Condition<T>[] {
+  return Object.entries(overrides).flatMap(([name, value]) => {
+    const min = scale[name]
+    return value !== undefined && min !== undefined ? [{ min, value }] : []
+  })
+}
+
 /**
  * Widest first, since `sizes` takes the first matching condition and the last
  * entry must be bare. `min-width` matches the Tailwind variant's boundary; a
  * `max-width: <next> - 1` one would leave a fractional-pixel gap.
  */
-function toSizes(
-  base: string,
-  overrides: Readonly<Record<string, string | undefined>>,
-  scale: BreakpointMap
-): string {
-  const conditions: string[] = []
-
-  for (const [name, min] of Object.entries(scale).sort(
-    ([, a], [, b]) => b - a
-  )) {
-    const value = overrides[name]
-    if (value !== undefined) {
-      conditions.push(`(min-width: ${min}px) ${value}`)
-    }
-  }
+function joinSizes(base: string, conditions: Condition<string>[]): string {
+  const sorted = [...conditions].sort((a, b) => b.min - a.min)
 
-  return [...conditions, base].join(", ")
+  return [
+    ...sorted.map(({ min, value }) => `(min-width: ${min}px) ${value}`),
+    base,
+  ].join(", ")
 }
 
 /** Builds `sizes` from the CSS length the image renders at per breakpoint. */
 export function buildImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(widths: ByBreakpoint<string, B>, breakpoints?: B): string {
+>(widths: ByBreakpoint<string, B>, options: ImageSizesOptions<B> = {}): string {
   const { base, ...overrides } = widths
-  return toSizes(base, overrides, breakpoints ?? BASEMENT_BREAKPOINTS)
+  const scale = options.breakpoints ?? BASEMENT_BREAKPOINTS
+
+  return joinSizes(base, toConditions<string>(overrides, scale))
 }
 
 /**
@@ -58,15 +73,39 @@ export function buildImageSizes<
  */
 export function buildGridImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(columns: ByBreakpoint<number, B>, breakpoints?: B): string {
+>(
+  columns: ByBreakpoint<number, B>,
+  options: GridImageSizesOptions<B> = {}
+): string {
+  const { maxWidth, breakpoints } = options
   const { base, ...overrides } = columns
-  const widths: Record<string, string> = {}
+  const steps = toConditions<number>(
+    overrides,
+    breakpoints ?? BASEMENT_BREAKPOINTS
+  )
+  const cap =
+    maxWidth !== undefined && Number.isFinite(maxWidth) && maxWidth > 0
+      ? maxWidth
+      : undefined
+
+  // The cap rarely lands on a breakpoint, so it needs its own condition.
+  if (cap !== undefined && !steps.some(({ min }) => min === cap)) {
+    const below = steps
+      .filter(({ min }) => min < cap)
+      .sort((a, b) => a.min - b.min)
+      .at(-1)
 
-  for (const [name, count] of Object.entries(overrides)) {
-    if (count !== undefined) {
-      widths[name] = columnWidth(count)
-    }
+    steps.push({ min: cap, value: below?.value ?? base })
   }
 
-  return toSizes(columnWidth(base), widths, breakpoints ?? BASEMENT_BREAKPOINTS)
+  return joinSizes(
+    columnWidth(base),
+    steps.map(({ min, value }) => ({
+      min,
+      value:
+        cap !== undefined && min >= cap
+          ? `${Math.round(cap / value)}px`
+          : columnWidth(value),
+    }))
+  )
 }

package/src/templates/next-pagebuilder-cache/AGENTS.md

@@ -11,7 +11,9 @@ page.
 Studio with a slug, not a directory. `app/(content)/[[...slug]]/page.tsx`
 resolves every one of them; a hand-written route shadows that resolver and
 becomes a URL no editor can see, move or delete. The only things that belong in
-`app/` are non-page endpoints — the Studio, API handlers, sitemap, feed.
+`app/` are non-page endpoints — the Studio, API handlers, sitemap, feed, and
+`app/components`, the Studio's live block preview: it renders fixtures rather
+than content, is gated to Studio embeds by `isStudioEmbed()` and is `noindex`.
 
 It runs with [Cache Components](https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents)
 (`cacheComponents: true`), so every Sanity read sits behind a `'use cache'`
@@ -22,10 +24,18 @@ boundaries where they are unless you mean to move them.
 
 ## Page-builder blocks
 
+**Blocks are inline objects, never documents.** A placement belongs to exactly
+one page, so the page's `pageBuilder` array stores the block itself and nothing
+is dereferenced at read time. Don't reintroduce a block-as-document with a
+reference member — that model was removed deliberately: no block was ever
+reused, and it cost a hop on every read plus a second id to address.
+
 **A block is `defineBlock` + a registry entry.** Define the schema with
 `defineBlock` (`lib/integrations/sanity/schemas/shared/block.ts`), never
-`defineType` — it implies `type: "document"` and appends **Anchor ID** and
-**Presentation Mode** for you. Register the component in
+`defineType` — it implies `type: "object"` and appends **Anchor ID** and
+**Presentation Mode** for you. The array member's type name *is* the block's
+`_type`, so the registry, the insert menu and the fixture library all key off
+the same string. Register the component in
 `components/page-builder/registry.tsx`; the renderer is driven by that map, so
 there is no switch to extend.
 
@@ -40,10 +50,12 @@ that was never registered — is a typecheck error.
 drives the insert menu; `misc` only when nothing else fits). Never collapse them
 into one field: that is what made the menu a single flat list.
 
-**And a preview image.** The insert menu renders one tile per block from a
-`studioPreview` document (Components → Component Previews) keyed
-`block.<memberName>`. A block without one falls back to its schema icon, which
-is what made the old menu unreadable.
+**And a fixture.** A block isn't done until `components/page-builder/library.ts`
+has an entry for it: a stand-in value typed as the block's query result, plus a
+one-line note. That entry is the block's preview everywhere — the live pane in
+the insert menu, its row in Studio → Components, and the `/components` route,
+all rendered by the production renderer. Without one the picker just says the
+component has no preview.
 
 **Never hardcode vertical padding in a block component.** The renderer wraps
 each block in `<Section>` (`components/page-builder/section.tsx`), which owns

package/src/templates/next-pagebuilder-cache/README.md

@@ -25,14 +25,18 @@ bun dev
 
 ## Page-builder blocks
 
-A block is two halves — a schema document and a React component — and each half
-has one place that makes it a block rather than an ordinary document or a loose
+A block is two halves — a schema type and a React component — and each half has
+one place that makes it a block rather than an ordinary object type or a loose
 component. Use them and Anchor ID, Presentation Mode and the spacing scale come
 for free.
 
+Blocks are **inline objects** in the page's `pageBuilder` array, never documents
+and never referenced: a placement belongs to exactly one page, so the block
+lives on that page and nothing is dereferenced at read time.
+
 **Define the schema with `defineBlock`, never `defineType`**
 (`lib/integrations/sanity/schemas/shared/block.ts`). It implies
-`type: "document"` and appends two fields to every block:
+`type: "object"` and appends two fields to every block:
 
 - **Anchor ID** — optional. Left empty, the anchor is generated from the block's
   own title at render time (`headline` / `heading` / `teaserHeading` / `title` /
@@ -61,6 +65,14 @@ block in `<Section>` (`components/page-builder/section.tsx`), which owns the
 component returns its content only — no outer `<section>`, no `py-*` / `pt-*` /
 `pb-*` on its root. Internal gaps between a block's own parts are fine.
 
+**Every block ships a fixture in `components/page-builder/library.ts`**: a
+stand-in value typed as the block's query result, plus a one-line note. It is
+the block's only preview, and it is rendered by the production renderer at
+`/components` — a route the Studio embeds in an iframe, so the insert menu and
+**Components** in the Studio show the real block rather than a screenshot. The
+route is gated to Studio embeds and `noindex`; a block with no entry simply has
+no preview.
+
 ### The spacing scale is content, not code
 
 Editors own it at **Layout → Spacing Scale**: a list of steps, each with a name

package/src/templates/next-pagebuilder-cache/app/actions/unlock-gated-content.ts

@@ -14,13 +14,14 @@ export type UnlockResult =
   | { ok: true; payload: GatedContentPayload }
   | { ok: false; error: string }
 
-type UnlockInput = { documentId: string; email: string }
+type UnlockInput = { pageId: string; blockKey: string; email: string }
 
 export async function unlockGatedContent({
-  documentId,
+  pageId,
+  blockKey,
   email,
 }: UnlockInput): Promise<UnlockResult> {
-  if (!documentId) return { ok: false, error: "Missing content id." }
+  if (!(pageId && blockKey)) return { ok: false, error: "Missing content id." }
   if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
     return { ok: false, error: "Enter a valid email address." }
   }
@@ -38,7 +39,7 @@ export async function unlockGatedContent({
   // is how `variant` goes missing.
   const payload = await client.fetch<GATED_CONTENT_QUERY_RESULT>(
     GATED_CONTENT_QUERY,
-    { id: documentId },
+    { pageId, blockKey },
     toSanityFetchOptions({
       ...fetchOptions,
       // stega must stay off: it injects invisible characters into strings, which

package/src/templates/next-pagebuilder-cache/app/components/page.tsx

@@ -0,0 +1,91 @@
+import type { Metadata } from "next"
+import { draftMode } from "next/headers"
+import { notFound } from "next/navigation"
+import { Suspense } from "react"
+import { SpacingScale } from "@/components/layout/spacing-scale"
+import {
+  COMPONENT_LIBRARY,
+  COMPONENT_PREVIEW_PARAM,
+  getLibraryEntry,
+  type LibraryEntry,
+} from "@/components/page-builder/library"
+import { Renderer } from "@/components/page-builder/renderer"
+import { Stage } from "@/components/page-builder/stage"
+import { isStudioEmbed } from "@/lib/utils/studio-embed"
+
+export const metadata: Metadata = {
+  title: "Components",
+  robots: { index: false, follow: false, nocache: true },
+}
+
+type Props = {
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}
+
+const firstValue = (value: string | string[] | undefined) =>
+  Array.isArray(value) ? value[0] : value
+
+const PREVIEW_PAGE_ID = "component-preview"
+
+const EntryHeader = ({ entry }: { entry: LibraryEntry }) => (
+  <header className="sticky top-0 z-10 flex items-baseline gap-3 border-neutral-200 border-b bg-white/85 px-6 py-3 backdrop-blur">
+    <h2 className="font-mono text-neutral-900 text-xs uppercase">
+      {entry.title}
+    </h2>
+    <p className="text-neutral-500 text-xs">{entry.notes}</p>
+  </header>
+)
+
+const PreviewStage = ({ entry }: { entry: LibraryEntry }) => (
+  <Stage background={entry.background}>
+    <Renderer
+      blocks={[entry.block]}
+      pageId={PREVIEW_PAGE_ID}
+      pinnedCategory={null}
+      searchParams={undefined}
+    />
+  </Stage>
+)
+
+// Both `isStudioEmbed()` (headers) and `searchParams` are request-time data, so
+// under Cache Components this has to sit inside the page's <Suspense> boundary —
+// at the top of the page it fails the prerender with blocking-prerender-dynamic.
+const Library = async ({ searchParams }: Props) => {
+  const [params, embedded] = await Promise.all([searchParams, isStudioEmbed()])
+
+  if (!embedded) notFound()
+
+  const requested = firstValue(params[COMPONENT_PREVIEW_PARAM])
+  const entry = getLibraryEntry(requested)
+
+  if (requested && !entry) notFound()
+
+  if (entry) return <PreviewStage entry={entry} />
+
+  return (
+    <>
+      {COMPONENT_LIBRARY.map((item) => (
+        <section key={item.documentType}>
+          <EntryHeader entry={item} />
+          <PreviewStage entry={item} />
+        </section>
+      ))}
+    </>
+  )
+}
+
+// Outside the `(content)` group, so `<SpacingScale />` is on this route.
+const Page = async ({ searchParams }: Props) => {
+  const { isEnabled: isDraftMode } = await draftMode()
+
+  return (
+    <main className="flex flex-col">
+      <SpacingScale isDraftMode={isDraftMode} />
+      <Suspense fallback={null}>
+        <Library searchParams={searchParams} />
+      </Suspense>
+    </main>
+  )
+}
+
+export default Page

package/src/templates/next-pagebuilder-cache/components/page-builder/components/gated-content/index.tsx

@@ -13,14 +13,15 @@ type GatedContentBlock = Extract<PageBuilderBlock, { _type: "gatedContent" }>
 
 type GatedContentProps = {
   block: GatedContentBlock
+  pageId: string
 }
 
 type GateState = "locked" | "loading" | "unlocked"
 
 const STORAGE_PREFIX = "gated-content:"
 
-export function GatedContent({ block }: GatedContentProps) {
-  const storageKey = `${STORAGE_PREFIX}${block._id}`
+export function GatedContent({ block, pageId }: GatedContentProps) {
+  const storageKey = `${STORAGE_PREFIX}${pageId}:${block._key}`
   const [state, setState] = useState<GateState>("locked")
   const [payload, setPayload] = useState<GatedContentPayload | null>(null)
   const [error, setError] = useState<string | null>(null)
@@ -33,7 +34,11 @@ export function GatedContent({ block }: GatedContentProps) {
     setState("loading")
     setError(null)
 
-    const result = await unlockGatedContent({ documentId: block._id, email })
+    const result = await unlockGatedContent({
+      pageId,
+      blockKey: block._key,
+      email,
+    })
 
     if (!result.ok) {
       setError(result.error)

package/src/templates/next-pagebuilder-cache/components/page-builder/library.ts

@@ -0,0 +1,183 @@
+import type { PageBuilderDocumentType } from "@/lib/integrations/sanity/page-builder-config"
+import type { PageBuilderBlock } from "./types"
+
+/** One block's stand-in value, rendered by `/components` through `Renderer`. */
+export type LibraryEntry = {
+  documentType: PageBuilderDocumentType
+  title: string
+  notes: string
+  background: string
+  block: PageBuilderBlock
+}
+
+type BlockOf<T extends PageBuilderDocumentType> = Extract<
+  PageBuilderBlock,
+  { _type: T }
+>
+
+const span = (key: string, text: string) => ({
+  _type: "span" as const,
+  _key: key,
+  text,
+  marks: [],
+})
+
+const paragraph = (key: string, text: string) => ({
+  _type: "block" as const,
+  _key: key,
+  style: "normal" as const,
+  markDefs: [],
+  children: [span(`${key}-span`, text)],
+})
+
+const heading = (key: string, text: string) => ({
+  ...paragraph(key, text),
+  style: "h2" as const,
+})
+
+const PLACEHOLDER_KEY = "placeholder"
+
+const hero: BlockOf<"hero"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "hero",
+  headline: "A heading that says what this page is for.",
+}
+
+const description: BlockOf<"description"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "description",
+  description:
+    "One paragraph of standfirst copy under a heading — long enough to set up the page, short enough that nobody skips it.",
+}
+
+const richTextBlock: BlockOf<"richTextBlock"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "richTextBlock",
+  content: [
+    heading("rt-head", "What long-form copy looks like here"),
+    paragraph(
+      "rt-one",
+      "Rich Text is the block for body copy: headings, paragraphs, lists, links and quotes, all authored in the Studio and rendered with the site's own typography."
+    ),
+    paragraph(
+      "rt-two",
+      "Because it is Portable Text rather than HTML, the same content renders in the page, in the markdown route and in the feed without a second template."
+    ),
+  ],
+}
+
+const gatedContent: BlockOf<"gatedContent"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "gatedContent",
+  internalTitle: "Gated guide",
+  teaserHeading: "A guide worth an email address",
+  teaserBody: [
+    paragraph(
+      "gc-teaser",
+      "The teaser is public. The payload — rich text, a file or a video — is withheld from the page query until a visitor submits the form."
+    ),
+  ],
+  gateType: "form",
+  gateHeadline: "Read the full guide",
+  gateDescription: "We'll email you a copy as well.",
+  submitLabel: "Get the guide",
+  successMessage: "Sent — it's on its way.",
+  kind: "richText",
+  anchorId: null,
+  presentation: null,
+}
+
+const blogCollection: BlockOf<"blogCollection"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "blogCollection",
+  subtitle: "Everything else we've written",
+}
+
+const blogContent: BlockOf<"blogContent"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "blogContent",
+  title: "How this starter renders a blog post",
+  categories: [],
+  date: "2026-02-11",
+  author: {
+    _id: "placeholder-author",
+    name: "Jane Doe",
+    avatar: null,
+    role: "Engineer",
+  },
+  body: [
+    paragraph(
+      "bc-one",
+      "A blog post is an ordinary page whose page builder holds a Blog Posts block: byline, date, categories and body all live on the block."
+    ),
+    heading("bc-head", "One block, one article"),
+    paragraph(
+      "bc-two",
+      "The collection block reads the same fields, so an article added in the Studio shows up in the index without touching code."
+    ),
+  ],
+  relatedPosts: [],
+}
+
+export const COMPONENT_LIBRARY: LibraryEntry[] = [
+  {
+    documentType: "hero",
+    title: "Heading",
+    notes: "The page's opening statement. Headline only, no media.",
+    background: "bg-white",
+    block: hero,
+  },
+  {
+    documentType: "description",
+    title: "Description",
+    notes: "A single paragraph of standfirst copy under a heading.",
+    background: "bg-white",
+    block: description,
+  },
+  {
+    documentType: "richTextBlock",
+    title: "Rich Text",
+    notes: "Long-form body copy — headings, lists, links and quotes.",
+    background: "bg-white",
+    block: richTextBlock,
+  },
+  {
+    documentType: "gatedContent",
+    title: "Gated Content",
+    notes:
+      "A teaser with an email gate. The payload is withheld until a visitor submits, so the preview shows the locked state.",
+    background: "bg-white",
+    block: gatedContent,
+  },
+  {
+    documentType: "blogCollection",
+    title: "Blog Collection",
+    notes:
+      "The full article index with search and category filters. Reads real posts.",
+    background: "bg-white",
+    block: blogCollection,
+  },
+  {
+    documentType: "blogContent",
+    title: "Blog Posts",
+    notes:
+      "The body of an article — byline, date, categories and rich text. Only valid on a blog entry page.",
+    background: "bg-white",
+    block: blogContent,
+  },
+]
+
+export const getLibraryEntry = (documentType: string | undefined) =>
+  documentType
+    ? (COMPONENT_LIBRARY.find((entry) => entry.documentType === documentType) ??
+      null)
+    : null
+
+export const COMPONENT_PREVIEW_PATH = "/components"
+
+export const COMPONENT_PREVIEW_PARAM = "component"
+
+export const getComponentPreviewPath = (documentType?: string) =>
+  documentType
+    ? `${COMPONENT_PREVIEW_PATH}?${COMPONENT_PREVIEW_PARAM}=${encodeURIComponent(documentType)}`
+    : COMPONENT_PREVIEW_PATH

package/src/templates/next-pagebuilder-cache/components/page-builder/registry.tsx

@@ -13,6 +13,7 @@ import { RichTextBlock } from "./components/rich-text-block"
 import type { PageBuilderBlock } from "./types"
 
 export type BlockContext = {
+  pageId: string
   searchParams: ContentCollectionSearchParams
   pinnedCategory: PinnedCollectionCategory
 }
@@ -48,7 +49,9 @@ const blockRegistry: {
     isEmpty: (block) => !block.description,
   },
   gatedContent: {
-    render: (block) => <GatedContent block={block} />,
+    render: (block, { pageId }) => (
+      <GatedContent block={block} pageId={pageId} />
+    ),
   },
   hero: {
     render: (block) => <Hero block={block} />,

package/src/templates/next-pagebuilder-cache/components/page-builder/renderer.tsx

@@ -12,18 +12,20 @@ import type { PageBuilderBlock, PageBuilderBlocks } from "./types"
 
 type RendererProps = {
   blocks: PageBuilderBlocks
+  pageId: string
   searchParams: ContentCollectionSearchParams
   pinnedCategory: PinnedCollectionCategory
 }
 
 export function Renderer({
   blocks,
+  pageId,
   searchParams,
   pinnedCategory,
 }: RendererProps) {
   if (!blocks?.length) return null
 
-  const context: BlockContext = { searchParams, pinnedCategory }
+  const context: BlockContext = { pageId, searchParams, pinnedCategory }
 
   const reservedAnchorIds = reserveAnchorIds(blocks)
   const takenAnchorIds = new Set<string>()

package/src/templates/next-pagebuilder-cache/components/page-builder/stage.tsx

@@ -0,0 +1,10 @@
+import type { PropsWithChildren } from "react"
+import { cn } from "@/lib/styles/cn"
+
+type StageProps = PropsWithChildren<{ background?: string }>
+
+export const Stage = ({ background, children }: StageProps) => (
+  <div className={cn("grid min-h-svh content-center", background)}>
+    {children}
+  </div>
+)

package/src/templates/next-pagebuilder-cache/components/page-document/index.tsx

@@ -31,6 +31,7 @@ export const getPageSections = (
         <Renderer
           key="page-builder"
           blocks={page.pageBuilder}
+          pageId={page._id}
           searchParams={searchParams}
           // Cleaned because the slug becomes a GROQ parameter: in draft mode the
           // projection carries stega characters that would break the match.
@@ -92,7 +93,7 @@ export const PageDocument = ({
   // Editor-selected page-level structured data (FAQ, Event, custom, etc.).
   const pageJsonLd = buildPageJsonLd(page.metadata?.jsonLd)
 
-  // Blog posts (pages with a Blog Content block) emit Article JSON-LD with
+  // Blog posts (pages with a Blog Posts block) emit Article JSON-LD with
   // fields derived from the post — no Custom block needed. Skipped when the
   // editor already supplied an Article (via a Custom block) to avoid duplicates.
   const blogBlock = page.pageBuilder?.find(