@glw907/cairn-cms 0.62.2 → 0.76.0

package/src/lib/content/concepts.ts

@@ -1,23 +1,41 @@
-// cairn-cms: concept normalization (seam 1). The adapter declares concepts as
-// `content: { posts?, pages? }`; this turns each declared key into a uniform descriptor
-// (id, label, directory, concept-fixed routing, fields, validator) the admin reads. A
-// future Fragments concept attaches by adding one key under `content` and one routing
-// entry, with no reshape here.
-import type { ConceptConfig, ConceptDescriptor, ConceptUrlPolicy, RoutingRule } from './types.js';
-import { urlPolicyFrom, type SiteConfig } from '../nav/site-config.js';
+// cairn-cms: concept normalization (seam 1). The adapter declares concepts as an open `content`
+// record; this turns each declared key into a uniform descriptor (id, label, directory, declared
+// routing, fields, validator) the admin reads. A new concept attaches by adding one key under
+// `content` and declaring its own routing and URL policy, with no reshape here.
+import type { ConceptConfig, ConceptDescriptor, ConceptUrlPolicy, NamedField, RoutingRule } from './types.js';
+import type { Fieldset } from './fieldset.js';
 
-/**
- * Concept-fixed routing, keyed by concept id (spec §7.2). Posts are dated feed entries;
- * pages are plain navigable structure. Not in adapter config. A future Fragments adds one
- * entry here and one key under `content`.
- */
-export const CONCEPT_ROUTING: Readonly<Record<string, RoutingRule>> = {
-  posts: { routable: true, dated: true, inFeeds: true },
-  pages: { routable: true, dated: false, inFeeds: false },
+/** Re-attach each fieldset record key to its descriptor as `name`, the normalized `NamedField[]`. */
+function namedFields(schema: Fieldset): NamedField[] {
+  return Object.entries(schema.fields).map(([name, descriptor]) => ({ name, ...descriptor }));
+}
+
+/** The named routing shorthands, each expanding to a concrete rule. */
+const ROUTING_SHORTHANDS: Readonly<Record<'feed' | 'page' | 'embedded', RoutingRule>> = {
+  feed: { routable: true, dated: true, inFeeds: true },
+  page: { routable: true, dated: false, inFeeds: false },
+  embedded: { routable: false, dated: false, inFeeds: false },
 };
 
-/** Routing for a concept with no table entry: a plain, non-feed, routable page. */
-const DEFAULT_ROUTING: RoutingRule = { routable: true, dated: false, inFeeds: false };
+/** Expand a concept's routing shorthand to a concrete rule. The single resolution point: omitted is `page`. */
+export function resolveRouting(routing: ConceptConfig['routing']): RoutingRule {
+  if (routing === undefined) return ROUTING_SHORTHANDS.page;
+  return typeof routing === 'string' ? ROUTING_SHORTHANDS[routing] : routing;
+}
+
+/**
+ * Declare a concept while preserving its fieldset type for typed reads, and validate its URL policy at
+ * declaration so a bad permalink or datePrefix fails at module load rather than at a defaulted render.
+ * Mirrors {@link defineAdapter}; the validation is the build-independent net for a concept with no entries.
+ */
+export function defineConcept<const C extends ConceptConfig>(concept: C): C {
+  validateUrlPolicy(
+    concept.label ?? concept.dir,
+    { permalink: concept.permalink, datePrefix: concept.datePrefix },
+    resolveRouting(concept.routing).dated,
+  );
+  return concept;
+}
 
 /** Title-case a concept id for the default sidebar label, e.g. "posts" to "Posts". */
 function defaultLabel(id: string): string {
@@ -41,7 +59,7 @@ const DATE_PREFIXES = new Set<string>(['year', 'month', 'day']);
  * here rather than emitting a wrong or defaulted URL at render. The permalink must be root-relative and
  * use only known tokens, a date token requires a dated concept, and the datePrefix must be in range.
  */
-function validateUrlPolicy(id: string, policy: ConceptUrlPolicy, dated: boolean): void {
+export function validateUrlPolicy(id: string, policy: ConceptUrlPolicy, dated: boolean): void {
   if (policy.permalink !== undefined) {
     const pattern = policy.permalink;
     if (!pattern.startsWith('/')) {
@@ -67,38 +85,48 @@ function validateUrlPolicy(id: string, policy: ConceptUrlPolicy, dated: boolean)
 }
 
 /**
- * Normalize an adapter's declared concepts into uniform descriptors (seam 1). URL policy
- * (`permalink`, `datePrefix`) comes from the YAML site-config, passed here as `urlPolicy` keyed by
- * concept id; each value defaults when the YAML omits it (`/:slug` for Pages, `/<id>/:slug`
- * otherwise; `datePrefix` defaults to `day`). `routing` is injectable so a contract test can prove
- * a new concept attaches additively; production passes the default `CONCEPT_ROUTING`.
+ * Normalize an adapter's declared concepts into uniform descriptors (seam 1). Each concept declares its
+ * own routing (a shorthand or an explicit rule, resolved by `resolveRouting`) and URL policy
+ * (`permalink`, `datePrefix`) on the config; both default when omitted (`/:slug` for Pages, `/<id>/:slug`
+ * otherwise; `datePrefix` defaults to `day`). A new concept attaches by adding one key under `content`.
  */
 export function normalizeConcepts(
   content: Record<string, ConceptConfig | undefined>,
-  urlPolicy: Record<string, ConceptUrlPolicy | undefined> = {},
-  routing: Readonly<Record<string, RoutingRule>> = CONCEPT_ROUTING,
 ): ConceptDescriptor[] {
   const descriptors: ConceptDescriptor[] = [];
   const declaredConcepts = new Set(
     Object.keys(content).filter((key) => content[key] !== undefined),
   );
-  for (const key of Object.keys(urlPolicy)) {
-    if (!declaredConcepts.has(key)) {
-      throw new Error(`cairn: URL policy names concept "${key}", which is not declared under content`);
-    }
-  }
   for (const [id, config] of Object.entries(content)) {
     if (!config) continue;
+    const fs = config.fields;
     const summaryFields = config.summaryFields ?? [];
-    const declared = new Set(config.schema.fields.map((field) => field.name));
+    const declared = new Set(Object.keys(fs.fields));
     const undeclared = summaryFields.find((key) => !declared.has(key));
     if (undeclared !== undefined) {
       throw new Error(
         `cairn: concept "${id}" summaryFields key "${undeclared}" is not a declared field`,
       );
     }
-    const conceptRouting = routing[id] ?? DEFAULT_ROUTING;
-    const policy = urlPolicy[id] ?? {};
+    // A reference (or array of reference) field names the concept it targets. Validate that concept at
+    // declaration, so a typo fails loudly here rather than at the build's verifyReferences gate (or, in
+    // the editor picker, as a silently empty target list). The check is the field descriptor's concept
+    // against the declared content keys.
+    for (const [name, descriptor] of Object.entries(fs.fields)) {
+      const targetConcept =
+        descriptor.type === 'reference'
+          ? descriptor.concept
+          : descriptor.type === 'array' && descriptor.item.type === 'reference'
+            ? descriptor.item.concept
+            : undefined;
+      if (targetConcept !== undefined && !declaredConcepts.has(targetConcept)) {
+        throw new Error(
+          `cairn: concept "${id}" reference field "${name}" names concept "${targetConcept}", which is not declared under content`,
+        );
+      }
+    }
+    const conceptRouting = resolveRouting(config.routing);
+    const policy: ConceptUrlPolicy = { permalink: config.permalink, datePrefix: config.datePrefix };
     validateUrlPolicy(id, policy, conceptRouting.dated);
     const label = config.label ?? defaultLabel(id);
     descriptors.push({
@@ -109,24 +137,24 @@ export function normalizeConcepts(
       routing: conceptRouting,
       permalink: policy.permalink ?? defaultPermalink(id),
       datePrefix: policy.datePrefix ?? 'day',
-      fields: config.schema.fields,
+      fields: namedFields(fs),
+      schema: fs,
       summaryFields,
-      validate: config.schema.validate,
+      validate: fs.validate,
     });
   }
   return descriptors;
 }
 
 /**
- * Resolve a site's concept descriptors from its content map and parsed site config. The admin runtime
- * (composeRuntime) and the delivery layer (siteDescriptors) both call this, so the per-concept URL
- * policy is derived once from the YAML and the runtime and delivery permalinks cannot diverge.
+ * Resolve a site's concept descriptors from its content map. The admin runtime (composeRuntime) and the
+ * delivery layer (siteDescriptors) both call this, so the per-concept routing and URL policy are derived
+ * once from the concept declarations and the runtime and delivery permalinks cannot diverge.
  */
 export function resolveConcepts(
   content: Record<string, ConceptConfig | undefined>,
-  siteConfig: SiteConfig,
 ): ConceptDescriptor[] {
-  return normalizeConcepts(content, urlPolicyFrom(siteConfig));
+  return normalizeConcepts(content);
 }
 
 /** Look up a normalized concept by id, or undefined when the site does not enable it. */

package/src/lib/content/field-rules.ts

@@ -0,0 +1,39 @@
+// cairn-cms: the shared field constraint rules the `fieldset` validator calls. They live apart from
+// the validator as pure helpers, so the constraint wording and the first-failing-rule-wins order are
+// stated once. No I/O and no clock reads, so the rules stay deterministic on Workers.
+
+/** Compile a field pattern once, throwing a labeled error when the source is not a valid regex. */
+export function compilePattern(source: string, label: string): RegExp {
+  try {
+    return new RegExp(source);
+  } catch (cause) {
+    throw new Error(`cairn: field "${label}" has an invalid pattern: ${source}`, { cause });
+  }
+}
+
+/** Return the first string-length violation message, or null when the value satisfies the bounds. */
+export function stringLengthError(
+  value: string,
+  constraints: { min?: number; max?: number; length?: number },
+  label: string,
+): string | null {
+  const { min, max, length } = constraints;
+  if (min != null && value.length < min) return `${label} must be at least ${min} characters`;
+  if (max != null && value.length > max) return `${label} must be at most ${max} characters`;
+  if (length != null && value.length !== length) return `${label} must be exactly ${length} characters`;
+  return null;
+}
+
+/** Return the format violation message when a compiled pattern rejects the value, else null. */
+export function patternError(value: string, compiled: RegExp | undefined, label: string): string | null {
+  if (compiled && !compiled.test(value)) return `${label} is not in the expected format`;
+  return null;
+}
+
+/** Return the first date-bounds violation message, or null when the value is within the bounds. */
+export function dateBoundsError(value: string, constraints: { min?: string; max?: string }, label: string): string | null {
+  const { min, max } = constraints;
+  if (min != null && value < min) return `${label} must be on or after ${min}`;
+  if (max != null && value > max) return `${label} must be on or before ${max}`;
+  return null;
+}

package/src/lib/content/fields.ts

@@ -0,0 +1,178 @@
+/** The stored value of an image field; re-exported so this module owns the image shape too. */
+export type { ImageValue } from './types.js';
+
+/** Common to every field descriptor: the form label and the universal options. */
+export interface FieldBase {
+  /** Form label. */
+  label: string;
+  /** One author-facing sentence shown under the field. */
+  help?: string;
+  /** A required field fails validation when empty. */
+  required?: boolean;
+  /** Form-render-time initial value; a sentinel like "today" resolves at render (Task 9). */
+  default?: string | boolean;
+}
+/** A single-line text input. */
+export interface TextField extends FieldBase {
+  type: 'text';
+  min?: number; max?: number; length?: number;
+  /** A regular-expression source string the value must match. */
+  pattern?: string;
+}
+/** A multi-line text input. */
+export interface TextareaField extends FieldBase {
+  type: 'textarea';
+  rows?: number; min?: number; max?: number; length?: number; pattern?: string;
+}
+/** A numeric input. */
+export interface NumberField extends FieldBase {
+  type: 'number';
+  min?: number; max?: number;
+  /** Constrain the value to whole numbers. */
+  integer?: boolean;
+}
+/** A single-choice input over a closed option list. */
+export interface SelectField extends FieldBase {
+  type: 'select';
+  /** The closed set of allowed values. */
+  options: readonly string[];
+}
+/** A multiple-choice input. */
+export interface MultiselectField extends FieldBase {
+  type: 'multiselect';
+  /** The allowed values; omitted leaves the set open. */
+  options?: readonly string[];
+  /** Allow the author to add values not in the list. */
+  creatable?: boolean;
+  /** Placeholder text for the open/creatable comma-separated input (freetags parity). */
+  placeholder?: string;
+  /** Mark the field as a site-wide taxonomy whose values pool across entries. */
+  taxonomy?: boolean;
+}
+/** A URL input whose format the validator enforces. */
+export interface UrlField extends FieldBase {
+  type: 'url';
+}
+/** An email-address input whose format the validator enforces. */
+export interface EmailField extends FieldBase {
+  type: 'email';
+}
+/** A calendar-date input. */
+export interface DateField extends FieldBase {
+  type: 'date';
+  /** Earliest allowed date as YYYY-MM-DD. */
+  min?: string;
+  /** Latest allowed date as YYYY-MM-DD. */
+  max?: string;
+}
+/** A date-and-time input. */
+export interface DatetimeField extends FieldBase {
+  type: 'datetime';
+  /** Earliest allowed moment as an ISO string. */
+  min?: string;
+  /** Latest allowed moment as an ISO string. */
+  max?: string;
+}
+/** A checkbox; absent means false. */
+export interface BooleanField extends FieldBase {
+  type: 'boolean';
+}
+/** A glyph chosen from the adapter's icon set; the stored value is the glyph's name. */
+export interface IconField extends FieldBase {
+  type: 'icon';
+}
+/** A hero image whose stored value is the nested ImageValue object. */
+export interface ImageField extends FieldBase {
+  type: 'image';
+  /** Whether this field feeds the social-card image. */
+  seo?: boolean;
+}
+/** A group of leaf fields, stored as a nested object. Holds only leaves (no nested container). */
+export interface ObjectField extends Omit<FieldBase, 'label'> {
+  type: 'object';
+  /**
+   * Optional group label. An object inside an array is labeled by the array (and summarized per row by
+   *  itemLabel), so it may omit this; a top-level object supplies it for the group legend.
+   */
+  label?: string;
+  /** The leaf fields this group holds, keyed by frontmatter sub-key. */
+  fields: Record<string, FieldDescriptor>;
+}
+/** A single edge to one entry of a named concept, stored as that target's permanent id. */
+export interface ReferenceField extends FieldBase {
+  type: 'reference';
+  /** The concept whose entries this field references. */
+  concept: string;
+}
+/** A repeatable field whose stored value is a list of its item's values. */
+export interface ArrayField extends FieldBase {
+  type: 'array';
+  /** The descriptor each list element conforms to: a leaf, or a flat object of leaves. */
+  item: FieldDescriptor;
+  /** A label for one row, shown beside the add and remove controls. */
+  itemLabel?: string;
+}
+/** The plain-data descriptor union the form, validator, and inference all read. Grows per task. */
+export type FieldDescriptor =
+  | TextField
+  | TextareaField
+  | NumberField
+  | SelectField
+  | MultiselectField
+  | UrlField
+  | EmailField
+  | DateField
+  | DatetimeField
+  | BooleanField
+  | IconField
+  | ImageField
+  | ObjectField
+  | ReferenceField
+  | ArrayField;
+
+/**
+ * The constructor namespace a concept declares its fields with. Each constructor captures its
+ * argument with a `const` type parameter and intersects it onto the descriptor, so the call-site
+ * literals (`required: true`, a `select`/`multiselect` `options` union) survive into the descriptor
+ * type for `Infer` to read. The runtime value is unchanged: still `{ type, ...o }`.
+ */
+export const fields = {
+  /** A single-line text field. */
+  text: <const O extends Omit<TextField, 'type'>>(o: O): TextField & O => ({ type: 'text', ...o }),
+  /** A multi-line text field. */
+  textarea: <const O extends Omit<TextareaField, 'type'>>(o: O): TextareaField & O => ({ type: 'textarea', ...o }),
+  /** A numeric field. */
+  number: <const O extends Omit<NumberField, 'type'>>(o: O): NumberField & O => ({ type: 'number', ...o }),
+  /** A single-choice field over a closed option list, preserving the literal option union. */
+  select: <const O extends Omit<SelectField, 'type'>>(o: O): SelectField & O => ({ type: 'select', ...o }),
+  /** A multiple-choice field, preserving the literal option union when one is given. */
+  multiselect: <const O extends Omit<MultiselectField, 'type'>>(o: O): MultiselectField & O => ({ type: 'multiselect', ...o }),
+  /** A URL field. */
+  url: <const O extends Omit<UrlField, 'type'>>(o: O): UrlField & O => ({ type: 'url', ...o }),
+  /** An email-address field. */
+  email: <const O extends Omit<EmailField, 'type'>>(o: O): EmailField & O => ({ type: 'email', ...o }),
+  /** A calendar-date field. */
+  date: <const O extends Omit<DateField, 'type'>>(o: O): DateField & O => ({ type: 'date', ...o }),
+  /** A date-and-time field. */
+  datetime: <const O extends Omit<DatetimeField, 'type'>>(o: O): DatetimeField & O => ({ type: 'datetime', ...o }),
+  /** A boolean checkbox field. */
+  boolean: <const O extends Omit<BooleanField, 'type'>>(o: O): BooleanField & O => ({ type: 'boolean', ...o }),
+  /** An icon field whose value is a glyph name from the adapter's icon set. */
+  icon: <const O extends Omit<IconField, 'type'>>(o: O): IconField & O => ({ type: 'icon', ...o }),
+  /** An image field whose value is the nested ImageValue object. */
+  image: <const O extends Omit<ImageField, 'type'>>(o: O): ImageField & O => ({ type: 'image', ...o }),
+  /** A group of leaf fields, preserving each leaf's type for inference. Label is optional (the array labels a row group). */
+  object: <const F extends Record<string, FieldDescriptor>, const O extends Omit<ObjectField, 'type' | 'fields'>>(
+    o: { fields: F } & O,
+  ): ObjectField & { fields: F } & O => ({ type: 'object', ...o }),
+  /** A single reference field storing one target entry's permanent id. */
+  reference: <const O extends Omit<ReferenceField, 'type'>>(o: O): ReferenceField & O => ({ type: 'reference', ...o }),
+  /**
+   * A repeatable field over one item descriptor, preserving the item type for inference. The item is
+   *  a leaf, or a flat object of leaves; `fieldset` rejects deeper nesting at declaration.
+   */
+  array: <const I extends FieldDescriptor, const O extends Omit<ArrayField, 'type' | 'item'>>(
+    item: I,
+    o?: O,
+  ): ArrayField & { item: I } & O => ({ type: 'array', item, ...(o as O) }),
+};