@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/elements/ops/upgrade.ts

@@ -0,0 +1,43 @@
+import type { DocumentDecl, ElementEntry, Schema } from '../define'
+import type { ElementId } from '../ids'
+import { CONTRACTS, CURRENT_CONTRACT, elements } from '../registry'
+import { walkDocument } from '../walk'
+
+export class UpgradeError extends Error {
+  constructor(public path: string, public from: number, public to: number, public cause: unknown) {
+    super(`Upgrading ${path} from v${from} to v${to} failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+    this.name = 'UpgradeError'
+  }
+}
+export type UpgradeOptions = { registry?: Record<ElementId, ElementEntry>; contracts?: Record<number, Record<ElementId, number>>; current?: number }
+
+/**
+ * Runs each leaf's upgrade chain from the element version recorded for `fromContract` up to the
+ * registry's current version, writes the results back, and stamps `_contract`. Reads run this on
+ * the fly; writes store the result. v1 ships no upgrades, so this is a stamp unless a registry with
+ * newer versions is passed (as the tests do).
+ */
+export function upgrade(schema: Schema, docDecl: DocumentDecl, doc: any, at: string, fromContract: number, opts: UpgradeOptions = {}): unknown {
+  const registry = opts.registry ?? (elements as Record<ElementId, ElementEntry>)
+  const contracts = opts.contracts ?? CONTRACTS
+  const current = opts.current ?? CURRENT_CONTRACT
+  const versions = contracts[fromContract]
+  if (!versions) throw new Error(`Unknown contract version ${fromContract}.`)
+  walkDocument(schema, docDecl, doc, {
+    leaf: ({ decl, value, at: here, set }) => {
+      if (value === undefined) return
+      const entry = registry[decl.element]
+      let v = versions[decl.element] ?? 1
+      let upgraded: unknown = value
+      while (v < entry.version) {
+        const step = entry.upgrade[v]
+        if (!step) throw new UpgradeError(here, v, v + 1, new Error(`${decl.element} has no upgrade from v${v}.`))
+        try { upgraded = step(upgraded) } catch (cause) { throw new UpgradeError(here, v, v + 1, cause) }
+        v++
+      }
+      if (upgraded !== value) set(upgraded)
+    },
+  }, at)
+  doc._contract = current
+  return doc
+}

package/src/elements/ops/validate.ts

@@ -0,0 +1,56 @@
+import { SLOT, type DocumentDecl, type Issue, type LeafIssue, type Mode, type Schema } from '../define'
+import { hasStoredShape, validateLeaf } from '../leaf'
+import { path } from '../path'
+import { walkDocument } from '../walk'
+import { record } from '../containers/group'
+
+export type ValidateOptions = { mode: Mode; previous?: unknown }
+
+const valueAtPointer = (doc: unknown, pointer: string): unknown =>
+  pointer === '' ? doc : pointer.slice(1).split('/').reduce<any>((n, seg) => (n == null ? undefined : n[seg.replace(/~1/g, '/').replace(/~0/g, '~')]), doc)
+const dig = (v: unknown, sub: string) => sub.split('.').reduce<any>((n, k) => (n == null ? undefined : n[k]), v)
+const slots = (v: unknown) => (Array.isArray(v) ? v.filter((x) => record(x) && x._block === SLOT).length : 0)
+
+export function validate(schema: Schema, docDecl: DocumentDecl, doc: unknown, at: string, opts: ValidateOptions): Issue[] {
+  const issues: Issue[] = []
+  const push = (base: string, i: LeafIssue) => issues.push({ path: path.child(base, ...i.path), code: i.code, message: i.message, severity: i.severity ?? 'error' })
+  const ids = new Map<string, string>()
+  const layoutRoot = docDecl.kind === 'layout' ? path.child(at, 'blocks') : null
+  const root = (p: string, code: string, message: string): Issue[] => [{ path: p, code, message, severity: 'error' }]
+  if (!record(doc)) return root(at, 'invalid_type', 'A stored document is an object.')
+  if (docDecl.kind === 'entry' && !Object.hasOwn(schema.collections, docDecl.collection)) return root(at, 'unknown-collection', `No collection named "${docDecl.collection}".`)
+  if (docDecl.kind === 'single' && !Object.hasOwn(schema.singles, docDecl.key)) return root(at, 'unknown-single', `No Single named "${docDecl.key}".`)
+  if (docDecl.kind === 'entry' && doc.fields !== undefined && !record(doc.fields)) return root(path.child(at, 'fields'), 'invalid_type', 'An entry stores its fields as an object.')
+  walkDocument(schema, docDecl, doc, {
+    enter: ({ container, decl, value, at: here }) => {
+      container.enter(decl, value, schema).forEach((i) => push(here, i))
+      if (container.id === 'u90/zone' && slots(value) !== (here === layoutRoot ? 1 : 0))
+        push(here, { path: [], code: 'slot', message: here === layoutRoot ? 'A layout holds exactly one SLOT.' : 'Only a layout may hold a SLOT.' })
+      if (Array.isArray(value))
+        for (const item of value)
+          if (record(item) && typeof item._id === 'string') {
+            if (ids.has(item._id)) push(here, { path: [], code: 'duplicate-id', message: `The id "${item._id}" is already used at ${ids.get(item._id)}.` })
+            else ids.set(item._id, here)
+          }
+    },
+    leaf: ({ entry, decl, value, at: here }) => {
+      validateLeaf(entry, decl, value, opts.mode).forEach((i) => push(here, i))
+      if (decl.lock?.length && opts.previous !== undefined) {
+        const pointer = path.toPointer(opts.previous, here)
+        const before = pointer === null ? undefined : valueAtPointer(opts.previous, pointer)
+        if (before !== undefined)
+          for (const sub of decl.lock)
+            if (JSON.stringify(dig(before, sub)) !== JSON.stringify(dig(value, sub)))
+              push(here, { path: sub.split('.'), code: 'locked', message: 'This part is set by the site and cannot be changed here.' })
+      }
+      if (value !== undefined && value !== null) {
+        const o = entry.options.safeParse(decl.options ?? {})
+        if (o.success && hasStoredShape(entry, o.data, value))
+          for (const ref of entry.refs(value, o.data, here))
+            if (ref.kind === 'single' && !Object.hasOwn(schema.singles, ref.key))
+              push(here, { path: [], code: 'unknown-single', message: `No Single named "${ref.key}".`, severity: 'warning' })
+      }
+    },
+  }, at)
+  return issues
+}

package/src/elements/order.ts

@@ -0,0 +1,10 @@
+/** A record's keys in declared order: the listed keys that exist, then any others in their stored order. */
+export function orderedKeys(record: Record<string, unknown>, order?: readonly string[]): string[] {
+  const keys = Object.keys(record)
+  if (!order?.length) return keys
+  const listed = order.filter((k, i) => Object.hasOwn(record, k) && order.indexOf(k) === i)
+  return [...listed, ...keys.filter((k) => !listed.includes(k))]
+}
+export function orderedEntries<T>(record: Record<string, T>, order?: readonly string[]): [string, T][] {
+  return orderedKeys(record, order).map((k) => [k, record[k]])
+}

package/src/elements/path.ts

@@ -0,0 +1,43 @@
+export { ID_RE, newId } from './ids'
+const KINDS = ['page', 'entry', 'layout', 'single'] as const
+export type DocKind = (typeof KINDS)[number]
+export type Path = string
+
+const doc = (kind: DocKind, id: string | number): Path => `${kind}:${id}`
+const child = (p: Path, ...segments: (string | number)[]): Path =>
+  segments.length ? `${p}/${segments.join('/')}` : p
+const parse = (p: Path): { kind: DocKind; id: string; segments: string[] } => {
+  const m = /^(page|entry|layout|single):([^/]+)(?:\/(.*))?$/.exec(p)
+  if (!m) throw new Error(`Not a u90 path: ${p}`)
+  return { kind: m[1] as DocKind, id: m[2], segments: m[3] ? m[3].split('/') : [] }
+}
+/**
+ * JSON Pointer (RFC 6901) of a path inside its document. Arrays are addressed by `_id`,
+ * and a leaf list item resolves to its `_value`. Returns null when a segment does not exist.
+ */
+const toPointer = (document: unknown, p: Path): string | null => {
+  const { kind, segments } = parse(p)
+  // A Single document is `{ value }`; its leaf sits at the document path itself.
+  let node: any = kind === 'single' ? (document as any)?.value : document
+  let pointer = kind === 'single' ? '/value' : ''
+  for (const seg of segments) {
+    if (Array.isArray(node)) {
+      const i = node.findIndex((item) => item && typeof item === 'object' && item._id === seg)
+      if (i < 0) return null
+      node = node[i]
+      pointer += `/${i}`
+      if (node && typeof node === 'object' && '_value' in node) {
+        node = node._value
+        pointer += '/_value'
+      }
+    } else if (node && typeof node === 'object' && seg in node) {
+      node = node[seg]
+      pointer += `/${seg.replace(/~/g, '~0').replace(/\//g, '~1')}`
+    } else return null
+  }
+  return pointer
+}
+export const path = { doc, child, parse, toPointer }
+
+/** A leaf's key in an overlay: its path inside the document, `blocks/<blockId>/headline`; '' for a Single's own leaf. */
+export const overlayKey = (at: Path): string => parse(at).segments.join('/')

package/src/elements/prefix.ts

@@ -0,0 +1,2 @@
+/** `route` under a language's address prefix (`/fr`): the home page is the prefix itself. It imports nothing, so the languages proxy can load it without the element registry. */
+export const prefixedRoute = (prefix: string, route: string): string => (route === '/' ? prefix : `${prefix}${route}`)

package/src/elements/registry.ts

@@ -0,0 +1,48 @@
+import type { ContainerEntry, ElementEntry, FieldDecl } from './define'
+import { ELEMENT_IDS, type ContainerId, type ElementId } from './ids'
+import { boolean } from './leaves/boolean'
+import { choice } from './leaves/choice'
+import { date } from './leaves/date'
+import { file } from './leaves/file'
+import { image } from './leaves/image'
+import { link } from './leaves/link'
+import { number } from './leaves/number'
+import { query } from './leaves/query'
+import { relation } from './leaves/relation'
+import { richText } from './leaves/rich-text'
+import { selection } from './leaves/selection'
+import { single } from './leaves/single'
+import { text } from './leaves/text'
+import { video } from './leaves/video'
+import { group } from './containers/group'
+import { list } from './containers/list'
+import { zone } from './containers/zone'
+
+/** Every element. `satisfies` fails the build if an id has no entry. */
+export const elements = {
+  'u90/text': text,
+  'u90/rich-text': richText,
+  'u90/image': image,
+  'u90/video': video,
+  'u90/file': file,
+  'u90/link': link,
+  'u90/date': date,
+  'u90/number': number,
+  'u90/boolean': boolean,
+  'u90/choice': choice,
+  'u90/relation': relation,
+  'u90/selection': selection,
+  'u90/query': query,
+  'u90/single': single,
+} satisfies Record<ElementId, ElementEntry>
+
+export const getElement = (id: ElementId): ElementEntry => elements[id] as ElementEntry
+
+export const CURRENT_CONTRACT = 1
+/** Which element version each contract version was written with. Add a row when any element's version changes. */
+export const CONTRACTS: Record<number, Record<ElementId, number>> = {
+  1: Object.fromEntries(ELEMENT_IDS.map((id) => [id, 1])) as Record<ElementId, number>,
+}
+
+export const containers = { 'u90/group': group, 'u90/list': list, 'u90/zone': zone } satisfies Record<ContainerId, ContainerEntry<any>>
+export const getContainer = (id: ContainerId): ContainerEntry<FieldDecl> => containers[id] as unknown as ContainerEntry<FieldDecl>

package/src/elements/tokens.ts

@@ -0,0 +1,14 @@
+/** `{key}` inside copy points at a Single. Keys are lower-case identifiers. */
+export const TOKEN = /\{([a-z][a-zA-Z0-9_-]*)\}/g
+export const tokenKeys = (s: string): string[] => [...s.matchAll(TOKEN)].map((m) => m[1])
+/** The text a Single's read value contributes inline: Text gives `text`, Link gives `label`. */
+export const textOfRead = (read: unknown): string | undefined => {
+  if (!read || typeof read !== 'object') return undefined
+  const r = read as Record<string, unknown>
+  if (typeof r.text === 'string') return r.text
+  if (typeof r.label === 'string') return r.label
+  return undefined
+}
+/** Unknown keys stay literal; `validate` reports them as `unknown-single` warnings. */
+export const resolveTokens = (s: string, single: (key: string) => unknown): string =>
+  s.replace(TOKEN, (match, key: string) => textOfRead(single(key)) ?? match)

package/src/elements/walk.ts

@@ -0,0 +1,42 @@
+import { isLeaf, type ContainerEntry, type DocumentDecl, type ElementEntry, type FieldDecl, type GroupDecl, type LeafDecl, type ListDecl, type Schema, type ZoneDecl } from './define'
+import { path } from './path'
+import { getContainer, getElement } from './registry'
+
+export type LeafNode = { entry: ElementEntry; decl: LeafDecl; value: unknown; at: string; set(v: unknown): void }
+export type ContainerNode = { container: ContainerEntry<FieldDecl>; decl: GroupDecl | ListDecl | ZoneDecl; value: unknown; at: string; set(v: unknown): void }
+export type Visitor = { leaf?(n: LeafNode): void; enter?(n: ContainerNode): void; exit?(n: ContainerNode): void }
+const noop = () => {}
+
+/** The only traversal. Depth first; containers are entered, their children walked, then exited. */
+export function walk(schema: Schema, decl: FieldDecl, value: unknown, visitor: Visitor, at: string, set: (v: unknown) => void = noop): void {
+  if (isLeaf(decl)) {
+    visitor.leaf?.({ entry: getElement(decl.element), decl, value, at, set })
+    return
+  }
+  const container = getContainer(decl.container)
+  const node: ContainerNode = { container, decl, value, at, set }
+  visitor.enter?.(node)
+  for (const child of container.children(decl, value, schema)) walk(schema, child.decl, child.value, visitor, path.child(at, child.key), child.set)
+  visitor.exit?.(node)
+}
+
+/** Stored document shapes: page/layout `{ blocks }`, entry `{ fields, blocks? }`, single `{ value }`. */
+export function walkDocument(schema: Schema, docDecl: DocumentDecl, doc: any, visitor: Visitor, at: string): void {
+  switch (docDecl.kind) {
+    case 'page':
+    case 'layout':
+      return walk(schema, docDecl.blocks, doc?.blocks, visitor, path.child(at, 'blocks'), (v) => { doc.blocks = v })
+    case 'entry': {
+      const collection = Object.hasOwn(schema.collections, docDecl.collection) ? schema.collections[docDecl.collection] : undefined
+      if (!collection) throw new Error(`No collection named "${docDecl.collection}".`)
+      walk(schema, { container: 'u90/group', fields: collection.fields, order: collection.order }, doc?.fields, visitor, path.child(at, 'fields'), (v) => { doc.fields = v })
+      if (collection.template) walk(schema, collection.template, doc?.blocks, visitor, path.child(at, 'blocks'), (v) => { doc.blocks = v })
+      return
+    }
+    case 'single': {
+      const single = Object.hasOwn(schema.singles, docDecl.key) ? schema.singles[docDecl.key] : undefined
+      if (!single) throw new Error(`No Single named "${docDecl.key}".`)
+      return walk(schema, single.field, doc?.value, visitor, at, (v) => { doc.value = v })
+    }
+  }
+}