@ingram-tech/nk-blog 0.1.5 → 0.1.6

package/src/render.tsx

@@ -0,0 +1,94 @@
+import { evaluate } from "@mdx-js/mdx";
+import type { ComponentType, ReactElement } from "react";
+import * as runtime from "react/jsx-runtime";
+import Markdown, { type Components } from "react-markdown";
+import remarkGfm from "remark-gfm";
+import type { PluggableList } from "unified";
+import type { BlogComponents } from "./contract.js";
+import { remarkLimitedMdx } from "./limited-mdx.js";
+import type { BlogPost } from "./types.js";
+
+export { remarkLimitedMdx, validateLimitedMdx } from "./limited-mdx.js";
+export type {
+	LimitedMdxOptions,
+	LimitedMdxResult,
+	LimitedMdxViolation,
+} from "./limited-mdx.js";
+
+/**
+ * The element map a site passes to style prose (h1–h4, p, code, tables, …).
+ * One key set shared by both pipelines — react-markdown's `Components` is the
+ * canonical shape. The map itself never ships from nk-blog: it is the brand.
+ */
+export type BlogElements = Components;
+
+// Per-post (Tier-2) components, merged over the site vocabulary in MDX scope.
+export type BespokeComponents = Record<string, ComponentType<never>>;
+
+/** Renders a `.md` body. Pure data — the automated publisher's format. */
+export const MarkdownBody: React.FC<{
+	content: string;
+	elements?: BlogElements;
+}> = ({ content, elements }) => (
+	<Markdown remarkPlugins={[remarkGfm]} components={elements}>
+		{content}
+	</Markdown>
+);
+
+/**
+ * Renders an `.mdx` body (async server component). `limited` (default true)
+ * enforces the vocabulary-only trust boundary; Tier-2 posts pass `bespoke`
+ * components, which turns enforcement off — those are human-reviewed code.
+ */
+export async function MdxBody(props: {
+	content: string;
+	components: BlogComponents;
+	elements?: BlogElements;
+	bespoke?: BespokeComponents;
+	limited?: boolean;
+}): Promise<ReactElement> {
+	// An *empty* bespoke map (a site conditionally spreading a possibly-empty
+	// registry) must not silently switch off the trust boundary — only actual
+	// human-reviewed components do.
+	const limited = props.limited ?? Object.keys(props.bespoke ?? {}).length === 0;
+	const scope = { ...props.components, ...props.bespoke };
+	const remarkPlugins: PluggableList = limited
+		? [remarkGfm, [remarkLimitedMdx, { allow: Object.keys(scope) }]]
+		: [remarkGfm];
+	const { default: MDXContent } = await evaluate(props.content, {
+		...runtime,
+		remarkPlugins,
+	});
+	return <MDXContent components={{ ...props.elements, ...scope }} />;
+}
+
+/** Format-dispatching renderer: the one component a post page needs. */
+export async function PostBody(props: {
+	post: BlogPost;
+	components: BlogComponents;
+	elements?: BlogElements;
+	bespoke?: BespokeComponents;
+}): Promise<ReactElement> {
+	if (props.post.format === "md") {
+		return <MarkdownBody content={props.post.content} elements={props.elements} />;
+	}
+	return MdxBody({
+		content: props.post.content,
+		components: props.components,
+		elements: props.elements,
+		bespoke: props.bespoke,
+	});
+}
+
+/**
+ * The hardened JSON-LD script tag, re-exported from nk-seo so it sits with the
+ * node builders that feed it (`blogPostArticle`, `blogPostBreadcrumbs`).
+ *
+ * nk-blog hands sites schema *nodes* and left rendering to them, which meant
+ * every site hand-rolled `<script type="application/ld+json"
+ * dangerouslySetInnerHTML={{ __html: JSON.stringify(nodes) }} />` — and a post
+ * title or FAQ answer containing `</script>` then closes the tag and injects
+ * markup into the page. `JsonLd` escapes `<`, so the safe path is now the one
+ * already in reach.
+ */
+export { JsonLd, serializeJsonLd } from "@ingram-tech/nk-seo/components";

package/src/rss.ts

