kilo-cms 0.1.0

package/src/collections/types.ts

@@ -0,0 +1,336 @@
+// Pure types + slug types. MUST NOT import 'drizzle-orm', './db', 'server-only', or any
+// specific host's schema — this module is reachable from client components, AND it's the
+// package's own generic engine, not one host app's fixed list of content types.
+//
+// Slugs are runtime-registered (via defineKiloConfig({ collections: [...], singles: [...] }))
+// rather than a compile-time union — a host app has no fixed set of collections the package
+// could know about ahead of time. This trades away automatic exhaustiveness-checking inside
+// the engine itself (accepted: the engine already re-validates registrations at runtime, see
+// registry.ts's dev-mode assertions) for the host still getting real completion/exhaustiveness
+// in ITS OWN code: `npx kilo-cms sync` generates `.kilo/types.gen.ts` with a real
+// `CollectionSlug` union derived from the host's live config, the same way Prisma/Payload
+// generate types from config instead of hand-authoring a union.
+export type CollectionSlug = string
+export type SingleSlug = string
+export type EntrySlug = string
+
+export type FieldWidth = 'full' | 'half' | 'third'
+export type SelectOption = { value: string; label: string }
+
+// Split so `ArrayItemFieldConfig` below can share the per-field props that make sense
+// nested inside an array row, without the top-level-only ones (group/readOnly/listColumn/…).
+type FieldCore = {
+  key: string // MUST equal the drizzle column property name (or, for an array item, the object key)
+  label: string
+  width?: FieldWidth // default 'full'
+  hint?: string
+  /** Only honored on text/textarea/number/password inputs — an example value shown in the empty
+   *  input, not a default. Use `hint` instead for instructions that should stay visible once the
+   *  field has a value. */
+  placeholder?: string
+  required?: boolean // validation: value must be present/non-empty
+  nullable?: boolean // DB truth: set iff the drizzle column is NOT .notNull() (array items: always false)
+  /** Client-side hides the field unless the condition holds against the current record (or, for
+   *  an array/block item field, the current row). Server-side, `required` is only enforced when
+   *  the condition holds (evaluated against the submitted body/row) — a conditionally-hidden
+   *  required field never blocks save. `field` names a SIBLING field in the same record/row —
+   *  cross-row or cross-record conditions aren't supported. Exactly one comparator per condition
+   *  (no AND/OR combination in v1 — compose by gating a `group` field instead, if you need more
+   *  than one condition to control several fields at once). `gt`/`gte`/`lt`/`lte` coerce both
+   *  sides with `Number(...)` — only meaningful against a `number`/`rating` sibling field. */
+  visibleIf?:
+    | { field: string; equals: unknown }
+    | { field: string; notEquals: unknown }
+    | { field: string; in: unknown[] }
+    | { field: string; gt: number }
+    | { field: string; gte: number }
+    | { field: string; lt: number }
+    | { field: string; lte: number }
+}
+
+type FieldBase = FieldCore & {
+  group: string // MUST match an EntryConfig['groups'][n].id
+  readOnly?: boolean // rendered disabled; never accepted from the client
+  // Never rendered as a form control at all (not even disabled) — but still gets a blank value,
+  // still round-trips through save/read, and IS accepted from the client (unlike readOnly, which
+  // renders disabled and is stripped from the submitted body). For a value set by something other
+  // than the admin form (seed data, automation) that shouldn't be exposed for manual editing.
+  hidden?: boolean
+  listColumn?: boolean // include as a ListingView column
+  listPrimary?: boolean // exactly one per collection: the linked title cell
+  searchable?: boolean // joined into the ?q= ILIKE OR-clause (text/textarea only)
+  sortable?: boolean // allowed value for ?sortBy=
+  filterable?: boolean // exposed in FilterBuilder + server filter whitelist
+  /** Only honored on text/textarea/richtext. Storage becomes a per-locale map (see
+   *  `src/lib/collections/locale.ts`) instead of the field's normal scalar shape — declare the
+   *  drizzle column as `jsonb('…').$type<Record<Locale,string>>()`, never the type's normal
+   *  column type. `required` is enforced only for the default locale; other locales may stay
+   *  blank (the public/consuming side is expected to fall back to the default locale). */
+  localized?: boolean
+}
+
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
+
+export type FieldConfig =
+  | (FieldBase & {
+      type: 'text'
+      maxLength?: number
+      // 'password' renders masked with a show/hide toggle and formats as •••••••• in read-only
+      // views and list columns. It does NOT encrypt at rest or redact the value from API reads —
+      // for a real secret needing that, use a hand-written encrypted column (see
+      // emailSettings.encryptedPassword / webhooks.encryptedSecret) outside the generic engine.
+      // 'tel' is a loose shape check (digits/spaces/+-()), not real phone-number validation.
+      format?: 'plain' | 'slug' | 'email' | 'url' | 'password' | 'tel'
+      /** Only honored with format: 'slug'. When the submitted value is blank the server
+       *  derives it by slugifying this sibling field. Blank source ⇒ `draft-<id>`. */
+      slugFrom?: string
+      /** Renders an autocomplete + inline "+ Create new …" sourced from another collection's
+       *  titleField. The STORED VALUE STAYS A PLAIN STRING (the label), not a foreign key —
+       *  this is deliberately NOT a `relation`. */
+      suggestionsFrom?: { collection: CollectionSlug; createLabel?: string }
+    })
+  | (FieldBase & { type: 'textarea'; maxLength?: number; rows?: number })
+  // display: 'range' renders <input type=range> (min/max required to be meaningful) instead of a
+  // number box; 'percentage' keeps the number box but formats with a trailing % on read/list.
+  | (FieldBase & { type: 'number'; min?: number; max?: number; integer?: boolean; display?: 'plain' | 'currency' | 'percentage' | 'range' })
+  | (FieldBase & { type: 'boolean'; display?: 'toggle' | 'checkbox'; checkboxLabel?: string })
+  // display: 'radio' renders native radio inputs instead of a <select> dropdown — same
+  // storage/validation/options either way, purely a widget choice (mirrors boolean.display).
+  | (FieldBase & { type: 'select'; options: SelectOption[]; display?: 'dropdown' | 'radio' })
+  // drizzle: text('…') holding a 6-digit hex string like '#3366ff' (what <input type=color> produces)
+  | (FieldBase & { type: 'color' })
+  // drizzle: integer('…'), 0 = unrated. `max` is the star count (default 5).
+  | (FieldBase & { type: 'rating'; max?: number })
+  | (FieldBase & { type: 'date' }) // drizzle date()      -> 'YYYY-MM-DD' string
+  | (FieldBase & { type: 'time' }) // drizzle time()      -> 'HH:MM:SS' string
+  | (FieldBase & { type: 'datetime' }) // drizzle timestamp() -> Date, JSON'd as ISO
+  // hasMany: true stores an array of ids (jsonb, NEVER nullable, blank is []) instead of a single
+  // id (text, single FK). Declare the drizzle column accordingly — the two are different column
+  // TYPES, not a runtime toggle on the same column. Never filterable/searchable/sortable when
+  // hasMany (jsonb array); listColumn is fine (renders joined labels).
+  | (FieldBase & { type: 'relation'; relationTo: CollectionSlug; hasMany?: boolean })
+  // Read-only, no backing column — resolved at GET time by querying `collection` for rows whose
+  // `on` field points back at this record's id (the reverse of a `relation`). Payload's `join`.
+  // Never accepted from the client, never searchable/sortable/filterable. `listColumn: true` IS
+  // supported — the list route resolves every listColumn join with ONE batched query per field
+  // (grouped by `on`'s value across the current page's rows), the same way relation labels are
+  // batched — not one query per row.
+  | (FieldBase & { type: 'join'; collection: CollectionSlug; on: string })
+  // drizzle: jsonb('…').$type<RichTextDocument>().notNull().default({ type: 'doc', content: [{ type: 'paragraph' }] })
+  | (FieldBase & { type: 'richtext' })
+  // drizzle: text('…') nullable, or text('…').notNull() for required — a required image renders no Remove button
+  | (FieldBase & { type: 'image'; aspect?: number; allowUrlInput?: boolean })
+  // drizzle: jsonb('…').$type<string[]>().notNull().default([])  — ALWAYS .notNull(), never nullable
+  | (FieldBase & { type: 'tags'; maxTags?: number; maxTagLength?: number })
+  // drizzle: jsonb('…').$type<string[]>().notNull().default([]) — ALWAYS .notNull(), never nullable.
+  // A CLOSED option set (validated server-side); `tags` is the freeform counterpart.
+  | (FieldBase & { type: 'multiselect'; options: SelectOption[] })
+  // drizzle: jsonb('…').$type<ItemShape[]>().notNull().default([]) — ALWAYS .notNull(), never nullable.
+  // A repeatable list of structured rows (Payload's `array` / Filament's `Repeater`). Item
+  // sub-fields are intentionally restricted to `ArrayItemFieldConfig` below — no relation
+  // (would need relationOptions threaded per row), richtext/tags/multiselect, or nested array.
+  | (FieldBase & { type: 'array'; fields: ArrayItemFieldConfig[]; minItems?: number; maxItems?: number; itemLabel?: string })
+  // drizzle: jsonb('…').$type<BlockRow[]>().notNull().default([]) — ALWAYS .notNull(), never nullable.
+  // A repeatable list where each row can be one of several registered shapes (Payload's
+  // `blocks` / Sanity's portable blocks) — an `array` where the row shape itself is a
+  // discriminated union. Each stored row is `{ blockType, ...that type's own field values }`.
+  | (FieldBase & { type: 'blocks'; blockTypes: BlockTypeDef[]; minItems?: number; maxItems?: number })
+  // drizzle: jsonb('…').$type<Record<string,unknown>>().notNull().default({}) — ALWAYS .notNull().
+  // A nested object WITHOUT repetition (unlike array/blocks, always exactly one occurrence) —
+  // Payload's `group`. Own fields reuse `BlockFieldConfig` (scalar + one level of array), same
+  // nesting cap as a block. Not itself nestable inside array/block items in v1.
+  | (FieldBase & { type: 'group'; fields: BlockFieldConfig[] })
+  // drizzle: jsonb('…'), any JSON-serializable value. No schema — a raw JSON/code editor
+  // (textarea of JSON text, parsed client-side). For structured, validated data prefer a proper
+  // field type; this is the escape hatch when nothing else fits.
+  | (FieldBase & { type: 'json' })
+  // drizzle: jsonb('…').$type<{lat:number;lng:number}>() — plain lat/lng number inputs, no map
+  // picker (no map library dependency in this project; wire one later if actually needed).
+  | (FieldBase & { type: 'point' })
+  // drizzle: text('…'), same storage shape as `image` (a '/uploads/…' path or absolute URL) but
+  // for any file type the upload endpoint already allowlists (images/video/audio/pdf — see
+  // `/api/admin/upload`). `accept` is passed straight to the browser's file picker; the server
+  // allowlist is the real gate, `accept` is just a UX hint.
+  | (FieldBase & { type: 'file'; accept?: string })
+
+export type FieldType = FieldConfig['type']
+
+// Only the type-specific extras from FieldConfig's corresponding variant, plus FieldCore
+// (no group/readOnly/hidden/listColumn/listPrimary/searchable/sortable/filterable — none of
+// those mean anything for a field nested inside an array row). Derived via Omit, not
+// hand-duplicated, so a new prop added to one of these variants is automatically available on
+// array items too. Deliberately excludes: relation/join (external data/queries), richtext/tags/
+// multiselect (editor complexity), array/blocks/group (nesting depth), and `localized` (a
+// per-locale map inside a repeater row is more complexity than it's worth for v1).
+type ArrayItemFieldType = 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'date' | 'image' | 'color' | 'rating' | 'json' | 'point' | 'file'
+export type ArrayItemFieldConfig = DistributiveOmit<
+  Extract<FieldConfig, { type: ArrayItemFieldType }>,
+  'group' | 'readOnly' | 'hidden' | 'listColumn' | 'listPrimary' | 'searchable' | 'sortable' | 'filterable' | 'localized'
+>
+
+// A block's own fields: any scalar item type, OR one level of `array`-of-scalars (so e.g. a
+// "Stats" block can have a repeatable list of {label, value} rows). Deliberately NOT recursive —
+// the nested array's `fields` is the plain, non-recursive `ArrayItemFieldConfig`, so nesting is
+// capped at exactly block -> array -> scalar. No array-of-arrays, no block-in-block.
+export type BlockFieldConfig = ArrayItemFieldConfig | (FieldCore & { type: 'array'; fields: ArrayItemFieldConfig[]; minItems?: number; maxItems?: number; itemLabel?: string })
+export type BlockTypeDef = { type: string; label: string; fields: BlockFieldConfig[] }
+
+/** Shared parameter type for the engine functions (`blankValueForField`, `fieldSchema`,
+ *  `DynamicField`) that must handle a top-level field, an array item, or a block field —
+ *  `BlockFieldConfig` already includes `ArrayItemFieldConfig`, so this is the full set. */
+export type AnyFieldConfig = FieldConfig | ArrayItemFieldConfig | BlockFieldConfig
+
+export type CollectionGroup = { id: string; label: string; description?: string }
+
+export type WorkflowConfig = {
+  publish: true
+  audit: boolean
+  review: boolean
+  trash: boolean
+  approval?: 'setting' | 'always' | 'never'
+  sortOrder?: boolean
+  duplicate?: boolean
+  webhooks?: boolean
+  /** Requires `...schedulingColumns` on the table. `dateField`/`timeField` name DECLARED
+   *  fields (a `date` and an optional `time`) that the editor combines, in the browser's
+   *  local timezone, into the engine-owned `scheduledAt`. */
+  scheduling?: { dateField: string; timeField?: string }
+}
+
+export const workflowColumnKeys = [
+  'createdBy',
+  'ownerId',
+  'updatedBy',
+  'reviewerId',
+  'approverId',
+  'reviewStatus',
+  'reviewedAt',
+  'approvedAt',
+  'published',
+  'publishedAt',
+  'deletedAt',
+  'sortOrder',
+  'scheduledAt',
+] as const
+export type WorkflowColumnKey = typeof workflowColumnKeys[number]
+
+type EntryBase = {
+  label: string
+  description?: string
+  touchUpdatedAt: boolean
+  groups: CollectionGroup[]
+  fields: FieldConfig[]
+  workflow?: WorkflowConfig
+}
+
+export type CollectionConfig = EntryBase & {
+  kind: 'collection'
+  slug: CollectionSlug
+  labelSingular: string // 'Add product', 'New product'
+  titleField: string // field key used as the row title AND as the relation label
+  defaultSort: { field: string; dir: 'asc' | 'desc' }
+  /** Public URL template for the list's "Preview" row action, e.g. '/services/:slug'.
+   *  ':<fieldKey>' is substituted from the row. Omitted ⇒ no Preview action. */
+  previewPath?: string
+}
+
+export type SingleConfig = EntryBase & {
+  kind: 'single'
+  slug: SingleSlug
+  fixedKey: { column: string; value: string }
+}
+
+export type EntryConfig = CollectionConfig | SingleConfig
+
+export const workflowListFilters = [
+  { key: 'published', label: 'Status', type: 'boolean' as const, requires: 'publish' as const },
+  {
+    key: 'reviewStatus',
+    label: 'Approval status',
+    type: 'select' as const,
+    requires: 'review' as const,
+    options: [
+      { value: 'draft', label: 'Draft' },
+      { value: 'in_review', label: 'In review' },
+      { value: 'reviewed', label: 'Reviewed' },
+      { value: 'approved', label: 'Approved' },
+    ],
+  },
+] as const
+export const workflowSortKeys = ['published', 'publishedAt', 'sortOrder', 'reviewStatus', 'scheduledAt'] as const
+
+/** Engine-owned, default-hidden list columns. `requires` is a WorkflowConfig flag. */
+export const workflowListColumns = [
+  { key: 'reviewStatus', label: 'Approval status', requires: 'review' as const, kind: 'reviewStatus' as const },
+  { key: 'ownerId', label: 'Owner', requires: 'audit' as const, kind: 'user' as const },
+  { key: 'reviewerId', label: 'Reviewer', requires: 'review' as const, kind: 'user' as const },
+  { key: 'createdBy', label: 'Created by', requires: 'audit' as const, kind: 'user' as const },
+  { key: 'updatedBy', label: 'Last updated by', requires: 'audit' as const, kind: 'user' as const },
+  { key: 'approverId', label: 'Approved by', requires: 'review' as const, kind: 'user' as const },
+  { key: 'publishedAt', label: 'Published', requires: 'publish' as const, kind: 'datetime' as const },
+  { key: 'scheduledAt', label: 'Scheduled', requires: 'scheduling' as const, kind: 'datetime' as const },
+] as const
+
+// Authoring rules for defs/*.ts:
+// - nullable: true iff the drizzle column is NOT .notNull(). Drives whether "empty" becomes
+//   null or the type's zero value.
+// - required: true for any .notNull() column with no meaningful zero value.
+// - readOnly: true for createdAt / updatedAt / any DB-managed column.
+// - Exactly one field per collection has listPrimary: true, and it should also be listColumn: true.
+// - searchable is only honored on text / textarea.
+// - filterable is only honored on boolean / select / relation / text.
+// - richtext columns must never be nullable — the editor can't represent null, blank is
+//   the empty tiptap doc.
+// - image is a plain text() column holding a '/uploads/…' path or an absolute URL.
+// - tags columns must never be nullable — blank is [].
+// - searchable/filterable are NOT honored on richtext / image / tags (jsonb columns would
+//   need a cast + GIN index for ILIKE/containment that the engine doesn't build).
+// - time is a drizzle time() column holding 'HH:MM:SS'; it is nullable in practice — blank is null.
+// - multiselect columns must never be nullable — blank is []. searchable/filterable are NOT
+//   honored (jsonb containment would need a GIN index the engine doesn't build).
+// - text.suggestionsFrom does NOT change storage: the column stays plain text holding the label.
+//   Use `relation` when you actually want a foreign key.
+// - text.slugFrom is only honored when format === 'slug'.
+// - A slug is the URL segment, the RBAC key, the content-view key, and the webhook prefix.
+//   It does NOT have to equal the drizzle export name — `query.ts`'s `tables` map is the
+//   single place the two are bound (e.g. 'blog' -> blogPosts, 'homepage' -> pages).
+// - array columns must never be nullable — blank is []. searchable/filterable/sortable are
+//   NOT honored (jsonb, and item shape is arbitrary). listColumn renders an item-count summary,
+//   not the row contents. Item sub-fields (`field.fields`) never declare group/readOnly/
+//   listColumn/listPrimary/searchable/sortable/filterable — those are meaningless nested.
+// - text.format: 'password' does not change storage or validation (still plain text, still
+//   maxLength/required) — only the widget (masked + reveal toggle) and read-side masking
+//   (list columns, read-only views) change. Never mark a password field searchable/sortable.
+// - select.display: 'radio' does not change storage/validation either — still the same
+//   options/value shape as a dropdown select, only the widget changes.
+// - color is a plain text() column holding a 6-digit hex string ('#rrggbb'); blank defaults to
+//   '#000000' (not '""') so the swatch always has a valid value to show.
+// - blocks columns must never be nullable — blank is []. searchable/filterable/sortable are NOT
+//   honored, same as array. A block's own fields (`BlockTypeDef.fields`) never declare
+//   group/readOnly/listColumn/listPrimary/searchable/sortable/filterable, same as array items —
+//   the only nesting a block's fields may use is one `array` field of scalar items; no
+//   array-of-arrays and no block-in-block. `BlockTypeDef.type` values must be unique within one
+//   `blocks` field's `blockTypes` (it's the stored discriminant).
+// - hidden: true is a top-level-only modifier (never on an array/block item field). The field
+//   still gets a blank value, still round-trips through save/read, and IS accepted from the
+//   client — it's just never rendered as a form control. Different from readOnly (renders
+//   disabled, stripped from the submitted body).
+// - text.format: 'tel' is a loose shape check, not real phone-number validation — same
+//   storage/required rules as plain text.
+// - number.display: 'percentage' only changes read-side formatting (adds a trailing %); the
+//   edit-time control is still a plain number input, same as 'currency' today.
+// - number.display: 'range' DOES change the edit-time control (<input type=range>) — declare
+//   `min`/`max` or the slider has no meaningful bounds.
+// - rating is an integer() column, 0 = unrated (not null unless explicitly nullable). required
+//   means "must pick at least 1 star", not "column is non-null".
+// - relation.hasMany changes the drizzle column type entirely (jsonb string[] vs text) — never
+//   flip it on an existing field without a migration. hasMany relations are never
+//   filterable/searchable/sortable.
+// - join has NO backing column at all — never declare `readOnly: false` on it (it's implicitly
+//   read-only), never make it searchable/sortable/filterable/listColumn. `on` must name a
+//   declared `relation` field (not hasMany) on the target collection.
+// - group/json/point/file are plain additions — group is jsonb object (NOT NULL, blank {}), json
+//   is jsonb any-value, point is jsonb {lat,lng}, file is text() exactly like image but for any
+//   allowlisted upload mime type.
+// - visibleIf/localized are FieldCore/FieldBase modifiers, not new types — see their own doc
+//   comments above. Neither is available on array/block item fields.

