@michaelthielemann/kestrel 1.2.1

package/layers/fields/app/utils/condition.ts

@@ -0,0 +1,71 @@
+import type { Condition, ConditionOperator, ConditionRule } from '../../../core/server/utils/defineCollection'
+
+/** Empty = absent or a "no value" (null/undefined/''/[]). Shared by the evaluator (the `empty`
+ *  operator + bare-rule presence) and the server's required-when-visible check. 0 and false are values. */
+export function isEmptyValue(value: unknown): boolean {
+  return value === null || value === undefined || value === '' || (Array.isArray(value) && value.length === 0)
+}
+
+// v1 path scope is SIBLING-ONLY. A bare name or `./name` resolves a sibling in the current scope;
+// cross-scope forms (`/abs`, `../parent`, dotted `a.b`) are out of v1 and resolve to undefined — so the
+// rule is simply false (the field hides), keeping the evaluator total: it never throws on a bad path.
+function resolvePath(field: string, scope: Record<string, unknown>): unknown {
+  const key = field.startsWith('./') ? field.slice(2) : field
+  if (key === '' || key.startsWith('/') || key.startsWith('..') || key.includes('/') || key.includes('.')) {
+    return undefined
+  }
+  return scope[key]
+}
+
+function compare(dep: unknown, target: number | string, op: 'gt' | 'gte' | 'lt' | 'lte'): boolean {
+  if (typeof dep !== typeof target || (typeof dep !== 'number' && typeof dep !== 'string')) return false
+  if (op === 'gt') return dep > target
+  if (op === 'gte') return dep >= target
+  if (op === 'lt') return dep < target
+  return dep <= target
+}
+
+function matchOperator(dep: unknown, op: ConditionOperator): boolean {
+  for (const [key, target] of Object.entries(op)) {
+    if (target === undefined) continue
+    let ok: boolean
+    switch (key) {
+      case 'eq': ok = dep === target; break
+      case 'ne': ok = dep !== target; break
+      case 'gt': case 'gte': case 'lt': case 'lte':
+        ok = compare(dep, target as number | string, key); break
+      case 'in': ok = Array.isArray(target) && (target as unknown[]).includes(dep); break
+      case 'notIn': ok = Array.isArray(target) && !(target as unknown[]).includes(dep); break
+      case 'regexp': {
+        if (typeof dep !== 'string' || typeof target !== 'string') { ok = false; break }
+        try { ok = new RegExp(target).test(dep) } catch { ok = false }
+        break
+      }
+      case 'empty': ok = target ? isEmptyValue(dep) : !isEmptyValue(dep); break
+      default: ok = false
+    }
+    if (!ok) return false
+  }
+  return true
+}
+
+function evaluateRule(rule: ConditionRule, scope: Record<string, unknown>): boolean {
+  const dep = resolvePath(rule.field, scope)
+  if (rule.is !== undefined) return dep === rule.is
+  if (rule.op) return matchOperator(dep, rule.op)
+  return !isEmptyValue(dep)
+}
+
+/** Pure, total (never throws) condition evaluator shared by the editor (hide widgets) and the server
+ *  (required-when-visible). `scope` is the sibling-value map the condition resolves against. */
+export function evaluateCondition(condition: Condition, scope: Record<string, unknown>): boolean {
+  if ('and' in condition) return condition.and.every((c) => evaluateCondition(c, scope))
+  if ('or' in condition) return condition.or.some((c) => evaluateCondition(c, scope))
+  if ('not' in condition) return !evaluateCondition(condition.not, scope)
+  return evaluateRule(condition, scope)
+}
+
+/** Whether a field is shown given the sibling-value `scope`. No condition => always visible. */
+export function isFieldVisible(field: { condition?: Condition } | null | undefined, scope: Record<string, unknown>): boolean {
+  return !field?.condition || evaluateCondition(field.condition, scope)
+}

package/layers/fields/app/utils/define-block.ts

@@ -0,0 +1,13 @@
+/**
+ * Runtime no-op for a block SFC's metadata call — `defineBlock({ label, slots, icon })`. The metadata is
+ * read at BUILD time by the SFC extractor (from the same call, statically); at runtime this only exists so
+ * the SFC's `<script setup>` doesn't reference an undefined `defineBlock`. Auto-imported in the app so block
+ * authors call it without an import (the field factories are auto-imported the same way).
+ */
+export function defineBlock(_meta?: {
+  label?: string | Record<string, string>
+  slots?: string[]
+  icon?: string
+}): void {
+  // intentionally empty — see above.
+}

