bsmnt 0.12.0 → 0.13.0

package/src/agent-skills/page-builder-block/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: page-builder-block
+description: >-
+  Create or modify a Sanity page-builder block in a basement page-builder
+  project so it follows the repo conventions: defined with `defineBlock`, drawn
+  through the renderer's block registry, Anchor ID (generated from the title
+  when empty), Presentation Mode, and spacing owned by the frame that instances
+  the block rather than the block itself. Use when asked to "add a block to the
+  page builder", "create a new section/component for Sanity", "add anchor links
+  to a block", "control the spacing of a block from Sanity", or when reviewing
+  an existing block for these rules.
+---
+
+# Page-builder block conventions
+
+Blocks are **documents** referenced from the `pageBuilder` array, drawn by
+`components/page-builder/renderer.tsx` through the registry in
+`components/page-builder/registry.tsx`. Read one existing block end to end
+before writing a new one — `hero` is the smallest complete example:
+
+- schema: `lib/integrations/sanity/schemas/components/reusable/hero.ts`
+- component: `components/page-builder/components/hero.tsx`
+- registration: `lib/integrations/sanity/schemas/components/index.ts`,
+  `lib/integrations/sanity/schemas/index.ts`,
+  `lib/integrations/sanity/page-builder-config.ts`,
+  `lib/integrations/sanity/structure.ts`,
+  `components/page-builder/registry.tsx`
+
+A block exists in two halves — a schema and a component — and each half has one
+place that makes it a block rather than an ordinary document or a loose React
+component. Use them and the conventions below come for free; skip them and a
+typecheck fails.
+
+## Non-negotiables
+
+1. **Define the schema with `defineBlock`, never `defineType`.**
+   `lib/integrations/sanity/schemas/shared/block.ts` implies
+   `type: "document"` and appends Anchor ID + Presentation Mode as the last two
+   fields:
+
+   ```ts
+   import { defineField } from "sanity"
+   import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block"
+
+   export const featureGrid = defineBlock({
+     name: "featureGrid",
+     title: "Feature Grid",
+     icon: featureGridIcon,
+     fields: [
+       // ...content fields...
+     ],
+     preview: { /* ... */ },
+   })
+   ```
+
+   What it adds:
+   - `anchorId` — optional. Left empty, the anchor is **generated from the
+     block's title** at render time (`resolveAnchorId` in
+     `lib/integrations/sanity/schemas/shared/anchor.ts` walks `headline`,
+     `heading`, `teaserHeading`, `title`, `label` — never `internalTitle`, which
+     is Studio-only) and de-duplicated per page. A value typed by hand always
+     wins. Name your block's headline field one of those and it works for free.
+   - `presentation` — object with `paddingTop` / `paddingBottom`, each storing
+     the `_key` of a step from the shared scale. No manual px, ever. A block
+     that never touches it follows whichever step is marked as the default.
+
+   Blocks that declare `groups` get a **Presentation** tab for the two fields,
+   added automatically — don't list it in `groups` yourself. A block with no
+   groups shows them inline, at the bottom of the form.
+
+2. **Register the component in the block registry.** One entry per block, keyed
+   by schema type; the renderer has no switch to extend:
+
+   ```tsx
+   featureGrid: {
+     render: (block) => <FeatureGrid block={block} />,
+     isEmpty: (block) => !block.items?.length,
+   },
+   ```
+
+   - `render` receives the block narrowed to its own `_type`, plus a
+     `BlockContext` for page-level values a block doesn't own (`searchParams`,
+     `pinnedCategory`). Take the second argument only if you need it.
+   - `isEmpty` is optional and declares when the block has nothing to show. The
+     renderer then skips the block **and** its `<Section>`, so an unfilled block
+     leaves no padded gap behind and doesn't claim an anchor id. Don't
+     early-return `null` from the component instead — the renderer has to know
+     before it wraps anything.
+
+   The registry's key set is typed as exactly `PageBuilderDocumentType`, so a
+   block registered in `page-builder-config.ts` without an entry here — or an
+   entry here for a block that was never registered there — is a typecheck
+   error.
+
+3. **Never hardcode vertical padding inside a block component.** The renderer
+   wraps every block in `<Section>` (`components/page-builder/section.tsx`),
+   which renders the `<section>` element, applies the anchor `id` and the
+   padding. A block 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 (`gap-*`, `space-y-*`, `mt-*` on children).
+
+4. **The spacing scale is content, not code.** Editors own it at **Layout →
+   Spacing Scale** (`spacingSettings`): a list of steps, each with a name, px
+   per breakpoint (mobile / tablet / desktop, empty reuses Desktop) and one
+   marked as the default — ticking a second one unticks the previous, so there
+   is always exactly one. They add, rename or remove steps without touching
+   code; when the list is empty the field offers an "Add the built-in steps"
+   button that seeds it.
+   `lib/integrations/sanity/schemas/shared/spacing.ts` holds the five built-in
+   steps (XS · SM · MD · LG · XL, MD default) used to seed the document and as
+   the fallback when it is empty, plus the resolver and the CSS builder.
+
+   Resolved values ship as CSS custom properties from
+   `components/layout/spacing-scale/index.tsx` (rendered by
+   `app/(content)/layout.tsx`), one `--section-space-<step key>` per step plus
+   `--section-space-default`, re-declared inside `min-width: 768px` and
+   `1440px` media queries. `Section` only references
+   `var(--section-space-<key>, var(--section-space-default, 2.5rem))`, so a
+   deleted or unknown step degrades to the default instead of breaking, and
+   **changing a value never requires a deploy**.
+
+   Publishing `spacingSettings` busts the layout cache: it is in
+   `SANITY_LAYOUT_TAGS` (`fetchers/layout.ts`, or `tags.ts` on the Cache
+   Components variant), same as navbar and footer.
+
+5. **Regenerate types after a schema change:** `bun run sanity:typegen`. The
+   page query spreads `...` for non-gated blocks, so new fields flow through
+   automatically — except `gatedContent`, whose GROQ branch lists fields
+   explicitly (`lib/integrations/sanity/queries.ts`). Add new fields there by
+   hand if the block is gated.
+
+## Checklist for a new block
+
+- [ ] Schema in `schemas/components/reusable/<block>.ts` (or `singleton/` for a
+      one-instance block), built with `defineBlock` and carrying a `preview`.
+- [ ] Icon in `lib/integrations/sanity/icons.ts` (phosphor duotone).
+- [ ] Exported from `schemas/components/index.ts` and registered in
+      `schemas/index.ts` (`schema.types`).
+- [ ] Member added to `page-builder-config.ts`: the `PageBuilderDocumentType`
+      union plus an entry in `reusablePageBuilderReferenceMembers` carrying
+      **both** axes — `pageTypes` (which page documents may host it) and
+      `category` (what the block is, one of `componentCategories`; `misc` only
+      when nothing fits).
+- [ ] Listed in `structure.ts` under the right folder.
+- [ ] Component in `components/page-builder/components/<block>.tsx`, typed with
+      `Extract<PageBuilderBlock, { _type: "<block>" }>`, no outer section, no
+      vertical padding. Variants via `cva`/`cn` when the block has variants.
+- [ ] Entry in `components/page-builder/registry.tsx`, with `isEmpty` when the
+      block can be left unfilled.
+- [ ] `bun run sanity:typegen && bun run typecheck && bun run lint && bun run build && bun run knip`.

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/components/anchor-id-input.tsx