package/src/collections/validation.ts

@@ -0,0 +1,217 @@
+import 'server-only'
+import { z } from 'zod'
+import { blankValueForField, isFieldVisible, richTextToText } from './values'
+import { fallbackLocaleConfig, type LocaleConfig } from './locale'
+import type { RichTextDocument } from '../richtext'
+import type { AnyFieldConfig, EntryConfig } from './types'
+
+export type ParseResult =
+  | { ok: true; data: Record<string, unknown> }
+  | { ok: false; error: string }
+
+/** 'live' validates required fields at full strength (the default). 'draft' relaxes required-ness —
+ *  used only by workflow-enabled collections saving an unpublished draft. */
+export type ParseMode = 'draft' | 'live'
+
+const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const uploadPathPattern = /^\/uploads\/(?:[a-z0-9-]+\/)?[a-z0-9-]+\.(jpg|png|webp)$/
+// A generic upload path — same shape as an image's, but any extension the upload endpoint
+// allowlists (mp4/webm/mov/mp3/wav/ogg/pdf/etc.), not just image formats.
+const uploadFilePattern = /^\/uploads\/(?:[a-z0-9-]+\/)?[a-z0-9-]+\.[a-z0-9]+$/
+// Loose shape check, not real phone-number validation — see FieldConfig text.format: 'tel'.
+const telPattern = /^[+\d][\d\s\-().]{5,}$/
+
+function relaxIfHidden<T extends AnyFieldConfig>(field: T, row: Record<string, unknown>): T {
+  return field.visibleIf && !isFieldVisible(field, row) ? { ...field, required: false } : field
+}
+
+/** Reparents a nested `z.object(...).safeParse` failure's issues onto the outer `ctx`, prefixed
+ *  by the row `index` (array/blocks) or left as-is (group, which has no index of its own). */
+function addIssuesAt(ctx: z.RefinementCtx, index: number | undefined, error: z.ZodError) {
+  for (const issue of error.issues) ctx.addIssue({ ...issue, path: index === undefined ? issue.path : [index, ...issue.path] })
+}
+
+function baseSchema(field: AnyFieldConfig, required: boolean, mode: ParseMode): z.ZodTypeAny {
+  switch (field.type) {
+    case 'text': {
+      let schema = z.string().max(field.maxLength ?? 255)
+      // Enforce the slug shape whenever the value is being validated at full strength, and
+      // unconditionally for slug fields that were never declared `required` (e.g. shop_*
+      // productCategories.slug, which is always parsed in 'live' mode anyway).
+      if (field.format === 'slug' && (required || !field.required)) schema = schema.regex(slugPattern, 'Use lowercase letters, numbers, and hyphens.')
+      if (field.format === 'email') schema = schema.email('Enter a valid email address.')
+      if (field.format === 'url') schema = schema.url('Enter a valid URL.')
+      if (field.format === 'tel') schema = schema.regex(telPattern, 'Enter a valid phone number.')
+      return required ? schema.trim().min(1, 'This field is required.') : schema
+    }
+    case 'textarea': {
+      const schema = z.string().max(field.maxLength ?? 5000)
+      return required ? schema.trim().min(1, 'This field is required.') : schema
+    }
+    case 'number': {
+      let schema = z.number()
+      if (field.integer) schema = schema.int('Must be a whole number.')
+      if (typeof field.min === 'number') schema = schema.min(field.min)
+      if (typeof field.max === 'number') schema = schema.max(field.max)
+      return schema
+    }
+    case 'boolean':
+      return z.boolean()
+    case 'color':
+      return z.string().regex(/^#[0-9a-f]{6}$/i, 'Use a hex color like #3366ff.')
+    case 'rating': {
+      const schema = z.number().int().min(0).max(field.max ?? 5)
+      return required ? schema.refine((value) => value > 0, 'Pick a rating.') : schema
+    }
+    case 'select': {
+      const values = field.options.map((option) => option.value)
+      // Deliberately a refine rather than z.enum: z.enum's tuple requirement is awkward
+      // with a runtime array and its typing varies across zod majors.
+      return z.string().refine((value) => values.includes(value), 'Not a valid option.')
+    }
+    case 'date':
+      return z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Use the YYYY-MM-DD format.')
+    case 'datetime':
+      return z.coerce.date()
+    case 'relation': {
+      if (field.hasMany) {
+        const list = z.array(z.string().trim().min(1).max(200)).max(200)
+        return required ? list.min(1, 'Pick at least one related record.') : list
+      }
+      return required ? z.string().trim().min(1, 'Pick a related record.').max(200) : z.string().max(200)
+    }
+    case 'join':
+      return z.unknown() // no backing column, never accepted from the client — see collectionBodySchema
+    case 'richtext': {
+      const doc = z
+        .object({ type: z.literal('doc'), content: z.array(z.unknown()).optional() })
+        .passthrough()
+        .transform((value) => value as unknown as RichTextDocument)
+      return required
+        ? doc.refine((value) => richTextToText(value, 400).trim().length > 0, 'This field is required.')
+        : doc
+    }
+    case 'image':
+      // '' never reaches here for a non-required field — fieldSchema's preprocess collapses it
+      // to the blank value first. A required image therefore rejects '' via this union.
+      return z.union([
+        z.string().url('Enter a valid image URL.'),
+        z.string().regex(uploadPathPattern, 'Upload a file, or paste a full https:// URL.'),
+      ])
+    case 'tags': {
+      const list = z.array(z.string().trim().min(1).max(field.maxTagLength ?? 40)).max(field.maxTags ?? 20)
+      return required ? list.min(1, 'Add at least one tag.') : list
+    }
+    case 'time':
+      return z.string().regex(/^\d{2}:\d{2}(:\d{2})?$/, 'Use the HH:MM format.')
+    case 'multiselect': {
+      const values = field.options.map((option) => option.value)
+      const list = z.array(z.string().refine((value) => values.includes(value), 'Not a valid option.')).max(field.options.length)
+      return required ? list.min(1, 'Choose at least one option.') : list
+    }
+    // array/blocks/group all validate each row/object against a schema built FROM THAT ROW,
+    // not a single static schema shared by every row — that's what lets an item sub-field's
+    // own `visibleIf` (gated on a SIBLING field in the same row) relax `required` server-side
+    // too, the same way top-level `visibleIf` already does via `collectionBodySchema`. Plain
+    // `z.array(z.object(staticShape))` can't do this: the shape has to be recomputed per row.
+    case 'array': {
+      let base = z.array(z.unknown())
+      if (typeof field.maxItems === 'number') base = base.max(field.maxItems)
+      const min = required ? Math.max(field.minItems ?? 1, 1) : field.minItems
+      if (typeof min === 'number') base = base.min(min, required ? 'Add at least one item.' : `Add at least ${min}.`)
+      return base.transform((rows, ctx) => rows.map((row, index) => {
+        const plainRow = (row && typeof row === 'object' ? row : {}) as Record<string, unknown>
+        const itemShape = Object.fromEntries(field.fields.map((item) => [item.key, fieldSchema(relaxIfHidden(item, plainRow), mode)]))
+        const result = z.object(itemShape).safeParse(row)
+        if (!result.success) { addIssuesAt(ctx, index, result.error); return plainRow }
+        return result.data
+      }))
+    }
+    case 'blocks': {
+      let base = z.array(z.unknown())
+      if (typeof field.maxItems === 'number') base = base.max(field.maxItems)
+      const min = required ? Math.max(field.minItems ?? 1, 1) : field.minItems
+      if (typeof min === 'number') base = base.min(min, required ? 'Add at least one block.' : `Add at least ${min}.`)
+      return base.transform((rows, ctx) => rows.map((row, index) => {
+        const plainRow = (row && typeof row === 'object' ? row : {}) as Record<string, unknown>
+        const blockDef = field.blockTypes.find((def) => def.type === plainRow.blockType)
+        if (!blockDef) { ctx.addIssue({ code: 'custom', path: [index, 'blockType'], message: 'Unknown block type.' }); return plainRow }
+        const itemShape: Record<string, z.ZodTypeAny> = { blockType: z.literal(blockDef.type) }
+        for (const item of blockDef.fields) itemShape[item.key] = fieldSchema(relaxIfHidden(item, plainRow), mode)
+        const result = z.object(itemShape).safeParse(row)
+        if (!result.success) { addIssuesAt(ctx, index, result.error); return plainRow }
+        return result.data
+      }))
+    }
+    case 'group':
+      return z.unknown().transform((raw, ctx) => {
+        const plainRow = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+        const itemShape = Object.fromEntries(field.fields.map((subfield) => [subfield.key, fieldSchema(relaxIfHidden(subfield, plainRow), mode)]))
+        const result = z.object(itemShape).safeParse(raw)
+        if (!result.success) { addIssuesAt(ctx, undefined, result.error); return plainRow }
+        return result.data
+      })
+    case 'json':
+      return z.unknown()
+    case 'point':
+      return z.object({ lat: z.number().min(-90).max(90), lng: z.number().min(-180).max(180) })
+    case 'file':
+      return z.union([
+        z.string().url('Enter a valid file URL.'),
+        z.string().regex(uploadFilePattern, 'Upload a file, or paste a full https:// URL.'),
+      ])
+  }
+}
+
+/** Wraps the base schema so "missing"/"empty" collapses to the field's blank value.
+ *  `localeConfig` defaults to the static fallback — API routes pass the live admin-configured
+ *  one (see `getLocaleConfig()`) so validation actually enforces whatever locales are live, not
+ *  a stale baked-in pair. */
+export function fieldSchema(field: AnyFieldConfig, mode: ParseMode = 'live', localeConfig: LocaleConfig = fallbackLocaleConfig): z.ZodTypeAny {
+  if ('localized' in field && field.localized) {
+    // required only enforced for the default locale — other locales may stay untranslated.
+    return z.object(Object.fromEntries(localeConfig.codes.map((locale) => [
+      locale,
+      fieldSchema({ ...field, localized: false, required: locale === localeConfig.default ? field.required : false } as AnyFieldConfig, mode, localeConfig),
+    ])))
+  }
+  const blank = blankValueForField(field, localeConfig)
+  const required = mode === 'live' && Boolean(field.required)
+  const inner = baseSchema(field, required, mode)
+  if (required && !field.nullable) return inner
+  return z.preprocess(
+    (value) => (value === undefined || value === null || value === '' ? undefined : value),
+    inner.optional().transform((value) => (value === undefined ? blank : value)),
+  )
+}
+
+/** `body` (when given) relaxes `required` for any field whose `visibleIf` doesn't hold against
+ *  it — a conditionally-hidden required field never blocks save. Evaluated against the raw
+ *  submitted body, not the stored row, since the gating field's new value is right there in it.
+ *  `allowedFields` (when given) ALSO relaxes `required` for any field the caller has no write
+ *  permission for — `applyFieldPermissions` silently overwrites those with the row's existing
+ *  value after validation anyway, so requiring them here would let a role without access to one
+ *  required field block every OTHER edit to the record too (it can never submit a real value for
+ *  a field it can't even see, especially now that read-redaction omits it from the record
+ *  entirely — see `redactFieldsForRead`). */
+export function collectionBodySchema(config: EntryConfig, mode: ParseMode = 'live', body?: Record<string, unknown>, allowedFields?: string[], localeConfig: LocaleConfig = fallbackLocaleConfig) {
+  const shape: Record<string, z.ZodTypeAny> = {}
+  for (const field of config.fields) {
+    if (field.readOnly || field.type === 'join') continue // never accepted from the client
+    const hidden = field.visibleIf && body && !isFieldVisible(field, body)
+    const unwritable = allowedFields && !allowedFields.includes(field.key)
+    const effective = hidden || unwritable ? { ...field, required: false } : field
+    shape[field.key] = fieldSchema(effective, mode, localeConfig)
+  }
+  return z.object(shape).strip() // unknown keys (including id) are dropped
+}
+
+export function formatZodError(error: z.ZodError): string {
+  return error.issues.map((issue) => `${issue.path.join(' ')}: ${issue.message}`).join(' · ')
+}
+
+export function parseCollectionBody(config: EntryConfig, body: unknown, mode: ParseMode = 'live', allowedFields?: string[], localeConfig: LocaleConfig = fallbackLocaleConfig): ParseResult {
+  const rawBody = body && typeof body === 'object' ? (body as Record<string, unknown>) : undefined
+  const parsed = collectionBodySchema(config, mode, rawBody, allowedFields, localeConfig).safeParse(body)
+  return parsed.success ? { ok: true, data: parsed.data } : { ok: false, error: formatZodError(parsed.error) }
+}