package/layers/fields/app/utils/field-constraints.ts

@@ -0,0 +1,17 @@
+import type { FieldDef } from '../../../core/server/utils/defineCollection'
+
+type NumberOptions = Extract<FieldDef, { type: 'number' }>['options']
+type ChoiceOptions = Extract<FieldDef, { type: 'choice' }>['options']
+
+/**
+ * Whether a number field is integer-valued — the default — i.e. neither
+ * `integer: false` nor a `decimals` precision opts it into reals.
+ */
+export function numberIsInteger(options: NumberOptions): boolean {
+  return options?.integer !== false && options?.decimals === undefined
+}
+
+/** The allowed values of a choice field, as a non-empty tuple (for `z.enum`). */
+export function choiceValues(options: ChoiceOptions): [string, ...string[]] {
+  return options.choices.map((c) => c.value) as [string, ...string[]]
+}

package/layers/fields/app/utils/field-factories.ts

@@ -0,0 +1,129 @@
+import type { FieldDef } from '../../../core/server/utils/defineCollection'
+
+/**
+ * Field factories for single-file (SFC) block authoring, à la Pruvious. A block's schema is declared as its
+ * component's `defineProps({ heading: textField({ required: true }), … })`; each factory returns a DUAL
+ * object — a Vue prop descriptor (`type` = a JS-global constructor) that ALSO carries the Kestrel `FieldDef`
+ * under `[KESTREL_FIELD]`. Vue reads `type` at runtime; the build-time SFC extractor reads `[KESTREL_FIELD]`.
+ *
+ * This file imports NO Vue/Nuxt runtime (only JS globals), so it is importable BOTH in the browser (the SFC's
+ * props declaration) AND by the Node extractor that injects these factories to evaluate a block's schema.
+ * `Symbol.for` (global registry) keeps the key identical even if the file is instantiated twice.
+ */
+export const KESTREL_FIELD = Symbol.for('kestrel.field')
+
+export interface FieldFactoryResult<C = unknown> {
+  /** A Vue prop constructor (String / Number / Boolean / Object / Array) — the runtime prop shape. Typed as
+   *  the specific constructor so Vue's `defineProps` accepts the factory result AND infers the prop's value
+   *  type (`textField()` → `string`, `mediaField()` → `number`, …). */
+  type: C
+  /** The Kestrel field definition the extractor lifts into the block's schema. */
+  [KESTREL_FIELD]: FieldDef
+}
+
+// Keys that belong on the FieldDef itself (not inside `options`); everything else a factory receives is a
+// type-specific option. Mirrors `BaseFieldDef` in defineCollection.ts.
+const BASE_KEYS = new Set(['required', 'translatable', 'unique', 'label', 'default', 'condition', 'renamedFrom', 'populate'])
+
+function partition(opts: Record<string, unknown>): { base: Record<string, unknown>; options: Record<string, unknown> } {
+  const base: Record<string, unknown> = {}
+  const options: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(opts)) (BASE_KEYS.has(k) ? base : options)[k] = v
+  return { base, options }
+}
+
+function wrap<C>(def: Record<string, unknown>, vueType: C): FieldFactoryResult<C> {
+  // The factory assembles the FieldDef structurally (open discriminated union); cast through `unknown`.
+  return { type: vueType, [KESTREL_FIELD]: def as unknown as FieldDef }
+}
+
+/** A leaf field: base props at the top level, everything else under `options`. */
+function leaf<C>(type: string, vueType: C) {
+  return (opts: Record<string, unknown> = {}): FieldFactoryResult<C> => {
+    const { base, options } = partition(opts)
+    const def: Record<string, unknown> = { type, ...base }
+    if (Object.keys(options).length) def.options = options
+    return wrap(def, vueType)
+  }
+}
+
+/** Generic escape hatch for a CUSTOM field type (registered via `defineFieldType`) that has no dedicated
+ *  factory — `field('secureGallery', { … })`. Base props split off the top level, the rest into `options`;
+ *  the Vue prop is typed `Object` (unknown value shape). */
+export function field(type: string, opts: Record<string, unknown> = {}): FieldFactoryResult<ObjectConstructor> {
+  const { base, options } = partition(opts)
+  const def: Record<string, unknown> = { type, ...base }
+  if (Object.keys(options).length) def.options = options
+  return wrap(def, Object)
+}
+
+export const textField = leaf('text', String)
+export const slugField = leaf('slug', String)
+export const richtextField = leaf('richtext', String)
+export const numberField = leaf('number', Number)
+export const booleanField = leaf('boolean', Boolean)
+export const jsonField = leaf('json', Object)
+export const linkField = leaf('link', Object)
+
+/** Media: `multiple` (stored bare, an id array) → Array prop; single (a `<name>Id` FK) → Number prop. */
+export function mediaField(opts: Record<string, unknown> = {}): FieldFactoryResult<ArrayConstructor | NumberConstructor> {
+  const { base, options } = partition(opts)
+  const def: Record<string, unknown> = { type: 'media', ...base }
+  if (Object.keys(options).length) def.options = options
+  return wrap(def, options.multiple ? Array : Number)
+}
+
+/** Choice: `multiple` → the value is a `string[]` (Array prop), single → a `string` (String prop). */
+export function choiceField(opts: Record<string, unknown> = {}): FieldFactoryResult<ArrayConstructor | StringConstructor> {
+  const { base, options } = partition(opts)
+  const def: Record<string, unknown> = { type: 'choice', ...base }
+  if (Object.keys(options).length) def.options = options
+  return wrap(def, options.multiple ? Array : String)
+}
+
+/** Datetime: `range` → the value is a `{ start, end }` object (Object prop), else a `string` (String prop). */
+export function datetimeField(opts: Record<string, unknown> = {}): FieldFactoryResult<ObjectConstructor | StringConstructor> {
+  const { base, options } = partition(opts)
+  const def: Record<string, unknown> = { type: 'datetime', ...base }
+  if (Object.keys(options).length) def.options = options
+  return wrap(def, options.range ? Object : String)
+}
+
+/** Relation: `collection`/`many`/`labelField` map into `relation`; `many` → Array prop, single → Number. */
+export function relationField(opts: Record<string, unknown> = {}): FieldFactoryResult<ArrayConstructor | NumberConstructor> {
+  const { collection, many, labelField, ...rest } = opts as {
+    collection?: string
+    many?: boolean
+    labelField?: string
+  } & Record<string, unknown>
+  if (typeof collection !== 'string' || !collection) {
+    throw new Error('relationField requires a `collection` (the target collection name)')
+  }
+  const { base, options } = partition(rest)
+  const relation: Record<string, unknown> = { collection }
+  if (many) relation.many = many
+  if (labelField) relation.labelField = labelField
+  const def: Record<string, unknown> = { type: 'relation', ...base, relation }
+  if (Object.keys(options).length) def.options = options
+  return wrap(def, many ? Array : Number)
+}
+
+/** Repeater: sub-fields are authored as factory calls too — unwrap each to its FieldDef (recursively).
+ *  `fieldLayout` (the sub-field editor layout) forwards into `options` instead of being dropped. */
+export function repeaterField(opts: Record<string, unknown> = {}): FieldFactoryResult<ArrayConstructor> {
+  const { fields, fieldLayout, ...rest } = opts as { fields?: Record<string, unknown>; fieldLayout?: unknown } & Record<string, unknown>
+  const { base } = partition(rest)
+  const options: Record<string, unknown> = { fields: unwrapFields(fields ?? {}) }
+  if (fieldLayout !== undefined) options.fieldLayout = fieldLayout
+  return wrap({ type: 'repeater', ...base, options }, Array)
+}
+
+/** Convert a `{ name: <factory-result | FieldDef> }` map into a `{ name: FieldDef }` map. A nested repeater's
+ *  result already carries a fully-unwrapped def, so recursion is implicit. */
+function unwrapFields(fields: Record<string, unknown>): Record<string, FieldDef> {
+  const out: Record<string, FieldDef> = {}
+  for (const [k, v] of Object.entries(fields)) {
+    out[k] = v && typeof v === 'object' && KESTREL_FIELD in v ? (v as FieldFactoryResult)[KESTREL_FIELD] : (v as FieldDef)
+  }
+  return out
+}