@@ -0,0 +1,71 @@
+import type { BlogPostPreview } from "./types.js";
+
+export interface RssConfig {
+	title: string;
+	description?: string;
+	/** Absolute site origin, e.g. "https://example.com". */
+	siteUrl: string;
+	/** Path prefix of the blog, e.g. "/posts". */
+	basePath: string;
+	/** Absolute URL the feed is served from, e.g. `${siteUrl}/rss.xml`. */
+	feedUrl: string;
+	language?: string;
+}
+
+const escapeXml = (value: string): string =>
+	value
+		// XML 1.0 forbids most C0 controls even escaped — a stray \x08 pasted
+		// into a title would make strict parsers reject the whole feed.
+		// oxlint-disable-next-line no-control-regex -- stripping XML-invalid chars is the point
+		.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, "")
+		.replaceAll("&", "&")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;");
+
+/**
+ * RSS 2.0 feed for a post list. Serve from a route handler (`rss.xml/route.ts`
+ * with `export const dynamic = "force-static"`) so it renders at build.
+ */
+export function generateRss(config: RssConfig, posts: BlogPostPreview[]): string {
+	const items = posts
+		.map((post) => {
+			const url = `${config.siteUrl}${config.basePath}/${post.slug}`;
+			return [
+				"\t\t<item>",
+				`\t\t\t<title>${escapeXml(post.title)}</title>`,
+				`\t\t\t<link>${escapeXml(url)}</link>`,
+				`\t\t\t<guid isPermaLink="true">${escapeXml(url)}</guid>`,
+				`\t\t\t<pubDate>${new Date(post.date).toUTCString()}</pubDate>`,
+				`\t\t\t<description>${escapeXml(post.description)}</description>`,
+				...post.authors.map(
+					(author) => `\t\t\t<dc:creator>${escapeXml(author)}</dc:creator>`,
+				),
+				...(post.category
+					? [`\t\t\t<category>${escapeXml(post.category)}</category>`]
+					: []),
+				"\t\t</item>",
+			].join("\n");
+		})
+		.join("\n");
+
+	return [
+		'<?xml version="1.0" encoding="UTF-8"?>',
+		'<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">',
+		"\t<channel>",
+		`\t\t<title>${escapeXml(config.title)}</title>`,
+		`\t\t<link>${escapeXml(config.siteUrl + config.basePath)}</link>`,
+		`\t\t<description>${escapeXml(config.description ?? config.title)}</description>`,
+		`\t\t<language>${escapeXml(config.language ?? "en")}</language>`,
+		`\t\t<atom:link href="${escapeXml(config.feedUrl)}" rel="self" type="application/rss+xml"/>`,
+		...(posts[0]
+			? [
+					`\t\t<lastBuildDate>${new Date(posts[0].date).toUTCString()}</lastBuildDate>`,
+				]
+			: []),
+		items,
+		"\t</channel>",
+		"</rss>",
+		"",
+	].join("\n");
+}

package/src/schema.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+
+// YAML (via gray-matter) parses bare dates like `2026-04-30` into Date objects
+// and quoted ones into strings — accept both, emit ISO 8601.
+const isoDate = z.union([z.string(), z.date()]).transform((value, ctx) => {
+	const parsed = value instanceof Date ? value : new Date(value);
+	if (Number.isNaN(parsed.getTime())) {
+		ctx.addIssue({
+			code: "custom",
+			message: `Invalid date "${String(value)}". Use ISO format (YYYY-MM-DD).`,
+		});
+		return z.NEVER;
+	}
+	return parsed.toISOString();
+});
+
+const nonEmpty = z.string().trim().min(1);
+
+/**
+ * Slug shape shared by the frontmatter contract and the publisher: alnum runs
+ * separated by single `-`/`_`/`.`. Rules out everything that breaks routes,
+ * RSS/JSON-LD URLs, or — via the publisher's `${dir}/${slug}.md` commit path —
+ * traverses into arbitrary repo locations (`../.github/workflows/x`).
+ */
+export const slugPattern = /^[a-z0-9]+(?:[-._][a-z0-9]+)*$/;
+
+const slugSchema = z
+	.string()
+	.regex(
+		slugPattern,
+		"Slug must be lowercase alphanumerics separated by single '-', '_' or '.'",
+	);
+
+/**
+ * The shared frontmatter contract. Every post on every site validates against
+ * this; unknown keys are preserved-ignored (sites may carry extras locally).
+ *
+ * Normalizations: `coverImage` is accepted as an alias of `image`; `author`
+ * (string or list) and `authors` collapse into a single `authors: string[]`.
+ */
+export const blogFrontmatterSchema = z
+	.object({
+		title: nonEmpty,
+		seoTitle: nonEmpty.optional(),
+		description: nonEmpty,
+		date: isoDate,
+		updated: isoDate.optional(),
+		author: z.union([nonEmpty, z.array(nonEmpty)]).optional(),
+		authors: z.array(nonEmpty).optional(),
+		category: nonEmpty.optional(),
+		tags: z.array(nonEmpty).default([]),
+		image: nonEmpty.optional(),
+		coverImage: nonEmpty.optional(),
+		slug: slugSchema.optional(),
+		draft: z.boolean().default(false),
+		featured: z.boolean().default(false),
+		// Reserved fields — validated now so adding behavior later isn't breaking.
+		lang: nonEmpty.optional(),
+		canonical: nonEmpty.optional(),
+	})
+	.transform(({ author, authors, coverImage, image, ...rest }) => ({
+		...rest,
+		image: image ?? coverImage,
+		authors: authors ?? (Array.isArray(author) ? author : author ? [author] : []),
+	}));
+
+export type BlogFrontmatter = z.infer<typeof blogFrontmatterSchema>;
+export type BlogFrontmatterInput = z.input<typeof blogFrontmatterSchema>;

