@crombolo/schema 0.0.0-stage → 0.9.1

package/src/forms.ts

@@ -0,0 +1,328 @@
+/**
+ * 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/18-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.
+ */
+
+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')
+}

package/src/generate.ts

@@ -0,0 +1,149 @@
+/**
+ * `crombolo generate`: TypeScript for the content types in a schema set, so a
+ * view can name a property and have the compiler check it. Umbraco's
+ * ModelsBuilder, minus the DLL.
+ */
+import { SYSTEM_CONTENT_TYPES } from '@crombolo/data'
+import { BUILTIN_DATA_TYPES, builtInContentTypeSchema, storageTypeFor } from './builtin.ts'
+import { allProperties, type SchemaContentType, type SchemaSet } from './model.ts'
+
+function pascal(alias: string): string {
+  const cleaned = alias.replace(/[^A-Za-z0-9]+(.)?/g, (_, next: string | undefined) =>
+    next ? next.toUpperCase() : '',
+  )
+  return cleaned.charAt(0).toUpperCase() + cleaned.slice(1)
+}
+
+/** The element types a block data type allows, by alias, for its content and its settings. */
+function blockElements(set: SchemaSet, config: Record<string, unknown>) {
+  const blocks = Array.isArray(config.blocks)
+    ? (config.blocks as Array<Record<string, unknown>>)
+    : []
+  const aliasOf = (key: unknown) =>
+    typeof key === 'string'
+      ? set.contentTypes.find((t) => t.key?.toLowerCase() === key.toLowerCase())?.alias
+      : undefined
+  const content = blocks.flatMap((b) => aliasOf(b.contentElementTypeKey) ?? [])
+  const settings = blocks.flatMap((b) => aliasOf(b.settingsElementTypeKey) ?? [])
+  return { content: [...new Set(content)], settings: [...new Set(settings)] }
+}
+
+const elementUnion = (aliases: string[]) =>
+  aliases.length === 0
+    ? 'PublishedElement'
+    : aliases.map((a) => `TypedElement<${pascal(a)}>`).join(' | ')
+
+/** What a template receives for a property of this data type (see `@crombolo/render` values). */
+function tsTypeFor(set: SchemaSet, dataTypeAlias: string): string {
+  const custom = set.dataTypes.find((d) => d.alias === dataTypeAlias)
+  const editor = custom?.editor ?? BUILTIN_DATA_TYPES.find((b) => b.alias === dataTypeAlias)?.editor
+  const config =
+    custom?.config ?? BUILTIN_DATA_TYPES.find((b) => b.alias === dataTypeAlias)?.config ?? {}
+  if (!editor) return 'unknown'
+  switch (editor) {
+    case 'Umbraco.TrueFalse':
+      return 'boolean'
+    case 'Umbraco.ContentPicker':
+      return 'PublishedContent | null'
+    case 'Umbraco.MultiNodeTreePicker':
+      return 'PublishedContent[]'
+    case 'Umbraco.MultiUrlPicker':
+      return 'Link[]'
+    case 'Umbraco.ElementPicker': {
+      // `allowedContentTypes` is a comma-separated list of element type keys, as
+      // Umbraco's AllowedContentTypeKeysParser reads it. Narrowing to those types
+      // is what makes `hero.value('body')` typed rather than `unknown`.
+      const allowed =
+        typeof config.allowedContentTypes === 'string' ? config.allowedContentTypes : ''
+      const aliases = allowed
+        .split(',')
+        .map((key) => key.trim())
+        .filter(Boolean)
+        .flatMap(
+          (key) =>
+            set.contentTypes.find((t) => t.key?.toLowerCase() === key.toLowerCase())?.alias ?? [],
+        )
+      // `Array<>` not `[]`: a union of two element types would otherwise bind as
+      // `A | (B[])`.
+      return `Array<${elementUnion([...new Set(aliases)])}>`
+    }
+    case 'Umbraco.Tags':
+    case 'Umbraco.CheckBoxList':
+    case 'Umbraco.DropDown.Flexible':
+    case 'Umbraco.MultipleTextstring':
+      return 'string[]'
+    case 'Umbraco.UploadField':
+      return 'string'
+    case 'Umbraco.BlockList': {
+      const { content, settings } = blockElements(set, config)
+      return `Array<BlockItem & { content: ${elementUnion(content)}; settings: ${settings.length ? `${elementUnion(settings)} | null` : 'PublishedElement | null'} }>`
+    }
+    case 'Umbraco.BlockGrid': {
+      const { content } = blockElements(set, config)
+      return `Array<BlockGridItem & { content: ${elementUnion(content)} }>`
+    }
+  }
+  switch (storageTypeFor(editor)) {
+    case 'Integer':
+    case 'Decimal':
+      return 'number'
+    case 'Date':
+    case 'Nvarchar':
+      return 'string'
+    default:
+      return editor === 'Umbraco.TextArea' || editor === 'Umbraco.RichText' ? 'string' : 'unknown'
+  }
+}
+
+/** Every property a type carries, including those from its compositions. */
+function effectiveProperties(set: SchemaSet, type: SchemaContentType, seen = new Set<string>()) {
+  if (seen.has(type.alias)) return []
+  seen.add(type.alias)
+  const out = [...allProperties(type)]
+  for (const alias of type.compositions) {
+    // A built-in type such as `seoFields` has no file until a site extends it.
+    const shipped = SYSTEM_CONTENT_TYPES.find((t) => t.alias === alias)
+    const composed =
+      set.contentTypes.find((t) => t.alias === alias) ??
+      (shipped ? builtInContentTypeSchema(shipped) : undefined)
+    if (composed) out.push(...effectiveProperties(set, composed, seen))
+  }
+  return out
+}
+
+export function generateTypes(set: SchemaSet): string {
+  const out: string[] = [
+    '// Generated by `crombolo generate` from schema/*.toml. Do not edit.',
+    '',
+    'export interface ContentTypeProperties {',
+  ]
+  for (const t of [...set.contentTypes].sort((a, b) => a.alias.localeCompare(b.alias))) {
+    out.push(`  ${JSON.stringify(t.alias)}: ${pascal(t.alias)}`)
+  }
+  out.push('}', '')
+  out.push('export type ContentTypeAlias = keyof ContentTypeProperties', '')
+  for (const t of [...set.contentTypes].sort((a, b) => a.alias.localeCompare(b.alias))) {
+    out.push(`/** ${t.name}${t.description ? ` — ${t.description}` : ''} */`)
+    out.push(`export interface ${pascal(t.alias)} {`)
+    const properties = effectiveProperties(set, t)
+    const byAlias = new Map(properties.map((p) => [p.alias, p]))
+    for (const p of [...byAlias.values()].sort((a, b) => a.alias.localeCompare(b.alias))) {
+      if (p.description) out.push(`  /** ${p.description} */`)
+      out.push(`  ${JSON.stringify(p.alias)}${p.mandatory ? '' : '?'}: ${tsTypeFor(set, p.type)}`)
+    }
+    out.push('}', '')
+  }
+  // Import only the value types the generated interfaces use.
+  const body = out.join('\n')
+  const used = [
+    'BlockGridItem',
+    'BlockItem',
+    'Link',
+    'PublishedContent',
+    'PublishedElement',
+    'TypedElement',
+  ].filter((name) => new RegExp(`\\b${name}\\b`).test(body.split('\n').slice(2).join('\n')))
+  if (used.length > 0)
+    out.splice(2, 0, `import type { ${used.join(', ')} } from '@crombolo/crombolo'`, '')
+  return `${out.join('\n').trimEnd()}\n`
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export * from './builtin.ts'
+export * from './check.ts'
+export * from './export.ts'
+export * from './forms.ts'
+export * from './generate.ts'
+export * from './load.ts'
+export * from './model.ts'
+export * from './parse.ts'
+export * from './parse-forms.ts'
+export * from './reader.ts'
+export * from './scaffold.ts'
+export * from './sync.ts'
+export * from './upgrade.ts'
+export * from './validate.ts'
+export * from './validate-forms.ts'
+export * from './value-migrations.ts'
+export * from './version.ts'
+export * from './write.ts'
+export * from './write-forms.ts'

package/src/load.ts

@@ -0,0 +1,137 @@
+/**
+ * Reads a `schema/` directory into a SchemaSet, and hashes it.
+ *
+ * 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 { SchemaForm } from './forms.ts'
+import type {
+  SchemaContentType,
+  SchemaDataType,
+  SchemaLanguage,
+  SchemaProblem,
+  SchemaSet,
+} from './model.ts'
+import { TYPE_KIND_FILES, typeFileKey } from './model.ts'
+import {
+  parseContentType,
+  parseDataType,
+  parseLanguages,
+  parseMediaType,
+  parseMemberType,
+  parseSchemaVersion,
+} from './parse.ts'
+import { parseForm } from './parse-forms.ts'
+import {
+  writeContentType,
+  writeDataType,
+  writeLanguages,
+  writeMediaType,
+  writeMemberType,
+} from './write.ts'
+import { writeForm } from './write-forms.ts'
+
+export interface LoadedSchema {
+  set: SchemaSet
+  problems: SchemaProblem[]
+  /** Which file each type or data type came from, by alias. */
+  files: Map<string, string>
+}
+
+function tomlFiles(dir: string): string[] {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.toml'))
+    .sort()
+    .map((name) => join(dir, name))
+}
+
+export function loadSchemaDirectory(schemaDir: string): LoadedSchema {
+  const problems: SchemaProblem[] = []
+  const files = new Map<string, string>()
+  const contentTypes: SchemaContentType[] = []
+  const dataTypes: SchemaDataType[] = []
+  let languages: SchemaLanguage[] = []
+  let version = '0'
+
+  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'))
+    problems.push(...parsed.problems)
+    if (parsed.value) version = parsed.value
+  }
+  for (const file of tomlFiles(join(schemaDir, TYPE_KIND_FILES.document.dir))) {
+    const parsed = parseContentType(rel(file), readFileSync(file, 'utf8'))
+    problems.push(...parsed.problems)
+    if (parsed.value) {
+      contentTypes.push(parsed.value)
+      files.set(parsed.value.alias, file)
+    }
+  }
+  const mediaTypes: SchemaContentType[] = []
+  for (const file of tomlFiles(join(schemaDir, 'media-types'))) {
+    const parsed = parseMediaType(rel(file), readFileSync(file, 'utf8'))
+    problems.push(...parsed.problems)
+    if (parsed.value) {
+      mediaTypes.push(parsed.value)
+      files.set(typeFileKey('media', parsed.value.alias), file)
+    }
+  }
+  const memberTypes: SchemaContentType[] = []
+  for (const file of tomlFiles(join(schemaDir, 'member-types'))) {
+    const parsed = parseMemberType(rel(file), readFileSync(file, 'utf8'))
+    problems.push(...parsed.problems)
+    if (parsed.value) {
+      memberTypes.push(parsed.value)
+      files.set(typeFileKey('member', parsed.value.alias), file)
+    }
+  }
+  for (const file of tomlFiles(join(schemaDir, 'data-types'))) {
+    const parsed = parseDataType(rel(file), readFileSync(file, 'utf8'))
+    problems.push(...parsed.problems)
+    if (parsed.value) {
+      dataTypes.push(parsed.value)
+      files.set(`data-type:${parsed.value.alias}`, file)
+    }
+  }
+  const forms: SchemaForm[] = []
+  for (const file of tomlFiles(join(schemaDir, 'forms'))) {
+    const parsed = parseForm(rel(file), readFileSync(file, 'utf8'))
+    problems.push(...parsed.problems)
+    if (parsed.value) {
+      forms.push(parsed.value)
+      files.set(`form:${parsed.value.alias}`, file)
+    }
+  }
+  const languagesFile = join(schemaDir, 'languages.toml')
+  if (existsSync(languagesFile)) {
+    const parsed = parseLanguages(rel(languagesFile), readFileSync(languagesFile, 'utf8'))
+    problems.push(...parsed.problems)
+    if (parsed.value) languages = parsed.value
+  }
+  return {
+    set: { version, contentTypes, mediaTypes, memberTypes, dataTypes, languages, forms },
+    problems,
+    files,
+  }
+}
+
+/** Order-independent content hash of a schema set. */
+export function hashSchemaSet(set: SchemaSet): string {
+  const parts = [
+    `version:${set.version}`,
+    ...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(),
+  ]
+  return createHash('sha256').update(parts.join('\n---\n')).digest('hex')
+}