@crombolo/schema 0.11.0 → 0.13.1

package/src/parse-forms.ts

@@ -6,13 +6,16 @@
  * type and the two share nothing but the reader.
  */
 import {
+  BUILT_IN_FORM_TYPES,
+  type ChoiceSource,
+  type ChoiceSourceKind,
   FORM_CONDITION_OPERATORS,
-  FORM_FIELD_TYPE_NAMES,
-  FORM_WORKFLOW_TYPES,
   type FormCondition,
   type FormConditionOperator,
   type FormConditionRule,
   type FormFieldType,
+  type FormSettingValue,
+  type FormTypes,
   type FormWorkflowTrigger,
   type FormWorkflowType,
   formFieldType,
@@ -31,6 +34,7 @@ const FORM_KEYS = [
   'notes',
   'store-entries',
   'requires-approval',
+  'step-pages',
   'submit-label',
   'next-label',
   'previous-label',
@@ -59,6 +63,7 @@ const FIELD_KEYS = [
   'css-class',
   'autocomplete',
   'values',
+  'source',
   'placeholder',
   'default-value',
   'content',
@@ -70,10 +75,12 @@ const FIELD_KEYS = [
   'accept',
   'max-size-kb',
   'multiple',
+  'settings',
   'condition',
 ] as const
 const CONDITION_KEYS = ['action', 'match', 'rule'] as const
 const RULE_KEYS = ['field', 'operator', 'value'] as const
+const SOURCE_KEYS = ['kind', 'parent'] as const
 const WORKFLOW_KEYS = ['key', 'type', 'name', 'on', 'settings'] as const
 
 function condition(r: Reader, value: unknown, path: string): FormCondition | undefined {
@@ -112,14 +119,30 @@ function condition(r: Reader, value: unknown, path: string): FormCondition | und
   }
 }
 
-function field(r: Reader, t: Toml, path: string): SchemaFormField {
+/** Kept as written: the validator names an unknown kind, as it does an unknown type. */
+function source(r: Reader, value: unknown, path: string): ChoiceSource | undefined {
+  if (value === undefined) return undefined
+  const t = r.table(value, path)
+  if (!t) return undefined
+  r.unknown(t, SOURCE_KEYS, path)
+  return {
+    kind: (r.str(t, 'kind', path, true) ?? '') as ChoiceSourceKind,
+    parent: r.str(t, 'parent', path, true) ?? '',
+  }
+}
+
+/** Says a type is unknown by its name, and what is known: the built-ins, then each bundle's. */
+function unknownType(kind: 'field' | 'workflow', type: string, known: Iterable<string>): string {
+  return `the ${kind} type "${type}" is not built in, and no wired bundle provides it; expected one of ${[...known].join(', ')}`
+}
+
+function field(r: Reader, t: Toml, path: string, types: FormTypes): SchemaFormField {
   r.unknown(t, FIELD_KEYS, path)
   const type = r.str(t, 'type', path, true) ?? ''
-  if (type && !formFieldType(type))
-    r.problem(
-      `${path}.type`,
-      `unknown field type; expected one of ${FORM_FIELD_TYPE_NAMES.join(', ')}`,
-    )
+  if (type && !formFieldType(type, types))
+    r.problem(`${path}.type`, unknownType('field', type, types.fields.keys()))
+  const settings =
+    t.settings === undefined ? undefined : (r.table(t.settings, `${path}.settings`) ?? {})
   // Consent is mandatory unless the form says otherwise: a consent box that can
   // be skipped records agreement nobody gave.
   const mandatoryByDefault = type === 'dataConsent'
@@ -137,6 +160,7 @@ function field(r: Reader, t: Toml, path: string): SchemaFormField {
     cssClass: r.str(t, 'css-class', path),
     autocomplete: r.str(t, 'autocomplete', path),
     values: r.strs(t, 'values', path),
+    ...(t.source !== undefined ? { source: source(r, t.source, `${path}.source`) } : {}),
     placeholder: r.str(t, 'placeholder', path),
     defaultValue: r.str(t, 'default-value', path),
     content: r.str(t, 'content', path),
@@ -148,37 +172,39 @@ function field(r: Reader, t: Toml, path: string): SchemaFormField {
     accept: r.strs(t, 'accept', path),
     maxSizeKb: r.num(t, 'max-size-kb', path),
     ...(t.multiple !== undefined ? { multiple: r.bool(t, 'multiple', path, false) } : {}),
+    ...(settings ? { settings: settings as Record<string, FormSettingValue> } : {}),
     condition: condition(r, t.condition, `${path}.condition`),
   }
 }
 
-function group(r: Reader, t: Toml, path: string): SchemaFormGroup {
+function group(r: Reader, t: Toml, path: string, types: FormTypes): SchemaFormGroup {
   r.unknown(t, GROUP_KEYS, path)
   return {
     caption: r.str(t, 'caption', path),
     columns: r.num(t, 'columns', path) ?? 1,
-    fields: r.tables(t.field, `${path}.field`).map((f, i) => field(r, f, `${path}.field[${i}]`)),
+    fields: r
+      .tables(t.field, `${path}.field`)
+      .map((f, i) => field(r, f, `${path}.field[${i}]`, types)),
     condition: condition(r, t.condition, `${path}.condition`),
   }
 }
 
-function page(r: Reader, t: Toml, path: string): SchemaFormPage {
+function page(r: Reader, t: Toml, path: string, types: FormTypes): SchemaFormPage {
   r.unknown(t, PAGE_KEYS, path)
   return {
     caption: r.str(t, 'caption', path),
-    groups: r.tables(t.group, `${path}.group`).map((g, i) => group(r, g, `${path}.group[${i}]`)),
+    groups: r
+      .tables(t.group, `${path}.group`)
+      .map((g, i) => group(r, g, `${path}.group[${i}]`, types)),
     condition: condition(r, t.condition, `${path}.condition`),
   }
 }
 
-function workflow(r: Reader, t: Toml, path: string): SchemaFormWorkflow {
+function workflow(r: Reader, t: Toml, path: string, types: FormTypes): SchemaFormWorkflow {
   r.unknown(t, WORKFLOW_KEYS, path)
   const type = r.str(t, 'type', path, true) ?? ''
-  if (type && !FORM_WORKFLOW_TYPES.includes(type as FormWorkflowType))
-    r.problem(
-      `${path}.type`,
-      `unknown workflow type; expected one of ${FORM_WORKFLOW_TYPES.join(', ')}`,
-    )
+  if (type && !types.workflows.has(type))
+    r.problem(`${path}.type`, unknownType('workflow', type, types.workflows.keys()))
   const on = r.str(t, 'on', path) ?? 'submit'
   if (on !== 'submit' && on !== 'approve') r.problem(`${path}.on`, "expected 'submit' or 'approve'")
   const settings = t.settings === undefined ? {} : r.table(t.settings, `${path}.settings`)
@@ -191,7 +217,11 @@ function workflow(r: Reader, t: Toml, path: string): SchemaFormWorkflow {
   }
 }
 
-export function parseForm(file: string, source: string): ParseResult<SchemaForm> {
+export function parseForm(
+  file: string,
+  source: string,
+  types: FormTypes = BUILT_IN_FORM_TYPES,
+): ParseResult<SchemaForm> {
   const r = new Reader(file)
   const root = toml(source, r)
   if (!root) return { value: undefined, problems: r.problems }
@@ -212,6 +242,7 @@ export function parseForm(file: string, source: string): ParseResult<SchemaForm>
     // what people typed would be the worst possible default.
     storeEntries: r.bool(t, 'store-entries', path, true),
     requiresApproval: r.bool(t, 'requires-approval', path, false),
+    ...(t['step-pages'] !== undefined ? { stepPages: r.bool(t, 'step-pages', path, false) } : {}),
     submitLabel: r.str(t, 'submit-label', path),
     nextLabel: r.str(t, 'next-label', path),
     previousLabel: r.str(t, 'previous-label', path),
@@ -222,8 +253,10 @@ export function parseForm(file: string, source: string): ParseResult<SchemaForm>
     minimumSubmitSeconds: r.num(t, 'minimum-submit-seconds', path),
     maxEntries: r.num(t, 'max-entries', path),
     since: r.str(t, 'since', path),
-    pages: r.tables(root.page, 'page').map((p, i) => page(r, p, `page[${i}]`)),
-    workflows: r.tables(root.workflow, 'workflow').map((w, i) => workflow(r, w, `workflow[${i}]`)),
+    pages: r.tables(root.page, 'page').map((p, i) => page(r, p, `page[${i}]`, types)),
+    workflows: r
+      .tables(root.workflow, 'workflow')
+      .map((w, i) => workflow(r, w, `workflow[${i}]`, types)),
   }
   return { value: r.problems.length === 0 ? value : undefined, problems: r.problems }
 }

package/src/parse.ts

@@ -11,6 +11,7 @@ import {
   type SchemaProperty,
   type SchemaTab,
   type SchemaTypeKind,
+  type SchemaUrls,
   TYPE_KIND_FILES,
 } from './model.ts'
 import { type ParseResult, Reader, type Toml, toml } from './reader.ts'
@@ -251,12 +252,35 @@ export function parseLanguages(file: string, source: string): ParseResult<Schema
 }
 
 export function parseSchemaVersion(file: string, source: string): ParseResult<string> {
+  const parsed = parseSchemaSettings(file, source)
+  return { value: parsed.value?.version, problems: parsed.problems }
+}
+
+/** `schema/schema.toml`: the schema version, and how the site's URLs are built. */
+export function parseSchemaSettings(
+  file: string,
+  source: string,
+): ParseResult<{ version: string; urls?: SchemaUrls }> {
   const r = new Reader(file)
   const root = toml(source, r)
   if (!root) return { value: undefined, problems: r.problems }
-  r.unknown(root, ['schema'], '')
+  r.unknown(root, ['schema', 'urls'], '')
   const t = r.table(root.schema, 'schema')
   const version = t ? r.str(t, 'version', 'schema', true) : undefined
   if (t) r.unknown(t, ['version'], 'schema')
-  return { value: r.problems.length === 0 ? version : undefined, problems: r.problems }
+  let urls: SchemaUrls | undefined
+  if (root.urls !== undefined) {
+    const u = r.table(root.urls, 'urls')
+    if (u) {
+      r.unknown(u, ['hide-top-level'], 'urls')
+      urls = { hideTopLevel: r.bool(u, 'hide-top-level', 'urls', true) }
+    }
+  }
+  return {
+    value:
+      r.problems.length === 0 && version !== undefined
+        ? { version, ...(urls ? { urls } : {}) }
+        : undefined,
+    problems: r.problems,
+  }
 }

package/src/sync.ts

@@ -3,6 +3,7 @@
  * retirement, and a type with content refuses to disappear. The algorithm and
  * the multi-node rules are in docs/schema-as-code.md, "Synchronisation".
  */
+import type { FormTypes } from '@crombolo/core'
 import { type ContentTypeAggregate, ObjectTypes, type PropertyTypeModel } from '@crombolo/core'
 import {
   appendCacheInstruction,
@@ -15,6 +16,7 @@ import {
   DataTypeRepository,
   type Db,
   DbDate,
+  DEFAULT_URL_OPTIONS,
   FolderRepository,
   LanguageRepository,
   Locks,
@@ -25,7 +27,12 @@ import {
   SYSTEM_CONTENT_TYPES,
   SYSTEM_MEDIA_TYPES,
   SYSTEM_MEMBER_TYPE,
+  sameUrlOptions,
+  syncWorkflows,
+  type UrlOptions,
   updateSchemaStateHash,
+  type WorkflowSyncReport,
+  writeUrlOptions,
 } from '@crombolo/data'
 import { BUILTIN_DATA_TYPES, storageTypeFor, systemPropertyKeys } from './builtin.ts'
 import { hashSchemaSet, type LoadedSchema } from './load.ts'
@@ -38,6 +45,7 @@ import {
   typeFileKey,
 } from './model.ts'
 import { validateSchemaSet } from './validate.ts'
+import { workflowVersion } from './workflows.ts'
 
 export interface SyncNode extends NodeSchemaState {
   nodeId: string
@@ -56,6 +64,8 @@ export interface SyncOptions {
    * is pending everywhere until `upgrade` makes the state current. Default current.
    */
   status?: 'prepared' | 'current'
+  /** The form field and workflow types the site's wired bundles add. */
+  formTypes?: FormTypes
 }
 
 export type SyncAction = 'applied' | 'would-apply' | 'skipped-older' | 'skipped-same' | 'refused'
@@ -88,6 +98,10 @@ export interface SyncReport {
   revived: string[]
   assignedKeys: AssignedKey[]
   deferred: string[]
+  /** Set when the sync changed how URLs are built, so the old ones can be redirected. */
+  urls?: { before: UrlOptions; after: UrlOptions }
+  /** Set when a workflow changed, with what that did to requests in flight. */
+  workflows?: WorkflowSyncReport
 }
 
 export const emptySyncReport = (
@@ -132,7 +146,10 @@ export async function syncSchema(
 ): Promise<SyncReport> {
   const problems = [
     ...loaded.problems,
-    ...validateSchemaSet(loaded.set, { componentAliases: options.componentAliases }),
+    ...validateSchemaSet(loaded.set, {
+      componentAliases: options.componentAliases,
+      types: options.formTypes,
+    }),
   ]
   if (problems.length > 0)
     return emptySyncReport('refused', { reason: 'the schema has problems', problems })
@@ -268,6 +285,24 @@ export async function syncSchema(
           report.updated.languages += result.updated
         }
 
+        // ---- how URLs are built: the files are the source, absent is the default.
+        // Only a current sync moves it; a prepared one serves no URLs yet.
+        if (status === 'current') {
+          const urls = { hideTopLevel: set.urls?.hideTopLevel ?? DEFAULT_URL_OPTIONS.hideTopLevel }
+          const before = await writeUrlOptions(tx, urls)
+          if (!sameUrlOptions(before, urls)) report.urls = { before, after: urls }
+          // Approval workflows likewise: only a current sync changes the rules
+          // that pages are published under.
+          const workflows = await syncWorkflows(
+            tx,
+            (set.workflows ?? []).map((workflow) => ({
+              workflow,
+              version: workflowVersion(workflow),
+            })),
+          )
+          if (workflows.changed.length > 0) report.workflows = workflows
+        }
+
         // ---- templates referenced by types must have a row
         const componentKeyByAlias = new Map<string, string>()
         for (const alias of new Set(set.contentTypes.flatMap((t) => t.components))) {

package/src/validate-forms.ts

@@ -8,14 +8,20 @@
  */
 import {
   allFormFields,
+  BUILT_IN_FORM_TYPES,
+  CHOICE_SOURCE_KINDS,
   type FormCondition,
+  type FormTypes,
   formFieldType,
   type SchemaForm,
   type SchemaFormField,
+  settingsProblems,
   VALUELESS_OPERATORS,
 } from '@crombolo/core'
 import type { SchemaProblem } from './model.ts'
 
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
 const VERSION = /^\d+(\.\d+)*$/
 const ALIAS = /^[a-zA-Z][a-zA-Z0-9]*$/
 
@@ -45,6 +51,8 @@ export interface ValidateFormsOptions {
   formThemes?: ReadonlySet<string>
   /** Content type aliases, so `saveAsContent` can be held to a real one. */
   contentTypeAliases?: ReadonlySet<string>
+  /** The field and workflow types in play: the built-ins, and the wired bundles'. */
+  types?: FormTypes
 }
 
 export function validateForms(
@@ -98,7 +106,7 @@ export function validateForms(
         'requires store-entries, since there is no entry to approve',
       )
 
-    validateFields(form, file, add)
+    validateFields(form, file, options.types ?? BUILT_IN_FORM_TYPES, add)
     validateWorkflows(form, file, options, add)
   }
   return problems
@@ -106,7 +114,7 @@ export function validateForms(
 
 type Add = (file: string, path: string, message: string) => void
 
-function validateFields(form: SchemaForm, file: string, add: Add): void {
+function validateFields(form: SchemaForm, file: string, types: FormTypes, add: Add): void {
   const fields = allFormFields(form)
   const seen = new Set<string>()
   /** Aliases usable by a condition: a field may only look at earlier ones. */
@@ -121,7 +129,7 @@ function validateFields(form: SchemaForm, file: string, add: Add): void {
         add(file, 'page.group.columns', `${group.columns} is not a column count between 1 and 4`)
       for (const field of group.fields) {
         const path = `page.group.field[${index}]`
-        const info = formFieldType(field.type)
+        const info = formFieldType(field.type, types)
 
         if (!ALIAS.test(field.alias))
           add(
@@ -148,13 +156,40 @@ function validateFields(form: SchemaForm, file: string, add: Add): void {
                 `a ${field.type} field collects nothing, so it cannot be sensitive`,
               )
           }
-          if (info.choices && field.values.length === 0)
+          const { source } = field
+          if (source && field.values.length > 0)
+            add(
+              file,
+              `${path}.source`,
+              'a field takes its choices from values or from a source, not both',
+            )
+          if (source && !info.choices)
+            add(file, `${path}.source`, `a ${field.type} field has nothing to choose from`)
+          if (source && info.choices) {
+            if (!CHOICE_SOURCE_KINDS.includes(source.kind))
+              add(
+                file,
+                `${path}.source.kind`,
+                `"${source.kind}" is not a kind of source; expected one of ${CHOICE_SOURCE_KINDS.join(', ')}`,
+              )
+            if (source.kind === 'content' && !UUID.test(source.parent))
+              add(file, `${path}.source.parent`, 'a content source names its parent page by key')
+            if (source.kind === 'dictionary' && source.parent.trim() === '')
+              add(
+                file,
+                `${path}.source.parent`,
+                'a dictionary source names its parent dictionary item',
+              )
+          }
+          if (info.choices && !source && field.values.length === 0)
             add(file, `${path}.values`, `a ${field.type} field needs values to choose from`)
           if (!info.choices && field.values.length > 0)
             add(file, `${path}.values`, `a ${field.type} field has nothing to choose from`)
-          // A default has to be one of the choices, or the form opens invalid.
+          // A default has to be one of the choices, or the form opens invalid. A
+          // source's choices are only known once it is resolved, so not checked here.
           if (
             info.choices &&
+            !source &&
             field.defaultValue !== undefined &&
             !field.values.includes(field.defaultValue)
           )
@@ -165,6 +200,21 @@ function validateFields(form: SchemaForm, file: string, add: Add): void {
             if (!info.settings.includes(setting as never))
               add(file, `${path}.${setting}`, `does not apply to a ${field.type} field`)
           }
+          // A built-in type's settings are keys of the field; only a bundle's
+          // type has a settings table, held to what it declares.
+          if (!info.bundle && field.settings !== undefined)
+            add(
+              file,
+              `${path}.settings`,
+              `a ${field.type} field is built in and takes no settings table; its settings are keys of the field`,
+            )
+          if (info.bundle)
+            for (const message of settingsProblems(
+              info.declared,
+              field.settings ?? {},
+              `a ${field.type} field`,
+            ))
+              add(file, `${path}.settings`, message)
         }
 
         if (field.pattern !== undefined) {
@@ -184,19 +234,27 @@ function validateFields(form: SchemaForm, file: string, add: Add): void {
           add(file, `${path}.max-size-kb`, 'must be at least 1')
 
         if (field.condition)
-          validateCondition(field.condition, fields, earlier, file, `${path}.condition`, add)
+          validateCondition(field.condition, fields, earlier, file, `${path}.condition`, types, add)
         earlier.add(field.alias.toLowerCase())
         index++
       }
       if (group.condition)
-        validateCondition(group.condition, fields, earlier, file, 'page.group.condition', add)
+        validateCondition(
+          group.condition,
+          fields,
+          earlier,
+          file,
+          'page.group.condition',
+          types,
+          add,
+        )
     }
     if (page.condition)
-      validateCondition(page.condition, fields, earlier, file, 'page.condition', add)
+      validateCondition(page.condition, fields, earlier, file, 'page.condition', types, add)
   }
 
   if (fields.length === 0) add(file, 'page.group.field', 'a form needs at least one field')
-  else if (fields.every((field) => formFieldType(field.type)?.presentational))
+  else if (fields.every((field) => formFieldType(field.type, types)?.presentational))
     add(file, 'page.group.field', 'every field is presentational, so the form collects nothing')
 }
 
@@ -206,6 +264,7 @@ function validateCondition(
   earlier: ReadonlySet<string>,
   file: string,
   path: string,
+  types: FormTypes,
   add: Add,
 ): void {
   for (const [index, rule] of condition.rules.entries()) {
@@ -223,7 +282,7 @@ function validateCondition(
         `${rulePath}.field`,
         `"${rule.field}" comes later in the form, so it has no value to compare yet`,
       )
-    if (formFieldType(target.type)?.presentational)
+    if (formFieldType(target.type, types)?.presentational)
       add(file, `${rulePath}.field`, `"${rule.field}" collects nothing, so it cannot be compared`)
     const valueless = VALUELESS_OPERATORS.includes(rule.operator)
     if (valueless && rule.value !== undefined)
@@ -275,6 +334,15 @@ function validateWorkflows(
         'runs on approval, but the form does not require approval so nothing ever approves it',
       )
 
+    const bundled = (options.types ?? BUILT_IN_FORM_TYPES).workflows.get(workflow.type)
+    if (bundled?.bundle) {
+      const where = `a ${workflow.type} workflow`
+      const declared = settingsProblems(bundled.declared, workflow.settings, where)
+      for (const message of declared) add(file, `${path}.settings`, message)
+      const own = declared.length === 0 ? bundled.validate?.(workflow.settings) : undefined
+      if (own) add(file, `${path}.settings`, own)
+      continue
+    }
     const rules = WORKFLOW_SETTINGS[workflow.type]
     if (!rules) continue
     const allowed = new Set([...rules.required, ...rules.optional])

package/src/validate.ts

@@ -2,6 +2,7 @@
  * Whole-set validation. Every problem is reported, not just the first, because
  * a person fixing a schema wants the full list.
  */
+
 import { SYSTEM_MEDIA_TYPES, SYSTEM_MEMBER_TYPE } from '@crombolo/data'
 import {
   BUILTIN_DATA_TYPE_ALIASES,
@@ -18,6 +19,7 @@ import {
   TYPE_KIND_FILES,
 } from './model.ts'
 import { type ValidateFormsOptions, validateForms } from './validate-forms.ts'
+import { validateWorkflows } from './workflows.ts'
 
 export interface ValidateOptions extends ValidateFormsOptions {
   /** Template aliases that exist as view files; omit to skip template checks. */
@@ -220,6 +222,12 @@ export function validateSchemaSet(set: SchemaSet, options: ValidateOptions = {})
         options.contentTypeAliases ?? new Set(set.contentTypes.map((t) => t.alias)),
     }),
   )
+  problems.push(
+    ...validateWorkflows(
+      set.workflows ?? [],
+      options.contentTypeAliases ?? new Set(set.contentTypes.map((t) => t.alias)),
+    ),
+  )
   return problems
 }