package/layers/fields/app/utils/field-meta.ts

@@ -0,0 +1,33 @@
+import type { FieldDef, FieldOf } from '../../../core/server/utils/defineCollection'
+import { numberIsInteger } from './field-constraints'
+
+export interface FieldConstraints {
+  required: boolean
+  minlength?: number
+  maxlength?: number
+  min?: number
+  max?: number
+  step?: number | 'any'
+  multiline?: boolean
+}
+
+/** Input-relevant attributes derived from a FieldDef, for the field widgets. */
+export function fieldConstraints(field: FieldDef): FieldConstraints {
+  const c: FieldConstraints = { required: !!field.required }
+  // `field as FieldOf<'x'>`: the open consumer arm makes `type` a non-discriminant, so `field.type === 'x'`
+  // doesn't narrow `field` — the cast applies the arm the guard just proved. (App-side: type-only, no
+  // runtime import of the server-side `fieldIs` guard into the client bundle.)
+  if (field.type === 'text') {
+    const f = field as FieldOf<'text'>
+    if (f.options?.minLength !== undefined) c.minlength = f.options.minLength
+    if (f.options?.maxLength !== undefined) c.maxlength = f.options.maxLength
+    if (f.options?.multiline) c.multiline = true
+  } else if (field.type === 'number') {
+    const f = field as FieldOf<'number'>
+    if (f.options?.min !== undefined) c.min = f.options.min
+    if (f.options?.max !== undefined) c.max = f.options.max
+    if (f.options?.decimals !== undefined) c.step = 1 / 10 ** f.options.decimals
+    else c.step = numberIsInteger(f.options) ? 1 : 'any'
+  }
+  return c
+}