package/src/seo.ts

@@ -0,0 +1,69 @@
+import {
+	article,
+	type ArticleInput,
+	type ArticleNode,
+	breadcrumbList,
+	type BreadcrumbListNode,
+	type OrganizationInput,
+	type WithContext,
+} from "@ingram-tech/nk-seo";
+import type { BlogPostPreview } from "./types.js";
+
+export interface BlogSeoConfig {
+	/** Absolute site origin, e.g. "https://example.com". */
+	baseUrl: string;
+	/** Path prefix of the blog, e.g. "/posts" or "/blog". */
+	basePath: string;
+	/** Injected as the article publisher when provided. */
+	publisher?: OrganizationInput;
+	/** Crumb label for the blog index; defaults to "Blog". */
+	blogName?: string;
+}
+
+export function postUrl(post: BlogPostPreview, config: BlogSeoConfig): string {
+	return `${config.baseUrl}${config.basePath}/${post.slug}`;
+}
+
+// JSON-LD consumers don't resolve relative URLs, so anything without a scheme
+// (leading-`/` or bare `img/x.png`) is absolutized against the site. Unlike
+// nk-seo's `absoluteUrl`, an already-absolute value passes through untouched
+// rather than being origin-checked: a post's image can live on a CDN and its
+// `canonical` can be a cross-origin syndication override, both legitimately
+// off-origin — so this must not throw the way the canonical-link resolver does.
+const toAbsoluteUrl = (url: string, baseUrl: string): string =>
+	/^https?:\/\//.test(url)
+		? url
+		: `${baseUrl}${url.startsWith("/") ? "" : "/"}${url}`;
+
+/** BlogPosting JSON-LD for a post — the nk-seo bridge. */
+export function blogPostArticle(
+	post: BlogPostPreview,
+	config: BlogSeoConfig,
+	overrides: Partial<ArticleInput> = {},
+): WithContext<ArticleNode> {
+	return article({
+		type: "BlogPosting",
+		headline: post.title,
+		description: post.description,
+		url: toAbsoluteUrl(post.canonical ?? postUrl(post, config), config.baseUrl),
+		datePublished: post.date,
+		dateModified: post.updated,
+		authors: post.authors.map((name) => ({ name })),
+		image: post.image ? toAbsoluteUrl(post.image, config.baseUrl) : undefined,
+		keywords: post.tags.length ? post.tags : undefined,
+		publisher: config.publisher,
+		...overrides,
+	});
+}
+
+/** Home → Blog → Post breadcrumb JSON-LD. */
+export function blogPostBreadcrumbs(
+	post: BlogPostPreview,
+	config: BlogSeoConfig,
+): WithContext<BreadcrumbListNode> {
+	return breadcrumbList([
+		{ name: "Home", url: config.baseUrl },
+		{ name: config.blogName ?? "Blog", url: `${config.baseUrl}${config.basePath}` },
+		{ name: post.title, url: postUrl(post, config) },
+	]);
+}

package/src/server.ts

