bsmnt 0.13.0 → 0.14.0

package/src/modules/features/forms/hubspot/files/lib/integrations/hubspot/README.md

@@ -105,10 +105,15 @@ selectable block. Adding this integration installs the
 HubSpot form into the page builder" and it makes the edits and verifies the
 typecheck. To do it by hand:
 
-1. `schemas/index.ts` — import `hubspotFormBlock`, add it to `schema.types`
+1. `schemas/components/reusable/hubspot-form.ts` — re-declare the adapter
+   through `defineBlock`, so the block is an inline object with Anchor ID and
+   Presentation Mode; export it from `schemas/components/index.ts` and add it to
+   `schema.types` in `schemas/index.ts`
 2. `page-builder-config.ts` — add `"hubspotFormBlock"` to
-   `PageBuilderDocumentType` and a `hubspotFormBlockReference` member
-3. `structure.ts` — add `S.documentTypeListItem("hubspotFormBlock")`
-4. `components/page-builder/renderer.tsx` — add a `case "hubspotFormBlock"` that
-   decodes `block.form` and renders `<HubSpotForm />`
+   `PageBuilderDocumentType` and a `pageBuilderBlockMembers` entry with
+   `pageTypes` and `category`
+3. `components/page-builder/registry.tsx` — one entry keyed `hubspotFormBlock`
+   that decodes `block.form` and renders `<HubSpotForm />`
+4. `components/page-builder/library.ts` — a fixture entry, which is what the
+   insert menu, Studio → Components and `/components` render
 5. `bun run sanity:typegen && bun typecheck`

package/src/modules/features/jobs/ashby/files/_sanity-adapter/job-board-block.ts

@@ -44,10 +44,3 @@ export const ashbyJobBoardBlock = defineType({
     },
   },
 })
-
-export const ashbyJobBoardBlockReference = defineType({
-  name: "ashbyJobBoardBlockReference",
-  title: "Ashby Job Board",
-  type: "reference",
-  to: [{ type: "ashbyJobBoardBlock" }],
-})

package/src/modules/features/jobs/ashby/files/lib/integrations/ashby/README.md

@@ -125,10 +125,16 @@ selectable block. Adding this integration installs the
 Ashby job board into the page builder" and it makes the edits and verifies the
 typecheck. To do it by hand:
 
-1. `schemas/index.ts` — import `ashbyJobBoardBlock`, add it to `schema.types`
+1. `schemas/components/reusable/ashby-job-board.ts` — re-declare the adapter
+   through `defineBlock`, so the block is an inline object with Anchor ID and
+   Presentation Mode; export it from `schemas/components/index.ts` and add it to
+   `schema.types` in `schemas/index.ts`
 2. `page-builder-config.ts` — add `"ashbyJobBoardBlock"` to
-   `PageBuilderDocumentType` and an `ashbyJobBoardBlockReference` member
-3. `structure.ts` — add `S.documentTypeListItem("ashbyJobBoardBlock")`
-4. `components/page-builder/renderer.tsx` — add a `case "ashbyJobBoardBlock"`
-   that awaits `getCareerJobs(block.boardName)` and renders the list
+   `PageBuilderDocumentType` and a `pageBuilderBlockMembers` entry with
+   `pageTypes` and `category`
+3. `components/page-builder/registry.tsx` — one entry keyed
+   `ashbyJobBoardBlock` that awaits `getCareerJobs(block.boardName)` and renders
+   the list
+4. `components/page-builder/library.ts` — a fixture entry, which is what the
+   insert menu, Studio → Components and `/components` render
 5. `bun run sanity:typegen && bun typecheck`

package/src/templates/next-default/lib/utils/README.md

@@ -45,6 +45,7 @@ export const metadata = generatePageMetadata({ title: 'About' })
 // next/image sizes — keys mirror the element's Tailwind variants
 buildImageSizes({ base: '100vw', desktop: '796px' })
 buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 })
+buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 }, { maxWidth: 1440 })
 
 // Refs — in a component, use the hook: an inline mergeRefs([...]) is a new
 // callback each render, so React detaches and reattaches every ref.

package/src/templates/next-default/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-experiments/lib/utils/README.md

@@ -45,6 +45,7 @@ export const metadata = generatePageMetadata({ title: 'About' })
 // next/image sizes — keys mirror the element's Tailwind variants
 buildImageSizes({ base: '100vw', desktop: '796px' })
 buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 })
+buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 }, { maxWidth: 1440 })
 
 // Refs — in a component, use the hook: an inline mergeRefs([...]) is a new
 // callback each render, so React detaches and reattaches every ref.

package/src/templates/next-experiments/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/AGENTS.md

@@ -11,14 +11,24 @@ 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`.
 
 ## 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.
 
@@ -33,10 +43,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/README.md

@@ -18,14 +18,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` /
@@ -54,6 +58,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/app/actions/unlock-gated-content.ts

@@ -10,13 +10,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." }
   }
@@ -27,7 +28,7 @@ export async function unlockGatedContent({
 
   const { data } = await fetchSanity<GATED_CONTENT_QUERY_RESULT>({
     query: GATED_CONTENT_QUERY,
-    params: { id: documentId },
+    params: { pageId, blockKey },
     // stega must stay off: it injects invisible characters into strings, which
     // would corrupt the asset URLs returned for download/playback.
     stega: false,

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

@@ -0,0 +1,81 @@
+import type { Metadata } from "next"
+import { notFound } from "next/navigation"
+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>
+)
+
+const Page = 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()
+
+  // Outside the `(content)` group, so `<SpacingScale />` is on this route.
+  if (entry) {
+    return (
+      <main className="flex flex-col">
+        <SpacingScale />
+        <PreviewStage entry={entry} />
+      </main>
+    )
+  }
+
+  return (
+    <main className="flex flex-col">
+      <SpacingScale />
+      {COMPONENT_LIBRARY.map((item) => (
+        <section key={item.documentType}>
+          <EntryHeader entry={item} />
+          <PreviewStage entry={item} />
+        </section>
+      ))}
+    </main>
+  )
+}
+
+export default Page

package/src/templates/next-pagebuilder/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)