package/layers/fields/app/utils/field-validate.ts

@@ -0,0 +1,75 @@
+import type { FieldDef, FieldOf } from '../../../core/server/utils/defineCollection'
+import { choiceValues, numberIsInteger } from './field-constraints'
+
+function isEmpty(value: unknown): boolean {
+  return value === undefined || value === null || value === ''
+}
+
+/**
+ * Advisory client-side validation for instant feedback. A lightweight mirror of a
+ * subset of the server rules — the server Zod schema stays the sole authority.
+ */
+export function validateField(field: FieldDef, value: unknown): string | null {
+  if (isEmpty(value)) return field.required ? 'This field is required.' : null
+
+  switch (field.type) {
+    case 'text': {
+      if (typeof value !== 'string') return null
+      const { minLength, maxLength } = (field as FieldOf<'text'>).options ?? {}
+      if (minLength !== undefined && value.length < minLength) return `Must be at least ${minLength} characters.`
+      if (maxLength !== undefined && value.length > maxLength) return `Must be at most ${maxLength} characters.`
+      return null
+    }
+    case 'number': {
+      if (typeof value !== 'number' || Number.isNaN(value)) return 'Must be a number.'
+      const opts = (field as FieldOf<'number'>).options
+      const { min, max } = opts ?? {}
+      if (numberIsInteger(opts) && !Number.isInteger(value)) return 'Must be a whole number.'
+      if (min !== undefined && value < min) return `Must be at least ${min}.`
+      if (max !== undefined && value > max) return `Must be at most ${max}.`
+      return null
+    }
+    // The widget model is always already-parsed (Json.vue stores `JSON.parse(raw)`, never raw text), so a
+    // json field's value here is never source to re-parse — even when it happens to be a plain string
+    // (e.g. `default: 'dark'`). The widget owns raw-text parse errors itself via its own `localError`.
+    case 'json':
+      return null
+    case 'datetime': {
+      const dt = (field as FieldOf<'datetime'>).options
+      const p = dt?.precision ?? 'datetime'
+      const re = p === 'date'
+        ? /^\d{4}-\d{2}-\d{2}$/
+        : p === 'time'
+          ? /^\d{2}:\d{2}(:\d{2})?$/
+          : /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?$/
+      if (dt?.range) {
+        const v = value && typeof value === 'object' ? (value as { start?: unknown; end?: unknown }) : {}
+        const start = typeof v.start === 'string' ? v.start : ''
+        const end = typeof v.end === 'string' ? v.end : ''
+        // A picker mid-selection (one endpoint chosen, the other still blank) is invalid regardless of
+        // `required` — the server only ever accepts a fully-filled range or a fully-empty one.
+        if (!start && !end) return field.required ? 'This field is required.' : null
+        if (!start || !end) return 'Both start and end are required.'
+        if (!re.test(start)) return 'Invalid start.'
+        if (!re.test(end)) return 'Invalid end.'
+        if (start > end) return 'Start must be before or equal to end.'
+        return null
+      }
+      return typeof value === 'string' && value && !re.test(value) ? 'Invalid date or time.' : null
+    }
+    case 'choice': {
+      const opts = (field as FieldOf<'choice'>).options
+      const allowed = new Set(choiceValues(opts))
+      if (opts.multiple) {
+        const arr = Array.isArray(value) ? value : []
+        if (field.required && arr.length === 0) return 'Select at least one option.'
+        if (arr.some((v) => !allowed.has(v as string))) return 'Invalid selection.'
+        return null
+      }
+      if (typeof value === 'string' && !allowed.has(value)) return 'Invalid selection.'
+      return null
+    }
+    default:
+      return null
+  }
+}

