nimbus-docs 0.1.3 → 0.1.5

package/dist/schemas.d.ts

@@ -1,4 +1,5 @@
 import { z } from "astro/zod";
+import * as astro_content0 from "astro:content";
 
 //#region src/schemas.d.ts
 interface DocSchemaConfig {
@@ -9,89 +10,72 @@ interface DocSchemaConfig {
  * Build a customizable docs schema. Use this when composing schemas outside
  * the `docsCollection()` factory (e.g. multiple docs collections with
  * different shapes).
+ *
+ * For typed Astro `image()` fields or per-collection field narrowing, use
+ * the richer `defineSchema(ctx => ...)` factory instead.
  */
-declare function defineDocSchema(config?: DocSchemaConfig): z.ZodObject<{
-  title: z.ZodString;
-  description: z.ZodOptional<z.ZodString>;
-  template: z.ZodDefault<z.ZodEnum<{
-    doc: "doc";
-    splash: "splash";
-  }>>;
-  sidebar: z.ZodOptional<z.ZodObject<{
-    order: z.ZodOptional<z.ZodNumber>;
-    label: z.ZodOptional<z.ZodString>;
-    badge: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-      text: z.ZodString;
-      variant: z.ZodDefault<z.ZodEnum<{
-        success: "success";
-        default: "default";
-        info: "info";
-        note: "note";
-        tip: "tip";
-        warning: "warning";
-        caution: "caution";
-        danger: "danger";
-      }>>;
-    }, z.core.$strip>]>>;
-    hidden: z.ZodOptional<z.ZodBoolean>;
-    hideChildren: z.ZodOptional<z.ZodBoolean>;
-  }, z.core.$strip>>;
-  hero: z.ZodOptional<z.ZodObject<{
-    title: z.ZodOptional<z.ZodString>;
-    tagline: z.ZodOptional<z.ZodString>;
-    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
-      text: z.ZodString;
-      link: z.ZodString;
-      variant: z.ZodDefault<z.ZodEnum<{
-        primary: "primary";
-        secondary: "secondary";
-        outline: "outline";
-      }>>;
-      icon: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
-  }, z.core.$strip>>;
-  head: z.ZodDefault<z.ZodArray<z.ZodObject<{
-    tag: z.ZodEnum<{
-      link: "link";
-      meta: "meta";
-      script: "script";
-      style: "style";
-    }>;
-    attrs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
-    content: z.ZodOptional<z.ZodString>;
-  }, z.core.$strip>>>;
-  draft: z.ZodDefault<z.ZodBoolean>;
-  noindex: z.ZodDefault<z.ZodBoolean>;
-  llms: z.ZodDefault<z.ZodBoolean>;
-  aiDeprioritize: z.ZodDefault<z.ZodBoolean>;
-  pagefind: z.ZodDefault<z.ZodBoolean>;
-  tableOfContents: z.ZodOptional<z.ZodObject<{
-    minHeadingLevel: z.ZodDefault<z.ZodNumber>;
-    maxHeadingLevel: z.ZodDefault<z.ZodNumber>;
-  }, z.core.$strip>>;
-  lastUpdated: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-  socialImage: z.ZodOptional<z.ZodString>;
-  prev: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-    link: z.ZodOptional<z.ZodString>;
-    label: z.ZodOptional<z.ZodString>;
-  }, z.core.$strip>, z.ZodLiteral<false>]>>;
-  next: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-    link: z.ZodOptional<z.ZodString>;
-    label: z.ZodOptional<z.ZodString>;
-  }, z.core.$strip>, z.ZodLiteral<false>]>>;
-  previousSlug: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
-}, z.core.$strip> | z.ZodObject<{
-  [x: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-}, z.core.$strip>;
+declare function defineDocSchema(config?: DocSchemaConfig): z.ZodObject<Readonly<{
+  [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}>, z.core.$loose>;
+/**
+ * Factory options for `defineSchema`.
+ *
+ *   - `extend`: additional fields merged into the framework schema. Use
+ *     this for user-defined frontmatter (`author`, `tags`, `cover`).
+ *   - `narrow`: replaces framework fields with tighter types within this
+ *     collection. Use when a collection has stricter rules — e.g.
+ *     `{ mode: z.literal("doc") }` says no landing pages in this collection.
+ */
+interface DefineSchemaOptions {
+  extend?: z.ZodTypeAny;
+  narrow?: Record<string, z.ZodTypeAny>;
+}
+/**
+ * Build a typed docs schema with access to the Astro `SchemaContext`.
+ * Use this when you want typed image fields (`ctx.image()`), per-
+ * collection narrowing of framework fields, or both. The simpler
+ * `defineDocSchema({ fields })` factory is still available for the
+ * common case of just adding fields.
+ *
+ *   import { defineCollection } from "astro:content";
+ *   import { z } from "astro/zod";
+ *   import { defineSchema } from "nimbus-docs/schemas";
+ *
+ *   export const collections = {
+ *     docs: defineCollection({
+ *       loader: ...,
+ *       schema: defineSchema((ctx) => ({
+ *         extend: z.object({
+ *           cover: ctx.image().optional(),
+ *           author: z.string().optional(),
+ *         }),
+ *         narrow: {
+ *           mode: z.literal("doc"),  // no landing pages here
+ *         },
+ *       })),
+ *     }),
+ *   };
+ */
+declare function defineSchema(factory: (ctx: astro_content0.SchemaContext) => DefineSchemaOptions): (ctx: astro_content0.SchemaContext) => z.ZodObject<Readonly<{
+  [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}>, z.core.$loose> | z.ZodIntersection<z.ZodObject<any, z.core.$strip>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
 /** Default docs schema. Equivalent to `defineDocSchema()`. */
-declare const docsSchema: z.ZodObject<{
+declare const docsSchema: z.ZodObject<Readonly<{
+  [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+}>, z.core.$loose>;
+/** Schema for partials (`<Render file="..." />` snippets). */
+declare const partialsSchema: z.ZodDefault<z.ZodObject<{
+  params: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>>;
+/** Docs frontmatter, framework fields type-checked, extra keys allowed. */
+declare const lenientDocsSchema: z.ZodObject<{
   title: z.ZodString;
   description: z.ZodOptional<z.ZodString>;
-  template: z.ZodDefault<z.ZodEnum<{
+  mode: z.ZodDefault<z.ZodEnum<{
     doc: "doc";
-    splash: "splash";
+    custom: "custom";
   }>>;
-  sidebar: z.ZodOptional<z.ZodObject<{
+  sidebar: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
     order: z.ZodOptional<z.ZodNumber>;
     label: z.ZodOptional<z.ZodString>;
     badge: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -109,40 +93,37 @@ declare const docsSchema: z.ZodObject<{
     }, z.core.$strip>]>>;
     hidden: z.ZodOptional<z.ZodBoolean>;
     hideChildren: z.ZodOptional<z.ZodBoolean>;
-  }, z.core.$strip>>;
-  hero: z.ZodOptional<z.ZodObject<{
-    title: z.ZodOptional<z.ZodString>;
-    tagline: z.ZodOptional<z.ZodString>;
-    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
-      text: z.ZodString;
-      link: z.ZodString;
-      variant: z.ZodDefault<z.ZodEnum<{
-        primary: "primary";
-        secondary: "secondary";
-        outline: "outline";
-      }>>;
-      icon: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
-  }, z.core.$strip>>;
+  }, z.core.$strip>]>>;
   head: z.ZodDefault<z.ZodArray<z.ZodObject<{
     tag: z.ZodEnum<{
-      link: "link";
       meta: "meta";
+      link: "link";
       script: "script";
       style: "style";
     }>;
     attrs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     content: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>>>;
+  banner: z.ZodOptional<z.ZodObject<{
+    content: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+      note: "note";
+      tip: "tip";
+      caution: "caution";
+      danger: "danger";
+    }>>;
+    dismissible: z.ZodOptional<z.ZodObject<{
+      id: z.ZodString;
+      days: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
   draft: z.ZodDefault<z.ZodBoolean>;
   noindex: z.ZodDefault<z.ZodBoolean>;
-  llms: z.ZodDefault<z.ZodBoolean>;
-  aiDeprioritize: z.ZodDefault<z.ZodBoolean>;
-  pagefind: z.ZodDefault<z.ZodBoolean>;
-  tableOfContents: z.ZodOptional<z.ZodObject<{
+  searchable: z.ZodOptional<z.ZodBoolean>;
+  tableOfContents: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
     minHeadingLevel: z.ZodDefault<z.ZodNumber>;
     maxHeadingLevel: z.ZodDefault<z.ZodNumber>;
-  }, z.core.$strip>>;
+  }, z.core.$strip>]>>;
   lastUpdated: z.ZodOptional<z.ZodCoercedDate<unknown>>;
   socialImage: z.ZodOptional<z.ZodString>;
   prev: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -154,13 +135,11 @@ declare const docsSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>, z.ZodLiteral<false>]>>;
   previousSlug: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
-}, z.core.$strip> | z.ZodObject<{
-  [x: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-}, z.core.$strip>;
-/** Schema for partials (`<Render file="..." />` snippets). */
-declare const partialsSchema: z.ZodDefault<z.ZodObject<{
+}, z.core.$loose>;
+/** Partials frontmatter, framework fields type-checked, extra keys allowed. */
+declare const lenientPartialsSchema: z.ZodObject<{
   params: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>>;
+}, z.core.$loose>;
 /** One row in a component's `props` frontmatter array. */
 declare const componentPropSchema: z.ZodObject<{
   name: z.ZodString;
@@ -183,5 +162,5 @@ declare const componentsSchema: z.ZodObject<{
   }, z.core.$strip>>>;
 }, z.core.$strip>;
 //#endregion
-export { ComponentProp, DocSchemaConfig, componentsSchema, defineDocSchema, docsSchema, partialsSchema };
+export { ComponentProp, DefineSchemaOptions, DocSchemaConfig, componentsSchema, defineDocSchema, defineSchema, docsSchema, lenientDocsSchema, lenientPartialsSchema, partialsSchema };
 //# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","names":[],"sources":["../src/schemas.ts"],"mappings":";;;UAgBiB,eAAA;;EAEf,MAAA,GAAS,MAAA,SAAe,CAAA,CAAE,UAAA;AAAA;;;;;;iBA2KZ,eAAA,CAAgB,MAAA,GAAQ,eAAA,GAAoB,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAS/C,UAAA,EAAU,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAGV,cAAA,EAAc,CAAA,CAAA,UAAA,CAAA,CAAA,CAAA,SAAA;;;;cAkBrB,mBAAA,EAAmB,CAAA,CAAA,SAAA;;;;;;;KAQb,aAAA,GAAgB,CAAA,CAAE,KAAA,QAAa,mBAAA;;cAG9B,gBAAA,EAAgB,CAAA,CAAA,SAAA"}
+{"version":3,"file":"schemas.d.ts","names":[],"sources":["../src/schemas.ts"],"mappings":";;;;UAiBiB,eAAA;EA6Oc;EA3O7B,MAAA,GAAS,MAAA,SAAe,CAAA,CAAE,UAAA;AAAA;;;;;;;;;iBA2OZ,eAAA,CAAgB,MAAA,GAAQ,eAAA,GAAoB,CAAA,CAAA,SAAA,CAAA,QAAA;EAAA;;;;;;;;;;;UAkB3C,mBAAA;EACf,MAAA,GAAS,CAAA,CAAE,UAAA;EACX,MAAA,GAAS,MAAA,SAAe,CAAA,CAAE,UAAA;AAAA;AAF5B;;;;;;;;;;;;;;;;;AA+BA;;;;;;;;;AA/BA,iBA+BgB,YAAA,CACd,OAAA,GAAU,GAAA,EADgB,cAAA,CACa,aAAA,KAAkB,mBAAA,IAEjD,GAAA,EAFoE,cAAA,CAEvC,aAAA,KAAa,CAAA,CAAA,SAAA,CAAA,QAAA;EAAA;;;cA8BvC,UAAA,EAAU,CAAA,CAAA,SAAA,CAAA,QAAA;EAAA;;;cAWV,cAAA,EAAc,CAAA,CAAA,UAAA,CAAA,CAAA,CAAA,SAAA;;;;cAad,iBAAA,EAAiB,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAGjB,qBAAA,EAAqB,CAAA,CAAA,SAAA;;;;cAU5B,mBAAA,EAAmB,CAAA,CAAA,SAAA;;;;;;;KAQb,aAAA,GAAgB,CAAA,CAAE,KAAA,QAAa,mBAAA;;cAG9B,gBAAA,EAAgB,CAAA,CAAA,SAAA"}

package/dist/schemas.js

@@ -1,3 +1,4 @@
+import { t as withStrictKeys } from "./strict-keys-BiXiT3pq.js";
 import { z } from "astro/zod";
 
 //#region src/schemas.ts
@@ -27,29 +28,14 @@ const sidebarBadgeSchema = z.union([z.string(), z.object({
 		"danger"
 	], { error: "\"variant\" must be one of: default, info, note, success, tip, warning, caution, danger" }).default("default")
 })]);
-const sidebarFrontmatterSchema = z.object({
+const sidebarSchema = z.object({
 	order: z.number({ error: "\"sidebar.order\" must be a number" }).optional(),
 	label: z.string({ error: "\"sidebar.label\" must be a string" }).optional(),
 	badge: sidebarBadgeSchema.optional(),
 	hidden: z.boolean({ error: "\"sidebar.hidden\" must be true or false" }).optional(),
 	hideChildren: z.boolean({ error: "\"sidebar.hideChildren\" must be true or false" }).optional()
-}).optional();
-const heroActionSchema = z.object({
-	text: z.string({ error: "hero action needs a \"text\" field" }),
-	link: z.string({ error: "hero action needs a \"link\" field" }),
-	variant: z.enum([
-		"primary",
-		"secondary",
-		"outline"
-	], { error: "hero action \"variant\" must be \"primary\", \"secondary\", or \"outline\"" }).default("primary"),
-	icon: z.string().optional()
 });
-const heroSchema = z.object({
-	title: z.string().optional(),
-	tagline: z.string().optional(),
-	actions: z.array(heroActionSchema).optional()
-}).optional();
-const prevNextFrontmatterSchema = z.union([
+const prevNextSchema = z.union([
 	z.string(),
 	z.object({
 		link: z.string().optional(),
@@ -67,27 +53,81 @@ const headElementSchema = z.object({
 	attrs: z.record(z.string(), z.string()).default({}),
 	content: z.string().optional()
 });
+const bannerSchema = z.object({
+	content: z.string({ error: "banner \"content\" must be a string" }),
+	type: z.enum([
+		"note",
+		"tip",
+		"caution",
+		"danger"
+	], { error: "banner \"type\" must be one of: note, tip, caution, danger" }).optional(),
+	dismissible: z.object({
+		id: z.string({ error: "banner \"dismissible.id\" must be a string — a stable identifier you bump when banner content meaningfully changes" }),
+		days: z.number({ error: "banner \"dismissible.days\" must be a number" }).optional()
+	}).optional()
+});
+/**
+* Frontmatter keys that used to exist but no longer do. When user content
+* still carries one of these, Zod's default `.strip()` behavior would
+* silently drop it — the page would build, but with subtly different
+* behavior (the old toggle just disappears). That's a confusing failure
+* mode for an authoring contract.
+*
+* `withUnknownKeyCheck` (below) consults this map. Hits get the friendly
+* migration message verbatim; everything else falls through to a generic
+* "Unknown frontmatter key" error so typos don't sneak past either.
+*
+* Entries removed in the v0 → v1 cleanup:
+*
+*   - `template` → `mode`: same shape, but `"splash"` is now `"custom"`.
+*   - `pagefind` → `searchable`: same boolean; default now derives from
+*     `noindex` (a non-crawlable page is non-searchable by default).
+*   - `llms`: removed. All published pages are listed in `/llms.txt`; the
+*     escape hatch is `noindex: true`.
+*   - `aiDeprioritize`: removed. The framework no longer emits an
+*     agent-downrank signal.
+*   - `hero`: removed. Compose the hero in MDX body with user-owned
+*     components instead of a frontmatter contract.
+*/
+const REMOVED_FRONTMATTER_KEYS = {
+	template: "was renamed to \"mode\". Replace `template: \"doc\"` with `mode: \"doc\"`, and `template: \"splash\"` with `mode: \"custom\"`.",
+	pagefind: "was renamed to \"searchable\". Same boolean shape; the default now derives from `noindex` (a non-crawlable page is non-searchable unless you set `searchable: true` explicitly).",
+	llms: "was removed. Every published page is now listed in /llms.txt; use `noindex: true` to keep a page out of both search engines and the LLM index.",
+	aiDeprioritize: "was removed. The framework no longer emits an agent-downrank signal. If you want a page hidden from agents, use `noindex: true`.",
+	hero: "was removed. Compose your hero in the MDX body using user-owned components; there is no longer a `hero` frontmatter contract."
+};
+/**
+* Apply this AFTER any `.extend()` so user-added fields are recognized
+* as valid. Wraps the schema in `.passthrough().superRefine()` so removed
+* keys raise a guided migration error; other unknown keys raise a
+* generic error pointing at `defineSchema({ extend: ... })`.
+*/
+function withFrontmatterKeyCheck(schema) {
+	return withStrictKeys(schema, {
+		removedKeys: REMOVED_FRONTMATTER_KEYS,
+		contextLabel: "Frontmatter key",
+		unknownHint: (key) => `If you meant to add a custom field, declare it in your collection's schema via \`defineSchema({ extend: z.object({ ${key}: ... }) })\`.`
+	});
+}
 function baseDocSchema() {
 	return z.object({
 		title: z.string({ error: (iss) => iss.input === void 0 ? "Missing required \"title\" in frontmatter. Every doc needs:\n\n  ---\n  title: \"Your Page Title\"\n  ---" : `"title" must be a string, received ${typeof iss.input}` }),
 		description: z.string({ error: "\"description\" must be a string" }).optional(),
-		template: z.enum(["doc", "splash"], { error: "\"template\" must be \"doc\" or \"splash\"" }).default("doc"),
-		sidebar: sidebarFrontmatterSchema,
-		hero: heroSchema,
+		mode: z.enum(["doc", "custom"], { error: "\"mode\" must be \"doc\" or \"custom\"" }).default("doc"),
+		sidebar: z.union([z.literal(false), sidebarSchema]).optional(),
 		head: z.array(headElementSchema).default([]),
+		banner: bannerSchema.optional(),
 		draft: z.boolean({ error: "\"draft\" must be true or false" }).default(false),
 		noindex: z.boolean({ error: "\"noindex\" must be true or false" }).default(false),
-		llms: z.boolean({ error: "\"llms\" must be true or false" }).default(true),
-		aiDeprioritize: z.boolean({ error: "\"aiDeprioritize\" must be true or false" }).default(false),
-		pagefind: z.boolean({ error: "\"pagefind\" must be true or false" }).default(true),
-		tableOfContents: z.object({
+		searchable: z.boolean({ error: "\"searchable\" must be true or false" }).optional(),
+		tableOfContents: z.union([z.literal(false), z.object({
 			minHeadingLevel: z.number({ error: "\"minHeadingLevel\" must be a number (1-6)" }).int().min(1).max(6).default(2),
 			maxHeadingLevel: z.number({ error: "\"maxHeadingLevel\" must be a number (1-6)" }).int().min(1).max(6).default(3)
-		}).refine((v) => v.minHeadingLevel <= v.maxHeadingLevel, { message: "minHeadingLevel must be <= maxHeadingLevel" }).optional(),
+		}).refine((v) => v.minHeadingLevel <= v.maxHeadingLevel, { message: "minHeadingLevel must be <= maxHeadingLevel" })]).optional(),
 		lastUpdated: z.coerce.date({ error: "\"lastUpdated\" must be a valid date (e.g. 2024-01-15)" }).optional(),
 		socialImage: z.string({ error: "\"socialImage\" must be a string (path or URL)" }).optional(),
-		prev: prevNextFrontmatterSchema,
-		next: prevNextFrontmatterSchema,
+		prev: prevNextSchema,
+		next: prevNextSchema,
 		previousSlug: z.union([z.string(), z.array(z.string())], { error: "\"previousSlug\" must be a string or array of strings" }).optional()
 	});
 }
@@ -95,16 +135,59 @@ function baseDocSchema() {
 * Build a customizable docs schema. Use this when composing schemas outside
 * the `docsCollection()` factory (e.g. multiple docs collections with
 * different shapes).
+*
+* For typed Astro `image()` fields or per-collection field narrowing, use
+* the richer `defineSchema(ctx => ...)` factory instead.
 */
 function defineDocSchema(config = {}) {
 	const base = baseDocSchema();
-	if (config.fields) return base.extend(config.fields);
-	return base;
+	return withFrontmatterKeyCheck(config.fields ? base.extend(config.fields) : base);
+}
+/**
+* Build a typed docs schema with access to the Astro `SchemaContext`.
+* Use this when you want typed image fields (`ctx.image()`), per-
+* collection narrowing of framework fields, or both. The simpler
+* `defineDocSchema({ fields })` factory is still available for the
+* common case of just adding fields.
+*
+*   import { defineCollection } from "astro:content";
+*   import { z } from "astro/zod";
+*   import { defineSchema } from "nimbus-docs/schemas";
+*
+*   export const collections = {
+*     docs: defineCollection({
+*       loader: ...,
+*       schema: defineSchema((ctx) => ({
+*         extend: z.object({
+*           cover: ctx.image().optional(),
+*           author: z.string().optional(),
+*         }),
+*         narrow: {
+*           mode: z.literal("doc"),  // no landing pages here
+*         },
+*       })),
+*     }),
+*   };
+*/
+function defineSchema(factory) {
+	return (ctx) => {
+		const { extend, narrow } = factory(ctx);
+		let schema = baseDocSchema();
+		if (narrow) schema = schema.extend(narrow);
+		if (extend) if (extend instanceof z.ZodObject) schema = schema.merge(extend);
+		else return schema.and(extend);
+		return withFrontmatterKeyCheck(schema);
+	};
 }
 /** Default docs schema. Equivalent to `defineDocSchema()`. */
 const docsSchema = defineDocSchema();
+const partialsObjectSchema = z.object({ params: z.array(z.string()).optional() });
 /** Schema for partials (`<Render file="..." />` snippets). */
-const partialsSchema = z.object({ params: z.array(z.string()).optional() }).default({});
+const partialsSchema = partialsObjectSchema.default({});
+/** Docs frontmatter, framework fields type-checked, extra keys allowed. */
+const lenientDocsSchema = baseDocSchema().passthrough();
+/** Partials frontmatter, framework fields type-checked, extra keys allowed. */
+const lenientPartialsSchema = partialsObjectSchema.passthrough();
 /** One row in a component's `props` frontmatter array. */
 const componentPropSchema = z.object({
 	name: z.string({ error: "prop needs a \"name\"" }),
@@ -121,5 +204,5 @@ const componentsSchema = z.object({
 });
 
 //#endregion
-export { componentsSchema, defineDocSchema, docsSchema, partialsSchema };
+export { componentsSchema, defineDocSchema, defineSchema, docsSchema, lenientDocsSchema, lenientPartialsSchema, partialsSchema };
 //# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","names":[],"sources":["../src/schemas.ts"],"sourcesContent":["/**\n * Content schemas for Nimbus.\n *\n * `docsSchema` is the default frontmatter contract for the `docs` collection.\n * `partialsSchema` is the contract for `<Render file=\"...\" />` partials.\n * `defineDocSchema(config)` returns a customizable schema for advanced users\n *   composing schemas outside the `docsCollection()` factory.\n *\n * Error messages target content authors, not framework developers.\n * Astro 6 ships Zod v4 via `astro/zod`. The v4 API uses a single `error`\n * field on every schema constructor — NOT v3's `required_error` /\n * `invalid_type_error` / `errorMap`.\n */\n\nimport { z } from \"astro/zod\";\n\nexport interface DocSchemaConfig {\n  /** Additional frontmatter fields merged into the default schema. */\n  fields?: Record<string, z.ZodTypeAny>;\n}\n\n// ---------------------------------------------------------------------------\n// Building blocks\n// ---------------------------------------------------------------------------\n\nconst sidebarBadgeSchema = z.union([\n  z.string(),\n  z.object({\n    text: z.string({ error: 'sidebar badge needs a \"text\" field' }),\n    variant: z\n      .enum(\n        [\"default\", \"info\", \"note\", \"success\", \"tip\", \"warning\", \"caution\", \"danger\"],\n        {\n          error:\n            '\"variant\" must be one of: default, info, note, success, tip, warning, caution, danger',\n        },\n      )\n      .default(\"default\"),\n  }),\n]);\n\nconst sidebarFrontmatterSchema = z\n  .object({\n    order: z.number({ error: '\"sidebar.order\" must be a number' }).optional(),\n    label: z.string({ error: '\"sidebar.label\" must be a string' }).optional(),\n    badge: sidebarBadgeSchema.optional(),\n    hidden: z.boolean({ error: '\"sidebar.hidden\" must be true or false' }).optional(),\n    hideChildren: z\n      .boolean({ error: '\"sidebar.hideChildren\" must be true or false' })\n      .optional(),\n  })\n  .optional();\n\nconst heroActionSchema = z.object({\n  text: z.string({ error: 'hero action needs a \"text\" field' }),\n  link: z.string({ error: 'hero action needs a \"link\" field' }),\n  variant: z\n    .enum([\"primary\", \"secondary\", \"outline\"], {\n      error: 'hero action \"variant\" must be \"primary\", \"secondary\", or \"outline\"',\n    })\n    .default(\"primary\"),\n  icon: z.string().optional(),\n});\n\nconst heroSchema = z\n  .object({\n    title: z.string().optional(),\n    tagline: z.string().optional(),\n    actions: z.array(heroActionSchema).optional(),\n  })\n  .optional();\n\nconst prevNextFrontmatterSchema = z\n  .union([\n    z.string(),\n    z.object({ link: z.string().optional(), label: z.string().optional() }),\n    z.literal(false),\n  ])\n  .optional();\n\nconst headElementSchema = z.object({\n  tag: z.enum([\"meta\", \"link\", \"script\", \"style\"], {\n    error: 'head element \"tag\" must be \"meta\", \"link\", \"script\", or \"style\"',\n  }),\n  attrs: z.record(z.string(), z.string()).default({}),\n  content: z.string().optional(),\n});\n\n// ---------------------------------------------------------------------------\n// Base docs schema\n// ---------------------------------------------------------------------------\n\nfunction baseDocSchema() {\n  return z.object({\n    title: z.string({\n      error: (iss) =>\n        iss.input === undefined\n          ? 'Missing required \"title\" in frontmatter. Every doc needs:\\n\\n  ---\\n  title: \"Your Page Title\"\\n  ---'\n          : `\"title\" must be a string, received ${typeof iss.input}`,\n    }),\n    description: z.string({ error: '\"description\" must be a string' }).optional(),\n    template: z\n      .enum([\"doc\", \"splash\"], {\n        error: '\"template\" must be \"doc\" or \"splash\"',\n      })\n      .default(\"doc\"),\n    sidebar: sidebarFrontmatterSchema,\n    hero: heroSchema,\n    head: z.array(headElementSchema).default([]),\n    draft: z.boolean({ error: '\"draft\" must be true or false' }).default(false),\n    noindex: z.boolean({ error: '\"noindex\" must be true or false' }).default(false),\n    /** Include this page in llms.txt and AI consumption indexes */\n    llms: z.boolean({ error: '\"llms\" must be true or false' }).default(true),\n    /** Signal AI crawlers to deprioritize this page */\n    aiDeprioritize: z\n      .boolean({ error: '\"aiDeprioritize\" must be true or false' })\n      .default(false),\n    pagefind: z.boolean({ error: '\"pagefind\" must be true or false' }).default(true),\n    tableOfContents: z\n      .object({\n        minHeadingLevel: z\n          .number({ error: '\"minHeadingLevel\" must be a number (1-6)' })\n          .int()\n          .min(1)\n          .max(6)\n          .default(2),\n        maxHeadingLevel: z\n          .number({ error: '\"maxHeadingLevel\" must be a number (1-6)' })\n          .int()\n          .min(1)\n          .max(6)\n          .default(3),\n      })\n      .refine((v) => v.minHeadingLevel <= v.maxHeadingLevel, {\n        message: \"minHeadingLevel must be <= maxHeadingLevel\",\n      })\n      .optional(),\n    lastUpdated: z.coerce\n      .date({ error: '\"lastUpdated\" must be a valid date (e.g. 2024-01-15)' })\n      .optional(),\n    /**\n     * Explicit per-page social/OG image override (path or absolute URL).\n     * When omitted, the page route is expected to fall back to a\n     * programmatically-generated card or the site-wide `config.socialImage`.\n     */\n    socialImage: z\n      .string({ error: '\"socialImage\" must be a string (path or URL)' })\n      .optional(),\n    prev: prevNextFrontmatterSchema,\n    next: prevNextFrontmatterSchema,\n    /**\n     * Versioning rename escape hatch.\n     *\n     * When a page is renamed between versions (the URL slug changes), the\n     * newer version's frontmatter declares the slug it had in an older\n     * version. The framework uses this to link the pages as cross-version\n     * alternates and to emit a `<link rel=\"canonical\">` to the current\n     * version's URL.\n     *\n     * Example: `docs-v1/old-name.mdx` was renamed in v2 to `new-name.mdx`.\n     * On the new page (`docs/new-name.mdx`, current version), set:\n     *\n     *   previousSlug: old-name\n     *\n     * Now `/new-name` and `/v1/old-name` are linked as the same logical\n     * page in `<head>` alternates, and the v1 page's canonical points to\n     * `/new-name`.\n     *\n     * Accepts a single slug string (the page's id in the older version)\n     * or an array of strings when the page has been renamed across more\n     * than one version.\n     */\n    previousSlug: z\n      .union([z.string(), z.array(z.string())], {\n        error: '\"previousSlug\" must be a string or array of strings',\n      })\n      .optional(),\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Build a customizable docs schema. Use this when composing schemas outside\n * the `docsCollection()` factory (e.g. multiple docs collections with\n * different shapes).\n */\nexport function defineDocSchema(config: DocSchemaConfig = {}) {\n  const base = baseDocSchema();\n  if (config.fields) {\n    return base.extend(config.fields);\n  }\n  return base;\n}\n\n/** Default docs schema. Equivalent to `defineDocSchema()`. */\nexport const docsSchema = defineDocSchema();\n\n/** Schema for partials (`<Render file=\"...\" />` snippets). */\nexport const partialsSchema = z\n  .object({\n    /**\n     * Declared parameters this partial accepts.\n     * Suffix with `?` for optional params: `[\"name\", \"deprecated?\"]`\n     */\n    params: z.array(z.string()).optional(),\n  })\n  .default({});\n\n// ---------------------------------------------------------------------------\n// Components collection — used by sites documenting their own UI components.\n// Pair with `componentsCollection()` from `nimbus-docs/content`. Authoring\n// pattern: hero `<Showcase>` block + `<Example>` blocks in the MDX body, with\n// `props` declared in frontmatter for a generated prop table.\n// ---------------------------------------------------------------------------\n\n/** One row in a component's `props` frontmatter array. */\nconst componentPropSchema = z.object({\n  name: z.string({ error: 'prop needs a \"name\"' }),\n  type: z.string({ error: 'prop needs a \"type\"' }),\n  defaultValue: z.string().optional(),\n  required: z.boolean().default(false),\n  description: z.string({ error: 'prop needs a \"description\"' }),\n});\n\nexport type ComponentProp = z.infer<typeof componentPropSchema>;\n\n/** Default schema for the components collection. */\nexport const componentsSchema = z.object({\n  title: z.string({\n    error: (iss) =>\n      iss.input === undefined\n        ? 'Missing \"title\" in frontmatter — display name used in the sidebar and page header.'\n        : `\"title\" must be a string, received ${typeof iss.input}`,\n  }),\n  tagline: z.string({\n    error: (iss) =>\n      iss.input === undefined\n        ? 'Missing \"tagline\" in frontmatter — one-sentence summary shown under the title.'\n        : `\"tagline\" must be a string, received ${typeof iss.input}`,\n  }),\n  props: z.array(componentPropSchema).default([]),\n});\n"],"mappings":"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"}
+{"version":3,"file":"schemas.js","names":[],"sources":["../src/schemas.ts"],"sourcesContent":["/**\n * Content schemas for Nimbus.\n *\n * `docsSchema` is the default frontmatter contract for the `docs` collection.\n * `partialsSchema` is the contract for `<Render file=\"...\" />` partials.\n * `defineDocSchema(config)` returns a customizable schema for advanced users\n *   composing schemas outside the `docsCollection()` factory.\n *\n * Error messages target content authors, not framework developers.\n * Astro 6 ships Zod v4 via `astro/zod`. The v4 API uses a single `error`\n * field on every schema constructor — NOT v3's `required_error` /\n * `invalid_type_error` / `errorMap`.\n */\n\nimport { z } from \"astro/zod\";\nimport { withStrictKeys } from \"./_internal/strict-keys.js\";\n\nexport interface DocSchemaConfig {\n  /** Additional frontmatter fields merged into the default schema. */\n  fields?: Record<string, z.ZodTypeAny>;\n}\n\n// ---------------------------------------------------------------------------\n// Building blocks\n// ---------------------------------------------------------------------------\n\nconst sidebarBadgeSchema = z.union([\n  z.string(),\n  z.object({\n    text: z.string({ error: 'sidebar badge needs a \"text\" field' }),\n    variant: z\n      .enum(\n        [\"default\", \"info\", \"note\", \"success\", \"tip\", \"warning\", \"caution\", \"danger\"],\n        {\n          error:\n            '\"variant\" must be one of: default, info, note, success, tip, warning, caution, danger',\n        },\n      )\n      .default(\"default\"),\n  }),\n]);\n\nconst sidebarSchema = z.object({\n  order: z.number({ error: '\"sidebar.order\" must be a number' }).optional(),\n  label: z.string({ error: '\"sidebar.label\" must be a string' }).optional(),\n  badge: sidebarBadgeSchema.optional(),\n  hidden: z.boolean({ error: '\"sidebar.hidden\" must be true or false' }).optional(),\n  hideChildren: z\n    .boolean({ error: '\"sidebar.hideChildren\" must be true or false' })\n    .optional(),\n});\n\nconst prevNextSchema = z\n  .union([\n    z.string(),\n    z.object({ link: z.string().optional(), label: z.string().optional() }),\n    z.literal(false),\n  ])\n  .optional();\n\nconst headElementSchema = z.object({\n  tag: z.enum([\"meta\", \"link\", \"script\", \"style\"], {\n    error: 'head element \"tag\" must be \"meta\", \"link\", \"script\", or \"style\"',\n  }),\n  attrs: z.record(z.string(), z.string()).default({}),\n  content: z.string().optional(),\n});\n\n// Mirrors `BannerProps` in types.ts. Layouts consume this directly off\n// `entry.data.banner` and render the `<Banner>` component with it, so the\n// schema is framework-owned (not user-extensible territory).\nconst bannerSchema = z.object({\n  content: z.string({ error: 'banner \"content\" must be a string' }),\n  type: z\n    .enum([\"note\", \"tip\", \"caution\", \"danger\"], {\n      error: 'banner \"type\" must be one of: note, tip, caution, danger',\n    })\n    .optional(),\n  dismissible: z\n    .object({\n      id: z.string({\n        error: 'banner \"dismissible.id\" must be a string — a stable identifier you bump when banner content meaningfully changes',\n      }),\n      days: z.number({ error: 'banner \"dismissible.days\" must be a number' }).optional(),\n    })\n    .optional(),\n});\n\n// ---------------------------------------------------------------------------\n// Removed/renamed frontmatter keys — surface migration errors loudly\n// ---------------------------------------------------------------------------\n\n/**\n * Frontmatter keys that used to exist but no longer do. When user content\n * still carries one of these, Zod's default `.strip()` behavior would\n * silently drop it — the page would build, but with subtly different\n * behavior (the old toggle just disappears). That's a confusing failure\n * mode for an authoring contract.\n *\n * `withUnknownKeyCheck` (below) consults this map. Hits get the friendly\n * migration message verbatim; everything else falls through to a generic\n * \"Unknown frontmatter key\" error so typos don't sneak past either.\n *\n * Entries removed in the v0 → v1 cleanup:\n *\n *   - `template` → `mode`: same shape, but `\"splash\"` is now `\"custom\"`.\n *   - `pagefind` → `searchable`: same boolean; default now derives from\n *     `noindex` (a non-crawlable page is non-searchable by default).\n *   - `llms`: removed. All published pages are listed in `/llms.txt`; the\n *     escape hatch is `noindex: true`.\n *   - `aiDeprioritize`: removed. The framework no longer emits an\n *     agent-downrank signal.\n *   - `hero`: removed. Compose the hero in MDX body with user-owned\n *     components instead of a frontmatter contract.\n */\nconst REMOVED_FRONTMATTER_KEYS: Record<string, string> = {\n  template:\n    'was renamed to \"mode\". Replace `template: \"doc\"` with `mode: \"doc\"`, and `template: \"splash\"` with `mode: \"custom\"`.',\n  pagefind:\n    'was renamed to \"searchable\". Same boolean shape; the default now derives from `noindex` (a non-crawlable page is non-searchable unless you set `searchable: true` explicitly).',\n  llms:\n    \"was removed. Every published page is now listed in /llms.txt; use `noindex: true` to keep a page out of both search engines and the LLM index.\",\n  aiDeprioritize:\n    \"was removed. The framework no longer emits an agent-downrank signal. If you want a page hidden from agents, use `noindex: true`.\",\n  hero:\n    \"was removed. Compose your hero in the MDX body using user-owned components; there is no longer a `hero` frontmatter contract.\",\n};\n\n/**\n * Apply this AFTER any `.extend()` so user-added fields are recognized\n * as valid. Wraps the schema in `.passthrough().superRefine()` so removed\n * keys raise a guided migration error; other unknown keys raise a\n * generic error pointing at `defineSchema({ extend: ... })`.\n */\nfunction withFrontmatterKeyCheck<T extends z.ZodObject<z.ZodRawShape>>(schema: T) {\n  return withStrictKeys(schema, {\n    removedKeys: REMOVED_FRONTMATTER_KEYS,\n    contextLabel: \"Frontmatter key\",\n    unknownHint: (key) =>\n      `If you meant to add a custom field, declare it in your collection's schema via \\`defineSchema({ extend: z.object({ ${key}: ... }) })\\`.`,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Base docs schema\n// ---------------------------------------------------------------------------\n\nfunction baseDocSchema() {\n  return z.object({\n    title: z.string({\n      error: (iss) =>\n        iss.input === undefined\n          ? 'Missing required \"title\" in frontmatter. Every doc needs:\\n\\n  ---\\n  title: \"Your Page Title\"\\n  ---'\n          : `\"title\" must be a string, received ${typeof iss.input}`,\n    }),\n    description: z.string({ error: '\"description\" must be a string' }).optional(),\n    mode: z\n      .enum([\"doc\", \"custom\"], {\n        error: '\"mode\" must be \"doc\" or \"custom\"',\n      })\n      .default(\"doc\"),\n    sidebar: z.union([z.literal(false), sidebarSchema]).optional(),\n    head: z.array(headElementSchema).default([]),\n    banner: bannerSchema.optional(),\n    draft: z.boolean({ error: '\"draft\" must be true or false' }).default(false),\n    noindex: z.boolean({ error: '\"noindex\" must be true or false' }).default(false),\n    /**\n     * Whether this page is included in the site search index. When omitted,\n     * derives from `noindex` (a page that's not crawlable is by default not\n     * searchable). Set explicitly to override — e.g. `{ noindex: true,\n     * searchable: true }` keeps the page out of search engines but findable\n     * in the site's own search.\n     */\n    searchable: z\n      .boolean({ error: '\"searchable\" must be true or false' })\n      .optional(),\n    tableOfContents: z\n      .union([\n        z.literal(false),\n        z\n          .object({\n            minHeadingLevel: z\n              .number({ error: '\"minHeadingLevel\" must be a number (1-6)' })\n              .int()\n              .min(1)\n              .max(6)\n              .default(2),\n            maxHeadingLevel: z\n              .number({ error: '\"maxHeadingLevel\" must be a number (1-6)' })\n              .int()\n              .min(1)\n              .max(6)\n              .default(3),\n          })\n          .refine((v) => v.minHeadingLevel <= v.maxHeadingLevel, {\n            message: \"minHeadingLevel must be <= maxHeadingLevel\",\n          }),\n      ])\n      .optional(),\n    lastUpdated: z.coerce\n      .date({ error: '\"lastUpdated\" must be a valid date (e.g. 2024-01-15)' })\n      .optional(),\n    /**\n     * Explicit per-page social/OG image override (path or absolute URL).\n     * When omitted, the page route is expected to fall back to a\n     * programmatically-generated card or the site-wide `config.socialImage`.\n     */\n    socialImage: z\n      .string({ error: '\"socialImage\" must be a string (path or URL)' })\n      .optional(),\n    prev: prevNextSchema,\n    next: prevNextSchema,\n    /**\n     * Versioning rename escape hatch.\n     *\n     * When a page is renamed between versions (the URL slug changes), the\n     * newer version's frontmatter declares the slug it had in an older\n     * version. The framework uses this to link the pages as cross-version\n     * alternates and to emit a `<link rel=\"canonical\">` to the current\n     * version's URL.\n     *\n     * Example: `docs-v1/old-name.mdx` was renamed in v2 to `new-name.mdx`.\n     * On the new page (`docs/new-name.mdx`, current version), set:\n     *\n     *   previousSlug: old-name\n     *\n     * Now `/new-name` and `/v1/old-name` are linked as the same logical\n     * page in `<head>` alternates, and the v1 page's canonical points to\n     * `/new-name`.\n     *\n     * Accepts a single slug string (the page's id in the older version)\n     * or an array of strings when the page has been renamed across more\n     * than one version.\n     */\n    previousSlug: z\n      .union([z.string(), z.array(z.string())], {\n        error: '\"previousSlug\" must be a string or array of strings',\n      })\n      .optional(),\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Build a customizable docs schema. Use this when composing schemas outside\n * the `docsCollection()` factory (e.g. multiple docs collections with\n * different shapes).\n *\n * For typed Astro `image()` fields or per-collection field narrowing, use\n * the richer `defineSchema(ctx => ...)` factory instead.\n */\nexport function defineDocSchema(config: DocSchemaConfig = {}) {\n  const base = baseDocSchema();\n  // Apply the unknown-key check AFTER extends so user-added fields are\n  // recognized as valid. Order matters — `.passthrough().superRefine()`\n  // returns a ZodEffects, which can't be further `.extend()`-ed.\n  const merged = config.fields ? base.extend(config.fields) : base;\n  return withFrontmatterKeyCheck(merged);\n}\n\n/**\n * Factory options for `defineSchema`.\n *\n *   - `extend`: additional fields merged into the framework schema. Use\n *     this for user-defined frontmatter (`author`, `tags`, `cover`).\n *   - `narrow`: replaces framework fields with tighter types within this\n *     collection. Use when a collection has stricter rules — e.g.\n *     `{ mode: z.literal(\"doc\") }` says no landing pages in this collection.\n */\nexport interface DefineSchemaOptions {\n  extend?: z.ZodTypeAny;\n  narrow?: Record<string, z.ZodTypeAny>;\n}\n\n/**\n * Build a typed docs schema with access to the Astro `SchemaContext`.\n * Use this when you want typed image fields (`ctx.image()`), per-\n * collection narrowing of framework fields, or both. The simpler\n * `defineDocSchema({ fields })` factory is still available for the\n * common case of just adding fields.\n *\n *   import { defineCollection } from \"astro:content\";\n *   import { z } from \"astro/zod\";\n *   import { defineSchema } from \"nimbus-docs/schemas\";\n *\n *   export const collections = {\n *     docs: defineCollection({\n *       loader: ...,\n *       schema: defineSchema((ctx) => ({\n *         extend: z.object({\n *           cover: ctx.image().optional(),\n *           author: z.string().optional(),\n *         }),\n *         narrow: {\n *           mode: z.literal(\"doc\"),  // no landing pages here\n *         },\n *       })),\n *     }),\n *   };\n */\nexport function defineSchema(\n  factory: (ctx: import(\"astro:content\").SchemaContext) => DefineSchemaOptions,\n) {\n  return (ctx: import(\"astro:content\").SchemaContext) => {\n    const { extend, narrow } = factory(ctx);\n    let schema = baseDocSchema() as z.ZodObject<any>;\n\n    // narrowing first (overrides framework fields)\n    if (narrow) {\n      schema = schema.extend(narrow);\n    }\n\n    // additive extension (new user fields). Prefer .merge for ZodObject\n    // (preserves object-ness for downstream .extend); fall back to .and\n    // for any other Zod type (intersection, union, etc.).\n    if (extend) {\n      if (extend instanceof z.ZodObject) {\n        schema = schema.merge(extend);\n      } else {\n        // Intersection path — `.and()` returns ZodIntersection, on which\n        // we can't run `withUnknownKeyCheck` (it operates on ZodObject's\n        // `.shape`). Users on this path lose the removed-key migration\n        // diagnostic; they own that trade-off by reaching for the\n        // non-object extend.\n        return schema.and(extend);\n      }\n    }\n\n    return withFrontmatterKeyCheck(schema);\n  };\n}\n\n/** Default docs schema. Equivalent to `defineDocSchema()`. */\nexport const docsSchema = defineDocSchema();\n\nconst partialsObjectSchema = z.object({\n  /**\n   * Declared parameters this partial accepts.\n   * Suffix with `?` for optional params: `[\"name\", \"deprecated?\"]`\n   */\n  params: z.array(z.string()).optional(),\n});\n\n/** Schema for partials (`<Render file=\"...\" />` snippets). */\nexport const partialsSchema = partialsObjectSchema.default({});\n\n// ---------------------------------------------------------------------------\n// Lenient variants — used by `nimbus-docs lint` (`nimbus/frontmatter-shape`).\n//\n// The standalone lint CLI can't yet see a site's extended\n// `content.config.ts` schema, so it validates the *types* of the fields\n// the framework owns while tolerating user-added fields (passthrough).\n// Unknown-key detection is deferred to when the engine can load the real\n// per-collection schema.\n// ---------------------------------------------------------------------------\n\n/** Docs frontmatter, framework fields type-checked, extra keys allowed. */\nexport const lenientDocsSchema = baseDocSchema().passthrough();\n\n/** Partials frontmatter, framework fields type-checked, extra keys allowed. */\nexport const lenientPartialsSchema = partialsObjectSchema.passthrough();\n\n// ---------------------------------------------------------------------------\n// Components collection — used by sites documenting their own UI components.\n// Pair with `componentsCollection()` from `nimbus-docs/content`. Authoring\n// pattern: hero `<Showcase>` block + `<Example>` blocks in the MDX body, with\n// `props` declared in frontmatter for a generated prop table.\n// ---------------------------------------------------------------------------\n\n/** One row in a component's `props` frontmatter array. */\nconst componentPropSchema = z.object({\n  name: z.string({ error: 'prop needs a \"name\"' }),\n  type: z.string({ error: 'prop needs a \"type\"' }),\n  defaultValue: z.string().optional(),\n  required: z.boolean().default(false),\n  description: z.string({ error: 'prop needs a \"description\"' }),\n});\n\nexport type ComponentProp = z.infer<typeof componentPropSchema>;\n\n/** Default schema for the components collection. */\nexport const componentsSchema = z.object({\n  title: z.string({\n    error: (iss) =>\n      iss.input === undefined\n        ? 'Missing \"title\" in frontmatter — display name used in the sidebar and page header.'\n        : `\"title\" must be a string, received ${typeof iss.input}`,\n  }),\n  tagline: z.string({\n    error: (iss) =>\n      iss.input === undefined\n        ? 'Missing \"tagline\" in frontmatter — one-sentence summary shown under the title.'\n        : `\"tagline\" must be a string, received ${typeof iss.input}`,\n  }),\n  props: z.array(componentPropSchema).default([]),\n});\n"],"mappings":"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"}

package/dist/strict-keys-BiXiT3pq.js

@@ -0,0 +1,35 @@
+//#region src/_internal/strict-keys.ts
+/**
+* Wrap `schema` so unknown keys raise issues at parse time. Captures
+* `Object.keys(schema.shape)` eagerly (before turning the schema into a
+* `ZodEffects` via `superRefine`) so the known-key set reflects the
+* schema as passed in. Call this AFTER any `.extend()` / `.merge()` so
+* user-added fields are recognized.
+*/
+function withStrictKeys(schema, options) {
+	const knownKeys = new Set(Object.keys(schema.shape));
+	return schema.passthrough().superRefine((data, ctx) => {
+		if (!data || typeof data !== "object") return;
+		for (const key of Object.keys(data)) {
+			if (knownKeys.has(key)) continue;
+			const removal = options.removedKeys[key];
+			if (removal) ctx.addIssue({
+				code: "custom",
+				path: [key],
+				message: `${options.contextLabel} "${key}" ${removal}`
+			});
+			else {
+				const hint = options.unknownHint?.(key);
+				ctx.addIssue({
+					code: "custom",
+					path: [key],
+					message: hint ? `Unknown ${options.contextLabel.toLowerCase()} "${key}". ${hint}` : `Unknown ${options.contextLabel.toLowerCase()} "${key}".`
+				});
+			}
+		}
+	});
+}
+
+//#endregion
+export { withStrictKeys as t };
+//# sourceMappingURL=strict-keys-BiXiT3pq.js.map

package/dist/strict-keys-BiXiT3pq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strict-keys-BiXiT3pq.js","names":[],"sources":["../src/_internal/strict-keys.ts"],"sourcesContent":["/**\n * Strict-key validation helper for Zod object schemas.\n *\n * Zod's default `.strip()` behavior silently drops unknown keys, which is\n * the wrong default for an authoring contract: a stale frontmatter or\n * config field that's been renamed or removed should fail loudly, not\n * vanish at parse time and produce subtly different behavior.\n *\n * This module wraps a `ZodObject` with `.passthrough().superRefine()` so\n * unknown keys survive the parse and get rejected with one issue per\n * key. Known-removed keys (passed via `removedKeys`) emit a friendly\n * migration message; everything else emits a generic \"unknown key\"\n * error with an actionable hint.\n *\n * Used by both the frontmatter schema (`src/schemas.ts`) and the config\n * schema (`src/_internal/validate.ts`). Each call site provides its own\n * `removedKeys` map and a `contextLabel` (\"Frontmatter key\" vs \"Config\n * field\" vs \"features.<key>\") so error messages read naturally.\n */\n\nimport type { z } from \"astro/zod\";\n\nexport interface StrictKeyOptions {\n  /**\n   * Map of removed-or-renamed keys → migration message. The message\n   * follows the contextLabel + key prefix; phrase it as the back-half of\n   * the sentence. Example: `'was renamed to \"mode\". Replace ...'`.\n   */\n  removedKeys: Record<string, string>;\n  /**\n   * Sentence-start label for the issue message. Examples: `Frontmatter\n   * key`, `Config field`, `features sub-key`. The key name (quoted) is\n   * appended automatically.\n   */\n  contextLabel: string;\n  /**\n   * Optional hint appended to the generic \"unknown key\" message for\n   * keys NOT in `removedKeys`. Receives the offending key. Use this to\n   * point users at the right escape hatch (e.g. how to add a custom\n   * field in their schema).\n   */\n  unknownHint?: (key: string) => string;\n}\n\n/**\n * Wrap `schema` so unknown keys raise issues at parse time. Captures\n * `Object.keys(schema.shape)` eagerly (before turning the schema into a\n * `ZodEffects` via `superRefine`) so the known-key set reflects the\n * schema as passed in. Call this AFTER any `.extend()` / `.merge()` so\n * user-added fields are recognized.\n */\nexport function withStrictKeys<T extends z.ZodObject<z.ZodRawShape>>(\n  schema: T,\n  options: StrictKeyOptions,\n) {\n  const knownKeys = new Set(Object.keys(schema.shape));\n  return schema.passthrough().superRefine((data, ctx) => {\n    if (!data || typeof data !== \"object\") return;\n    for (const key of Object.keys(data as Record<string, unknown>)) {\n      if (knownKeys.has(key)) continue;\n      const removal = options.removedKeys[key];\n      if (removal) {\n        ctx.addIssue({\n          code: \"custom\",\n          path: [key],\n          message: `${options.contextLabel} \"${key}\" ${removal}`,\n        });\n      } else {\n        const hint = options.unknownHint?.(key);\n        ctx.addIssue({\n          code: \"custom\",\n          path: [key],\n          message: hint\n            ? `Unknown ${options.contextLabel.toLowerCase()} \"${key}\". ${hint}`\n            : `Unknown ${options.contextLabel.toLowerCase()} \"${key}\".`,\n        });\n      }\n    }\n  });\n}\n"],"mappings":";;;;;;;;AAmDA,SAAgB,eACd,QACA,SACA;CACA,MAAM,YAAY,IAAI,IAAI,OAAO,KAAK,OAAO,MAAM,CAAC;AACpD,QAAO,OAAO,aAAa,CAAC,aAAa,MAAM,QAAQ;AACrD,MAAI,CAAC,QAAQ,OAAO,SAAS,SAAU;AACvC,OAAK,MAAM,OAAO,OAAO,KAAK,KAAgC,EAAE;AAC9D,OAAI,UAAU,IAAI,IAAI,CAAE;GACxB,MAAM,UAAU,QAAQ,YAAY;AACpC,OAAI,QACF,KAAI,SAAS;IACX,MAAM;IACN,MAAM,CAAC,IAAI;IACX,SAAS,GAAG,QAAQ,aAAa,IAAI,IAAI,IAAI;IAC9C,CAAC;QACG;IACL,MAAM,OAAO,QAAQ,cAAc,IAAI;AACvC,QAAI,SAAS;KACX,MAAM;KACN,MAAM,CAAC,IAAI;KACX,SAAS,OACL,WAAW,QAAQ,aAAa,aAAa,CAAC,IAAI,IAAI,KAAK,SAC3D,WAAW,QAAQ,aAAa,aAAa,CAAC,IAAI,IAAI;KAC3D,CAAC;;;GAGN"}