@glw907/cairn-cms 0.68.0 → 0.76.0

package/dist/content/concepts.d.ts

@@ -1,24 +1,30 @@
 import type { ConceptConfig, ConceptDescriptor, ConceptUrlPolicy, RoutingRule } from './types.js';
-import { type SiteConfig } from '../nav/site-config.js';
+/** Expand a concept's routing shorthand to a concrete rule. The single resolution point: omitted is `page`. */
+export declare function resolveRouting(routing: ConceptConfig['routing']): RoutingRule;
 /**
- * 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`.
+ * 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 declare const CONCEPT_ROUTING: Readonly<Record<string, RoutingRule>>;
+export declare function defineConcept<const C extends ConceptConfig>(concept: C): C;
 /**
- * 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`.
+ * Validate one concept's URL policy at build, so a misconfigured permalink or datePrefix fails loudly
+ * 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.
  */
-export declare function normalizeConcepts(content: Record<string, ConceptConfig | undefined>, urlPolicy?: Record<string, ConceptUrlPolicy | undefined>, routing?: Readonly<Record<string, RoutingRule>>): ConceptDescriptor[];
+export declare function validateUrlPolicy(id: string, policy: ConceptUrlPolicy, dated: boolean): void;
 /**
- * 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.
+ * 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 declare function resolveConcepts(content: Record<string, ConceptConfig | undefined>, siteConfig: SiteConfig): ConceptDescriptor[];
+export declare function normalizeConcepts(content: Record<string, ConceptConfig | undefined>): ConceptDescriptor[];
+/**
+ * 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 declare function resolveConcepts(content: Record<string, ConceptConfig | undefined>): ConceptDescriptor[];
 /** Look up a normalized concept by id, or undefined when the site does not enable it. */
 export declare function findConcept(concepts: ConceptDescriptor[], id: string): ConceptDescriptor | undefined;

package/dist/content/concepts.js