package/layers/fields/app/utils/field-value.ts

@@ -0,0 +1,7 @@
+export function tryParseJson(text: string): { ok: true; value: unknown } | { ok: false } {
+  try {
+    return { ok: true, value: JSON.parse(text) }
+  } catch {
+    return { ok: false }
+  }
+}

package/layers/fields/app/utils/richtext-links.ts

@@ -0,0 +1,48 @@
+// Internal links inside richtext are stored as a marker href `kestrel:<collection>:<id>` (the editor
+// sets it via the normal Link mark; sanitize allows the `kestrel:` scheme). At read time the marker is
+// rewritten to the target's real localized path — the richtext counterpart of the `link` field's
+// server populator. Pure string helpers, shared by the server populate pass and the client preview.
+
+/** URL scheme that flags an internal richtext link (`kestrel:<collection>:<id>`); shared with sanitize. */
+export const RICHTEXT_LINK_SCHEME = 'kestrel'
+
+const MARKER_HREF = new RegExp(`href="${RICHTEXT_LINK_SCHEME}:([a-zA-Z0-9_-]+):(\\d+)"`, 'g')
+const MARKER_VALUE = new RegExp(`^${RICHTEXT_LINK_SCHEME}:([a-zA-Z0-9_-]+):(\\d+)$`)
+
+/** The marker href the editor stores for an internal richtext link. */
+export function richtextLinkHref(collection: string, id: number): string {
+  return `${RICHTEXT_LINK_SCHEME}:${collection}:${id}`
+}
+
+/**
+ * Parse a bare `kestrel:<collection>:<id>` marker href back to its `{collection, id}` (the inverse of
+ * `richtextLinkHref`); returns `null` for an ordinary/external anchor, a malformed marker, or non-string
+ * input. Used by the toolbar to prefill the internal-link picker when re-editing an existing link.
+ */
+export function parseRichtextLinkHref(href: string | null | undefined): { collection: string; id: number } | null {
+  if (typeof href !== 'string') return null
+  const m = href.match(MARKER_VALUE)
+  return m ? { collection: m[1]!, id: Number(m[2]) } : null
+}
+
+/** Every internal-link `{collection, id}` referenced by marker hrefs in the HTML (for batch resolve). */
+export function collectRichtextRefs(html: string | null | undefined): { collection: string; id: number }[] {
+  if (!html) return []
+  return [...html.matchAll(MARKER_HREF)].map((m) => ({ collection: m[1]!, id: Number(m[2]) }))
+}
+
+const escapeAttr = (s: string): string => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;')
+
+/**
+ * Rewrite every `kestrel:<collection>:<id>` marker href to whatever the injected resolver returns; a
+ * target the resolver declines becomes `#`. The production resolver is status-gated, so that covers a
+ * missing target AND a draft one. Ordinary anchors are left untouched. Non-string input → `''`.
+ */
+export function resolveRichtextLinks(
+  html: string | null | undefined,
+  resolveHref: (collection: string, id: number) => string | null,
+): string {
+  if (typeof html !== 'string' || !html) return ''
+  return html.replace(MARKER_HREF, (_m, collection: string, idStr: string) =>
+    `href="${escapeAttr(resolveHref(collection, Number(idStr)) ?? '#')}"`)
+}

package/layers/fields/nuxt.config.ts

@@ -0,0 +1 @@
+export default defineNuxtConfig({})

package/layers/fields/server/api/blocks/index.get.ts

@@ -0,0 +1,9 @@
+// Admin-only (default-deny applies to /api/**): the per-block field schemas the editor needs to
+// render block inputs. `?allowed=a,b` restricts to a collection's allowed block types.
+export default defineEventHandler((event) => {
+  const q = getQuery(event)
+  const allowed = typeof q.allowed === 'string' && q.allowed.length
+    ? q.allowed.split(',').map((s) => s.trim()).filter(Boolean)
+    : undefined
+  return { data: allBlocks(allowed).map(serializeBlock) }
+})