canopycms 0.0.67-int.90 → 0.0.67

package/dist/entry-schema.js

@@ -5,12 +5,6 @@ import { DEFAULT_SEO_FIELD_NAMES } from './static/seo.js';
  * The fields reference resolution adds to a target's own data, on top of whatever
  * `resolvedSchema` declares.
  *
- * These have always been returned at runtime (`resolveSingleReferenceOnce` in
- * content-store.ts) but were missing from the inferred type, so a resolved reference typed
- * narrower than it actually is — which is why reading `ref.id` needed a cast, and one source
- * of the library-internal type error `adopter-migration.md` records under
- * `exactOptionalPropertyTypes` + `skipLibCheck: false`.
- *
  * `urlPath` is what makes a resolved reference linkable without a second lookup; it follows
  * the same collection+slug rule `listEntries` publishes as `item.urlPath`, so an index entry
  * collapses to its parent path.
@@ -21,24 +15,20 @@ export const RESOLVED_REFERENCE_KEYS = ['id', 'slug', 'collection', 'urlPath'];
  * embed it, then the reserved metadata.
  *
  * Exists so the two places that construct one — the server resolver in content-store.ts and
- * the editor's live-preview endpoint in api/resolve-references.ts — cannot drift. They already
- * had: the preview endpoint kept the old `{ id, ...data }` order and carried none of the other
- * three keys, so a component rendering `<a href={ref.urlPath}>` showed `undefined` while
- * previewing and a real URL once published.
- *
- * The ordering is the contract, not a detail. Metadata last means a target that models `id` as
- * a content field cannot shadow the real content ID — which matters because the write boundary
- * recovers a reference's id from `value.id` (`referenceValueId`), so shadowing it made a
- * re-save persist the wrong value and silently repoint the reference. Body before metadata
- * closes the same hole for a body field named `id`; that schema is also rejected outright by
- * the entry schema registry, so this ordering is the guarantee and that check is the loud
- * error rather than a silent drop.
+ * the editor's live-preview endpoint in api/resolve-references.ts — cannot drift.
+ *
+ * The ordering is the contract, not a detail. Metadata LAST means a target that models `id` as
+ * a content field cannot shadow the real content ID, which the write boundary recovers from
+ * `value.id` (`referenceValueId`) — a shadowed id makes a re-save persist the wrong value and
+ * silently repoint the reference. Body before metadata closes the same hole for a body field
+ * named `id`; the entry schema registry also rejects that schema outright, so this ordering is
+ * the guarantee and that check is the loud error rather than a silent drop.
  */
 export function buildResolvedReference(data, meta, body) {
     const resolved = { ...data };
     // Truthiness, matching `readEntryData`'s own merge: a listed md entry with an empty body
     // carries no body key, so resolving one to `''` would reintroduce a listed-vs-resolved
-    // shape disagreement.
+    // shape mismatch.
     if (body && body.value)
         resolved[body.fieldName] = body.value;
     resolved.id = meta.id;
@@ -47,59 +37,44 @@ export function buildResolvedReference(data, meta, body) {
     resolved.urlPath = meta.urlPath;
     return resolved;
 }
-/**
- * Helper to define entry schema field arrays with literal inference without sprinkling `as const`.
- */
+/** Define an entry schema's field array with literal inference, without sprinkling `as const`. */
 export const defineEntrySchema = (fields) => fields;
 /**
- * Define a reusable inline field group — a visual container in the editor that groups
- * related fields together without creating a nested data key. The group's fields are
- * stored flat alongside the other fields in the content file.
- *
- * Use this when you want consistent visual organization across schemas without
- * changing your content file structure.
- *
- * For data-nested grouping (fields stored under a named key), use defineNestedFieldGroup().
+ * Define a reusable inline field group — a visual container in the editor that groups related
+ * fields without creating a nested data key, so they are stored FLAT alongside the other fields.
+ * Use it for consistent visual organization across schemas without changing the content file
+ * structure; for data-nested grouping, use defineNestedFieldGroup().
  *
  * @example
  * const seoGroup = defineInlineFieldGroup({
  *   name: 'seo',
  *   label: 'SEO',
- *   fields: [
- *     { name: 'metaTitle', type: 'string', label: 'Meta Title' },
- *     { name: 'metaDescription', type: 'string', label: 'Meta Description' },
- *   ],
+ *   fields: [{ name: 'metaTitle', type: 'string', label: 'Meta Title' }],
  * })
- * // TypeFromEntrySchema: { ..., metaTitle: string, metaDescription: string }
+ * // TypeFromEntrySchema: { ..., metaTitle: string }
  */
 export const defineInlineFieldGroup = (group) => ({ ...group, type: 'group' });
 /**
  * The recommended SEO field group, ready to drop into any entry schema.
  *
- * Emits the seven fields `extractSeoFields()` reads by default (`metaTitle`,
- * `metaDescription`, `ogImage`, `ogType`, `canonical`, `noindex`, `twitterCard`), so schema and
- * read side agree with no configuration. Every field is `required: false` — SEO metadata is
- * always optional, and an unset field must fall back rather than fail validation.
+ * Emits the seven fields `extractSeoFields()` reads by default (`metaTitle`, `metaDescription`,
+ * `ogImage`, `ogType`, `canonical`, `noindex`, `twitterCard`), so schema and read side agree with
+ * no configuration. Every field is `required: false`: SEO metadata is always optional, and an
+ * unset field must fall back rather than fail validation.
  *
- * **Flat by default.** The fields are stored flat in the content file (an inline group: a
- * visual container in the editor that adds no data key). Pass `group: 'seo'` for the nested
- * convention, which stores them under that key — and then pass the same `{ group: 'seo' }` to
- * `extractSeoFields` / `entryToMetadata`.
+ * **Flat by default** — an inline group, stored at the top level of the content file with no data
+ * key of its own. `group: 'seo'` nests them under that key instead, and the same
+ * `{ group: 'seo' }` must then be passed to `extractSeoFields` / `entryToMetadata`.
  *
  * @example
  * // Flat (recommended): frontmatter carries `metaTitle:` at the top level.
- * const pageSchema = defineEntrySchema([
- *   { name: 'title', type: 'string' },
- *   defineSeoFieldGroup(),
- * ])
- * // TypeFromEntrySchema: { title: string; metaTitle?: string; metaDescription?: string; ... }
+ * defineEntrySchema([{ name: 'title', type: 'string' }, defineSeoFieldGroup()])
+ * // TypeFromEntrySchema: { title: string; metaTitle?: string; ... }
  *
  * @example
- * // Nested: frontmatter carries `seo: { metaTitle: … }`.
- * const pageSchema = defineEntrySchema([defineSeoFieldGroup({ group: 'seo' })])
+ * // Nested: frontmatter carries `seo: { metaTitle: … }`, and the `seo` key is itself optional.
+ * defineEntrySchema([defineSeoFieldGroup({ group: 'seo' })])
  * const metadata = entryToMetadata(data, { group: 'seo' })
- * // TypeFromEntrySchema: { seo?: { metaTitle?: string; ... } } — the wrapper key itself is
- * // optional too, so an entry that sets no SEO fields at all can omit `seo` entirely.
  */
 const SEO_GROUP_FIELDS = [
     {
@@ -165,34 +140,27 @@ export function defineSeoFieldGroup(opts = {}) {
         : { ...base, name: 'seo', type: 'group' };
 }
 /**
- * Define a reusable nested field group — a visual container in the editor that groups
- * related fields under a named key in the content file.
- *
- * Use this when the fields logically belong together as a sub-object (e.g., seo.metaTitle)
- * and you want that structure reflected in your content files.
- *
- * For visual-only grouping without data nesting, use defineInlineFieldGroup().
+ * Define a reusable nested field group — a visual container in the editor whose fields are
+ * stored under a named key in the content file (e.g. seo.metaTitle). Use it when the fields
+ * belong together as a sub-object and that structure should be reflected on disk; for
+ * visual-only grouping without data nesting, use defineInlineFieldGroup().
  *
  * @example
  * const seoGroup = defineNestedFieldGroup({
  *   name: 'seo',
  *   label: 'SEO',
- *   fields: [
- *     { name: 'metaTitle', type: 'string', label: 'Meta Title' },
- *     { name: 'metaDescription', type: 'string', label: 'Meta Description' },
- *   ],
+ *   fields: [{ name: 'metaTitle', type: 'string', label: 'Meta Title' }],
  * })
- * // TypeFromEntrySchema: { ..., seo: { metaTitle: string, metaDescription: string } }
+ * // TypeFromEntrySchema: { ..., seo: { metaTitle: string } }
  */
 export const defineNestedFieldGroup = (group) => ({ ...group, type: 'object' });
 /**
  * Define a reusable block template once and embed it in multiple entry schemas' `block` fields.
  *
- * A `block` field holds an ordered, repeatable list of heterogeneous section blocks discriminated by
- * a `template` key (the "flexible content" / "page blocks" pattern). Defining each template inline in
- * every schema's `templates` array duplicates the field definitions; this const-inference identity
- * helper (like defineEntrySchema) lets you define a template once and reuse it across schemas while
- * still deriving the correct discriminated-union type via TypeFromEntrySchema.
+ * A `block` field holds an ordered, repeatable list of heterogeneous section blocks discriminated
+ * by a `template` key (the "flexible content" / "page blocks" pattern). This const-inference
+ * identity helper (like defineEntrySchema) keeps a template's field definitions in one place
+ * across schemas while TypeFromEntrySchema still derives the discriminated union.
  *
  * @example
  * const heroBlock = defineBlockTemplate({
@@ -207,10 +175,7 @@ export const defineNestedFieldGroup = (group) => ({ ...group, type: 'object' });
  *   name: 'cta',
  *   fields: [{ name: 'label', type: 'string' }, { name: 'href', type: 'string' }],
  * })
- *
- * // Reuse the same templates across multiple page schemas:
  * const pageSchema = defineEntrySchema([
- *   { name: 'title', type: 'string' },
  *   { name: 'sections', type: 'block', templates: [heroBlock, ctaBlock] },
  * ])
  * // TypeFromEntrySchema<typeof pageSchema>['sections'] narrows to:
@@ -219,32 +184,22 @@ export const defineNestedFieldGroup = (group) => ({ ...group, type: 'object' });
  */
 export const defineBlockTemplate = (template) => template;
 /**
- * Const-inference identity helper for a reusable field fragment — a plain array of field
- * configs (not a group, not a template) that you spread into multiple schemas' `fields`.
- * Exists purely for discoverability: `defineEntrySchema` and `defineBlockTemplate` already
- * infer literal types from a `const fields = [...] as const` array, so spreading it works
- * without this helper too. Wrapping the definition site in `defineFieldFragment(...)` just
- * makes the pattern easy to find (and to grep for) alongside `defineInlineFieldGroup` and
+ * Const-inference identity helper for a reusable field fragment — a plain array of field configs
+ * (not a group, not a template) spread into several schemas' `fields`. Purely for
+ * discoverability: `defineEntrySchema` and `defineBlockTemplate` already infer literal types from
+ * a `const fields = [...] as const` array, so spreading works without this helper; wrapping the
+ * definition site just makes the pattern easy to find alongside `defineInlineFieldGroup` and
  * `defineNestedFieldGroup`.
  *
- * Use this over a field group when you don't want the fields visually boxed together in
- * the editor, or when different schemas need to override one field (e.g. a different
- * `label` or `required`) — spread the fragment, then follow it with an object that
- * overrides just the field(s) that differ for that schema.
+ * Use it over a field group when the fields should not be visually boxed together in the editor,
+ * or when schemas need to override one field (a different `label` or `required`) — spread the
+ * fragment, then follow it with an object overriding just the fields that differ.
  *
  * @example
  * const ctaFields = defineFieldFragment([
  *   { name: 'ctaLabel', type: 'string', label: 'Button Label' },
  *   { name: 'ctaHref', type: 'string', label: 'Button Link' },
  * ])
- *
- * const heroSchema = defineEntrySchema([
- *   { name: 'headline', type: 'string' },
- *   ...ctaFields,
- * ])
- * const bannerSchema = defineEntrySchema([
- *   { name: 'message', type: 'string' },
- *   ...ctaFields,
- * ])
+ * const heroSchema = defineEntrySchema([{ name: 'headline', type: 'string' }, ...ctaFields])
  */
 export const defineFieldFragment = (fields) => fields;