@crombolo/schema 0.11.0 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/schema",
-  "version": "0.11.0",
+  "version": "0.13.1",
   "description": "Schema-as-code for crombolo: TOML document, media and member type definitions.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.11.0",
-    "@crombolo/data": "0.11.0"
+    "@crombolo/core": "0.13.1",
+    "@crombolo/data": "0.13.1"
   }
 }

package/src/check.ts

@@ -17,6 +17,9 @@ import {
   latestPreparedState,
   pendingMigrations,
   readLedger,
+  SYSTEM_CONTENT_TYPES,
+  SYSTEM_MEDIA_TYPES,
+  SYSTEM_MEMBER_TYPE,
 } from '@crombolo/data'
 import { BUILTIN_DATA_TYPES, storageTypeFor } from './builtin.ts'
 import type { LoadedSchema } from './load.ts'
@@ -213,26 +216,56 @@ export async function runCheck(
   const ledgered = new Set(ledger.filter((r) => r.kind === 'value').map((r) => r.name))
   const prepared = await latestPreparedState(db)
 
-  // ---- types removed while they have content
-  const inFiles = new Set(loaded.set.contentTypes.map((t) => t.alias))
-  const dbTypes = await db.query<{ unique_id: string; alias: string }>(
-    'SELECT n.unique_id, ct.alias FROM content_type ct JOIN node n ON n.id = ct.node_id WHERE ct.retired_at IS NULL',
-  )
-  for (const row of dbTypes) {
-    if (inFiles.has(String(row.alias))) continue
-    const count = await types.contentCount(String(row.unique_id).toLowerCase())
-    if (count === 0) continue
-    findings.push({
-      kind: 'blocking',
-      code: 'type-removed-with-content',
-      subjectType: 'document-type',
-      subjectKey: String(row.unique_id).toLowerCase(),
-      subjectName: String(row.alias),
-      propertyAlias: null,
-      culture: null,
-      message: `content type "${row.alias}" was removed from schema/ but ${count} document(s) of it exist`,
-      link: null,
-    })
+  // ---- types removed while they have content; the shipped types need no file
+  const shipped = new Set([
+    ...SYSTEM_MEDIA_TYPES.map((t) => t.key),
+    ...SYSTEM_CONTENT_TYPES.map((t) => t.key),
+    SYSTEM_MEMBER_TYPE.key,
+  ])
+  const kinds = [
+    {
+      kind: 'document' as const,
+      files: loaded.set.contentTypes,
+      noun: 'content type',
+      items: 'document(s)',
+    },
+    {
+      kind: 'media' as const,
+      files: loaded.set.mediaTypes ?? [],
+      noun: 'media type',
+      items: 'media item(s)',
+    },
+    {
+      kind: 'member' as const,
+      files: loaded.set.memberTypes ?? [],
+      noun: 'member type',
+      items: 'member(s)',
+    },
+  ]
+  for (const { kind, files, noun, items } of kinds) {
+    const repo = kind === 'document' ? types : new ContentTypeRepository(db, { kind })
+    const inFiles = new Set(files.map((t) => t.alias.toLowerCase()))
+    const dbTypes = await db.query<{ unique_id: string; alias: string }>(
+      'SELECT n.unique_id, ct.alias FROM content_type ct JOIN node n ON n.id = ct.node_id WHERE ct.retired_at IS NULL AND n.node_object_type = ?',
+      [repo.objectType],
+    )
+    for (const row of dbTypes) {
+      const key = String(row.unique_id).toLowerCase()
+      if (inFiles.has(String(row.alias).toLowerCase()) || shipped.has(key)) continue
+      const count = await repo.contentCount(key)
+      if (count === 0) continue
+      findings.push({
+        kind: 'blocking',
+        code: 'type-removed-with-content',
+        subjectType: `${kind}-type` as const,
+        subjectKey: key,
+        subjectName: String(row.alias),
+        propertyAlias: null,
+        culture: null,
+        message: `${noun} "${row.alias}" was removed from schema/ but ${count} ${items} of it exist`,
+        link: null,
+      })
+    }
   }
 
   // ---- properties that need data: newly mandatory, or changing editor

package/src/export.ts

@@ -18,6 +18,7 @@ import {
   type Db,
   FolderRepository,
   LanguageRepository,
+  readUrlOptions,
   SYSTEM_CONTENT_TYPES,
   SYSTEM_MEDIA_TYPES,
 } from '@crombolo/data'
@@ -188,6 +189,7 @@ function isUnchangedBuiltin(dataType: SchemaDataType): boolean {
 
 /** Every live definition in the database as a schema set; keys are always present. */
 export async function exportSchemaSet(db: Db, version: string): Promise<SchemaSet> {
+  const urls = await readUrlOptions(db)
   const types = new ContentTypeRepository(db)
   const dataTypes = new DataTypeRepository(db)
   const templates = new ComponentRepository(db)
@@ -330,6 +332,7 @@ export async function exportSchemaSet(db: Db, version: string): Promise<SchemaSe
     memberTypes,
     dataTypes: exportedDataTypes,
     languages,
+    ...(urls.hideTopLevel ? {} : { urls }),
   }
 }
 
@@ -342,7 +345,7 @@ export function writeSchemaFiles(schemaDir: string, set: SchemaSet): string[] {
     writeFileSync(file, content)
     written.push(file)
   }
-  put('schema.toml', writeSchemaVersion(set.version))
+  put('schema.toml', writeSchemaVersion(set.version, set.urls))
   for (const t of set.contentTypes)
     put(join(TYPE_KIND_FILES.document.dir, fileNameFor(t.alias)), writeContentType(t))
   for (const t of set.mediaTypes ?? [])

package/src/forms.ts

@@ -1,328 +1,34 @@
 /**
- * The form model, and the closed set of field types it may use.
- *
- * A form definition is structure, so it is a file like every other type
- * (`docs/forms.md`). Field types are an internal registry rather than an
- * extension point: the TOML vocabulary, the validator, the renderer and the
- * entry value shape all have to agree, and freezing that contract before
- * anything has stressed it would be a promise made too early.
+ * The form model and its closed set of field types. It lives in `@crombolo/core`,
+ * which the renderer shares; re-exported here for the schema package's users.
  */
-
-export type FormFieldType =
-  | 'shortAnswer'
-  | 'longAnswer'
-  | 'email'
-  | 'number'
-  | 'date'
-  | 'checkbox'
-  | 'dropdown'
-  | 'singleChoice'
-  | 'multipleChoice'
-  | 'fileUpload'
-  | 'dataConsent'
-  | 'titleAndDescription'
-  | 'richText'
-  | 'hidden'
-
-/** How a submitted value is stored, which decides how an entry reads it back. */
-export type FormValueKind = 'string' | 'strings' | 'number' | 'boolean' | 'files' | 'none'
-
-export interface FormFieldTypeInfo {
-  type: FormFieldType
-  label: string
-  stores: FormValueKind
-  /** Whether a choice list (`values`) applies, and is required. */
-  choices: boolean
-  /**
-   * Collects nothing: a caption and some text on the page. Never mandatory,
-   * never in an export, and never a condition's subject.
-   */
-  presentational: boolean
-  /** The settings this type accepts beyond the ones every field has. */
-  settings: readonly FormFieldSetting[]
-}
-
-export type FormFieldSetting =
-  | 'placeholder'
-  | 'maxlength'
-  | 'rows'
-  | 'min'
-  | 'max'
-  | 'step'
-  | 'accept'
-  | 'max-size-kb'
-  | 'content'
-  | 'default-value'
-  | 'multiple'
-
-const TEXTUAL = ['placeholder', 'maxlength', 'default-value'] as const
-
-export const FORM_FIELD_TYPES: readonly FormFieldTypeInfo[] = [
-  {
-    type: 'shortAnswer',
-    label: 'Short answer',
-    stores: 'string',
-    choices: false,
-    presentational: false,
-    settings: TEXTUAL,
-  },
-  {
-    type: 'longAnswer',
-    label: 'Long answer',
-    stores: 'string',
-    choices: false,
-    presentational: false,
-    settings: [...TEXTUAL, 'rows'],
-  },
-  {
-    type: 'email',
-    label: 'Email address',
-    stores: 'string',
-    choices: false,
-    presentational: false,
-    settings: TEXTUAL,
-  },
-  {
-    type: 'number',
-    label: 'Number',
-    stores: 'number',
-    choices: false,
-    presentational: false,
-    settings: ['placeholder', 'min', 'max', 'step', 'default-value'],
-  },
-  {
-    type: 'date',
-    label: 'Date',
-    stores: 'string',
-    choices: false,
-    presentational: false,
-    settings: ['min', 'max', 'default-value'],
-  },
-  {
-    type: 'checkbox',
-    label: 'Checkbox',
-    stores: 'boolean',
-    choices: false,
-    presentational: false,
-    settings: ['default-value'],
-  },
-  {
-    type: 'dropdown',
-    label: 'Dropdown',
-    stores: 'string',
-    choices: true,
-    presentational: false,
-    settings: ['default-value'],
-  },
-  {
-    type: 'singleChoice',
-    label: 'Single choice',
-    stores: 'string',
-    choices: true,
-    presentational: false,
-    settings: ['default-value'],
-  },
-  {
-    type: 'multipleChoice',
-    label: 'Multiple choice',
-    stores: 'strings',
-    choices: true,
-    presentational: false,
-    settings: [],
-  },
-  {
-    type: 'fileUpload',
-    label: 'File upload',
-    stores: 'files',
-    choices: false,
-    presentational: false,
-    settings: ['accept', 'max-size-kb', 'multiple'],
-  },
-  {
-    // Mandatory by default: a consent field that can be skipped is not consent.
-    type: 'dataConsent',
-    label: 'Data consent',
-    stores: 'boolean',
-    choices: false,
-    presentational: false,
-    settings: [],
-  },
-  {
-    type: 'titleAndDescription',
-    label: 'Title and description',
-    stores: 'none',
-    choices: false,
-    presentational: true,
-    settings: ['content'],
-  },
-  {
-    type: 'richText',
-    label: 'Rich text',
-    stores: 'none',
-    choices: false,
-    presentational: true,
-    settings: ['content'],
-  },
-  {
-    type: 'hidden',
-    label: 'Hidden',
-    stores: 'string',
-    choices: false,
-    presentational: false,
-    settings: ['default-value'],
-  },
-]
-
-const BY_TYPE = new Map(FORM_FIELD_TYPES.map((info) => [info.type, info]))
-
-export function formFieldType(type: string): FormFieldTypeInfo | undefined {
-  return BY_TYPE.get(type as FormFieldType)
-}
-
-export const FORM_FIELD_TYPE_NAMES: readonly string[] = FORM_FIELD_TYPES.map((info) => info.type)
-
-/** Password is absent on purpose: a form that collects one should not exist. */
-export type FormConditionOperator =
-  | 'is'
-  | 'isNot'
-  | 'contains'
-  | 'doesNotContain'
-  | 'startsWith'
-  | 'endsWith'
-  | 'greaterThan'
-  | 'lessThan'
-  | 'isEmpty'
-  | 'isNotEmpty'
-
-export const FORM_CONDITION_OPERATORS: readonly FormConditionOperator[] = [
-  'is',
-  'isNot',
-  'contains',
-  'doesNotContain',
-  'startsWith',
-  'endsWith',
-  'greaterThan',
-  'lessThan',
-  'isEmpty',
-  'isNotEmpty',
-]
-
-/** The two operators that take no value, because the value is the emptiness. */
-export const VALUELESS_OPERATORS: readonly FormConditionOperator[] = ['isEmpty', 'isNotEmpty']
-
-export interface FormConditionRule {
-  /** Another field's alias, which must appear before this one. */
-  field: string
-  operator: FormConditionOperator
-  value?: string
-}
-
-export interface FormCondition {
-  action: 'show' | 'hide'
-  match: 'all' | 'any'
-  rules: FormConditionRule[]
-}
-
-export interface SchemaFormField {
-  key?: string
-  alias: string
-  type: FormFieldType
-  caption: string
-  helpText?: string
-  mandatory: boolean
-  mandatoryMessage?: string
-  /** A regular expression the value must match, and what to say when it does not. */
-  pattern?: string
-  patternMessage?: string
-  /** Hidden from anyone without the sensitive-data permission, in the API and in exports. */
-  sensitive: boolean
-  cssClass?: string
-  autocomplete?: string
-  /** A choice list, for the types that take one. */
-  values: string[]
-  placeholder?: string
-  defaultValue?: string
-  content?: string
-  maxlength?: number
-  rows?: number
-  min?: number
-  max?: number
-  step?: number
-  accept: string[]
-  maxSizeKb?: number
-  multiple?: boolean
-  condition?: FormCondition
-}
-
-export interface SchemaFormGroup {
-  caption?: string
-  /** A simple column count; the renderer lays the fields out across it. */
-  columns: number
-  fields: SchemaFormField[]
-  condition?: FormCondition
-}
-
-export interface SchemaFormPage {
-  caption?: string
-  groups: SchemaFormGroup[]
-  condition?: FormCondition
-}
-
-export type FormWorkflowType = 'sendEmail' | 'saveAsContent' | 'sendToUrl'
-
-export const FORM_WORKFLOW_TYPES: readonly FormWorkflowType[] = [
-  'sendEmail',
-  'saveAsContent',
-  'sendToUrl',
-]
-
-/** The state transition a workflow runs on. */
-export type FormWorkflowTrigger = 'submit' | 'approve'
-
-export interface SchemaFormWorkflow {
-  key?: string
-  type: FormWorkflowType
-  name: string
-  on: FormWorkflowTrigger
-  /** Per-type, so it is checked by the validator rather than by the shape. */
-  settings: Record<string, unknown>
-}
-
-export interface SchemaForm {
-  key?: string
-  alias: string
-  name: string
-  notes?: string
-  /** Whether a submission is kept. Off makes the form fire workflows and store nothing. */
-  storeEntries: boolean
-  /** Entries wait as `submitted` until someone approves them. */
-  requiresApproval: boolean
-  submitLabel?: string
-  nextLabel?: string
-  previousLabel?: string
-  /** Shown in place of the form after a submission, when there is no redirect. */
-  messageOnSubmit?: string
-  /** A document key to send the visitor to instead of showing a message. */
-  redirectTo?: string
-  /** A theme directory under `components/Forms/`. */
-  theme?: string
-  /** A field real visitors never fill; a filled one is marked as spam. */
-  honeypot: boolean
-  /** A submission faster than this is marked as spam. */
-  minimumSubmitSeconds?: number
-  /** Refused once this many entries exist, for a form with a hard cap. */
-  maxEntries?: number
-  since?: string
-  pages: SchemaFormPage[]
-  workflows: SchemaFormWorkflow[]
-}
-
-/** Every field in a form, in the order a visitor meets them. */
-export function allFormFields(form: SchemaForm): SchemaFormField[] {
-  return form.pages.flatMap((page) => page.groups.flatMap((group) => group.fields))
-}
-
-/** Every field that stores something, which is what an entry and an export carry. */
-export function storingFormFields(form: SchemaForm): SchemaFormField[] {
-  return allFormFields(form).filter((field) => formFieldType(field.type)?.stores !== 'none')
-}
+export {
+  allFormFields,
+  CHOICE_SOURCE_KINDS,
+  type ChoiceOption,
+  type ChoiceSource,
+  type ChoiceSourceKind,
+  choiceOptions,
+  FORM_CONDITION_OPERATORS,
+  FORM_FIELD_TYPE_NAMES,
+  FORM_FIELD_TYPES,
+  FORM_WORKFLOW_TYPES,
+  type FormCondition,
+  type FormConditionOperator,
+  type FormConditionRule,
+  type FormFieldSetting,
+  type FormFieldType,
+  type FormFieldTypeInfo,
+  type FormValueKind,
+  type FormWorkflowTrigger,
+  type FormWorkflowType,
+  formFieldType,
+  type SchemaForm,
+  type SchemaFormField,
+  type SchemaFormGroup,
+  type SchemaFormPage,
+  type SchemaFormWorkflow,
+  storingFormFields,
+  VALUELESS_OPERATORS,
+  withResolvedChoices,
+} from '@crombolo/core'

package/src/index.ts

@@ -15,5 +15,6 @@ export * from './validate.ts'
 export * from './validate-forms.ts'
 export * from './value-migrations.ts'
 export * from './version.ts'
+export * from './workflows.ts'
 export * from './write.ts'
 export * from './write-forms.ts'

package/src/load.ts

@@ -4,9 +4,11 @@
  * The hash is over canonical serialisations, sorted — so it does not change
  * with file order, whitespace or comments, only with meaning.
  */
+
 import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import type { FormTypes, SchemaWorkflow } from '@crombolo/core'
 import type { SchemaForm } from './forms.ts'
 import type {
   SchemaContentType,
@@ -14,6 +16,7 @@ import type {
   SchemaLanguage,
   SchemaProblem,
   SchemaSet,
+  SchemaUrls,
 } from './model.ts'
 import { TYPE_KIND_FILES, typeFileKey } from './model.ts'
 import {
@@ -22,9 +25,10 @@ import {
   parseLanguages,
   parseMediaType,
   parseMemberType,
-  parseSchemaVersion,
+  parseSchemaSettings,
 } from './parse.ts'
 import { parseForm } from './parse-forms.ts'
+import { parseWorkflow, writeWorkflow } from './workflows.ts'
 import {
   writeContentType,
   writeDataType,
@@ -49,22 +53,34 @@ function tomlFiles(dir: string): string[] {
     .map((name) => join(dir, name))
 }
 
-export function loadSchemaDirectory(schemaDir: string): LoadedSchema {
+export interface LoadSchemaOptions {
+  /** The field and workflow types forms may use: the built-ins, and the wired bundles'. */
+  formTypes?: FormTypes
+}
+
+export function loadSchemaDirectory(
+  schemaDir: string,
+  options: LoadSchemaOptions = {},
+): LoadedSchema {
   const problems: SchemaProblem[] = []
   const files = new Map<string, string>()
   const contentTypes: SchemaContentType[] = []
   const dataTypes: SchemaDataType[] = []
   let languages: SchemaLanguage[] = []
   let version = '0'
+  let urls: SchemaUrls | undefined
 
   const rel = (file: string) =>
     file.startsWith(schemaDir) ? `schema${file.slice(schemaDir.length)}` : file
 
   const versionFile = join(schemaDir, 'schema.toml')
   if (existsSync(versionFile)) {
-    const parsed = parseSchemaVersion(rel(versionFile), readFileSync(versionFile, 'utf8'))
+    const parsed = parseSchemaSettings(rel(versionFile), readFileSync(versionFile, 'utf8'))
     problems.push(...parsed.problems)
-    if (parsed.value) version = parsed.value
+    if (parsed.value) {
+      version = parsed.value.version
+      urls = parsed.value.urls
+    }
   }
   for (const file of tomlFiles(join(schemaDir, TYPE_KIND_FILES.document.dir))) {
     const parsed = parseContentType(rel(file), readFileSync(file, 'utf8'))
@@ -102,13 +118,22 @@ export function loadSchemaDirectory(schemaDir: string): LoadedSchema {
   }
   const forms: SchemaForm[] = []
   for (const file of tomlFiles(join(schemaDir, 'forms'))) {
-    const parsed = parseForm(rel(file), readFileSync(file, 'utf8'))
+    const parsed = parseForm(rel(file), readFileSync(file, 'utf8'), options.formTypes)
     problems.push(...parsed.problems)
     if (parsed.value) {
       forms.push(parsed.value)
       files.set(`form:${parsed.value.alias}`, file)
     }
   }
+  const workflows: SchemaWorkflow[] = []
+  for (const file of tomlFiles(join(schemaDir, 'workflows'))) {
+    const parsed = parseWorkflow(rel(file), readFileSync(file, 'utf8'))
+    problems.push(...parsed.problems)
+    if (parsed.value) {
+      workflows.push(parsed.value)
+      files.set(`workflow:${parsed.value.alias}`, file)
+    }
+  }
   const languagesFile = join(schemaDir, 'languages.toml')
   if (existsSync(languagesFile)) {
     const parsed = parseLanguages(rel(languagesFile), readFileSync(languagesFile, 'utf8'))
@@ -116,7 +141,17 @@ export function loadSchemaDirectory(schemaDir: string): LoadedSchema {
     if (parsed.value) languages = parsed.value
   }
   return {
-    set: { version, contentTypes, mediaTypes, memberTypes, dataTypes, languages, forms },
+    set: {
+      version,
+      contentTypes,
+      mediaTypes,
+      memberTypes,
+      dataTypes,
+      languages,
+      forms,
+      ...(workflows.length > 0 ? { workflows } : {}),
+      ...(urls ? { urls } : {}),
+    },
     problems,
     files,
   }
@@ -126,12 +161,16 @@ export function loadSchemaDirectory(schemaDir: string): LoadedSchema {
 export function hashSchemaSet(set: SchemaSet): string {
   const parts = [
     `version:${set.version}`,
+    // Only when not the default, so every site hashed before this kept its hash.
+    ...(set.urls?.hideTopLevel === false ? ['urls:top-level-shown'] : []),
     ...set.contentTypes.map((t) => writeContentType(t)).sort(),
     ...(set.mediaTypes ?? []).map((t) => writeMediaType(t)).sort(),
     ...(set.memberTypes ?? []).map((t) => writeMemberType(t)).sort(),
     ...set.dataTypes.map((d) => writeDataType(d)).sort(),
     writeLanguages([...set.languages].sort((a, b) => a.iso.localeCompare(b.iso))),
     ...(set.forms ?? []).map((f) => writeForm(f)).sort(),
+    // Absent from a set with none, so every hash taken before workflows stands.
+    ...(set.workflows ?? []).map((w) => writeWorkflow(w)).sort(),
   ]
   return createHash('sha256').update(parts.join('\n---\n')).digest('hex')
 }

package/src/model.ts

@@ -1,4 +1,4 @@
-import type { SchemaForm } from '@crombolo/core'
+import type { SchemaForm, SchemaWorkflow } from '@crombolo/core'
 
 /**
  * The schema-as-code model: what a site's `schema/*.toml` files describe.
@@ -112,6 +112,16 @@ export interface SchemaSet {
   languages: SchemaLanguage[]
   /** `schema/forms/*.toml` — form definitions; see `docs/forms.md`. */
   forms?: SchemaForm[]
+  /** `[urls]` in schema/schema.toml; Umbraco's defaults when absent. */
+  urls?: SchemaUrls
+  /** `schema/workflows/*.toml` — approval workflows; see `docs/workflows.md`. */
+  workflows?: SchemaWorkflow[]
+}
+
+/** How URLs are built, as Umbraco's `Umbraco:CMS:Global` settings set it. */
+export interface SchemaUrls {
+  /** `HideTopLevelNodeFromPath`: true, the default, leaves the top-level page out of paths. */
+  hideTopLevel: boolean
 }
 
 /** A problem found while parsing or validating, always locatable. */