@@ -0,0 +1,17 @@
+import { type StringInputProps, useFormValue } from "sanity";
+import { deriveAnchorId } from "@/lib/integrations/sanity/schemas/shared/anchor";
+
+export function AnchorIdInput(props: StringInputProps) {
+	const document = useFormValue([]) as Record<string, unknown> | undefined;
+	const derived = deriveAnchorId(document ?? {});
+
+	return props.renderDefault({
+		...props,
+		elementProps: {
+			...props.elementProps,
+			placeholder: derived
+				? `${derived} — generated from the title`
+				: "generated from the title",
+		},
+	});
+}

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/components/presentation-input.tsx

@@ -0,0 +1,146 @@
+import { Box, Card, Flex, Select, Stack, Text } from "@sanity/ui";
+import { useEffect, useState } from "react";
+import { type ObjectInputProps, set, setIfMissing, useClient } from "sanity";
+import { apiVersion } from "@/lib/integrations/sanity/env";
+import {
+	paddingBottomIcon,
+	paddingTopIcon,
+	type SanityStudioIcon,
+} from "@/lib/integrations/sanity/icons";
+import {
+	getDefaultSpacingStep,
+	resolveSpacingSteps,
+	type SpacingStep,
+	type SpacingStepSource,
+	spacingStepOptions,
+} from "@/lib/integrations/sanity/schemas/shared/spacing";
+
+const SPACING_STEPS_QUERY = `coalesce(
+	*[_id == "drafts.spacingSettings"][0],
+	*[_id == "spacingSettings"][0]
+).steps[]{ _key, name, mobile, tablet, desktop, isDefault }`;
+
+type PaddingField = "paddingTop" | "paddingBottom";
+
+type PresentationValue = Partial<Record<PaddingField, string>>;
+
+function useSpacingSteps() {
+	const client = useClient({ apiVersion });
+	const [steps, setSteps] = useState<SpacingStep[]>(() =>
+		resolveSpacingSteps(null),
+	);
+
+	useEffect(() => {
+		let active = true;
+		client
+			.fetch<SpacingStepSource[] | null>(SPACING_STEPS_QUERY)
+			.then((rows) => {
+				if (active) setSteps(resolveSpacingSteps(rows));
+			})
+			.catch(() => setSteps(resolveSpacingSteps(null)));
+		return () => {
+			active = false;
+		};
+	}, [client]);
+
+	return steps;
+}
+
+type SpacingRowProps = {
+	name: PaddingField;
+	label: string;
+	icon: SanityStudioIcon;
+	options: Array<{ value: string; title: string }>;
+	value: string;
+	onSelect: (name: PaddingField, next: string) => void;
+};
+
+function SpacingRow({
+	name,
+	label,
+	icon,
+	options,
+	value,
+	onSelect,
+}: SpacingRowProps) {
+	const Icon = icon;
+
+	return (
+		<Flex align="center" gap={2}>
+			<Card
+				padding={2}
+				radius={2}
+				tone="transparent"
+				border
+				title={label}
+				aria-hidden
+			>
+				<Text size={2}>
+					<Icon />
+				</Text>
+			</Card>
+			<Box flex={1}>
+				<Select
+					aria-label={label}
+					fontSize={1}
+					padding={3}
+					radius={2}
+					value={value}
+					onChange={(event) => onSelect(name, event.currentTarget.value)}
+				>
+					{options.map((option) => (
+						<option key={option.value} value={option.value}>
+							{option.title}
+						</option>
+					))}
+				</Select>
+			</Box>
+		</Flex>
+	);
+}
+
+export function PresentationInput(props: ObjectInputProps) {
+	const value = props.value as PresentationValue | undefined;
+	const steps = useSpacingSteps();
+	const options = spacingStepOptions(steps);
+	const fallback = getDefaultSpacingStep(steps).key;
+
+	const resolve = (key: string | undefined) =>
+		steps.some((step) => step.key === key) ? (key as string) : fallback;
+
+	const handleSelect = (name: PaddingField, next: string) => {
+		props.onChange([setIfMissing({}), set(next, [name])]);
+	};
+
+	return (
+		<Stack space={3}>
+			<Flex gap={3} wrap="wrap">
+				<Box flex={1} style={{ minWidth: 200 }}>
+					<SpacingRow
+						name="paddingTop"
+						label="Padding top"
+						icon={paddingTopIcon}
+						options={options}
+						value={resolve(value?.paddingTop)}
+						onSelect={handleSelect}
+					/>
+				</Box>
+				<Box flex={1} style={{ minWidth: 200 }}>
+					<SpacingRow
+						name="paddingBottom"
+						label="Padding bottom"
+						icon={paddingBottomIcon}
+						options={options}
+						value={resolve(value?.paddingBottom)}
+						onSelect={handleSelect}
+					/>
+				</Box>
+			</Flex>
+			<Text size={1} muted>
+				Spacing above and below this block, from the shared scale (edit the steps
+				in Layout → Spacing Scale). Untouched blocks follow whichever step is
+				marked as the default.
+			</Text>
+		</Stack>
+	);
+}

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/components/spacing-steps-input.tsx