@@ -0,0 +1,22 @@
+// Server entry: everything that touches the filesystem, the GitHub API, or
+// env. Import from pages/route handlers/scripts only — never from client
+// components (the root "." export carries the types you need there).
+export {
+	createBlog,
+	parsePost,
+	parsePostFileName,
+	type Blog,
+	type BlogConfig,
+	type BlogSource,
+	type RawPostFile,
+} from "./blog.js";
+export { fsSource } from "./sources/fs.js";
+export { githubSource, type GitHubRepoConfig } from "./sources/github.js";
+export {
+	publishPost,
+	serializePost,
+	type PublishedPost,
+	type PublishPostInput,
+} from "./sources/publish.js";
+export { generateRss, type RssConfig } from "./rss.js";
+export { keys } from "./keys.js";

package/src/sources/fs.ts

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { BlogSource, RawPostFile } from "../blog.js";
+
+/**
+ * Build-time filesystem source. The blog contract is full SSG: call this from
+ * `generateStaticParams`-driven pages (with `dynamicParams = false`), sitemap
+ * and RSS route handlers — all of which run at build. It must NOT be relied on
+ * at request time on serverless hosts: output file tracing does not follow
+ * `fs` reads made inside a published package, so the content directory may be
+ * absent from the deployed function (`outputFileTracingIncludes` is the escape
+ * hatch if you truly need runtime reads).
+ */
+export function fsSource(dir: string): BlogSource {
+	const root = path.isAbsolute(dir) ? dir : path.join(process.cwd(), dir);
+
+	return {
+		async load(): Promise<RawPostFile[]> {
+			let entries;
+			try {
+				entries = await fs.readdir(root, { withFileTypes: true });
+			} catch (error) {
+				if (
+					error instanceof Error &&
+					"code" in error &&
+					error.code === "ENOENT"
+				) {
+					return [];
+				}
+				throw error;
+			}
+
+			const names: string[] = [];
+			for (const entry of entries) {
+				if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
+					names.push(entry.name);
+				} else if (entry.isDirectory()) {
+					// Folder post: <slug>/index.md(x) with colocated assets/code.
+					for (const index of ["index.mdx", "index.md"]) {
+						try {
+							await fs.access(path.join(root, entry.name, index));
+							names.push(`${entry.name}/${index}`);
+							break;
+						} catch {
+							// keep looking
+						}
+					}
+				}
+			}
+
+			return Promise.all(
+				names.map(async (name) => ({
+					name,
+					content: await fs.readFile(path.join(root, name), "utf8"),
+				})),
+			);
+		},
+	};
+}

package/src/sources/github.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+import type { BlogSource, RawPostFile } from "../blog.js";
+import { assertResponseOk } from "../http.js";
+import { keys } from "../keys.js";
+
+export interface GitHubRepoConfig {
+	owner: string;
+	repo: string;
+	/** Branch, tag, or commit; defaults to the repo's default branch. */
+	ref?: string;
+	/** Content directory inside the repo, e.g. "content/blog". */
+	dir: string;
+	/** Falls back to the GITHUB_TOKEN env var. */
+	token?: string;
+}
+
+const API = "https://api.github.com";
+
+export function githubHeaders(token: string | undefined): Record<string, string> {
+	const resolved = token ?? keys().GITHUB_TOKEN;
+	return {
+		accept: "application/vnd.github+json",
+		"x-github-api-version": "2022-11-28",
+		"user-agent": "nk-blog",
+		...(resolved ? { authorization: `Bearer ${resolved}` } : {}),
+	};
+}
+
+const treeSchema = z.object({
+	truncated: z.boolean(),
+	tree: z.array(
+		z.object({
+			path: z.string(),
+			type: z.string(),
+			sha: z.string(),
+		}),
+	),
+});
+
+const blobSchema = z.object({
+	content: z.string(),
+	encoding: z.literal("base64"),
+});
+
+/**
+ * Read a repo's posts over the GitHub API — the admin publisher's read path
+ * (list a target's real posts; reconcile instead of blind-append). One Trees
+ * call for the listing, then batched blob fetches: never per-file `contents`
+ * round-trips.
+ */
+export function githubSource(config: GitHubRepoConfig): BlogSource {
+	return {
+		async load(): Promise<RawPostFile[]> {
+			const headers = githubHeaders(config.token);
+			const base = `${API}/repos/${config.owner}/${config.repo}`;
+			const ref = config.ref ?? "HEAD";
+
+			const treeResponse = await fetch(
+				`${base}/git/trees/${encodeURIComponent(ref)}?recursive=1`,
+				{ headers },
+			);
+			await assertResponseOk(
+				treeResponse,
+				`nk-blog: listing ${config.owner}/${config.repo}@${ref}`,
+			);
+			const { tree, truncated } = treeSchema.parse(await treeResponse.json());
+			if (truncated) {
+				throw new Error(
+					`nk-blog: git tree for ${config.owner}/${config.repo} is truncated; narrow \`dir\``,
+				);
+			}
+
+			const prefix = `${config.dir.replace(/\/$/, "")}/`;
+			const files = tree.filter(
+				(entry) =>
+					entry.type === "blob" &&
+					entry.path.startsWith(prefix) &&
+					/\.mdx?$/.test(entry.path),
+			);
+
+			// Bounded concurrency: an unbounded Promise.all over every post blob
+			// hammers the API and trips secondary rate limits on large blogs.
+			const CONCURRENCY = 8;
+			const results: { name: string; content: string }[] = [];
+			for (let i = 0; i < files.length; i += CONCURRENCY) {
+				const chunk = await Promise.all(
+					files.slice(i, i + CONCURRENCY).map(async (entry) => {
+						const blobResponse = await fetch(
+							`${base}/git/blobs/${entry.sha}`,
+							{
+								headers,
+							},
+						);
+						await assertResponseOk(
+							blobResponse,
+							`nk-blog: reading ${entry.path}`,
+						);
+						const blob = blobSchema.parse(await blobResponse.json());
+						return {
+							name: entry.path.slice(prefix.length),
+							content: Buffer.from(blob.content, "base64").toString(
+								"utf8",
+							),
+						};
+					}),
+				);
+				results.push(...chunk);
+			}
+			return results;
+		},
+	};
+}