@@ -1,15 +1,28 @@
-import { urlPolicyFrom } from '../nav/site-config.js';
+/** Re-attach each fieldset record key to its descriptor as `name`, the normalized `NamedField[]`. */
+function namedFields(schema) {
+    return Object.entries(schema.fields).map(([name, descriptor]) => ({ name, ...descriptor }));
+}
+/** The named routing shorthands, each expanding to a concrete rule. */
+const ROUTING_SHORTHANDS = {
+    feed: { routable: true, dated: true, inFeeds: true },
+    page: { routable: true, dated: false, inFeeds: false },
+    embedded: { routable: false, 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) {
+    if (routing === undefined)
+        return ROUTING_SHORTHANDS.page;
+    return typeof routing === 'string' ? ROUTING_SHORTHANDS[routing] : routing;
+}
 /**
- * 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`.
+ * 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 const CONCEPT_ROUTING = {
-    posts: { routable: true, dated: true, inFeeds: true },
-    pages: { routable: true, dated: false, inFeeds: false },
-};
-/** Routing for a concept with no table entry: a plain, non-feed, routable page. */
-const DEFAULT_ROUTING = { routable: true, dated: false, inFeeds: false };
+export function defineConcept(concept) {
+    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) {
     return id.charAt(0).toUpperCase() + id.slice(1);
@@ -29,7 +42,7 @@ const DATE_PREFIXES = new Set(['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, policy, dated) {
+export function validateUrlPolicy(id, policy, dated) {
     if (policy.permalink !== undefined) {
         const pattern = policy.permalink;
         if (!pattern.startsWith('/')) {
@@ -50,31 +63,40 @@ function validateUrlPolicy(id, policy, dated) {
     }
 }
 /**
- * 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, urlPolicy = {}, routing = CONCEPT_ROUTING) {
+export function normalizeConcepts(content) {
     const descriptors = [];
     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 = { permalink: config.permalink, datePrefix: config.datePrefix };
         validateUrlPolicy(id, policy, conceptRouting.dated);
         const label = config.label ?? defaultLabel(id);
         descriptors.push({
@@ -85,20 +107,21 @@ export function normalizeConcepts(content, urlPolicy = {}, routing = CONCEPT_ROU
             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, siteConfig) {
-    return normalizeConcepts(content, urlPolicyFrom(siteConfig));
+export function resolveConcepts(content) {
+    return normalizeConcepts(content);
 }
 /** Look up a normalized concept by id, or undefined when the site does not enable it. */
 export function findConcept(concepts, id) {

package/dist/content/field-rules.js

@@ -1,7 +1,6 @@
-// cairn-cms: the shared field constraint rules. Both the v1 `defineFields` validator and the v2
-// `fieldset` validator call these pure helpers, so the two validators cannot drift on the
-// constraint wording or the first-failing-rule-wins order. No I/O and no clock reads, so the
-// rules stay deterministic on Workers.
+// 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, label) {
     try {

package/dist/content/fields.d.ts

@@ -50,6 +50,8 @@ export interface MultiselectField extends FieldBase {
     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;
 }
@@ -81,14 +83,43 @@ export interface DatetimeField extends FieldBase {
 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 | ImageField;
+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
@@ -116,6 +147,23 @@ export declare const fields: {
     datetime: <const O extends Omit<DatetimeField, "type">>(o: O) => DatetimeField & O;
     /** A boolean checkbox field. */
     boolean: <const O extends Omit<BooleanField, "type">>(o: O) => BooleanField & 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;
     /** An image field whose value is the nested ImageValue object. */
     image: <const O extends Omit<ImageField, "type">>(o: O) => ImageField & 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;
+    /** A single reference field storing one target entry's permanent id. */
+    reference: <const O extends Omit<ReferenceField, "type">>(o: O) => ReferenceField & 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;
 };

package/dist/content/fields.js

@@ -25,6 +25,17 @@ export const fields = {
     datetime: (o) => ({ type: 'datetime', ...o }),
     /** A boolean checkbox field. */
     boolean: (o) => ({ type: 'boolean', ...o }),
+    /** An icon field whose value is a glyph name from the adapter's icon set. */
+    icon: (o) => ({ type: 'icon', ...o }),
     /** An image field whose value is the nested ImageValue object. */
     image: (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: (o) => ({ type: 'object', ...o }),
+    /** A single reference field storing one target entry's permanent id. */
+    reference: (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: (item, o) => ({ type: 'array', item, ...o }),
 };

package/dist/content/fieldset.d.ts

@@ -1,12 +1,19 @@
 import type { FieldDescriptor, ImageValue } from './fields.js';
 import type { ValidationResult } from './types.js';
-import type { StandardInput, StandardSchemaV1 } from './schema.js';
+import type { StandardInput, StandardSchemaV1 } from './standard-schema.js';
 /**
- * The behavior table co-bundled with a fieldset, keyed by field name. It holds function-valued
- *  behavior a descriptor cannot carry as plain data (a cross-field validator, an array itemLabel).
- *  Scalars have no behavior, so the table is empty for now and reserved for later co-bundled functions.
+ * Function-valued behavior a field descriptor cannot carry as plain data, keyed by field name. A
+ *  `validate` runs cross-field after per-field coercion; an `itemLabel` derives an array row's label.
+ *  Resident in the app bundle, never in the `load` payload.
  */
-export type BehaviorTable = Record<string, never>;
+export interface FieldBehavior {
+    /** A cross-field validator: returns an error string, or null when valid. `siblings` is the raw input record. */
+    validate?(value: unknown, siblings: Record<string, unknown>): string | null;
+    /** Derive an array row's label from its item value and zero-based index. */
+    itemLabel?(item: Record<string, unknown>, index: number): string | undefined;
+}
+/** The behavior table co-bundled with a fieldset, keyed by field name. Empty for a behavior-free fieldset. */
+export type BehaviorTable = Record<string, FieldBehavior>;
 /**
  * Options for `fieldset`. `refine` runs after the per-field coercion and constraints pass, for
  *  cross-field and body-dependent checks. It is validation-only: it returns field-keyed errors to
@@ -14,6 +21,8 @@ export type BehaviorTable = Record<string, never>;
  */
 export interface FieldsetOptions {
     refine?: (data: Record<string, unknown>, body: string) => Record<string, string> | undefined;
+    /** Function-valued per-field behavior, keyed by field name. Each key must name a declared field. */
+    behavior?: BehaviorTable;
 }
 /**
  * A concept's fieldset: the plain-data descriptors, the co-bundled behavior table, the server-derived
@@ -42,6 +51,12 @@ type ValueOf<D extends FieldDescriptor> = D extends {
 } ? boolean : D extends {
     type: 'image';
 } ? ImageValue : D extends {
+    type: 'object';
+    fields: infer F extends Record<string, FieldDescriptor>;
+} ? InferRecord<F> : D extends {
+    type: 'array';
+    item: infer I extends FieldDescriptor;
+} ? ValueOf<I>[] : D extends {
     type: 'select';
     options: readonly (infer O extends string)[];
 } ? O : D extends {
@@ -54,21 +69,27 @@ type ValueOf<D extends FieldDescriptor> = D extends {
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
+/** Drop an index signature so a captured literal record infers its own keys only, not `[x: string]`. */
+type RemoveIndex<T> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
 /**
  * The normalized frontmatter type inferred from a fieldset's descriptor record. A descriptor
- *  declared `required: true` is a required key; every other descriptor is optional.
+ *  declared `required: true` is a required key; every other descriptor is optional. The captured
+ *  literal record carries an index signature (the constructor's `Record<string, FieldDescriptor>`
+ *  intersected with the literal), so strip it first or every nested key would also infer `[x: string]`.
  */
-type Infer<R extends Record<string, FieldDescriptor>> = Prettify<{
+type InferRecord<RR extends Record<string, FieldDescriptor>, R = RemoveIndex<RR>> = Prettify<{
     -readonly [K in keyof R as R[K] extends {
         required: true;
-    } ? K : never]: ValueOf<R[K]>;
+    } ? K : never]: ValueOf<R[K] extends FieldDescriptor ? R[K] : never>;
 } & {
     -readonly [K in keyof R as R[K] extends {
         required: true;
-    } ? never : K]?: ValueOf<R[K]>;
+    } ? never : K]?: ValueOf<R[K] extends FieldDescriptor ? R[K] : never>;
 }>;
 /** Extract the inferred frontmatter type from a `Fieldset`. */
-export type InferFieldset<S> = S extends Fieldset<infer R> ? Infer<R> : never;
+export type InferFieldset<S> = S extends Fieldset<infer R> ? InferRecord<R> : never;
 /**
  * Build a fieldset from a key-to-descriptor record. The returned schema carries the descriptors, a
  *  server-derived validator that coerces per type and returns field-keyed errors or normalized data,