@@ -0,0 +1,84 @@
+import { Button, Card, Stack, Text } from "@sanity/ui";
+import { useEffect, useRef } from "react";
+import { type ArrayOfObjectsInputProps, set } from "sanity";
+import { defaultSpacingSteps } from "@/lib/integrations/sanity/schemas/shared/spacing";
+
+type StepValue = { _key?: string; isDefault?: boolean };
+
+const defaultKeysOf = (value: StepValue[] | undefined) =>
+	(value ?? [])
+		.filter((step) => step?.isDefault === true)
+		.flatMap((step) => (step._key ? [step._key] : []));
+
+export function SpacingStepsInput(props: ArrayOfObjectsInputProps) {
+	const value = props.value as StepValue[] | undefined;
+	const { onChange } = props;
+
+	const defaultKeys = defaultKeysOf(value);
+	const defaultKeysId = defaultKeys.join(",");
+	const lastSingleDefault = useRef<string | undefined>(defaultKeys[0]);
+
+	useEffect(() => {
+		const keys = defaultKeysId ? defaultKeysId.split(",") : [];
+
+		if (keys.length < 2) {
+			lastSingleDefault.current = keys[0];
+			return;
+		}
+
+		const keep = keys.find((key) => key !== lastSingleDefault.current) ?? keys[0];
+		lastSingleDefault.current = keep;
+
+		onChange(
+			keys
+				.filter((key) => key !== keep)
+				.map((key) => set(false, [{ _key: key }, "isDefault"])),
+		);
+	}, [defaultKeysId, onChange]);
+
+	const seed = () => {
+		onChange(
+			set(
+				defaultSpacingSteps.map((step) => ({
+					_key: step.key,
+					_type: "spacingStep",
+					name: step.name,
+					mobile: step.mobile,
+					tablet: step.tablet,
+					desktop: step.desktop,
+					isDefault: step.isDefault,
+				})),
+			),
+		);
+	};
+
+	return (
+		<Stack space={3}>
+			{props.renderDefault(props)}
+			{value?.length ? null : (
+				<Card padding={3} radius={2} border tone="primary">
+					<Stack space={3}>
+						<Text size={1}>
+							No steps yet, so blocks fall back to the built-in scale:{" "}
+							{defaultSpacingSteps
+								.map(
+									(step) =>
+										`${step.name} ${step.desktop}px${
+											step.isDefault ? " (default)" : ""
+										}`,
+								)
+								.join(" · ")}
+							.
+						</Text>
+						<Button
+							text="Add the built-in steps"
+							tone="primary"
+							mode="ghost"
+							onClick={seed}
+						/>
+					</Stack>
+				</Card>
+			)}
+		</Stack>
+	);
+}

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/fetchers/layout.ts