package/src/sources/publish.ts

@@ -0,0 +1,103 @@
+import matter from "gray-matter";
+import { z } from "zod";
+import {
+	blogFrontmatterSchema,
+	type BlogFrontmatterInput,
+	slugPattern,
+} from "../schema.js";
+import type { PostFormat } from "../types.js";
+import { assertResponseOk } from "../http.js";
+import { githubHeaders, type GitHubRepoConfig } from "./github.js";
+
+const API = "https://api.github.com";
+
+/** Canonical on-disk form of a post: YAML frontmatter + body, one trailing \n. */
+export function serializePost(frontmatter: BlogFrontmatterInput, body: string): string {
+	// Validate before serializing so admin can never commit a file the sites'
+	// readers would reject at build time.
+	blogFrontmatterSchema.parse(frontmatter);
+	return `${matter.stringify(`\n${body.trim()}\n`, frontmatter).trim()}\n`;
+}
+
+export interface PublishPostInput {
+	slug: string;
+	frontmatter: BlogFrontmatterInput;
+	body: string;
+	/** Admin's automated path emits "md" (data, never code) — the default. */
+	format?: PostFormat;
+	message?: string;
+	/** Commit to this branch (e.g. for a draft/preview PR) instead of the ref. */
+	branch?: string;
+	/** Update an existing post instead of failing the slug-collision check. */
+	overwrite?: boolean;
+}
+
+const putResponseSchema = z.object({
+	content: z.object({ path: z.string(), sha: z.string() }),
+	commit: z.object({ sha: z.string(), html_url: z.string().optional() }),
+});
+
+export type PublishedPost = z.infer<typeof putResponseSchema>;
+
+/**
+ * Publish a post by committing one content file to the target repo — the
+ * entire replacement for admin's buildPostsJson/buildMdx machinery.
+ */
+export async function publishPost(
+	target: GitHubRepoConfig,
+	input: PublishPostInput,
+): Promise<PublishedPost> {
+	if (!slugPattern.test(input.slug)) {
+		// The slug lands in a repo file path — anything looser is a traversal
+		// vector (`../.github/workflows/x`) and breaks routes/RSS URLs anyway.
+		throw new Error(`nk-blog: invalid slug "${input.slug}"`);
+	}
+	const frontmatterSlug = input.frontmatter.slug;
+	if (frontmatterSlug !== undefined && frontmatterSlug !== input.slug) {
+		// The reader routes by the frontmatter override, so a mismatch defeats
+		// the filename-based collision check below and can break the target
+		// site's build with a duplicate-slug error.
+		throw new Error(
+			`nk-blog: frontmatter slug "${frontmatterSlug}" does not match publish slug "${input.slug}"`,
+		);
+	}
+	const headers = githubHeaders(target.token);
+	const base = `${API}/repos/${target.owner}/${target.repo}`;
+	const filePath = `${target.dir.replace(/\/$/, "")}/${input.slug}.${
+		input.format ?? "md"
+	}`;
+	const branch = input.branch ?? target.ref;
+	const refQuery = branch ? `?ref=${encodeURIComponent(branch)}` : "";
+
+	// Slug-collision check (and the sha needed when overwriting).
+	const existing = await fetch(`${base}/contents/${filePath}${refQuery}`, {
+		headers,
+	});
+	let existingSha: string | undefined;
+	if (existing.ok) {
+		if (!input.overwrite) {
+			throw new Error(
+				`nk-blog: ${filePath} already exists in ${target.owner}/${target.repo}`,
+			);
+		}
+		existingSha = z.object({ sha: z.string() }).parse(await existing.json()).sha;
+	} else if (existing.status !== 404) {
+		await assertResponseOk(existing, `nk-blog: checking ${filePath}`);
+	}
+
+	const response = await fetch(`${base}/contents/${filePath}`, {
+		method: "PUT",
+		headers: { ...headers, "content-type": "application/json" },
+		body: JSON.stringify({
+			message: input.message ?? `content: publish ${input.slug}`,
+			content: Buffer.from(
+				serializePost(input.frontmatter, input.body),
+				"utf8",
+			).toString("base64"),
+			...(branch ? { branch } : {}),
+			...(existingSha ? { sha: existingSha } : {}),
+		}),
+	});
+	await assertResponseOk(response, `nk-blog: publishing ${filePath}`);
+	return putResponseSchema.parse(await response.json());
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+export type PostFormat = "md" | "mdx";
+
+/** Everything a listing page needs — no body. */
+export interface BlogPostPreview {
+	slug: string;
+	title: string;
+	seoTitle?: string;
+	description: string;
+	/** ISO 8601. */
+	date: string;
+	/** ISO 8601; set when the post declares an `updated` date. */
+	updated?: string;
+	authors: string[];
+	/** First author — convenience for single-byline layouts. */
+	author: string;
+	category?: string;
+	tags: string[];
+	image?: string;
+	draft: boolean;
+	featured: boolean;
+	/** Reserved for i18n'd blogs; not interpreted by the reader yet. */
+	lang?: string;
+	/** Reserved canonical-URL override for syndicated posts. */
+	canonical?: string;
+	format: PostFormat;
+	readingTimeMinutes: number;
+	/** e.g. "5 min read" — derived from the body, never authored. */
+	readTime: string;
+}
+
+/** A full post: the preview fields plus the body (frontmatter stripped). */
+export interface BlogPost extends BlogPostPreview {
+	content: string;
+}

package/src/unstyled/callout.tsx

@@ -0,0 +1,18 @@
+import type { CalloutProps } from "../contract.js";
+
+/**
+ * Unstyled default. Semantic structure only — style it from the site via the
+ * data attributes, or replace it wholesale. No visual props beyond className,
+ * ever (the bright line that keeps "unstyled" from eroding into a theme).
+ */
+export const Callout: React.FC<CalloutProps> = ({
+	variant = "note",
+	title,
+	className,
+	children,
+}) => (
+	<aside data-callout={variant} className={className}>
+		{title ? <p data-callout-title>{title}</p> : null}
+		<div data-callout-body>{children}</div>
+	</aside>
+);

package/src/unstyled/figure.tsx

@@ -0,0 +1,30 @@
+import type { FigureProps } from "../contract.js";
+
+const toDimension = (value: number | string | undefined): number | undefined =>
+	typeof value === "string" ? Number(value) : value;
+
+/**
+ * Unstyled captioned image: correct semantics (figure/figcaption), lazy
+ * loading, and explicit dimensions when given (CLS). Sites wanting
+ * next/image replace this wholesale.
+ */
+export const Figure: React.FC<FigureProps> = ({
+	src,
+	alt,
+	caption,
+	width,
+	height,
+	className,
+}) => (
+	<figure className={className}>
+		<img
+			src={src}
+			alt={alt}
+			width={toDimension(width)}
+			height={toDimension(height)}
+			loading="lazy"
+			decoding="async"
+		/>
+		{caption ? <figcaption>{caption}</figcaption> : null}
+	</figure>
+);