bsmnt 0.11.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/files/components/ui/sanity-image/index.tsx

@@ -2,7 +2,8 @@ import { getImageDimensions } from "@sanity/asset-utils";
 import { Image, type ImageProps } from "@/components/ui/image";
 import { urlForImage } from "@/lib/integrations/sanity/utils/image";
 
-interface SanityImageProps extends Omit<ImageProps, "src" | "aspectRatio"> {
+interface SanityImageBaseProps
+	extends Omit<ImageProps, "src" | "aspectRatio" | "sizes" | "width" | "height"> {
 	image: {
 		asset?: {
 			_ref: string;
@@ -15,6 +16,38 @@ interface SanityImageProps extends Omit<ImageProps, "src" | "aspectRatio"> {
 	maxWidth?: number;
 }
 
+type SanityImageProps = SanityImageBaseProps &
+	(
+		| { sizes: string; width?: never; height?: never }
+		| { width: number; height: number; sizes?: string }
+	);
+
+const MAX_SOURCE_WIDTH = 3840;
+
+const isGifRef = (ref: string) => ref.endsWith("-gif");
+
+const getImageSrc = (
+	image: SanityImageProps["image"],
+	maxWidth: number,
+	croppedWidth: number,
+) => {
+	const builder = urlForImage(image);
+	const ref = image.asset?._ref ?? "";
+
+	if (ref.endsWith("-svg")) return builder.url();
+
+	const requestWidth = Math.min(maxWidth, MAX_SOURCE_WIDTH, croppedWidth);
+	const { left, right, top, bottom } = image.crop ?? {};
+	const hasCrop = Boolean(left || right || top || bottom);
+	const isGif = isGifRef(ref);
+
+	if (!(isGif || hasCrop) && requestWidth >= croppedWidth) {
+		return builder.url();
+	}
+
+	return builder.width(requestWidth).url();
+};
+
 export function SanityImage({
 	image,
 	maxWidth = 1920,
@@ -39,11 +72,10 @@ export function SanityImage({
 
 	return (
 		<Image
-			src={urlForImage(image)
-				.width(Math.min(maxWidth, sourceWidth))
-				.url()}
+			src={getImageSrc(image, maxWidth, sourceWidth)}
 			alt={alt || image.alt || ""}
 			aspectRatio={sourceWidth / sourceHeight}
+			unoptimized={isGifRef(image.asset._ref)}
 			{...imageProps}
 			{...props}
 		/>

package/src/modules/features/cms/sanity/files/lib/integrations/sanity/components/rich-text.tsx

@@ -37,7 +37,13 @@ export function RichText({ content }: RichTextProps) {
 			value={content}
 			components={{
 				types: {
-					image: ({ value }) => <SanityImage image={value} maxWidth={1920} />,
+					image: ({ value }) => (
+						<SanityImage
+							image={value}
+							maxWidth={1920}
+							sizes="(min-width: 768px) 768px, 100vw"
+						/>
+					),
 				},
 				marks: {
 					link: ({ children, value }) => {

package/src/modules/features/cms/sanity-pagebuilder/files/components/sanity/rich-text.tsx

@@ -42,7 +42,13 @@ export const RichText = ({ content }: RichTextProps) => {
 			value={content}
 			components={{
 				types: {
-					image: ({ value }) => <SanityImage image={value} maxWidth={1920} />,
+					image: ({ value }) => (
+						<SanityImage
+							image={value}
+							maxWidth={1920}
+							sizes="(min-width: 768px) 768px, 100vw"
+						/>
+					),
 					table: ({ value }) => {
 						const rows = value?.rows as
 							| Array<{ _key?: string; cells?: string[] }>

package/src/modules/features/cms/sanity-pagebuilder/files/components/ui/sanity-image/index.tsx

@@ -2,7 +2,8 @@ import { getImageDimensions } from "@sanity/asset-utils";
 import { Image, type ImageProps } from "@/components/ui/image";
 import { urlForImage } from "@/lib/integrations/sanity/utils/image";
 
-interface SanityImageProps extends Omit<ImageProps, "src" | "aspectRatio"> {
+interface SanityImageBaseProps
+	extends Omit<ImageProps, "src" | "aspectRatio" | "sizes" | "width" | "height"> {
 	image: {
 		asset?: {
 			_ref: string;
@@ -15,6 +16,38 @@ interface SanityImageProps extends Omit<ImageProps, "src" | "aspectRatio"> {
 	maxWidth?: number;
 }
 
+type SanityImageProps = SanityImageBaseProps &
+	(
+		| { sizes: string; width?: never; height?: never }
+		| { width: number; height: number; sizes?: string }
+	);
+
+const MAX_SOURCE_WIDTH = 3840;
+
+const isGifRef = (ref: string) => ref.endsWith("-gif");
+
+const getImageSrc = (
+	image: SanityImageProps["image"],
+	maxWidth: number,
+	croppedWidth: number,
+) => {
+	const builder = urlForImage(image);
+	const ref = image.asset?._ref ?? "";
+
+	if (ref.endsWith("-svg")) return builder.url();
+
+	const requestWidth = Math.min(maxWidth, MAX_SOURCE_WIDTH, croppedWidth);
+	const { left, right, top, bottom } = image.crop ?? {};
+	const hasCrop = Boolean(left || right || top || bottom);
+	const isGif = isGifRef(ref);
+
+	if (!(isGif || hasCrop) && requestWidth >= croppedWidth) {
+		return builder.url();
+	}
+
+	return builder.width(requestWidth).url();
+};
+
 export function SanityImage({
 	image,
 	maxWidth = 1920,
@@ -39,11 +72,10 @@ export function SanityImage({
 
 	return (
 		<Image
-			src={urlForImage(image)
-				.width(Math.min(maxWidth, sourceWidth))
-				.url()}
+			src={getImageSrc(image, maxWidth, sourceWidth)}
 			alt={alt || image.alt || ""}
 			aspectRatio={sourceWidth / sourceHeight}
+			unoptimized={isGifRef(image.asset._ref)}
 			{...imageProps}
 			{...props}
 		/>

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/page-builder-input.tsx

@@ -1,25 +1,43 @@
 import { type ArrayOfObjectsInputProps, useFormValue } from "sanity";
+import { PageBuilderInsertMenu } from "@/lib/integrations/sanity/components/page-builder-insert-menu";
+import { useStudioPreviewUrls } from "@/lib/integrations/sanity/components/use-studio-preview-urls";
 import {
+	blockPreviewKey,
 	getVisiblePageBuilderInsertMenuGroups,
-	getVisiblePageBuilderReferenceMembers,
+	getVisiblePageBuilderMemberNames,
 	type PageBuilderGroupName,
+	pageBuilderReferenceMembers,
 } from "@/lib/integrations/sanity/page-builder-config";
 
+const BLOCK_PREVIEW_KEYS = pageBuilderReferenceMembers.map((member) =>
+	blockPreviewKey(member.name),
+);
+
+function useInsertMenuViews() {
+	const previewUrls = useStudioPreviewUrls(BLOCK_PREVIEW_KEYS);
+
+	return [
+		{
+			name: "grid" as const,
+			previewImageUrl: (schemaTypeName: string) =>
+				previewUrls?.[blockPreviewKey(schemaTypeName)],
+		},
+		{ name: "list" as const },
+	];
+}
+
 export function PageBuilderInput(props: ArrayOfObjectsInputProps) {
 	const pageTypeValue = useFormValue(["type"]);
 	const pageType =
 		typeof pageTypeValue === "string"
 			? (pageTypeValue as PageBuilderGroupName)
 			: undefined;
-
-	const visibleMemberNames = new Set(
-		getVisiblePageBuilderReferenceMembers(pageType).map(
-			(member) => member.name,
-		),
-	);
+	const views = useInsertMenuViews();
+	const visibleMemberNames = getVisiblePageBuilderMemberNames(pageType);
 
 	return props.renderDefault({
 		...props,
+		arrayFunctions: PageBuilderInsertMenu,
 		schemaType: {
 			...props.schemaType,
 			of: props.schemaType.of.filter(
@@ -32,6 +50,7 @@ export function PageBuilderInput(props: ArrayOfObjectsInputProps) {
 				insertMenu: {
 					...props.schemaType.options?.insertMenu,
 					groups: getVisiblePageBuilderInsertMenuGroups(pageType),
+					views,
 				},
 			},
 		},

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/components/page-builder-insert-menu.tsx

@@ -0,0 +1,242 @@
+import { AddIcon, SearchIcon } from "@sanity/icons";
+import {
+	Box,
+	Button,
+	Card,
+	Dialog,
+	Flex,
+	Grid,
+	Stack,
+	Text,
+	TextInput,
+} from "@sanity/ui";
+import { useMemo, useState } from "react";
+import type { ArrayInputFunctionsProps, ArraySchemaType } from "sanity";
+
+type ArrayItem = { _key: string };
+type MemberSchemaType = ArraySchemaType["of"][number];
+
+type CreateItem = (memberType: MemberSchemaType) => ArrayItem;
+
+type InsertMenuSection = {
+	name: string;
+	title: string;
+	members: MemberSchemaType[];
+};
+
+const SCROLL_HEIGHT = "min(60vh, 34rem)";
+const TILE_ASPECT_RATIO = "3 / 2";
+
+const memberTitle = (member: MemberSchemaType) => member.title ?? member.name;
+
+function BlockTile({
+	member,
+	previewUrl,
+	onSelect,
+}: {
+	member: MemberSchemaType;
+	previewUrl: string | undefined;
+	onSelect: () => void;
+}) {
+	const Icon = member.icon;
+
+	return (
+		<Card
+			as="button"
+			border
+			onClick={onSelect}
+			overflow="hidden"
+			padding={0}
+			radius={2}
+			style={{ cursor: "pointer", textAlign: "left", width: "100%" }}
+			type="button"
+		>
+			<Stack space={0}>
+				<Box
+					style={{
+						aspectRatio: TILE_ASPECT_RATIO,
+						background: "var(--card-muted-bg-color)",
+						position: "relative",
+					}}
+				>
+					{previewUrl ? (
+						// biome-ignore lint/performance/noImgElement: Studio-only CMS asset
+						<img
+							alt=""
+							src={`${previewUrl}?w=640&fit=max&auto=format`}
+							style={{
+								height: "100%",
+								inset: 0,
+								objectFit: "contain",
+								position: "absolute",
+								width: "100%",
+							}}
+						/>
+					) : (
+						<Flex
+							align="center"
+							justify="center"
+							style={{ inset: 0, position: "absolute" }}
+						>
+							{Icon ? <Icon /> : null}
+						</Flex>
+					)}
+				</Box>
+				<Box padding={2}>
+					<Text size={1} textOverflow="ellipsis" weight="medium">
+						{memberTitle(member)}
+					</Text>
+				</Box>
+			</Stack>
+		</Card>
+	);
+}
+
+function InsertMenuDialog({
+	sections,
+	previewImageUrl,
+	onSelect,
+	onClose,
+}: {
+	sections: InsertMenuSection[];
+	previewImageUrl: ((schemaTypeName: string) => string | undefined) | undefined;
+	onSelect: (member: MemberSchemaType) => void;
+	onClose: () => void;
+}) {
+	const [search, setSearch] = useState("");
+
+	const visibleSections = useMemo(() => {
+		const query = search.trim().toLowerCase();
+		if (!query) return sections;
+		return sections
+			.map((section) => ({
+				...section,
+				members: section.members.filter((member) =>
+					memberTitle(member).toLowerCase().includes(query),
+				),
+			}))
+			.filter((section) => section.members.length > 0);
+	}, [search, sections]);
+
+	return (
+		<Dialog
+			header="Components"
+			id="page-builder-insert"
+			onClose={onClose}
+			open
+			width={3}
+		>
+			<Stack padding={4} space={4}>
+				<TextInput
+					autoFocus
+					icon={SearchIcon}
+					onChange={(event) => setSearch(event.currentTarget.value)}
+					placeholder="Search components…"
+					value={search}
+				/>
+				<Box style={{ height: SCROLL_HEIGHT, overflowY: "auto" }}>
+					{visibleSections.length === 0 ? (
+						<Text muted size={1}>
+							No components match “{search}”.
+						</Text>
+					) : (
+						<Stack space={5}>
+							{visibleSections.map((section) => (
+								<Stack key={section.name} space={3}>
+									<Text muted size={1} weight="semibold">
+										{section.title}
+									</Text>
+									<Grid columns={[2, 3, 4]} gap={3}>
+										{section.members.map((member) => (
+											<BlockTile
+												key={member.name}
+												member={member}
+												onSelect={() => onSelect(member)}
+												previewUrl={previewImageUrl?.(member.name)}
+											/>
+										))}
+									</Grid>
+								</Stack>
+							))}
+						</Stack>
+					)}
+				</Box>
+			</Stack>
+		</Dialog>
+	);
+}
+
+/**
+ * Pass as `arrayFunctions`. Reads `insertMenu.groups` and `insertMenu.views`, so
+ * a schema already configuring the built-in menu needs no extra wiring.
+ *
+ * Replaces the built-in popover, which is anchored to the array grid element and
+ * so clips on page scroll and resizes when switching tabs.
+ */
+export function PageBuilderInsertMenu(
+	props: ArrayInputFunctionsProps<ArrayItem, ArraySchemaType>,
+) {
+	const { onItemAppend, onValueCreate, readOnly, schemaType } = props;
+	const [open, setOpen] = useState(false);
+
+	const insertMenu = schemaType.options?.insertMenu;
+	const members = schemaType.of;
+
+	const sections = useMemo<InsertMenuSection[]>(() => {
+		const byName = new Map(members.map((member) => [member.name, member]));
+		const groups = insertMenu?.groups;
+		if (!groups) {
+			return [{ name: "all", title: "Components", members: [...members] }];
+		}
+		return groups
+			.map((group) => ({
+				name: group.name,
+				title: group.title ?? group.name,
+				members: (group.of ?? [])
+					.map((name) => byName.get(name))
+					.filter((member) => member !== undefined),
+			}))
+			.filter((section) => section.members.length > 0);
+	}, [members, insertMenu]);
+
+	const previewImageUrl = useMemo(() => {
+		const gridView = insertMenu?.views?.find((view) => view.name === "grid");
+		return gridView && "previewImageUrl" in gridView
+			? gridView.previewImageUrl
+			: undefined;
+	}, [insertMenu]);
+
+	const insert = (member: MemberSchemaType) => {
+		onItemAppend((onValueCreate as unknown as CreateItem)(member));
+		setOpen(false);
+	};
+
+	const onlyMember = members.length === 1 ? members[0] : undefined;
+
+	if (schemaType.options?.disableActions?.includes("add")) return null;
+
+	return (
+		<>
+			<Grid>
+				<Button
+					disabled={readOnly === true}
+					fontSize={1}
+					icon={AddIcon}
+					mode="ghost"
+					onClick={() => (onlyMember ? insert(onlyMember) : setOpen(true))}
+					padding={3}
+					text={onlyMember ? "Add item" : "Add item…"}
+				/>
+			</Grid>
+
+			{open && (
+				<InsertMenuDialog
+					onClose={() => setOpen(false)}
+					onSelect={insert}
+					previewImageUrl={previewImageUrl}
+					sections={sections}
+				/>
+			)}
+		</>
+	);
+}