@@ -8,6 +8,7 @@ export type NavbarData = NonNullable<LayoutData["navbar"]>;
 export type FooterData = NonNullable<LayoutData["footer"]>;
 export type CompanyData = NonNullable<LayoutData["companyData"]>;
 export type StructuredData = NonNullable<LayoutData["structuredData"]>;
+export type SpacingSettings = NonNullable<LayoutData["spacingSettings"]>;
 
 // Singleton document types that, when published, should bust the layout cache.
 export const SANITY_LAYOUT_TAGS = [
@@ -15,6 +16,7 @@ export const SANITY_LAYOUT_TAGS = [
 	"footer",
 	"companyData",
 	"structuredData",
+	"spacingSettings",
 ];
 
 const EMPTY_LAYOUT: LayoutData = {
@@ -22,11 +24,12 @@ const EMPTY_LAYOUT: LayoutData = {
 	footer: null,
 	companyData: null,
 	structuredData: null,
+	spacingSettings: null,
 };
 
-// One query for all four layout singletons, wrapped in React cache so the header,
-// footer and json-ld share a single round trip. Tagged with all four `_type` tags
-// because it reads all four documents.
+// One query for every layout singleton, wrapped in React cache so the header,
+// footer, json-ld and spacing scale share a single round trip. Tagged with each
+// `_type` because it reads all of those documents.
 export const getLayoutData = cache(async (): Promise<LayoutData> => {
 	const { data } = await fetchSanity<LayoutData>({
 		query: LAYOUT_QUERY,

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/icons.ts

@@ -2,6 +2,9 @@ import type { Icon, IconProps } from "@phosphor-icons/react";
 import {
 	AppWindowIcon,
 	ArrowBendUpRightIcon,
+	ArrowLineDownIcon,
+	ArrowLineUpIcon,
+	ArrowsOutLineVerticalIcon,
 	ArticleNyTimesIcon,
 	BracketsCurlyIcon,
 	BriefcaseIcon,
@@ -75,6 +78,11 @@ export const richTextIcon = asDuotoneIcon(TextTIcon);
 export const contentIcon = asDuotoneIcon(ArticleNyTimesIcon);
 export const gatedContentIcon = asDuotoneIcon(LockKeyIcon);
 
+export const spacingSettingsIcon = asDuotoneIcon(ArrowsOutLineVerticalIcon);
+
+export const paddingTopIcon = asDuotoneIcon(ArrowLineUpIcon);
+export const paddingBottomIcon = asDuotoneIcon(ArrowLineDownIcon);
+
 export const pageIcon = asDuotoneIcon(FileTextIcon);
 export const pagesFolderIcon = asDuotoneIcon(BrowsersIcon);
 export const pageFolderIcon = asDuotoneIcon(FolderOpenIcon);

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/queries.ts

@@ -96,6 +96,8 @@ const pageBuilderProjection = `
       _type == "gatedContent" => {
         _id,
         _type,
+        anchorId,
+        presentation,
         internalTitle,
         teaserHeading,
         teaserBody[]{
@@ -533,6 +535,16 @@ export const LAYOUT_QUERY = defineQuery(`
     },
     "structuredData": *[_type == "structuredData"][0]{
       ${structuredDataProjection}
+    },
+    "spacingSettings": *[_type == "spacingSettings"][0]{
+      steps[]{
+        _key,
+        name,
+        mobile,
+        tablet,
+        desktop,
+        isDefault
+      }
     }
   }
 `);

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/schemas/components/reusable/blog-content.ts

@@ -1,10 +1,10 @@
-import { defineField, defineType } from "sanity";
+import { defineField } from "sanity";
 import { contentIcon } from "@/lib/integrations/sanity/icons";
+import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block";
 
-export const blogContent = defineType({
+export const blogContent = defineBlock({
 	name: "blogContent",
 	title: "Blog Content",
-	type: "document",
 	icon: contentIcon,
 	fields: [
 		defineField({

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/schemas/components/reusable/description.ts

@@ -1,10 +1,10 @@
-import { defineField, defineType } from "sanity";
+import { defineField } from "sanity";
 import { descriptionIcon } from "@/lib/integrations/sanity/icons";
+import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block";
 
-export const description = defineType({
+export const description = defineBlock({
 	name: "description",
 	title: "Description",
-	type: "document",
 	icon: descriptionIcon,
 	fields: [
 		defineField({

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/schemas/components/reusable/gated-content.ts

@@ -1,5 +1,6 @@
-import { defineField, defineType } from "sanity";
+import { defineField } from "sanity";
 import { gatedContentIcon } from "@/lib/integrations/sanity/icons";
+import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block";
 
 type GatedContentParent = { kind?: string };
 
@@ -19,10 +20,9 @@ const requiredForKind =
 		return isEmpty ? message : true;
 	};
 
-export const gatedContent = defineType({
+export const gatedContent = defineBlock({
 	name: "gatedContent",
 	title: "Gated Content",
-	type: "document",
 	icon: gatedContentIcon,
 	description:
 		"Content hidden behind a lead-capture gate. Everyone sees the teaser; the payload is withheld from the page until the visitor submits the form.",

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/schemas/components/reusable/hero.ts

@@ -1,10 +1,10 @@
-import { defineField, defineType } from "sanity";
+import { defineField } from "sanity";
 import { heroIcon } from "@/lib/integrations/sanity/icons";
+import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block";
 
-export const hero = defineType({
+export const hero = defineBlock({
 	name: "hero",
 	title: "Heading",
-	type: "document",
 	icon: heroIcon,
 	fields: [
 		defineField({

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/schemas/components/reusable/rich-text-block.ts

@@ -1,10 +1,10 @@
-import { defineField, defineType } from "sanity";
+import { defineField } from "sanity";
 import { richTextIcon } from "@/lib/integrations/sanity/icons";
+import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block";
 
-export const richTextBlock = defineType({
+export const richTextBlock = defineBlock({
 	name: "richTextBlock",
 	title: "Rich Text",
-	type: "document",
 	icon: richTextIcon,
 	fields: [
 		defineField({

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/schemas/components/singleton/content-collection.ts

@@ -1,6 +1,7 @@
-import { defineField, defineType } from "sanity";
+import { defineField } from "sanity";
 import type { SanityStudioIcon } from "@/lib/integrations/sanity/icons";
 import { pageListIcon } from "@/lib/integrations/sanity/icons";
+import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block";
 
 function createContentCollection(config: {
 	name: string;
@@ -8,10 +9,9 @@ function createContentCollection(config: {
 	icon: SanityStudioIcon;
 	label: string;
 }) {
-	return defineType({
+	return defineBlock({
 		name: config.name,
 		title: config.title,
-		type: "document",
 		icon: config.icon,
 		description: `This component contains all the ${config.label}`,
 		fields: [

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/schemas/index.ts

@@ -23,6 +23,7 @@ import { companyData } from "./layout/company-data";
 import { footer } from "./layout/footer";
 import { navbar } from "./layout/navbar";
 import { redirect } from "./layout/redirect";
+import { spacingSettings, spacingStep } from "./layout/spacing-settings";
 import { structuredData } from "./layout/structured-data";
 import { externalLink, link, pageReference } from "./shared/link";
 import { metadata } from "./shared/metadata";
@@ -35,6 +36,7 @@ import {
 import { page } from "./shared/page";
 import { pageBuilder } from "./shared/page-builder";
 import { pageFolder } from "./shared/page-folder";
+import { presentation } from "./shared/presentation";
 import { richText } from "./shared/richText";
 import {
 	customJsonLd,
@@ -74,9 +76,12 @@ export {
 	pageBuilder,
 	pageFolder,
 	pageReference,
+	presentation,
 	redirect,
 	richText,
 	softwareApplicationJsonLd,
+	spacingSettings,
+	spacingStep,
 	structuredData,
 	studioPreview,
 	videoJsonLd,
@@ -91,6 +96,7 @@ export const schema: { types: SchemaTypeDefinition[] } = {
 		link,
 		metadata,
 		pageBuilder,
+		presentation,
 		richText,
 
 		// Page-level JSON-LD blocks (selectable in metadata)
@@ -122,6 +128,8 @@ export const schema: { types: SchemaTypeDefinition[] } = {
 		navbar,
 		footer,
 		structuredData,
+		spacingStep,
+		spacingSettings,
 
 		// Layout collections (managed lists, not singletons)
 		redirect,